MySQL Reference Manual - ISA-UMH
MySQL Reference Manual
c 1997-2003 MySQL AB
Copyright °
i
Table of Contents
1
General Information . . . . . . . . . . . . . . . . . . . . . . . 1
1.1
1.2
1.3
1.4
1.5
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 Conventions Used in This Manual . . . . . . . . . . . . . . . . 2
Overview of the MySQL Database Management System . . . . 3
1.2.1 History of MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.2 The Main Features of MySQL . . . . . . . . . . . . . . . . . . . 5
1.2.3 Stability of MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.2.4 How Big MySQL Tables Can Be . . . . . . . . . . . . . . . . . 9
1.2.5 Year 2000 Compliance . . . . . . . . . . . . . . . . . . . . . . . . . 10
Overview of MySQL AB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.3.1 The Business Model and Services of MySQL AB . . 12
1.3.1.1 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.3.1.2 Training and Certification . . . . . . . . . . . . . 13
1.3.1.3 Consulting . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.3.1.4 Commercial Licenses . . . . . . . . . . . . . . . . . . 14
1.3.1.5 Partnering . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.3.2 Contact Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
MySQL Support and Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.4.1 Support Offered by MySQL AB. . . . . . . . . . . . . . . . . 16
1.4.2 Copyrights and Licenses Used by MySQL. . . . . . . . 16
1.4.3 MySQL Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4.3.1 Using the MySQL Software Under a
Commercial License . . . . . . . . . . . . . . . . . . . . . . . 17
1.4.3.2 Using the MySQL Software for Free Under
GPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.4.4 MySQL AB Logos and Trademarks . . . . . . . . . . . . . 19
1.4.4.1 The Original MySQL Logo. . . . . . . . . . . . . 19
1.4.4.2 MySQL Logos that may be Used Without
Written Permission . . . . . . . . . . . . . . . . . . . . . . . 19
1.4.4.3 When You Need Written Permission to Use
MySQL Logos . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.4.4.4 MySQL AB Partnership Logos . . . . . . . . . 20
1.4.4.5 Using the Word MySQL in Printed Text or
Presentations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.4.4.6 Using the Word MySQL in Company and
Product Names . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
MySQL Development Roadmap . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.5.1 MySQL 4.0 in a Nutshell . . . . . . . . . . . . . . . . . . . . . . . 21
1.5.1.1 Features Available in MySQL 4.0 . . . . . . . 21
1.5.1.2 Embedded MySQL Server . . . . . . . . . . . . . 22
1.5.2 MySQL 4.1 in a Nutshell . . . . . . . . . . . . . . . . . . . . . . . 23
1.5.2.1 Features Available in MySQL 4.1 . . . . . . . 23
1.5.2.2 Stepwise Rollout . . . . . . . . . . . . . . . . . . . . . . 24
ii
1.5.2.3 Ready for Immediate Development Use
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.5.3 MySQL 5.0, The Next Development Release . . . . . 25
1.6 MySQL and the Future (The TODO) . . . . . . . . . . . . . . . . . . . . 25
1.6.1 New Features Planned For 4.1 . . . . . . . . . . . . . . . . . . 25
1.6.2 New Features Planned For 5.0 . . . . . . . . . . . . . . . . . . 25
1.6.3 New Features Planned For 5.1 . . . . . . . . . . . . . . . . . . 26
1.6.4 New Features Planned for the Near Future . . . . . . 27
1.6.5 New Features Planned for the Mid-Term Future . . 30
1.6.6 New Features We Don’t Plan to Do . . . . . . . . . . . . . 31
1.7 MySQL Information Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
1.7.1 MySQL Mailing Lists . . . . . . . . . . . . . . . . . . . . . . . . . . 31
1.7.1.1 The MySQL Mailing Lists . . . . . . . . . . . . . 31
1.7.1.2 Asking Questions or Reporting Bugs. . . . 33
1.7.1.3 How to Report Bugs or Problems . . . . . . 34
1.7.1.4 Guidelines for Answering Questions on the
Mailing List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
1.7.2 MySQL Community Support on IRC (Internet Relay
Chat) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
1.8 MySQL Standards Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . 39
1.8.1 What Standards MySQL Follows . . . . . . . . . . . . . . . 40
1.8.2 Running MySQL in ANSI Mode . . . . . . . . . . . . . . . . 40
1.8.3 MySQL Extensions to the SQL-92 Standard . . . . . 41
1.8.4 MySQL Differences Compared to SQL-92 . . . . . . . . 43
1.8.4.1 Subqueries . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
1.8.4.2 SELECT INTO TABLE . . . . . . . . . . . . . . . . . . . 44
1.8.4.3 Transactions and Atomic Operations . . . 44
1.8.4.4 Stored Procedures and Triggers . . . . . . . . 46
1.8.4.5 Foreign Keys . . . . . . . . . . . . . . . . . . . . . . . . . 47
1.8.4.6 Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
1.8.4.7 ‘--’ as the Start of a Comment. . . . . . . . . 48
1.8.5 How MySQL deals with constraints . . . . . . . . . . . . . 49
1.8.5.1 Constraint PRIMARY KEY / UNIQUE
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
1.8.5.2 Constraint NOT NULL and DEFAULT values
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
1.8.5.3 Constraint ENUM and SET . . . . . . . . . . . . . . 50
1.8.6 Known Errors and Design Deficiencies in MySQL
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
1.8.6.1 Errors in 3.23 Fixed in a Later MySQL
Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
1.8.6.2 Open Bugs / Design Deficiencies in MySQL
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
iii
2
Installing MySQL . . . . . . . . . . . . . . . . . . . . . . . . . 57
2.1
2.2
2.3
2.4
2.5
Quick Standard MySQL Installation . . . . . . . . . . . . . . . . . . . . . 57
2.1.1 Installing MySQL on Windows . . . . . . . . . . . . . . . . . 57
2.1.1.1 Windows System Requirements . . . . . . . . 57
2.1.1.2 Installing a Windows Binary Distribution
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
2.1.1.3 Preparing the Windows MySQL
Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.1.1.4 Selecting a Windows Server . . . . . . . . . . . . 60
2.1.1.5 Starting the Server for the First Time . . 60
2.1.1.6 Starting MySQL on Windows 95, 98, or Me
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
2.1.1.7 Starting MySQL on Windows NT, 2000, or
XP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
2.1.1.8 Running MySQL on Windows. . . . . . . . . . 64
2.1.2 Installing MySQL on Linux. . . . . . . . . . . . . . . . . . . . . 65
2.1.3 Installing MySQL on Mac OS X . . . . . . . . . . . . . . . . 67
2.1.4 Installing MySQL on NetWare . . . . . . . . . . . . . . . . . . 70
2.1.4.1 Installing the MySQL for NetWare Binaries
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
General Installation Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
2.2.1 How to Get MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
2.2.2 Verifying Package Integrity Using MD5 Checksums or
GnuPG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
2.2.3 Operating Systems Supported by MySQL . . . . . . . 74
2.2.4 Which MySQL Version to Use . . . . . . . . . . . . . . . . . . 76
2.2.5 Installation Layouts. . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
2.2.6 How and When Updates Are Released. . . . . . . . . . . 79
2.2.7 Release Philosophy - No Known Bugs in Releases
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
2.2.8 MySQL Binaries Compiled by MySQL AB. . . . . . . 81
2.2.9 Installing a MySQL Binary Distribution . . . . . . . . . 86
Installing a MySQL Source Distribution. . . . . . . . . . . . . . . . . . 89
2.3.1 Quick Installation Overview . . . . . . . . . . . . . . . . . . . . 90
2.3.2 Applying Patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
2.3.3 Typical configure Options . . . . . . . . . . . . . . . . . . . . 93
2.3.4 Installing from the Development Source Tree. . . . . 95
2.3.5 Dealing With Problems Compiling MySQL . . . . . . 97
2.3.6 MIT-pthreads Notes . . . . . . . . . . . . . . . . . . . . . . . . . . 101
2.3.7 Installing MySQL from Source on Windows. . . . . 102
2.3.7.1 Building MySQL Using VC++ . . . . . . . . . 103
2.3.7.2 Creating a Windows Source Package from
the Latest Development Source . . . . . . . . . . . 105
Post-installation Setup and Testing . . . . . . . . . . . . . . . . . . . . . 105
2.4.1 Problems Running mysql_install_db . . . . . . . . . 109
2.4.2 Problems Starting the MySQL Server . . . . . . . . . . 111
2.4.3 Starting and Stopping MySQL Automatically . . . 112
Upgrading/Downgrading MySQL . . . . . . . . . . . . . . . . . . . . . . . 114
iv
2.6
2.5.1 Upgrading From Version 4.0 to 4.1 . . . . . . . . . . . . . 114
2.5.2 Upgrading From Version 3.23 to 4.0 . . . . . . . . . . . . 117
2.5.3 Upgrading From Version 3.22 to 3.23 . . . . . . . . . . . 120
2.5.4 Upgrading from Version 3.21 to 3.22 . . . . . . . . . . . 122
2.5.5 Upgrading from Version 3.20 to 3.21 . . . . . . . . . . . 122
2.5.6 Upgrading the Grant Tables . . . . . . . . . . . . . . . . . . . 123
2.5.7 Upgrading to Another Architecture . . . . . . . . . . . . 124
2.5.8 Upgrading MySQL under Windows . . . . . . . . . . . . 125
Operating System Specific Notes . . . . . . . . . . . . . . . . . . . . . . . 126
2.6.1 Windows Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
2.6.1.1 Connecting to MySQL Remotely from
Windows with SSH . . . . . . . . . . . . . . . . . . . . . . 126
2.6.1.2 Compiling MySQL Clients on Windows
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
2.6.1.3 MySQL on Windows Compared to MySQL
on Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
2.6.2 Linux Notes (All Linux Versions) . . . . . . . . . . . . . . 129
2.6.2.1 Linux Notes for Binary Distributions . . 133
2.6.2.2 Linux x86 Notes . . . . . . . . . . . . . . . . . . . . . 134
2.6.2.3 Linux SPARC Notes . . . . . . . . . . . . . . . . . 135
2.6.2.4 Linux Alpha Notes . . . . . . . . . . . . . . . . . . . 135
2.6.2.5 Linux PowerPC Notes . . . . . . . . . . . . . . . . 136
2.6.2.6 Linux MIPS Notes . . . . . . . . . . . . . . . . . . . 136
2.6.2.7 Linux IA-64 Notes . . . . . . . . . . . . . . . . . . . 136
2.6.3 Solaris Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
2.6.3.1 Solaris 2.7/2.8 Notes . . . . . . . . . . . . . . . . . 139
2.6.3.2 Solaris x86 Notes . . . . . . . . . . . . . . . . . . . . 140
2.6.4 BSD Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
2.6.4.1 FreeBSD Notes . . . . . . . . . . . . . . . . . . . . . . 140
2.6.4.2 NetBSD Notes . . . . . . . . . . . . . . . . . . . . . . . 142
2.6.4.3 OpenBSD 2.5 Notes . . . . . . . . . . . . . . . . . . 142
2.6.4.4 OpenBSD 2.8 Notes . . . . . . . . . . . . . . . . . . 142
2.6.4.5 BSD/OS Version 2.x Notes . . . . . . . . . . . 143
2.6.4.6 BSD/OS Version 3.x Notes . . . . . . . . . . . 143
2.6.4.7 BSD/OS Version 4.x Notes . . . . . . . . . . . 143
2.6.5 Mac OS X Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
2.6.5.1 Mac OS X 10.x . . . . . . . . . . . . . . . . . . . . . . 144
2.6.5.2 Mac OS X Server 1.2 (Rhapsody) . . . . . 144
2.6.6 Other Unix Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
2.6.6.1 HP-UX Notes for Binary Distributions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
2.6.6.2 HP-UX Version 10.20 Notes. . . . . . . . . . . 145
2.6.6.3 HP-UX Version 11.x Notes. . . . . . . . . . . . 146
2.6.6.4 IBM-AIX notes . . . . . . . . . . . . . . . . . . . . . . 147
2.6.6.5 SunOS 4 Notes . . . . . . . . . . . . . . . . . . . . . . 148
2.6.6.6 Alpha-DEC-UNIX Notes (Tru64). . . . . . 149
2.6.6.7 Alpha-DEC-OSF/1 Notes . . . . . . . . . . . . . 150
2.6.6.8 SGI Irix Notes . . . . . . . . . . . . . . . . . . . . . . . 151
v
2.7
3
2.6.6.9 SCO Notes . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.6.10 SCO UnixWare Version 7.1.x Notes . .
2.6.7 OS/2 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.8 Novell NetWare Notes . . . . . . . . . . . . . . . . . . . . . . . .
2.6.9 BeOS Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Perl Installation Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.7.1 Installing Perl on Unix . . . . . . . . . . . . . . . . . . . . . . . .
2.7.2 Installing ActiveState Perl on Windows . . . . . . . .
2.7.3 Problems Using the Perl DBI/DBD Interface . . . . .
152
154
155
155
156
156
156
157
157
MySQL Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . 160
3.1
3.2
3.3
3.4
3.5
3.6
3.7
3.8
Connecting to and Disconnecting from the Server . . . . . . . . 160
Entering Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Creating and Using a Database. . . . . . . . . . . . . . . . . . . . . . . . . 164
3.3.1 Creating and Selecting a Database . . . . . . . . . . . . . 165
3.3.2 Creating a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
3.3.3 Loading Data into a Table . . . . . . . . . . . . . . . . . . . . 167
3.3.4 Retrieving Information from a Table . . . . . . . . . . . 168
3.3.4.1 Selecting All Data . . . . . . . . . . . . . . . . . . . 169
3.3.4.2 Selecting Particular Rows . . . . . . . . . . . . . 169
3.3.4.3 Selecting Particular Columns . . . . . . . . . 171
3.3.4.4 Sorting Rows . . . . . . . . . . . . . . . . . . . . . . . . 172
3.3.4.5 Date Calculations . . . . . . . . . . . . . . . . . . . . 173
3.3.4.6 Working with NULL Values . . . . . . . . . . . . 176
3.3.4.7 Pattern Matching . . . . . . . . . . . . . . . . . . . . 177
3.3.4.8 Counting Rows . . . . . . . . . . . . . . . . . . . . . . 179
3.3.4.9 Using More Than one Table . . . . . . . . . . 182
Getting Information About Databases and Tables . . . . . . . 183
Using mysql in Batch Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Examples of Common Queries . . . . . . . . . . . . . . . . . . . . . . . . . . 186
3.6.1 The Maximum Value for a Column . . . . . . . . . . . . 186
3.6.2 The Row Holding the Maximum of a Certain
Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
3.6.3 Maximum of Column per Group . . . . . . . . . . . . . . . 187
3.6.4 The Rows Holding the Group-wise Maximum of a
Certain Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
3.6.5 Using User Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 189
3.6.6 Using Foreign Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
3.6.7 Searching on Two Keys . . . . . . . . . . . . . . . . . . . . . . . 191
3.6.8 Calculating Visits Per Day . . . . . . . . . . . . . . . . . . . . 191
3.6.9 Using AUTO_INCREMENT. . . . . . . . . . . . . . . . . . . . . . . . 192
Queries from the Twin Project . . . . . . . . . . . . . . . . . . . . . . . . . 193
3.7.1 Find All Non-distributed Twins. . . . . . . . . . . . . . . . 194
3.7.2 Show a Table of Twin Pair Status . . . . . . . . . . . . . 196
Using MySQL with Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
vi
4
Database Administration . . . . . . . . . . . . . . . . . 198
4.1
4.2
4.3
4.4
4.5
Configuring MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
4.1.1 mysqld Command-line Options . . . . . . . . . . . . . . . . 198
4.1.2 ‘my.cnf’ Option Files . . . . . . . . . . . . . . . . . . . . . . . . . 206
Running Multiple MySQL Servers on the Same Machine. . 209
4.2.1 Running Multiple Servers on Windows . . . . . . . . . 211
4.2.1.1 Starting Multiple Windows Servers at the
Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . 211
4.2.1.2 Starting Multiple Windows Servers as
Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
4.2.2 Running Multiple Servers on Unix . . . . . . . . . . . . . 214
4.2.3 Using Client Programs in a Multiple-Server
Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
General Security Issues and the MySQL Access Privilege
System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
4.3.1 General Security Guidelines . . . . . . . . . . . . . . . . . . . 216
4.3.2 How to Make MySQL Secure Against Crackers . . 218
4.3.3 Startup Options for mysqld Concerning Security
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
4.3.4 Security issues with LOAD DATA LOCAL . . . . . . . . . . 221
4.3.5 What the Privilege System Does . . . . . . . . . . . . . . . 221
4.3.6 How the Privilege System Works. . . . . . . . . . . . . . . 222
4.3.7 Privileges Provided by MySQL . . . . . . . . . . . . . . . . 225
4.3.8 Connecting to the MySQL Server . . . . . . . . . . . . . . 227
4.3.9 Access Control, Stage 1: Connection Verification
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
4.3.10 Access Control, Stage 2: Request Verification . . 231
4.3.11 Password Hashing in MySQL 4.1 . . . . . . . . . . . . . 234
4.3.12 Causes of Access denied Errors . . . . . . . . . . . . . . 238
MySQL User Account Management . . . . . . . . . . . . . . . . . . . . . 242
4.4.1 GRANT and REVOKE Syntax . . . . . . . . . . . . . . . . . . . . . 242
4.4.2 MySQL User Names and Passwords . . . . . . . . . . . . 247
4.4.3 When Privilege Changes Take Effect . . . . . . . . . . . 248
4.4.4 Setting Up the Initial MySQL Privileges. . . . . . . . 248
4.4.5 Adding New Users to MySQL . . . . . . . . . . . . . . . . . 249
4.4.6 Deleting Users from MySQL . . . . . . . . . . . . . . . . . . . 252
4.4.7 Limiting user resources. . . . . . . . . . . . . . . . . . . . . . . . 252
4.4.8 Setting Up Passwords . . . . . . . . . . . . . . . . . . . . . . . . . 253
4.4.9 Keeping Your Password Secure . . . . . . . . . . . . . . . . 254
4.4.10 Using Secure Connections . . . . . . . . . . . . . . . . . . . . 255
4.4.10.1 Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
4.4.10.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . 256
4.4.10.3 Setting Up SSL Certificates for MySQL
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
4.4.10.4 SSL GRANT Options . . . . . . . . . . . . . . . . . 260
4.4.10.5 SSL Command-line Options . . . . . . . . . 262
Disaster Prevention and Recovery . . . . . . . . . . . . . . . . . . . . . . 262
4.5.1 Database Backups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
vii
4.5.2 BACKUP TABLE Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 264
4.5.3 RESTORE TABLE Syntax . . . . . . . . . . . . . . . . . . . . . . . . 264
4.5.4 CHECK TABLE Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 265
4.5.5 REPAIR TABLE Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 266
4.5.6 Using myisamchk for Table Maintenance and Crash
Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
4.5.6.1 myisamchk Invocation Syntax . . . . . . . . . 268
4.5.6.2 General Options for myisamchk . . . . . . . 269
4.5.6.3 Check Options for myisamchk . . . . . . . . . 270
4.5.6.4 Repair Options for myisamchk . . . . . . . . 271
4.5.6.5 Other Options for myisamchk . . . . . . . . . 272
4.5.6.6 myisamchk Memory Usage . . . . . . . . . . . . 273
4.5.6.7 Using myisamchk for Crash Recovery . . 273
4.5.6.8 How to Check Tables for Errors . . . . . . . 274
4.5.6.9 How to Repair Tables . . . . . . . . . . . . . . . . 275
4.5.6.10 Table Optimisation . . . . . . . . . . . . . . . . . 277
4.5.7 Setting Up a Table Maintenance Regimen . . . . . . 278
4.5.8 Getting Information About a Table . . . . . . . . . . . . 279
4.6 Database Administration Language Reference . . . . . . . . . . . 283
4.6.1 OPTIMIZE TABLE Syntax . . . . . . . . . . . . . . . . . . . . . . . 283
4.6.2 ANALYZE TABLE Syntax . . . . . . . . . . . . . . . . . . . . . . . . 284
4.6.3 CHECKSUM TABLE Syntax . . . . . . . . . . . . . . . . . . . . . . . 285
4.6.4 FLUSH Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
4.6.5 RESET Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
4.6.6 PURGE MASTER LOGS Syntax . . . . . . . . . . . . . . . . . . . . 286
4.6.7 KILL Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
4.6.8 SHOW Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
4.6.8.1 Retrieving information about Database,
Tables, Columns, and Indexes . . . . . . . . . . . . . 288
4.6.8.2 SHOW TABLE STATUS . . . . . . . . . . . . . . . . . . 289
4.6.8.3 SHOW STATUS . . . . . . . . . . . . . . . . . . . . . . . . . 290
4.6.8.4 SHOW VARIABLES . . . . . . . . . . . . . . . . . . . . . 293
4.6.8.5 SHOW [BDB] LOGS . . . . . . . . . . . . . . . . . . . . . 304
4.6.8.6 SHOW PROCESSLIST . . . . . . . . . . . . . . . . . . . 304
4.6.8.7 SHOW GRANTS . . . . . . . . . . . . . . . . . . . . . . . . . 306
4.6.8.8 SHOW CREATE TABLE . . . . . . . . . . . . . . . . . . 306
4.6.8.9 SHOW WARNINGS | ERRORS . . . . . . . . . . . . . 306
4.6.8.10 SHOW TABLE TYPES . . . . . . . . . . . . . . . . . . 308
4.6.8.11 SHOW PRIVILEGES . . . . . . . . . . . . . . . . . . . 309
4.7 MySQL Localisation and International Usage. . . . . . . . . . . . 309
4.7.1 The Character Set Used for Data and Sorting . . . 309
4.7.1.1 German character set . . . . . . . . . . . . . . . . 310
4.7.2 Non-English Error Messages . . . . . . . . . . . . . . . . . . . 310
4.7.3 Adding a New Character Set . . . . . . . . . . . . . . . . . . 311
4.7.4 The Character Definition Arrays . . . . . . . . . . . . . . . 312
4.7.5 String Collating Support . . . . . . . . . . . . . . . . . . . . . . 313
4.7.6 Multi-byte Character Support . . . . . . . . . . . . . . . . . 313
4.7.7 Problems With Character Sets. . . . . . . . . . . . . . . . . 313
viii
4.8
MySQL Server-Side Scripts and Utilities . . . . . . . . . . . . . . . . 314
4.8.1 Overview of the Server-Side Scripts and Utilities
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
4.8.2 mysqld_safe, The Wrapper Around mysqld . . . . 315
4.8.3 mysqld_multi, A Program for Managing Multiple
MySQL Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
4.8.4 myisampack, The MySQL Compressed Read-only
Table Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
4.8.5 mysqld-max, An Extended mysqld Server. . . . . . . 326
4.9 MySQL Client-Side Scripts and Utilities . . . . . . . . . . . . . . . . 328
4.9.1 Overview of the Client-Side Scripts and Utilities
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
4.9.2 mysql, The Command-line Tool. . . . . . . . . . . . . . . . 329
4.9.3 mysqlcc, The MySQL Control Center . . . . . . . . . . 337
4.9.4 mysqladmin, Administering a MySQL Server . . . 339
4.9.5 mysqlbinlog, Executing the queries from a binary
log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
4.9.6 Using mysqlcheck for Table Maintenance and Crash
Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
4.9.7 mysqldump, Dumping Table Structure and Data
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
4.9.8 mysqlhotcopy, Copying MySQL Databases and
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
4.9.9 mysqlimport, Importing Data from Text Files . . 349
4.9.10 mysqlshow, Showing Databases, Tables, and
Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
4.9.11 mysql_config, Get compile options for compiling
clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
4.9.12 perror, Explaining Error Codes . . . . . . . . . . . . . . 353
4.9.13 How to Run SQL Commands from a Text File . . 353
4.10 The MySQL Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
4.10.1 The Error Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
4.10.2 The General Query Log . . . . . . . . . . . . . . . . . . . . . . 355
4.10.3 The Update Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
4.10.4 The Binary Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
4.10.5 The Slow Query Log . . . . . . . . . . . . . . . . . . . . . . . . . 358
4.10.6 Log File Maintenance . . . . . . . . . . . . . . . . . . . . . . . . 359
4.11 Replication in MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
4.11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
4.11.2 Replication Implementation Overview . . . . . . . . . 360
4.11.3 Replication Implementation Details . . . . . . . . . . . 362
4.11.4 How to Set Up Replication . . . . . . . . . . . . . . . . . . . 366
4.11.5 Replication Features and Known Problems . . . . 370
4.11.6 Replication Startup Options . . . . . . . . . . . . . . . . . . 373
4.11.7 SQL Statements for Controlling Master Servers
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
4.11.7.1 PURGE MASTER LOGS . . . . . . . . . . . . . . . . . 381
4.11.7.2 RESET MASTER . . . . . . . . . . . . . . . . . . . . . . 381
ix
4.11.7.3 SET SQL_LOG_BIN . . . . . . . . . . . . . . . . . . .
4.11.7.4 SHOW BINLOG EVENTS . . . . . . . . . . . . . . . .
4.11.7.5 SHOW MASTER STATUS . . . . . . . . . . . . . . . .
4.11.7.6 SHOW MASTER LOGS . . . . . . . . . . . . . . . . . .
4.11.7.7 SHOW SLAVE HOSTS . . . . . . . . . . . . . . . . . .
4.11.8 SQL Statements for Controlling Slave Servers . .
4.11.8.1 CHANGE MASTER TO . . . . . . . . . . . . . . . . . .
4.11.8.2 LOAD DATA FROM MASTER . . . . . . . . . . . . .
4.11.8.3 LOAD TABLE tbl_name FROM MASTER. . .
4.11.8.4 MASTER_POS_WAIT() . . . . . . . . . . . . . . . .
4.11.8.5 RESET SLAVE. . . . . . . . . . . . . . . . . . . . . . . .
4.11.8.6 SET GLOBAL SQL_SLAVE_SKIP_COUNTER
........................................
4.11.8.7 SHOW SLAVE STATUS . . . . . . . . . . . . . . . . .
4.11.8.8 START SLAVE. . . . . . . . . . . . . . . . . . . . . . . .
4.11.8.9 STOP SLAVE . . . . . . . . . . . . . . . . . . . . . . . . .
4.11.9 Replication FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.11.10 Troubleshooting Replication . . . . . . . . . . . . . . . . .
4.11.11 Reporting Replication Bugs . . . . . . . . . . . . . . . . .
5
381
381
382
382
382
382
382
384
385
385
385
386
386
389
390
390
396
397
MySQL Optimisation . . . . . . . . . . . . . . . . . . . . 398
5.1
Optimisation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
5.1.1 MySQL Design Limitations/Tradeoffs . . . . . . . . . . 398
5.1.2 Portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
5.1.3 What We Have Used MySQL For . . . . . . . . . . . . . . 400
5.1.4 The MySQL Benchmark Suite . . . . . . . . . . . . . . . . . 401
5.1.5 Using Your Own Benchmarks. . . . . . . . . . . . . . . . . . 402
5.2 Optimising SELECTs and Other Queries . . . . . . . . . . . . . . . . . 403
5.2.1 EXPLAIN Syntax (Get Information About a SELECT)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
5.2.2 Estimating Query Performance . . . . . . . . . . . . . . . . 410
5.2.3 Speed of SELECT Queries . . . . . . . . . . . . . . . . . . . . . . 410
5.2.4 How MySQL Optimises WHERE Clauses . . . . . . . . . 411
5.2.5 How MySQL Optimises IS NULL . . . . . . . . . . . . . . . 412
5.2.6 How MySQL Optimises DISTINCT. . . . . . . . . . . . . . 413
5.2.7 How MySQL Optimises LEFT JOIN and RIGHT JOIN
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
5.2.8 How MySQL Optimises ORDER BY . . . . . . . . . . . . . . 415
5.2.9 How MySQL Optimises LIMIT . . . . . . . . . . . . . . . . . 416
5.2.10 Speed of INSERT Queries . . . . . . . . . . . . . . . . . . . . . 417
5.2.11 Speed of UPDATE Queries . . . . . . . . . . . . . . . . . . . . . 419
5.2.12 Speed of DELETE Queries . . . . . . . . . . . . . . . . . . . . . 419
5.2.13 Other Optimisation Tips . . . . . . . . . . . . . . . . . . . . . 419
5.3 Locking Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
5.3.1 How MySQL Locks Tables . . . . . . . . . . . . . . . . . . . . 422
5.3.2 Table Locking Issues . . . . . . . . . . . . . . . . . . . . . . . . . . 422
5.4 Optimising Database Structure . . . . . . . . . . . . . . . . . . . . . . . . . 424
5.4.1 Design Choices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
x
5.5
5.6
6
5.4.2 Get Your Data as Small as Possible . . . . . . . . . . . . 424
5.4.3 How MySQL Uses Indexes . . . . . . . . . . . . . . . . . . . . 425
5.4.4 Column Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
5.4.5 Multiple-Column Indexes. . . . . . . . . . . . . . . . . . . . . . 428
5.4.6 How MySQL Counts Open Tables . . . . . . . . . . . . . 429
5.4.7 How MySQL Opens and Closes Tables . . . . . . . . . 429
5.4.8 Drawbacks to Creating Large Numbers of Tables in
the Same Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Optimising the MySQL Server . . . . . . . . . . . . . . . . . . . . . . . . . 430
5.5.1 System/Compile Time and Startup Parameter
Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
5.5.2 Tuning Server Parameters . . . . . . . . . . . . . . . . . . . . . 431
5.5.3 How Compiling and Linking Affects the Speed of
MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
5.5.4 How MySQL Uses Memory . . . . . . . . . . . . . . . . . . . . 435
5.5.5 How MySQL uses DNS . . . . . . . . . . . . . . . . . . . . . . . 436
5.5.6 SET Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Disk Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
5.6.1 Using Symbolic Links . . . . . . . . . . . . . . . . . . . . . . . . . 442
5.6.1.1 Using Symbolic Links for Databases on
Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
5.6.1.2 Using Symbolic Links for Tables on Unix
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
5.6.1.3 Using Symbolic Links for Databases on
Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
MySQL Language Reference . . . . . . . . . . . . . 446
6.1
6.2
Language Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
6.1.1 Literals: How to Write Strings and Numbers . . . . 446
6.1.1.1 Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
6.1.1.2 Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
6.1.1.3 Hexadecimal Values . . . . . . . . . . . . . . . . . . 448
6.1.1.4 NULL Values . . . . . . . . . . . . . . . . . . . . . . . . . 448
6.1.2 Database, Table, Index, Column, and Alias Names
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
6.1.3 Case Sensitivity in Names . . . . . . . . . . . . . . . . . . . . . 450
6.1.4 User Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
6.1.5 System Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
6.1.6 Comment Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
6.1.7 Treatment of Reserved Words in MySQL . . . . . . . 456
Column Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
6.2.1 Numeric Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
6.2.2 Date and Time Types . . . . . . . . . . . . . . . . . . . . . . . . . 465
6.2.2.1 Y2K Issues and Date Types. . . . . . . . . . . 466
6.2.2.2 The DATETIME, DATE, and TIMESTAMP Types
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
6.2.2.3 The TIME Type . . . . . . . . . . . . . . . . . . . . . . 471
6.2.2.4 The YEAR Type . . . . . . . . . . . . . . . . . . . . . . 472
xi
6.2.3 String Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
6.2.3.1 The CHAR and VARCHAR Types . . . . . . . . . 472
6.2.3.2 The BLOB and TEXT Types . . . . . . . . . . . . 473
6.2.3.3 The ENUM Type . . . . . . . . . . . . . . . . . . . . . . 474
6.2.3.4 The SET Type . . . . . . . . . . . . . . . . . . . . . . . 475
6.2.4 Choosing the Right Type for a Column. . . . . . . . . 476
6.2.5 Using Column Types from Other Database Engines
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
6.2.6 Column Type Storage Requirements . . . . . . . . . . . 477
6.3 Functions for Use in SELECT and WHERE Clauses . . . . . . . . . 479
6.3.1 Non-Type-Specific Operators and Functions . . . . 479
6.3.1.1 Parentheses. . . . . . . . . . . . . . . . . . . . . . . . . . 479
6.3.1.2 Comparison Operators . . . . . . . . . . . . . . . 480
6.3.1.3 Logical Operators . . . . . . . . . . . . . . . . . . . . 483
6.3.1.4 Control Flow Functions. . . . . . . . . . . . . . . 485
6.3.2 String Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
6.3.2.1 String Comparison Functions . . . . . . . . . 494
6.3.2.2 Case-Sensitivity . . . . . . . . . . . . . . . . . . . . . . 496
6.3.3 Numeric Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
6.3.3.1 Arithmetic Operations . . . . . . . . . . . . . . . 497
6.3.3.2 Mathematical Functions . . . . . . . . . . . . . . 498
6.3.4 Date and Time Functions . . . . . . . . . . . . . . . . . . . . . 504
6.3.5 Cast Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
6.3.6 Other Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
6.3.6.1 Bit Functions . . . . . . . . . . . . . . . . . . . . . . . . 520
6.3.6.2 Miscellaneous Functions . . . . . . . . . . . . . . 521
6.3.7 Functions and Modifiers for Use with GROUP BY
Clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
6.3.7.1 GROUP BY Functions . . . . . . . . . . . . . . . . . . 530
6.3.7.2 GROUP BY Modifiers . . . . . . . . . . . . . . . . . . . 532
6.3.7.3 GROUP BY with Hidden Fields . . . . . . . . . . 535
6.4 Data Manipulation: SELECT, INSERT, UPDATE, DELETE . . . . 536
6.4.1 SELECT Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536
6.4.1.1 JOIN Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 541
6.4.1.2 UNION Syntax . . . . . . . . . . . . . . . . . . . . . . . . 543
6.4.2 Subquery Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
6.4.2.1 The Subquery as Scalar Operand . . . . . . 544
6.4.2.2 Comparisons Using Subqueries . . . . . . . . 545
6.4.2.3 Subqueries with ANY, IN, and SOME . . . . 545
6.4.2.4 Subqueries with ALL. . . . . . . . . . . . . . . . . . 546
6.4.2.5 Correlated Subqueries . . . . . . . . . . . . . . . . 546
6.4.2.6 EXISTS and NOT EXISTS . . . . . . . . . . . . . . 547
6.4.2.7 Row Subqueries . . . . . . . . . . . . . . . . . . . . . . 547
6.4.2.8 Subqueries in the FROM clause . . . . . . . . . 548
6.4.2.9 Subquery Errors . . . . . . . . . . . . . . . . . . . . . 549
6.4.2.10 Optimising Subqueries . . . . . . . . . . . . . . 550
6.4.2.11 Rewriting Subqueries for Earlier MySQL
Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
xii
6.5
6.6
6.7
6.8
6.9
6.4.3 INSERT Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
6.4.3.1 INSERT ... SELECT Syntax . . . . . . . . . . . 555
6.4.3.2 INSERT DELAYED Syntax . . . . . . . . . . . . . . 555
6.4.4 UPDATE Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
6.4.5 DELETE Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
6.4.6 TRUNCATE Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
6.4.7 REPLACE Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
6.4.8 LOAD DATA INFILE Syntax . . . . . . . . . . . . . . . . . . . . . 561
6.4.9 HANDLER Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
6.4.10 DO Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
Data Definition: CREATE, DROP, ALTER . . . . . . . . . . . . . . . . . . 569
6.5.1 CREATE DATABASE Syntax . . . . . . . . . . . . . . . . . . . . . . 569
6.5.2 DROP DATABASE Syntax . . . . . . . . . . . . . . . . . . . . . . . . 570
6.5.3 CREATE TABLE Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 570
6.5.3.1 Silent Column Specification Changes . . 579
6.5.4 ALTER TABLE Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 579
6.5.5 RENAME TABLE Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 583
6.5.6 DROP TABLE Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 584
6.5.7 CREATE INDEX Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 584
6.5.8 DROP INDEX Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
Basic MySQL User Utility Commands . . . . . . . . . . . . . . . . . . 585
6.6.1 USE Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
6.6.2 DESCRIBE Syntax (Get Information About Columns)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
MySQL Transactional and Locking Commands . . . . . . . . . . 586
6.7.1 START TRANSACTION, COMMIT, and ROLLBACK Syntax
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
6.7.2 Statements That Cannot Be Rolled Back . . . . . . . 587
6.7.3 Statements That Cause an Implicit Commit . . . . 587
6.7.4 SAVEPOINT and ROLLBACK TO SAVEPOINT Syntax
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
6.7.5 LOCK TABLES and UNLOCK TABLES Syntax . . . . . . . 588
6.7.6 SET TRANSACTION Syntax . . . . . . . . . . . . . . . . . . . . . . 590
MySQL Full-text Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
6.8.1 Full-text Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 594
6.8.2 Fine-tuning MySQL Full-text Search . . . . . . . . . . . 594
6.8.3 Full-text Search TODO . . . . . . . . . . . . . . . . . . . . . . . 595
MySQL Query Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
6.9.1 How the Query Cache Operates. . . . . . . . . . . . . . . . 596
6.9.2 Query Cache Configuration . . . . . . . . . . . . . . . . . . . . 597
6.9.3 Query Cache Options in SELECT . . . . . . . . . . . . . . . 598
6.9.4 Query Cache Status and Maintenance . . . . . . . . . . 598
xiii
7
MySQL Table Types . . . . . . . . . . . . . . . . . . . . . 600
7.1 MyISAM Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
7.1.1 Space Needed for Keys . . . . . . . . . . . . . . . . . . . . . . . . 603
7.1.2 MyISAM Table Formats . . . . . . . . . . . . . . . . . . . . . . . . 603
7.1.2.1 Static (Fixed-length) Table Characteristics
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
7.1.2.2 Dynamic Table Characteristics . . . . . . . . 604
7.1.2.3 Compressed Table Characteristics . . . . . 605
7.1.3 MyISAM Table Problems . . . . . . . . . . . . . . . . . . . . . . . 605
7.1.3.1 Corrupted MyISAM Tables . . . . . . . . . . . . . 606
7.1.3.2 Clients is using or hasn’t closed the table
properly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
7.2 MERGE Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
7.2.1 MERGE Table Problems . . . . . . . . . . . . . . . . . . . . . . . . 609
7.3 ISAM Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
7.4 HEAP Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
7.5 InnoDB Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611
7.5.1 InnoDB Tables Overview . . . . . . . . . . . . . . . . . . . . . . 612
7.5.2 InnoDB in MySQL Version 3.23 . . . . . . . . . . . . . . . 612
7.5.3 InnoDB Startup Options . . . . . . . . . . . . . . . . . . . . . . 613
7.5.4 Creating InnoDB Tablespace . . . . . . . . . . . . . . . . . . 619
7.5.4.1 If Something Goes Wrong in Database
Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
7.5.5 Creating InnoDB Tables . . . . . . . . . . . . . . . . . . . . . . 620
7.5.5.1 Converting MyISAM Tables to InnoDB
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
7.5.5.2 FOREIGN KEY Constraints . . . . . . . . . . . . . 621
7.5.5.3 Multiple tablespaces - putting each table
into its own .ibd file . . . . . . . . . . . . . . . . . . . . . . 624
7.5.6 Adding and Removing InnoDB Data and Log Files
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
7.5.7 Backing up and Recovering an InnoDB Database
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
7.5.7.1 Forcing recovery . . . . . . . . . . . . . . . . . . . . . 627
7.5.7.2 Checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . 627
7.5.8 Moving an InnoDB Database to Another Machine
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
7.5.9 InnoDB Transaction Model and Locking . . . . . . . . 628
7.5.9.1 InnoDB and SET ... TRANSACTION
ISOLATION LEVEL ... . . . . . . . . . . . . . . . . . . . . 629
7.5.9.2 Consistent Non-Locking Read . . . . . . . . . 630
7.5.9.3 Locking Reads SELECT ... FOR UPDATE and
SELECT ... LOCK IN SHARE MODE . . . . . . . . . . 631
7.5.9.4 Next-key Locking: Avoiding the Phantom
Problem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
7.5.9.5 Locks Set by Different SQL Statements in
InnoDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
7.5.9.6 Deadlock Detection and Rollback. . . . . . 633
xiv
7.5.10
7.5.11
7.5.12
7.5.13
7.5.14
7.5.15
7.5.16
7.5.9.7 An Example of How the Consistent Read
Works in InnoDB . . . . . . . . . . . . . . . . . . . . . . . . . 633
7.5.9.8 How to Cope With Deadlocks . . . . . . . . . 634
Performance Tuning Tips . . . . . . . . . . . . . . . . . . . . 635
7.5.10.1 SHOW INNODB STATUS and the InnoDB
Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
Implementation of Multi-versioning . . . . . . . . . . . 639
Table and Index Structures . . . . . . . . . . . . . . . . . . . 639
7.5.12.1 Physical Structure of an Index . . . . . . . 640
7.5.12.2 Insert Buffering . . . . . . . . . . . . . . . . . . . . . 640
7.5.12.3 Adaptive Hash Indexes . . . . . . . . . . . . . . 640
7.5.12.4 Physical Record Structure . . . . . . . . . . . 641
7.5.12.5 How an AUTO_INCREMENT Column Works
in InnoDB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
File Space Management and Disk I/O . . . . . . . . . 642
7.5.13.1 Disk I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
7.5.13.2 File Space Management . . . . . . . . . . . . . 643
7.5.13.3 Defragmenting a Table . . . . . . . . . . . . . . 643
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
Restrictions on InnoDB Tables . . . . . . . . . . . . . . . 644
InnoDB Change History. . . . . . . . . . . . . . . . . . . . . . 645
7.5.16.1 MySQL/InnoDB-4.1.1, December 4, 2003
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
7.5.16.2 MySQL/InnoDB-4.0.16, October 22, 2003
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
7.5.16.3 MySQL/InnoDB-3.23.58, September 15,
2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
7.5.16.4 MySQL/InnoDB-4.0.15, September 10,
2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
7.5.16.5 MySQL/InnoDB-4.0.14, July 22, 2003
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
7.5.16.6 MySQL/InnoDB-3.23.57, June 20, 2003
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
7.5.16.7 MySQL/InnoDB-4.0.13, May 20, 2003
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
7.5.16.8 MySQL/InnoDB-4.1.0, April 3, 2003 . . 649
7.5.16.9 MySQL/InnoDB-3.23.56, March 17, 2003
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
7.5.16.10 MySQL/InnoDB-4.0.12, March 18, 2003
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
7.5.16.11 MySQL/InnoDB-4.0.11, February 25,
2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
7.5.16.12 MySQL/InnoDB-4.0.10, February 4, 2003
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
7.5.16.13 MySQL/InnoDB-3.23.55, January 24,
2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651
7.5.16.14 MySQL/InnoDB-4.0.9, January 14, 2003
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651
xv
7.5.16.15 MySQL/InnoDB-4.0.8, January 7, 2003
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651
7.5.16.16 MySQL/InnoDB-4.0.7, December 26,
2002 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
7.5.16.17 MySQL/InnoDB-4.0.6, December 19,
2002 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
7.5.16.18 MySQL/InnoDB-3.23.54, December 12,
2002 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
7.5.16.19 MySQL/InnoDB-4.0.5, November 18,
2002 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
7.5.16.20 MySQL/InnoDB-3.23.53, October 9, 2002
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
7.5.16.21 MySQL/InnoDB-4.0.4, October 2, 2002
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
7.5.16.22 MySQL/InnoDB-4.0.3, August 28, 2002
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
7.5.16.23 MySQL/InnoDB-3.23.52, August 16,
2002 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
7.5.16.24 MySQL/InnoDB-4.0.2, July 10, 2002
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
7.5.16.25 MySQL/InnoDB-3.23.51, June 12, 2002
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
7.5.16.26 MySQL/InnoDB-3.23.50, April 23, 2002
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
7.5.16.27 MySQL/InnoDB-3.23.49, February 17,
2002 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
7.5.16.28 MySQL/InnoDB-3.23.48, February 9,
2002 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
7.5.16.29 MySQL/InnoDB-3.23.47, December 28,
2001 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
7.5.16.30 MySQL/InnoDB-4.0.1, December 23,
2001 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
7.5.16.31 MySQL/InnoDB-3.23.46, November 30,
2001 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
7.5.16.32 MySQL/InnoDB-3.23.45, November 23,
2001 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
7.5.16.33 MySQL/InnoDB-3.23.44, November 2,
2001 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
7.5.16.34 MySQL/InnoDB-3.23.43, October 4, 2001
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
7.5.16.35 MySQL/InnoDB-3.23.42, September 9,
2001 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
7.5.16.36 MySQL/InnoDB-3.23.41, August 13,
2001 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
7.5.16.37 MySQL/InnoDB-3.23.40, July 16, 2001
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
7.5.16.38 MySQL/InnoDB-3.23.39, June 13, 2001
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
xvi
7.5.16.39 MySQL/InnoDB-3.23.38, May 12, 2001
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
7.5.17 InnoDB Contact Information . . . . . . . . . . . . . . . . . . 662
7.6 BDB or BerkeleyDB Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
7.6.1 Overview of BDB Tables . . . . . . . . . . . . . . . . . . . . . . . 663
7.6.2 Installing BDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
7.6.3 BDB Startup Options . . . . . . . . . . . . . . . . . . . . . . . . . . 663
7.6.4 Characteristics of BDB Tables . . . . . . . . . . . . . . . . . . 664
7.6.5 Things We Need to Fix for BDB in the Near Future
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
7.6.6 Operating Systems Supported by BDB . . . . . . . . . . 666
7.6.7 Restrictions on BDB Tables . . . . . . . . . . . . . . . . . . . . 666
7.6.8 Errors That May Occur When Using BDB Tables
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
8
Introduction to MaxDB . . . . . . . . . . . . . . . . . . 668
8.1 History of MaxDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2 Licensing and Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3 Basic Concepts of MaxDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4 Feature Differences between MaxDB and MySQL . . . . . . . .
8.5 Interoperability Features between MaxDB and MySQL . . .
8.6 MaxDB-related Links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.7 Reserved Words in MaxDB . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.8 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.9 Column Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
668
668
668
668
669
669
670
672
672
National Character Sets and Unicode . . . . . 674
9.1 Character Sets and Collations in General. . . . . . . . . . . . . . . . 674
9.2 Character Sets and Collations in MySQL . . . . . . . . . . . . . . . 675
9.3 Determining the Default Character Set and Collation . . . . 675
9.3.1 Server Character Set and Collation . . . . . . . . . . . . 675
9.3.2 Database Character Set and Collation . . . . . . . . . . 676
9.3.3 Table Character Set and Collation . . . . . . . . . . . . . 676
9.3.4 Column Character Set and Collation . . . . . . . . . . . 677
9.3.5 Examples of Character Set and Collation Assignment
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
9.3.6 Connection Character Sets and Collations . . . . . . 679
9.3.7 Character String Literal Character Set and Collation
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679
9.3.8 COLLATE Clause in Various Parts of an SQL Query
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
9.3.9 COLLATE Clause Precedence . . . . . . . . . . . . . . . . . . . 681
9.3.10 BINARY Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
9.3.11 Some Special Cases Where the Collation
Determination is Tricky . . . . . . . . . . . . . . . . . . . . . . . . . 681
9.3.12 Collations Must Be for the Right Character Set
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
9.3.13 An example of the Effect of Collation . . . . . . . . . 682
xvii
9.4
9.5
9.6
9.7
9.8
9.9
9.10
9.11
10
Operations Affected by Character Set Support . . . . . . . . . . 683
9.4.1 Result Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
9.4.2 CONVERT() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
9.4.3 CAST() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
9.4.4 SHOW CHARACTER SET . . . . . . . . . . . . . . . . . . . . . . . . . . 684
9.4.5 SHOW COLLATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
9.4.6 SHOW CREATE DATABASE . . . . . . . . . . . . . . . . . . . . . . . . 685
9.4.7 SHOW FULL COLUMNS . . . . . . . . . . . . . . . . . . . . . . . . . . . 686
Unicode Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686
UTF8 for Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
Compatibility with Other DBMSs . . . . . . . . . . . . . . . . . . . . . . 687
New Character Set Configuration File format. . . . . . . . . . . . 688
National Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
Upgrading from MySQL 4.0. . . . . . . . . . . . . . . . . . . . . . . . . . . 688
9.10.1 4.0 Character Sets and Corresponding 4.1
Character Set/Collation Pairs. . . . . . . . . . . . . . . . . . . . 689
The Character Sets and Collations that MySQL Supports
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
9.11.1 The Unicode Character Sets . . . . . . . . . . . . . . . . . . 691
9.11.2 Platform Specific Character Sets . . . . . . . . . . . . . . 691
9.11.3 Character Sets for South Europe and Middle East
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691
9.11.4 The Asian Character Sets . . . . . . . . . . . . . . . . . . . . 691
9.11.5 The Baltic Character Sets . . . . . . . . . . . . . . . . . . . . 692
9.11.6 The Cyrillic Character Sets. . . . . . . . . . . . . . . . . . . 692
9.11.7 The Central European Character Sets . . . . . . . . . 693
9.11.8 The West European Character Sets . . . . . . . . . . . 694
Spatial Extensions in MySQL . . . . . . . . . . . 696
10.1
10.2
10.3
10.4
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The OpenGIS Geometry Model . . . . . . . . . . . . . . . . . . . . . . .
10.2.1 The Geometry Class Hierarchy . . . . . . . . . . . . . . .
10.2.2 Class Geometry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.3 Class Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.4 Class Curve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.5 Class LineString . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.6 Class Surface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.7 Class Polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.8 Class GeometryCollection . . . . . . . . . . . . . . . . . .
10.2.9 Class MultiPoint . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.10 Class MultiCurve . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2.11 Class MultiLineString . . . . . . . . . . . . . . . . . . . . .
10.2.12 Class MultiSurface . . . . . . . . . . . . . . . . . . . . . . . .
10.2.13 Class MultiPolygon . . . . . . . . . . . . . . . . . . . . . . . .
Supported Spatial Data Formats . . . . . . . . . . . . . . . . . . . . . .
10.3.1 Well-Known Text (WKT) Format. . . . . . . . . . . . .
10.3.2 Well-Known Binary (WKB) Format. . . . . . . . . . .
Creating a Spatially Enabled MySQL Database. . . . . . . . .
696
696
697
698
699
699
700
700
700
701
701
701
702
702
702
703
703
704
704
xviii
10.4.1 MySQL Spatial Datatypes . . . . . . . . . . . . . . . . . . . 705
10.4.2 Creating Spatial Values . . . . . . . . . . . . . . . . . . . . . . 705
10.4.2.1 Creating Geometry Values Using WKT
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
10.4.2.2 Creating Geometry Values Using WKB
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
10.4.2.3 Creating Geometry Values Using
MySQL-Specific Functions . . . . . . . . . . . . . . . . 707
10.4.3 Creating Spatial Columns . . . . . . . . . . . . . . . . . . . . 708
10.4.4 Populating Spatial Columns . . . . . . . . . . . . . . . . . . 708
10.4.5 Fetching Spatial Data . . . . . . . . . . . . . . . . . . . . . . . . 710
10.4.5.1 Fetching Spatial Data in Internal Format
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
10.4.5.2 Fetching Spatial Data in WKT Format
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
10.4.5.3 Fetching Spatial Data in WKB Format
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
10.5 Analysing Spatial Information. . . . . . . . . . . . . . . . . . . . . . . . . 710
10.5.1 Functions to Convert Geometries Between Formats
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
10.5.2 Geometry Property Analysis Functions . . . . . . . . 711
10.5.2.1 General Geometry Property Analysis
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
10.5.2.2 Point Property Analysis Functions . . . 713
10.5.2.3 LineString Property Analysis Functions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
10.5.2.4 MultiLineString Property Analysis
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
10.5.2.5 Polygon Property Analysis Functions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
10.5.2.6 MultiPolygon Property Analysis
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
10.5.2.7 GeometryCollection Property Analysis
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
10.5.3 Functions That Create New Geometries From
Existing Ones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
10.5.3.1 Geometry Functions That Produce New
Geometries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
10.5.3.2 Spatial Operators . . . . . . . . . . . . . . . . . . . 718
10.5.4 Functions For Testing Spatial Relations Between
Geometric Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
10.5.5 Relations On Geometry Minimal Bounding
Rectangles (MBRs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
10.5.6 Functions That Test Spatial Relationships Between
Geometries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
10.6 Optimising Spatial Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
10.6.1 Creating Spatial Indexes . . . . . . . . . . . . . . . . . . . . . 721
10.6.2 Using a Spatial Index . . . . . . . . . . . . . . . . . . . . . . . . 722
xix
10.7
11
MySQL Conformance and Compatibility . . . . . . . . . . . . . . . 724
10.7.1 GIS Features That Are Not Yet Implemented . . 724
MySQL APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . 725
11.1
MySQL
11.1.1
11.1.2
11.1.3
C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C API Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C API Function Overview . . . . . . . . . . . . . . . . . . . .
C API Function Descriptions . . . . . . . . . . . . . . . . .
11.1.3.1 mysql_affected_rows() . . . . . . . . . . . .
11.1.3.2 mysql_change_user() . . . . . . . . . . . . . .
11.1.3.3 mysql_character_set_name(). . . . . . .
11.1.3.4 mysql_close() . . . . . . . . . . . . . . . . . . . . .
11.1.3.5 mysql_connect() . . . . . . . . . . . . . . . . . . .
11.1.3.6 mysql_create_db() . . . . . . . . . . . . . . . .
11.1.3.7 mysql_data_seek() . . . . . . . . . . . . . . . .
11.1.3.8 mysql_debug() . . . . . . . . . . . . . . . . . . . . .
11.1.3.9 mysql_drop_db() . . . . . . . . . . . . . . . . . . .
11.1.3.10 mysql_dump_debug_info() . . . . . . . . .
11.1.3.11 mysql_eof() . . . . . . . . . . . . . . . . . . . . . .
11.1.3.12 mysql_errno() . . . . . . . . . . . . . . . . . . . .
11.1.3.13 mysql_error() . . . . . . . . . . . . . . . . . . . .
11.1.3.14 mysql_escape_string() . . . . . . . . . . .
11.1.3.15 mysql_fetch_field() . . . . . . . . . . . . .
11.1.3.16 mysql_fetch_fields() . . . . . . . . . . . .
11.1.3.17 mysql_fetch_field_direct() . . . . .
11.1.3.18 mysql_fetch_lengths() . . . . . . . . . . .
11.1.3.19 mysql_fetch_row() . . . . . . . . . . . . . . .
11.1.3.20 mysql_field_count() . . . . . . . . . . . . .
11.1.3.21 mysql_field_seek() . . . . . . . . . . . . . .
11.1.3.22 mysql_field_tell() . . . . . . . . . . . . . .
11.1.3.23 mysql_free_result() . . . . . . . . . . . . .
11.1.3.24 mysql_get_client_info() . . . . . . . . .
11.1.3.25 mysql_get_client_version() . . . . .
11.1.3.26 mysql_get_host_info() . . . . . . . . . . .
11.1.3.27 mysql_get_proto_info() . . . . . . . . . .
11.1.3.28 mysql_get_server_info() . . . . . . . . .
11.1.3.29 mysql_get_server_version() . . . . .
11.1.3.30 mysql_info() . . . . . . . . . . . . . . . . . . . . .
11.1.3.31 mysql_init() . . . . . . . . . . . . . . . . . . . . .
11.1.3.32 mysql_insert_id() . . . . . . . . . . . . . . .
11.1.3.33 mysql_kill() . . . . . . . . . . . . . . . . . . . . .
11.1.3.34 mysql_list_dbs(). . . . . . . . . . . . . . . . .
11.1.3.35 mysql_list_fields() . . . . . . . . . . . . .
11.1.3.36 mysql_list_processes() . . . . . . . . . .
11.1.3.37 mysql_list_tables() . . . . . . . . . . . . .
11.1.3.38 mysql_num_fields() . . . . . . . . . . . . . .
11.1.3.39 mysql_num_rows(). . . . . . . . . . . . . . . . .
11.1.3.40 mysql_options() . . . . . . . . . . . . . . . . . .
725
725
728
732
733
733
735
735
735
736
737
737
738
738
739
740
741
741
742
742
743
744
745
746
747
748
748
748
749
749
750
750
750
751
752
752
753
753
754
755
755
756
757
758
xx
11.1.3.41 mysql_ping() . . . . . . . . . . . . . . . . . . . . . 760
11.1.3.42 mysql_query() . . . . . . . . . . . . . . . . . . . . 761
11.1.3.43 mysql_real_connect() . . . . . . . . . . . . 761
11.1.3.44 mysql_real_escape_string() . . . . . 764
11.1.3.45 mysql_real_query() . . . . . . . . . . . . . . 765
11.1.3.46 mysql_reload() . . . . . . . . . . . . . . . . . . . 766
11.1.3.47 mysql_row_seek(). . . . . . . . . . . . . . . . . 766
11.1.3.48 mysql_row_tell(). . . . . . . . . . . . . . . . . 767
11.1.3.49 mysql_select_db() . . . . . . . . . . . . . . . 767
11.1.3.50 mysql_set_server_option(). . . . . . . 768
11.1.3.51 mysql_shutdown(). . . . . . . . . . . . . . . . . 769
11.1.3.52 mysql_sqlstate(). . . . . . . . . . . . . . . . . 769
11.1.3.53 mysql_ssl_set() . . . . . . . . . . . . . . . . . . 770
11.1.3.54 mysql_stat() . . . . . . . . . . . . . . . . . . . . . 770
11.1.3.55 mysql_store_result() . . . . . . . . . . . . 771
11.1.3.56 mysql_thread_id() . . . . . . . . . . . . . . . 772
11.1.3.57 mysql_use_result() . . . . . . . . . . . . . . 772
11.1.3.58 mysql_warning_count() . . . . . . . . . . . 773
11.1.3.59 mysql_commit() . . . . . . . . . . . . . . . . . . . 774
11.1.3.60 mysql_rollback(). . . . . . . . . . . . . . . . . 774
11.1.3.61 mysql_autocommit() . . . . . . . . . . . . . . 775
11.1.3.62 mysql_more_results() . . . . . . . . . . . . 775
11.1.3.63 mysql_next_result() . . . . . . . . . . . . . 775
11.1.4 C API Prepared Statements . . . . . . . . . . . . . . . . . . 776
11.1.5 C API Prepared Statement Datatypes. . . . . . . . . 776
11.1.6 C API Prepared Statement Function Overview
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
11.1.7 C API Prepared Statement Function Descriptions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781
11.1.7.1 mysql_prepare() . . . . . . . . . . . . . . . . . . . 781
11.1.7.2 mysql_param_count() . . . . . . . . . . . . . . 783
11.1.7.3 mysql_get_metadata() . . . . . . . . . . . . . 783
11.1.7.4 mysql_bind_param() . . . . . . . . . . . . . . . 784
11.1.7.5 mysql_execute() . . . . . . . . . . . . . . . . . . . 785
11.1.7.6 mysql_stmt_affected_rows(). . . . . . . 789
11.1.7.7 mysql_bind_result() . . . . . . . . . . . . . . 790
11.1.7.8 mysql_stmt_store_result() . . . . . . . . 791
11.1.7.9 mysql_stmt_data_seek() . . . . . . . . . . . 791
11.1.7.10 mysql_stmt_row_seek() . . . . . . . . . . . 792
11.1.7.11 mysql_stmt_row_tell() . . . . . . . . . . . 792
11.1.7.12 mysql_stmt_num_rows() . . . . . . . . . . . 793
11.1.7.13 mysql_fetch() . . . . . . . . . . . . . . . . . . . . 793
11.1.7.14 mysql_send_long_data() . . . . . . . . . . 799
11.1.7.15 mysql_stmt_close() . . . . . . . . . . . . . . 800
11.1.7.16 mysql_stmt_errno() . . . . . . . . . . . . . . 801
11.1.7.17 mysql_stmt_error() . . . . . . . . . . . . . . 802
11.1.7.18 mysql_stmt_sqlstate() . . . . . . . . . . . 802
11.1.8 C API Handling of Multiple Query Execution . . 803
xxi
11.1.9 C API Handling of Date and Time Values . . . . . 803
11.1.10 C API Threaded Function Descriptions . . . . . . 805
11.1.10.1 my_init() . . . . . . . . . . . . . . . . . . . . . . . . 805
11.1.10.2 mysql_thread_init() . . . . . . . . . . . . . 805
11.1.10.3 mysql_thread_end() . . . . . . . . . . . . . . 806
11.1.10.4 mysql_thread_safe() . . . . . . . . . . . . . 806
11.1.11 C API Embedded Server Function Descriptions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
11.1.11.1 mysql_server_init() . . . . . . . . . . . . . 806
11.1.11.2 mysql_server_end() . . . . . . . . . . . . . . 807
11.1.12 Common questions and problems when using the
C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
11.1.12.1 Why mysql_store_result() Sometimes
Returns NULL After mysql_query() Returns
Success . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
11.1.12.2 What Results You Can Get from a Query
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
11.1.12.3 How to Get the Unique ID for the Last
Inserted Row . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
11.1.12.4 Problems Linking with the C API . . . 809
11.1.13 Building Client Programs . . . . . . . . . . . . . . . . . . . 809
11.1.14 How to Make a Threaded Client . . . . . . . . . . . . . 810
11.1.15 libmysqld, the Embedded MySQL Server Library
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
11.1.15.1 Overview of the Embedded MySQL
Server Library . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
11.1.15.2 Compiling Programs with libmysqld
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
11.1.15.3 Restrictions when using the Embedded
MySQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
11.1.15.4 Using Option Files with the Embedded
Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
11.1.15.5 Things left to do in Embedded Server
(TODO) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
11.1.15.6 A Simple Embedded Server Example
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
11.1.15.7 Licensing the Embedded Server . . . . . 817
11.2 MySQL ODBC Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
11.2.1 How to Install MyODBC . . . . . . . . . . . . . . . . . . . . . 817
11.2.2 How to Fill in the Various Fields in the ODBC
Administrator Program . . . . . . . . . . . . . . . . . . . . . . . . . 818
11.2.3 Connect parameters for MyODBC . . . . . . . . . . . . 819
11.2.4 How to Report Problems with MyODBC . . . . . . 820
11.2.5 Programs Known to Work with MyODBC . . . . . 820
11.2.6 How to Get the Value of an AUTO_INCREMENT
Column in ODBC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825
11.2.7 Reporting Problems with MyODBC. . . . . . . . . . . 826
11.3 MySQL Java Connectivity (JDBC) . . . . . . . . . . . . . . . . . . . . 826
xxii
11.4
11.5
11.6
11.7
11.8
11.9
12
PHP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Common Problems with MySQL and PHP . . . .
Perl API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DBI with DBD::mysql . . . . . . . . . . . . . . . . . . . . . . . .
The DBI Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . .
More DBI/DBD Information . . . . . . . . . . . . . . . . . . .
C++ API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Borland C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Python API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tcl API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Eiffel Wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
827
827
827
827
828
834
834
834
834
834
834
Error Handling in MySQL . . . . . . . . . . . . . . 836
12.1
13
MySQL
11.4.1
MySQL
11.5.1
11.5.2
11.5.3
MySQL
11.6.1
MySQL
MySQL
MySQL
Error Returns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
Extending MySQL . . . . . . . . . . . . . . . . . . . . . . 843
13.1
13.2
13.3
MySQL Internals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
13.1.1 MySQL Threads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
13.1.2 MySQL Test Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
13.1.2.1 Running the MySQL Test Suite . . . . . . 844
13.1.2.2 Extending the MySQL Test Suite . . . . 844
13.1.2.3 Reporting Bugs in the MySQL Test Suite
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845
Adding New Functions to MySQL . . . . . . . . . . . . . . . . . . . . . 846
13.2.1 CREATE FUNCTION/DROP FUNCTION Syntax . . . . . 847
13.2.2 Adding a New User-definable Function . . . . . . . . 847
13.2.2.1 UDF Calling Sequences for simple
functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
13.2.2.2 UDF Calling Sequences for aggregate
functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850
13.2.2.3 Argument Processing . . . . . . . . . . . . . . . . 851
13.2.2.4 Return Values and Error Handling . . . 852
13.2.2.5 Compiling and Installing User-definable
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
13.2.3 Adding a New Native Function . . . . . . . . . . . . . . . 855
Adding New Procedures to MySQL . . . . . . . . . . . . . . . . . . . . 856
13.3.1 Procedure Analyse. . . . . . . . . . . . . . . . . . . . . . . . . . . 856
13.3.2 Writing a Procedure . . . . . . . . . . . . . . . . . . . . . . . . . 856
xxiii
Appendix A Problems and Common Errors . . 857
A.1
A.2
A.3
A.4
A.5
A.6
A.7
How to Determine What Is Causing Problems . . . . . . . . . . 857
Common Errors When Using MySQL . . . . . . . . . . . . . . . . . . 858
A.2.1 Access denied Error . . . . . . . . . . . . . . . . . . . . . . . . . 858
A.2.2 MySQL server has gone away Error. . . . . . . . . . . . 858
A.2.3 Can’t connect to [local] MySQL server Error
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 859
A.2.4 Client does not support authentication
protocol error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861
A.2.5 Host ’...’ is blocked Error . . . . . . . . . . . . . . . . . 861
A.2.6 Too many connections Error . . . . . . . . . . . . . . . . . 862
A.2.7 Some non-transactional changed tables
couldn’t be rolled back Error . . . . . . . . . . . . . . . . . 862
A.2.8 Out of memory Error . . . . . . . . . . . . . . . . . . . . . . . . . 862
A.2.9 Packet too large Error . . . . . . . . . . . . . . . . . . . . . . 863
A.2.10 Communication Errors / Aborted Connection
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
A.2.11 The table is full Error . . . . . . . . . . . . . . . . . . . . 864
A.2.12 Can’t create/write to file Error . . . . . . . . . . 865
A.2.13 Commands out of sync Error in Client . . . . . . . . 865
A.2.14 Ignoring user Error . . . . . . . . . . . . . . . . . . . . . . . . 866
A.2.15 Table ’xxx’ doesn’t exist Error . . . . . . . . . . . 866
A.2.16 Can’t initialize character set xxx error . . 866
A.2.17 File Not Found . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
Installation Related Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
A.3.1 Problems When Linking with the MySQL Client
Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
A.3.2 How to Run MySQL As a Normal User . . . . . . . . 868
A.3.3 Problems with File Permissions . . . . . . . . . . . . . . . 869
Administration Related Issues . . . . . . . . . . . . . . . . . . . . . . . . . 870
A.4.1 What To Do If MySQL Keeps Crashing. . . . . . . . 870
A.4.2 How to Reset a Forgotten Root Password . . . . . . 872
A.4.3 How MySQL Handles a Full Disk. . . . . . . . . . . . . . 873
A.4.4 Where MySQL Stores Temporary Files . . . . . . . . 873
A.4.5 How to Protect or Change the MySQL Socket File
‘/tmp/mysql.sock’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
A.4.6 Time Zone Problems . . . . . . . . . . . . . . . . . . . . . . . . . 875
Query Related Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875
A.5.1 Case-Sensitivity in Searches . . . . . . . . . . . . . . . . . . . 875
A.5.2 Problems Using DATE Columns . . . . . . . . . . . . . . . . 875
A.5.3 Problems with NULL Values . . . . . . . . . . . . . . . . . . . 877
A.5.4 Problems with alias . . . . . . . . . . . . . . . . . . . . . . . . . 878
A.5.5 Deleting Rows from Related Tables . . . . . . . . . . . . 878
A.5.6 Solving Problems with No Matching Rows . . . . . 878
A.5.7 Problems with Floating-Point Comparison . . . . . 879
Optimiser Related Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881
A.6.1 How to avoid table scan,,, . . . . . . . . . . . . . . . . . . . . 881
Table Definition Related Issues . . . . . . . . . . . . . . . . . . . . . . . . 882
xxiv
A.7.1 Problems with ALTER TABLE. . . . . . . . . . . . . . . . . . . 882
A.7.2 How To Change the Order of Columns in a Table
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882
A.7.3 TEMPORARY TABLE problems . . . . . . . . . . . . . 883
Appendix B Contributed Programs . . . . . . . . . 884
B.1
B.2
B.3
APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884
Converters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
Appendix C Credits . . . . . . . . . . . . . . . . . . . . . . . . 889
C.1
C.2
C.3
C.4
C.5
C.6
C.7
Developers at MySQL AB . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contributors to MySQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Documenters and translators . . . . . . . . . . . . . . . . . . . . . . . . . .
Libraries used by and included with MySQL . . . . . . . . . . . .
Packages that support MySQL . . . . . . . . . . . . . . . . . . . . . . . . .
Tools that was used to create MySQL . . . . . . . . . . . . . . . . . .
Supporters to MySQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
889
892
896
897
898
898
899
Appendix D MySQL Change History . . . . . . . . 900
D.1 Changes in release 5.0.0 (Development). . . . . . . . . . . . . . . . . 900
D.2 Changes in release 4.1.x (Alpha) . . . . . . . . . . . . . . . . . . . . . . . 900
D.2.1 Changes in release 4.1.2 (not released yet) . . . . . 901
D.2.2 Changes in release 4.1.1 (01 Dec 2003) . . . . . . . . . 901
D.2.3 Changes in release 4.1.0 (03 Apr 2003: Alpha) . . 906
D.3 Changes in release 4.0.x (Production) . . . . . . . . . . . . . . . . . . 908
D.3.1 Changes in release 4.0.17 (not released yet) . . . . 908
D.3.2 Changes in release 4.0.16 (17 Oct 2003) . . . . . . . . 910
D.3.3 Changes in release 4.0.15 (03 Sep 2003) . . . . . . . . 912
D.3.4 Changes in release 4.0.14 (18 Jul 2003) . . . . . . . . 916
D.3.5 Changes in release 4.0.13 (16 May 2003) . . . . . . . 920
D.3.6 Changes in release 4.0.12 (15 Mar 2003: Production)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
D.3.7 Changes in release 4.0.11 (20 Feb 2003) . . . . . . . . 925
D.3.8 Changes in release 4.0.10 (29 Jan 2003) . . . . . . . . 926
D.3.9 Changes in release 4.0.9 (09 Jan 2003) . . . . . . . . . 927
D.3.10 Changes in release 4.0.8 (07 Jan 2003) . . . . . . . . 927
D.3.11 Changes in release 4.0.7 (20 Dec 2002) . . . . . . . . 928
D.3.12 Changes in release 4.0.6 (14 Dec 2002: Gamma)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928
D.3.13 Changes in release 4.0.5 (13 Nov 2002) . . . . . . . 930
D.3.14 Changes in release 4.0.4 (29 Sep 2002) . . . . . . . . 932
D.3.15 Changes in release 4.0.3 (26 Aug 2002: Beta) . . 933
D.3.16 Changes in release 4.0.2 (01 Jul 2002) . . . . . . . . 935
D.3.17 Changes in release 4.0.1 (23 Dec 2001) . . . . . . . . 939
D.3.18 Changes in release 4.0.0 (Oct 2001: Alpha). . . . 940
D.4 Changes in release 3.23.x (Recent; still supported). . . . . . . 941
xxv
D.4.1 Changes in release 3.23.59 (not released yet) . . . 942
D.4.2 Changes in release 3.23.58 (11 Sep 2003) . . . . . . . 942
D.4.3 Changes in release 3.23.57 (06 Jun 2003) . . . . . . . 943
D.4.4 Changes in release 3.23.56 (13 Mar 2003) . . . . . . 944
D.4.5 Changes in release 3.23.55 (23 Jan 2003) . . . . . . . 945
D.4.6 Changes in release 3.23.54 (05 Dec 2002) . . . . . . . 946
D.4.7 Changes in release 3.23.53 (09 Oct 2002) . . . . . . . 946
D.4.8 Changes in release 3.23.52 (14 Aug 2002) . . . . . . 947
D.4.9 Changes in release 3.23.51 (31 May 2002) . . . . . . 948
D.4.10 Changes in release 3.23.50 (21 Apr 2002) . . . . . 948
D.4.11 Changes in release 3.23.49 . . . . . . . . . . . . . . . . . . . 949
D.4.12 Changes in release 3.23.48 (07 Feb 2002) . . . . . . 950
D.4.13 Changes in release 3.23.47 (27 Dec 2001). . . . . . 950
D.4.14 Changes in release 3.23.46 (29 Nov 2001) . . . . . 951
D.4.15 Changes in release 3.23.45 (22 Nov 2001) . . . . . 951
D.4.16 Changes in release 3.23.44 (31 Oct 2001) . . . . . . 952
D.4.17 Changes in release 3.23.43 (04 Oct 2001) . . . . . . 953
D.4.18 Changes in release 3.23.42 (08 Sep 2001) . . . . . . 953
D.4.19 Changes in release 3.23.41 (11 Aug 2001) . . . . . 954
D.4.20 Changes in release 3.23.40 . . . . . . . . . . . . . . . . . . . 954
D.4.21 Changes in release 3.23.39 (12 Jun 2001) . . . . . . 955
D.4.22 Changes in release 3.23.38 (09 May 2001) . . . . . 956
D.4.23 Changes in release 3.23.37 (17 Apr 2001) . . . . . 956
D.4.24 Changes in release 3.23.36 (27 Mar 2001) . . . . . 957
D.4.25 Changes in release 3.23.35 (15 Mar 2001) . . . . . 958
D.4.26 Changes in release 3.23.34a . . . . . . . . . . . . . . . . . . 958
D.4.27 Changes in release 3.23.34 (10 Mar 2001) . . . . . 958
D.4.28 Changes in release 3.23.33 (09 Feb 2001) . . . . . . 959
D.4.29 Changes in release 3.23.32 (22 Jan 2001:
Production) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
D.4.30 Changes in release 3.23.31 (17 Jan 2001) . . . . . . 961
D.4.31 Changes in release 3.23.30 (04 Jan 2001) . . . . . . 961
D.4.32 Changes in release 3.23.29 (16 Dec 2000). . . . . . 962
D.4.33 Changes in release 3.23.28 (22 Nov 2000: Gamma)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
D.4.34 Changes in release 3.23.27 (24 Oct 2000) . . . . . . 965
D.4.35 Changes in release 3.23.26 (18 Oct 2000) . . . . . . 966
D.4.36 Changes in release 3.23.25 (29 Sep 2000) . . . . . . 967
D.4.37 Changes in release 3.23.24 (08 Sep 2000) . . . . . . 968
D.4.38 Changes in release 3.23.23 (01 Sep 2000) . . . . . . 968
D.4.39 Changes in release 3.23.22 (31 Jul 2000) . . . . . . 969
D.4.40 Changes in release 3.23.21 . . . . . . . . . . . . . . . . . . . 970
D.4.41 Changes in release 3.23.20 . . . . . . . . . . . . . . . . . . . 970
D.4.42 Changes in release 3.23.19 . . . . . . . . . . . . . . . . . . . 971
D.4.43 Changes in release 3.23.18 . . . . . . . . . . . . . . . . . . . 971
D.4.44 Changes in release 3.23.17 . . . . . . . . . . . . . . . . . . . 971
D.4.45 Changes in release 3.23.16 . . . . . . . . . . . . . . . . . . . 972
D.4.46 Changes in release 3.23.15 (May 2000: Beta) . . 973
xxvi
D.4.47 Changes in release 3.23.14 . . . . . . . . . . . . . . . . . . . 973
D.4.48 Changes in release 3.23.13 . . . . . . . . . . . . . . . . . . . 974
D.4.49 Changes in release 3.23.12 (07 Mar 2000) . . . . . 974
D.4.50 Changes in release 3.23.11 . . . . . . . . . . . . . . . . . . . 975
D.4.51 Changes in release 3.23.10 . . . . . . . . . . . . . . . . . . . 976
D.4.52 Changes in release 3.23.9 . . . . . . . . . . . . . . . . . . . . 976
D.4.53 Changes in release 3.23.8 (02 Jan 2000) . . . . . . . 977
D.4.54 Changes in release 3.23.7 (10 Dec 1999) . . . . . . . 977
D.4.55 Changes in release 3.23.6 . . . . . . . . . . . . . . . . . . . . 978
D.4.56 Changes in release 3.23.5 (20 Oct 1999) . . . . . . . 979
D.4.57 Changes in release 3.23.4 (28 Sep 1999) . . . . . . . 979
D.4.58 Changes in release 3.23.3 . . . . . . . . . . . . . . . . . . . . 980
D.4.59 Changes in release 3.23.2 (09 Aug 1999) . . . . . . 980
D.4.60 Changes in release 3.23.1 . . . . . . . . . . . . . . . . . . . . 981
D.4.61 Changes in release 3.23.0 (05 Aug 1999: Alpha)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
D.5 Changes in release 3.22.x (Old; discontinued) . . . . . . . . . . . 983
D.5.1 Changes in release 3.22.35 . . . . . . . . . . . . . . . . . . . . 983
D.5.2 Changes in release 3.22.34 . . . . . . . . . . . . . . . . . . . . 984
D.5.3 Changes in release 3.22.33 . . . . . . . . . . . . . . . . . . . . 984
D.5.4 Changes in release 3.22.32 (14 Feb 2000) . . . . . . . 984
D.5.5 Changes in release 3.22.31 . . . . . . . . . . . . . . . . . . . . 984
D.5.6 Changes in release 3.22.30 . . . . . . . . . . . . . . . . . . . . 984
D.5.7 Changes in release 3.22.29 (02 Jan 2000) . . . . . . . 984
D.5.8 Changes in release 3.22.28 (20 Oct 1999) . . . . . . . 985
D.5.9 Changes in release 3.22.27 . . . . . . . . . . . . . . . . . . . . 985
D.5.10 Changes in release 3.22.26 (16 Sep 1999) . . . . . . 985
D.5.11 Changes in release 3.22.25 . . . . . . . . . . . . . . . . . . . 985
D.5.12 Changes in release 3.22.24 (05 Jul 1999) . . . . . . 985
D.5.13 Changes in release 3.22.23 (08 Jun 1999) . . . . . . 986
D.5.14 Changes in release 3.22.22 (30 Apr 1999) . . . . . 986
D.5.15 Changes in release 3.22.21 . . . . . . . . . . . . . . . . . . . 986
D.5.16 Changes in release 3.22.20 (18 Mar 1999) . . . . . 987
D.5.17 Changes in release 3.22.19 (Mar 1999: Production)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987
D.5.18 Changes in release 3.22.18 . . . . . . . . . . . . . . . . . . . 987
D.5.19 Changes in release 3.22.17 . . . . . . . . . . . . . . . . . . . 987
D.5.20 Changes in release 3.22.16 (Feb 1999: Gamma)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987
D.5.21 Changes in release 3.22.15 . . . . . . . . . . . . . . . . . . . 988
D.5.22 Changes in release 3.22.14 . . . . . . . . . . . . . . . . . . . 988
D.5.23 Changes in release 3.22.13 . . . . . . . . . . . . . . . . . . . 988
D.5.24 Changes in release 3.22.12 . . . . . . . . . . . . . . . . . . . 989
D.5.25 Changes in release 3.22.11 . . . . . . . . . . . . . . . . . . . 989
D.5.26 Changes in release 3.22.10 . . . . . . . . . . . . . . . . . . . 990
D.5.27 Changes in release 3.22.9 . . . . . . . . . . . . . . . . . . . . 990
D.5.28 Changes in release 3.22.8 . . . . . . . . . . . . . . . . . . . . 991
D.5.29 Changes in release 3.22.7 (Sep 1998: Beta) . . . . 991
xxvii
D.5.30
D.5.31
D.5.32
D.5.33
D.5.34
D.5.35
D.5.36
D.6 Changes
D.6.1
D.6.2
D.6.3
D.6.4
D.6.5
D.6.6
D.6.7
D.6.8
D.6.9
D.6.10
D.6.11
D.6.12
D.6.13
D.6.14
D.6.15
D.6.16
D.6.17
D.6.18
D.6.19
D.6.20
D.6.21
D.6.22
D.6.23
D.6.24
D.6.25
D.6.26
D.6.27
D.6.28
D.6.29
D.6.30
D.6.31
D.6.32
D.6.33
D.6.34
D.6.35
D.7 Changes
D.7.1
D.7.2
D.7.3
D.7.4
Changes in release 3.22.6 . . . . . . . . . . . . . . . . . . . . 992
Changes in release 3.22.5 . . . . . . . . . . . . . . . . . . . . 992
Changes in release 3.22.4 . . . . . . . . . . . . . . . . . . . . 994
Changes in release 3.22.3 . . . . . . . . . . . . . . . . . . . . 994
Changes in release 3.22.2 . . . . . . . . . . . . . . . . . . . . 994
Changes in release 3.22.1 (Jun 1998: Alpha) . . 995
Changes in release 3.22.0 . . . . . . . . . . . . . . . . . . . . 996
in release 3.21.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
Changes in release 3.21.33 . . . . . . . . . . . . . . . . . . . . 997
Changes in release 3.21.32 . . . . . . . . . . . . . . . . . . . . 997
Changes in release 3.21.31 . . . . . . . . . . . . . . . . . . . . 998
Changes in release 3.21.30 . . . . . . . . . . . . . . . . . . . . 998
Changes in release 3.21.29 . . . . . . . . . . . . . . . . . . . . 998
Changes in release 3.21.28 . . . . . . . . . . . . . . . . . . . . 999
Changes in release 3.21.27 . . . . . . . . . . . . . . . . . . . . 999
Changes in release 3.21.26 . . . . . . . . . . . . . . . . . . . . 999
Changes in release 3.21.25 . . . . . . . . . . . . . . . . . . . 1000
Changes in release 3.21.24 . . . . . . . . . . . . . . . . . . 1000
Changes in release 3.21.23 . . . . . . . . . . . . . . . . . . 1000
Changes in release 3.21.22 . . . . . . . . . . . . . . . . . . 1001
Changes in release 3.21.21a . . . . . . . . . . . . . . . . . 1001
Changes in release 3.21.21 . . . . . . . . . . . . . . . . . . 1001
Changes in release 3.21.20 . . . . . . . . . . . . . . . . . . 1002
Changes in release 3.21.19 . . . . . . . . . . . . . . . . . . 1002
Changes in release 3.21.18 . . . . . . . . . . . . . . . . . . 1002
Changes in release 3.21.17 . . . . . . . . . . . . . . . . . . 1002
Changes in release 3.21.16 . . . . . . . . . . . . . . . . . . 1003
Changes in release 3.21.15 . . . . . . . . . . . . . . . . . . 1003
Changes in release 3.21.14b . . . . . . . . . . . . . . . . . 1004
Changes in release 3.21.14a . . . . . . . . . . . . . . . . . 1004
Changes in release 3.21.13 . . . . . . . . . . . . . . . . . . 1005
Changes in release 3.21.12 . . . . . . . . . . . . . . . . . . 1005
Changes in release 3.21.11 . . . . . . . . . . . . . . . . . . 1006
Changes in release 3.21.10 . . . . . . . . . . . . . . . . . . 1006
Changes in release 3.21.9 . . . . . . . . . . . . . . . . . . . 1006
Changes in release 3.21.8 . . . . . . . . . . . . . . . . . . . 1007
Changes in release 3.21.7 . . . . . . . . . . . . . . . . . . . 1007
Changes in release 3.21.6 . . . . . . . . . . . . . . . . . . . 1007
Changes in release 3.21.5 . . . . . . . . . . . . . . . . . . . 1008
Changes in release 3.21.4 . . . . . . . . . . . . . . . . . . . 1008
Changes in release 3.21.3 . . . . . . . . . . . . . . . . . . . 1008
Changes in release 3.21.2 . . . . . . . . . . . . . . . . . . . 1009
Changes in release 3.21.0 . . . . . . . . . . . . . . . . . . . 1010
in release 3.20.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
Changes in release 3.20.18 . . . . . . . . . . . . . . . . . . . 1011
Changes in release 3.20.17 . . . . . . . . . . . . . . . . . . . 1011
Changes in release 3.20.16 . . . . . . . . . . . . . . . . . . . 1012
Changes in release 3.20.15 . . . . . . . . . . . . . . . . . . . 1012
xxviii
D.7.5
D.7.6
D.7.7
D.7.8
D.7.9
D.7.10
D.7.11
D.7.12
D.7.13
D.7.14
D.8 Changes
D.8.1
D.8.2
D.8.3
Changes in release 3.20.14 . . . . . . . . . . . . . . . . . . .
Changes in release 3.20.13 . . . . . . . . . . . . . . . . . . .
Changes in release 3.20.11 . . . . . . . . . . . . . . . . . . .
Changes in release 3.20.10 . . . . . . . . . . . . . . . . . . .
Changes in release 3.20.9 . . . . . . . . . . . . . . . . . . . .
Changes in release 3.20.8 . . . . . . . . . . . . . . . . . . .
Changes in release 3.20.7 . . . . . . . . . . . . . . . . . . .
Changes in release 3.20.6 . . . . . . . . . . . . . . . . . . .
Changes in release 3.20.3 . . . . . . . . . . . . . . . . . . .
Changes in release 3.20.0 . . . . . . . . . . . . . . . . . . .
in release 3.19.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changes in release 3.19.5 . . . . . . . . . . . . . . . . . . . .
Changes in release 3.19.4 . . . . . . . . . . . . . . . . . . . .
Changes in release 3.19.3 . . . . . . . . . . . . . . . . . . . .
1013
1013
1014
1014
1014
1014
1015
1015
1016
1017
1017
1017
1018
1018
Appendix E Porting to Other Systems . . . . . 1019
E.1
E.2
E.3
E.4
E.5
E.6
Debugging a MySQL server. . . . . . . . . . . . . . . . . . . . . . . . . . . 1020
E.1.1 Compiling MYSQL for Debugging . . . . . . . . . . . . 1020
E.1.2 Creating Trace Files . . . . . . . . . . . . . . . . . . . . . . . . . 1021
E.1.3 Debugging mysqld under gdb . . . . . . . . . . . . . . . . 1022
E.1.4 Using a Stack Trace . . . . . . . . . . . . . . . . . . . . . . . . . 1023
E.1.5 Using Log Files to Find Cause of Errors in mysqld
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
E.1.6 Making a Test Case If You Experience Table
Corruption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
Debugging a MySQL client . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
The DBUG Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
Locking methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
Comments about RTS threads . . . . . . . . . . . . . . . . . . . . . . . . 1028
Differences between different thread packages . . . . . . . . . . 1030
Appendix F Environment Variables . . . . . . . . 1032
Appendix G MySQL Regular Expressions . . 1033
Appendix H GNU General Public License . . 1036
SQL command, type and function index . . . . . 1042
Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051
Chapter 1: General Information
1
1 General Information
R
The MySQL °
software delivers a very fast, multi-threaded, multi-user, and robust SQL
(Structured Query Language) database server. MySQL Server is intended for missioncritical, heavy-load production systems as well as for embedding into mass-deployed software. MySQL is a trademark of MySQL AB.
The MySQL software is Dual Licensed. Users can choose to use the MySQL software as an
Open Source/Free Software product under the terms of the GNU General Public License
(http://www.fsf.org/licenses/) or can purchase a standard commercial license from
MySQL AB. See Section 1.4 [Licensing and Support], page 16.
The MySQL web site (http://www.mysql.com/) provides the latest information about the
MySQL software.
The following list describes some sections of particular interest in this manual:
• For information about the company behind the MySQL Database Server, see Section 1.3
[What is MySQL AB], page 12.
• For a discussion about the capabilities of the MySQL Database Server, see Section 1.2.2
[Features], page 5.
• For installation instructions, see Chapter 2 [Installing], page 57.
• For tips on porting the MySQL Database Software to new architectures or operating
systems, see Appendix E [Porting], page 1019.
• For information about upgrading from a Version 4.0 release, see Section 2.5.1
[Upgrading-from-4.0], page 115.
• For information about upgrading from a Version 3.23 release, see Section 2.5.2
[Upgrading-from-3.23], page 117.
• For information about upgrading from a Version 3.22 release, see Section 2.5.3
[Upgrading-from-3.22], page 120.
• For a tutorial introduction to the MySQL Database Server, see Chapter 3 [Tutorial],
page 160.
• For examples of SQL and benchmarking information, see the benchmarking directory
(‘sql-bench’ in the distribution).
• For a history of new features and bug fixes, see Appendix D [News], page 900.
• For a list of currently known bugs and misfeatures, see Section 1.8.6 [Bugs], page 51.
• For future plans, see Section 1.6 [TODO], page 25.
• For a list of all the contributors to this project, see Appendix C [Credits], page 889.
Important:
Reports of errors (often called bugs), as well as questions and comments, should be sent
to the general MySQL mailing list. See Section 1.7.1.1 [Mailing-list], page 31. See Section 1.7.1.3 [Bug reports], page 34.
The mysqlbug script should be used to generate bug reports on Unix. (Windows distributions contain a file ‘mysqlbug.txt’ in the base directory that can be used as a template for
a bug report.)
2
MySQL Technical Reference for Version 4.1.1-alpha
For source distributions, the mysqlbug script can be found in the ‘scripts’ directory. For
binary distributions, mysqlbug can be found in the ‘bin’ directory (‘/usr/bin’ for the
MySQL-server RPM package).
If you have found a sensitive security bug in MySQL Server, you should send an e-mail to
[email protected]
1.1 About This Manual
This is the MySQL reference manual; it documents MySQL up to Version 4.1.1-alpha. Functional changes are always indicated with reference to the version, so this manual is also suitable if you are using an older version of the MySQL software (such as 3.23 or 4.0-production).
There are also references for version 5.0 (development).
Being a reference manual, it does not provide general instruction on SQL or relational
database concepts.
As the MySQL Database Software is under constant development, the manual is
also updated frequently.
The most recent version of this manual is available at
http://www.mysql.com/documentation/ in many different formats, including HTML,
PDF, and Windows HLP versions.
The primary document is the Texinfo file. The HTML version is produced automatically
using a modified version of texi2html. The plain text and Info versions are produced
with makeinfo. The PostScript version is produced using texi2dvi and dvips. The PDF
version is produced with pdftex.
If you have a hard time finding information in the manual, you can try our searchable
version at http://www.mysql.com/doc/.
If you have any suggestions concerning additions or corrections to this manual, please send
them to the documentation team at [email protected]
This manual was initially written by David Axmark and Michael (Monty) Widenius. It
is now maintained by the MySQL Documentation Team, consisting of Arjen Lentz, Paul
DuBois and Stefan Hinz. For the many other contributors, see Appendix C [Credits],
page 889.
The copyright (2003) to this manual is owned by the Swedish company MySQL AB. See
Section 1.4.2 [Copyright], page 16.
1.1.1 Conventions Used in This Manual
This manual uses certain typographical conventions:
constant
Constant-width font is used for command names and options; SQL statements;
database, table, and column names; C and Perl code; and environment variables. Example: “To see how mysqladmin works, invoke it with the --help
option.”
‘filename’
Constant-width font with surrounding quotes is used for filenames and pathnames. Example: “The distribution is installed under the ‘/usr/local/’ directory.”
Chapter 1: General Information
3
‘c’
Constant-width font with surrounding quotes is also used to indicate character
sequences. Example: “To specify a wildcard, use the ‘%’ character.”
italic
Italic font is used for emphasis, like this.
boldface
Boldface font is used in table headings and to convey especially strong emphasis.
When commands are shown that are meant to be executed by a particular program, the
program is indicated by a prompt shown before the command. For example, shell> indicates a command that you execute from your login shell, and mysql> indicates a command
that you execute from the mysql client program:
shell> type a shell command here
mysql> type a mysql command here
The “shell” is your command interpreter. On Unix, this is typically a program such as sh or
csh. On Windows, the equivalent is command.com or cmd.exe, typically run in a Windows
console.
Shell commands are shown using Bourne shell syntax. If you are using a csh-style shell,
you may need to issue commands slightly differently. For example, the sequence to set an
environment variable and run a command looks like this in Bourne shell syntax:
shell> VARNAME=value some_command
For csh or tcsh, you would execute the sequence like this:
shell> setenv VARNAME value
shell> some_command
Database, table, and column names must often be substituted into commands. To indicate
that such substitution is necessary, this manual uses db_name, tbl_name, and col_name.
For example, you might see a statement like this:
mysql> SELECT col_name FROM db_name.tbl_name;
This means that if you were to enter a similar statement, you would supply your own
database, table, and column names, perhaps like this:
mysql> SELECT author_name FROM biblio_db.author_list;
SQL keywords are not case sensitive and may be written in uppercase or lowercase. This
manual uses uppercase.
In syntax descriptions, square brackets (‘[’ and ‘]’) are used to indicate optional words or
clauses. For example, in the following statement, IF EXISTS is optional:
DROP TABLE [IF EXISTS] tbl_name
When a syntax element consists of a number of alternatives, the alternatives are separated by
vertical bars (‘|’). When one member from a set of choices may be chosen, the alternatives
are listed within square brackets (‘[’ and ‘]’):
TRIM([[BOTH | LEADING | TRAILING] [remstr] FROM] str)
When one member from a set of choices must be chosen, the alternatives are listed within
braces (‘{’ and ‘}’):
{DESCRIBE | DESC} tbl_name {col_name | wild}
4
MySQL Technical Reference for Version 4.1.1-alpha
1.2 Overview of the MySQL Database Management System
MySQL, the most popular Open Source SQL database management system, is developed,
distributed, and supported by MySQL AB. MySQL AB is a commercial company, founded by
the MySQL developers, that builds its business by providing services around the MySQL
database management system. See Section 1.3 [What is MySQL AB], page 12.
The MySQL web site (http://www.mysql.com/) provides the latest information about MySQL
software and MySQL AB.
MySQL is a database management system.
A database is a structured collection of data. It may be anything from a simple
shopping list to a picture gallery or the vast amounts of information in a corporate network. To add, access, and process data stored in a computer database,
you need a database management system such as MySQL Server. Since computers are very good at handling large amounts of data, database management
systems play a central role in computing, as stand-alone utilities or as parts of
other applications.
MySQL is a relational database management system.
A relational database stores data in separate tables rather than putting all the
data in one big storeroom. This adds speed and flexibility. The SQL part of
“MySQL” stands for “Structured Query Language”. SQL is the most common
standardised language used to access databases and is defined by the ANSI/ISO
SQL Standard.(The SQL standard has been evolving since 1986 and several
versions exist. In this manual, “SQL-92” refers to the standard released in
1992, “SQL-99” refers to the standard released in 1999, and “SQL:2003” refers
to the version of the standard that is expected to be released in mid-2003.We use
the term “the SQL standard” to mean the current version of the SQL Standard
at any time.)
MySQL software is Open Source.
Open Source means that it is possible for anyone to use and modify the software.
Anybody can download the MySQL software from the Internet and use it without
paying anything. If you wish, you may study the source code and change it
to suit your needs. The MySQL software uses the GPL (GNU General Public
License), http://www.fsf.org/licenses/, to define what you may and may
not do with the software in different situations. If you feel uncomfortable with
the GPL or need to embed MySQL code into a commercial application, you can buy
a commercially licensed version from us. See Section 1.4.3 [MySQL licenses],
page 17.
Why use the MySQL Database Server?
The MySQL Database Server is very fast, reliable, and easy to use. If that is
what you are looking for, you should give it a try. MySQL Server also has a
practical set of features developed in close cooperation with our users. You can
find a performance comparison of MySQL Server with other database managers
on our benchmark page. See Section 5.1.4 [MySQL Benchmarks], page 401.
MySQL Server was originally developed to handle large databases much faster
than existing solutions and has been successfully used in highly demanding pro-
Chapter 1: General Information
5
duction environments for several years. Though 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.
The technical features of MySQL Server
For advanced technical information, see Chapter 6 [Reference], page 446. The
MySQL Database Software is a client/server system that consists of a multithreaded 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 a multi-threaded library which you can link
into your application to get a smaller, faster, easier-to-manage product.
There is a large amount of contributed MySQL software available.
It is very likely that you will find that your favorite application or language
already supports the MySQL Database Server.
The official way to pronounce MySQL is “My Ess Que Ell” (not “my sequel”), but we don’t
mind if you pronounce it as “my sequel” or in some other localised way.
1.2.1 History of MySQL
We started out with the intention of using mSQL to connect to our tables using our own fast
low-level (ISAM) routines. However, after some testing, we came to the conclusion that
mSQL was not fast enough nor 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
chosen to allow third-party code that was written for use with mSQL to be ported easily for
use with MySQL.
The derivation of the name MySQL is not clear. Our base directory and a large number of
our libraries and tools have had the prefix “my” for well over 10 years. However, co-founder
Monty Widenius’s daughter is also named My. Which of the two gave its name to MySQL is
still a mystery, even for us.
The name of the MySQL Dolphin (our logo) is Sakila. Sakila was chosen by the founders
of MySQL AB from a huge list of names suggested by users in our "Name the Dolphin"
contest. The winning name was submitted by Ambrose Twebaze, an open source software
developer from Swaziland, Africa. According to Ambrose, the name Sakila has its roots
in SiSwati, the local language of Swaziland. Sakila is also the name of a town in Arusha,
Tanzania, near Ambrose’s country of origin, Uganda.
1.2.2 The Main Features of MySQL
The following list describes some of the important characteristics of the MySQL Database
Software. See Section 1.5.1 [MySQL 4.0 Nutshell], page 21.
Internals and Portability
• Written in C and C++.
• Tested with a broad range of different compilers.
6
MySQL Technical Reference for Version 4.1.1-alpha
• Works on many different platforms. See Section 2.2.3 [Which OS], page 74.
• Uses GNU Automake, Autoconf, and Libtool for portability.
• APIs for C, C++, Eiffel, Java, Perl, PHP, Python, Ruby, and Tcl are available. See Chapter 11 [Clients], page 725.
• Fully multi-threaded using kernel threads. This means it can easily use
multiple CPUs if they are available.
• Provides transactional and non-transactional storage engines.
• Uses very fast B-tree disk tables (MyISAM) with index compression.
• Relatively easy to add another storage engine. This is useful if you want
to add an SQL interface to an in-house database.
• A very fast thread-based memory allocation system.
• Very fast joins using an optimised one-sweep multi-join.
• In-memory hash tables which are used as temporary tables.
• SQL functions are implemented through a highly optimised class library
and should be as fast as possible. Usually there isn’t any memory allocation
at all after query initialisation.
• The MySQL code is tested with Purify (a commercial memory leakage detector) as well as with Valgrind, a GPL tool
(http://developer.kde.org/~sewardj/).
• Available as client/server or embedded (linked) version.
Column Types
• Many column types: signed/unsigned integers 1, 2, 3, 4, and 8 bytes
long, FLOAT, DOUBLE, CHAR, VARCHAR, TEXT, BLOB, DATE, TIME, DATETIME,
TIMESTAMP, YEAR, SET, and ENUM types. See Section 6.2 [Column types],
page 458.
• Fixed-length and variable-length records.
Commands and Functions
• Full operator and function support in the SELECT and WHERE clauses of
queries. For example:
mysql> SELECT CONCAT(first_name, " ", last_name)
-> FROM tbl_name
-> WHERE income/dependents > 10000 AND age > 30;
• Full support for SQL GROUP BY and ORDER BY clauses. Support for group
functions (COUNT(), COUNT(DISTINCT ...), 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 SQL-92.
• DELETE, INSERT, REPLACE, and UPDATE return the number of rows that were
changed (affected). It is possible to return the number of rows matched
instead by setting a flag when connecting to the server.
Chapter 1: General Information
7
• The MySQL-specific SHOW command can be used to retrieve information
about databases, tables, and indexes. The EXPLAIN command can be used
to determine how the optimiser resolves a query.
• Function names do not clash with table or column names. For example,
ABS is a valid column name. The only restriction is that for a function call,
no spaces are allowed between the function name and the ‘(’ that follows
it. See Section 6.1.7 [Reserved words], page 456.
• You can mix tables from different databases in the same query (as of Version 3.22).
Security
• A privilege and password system that is very flexible and secure, and allows
host-based verification. Passwords are secure because all password traffic
is encrypted when you connect to a server.
Scalability and Limits
• Handles large databases. We use MySQL Server with databases that contain 50 million records. We also know of users that use MySQL Server with
60,000 tables and about 5,000,000,000 rows.
• Up to 32 indexes per table are allowed. Each index may consist of 1 to
16 columns or parts of columns. The maximum index width is 500 bytes
(this may be changed when compiling MySQL Server). An index may use
a prefix of a CHAR or VARCHAR column.
Connectivity
• Clients may connect to the MySQL server using TCP/IP sockets on any
platform. On Windows systems in the NT family (NT, 2000, or XP),
clients may connect using named pipes. On Unix systems, clients may
connect using Unix domain socket files.
• The Connector/ODBC 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
may be run on Windows or Unix. Connector/ODBC source is available. All
ODBC 2.5 functions are supported, as are many others. See Section 11.2
[ODBC], page 817.
Localisation
• The server can provide error messages to clients in many languages. See
Section 4.7.2 [Languages], page 311.
• Full support for several different character sets, including ISO-8859-1
(Latin1), german, big5, ujis, and more. For example, the Scandinavian
characters ‘^
a’, ‘ä’ and ‘ö’ are allowed in table and column names.
• All data is saved in the chosen character set. All comparisons for normal
string columns are case-insensitive.
• Sorting is done according to the chosen character set (the Swedish way by
default). It is possible to change this when the MySQL server is started. To
see an example of very advanced sorting, look at the Czech sorting code.
8
MySQL Technical Reference for Version 4.1.1-alpha
MySQL Server supports many different character sets that can be specified
at compile and runtime.
Clients and Tools
• The MySQL server has built-in support for SQL statements to check, optimise, 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 Database Administration], page 198.
• All MySQL programs can be invoked with the --help or -? options to obtain
online assistance.
1.2.3 Stability of MySQL
This section addresses the questions “How stable is MySQL Server? ” and “Can I depend
on MySQL Server in this project? ” We will try to clarify these issues and answer some
important questions that concern many potential users. The information in this section is
based on data gathered from the mailing list, which is very active in identifying problems
as well as reporting types of use.
The original code stems back from the early 1980s, providing a stable code base, and the
ISAM table format remains backward-compatible. At TcX, the predecessor of MySQL AB,
MySQL code has worked in projects since mid-1996, without any problems. When the MySQL
Database Software was released to a wider public, our new users quickly found some pieces
of “untested code”. Each new release since then has had fewer portability problems (even
though each new release has also had many new features).
Each release of the MySQL Server has been usable. Problems have occurred only when
users try code from the “gray zones.” Naturally, new users don’t know what the gray zones
are; this section therefore attempts to document those areas that are currently known.
The descriptions mostly deal with Version 3.23 and 4.0 of MySQL Server. All known and
reported bugs are fixed in the latest version, with the exception of those listed in the bugs
section, which are design-related. See Section 1.8.6 [Bugs], page 51.
The MySQL Server design is multi-layered with independent modules. Some of the newer
modules are listed here with an indication of how well-tested each of them is:
Replication — Gamma
Large groups of servers using replication are in production use, with good results. Work on enhanced replication features is continuing in MySQL 4.x.
InnoDB tables — Stable (in 3.23 from 3.23.49)
The InnoDB transactional storage engine has been declared stable in the MySQL
3.23 tree, starting from version 3.23.49. InnoDB is being used in large, heavyload production systems.
BDB tables — Gamma
The Berkeley DB code is very stable, but we are still improving the BDB transactional storage engine interface in MySQL Server, so it will take some time
before this is as well tested as the other table types.
Chapter 1: General Information
9
Full-text searches — Beta
Full-text searching works but is not yet widely used. Important enhancements
have been implemented in MySQL 4.0.
MyODBC 3.51 (uses ODBC SDK 3.51) — Stable
In wide production use. Some issues brought up appear to be applicationrelated and independent of the ODBC driver or underlying database server.
Automatic recovery of MyISAM tables — Gamma
This status applies only to the new code in the MyISAM storage engine that
checks if the table was closed properly on open and executes an automatic
check/repair of the table if it wasn’t.
Bulk-insert — Alpha
New feature in MyISAM tables in MySQL 4.0 for faster insert of many rows.
Locking — Gamma
This is very system-dependent. On some systems there are big problems using
standard operating system locking (fcntl()). In these cases, you should run
mysqld with the --skip-external-locking flag. Problems are known to occur
on some Linux systems, and on SunOS when using NFS-mounted filesystems.
Paying customers receive high-quality support directly from MySQL AB. MySQL AB also
provides the MySQL mailing list as a community resource where anyone may ask questions.
Bugs are usually fixed right away with a patch. For serious bugs, there is almost always a
new release.
1.2.4 How Big MySQL Tables Can Be
MySQL Version 3.22 had a 4 GB (4 gigabyte) limit on table size. With the MyISAM table
type in MySQL Version 3.23, the maximum table size was increased to 8 million terabytes (2
^ 63 bytes). With this larger allowed table size, the maximum effective table size for MySQL
databases now normally is determined by operating system constraints on file sizes, not by
MySQL internal limits.
The following table lists some examples of operating system file-size limits:
Operating System
File-Size Limit
Linux-Intel 32-bit
2 GB, much more when using LFS
Linux-Alpha
8 TB (?)
Solaris 2.5.1
2 GB (4GB possible with patch)
Solaris 2.6
4 GB (can be changed with flag)
Solaris 2.7 Intel
4 GB
Solaris 2.7 UltraSPARC
512 GB
On Linux 2.2 you can get tables larger than 2 GB in size by using the LFS patch for the
ext2 filesystem. On Linux 2.4 patches also exist for ReiserFS to get support for big files.
Most current Linux distributions are based on kernel 2.4 and already include all the required
Large File Support (LFS) patches. However, the maximum available file size still depends
on several factors, one of them being the file system used to store MySQL tables.
For a very detailed overview about LFS in Linux, have a look at Andreas Jaeger’s "Large
File Support in Linux" page at http://www.suse.de/~aj/linux_lfs.html.
10
MySQL Technical Reference for Version 4.1.1-alpha
By default, MySQL creates MyISAM tables with an internal structure that allows a maximum
size of about 4 GB. You can check the maximum table size for a table with the SHOW
TABLE STATUS command or with the myisamchk -dv table_name. See Section 4.6.8 [SHOW],
page 287.
If you need a table that will be larger than 4 GB in size (and your operating system
supports large files), the CREATE TABLE statement allows AVG_ROW_LENGTH and MAX_ROWS
options. Use these options to create tables that can be larger than 4 GB. See Section 6.5.3
[CREATE TABLE], page 570. You can also set these options later, with ALTER TABLE. See
Section 6.5.4 [ALTER TABLE], page 579.
Other ways to work around file-size limits for MyISAM tables are as follows:
• If your large table is read-only, you can use myisampack to compress it. myisampack
usually compresses a table by at least 50%, so you can have, in effect, much bigger
tables. myisampack also can merge multiple tables into a single table. See Section 4.8.4
[myisampack], page 320.
• Another way to get around the operating system file limit for MyISAM datafiles is by
using the RAID options. See Section 6.5.3 [CREATE TABLE], page 570.
• MySQL includes a MERGE library that allows you to handle a collection of identical tables
as one. See Section 7.2 [MERGE tables], page 607.
1.2.5 Year 2000 Compliance
The MySQL Server itself has no problems with Year 2000 (Y2K) compliance:
• MySQL Server uses Unix time functions that handle dates into the year 2037 for
TIMESTAMP values. For DATE and DATETIME values, dates through the year 9999 are
accepted.
• All MySQL date functions are stored in one file, ‘sql/time.cc’, and are coded very
carefully to be year 2000-safe.
• In MySQL Version 3.22 and later, the YEAR column type can store years 0 and 1901
to 2155 in one byte and display them using two or four digits. All 2-digit years are
considered to be in the range 1970 to 2069, which means that if you store 01 in a YEAR
column, MySQL Server treats it as 2001.
The following simple demonstration illustrates that MySQL Server doesn’t have any problems with dates until after the year 2030:
mysql> DROP TABLE IF EXISTS y2k;
Query OK, 0 rows affected (0.01 sec)
mysql> CREATE TABLE y2k (date DATE,
->
date_time DATETIME,
->
time_stamp TIMESTAMP);
Query OK, 0 rows affected (0.00 sec)
mysql> INSERT INTO y2k VALUES
-> ("1998-12-31","1998-12-31 23:59:59",19981231235959),
-> ("1999-01-01","1999-01-01 00:00:00",19990101000000),
Chapter 1: General Information
11
-> ("1999-09-09","1999-09-09 23:59:59",19990909235959),
-> ("2000-01-01","2000-01-01 00:00:00",20000101000000),
-> ("2000-02-28","2000-02-28 00:00:00",20000228000000),
-> ("2000-02-29","2000-02-29 00:00:00",20000229000000),
-> ("2000-03-01","2000-03-01 00:00:00",20000301000000),
-> ("2000-12-31","2000-12-31 23:59:59",20001231235959),
-> ("2001-01-01","2001-01-01 00:00:00",20010101000000),
-> ("2004-12-31","2004-12-31 23:59:59",20041231235959),
-> ("2005-01-01","2005-01-01 00:00:00",20050101000000),
-> ("2030-01-01","2030-01-01 00:00:00",20300101000000),
-> ("2050-01-01","2050-01-01 00:00:00",20500101000000);
Query OK, 13 rows affected (0.01 sec)
Records: 13 Duplicates: 0 Warnings: 0
mysql> SELECT * FROM y2k;
+------------+---------------------+----------------+
| date
| date_time
| time_stamp
|
+------------+---------------------+----------------+
| 1998-12-31 | 1998-12-31 23:59:59 | 19981231235959 |
| 1999-01-01 | 1999-01-01 00:00:00 | 19990101000000 |
| 1999-09-09 | 1999-09-09 23:59:59 | 19990909235959 |
| 2000-01-01 | 2000-01-01 00:00:00 | 20000101000000 |
| 2000-02-28 | 2000-02-28 00:00:00 | 20000228000000 |
| 2000-02-29 | 2000-02-29 00:00:00 | 20000229000000 |
| 2000-03-01 | 2000-03-01 00:00:00 | 20000301000000 |
| 2000-12-31 | 2000-12-31 23:59:59 | 20001231235959 |
| 2001-01-01 | 2001-01-01 00:00:00 | 20010101000000 |
| 2004-12-31 | 2004-12-31 23:59:59 | 20041231235959 |
| 2005-01-01 | 2005-01-01 00:00:00 | 20050101000000 |
| 2030-01-01 | 2030-01-01 00:00:00 | 20300101000000 |
| 2050-01-01 | 2050-01-01 00:00:00 | 00000000000000 |
+------------+---------------------+----------------+
13 rows in set (0.00 sec)
The final TIMESTAMP column value is zero because the final year (2050) exceeds the
TIMESTAMP maximum. The TIMESTAMP datatype, which is used to store the current time,
supports values that range from 19700101000000 to 20300101000000 on 32-bit machines
(signed value). On 64-bit machines, TIMESTAMP handles values up to 2106 (unsigned
value).
The example also shows that the DATE and DATETIME datatypes have no problems with the
dates used. They handle dates through the year 9999.
Although MySQL Server itself is Y2K-safe, you may run into problems if you use it with
applications that are not Y2K-safe. For example, many old applications store or manipulate
years using 2-digit values (which are ambiguous) rather than 4-digit values. This problem
may be compounded by applications that use values such as 00 or 99 as “missing” value
indicators. Unfortunately, these problems may be difficult to fix because different applica-
12
MySQL Technical Reference for Version 4.1.1-alpha
tions may be written by different programmers, each of whom may use a different set of
conventions and date-handling functions.
Thus, even though MySQL Server has no Y2K problems, it is the application’s responsibility
to provide unambiguous input. See Section 6.2.2.1 [Y2K issues], page 466 for MySQL Server’s
rules for dealing with ambiguous date input data that contains 2-digit year values.
1.3 Overview of MySQL AB
MySQL AB is the company of the MySQL founders and main developers. MySQL AB was originally established in Sweden by David Axmark, Allan Larsson, and Michael “Monty” Widenius.
The developers of the MySQL server are all employed by the company. We are a virtual organisation with people in a dozen countries around the world. We communicate extensively
over the Net every day with one another and with our users, supporters, and partners.
We are dedicated to developing the MySQL software and spreading our database to new users.
MySQL AB owns the copyright to the MySQL source code, the MySQL logo and trademark, and
this manual. See Section 1.2 [What-is], page 4.
The MySQL core values show our dedication to MySQL and Open Source.
We want the MySQL Database Software to be:
• The best and the most widely used database in the world.
• Available to, and affordable by all.
• Easy to use.
• Continuously improving while remaining fast and safe.
• Fun to use and improve.
• Free from bugs.
MySQL AB and the people at MySQL AB:
• Promote Open Source philosophy and support the Open Source community.
• Aim to be good citizens.
• Prefer partners that share our values and mind-set.
• Answer e-mail and provide support.
• Are a virtual company, networking with others.
• Work against software patents.
The MySQL web site (http://www.mysql.com/) provides the latest information about MySQL
and MySQL AB.
By the way, the “AB” part of the company name is the acronym for the Swedish “aktiebolag”, or “stock company.” It translates to “MySQL, Inc.” In fact, MySQL Inc. and MySQL
GmbH are examples of MySQL AB subsidiaries. They are located in the US and Germany,
respectively.
Chapter 1: General Information
13
1.3.1 The Business Model and Services of MySQL AB
One of the most common questions we encounter is: “How can you make a living from
something you give away for free? ” This is how.
MySQL AB makes money on support, services, commercial licenses, and royalties. We use
these revenues to fund product development and to expand the MySQL business.
The company has been profitable since its inception. In October 2001, we accepted venture financing from leading Scandinavian investors and a handful of business angels. This
investment is used to solidify our business model and build a basis for sustainable growth.
1.3.1.1 Support
MySQL AB is run and owned by the founders and main developers of the MySQL database. The
developers are committed to giving support to customers and other users in order to stay
in touch with their needs and problems. All our support is given by qualified developers.
Really tricky questions are answered by Michael Monty Widenius, principal author of the
MySQL Server. See Section 1.4.1 [Support], page 16.
For more information and ordering support at various levels, see http://www.mysql.com/support/
or contact our sales staff at [email protected]
1.3.1.2 Training and Certification
MySQL AB delivers MySQL and related training worldwide. We offer both open courses and
in-house courses tailored to the specific needs of your company. MySQL Training is also
available through our partners, the Authorised MySQL Training Centers.
Our training material uses the same example databases used in our documentation and
our sample applications, and is always updated to reflect the latest MySQL version. Our
trainers are backed by the development team to guarantee the quality of the training and
the continuous development of the course material. This also ensures that no questions
raised during the courses remain unanswered.
Attending our training courses will enable you to achieve your MySQL application goals. You
will also:
• Save time.
• Improve the performance of your applications.
• Reduce or eliminate the need for additional hardware, decreasing cost.
• Enhance security.
• Increase customers’ and co-workers’ satisfaction.
• Prepare yourself for MySQL Certification.
If you are interested in our training as a potential participant or as a training partner,
please visit the training section at http://www.mysql.com/training/ or contact us at:
[email protected]
For details about the MySQL Certification Program, please see http://www.mysql.com/certification/.
14
MySQL Technical Reference for Version 4.1.1-alpha
1.3.1.3 Consulting
MySQL AB and its Authorised Partners offer consulting services to users of MySQL Server
and to those who embed MySQL Server in their own software, all over the world.
Our consultants can help you design and tune your databases, construct efficient queries,
tune your platform for optimal performance, resolve migration issues, set up replication,
build robust transactional applications, and more. We also help customers embed MySQL
Server in their products and applications for large-scale deployment.
Our consultants work in close collaboration with our development team, which ensures the
technical quality of our professional services. Consulting assignments range from 2-day
power-start sessions to projects that span weeks and months. Our expertise not only covers
MySQL Server—it also extends into programming and scripting languages such as PHP,
Perl, and more.
If you are interested in our consulting services or want to become a consulting partner,
please visit the consulting section of our web site at http://www.mysql.com/consulting/
or contact our consulting staff at [email protected]
1.3.1.4 Commercial Licenses
The MySQL database is released under the GNU General Public License (GPL). This means
that the MySQL software can be used free of charge under the GPL. If you do not want
to be bound by the GPL terms (such as the requirement that your application must also
be GPL, you may purchase a commercial license for the same product from MySQL AB; see
http://www.mysql.com/products/pricing.html. Since MySQL AB owns the copyright to
the MySQL source code, we are able to employ Dual Licensing, which means that the same
product is available under GPL and under a commercial license. This does not in any way
affect the Open Source commitment of MySQL AB. For details about when a commercial
license is required, please see Section 1.4.3 [MySQL licenses], page 17.
We also sell commercial licenses of third-party Open Source GPL software that adds value
to MySQL Server. A good example is the InnoDB transactional storage engine that offers
ACID support, row-level locking, crash recovery, multi-versioning, foreign key support, and
more. See Section 7.5 [InnoDB], page 612.
1.3.1.5 Partnering
MySQL AB has a worldwide partner programme that covers training courses, consulting and
support, publications, plus reselling and distributing MySQL and related products. MySQL AB
Partners get visibility on the http://www.mysql.com/ web site and the right to use special
versions of the MySQL trademarks to identify their products and promote their business.
If you are interested in becoming a MySQL AB Partner, please e-mail [email protected]
The word MySQL and the MySQL dolphin logo are trademarks of MySQL AB. See Section 1.4.4
[MySQL AB Logos and Trademarks], page 19. These trademarks represent a significant
value that the MySQL founders have built over the years.
The MySQL web site (http://www.mysql.com/) is popular among developers and users. In
October 2001, we served 10 million page views. Our visitors represent a group that makes
Chapter 1: General Information
15
purchase decisions and recommendations for both software and hardware. Twelve percent of
our visitors authorise purchase decisions, and only nine percent are not involved in purchase
decisions at all. More than 65% have made one or more online business purchases within
the last half-year, and 70% plan to make one in the next few months.
1.3.2 Contact Information
The MySQL web site (http://www.mysql.com/) provides the latest information about MySQL
and MySQL AB.
For press services and inquiries not covered in our News releases (http://www.mysql.com/news/),
please send an e-mail to [email protected]
If you have a valid support contract with MySQL AB, you will get timely, precise answers to
your technical questions about the MySQL software. For more information, see Section 1.4.1
[Support], page 16. On our web site, see http://www.mysql.com/support/, or send an
e-mail to [email protected]
For information about MySQL training, please visit the training section at
http://www.mysql.com/training/. If you have restricted access to the Internet, please
contact the MySQL AB training staff via e-mail at [email protected] See Section 1.3.1.2
[Business Services Training], page 13.
For information on the MySQL Certification Program, please see http://www.mysql.com/certification
See Section 1.3.1.2 [Business Services Training], page 13.
If you’re interested in consulting, please visit the consulting section of our web site at
http://www.mysql.com/consulting/. If you have restricted access to the Internet, please
contact the MySQL AB consulting staff via e-mail at [email protected] See Section 1.3.1.3 [Business Services Consulting], page 14.
Commercial licenses may be purchased online at https://order.mysql.com/. There you
will also find information on how to fax your purchase order to MySQL AB. More information
about licensing can be found at http://www.mysql.com/products/pricing.html. If you
have questions regarding licensing or you want a quote for a high-volume license deal,
please fill in the contact form on our web site (http://www.mysql.com/) or send an e-mail
message to [email protected] (for licensing questions) or to [email protected] (for
sales inquiries). See Section 1.4.3 [MySQL licenses], page 17.
If you represent a business that is interested in partnering with MySQL AB, please send an
e-mail to [email protected] See Section 1.3.1.5 [Business Services Partnering], page 14.
For more information on the MySQL trademark policy, refer to http://www.mysql.com/company/trademark.
or send an e-mail to [email protected] See Section 1.4.4 [MySQL AB Logos and
Trademarks], page 19.
If you are interested in any of the MySQL AB jobs listed in our jobs section
(http://www.mysql.com/company/jobs/), please send an e-mail to [email protected]
Please do not send your CV as an attachment, but rather as plain text at the end of your
e-mail message.
For general discussion among our many users, please direct your attention to the appropriate
mailing list. See Section 1.7.1 [Questions], page 31.
Reports of errors (often called bugs), as well as questions and comments, should be sent to
the general MySQL mailing list. See Section 1.7.1.1 [Mailing-list], page 31. If you have found
16
MySQL Technical Reference for Version 4.1.1-alpha
a sensitive security bug in the MySQL Server, please send an e-mail to [email protected]
See Section 1.7.1.3 [Bug reports], page 34.
If you have benchmark results that we can publish, please contact us via e-mail at
[email protected]
If you have suggestions concerning additions or corrections to this manual, please send them
to the manual team via e-mail at [email protected]
For questions or comments about the workings or content of the MySQL web site
(http://www.mysql.com/), please send an e-mail to [email protected]
MySQL AB has a privacy policy, which can be read at http://www.mysql.com/company/privacy.html.
For any queries regarding this policy, please send an e-mail to [email protected]
For all other inquires, please send an e-mail to [email protected]
1.4 MySQL Support and Licensing
This section describes MySQL support and licensing arrangements.
1.4.1 Support Offered by MySQL AB
Technical support from MySQL AB means individualised answers to your unique problems
direct from the software engineers who code the MySQL database engine.
We try to take a broad and inclusive view of technical support. Almost any problem
involving MySQL software is important to us if it’s important to you. Typically customers
seek help on how to get different commands and utilities to work, remove performance
bottlenecks, restore crashed systems, understand operating system or networking impacts
on MySQL, set up best practices for backup and recovery, utilise APIs, and so on. Our
support covers only the MySQL server and our own utilities, not third-party products that
access the MySQL server, though we try to help with these where we can.
Detailed information about our various support options is given at http://www.mysql.com/support/,
where support contracts can also be ordered online. If you have restricted access to the
Internet, please contact our sales staff via e-mail at [email protected]
Technical support is like life insurance. You can live happily without it for years, but when
your hour arrives it becomes critically important, yet it’s too late to buy it. If you use
MySQL Server for important applications and encounter sudden difficulties, it may be too
time consuming to figure out all the answers yourself. You may need immediate access to
the most experienced MySQL troubleshooters available, those employed by MySQL AB.
1.4.2 Copyrights and Licenses Used by MySQL
MySQL AB owns the copyright to the MySQL source code, the MySQL logos and trademarks
and this manual. See Section 1.3 [What is MySQL AB], page 12. Several different licenses
are relevant to the MySQL distribution:
1. All the MySQL-specific source in the server, the mysqlclient library and the client, as
well as the GNU readline library is covered by the GNU General Public License. See
Appendix H [GPL license], page 1036. The text of this license can be found as the file
‘COPYING’ in the distribution.
Chapter 1: General Information
17
2. The GNU getopt library is covered by the GNU Lesser General Public License. See
http://www.fsf.org/licenses/.
3. Some parts of the source (the regexp library) are covered by a Berkeley-style copyright.
4. Older versions of MySQL (3.22 and earlier) are subject to a stricter license
(http://www.mysql.com/products/mypl.html).
See the documentation of the
specific version for information.
5. The MySQL reference manual is currently not distributed under a GPL-style license. Use
of the manual is subject to the following terms:
• Conversion to other formats is allowed, but the actual content may not be altered
or edited in any way.
• You may create a printed copy for your own personal use.
• For all other uses, such as selling printed copies or using (parts of) the manual in
another publication, prior written agreement from MySQL AB is required.
Please send an e-mail to [email protected] for more information or if you are interested
in doing a translation.
For information about how the MySQL licenses work in practice, please refer to Section 1.4.3
[MySQL licenses], page 17. Also see Section 1.4.4 [MySQL AB Logos and Trademarks],
page 19.
1.4.3 MySQL Licenses
The MySQL software is released under the GNU General Public License (GPL),
which is probably the best known Open Source license.
The formal terms of
the GPL license can be found at http://www.fsf.org/licenses/.
See also
http://www.fsf.org/licenses/gpl-faq.html and http://www.gnu.org/philosophy/enforcing-gpl.h
Since the MySQL software is released under the GPL, it may often be used for free, but
for certain uses you may want or need to buy commercial licenses from MySQL AB at
https://order.mysql.com/. See http://www.mysql.com/products/licensing.html for
more information.
Older versions of MySQL (3.22 and earlier) are subject to a stricter license
(http://www.mysql.com/products/mypl.html). See the documentation of the specific
version for information.
Please note that the use of the MySQL software under commercial license, GPL, or the old
MySQL license does not automatically give you the right to use MySQL AB trademarks. See
Section 1.4.4 [MySQL AB Logos and Trademarks], page 19.
1.4.3.1 Using the MySQL Software Under a Commercial License
The GPL license is contagious in the sense that when a program is linked to a GPL program
all the source code for all the parts of the resulting product must also be released under
the GPL. If you do not follow this GPL requirement, you break the license terms and forfeit
your right to use the GPL program altogether. You also risk damages.
You need a commercial license:
18
MySQL Technical Reference for Version 4.1.1-alpha
• When you link a program with any GPL code from the MySQL software and don’t want
the resulting product to be licensed under GPL, perhaps because you want to build a
commercial product or keep the added non-GPL code closed source for other reasons.
When purchasing commercial licenses, you are not using the MySQL software under GPL
even though it’s the same code.
• When you distribute a non-GPL application that only works with the MySQL software
and ship it with the MySQL software. This type of solution is considered to be linking
even if it’s done over a network.
• When you distribute copies of the MySQL software without providing the source code
as required under the GPL license.
• When you want to support the further development of the MySQL database even if you
don’t formally need a commercial license. Purchasing support directly from MySQL AB
is another good way of contributing to the development of the MySQL software, with
immediate advantages for you. See Section 1.4.1 [Support], page 16.
If you require a license, you will need one for each installation of the MySQL software. This
covers any number of CPUs on a machine, and there is no artificial limit on the number of
clients that connect to the server in any way.
For commercial licenses, please visit our website at http://www.mysql.com/products/licensing.html.
For support contracts, see http://www.mysql.com/support/. If you have special needs
or you have restricted access to the Internet, please contact our sales staff via e-mail at
[email protected]
1.4.3.2 Using the MySQL Software for Free Under GPL
You can use the MySQL software for free under the GPL if you adhere to the
conditions of the GPL. For additional details, including answers to common questions about the GPL, see the generic FAQ from the Free Software Foundation at
http://www.fsf.org/licenses/gpl-faq.html. Common uses of the GPL include:
• When you distribute both your own application and the MySQL source code under the
GPL with your product.
• When you distribute the MySQL source code bundled with other programs that are not
linked to or dependent on the MySQL system for their functionality even if you sell the
distribution commercially. This is called mere aggregation in the GPL license.
• When you are not distributing any part of the MySQL system, you can use it for free.
• When you are an Internet Service Provider (ISP), offering web hosting with MySQL
servers for your customers. We encourage people to use ISPs that have MySQL support,
as this will give them the confidence that their ISP will, in fact, have the resources to
solve any problems they may experience with the MySQL installation. Even if an ISP
does not have a commercial license for MySQL Server, their customers should at least
be given read access to the source of the MySQL installation so that the customers can
verify that it is correctly patched.
• When you use the MySQL database software in conjunction with a web server, you do
not need a commercial license (so long as it is not a product you distribute). This is
true even if you run a commercial web server that uses MySQL Server, because you are
Chapter 1: General Information
19
not distributing any part of the MySQL system. However, in this case we would like you
to purchase MySQL support because the MySQL software is helping your enterprise.
If your use of MySQL database software does not require a commercial license, we encourage
you to purchase support from MySQL AB anyway. This way you contribute toward MySQL
development and also gain immediate advantages for yourself. See Section 1.4.1 [Support],
page 16.
If you use the MySQL database software in a commercial context such that you profit by its
use, we ask that you further the development of the MySQL software by purchasing some
level of support. We feel that if the MySQL database helps your business, it is reasonable to
ask that you help MySQL AB. (Otherwise, if you ask us support questions, you are not only
using for free something into which we’ve put a lot a work, you’re asking us to provide free
support, too.)
1.4.4 MySQL AB Logos and Trademarks
Many users of the MySQL database want to display the MySQL AB dolphin logo
on their web sites, books, or boxed products.
We welcome and encourage this,
although it should be noted that the word MySQL and the MySQL dolphin logo are
trademarks of MySQL AB and may only be used as stated in our trademark policy at
http://www.mysql.com/company/trademark.html.
1.4.4.1 The Original MySQL Logo
The MySQL dolphin logo was designed by the Finnish advertising agency Priority in 2001.
The dolphin was chosen as a suitable symbol for the MySQL database since it is a smart, fast,
and lean animal, effortlessly navigating oceans of data. We also happen to like dolphins.
The original MySQL logo may only be used by representatives of MySQL AB and by those
having a written agreement allowing them to do so.
1.4.4.2 MySQL Logos that may be Used Without Written
Permission
We have designed a set of special Conditional Use logos that may be downloaded from
our web site at http://www.mysql.com/press/logos.html and used on third-party web
sites without written permission from MySQL AB. The use of these logos is not entirely
unrestricted but, as the name implies, subject to our trademark policy that is also available
on our web site. You should read through the trademark policy if you plan to use them.
The requirements are basically as follows:
• Use the logo you need as displayed on the http://www.mysql.com/ site. You may
scale it to fit your needs, but may not change colours or design, or alter the graphics
in any way.
• Make it evident that you, and not MySQL AB, are the creator and owner of the site that
displays the MySQL trademark.
20
MySQL Technical Reference for Version 4.1.1-alpha
• Don’t use the trademark in a way that is detrimental to MySQL AB or to the value of
MySQL AB trademarks. We reserve the right to revoke the right to use the MySQL AB
trademark.
• If you use the trademark on a web site, make it clickable, leading directly to
http://www.mysql.com/.
• If you use the MySQL database under GPL in an application, your application must be
Open Source and must be able to connect to a MySQL server.
Contact us via e-mail at [email protected] to inquire about special arrangements to
fit your needs.
1.4.4.3 When You Need Written Permission to Use MySQL Logos
You need written permission from MySQL AB before using MySQL logos in the following cases:
• When displaying any MySQL AB logo anywhere except on your web site.
• When displaying any MySQL AB logo except the Conditional Use logos mentioned previously on web sites or elsewhere.
Due to legal and commercial reasons we monitor the use of MySQL trademarks on products, books, and other items. We usually require a fee for displaying MySQL AB logos on
commercial products, since we think it is reasonable that some of the revenue is returned
to fund further development of the MySQL database.
1.4.4.4 MySQL AB Partnership Logos
MySQL partnership logos may be used only by companies and persons having a written
partnership agreement with MySQL AB. Partnerships include certification as a MySQL trainer
or consultant. For more information, please see Section 1.3.1.5 [Partnering], page 14.
1.4.4.5 Using the Word MySQL in Printed Text or Presentations
MySQL AB welcomes references to the MySQL database, but it should be noted that the word
MySQL is a trademark of MySQL AB. Because of this, you must append the trademark symbol
(TM) to the first or most prominent use of the word MySQL in a text and, where appropriate,
state that MySQL is a trademark of MySQL AB. For more information, please refer to our
trademark policy at http://www.mysql.com/company/trademark.html.
1.4.4.6 Using the Word MySQL in Company and Product Names
Use of the word MySQL in product or company names or in Internet domain names is not
allowed without written permission from MySQL AB.
Chapter 1: General Information
21
1.5 MySQL Development Roadmap
This section provides a snapshot of the MySQL development roadmap, including major
features implemented or planned for MySQL 4.0, 4.1, 5.0, and 5.1 The following sections
provide information for each version series. Plans for some of the most requested features
are summarized in the following table.
Feature
Unions
Subqueries
R-trees
Stored procedures
Views
Cursors
Foreign keys
Triggers
Full outer join
Constraints
MySQL version
4.0
4.1
4.1 (for MyISAM tables)
5.0
5.0 or 5.1
5.0
5.1 (already implemented in 3.23 for InnoDB)
5.1
5.1
5.1
1.5.1 MySQL 4.0 in a Nutshell
Long awaited by our users, MySQL Server 4.0 is now available in production status.
MySQL 4.0 is available for download from http://www.mysql.com/ and from our mirrors.
MySQL 4.0 has been tested by a large number of users and is in production use at many
large sites.
The major new features of MySQL Server 4.0 are geared toward our existing business and
community users, enhancing the MySQL database software as the solution for missioncritical, heavy-load database systems. Other new features target the users of embedded
databases.
MySQL 4.0 was declared stable for production use as of Version 4.0.12, released in March
2003. This means that, in the future, only bug fixes will be done for the 4.0 series and only
critical bug fixes will be done for the older 3.23 series. See Section 2.5.2 [Upgrading-from3.23], page 117.
New features to the MySQL software are being added to MySQL 4.1 which is now also
available (alpha version). See Section 1.5.2 [MySQL 4.1 Nutshell], page 23.
1.5.1.1 Features Available in MySQL 4.0
Speed enhancements
• MySQL 4.0 has a query cache that can give a huge speed boost to applications with repetitive queries. See Section 6.9 [Query Cache], page 596.
• Version 4.0 further increases the speed of MySQL Server in a number
of areas, such as bulk INSERTs, searching on packed indexes, creation of
FULLTEXT indexes, and COUNT(DISTINCT).
22
MySQL Technical Reference for Version 4.1.1-alpha
Embedded MySQL Server introduced
• The new Embedded Server library can easily be used to create standalone
and embedded applications. The embedded server provides an alternative to using MySQL in a client/server environment. See Section 1.5.1.2
[Nutshell Embedded MySQL], page 23.
InnoDB storage engine as standard
• The InnoDB storage engine is now offered as a standard feature of the
MySQL server. This means full support for ACID transactions, foreign keys
with cascading UPDATE and DELETE, and row-level locking are now standard
features. See Section 7.5 [InnoDB], page 612.
New functionality
• The enhanced FULLTEXT search properties of MySQL Server 4.0 enables
FULLTEXT indexing of large text masses with both binary and naturallanguage searching logic. You can customise minimal word length and
define your own stop word lists in any human language, enabling a new
set of applications to be built on MySQL Server. See Section 6.8 [Fulltext
Search], page 590.
Standards compliance, portability, and migration
• Features to simplify migration from other database systems to MySQL
Server include TRUNCATE TABLE (as in Oracle).
• Many users will also be happy to learn that MySQL Server now supports
the UNION statement, a long-awaited standard SQL feature.
• MySQL now runs natively on the Novell NetWare 6.0 platform. See Section 2.6.8 [Novell NetWare], page 155.
Internationalisation
• Our German, Austrian, and Swiss users will note that MySQL now supports
a new character set, latin1_de, which ensures that the German sorting
order sorts words with umlauts in the same order as do German telephone
books.
Usability enhancements
In the process of implementing features for new users, we have not forgotten
requests from our loyal community of existing users.
• Most mysqld parameters (startup options) can now be set without taking
down the server. This is a convenient feature for database administrators
(DBAs). See Section 5.5.6 [SET OPTION], page 437.
• Multiple-table DELETE and UPDATE statements have been added..
• Support has been added to the MyISAM storage engine for symbolic linking
at the table level (and not just the database level as before). Also, symbolic
link handling at the database level is enabled by default on Windows.
• SQL_CALC_FOUND_ROWS and FOUND_ROWS() are new functions that make it
possible to find out the number of rows a SELECT query that includes a
LIMIT clause would have returned without that clause.
The news section of this manual includes a more in-depth list of features. See Section D.3
[News-4.0.x], page 908.
Chapter 1: General Information
23
1.5.1.2 Embedded MySQL Server
libmysqld makes MySQL Server suitable for a vastly expanded realm of applications. Using
the embedded MySQL server library, one can embed MySQL Server into various applications
and electronics devices, where the end user has no knowledge of there actually being an
underlying database. Embedded MySQL Server is ideal for use behind the scenes in Internet
appliances, public kiosks, turnkey hardware/software combination units, high performance
Internet servers, self-contained databases distributed on CD-ROM, and so on.
Many users of libmysqld will benefit from the MySQL Dual Licensing. For those not
wishing to be bound by the GPL, the software is also made available under a commercial
license. The embedded MySQL library uses the same interface as the normal client library,
so it is convenient and easy to use. See Section 11.1.15 [libmysqld], page 811.
1.5.2 MySQL 4.1 in a Nutshell
MySQL Server 4.0 laid the foundation for new features such as subqueries and Unicode
(implemented in version 4.1) and for the work on SQL-99 stored procedures being done for
version 5.0. These features come at the top of the wish list of many of our customers.
With these additions, critics of the MySQL Database Server have to be more imaginative
than ever in pointing out deficiencies in the MySQL database management system. Already
well-known for its stability, speed, and ease of use, MySQL Server will be able to fulfill the
requirement checklists of very demanding buyers.
1.5.2.1 Features Available in MySQL 4.1
The features listed in this section are implemented in MySQL 4.1. A few other features are
still planned for MySQL 4.1. See Section 1.6.1 [TODO MySQL 4.1], page 25.
Most new features being coded, such as stored procedures, will be available in MySQL 5.0.
See Section 1.6.2 [TODO MySQL 5.0], page 26.
Support for subqueries and derived tables
• A subquery is a SELECT statement nested within another statement. A
derived table (an unnamed view) is a subquery in the FROM clause of another
statement. See Section 6.4.2 [Subqueries], page 543.
Speed enhancements
• Faster binary protocol with prepared statements and parameter binding.
See Section 11.1.4 [C API Prepared statements], page 776.
• BTREE indexing is now supported for HEAP tables, significantly improving
response time for non-exact searches.
New functionality
• CREATE TABLE table_name2 LIKE table_name1 allows you to create, with
a single statement, a new table with a structure exactly like that of an
existing table.
• Support for OpenGIS spatial types (geographical data). See Chapter 10
[Spatial extensions in MySQL], page 696.
24
MySQL Technical Reference for Version 4.1.1-alpha
• Replication can be done over SSL connections.
Standards compliance, portability, and migration
• The new client/server protocol adds the ability to pass multiple warnings
to the client, rather than only a single result. This makes jobs such as bulk
loading of data much easier to track. SHOW WARNINGS shows warnings for
the last command. See Section 4.6.8.9 [SHOW WARNINGS], page 307.
Internationalisation
• To support our ever expanding user base using local languages in applications, the MySQL software now offers extensive Unicode support through
the utf8 and ucs2 character sets.
• Character sets can now be defined per column, table, and database. This
allows for a high degree of flexibility in application design, particularly for
multi-language web sites.
• For documentation for this improved character set support, see Chapter 9
[Charset], page 674.
Usability enhancements
• In response to popular demand, we have added a server-based HELP command that can be used to get help information for SQL statements. The
advantage of having this information on the server side is that the information is always applicable for that particular server version. Because
this information is available by issuing a SQL statement, any client can be
written to access it. For example, the mysql command line client has been
modified to have this capability.
• In the new client/server protocol, multiple statements can be issued with
a single call. See Section 11.1.8 [C API multiple queries], page 803.
• The new client/server protocol also supports returning multiple result sets.
This might occur as a result of sending multiple statements, for example.
(See previous item.)
• A new INSERT ... ON DUPLICATE KEY UPDATE ... syntax has been implemented. This allows you to UPDATE an existing row if the INSERT would
have caused a duplicate in a PRIMARY or UNIQUE key (index). See Section 6.4.3 [INSERT], page 552.
• We have implemented a new aggregate function, GROUP_CONCAT(), that
adds the extremely useful capability of concatenating columns from
grouped rows into a single result string. See Section 6.3.7 [Group by
functions and modifiers], page 530.
The news section in this manual includes a more in-depth list of features. See Section D.2
[News-4.1.x], page 900.
1.5.2.2 Stepwise Rollout
New features are being added to MySQL 4.1. The alpha version is already available for
download. See Section 1.5.2.3 [Nutshell Ready for Immediate Use], page 25.
Chapter 1: General Information
25
The set of features that are being added to version 4.1 is mostly fixed. Additional development is already ongoing for version 5.0. MySQL 4.1 will go through the steps of Alpha
(during which time new features might still be added/changed), Beta (when we have feature
freeze and only bug corrections will be done), and Gamma (indicating that a production
release is just weeks ahead). At the end of this process, MySQL 4.1 will become the new
production release.
1.5.2.3 Ready for Immediate Development Use
MySQL 4.1 is currently in the alpha stage, and binaries are available for download at
http://www.mysql.com/downloads/mysql-4.1.html. All binary releases pass our extensive test suite without any errors on the platforms on which we test. See Section D.2
[News-4.1.x], page 900.
For those wishing to use the most recent development source for MySQL 4.1, we have made
our 4.1 BitKeeper repository publicly available. See Section 2.3.4 [Installing source tree],
page 95.
1.5.3 MySQL 5.0, The Next Development Release
New development for MySQL is focused on the 5.0 release, featuring Stored Procedures and
other new features. See Section 1.6.2 [TODO MySQL 5.0], page 26.
For those wishing to take a look at the bleeding edge of MySQL development, we have
made our BitKeeper repository for MySQL version 5.0 publicly available. See Section 2.3.4
[Installing source tree], page 95.
1.6 MySQL and the Future (The TODO)
This section summarises the features that we plan to implement in MySQL Server. The lists
are broken up per version, and the items are approximately in the order they will be done.
Note: If you are an enterprise level user with an urgent need for a particular feature, please
contact [email protected] to discuss sponsoring options. Targeted financing by sponsor
companies allows us to allocate additional resources for specific purposes. One example of
a feature sponsored in the past is replication.
1.6.1 New Features Planned For 4.1
The features below are not yet implemented in MySQL 4.1, but are planned for implementation before MySQL 4.1 moves into its beta phase. For a list what is already done in
MySQL 4.1, see Section 1.5.2.1 [Nutshell 4.1 features], page 23.
• Stable OpenSSL support (MySQL 4.0 supports rudimentary, not 100% tested, support
for OpenSSL).
• More testing of prepared statements.
• More testing of multiple character sets for one table.
26
MySQL Technical Reference for Version 4.1.1-alpha
1.6.2 New Features Planned For 5.0
The following features are planned for inclusion into MySQL 5.0. Note that because we have
many developers that are working on different projects, there will also be many additional
features. There is also a small chance that some of these features will be added to MySQL
4.1. For a list what is already done in MySQL 4.1, see Section 1.5.2.1 [Nutshell 4.1 features],
page 23.
For those wishing to take a look at the bleeding edge of MySQL development, we have
made our BitKeeper repository for MySQL version 5.0 publicly available. See Section 2.3.4
[Installing source tree], page 95.
Stored Procedures
• Stored procedures are currently being implemented. This effort is based
on SQL-99, which has a basic syntax similar (but not identical) to Oracle
PL/SQL. We will also implement the SQL-99 framework to hook in external
languages, and (where possible) compatibility with, for example, PL/SQL
and T-SQL.
New functionality
• Elementary cursor support.
• The ability to specify explicitly for MyISAM tables that an index should be
created as an RTREE index. In 4.1, RTREE indexes are used internally for
geometrical data (GIS datatypes), but cannot be created on request.
• Dynamic length rows for HEAP tables.
Standards compliance, portability and migration
• Add true VARCHAR support (column lengths longer than 255, and no stripping of trailing whitespace). (There is already support for this in the
MyISAM storage engine, but it is not yet available at the user level.)
Speed enhancements
• SHOW COLUMNS FROM table_name (used by mysql client to allow expansions
of column names) should not open the table, only the definition file. This
will require less memory and be much faster.
• Allow DELETE on MyISAM tables to use the record cache. To do this, we
need to update the threads record cache when we update the ‘.MYD’ file.
• Better in-memory (HEAP) tables:
• Dynamic size rows.
• Faster row handling (less copying).
Internationalisation
• When using SET CHARACTER SET we should translate the whole query at
once and not only strings. This will enable users to use the translated
characters in database, table, and column names.
Usability enhancements
• Resolving the issue of RENAME TABLE on a table used in an active MERGE
table possibly corrupting the table.
Chapter 1: General Information
27
1.6.3 New Features Planned For 5.1
New functionality
• FOREIGN KEY support for all table types.
• Column-level constraints.
• Fail-safe replication.
• Online backup with very low performance penalty. The online backup will
make it easy to add a new replication slave without taking down the master.
Speed enhancements
• New text based table definition file format (‘.frm’ files) and a table cache
for table definitions. This will enable us to do faster queries of table structures and do more efficient foreign key support.
• Optimise BIT type to take 1 bit. (BIT now takes 1 byte; it is treated as a
synonym for TINYINT.)
Usability enhancements
• Add options to the client/server protocol to get progress notes for long
running commands.
• Implement RENAME DATABASE. To make this safe for all storage engines, it
should work as follows:
• Create the new database.
• For every table do a rename of the table to another database, as we
do with the RENAME command.
• Drop the old database.
• New internal file interface change. This will make all file handling much
more general and make it easier to add extensions like RAID.
1.6.4 New Features Planned for the Near Future
New functionality
• Oracle-like CONNECT BY PRIOR ... to search tree-like (hierarchical) structures.
• Add all missing SQL-92 and ODBC 3.0 types.
• Add SUM(DISTINCT).
• INSERT SQL_CONCURRENT and mysqld --concurrent-insert to do a concurrent insert at the end of a table if the table is read-locked.
• Allow update of variables in UPDATE statements. For example: UPDATE
TABLE foo SET @a=a+b,[email protected], [email protected]+c.
• Change when user variables are updated so that one can use them with
GROUP BY, as in the following example: SELECT id, @a:=COUNT(*),
SUM(sum_col)/@a FROM table_name GROUP BY id.
• Add an IMAGE option to LOAD DATA INFILE to not update TIMESTAMP and
AUTO_INCREMENT fields.
28
MySQL Technical Reference for Version 4.1.1-alpha
• Add LOAD DATA INFILE ... UPDATE syntax that works like this:
• For tables with primary keys, if an input record contains a primary key
value, existing rows matching that primary key value are updated from
the remainder of the input columns. However, columns corresponding
to columns that are missing from the input record are not touched.
• For tables with primary keys, if an input record does not contain the
primary key value or is missing some part of the key, the record is
treated as LOAD DATA INFILE ... REPLACE INTO.
• Make LOAD DATA INFILE understand syntax like:
LOAD DATA INFILE ’file_name.txt’ INTO TABLE tbl_name
TEXT_FIELDS (text_field1, text_field2, text_field3)
SET table_field1=CONCAT(text_field1, text_field2),
table_field3=23
IGNORE text_field3
This can be used to skip over extra columns in the text file, or update
columns based on expressions of the read data.
• New functions for working with SET type columns:
• ADD_TO_SET(value,set)
• REMOVE_FROM_SET(value,set)
• If you abort mysql in the middle of a query, you should open another
connection and kill the old running query. Alternatively, an attempt should
be made to detect this in the server.
• Add a storage engine interface for table information so that you can use it
as a system table. This would be a bit slow if you requested information
about all tables, but very flexible. SHOW INFO FROM tbl_name for basic
table information should be implemented.
• Allow SELECT a FROM table_name1 LEFT JOIN table_name2 USING (a);
in this case a is assumed to come from the table_name1 table.
• DELETE and REPLACE options to the UPDATE statement (this will delete rows
when one gets a duplicate key error while updating).
• Change the format of DATETIME to store fractions of seconds.
• Make it possible to use the new GNU regexp library instead of the current
one (the new library should be much faster than the current one).
Standards compliance, portability and migration
• Don’t add automatic DEFAULT values to columns. Produce an error for
any INSERT statement that is missing a value for a column that has no
DEFAULT.
• Add ANY(), EVERY(), and SOME() group functions. In standard SQL, these
work only on boolean columns, but we can extend these to work on any
columns/expressions by treating 0 values as FALSE and non-zero values as
TRUE.
• Fix the type of MAX(column) to be the same as the column type:
Chapter 1: General Information
mysql>
mysql>
mysql>
mysql>
29
CREATE TABLE t1 (a DATE);
INSERT INTO t1 VALUES (NOW());
CREATE TABLE t2 SELECT MAX(a) FROM t1;
SHOW COLUMNS FROM t2;
Speed enhancements
• Don’t allow more than a defined number of threads to run MyISAM recover
at the same time.
• Change INSERT ... SELECT to optionally use concurrent inserts.
• Add an option to periodically flush key pages for tables with delayed keys
if they haven’t been used in a while.
• Allow join on key parts (optimisation issue).
• Add simulation of pread()/pwrite() on Windows to enable concurrent
inserts.
• Add a logfile analyser that could parse out information about which tables
are hit most often, how often multiple-table joins are executed, etc. This
should help users identify areas or table design that could be optimised to
execute much more efficient queries.
Internationalisation
Usability enhancements
• Return the original field types() when doing SELECT MIN(column) ...
GROUP BY.
• Make it possible to specify long_query_time with a granularity in microseconds.
• Link the myisampack code into the server so that it can perform PACK or
COMPRESS operations.
• Add a temporary key buffer cache during INSERT/DELETE/UPDATE so that
we can gracefully recover if the index file gets full.
• If you perform an ALTER TABLE on a table that is symlinked to another
disk, create temporary tables on that disk.
• Implement a DATE/DATETIME type that handles time zone information properly, to make dealing with dates in different time zones easier.
• Fix configure so that one can compile all libraries (like MyISAM) without
threads.
• Allow SQL variables as LIMIT arguments, for example, LIMIT @a,@b.
• Automatic output from mysql to a web browser.
• LOCK DATABASES (with various options).
• Many more variables for SHOW STATUS. Records reads and updates. Selects
on a single table and selects with joins. Mean number of tables in select.
Number of ORDER BY and GROUP BY queries.
• mysqladmin copy database new-database; this requires a COPY operation
to be added to mysqld.
• Processlist output should indicate the number of queries/threads.
30
MySQL Technical Reference for Version 4.1.1-alpha
• SHOW HOSTS for printing information about the hostname cache.
• Change table names from empty strings to NULL for calculated columns.
• Don’t use Item_copy_string on numerical values to avoid number->string>number conversion in case of: SELECT COUNT(*)*(id+0) FROM table_
name GROUP BY id
• Change so that ALTER TABLE doesn’t abort clients that execute INSERT
DELAYED.
• Fix so that when columns are referenced in an UPDATE clause, they contain
the old values from before the update started.
New operating systems
• Port of the MySQL clients to LynxOS.
1.6.5 New Features Planned for the Mid-Term Future
• Implement function: get_changed_tables(timeout,table1,table2,...).
• Change reading through tables to use memmap when possible. Now only compressed
tables use memmap.
• Make the automatic timestamp code nicer. Add timestamps to the update log with
SET TIMESTAMP=#;.
• Use read/write mutex in some places to get more speed.
• Simple views (stepwise implementation up to full functionality). See Section 1.8.4.6
[ANSI diff Views], page 48.
• Automatically close some tables if a table, temporary table, or temporary files gets
error 23 (not enough open files).
• Better constant propagation. When an occurrence of col_name=n is found in an expression, for some constant n, replace other occurrences of col_name within the expression
with n. Currently, this is done only for some simple cases.
• Change all const expressions with calculated expressions if possible.
• Optimise key = expression. At the moment only key = field or key = constant are
optimised.
• Join some of the copy functions for nicer code.
• Change ‘sql_yacc.yy’ to an inline parser to reduce its size and get better error messages (5 days).
• Change the parser to use only one rule per different number of arguments in function.
• Use of full calculation names in the order part (for ACCESS97).
• MINUS, INTERSECT, and FULL OUTER JOIN. (Currently UNION [in 4.0] and LEFT|RIGHT
OUTER JOIN are supported.)
• Allow SQL_OPTION MAX_SELECT_TIME=#, for placing a time limit on a query.
• Make the update log write to a database.
• Enhance LIMIT to allow retrieval of data from the end of a result set.
• Alarm around client connect/read/write functions.
Chapter 1: General Information
31
• Please note the changes to mysqld_safe: according to FSSTND (which Debian tries
to follow) PID files should go into ‘/var/run/<progname>.pid’ and log files into
‘/var/log’. It would be nice if you could put the "DATADIR" in the first declaration of "pidfile" and "log", so the placement of these files can be changed with a
single statement.
• Allow a client to request logging.
• Add use of zlib() to LOAD DATA INFILE, to allow the statement to read files that have
been compressed with gzip.
• Fix sorting and grouping of BLOB columns (partly solved now).
• Change to use semaphores when counting threads. One should first implement a
semaphore library for MIT-pthreads.
• Add full support for JOIN with parentheses.
• As an alternative for one thread/connection manage a pool of threads to handle the
queries.
• Allow GET_LOCK() to obtain more than one lock. When doing this, one must also
handle the possible deadlocks this change will introduce.
Time is given according to amount of work, not real time.
1.6.6 New Features We Don’t Plan to Do
We aim toward full compliance with SQL-92/SQL-99; there are no features we plan not to
implement.
1.7 MySQL Information Sources
1.7.1 MySQL Mailing Lists
This section introduces you to the MySQL mailing lists and provides some guidelines as
to how the lists should be used. When you subscribe to a mailing list, you will receive, as
e-mail messages, all postings to the list. You will also be able to send your own questions
and answers to the list.
1.7.1.1 The MySQL Mailing Lists
To subscribe to or unsubscribe from any of the mailing lists described in this section, visit
http://lists.mysql.com/. 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.
32
MySQL Technical Reference for Version 4.1.1-alpha
If you wish to have traffic for a mailing list go to a separate mailbox in your mail program, set
up a filter based on the message headers. You can use either the List-ID: or DeliveredTo: headers to identify list messages.
The MySQL mailing lists are as follows:
announce
This list is for announcements of new versions of MySQL and related programs.
This is a low-volume list to which all MySQL users should subscribe.
mysql
This is the main list for general MySQL discussion. Please note that some
topics are better discussed on the more-specialised lists. If you post to the
wrong list, you may not get an answer.
mysql-digest
This is the mysql list in digest form. Subscribing to this list means you will get
all list messages, sent as one large mail message once a day.
bugs
This list will be of interest to you if you want to stay informed about issues
reported since the last release of MySQL or if you want to be actively involved
in the process of bug hunting and fixing. See Section 1.7.1.3 [Bug reports],
page 34.
bugs-digest
This is the bugs list in digest form.
internals
This list is for people who work on the MySQL code. This is also the forum for
discussions on MySQL development and post patches.
internals-digest
This is the internals list in digest form.
mysqldoc
This list is for people who work on the MySQL documentation: people from
MySQL AB, translators, and other community members.
mysqldoc-digest
This is the mysqldoc list in digest form.
benchmarks
This list is for anyone interested in performance issues. Discussions concentrate
on database performance (not limited to MySQL) but also include broader
categories such as performance of the kernel, file system, disk system, and so
on.
benchmarks-digest
This is the benchmarks list in digest form.
packagers
This list is for discussions on packaging and distributing MySQL. This is the
forum used by distribution maintainers to exchange ideas on packaging MySQL
and on ensuring that MySQL looks and feels as similar as possible on all supported platforms and operating systems.
packagers-digest
This is the packagers list in digest form.
Chapter 1: General Information
java
33
This list is for discussions about the MySQL server and Java.It is mostly used
to discuss JDBC drivers, including MySQL Connector/J.
java-digest
This is the java list in digest form.
win32
This list is for all topics concerning the MySQL software on Microsoft operating
systems, such as Windows 9x/Me/NT/2000/XP.
win32-digest
This is the win32 list in digest form.
myodbc
This list is for all topics concerning connecting to the MySQL server with
ODBC.
myodbc-digest
This is the myodbc list in digest form.
mysqlcc
This list is for all topics concerning the MySQL Control Center graphical client.
mysqlcc-digest
This is the mysqlcc list in digest form.
plusplus
This list is for all topics concerning programming with the C++ API to MySQL.
plusplus-digest
This is the plusplus list in digest form.
msql-mysql-modules
This list is for all topics concerning the Perl support for MySQL with msqlmysql-modules, which is now named DBD-mysql.
msql-mysql-modules-digest
This is the msql-mysql-modules list in digest form.
If you’re unable to get an answer to your questions from a MySQL mailing list, one option
is to pay for support from MySQL AB. This will put you in direct contact with MySQL
developers. See Section 1.4.1 [Support], page 16.
The following table shows some MySQL mailing lists in languages other than English. These
lists are not operated by MySQL AB, so we can’t guarantee their quality.
[email protected] A French mailing list
[email protected] A Korean mailing list
E-mail subscribe mysql [email protected] to this list.
[email protected] A German mailing list
E-mail 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
E-mail subscribe mysql-br [email protected] to this list.
[email protected] A Spanish mailing list
E-mail subscribe mysql [email protected] to this list.
34
MySQL Technical Reference for Version 4.1.1-alpha
1.7.1.2 Asking Questions or Reporting Bugs
Before posting a bug report or question, please do the following:
• Start by searching the MySQL online manual at:
http://www.mysql.com/doc/
We try to keep the manual up to date by updating it frequently with
solutions to newly found problems.
The change history appendix
(http://www.mysql.com/doc/en/News.html) can be particularly useful since
it is quite possible that a newer version already contains a solution to your problem.
• Search in the bugs database at http://bugs.mysql.com/ to see whether the bug has
already been reported/solved.
• Search the MySQL mailing list archives:
http://lists.mysql.com/
• You can also use http://www.mysql.com/search/ to search all the web pages (including the manual) that are located at http://www.mysql.com/.
If you can’t find an answer in the manual or the archives, check with your local MySQL
expert. If you still can’t find an answer to your question, please follow the guidelines on
sending mail to a MySQL mailing list, outlined in the next section, before contacting us.
1.7.1.3 How to Report Bugs or Problems
Our bugs database is public, and can be browsed and searched by anyone at
http://bugs.mysql.com/. If you log into the system, you will also be able to enter new
reports.
Writing a good bug report takes patience, but doing it right the first time saves time both
for us and for yourself. A good bug report, containing a full test case for the bug, makes
it very likely that we will fix the bug in the next release. This section will help you write
your report correctly so that you don’t waste your time doing things that may not help us
much or at all.
We encourage everyone to use the mysqlbug script to generate a bug report (or a report
about any problem). mysqlbug can be found in the ‘scripts’ directory (source distribution)
and in the ‘bin’ directory under your MySQL installation directory (binary distribution).
If you are unable to use mysqlbug (for instance, if you are running on Windows), it is still
vital that you include all the necessary information noted in this section (most importantly
a description of the operating system and the MySQL version).
The mysqlbug script helps you generate a report by determining much of the following
information automatically, but if something important is missing, please include it with
your message. Please read this section carefully and make sure that all the information
described here is included in your report.
Preferably, you should test the problem using the latest production or development version
of MySQL Server before posting. Anyone should be able to repeat the bug by just using
’mysql test < script’ on the included test case or run the shell or Perl script that is
included in the bug report.
Chapter 1: General Information
35
All bugs posted in the bugs database at http://bugs.mysql.com/ will be corrected or
documented in the next MySQL release. If only minor code changes are needed to correct
a problem, we will also post a patch that fixes the problem.
The normal place to report bugs is http://bugs.mysql.com/.
If you have found a sensitive security bug in MySQL, please send an e-mail to
[email protected]
If you have a repeatable bug report, please report this into the bugs database at
http://bugs.mysql.com/. Note that even in this case it’s good to run the mysqlbug
script first to find information about your system. Any bug that we are able to repeat has
a high chance of being fixed in the next MySQL release.
To report other problems, you can use one of the MySQL mailing lists.
Remember that it is possible for us to respond to a message containing too much information, but not to one containing too little. People often omit facts because they think they
know the cause of a problem and assume that some details don’t matter. A good principle
is: if you are in doubt about stating something, state it. It is a thousand times faster and
less troublesome to write a couple of lines more in your report than to be forced to ask
again and wait for the answer because you didn’t include enough information the first time.
The most common errors made in bug reports are (a) not including the version number of
the MySQL distribution used and (b) not fully describing the platform on which the MySQL
server is installed (including the platform type and version number). This is highly relevant
information, and in 99 cases out of 100 the bug report is useless without it. Very often we
get questions like, “Why doesn’t this work for me?” Then we find that the feature requested
wasn’t implemented in that MySQL version, or that a bug described in a report has already
been fixed in newer MySQL versions. Sometimes the error is platform-dependent; in such
cases, it is next to impossible for us to fix anything without knowing the operating system
and the version number of the platform.
Remember also to provide information about your compiler, if it is related to the problem.
Often people find bugs in compilers and think the problem is MySQL-related. Most compilers are under development all the time and become better version by version. To determine
whether your problem depends on your compiler, we need to know what compiler you use.
Note that every compiling problem should be regarded as a bug and reported accordingly.
It is most helpful when a good description of the problem is included in the bug report.
That is, give a good example of everything you did that led to the problem and describe,
in exact detail, the problem itself. The best reports are those that include a full example
showing how to reproduce the bug or problem. See Section E.1.6 [Reproduceable test case],
page 1025.
If a program produces an error message, it is very important to include the message in your
report. If we try to search for something from the archives using programs, it is better that
the error message reported exactly matches the one that the program produces. (Even the
case should be observed.) You should never try to remember what the error message was;
instead, copy and paste the entire message into your report.
If you have a problem with MyODBC, please try to generate a MyODBC trace file and
send it with your report. See Section 11.2.7 [MyODBC bug report], page 826.
Please remember that many of the people who will read your report will do so using an
80-column display. When generating reports or examples using the mysql command-line
36
MySQL Technical Reference for Version 4.1.1-alpha
tool, you should therefore use the --vertical option (or the \G statement terminator) for
output that would exceed the available width for such a display (for example, with the
EXPLAIN SELECT statement; see the example later in this section).
Please include the following information in your report:
• The version number of the MySQL distribution you are using (for example, MySQL Version 4.0.12). You can find out which version you are running by executing mysqladmin
version. mysqladmin 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. For most operating systems, you can get this
information by executing the Unix command uname -a. 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.
• Sometimes the amount of memory (real and virtual) is relevant. If in doubt, include
these values.
• If you are using a source distribution of the MySQL software, the name and version
number of the compiler used is needed. If you have a binary distribution, the distribution name is needed.
• If the problem occurs during compilation, include the exact error messages and also a
few lines of context around the offending code in the file where the error occurrs.
• If mysqld died, you should also report the query that crashed mysqld. You can usually
find this out by running mysqld with logging enabled. See Section E.1.5 [Using log
files], page 1024.
• If a database table is related to the problem, include the output from mysqldump -no-data db_name tbl_name1 tbl_name2 .... This is very easy to do and is a powerful
way to get information about any table in a database. The information will help us
create a situation matching the one you have.
• For speed-related bugs or problems with SELECT statements, you should always include
the output of EXPLAIN SELECT ..., and at least the number of rows that the SELECT
statement produces. You should also include the output from SHOW CREATE TABLE tbl_
name for each involved table. The more information you give about your situation, the
more likely it is that someone can help you. The following is an example of a very good
bug report (it should of course be posted with the mysqlbug script).
Example run using the mysql command-line tool (note the use of the \G statement
terminator for statements whose output width would otherwise exceed that of an 80column display device):
mysql> SHOW VARIABLES;
mysql> SHOW COLUMNS FROM ...\G
<output from SHOW COLUMNS>
mysql> EXPLAIN SELECT ...\G
<output from EXPLAIN>
mysql> FLUSH STATUS;
mysql> SELECT ...;
<A short version of the output from SELECT,
Chapter 1: General Information
•
•
•
•
•
•
•
37
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
will reproduce the anomaly. This script should include any necessary source files. The
more closely the script can reproduce your situation, the better. If you can make a
reproducible test case, you should post it on http://bugs.mysql.com/ for high-priority
treatment.
If you can’t provide a script, you should at least include the output from mysqladmin
variables extended-status processlist in your mail to provide some information
on how your system is performing.
If you can’t produce a test case with only a few rows, or if the test table is too big to
be mailed to the mailing list (more than 10 rows), you should dump your tables using
mysqldump and create a ‘README’ file that describes your problem.
Create a compressed archive of your files using tar and gzip or zip, and use ftp to
transfer the archive to ftp://support.mysql.com/pub/mysql/secret/. Then enter
the problem into our bugs database at http://bugs.mysql.com/.
If you think that the MySQL server produces a strange result from a query, include
not only the result, but also your opinion of what the result should be, and an account
describing the basis for your opinion.
When giving an example of the problem, it’s better to use the variable names, table
names, etc., that exist in your actual situation than to come up with new names. The
problem could be related to the name of a variable or table. These cases are rare,
perhaps, but it is better to be safe than sorry. After all, it should be easier for you to
provide an example that uses your actual situation, and it is by all means better for us.
In case you have data you don’t want to show to others, you can use ftp to transfer
it to ftp://support.mysql.com/pub/mysql/secret/. If the data is really top secret
and you don’t want to show it even to us, then go ahead and provide an example using
other names, but please regard this as the last choice.
Include all the options given to the relevant programs, if possible. For example, indicate
the options that you use when you start the mysqld daemon as well as the options that
you use to run any MySQL client programs. The options to programs like mysqld and
mysql, and to the configure script, are often keys to answers and are very relevant.
It is never a bad idea to include them. If you use any modules, such as Perl or PHP,
please include the version numbers of those as well.
If your question is related to the privilege system, please include the output of
mysqlaccess, the output of mysqladmin reload, and all the error messages you
get when trying to connect. When you test your privileges, you should first run
mysqlaccess. After this, execute mysqladmin reload version and try to connect
with the program that gives you trouble. mysqlaccess can be found in the ‘bin’
directory under your MySQL installation directory.
If you have a patch for a bug, do include it. But don’t assume the patch is all we need,
or that we will use it, if you don’t provide some necessary information such as test
cases showing the bug that your patch fixes. We might find problems with your patch
or we might not understand it at all; if so, we can’t use it.
38
MySQL Technical Reference for Version 4.1.1-alpha
If we can’t verify exactly what the patch is meant for, we won’t use it. Test cases will
help us here. Show that the patch will handle all the situations that may occur. If we
find a borderline case (even a rare one) where the patch won’t work, it may be useless.
• Guesses about what the bug is, why it occurs, or what it depends on are usually
wrong. Even the MySQL team can’t guess such things without first using a debugger
to determine the real cause of a bug.
• Indicate in your bug report that you have checked the reference manual and mail archive
so that others know you have tried to solve the problem yourself.
• If you get a parse error, please check your syntax closely. If you can’t find something
wrong with it, it’s extremely likely that your current version of MySQL Server doesn’t
support the syntax you are using. If you are using the current version and the manual at
http://www.mysql.com/doc/ doesn’t cover the syntax you are using, MySQL Server
doesn’t support your query. In this case, your only options are to implement the syntax
yourself or e-mail [email protected] and ask for an offer to implement it.
If the manual covers the syntax you are using, but you have an older version of MySQL
Server, you should check the MySQL change history to see when the syntax was implemented. In this case, you have the option of upgrading to a newer version of MySQL
Server. See Appendix D [News], page 900.
• If your problem is that your data appears corrupt or you get errors when you access a particular table, you should first check and then try repairing your tables with
myisamchk or CHECK TABLE and REPAIR TABLE. See Chapter 4 [MySQL Database Administration], page 198.
• If you often get corrupted tables you should try to find out when and why this happens.
In this case, the ‘mysql-data-directory/’hostname’.err’ file may contain some information about what happened. See Section 4.10.1 [Error log], page 354. 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’s much easier for us to provide you with a fix for the
problem. See Section A.1 [What is crashing], page 857.
• 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.2.4 [Which version], page 76.
If you are a support customer, please cross-post the bug report to [email protected]
for higher-priority treatment, as well as to the appropriate mailing list to see if someone
else has experienced (and perhaps solved) the problem.
For information on reporting bugs in MyODBC, see Section 11.2.4 [ODBC Problems], page 820.
For solutions to some common problems, see Appendix A [Problems], page 857.
When answers are sent to you individually and not to the mailing list, it is considered good
etiquette to summarise 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.
Chapter 1: General Information
39
1.7.1.4 Guidelines for Answering Questions on the Mailing List
If you consider your answer to have broad interest, you may want to post it to the mailing
list instead of replying directly to the individual who asked. Try to make your answer
general enough that people other than the original poster may benefit from it. When you
post to the list, please make sure that your answer is not a duplication of a previous answer.
Try to summarise the essential part of the question in your reply; don’t feel obliged to quote
the entire original message.
Please don’t post mail messages from your browser with HTML mode turned on. Many
users don’t read mail with a browser.
1.7.2 MySQL Community Support on IRC (Internet Relay Chat)
In addition to the various MySQL mailing lists, you can find experienced community people
on IRC (Internet Relay Chat). These are the best networks/channels currently known to
us:
• freenode (see http://www.freenode.net/ for servers)
• #mysql Primarily MySQL questions but other database and SQL questions welcome.
• #mysqlphp Questions about MySQL+PHP, a popular combination.
• #mysqlperl Questions about MySQL+Perl, another popular combination.
• EFnet (see http://www.efnet.org/ for servers)
• #mysql MySQL questions.
If you are looking for IRC client software to connect to an IRC network, take a look at
X-Chat (http://www.xchat.org/). X-Chat (GPL licensed) is available for Unix as well as
for Windows platforms.
1.8 MySQL Standards Compliance
This section describes how MySQL relates to the ANSI/ISO SQL standards. MySQL Server
has many extensions to the SQL standard, and here you will find out what they are and
how to use them. You will also find information about functionality missing from MySQL
Server, and how to work around some differences.
Our goal is to not, without a very good reason, restrict MySQL Server usability for any
usage. Even if we don’t have the resources to do development for every possible use, we are
always willing to help and offer suggestions to people who are trying to use MySQL Server
in new territories.
One of our main goals with the product is to continue to work toward compliance with
the SQL-99 standard, but without sacrificing speed or reliability. We are not afraid to add
extensions to SQL or support for non-SQL features if this greatly increases the usability of
MySQL Server for a big part of our users. (The new HANDLER interface in MySQL Server
4.0 is an example of this strategy. See Section 6.4.9 [HANDLER], page 568.)
40
MySQL Technical Reference for Version 4.1.1-alpha
We will continue to support transactional and non-transactional databases to satisfy both
heavy web/logging usage and mission-critical 24/7 usage.
MySQL Server was designed from the start to work with medium size databases (10-100
million rows, or about 100 MB per table) on small computer systems. We will continue
to extend MySQL Server to work even better with terabyte-size databases, as well as to
make it possible to compile a reduced MySQL version that is more suitable for hand-held
devices and embedded usage. The compact design of the MySQL server makes both of these
directions possible without any conflicts in the source tree.
We are currently not targeting realtime support (even if you can already do a lot of things
with our replication services).
Database cluster support is planned to begin sometime in 2004 through implementation of
a new storage engine.
We are looking at providing XML support in the database server.
1.8.1 What Standards MySQL Follows
Entry-level SQL-92. ODBC levels 0-3.51.
We are aiming toward supporting the full SQL-99 standard, but without concessions to
speed and quality of the code.
1.8.2 Running MySQL in ANSI Mode
If you start mysqld with the --ansi or --sql-mode=ANSI option, the following behaviours
of MySQL Server change:
• || is a string concatenation operator rather than a synonym for OR.
• ‘"’ is treated as an identifier quote character (like the MySQL Server ‘‘’ quote character)
and not as a string quote character. You can still use ‘‘’ to quote identifers in ANSI
mode. An implication of this is that you cannot use double quotes to quote a literal
string, because it will be intepreted as an identifier.
• You can have any number of spaces between a function name and the ‘(’ character.
This forces all function names to be treated as reserved words. As a result, if you want
to access any database, table, or column name that is a reserved word, you must quote
it. For example, because there is a USER() function, the name of the user table in the
mysql database and the User column in that table become reserved, so you must quote
them:
SELECT "User" FROM mysql."user";
• REAL is a synonym for FLOAT instead of a synonym for DOUBLE.
• The default transaction isolation level is SERIALIZABLE. See Section 6.7.6 [SET
TRANSACTION], page 590.
• You can use a field/expression in GROUP BY that is not in the field list.
Running the server in ANSI mode is the same as starting it with these options:
--sql-mode=REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_BY
--transaction-isolation=SERIALIZABLE
In MySQL 4.1, you can achieve the same effect with these two statements:
Chapter 1: General Information
41
SET GLOBAL TRANSACTION ISOLATION LEVEL SERIALIZABLE;
SET GLOBAL sql_mode =
"REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_BY";
In MySQL 4.1.1, the sql_mode options shown can be also be set with:
SET GLOBAL sql_mode="ansi";
In this case, the value of the sql_mode variable will be set to all options that are relevant
for ANSI mode. You can check the result by doing:
mysql> SET GLOBAL sql_mode="ansi";
mysql> SELECT @@GLOBAL.sql_mode;
-> "REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_
1.8.3 MySQL Extensions to the SQL-92 Standard
MySQL Server includes some extensions that you probably will not find in other SQL
databases. Be warned that if you use them, your code will not be portable to other SQL
servers. In some cases, you can write code that includes MySQL extensions, but is still
portable, by using comments of the form /*! ... */. In this case, MySQL Server will
parse and execute the code within the comment as it would any other MySQL statement,
but other SQL servers will ignore the extensions. For example:
SELECT /*! STRAIGHT_JOIN */ col_name FROM table1,table2 WHERE ...
If you add a version number after the ’!’, the syntax will be executed only if the MySQL
version is equal to or newer than the used version number:
CREATE /*!32302 TEMPORARY */ TABLE t (a INT);
This means that if you have Version 3.23.02 or newer, MySQL Server will use the TEMPORARY
keyword.
The following is a list of MySQL extensions:
• The field types MEDIUMINT, SET, ENUM, and the different BLOB and TEXT types.
• The field attributes AUTO_INCREMENT, BINARY, NULL, UNSIGNED, and ZEROFILL.
• All string comparisons are case-insensitive by default, with sort ordering determined
by the current character set (ISO-8859-1 Latin1 by default). If you don’t like this, you
should declare your columns with the BINARY attribute or use the BINARY cast, which
causes comparisons to be done according to the ASCII order used on the MySQL server
host.
• MySQL Server maps each database to a directory under the MySQL data directory,
and tables within a database to filenames in the database directory.
This has a few implications:
− Database names and table names are case sensitive in MySQL Server on operating systems that have case sensitive filenames (like most Unix systems). See
Section 6.1.3 [Name case sensitivity], page 450.
− Database, table, index, column, or alias names may begin with a digit (but may
not consist solely of digits).
− You can use standard system commands to back up, rename, move, delete, and
copy tables. For example, to rename a table, rename the ‘.MYD’, ‘.MYI’, and ‘.frm’
files to which the table corresponds.
42
MySQL Technical Reference for Version 4.1.1-alpha
• 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 as in: create table
ralph.my_table...IN my_tablespace.
• LIKE is allowed on numeric columns.
• Use of INTO OUTFILE and STRAIGHT_JOIN in a SELECT statement. See Section 6.4.1
[SELECT], page 536.
• The SQL_SMALL_RESULT option in a SELECT statement.
• EXPLAIN SELECT to get a description of how tables are joined.
• Use of index names, indexes on a prefix of a field, and use of INDEX or KEY in a CREATE
TABLE statement. See Section 6.5.3 [CREATE TABLE], page 570.
• Use of TEMPORARY or IF NOT EXISTS with CREATE TABLE.
• Use of COUNT(DISTINCT list) where list has more than one element.
• Use of CHANGE col_name, DROP col_name, or DROP INDEX, IGNORE or RENAME in an
ALTER TABLE statement. See Section 6.5.4 [ALTER TABLE], page 579.
• Use of RENAME TABLE. See Section 6.5.5 [RENAME TABLE], page 583.
• Use of multiple ADD, ALTER, DROP, or CHANGE clauses in an ALTER TABLE statement.
• Use of DROP TABLE with the keywords IF EXISTS.
• You can drop multiple tables with a single DROP TABLE statement.
• The ORDER BY and LIMIT clauses of the UPDATE and DELETE statements.
• INSERT INTO ... 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 LOAD DATA INFILE. In many cases, this syntax is compatible with Oracle’s LOAD
DATA INFILE. See Section 6.4.8 [LOAD DATA], page 561.
• The ANALYZE TABLE, CHECK TABLE, OPTIMIZE TABLE, and REPAIR TABLE statements.
• The SHOW statement. See Section 4.6.8 [SHOW], page 287.
• Strings may be enclosed by either ‘"’ or ‘’’, not just by ‘’’.
• Use of the escape ‘\’ character.
• The SET statement. See Section 5.5.6 [SET], page 437.
• You don’t need to name all selected columns in the GROUP BY part. This gives better
performance for some very specific, but quite normal queries. See Section 6.3.7 [Group
by functions and modifiers], page 530.
• One can specify ASC and DESC with GROUP BY.
• To make it easier for users who come from other SQL environments, MySQL Server
supports aliases for many functions. For example, all string functions support both
standard SQL syntax and ODBC syntax.
• MySQL Server understands the || and && operators to mean logical OR and AND, as
in the C programming language. In MySQL Server, || and OR are synonyms, as are
&& and AND. Because of this nice syntax, MySQL Server doesn’t support the standard
SQL-99 || operator for string concatenation; use CONCAT() instead. Because CONCAT()
Chapter 1: General Information
43
takes any number of arguments, it’s easy to convert use of the || operator to MySQL
Server.
• CREATE DATABASE or DROP DATABASE. See Section 6.5.1 [CREATE DATABASE], page 569.
• 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 column
comparisons to the left of the FROM in SELECT statements. For example:
mysql> SELECT col1=1 AND col2=2 FROM tbl_name;
• The LAST_INSERT_ID() function.
page 752.
See Section 11.1.3.32 [mysql_insert_id()],
• 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 any number of arguments.)
• The BIT_COUNT(), CASE, ELT(), FROM_DAYS(), FORMAT(), IF(), PASSWORD(),
ENCRYPT(), MD5(), ENCODE(), DECODE(), PERIOD_ADD(), PERIOD_DIFF(), TO_DAYS(),
or WEEKDAY() functions.
• Use of TRIM() to trim substrings. SQL-99 supports removal of single characters only.
• The GROUP BY functions STD(), BIT_OR(), BIT_AND(), BIT_XOR(), and
GROUP_CONCAT(). See Section 6.3.7 [Group by functions and modifiers], page 530.
• Use of REPLACE instead of DELETE + INSERT. See Section 6.4.7 [REPLACE], page 560.
• The FLUSH, RESET and DO statements.
• The ability to set variables in a statement with :=:
SELECT @a:=SUM(total),@b=COUNT(*),@a/@b AS avg FROM test_table;
SELECT @t1:=(@t2:=1)[email protected]:=4,@t1,@t2,@t3;
1.8.4 MySQL Differences Compared to SQL-92
We try to make MySQL Server follow the ANSI SQL standard (SQL-92/SQL-99) and the
ODBC SQL standard, but in some cases MySQL Server performs operations differently:
• For VARCHAR columns, trailing spaces are removed when the value is stored. See Section 1.8.6 [Bugs], page 51.
• In some cases, CHAR columns are silently changed to VARCHAR columns.
tion 6.5.3.1 [Silent column changes], page 579.
See Sec-
• Privileges for a table are not automatically revoked when you delete a table. You must
explicitly issue a REVOKE to revoke privileges for a table. See Section 4.4.1 [GRANT],
page 242.
For a prioritised list indicating when new extensions will be added to MySQL Server, you
should consult the online MySQL TODO list at http://www.mysql.com/doc/en/TODO.html.
That is the latest version of the TODO list in this manual. See Section 1.6 [TODO],
page 25.
44
MySQL Technical Reference for Version 4.1.1-alpha
1.8.4.1 Subqueries
MySQL Version 4.1 supports subqueries and derived tables (unnamed views). See Section 6.4.2 [Subqueries], page 543.
For MySQL versions prior to 4.1, most subqueries can be successfully rewritten using joins
and and other methods. See Section 6.4.2.11 [Rewriting subqueries], page 551.
1.8.4.2 SELECT INTO TABLE
MySQL Server doesn’t yet support the Sybase SQL extension: SELECT ... INTO TABLE
.... Instead, MySQL Server supports the SQL-99 syntax INSERT INTO ... SELECT ...,
which is basically the same thing. See Section 6.4.3.1 [INSERT SELECT], page 555.
INSERT INTO tblTemp2 (fldID)
SELECT tblTemp1.fldOrder_ID
FROM tblTemp1 WHERE tblTemp1.fldOrder_ID > 100;
Alternatively, you can use SELECT INTO OUTFILE... or CREATE TABLE ... SELECT.
1.8.4.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 7 [Table types], page 600.
The other non-transactional table types (such as MyISAM) in MySQL Server follow a different
paradigm for data integrity called “Atomic Operations.” In transactional terms, MyISAM
tables effectively always operate in AUTOCOMMIT=1 mode. Atomic operations often offer
comparable integrity with higher performance.
With MySQL Server supporting both paradigms, the user is able to decide if he needs the
speed of atomic operations or if he needs to use transactional features in his applications.
This choice can be made on a per-table basis.
As noted, the trade off for transactional vs. non-transactional table types lies mostly in
performance. Transactional tables have significantly higher memory and diskspace requirements, and more CPU overhead. That said, transactional table types such as InnoDB do of
course offer many unique features. MySQL Server’s modular design allows the concurrent
use of all these different storage engines to suit different requirements and deliver optimum
performance in all situations.
But how does one use the features of MySQL Server to maintain rigorous integrity even
with the non-transactional MyISAM tables, and how do these features compare with the
transactional table types?
1. In the transactional paradigm, if your applications are written in a way that is dependent on the calling of ROLLBACK instead of COMMIT in critical situations, transactions
are more convenient. Transactions also ensure that unfinished updates or corrupting
activities are not committed to the database; the server is given the opportunity to do
an automatic rollback and your database is saved.
MySQL Server, in almost all cases, allows you to resolve potential problems by including
simple checks before updates and by running simple scripts that check the databases
Chapter 1: General Information
45
for inconsistencies and automatically repair or warn if such an inconsistency occurs.
Note that just by using the MySQL log or even adding one extra log, one can normally
fix tables perfectly with no data integrity loss.
2. More often than not, critical transactional updates can be rewritten to be atomic.
Generally speaking, all integrity problems that transactions solve can be done with
LOCK TABLES or atomic updates, ensuring that you never will get an automatic abort
from the server, which is a common problem with transactional database systems.
3. Even a transactional system can lose data if the server goes down. The difference
between different systems lies in just how small the time-lap is where they could lose
data. No system is 100% secure, only “secure enough.” Even Oracle, reputed to be
the safest of transactional database systems, is reported to sometimes lose data in such
situations.
To be safe with MySQL Server, whether using transactional tables or not, you only
need to have backups and have the binary logging turned on. With this you can recover
from any situation that you could with any other transactional database system. It
is, of course, always good to have backups, independent of which database system you
use.
The transactional paradigm has its benefits and its drawbacks. Many users and application
developers depend on the ease with which they can code around problems where an abort
appears to be, or is necessary. However, even if you are new to the atomic operations
paradigm, or more familiar with transactions, do consider the speed benefit that 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 transactionlevel reliability and integrity even for non-transactional tables. If you lock tables with LOCK
TABLES, all updates will stall until any integrity checks are made. If you only obtain a
read lock (as opposed to a write lock), reads and inserts are still allowed to happen. The
new inserted records will not be seen by any of the clients that have a read lock until they
release their read locks. With INSERT DELAYED you can queue inserts into a local queue,
until the locks are released, without having the client wait for the insert to complete. See
Section 6.4.3.2 [INSERT DELAYED], page 555.
“Atomic,” in the sense that we mean it, is nothing magical. It only means that you can
be sure that while each specific update is running, no other user can interfere with it, and
there will never be an automatic rollback (which can happen with transactional tables if
you are not very careful). MySQL Server also guarantees that there will not be any dirty
reads.
Following are some techniques for working with non-transactional tables:
• Loops that need transactions normally can be coded with the help of LOCK TABLES, and
you don’t need cursors to update records on the fly.
• To avoid using ROLLBACK, you can use the following strategy:
1. Use LOCK TABLES ... to lock all the tables you want to access.
2. Test conditions.
3. Update if everything is okay.
4. Use UNLOCK TABLES to release your locks.
46
MySQL Technical Reference for Version 4.1.1-alpha
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 this case, all locks will be released but
some of the updates may not have been executed.
• You can also use functions to update records in a single operation. You can get a very
efficient application by using the following techniques:
• Modify fields relative to their current value.
• Update only those fields that actually have changed.
For example, when we are doing updates to some 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 the user can decide which version of the customer record he should
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_he_owes_us=money_he_owes_us-125
WHERE
customer_id=id AND address=’old address’ AND phone=’old phone’;
As you can see, this is very efficient and works even if another client has changed the
values in the pay_back or money_he_owes_us columns.
• In many cases, users have wanted ROLLBACK and/or LOCK TABLES for the purpose of
managing unique identifiers for some tables. This can be handled much more efficiently
by using an AUTO_INCREMENT column and either the SQL function LAST_INSERT_ID()
or the C API function mysql_insert_id(). See Section 11.1.3.32 [mysql_insert_
id()], page 752.
You can generally code around row-level locking. Some situations really need it, and
InnoDB tables support row-level locking. With MyISAM, 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 already 1 in the original row.
You can think of it as though MySQL Server changed the preceding query to:
UPDATE tbl_name SET row_flag=1 WHERE id=ID AND row_flag <> 1;
Chapter 1: General Information
47
1.8.4.4 Stored Procedures and Triggers
Stored procedures are being implemented in our version 5.0 development tree. See Section 2.3.4 [Installing source tree], page 95.
This effort is based on SQL-99, which has a basic syntax similar (but not identical) to
Oracle PL/SQL. In addition to this, we are implementing the SQL-99 framework to hook
in external languages.
A stored procedure is a set of SQL commands that can be compiled and stored in the server.
Once this has been done, clients don’t need to keep re-issuing the entire query but can refer
to the stored procedure. This provides better overall performance because the query has
to be parsed only once, and less information needs to be sent between the server and the
client. You can also raise the conceptual level by having libraries of functions in the server.
However, stored procedures of course do increase the load on the database server system,
as more of the work is done on the server side and less on the client (application) side.
Triggers are scheduled for implementation in MySQL version 5.1. A trigger is effectively a
type of stored procedure, one that is invoked when a particular event occurs. For example,
you could set up a stored procedure that is triggered each time a record is deleted from
a transactional table and that stored procedure automatically deletes the corresponding
customer from a customer table when all their transactions are deleted.
1.8.4.5 Foreign Keys
In MySQL Server 3.23.44 and up, InnoDB tables support checking of foreign key constraints,
including CASCADE, ON DELETE, and ON UPDATE. See Section 7.5.5.2 [InnoDB foreign key
constraints], page 621.
For other table types, MySQL Server currently only parses the FOREIGN KEY syntax in
CREATE TABLE commands, but does not use/store this info. In the near future this implementation will be extended so that the information is stored in the table specification file
and may be retrieved by mysqldump and ODBC. At a later stage, foreign key constraints
will be implemented for MyISAM tables as well.
Note that foreign keys in SQL are not used to join tables, but are used for checking and
enforcing referential integrity (foreign key constraints). If you want to get results from
multiple tables from a SELECT statement, you do this by joining tables:
SELECT * FROM table1,table2 WHERE table1.id = table2.id;
See Section 6.4.1.1 [JOIN], page 541. See Section 3.6.6 [example-Foreign keys], page 189.
When used as a constraint, FOREIGN KEYs don’t need to be used if the application inserts
rows into MyISAM tables in the proper order.
For MyISAM tables, you can work around the lack of ON DELETE by adding the appropriate
DELETE statement to an application when you delete records from a table that has a foreign
key. In practice this is as quick (in some cases quicker) and much more portable than using
foreign keys.
In MySQL Server 4.0 you can use multiple-table delete to delete rows from many tables
with one command. See Section 6.4.5 [DELETE], page 558.
48
MySQL Technical Reference for Version 4.1.1-alpha
The FOREIGN KEY syntax without ON DELETE ... is often used by ODBC applications to
produce automatic WHERE clauses.
Do keep in mind that foreign keys are often misused, which can cause severe problems.
Even when used properly, foreign key support is not a magic solution for the referential
integrity problem, although it can help.
Some advantages of foreign key enforcement:
• Assuming proper design of the relationships, foreign key constraints will make it more
difficult for a programmer to introduce an inconsistency into the database.
• Using cascading updates and deletes can simplify the client code.
• Properly designed foreign key rules aid in documenting relationships between tables.
Disadvantages:
• Mistakes, which are easy to make in designing key relationships, can cause severe
problems—for example, circular rules, or the wrong combination of cascading deletes.
• Additional checking on the database level affects performance, for this reason some
major commercial applications have coded this logic on the application level.
• It is not uncommon for a DBA to make such a complex topology of relationships that
it becomes very difficult, and in some cases impossible, to back up or restore individual
tables.
1.8.4.6 Views
Views are currently being implemented, and will appear in the 5.0 or 5.1 version of MySQL
Server.
Historically, MySQL Server has been most used in applications and on web systems where
the application writer has full control over database usage. Of course, usage has shifted over
time, and so we find that an increasing number of users now regard views as an important
aspect.
Unnamed views (derived tables, a subquery in the FROM clause of a SELECT) are already
implemented in version 4.1.
Views are useful for allowing users to access a set of relations (tables) as if it were a single
table, and limiting their access to just that. Views can also be used to restrict access to rows
(a subset of a particular table). One does not require views to restrict access to columns,
as MySQL Server has a sophisticated privilege system. See Section 4.3 [Privilege system],
page 216.
Many DBMS don’t allow updates to a view, instead you have to perform the updates on
the individual tables. In designing our implementation of views, we aim toward (as fully
as possible within the confines of SQL) compliance with “Codd’s Rule #6” for relational
database systems: all views that are theoretically updatable, should in practice also be
updatable.
Chapter 1: General Information
49
1.8.4.7 ‘--’ as the Start of a Comment
Some other SQL databases use ‘--’ to start comments. MySQL Server has ‘#’ as the start
comment character. You can also use the C comment style /* this is a comment */ with
MySQL Server. See Section 6.1.6 [Comments], page 455.
MySQL Server Version 3.23.3 and above support the ‘--’ comment style, provided the
comment is followed by a space (or by a control character such as a newline). This is
because this comment style has caused many problems with automatically generated SQL
queries that have used something like the following code, where we automatically insert the
value of the payment for !payment!:
UPDATE tbl_name SET credit=credit-!payment!
Think about what happens if the value of payment is negative. Because 1--1 is legal in
SQL, the consequences of allowing comments to start with ‘--’ are terrible.
Using our implementation of this method of commenting in MySQL Server Version 3.23.3
and up, 1-- This is a comment is actually safe.
Another safe feature is that the mysql command-line client removes all lines that start with
‘--’.
The following information is relevant only if you are running a MySQL version earlier than
3.23.3:
If you have an SQL program in a text file that contains ‘--’ comments you should use:
shell> replace " --" " #" < text-file-with-funny-comments.sql \
| mysql database
instead of the usual:
shell> mysql database < text-file-with-funny-comments.sql
You can also edit the command file “in place” to change the ‘--’ comments to ‘#’ comments:
shell> replace " --" " #" -- text-file-with-funny-comments.sql
Change them back with this command:
shell> replace " #" " --" -- text-file-with-funny-comments.sql
1.8.5 How MySQL deals with constraints
As MySQL allows you to work with both transactional and non-transactional tables
(which don’t allow rollback), constraint handling is a bit different in MySQL than in other
databases.
We have to handle the case when you have updated a lot of rows with a non-transactional
table which can’t rollback on errors.
The basic philosophy is to try to give an error for anything that we can detect on compile
time but try to recover from any errors we get run time. We do this in most cases, but not
yet for all. See Section 1.6.4 [TODO future], page 27.
The basic options MySQL has is to stop the statement in the middle or do its best to recover
from the problem and continue.
Here follows what happens with the different types of constraints.
50
MySQL Technical Reference for Version 4.1.1-alpha
1.8.5.1 Constraint PRIMARY KEY / UNIQUE
Normally you will get an error when you try to INSERT / UPDATE a row that causes a
primary key, unique key or foreign key violation. If you are using a transactional storage
engine, like InnoDB, MySQL will automatically roll back the transaction. If you are using
a non-transactional storage engine MySQL will stop at the wrong row and leave the rest of
the rows unprocessed.
To make life easier MySQL has added support for the IGNORE directive to most commands
that can cause a key violation (like INSERT IGNORE ...). In this case MySQL will ignore any
key violation and continue with processing the next row. You can get information of what
MySQL did with the mysql_info() API function and in later MySQL 4.1 version with the
SHOW WARNINGS command. See Section 11.1.3.30 [mysql info], page 751. See Section 4.6.8.9
[SHOW WARNINGS], page 307.
Note that for the moment only InnoDB tables support foreign keys. See Section 7.5.5.2 [InnoDB foreign key constraints], page 621. Foreign key support in MyISAM tables is scheduled
for inclusion in the MySQL 5.0 source tree.
1.8.5.2 Constraint NOT NULL and DEFAULT values
To be able to support easy handling of non-transactional tables all fields in MySQL have
default values.
If you insert a ’wrong’ value in a column like a NULL in a NOT NULL column or a too big
numerical value in a numerical column, MySQL will instead of giving an error instead set
the column to the ’best possible value’. For numerical values this is 0, the smallest possible
values or the largest possible value. For strings this is either the empty string or the longest
possible string that can be in the column.
This means that if you try to store NULL into a column that doesn’t take NULL values,
MySQL Server will store 0 or ’’ (empty string) in it instead. This last behaviour can, for
single row inserts, be changed with the -DDONT_USE_DEFAULT_FIELDS compile option.) See
Section 2.3.3 [configure options], page 93. This causes INSERT statements to generate an
error unless you explicitly specify values for all columns that require a non-NULL value.
The reason for the above rules is that we can’t check these conditions before the query starts
to execute. If we encounter a problem after updating a few rows, we can’t just rollback as
the table type may not support this. The option to stop is not that good as in this case
the update would be ’half done’ which is probably the worst possible scenario. In this case
it’s better to ’do the best you can’ and then continue as if nothing happened. In MySQL
5.0 we plan to improve this by providing warnings for automatic field conversions, plus an
option to let you roll back statements that only use transactional tables in case one such
statement does a field assignment that is not allowed.
The above means that one should generally not use MySQL to check field content, but
instead handle this in the application.
Chapter 1: General Information
51
1.8.5.3 Constraint ENUM and SET
In MySQL 4.x ENUM is not a real constraint but a more efficient way to store fields that
can only contain a given set of values. This is because of the same reasons NOT NULL is not
honoured. See Section 1.8.5.2 [constraint NOT NULL], page 50.
If you insert an wrong value in an ENUM field, it will be set to the reserved enum number 0,
which will be displayed as an empty string in string context. See Section 6.2.3.3 [ENUM],
page 474.
If you insert an wrong option in a SET field, the wrong value will be ignored. See Section 6.2.3.4 [SET], page 475.
1.8.6 Known Errors and Design Deficiencies in MySQL
1.8.6.1 Errors in 3.23 Fixed in a Later MySQL Version
The following known errors/bugs are not fixed in MySQL 3.23 because fixing them would
involves changing a lot of code which could introduce other even worse bugs. The bugs are
also classified as ’not fatal’ or ’bearable’.
• One can get a deadlock when doing LOCK TABLE on multiple tables and then in the
same connection doing a DROP TABLE on one of them while another thread is trying to
lock the table. One can however do a KILL on any of the involved threads to resolve
this. Fixed in 4.0.12.
• SELECT MAX(key_column) FROM t1,t2,t3... where one of the tables are empty
doesn’t return NULL but instead the maximum value for the column. Fixed in 4.0.11.
• DELETE FROM heap_table without a WHERE doesn’t work on a locked HEAP table.
1.8.6.2 Open Bugs / Design Deficiencies in MySQL
The following problems are known and fixing them is a high priority:
• FLUSH TABLES WITH READ LOCK does not block CREATE TABLE or COMMIT, which make
cause a problem with the binary log position when doing a full backup of tables and
the binary log.
• ANALYZE TABLE on a BDB table may in some cases make the table unusable until one
has restarted mysqld. When this happens you will see errors like the following in the
MySQL error file:
001207 22:07:56 bdb: log_flush: LSN past current end-of-log
• MySQL accepts parentheses in the FROM part, but silently ignores them. The reason
for not giving an error is that many clients that automatically generate queries add
parentheses in the FROM part even where they are not needed.
• Concatenating many RIGHT JOINS or combining LEFT and RIGHT join in the same query
may not give a correct answer as MySQL only generates NULL rows for the table preceding a LEFT or before a RIGHT join. This will be fixed in 5.0 at the same time we add
support for parentheses in the FROM part.
52
MySQL Technical Reference for Version 4.1.1-alpha
• Don’t execute ALTER TABLE on a BDB table on which you are running multi-statement
transactions until all those transactions complete. (The transaction will probably be
ignored.)
• ANALYZE TABLE, OPTIMIZE TABLE, and REPAIR TABLE may cause problems on tables for
which you are using INSERT DELAYED.
• Doing a LOCK TABLE ... and FLUSH TABLES ... doesn’t guarantee that there isn’t a
half-finished transaction in progress on the table.
• BDB tables are a bit slow to open. If you have many BDB tables in a database, it will
take a long time to use the mysql client on the database if you are not using the -A
option or if you are using rehash. This is especially notable when you have a big table
cache.
• Replication uses query-level logging: the master writes the executed queries to the
binary log. This is a very fast, compact, and efficient logging method that works
perfectly in most cases. Though we have never heard of it actually occurring, it is
theoretically possible for the data on the master and slave to become different if a
query is designed in such a way that the data modification is non-deterministic, that
is, left to the will of the query optimiser (which generally is not a good practice, even
outside of replication!). For example:
− CREATE ... SELECT or INSERT ... SELECT which feeds zeros or NULLs into an
auto_increment column.
− DELETE if you are deleting rows from a table which has foreign keys with ON DELETE
CASCADE properties.
− REPLACE ... SELECT, INSERT IGNORE ... SELECT if you have duplicate key values
in the inserted data.
IF and only if all these queries have NO ORDER BY clause guaranteeing a deterministic
order.
Indeed, for example for INSERT ... SELECT with no ORDER BY, the SELECT may return
rows in a different order (which will result in a row having different ranks, hence getting
a different number in the auto_increment column), depending on the choices made by
the optimisers on the master and slave. A query will be optimised differently on the
master and slave only if:
− The files used by the two queries are not exactly the same; for example OPTIMIZE
TABLE was run on the master tables and not on the slave tables (to fix this, since
MySQL 4.1.1, OPTIMIZE, ANALYZE and REPAIR are written to the binary log).
− The table is stored in a different storage engine on the master than on the slave
(one can run with different storage engines on the slave and master: for example
InnoDB on the master and MyISAM on the slave, if the slave has less available
disk space).
− The MySQL buffers’ sizes (key_buffer_size etc) are different on the master and
slave.
− The master and slave run different MySQL versions, and the optimiser code is
different between these versions.
This problem may also affect database restoration using mysqlbinlog|mysql.
Chapter 1: General Information
53
The easiest way to avoid this problem in all cases is add an ORDER BY clause to such
non-deterministic queries to ensure that the rows are always stored/modified in the
same order. In future MySQL versions we will automatically add an ORDER BY clause
when needed.
The following problems are known and will be fixed in due time:
• When using RPAD function, or any other string function that ends up adding blanks to
the right, in a query that has to use temporary table to be resolved, then all resulting
strings will be RTRIM’ed. This is an example of the query:
SELECT RPAD(t1.field1, 50, ’ ’) AS f2, RPAD(t2.field2, 50, ’ ’) AS f1
FROM table1 as t1 LEFT JOIN table2 AS t2 ON t1.record=t2.joinID ORDER BY
t2.record;
Final result of this bug is that use will not be able to get blanks on the right side of
the resulting field.
The above behaviour exists in all versions of MySQL.
The reason for this is due to the fact that HEAP tables, which are used first for
temporary tables, are not capable of handling VARCHAR columns.
This behaviour will be fixed in one of the 4.1 series releases.
• Because of how table definitions files are stored one can’t use character 255 (CHAR(255))
in table names, column names or enums. This is scheduled to be fixed in version 5.1
when we have new table definition format files.
• When using SET CHARACTER SET, one can’t use translated characters in database, table,
and column names.
• One can’t use _ or % with ESCAPE in LIKE ... ESCAPE.
• If you have a DECIMAL column with a number stored in different formats (+01.00, 1.00,
01.00), GROUP BY may regard each value as a different value.
• DELETE FROM merge_table used without a WHERE will only clear the mapping for the
table, not delete everything in the mapped tables.
• You cannot build the server in another directory when using MIT-pthreads. Because
this requires changes to MIT-pthreads, we are not likely to fix this. See Section 2.3.6
[MIT-pthreads], page 101.
• BLOB values can’t “reliably” be used in GROUP BY or ORDER BY or DISTINCT. Only
the first max_sort_length bytes (default 1024) are used when comparing BLOBs in
these cases. This can be changed with the -O max_sort_length option to mysqld. A
workaround for most cases is to use a substring: SELECT DISTINCT LEFT(blob,2048)
FROM tbl_name.
• Calculation is done with BIGINT or DOUBLE (both are normally 64 bits long). It depends
on the function which precision one gets. The general rule is that bit functions are done
with BIGINT precision, IF, and ELT() with BIGINT or DOUBLE precision and the rest
with DOUBLE precision. One should try to avoid using unsigned long long values if they
resolve to be bigger than 63 bits (9223372036854775807) for anything else than bit
fields. MySQL Server 4.0 has better BIGINT handling than 3.23.
• All string columns, except BLOB and TEXT columns, automatically have all trailing
spaces removed when retrieved. For CHAR types this is okay, and may be regarded as a
54
•
•
•
•
•
•
•
•
MySQL Technical Reference for Version 4.1.1-alpha
feature according to SQL-92. The bug is that in MySQL Server, VARCHAR columns are
treated the same way.
You can only have up to 255 ENUM and SET columns in one table.
In MIN(), MAX() and other aggregate functions, MySQL currently compares ENUM and
SET columns by their string value rather than by the string’s relative position in the
set.
mysqld_safe redirects all messages from mysqld to the mysqld log. One problem with
this is that if you execute mysqladmin refresh to close and reopen the log, stdout and
stderr are still redirected to the old log. If you use --log extensively, you should edit
mysqld_safe to log to ‘’hostname’.err’ instead of ‘’hostname’.log’ so you can easily
reclaim the space for the old log by deleting the old one and executing mysqladmin
refresh.
In the UPDATE statement, columns are updated from left to right. If you refer to an
updated column, you will get the updated value instead of the original value. For
example:
mysql> UPDATE tbl_name SET KEY=KEY+1,KEY=KEY+1;
This will update KEY with 2 instead of with 1.
You can refer to multiple temporary tables in the same query, but you cannot refer to
any given temporary table more than once. For example, the following doesn’t work:
mysql> SELECT * FROM temporary_table, temporary_table AS t2;
RENAME doesn’t work with TEMPORARY tables or tables used in a MERGE table.
The optimiser may handle DISTINCT differently if you are using ’hidden’ columns in a
join or not. In a join, hidden columns are counted as part of the result (even if they are
not shown) while in normal queries hidden columns don’t participate in the DISTINCT
comparison. We will probably change this in the future to never compare the hidden
columns when executing DISTINCT.
An example of this is:
SELECT DISTINCT mp3id FROM band_downloads
WHERE userid = 9 ORDER BY id DESC;
and
SELECT DISTINCT band_downloads.mp3id
FROM band_downloads,band_mp3
WHERE band_downloads.userid = 9
AND band_mp3.id = band_downloads.mp3id
ORDER BY band_downloads.id DESC;
In the second case you may in MySQL Server 3.23.x get two identical rows in the result
set (because the hidden id column may differ).
Note that this happens only for queries where you don’t have the ORDER BY columns
in the result, something that you are not allowed to do in SQL-92.
Because MySQL Server allows you to work with table types that don’t support transactions, and thus can’t rollback data, some things behave a little differently in MySQL
Server than in other SQL servers. This is just to ensure that MySQL Server never
needs to do a rollback for an SQL command. This may be a little awkward at times
Chapter 1: General Information
•
•
•
•
55
as column values must be checked in the application, but this will actually give you a
nice speed increase as it allows MySQL Server to do some optimisations that otherwise
would be very hard to do.
If you set a column to an incorrect value, MySQL Server will, instead of doing a
rollback, store the best possible value in the column:
− If you try to store a value outside the range in a numerical column, MySQL Server
will instead store the smallest or biggest possible value in the column.
− If you try to store a string that doesn’t start with a number into a numerical
column, MySQL Server will store 0 into it.
− If you try to store NULL into a column that doesn’t take NULL values, MySQL Server
will store 0 or ’’ (empty string) in it instead. (This behaviour can, however, be
changed with the -DDONT USE DEFAULT FIELDS compile option.)
− MySQL allows you to store some wrong date values into DATE and DATETIME
columns (like 2000-02-31 or 2000-02-00). The idea is that it’s not the SQL server
job to validate date. If MySQL can store a date and retrieve exactly the same
date, then MySQL will store the date. If the date is totally wrong (outside the
server’s ability to store it), then the special date value 0000-00-00 will be stored
in the column.
− If you set an ENUM column to an unsupported value, it will be set to the error value
empty string, with numeric value 0.
− If you set a SET column to an unsupported value, the value will be ignored.
If you execute a PROCEDURE on a query that returns an empty set, in some cases the
PROCEDURE will not transform the columns.
Creation of a table of type MERGE doesn’t check if the underlying tables are of compatible
types.
MySQL Server can’t yet handle NaN, -Inf, and Inf values in double. Using these will
cause problems when trying to export and import data. We should as an intermediate
solution change NaN to NULL (if possible) and -Inf and Inf to the minimum respective
maximum possible double value.
If you use ALTER TABLE to first add a UNIQUE index to a table used in a MERGE table
and then use ALTER TABLE to add a normal index on the MERGE table, the key order
will be different for the tables if there was an old key that was not unique in the table.
This is because ALTER TABLE puts UNIQUE keys before normal keys to be able to detect
duplicate keys as early as possible.
The following are known bugs in earlier versions of MySQL:
• You can get a hung thread if you do a DROP TABLE on a table that is one among many
tables that is locked with LOCK TABLES.
• In the following case you can get a core dump:
− Delayed insert handler has pending inserts to a table.
− LOCK table with WRITE.
− FLUSH TABLES.
• Before MySQL Server Version 3.23.2 an UPDATE that updated a key with a WHERE on
the same key may have failed because the key was used to search for records and the
same row may have been found multiple times:
56
MySQL Technical Reference for Version 4.1.1-alpha
UPDATE tbl_name SET KEY=KEY+1 WHERE KEY > 100;
A workaround is to use:
mysql> UPDATE tbl_name SET KEY=KEY+1 WHERE KEY+0 > 100;
This will work because MySQL Server will not use an index on expressions in the WHERE
clause.
• Before MySQL Server Version 3.23, all numeric types were treated as fixed-point fields.
That means you had to specify how many decimals a floating-point field shall have.
All results were returned with the correct number of decimals.
For platform-specific bugs, see the sections about compiling and porting. See Section 2.3
[Installing source], page 89. See Appendix E [Porting], page 1019.
Chapter 2: Installing MySQL
57
2 Installing MySQL
This chapter describes how to obtain and install MySQL:
• For a list of sites from which you can obtain MySQL, see Section 2.2.1 [Getting MySQL],
page 71.
• To see which platforms are supported, see Section 2.2.3 [Which OS], page 74. Please
note that not all supported systems are equally good for running MySQL on them. On
some it is much more robust and efficient than others—see Section 2.2.3 [Which OS],
page 74 for details.
• Several versions of MySQL are available in both binary and source distributions. We
also provide public access to our current source tree for those who want to see our most
recent developments and help us test new code. To determine which version and type
of distribution you should use, see Section 2.2.4 [Which version], page 76. When in
doubt, use a binary distribution.
• Installation instructions for binary and source distributions are described in
Section 2.2.9 [Installing binary], page 86, and Section 2.3 [Installing source], page 89.
Each set of instructions includes a section on system-specific problems you may run
into.
• For post-installation procedures, see Section 2.4 [Post-installation], page 105. These
procedures apply whether you install MySQL using a binary or source distribution.
2.1 Quick Standard MySQL Installation
This chapter covers the installation of MySQL on platforms where we offer packages using
the native packaging format of the respective platform. However, binary distributions of
MySQL are available for many other platforms as well, see Section 2.2.9 [Installing binary],
page 86 for generic installation instructions for these packages that apply to all platforms.
See Section 2.2 [General Installation Issues], page 71 for more information on what other
binary distributions are available and how to obtain them.
2.1.1 Installing MySQL on Windows
The installation process for MySQL on Windows has the following steps:
1. Install the distribution.
2. Set up an option file if necessary.
3. Select the server you want to use.
4. Start the server.
MySQL for Windows is available in two distribution formats:
• The binary distribution contains a setup program that installs everything you need so
that you can start the server immediately.
• The source distribution contains all the code and support files for building the executables using the VC++ 6.0 compiler. See Section 2.3.7 [Windows source build], page 102.
Generally speaking, you should use the binary distribution. It’s simpler, and you need no
additional tools to get MySQL up and running.
58
MySQL Technical Reference for Version 4.1.1-alpha
2.1.1.1 Windows System Requirements
To run MySQL on Windows, you will need the following:
• A 32-bit Windows operating system such as 9x, Me, NT, 2000, or XP. The NT family
(Windows NT, 2000, and XP) permits you to run the MySQL server as a service. See
Section 2.1.1.7 [NT start], page 62.
• TCP/IP protocol support.
• A copy of the MySQL binary distribution for Windows, which can be downloaded from
http://www.mysql.com/downloads/.
Note: The distribution files are supplied with a zipped format and we recommend the
use of an adequate FTP client with resume feature to avoid corruption of files during
the download process.
• A ZIP program to unpack the distribution file.
• Enough space on the hard drive to unpack, install, and create the databases in accordance with your requirements.
• If you plan to connect to the MySQL server via ODBC, you will also need the MyODBC
driver. See Section 11.2 [ODBC], page 817.
• If you need tables with a size larger than 4 GB, install MySQL on an NTFS or newer
filesystem. Don’t forget to use MAX_ROWS and AVG_ROW_LENGTH when you create tables.
See Section 6.5.3 [CREATE TABLE], page 570.
2.1.1.2 Installing a Windows Binary Distribution
To install MySQL on Windows using a binary distribution, follow this procedure:
1. If you are working on a Windows NT, 2000, or XP machine, make sure you have logged
in as a user with administrator privileges.
2. If you are doing an upgrade of an earlier MySQL installation, it is necessary to stop
the current server. On Windows NT, 2000, or XP machines, if you are running the
server as a Windows service, stop it as follows from the command prompt:
C:\> NET STOP MySQL
If you plan to use a different server after the upgrade (for example, if you want to run
mysqld-max rather than mysqld), remove the existing service:
C:\mysql\bin> mysqld --remove
You can reinstall the service to use the proper server after upgrading.
If you are not running the MySQL server as a service, stop it like this:
C:\mysql\bin> mysqladmin -u root shutdown
3. Exit the WinMySQLAdmin program if it is running.
4. Unzip the distribution file to a temporary directory.
5. Run the setup.exe program to begin the installation process. If you want to install
MySQL into a location other than the default directory (‘C:\mysql’), use the Browse
button to specify your preferred directory. If you do not install MySQL into the default
location, you will need to specify the location whenever you start the server. The easiest
Chapter 2: Installing MySQL
59
way to do this is to use an option file, as described in Section 2.1.1.3 [Windows prepare
environment], page 59.
6. Finish the install process.
2.1.1.3 Preparing the Windows MySQL Environment
If you need to specify startup options when you run the server, you can indicate them on the
command line or place them in an option file. For options that will be used every time the
server starts, you will find it most convenient to use an option file to specify your MySQL
configuration. This is true particularly under the following circumstances:
• The installation or data directory locations are different from the default locations
(‘C:\mysql’ and ‘C:\mysql\data’).
• You need to tune the server settings. For example, to use the InnoDB transactional
tables in MySQL version 3.23, you must manually create two new directories to hold
the InnoDB data and log files—such as, ‘C:\ibdata’ and ‘C:\iblogs’. You will also
need to add some extra lines to the option file, as described in Section 7.5.3 [InnoDB
start], page 613. (As of MySQL 4.0, InnoDB creates its datafiles and log files in the
data directory by default. This means you need not configure InnoDB explicitly. You
may still do so if you wish, and an option file will be useful in this case, too.)
On Windows, the MySQL installer places the data directory directly under the directory
where you install MySQL. If you would like to use a data directory in a different location, you should copy the entire contents of the ‘data’ directory to the new location. For
example, by default, the installer places MySQL in ‘C:\mysql’ and the data directory in
‘C:\mysql\data’. If you want to use a data directory of ‘E:\mydata’, you must do two
things:
• Move the data directory from ‘C:\mysql\data’ to ‘E:\mydata’.
• Use a --datadir option to specify the new data directory location each time you start
the server.
When the MySQL server starts on Windows, it looks for options in two files: The ‘my.ini’
file in the Windows directory, and the ‘C:\my.cnf’ file. The Windows directory typically
is named something like ‘C:\WINDOWS’ or ‘C:\WinNT’. You can determine its exact location
from the value of the WINDIR environment variable using the following command:
C:\> echo %WINDIR%
MySQL looks for options first in the ‘my.ini’ file, then in the ‘my.cnf’ file. However, to
avoid confusion, it’s best if you use only one file. If your PC uses a boot loader where the
C: drive isn’t the boot drive, your only option is to use the ‘my.ini’ file. Whichever one
you use, it must be a plain text file.
An option file can be created and modified with any text editor, such as the Notepad
program. For example, if MySQL is installed at ‘D:\mysql’ and the data directory is
located as ‘D:\mydata\data’, you can create the option file and set up a [mysqld] section
to specify values for the basedir and datadir parameters:
[mysqld]
# set basedir to your installation path
basedir=D:/mysql
60
MySQL Technical Reference for Version 4.1.1-alpha
# set datadir to the location of your data directory
datadir=D:/mydata/data
Note that Windows pathnames are specified in option files using forward slashes rather than
backslashes. If you do use backslashes, you must double them.
Another way to manage an option file is to use the the WinMySQLAdmin tool. You can
find WinMySQLAdmin in the ‘bin’ directory of your MySQL installation, as well as a help
file containing instructions for using it. WinMySQLAdmin has the capability of editing your
option file, but note these points:
• WinMySQLAdmin uses only the ‘my.ini’ file.
• If WinMySQLAdmin finds a ‘C:\my.cnf’ file, it will in fact rename it to ‘C:\my_cnf.bak’
to disable it.
Now you are ready to test starting the server.
2.1.1.4 Selecting a Windows Server
Starting with MySQL 3.23.38, the Windows distribution includes both the normal and the
MySQL-Max server binaries. Here is a list of the different MySQL servers from which you
can choose:
Binary
Description
mysqld
Compiled with full debugging and automatic memory allocation checking, symbolic links, and InnoDB and BDB tables.
mysqld-opt
Optimised binary. From version 4.0 on, InnoDB is enabled. Before 4.0,
this server includes no transactional table support.
mysqld-nt
Optimised binary for NT/2000/XP with support for named pipes.
mysqld-max
Optimised binary with support for symbolic links, and InnoDB and BDB
tables.
mysqld-max-nt
Like mysqld-max, but compiled with support for named pipes.
All of the preceding binaries are optimised for modern Intel processors but should work on
any Intel i386-class or higher processor.
The mysqld-nt or mysqld-max-nt server support named pipe connections. If you use either
of these servers, named pipe use is subject to these conditions:
• The server must be run on a version of Windows that supports named pipes (NT, 2000,
XP).
• Starting from 3.23.50, named pipes are enabled only if you start the server with the
--enable-named-pipe option.
• These servers can be run on Windows 98 or Me, but only if TCP/IP is installed; named
pipe connections cannot be used.
• On Windows 95, these servers cannot be used.
2.1.1.5 Starting the Server for the First Time
On Windows 95, 98, or Me, MySQL clients always connect to the server using TCP/IP. On
NT-based systems such as Windows NT, 2000, or XP, clients have two options. They can
use TCP/IP, or they can use a named pipe if the server supports named pipe connections.
Chapter 2: Installing MySQL
61
For information about which server binary to run, see Section 2.1.1.3 [Windows prepare
environment], page 59.
This section gives a general overview of starting the MySQL server. The following sections
provide more specific information for particular versions of Windows.
The examples in these sections assume that MySQL is installed under the default location
of ‘C:\mysql’. Adjust the pathnames shown in the examples if you have MySQL installed
in a different location.
Testing is best done from a command prompt in a console window (a “DOS window”). This
way you can have the server display status messages in the window where they are easy to
see. If something is wrong with your configuration, these messages will make it easier for
you to identify and fix any problems.
Make sure you are in the directory where the server is located, then enter this command:
shell> mysqld --console
For servers that include InnoDB support, you should see the following messages as the server
starts up:
InnoDB: The first specified datafile c:\ibdata\ibdata1 did not exist:
InnoDB: a new database to be created!
InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200
InnoDB: Database physically writes the file full: wait...
InnoDB: Log file c:\iblogs\ib_logfile0 did not exist: new to be created
InnoDB: Setting log file c:\iblogs\ib_logfile0 size to 31457280
InnoDB: Log file c:\iblogs\ib_logfile1 did not exist: new to be created
InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280
InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be created
InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280
InnoDB: Doublewrite buffer not found: creating new
InnoDB: Doublewrite buffer created
InnoDB: creating foreign key constraint system tables
InnoDB: foreign key constraint system tables created
011024 10:58:25 InnoDB: Started
When the server finishes its startup sequence, you should see something like this, which
indicates that the server is ready to service client connections::
mysqld: ready for connections
Version: ’4.0.14-log’ socket: ’’
port: 3306
The server will continue to write to the console any further diagnostic output it produces.
You can open a new console window in which to run client programs.
If you omit the --console option, the server writes diagnostic output to the error log in
the data directory. The error log is the file with the ‘.err’ extension.
2.1.1.6 Starting MySQL on Windows 95, 98, or Me
On Windows 95, 98, or Me, MySQL uses TCP/IP to connect a client to a server. (This will
allow any machine on your network to connect to your MySQL server.) Because of this, you
62
MySQL Technical Reference for Version 4.1.1-alpha
must make sure that TCP/IP support is installed on your machine before starting MySQL.
You can find TCP/IP on your Windows CD-ROM.
Note that if you are using an old Windows 95 release (for example, OSR2), it’s likely that
you have an old Winsock package; MySQL requires Winsock 2! You can get the newest
Winsock from http://www.microsoft.com/. Windows 98 has the new Winsock 2 library,
so it is unnecessary to update the library.
To start the mysqld server, you should start a console window (a “DOS” window) and enter
this command:
shell> C:\mysql\bin\mysqld
This will start mysqld in the background. That is, after the server starts up, you should
see another command prompt. (Note that if you start the server this way on Windows NT,
2000, or XP, the server will run in the foreground and no command prompt will appear
until the server exits. Because of this, you should open another console window to run client
programs while the server is running.
You can stop the MySQL server by executing this command:
shell> C:\mysql\bin\mysqladmin -u root shutdown
This invokes the MySQL administrative utility mysqladmin to connect to the server and
tell it to shut down. The command connects as root, which is the default administrative
account in the MySQL grant system. Please 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 if the server wrote any messages there
to indicate the cause of the problem. The error log is located in the ‘C:\mysql\data’
directory. It is the file with a suffix of ‘.err’. You can also try to start the server as mysqld
--console; in this case, you may get some useful information on the screen that may help
solve the problem.
The last option is to start mysqld with --standalone --debug. In this case mysqld will
write a log file ‘C:\mysqld.trace’ that should contain the reason why mysqld doesn’t start.
See Section E.1.2 [Making trace files], page 1021.
Use mysqld --help to display all the options that mysqld understands!
2.1.1.7 Starting MySQL on Windows NT, 2000, or XP
On the NT family (Windows NT, 2000, or XP), the recommended way to run MySQL
is to install it as a Windows service. Then Windows starts and stops the MySQL server
automatically when Windows starts and stops. A server installed as a service can also be
controlled from the command line using NET commands, or with the graphical Services
utility.
The Services utility (the Windows Service Control Manager) can be found in the Windows Control Panel (under Administrative Tools on Windows 2000). It is advisable to
close the Services utility while performing server installation or removal operations from
this command line. This prevents some odd errors.
To get MySQL to work with TCP/IP on Windows NT 4, you must install service pack 3
(or newer)!
Chapter 2: Installing MySQL
63
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:\mysql\bin\mysqladmin -u root shutdown
This invokes the MySQL administrative utility mysqladmin to connect to the server and
tell it to shut down. The command connects as root, which is the default administrative
account in the MySQL grant system. Please note that users in the MySQL grant system
are wholly independent from any login users under Windows.
Now install the server as a service:
shell> mysqld --install
If you have problems installing mysqld as a service using just the server name, try installing
it using its full pathname:
shell> C:\mysql\bin\mysqld --install
As of MySQL 4.0.2, you can specify a specific service name after the --install option. As
of MySQL 4.0.3, you can in addition specify a --defaults-file option after the service
name to indicate where the server should obtain options when it starts up. The rules that
determine the service name and option files the server uses are as follows:
• If you specify no service name, the server uses the default service name of MySQL and
the server reads options from the [mysqld] group in the standard option files.
• If you specify a service name after the --install option, the server ignores the
[mysqld] option group and instead reads options from the group that has the same
name as the service. The server reads options from the standard option files.
• If you specify a --defaults-file option after the service name, the server ignores the
standard option files and reads options only from the [mysqld] group of the named
file.
Note: Prior to MySQL 4.0.17, a server installed as a Windows service has problems starting
if its pathname or the service name contains spaces. For this reason, avoid installing MySQL
in a directory such as ‘C:\Program Files’ or using a service name containing spaces.
In the usual case that you install the server with --install but no service name, the server
is installed with a service name of MySQL.
As a more complex example, consider the following command:
shell> C:\mysql\bin\mysqld --install mysql --defaults-file=C:\my-opts.cnf
Here, a service name is given after the --install option. If no --defaults-file option
had been given, this command would have the effect of causing the server to read the
[mysql] group from the standard option files. (This would be a bad idea, because that
option group is for use by the mysql client program.) However, because the --defaultsfile option is present, the server reads options only from the named file, and only from
the [mysqld] option group.
You can also specify options as “Start parameters” in the Windows Services utility
before you start the MySQL service.
Once a MySQL server is installed as a service, Windows will start the service automatically
whenever Windows starts. The service also can be started immediately from the Services
utility, or by using the command NET START MYSQL. The NET command is not case sensitive.
64
MySQL Technical Reference for Version 4.1.1-alpha
Please note that when run as a service, mysqld has no access to a console window, so no
messages can be seen there. If mysqld doesn’t start, check the error log to see if the server
wrote any messages there to indicate the cause of the problem. The error log is located in
the ‘C:\mysql\data’ directory. It is the file with a suffix of ‘.err’.
When mysqld is running as a service, it can be stopped by using the Services utility,
the command NET STOP MYSQL, or the command mysqladmin shutdown. If the service is
running when Windows shuts down, Windows will stop the server automatically.
From MySQL version 3.23.44, you have the choice of installing the server as a Manual service
if you don’t wish the service to be started automatically during the boot process. To do
this, use the --install-manual option rather than the --install option:
shell> C:\mysql\bin\mysqld --install-manual
To remove a server that is installed as a service, first stop it if it is running. Then use the
--remove option to remove it:
shell> mysqld --remove
One problem with automatic MySQL service shutdown is that, for MySQL versions older
than 3.23.49, Windows waited only for a few seconds for the shutdown to complete, then
killed the database server process if the time limit was exceeded. This had the potential
to cause problems. (For example, the InnoDB storage engine had to perform crash recovery
at the next startup.) Starting from MySQL version 3.23.49, Windows waits longer for
the MySQL server shutdown to complete. If you notice this still is not enough for your
installation, it is safest not to run the MySQL server as a service. Instead, start it from the
command-line prompt, and stop it with mysqladmin shutdown.
The change to tell Windows to wait longer when stopping the MySQL server
works for Windows 2000 and XP, but not for Windows NT. On NT, Windows
waits only 20 seconds for a service to shut down, and after that kills the service process.
You can increase this default by opening the Registry Editor
‘\winnt\system32\regedt32.exe’ and editing the value of WaitToKillServiceTimeout
at HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control in the Registry tree.
Specify the new larger value in milliseconds (for example, the value 120000 tells Windows
NT to wait up to 120 seconds).
If you don’t want to start mysqld as a service, you can start it from the command line
the same way as for versions of Windows that are not based on NT. For instructions, see
Section 2.1.1.6 [Win95 start], page 61.
2.1.1.8 Running MySQL on Windows
MySQL supports TCP/IP on all Windows platforms. The mysqld-nt and mysql-max-nt
servers support named pipes on NT, 2000, and XP. However, the default is to use TCP/IP
regardless of the platform:
• Named pipes are actually slower than TCP/IP in many Windows configurations.
• Some users have experienced problems shutting down the MySQL server when named
pipes are used.
Starting from 3.23.50, named pipes are enabled for mysqld-nt and mysql-max-nt only if
they are started with the --enable-named-pipe option.
Chapter 2: Installing MySQL
65
You can force a MySQL client to use named pipes by specifying the --pipe option or by
specifying . (period) as the host name. Use the --socket option to specify the name of
the pipe. In MySQL 4.1, you should use the --protocol=PIPE option.
You can test whether the MySQL server is working by executing any of the following
commands:
C:\>
C:\>
C:\>
C:\>
C:\mysql\bin\mysqlshow
C:\mysql\bin\mysqlshow -u root mysql
C:\mysql\bin\mysqladmin version status proc
C:\mysql\bin\mysql test
If mysqld is slow to answer to connections on Windows 9x/Me, there is probably a problem
with your DNS. In this case, start mysqld with the --skip-name-resolve option and use
only localhost and IP numbers in the Host column of the MySQL grant tables.
There are two versions of the MySQL command-line tool:
Binary
mysql
mysqlc
Description
Compiled on native Windows, offering limited text editing capabilities.
Compiled with the Cygnus GNU compiler and libraries, which offers
readline editing.
If you want to use mysqlc, you must have a copy of the ‘cygwinb19.dll’ library installed
somewhere that mysqlc can find it. Current distributions of MySQL include this library in
the same directory as mysqlc (the ‘bin’ directory under the base directory of your MySQL
installation). If your distribution does not have the cygwinb19.dll library in the ‘bin’
directory, look for it in the lib directory and copy it to your Windows system directory
(‘\Windows\system’ or similar place).
The default privileges on Windows give all local users full privileges to all databases without
specifying a password. To make MySQL more secure, you should set a password for all users
and remove the row in the mysql.user table that has Host=’localhost’ and User=’’.
You should also add a password for the root user. The following example starts by removing
the anonymous user that has all privileges, then sets a root user password:
C:\> C:\mysql\bin\mysql mysql
mysql> DELETE FROM user WHERE Host=’localhost’ AND User=’’;
mysql> FLUSH PRIVILEGES;
mysql> QUIT
C:\> C:\mysql\bin\mysqladmin -u root password your_password
After you’ve set the password, if you want to shut down the mysqld server, you can do so
using this command:
C:\> mysqladmin --user=root --password=your_password shutdown
If you are using a server from an old Windows shareware distribution of MySQL Version
3.21, the mysqladmin command to set the password will fail with an error: parse error
near ’SET password’. The solution to this problem is to upgrade to a newer version of
MySQL.
With the current MySQL versions you can easily add new users and change privileges with
GRANT and REVOKE commands. See Section 4.4.1 [GRANT], page 242.
66
MySQL Technical Reference for Version 4.1.1-alpha
2.1.2 Installing MySQL on Linux
The recommended way to install MySQL on Linux is by using the RPM packages. The
MySQL RPMs are currently built on a SuSE Linux 7.3 system but should work on most
versions of Linux that support rpm and use glibc.
If you have problems with an RPM file (for example, if you receive the error “Sorry, the
host ’xxxx’ could not be looked up”), see Section 2.6.2.1 [Binary notes-Linux], page 133.
In most cases, you only need to install the MySQL-server and MySQL-client packages to
get a functional MySQL installation. The other packages are not required for a standard
installation. If you want to run a MySQL Max server that has additional capabilities,
you should install the MySQL-Max RPM after installing the MySQL-server RPM. See Section 4.8.5 [mysqld-max], page 326.
If you get a dependency failure when trying to install the MySQL 4.0 packages (for example,
“error: removing these packages would break dependencies: libmysqlclient.so.10
is needed by ...”), you should also install the package MySQL-shared-compat, which
includes both the shared libraries for backward compatibility (libmysqlclient.so.12 for
MySQL 4.0 and libmysqlclient.so.10 for MySQL 3.23).
Many Linux distributions still ship with MySQL 3.23 and they usually link applications
dynamically to save disk space. If these shared libraries are in a separate package (for
example, MySQL-shared), it is sufficient to simply leave this package installed and just
upgrade the MySQL server and client packages (which are statically linked and do not
depend on the shared libraries). For distributions that include the shared libraries in the
same package as the MySQL server (for example, Red Hat Linux), you could either install
our 3.23 MySQL-shared RPM, or use the MySQL-shared-compat package instead.
The following RPM packages are available:
• MySQL-server-VERSION.i386.rpm
The MySQL server. You will need this unless you only want to connect to a MySQL
server running on another machine. Please note that this package was called MySQLVERSION.i386.rpm before MySQL 4.0.10.
• MySQL-Max-VERSION.i386.rpm
The MySQL Max server. This server has additional capabilities that the one in the
MySQL-server RPM does not. You must install the MySQL-server RPM first, because
the MySQL-Max RPM depends on it.
• MySQL-client-VERSION.i386.rpm
The standard MySQL client programs. You probably always want to install this package.
• MySQL-bench-VERSION.i386.rpm
Tests and benchmarks. Requires Perl and the DBD-mysql module.
• MySQL-devel-VERSION.i386.rpm
The libraries and include files that are needed if you want to compile other MySQL
clients, such as the Perl modules.
• MySQL-shared-VERSION.i386.rpm
This package contains the shared libraries (libmysqlclient.so*) that certain languages and applications need to dynamically load and use MySQL.
Chapter 2: Installing MySQL
67
• MySQL-shared-compat-VERSION.i386.rpm
This package includes the shared libraries for both MySQL 3.23 and MySQL 4.0. Install
this package instead of MySQL-shared, if you have applications installed that are dynamically linked against MySQL 3.23 but you want to upgrade to MySQL 4.0 without
breaking the library dependencies. This package is available since MySQL 4.0.13.
• MySQL-embedded-VERSION.i386.rpm
The embedded MySQL server library (from MySQL 4.0).
• MySQL-VERSION.src.rpm
This contains the source code for all of the previous packages. It can also be used to
rebuild the RPMs on other architectures (for example, Alpha or SPARC).
To see all files in an RPM package (for example, a MySQL-server RPM), run:
shell> rpm -qpl MySQL-server-VERSION.i386.rpm
To perform a standard minimal installation, run:
shell> rpm -i MySQL-server-VERSION.i386.rpm MySQL-client-VERSION.i386.rpm
To install just the client package, run:
shell> rpm -i MySQL-client-VERSION.i386.rpm
RPM provides a feature to verify the integrity and authenticity of packages before installing
them. If you would like to learn more about this feature please see Section 2.2.2 [Verifying
Package Integrity], page 71.
The server RPM places data under the ‘/var/lib/mysql’ directory. The RPM also 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 you don’t lose it when you
install a newer RPM.) See Section 2.4.3 [Automatic start], page 113 for more information
on how MySQL can be started automatically on system startup.
If you want to install the MySQL RPM on older Linux distributions that do not support
initialisation scripts in ‘/etc/init.d’ (directly or via a symlink), you should create a symbolic link that points to the location where your initialisation scripts actually are installed.
For example, if that location is ‘/etc/rc.d/init.d’, use these commands before installing
the RPM to create ‘/etc/init.d’ as a symbolic link that points there:
shell> cd /etc; ln -s rc.d/init.d .
However, all current major Linux distributions should already support the new directory
layout that uses ‘/etc/init.d’, because it is required for LSB (Linux Standard Base)
compliance.
If the RPM files that you install include MySQL-server, the mysqld daemon should be
up and running after installation. You should now be able to start using MySQL. See
Section 2.4 [Post-installation], page 105.
If something goes wrong, you can find more information in the binary installation chapter.
See Section 2.2.9 [Installing binary], page 86.
68
MySQL Technical Reference for Version 4.1.1-alpha
2.1.3 Installing MySQL on Mac OS X
Beginning with MySQL 4.0.11, you can install MySQL on Mac OS X 10.2 (“Jaguar”) using
a Mac OS X PKG binary package instead of the binary tarball distribution. Please note that
older versions of Mac OS X (for example, 10.1.x) are not supported by this package.
The package is located inside a disk image (.dmg) file, that you first need to mount by
double-clicking its icon in the Finder. It should then mount the image and display its
contents.
NOTE: Before proceeding with the installation, be sure to shut down all running MySQL
server instances by either using the MySQL Manager Application (on Mac OS X Server) or
via mysqladmin shutdown on the command line.
To actually install the MySQL PKG, double click on the package icon. This launches the
Mac OS Package Installer, which will guide you through the installation of MySQL.
The Mac OS X PKG of MySQL will install itself into ‘/usr/local/mysql-<version>’
and will also install a symbolic link ‘/usr/local/mysql’, pointing to the new location.
If a directory named ‘/usr/local/mysql’ already exists, it will be renamed to
‘/usr/local/mysql.bak’ first. Additionally, it will install the grant tables in the mysql
database by executing mysql_install_db after the installation.
The installation layout is similar to the one of the 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.2.5 [Installation layouts], page 79.
MySQL installation requires a Mac OS X user account named mysql (a user account with
this name should exist by default on Mac OS X 10.2 and up).
If you are running Mac OS X Server, you already have a version of MySQL installed:
• Mac OS X Server 10.2-10.2.2 come with MySQL 3.23.51 installed
• Mac OS X Server 10.2.3-10.2.6 ship with MySQL 3.23.53
• Mac OS X Server 10.3 ships with MySQL 4.0.14
This manual section covers the installation of the official MySQL Mac OS X PKG only.
Make sure to read Apple’s help about installing MySQL (Run the “Help View” application,
select “Mac OS X Server” help, and do a search for “MySQL” and read the item entitled
“Installing MySQL”).
Especially note that the pre-installed version of MySQL on Mac OS X Server is started
with the command safe_mysqld instead of mysqld_safe.
If you previously used Marc Liyanage’s MySQL packages for Mac OS X from
http://www.entropy.ch, you can simply follow the update instructions for packages using
the binary installation layout as given on his pages.
If you are upgrading from Marc’s 3.23.xx versions or from the Mac OS X Server version of
MySQL to the official MySQL PKG, you also need to convert the existing MySQL privilege
tables to the current format, because some new security privileges have been added. See
Section 2.5.6 [Upgrading-grant-tables], page 123.
If you would like to automatically start up MySQL during system bootup, you also need
to install the MySQL Startup Item. Starting with MySQL 4.0.15, it is part of the Mac
Chapter 2: Installing MySQL
69
OS X installation disk images as a separate installation package. Simply double-click the
MySQLStartupItem.pkg icon and follow the instructions to install it.
Note that this only has to be done once! There is no need to install the Startup Item every
time you upgrade the MySQL package.
Due to a bug in the Mac OS X package installer, you may sometimes see the error message
You cannot install this software on this disk. (null) in the destination disk selection dialogue. If this error occurs, simply click the Go Back button once to return to the
previous screen. Now click Continue to advance to the destination disk selection again you should now be able to choose the destination disk correctly. We have reported this bug
to Apple and they are investigating this problem.
The Startup Item will be installed into ‘/Library/StartupItems/MySQL’. It adds a variable
MYSQLCOM=-YES- to the system configuration file ‘/etc/hostconfig’. If you would like to
disable the automatic startup of MySQL, simply change this variable to MYSQLCOM=-NO-.
On Mac OS X Server, the Startup Item installation script will automatically disable
the startup of the default MySQL installation by changing the variable MYSQL in
‘/etc/hostconfig’ to MYSQL=-NO-. This is to avoid conflicts on bootup. However, it does
not shut down an already running MySQL server.
After the installation, you can start up MySQL by running the following commands in a
terminal window. Please note that you need to have administrator privileges to perform
this task.
If you have installed the Startup Item:
shell> sudo /Library/StartupItems/MySQL/MySQL start
(Enter your password, if necessary)
(Press Control-D or enter "exit" to exit the shell)
If you don’t 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 now be able to connect to the MySQL server, for example, by running
‘/usr/local/mysql/bin/mysql’.
If you installed MySQL for the first time, please remember to set a password for the MySQL
root user!
This is done with the following two commands:
/usr/local/mysql/bin/mysqladmin -u root password <password>
/usr/local/mysql/bin/mysqladmin -u root -h ‘hostname‘ password <password>
Please make sure that the hostname command in the second line is enclosed by backticks
(‘), so the shell can replace it with the output of this command (the host name of this
system)!
You might want to also add aliases to your shell’s resource file to access mysql and
mysqladmin from the command line:
70
MySQL Technical Reference for Version 4.1.1-alpha
alias mysql ’/usr/local/mysql/bin/mysql’
alias mysqladmin ’/usr/local/mysql/bin/mysqladmin’
Alternatively, you could simply add /usr/local/mysql/bin to your PATH environment
variable, for example, by adding the following to ‘$HOME/.tcshrc’:
setenv PATH ${PATH}:/usr/local/mysql/bin
Please note that installing a new MySQL PKG does not remove the directory of an older
installation. Unfortunately, the Mac OS X Installer does not yet offer the functionality
required to properly upgrade previously installed packages.
After you have copied over the MySQL database files from the previous version and have
successfully started the new version, 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.1.4 Installing MySQL on NetWare
As of version 4.0.11, the MySQL server is available for Novell NetWare in binary package
form. In order to host MySQL, the NetWare server must meet these requirements:
• NetWare version 6.5, or NetWare 6.0 with Support Pack 3 installed (You can obtain
this at http://support.novell.com/filefinder/13659/index.html). The system
must meet Novell’s minimum requirements to run the respective version of NetWare.
• MySQL data, as well as the binaries themselves, must be installed on an NSS volume;
traditional volumes are not supported.
The binary package for NetWare can be obtained at http://www.mysql.com/downloads/.
If you are running MySQL on NetWare 6.0, we strongly suggest that you use the --skipexternal-locking option on the command line. It will also be neccesary 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.
2.1.4.1 Installing the MySQL for NetWare Binaries
1. If you are upgrading from a prior installation, stop the MySQL server. This is done
from the server console, using:
SERVER: mysqladmin -u root shutdown
2. Log on to the target server from a client machine with access to the location where you
will install 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’) now, as well as ‘my.cnf’ if you have customised it.
You can then delete the old copy of MySQL.
4. You may wish to rename the directory to something more consistent and easy to use.
We recommend using ‘SYS:MYSQL’; examples in the manual will use this to refer to the
installation directory in general.
Chapter 2: Installing MySQL
71
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. Install the initial database, if needed, 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 4.0.x database server
SEARCH ADD SYS:MYSQL\BIN
MYSQLD_SAFE
If you are using NetWare 6.0, you should add the --skip-external-locking flag:
#Starts the MySQL 4.0.x database server
SEARCH ADD SYS:MYSQL\BIN
MYSQLD_SAFE --skip-external-locking
If there was an existing installation of MySQL on the server, be sure to check for existing
MySQL startup commands in autoexec.ncf, and edit or delete them as necessary.
2.2 General Installation Issues
2.2.1 How to Get MySQL
Check the MySQL homepage (http://www.mysql.com/) for information about the current
version and for downloading instructions.
Our main mirror is located at http://mirrors.sunsite.dk/mysql/.
For a complete up-to-date list of MySQL web/download mirrors, see http://www.mysql.com/downloads/mi
There you will also find information about becoming a MySQL mirror site and how to
report a bad or out-of-date mirror.
2.2.2 Verifying Package Integrity Using MD5 Checksums or GnuPG
After you have downloaded the MySQL package that suits your needs and before you
attempt to install it, you should make sure it is intact and has not been tampered with.
MySQL AB offers two means of integrity checking: MD5 checksums and cryptographic signatures using GnuPG, the GNU Privacy Guard.
Verifying the MD5 Checksum
After you have downloaded the package, you should check, if the MD5 checksum matches
the one provided on the MySQL download pages. Each package has an individual checksum,
that you can verify with the following command:
72
MySQL Technical Reference for Version 4.1.1-alpha
shell> md5sum <package>
Note, that not all operating systems support the md5sum command - on some it is simply
called md5, others do not ship it at all. On Linux, it is part of the GNU Text Utilities
package, which is available for a wide range of platforms. You can download the source
code from http://www.gnu.org/software/textutils/ as well. If you have OpenSSL installed, you can also use the command openssl md5 <package> instead. A DOS/Windows
implementation of the md5 command is available from http://www.fourmilab.ch/md5/.
Example:
shell> md5sum mysql-standard-4.0.10-gamma-pc-linux-i686.tar.gz
155836a7ed8c93aee6728a827a6aa153
mysql-standard-4.0.10-gamma-pc-linux-i686.tar.gz
You should check, if the resulting checksum matches the one printed on the download page
right below the respective package.
Signature Checking Using GnuPG
A more reliable method of verifying the integrity of a package is using cryptographic
signatures. MySQL AB uses the GNU Privacy Guard (GnuPG), an Open Source alternative
to the very well-known Pretty Good Privacy (PGP) by Phil Zimmermann.
See
http://www.gnupg.org/ and http://www.openpgp.org/ for more information about
OpenPGP/GnuPG and how to obtain and install GnuPG on your system. Most Linux
distributions already ship with GnuPG installed by default.
Beginning with MySQL 4.0.10 (February 2003), MySQL AB has started signing their downloadable packages with GnuPG. Cryptographic signatures are a much more reliable method
of verifying the integrity and authenticity of a file.
To verify the signature for a specific package, you first need to obtain a copy of MySQL
AB’s public GPG build key [email protected] You can either cut and paste it directly
from here, or obtain it from http://www.keyserver.net/.
Key ID:
pub 1024D/5072E1F5 2003-02-03
MySQL Package signing key (www.mysql.com) <[email protected]>
Fingerprint: A4A9 4068 76FC BD3C 4567 70C8 8C71 8D3B 5072 E1F5
Public Key (ASCII-armored):
-----BEGIN PGP PUBLIC KEY BLOCK----Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org
mQGiBD4+owwRBAC14GIfUfCyEDSIePvEW3SAFUdJBtoQHH/nJKZyQT7h9bPlUWC3
RODjQReyCITRrdwyrKUGku2FmeVGwn2u2WmDMNABLnpprWPkBdCk96+OmSLN9brZ
fw2vOUgCmYv2hW0hyDHuvYlQA/BThQoADgj8AW6/0Lo7V1W9/8VuHP0gQwCgvzV3
BqOxRznNCRCRxAuAuVztHRcEAJooQK1+iSiunZMYD1WufeXfshc57S/+yeJkegNW
hxwR9pRWVArNYJdDRT+rf2RUe3vpquKNQU/hnEIUHJRQqYHo8gTxvxXNQc7fJYLV
K2HtkrPbP72vwsEKMYhhr0eKCbtLGfls9krjJ6sBgACyP/Vb7hiPwxh6rDZ7ITnE
Chapter 2: Installing MySQL
73
kYpXBACmWpP8NJTkamEnPCia2ZoOHODANwpUkP43I7jsDmgtobZX9qnrAXw+uNDI
QJEXM6FSbi0LLtZciNlYsafwAPEOMDKpMqAK6IyisNtPvaLd8lH0bPAnWqcyefep
rv0sxxqUEMcM3o7wwgfN83POkDasDbs3pjwPhxvhz6//62zQJ7Q7TXlTUUwgUGFj
a2FnZSBzaWduaW5nIGtleSAod3d3Lm15c3FsLmNvbSkgPGJ1aWxkQG15c3FsLmNv
bT6IXQQTEQIAHQUCPj6jDAUJCWYBgAULBwoDBAMVAwIDFgIBAheAAAoJEIxxjTtQ
cuH1cY4AnilUwTXn8MatQOiG0a/bPxrvK/gCAJ4oinSNZRYTnblChwFaazt7PF3q
zIhMBBMRAgAMBQI+PqPRBYMJZgC7AAoJEElQ4SqycpHyJOEAn1mxHijft00bKXvu
cSo/pECUmppiAJ41M9MRVj5VcdH/KN/KjRtW6tHFPYhMBBMRAgAMBQI+QoIDBYMJ
YiKJAAoJELb1zU3GuiQ/lpEAoIhpp6BozKI8p6eaabzF5MlJH58pAKCu/ROofK8J
Eg2aLos+5zEYrB/LsrkCDQQ+PqMdEAgA7+GJfxbMdY4wslPnjH9rF4N2qfWsEN/l
xaZoJYc3a6M02WCnHl6ahT2/tBK2w1QI4YFteR47gCvtgb6O1JHffOo2HfLmRDRi
Rjd1DTCHqeyX7CHhcghj/dNRlW2Z0l5QFEcmV9U0Vhp3aFfWC4Ujfs3LU+hkAWzE
7zaD5cH9J7yv/6xuZVw411x0h4UqsTcWMu0iM1BzELqX1DY7LwoPEb/O9Rkbf4fm
Le11EzIaCa4PqARXQZc4dhSinMt6K3X4BrRsKTfozBu74F47D8Ilbf5vSYHbuE5p
/1oIDznkg/p8kW+3FxuWrycciqFTcNz215yyX39LXFnlLzKUb/F5GwADBQf+Lwqq
a8CGrRfsOAJxim63CHfty5mUc5rUSnTslGYEIOCR1BeQauyPZbPDsDD9MZ1ZaSaf
anFvwFG6Llx9xkU7tzq+vKLoWkm4u5xf3vn55VjnSd1aQ9eQnUcXiL4cnBGoTbOW
I39EcyzgslzBdC++MPjcQTcA7p6JUVsP6oAB3FQWg54tuUo0Ec8bsM8b3Ev42Lmu
QT5NdKHGwHsXTPtl0klk4bQk4OajHsiy1BMahpT27jWjJlMiJc+IWJ0mghkKHt92
6s/ymfdf5HkdQ1cyvsz5tryVI3Fx78XeSYfQvuuwqp2H139pXGEkg0n6KdUOetdZ
Whe70YGNPw1yjWJT1IhMBBgRAgAMBQI+PqMdBQkJZgGAAAoJEIxxjTtQcuH17p4A
n3r1QpVC9yhnW2cSAjq+kr72GX0eAJ4295kl6NxYEuFApmr1+0uUq/SlsQ==
=YJkx
-----END PGP PUBLIC KEY BLOCK----You can import this key into your public GPG keyring by using gpg --import. See the GPG
documentation for more info on how to work with public keys.
After you have downloaded and imported the public build key, now download your
desired MySQL package and the corresponding signature, which is also available from
the download page. The signature has the file name extension ‘.asc’. For example,
the signature for ‘mysql-standard-4.0.10-gamma-pc-linux-i686.tar.gz’ would be
‘mysql-standard-4.0.10-gamma-pc-linux-i686.tar.gz.asc’. Make sure that both
files are stored in the same directory and then run the following command to verify the
signature for this file:
shell> gpg --verify <package>.asc
Example:
shell> gpg --verify
gpg: Warning: using
gpg: Signature made
gpg: Good signature
"MySQL Package
mysql-standard-4.0.10-gamma-pc-linux-i686.tar.gz.asc
insecure memory!
Mon 03 Feb 2003 08:50:39 PM MET using DSA key ID 5072E1F5
from
signing key (www.mysql.com) <[email protected]>"
The "Good signature" message indicates that everything is all right.
74
MySQL Technical Reference for Version 4.1.1-alpha
Signature Checking Using RPM
For RPM packages, there is no separate signature - RPM packages actually have a built-in GPG
signature and MD5 checksum. You can verify them by running the following command:
shell> rpm --checksig <package>.rpm
Example:
shell> rpm --checksig MySQL-server-4.0.10-0.i386.rpm
MySQL-server-4.0.10-0.i386.rpm: md5 gpg OK
Note: If you are using RPM 4.1 and it complains about (GPG) NOT OK (MISSING KEYS:
GPG#5072e1f5) (even though you have imported it into your GPG public keyring), you
need to import the key into the RPM keyring first. RPM 4.1 no longer uses your GPG
keyring (and GPG itself), but rather maintains its own keyring (because it’s a system wide
application and the GPG public keyring is user-specific file). To import the MySQL public
key into the RPM keyring, please use the following command:
shell> rpm --import <pubkey>
Example:
shell> rpm --import mysql_pubkey.asc
In case you notice that the MD5 checksum or GPG signatures do not match, first try to
download the respective package one more time, maybe from another mirror site. If you
repeatedly cannot successfully verify the integrity of the package, please notify us about
such incidents including the full package name and the download site you have been using
at [email protected] or [email protected]
2.2.3 Operating Systems Supported by MySQL
We use GNU Autoconf, so it is possible to port MySQL to all modern systems with working
Posix threads and a C++ compiler. (To compile only the client code, a C++ compiler is
required but not threads.) We use and develop the software ourselves primarily on Linux
(SuSE and Red Hat), FreeBSD and Sun Solaris (Versions 8 and 9).
Note that for many operating systems, the native thread support works only in the latest
versions. MySQL has been reported to compile successfully on the following operating
system/thread package combinations:
• AIX 4.x, 5.x with native threads. See Section 2.6.6.4 [IBM-AIX], page 147.
• Amiga.
• BSDI 2.x with the MIT-pthreads package. See Section 2.6.4.5 [BSDI], page 143.
• BSDI 3.0, 3.1 and 4.x with native threads. See Section 2.6.4.5 [BSDI], page 143.
• SCO OpenServer with a recent port of the FSU Pthreads package. See Section 2.6.6.9
[SCO], page 152.
• SCO UnixWare 7.1.x. See Section 2.6.6.10 [SCO UnixWare], page 154.
• DEC Unix 4.x with native threads. See Section 2.6.6.6 [Alpha-DEC-UNIX], page 149.
Chapter 2: Installing MySQL
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
75
FreeBSD 2.x with the MIT-pthreads package. See Section 2.6.4.1 [FreeBSD], page 141.
FreeBSD 3.x and 4.x with native threads. See Section 2.6.4.1 [FreeBSD], page 141.
FreeBSD 4.x with Linuxthreads. See Section 2.6.4.1 [FreeBSD], page 141.
HP-UX 10.20 with the DCE threads or the MIT-pthreads package. See Section 2.6.6.2
[HP-UX 10.20], page 145.
HP-UX 11.x with the native threads. See Section 2.6.6.3 [HP-UX 11.x], page 146.
Linux 2.0+ with LinuxThreads 0.7.1+ or glibc 2.0.7+. See Section 2.6.2 [Linux],
page 129.
Mac OS X. See Section 2.6.5 [Mac OS X], page 144.
NetBSD 1.3/1.4 Intel and NetBSD 1.3 Alpha (Requires GNU make). See Section 2.6.4.2
[NetBSD], page 142.
Novell NetWare 6.0. See Section 2.6.8 [Novell NetWare], page 155.
OpenBSD > 2.5 with native threads. OpenBSD < 2.5 with the MIT-pthreads package.
See Section 2.6.4.3 [OpenBSD], page 142.
OS/2 Warp 3, FixPack 29 and OS/2 Warp 4, FixPack 4. See Section 2.6.7 [OS/2],
page 155.
SGI Irix 6.x with native threads. See Section 2.6.6.8 [SGI-Irix], page 151.
Solaris 2.5 and above with native threads on SPARC and x86. See Section 2.6.3 [Solaris], page 137.
SunOS 4.x with the MIT-pthreads package. See Section 2.6.3 [Solaris], page 137.
Tru64 Unix
Windows 9x, Me, NT, 2000 and XP. See Section 2.6.1 [Windows], page 126.
Note that not all platforms are suited equally well for running MySQL. How well a certain platform is suited for a high-load mission-critical MySQL server is determined by the
following factors:
• General stability of the thread library. A platform may have excellent reputation
otherwise, but if the thread library is unstable in the code that is called by MySQL,
even if everything else is perfect, MySQL will be only as stable as the thread library.
• The ability of the kernel and/or thread library to take advantage of SMP on multiprocessor systems. In other words, when a process creates a thread, it should be
possible for that thread to run on a different CPU than the original process.
• The ability of the kernel and/or the thread library to run many threads which acquire/release a mutex over a short critical region frequently without excessive context
switches. In other words, if the implementation of pthread_mutex_lock() is too anxious to yield CPU time, this will hurt MySQL tremendously. If this issue is not taken
care of, adding extra CPUs will actually make MySQL slower.
• General filesystem stability/performance.
• Ability of the filesystem to deal with large files at all and deal with them efficiently, if
your tables are big.
• Our level of expertise here at MySQL AB with the platform. If we know a platform
well, we introduce platform-specific optimisations/fixes enabled at compile time. We
can also provide advice on configuring your system optimally for MySQL.
76
MySQL Technical Reference for Version 4.1.1-alpha
• The amount of testing of similar configurations we have done internally.
• The number of users that have successfully run MySQL on that platform in similar
configurations. If this number is high, the chances of hitting some platform-specific
surprises are much smaller.
Based on the preceding criteria, the best platforms for running MySQL at this point are
x86 with SuSE Linux 8.2, 2.4 kernel, and ReiserFS (or any similar Linux distribution) and
SPARC with Solaris (2.7-9). FreeBSD comes third, but we really hope it will join the top
club once the thread library is improved. We also hope that at some point we will be
able to include all other platforms on which MySQL compiles, runs okay, but not quite
with the same level of stability and performance, into the top category. This will require
some effort on our part in cooperation with the developers of the OS/library components
MySQL depends upon. If you are interested in making one of those components better,
are in a position to influence their development, and need more detailed instructions on
what MySQL needs to run better, send an e-mail to the MySQL internals mailing list. See
Section 1.7.1.1 [Mailing-list], page 31.
Please note that the preceding comparison is not to say that one OS is better or worse
than the other in general. We are talking about choosing a particular OS for a dedicated
purpose—running MySQL, and compare platforms in that regard only. With this in mind,
the result of this comparison would be different if we included more issues into it. And in
some cases, the reason one OS is better than the other could simply be that we have put
forth more effort into testing on and optimising for that particular platform. We are just
stating our observations to help you decide on which platform to use MySQL on in your
setup.
2.2.4 Which MySQL Version to Use
The first decision to make is whether you want to use the latest development release or the
last production (stable) release:
• Normally, if you are beginning to use MySQL for the first time or trying to port it to
some system for which there is no binary distribution, we recommend going with the
production release (currently version 4.0). Note that all MySQL releases are checked
with the MySQL benchmarks and an extensive test suite before each release (even the
development releases).
• Otherwise, if you are running an old system and want to upgrade, but don’t want to
take chances with a non-seamless upgrade, you should upgrade to the latest in the same
branch you are using (where only the last version number is newer than yours). We
have tried to fix only fatal bugs and make small, relatively safe changes to that version.
The second decision to make is whether you want to use a source distribution or a binary
distribution. In most cases you should probably use a binary distribution, if one exists for
your platform, as this generally will be easier to install than a source distribution.
In the following cases you probably will be better off with a source installation:
• If you want to install MySQL at some explicit location. (The standard binary distributions are “ready to run” at any place, but you may want to get even more flexibility).
Chapter 2: Installing MySQL
77
• To be able to satisfy different user requirements, we are providing two different binary
versions: one compiled with the non-transactional storage engines (a small, fast binary),
and one configured with the most important extended options like transaction-safe
tables. Both versions are compiled from the same source distribution. All native MySQL
clients can connect to both MySQL versions.
The extended MySQL binary distribution is marked with the -max suffix and is configured with the same options as mysqld-max. See Section 4.8.5 [mysqld-max], page 326.
If you want to use the MySQL-Max RPM, you must first install the standard MySQLserver RPM.
• If you want to configure mysqld with some extra features that are not in the standard
binary distributions. Here is a list of the most common extra options that you may
want to use:
• --with-innodb (default for MySQL 4.0 and onwards)
• --with-berkeley-db (not available on all platforms)
• --with-raid
• --with-libwrap
• --with-named-z-libs (This is done for some of the binaries)
• --with-debug[=full]
• The default binary distribution is normally compiled with support for all character sets
and should work on a variety of processors from the same processor family.
If you want a faster MySQL server you may want to recompile it with support for only
the character sets you need, use a better compiler (like pgcc), or use compiler options
that are better optimised for your processor.
• If you have found a bug and reported it to the MySQL development team you will
probably receive a patch that you need to apply to the source distribution to get the
bug fixed.
• If you want to read (and/or modify) the C and C++ code that makes up MySQL,
you should get a source distribution. The source code is always the ultimate manual.
Source distributions also contain more tests and examples than binary distributions.
The MySQL naming scheme uses release numbers that consist of three numbers and a suffix.
For example, a release name like mysql-4.1.0-alpha is interpreted like this:
• The first number (4) is the major version and also describes the file format. All Version
4 releases have the same file format.
• The second number (1) is the release level.
• The third number (0) is the version number within the release level. This is incremented
for each new distribution. Usually you want the latest version for the release level you
have chosen.
• The suffix (alpha) indicates the stability level of the release. The possible suffixes are:
− alpha indicates that the release contains some large section of new code that hasn’t
been 100% tested. Known bugs (usually there are none) should be documented
in the News section. See Appendix D [News], page 900. There are also new
commands and extensions in most alpha releases. Active development that may
78
MySQL Technical Reference for Version 4.1.1-alpha
involve major code changes can occur on an alpha release, but everything will be
tested before doing a release. There should be no known bugs in any MySQL
release.
− beta means that all new code has been tested. No major new features that could
cause corruption on old code are added. There should be no known bugs. A
version changes from alpha to beta when there haven’t been any reported fatal
bugs within an alpha version for at least a month and we don’t plan to add any
features that could make any old command more unreliable.
− gamma is a beta that has been around a while and seems to work fine. Only minor
fixes are added. This is what many other companies call a release.
− If there is no suffix, it means that the version has been run for a while at many
different sites with no reports of bugs other than platform-specific bugs. Only
critical bug fixes are applied to the release. This is what we call a production
(stable) release.
In the MySQL development process, multiple versions co-exist and are at a different stage.
Naturally, relevant bugfixes from an earlier series also propagate upward.
• For the old stable/production series 3.23, new versions are only released for critical
bugs.
• The current series 4.0) is stable/production quality, with new versions released for
bugfixes. No new features are added that could influence the code stability.
• In the alpha branch 4.1 major new features are added. Sources and binaries are
available for use and testing on development systems.
• The development branch 5.0 is only available from the BitKeeper tree.
All versions 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.
Note that all releases have been tested at least with:
An internal test suite
This is part of a production system for a customer. It has many tables with
hundreds of megabytes of data.
The MySQL benchmark suite
This runs a range of common queries. It is also a test to see whether the latest
batch of optimisations actually made the code faster. See Section 5.1.4 [MySQL
Benchmarks], page 401.
The crash-me test
This tries to determine what features the database supports and what its capabilities and limitations are. See Section 5.1.4 [MySQL Benchmarks], page 401.
Another test is that we use the newest MySQL version in our internal production environment, on at least one machine. We have more than 100 gigabytes of data to work with.
Chapter 2: Installing MySQL
79
2.2.5 Installation Layouts
This section describes the default layout of the directories created by installing binary and
source distributions.
A binary distribution is installed by unpacking it at the installation location you choose
(typically ‘/usr/local/mysql’) and creates the following directories in that location:
Directory
‘bin’
‘data’
‘docs’
‘include’
‘lib’
‘scripts’
‘share/mysql’
‘sql-bench’
Contents of directory
Client programs and the mysqld server
Log files, databases
Documentation, ChangeLog
Include (header) files
Libraries
mysql_install_db
Error message files
Benchmarks
A source distribution is installed after you configure and compile it. By default, the installation step installs files under ‘/usr/local’, in the following subdirectories:
Directory
Contents of directory
‘bin’
Client programs and scripts
‘include/mysql’Include (header) files
‘info’
Documentation in Info format
‘lib/mysql’
Libraries
‘libexec’
The mysqld server
‘share/mysql’ Error message files
‘sql-bench’
Benchmarks and crash-me test
‘var’
Databases and log files
Within an installation directory, the layout of a source installation differs from that of a
binary installation in the following ways:
• 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 ‘/usr/local/bin’ directory rather than in
‘/usr/local/mysql/scripts’.
• The header file and library directories are ‘include/mysql’ and ‘lib/mysql’ rather
than ‘include’ and ‘lib’.
You can create your own binary installation from a compiled source distribution by executing
the script ‘scripts/make_binary_distribution’.
2.2.6 How and When Updates Are Released
MySQL is evolving quite rapidly here at MySQL AB and we want to share this with other
MySQL users. We try to make a release when we have very useful features that others seem
to have a need for.
80
MySQL Technical Reference for Version 4.1.1-alpha
We also try to help out users who request features that are easy to implement. We take note
of what our licensed users want to have, and we especially take note of what our extended
e-mail supported customers want and try to help them out.
No one has to download a new release. The News section will tell you if the new release
has something you really want. See Appendix D [News], page 900.
We use the following policy when updating MySQL:
• 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.
• Production (stable-tested) releases are meant to appear about 1-2 times a year, but if
small bugs are found, a release with only bug fixes will be released.
• Working releases/bug fixes to old releases are meant to appear about every 1-8 weeks.
• Binary distributions for some platforms will be made by us for major releases. Other
people may make binary distributions for other systems but probably less frequently.
• We usually make patches available as soon as we have located and fixed small bugs.
They usually are immediately available from our public BitKeeper repositories. They
will also be included in the next release.
• Non-critical but annoying bugs will be added to the MySQL source repository and they
will be fixed in the next release.
• If there is, by any chance, a fatal bug in a release we will make a new release as soon
as possible. We would like other companies to do this, too.
The current production release is Version 4.0; we have already moved active development
to Version 4.1 and 5.0. Bugs will still be fixed in the 4.0 version, and critical bugs also in
the 3.23 series. We don’t believe in a complete freeze, as this also leaves out bug fixes and
things that “must be done.” “Somewhat frozen” means that we may add small things that
“almost surely will not affect anything that’s already working.”
MySQL uses a slightly different naming scheme from most other products. In general it’s
relatively safe to use any version that has been out for a couple of weeks without being
replaced with a new version. See Section 2.2.4 [Which version], page 76.
2.2.7 Release Philosophy - No Known Bugs in Releases
We put a lot of time and effort into making our releases bug free. To our knowledge, we
have not released a single MySQL version with any known ’fatal’ repeatable bugs.
A fatal bug is something that crashes MySQL under normal usage, gives wrong answers for
normal queries, or has a security problem.
We have documented all open problems, bugs, and issues that are dependent on design
decisions. See Section 1.8.6 [Bugs], page 51.
Our aim is to fix everything that is fixable, but without risking making a stable MySQL
version less stable. In certain cases, this means we can fix an issue in the development
versions, but not in the stable (production) version. Naturally, we document such issues so
that users are aware.
Here is a description of how our build process works:
Chapter 2: Installing MySQL
81
• We monitor bugs from our customer support list, the MySQL external mailing lists
and the bugs database at http://bugs.mysql.com/.
• All reported bugs for live versions are entered into the bugs database.
• When we fix a bug, we always try to make a test case of it and include this into our
test system to ensure that the bug will never come back. (About 90% of all fixed bugs
have a test case.)
• We also create test cases for all new features we add to MySQL.
• Before we start to build a new MySQL release, we ensure that all reported repeatable
bugs for the MySQL version (3.23.x, 4.0.x, etc) are fixed. If something is impossible to
fix (because some internal design decision in MySQL) we document this in the manual.
See Section 1.8.6 [Bugs], page 51.
• We do a build on all platforms for which we support binaries (15+ platforms) and run
our test suite and benchmark suite on all of them.
• We will not publish a binary for a platform for which the test or benchmark suite fails.
If it’s a general error in the source, we fix this and do the build plus tests on all systems
again, from scratch.
• If we, during the build and test process (which takes 2-3 days), receive a report regarding a fatal bug (for example, one that causes a core dump), we fix this and restart the
build process.
• After publishing the binaries on http://www.mysql.com/, we send out an announce
email on the mysql and announce mailing lists. See Section 1.7.1.1 [Mailing-list],
page 31. The announcement message contains a list of all changes to the release and
any known problems with the release. (The ’known problems’ section in the release
notes has only been needed in a handful of releases.)
• To quickly give our users access to the latest MySQL features, we do a new MySQL
release every 4-5 weeks.
• If we, after the release is done, get any bug reports that there was (after all) anything
critically wrong with the build on a specific platform, we will fix this at once and build
a new ’a’ release for that platform. Thanks to our large user base, problems are found
quickly.
• Our track record for making good releases is quite good. In the last 150 releases, we
had to do a new build for less than 10 releases (in 3 of these cases, the bug was a faulty
glibc library on one of our build machines that took us a long time to track down).
2.2.8 MySQL Binaries Compiled by MySQL AB
As a service, we at MySQL AB provide a set of binary distributions of MySQL that are
compiled at our site or at sites where customers kindly have given us access to their machines.
In addition to the binaries provided in platform-specific package formats (see Section 2.1
[Quick Standard Installation], page 57), we do offer binary distributions for a number of
platforms by means of compressed tar archives (.tar.gz).
These distributions are generated using the script Build-tools/Do-compile which compiles the source code and creates the binary tar.gz archive using scripts/make_binary_
82
MySQL Technical Reference for Version 4.1.1-alpha
distribution These binaries are configured and built with the following compilers and
options.
Binaries built on MySQL AB development systems:
Linux 2.4.xx x86 with gcc 2.95.3
CFLAGS="-O2 -mcpu=pentiumpro" CXX=gcc CXXFLAGS="-O2 mcpu=pentiumpro -felide-constructors" ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex --enable-thread-safe-client
--enable-local-infile --enable-assembler --disable-shared --withclient-ldflags=-all-static --with-mysqld-ldflags=-all-static
Linux 2.4.xx Intel Itanium 2 with ecc (Intel C++ Itanium Compiler 7.0)
CC=ecc CFLAGS="-O2 -tpp2 -ip -nolib_inline" CXX=ecc CXXFLAGS="-O2
-tpp2 -ip -nolib_inline" ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex --enable-thread-safe-client
--enable-local-infile
Linux 2.4.xx Intel Itanium with ecc (Intel C++ Itanium Compiler 7.0)
CC=ecc CFLAGS=-tpp1 CXX=ecc CXXFLAGS=-tpp1 ./configure -prefix=/usr/local/mysql --with-extra-charsets=complex --enablethread-safe-client --enable-local-infile
Linux 2.4.xx alpha with ccc (Compaq C V6.2-505 / Compaq C++ V6.3-006)
CC=ccc CFLAGS="-fast -arch generic" CXX=cxx CXXFLAGS="fast -arch generic -noexceptions -nortti" ./configure -prefix=/usr/local/mysql --with-extra-charsets=complex
--enable-thread-safe-client --enable-local-infile --withmysqld-ldflags=-non_shared --with-client-ldflags=-non_shared
--disable-shared
Linux 2.4.xx s390 with gcc 2.95.3
CFLAGS="-O2" CXX=gcc CXXFLAGS="-O2 -felide-constructors"
./configure --prefix=/usr/local/mysql --with-extra-charsets=complex
--enable-thread-safe-client --enable-local-infile --disable-shared
--with-client-ldflags=-all-static --with-mysqld-ldflags=-allstatic
Linux 2.4.xx x86 64 (AMD64) with gcc 3.2.1
CXX=gcc ./configure --prefix=/usr/local/mysql --with-extracharsets=complex --enable-thread-safe-client --enable-local-infile
--disable-shared
Sun Solaris 8 x86 with gcc 3.2.3
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="O3 -fno-omit-frame-pointer -felide-constructors -fnoexceptions -fno-rtti" ./configure --prefix=/usr/local/mysql -localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin
--with-extra-charsets=complex --enable-thread-safe-client
--enable-local-infile --disable-shared --with-innodb
Chapter 2: Installing MySQL
83
Sun Solaris 8 sparc with gcc 3.2
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
-fno-omit-frame-pointer -felide-constructors -fno-exceptions
-fno-rtti" ./configure --prefix=/usr/local/mysql --with-extracharsets=complex --enable-thread-safe-client --enable-local-infile
--enable-assembler --with-named-z-libs=no --with-named-curseslibs=-lcurses --disable-shared
Sun Solaris 8 sparc 64bit with gcc 3.2
CC=gcc CFLAGS="-O3 -m64 -fno-omit-frame-pointer" CXX=gcc
CXXFLAGS="-O3 -m64 -fno-omit-frame-pointer -felide-constructors
-fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex --enable-thread-safe-client
--enable-local-infile --enable-assembler --with-named-z-libs=no
--with-named-curses-libs=-lcurses --disable-shared
Sun Solaris 9 sparc with gcc 2.95.3
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
-fno-omit-frame-pointer -felide-constructors -fno-exceptions
-fno-rtti" ./configure --prefix=/usr/local/mysql --with-extracharsets=complex --enable-thread-safe-client --enable-local-infile
--enable-assembler --with-named-curses-libs=-lcurses --disableshared
Sun Solaris 9 sparc with cc-5.0 (Sun Forte 5.0)
CC=cc-5.0 CXX=CC ASFLAGS="-xarch=v9" CFLAGS="-Xa -xstrconst
-mt -D_FORTEC_ -xarch=v9" CXXFLAGS="-noex -mt -D_FORTEC_
-xarch=v9" ./configure --prefix=/usr/local/mysql --with-extracharsets=complex --enable-thread-safe-client --enable-local-infile
--enable-assembler --with-named-z-libs=no --enable-thread-safeclient --disable-shared
IBM AIX 4.3.2 ppc with gcc 3.2.3
CFLAGS="-O2 -mcpu=powerpc -Wa,-many " CXX=gcc CXXFLAGS="-O2
-mcpu=powerpc -Wa,-many -felide-constructors -fno-exceptions
-fno-rtti" ./configure --prefix=/usr/local/mysql --with-extracharsets=complex --enable-thread-safe-client --enable-local-infile
--with-named-z-libs=no --disable-shared
IBM AIX 4.3.3 ppc with xlC_r (IBM Visual Age C/C++ 6.0)
CC=xlc_r CFLAGS="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192"
CXX=xlC_r CXXFLAGS ="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192"
./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data
--libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
--enable-thread-safe-client --enable-local-infile --with-named-zlibs=no --disable-shared --with-innodb
IBM AIX 5.1.0 ppc with gcc 3.3
CFLAGS="-O2 -mcpu=powerpc -Wa,-many" CXX=gcc CXXFLAGS="-O2
-mcpu=powerpc -Wa,-many -felide-constructors -fno-exceptions
84
MySQL Technical Reference for Version 4.1.1-alpha
-fno-rtti" ./configure --prefix=/usr/local/mysql --with-extracharsets=complex --with-server-suffix="-pro" --enable-threadsafe-client --enable-local-infile --with-named-z-libs=no
--disable-shared
HP-UX 10.20 pa-risc1.1 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
HP-UX 11.11 pa-risc2.0 64bit with aCC (HP ANSI C++ B3910B A.03.33)
CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure -prefix=/usr/local/mysql --with-extra-charsets=complex --enablethread-safe-client --enable-local-infile --disable-shared
HP-UX 11.11 pa-risc2.0 32bit with aCC (HP ANSI C++ B3910B A.03.33)
CC=cc CXX=aCC CFLAGS="+DAportable" CXXFLAGS="+DAportable"
./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data
--libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
--enable-thread-safe-client --enable-local-infile --disable-shared
--with-innodb
Apple Mac OS X 10.2 powerpc with gcc 3.1
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
-fno-omit-frame-pointer -felide-constructors -fno-exceptions
-fno-rtti" ./configure --prefix=/usr/local/mysql --with-extracharsets=complex --enable-thread-safe-client --enable-local-infile
--disable-shared
FreeBSD 4.7 i386 with gcc 2.95.4
CFLAGS=-DHAVE_BROKEN_REALPATH ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex --enable-thread-safe-client
--enable-local-infile --enable-assembler --with-named-z-libs=notused --disable-shared
QNX Neutrino 6.2.1 i386 with gcc 2.95.3qnx-nto 20010315
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
-fno-omit-frame-pointer -felide-constructors -fno-exceptions
-fno-rtti" ./configure --prefix=/usr/local/mysql --with-extracharsets=complex --enable-thread-safe-client --enable-local-infile
--disable-shared
The following binaries are built on third-party systems kindly provided to MySQL AB by
other users. Please note that these are only provided as a courtesy. Since MySQL AB
does not have full control over these systems, we can only provide limited support for the
binaries built on these systems.
Chapter 2: Installing MySQL
85
SCO Unix 3.2v5.0.6 i386 with gcc 2.95.3
CFLAGS="-O3 -mpentium" LDFLAGS=-static CXX=gcc CXXFLAGS="-O3 mpentium -felide-constructors" ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex --enable-thread-safe-client
--enable-local-infile --with-named-z-libs=no --enable-thread-safeclient --disable-shared
SCO OpenUnix 8.0.0 i386 with CC 3.2
CC=cc CFLAGS="-O" CXX=CC ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex --enable-thread-safe-client
--enable-local-infile --with-named-z-libs=no --enable-thread-safeclient --disable-shared
Compaq Tru64 OSF/1 V5.1 732 alpha with cc/cxx (Compaq C V6.3-029i / DIGITAL
C++ V6.1-027)
CC="cc -pthread" CFLAGS="-O4 -ansi_alias -ansi_args -fast inline speed -speculate all" CXX="cxx -pthread" CXXFLAGS="-O4
-ansi_alias -fast -inline speed -speculate all -noexceptions
-nortti" ./configure --prefix=/usr/local/mysql --with-extracharsets=complex --enable-thread-safe-client --enable-local-infile
--with-prefix=/usr/local/mysql --with-named-thread-libs="lpthread -lmach -lexc -lc" --disable-shared --with-mysqld-ldflags=all-static
SGI Irix 6.5 IP32 with gcc 3.0.1
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXXFLAGS="-O3
-fno-omit-frame-pointer -felide-constructors -fno-exceptions
-fno-rtti" ./configure --prefix=/usr/local/mysql --with-extracharsets=complex --enable-thread-safe-client --enable-local-infile
--disable-shared
FreeBSD 5.0 sparc64 with gcc 3.2.1
CFLAGS=-DHAVE_BROKEN_REALPATH ./configure --prefix=/usr/local/mysql
--localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin
--with-extra-charsets=complex --enable-thread-safe-client
--enable-local-infile --disable-shared --with-innodb
The following compile options have been used for binary packages MySQL AB used to
provide in the past. These binaries are no longer being updated, but the compile options
are kept here for reference purposes.
Linux 2.2.xx sparc with egcs 1.1.2
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
-fno-omit-frame-pointer -felide-constructors -fno-exceptions
-fno-rtti" ./configure --prefix=/usr/local/mysql --with-extracharsets=complex --enable-thread-safe-client --enable-local-infile
--enable-assembler --disable-shared
Linux 2.2.x with x686 with gcc 2.95.2
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro
-felide-constructors -fno-exceptions -fno-rtti" ./configure
86
MySQL Technical Reference for Version 4.1.1-alpha
--prefix=/usr/local/mysql --enable-assembler --with-mysqldldflags=-all-static --disable-shared --with-extra-charsets=complex
SunOS 4.1.4 2 sun4c with gcc 2.7.2.1
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors" ./configure
--prefix=/usr/local/mysql --disable-shared --with-extracharsets=complex --enable-assembler
SunOS 5.5.1 (and above) sun4u with egcs 1.0.3a or 2.90.27 or gcc 2.95.2 and newer
CC=gcc CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors
-fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
--with-low-memory --with-extra-charsets=complex --enable-assembler
SunOS 5.6 i86pc with gcc 2.8.1
CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql
--with-low-memory --with-extra-charsets=complex
BSDI BSD/OS 3.1 i386 with gcc 2.7.2.1
CC=gcc CXX=gcc CXXFLAGS=-O ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex
BSDI BSD/OS 2.1 i386 with gcc 2.7.2
CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex
AIX 2 4 with gcc 2.7.2.2
CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex
Anyone who has more optimal options for any of the preceding configurations listed can
always mail them to the MySQL internals s mailing list. See Section 1.7.1.1 [Mailing-list],
page 31.
RPM distributions prior to MySQL Version 3.22 are user-contributed. Beginning with
Version 3.22, the RPMs are generated by us at MySQL AB.
If you want to compile a debug version of MySQL, you should add --with-debug or -with-debug=full to the preceding configure lines and remove any -fomit-frame-pointer
options.
For the Windows distribution, please see Section 2.1.1 [Windows installation], page 57.
2.2.9 Installing a MySQL Binary Distribution
This chapter covers the installation of MySQL binary distributions (.tar.gz Archives) for
various platforms (see Section 2.2.8 [MySQL binaries], page 81 for a detailed list).
In addition to these generic packages, we also offer binaries in platform-specific package
formats for selected platforms. See Section 2.1 [Quick Standard Installation], page 57 for
more information on how to install these.
The generic MySQL binary distributions are packaged as gzip-compressed GNU tar archives
(.tar.gz). You need the following tools to install a MySQL binary distribution:
• GNU gunzip to uncompress the distribution.
Chapter 2: Installing MySQL
87
• A reasonable tar to unpack the distribution. GNU tar is known to work. Some tar
implementations that come pre-installed with the operating system (e.g. Sun tar) are
known to have problems (with long file names, for example). In that case, you should
install GNU tar first.
If you run into problems, please always use mysqlbug when posting questions to a MySQL
mailing list. Even if the problem isn’t a bug, mysqlbug gathers system information that
will help others solve your problem. By not using mysqlbug, you lessen the likelihood of
getting a solution to your problem. You will find mysqlbug in the ‘bin’ directory after you
unpack the distribution. See Section 1.7.1.3 [Bug reports], page 34.
The basic commands you must execute to install and use a MySQL binary distribution are:
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
groupadd mysql
useradd -g mysql mysql
cd /usr/local
gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf ln -s full-path-to-mysql-VERSION-OS mysql
cd mysql
scripts/mysql_install_db
chown -R root .
chown -R mysql data
chgrp -R mysql .
bin/mysqld_safe --user=mysql &
If your version of MySQL is older than 4.0, substitute bin/safe_mysqld for bin/mysqld_
safe in the final command.
You can add new users using the bin/mysql_setpermission script if you install the DBI
and DBD-mysql Perl modules.
A more detailed description follows.
To install a binary distribution, follow these steps, then proceed to Section 2.4 [Postinstallation], page 105, for post-installation setup and testing:
1. Pick the directory under which you want to unpack the distribution, and move into it.
In the following example, we unpack the distribution under ‘/usr/local’ (The following
instructions, therefore, assume you have permission to create files and directories in
‘/usr/local’. If that directory is protected, you will need to perform the installation
as root.)
2. Obtain a distribution file from one of the sites listed in Section 2.2.1 [Getting MySQL],
page 71.
MySQL binary distributions are provided as compressed tar archives and have names
like ‘mysql-VERSION-OS.tar.gz’, where VERSION is a number (for example, 3.21.15),
and OS indicates the type of operating system for which the distribution is intended (for
example, pc-linux-gnu-i586). Note that all binaries are built from the same MySQL
source distribution.
3. Add a user and group for mysqld to run as:
shell> groupadd mysql
shell> useradd -g mysql mysql
88
MySQL Technical Reference for Version 4.1.1-alpha
These commands add the mysql group and the mysql user. The syntax for useradd
and groupadd may differ slightly on different versions of Unix. They may also be
called adduser and addgroup. You may wish to call the user and group something else
instead of mysql.
4. Change into the intended installation directory:
shell> cd /usr/local
5. Unpack the distribution, which will create the installation directory. Then create a
symbolic link to that directory:
shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf shell> ln -s full-path-to-mysql-VERSION-OS mysql
Using GNU tar, you can also replace the first line with the following alternative command to decompress and extract the distribution in one go:
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
The first command creates a directory named ‘mysql-VERSION-OS’. The second command makes a symbolic link to that directory. This lets you refer more easily to the
installation directory as ‘/usr/local/mysql’.
6. Change into the installation directory:
shell> cd mysql
You will find several files and subdirectories in the mysql directory. The most important
for installation purposes are the ‘bin’ and ‘scripts’ subdirectories.
‘bin’
‘scripts’
This directory contains client programs and the server You should add the
full pathname of this directory to your PATH environment variable so that
your shell finds the MySQL programs properly. See Appendix F [Environment variables], page 1032.
This directory contains the mysql_install_db script used to initialise the
mysql database containing the grant tables that store the server access
permissions.
7. If you would like to use mysqlaccess and have the MySQL distribution in some nonstandard place, you must change the location where mysqlaccess expects to find the
mysql client. Edit the ‘bin/mysqlaccess’ script at approximately line 18. Search for
a line that looks like this:
$MYSQL
= ’/usr/local/bin/mysql’;
# path to mysql executable
Change the path to reflect the location where mysql actually is stored on your system.
If you do not do this, you will get a Broken pipe error when you run mysqlaccess.
8. Create the MySQL grant tables (necessary only if you haven’t installed MySQL before):
shell> scripts/mysql_install_db
Note that MySQL versions older than Version 3.22.10 started the MySQL server when
you run mysql_install_db. This is no longer true.
9. Change ownership of binaries to root and ownership of the data directory to the user
that you will run mysqld as:
shell> chown -R root /usr/local/mysql/.
shell> chown -R mysql /usr/local/mysql/data
Chapter 2: Installing MySQL
89
shell> chgrp -R mysql /usr/local/mysql/.
The first command changes the owner attribute of the files to the root user, the second
one changes the owner attribute of the data directory to the mysql user, and the third
one changes the group attribute to the mysql group.
10. If you want to install support for the Perl DBI/DBD interface, see Section 2.7 [Perl
support], page 156.
11. If you would like MySQL to start automatically when you boot your machine, you can
copy support-files/mysql.server to the location where your system has its startup
files. More information can be found in the support-files/mysql.server script itself
and in Section 2.4.3 [Automatic start], page 113.
After everything has been unpacked and installed, you should initialise and test your distribution.
You can start the MySQL server with the following command:
shell> bin/mysqld_safe --user=mysql &
If your version of MySQL is older than 4.0, substitute bin/safe_mysqld for bin/mysqld_
safe in the command.
Now proceed to Section 4.8.2 [mysqld_safe],
[Post-installation], page 105.
page 315,
and See Section 2.4
2.3 Installing a MySQL Source Distribution
Before you proceed with the source installation, check first to see if our binary is available
for your platform and if it will work for you. We put a lot of effort into making sure that
our binaries are built with the best possible options.
You need the following tools to build and install MySQL from source:
• GNU gunzip to uncompress the distribution.
• A reasonable tar to unpack the distribution. GNU tar is known to work. Some tar
implementations that come pre-installed with the operating system (e.g. Sun tar) are
known to have problems (with long file names, for example). In that case, you should
install GNU tar first.
• A working ANSI C++ compiler. gcc >= 2.95.2, egcs >= 1.0.2 or egcs 2.91.66, SGI
C++, and SunPro C++ are some of the compilers that are known to work. libg++ is
not needed when using gcc. gcc 2.7.x has a bug that makes it impossible to compile
some perfectly legal C++ files, such as ‘sql/sql_base.cc’. If you only have gcc 2.7.x,
you must upgrade your gcc to be able to compile MySQL. gcc 2.8.1 is also known to
have problems on some platforms, so it should be avoided if a new compiler exists for
the platform.
gcc >= 2.95.2 is recommended when compiling MySQL Version 3.23.x.
• A good make program. GNU make is always recommended and is sometimes required.
If you have problems, we recommend trying GNU make 3.75 or newer.
If you are using a recent version of gcc, recent enough to understand the -fno-exceptions
option, it is very important that you use it. Otherwise, you may compile a binary that
90
MySQL Technical Reference for Version 4.1.1-alpha
crashes randomly. We also recommend that you use -felide-constructors and -fnortti along with -fno-exceptions. When in doubt, do the following:
CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors -fno-exceptions \
-fno-rtti" ./configure --prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static
On most systems this will give you a fast and stable binary.
If you run into problems, please always use mysqlbug when posting questions to a MySQL
mailing list. Even if the problem isn’t a bug, mysqlbug gathers system information that
will help others solve your problem. By not using mysqlbug, you lessen the likelihood of
getting a solution to your problem. You will find mysqlbug in the ‘scripts’ directory after
you unpack the distribution. See Section 1.7.1.3 [Bug reports], page 34.
2.3.1 Quick Installation Overview
The basic commands you must execute to install a MySQL source distribution are:
shell> groupadd mysql
shell> useradd -g mysql mysql
shell> gunzip < mysql-VERSION.tar.gz | tar -xvf shell> cd mysql-VERSION
shell> ./configure --prefix=/usr/local/mysql
shell> make
shell> make install
shell> scripts/mysql_install_db
shell> chown -R root /usr/local/mysql
shell> chown -R mysql /usr/local/mysql/var
shell> chgrp -R mysql /usr/local/mysql
shell> cp support-files/my-medium.cnf /etc/my.cnf
shell> /usr/local/mysql/bin/mysqld_safe --user=mysql &
If your version of MySQL is older than 4.0, substitute bin/safe_mysqld for bin/mysqld_
safe in the final command.
If you want to have support for InnoDB tables, you should edit the /etc/my.cnf file and
remove the # character before the parameter that starts with innodb_.... See Section 4.1.2
[Option files], page 206, and Section 7.5.3 [InnoDB start], page 613.
If you start from a source RPM, do the following:
shell> rpm --rebuild --clean MySQL-VERSION.src.rpm
This will make a binary RPM that you can install.
You can add new users using the bin/mysql_setpermission script if you install the DBI
and DBD-mysql Perl modules.
A more detailed description follows.
To install a source distribution, follow these steps, then proceed to Section 2.4 [Postinstallation], page 105, for post-installation initialisation and testing:
1. Pick the directory under which you want to unpack the distribution, and move into it.
Chapter 2: Installing MySQL
91
2. Obtain a distribution file from one of the sites listed in Section 2.2.1 [Getting MySQL],
page 71.
3. If you are interested in using Berkeley DB tables with MySQL, you will need to obtain
a patched version of the Berkeley DB source code. Please read the chapter on Berkeley
DB tables before proceeding. See Section 7.6 [BDB], page 663.
MySQL source distributions are provided as compressed tar archives and have names
like ‘mysql-VERSION.tar.gz’, where VERSION is a number like 4.1.1-alpha.
4. Add a user and group for mysqld to run as:
shell> groupadd mysql
shell> useradd -g mysql 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. They may also be
called adduser and addgroup. You may wish to call the user and group something else
instead of mysql.
5. Unpack the distribution into the current directory:
shell> gunzip < /path/to/mysql-VERSION.tar.gz | tar xvf This command creates a directory named ‘mysql-VERSION’.
6. Change 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 some options. Run ./configure
--help for a list of options. Section 2.3.3 [configure options], page 93, 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 if
configure aborts. Post the bug report using the mysqlbug script. See Section 1.7.1.3
[Bug reports], page 34.
If the compile fails, see Section 2.3.5 [Compilation problems], page 98, for help with a
number of common problems.
8. Install everything:
shell> make install
You might need to run this command as root.
9. Create the MySQL grant tables (necessary only if you haven’t installed MySQL before):
shell> scripts/mysql_install_db
Note that MySQL versions older than Version 3.22.10 started the MySQL server when
you run mysql_install_db. This is no longer true.
92
MySQL Technical Reference for Version 4.1.1-alpha
10. Change ownership of binaries to root and ownership of the data directory to the user
that you will run mysqld as:
shell> chown -R root /usr/local/mysql
shell> chown -R mysql /usr/local/mysql/var
shell> chgrp -R mysql /usr/local/mysql
The first command changes the owner attribute of the files to the root user, the second
one changes the owner attribute of the data directory to the mysql user, and the third
one changes the group attribute to the mysql group.
11. If you want to install support for the Perl DBI/DBD interface, see Section 2.7 [Perl
support], page 156.
12. If you would like MySQL to start automatically when you boot your machine, you can
copy support-files/mysql.server to the location where your system has its startup
files. More information can be found in the support-files/mysql.server script itself
and in Section 2.4.3 [Automatic start], page 113.
After everything has been installed, you should initialise and test your distribution using
this command:
shell> /usr/local/mysql/bin/mysqld_safe --user=mysql &
If your version of MySQL is older than 4.0, substitute safe_mysqld for mysqld_safe in the
command.
If that command fails immediately with mysqld daemon ended, you can find some information in the file ‘mysql-data-directory/’hostname’.err’. The likely reason is that you
already have another mysqld server running. See Section 4.2 [Multiple servers], page 209.
Now proceed to Section 2.4 [Post-installation], page 105.
2.3.2 Applying Patches
Sometimes patches appear on the mailing list or are placed in the patches area of the
MySQL web site (http://www.mysql.com/downloads/patches.html).
To apply a patch from the mailing list, save the message in which the patch appears in a file,
change into the top-level directory of your MySQL source tree, and run these commands:
shell> patch -p1 < patch-file-name
shell> rm config.cache
shell> make clean
Patches from the FTP site are distributed as plain text files or as files compressed with
gzip. Apply a plain patch as shown previously for mailing list patches. To apply a compressed patch, change into the top-level directory of your MySQL source tree and run these
commands:
shell> gunzip < patch-file-name.gz | patch -p1
shell> rm config.cache
shell> make clean
After applying a patch, follow the instructions for a normal source install, beginning with
the ./configure step. After running the make install step, restart your MySQL server.
Chapter 2: Installing MySQL
93
You may need to bring down any currently running server before you run make install.
(Use mysqladmin shutdown to do this.) Some systems do not allow you to install a new
version of a program if it replaces the version that is currently executing.
2.3.3 Typical configure Options
The configure script gives you a great deal of control over how you configure your MySQL
distribution. Typically you do this using options on the configure command-line. You can
also affect configure using certain environment variables. See Appendix F [Environment
variables], page 1032. For a list of options supported by configure, run this command:
shell> ./configure --help
Some of the more commonly used configure options are described here:
• To compile just the MySQL client libraries and client programs and not the server, use
the --without-server option:
shell> ./configure --without-server
If you don’t have a C++ compiler, mysql will not compile (it is the one client program
that requires C++). In this case, you can remove the code in configure that tests
for the C++ compiler and then run ./configure with the --without-server option.
The compile step will still try to build mysql, but you can ignore any warnings about
‘mysql.cc’. (If make stops, try make -k to tell it to continue with the rest of the build
even if errors occur.)
• If you want to get an embedded MySQL library (libmysqld.a) you should use the
--with-embedded-server option.
• If you don’t want your log files and database directories located under
‘/usr/local/var’, use a configure command, something like one of these:
shell> ./configure --prefix=/usr/local/mysql
shell> ./configure --prefix=/usr/local \
--localstatedir=/usr/local/mysql/data
The first command changes the installation prefix so that everything is installed under
‘/usr/local/mysql’ rather than the default of ‘/usr/local’. The second command
preserves the default installation prefix, but overrides the default location for database
directories (normally ‘/usr/local/var’) and changes it to /usr/local/mysql/data.
After you have compiled MySQL, you can change these options with option files. See
Section 4.1.2 [Option files], page 206.
• If you are using Unix and you want the MySQL socket located somewhere other than
the default location (normally in the directory ‘/tmp’ or ‘/var/run’) use a configure
command like this:
shell> ./configure --with-unix-socket-path=/usr/local/mysql/tmp/mysql.sock
Note that the given file must be an absolute pathname. You can also later change the
location ‘mysql.sock’ by using the MySQL option files. See Section A.4.5 [Problems
with mysql.sock], page 874.
• If you want to compile statically linked programs (for example, to make a binary
distribution, to get more speed, or to work around problems with some Red Hat Linux
distributions), run configure like this:
94
MySQL Technical Reference for Version 4.1.1-alpha
shell> ./configure --with-client-ldflags=-all-static \
--with-mysqld-ldflags=-all-static
• If you are using gcc and don’t have libg++ or libstdc++ installed, you can tell
configure to use gcc as your C++ compiler:
shell> CC=gcc CXX=gcc ./configure
When you use gcc as your C++ compiler, it will not attempt to link in libg++ or
libstdc++. This may be a good idea to do even if you have the above libraries installed,
as some versions of these libraries have caused strange problems for MySQL users in
the past.
Here are some common environment variables to set depending on the compiler you
are using:
Compiler
Recommended options
gcc 2.7.2.1
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors"
egcs 1.0.3a
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors -fnoexceptions -fno-rtti"
gcc 2.95.2
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 mpentiumpro \ -felide-constructors -fno-exceptions -fno-rtti"
pgcc 2.90.29 or CFLAGS="-O3 -mpentiumpro -mstack-align-double" CXX=gcc
newer
\
CXXFLAGS="-O3
-mpentiumpro
-mstack-align-double
-felide-constructors \ -fno-exceptions -fno-rtti"
In most cases you can get a reasonably optimal MySQL binary by using the options
from the preceding table 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://www.mysql.com/ are all
compiled with full optimisation and should be perfect for most users. See Section 2.2.8
[MySQL binaries], page 81. There are some configuration setings you can tweak to
make an even faster binary, but this is only for advanced users. See Section 5.5.3
[Compile and link options], page 434.
If the build fails and produces errors about your compiler or linker not being able to
create the shared library ‘libmysqlclient.so.#’ (‘#’ is a version number), you can
work around this problem by giving the --disable-shared option to configure. In
this case, configure will not build a shared ‘libmysqlclient.so.#’ library.
• You can configure MySQL not to use DEFAULT column values for non-NULL columns
(that is, columns that are not allowed to be NULL). See Section 1.8.5.2 [constraint
NOT NULL], page 50.
shell> CXXFLAGS=-DDONT_USE_DEFAULT_FIELDS ./configure
• By default, MySQL uses the ISO-8859-1 (Latin1) character set. To change the default
set, use the --with-charset option:
Chapter 2: Installing MySQL
95
shell> ./configure --with-charset=CHARSET
CHARSET may be one of big5, cp1251, cp1257, czech, danish, dec8, dos, euc_kr,
gb2312, gbk, german1, hebrew, hp8, hungarian, koi8_ru, koi8_ukr, latin1, latin2,
sjis, swe7, tis620, ujis, usa7, or win1251ukr. See Section 4.7.1 [Character sets],
page 309.
If you want to convert characters between the server and the client, you should take a
look at the SET CHARACTER SET command. See Section 5.5.6 [SET], page 437.
Warning: If you change character sets after having created any tables, you will have
to run myisamchk -r -q --set-character-set=charset on every table. Your indexes
may be sorted incorrectly otherwise. (This can happen if you install MySQL, create
some tables, then reconfigure MySQL to use a different character set and reinstall it.)
With the option --with-extra-charsets=LIST you can define which additional character sets should be compiled into the server.
Here LIST is either a list of character sets separated with spaces, complex to include all
characters that can’t be dynamically loaded, or all to include all character sets into
the binaries.
• To configure MySQL with debugging code, use the --with-debug option:
shell> ./configure --with-debug
This causes a safe memory allocator to be included that can find some errors and
that provides output about what is happening. See Section E.1 [Debugging server],
page 1020.
• If your client programs are using threads, you need to also compile a thread-safe version of the MySQL client library with the --enable-thread-safe-client configure
options. This will create a libmysqlclient_r library with which you should link your
threaded applications. See Section 11.1.14 [Threaded clients], page 810.
• Options that pertain to particular systems can be found in the system-specific section
of this manual. See Section 2.6 [Operating System Specific Notes], page 126.
2.3.4 Installing from the Development Source Tree
Caution: You should read this section only if you are interested in helping us test our new
code. If you just want to get MySQL up and running on your system, you should use a
standard release distribution (either a source or binary distribution will do).
To obtain our most recent development source tree, use these instructions:
1. Download BitKeeper from http://www.bitmover.com/cgi-bin/download.cgi. You
will need Bitkeeper 3.0 or newer to access our repository.
2. Follow the instructions to install it.
3. After BitKeeper is installed, first go to the directory you want to work from, and then
use one of the following commands to clone the MySQL version branch of your choice:
To clone the 3.23 (old) branch, use this command:
shell> bk clone bk://mysql.bkbits.net/mysql-3.23 mysql-3.23
To clone the 4.0 (stable/production) branch, use this command:
96
MySQL Technical Reference for Version 4.1.1-alpha
shell> bk clone bk://mysql.bkbits.net/mysql-4.0 mysql-4.0
To clone the 4.1 alpha branch, use this command:
shell> bk clone bk://mysql.bkbits.net/mysql-4.1 mysql-4.1
To clone the 5.0 development branch, use this command:
shell> bk clone bk://mysql.bkbits.net/mysql-5.0 mysql-5.0
In the preceding examples the source tree will be set up in the ‘mysql-3.23/’,
‘mysql-4.0/’, ‘mysql-4.1/’, or ‘mysql-5.0/’ subdirectory of your current directory.
If you are behind a firewall and can only initiate HTTP connections, you can also use
BitKeeper via HTTP.
If you are required to use a proxy server, simply set the environment variable http_
proxy to point to your proxy:
shell> export http_proxy="http://your.proxy.server:8080/"
Now, simply replace the bk:// with http:// when doing a clone. Example:
shell> bk clone http://mysql.bkbits.net/mysql-4.1 mysql-4.1
The initial download of the source tree may take a while, depending on the speed of
your connection - please be patient.
4. You will need GNU make, autoconf 2.53 (or newer), automake 1.5, libtool 1.4,
and m4 to run the next set of commands. Even though many operating system already
come with their own implementation of make, chances are high that the compilation
fails with strange error messages. Therefore it is highly recommended to use GNU
make (sometimes also named gmake) by all means.
Fortunately, a large number of operating systems already ship with the GNU toolchain
preinstalled or supply installable packages of these. In any case, they can also be
downloaded from the following locations:
• http://www.gnu.org/software/autoconf/
• http://www.gnu.org/software/automake/
• http://www.gnu.org/software/libtool/
• http://www.gnu.org/software/make/
If you are trying to configure MySQL 4.1, you will also need GNU bison 1.75. Older
versions of bison may report this error: sql_yacc.yy:#####: fatal error: maximum
table size (32767) exceeded. Note: the maximum table size is not actually exceeded, the error is caused by bugs in these earlier bison versions.
Versions of MySQL before version 4.1 may also compile with other yacc implementations (e.g. BSD yacc 91.7.30). For later versions, GNU bison is a requirement.
The typical command to do in a shell is:
cd mysql-4.0
bk -r edit
aclocal; autoheader; autoconf; automake
(cd innobase; aclocal; autoheader; autoconf; automake) # for InnoDB
(cd bdb/dist; sh s_all ) # for Berkeley DB
./configure # Add your favorite options here
make
Chapter 2: Installing MySQL
5.
6.
7.
8.
9.
10.
11.
97
If you get some strange error during this stage, check that you really have libtool
installed.
A collection of our standard configure scripts is located in the ‘BUILD/’ subdirectory. If
you are lazy, you can use ‘BUILD/compile-pentium-debug’. To compile on a different
architecture, modify the script by removing flags that are Pentium-specific.
When the build is done, run make install. Be careful with this on a production
machine; the command may overwrite your live release installation. If you have another
installation of MySQL, we recommend that you run ./configure with different values
for the prefix, with-tcp-port, and unix-socket-path options than those used for
your production server.
Play hard with your new installation and try to make the new features crash. Start by
running make test. See Section 13.1.2 [MySQL test suite], page 843.
If you have gotten to the make stage and the distribution does not compile, please report
it in our bugs database at http://bugs.mysql.com/. If you have installed the latest
versions of the required GNU tools, and they crash trying to process our configuration
files, please report that also. However, if you execute aclocal and get a command not
found error or a similar problem, do not report it. Instead, make sure all the necessary
tools are installed and that your PATH variable is set correctly so that your shell can
find them.
After the initial bk clone operation to get the source tree, you should run bk pull
periodically to get the updates.
You can examine the change history for the tree with all the diffs by using bk sccstool.
If you see some funny diffs or code that you have a question about, do not hesitate
to send e-mail to the MySQL internals mailing list. See Section 1.7.1.1 [Mailing-list],
page 31. Also, if you think you have a better idea on how to do something, send an
e-mail to the same address with a patch. bk diffs will produce a patch for you after
you have made changes to the source. If you do not have the time to code your idea,
just send a description.
BitKeeper has a nice help utility that you can access via bk helptool.
Please note that any commits (bk ci or bk citool) will trigger the posting of a message
with the changeset to our internals mailing list, as well as the usual openlogging.org
submission with just the changeset comments. Generally, you wouldn’t need to use
commit (since the public tree will not allow bk push), but rather use the bk diffs
method described previously.
You can also browse changesets, comments and sourcecode online by browsing to for example, http://mysql.bkbits.net:8080/mysql-4.1 For MySQL 4.1.
The manual is in a separate tree which can be cloned with:
shell> bk clone bk://mysql.bkbits.net/mysqldoc mysqldoc
There are also public BitKeeper trees for MySQL Control Center and Connector/ODBC.
They can be cloned respectively as follows.
To clone MySQL Control center, use this command:
shell> bk clone http://mysql.bkbits.net/mysqlcc mysqlcc
To clone Connector/ODBC, use this command:
shell> bk clone http://mysql.bkbits.net/myodbc3 myodbc3
98
MySQL Technical Reference for Version 4.1.1-alpha
2.3.5 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.
See Section 2.3.6 [MIT-pthreads], page 101 for warnings that may occur when using MITpthreads. 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 already has 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.
The following list describes some of the problems when compiling MySQL that have been
found to occur most often:
• If you get errors when compiling ‘sql_yacc.cc’, such as the ones shown here, you have
probably run out of memory or swap space:
Internal compiler error: program cc1plus got fatal signal 11
or
Out of virtual memory
or
Virtual memory exhausted
The problem is that gcc requires huge amounts 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-low-memory option usually fixes it.
• By default, configure picks c++ as the compiler name and GNU c++ links with -lg++.
If you are using gcc, that behaviour can cause problems during configuration such as
this:
configure: error: installation or configuration problem:
C++ compiler cannot create executables.
Chapter 2: Installing MySQL
99
You might also observe problems during compilation related to g++, libg++, or
libstdc++.
One cause of these problems is that you may not have g++, or you may have g++ but
not libg++, or libstdc++. Take a look at the ‘config.log’ file. It should contain the
exact reason why your C++ compiler didn’t work. To work around these problems, you
can use gcc as your C++ compiler. Try setting the environment variable CXX to "gcc
-O3". For example:
shell> CXX="gcc -O3" ./configure
This works because gcc compiles C++ sources as well as g++ does, but does not link in
libg++ or libstdc++ by default.
Another way to fix these problems, of course, is to install g++, libg++, and libstdc++.
We would however like to recommend you to not use libg++ or libstdc++ with MySQL
as this will only increase the binary size of mysqld without giving you any benefits.
Some versions of these libraries have also caused strange problems for MySQL users in
the past.
Using gcc as the C++ compiler is also required, if you want to compile MySQL with
RAID functionality (see Section 6.5.3 [CREATE TABLE], page 570 for more info on
RAID table type) and you are using GNU gcc version 3 and above. If you get errors
like the ones below during the linking stage when you configure MySQL to compile
with the option --with-raid, try to use gcc as your C++ compiler by defining the
above mentioned environment variable CXX:
gcc -O3 -DDBUG_OFF -rdynamic -o isamchk isamchk.o sort.o libnisam.a
../mysys/libmysys.a ../dbug/libdbug.a ../strings/libmystrings.a -lpthread
-lz -lcrypt -lnsl -lm -lpthread
../mysys/libmysys.a(raid.o)(.text+0x79): In function ‘my_raid_create’:
: undefined reference to ‘operator new(unsigned)’
../mysys/libmysys.a(raid.o)(.text+0xdd): In function ‘my_raid_create’:
: undefined reference to ‘operator delete(void*)’
../mysys/libmysys.a(raid.o)(.text+0x129): In function ‘my_raid_open’:
: undefined reference to ‘operator new(unsigned)’
../mysys/libmysys.a(raid.o)(.text+0x189): In function ‘my_raid_open’:
: undefined reference to ‘operator delete(void*)’
../mysys/libmysys.a(raid.o)(.text+0x64b): In function ‘my_raid_close’:
: undefined reference to ‘operator delete(void*)’
collect2: ld returned 1 exit status
• If your compile fails with errors, such as any of the following, you must upgrade your
version of make to GNU make:
making all in mit-pthreads
make: Fatal error in reader: Makefile, line 18:
Badly formed macro assignment
or
make: file ‘Makefile’ line 18: Must be a separator (:
or
pthread.h: No such file or directory
Solaris and FreeBSD are known to have troublesome make programs.
100
•
•
•
•
•
•
MySQL Technical Reference for Version 4.1.1-alpha
GNU make Version 3.75 is known to work.
If you want to define flags to be used by your C or C++ compilers, do so by adding
the flags to the CFLAGS and CXXFLAGS environment variables. You can also specify the
compiler names this way using CC and CXX. For example:
shell> CC=gcc
shell> CFLAGS=-O3
shell> CXX=gcc
shell> CXXFLAGS=-O3
shell> export CC CFLAGS CXX CXXFLAGS
See Section 2.2.8 [MySQL binaries], page 81, for a list of flag definitions that have been
found to be useful on various systems.
If you get an error message like this, you need to upgrade your gcc compiler:
client/libmysql.c:273: parse error before ‘__attribute__’
gcc 2.8.1 is known to work, but we recommend using gcc 2.95.2 or egcs 1.0.3a instead.
If you get errors such as those shown here when compiling mysqld, configure didn’t
correctly detect the type of the last argument to accept(), getsockname(), or
getpeername():
cxx: Error: mysqld.cc, line 645: In this statement, the referenced
type of the pointer value ’’length’’ is ’’unsigned long’’, which
is not compatible with ’’int’’.
new_sock = accept(sock, (struct sockaddr *)&cAddr, &length);
To fix this, edit the ‘config.h’ file (which is generated by configure). Look for these
lines:
/* Define as the base type of the last arg to accept */
#define SOCKET_SIZE_TYPE XXX
Change XXX to size_t or int, depending on your operating system. (Note that you
will have to do this each time you run configure because configure regenerates
‘config.h’.)
The ‘sql_yacc.cc’ file is generated from ‘sql_yacc.yy’. Normally the build process
doesn’t need to create ‘sql_yacc.cc’, because MySQL comes with an already generated
copy. However, if you do need to re-create it, you might encounter this error:
"sql_yacc.yy", line xxx fatal: default action causes potential...
This is a sign that your version of yacc is deficient. You probably need to install bison
(the GNU version of yacc) and use that instead.
If you need to debug mysqld or a MySQL client, run configure with the --withdebug option, then recompile and link your clients with the new client library. See
Section E.2 [Debugging client], page 1025.
If you get a compilation error on Linux (e.g. SuSE Linux 8.1 or Red Hat Linux 7.3)
similar to the following one:
libmysql.c:1329: warning: passing arg 5 of ‘gethostbyname_r’ from incompatible p
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
Chapter 2: Installing MySQL
101
By default, the configure script attempts to determine the correct number of arguments by using g++ the GNU C++ compiler. This test yields wrong results, if g++ is
not installed. There are two ways to work around this problem:
• 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"
Please note that you need to run configure again afterwards.
2.3.6 MIT-pthreads Notes
This section describes some of the issues involved in using MIT-pthreads.
Note that on Linux you should not use MIT-pthreads but use the installed LinuxThreads
implementation instead. See Section 2.6.2 [Linux], page 129.
If your system does not provide native thread support, you will need to build MySQL using
the MIT-pthreads package. This includes older FreeBSD systems, SunOS 4.x, Solaris 2.4
and earlier, and some others. See Section 2.2.3 [Which OS], page 74.
Note, that beginning with MySQL 4.0.2 MIT-pthreads are no longer part of the source
distribution. If you require this package, you need to download it separately from
http://www.mysql.com/Downloads/Contrib/pthreads-1_60_beta6-mysql.tar.gz
After downloading, extract this source archive into the top level of the MySQL source
directory. It will create a new subdirectory mit-pthreads.
• On most systems, you can force MIT-pthreads to be used by running configure with
the --with-mit-threads option:
shell> ./configure --with-mit-threads
Building in a non-source directory is not supported when using MIT-pthreads because
we want to minimise our changes to this code.
• The checks that determine whether to use MIT-pthreads occur only during the part
of the configuration process that deals with the server code. If you have configured
the distribution using --without-server to build only the client code, clients will not
know whether MIT-pthreads is being used and will use Unix socket connections by
default. Because Unix sockets do not work under MIT-pthreads on some platforms,
this means you will need to use -h or --host when you run client programs.
• When MySQL is compiled using MIT-pthreads, system locking is disabled by default
for performance reasons. You can tell the server to use system locking with the -external-locking option. This is only needed if you want to be able to run two
MySQL servers against the same datafiles (not recommended).
• Sometimes the pthread bind() command fails to bind to a socket without any error
message (at least on Solaris). The result is that all connections to the server fail. For
example:
shell> mysqladmin version
mysqladmin: connect to server at ’’ failed;
error: ’Can’t connect to mysql server on localhost (146)’
102
MySQL Technical Reference for Version 4.1.1-alpha
The solution to this is to kill the mysqld server and restart it. This has only happened
to us when we have forced down the server and done a restart immediately.
• With MIT-pthreads, the sleep() system call isn’t interruptible with SIGINT (break).
This is only noticeable when you run mysqladmin --sleep. You must wait for the
sleep() call to terminate before the interrupt is served and the process stops.
• When linking, you may receive warning messages like these (at least on Solaris); they
can be ignored:
ld: warning: symbol ‘_iob’ has differing sizes:
(file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
file /usr/lib/libc.so value=0x140);
/my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
ld: warning: symbol ‘__iob’ has differing sizes:
(file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
file /usr/lib/libc.so value=0x140);
/my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
• Some other warnings also can be ignored:
implicit declaration of function ‘int strtoll(...)’
implicit declaration of function ‘int strtoul(...)’
• We haven’t gotten readline to work with MIT-pthreads. (This isn’t needed, but may
be interesting for someone.)
2.3.7 Installing MySQL from Source on Windows
These instructions describe how to build MySQL binaries from source for versions 4.1 and
above on Windows. Instructions are provided for building binaries from a standard source
distribution or from the BitKeeper tree that contains the latest development source.
Note: The instructions in this document are strictly for users who want to test MySQL on
Windows from the latest source distribution or from the BitKeeper tree. For production use,
MySQL AB does not advise using a MySQL server built by yourself from source. Normally,
it is best to use precompiled binary distributions of MySQL that are built specifically
for optimal performance on Windows by MySQL AB. Instructions for installing a binary
distributions are available at Section 2.1.1 [Windows installation], page 57.
To build MySQL on Windows from source, you need the following compiler and resources
available on your Windows system:
• VC++ 6.0 compiler (updated with 4 or 5 SP and Pre-processor package) The
Pre-processor package is necessary for the macro assembler. More details at:
http://msdn.microsoft.com/vstudio/downloads/updates/sp/vs6/sp5/faq.aspx.
• Approximately 45 MB disk space
• 64 MB RAM
You’ll also need a MySQL source distribution for Windows. There are two ways you can
get a source distribution for MySQL version 4.1 and above:
1. Obtain a source distribution packaged by MySQL AB for the particular
version of MySQL in which you are interested. Prepackaged source distribu-
Chapter 2: Installing MySQL
103
tions are available for released versions of MySQL and can be obtained from
http://www.mysql.com/downloads/.
2. You can package a source distribution yourself from the latest BitKeeper developer
source tree. If you plan to do this, you must create the package on a Unix system
and then transfer it to your Windows system. (The reason for this is that some of the
configuration and build steps require tools that work only on Unix.) The BitKeeper
approach thus requires:
• A system running Unix, or a Unix-like system such as Linux
• BitKeeper 3.0 installed on that system. You can obtain BitKeeper from
http://www.bitkeeper.com/.
If you are using a Windows source distribution, you can go directly to Section 2.3.7.1 [Windows VC++ Build], page 103. To build from the BitKeeper tree, proceed to Section 2.3.7.2
[Windows BitKeeper Build], page 105.
If you find something not working as expected, or you have suggestions about ways to
improve the current build process on Windows, please send a message to the win32 mailing
list. See Section 1.7.1.1 [Mailing-list], page 31.
2.3.7.1 Building MySQL Using VC++
Note: MySQL 4.1 and above VC++ workspace files are compatible with Microsoft Visual
Studio 6.0 and above(7.0/.NET) editions and tested by MySQL AB staff before each release.
Follow this procedure to build MySQL:
1. Create a work directory (for example, ‘workdir’).
2. Unpack the source distribution in the aforementioned directory using WinZip or other
Windows tools that can read ‘.zip’ files.
3. Start the VC++ 6.0 compiler.
4. In the File menu, select Open Workspace.
5. Open the ‘mysql.dsw’ workspace you find in the work directory.
6. From the Build menu, select the Set Active Configuration menu.
7. Click over the screen selecting mysqld - Win32 Debug and click OK.
8. Press F7 to begin the build of the debug server, libraries, and some client applications.
9. Compile the release versions that you want, in the same way.
10. Debug versions of the programs and libraries are placed in the ‘client_debug’ and
‘lib_debug’ directories. Release versions of the programs and libraries are placed in
the ‘client_release’ and ‘lib_release’ directories. Note that if you want to build
both debug and release versions, you can select the “build all” option from the Build
menu.
11. Test the server. The server built using the preceding instructions will expect that
the MySQL base directory and data directory are ‘C:\mysql’ and ‘C:\mysql\data’ by
default. If you want to test your server using the source tree root directory and its
data directory as the base directory and data directory, you will need to tell the server
their pathnames. You can either do this on the command line with the --basedir
and --datadir options, or place appropriate options in an option file (‘C:\my.cnf’ or
104
MySQL Technical Reference for Version 4.1.1-alpha
the ‘my.ini’ file in your Windows directory). If you have an existing data directory
elsewhere that you want to use, you can specify its pathname instead.
12. Start your server from the ‘client_release’ or ‘client_debug’ directory, depending
on which server you want to use. The general server startup instructions are at Section 2.1.1 [Windows installation], page 57. You’ll need to to adapt the instructions
appropriately if you want to use a different base directory or data directory.
13. 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 that exists
in your ‘client_release’ or ‘client_debug’ directory.
When you are satisifed that the programs you have built are working correctly, stop the
server. Then install MySQL as follows:
1. Create the directories where you want to install MySQL. For example, to install into
‘C:\mysql’, use these commands:
C:
mkdir \mysql
mkdir \mysql\bin
mkdir \mysql\data
mkdir \mysql\share
mkdir \mysql\scripts
If you want to compile other clients and link them to MySQL, you should also create
several additional directories:
mkdir \mysql\include
mkdir \mysql\lib
mkdir \mysql\lib\debug
mkdir \mysql\lib\opt
If you want to benchmark MySQL, create this directory:
mkdir \mysql\sql-bench
Benchmarking requires Perl support.
2. From the ‘workdir’ directory, copy into the C:\mysql directory the following directories:
copy client_release\*.exe C:\mysql\bin
copy client_debug\mysqld.exe C:\mysql\bin\mysqld-debug.exe
xcopy scripts\*.* C:\mysql\scripts /E
xcopy share\*.* C:\mysql\share /E
If you want to compile other clients and link them to MySQL, you should also do this:
copy lib_debug\mysqlclient.lib C:\mysql\lib\debug
copy lib_debug\libmysql.* C:\mysql\lib\debug
copy lib_debug\zlib.* C:\mysql\lib\debug
copy lib_release\mysqlclient.lib C:\mysql\lib\opt
copy lib_release\libmysql.* C:\mysql\lib\opt
copy lib_release\zlib.* C:\mysql\lib\opt
copy include\*.h C:\mysql\include
copy libmysql\libmysql.def C:\mysql\include
If you want to benchmark MySQL, you should also do this:
Chapter 2: Installing MySQL
105
xcopy sql-bench\*.* C:\mysql\bench /E
Set up and start the server in the same way as for the binary Windows distribution. See
Section 2.1.1 [Windows installation], page 57.
2.3.7.2 Creating a Windows Source Package from the Latest
Development Source
To build the latest Windows source package from the current BitKeeper source tree, use
the following instructions. Please note that this procedure must be performed on a system
running a Unix or Unix-like operating system. (The procedure is known to work well on
Linux, for example.)
1. Clone the BitKeeper source tree for MySQL (version 4.1 or above, as desired). For
more information how to clone the source tree, see the instructions at Section 2.3.4
[Installing source tree], page 95.
2. Configure and build the distribution so that you have a server binary to work with.
One way to do this is to run the following command in the top-level directory of your
source tree:
shell> ./BUILD/compile-pentium-max
3. After making sure that the build process completed successfully, run the following
utility script from top-level directory of your source tree:
shell> ./scripts/make_win_src_distribution
This script creates a Windows source package, to be used on your Windows system.
You can supply different options to the script based on your needs. It accepts the
following options:
--debug
Debug, without creating the package
--tmp
Specify the temporary location
--suffix Suffix name for the package
--dirname Directory name to copy files (intermediate)
--silent Do not list verbosely files processed
--tar
Create tar.gz package instead of .zip
--help
Show this help message
By default, make_win_src_distribution creates a zipped archive with the name
‘mysql-VERSION-win-src.zip’, where VERSION represents the version of your MySQL
source tree.
4. Copy or upload to your Windows machine the Windows source package that you have
just created. To compile it, use the instructions in Section 2.3.7.1 [Windows VC++
Build], page 103.
2.4 Post-installation Setup and Testing
Once you’ve installed MySQL (from either a binary or source distribution), you need to
initialise the grant tables, start the server, and make sure that the server works okay. You
may also wish to arrange for the server to be started and stopped automatically when your
system starts up and shuts down.
106
MySQL Technical Reference for Version 4.1.1-alpha
Normally you install the grant tables and start the server like this for installation from a
source distribution:
shell> ./scripts/mysql_install_db
shell> cd mysql_installation_directory
shell> ./bin/mysqld_safe --user=mysql &
For a binary distribution (not RPM or pkg packages), do this:
shell> cd mysql_installation_directory
shell> ./scripts/mysql_install_db
shell> ./bin/mysqld_safe --user=mysql &
The mysql_install_db script creates the mysql database which will hold all database
privileges, the test database which you can use to test MySQL, and also privilege entries
for the user that runs mysql_install_db and a root user. The entries are created without
passwords. The mysqld_safe script starts the mysqld server. (If your version of MySQL
is older than 4.0, use safe_mysqld rather than mysqld_safe.)
mysql_install_db will not overwrite any old privilege tables, so it should be safe to run
in any circumstances. If you don’t want to have the test database you can remove it with
mysqladmin -u root drop test after starting the server.
Testing is most easily done from the top-level directory of the MySQL distribution.
For a binary distribution, this is your installation directory (typically something like
‘/usr/local/mysql’). For a source distribution, this is the main directory of your MySQL
source tree.
In the commands shown in this section and in the following subsections, BINDIR is the
path to the location in which programs like mysqladmin and mysqld_safe are installed.
For a binary distribution, this is the ‘bin’ directory within the distribution. For a source
distribution, BINDIR is probably ‘/usr/local/bin’, unless you specified an installation
directory other than ‘/usr/local’ when you ran configure. EXECDIR is the location in
which the mysqld server is installed. For a binary distribution, this is the same as BINDIR.
For a source distribution, EXECDIR is probably ‘/usr/local/libexec’.
Testing is described in detail:
1. If necessary, start the mysqld server and set up the initial MySQL grant tables containing the privileges that determine how users are allowed to connect to the server.
This is normally done with the mysql_install_db script:
shell> scripts/mysql_install_db
Typically, mysql_install_db needs to be run only the first time you install MySQL.
Therefore, if you are upgrading an existing installation, you can skip this step. (However, mysql_install_db is quite safe to use and will not update any tables that already
exist, so if you are unsure of what to do, you can always run mysql_install_db.)
mysql_install_db creates six tables (user, db, host, tables_priv, columns_priv,
and func) in the mysql database. A description of the initial privileges is given in
Section 4.4.4 [Default privileges], page 248. Briefly, these privileges allow the MySQL
root user to do anything, and allow anybody to create or use databases with a name
of test or starting with test_.
If you don’t set up the grant tables, the following error will appear in the log file when
you start the server:
Chapter 2: Installing MySQL
107
mysqld: Can’t find file: ’host.frm’
This may also happen with a binary MySQL distribution if you don’t start MySQL by
executing exactly ./bin/mysqld_safe. See Section 4.8.2 [mysqld_safe], page 315.
You might need to run mysql_install_db as root. However, if you prefer, you can
run the MySQL server as an unprivileged (non-root) user, provided that the user can
read and write files in the database directory. Instructions for running MySQL as an
unprivileged user are given in Section A.3.2 [Changing MySQL user], page 869.
If you have problems with mysql_install_db, see Section 2.4.1 [mysql_install_db],
page 109.
There are some alternatives to running the mysql_install_db script as it is provided
in the MySQL distribution:
• You may want to edit mysql_install_db before running it, to change the initial
privileges that are installed into the grant tables. This is useful if you want to
install MySQL on a lot of machines with the same privileges. In this case you
probably should need only to add a few extra INSERT statements to the mysql.user
and mysql.db tables.
• If you want to change the contents of the grant tables after installing them, you can
run mysql_install_db, then use mysql -u root mysql to connect to the grant
tables as the MySQL root user and issue SQL statements to modify the grant
tables directly.
• It is possible to re-create the grant tables completely after they have already been
created. You might want to do this if you’ve already installed the tables but then
want to re-create them after editing mysql_install_db.
For more information about these alternatives, see Section 4.4.4 [Default privileges],
page 248.
2. Start the MySQL server like this:
shell> cd mysql_installation_directory
shell> bin/mysqld_safe &
If your version of MySQL is older than 4.0, substitute bin/safe_mysqld for
bin/mysqld_safe in the final command.
If you have problems starting the server, see Section 2.4.2 [Starting server], page 111.
3. Use mysqladmin to verify that the server is running. The following commands provide
a simple test to check that the server is up and responding to connections:
shell> BINDIR/mysqladmin version
shell> BINDIR/mysqladmin variables
The output from mysqladmin version varies slightly depending on your platform and
version of MySQL, but should be similar to that shown here:
shell> BINDIR/mysqladmin version
mysqladmin Ver 8.14 Distrib 3.23.32, for linux on i586
Copyright (C) 2000 MySQL AB & MySQL Finland AB & TCX DataKonsult AB
This software comes with ABSOLUTELY NO WARRANTY. This is free software,
and you are welcome to modify and redistribute it under the GPL license.
108
MySQL Technical Reference for Version 4.1.1-alpha
Server version
Protocol version
Connection
TCP port
UNIX socket
Uptime:
3.23.32-debug
10
Localhost via Unix socket
3306
/tmp/mysql.sock
16 sec
Threads: 1 Questions: 9 Slow queries: 0
Opens: 7 Flush tables: 2 Open tables: 0
Queries per second avg: 0.000
Memory in use: 132K Max memory used: 16773K
To get a feeling for what else you can do with BINDIR/mysqladmin, invoke it with the
--help option.
4. Verify that you can shut down the server:
shell> BINDIR/mysqladmin -u root shutdown
5. Verify that you can restart the server. Do this using mysqld_safe or by invoking
mysqld directly. For example:
shell> BINDIR/mysqld_safe --log &
If mysqld_safe fails, try running it from the MySQL installation directory (if you are
not already there). If that doesn’t work, see Section 2.4.2 [Starting server], page 111.
6. Run some simple tests to verify that the server is working. The output should be
similar to what is shown here:
shell> BINDIR/mysqlshow
+-----------+
| Databases |
+-----------+
| mysql
|
+-----------+
shell> BINDIR/mysqlshow mysql
Database: mysql
+--------------+
|
Tables
|
+--------------+
| columns_priv |
| db
|
| func
|
| host
|
| tables_priv |
| user
|
+--------------+
shell> BINDIR/mysql -e "SELECT host,db,user FROM db" mysql
+------+--------+------+
| host | db
| user |
Chapter 2: Installing MySQL
109
+------+--------+------+
| %
| test
|
|
| %
| test_% |
|
+------+--------+------+
There is also 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, using the Perl DBI module to
provide a database-independent interface to the various databases. The following additional Perl modules are required to run the benchmark suite:
DBI
DBD-mysql
Data-Dumper
Data-ShowTable
These modules can be obtained from CPAN http://www.cpan.org/. See Section 2.7.1
[Perl installation], page 156.
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> run-all-tests
If you don’t have the ‘sql-bench’ directory, you are probably using an RPM for a binary
distribution. (Source distribution RPMs include the benchmark directory.) In this case,
you must first install the benchmark suite before you can use it. Beginning with MySQL
Version 3.22, there are benchmark RPM files named ‘mysql-bench-VERSION-i386.rpm’
that contain benchmark code and data.
If you have a source distribution, you can also run the tests in the ‘tests’ subdirectory.
For example, to run ‘auto_increment.tst’, do this:
shell> BINDIR/mysql -vvf test < ./tests/auto_increment.tst
The expected results are shown in the ‘./tests/auto_increment.res’ file.
2.4.1 Problems Running mysql_install_db
The purpose of the mysql_install_db script is to generate new MySQL privilege tables.
It will not affect any other data. It will also not do anything if you already have MySQL
privilege tables installed.
If you want to re-create your privilege tables, you should take down the mysqld server, if
it’s running, and then do something like:
mv mysql-data-directory/mysql mysql-data-directory/mysql-old
mysql_install_db
This section lists problems you might encounter when you run mysql_install_db:
mysql_install_db doesn’t 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
110
MySQL Technical Reference for Version 4.1.1-alpha
mysql daemon ended
In this case, you should examine the log file very carefully. The log should
be located in the directory ‘XXXXXX’ named by the error message, and should
indicate why mysqld didn’t start. If you don’t understand what happened,
include the log when you post a bug report using mysqlbug. See Section 1.7.1.3
[Bug reports], page 34.
There is already a mysqld daemon running
In this case, you probably don’t have to run mysql_install_db at all. You
have to run mysql_install_db only once, when you install MySQL the first
time.
Installing a second mysqld daemon doesn’t work when one daemon is running
This can happen when you already have an existing MySQL installation, but
want to put a new installation in a different place (for example, for testing,
or perhaps you simply want to run two installations at the same time). Generally the problem that occurs when you try to run the second server is that
it tries to use the same socket and port as the old one. In this case you will
get the error message: Can’t start server: Bind on TCP/IP port: Address
already in use or Can’t start server: Bind on unix socket.... See Section 4.2 [Multiple servers], page 209.
You don’t have write access to ‘/tmp’
If you don’t have write access to create a socket file at the default place (in
‘/tmp’) or permission to create temporary files in ‘/tmp,’ you will get an error
when running mysql_install_db or when starting or using mysqld.
You can specify a different socket and temporary directory as follows:
shell> TMPDIR=/some_tmp_dir/
shell> MYSQL_UNIX_PORT=/some_tmp_dir/mysqld.sock
shell> export TMPDIR MYSQL_UNIX_PORT
See Section A.4.5 [Problems with mysql.sock], page 874.
‘some_tmp_dir’ should be the path to some directory for which you have write
permission. See Appendix F [Environment variables], page 1032.
After this you should be able to run mysql_install_db and start the server
with these commands:
shell> scripts/mysql_install_db
shell> BINDIR/mysqld_safe &
mysqld crashes immediately
If you are running Red Hat Version 5.0 with a version of glibc older than
2.0.7-5, you should make sure you have installed all glibc patches. There
is a lot of information about this in the MySQL mail archives. Links to the
mail archives are available online at http://lists.mysql.com/. Also, see Section 2.6.2 [Linux], page 129.
You can also start mysqld manually using the --skip-grant-tables option
and add the privilege information yourself using mysql:
shell> BINDIR/mysqld_safe --skip-grant-tables &
Chapter 2: Installing MySQL
111
shell> BINDIR/mysql -u root mysql
From mysql, manually execute the SQL commands in mysql_install_db.
Make sure you run mysqladmin flush-privileges or mysqladmin reload afterward to tell the server to reload the grant tables.
2.4.2 Problems Starting the MySQL Server
If you are going to use tables that support transactions (InnoDB, BDB), you should first
create a ‘my.cnf’ file and set startup options for the table types you plan to use. See
Chapter 7 [Table types], page 600.
Generally, you start the mysqld server in one of these ways:
• By invoking mysql.server. This script is used primarily at system startup and shutdown, and is described more fully in Section 2.4.3 [Automatic start], page 113.
• By invoking mysqld_safe, which tries to determine the proper options for mysqld and
then runs it with those options. See Section 4.8.2 [mysqld_safe], page 315.
• For Windows NT/2000/XP, please see Section 2.1.1.7 [NT start], page 62.
• By invoking mysqld directly.
When the mysqld daemon starts up, it changes the directory to the data directory. This is
where it expects to write log files and the pid (process ID) file, and where it expects to find
databases.
The data directory location is hardwired in when the distribution is compiled. However, if
mysqld expects to find the data directory somewhere other than where it really is on your
system, it will not work properly. If you have problems with incorrect paths, you can find
out what options mysqld allows and what the default path settings are by invoking mysqld
with the --help option. You can override the defaults by specifying the correct pathnames
as command-line arguments to mysqld. (These options can be used with mysqld_safe as
well.)
Normally you should need to tell mysqld only the base directory under which MySQL is
installed. You can do this with the --basedir option. You can also use --help to check the
effect of changing path options (note that --help must be the final option of the mysqld
command). For example:
shell> EXECDIR/mysqld --basedir=/usr/local --help
Once you determine the path settings you want, start the server without the --help option.
Whichever method you use to start the server, if it fails to start up correctly, check the
log file to see if you can find out why. Log files are located in the data directory (typically ‘/usr/local/mysql/data’ for a binary distribution, ‘/usr/local/var’ for a source
distribution, and ‘\mysql\data\mysql.err’ on Windows). 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 check the last few lines of these files:
shell> tail host_name.err
shell> tail host_name.log
Look for something like the following in the log file:
112
MySQL Technical Reference for Version 4.1.1-alpha
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 didn’t start mysqld with --bdb-no-recover and Berkeley DB found
something wrong with its log files when it tried to recover your databases. To be able to
continue, you should move away the old Berkeley DB log file from the database directory to
some other place, where you can later examine it. The log files are named ‘log.0000000001’,
where the number will increase over time.
If you are running mysqld with BDB table support and mysqld core dumps at start this
could be because of some problems with the BDB recover log. In this case you can try
starting mysqld with --bdb-no-recover. If this helps, then you should remove all ‘log.*’
files from the data directory and try starting mysqld again.
If you get the following error, it means that some other program (or another mysqld server)
is already using the TCP/IP port or socket mysqld is trying to use:
Can’t start server: Bind on TCP/IP port: Address already in use
or
Can’t start server: Bind on unix socket...
Use ps to make sure that you don’t have another mysqld server running. If you can’t
find another server running, you can try to execute the command telnet your-host-name
tcp-ip-port-number and press Enter a couple of times. If you don’t get an error message
like telnet: Unable to connect to remote host: Connection refused, something is using the TCP/IP port mysqld is trying to use. See Section 2.4.1 [mysql install db], page 109
and Section 4.2 [Multiple servers], page 209.
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 ’your-host-name’ variables
If you get Errcode 13, which means Permission denied, when starting mysqld this means
that you didn’t have the right to read/create files in the MySQL database or log directory.
In this case you should either start mysqld as the root user or change the permissions for
the involved files and directories so that you have the right to use them.
If mysqld_safe starts the server but you can’t connect to it, you should make sure you
have an entry in ‘/etc/hosts’ that looks like this:
127.0.0.1
localhost
This problem occurs only on systems that don’t have a working thread library and for which
MySQL must be configured to use MIT-pthreads.
If you can’t get mysqld to start you can try to make a trace file to find the problem. See
Section E.1.2 [Making trace files], page 1021.
If you are using InnoDB tables, refer to the InnoDB-specific startup options. See Section 7.5.3 [InnoDB start], page 613.
If you are using BDB (Berkeley DB) tables, you should familiarise yourself with the different
BDB-specific startup options. See Section 7.6.3 [BDB start], page 664.
Chapter 2: Installing MySQL
113
2.4.3 Starting and Stopping MySQL Automatically
The mysql.server and mysqld_safe scripts can be used to start the server automatically
at system startup time. mysql.server can also be used to stop the server.
The mysql.server script can be used to start or stop the server by invoking it with start
or stop arguments:
shell> mysql.server start
shell> mysql.server stop
mysql.server can be found in the ‘share/mysql’ directory under the MySQL installation
directory or in the ‘support-files’ directory of the MySQL source tree.
Note that if you use the Linux RPM package (MySQL-server-VERSION.rpm), the
mysql.server script has already been installed as ‘/etc/init.d/mysql’ - you don’t have
to install it manually. See Section 2.1.2 [Linux-RPM], page 66 for more information on the
Linux RPM packages.
On Mac OS X, you can install a separate MySQL Startup Item package to enable the
automatic startup of MySQL on system bootup. See Section 2.1.3 [Mac OS X installation],
page 68 for details.
Before mysql.server starts the server, it changes the directory to the MySQL installation
directory, then invokes mysqld_safe. You might need to edit mysql.server if you have a
binary distribution that you’ve installed in a non-standard location. Modify it to cd into
the proper directory before it runs mysqld_safe. If you want the server to run as some
specific user, add an appropriate user line to the ‘/etc/my.cnf’ file, as shown later in this
section.
mysql.server stop brings down the server by sending a signal to it. You can also take
down the server manually by executing mysqladmin shutdown.
You need to add these start and stop commands to the appropriate places in your ‘/etc/rc*’
files when you want to start up MySQL automatically on your server.
On most current Linux distributions, it is sufficient to copy the file mysql.server into the
‘/etc/init.d’ directory (or ‘/etc/rc.d/init.d’ on older Red Hat systems). Afterwards,
run the following command to enable the startup of MySQL on system bootup:
shell> chkconfig --add mysql.server
On FreeBSD startup scripts generally should go in ‘/usr/local/etc/rc.d/’. The rc(8)
manual page also states that scripts in this directory are only executed, if their basename
matches the shell globbing pattern *.sh. Any other files or directories present within
the directory are silently ignored. In other words, on FreeBSD you should install the file
‘mysql.server’ as ‘/usr/local/etc/rc.d/mysql.server.sh’ to enable automatic startup.
As an alternative to the above, some operating systems also use ‘/etc/rc.local’ or
‘/etc/init.d/boot.local’ to start additional services on bootup. To start up MySQL
using this method, you could append something like the following to it:
/bin/sh -c ’cd /usr/local/mysql; ./bin/mysqld_safe --user=mysql &’
You can also add options for mysql.server in a global ‘/etc/my.cnf’ file. A typical
‘/etc/my.cnf’ file might look like this:
114
MySQL Technical Reference for Version 4.1.1-alpha
[mysqld]
datadir=/usr/local/mysql/var
socket=/var/tmp/mysql.sock
port=3306
user=mysql
[mysql.server]
basedir=/usr/local/mysql
The mysql.server script understands the following options: datadir, basedir, and pidfile.
The following table shows which option groups each startup script reads from option files:
Script
Option groups
mysqld
[mysqld], [server] and [mysqld-major-version]
mysql.server [mysql.server], [mysqld], and [server]
mysqld_safe [mysqld], [server], and [mysqld_safe]
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.
See Section 4.1.2 [Option files], page 206.
2.5 Upgrading/Downgrading MySQL
Before you do an upgrade, you should back up your old databases.
You can always move the MySQL format files and datafiles between different versions on
the same architecture as long as you have the same base version of MySQL. The current
base version is 4. If you change the character set when running MySQL, you must run
myisamchk -r -q --set-character-set=charset on all tables. Otherwise, your indexes
may not be ordered correctly, because changing the character set may also change the sort
order.
If you are afraid of new versions, you can always rename your old mysqld to something like
mysqld-old-version-number. If your new mysqld then does something unexpected, you
can simply shut it down and restart with your old mysqld.
If, after an upgrade, you experience problems with recompiled client programs, such as
Commands out of sync or unexpected core dumps, you probably have used an old header
or library file when compiling your programs. In this case you should check the date for
your ‘mysql.h’ file and ‘libmysqlclient.a’ library to verify that they are from the new
MySQL distribution. If not, please recompile your programs.
If problems occur, such as that the new mysqld server doesn’t want to start or that you
can’t connect without a password, check that you don’t have some old ‘my.cnf’ file from
your old installation. You can check this with: program-name --print-defaults. If this
outputs anything other than the program name, you have an active ‘my.cnf’ file that affects
server operation.
It is a good idea to rebuild and reinstall the Perl DBD-mysql module whenever you install
a new release of MySQL. The same applies to other MySQL interfaces as well, such as the
Python MySQLdb module.
Chapter 2: Installing MySQL
115
2.5.1 Upgrading From Version 4.0 to 4.1
Several visible behaviours have changed between MySQL 4.0 and MySQL 4.1 to fix some
critical bugs and make MySQL more compatible with the ANSI SQL standard. These
changes may affect your applications.
Some of the 4.1 behaviours can be tested in 4.0 before performing a full upgrade to 4.1.
We have added to later MySQL 4.0 releases (from 4.0.12 on) a --new startup option for
mysqld.
This option gives you the 4.1 behaviour for the most critical changes. You can also enable
these behaviours for a given client connection with the SET @@new=1 command, or turn
them off if they are on with SET @@new=0.
If you believe that some of the 4.1 changes will affect you, we recommend that before
upgrading to 4.1, you download the latest MySQL 4.0 version and run it with the --new
option by adding the following to your config file:
[mysqld-4.0]
new
That way you can test the new behaviors in 4.0 to make sure that your applications work
with them. This will help you have a smooth painless transition when you perform a full
upgrade to 4.1 later. Doing it the above way will ensure that you don’t accidently later run
the 4.1 version with the --new option.
The following list describes changes that may affect applications and that you should watch
out for when upgrading to version 4.1:
• TIMESTAMP is now returned as a string in ’YYYY-MM-DD HH:MM:SS’ format. (The --new
option can be used from 4.0.12 on to make a 4.0 server behave as 4.1 in this respect.)
If you want to have the value returned as a number (like Version 4.0 does) you should
add +0 to TIMESTAMP columns when you retrieve them:
mysql> SELECT ts_col + 0 FROM tbl_name;
Display widths for TIMESTAMP columns are no longer supported. For example, if you
declare a column as TIMESTAMP(10), the (10) is ignored.
These changes were necessary for SQL standards compliance. In a future version, a
further change will be made (backward compatible with this change), allowing the
timestamp length to indicate the desired number of digits for fractions of a second.
• Binary values such as 0xFFDF now are assumed to be strings instead of numbers. This
fixes some problems with character sets where it’s convenient to input a string as a
binary value. With this change, you should use CAST() if you want to compare binary
values numerically as integers:
mysql> SELECT CAST(0xFEFF AS UNSIGNED INTEGER) < CAST(0xFF AS UNSIGNED INTEGER);
-> 0
If you don’t use CAST(), a lexical string comparison will be done:
mysql> SELECT 0xFEFF < 0xFF;
-> 1
Using binary items in a numeric context or comparing them using the = operator should
work as before. (The --new option can be used from 4.0.13 on to make a 4.0 server
behave as 4.1 in this respect.)
116
MySQL Technical Reference for Version 4.1.1-alpha
• For functions that produce a DATE, DATETIME, or TIME value, the result returned to the
client now is fixed up to have a temporal type. For example, in MySQL 4.1, you get
this result:
mysql> SELECT CAST("2001-1-1" as DATETIME);
-> ’2001-01-01 00:00:00’
In MySQL 4.0, the result is different:
mysql> SELECT CAST("2001-1-1" as DATETIME);
-> ’2001-01-01’
• DEFAULT values no longer can be specified for AUTO_INCREMENT columns. (In 4.0, a
DEFAULT value is silently ignored; in 4.1, an error occurs).
• LIMIT no longer accept negative arguments. Use 18446744073709551615 instead of -1.
• SERIALIZE is no longer a valid option value for the sql_mode variable.
You should use SET TRANSACTION ISOLATION LEVEL SERIALIZABLE instead.
SERIALIZE is no longer valid for the --sql-mode option for mysqld, either. Use
--transaction-isolation=SERIALIZABLE instead.
• All tables and string columns now have a character set. See Chapter 9 [Charset],
page 674.
Character set information is displayed by SHOW CREATE TABLE and
mysqldump. (MySQL versions 4.0.6 and above can read the new dump files; older
versions cannot.)
• The table definition format used in ‘.frm’ files has changed slightly in 4.1. MySQL
4.0 versions from 4.0.11 on can read the new ‘.frm’ format directly, but older versions
cannot. If you need to move tables from 4.1 to a version earlier than 4.0.11, you should
use mysqldump. See Section 4.9.7 [mysqldump], page 344.
• If you are running multiple servers on the same Windows machine, you should use a
different --shared_memory_base_name option on all machines.
• The interface to aggregated UDF functions has changed a bit. You must now declare
a xxx_clear() function for each aggregate function XXX().
In general, upgrading to 4.1 from an earlier MySQL version involves the following steps:
• Check the changes listed earlier in this section to see if there are any that may affect
your applications.
• Read the 4.1 news items to see what significant new features you can use in 4.1. See
Section D.2 [News-4.1.x], page 900.
• If you are running MySQL Server on Windows, please also see Section 2.5.8 [Windows
upgrading], page 125.
• After upgrading, update the grant tables to generate the new longer Password column
that is needed for secure handling of passwords. The procedure uses mysql_fix_
privilege_tables and is described in Section 2.5.6 [Upgrading-grant-tables], page 123.
The password hashing mechanism has changed in 4.1 to provide better security, but this
may cause compatibility problems if you still have clients that use the client library from
4.0 or earlier. (It is very likely that you will have 4.0 clients in situations where clients
connect from remote hosts that have not yet upgraded to 4.1). The following list indicates
some possible upgrade strategies. They represent various tradeoffs between the goal of
compatibility with old clients and the goal of security.
Chapter 2: Installing MySQL
117
• Don’t upgrade to 4.1. No behaviour will change, but of course you cannot use any of
the new features provided by the 4.1 client/server protocol, either. (MySQL 4.1 has
an extended client/server protocol that offers such features as prepared statements and
multiple result sets.) See Section 11.1.4 [C API Prepared statements], page 776.
• Upgrade to 4.1 and run the mysql_fix_privilege_tables script to widen the
Password column in the user table so that it can hold long password hashes. But run
the server with the --old-passwords option to provide backward compatibility that
allows pre-4.1 clients to continue to connect to their short-hash accounts. Eventually,
when all your clients are upgraded to 4.1, you can stop using the --old-passwords
server option. You can also change the passwords for your MySQL accounts to use
the new more secure format.
• Upgrade to 4.1 and run the mysql_fix_privilege_tables script to widen the
Password column in the user table. If you know that all clients also have been
upgraded to 4.1, don’t run the server with the --old-passwords option. Instead,
change the passwords on all existing accounts so that they have the new format. A
pure-4.1 installation is the most secure.
Further background on password hashing with respect to client authentication and
password-changing operations may be found in Section 4.3.11 [Password hashing],
page 234.
2.5.2 Upgrading From Version 3.23 to 4.0
In general, you should do the following when upgrading to 4.0 from an earlier MySQL
version:
• After upgrading, update the grant tables to add new privileges and features. The procedure uses the mysql_fix_privilege_tables script and is described in Section 2.5.6
[Upgrading-grant-tables], page 123.
• Edit any MySQL startup scripts or configure files to not use any of the deprecated
options described later in this section.
• Convert your old ISAM files to MyISAM files with the mysql_convert_table_format
database script. (This is a Perl script; it requires that DBI be installed.) To convert
the tables in a given database, use this command:
shell> mysql_convert_table_format database db_name
Note that this should only be used if all tables in the given database are ISAM or MyISAM
tables. To avoid converting tables of other types to MyISAM, you can explicitly list the
names of your ISAM tables after the database name on the command line. You can
also issue a ALTER TABLE table_name TYPE=MyISAM statement for each ISAM table to
convert it to MyISAM.
To find out the table type for a given table, use this statement:
mysql> SHOW TABLE STATUS LIKE ’tbl_name’;
• Ensure that you don’t have any MySQL clients that use shared libraries (like the Perl
DBD-mysql mode). If you do, you should recompile them, because the data structures used in ‘libmysqlclient.so’ have changed. The same applies to other MySQL
interfaces as well, such as the Python MySQLdb module.
118
MySQL Technical Reference for Version 4.1.1-alpha
MySQL 4.0 will work even if you don’t do the above, but you will not be able to use the new
security privileges that MySQL 4.0 and you may run into problems when upgrading later
to MySQL 4.1 or newer. The ISAM file format still works in MySQL 4.0 but it’s deprecated
and will be disabled (not compiled in by default) in MySQL 4.1. MyISAM tables should be
used instead.
Old clients should work with a Version 4.0 server without any problems.
Even if you do the above, you can still downgrade to MySQL 3.23.52 or newer if you run
into problems with the MySQL 4.0 series. In this case, you must use mysqldump to dump
any tables that use full-text indexes and reload the dump file into the 3.23 server. This is
necessary because 4.0 uses a new format for full-text indexing.
The following is a more complete list that tells what you must watch out for when upgrading
to version 4.0:
• MySQL 4.0 has a lot of new privileges in the mysql.user table. See Section 4.4.1
[GRANT], page 242.
To get these new privileges to work, you must update the grant tables. The procedure is described in Section 2.5.6 [Upgrading-grant-tables], page 123. Until you do
this, all users have the SHOW DATABASES, CREATE TEMPORARY TABLES, and LOCK TABLES
privileges. SUPER and EXECUTE privileges take their value from PROCESS. REPLICATION
SLAVE and REPLICATION CLIENT take their values from FILE.
If you have any scripts that create new users, you may want to change them to use the
new privileges. If you are not using GRANT commands in the scripts, this is a good time
to change your scripts to use GRANT instead of modifying the grant tables directly..
From version 4.0.2 on, the option --safe-show-database is deprecated (and no longer
does anything). See Section 4.3.3 [Privileges options], page 220.
If you get Access denied errors for new users in version 4.0.2 and up, you should check
if you need some of the new grants that you didn’t need before. In particular, you will
need REPLICATION SLAVE (instead of FILE) for new slaves.
• ‘safe_mysqld’ is renamed to ‘mysqld_safe’. For backward compatibility, binary distributions will for some time include safe_mysqld as a symlink to mysqld_safe.
• InnoDB support is now included by default in binary distributions. If you build MySQL
from source, InnoDB is configured in by default. If you do not use InnoDB and want
to save memory when running a server that has InnoDB support enabled, use the -skip-innodb server startup option. To compile MySQL without InnoDB support, run
configure with the --without-innodb option.
• The startup parameters myisam_max_extra_sort_file_size and myisam_max_
extra_sort_file_size are now given in bytes (they were given in megabytes before
4.0.3).
• External system locking of MyISAM/ISAM files is now turned off by default. Your can
turn this on by doing --external-locking. (However, this is never needed for most
users.)
• The following startup variables/options have been renamed:
Old Name
New Name
myisam_bulk_insert_tree_size
bulk_insert_buffer_size
query_cache_startup_type
query_cache_type
Chapter 2: Installing MySQL
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
119
record_buffer
read_buffer_size
record_rnd_buffer
read_rnd_buffer_size
sort_buffer
sort_buffer_size
warnings
log-warnings
--err-log
--log-error (for mysqld_safe)
The startup options record_buffer, sort_buffer and warnings will still work in
MySQL 4.0 but are deprecated.
The following SQL variables have changed name.
Old Name
New Name
SQL_BIG_TABLES
BIG_TABLES
SQL_LOW_PRIORITY_UPDATES
LOW_PRIORITY_UPDATES
SQL_MAX_JOIN_SIZE
MAX_JOIN_SIZE
SQL_QUERY_CACHE_TYPE
QUERY_CACHE_TYPE
The old names still work in MySQL 4.0 but are deprecated.
You have to use SET GLOBAL SQL_SLAVE_SKIP_COUNTER=# instead of SET SQL_SLAVE_
SKIP_COUNTER=#.
The mysqld startup options --skip-locking and --enable-locking were renamed
to --skip-external-locking and --external-locking.
SHOW MASTER STATUS now returns an empty set if binary logging is not enabled.
SHOW SLAVE STATUS now returns an empty set if slave is not initialised.
mysqld now has the option --temp-pool enabled by default as this gives better performance with some operating systems (most notably Linux).
DOUBLE and FLOAT columns now honour the UNSIGNED flag on storage (before, UNSIGNED
was ignored for these columns).
ORDER BY col_name DESC sorts NULL values last, as of MySQL 4.0.11. In 3.23 and in
earlier 4.0 versions, this was not always consistent.
SHOW INDEX has two more columns (Null and Index_type) than it had in 3.23.
CHECK, LOCALTIME and LOCALTIMESTAMP are now reserved words.
The result of all bitwise operators (|, &, <<, >>, and ~)) is now unsigned. This may
cause problems if you are using them in a context where you want a signed result. See
Section 6.3.5 [Cast Functions], page 518.
Note: when you use subtraction between integer values where one is of type UNSIGNED,
the result will be unsigned. In other words, before upgrading to MySQL 4.0, you
should check your application for cases where you are subtracting a value from an
unsigned entity and want a negative answer or subtracting an unsigned value from
an integer column. You can disable this behaviour by using the --sql-mode=NO_
UNSIGNED_SUBTRACTION option when starting mysqld. See Section 6.3.5 [Cast Functions], page 518.
To use MATCH ... AGAINST (... IN BOOLEAN MODE) with your tables, you need to rebuild them with REPAIR TABLE table_name USE_FRM.
LOCATE() and INSTR() are case-sensitive if one of the arguments is a binary string.
Otherwise they are case-insensitive.
STRCMP() now uses the current character set when doing comparisons, which means
that the default comparison behaviour now is case-insensitive.
120
MySQL Technical Reference for Version 4.1.1-alpha
• HEX(string) now returns the characters in string converted to hexadecimal. If you
want to convert a number to hexadecimal, you should ensure that you call HEX() with
a numeric argument.
• In 3.23, INSERT INTO ... SELECT always had IGNORE enabled. In 4.0.1, MySQL will
stop (and possibly roll back) by default in case of an error unless you specify IGNORE.
• The old C API functions mysql_drop_db(), mysql_create_db(), and
mysql_connect() are no longer supported unless you compile MySQL with
CFLAGS=-DUSE_OLD_FUNCTIONS. However, it is preferable to change client programs
to use the new 4.0 API instead.
• In the MYSQL_FIELD structure, length and max_length have changed from unsigned
int to unsigned long. This should not cause any problems, except that they may
generate warning messages when used as arguments in the printf() class of functions.
• You should use TRUNCATE TABLE when you want to delete all rows from a table and you
don’t need to obtain a count of the number of rows that were deleted. (DELETE FROM
table_name returns a row count in 4.0, and TRUNCATE TABLE is faster.)
• You will get an error if you have an active LOCK TABLES or transaction when trying to
execute TRUNCATE TABLE or DROP DATABASE.
• You should use integers to store values in BIGINT columns (instead of using strings,
as you did in MySQL 3.23). Using strings will still work, but using integers is more
efficient.
• The format of SHOW OPEN TABLES has changed.
• Multi-threaded clients should use mysql_thread_init() and mysql_thread_end().
See Section 11.1.14 [Threaded clients], page 810.
• If you want to recompile the Perl DBD::mysql module, you must get DBD-mysql version
1.2218 or newer because older DBD modules used the deprecated mysql_drop_db()
call. Version 2.1022 or newer is recommended.
• RAND(seed) returns a different random number series in 4.0 than in 3.23; this was done
to further differentiate RAND(seed) and RAND(seed+1).
• The default type returned by IFNULL(A,B) is now set to be the more ’general’ of the
types of A and B. (The general-to-specific order is string, REAL or INTEGER).
If you are running MySQL Server on Windows, please also see Section 2.5.8 [Windows
upgrading], page 125. If you are using replication, please also see Section 4.11.2 [Replication
Implementation], page 360.
2.5.3 Upgrading From Version 3.22 to 3.23
MySQL Version 3.23 supports tables of the new MyISAM type and the old ISAM type. You
don’t have to convert your old tables to use these with Version 3.23. By default, all new
tables will be created with type MyISAM (unless you start mysqld with the --defaulttable-type=isam option). You can convert an ISAM table to MyISAM format with ALTER
TABLE table_name TYPE=MyISAM or the Perl script mysql_convert_table_format.
Version 3.22 and 3.21 clients will work without any problems with a Version 3.23 server.
The following list tells what you have to watch out for when upgrading to Version 3.23:
Chapter 2: Installing MySQL
121
• All tables that use the tis620 character set must be fixed with myisamchk -r or REPAIR
TABLE.
• If you do a DROP DATABASE on a symbolically linked database, both the link and the
original database are deleted. (This didn’t happen in 3.22 because configure didn’t
detect the availability of the readlink() system call.)
• OPTIMIZE TABLE now works only for MyISAM tables. For other table types, you can use
ALTER TABLE to optimise the table. During OPTIMIZE TABLE, the table is now locked
to prevent it from being used by other threads.
• The MySQL client mysql is now by default started with the option --no-namedcommands (-g). This option can be disabled with --enable-named-commands (-G).
This may cause incompatibility problems in some cases—for example, in SQL scripts
that use named commands without a semicolon. Long format commands still work
from the first line.
• Date functions that work on parts of dates (like MONTH()) will now return 0 for 000000-00 dates. (In MySQL 3.22, these functions returned NULL.)
• If you are using the german character sort order for ISAM tables, you must repair them
with isamchk -r, because we have made some changes in the sort order.
• The default return type of IF() now depends on both arguments and not only the first
argument.
• AUTO_INCREMENT columns should not be used to store negative numbers. The reason for
this is that negative numbers caused problems when wrapping from -1 to 0. You should
not store 0 in AUTO_INCREMENT columns, either; CHECK TABLE will complain about 0
values because they may change if you dump and restore the table. AUTO_INCREMENT
for MyISAM tables is now handled at a lower level and is much faster than before. In
addition, for MyISAM tables, old numbers are no longer reused, even if you delete rows
from the table.
• CASE, DELAYED, ELSE, END, FULLTEXT, INNER, RIGHT, THEN, and WHEN are now reserved
words.
• FLOAT(X) is now a true floating-point type and not a value with a fixed number of
decimals.
• When declaring columns using a DECIMAL(length,dec) type, the length argument no
longer includes a place for the sign or the decimal point.
• A TIME string must now be of one of the following formats:
[H]H:]MM:]SS[.fraction] or [[[[[H]H]H]H]MM]SS[.fraction].
[[[DAYS]
• LIKE now compares strings using the same character comparison rules as for the = operator. If you require the old behaviour, you can compile MySQL with the CXXFLAGS=DLIKE_CMP_TOUPPER flag.
• REGEXP is now case-insensitive if neither of the strings are binary strings.
• When you check or repair MyISAM (‘.MYI’) tables, you should use the CHECK TABLE
statement or the myisamchk command. For ISAM (‘.ISM’) tables, use the isamchk
command.
• If you want your mysqldump files to be compatible between MySQL Version 3.22 and
Version 3.23, you should not use the --opt or --all option to mysqldump.
122
MySQL Technical Reference for Version 4.1.1-alpha
• Check all your calls to DATE_FORMAT() to make sure there is a ‘%’ before each format
character. (MySQL Version 3.22 and later already allowed this syntax.)
• mysql_fetch_fields_direct() is now a function (it used to be a macro) and it returns
a pointer to a MYSQL_FIELD instead of a MYSQL_FIELD.
• mysql_num_fields() can no longer be used on a MYSQL* object (it’s now a function
that takes a MYSQL_RES* value as an argument). With a MYSQL* object, you should
now use mysql_field_count() instead.
• In MySQL Version 3.22, the output of SELECT DISTINCT ... was almost always sorted.
In Version 3.23, you must use GROUP BY or ORDER BY to obtain sorted output.
• SUM() now returns NULL instead of 0 if there are no matching rows. This is required
by SQL-99.
• An AND or OR with NULL values will now return NULL instead of 0. This mostly affects
queries that use NOT on an AND/OR expression as NOT NULL = NULL.
• LPAD() and RPAD() now shorten the result string if it’s longer than the length argument.
2.5.4 Upgrading from Version 3.21 to 3.22
Nothing that affects compatibility has changed between versions 3.21 and 3.22. The only
pitfall is that new tables that are created with DATE type columns will use the new way to
store the date. You can’t access these new columns from an old version of mysqld.
After installing MySQL Version 3.22, you should start the new server and then run the
mysql_fix_privilege_tables script. This will add the new privileges that you need to
use the GRANT command. If you forget this, you will get Access denied when you try to use
ALTER TABLE, CREATE INDEX, or DROP INDEX. The procedure for updating the grant tables
is described in Section 2.5.6 [Upgrading-grant-tables], page 123.
The C API interface to mysql_real_connect() has changed. If you have an old client
program that calls this function, you must place a 0 for the new db argument (or recode
the client to send the db element for faster connections). You must also call mysql_init()
before calling mysql_real_connect(). This change was done to allow the new mysql_
options() function to save options in the MYSQL handler structure.
The mysqld variable key_buffer has been renamed to key_buffer_size, but you can still
use the old name in your startup files.
2.5.5 Upgrading from Version 3.20 to 3.21
If you are running a version older than Version 3.20.28 and want to switch to Version 3.21,
you need to do the following:
You can start the mysqld Version 3.21 server with the --old-protocol option to use it with
clients from a Version 3.20 distribution. In this case, the new client function mysql_errno()
will not return any server error, only CR_UNKNOWN_ERROR (but it works for client errors),
and the server uses the old pre-3.21 password() checking rather than the new method.
If you are not using the --old-protocol option to mysqld, you will need to make the
following changes:
Chapter 2: Installing MySQL
123
• All client code must be recompiled. If you are using ODBC, you must get the new
MyODBC 2.x driver.
• The script scripts/add_long_password must be run to convert the Password field in
the mysql.user table to CHAR(16).
• All passwords must be reassigned in the mysql.user table (to get 62-bit rather than
31-bit passwords).
• The table format hasn’t changed, so you don’t have to convert any tables.
MySQL Version 3.20.28 and above can handle the new user table format without affecting
clients. If you have a MySQL version earlier than Version 3.20.28, passwords will no longer
work with it if you convert the user table. So to be safe, you should first upgrade to at
least Version 3.20.28 and then upgrade to Version 3.21.
The new client code works with a 3.20.x mysqld server, so if you experience problems with
3.21.x, you can use the old 3.20.x server without having to recompile the clients again.
If you are not using the --old-protocol option to mysqld, old clients will be unable to
connect and will issue the following error message:
ERROR: Protocol mismatch. Server Version = 10 Client Version = 9
The new Perl DBI/DBD interface also supports the old mysqlperl interface. The only change
you have to make if you use mysqlperl is to change the arguments to the connect()
function. The new arguments are: host, database, user, and password (note that the
user and password arguments have changed places). See Section 11.5.2 [Perl DBI Class],
page 828.
The following changes may affect queries in old applications:
• HAVING must now be specified before any ORDER BY clause.
• The parameters to LOCATE() have been swapped.
• There are some new reserved words. The most notable are DATE, TIME, and TIMESTAMP.
2.5.6 Upgrading the Grant Tables
Some releases introduce changes to the structure of the grant tables (the tables in the mysql
database) to add new privileges or features. To make sure that your grant tables are current
when you update to a new version of MySQL, you should update your grant tables as well.
On Unix or Unix-like systems, update the grant tables by running the mysql_fix_
privilege_tables script:
shell> mysql_fix_privilege_tables
You must run this script while the server is running. It attempts to connect to the server
running on the local host as root. If your root account requires a password, indicate the
password on the command line. For MySQL 4.1 and up, specify the password like this:
shell> mysql_fix_privilege_tables --password=root_password
Prior to MySQL 4.1, specify the password like this:
shell> mysql_fix_privilege_tables root_password
The mysql_fix_privilege_tables script performs any actions necessary to convert your
grant tables to the current format. You may see some Duplicate column name warnings as
it runs; they can be ignored.
124
MySQL Technical Reference for Version 4.1.1-alpha
After running the script, stop the server and restart it.
On Windows systems, there isn’t an easy way to update the grant tables until MySQL 4.0.15.
From version 4.0.15 on, MySQL distributions include a mysql_fix_privilege_tables.sql
SQL script that you can run using the mysql client. If your MySQL installation is located
at ‘C:\mysql’, the commands look like this:
C:\mysql\bin> mysql -u root -p mysql
mysql> SOURCE C:\mysql\scripts\mysql_fix_privilege_tables.sql
If your installation is located in some other directory, adjust the pathnames appropriately.
The command will prompt you for the root password; enter it when prompted.
As with the Unix procedure, you may see some Duplicate column name warnings as mysql
processes the statements in the mysql_fix_privilege_tables.sql script; they can be
ignored.
After running the script, stop the server and restart it.
2.5.7 Upgrading to Another Architecture
If you are using MySQL Version 3.23, 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 7.1 [MyISAM Tables], page 601.
The MySQL ISAM data and index files (‘.ISD’ and ‘*.ISM’, respectively) are architecturedependent and in some cases OS-dependent. If you want to move your applications to
another machine that has a different architecture or OS than your current machine, you
should not try to move a database by simply copying the files to the other machine. Use
mysqldump instead.
By default, mysqldump will 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.
Try mysqldump --help to see what options are available. If you are moving the data to a
newer version of MySQL, you should use mysqldump --opt with the newer version to get a
fast, compact dump.
The easiest (although not the fastest) way to move a database between two machines is to
run the following commands on the machine on which the database is located:
shell> mysqladmin -h ’other hostname’ create db_name
shell> mysqldump --opt db_name \
| mysql -h ’other hostname’ db_name
If you want to copy a database from a remote machine over a slow network, you can use:
shell> mysqladmin create db_name
shell> mysqldump -h ’other hostname’ --opt --compress db_name \
| mysql db_name
You can also store the result in a file, then transfer the file to the target machine and load
the file into the database there. For example, you can dump a database to a file on the
source machine like this:
Chapter 2: Installing MySQL
125
shell> mysqldump --quick db_name | gzip > db_name.contents.gz
(The file created in this example is compressed.) Transfer the file containing the database
contents to the target machine and run these commands there:
shell> mysqladmin create db_name
shell> gunzip < db_name.contents.gz | mysql db_name
You can also use mysqldump and mysqlimport to transfer the database. For big tables,
this is much faster than simply using mysqldump. In the following commands, DUMPDIR
represents the full pathname of the directory you use to store the output from mysqldump.
First, create the directory for the output files and dump the database:
shell> mkdir DUMPDIR
shell> mysqldump --tab=DUMPDIR db_name
Then transfer the files in the DUMPDIR directory to some corresponding directory on the
target machine and load the files into MySQL there:
shell> mysqladmin create db_name
# create database
shell> cat DUMPDIR/*.sql | mysql db_name
# create tables in database
shell> mysqlimport db_name DUMPDIR/*.txt
# load data into tables
Also, don’t forget to copy the mysql database because that’s where the grant tables (user,
db, host) are stored. You may have to run commands as the MySQL root user on the new
machine until you have the mysql database in place.
After you import the mysql database on the new machine, execute mysqladmin flushprivileges so that the server reloads the grant table information.
2.5.8 Upgrading MySQL under Windows
When upgrading MySQL under Windows, please follow these steps:
1. Download the latest Windows distribution of MySQL.
2. Choose a time of day with low usage, where a maintenance break is acceptable.
3. Alert the users that still are active about the maintenance break.
4. Stop the running MySQL Server (for example, with NET STOP mysql or with the
Services utility if you are running MySQL as a service, or with mysqladmin
shutdown otherwise).
5. Exit the WinMySQLAdmin program if it is running.
6. Run the installation script of the Windows distribution, by clicking the "Install" button
in WinZip and following the installation steps of the script.
7. You may either overwrite your old MySQL installation (usually located at ‘C:\mysql’),
or install it into a different directory, such as C:\mysql4. Overwriting the old installation is recommended.
8. Restart the server (for example, with NET START mysql if you run MYSQL as a service,
or by invoking mysqld directly otherwise).
9. Update the grant tables. The procedure is described in Section 2.5.6 [Upgrading-granttables], page 123.
Possible error situations:
126
MySQL Technical Reference for Version 4.1.1-alpha
A system error has occurred.
System error 1067 has occurred.
The process terminated unexpectedly.
This error means that your ‘my.cnf’ file (by default ‘C:\my.cnf’) contains an option that
cannot be recognised by MySQL. You can verify that this is the case by trying to restart
MySQL with the ‘my.cnf’ file renamed, for example, to ‘my_cnf.old’ to prevent the server
from using it. Once you have verified it, you need to identify which option is the culprit.
Create a new ‘my.cnf’ file and move parts of the old file to it (restarting the server after
you move each part) until you determine which option causes server startup to fail.
2.6 Operating System Specific Notes
2.6.1 Windows Notes
This section describes issues specific to using MySQL on Windows.
2.6.1.1 Connecting to MySQL Remotely from Windows with SSH
Here is a note about how to connect to get a secure connection to remote MySQL server
with SSH (by David Carlson [email protected]):
1. Install an SSH client on your Windows machine. As a user, the best non-free one
I’ve found is from SecureCRT from http://www.vandyke.com/. Another option is
f-secure from http://www.f-secure.com/. You can also find some free ones on
Google at http://directory.google.com/Top/Computers/Security/Products_
and_Tools/Cryptography/SSH/Clients/Windows/.
2. Start your Windows SSH client. Set Host_Name = yourmysqlserver_URL_or_IP. Set
userid=your_userid to log in to your server. This userid value may not be the same
as the username of your MySQL account.
3. Set up port forwarding. Either do a remote forward (Set local_port: 3306, remote_
host: yourmysqlservername_or_ip, remote_port: 3306 ) or a local forward (Set
port: 3306, host: localhost, remote port: 3306).
4. Save everything, otherwise you’ll have to redo it the next time.
5. Log in to your server with the SSH session you just created.
6. On your Windows machine, start some ODBC application (such as Access).
7. Create a new file in Windows and link to MySQL using the ODBC driver the same
way you normally do, except type in localhost for the MySQL host server—not
yourmysqlservername.
You should now have an ODBC connection to MySQL, encrypted using SSH.
2.6.1.2 Compiling MySQL Clients on Windows
In your source files, you should include ‘my_global.h’ before ‘mysql.h’:
Chapter 2: Installing MySQL
127
#include <my_global.h>
#include <mysql.h>
‘my_global.h’ includes any other files needed for Windows compatibility (such as
‘windows.h’) if you compile your program on Windows.
You can either link your code with the dynamic ‘libmysql.lib’ library, which is just a
wrapper to load in ‘libmysql.dll’ on demand, or link with the static ‘mysqlclient.lib’
library.
Note that because the MySQL client libraries are compiled as threaded libraries, you should
also compile your code to be multi-threaded!
2.6.1.3 MySQL on Windows Compared to MySQL on Unix
MySQL for Windows has by now proven itself to be very stable. The Windows version
of MySQL has the same features as the corresponding Unix version, with the following
exceptions:
Windows 95 and threads
Windows 95 leaks about 200 bytes of main memory for each thread creation.
Each connection in MySQL creates a new thread, so you shouldn’t run mysqld
for an extended time on Windows 95 if your server handles many connections!
Other versions of Windows don’t suffer from this bug.
Concurrent reads
MySQL depends on the pread() and pwrite() calls to be able to mix INSERT
and SELECT. Currently we use mutexes to emulate pread()/pwrite(). We
will, in the long run, replace the file level interface with a virtual interface so
that we can use the readfile()/writefile() interface on NT/2000/XP to
get more speed. The current implementation limits the number of open files
MySQL can use to 1024, which means that you will not be able to run as many
concurrent threads on NT/2000/XP as on Unix.
Blocking read
MySQL uses a blocking read for each connection, which has the following implications:
• A connection will not be disconnected automatically after 8 hours, as happens with the Unix version of MySQL.
• If a connection hangs, it’s impossible to break it without killing MySQL.
• mysqladmin kill will not work on a sleeping connection.
• mysqladmin shutdown can’t abort as long as there are sleeping connections.
We plan to fix this problem when our Windows developers have figured out a
nice workaround.
DROP DATABASE
You can’t drop a database that is in use by some thread.
Killing MySQL from the task manager
You can’t kill MySQL from the task manager or with the shutdown utility in
Windows 95. You must take it down with mysqladmin shutdown.
128
MySQL Technical Reference for Version 4.1.1-alpha
Case-insensitive names
Filenames are not case sensitive on Windows, so MySQL database and table
names are also not case sensitive on Windows. The only restriction is that
database and table names must be specified using the same case throughout a
given statement. See Section 6.1.3 [Name case sensitivity], page 450.
The ‘\’ directory character
Pathname components in Windows 95 are separated by the ‘\’ character, which
is also the escape character in MySQL. If you are using LOAD DATA INFILE or
SELECT ... INTO OUTFILE, use Unix style filenames with ‘/’ characters:
mysql> LOAD DATA INFILE "C:/tmp/skr.txt" INTO TABLE skr;
mysql> SELECT * INTO OUTFILE ’C:/tmp/skr.txt’ FROM skr;
Alternatively, you must double the ‘\’ character:
mysql> LOAD DATA INFILE "C:\\tmp\\skr.txt" INTO TABLE skr;
mysql> SELECT * INTO OUTFILE ’C:\\tmp\\skr.txt’ FROM skr;
Problems with pipes.
Pipes doesn’t work reliably in the Windows command-line prompt. If the pipe
includes the character ^Z / CHAR(24), Windows will think it has encountered
end-of-file and abort the program.
This is mainly a problem when you try to apply a binary log as follows:
mysqlbinlog binary-log-name | mysql --user=root
If you get a problem applying the log and suspect it’s because of an ^Z /
CHAR(24) character you can use the following workaround:
mysqlbinlog binary-log-file --result-file=/tmp/bin.sql
mysql --user=root --execute "source /tmp/bin.sql"
The latter command also can be used to reliably read in any SQL file that may
contain binary data.
Can’t open named pipe error
If you use a MySQL Version 3.22 server on NT with the newest MySQL client
programs, you will get the following error:
error 2017: can’t open named pipe to host: . pipe...
This is because the release version of MySQL uses named pipes on NT by
default. You can avoid this error by using the --host=localhost option to
the new MySQL clients or create an option file ‘C:\my.cnf’ that contains the
following information:
[client]
host = localhost
Starting from 3.23.50, named pipes are enabled only if mysqld-nt or mysqldmax-nt is started with --enable-named-pipe.
Access denied for user error
If you attempt to run a MySQL client program to connect to a server running on the same machine, but get the error Access denied for user: ’[email protected]’ to database ’mysql’, this means that MySQL can’t resolve
your host name properly.
Chapter 2: Installing MySQL
129
To fix this, you should create a file ‘\windows\hosts’ with the following information:
127.0.0.1
localhost
ALTER TABLE
While you are executing an ALTER TABLE statement, the table is locked from
being used by other threads. This has to do with the fact that on Windows,
you can’t delete a file that is in use by another threads. In the future, we may
find some way to work around this problem.
DROP TABLE
DROP TABLE on a table that is in use by a MERGE table will not work on Windows
because the MERGE handler does the table mapping hidden from the upper layer
of MySQL. Because Windows doesn’t allow you to drop files that are open, you
first must flush all MERGE tables (with FLUSH TABLES) or drop the MERGE table
before dropping the table. We will fix this at the same time we introduce views.
DATA DIRECTORY and INDEX DIRECTORY
The DATA DIRECTORY and INDEX DIRECTORY options for CREATE TABLE are ignored on Windows, because Windows doesn’t support symbolic links.
Here are some open issues for anyone who might want to help us improve MySQL on
Windows:
• Add some nice start and shutdown icons to the MySQL installation.
• It would be really nice to be able to kill mysqld from the task manager. For the
moment, you must use mysqladmin shutdown.
• Port readline to Windows for use in the mysql command-line tool.
• GUI versions of the standard MySQL clients (mysql, mysqlshow, mysqladmin, and
mysqldump) would be nice.
• It would be nice if the socket read and write functions in ‘net.c’ were interruptible.
This would make it possible to kill open threads with mysqladmin kill on Windows.
• Add macros to use the faster thread-safe increment/decrement methods provided by
Windows.
2.6.2 Linux Notes (All Linux Versions)
The following notes regarding glibc apply only to the situation when you build MySQL
yourself. If you are running Linux on an x86 machine, in most cases it is much better for you
to just use our binary. We link our binaries against the best patched version of glibc we
can come up with and with the best compiler options, in an attempt to make it suitable for
a high-load server. For a typical user, even for setups with a lot of concurrent connections
and/or tables exceeding the 2G limit, our binary in most cases is the best choice. So if you
read the following text, and are in doubt about what you should do, try our binary first to
see if it meets your needs, and worry about your own build only after you have discovered
that our binary is not good enough. In that case, we would appreciate a note about it, so
we can build a better binary next time.
130
MySQL Technical Reference for Version 4.1.1-alpha
MySQL uses LinuxThreads on Linux. If you are using an old Linux version that doesn’t
have glibc2, you must install LinuxThreads before trying to compile MySQL. You can get
LinuxThreads at http://www.mysql.com/downloads/os-linux.html.
Note: we have seen some strange problems with Linux 2.2.14 and MySQL on SMP systems.
If you have a SMP system, we recommend you upgrade to Linux 2.4 as soon as possible.
Your system will be faster and more stable.
Note that glibc versions before and including Version 2.1.1 have a fatal bug in pthread_
mutex_timedwait handling, which is used when you issue INSERT DELAYED statements. We
recommend that you not use INSERT DELAYED before upgrading glibc.
If you plan to have 1000+ concurrent connections, you will need to make some changes to
LinuxThreads, recompile it, and relink MySQL against the new ‘libpthread.a’. Increase
PTHREAD_THREADS_MAX in ‘sysdeps/unix/sysv/linux/bits/local_lim.h’ to 4096 and decrease STACK_SIZE in ‘linuxthreads/internals.h’ to 256 KB. The paths are relative to
the root of glibc Note that MySQL will not be stable with around 600-1000 connections
if STACK_SIZE is the default of 2 MB.
If MySQL can’t open enough files, or connections, it may be that you haven’t configured
Linux to handle enough files.
In Linux 2.2 and onward, you can check the number of allocated file handles by doing:
cat /proc/sys/fs/file-max
cat /proc/sys/fs/dquot-max
cat /proc/sys/fs/super-max
If you have more than 16 MB 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 preceding commands from the command-line as root, but these settings
will be lost the next time your computer reboots.
Alternatively, you can set these parameters on bootup by using the sysctl tool, which is
used by many Linux distributions (SuSE has added it as well, beginning with SuSE Linux
8.0). Just put the following values into a file named ‘/etc/sysctl.conf’:
# Increase some values for MySQL
fs.file-max = 65536
fs.dquot-max = 8192
fs.super-max = 1024
You should also add the following to ‘/etc/my.cnf’:
[mysqld_safe]
open-files-limit=8192
This should allow MySQL to create up to 8192 connections + files.
The STACK_SIZE constant in LinuxThreads controls the spacing of thread stacks in the
address space. It needs to be large enough so that there will be plenty of room for the
stack of each individual thread, but small enough to keep the stack of some threads from
running into the global mysqld data. Unfortunately, the Linux implementation of mmap(),
Chapter 2: Installing MySQL
131
as we have experimentally discovered, will successfully unmap an already mapped region if
you ask it to map out an address already in use, zeroing out the data on the entire page,
instead of returning an error. So, the safety of mysqld or any other threaded application
depends on the "gentleman" behaviour of the code that creates threads. The user must
take measures to make sure the number of running threads at any time is sufficiently low
for thread stacks to stay away from the global heap. With mysqld, you should enforce this
"gentleman" behaviour by setting a reasonable value for the max_connections variable.
If you build MySQL yourself and do not want to mess with patching 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 2G patch. If you are using our binary
or RPM version 3.23.25 or later, you can safely set max_connections at 1500, assuming
no large key buffer or heap tables with lots of data. The more you reduce STACK_SIZE in
LinuxThreads the more threads you can safely create. We recommend the values between
128K and 256K.
If you use a lot of concurrent connections, you may suffer from a "feature" in the 2.2
kernel that penalises a process for forking or cloning a child in an attempt to prevent a
fork bomb attack. This will cause MySQL not to scale well as you increase the number
of concurrent clients. On single-CPU systems, we have seen this manifested in a very
slow thread creation, which means it may take a long time to connect to MySQL (as
long as 1 minute), and it may take just as long to shut it down. On multiple-CPU systems, we have observed a gradual drop in query speed as the number of clients increases.
In the process of trying to find a solution, we have received a kernel patch from one of
our users, who claimed it made a lot of difference for his site. The patch is available
at http://www.mysql.com/Downloads/Patches/linux-fork.patch. We have now done
rather extensive testing of this patch on both development and production systems. It
has significantly improved MySQL performance without causing any problems and we now
recommend it to our users who are still running 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 just upgrade to 2.4,
which will also give you a nice SMP boost in addition to fixing this fairness bug.
We have tested MySQL on the 2.4 kernel on a 2-CPU machine and found MySQL scales
much better—there was virtually no slowdown on queries throughput all the way up to 1000
clients, and the MySQL scaling factor (computed as the ratio of maximum throughput to
the throughput with one client) was 180%. We have observed similar results on a 4-CPU
system—virtually no slowdown as the number of clients was increased up to 1000, and 300%
scaling factor. So for a high-load SMP server we would definitely recommend the 2.4 kernel
at this point. We have discovered that it is essential to run mysqld process with the highest
possible priority on the 2.4 kernel to achieve maximum performance. This can be done
by adding renice -20 $$ command to mysqld_safe. In our testing on a 4-CPU machine,
increasing the priority gave 60% increase in throughput with 400 clients.
We are currently also trying to collect more information on how well MySQL performs on 2.4
kernel on 4-way and 8-way systems. If you have access such a system and have done some
benchmarks, please send a mail to [email protected] with the results - we will include them
in the manual.
132
MySQL Technical Reference for Version 4.1.1-alpha
There is another issue that greatly hurts MySQL performance, especially on SMP
systems. The implementation of mutex in LinuxThreads in glibc-2.1 is very bad
for programs with many threads that only hold the mutex for a short time. On an
SMP system, ironic as it is, if you link MySQL against unmodified LinuxThreads,
removing processors from the machine improves MySQL performance in many
cases. We have made a patch available for glibc 2.1.3 to correct this behaviour
(http://www.mysql.com/Downloads/Linux/linuxthreads-2.1-patch).
With glibc-2.2.2 MySQL version 3.23.36 will use the adaptive mutex, which is much better than even the patched one in glibc-2.1.3. Be warned, however, that under some conditions, the current mutex code in glibc-2.2.2 overspins, which hurts MySQL performance.
The chance of this condition can be reduced by renicing mysqld process to the highest
priority. We have also been able to correct the overspin behaviour with a patch, available
at http://www.mysql.com/Downloads/Linux/linuxthreads-2.2.2.patch. It combines
the correction of overspin, maximum number of threads, and stack spacing all in one. You
will need to apply it in the linuxthreads directory with patch -p0 </tmp/linuxthreads2.2.2.patch. We hope it will be included in some form in to the future releases of glibc2.2. In any case, if you link against glibc-2.2.2 you still need to correct STACK_SIZE
and PTHREAD_THREADS_MAX. We hope that the defaults will be corrected to some more
acceptable values for high-load MySQL setup in the future, so that your own build can be
reduced to ./configure; make; make install.
We recommend that you use the above patches to build a special static version of
libpthread.a and use it only for statically linking against MySQL. We know that the
patches are safe for MySQL and significantly improve its performance, but we cannot say
anything about other applications. If you link other applications against the patched
version of the library, or build a patched shared version and install it on your system,
you are doing it at your own risk with regard to other applications that depend on
LinuxThreads.
If you experience any strange problems during the installation of MySQL, or with some
common utilities hanging, it is very likely that they are either library or compiler related.
If this is the case, using our binary will resolve them.
One known problem with the binary distribution is that with older Linux systems that use
libc (like Red Hat 4.x or Slackware), you will get some non-fatal problems with hostname
resolution. See Section 2.6.2.1 [Binary notes-Linux], page 133.
When using LinuxThreads you will see a minimum of three processes running. These are in
fact threads. There will be one thread for the LinuxThreads manager, one thread to handle
connections, and one thread to handle alarms and signals.
Note that the Linux kernel and the LinuxThread library can by default only have 1024
threads. This means that you can only have up to 1021 connections to MySQL on an
unpatched system. The page http://www.volano.com/linuxnotes.html contains information how to go around this limit.
If you see a dead mysqld daemon process with ps, this usually means that you have found
a bug in MySQL or you have a corrupted table. See Section A.4.1 [Crashing], page 870.
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
Chapter 2: Installing MySQL
133
size by adding ulimit -c 1000000 to mysqld_safe or starting mysqld_safe with --corefile-size=1000000. See Section 4.8.2 [mysqld_safe], page 315.
If you are linking your own MySQL client and get the error:
ld.so.1: ./my: fatal: libmysqlclient.so.4:
open failed: No such file or directory
When executing them, the problem can be avoided by one of the following methods:
• Link the client with the following flag (instead of -Lpath): -Wl,r/pathlibmysqlclient.so.
• Copy libmysqclient.so to ‘/usr/lib’.
• Add the pathname of the directory where ‘libmysqlclient.so’ is located to the LD_
RUN_PATH environment variable before running your client.
If you are using the Fujitsu compiler (fcc / FCC) you will have some problems compiling
MySQL because the Linux header files are very 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.6.2.1 Linux Notes for Binary Distributions
MySQL needs at least Linux Version 2.0.
Warning: We have reports from some MySQL users that they have got serious stability
problems with MySQL with Linux 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 multi-cpu box, then you
should seriously consider using 2.4 as this will give you a significant speed boost.
The binary release is linked with -static, which means you do not normally need to worry
about which version of the system libraries you have. You need not install LinuxThreads,
either. A program linked with -static is slightly bigger than a dynamically linked program
but also slightly faster (3-5%). One problem, however, is that you can’t use user-definable
functions (UDFs) with a statically linked program. 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.
If you are using a libc-based system (instead of a glibc2 system),
some problems with hostname resolution and getpwnam() with the
is because glibc unfortunately depends on some external libraries
and getpwent(), even when compiled with -static). In this case
following error message when you run mysql_install_db:
you will probably get
binary release. (This
to resolve hostnames
you probably get the
Sorry, the host ’xxxx’ could not be looked up
or the following error when you try to run mysqld with the --user option:
134
MySQL Technical Reference for Version 4.1.1-alpha
getpwnam: No such file or directory
You can solve this problem in one of the following ways:
• Get a MySQL source distribution (an RPM or the tar.gz distribution) and install this
instead.
• Execute mysql_install_db --force; this will not execute the resolveip test in
mysql_install_db. The downside is that you can’t use host names in the grant
tables; you must use IP numbers instead (except for localhost). If you are using an
old MySQL release that doesn’t support --force, you have to remove the resolveip
test in mysql_install with an editor.
• Start mysqld with su instead of using --user.
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.
MySQL Perl support requires Version Perl 5.004 03 or newer.
On some Linux 2.2 versions, you may get the error Resource temporarily unavailable
when you do a lot of new connections to a mysqld server over TCP/IP.
The problem is that Linux has a delay between when you close a TCP/IP socket and until
this is actually freed by the system. As there is only room for a finite number of TCP/IP
slots, you will get the above error if you try to do too many new TCP/IP connections during
a small time, like when you run the MySQL ‘test-connect’ benchmark over TCP/IP.
We have mailed about this problem a couple of times to different Linux mailing lists but
have never been able to resolve this properly.
The only known ’fix’ to this problem is to use persistent connections in your clients or use
sockets, if you are running the database server and clients on the same machine. We hope
that the Linux 2.4 kernel will fix this problem in the future.
2.6.2.2 Linux x86 Notes
MySQL requires libc Version 5.4.12 or newer. It’s known to work with libc 5.4.46. glibc
Version 2.0.6 and later should also work. There have been some problems with the glibc
RPMs from Red Hat, so if you have problems, check whether there are any updates. The
glibc 2.0.7-19 and 2.0.7-29 RPMs are known to work.
If you are using Red Hat 8.0 or a new glibc 2.2.x library, you should start mysqld with
the option --thread-stack=192K. (Use -O thread_stack=192K before MySQL 4.) If you
don’t do this, mysqld will die in gethostbyaddr() because the new glibc library requires
a stack size greater than 128K for this call. This stack size is now the default on MySQL
4.0.10 and above.
If you are using gcc 3.0 and above to compile MySQL, you must install the libstdc++v3
library before compiling MySQL; if you don’t do this, you will 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.
Chapter 2: Installing MySQL
135
Just do what the error message says and add an extra underscore to the _P macro that has
only one underscore, then try again.
You may get some warnings when compiling; those shown here can be ignored:
mysqld.cc -o objs-thread/mysqld.o
mysqld.cc: In function ‘void init_signals()’:
mysqld.cc:315: warning: assignment of negative value ‘-1’ to
‘long unsigned int’
mysqld.cc: In function ‘void * signal_hand(void *)’:
mysqld.cc:346: warning: assignment of negative value ‘-1’ to
‘long unsigned int’
mysql.server can be found in the ‘share/mysql’ directory under the MySQL installation
directory or in the ‘support-files’ directory of the MySQL source tree.
If mysqld always core dumps when it starts up, the problem may be that you have an old
‘/lib/libc.a’. Try renaming it, then remove ‘sql/mysqld’ and do a new make install
and try again. This problem has been reported on some Slackware installations.
If you get the following error when linking mysqld, it means that your ‘libg++.a’ is not
installed correctly:
/usr/lib/libc.a(putc.o): In function ‘_IO_putc’:
putc.o(.text+0x0): multiple definition of ‘_IO_putc’
You can avoid using ‘libg++.a’ by running configure like this:
shell> CXX=gcc ./configure
2.6.2.3 Linux SPARC Notes
In some implementations, readdir_r() is broken. The symptom is that SHOW DATABASES always returns an empty set. This can be fixed by removing HAVE_READDIR_R from ‘config.h’
after configuring and before compiling.
2.6.2.4 Linux Alpha Notes
MySQL Version 3.23.12 is the first MySQL version that is tested on Linux-Alpha. If you
plan to use MySQL on Linux-Alpha, you should ensure that you have this version or newer.
We have tested MySQL on Alpha with our benchmarks and test suite, and it appears to
work nicely.
We currently build the MySQL binary packages on SuSE Linux 7.0 for AXP, kernel 2.4.4SMP, 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 above compilers at http://www.support.compaq.com/alpha-tools/. By
using these compilers, instead of gcc, we get about 9-14% better performance with MySQL.
Note that until MySQL version 3.23.52 and 4.0.2 we optimised the binary for the current
CPU only (by using the -fast compile option); this meant that you could only use our
binaries if you had an Alpha EV6 processor.
136
MySQL Technical Reference for Version 4.1.1-alpha
Starting with all following releases we added the -arch generic flag to our compile options,
which makes sure the binary runs on all Alpha processors. We also compile statically to
avoid library problems.
CC=ccc CFLAGS="-fast -arch generic" CXX=cxx \
CXXFLAGS="-fast -arch generic -noexceptions -nortti" \
./configure --prefix=/usr/local/mysql --disable-shared \
--with-extra-charsets=complex --enable-thread-safe-client \
--with-mysqld-ldflags=-non_shared --with-client-ldflags=-non_shared
If you want to use egcs the following configure line worked for us:
CFLAGS="-O3 -fomit-frame-pointer" CXX=gcc \
CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql \
--disable-shared
Some known problems when running MySQL on Linux-Alpha:
• Debugging threaded applications like MySQL will not work with gdb 4.18. You should
download and use gdb 5.1 instead!
• If you try linking mysqld statically when using gcc, the resulting image will core dump
at start. In other words, don’t use --with-mysqld-ldflags=-all-static with gcc.
2.6.2.5 Linux PowerPC Notes
MySQL should work on MkLinux with the newest glibc package (tested with glibc 2.0.7).
2.6.2.6 Linux MIPS Notes
To get MySQL to work on Qube2, (Linux Mips), you need the newest glibc libraries
(glibc-2.0.7-29C2 is known to work). You must also use the egcs C++ compiler (egcs1.0.2-9, gcc 2.95.2 or newer).
2.6.2.7 Linux IA-64 Notes
To get MySQL to compile on Linux IA-64, we use the following compile line: Using gcc2.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 in some other place than ‘/usr/local/mysql’ you need to
add the path of the directory where you have ‘libmysqlclient.so’ installed either to the
‘/etc/ld.so.conf’ file or to the value of your LD_LIBRARY_PATH environment variable.
See Section A.3.1 [Link errors], page 868.
Chapter 2: Installing MySQL
137
2.6.3 Solaris Notes
On Solaris, you may run into trouble even before you get the MySQL distribution unpacked!
Solaris tar can’t handle long file names, so you may see an error like this when you unpack
MySQL:
x mysql-3.22.12-beta/bench/Results/ATIS-mysql_odbc-NT_4.0-cmp-db2,\
informix,ms-sql,mysql,oracle,solid,sybase, 0 bytes, 0 tape blocks
tar: directory checksum error
In this case, you must use GNU tar (gtar) to unpack the distribution. You can find a
precompiled copy for Solaris at http://www.mysql.com/downloads/os-solaris.html.
Sun native threads only work on Solaris 2.5 and higher. For Version 2.4 and earlier, MySQL
will automatically use MIT-pthreads. See Section 2.3.6 [MIT-pthreads], page 101.
If you get the following error from configure:
checking for restartable system calls... configure: error can not run test
programs while cross compiling
This means that you have something wrong with your compiler installation! In this case
you should upgrade your compiler to a newer version. You may also be able to solve this
problem by inserting the following row into the ‘config.cache’ file:
ac_cv_sys_restartable_syscalls=${ac_cv_sys_restartable_syscalls=’no’}
If you are using Solaris on a SPARC, the recommended compiler is gcc 2.95.2 or 3.2. You
can find this at http://gcc.gnu.org/. Note that egcs 1.1.1 and gcc 2.8.1 don’t work
reliably on SPARC!
The recommended configure line when using gcc 2.95.2 is:
CC=gcc CFLAGS="-O3" \
CXX=gcc CXXFLAGS="-O3 -felide-constructors -fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql --with-low-memory --enable-assembler
If you have an UltraSPARC, you can get 4% more performance by adding "-mcpu=v8
-Wa,-xarch=v8plusa" to CFLAGS and CXXFLAGS.
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
You can create a 64-bit binary using Sun’s Forte compiler with the following compile flags:
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 64bit Solaris binary using gcc, add -m64 to CFLAGS and CXXFLAGS. Note that
this only works with MySQL 4.0 and up - MySQL 3.23 does not include the required
modifications to support this.
In the MySQL benchmarks, we got a 4% speedup on an UltraSPARC when using Forte 5.0
in 32-bit mode compared to using gcc 3.2 with -mcpu flags.
If you create a 64-bit binary, it’s 4 % slower than the 32-bit binary, but mysqld can instead
handle more treads and memory.
138
MySQL Technical Reference for Version 4.1.1-alpha
If you get a problem with fdatasync or sched_yield, you can fix this by adding LIBS=-lrt
to the configure line
The following paragraph is only relevant for older compilers than WorkShop 5.3:
You may also have to edit the configure script to 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 error message shown here when you run it, you have tried to compile
MySQL with the Sun compiler without enabling the multi-thread option (-mt):
libc internal error: _rmutex_unlock: rmutex not held
Add -mt to CFLAGS and CXXFLAGS and try again.
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.
You should recompile gcc and GNU binutils on the machine you will be running them from
to avoid any problems.
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 will break all programs that use threads (and possibly other
programs)!
Solaris doesn’t provide static versions of all system libraries (libpthreads and libdl), so
you can’t compile MySQL with --static. If you try to do so, you will get the error:
ld: fatal: library -ldl: not found
or
undefined reference to ‘dlopen’
or
cannot find -lrt
If too many processes try to connect very rapidly to mysqld, you will see this error in the
MySQL log:
Error in accept: Protocol error
You might try starting the server with the --set-variable back_log=50 option as a
workaround for this. Please note that --set-variable=name=value and -O name=value
Chapter 2: Installing MySQL
139
syntax is deprecated as of MySQL 4.0. Use --back_log=50 instead. See Section 4.1.1
[Command-line options], page 198.
If you are linking your own MySQL client, you might get the following error when you try
to execute it:
ld.so.1: ./my: fatal: libmysqlclient.so.#:
open failed: No such file or directory
The problem can be avoided by one of the following methods:
• Link the client with the following flag (instead of -Lpath): -Wl,r/full-path-tolibmysqlclient.so.
• Copy ‘libmysqclient.so’ to ‘/usr/lib’.
• Add the pathname of the directory where ‘libmysqlclient.so’ is located to the LD_
RUN_PATH environment variable before running your client.
If you have problems with configure trying to link with -lz and you don’t have zlib
installed, you have two options:
• If you want to be able to use the compressed communication protocol, you need to get
and install zlib from ftp.gnu.org.
• Configure with --with-named-z-libs=no.
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’.
As Solaris doesn’t support core files for setuid() applications, you can’t get a core file from
mysqld if you are using the --user option.
2.6.3.1 Solaris 2.7/2.8 Notes
You can normally 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.
Note that MySQL Version 3.23.4 and above should be able to autodetect new versions of
Solaris 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 do the following to fix the problem:
Copy /usr/include/widec.h to .../lib/gcc-lib/os/gcc-version/include and change
line 41 from:
#if
!defined(lint) && !defined(__lint)
to
140
MySQL Technical Reference for Version 4.1.1-alpha
#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 errors like this when you run make, it’s because configure didn’t detect the
‘curses.h’ file (probably because of the error in ‘/usr/include/widec.h’):
In file included from mysql.cc:50:
/usr/include/term.h:1060: syntax error before ‘,’
/usr/include/term.h:1081: syntax error before ‘;’
The solution to this is to do one of the following:
• Configure with CFLAGS=-DHAVE_CURSES_H CXXFLAGS=-DHAVE_CURSES_H ./configure.
• Edit ‘/usr/include/widec.h’ as indicted above and rerun configure.
• Remove the #define HAVE_TERM line from ‘config.h’ file and run make again.
If you get a problem that your linker can’t find -lz when linking your client program, the
problem is probably that your ‘libz.so’ file is installed in ‘/usr/local/lib’. You can fix
this 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.
• Configure MySQL with the --with-named-z-libs=no option.
2.6.3.2 Solaris x86 Notes
On Solaris 8 on x86, mysqld will dump core if you remove the debug symbols using strip.
If you are using gcc or egcs on Solaris x86 and you experience problems with core dumps
under load, you should use the following configure command:
CC=gcc CFLAGS="-O3 -fomit-frame-pointer -DHAVE_CURSES_H" \
CXX=gcc \
CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors -fno-exceptions \
-fno-rtti -DHAVE_CURSES_H" \
./configure --prefix=/usr/local/mysql
This will avoid problems with the libstdc++ library and with C++ exceptions.
If this doesn’t help, you should compile a debug version and run it with a trace file or under
gdb. See Section E.1.3 [Using gdb on mysqld], page 1022.
2.6.4 BSD Notes
This section provides information for the various BSD flavours, as well as specific versions
within those.
Chapter 2: Installing MySQL
141
2.6.4.1 FreeBSD Notes
FreeBSD 4.x or newer is recommended for running MySQL since the thread package is much
more integrated.
The easiest and therefore the preferred way to install is to use the mysql-server and mysqlclient ports available on http://www.freebsd.org/.
Using these gives you:
• A working MySQL with all optimisations known to work on your version of FreeBSD
enabled.
• Automatic configuration and build.
• Startup scripts installed in /usr/local/etc/rc.d.
• Ability to see which files that are installed with pkg info -L. And to remove them all
with pkg delete if you no longer want MySQL on that machine.
It is recommended you use MIT-pthreads on FreeBSD 2.x and native threads on Versions
3 and up. It is possible to run with native threads on some late 2.2.x versions but you may
encounter problems shutting down mysqld.
Unfortunately, certain function calls on FreeBSD are not yet fully thread-safe, most notably
the gethostbyname() function, which is used by MySQL to convert host names into IP
addresses. Under certain circumstances, the mysqld process will suddenly cause 100% CPU
load and will be unresponsive. If you encounter this, try to start up 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 vs. native threads have a look
at Jeremy Zawodny’s article "FreeBSD or Linux for your MySQL Server?" at
http://jeremy.zawodny.com/blog/archives/000697.html
The known problems when using LinuxThreads on FreeBSD are:
• wait_timeout is not working (probably signal handling problem in
FreeBSD/LinuxThreads).
This is supposed to get fixed in FreeBSD 5.0.
The symptom is that persistent connections can hang for a long time without getting
closed done.
The MySQL ‘Makefile’s require GNU make (gmake) to work. If you want to compile
MySQL you need to install GNU make first.
Be sure to have your name resolver setup correct. Otherwise, you may experience resolver
delays or failures when connecting to mysqld.
Make sure that the localhost entry in the ‘/etc/hosts’ file is correct (otherwise, you will
have problems connecting to the database). The ‘/etc/hosts’ file should start with a line:
127.0.0.1
localhost localhost.your.domain
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 \
142
MySQL Technical Reference for Version 4.1.1-alpha
-fno-strength-reduce" \
./configure --prefix=/usr/local/mysql --enable-assembler
gmake
gmake install
./scripts/mysql_install_db
cd /usr/local/mysql
./bin/mysqld_safe &
If you notice that configure will use MIT-pthreads, you should read the MIT-pthreads
notes. See Section 2.3.6 [MIT-pthreads], page 101.
If you get an error from make install that it can’t find ‘/usr/include/pthreads’,
configure didn’t detect that you need MIT-pthreads. This is fixed by executing these
commands:
shell> rm config.cache
shell> ./configure --with-mit-threads
FreeBSD is also known to have a very low default file handle limit. See Section A.2.17
[Not enough file handles], page 867. Uncomment the ulimit -n section in 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 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.8.2
[mysqld_safe], page 315.
If you have a lot of memory you should consider rebuilding the kernel to allow MySQL to
take more than 512M of RAM. Take a look at option MAXDSIZ in the LINT config file for
more info.
If you get problems with the current date in MySQL, setting the TZ variable will probably
help. See Appendix F [Environment variables], page 1032.
To get a secure and stable system you should only use FreeBSD kernels that are marked
-RELEASE.
2.6.4.2 NetBSD Notes
To compile on NetBSD you need GNU make. Otherwise, the compile will crash when make
tries to run lint on C++ files.
2.6.4.3 OpenBSD 2.5 Notes
On OpenBSD Version 2.5, you can compile MySQL with native threads with the following
options:
CFLAGS=-pthread CXXFLAGS=-pthread ./configure --with-mit-threads=no
2.6.4.4 OpenBSD 2.8 Notes
Our users have reported that OpenBSD 2.8 has a threading bug which causes problems
with MySQL. The OpenBSD Developers have fixed the problem, but as of January 25th,
2001, it’s only available in the “-current” branch. The symptoms of this threading bug are:
slow response, high load, high CPU usage, and crashes.
Chapter 2: Installing MySQL
143
If you get an error like Error in accept:: Bad file descriptor or error 9 when trying to
open tables or directories, the problem is probably that you haven’t allocated enough file
descriptors for MySQL.
In this case, try starting mysqld_safe as root with the following options:
shell> mysqld_safe --user=mysql --open-files-limit=2048 &
2.6.4.5 BSD/OS Version 2.x Notes
If you get the following error when compiling MySQL, your 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 will probably
help. See Appendix F [Environment variables], page 1032.
2.6.4.6 BSD/OS Version 3.x Notes
Upgrade to BSD/OS Version 3.1. If that is not possible, install BSDIpatch M300-038.
Use the following command when configuring MySQL:
shell> 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:
shell> 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-threadpriority option to mysqld! This will run all threads with the same priority; on BSDI
Version 3.1, this gives better performance (at least until BSDI fixes their thread scheduler).
If you get the error virtual memory exhausted while compiling, you should 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.
144
MySQL Technical Reference for Version 4.1.1-alpha
2.6.4.7 BSD/OS Version 4.x Notes
BSDI Version 4.x has some thread-related bugs. If you want to use MySQL on this, you
should install all thread-related patches. At least M400-023 should be installed.
On some BSDI Version 4.x systems, you may get problems with shared libraries. The
symptom is that you can’t execute any client programs, for example, mysqladmin. In this
case you need to reconfigure not to use shared libraries with the --disable-shared option
to configure.
Some customers have had problems on BSDI 4.0.1 that the mysqld binary after a while
can’t open tables. This is because some library/system related bug causes mysqld to change
current directory without asking for this!
The fix is to either upgrade to 3.23.34 or after running configure remove the line #define
HAVE_REALPATH from config.h before running make.
Note that the above means that you can’t symbolic link a database directories to another
database directory or symbolic link a table to another database on BSDI! (Making a symbolic link to another disk is okay).
2.6.5 Mac OS X Notes
2.6.5.1 Mac OS X 10.x
MySQL should work without any problems on Mac OS X 10.x (Darwin). You don’t need
the pthread patches for this OS!
This also applies to Mac OS X 10.x Server. Compiling for the Server platform is the same
as for the client version of Mac OS X. However please note that MySQL comes preinstalled
on the Server!
Our binary for Mac OS X is compiled on Darwin 6.3 with the following configure line:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc \
CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql \
--with-extra-charsets=complex --enable-thread-safe-client \
--enable-local-infile --disable-shared
See Section 2.1.3 [Mac OS X installation], page 68.
2.6.5.2 Mac OS X Server 1.2 (Rhapsody)
Before trying to configure MySQL on Mac OS X Server 1.2 (aka Rhapsody) you must first
install the pthread package from http://www.prnet.de/RegEx/mysql.html.
See Section 2.1.3 [Mac OS X installation], page 68.
2.6.6 Other Unix Notes
Chapter 2: Installing MySQL
145
2.6.6.1 HP-UX Notes for Binary Distributions
Some of the binary distributions of MySQL for HP-UX are distributed as an HP depot file
and as a tar file. To use the depot file you must be running at least HP-UX 10.x to have
access to HP’s software depot tools.
The HP version of MySQL was compiled on an HP 9000/8xx server under HP-UX 10.20,
and uses MIT-pthreads. It is known to work well under this configuration. MySQL Version
3.22.26 and newer can also be built with HP’s native thread package.
Other configurations that may work:
• HP 9000/7xx running HP-UX 10.20+
• HP 9000/8xx running HP-UX 10.30
The following configurations almost definitely won’t work:
• HP 9000/7xx or 8xx running HP-UX 10.x where x < 2
• HP 9000/7xx or 8xx running HP-UX 9.x
To install the distribution, use one of the commands here, where /path/to/depot is the
full pathname of the depot file:
• To install everything, including the server, client and development tools:
shell> /usr/sbin/swinstall -s /path/to/depot mysql.full
• To install only the server:
shell> /usr/sbin/swinstall -s /path/to/depot mysql.server
• To install only the client package:
shell> /usr/sbin/swinstall -s /path/to/depot mysql.client
• To install only the development tools:
shell> /usr/sbin/swinstall -s /path/to/depot mysql.developer
The depot places binaries and libraries in ‘/opt/mysql’ and data in ‘/var/opt/mysql’. The
depot also creates the appropriate entries in ‘/etc/init.d’ and ‘/etc/rc2.d’ to start the
server automatically at boot time. Obviously, this entails being root to install.
To install the HP-UX tar.gz distribution, you must have a copy of GNU tar.
2.6.6.2 HP-UX Version 10.20 Notes
There are a couple of small problems when compiling MySQL on HP-UX. We recommend
that you use gcc instead of the HP-UX native compiler, because gcc produces better code!
We recommend using gcc 2.95 on HP-UX. Don’t use high optimisation flags (like -O6) as
this may not be safe on HP-UX.
The following configure line should work with gcc 2.95:
CFLAGS="-I/opt/dce/include -fpic" \
CXXFLAGS="-I/opt/dce/include -felide-constructors -fno-exceptions \
-fno-rtti" CXX=gcc ./configure --with-pthread \
--with-named-thread-libs=’-ldce’ --prefix=/usr/local/mysql --disable-shared
The following configure line should work with gcc 3.1:
146
MySQL Technical Reference for Version 4.1.1-alpha
CFLAGS="-DHPUX -I/opt/dce/include -O3 -fPIC" CXX=gcc \
CXXFLAGS="-DHPUX -I/opt/dce/include -felide-constructors -fno-exceptions \
-fno-rtti -O3 -fPIC" ./configure --prefix=/usr/local/mysql \
--with-extra-charsets=complex --enable-thread-safe-client \
--enable-local-infile --with-pthread \
--with-named-thread-libs=-ldce --with-lib-ccflags=-fPIC
--disable-shared
2.6.6.3 HP-UX Version 11.x Notes
For HP-UX Version 11.x, we recommend MySQL Version 3.23.15 or later.
Because of some critical bugs in the standard HP-UX libraries, you should install the following patches before trying to run MySQL on HP-UX 11.0:
PHKL_22840 Streams cumulative
PHNE_22397 ARPA cumulative
This will solve the problem of getting EWOULDBLOCK from recv() and EBADF from accept()
in threaded applications.
If you are using gcc 2.95.1 on an unpatched HP-UX 11.x system, you will get the error:
In file included from /usr/include/unistd.h:11,
from ../include/global.h:125,
from mysql_priv.h:15,
from item.cc:19:
/usr/include/sys/unistd.h:184: declaration of C function ...
/usr/include/sys/pthread.h:440: previous declaration ...
In file included from item.h:306,
from mysql_priv.h:158,
from item.cc:19:
The problem is that HP-UX doesn’t define pthreads_atfork() consistently.
It has conflicting prototypes in ‘/usr/include/sys/unistd.h’:184 and
‘/usr/include/sys/pthread.h’:440 (details below).
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’. Here’s the diff:
183,184c183,184
<
extern int pthread_atfork(void (*prepare)(), void (*parent)(),
<
void (*child)());
-->
extern int pthread_atfork(void (*prepare)(void), void (*parent)(void),
>
void (*child)(void));
After this, the following configure line should work:
CFLAGS="-fomit-frame-pointer -O3 -fpic" CXX=gcc \
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti -O3" \
./configure --prefix=/usr/local/mysql --disable-shared
If you are using MySQL 4.0.5 with the HP-UX compiler you can use: (tested with cc
B.11.11.04):
Chapter 2: Installing MySQL
147
CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure --with-extra-character-set=com
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
checking for cc option to accept ANSI C... no
configure: error: MySQL requires a ANSI C compiler (and a C++ compiler).
Try gcc. See the Installation chapter in the Reference Manual.
Check that you don’t have the path to the K&R compiler before the path to the HP-UX C
and C++ compiler.
Another reason for not beeing able to compile is that you didn’t define the +DD64 flags
above.
Another possibility for HP-UX 11 is to use MySQL binaries for HP-UX 10.20. We have
received reports from some users that these binaries work fine on HP-UX 11.00. If you
encounter problems, be sure to check your HP-UX patch level.
2.6.6.4 IBM-AIX notes
Automatic detection of xlC is missing from Autoconf, so a configure command something
like this is needed when compiling MySQL (This example uses the IBM compiler):
export CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 "
export CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192"
export CFLAGS="-I /usr/local/include"
export LDFLAGS="-L /usr/local/lib"
export CPPFLAGS=$CFLAGS
export CXXFLAGS=$CFLAGS
./configure --prefix=/usr/local \
--localstatedir=/var/mysql \
--sysconfdir=/etc/mysql \
--sbindir=’/usr/local/bin’ \
--libexecdir=’/usr/local/bin’ \
--enable-thread-safe-client \
--enable-large-files
Above are the options used to compile the MySQL distribution that can be found at
http://www-frec.bull.com/.
If you change the -O3 to -O2 in the above configure line, you must also remove the -qstrict
option (this is a limitation in the IBM C compiler).
If you are using gcc or egcs to compile MySQL, you must use the -fno-exceptions flag,
as the exception handling in gcc/egcs is not thread-safe! (This is tested with egcs 1.1.)
There are also some known problems with IBM’s assembler, which may cause it to generate
bad code when used with gcc.
We recommend the following configure line with egcs and gcc 2.95 on AIX:
CC="gcc -pipe -mcpu=power -Wa,-many" \
CXX="gcc -pipe -mcpu=power -Wa,-many" \
148
MySQL Technical Reference for Version 4.1.1-alpha
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql --with-low-memory
The -Wa,-many is necessary for the compile to be successful. IBM is aware of this problem
but is in to hurry to fix it because of the workaround available. We don’t know if the
-fno-exceptions is required with gcc 2.95, but as MySQL doesn’t use exceptions and the
above option generates faster code, we recommend that you should always use this option
with egcs / gcc.
If you get a problem with assembler code try changing the -mcpu=xxx to match your CPU.
Typically power2, power, or powerpc may need to be used, alternatively you might need
to use 604 or 604e. I’m not positive but I would think using "power" would likely be safe
most of the time, even on a power2 machine.
If you don’t know what your CPU is then do a "uname -m", this will give you back a
string that looks like "000514676700", with a format of xxyyyyyymmss where xx and ss are
always 0’s, yyyyyy is a unique system ID and mm is the ID of the CPU Planar. A chart of
these values can be found at http://publib.boulder.ibm.com/doc_link/en_US/a_doc_
lib/cmds/aixcmds5/uname.htm. This will give you a machine type and a machine model
you can use to determine what type of CPU you have.
If you have problems with signals (MySQL dies unexpectedly under high load) you may
have found an OS bug with threads and signals. In this case you can tell MySQL not to
use signals by configuring with:
shell> 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 will die when it issues its next command.
On some versions of AIX, linking with libbind.a makes getservbyname core dump. This
is an AIX bug and should be reported to IBM.
For AIX 4.2.1 and gcc you have to do the following changes.
After configuring, edit ‘config.h’ and ‘include/my_config.h’ and change the line that
says
#define HAVE_SNPRINTF 1
to
#undef HAVE_SNPRINTF
And finally, in ‘mysqld.cc’ you need to add a prototype for initgoups.
#ifdef _AIX41
extern "C" int initgroups(const char *,int);
#endif
If you need to allocate a lot of memory to the mysqld process, it’s not enough to just set
’ulimit -d unlimited’. You may also have to set in mysqld_safe something like:
export LDR_CNTRL=’MAXDATA=0x80000000’
You can find more about using a lot of memory at: http://publib16.boulder.ibm.com/pseries/en_
US/aixprggd/genprogc/lrg_prg_support.htm.
Chapter 2: Installing MySQL
149
2.6.6.5 SunOS 4 Notes
On SunOS 4, MIT-pthreads is needed to compile MySQL, which in turn means you will
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:
shell> ./configure --disable-shared --with-mysqld-ldflags=-all-static
When compiling readline, you may get warnings about duplicate defines. These may be
ignored.
When compiling mysqld, there will be some implicit declaration of function warnings.
These may be ignored.
2.6.6.6 Alpha-DEC-UNIX Notes (Tru64)
If you are using egcs 1.1.2 on Digital Unix, you should upgrade to gcc 2.95.2, as 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 libraries -lmach -lexc (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:
shell> 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.8.2 [mysqld_safe], page 315.
If you get a problem when compiling mysys/get opt.c, just remove the line #define
NO PROTO from the start of that file!
If you are using Compaq’s CC compiler, the following configure line should work:
CC="cc -pthread"
CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all -arch host"
CXX="cxx -pthread"
CXXFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all -arch host \
-noexceptions -nortti"
export CC CFLAGS CXX CXXFLAGS
150
MySQL Technical Reference for Version 4.1.1-alpha
./configure \
--prefix=/usr/local/mysql \
--with-low-memory \
--enable-large-files \
--enable-shared=yes \
--with-named-thread-libs="-lpthread -lmach -lexc -lc"
gnumake
If you get a problem with libtool, when compiling with shared libraries as above, when
linking mysql, you should be able to get around this by issuing:
cd mysql
/bin/sh ../libtool --mode=link cxx -pthread -O3 -DDBUG_OFF \
-O4 -ansi_alias -ansi_args -fast -inline speed \
-speculate all \ -arch host -DUNDEF_HAVE_GETHOSTBYNAME_R \
-o mysql mysql.o readline.o sql_string.o completion_hash.o \
../readline/libreadline.a -lcurses \
../libmysql/.libs/libmysqlclient.so -lm
cd ..
gnumake
gnumake install
scripts/mysql_install_db
2.6.6.7 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 behaviour (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 \
Chapter 2: Installing MySQL
151
-arch host
CXX=cxx -pthread
CXXFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed -speculate all \
-arch host -noexceptions -nortti
export CC CFLAGS CXX CXXFLAGS
./configure --prefix=/usr/mysql/mysql --with-mysqld-ldflags=-all-static \
--disable-shared --with-named-thread-libs="-lmach -lexc -lc"
In some versions of OSF/1, the alloca() function is broken. Fix this by removing the line
in ‘config.h’ that defines ’HAVE_ALLOCA’.
The alloca() function also may have an incorrect prototype in /usr/include/alloca.h.
This warning resulting from this can be ignored.
configure will use the following thread libraries automatically: --with-named-threadlibs="-lpthread -lmach -lexc -lc".
When using gcc, you can also try running configure like this:
shell> 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:
shell> CFLAGS=-DDONT_USE_THR_ALARM \
CXXFLAGS=-DDONT_USE_THR_ALARM \
./configure ...
This doesn’t affect the performance of MySQL, but has the side effect that you can’t kill
clients that are “sleeping” on a connection with mysqladmin kill or mysqladmin shutdown.
Instead, the client will die when it issues its next command.
With gcc 2.95.2, you will probably run into the following compile error:
sql_acl.cc:1456: Internal compiler error in ‘scan_region’, at except.c:2566
Please submit a full bug report.
To fix this you should change to the sql directory and do a “cut and paste” of the last gcc
line, but change -O3 to -O0 (or add -O0 immediately after gcc if you don’t have any -O
option on your compile line). After this is done you can just change back to the top-level
directly and run make again.
2.6.6.8 SGI Irix Notes
If you are using Irix Version 6.5.3 or newer mysqld will only be able to create threads if you
run it as a user with CAP_SCHED_MGT privileges (like root) or give the mysqld server this
privilege with the following shell command:
shell> 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.
152
MySQL Technical Reference for Version 4.1.1-alpha
SGI recommends that you install all of the patches on this page as a set:
http://support.sgi.com/surfzone/patches/patchset/6.2_indigo.rps.html
At the very minimum, you should install the latest kernel rollup, the latest rld rollup, and
the latest libc rollup.
You definitely need all the POSIX patches on this page, for pthreads support:
http://support.sgi.com/surfzone/patches/patchset/6.2_posix.rps.html
If you get the something like the following error when compiling ‘mysql.cc’:
"/usr/include/curses.h", line 82: error(1084): invalid combination of type
Type the following in the top-level directory of your MySQL source tree:
shell> extra/replace bool curses_bool < /usr/include/curses.h \
> include/curses.h
shell> 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 2-to-10-fold
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.6.6.9 SCO Notes
The current port is tested only on “sco3.2v5.0.5”, “sco3.2v5.0.6” and “sco3.2v5.0.7” systems.
There has also been a lot of progress on a port to “sco 3.2v4.2”.
For the moment the recommended compiler on OpenServer is gcc 2.95.2. With this you
should be able to compile MySQL with just:
CC=gcc CXX=gcc ./configure ... (options)
1. For OpenServer 5.0.x you need to use gcc-2.95.2p1 or newer from the Skunkware.
http://www.sco.com/skunkware/ and choose browser OpenServer packages or by ftp
to ftp2.caldera.com in the pub/skunkware/osr5/devtools/gcc directory.
2. You need the port of GCC 2.5.x for this product and the Development system. They
are required on this version of SCO Unix. You cannot just use the GCC Dev system.
Chapter 2: Installing MySQL
153
3. 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 http://www.mysql.com/Downloads/SCO/FSU-threads-3.5c.tar
4. FSU Pthreads can be compiled with SCO Unix 4.2 with tcpip. Or 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 ODT or OS 3.0 you will need a good port of GCC 2.5.x
There are a lot of problems without a good port. The port for this product requires
the SCO Unix Development system. Without it, you are missing the libraries and the
linker that is needed.
5. To build FSU Pthreads on your system, do the following:
1. Run ./configure in the ‘threads/src’ directory and select the SCO OpenServer
option. This command copies ‘Makefile.SCO5’ to ‘Makefile’.
2. Run make.
3. To install in the default ‘/usr/include’ directory, login as root, then cd to the
‘thread/src’ directory, and run make install.
6. Remember to use GNU make when making MySQL.
7. If you don’t start mysqld_safe as root, you probably will get only the default 110
open files per process. mysqld will write a note about this in the log file.
8. With SCO 3.2V5.0.5, you should use FSU Pthreads version 3.5c or newer. You should
also use gcc 2.95.2 or newer!
The following configure command should work:
shell> ./configure --prefix=/usr/local/mysql --disable-shared
9. With SCO 3.2V4.2, you should use FSU Pthreads version 3.5c or newer. The following
configure command should work:
shell> CFLAGS="-D_XOPEN_XPG4" CXX=gcc CXXFLAGS="-D_XOPEN_XPG4" \
./configure \
--prefix=/usr/local/mysql \
--with-named-thread-libs="-lgthreads -lsocket -lgen -lgthreads" \
--with-named-curses-libs="-lcurses"
You may get some problems with some include files. In this case, you can find new SCOspecific include files at http://www.mysql.com/Downloads/SCO/SCO-3.2v4.2-includes.tar.gz.
You should unpack this file in the ‘include’ directory of your MySQL source tree.
SCO development notes:
• MySQL should automatically detect FSU Pthreads and link mysqld with -lgthreads
-lsocket -lgthreads.
• The SCO development libraries are re-entrant in FSU Pthreads. SCO claim’s that its
libraries’ functions are re-entrant, so they must be reentrant 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 http://www.mysql.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().
154
MySQL Technical Reference for Version 4.1.1-alpha
• 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.
• SCO provides Operating Systems Patches at ftp://ftp.sco.com/pub/openserver5
for OpenServer 5.0.x
• SCO provides secruity 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/openser
or ftp://stage.caldera.com/pub/security/openserver/CSSA-2001-SCO.10/ as
both libsocket.so.2 and libresolv.so.1 with instructions for installing on pre-OSR506
systems.
It’s probably a good idea to install the above patches before trying to compile/use
MySQL.
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
This is because the Perl dynaloader will not load the DBI modules if they were compiled
with icc or cc.
Perl works best when compiled with cc.
2.6.6.10 SCO UnixWare Version 7.1.x Notes
You must use a version of MySQL at least as recent as Version 3.22.13 and of UnixWare
7.1.0 because these version fixes some portability and OS problems under UnixWare.
We have been able to compile MySQL with the following configure command on UnixWare
Version 7.1.x:
Chapter 2: Installing MySQL
155
CC=cc CXX=CC ./configure --prefix=/usr/local/mysql
If you want to use gcc, you must use gcc 2.95.2 or newer.
CC=gcc CXX=g++ ./configure --prefix=/usr/local/mysql
1. SCO provides Operating Systems Patches at ftp://ftp.sco.com/pub/unixware7 for
UnixWare 7.1.1 and 7.1.3 ftp://ftp.sco.com/pub/openunix8 for OpenUNIX 8.0.0
2. SCO provides information about Security Fixes at ftp://ftp.sco.com/pub/security/OpenUNIX
for OpenUNIX ftp://ftp.sco.com/pub/security/UnixWare for UnixWare
2.6.7 OS/2 Notes
MySQL uses quite a few open files. Because of this, you should add something like the
following to your ‘CONFIG.SYS’ file:
SET EMXOPT=-c -n -h1024
If you don’t do this, you will probably run into the following error:
File ’xxxx’ not found (Errcode: 24)
When using MySQL with OS/2 Warp 3, FixPack 29 or above is required. With OS/2 Warp
4, FixPack 4 or above is required. This is a requirement of the Pthreads library. MySQL
must be installed in a partition that supports long filenames such as HPFS, FAT32, etc.
The ‘INSTALL.CMD’ script must be run from OS/2’s own ‘CMD.EXE’ and may not work with
replacement shells such as ‘4OS2.EXE’.
The ‘scripts/mysql-install-db’ script has been renamed. It is now called ‘install.cmd’
and is a REXX script, which will set up the default MySQL security settings and create
the WorkPlace Shell icons for MySQL.
Dynamic module support is compiled in but not fully tested. Dynamic modules should be
compiled using the Pthreads run-time library.
gcc -Zdll -Zmt -Zcrtdll=pthrdrtl -I../include -I../regex -I.. \
-o example udf_example.cc -L../lib -lmysqlclient udf_example.def
mv example.dll example.udf
Note: Due to limitations in OS/2, UDF module name stems must not exceed 8 characters.
Modules are stored in the ‘/mysql2/udf’ directory; the safe-mysqld.cmd script will put this
directory in the BEGINLIBPATH environment variable. When using UDF modules, specified
extensions are ignored—it is assumed to be ‘.udf’. For example, in Unix, the shared module
might be named ‘example.so’ and you would load a function from it like this:
mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME "example.so";
In OS/2, the module would be named ‘example.udf’, but you would not specify the module
extension:
mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME "example";
2.6.8 Novell NetWare Notes
Porting MySQL to NetWare was an effort spearheaded by Novell. Novell customers will be
pleased to note that NetWare 6.5 will ship with bundled MySQL binaries, complete with
an automatic commercial use license for all servers running that version of NetWare.
156
MySQL Technical Reference for Version 4.1.1-alpha
See Section 2.1.4 [NetWare installation], page 70.
MySQL for NetWare is compiled using a combination of Metrowerks CodeWarrior for
NetWare and special cross-compilation versions of the GNU autotools. Check back here in
the future for more information on building and optimising MySQL for NetWare.
2.6.9 BeOS Notes
We have in the past talked with some BeOS developers that have said that MySQL is 80%
ported to BeOS, but we haven’t heard from them in a while.
2.7 Perl Installation Comments
2.7.1 Installing Perl on Unix
Perl support for MySQL is provided by means of the DBI/DBD client interface. See Section 11.5 [Perl], page 827. The Perl DBD/DBI client code requires Perl Version 5.004 or later.
The interface will not work if you have an older version of Perl.
MySQL Perl support also requires that you’ve installed MySQL client programming support. If you installed MySQL from RPM files, client programs are in the client RPM, but
client programming support is in the developer RPM. Make sure you’ve installed the latter
RPM.
As of Version 3.22.8, Perl support is distributed separately from the main MySQL distribution. If you want to install Perl support, the files you will need can be obtained from
http://www.mysql.com/downloads/api-dbi.html.
The Perl distributions are provided as compressed tar archives and have names like
‘MODULE-VERSION.tar.gz’, where MODULE is the module name and VERSION is the version
number. You should get the Data-Dumper, DBI, and DBD-mysql distributions and install
them in that order. The installation procedure is shown here. The example shown is for
the Data-Dumper module, but the procedure is the same for all three distributions:
1. Unpack the distribution into the current directory:
shell> gunzip < Data-Dumper-VERSION.tar.gz | tar xvf This command creates a directory named ‘Data-Dumper-VERSION’.
2. Change into the top-level directory of the unpacked distribution:
shell> cd Data-Dumper-VERSION
3. Build the distribution and compile everything:
shell> perl Makefile.PL
shell> make
shell> make test
shell> make install
The make test command is important because it verifies that the module is working. Note
that when you run that command during the DBD-mysql installation to exercise the interface
code, the MySQL server must be running or the test will fail.
Chapter 2: Installing MySQL
157
It is a good idea to rebuild and reinstall the DBD-mysql distribution whenever you install a
new release of MySQL, particularly if you notice symptoms such as that all your DBI scripts
fail after you upgrade MySQL.
If you don’t have the right to install Perl modules in the system directory or if you want to
install local Perl modules, the following reference may help you:
http://servers.digitaldaze.com/extensions/perl/modules.html#modules
Look under the heading Installing New Modules that Require Locally Installed
Modules.
2.7.2 Installing ActiveState Perl on Windows
On Windows, you should do the following to install the MySQL DBD module with ActiveState Perl:
• Get ActiveState Perl from http://www.activestate.com/Products/ActivePerl/
and install it.
• Open a console window (a “DOS window”).
• If required, set the HTTP_proxy variable. For example, you might try:
set HTTP_proxy=my.proxy.com:3128
• Start the PPM program:
C:\> c:\perl\bin\ppm.pl
• If you have not already done so, install DBI:
ppm> install DBI
• If this succeeds, run the following command:
install \
ftp://ftp.de.uu.net/pub/CPAN/authors/id/JWIED/DBD-mysql-1.2212.x86.ppd
The above should work at least with ActiveState Perl Version 5.6.
If you can’t get the above to work, you should instead install the MyODBC driver and connect
to the MySQL server through ODBC:
use DBI;
$dbh= DBI->connect("DBI:ODBC:$dsn",$user,$password) ||
die "Got error $DBI::errstr when connecting to $dsn\n";
2.7.3 Problems Using the Perl DBI/DBD Interface
If Perl reports that it can’t find the ‘../mysql/mysql.so’ module, then the problem is
probably that Perl can’t locate the shared library ‘libmysqlclient.so’.
You can fix this by any 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’).
158
MySQL Technical Reference for Version 4.1.1-alpha
• On Linux you can add the pathname of the directory where ‘libmysqlclient.so’ is
located to the ‘/etc/ld.so.conf’ file.
• Add the pathname of the directory where ‘libmysqlclient.so’ is located to the LD_
RUN_PATH environment variable.
If you get the following errors from DBD-mysql, you are probably using gcc (or using an old
binary compiled with gcc):
/usr/bin/perl: can’t resolve symbol ’__moddi3’
/usr/bin/perl: can’t resolve symbol ’__divdi3’
Add -L/usr/lib/gcc-lib/... -lgcc to the link command when the ‘mysql.so’ library
gets built (check the output from make for ‘mysql.so’ when you compile the Perl client).
The -L option should specify the pathname of the directory where ‘libgcc.a’ is located on
your system.
Another cause of this problem may be that Perl and MySQL aren’t both compiled with
gcc. In this case, you can solve the mismatch by compiling both with gcc.
If you get 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.
it means that you need to add the -lz compression library to the link line. This 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 use the Perl module on a system that doesn’t support dynamic linking (like
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:
shell> LD_LIBRARY_PATH=/lib:/usr/lib:/usr/local/lib:/usr/progressive/lib
or
shell> LD_LIBRARY_PATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
/usr/progressive/lib:/usr/skunk/lib
shell> LIBPATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
/usr/progressive/lib:/usr/skunk/lib
shell> 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:
Chapter 2: Installing MySQL
159
shell> perl Makefile.PL -static -config
shell> make
shell> make install
shell> make perl
Then you must install the new Perl. The output of make perl will indicate the exact make
command you will need to execute to perform the installation. On SCO, this is make -f
Makefile.aperl inst_perl MAP_TARGET=perl.
Next, use the just-created Perl to create another Perl that also includes a statically linked
DBD::mysql by running these commands in the directory where your DBD-mysql distribution
is located:
shell> perl Makefile.PL -static -config
shell> make
shell> make install
shell> make perl
Finally, you should install this new Perl. Again, the output of make perl indicates the
command to use.
160
MySQL Technical Reference for Version 4.1.1-alpha
3 MySQL Tutorial
This chapter provides a tutorial introduction to MySQL by showing how to use the mysql
client program to create and use a simple database. mysql (sometimes referred to as the
“terminal monitor” or just “monitor”) is an interactive program that allows you to connect
to a MySQL server, run queries, and view the results. mysql may also be used in batch
mode: you place your queries in a file beforehand, then tell mysql to execute the contents
of the file. Both ways of using mysql are covered here.
To see a list of options provided by mysql, invoke it with the --help option:
shell> mysql --help
This chapter assumes that mysql is installed on your machine and that a MySQL server is
available to which you can connect. If this is not true, contact your MySQL administrator.
(If you are the administrator, you will need to consult other sections of this manual.)
This chapter describes the entire process of setting up and using a database. If you are
interested only in accessing an already-existing database, you may want to skip over the
sections that describe how to create the database and the tables it contains.
Because this chapter is tutorial in nature, many details are necessarily omitted. Consult
the relevant sections of the manual for more information on the topics covered here.
3.1 Connecting to and Disconnecting from the Server
To connect to the server, you’ll usually need to provide a MySQL 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’ll also need to specify a hostname. Contact your administrator
to find out what connection parameters you should use to connect (that is, what host, 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: ********
The ******** represents your password; enter it when mysql displays the Enter password:
prompt.
If that works, you should see some introductory information followed by a mysql> prompt:
shell> mysql -h host -u user -p
Enter password: ********
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 25338 to server version: 4.0.14-log
Type ’help;’ or ’\h’ for help. Type ’\c’ to clear the buffer.
mysql>
The prompt tells you that mysql is ready for you to enter commands.
Some MySQL installations allow users to connect as the anonymous (unnamed) user to the
server running on the local host. If this is the case on your machine, you should be able to
connect to that server by invoking mysql without any options:
Chapter 3: MySQL Tutorial
161
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 you are connected to the server. They
indicate this by the mysql> prompt.
3.2 Entering Queries
Make sure you are connected to the server, as discussed in the previous section. Doing so
will not in itself select any database to work with, but that’s okay. At this point, it’s more
important to find out a little about how to issue queries than to jump right in creating
tables, loading data into them, and retrieving data from them. This section describes the
basic principles of entering commands, using several queries you can try out to familiarise
yourself with how mysql works.
Here’s a simple command that asks the server to tell you its version number and the current
date. Type it in as shown here following the mysql> prompt and press Enter:
mysql> SELECT VERSION(), CURRENT_DATE;
+--------------+--------------+
| VERSION()
| CURRENT_DATE |
+--------------+--------------+
| 3.22.20a-log | 1999-03-19
|
+--------------+--------------+
1 row in set (0.01 sec)
mysql>
This query illustrates several things about mysql:
• A command normally consists of an SQL statement followed by a semicolon. (There
are some exceptions where a semicolon may be omitted. QUIT, mentioned earlier, is
one of them. We’ll get to others later.)
• When you issue a command, mysql sends it to the server for execution and displays
the results, then prints another mysql> prompt to indicate that it is ready for another
command.
• mysql displays query output in tabular form (rows and columns). The first row contains
labels for the columns. The rows following are the query results. Normally, column
labels are the names of the columns you fetch from database tables. If you’re retrieving
the value of an expression rather than a table column (as in the example just shown),
mysql labels the column using the expression itself.
• mysql shows how many rows were returned and how long the query took to execute,
which gives you a rough idea of server performance. These values are imprecise because
they represent wall clock time (not CPU or machine time), and because they are affected
by factors such as server load and network latency. (For brevity, the “rows in set” line
is not shown in the remaining examples in this chapter.)
162
MySQL Technical Reference for Version 4.1.1-alpha
Keywords may be entered in any lettercase. The following queries are equivalent:
mysql> SELECT VERSION(), CURRENT_DATE;
mysql> select version(), current_date;
mysql> SeLeCt vErSiOn(), current_DATE;
Here’s another query. It demonstrates that you can use mysql as a simple calculator:
mysql> SELECT SIN(PI()/4), (4+1)*5;
+-------------+---------+
| SIN(PI()/4) | (4+1)*5 |
+-------------+---------+
|
0.707107 |
25 |
+-------------+---------+
The queries shown thus far have been relatively short, single-line statements. You can even
enter multiple statements on a single line. Just end each one with a semicolon:
mysql> SELECT VERSION(); SELECT NOW();
+--------------+
| VERSION()
|
+--------------+
| 3.22.20a-log |
+--------------+
+---------------------+
| NOW()
|
+---------------------+
| 1999-03-19 00:15:33 |
+---------------------+
A command need not be given all on a single line, so lengthy commands that require several
lines are not a problem. mysql determines where your statement ends by looking for the
terminating semicolon, not by looking for the end of the input line. (In other words, mysql
accepts free-format input: it collects input lines but does not execute them until it sees the
semicolon.)
Here’s a simple multiple-line statement:
mysql> SELECT
-> USER()
-> ,
-> CURRENT_DATE;
+--------------------+--------------+
| USER()
| CURRENT_DATE |
+--------------------+--------------+
| [email protected] | 1999-03-18
|
+--------------------+--------------+
In this example, notice how the prompt changes from mysql> to -> after you enter the first
line of a multiple-line query. This is how mysql indicates that it hasn’t seen a complete
statement and is waiting for the rest. The prompt is your friend, because it provides valuable
feedback. If you use that feedback, you will always be aware of what mysql is waiting for.
Chapter 3: MySQL Tutorial
163
If you decide you don’t want to execute a command that you are in the process of entering,
cancel it by typing \c:
mysql> SELECT
-> USER()
-> \c
mysql>
Here, too, notice the prompt. It switches back to mysql> after you type \c, providing
feedback to indicate that mysql is ready for a new command.
The following table shows each of the prompts you may see and summarises what they
mean about the state that mysql is in:
Prompt
Meaning
mysql>
Ready for new command.
->
Waiting for next line of multiple-line command.
’>
Waiting for next line, collecting a string that begins with a single quote
(‘’’).
">
Waiting for next line, collecting a string that begins with a double
quote (‘"’).
‘>
Waiting for next line, collecting an identifier that begins with a backtick
(‘‘’).
Multiple-line statements commonly occur by accident when you intend to issue a command
on a single line, but forget the terminating semicolon. In this case, mysql waits for more
input:
mysql> SELECT USER()
->
If this happens to you (you think you’ve entered a statement but the only response is a
-> prompt), most likely mysql is waiting for the semicolon. If you don’t notice what the
prompt is telling you, you might sit there for a while before realising what you need to do.
Enter a semicolon to complete the statement, and mysql will execute it:
mysql> SELECT USER()
-> ;
+--------------------+
| USER()
|
+--------------------+
| [email protected] |
+--------------------+
The ’> and "> prompts occur during string collection. In MySQL, you can write strings
surrounded by either ‘’’ or ‘"’ characters (for example, ’hello’ or "goodbye"), and mysql
lets you enter strings that span multiple lines. When you see a ’> or "> prompt, it means
that you’ve entered a line containing a string that begins with a ‘’’ or ‘"’ quote character,
but have not yet entered the matching quote that terminates the string. That’s fine if you
really are entering a multiple-line string, but how likely is that? Not very. More often,
the ’> and "> prompts indicate that you’ve inadvertantly left out a quote character. For
example:
mysql> SELECT * FROM my_table WHERE name = "Smith AND age < 30;
">
164
MySQL Technical Reference for Version 4.1.1-alpha
If you enter this SELECT statement, then press Enter and wait for the result, nothing will
happen. Instead of wondering why this query takes so long, notice the clue provided by the
"> prompt. It tells you that mysql expects to see the rest of an unterminated string. (Do
you see the error in the statement? The string "Smith is missing the second quote.)
At this point, what do you do? The simplest thing is to cancel the command. However,
you cannot just type \c in this case, because mysql interprets it as part of the string that
it is collecting! Instead, enter the closing quote character (so mysql knows you’ve finished
the string), then type \c:
mysql> SELECT * FROM my_table WHERE name = "Smith AND age < 30;
"> "\c
mysql>
The prompt changes back to mysql>, indicating that mysql is ready for a new command.
The ‘> prompt is similar to th ’> and "> prompts, but indicates that you have begun but
not completed a backtick-quoted identifier.
It’s important to know what the ’>, ">, and ‘> prompts signify, because if you mistakenly
enter an unterminated string, any further lines you type will appear to be ignored by
mysql—including a line containing QUIT! This can be quite confusing, especially if you
don’t know that you need to supply the terminating quote before you can cancel the current
command.
3.3 Creating and Using a Database
Now that you know how to enter commands, it’s time to access a database.
Suppose you have several pets in your home (your menagerie) and you’d like to keep track
of various types of information about them. You can do so by creating tables to hold your
data and loading them with the desired information. Then you can answer different sorts
of questions about your animals by retrieving data from the tables. This section shows you
how to:
• Create a database
• Create a table
• Load data into the table
• Retrieve data from the table in various ways
• Use multiple tables
The menagerie database will be simple (deliberately), but it is not difficult to think
of real-world situations in which a similar type of database might be used. For
example, a database like this could be used by a farmer to keep track of livestock,
or by a veterinarian to keep track of patient records.
A menagerie distribution
containing some of the queries and sample data used in the following sections can be
obtained from the MySQL web site. It’s available in either compressed tar format
(http://www.mysql.com/Downloads/Contrib/Examples/menagerie.tar.gz) or Zip
format (http://www.mysql.com/Downloads/Contrib/Examples/menagerie.zip).
Use the SHOW statement to find out what databases currently exist on the server:
Chapter 3: MySQL Tutorial
165
mysql> SHOW DATABASES;
+----------+
| Database |
+----------+
| mysql
|
| test
|
| tmp
|
+----------+
The list of databases is probably different on your machine, but the mysql and test
databases are likely to be among them. The mysql database is required because it describes user access privileges. The test database is often provided as a workspace for users
to try things out.
Note that you may not see all databases if you don’t have the SHOW DATABASES privilege.
See Section 4.4.1 [GRANT], page 242.
If the test database exists, try to access it:
mysql> USE test
Database changed
Note that USE, like QUIT, does not require a semicolon. (You can terminate such statements
with a semicolon if you like; it does no harm.) The USE statement is special in another way,
too: it must be given on a single line.
You can use the test database (if you have access to it) for the examples that follow, but
anything you create in that database can be removed by anyone else with access to it. For
this reason, you should probably ask your MySQL administrator for permission to use a
database of your own. Suppose you want to call yours menagerie. The administrator needs
to execute a command like this:
mysql> GRANT ALL ON menagerie.* TO ’your_mysql_name’@’your_client_host’;
where your_mysql_name is the MySQL 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.)
Creating a database does not select it for use; you must do that explicitly. To make
menagerie the current database, use this command:
mysql> USE menagerie
Database changed
Your database needs to be created only once, but you must select it for use each time you
begin a mysql session. You can do this by issuing a USE statement as shown in the example.
166
MySQL Technical Reference for Version 4.1.1-alpha
Alternatively, you can select the database on the command-line when you invoke mysql.
Just specify its name after any connection parameters that you might need to provide. For
example:
shell> mysql -h host -u user -p menagerie
Enter password: ********
Note that menagerie is not your password on the command just shown. If you want to
supply your password on the command-line after the -p option, you must do so with no
intervening space (for example, as -pmypassword, not as -p mypassword). However, putting
your password on the command-line is not recommended, because doing so exposes it to
snooping by other users logged in on your machine.
3.3.2 Creating a Table
Creating the database is the easy part, but at this point it’s empty, as SHOW TABLES will
tell you:
mysql> SHOW TABLES;
Empty set (0.00 sec)
The harder part is deciding what the structure of your database should be: what tables you
will need and what columns will be in each of them.
You’ll want a table that contains a record for each of your pets. This can be called the pet
table, and it should contain, as a bare minimum, each animal’s name. Because the name
by itself is not very interesting, the table should contain other information. For example,
if more than one person in your family keeps pets, you might want to list each animal’s
owner. You might also want to record some basic descriptive information such as species
and sex.
How about age? That might be of interest, but it’s not a good thing to store in a database.
Age changes as time passes, which means you’d have to update your records often. Instead,
it’s better to store a fixed value such as date of birth. Then, whenever you need age, you can
calculate it as the difference between the current date and the birth date. MySQL provides
functions for doing date arithmetic, so this is not difficult. Storing birth date rather than
age has other advantages, too:
• You can use the database for tasks such as generating reminders for upcoming pet
birthdays. (If you think this type of query is somewhat silly, note that it is the same
question you might ask in the context of a business database to identify clients to whom
you’ll soon need to send out birthday greetings, for that computer-assisted personal
touch.)
• You can calculate age in relation to dates other than the current date. For example, if
you store death date in the database, you can easily calculate how old a pet was when
it died.
You can probably think of other types of information that would be useful in the pet table,
but the ones identified so far are sufficient for now: name, owner, species, sex, birth, and
death.
Use a CREATE TABLE statement to specify the layout of your table:
Chapter 3: MySQL Tutorial
167
mysql> CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20),
-> species VARCHAR(20), sex CHAR(1), birth DATE, death DATE);
VARCHAR is a good choice for the name, owner, and species columns because the column
values will vary in length. The lengths of those columns need not all be the same, and
need not be 20. You can pick any length from 1 to 255, whatever seems most reasonable to
you. (If you make a poor choice and it turns out later that you need a longer field, MySQL
provides an ALTER TABLE statement.)
Several types of values can be chosen to represent sex in animal records, such as "m" and
"f", or perhaps "male" and "female". It’s simplest to use the single characters "m" and
"f".
The use of the DATE datatype for the birth and death columns is a fairly obvious choice.
Now that you have created a table, SHOW TABLES should produce some output:
mysql> SHOW TABLES;
+---------------------+
| Tables in menagerie |
+---------------------+
| pet
|
+---------------------+
To verify that your table was created the way you expected, use a DESCRIBE statement:
mysql> DESCRIBE pet;
+---------+-------------+------+-----+---------+-------+
| Field
| Type
| Null | Key | Default | Extra |
+---------+-------------+------+-----+---------+-------+
| name
| varchar(20) | YES |
| NULL
|
|
| owner
| varchar(20) | YES |
| NULL
|
|
| species | varchar(20) | YES |
| NULL
|
|
| sex
| char(1)
| YES |
| NULL
|
|
| birth
| date
| YES |
| NULL
|
|
| death
| date
| YES |
| NULL
|
|
+---------+-------------+------+-----+---------+-------+
You can use DESCRIBE any time, for example, if you forget the names of the columns in
your table or what types they have.
3.3.3 Loading Data into a Table
After creating your table, you need to populate it. The LOAD DATA and INSERT statements
are useful for this.
Suppose 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
Fluffy
Claws
Buffy
Fang
owner
Harold
Gwen
Harold
Benny
species
cat
cat
dog
dog
sex
f
m
f
m
birth
1993-02-04
1994-03-17
1989-05-13
1990-08-27
death
168
MySQL Technical Reference for Version 4.1.1-alpha
Bowser
Chirpy
Whistler
Slim
Diane
Gwen
Gwen
Benny
dog
bird
bird
snake
m
f
m
1979-08-31
1998-09-11
1997-12-09
1996-04-29
1995-07-29
Because you are beginning with an empty table, an easy way to populate it is to create a
text file containing a row for each of your animals, then load the contents of the file into
the table with a single statement.
You could create a text file ‘pet.txt’ containing one record per line, with values separated
by tabs, and given in the order in which the columns were listed in the CREATE TABLE
statement. For missing values (such as unknown sexes or death dates for animals that are
still living), you can use NULL values. To represent these in your text file, use \N (backslash,
capital-N). For example, the record for Whistler the bird would look like this (where the
whitespace between values is a single tab character):
name
owner
Whistler Gwen
species sex birth
bird
\N 1997-12-09
death
\N
To load the text file ‘pet.txt’ into the pet table, use this command:
mysql> LOAD DATA LOCAL INFILE "pet.txt" INTO TABLE pet;
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 4.3.4 [LOAD DATA LOCAL], page 221 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 Diane gets a new hamster named Puffball.
You could add a new record using an INSERT statement like this:
mysql> INSERT INTO pet
-> VALUES (’Puffball’,’Diane’,’hamster’,’f’,’1999-03-30’,NULL);
Note that string and date values are specified as quoted strings here. Also, with INSERT,
you can insert NULL directly to represent a missing value. You do not use \N like you do
with LOAD DATA.
From this example, you should be able to see that there would be a lot more typing involved
to load your records initially using several INSERT statements rather than a single LOAD DATA
statement.
3.3.4 Retrieving Information from a Table
The SELECT statement is used to pull information from a table. The general form of the
statement is:
SELECT what_to_select
FROM which_table
WHERE conditions_to_satisfy;
Chapter 3: MySQL Tutorial
169
what_to_select indicates what you want to see. This can be a list of columns, or * to
indicate “all columns.” which_table indicates the table from which you want to retrieve
data. The WHERE clause is optional. If it’s present, conditions_to_satisfy specifies
conditions that rows must satisfy to qualify for retrieval.
3.3.4.1 Selecting All Data
The simplest form of SELECT retrieves everything from a table:
mysql> SELECT * FROM pet;
+----------+--------+---------+------+------------+------------+
| name
| owner | species | sex | birth
| death
|
+----------+--------+---------+------+------------+------------+
| Fluffy
| Harold | cat
| f
| 1993-02-04 | NULL
|
| Claws
| Gwen
| cat
| m
| 1994-03-17 | NULL
|
| Buffy
| Harold | dog
| f
| 1989-05-13 | NULL
|
| Fang
| Benny | dog
| m
| 1990-08-27 | NULL
|
| Bowser
| Diane | dog
| m
| 1979-08-31 | 1995-07-29 |
| Chirpy
| Gwen
| bird
| f
| 1998-09-11 | NULL
|
| Whistler | Gwen
| bird
| NULL | 1997-12-09 | NULL
|
| Slim
| Benny | snake
| m
| 1996-04-29 | NULL
|
| Puffball | Diane | hamster | f
| 1999-03-30 | NULL
|
+----------+--------+---------+------+------------+------------+
This form of SELECT is useful if you want to review your entire table, for instance, after
you’ve just loaded it with your initial dataset. For example, you may happen to think
that the birth date for Bowser doesn’t seem quite right. Consulting your original pedigree
papers, you find that the correct birth year should be 1989, not 1979.
There are least a couple of ways to fix this:
• Edit the file ‘pet.txt’ to correct the error, then empty the table and reload it using
DELETE 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.
170
MySQL Technical Reference for Version 4.1.1-alpha
You can select only particular rows from your table. For example, if you want to verify the
change that you made to Bowser’s birth date, select Bowser’s record like this:
mysql> SELECT * FROM pet WHERE name = "Bowser";
+--------+-------+---------+------+------------+------------+
| name
| owner | species | sex | birth
| death
|
+--------+-------+---------+------+------------+------------+
| Bowser | Diane | dog
| m
| 1989-08-31 | 1995-07-29 |
+--------+-------+---------+------+------------+------------+
The output confirms that the year is correctly recorded now as 1989, not 1979.
String comparisons normally are case-insensitive, so you can specify the name as "bowser",
"BOWSER", etc. The query result will be the same.
You can specify conditions on any column, not just name. For example, if you want to know
which animals were born after 1998, test the birth column:
mysql> SELECT * FROM pet WHERE birth >= "1998-1-1";
+----------+-------+---------+------+------------+-------+
| name
| owner | species | sex | birth
| death |
+----------+-------+---------+------+------------+-------+
| Chirpy
| Gwen | bird
| f
| 1998-09-11 | NULL |
| Puffball | Diane | hamster | f
| 1999-03-30 | NULL |
+----------+-------+---------+------+------------+-------+
You can combine conditions, for example, to locate female dogs:
mysql> SELECT * FROM pet WHERE species = "dog" AND sex = "f";
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
The preceding query uses the AND logical operator. There is also an OR operator:
mysql> SELECT * FROM pet WHERE species = "snake" OR species = "bird";
+----------+-------+---------+------+------------+-------+
| name
| owner | species | sex | birth
| death |
+----------+-------+---------+------+------------+-------+
| Chirpy
| Gwen | bird
| f
| 1998-09-11 | NULL |
| Whistler | Gwen | bird
| NULL | 1997-12-09 | NULL |
| Slim
| Benny | snake
| m
| 1996-04-29 | NULL |
+----------+-------+---------+------+------------+-------+
AND and OR may be intermixed, though AND has higher precedence than OR. If you use both
operators, it’s a good idea to use parentheses to indicate explicitly how conditions should
be grouped:
mysql> SELECT * FROM pet WHERE (species = "cat" AND sex = "m")
-> OR (species = "dog" AND sex = "f");
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
Chapter 3: MySQL Tutorial
171
| Claws | Gwen
| cat
| m
| 1994-03-17 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
3.3.4.3 Selecting Particular Columns
If you don’t want to see entire rows from your table, just name the columns in which you’re
interested, separated by commas. For example, if you want to know when your animals
were born, select the name and birth columns:
mysql> SELECT name, birth FROM pet;
+----------+------------+
| name
| birth
|
+----------+------------+
| Fluffy
| 1993-02-04 |
| Claws
| 1994-03-17 |
| Buffy
| 1989-05-13 |
| Fang
| 1990-08-27 |
| Bowser
| 1989-08-31 |
| Chirpy
| 1998-09-11 |
| Whistler | 1997-12-09 |
| Slim
| 1996-04-29 |
| Puffball | 1999-03-30 |
+----------+------------+
To find out who owns pets, use this query:
mysql> SELECT owner FROM pet;
+--------+
| owner |
+--------+
| Harold |
| Gwen
|
| Harold |
| Benny |
| Diane |
| Gwen
|
| Gwen
|
| Benny |
| Diane |
+--------+
However, notice that the query simply retrieves the owner field from each record, and some
of them appear more than once. To minimise the output, retrieve each unique output record
just once by adding the keyword DISTINCT:
mysql> SELECT DISTINCT owner FROM pet;
+--------+
| owner |
+--------+
172
MySQL Technical Reference for Version 4.1.1-alpha
| Benny |
| Diane |
| Gwen
|
| Harold |
+--------+
You can use a WHERE clause to combine row selection with column selection. For example,
to get birth dates for dogs and cats only, use this query:
mysql> SELECT name, species, birth FROM pet
-> WHERE species = "dog" OR species = "cat";
+--------+---------+------------+
| name
| species | birth
|
+--------+---------+------------+
| Fluffy | cat
| 1993-02-04 |
| Claws | cat
| 1994-03-17 |
| Buffy | dog
| 1989-05-13 |
| Fang
| dog
| 1990-08-27 |
| Bowser | dog
| 1989-08-31 |
+--------+---------+------------+
3.3.4.4 Sorting Rows
You may have noticed in the preceding examples that the result rows are displayed in no
particular order. It’s often easier to examine query output when the rows are sorted in
some meaningful way. To sort a result, use an ORDER BY clause.
Here are animal birthdays, sorted by date:
mysql> SELECT name, birth FROM pet ORDER BY birth;
+----------+------------+
| name
| birth
|
+----------+------------+
| Buffy
| 1989-05-13 |
| Bowser
| 1989-08-31 |
| Fang
| 1990-08-27 |
| Fluffy
| 1993-02-04 |
| Claws
| 1994-03-17 |
| Slim
| 1996-04-29 |
| Whistler | 1997-12-09 |
| Chirpy
| 1998-09-11 |
| Puffball | 1999-03-30 |
+----------+------------+
On character type columns, sorting—like all other comparison operations—is normally performed in a case-insensitive fashion. This means that the order will be undefined for columns
that are identical except for their case. You can force a case-sensitive sort for a column by
using the BINARY cast: ORDER BY BINARY col_name.
The default sort order is ascending, with smallest values first. To sort in reverse (descending)
order, add the DESC keyword to the name of the column you are sorting by:
Chapter 3: MySQL Tutorial
173
mysql> SELECT name, birth FROM pet ORDER BY birth DESC;
+----------+------------+
| name
| birth
|
+----------+------------+
| Puffball | 1999-03-30 |
| Chirpy
| 1998-09-11 |
| Whistler | 1997-12-09 |
| Slim
| 1996-04-29 |
| Claws
| 1994-03-17 |
| Fluffy
| 1993-02-04 |
| Fang
| 1990-08-27 |
| Bowser
| 1989-08-31 |
| Buffy
| 1989-05-13 |
+----------+------------+
You can sort on multiple columns, and you can sort columns in different directions. For
example, to sort by type of animal in ascending order, then by birth date within animal
type in descending order (youngest animals first), use the following query:
mysql> SELECT name, species, birth FROM pet ORDER BY species, birth DESC;
+----------+---------+------------+
| name
| species | birth
|
+----------+---------+------------+
| Chirpy
| bird
| 1998-09-11 |
| Whistler | bird
| 1997-12-09 |
| Claws
| cat
| 1994-03-17 |
| Fluffy
| cat
| 1993-02-04 |
| Fang
| dog
| 1990-08-27 |
| Bowser
| dog
| 1989-08-31 |
| Buffy
| dog
| 1989-05-13 |
| Puffball | hamster | 1999-03-30 |
| Slim
| snake
| 1996-04-29 |
+----------+---------+------------+
Note that the DESC keyword applies only to the column name immediately preceding it
(birth); it does not affect the species column sort order.
3.3.4.5 Date Calculations
MySQL provides several functions that you can use to perform calculations on dates, for
example, to calculate ages or extract parts of dates.
To determine how many years old each of your pets is, compute the difference in the year
part of the current date and the birth date, then subtract one if the current date occurs
earlier in the calendar year than the birth date. The following query shows, for each pet,
the birth date, the current date, and the age in years.
mysql> SELECT name, birth, CURDATE(),
-> (YEAR(CURDATE())-YEAR(birth))
-> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
174
MySQL Technical Reference for Version 4.1.1-alpha
-> AS age
-> FROM pet;
+----------+------------+------------+------+
| name
| birth
| CURDATE() | age |
+----------+------------+------------+------+
| Fluffy
| 1993-02-04 | 2003-08-19 |
10 |
| Claws
| 1994-03-17 | 2003-08-19 |
9 |
| Buffy
| 1989-05-13 | 2003-08-19 |
14 |
| Fang
| 1990-08-27 | 2003-08-19 |
12 |
| Bowser
| 1989-08-31 | 2003-08-19 |
13 |
| Chirpy
| 1998-09-11 | 2003-08-19 |
4 |
| Whistler | 1997-12-09 | 2003-08-19 |
5 |
| Slim
| 1996-04-29 | 2003-08-19 |
7 |
| Puffball | 1999-03-30 | 2003-08-19 |
4 |
+----------+------------+------------+------+
Here, YEAR() pulls out the year part of a date and RIGHT() pulls off the rightmost five characters that represent the MM-DD (calendar year) part of the date. The part of the expression
that compares the MM-DD values evaluates to 1 or 0, which adjusts the year difference down
a year if CURDATE() occurs earlier in the year than birth. The full expression is somewhat
ungainly, so an alias (age) is used to make the output column label more meaningful.
The query works, but the result could be scanned more easily if the rows were presented
in some order. This can be done by adding an ORDER BY name clause to sort the output by
name:
mysql> SELECT name, birth, CURDATE(),
-> (YEAR(CURDATE())-YEAR(birth))
-> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
-> AS age
-> FROM pet ORDER BY name;
+----------+------------+------------+------+
| name
| birth
| CURDATE() | age |
+----------+------------+------------+------+
| Bowser
| 1989-08-31 | 2003-08-19 |
13 |
| Buffy
| 1989-05-13 | 2003-08-19 |
14 |
| Chirpy
| 1998-09-11 | 2003-08-19 |
4 |
| Claws
| 1994-03-17 | 2003-08-19 |
9 |
| Fang
| 1990-08-27 | 2003-08-19 |
12 |
| Fluffy
| 1993-02-04 | 2003-08-19 |
10 |
| Puffball | 1999-03-30 | 2003-08-19 |
4 |
| Slim
| 1996-04-29 | 2003-08-19 |
7 |
| Whistler | 1997-12-09 | 2003-08-19 |
5 |
+----------+------------+------------+------+
To sort the output by age rather than name, just use a different ORDER BY clause:
mysql> SELECT name, birth, CURDATE(),
-> (YEAR(CURDATE())-YEAR(birth))
-> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
-> AS age
Chapter 3: MySQL Tutorial
175
-> FROM pet ORDER BY age;
+----------+------------+------------+------+
| name
| birth
| CURDATE() | age |
+----------+------------+------------+------+
| Chirpy
| 1998-09-11 | 2003-08-19 |
4 |
| Puffball | 1999-03-30 | 2003-08-19 |
4 |
| Whistler | 1997-12-09 | 2003-08-19 |
5 |
| Slim
| 1996-04-29 | 2003-08-19 |
7 |
| Claws
| 1994-03-17 | 2003-08-19 |
9 |
| Fluffy
| 1993-02-04 | 2003-08-19 |
10 |
| Fang
| 1990-08-27 | 2003-08-19 |
12 |
| Bowser
| 1989-08-31 | 2003-08-19 |
13 |
| Buffy
| 1989-05-13 | 2003-08-19 |
14 |
+----------+------------+------------+------+
A similar query can be used to determine age at death for animals that have died. You
determine which animals these are by checking whether the death value is NULL. Then, for
those with non-NULL values, compute the difference between the death and birth values:
mysql> SELECT name, birth, death,
-> (YEAR(death)-YEAR(birth)) - (RIGHT(death,5)<RIGHT(birth,5))
-> AS age
-> FROM pet WHERE death IS NOT NULL ORDER BY age;
+--------+------------+------------+------+
| name
| birth
| death
| age |
+--------+------------+------------+------+
| Bowser | 1989-08-31 | 1995-07-29 |
5 |
+--------+------------+------------+------+
The query uses death IS NOT NULL rather than death <> NULL because NULL is a special
value that cannot be compared using the usual comparison operators. This is discussed
later. See Section 3.3.4.6 [Working with NULL], page 176.
What if you want to know which animals have birthdays next month? For this type of
calculation, year and day are irrelevant; you simply want to extract the month part of the
birth column. MySQL provides several date-part extraction functions, such as YEAR(),
MONTH(), and DAYOFMONTH(). MONTH() is the appropriate function here. To see how it
works, run a simple query that displays the value of both birth and MONTH(birth):
mysql> SELECT name, birth, MONTH(birth) FROM pet;
+----------+------------+--------------+
| name
| birth
| MONTH(birth) |
+----------+------------+--------------+
| Fluffy
| 1993-02-04 |
2 |
| Claws
| 1994-03-17 |
3 |
| Buffy
| 1989-05-13 |
5 |
| Fang
| 1990-08-27 |
8 |
| Bowser
| 1989-08-31 |
8 |
| Chirpy
| 1998-09-11 |
9 |
| Whistler | 1997-12-09 |
12 |
| Slim
| 1996-04-29 |
4 |
176
MySQL Technical Reference for Version 4.1.1-alpha
| Puffball | 1999-03-30 |
3 |
+----------+------------+--------------+
Finding animals with birthdays in the upcoming month is easy, too. Suppose the current
month is April. Then the month value is 4 and you look for animals born in May (month
5) like this:
mysql> SELECT name, birth FROM pet WHERE MONTH(birth) = 5;
+-------+------------+
| name | birth
|
+-------+------------+
| Buffy | 1989-05-13 |
+-------+------------+
There is a small complication if the current month is December, of course. You don’t just
add one to the month number (12) and look for animals born in month 13, because there
is no such month. Instead, you look for animals born in January (month 1).
You can even write the query so that it works no matter what the current month is. That
way you don’t have to use a particular month number in the query. DATE_ADD() allows you
to add a time interval to a given date. If you add a month to the value of CURDATE(), then
extract the month part with MONTH(), the result produces the month in which to look for
birthdays:
mysql> SELECT name, birth FROM pet
-> WHERE MONTH(birth) = MONTH(DATE_ADD(CURDATE(), INTERVAL 1 MONTH));
A different way to accomplish the same task is to add 1 to get the next month after the
current one (after using the modulo function (MOD) to wrap around the month value to 0 if
it is currently 12):
mysql> SELECT name, birth FROM pet
-> WHERE MONTH(birth) = MOD(MONTH(CURDATE()), 12) + 1;
Note that MONTH returns a number between 1 and 12. And MOD(something,12) returns a
number between 0 and 11. So the addition has to be after the MOD(), otherwise we would
go from November (11) to January (1).
3.3.4.6 Working with NULL Values
The NULL value can be surprising until you get used to it. Conceptually, NULL means missing
value or unknown value and it is treated somewhat differently than other values. To test
for NULL, you cannot use the arithmetic comparison operators such as =, <, or <>. To
demonstrate this for yourself, try the following query:
mysql> SELECT 1 = NULL, 1 <> NULL, 1 < NULL, 1 > NULL;
+----------+-----------+----------+----------+
| 1 = NULL | 1 <> NULL | 1 < NULL | 1 > NULL |
+----------+-----------+----------+----------+
|
NULL |
NULL |
NULL |
NULL |
+----------+-----------+----------+----------+
Clearly you get no meaningful results from these comparisons. Use the IS NULL and IS NOT
NULL operators instead:
Chapter 3: MySQL Tutorial
177
mysql> SELECT 1 IS NULL, 1 IS NOT NULL;
+-----------+---------------+
| 1 IS NULL | 1 IS NOT NULL |
+-----------+---------------+
|
0 |
1 |
+-----------+---------------+
Note that in MySQL, 0 or NULL means false and anything else means true. The default
truth value from a boolean operation is 1.
This special treatment of NULL is why, in the previous section, it was necessary to determine
which animals are no longer alive using death IS NOT NULL instead of death <> NULL.
Two NULL values are regarded as equal in a GROUP BY.
When doing an ORDER BY, NULL values are presented first if you do ORDER BY ... ASC and
last if you do ORDER BY ... DESC.
Note that MySQL 4.0.2 to 4.0.10 incorrectly always sorts NULL values first regardless of the
sort direction.
3.3.4.7 Pattern Matching
MySQL provides standard SQL pattern matching as well as a form of pattern matching
based on extended regular expressions similar to those used by Unix utilities such as vi,
grep, and sed.
SQL pattern matching allows you to use ‘_’ to match any single character and ‘%’ to match
an arbitrary number of characters (including zero characters). In MySQL, SQL patterns
are case-insensitive by default. Some examples are shown here. Note that you do not use =
or <> when you use SQL patterns; use the LIKE or NOT LIKE comparison operators instead.
To find names beginning with ‘b’:
mysql> SELECT * FROM pet WHERE name LIKE "b%";
+--------+--------+---------+------+------------+------------+
| name
| owner | species | sex | birth
| death
|
+--------+--------+---------+------+------------+------------+
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL
|
| Bowser | Diane | dog
| m
| 1989-08-31 | 1995-07-29 |
+--------+--------+---------+------+------------+------------+
To find names ending with ‘fy’:
mysql> SELECT * FROM pet WHERE name LIKE "%fy";
+--------+--------+---------+------+------------+-------+
| name
| owner | species | sex | birth
| death |
+--------+--------+---------+------+------------+-------+
| Fluffy | Harold | cat
| f
| 1993-02-04 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+--------+--------+---------+------+------------+-------+
To find names containing a ‘w’:
mysql> SELECT * FROM pet WHERE name LIKE "%w%";
+----------+-------+---------+------+------------+------------+
178
MySQL Technical Reference for Version 4.1.1-alpha
| 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 fives instances of the ‘_’ pattern
character:
mysql> SELECT * FROM pet WHERE name LIKE "_____";
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
| Claws | Gwen
| cat
| m
| 1994-03-17 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
The other type of pattern matching provided by MySQL uses extended regular expressions.
When you test for a match for this type of pattern, use the REGEXP and NOT REGEXP operators
(or RLIKE and NOT RLIKE, which are synonyms).
Some characteristics of extended regular expressions are:
• ‘.’ matches any single character.
• A character class ‘[...]’ matches any character within the brackets. For example,
‘[abc]’ matches ‘a’, ‘b’, or ‘c’. To name a range of characters, use a dash. ‘[a-z]’
matches any letter, whereas ‘[0-9]’ matches any digit.
• ‘*’ matches zero or more instances of the thing preceding it. For example, ‘x*’ matches
any number of ‘x’ characters, ‘[0-9]*’ matches any number of digits, and ‘.*’ matches
any number of anything.
• A REGEXP pattern match succeed if the pattern matches anywhere in the value being
tested. (This differs from 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 |
+--------+--------+---------+------+------------+------------+
Prior to MySQL Version 3.23.4, REGEXP is case-sensitive, and the previous query will return
no rows. In this case, to match either lowercase or uppercase ‘b’, use this query instead:
Chapter 3: MySQL Tutorial
179
mysql> SELECT * FROM pet WHERE name REGEXP "^[bB]";
From MySQL 3.23.4 on, if you really want to force a REGEXP comparison to be case-sensitive,
use the BINARY keyword to make one of the strings a binary string. This query will match
only lowercase ‘b’ at the beginning of a name:
mysql> SELECT * FROM pet WHERE name REGEXP BINARY "^b";
To find names ending with ‘fy’, use ‘$’ to match the end of the name:
mysql> SELECT * FROM pet WHERE name REGEXP "fy$";
+--------+--------+---------+------+------------+-------+
| name
| owner | species | sex | birth
| death |
+--------+--------+---------+------+------------+-------+
| Fluffy | Harold | cat
| f
| 1993-02-04 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+--------+--------+---------+------+------------+-------+
To find names containing a ‘w’, use this query:
mysql> SELECT * FROM pet WHERE name REGEXP "w";
+----------+-------+---------+------+------------+------------+
| name
| owner | species | sex | birth
| death
|
+----------+-------+---------+------+------------+------------+
| Claws
| Gwen | cat
| m
| 1994-03-17 | NULL
|
| Bowser
| Diane | dog
| m
| 1989-08-31 | 1995-07-29 |
| Whistler | Gwen | bird
| NULL | 1997-12-09 | NULL
|
+----------+-------+---------+------+------------+------------+
Because a regular expression pattern matches if it occurs anywhere in the value, it is not
necessary in the previous query to put a wildcard on either side of the pattern to get it to
match the entire value like it would be if you used an SQL pattern.
To find names containing exactly five characters, use ‘^’ and ‘$’ to match the beginning and
end of the name, and five instances of ‘.’ in between:
mysql> SELECT * FROM pet WHERE name REGEXP "^.....$";
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
| Claws | Gwen
| cat
| m
| 1994-03-17 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
You could also write the previous query using the ‘{n}’ “repeat-n-times” operator:
mysql> SELECT * FROM pet WHERE name REGEXP "^.{5}$";
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
| Claws | Gwen
| cat
| m
| 1994-03-17 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
180
MySQL Technical Reference for Version 4.1.1-alpha
3.3.4.8 Counting Rows
Databases are often used to answer the question, “How often does a certain type of data
occur in a table?” For example, you might want to know how many pets you have, or how
many pets each owner has, or you might want to perform various kinds of census operations
on your animals.
Counting the total number of animals you have is the same question as “How many rows
are in the pet table?” because there is one record per pet. COUNT(*) counts the number of
rows, so the query to count your animals looks like this:
mysql> SELECT COUNT(*) FROM pet;
+----------+
| COUNT(*) |
+----------+
|
9 |
+----------+
Earlier, you retrieved the names of the people who owned pets. You can use COUNT() if you
want to find out how many pets each owner has:
mysql> SELECT owner, COUNT(*) FROM pet GROUP BY owner;
+--------+----------+
| owner | COUNT(*) |
+--------+----------+
| Benny |
2 |
| Diane |
2 |
| Gwen
|
3 |
| Harold |
2 |
+--------+----------+
Note the use of GROUP BY to group together all records for each owner. Without it, all you
get is an error message:
mysql> SELECT owner, COUNT(*) FROM pet;
ERROR 1140: Mixing of GROUP columns (MIN(),MAX(),COUNT()...)
with no GROUP columns is illegal if there is no GROUP BY clause
COUNT() and GROUP BY are useful for characterising your data in various ways. The following
examples show different ways to perform animal census operations.
Number of animals per species:
mysql> SELECT species, COUNT(*) FROM pet GROUP BY species;
+---------+----------+
| species | COUNT(*) |
+---------+----------+
| bird
|
2 |
| cat
|
2 |
| dog
|
3 |
| hamster |
1 |
| snake
|
1 |
+---------+----------+
Number of animals per sex:
Chapter 3: MySQL Tutorial
181
mysql> SELECT sex, COUNT(*) FROM pet GROUP BY sex;
+------+----------+
| sex | COUNT(*) |
+------+----------+
| NULL |
1 |
| f
|
4 |
| m
|
4 |
+------+----------+
(In this output, NULL indicates that the sex is unknown.)
Number of animals per combination of species and sex:
mysql> SELECT species, sex, COUNT(*) FROM pet GROUP BY species, sex;
+---------+------+----------+
| species | sex | COUNT(*) |
+---------+------+----------+
| bird
| NULL |
1 |
| bird
| f
|
1 |
| cat
| f
|
1 |
| cat
| m
|
1 |
| dog
| f
|
1 |
| dog
| m
|
2 |
| hamster | f
|
1 |
| snake
| m
|
1 |
+---------+------+----------+
You need not retrieve an entire table when you use COUNT(). For example, the previous
query, when performed just on dogs and cats, looks like this:
mysql> SELECT species, sex, COUNT(*) FROM pet
-> WHERE species = "dog" OR species = "cat"
-> GROUP BY species, sex;
+---------+------+----------+
| species | sex | COUNT(*) |
+---------+------+----------+
| cat
| f
|
1 |
| cat
| m
|
1 |
| dog
| f
|
1 |
| dog
| m
|
2 |
+---------+------+----------+
Or, if you wanted the number of animals per sex only for known-sex animals:
mysql> SELECT species, sex, COUNT(*) FROM pet
-> WHERE sex IS NOT NULL
-> GROUP BY species, sex;
+---------+------+----------+
| species | sex | COUNT(*) |
+---------+------+----------+
| bird
| f
|
1 |
| cat
| f
|
1 |
182
MySQL Technical Reference for Version 4.1.1-alpha
| cat
| m
|
1 |
| dog
| f
|
1 |
| dog
| m
|
2 |
| hamster | f
|
1 |
| snake
| m
|
1 |
+---------+------+----------+
3.3.4.9 Using More Than one Table
The pet table keeps track of which pets you have. If you want to record other information
about them, such as events in their lives like visits to the vet or when litters are born, you
need another table. What should this table look like? It needs:
• To contain the pet name so you know which animal each event pertains to.
• A date so you know when the event occurred.
• A field to describe the event.
• An event type field, if you want to be able to categorise events.
Given these considerations, the CREATE TABLE statement for the event table might look like
this:
mysql> CREATE TABLE event (name VARCHAR(20), date DATE,
-> type VARCHAR(15), remark VARCHAR(255));
As with the pet table, it’s easiest to load the initial records by creating a tab-delimited text
file containing the information:
name
Fluffy
Buffy
Buffy
Chirpy
Slim
Bowser
Fang
Fang
Claws
Whistler
date
1995-05-15
1993-06-23
1994-06-19
1999-03-21
1997-08-03
1991-10-12
1991-10-12
1998-08-28
1998-03-17
1998-12-09
type
litter
litter
litter
vet
vet
kennel
kennel
birthday
birthday
birthday
remark
4 kittens, 3 female, 1 male
5 puppies, 2 female, 3 male
3 puppies, 3 female
needed beak straightened
broken rib
Gave him a new chew toy
Gave him a new flea collar
First birthday
Load the records like this:
mysql> LOAD DATA LOCAL INFILE "event.txt" INTO TABLE event;
Based on what you’ve learned from the queries you’ve run on the pet table, you should be
able to perform retrievals on the records in the event table; the principles are the same.
But when is the event table by itself insufficient to answer questions you might ask?
Suppose 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,
Chapter 3: MySQL Tutorial
183
-> (YEAR(date)-YEAR(birth)) - (RIGHT(date,5)<RIGHT(birth,5)) AS age,
-> remark
-> FROM pet, event
-> WHERE pet.name = event.name AND type = "litter";
+--------+------+-----------------------------+
| name
| age | remark
|
+--------+------+-----------------------------+
| Fluffy |
2 | 4 kittens, 3 female, 1 male |
| Buffy |
4 | 5 puppies, 2 female, 3 male |
| Buffy |
5 | 3 puppies, 3 female
|
+--------+------+-----------------------------+
There are several things to note about this query:
• The FROM clause lists two tables because the query needs to pull information from both
of them.
• When combining (joining) information from multiple tables, you need to specify how
records in one table can be matched to records in the other. This is easy because they
both have a name column. The query uses WHERE clause to match up records in the two
tables based on the name values.
• Because the name column occurs in both tables, you must be specific about which table
you mean when referring to the column. This is done by prepending the table name to
the column name.
You need not have two different tables to perform a join. Sometimes it is useful to join a
table to itself, if you want to compare records in a table to other records in that same table.
For example, to find breeding pairs among your pets, you can join the pet table with itself
to produce candidate pairs of males and females of like species:
mysql> SELECT p1.name, p1.sex, p2.name, p2.sex, p1.species
-> FROM pet AS p1, pet AS p2
-> WHERE p1.species = p2.species AND p1.sex = "f" AND p2.sex = "m";
+--------+------+--------+------+---------+
| name
| sex | name
| sex | species |
+--------+------+--------+------+---------+
| Fluffy | f
| Claws | m
| cat
|
| Buffy | f
| Fang
| m
| dog
|
| Buffy | f
| Bowser | m
| dog
|
+--------+------+--------+------+---------+
In this query, we specify aliases for the table name in order to refer to the columns and
keep straight which instance of the table each column reference is associated with.
3.4 Getting Information About Databases and Tables
What if you forget the name of a database or table, or what the structure of a given table is
(for example, what its columns are called)? MySQL addresses this problem through several
statements that provide information about the databases and tables it supports.
You have already seen SHOW DATABASES, which lists the databases managed by the server.
To find out which database is currently selected, use the DATABASE() function:
184
MySQL Technical Reference for Version 4.1.1-alpha
mysql> SELECT DATABASE();
+------------+
| DATABASE() |
+------------+
| menagerie |
+------------+
If you haven’t selected any database yet, the result is NULL (or the empty string before
MySQL 4.1.1).
To find out what tables the current database contains (for example, when you’re not sure
about the name of a table), use this command:
mysql> SHOW TABLES;
+---------------------+
| Tables in menagerie |
+---------------------+
| event
|
| pet
|
+---------------------+
If you want to find out about the structure of a table, the DESCRIBE command is useful; it
displays information about each of a table’s columns:
mysql> DESCRIBE pet;
+---------+-------------+------+-----+---------+-------+
| Field
| Type
| Null | Key | Default | Extra |
+---------+-------------+------+-----+---------+-------+
| name
| varchar(20) | YES |
| NULL
|
|
| owner
| varchar(20) | YES |
| NULL
|
|
| species | varchar(20) | YES |
| NULL
|
|
| sex
| char(1)
| YES |
| NULL
|
|
| birth
| date
| YES |
| NULL
|
|
| death
| date
| YES |
| NULL
|
|
+---------+-------------+------+-----+---------+-------+
Field indicates the column name, Type is the datatype for the column, NULL indicates
whether the column can contain NULL values, Key indicates whether the column is indexed,
and Default specifies the column’s default value.
If you have indexes on a table, SHOW INDEX FROM tbl_name produces information about
them.
3.5 Using mysql in Batch Mode
In the previous sections, you used mysql interactively to enter queries and view the results.
You can also run mysql in batch mode. To do this, put the commands you want to run in
a file, then tell mysql to read its input from the file:
shell> mysql < batch-file
If you are running mysql under Windows and have some special characters in the file that
cause problems, you can do this:
Chapter 3: MySQL Tutorial
185
dos> mysql -e "source batch-file"
If you need to specify connection parameters on the command line, the command might
look like this:
shell> mysql -h host -u user -p < batch-file
Enter password: ********
When you use mysql this way, you are creating a script file, then executing the script.
If you want the script to continue even if some of the statements in it produce errors, you
should use the --force command-line option.
Why use a script? Here are a few reasons:
• If you run a query repeatedly (say, every day or every week), making it a script allows
you to avoid retyping it each time you execute it.
• You can generate new queries from existing ones that are similar by copying and editing
script files.
• Batch mode can also be useful while you’re developing a query, particularly for multipleline commands or multiple-statement sequences of commands. If you make a mistake,
you don’t have to retype everything. Just edit your script to correct the error, then
tell mysql to execute it again.
• If you have a query that produces a lot of output, you can run the output through a
pager rather than watching it scroll off the top of your screen:
shell> mysql < batch-file | more
• You can catch the output in a file for further processing:
shell> mysql < batch-file > mysql.out
• You can distribute your script to other people so they can run the commands, too.
• Some situations do not allow for interactive use, for example, when you run a query
from a 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
186
MySQL Technical Reference for Version 4.1.1-alpha
snake
If you want to get the interactive output format in batch mode, use mysql -t. To echo to
the output the commands that are executed, use mysql -vvv.
You can also use scripts from the mysql prompt by using the source command:
mysql> source filename;
3.6 Examples of Common Queries
Here are examples of how to solve some common problems with MySQL.
Some of the examples use the table shop to hold the price of each article (item number)
for certain traders (dealers). Supposing that each trader has a single fixed price per article,
then (article, dealer) is a primary key for the records.
Start the command-line tool mysql and select a database:
shell> mysql your-database-name
(In most MySQL installations, you can use the database name test).
You can create and populate the example table with these statements:
mysql>
->
->
->
->
mysql>
->
->
CREATE TABLE shop (
article INT(4) UNSIGNED ZEROFILL DEFAULT ’0000’ NOT NULL,
dealer CHAR(20)
DEFAULT ’’
NOT NULL,
price
DOUBLE(16,2)
DEFAULT ’0.00’ NOT NULL,
PRIMARY KEY(article, dealer));
INSERT INTO shop VALUES
(1,’A’,3.45),(1,’B’,3.99),(2,’A’,10.99),(3,’B’,1.45),(3,’C’,1.69),
(3,’D’,1.25),(4,’D’,19.95);
After issuing the statements, the table should have the following contents:
mysql> SELECT * FROM shop;
+---------+--------+-------+
| article | dealer | price |
+---------+--------+-------+
|
0001 | A
| 3.45 |
|
0001 | B
| 3.99 |
|
0002 | A
| 10.99 |
|
0003 | B
| 1.45 |
|
0003 | C
| 1.69 |
|
0003 | D
| 1.25 |
|
0004 | D
| 19.95 |
+---------+--------+-------+
3.6.1 The Maximum Value for a Column
“What’s the highest item number?”
SELECT MAX(article) AS article FROM shop;
Chapter 3: MySQL Tutorial
187
+---------+
| article |
+---------+
|
4 |
+---------+
3.6.2 The Row Holding the Maximum of a Certain Column
“Find number, dealer, and price of the most expensive article.”
In SQL-99 (and MySQL Version 4.1) this is easily done with a subquery:
SELECT article, dealer, price
FROM
shop
WHERE price=(SELECT MAX(price) FROM shop);
In MySQL versions prior to 4.1, just do it in two steps:
1. Get the maximum price value from the table with a SELECT statement.
mysql> SELECT MAX(price) FROM shop;
+------------+
| MAX(price) |
+------------+
|
19.95 |
+------------+
2. Using the value 19.95 shown by the previous query to be the maximum article price,
write a query to locate and display the corresponding record:
mysql> SELECT article, dealer, price
-> FROM
shop
-> WHERE price=19.95;
+---------+--------+-------+
| article | dealer | price |
+---------+--------+-------+
|
0004 | D
| 19.95 |
+---------+--------+-------+
Another solution is to sort all rows descending by price and only get the first row using the
MySQL-specific LIMIT clause:
SELECT article, dealer, price
FROM
shop
ORDER BY price DESC
LIMIT 1;
NOTE: If there were several most expensive articles, each with a price of 19.95, the LIMIT
solution would show only one of them!
3.6.3 Maximum of Column per Group
“What’s the highest price per article?”
188
MySQL Technical Reference for Version 4.1.1-alpha
SELECT article, MAX(price) AS price
FROM
shop
GROUP BY article
+---------+-------+
| article | price |
+---------+-------+
|
0001 | 3.99 |
|
0002 | 10.99 |
|
0003 | 1.69 |
|
0004 | 19.95 |
+---------+-------+
3.6.4 The Rows Holding the Group-wise Maximum of a Certain
Field
“For each article, find the dealer or dealers with the most expensive price.”
In SQL-99 (and MySQL Version 4.1 or greater), the problem can be solved with a subquery
like this:
SELECT article, dealer, price
FROM
shop s1
WHERE price=(SELECT MAX(s2.price)
FROM shop s2
WHERE s1.article = s2.article);
In MySQL versions prior to 4.1, it’s best do it in several steps:
1. Get the list of (article,maxprice) pairs.
2. For each article, get the corresponding rows that have the stored maximum price.
This can easily be done with a temporary table and a join:
CREATE TEMPORARY TABLE tmp (
article INT(4) UNSIGNED ZEROFILL DEFAULT ’0000’ NOT NULL,
price
DOUBLE(16,2)
DEFAULT ’0.00’ NOT NULL);
LOCK TABLES shop READ;
INSERT INTO tmp SELECT article, MAX(price) FROM shop GROUP BY article;
SELECT shop.article, dealer, shop.price FROM shop, tmp
WHERE shop.article=tmp.article AND shop.price=tmp.price;
UNLOCK TABLES;
DROP TABLE tmp;
If you don’t use a TEMPORARY table, you must also lock the tmp table.
“Can it be done with a single query?”
Yes, but only by using a quite inefficient trick called the “MAX-CONCAT trick”:
Chapter 3: MySQL Tutorial
189
SELECT article,
SUBSTRING( MAX( CONCAT(LPAD(price,6,’0’),dealer) ), 7) AS dealer,
0.00+LEFT(
MAX( CONCAT(LPAD(price,6,’0’),dealer) ), 6) AS price
FROM
shop
GROUP BY article;
+---------+--------+-------+
| article | dealer | price |
+---------+--------+-------+
|
0001 | B
| 3.99 |
|
0002 | A
| 10.99 |
|
0003 | C
| 1.69 |
|
0004 | D
| 19.95 |
+---------+--------+-------+
The last example can, of course, be made a bit more efficient by doing the splitting of the
concatenated column in the client.
3.6.5 Using User Variables
You can use MySQL user variables to remember results without having to store them in
temporary variables in the client. See Section 6.1.4 [Variables], page 451.
For example, to find the articles with the highest and lowest price you can do this:
mysql> SELECT @min_price:=MIN(price),@max_price:=MAX(price) FROM shop;
mysql> SELECT * FROM shop WHERE [email protected]_price OR [email protected]_price;
+---------+--------+-------+
| article | dealer | price |
+---------+--------+-------+
|
0003 | D
| 1.25 |
|
0004 | D
| 19.95 |
+---------+--------+-------+
3.6.6 Using Foreign Keys
In MySQL 3.23.44 and up, InnoDB tables support checking of foreign key constraints. See
Section 7.5 [InnoDB], page 612. See also Section 1.8.4.5 [ANSI diff Foreign Keys], page 47.
You don’t actually need foreign keys to join 2 tables. For table types other than InnoDB),
the only things MySQL currently doesn’t do are 1) CHECK to make sure that the keys you
use really exist in the table or tables you’re referencing and 2) automatically delete rows
from a table with a foreign key definition. Using your keys to join tables will work just fine:
CREATE TABLE person (
id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
name CHAR(60) NOT NULL,
PRIMARY KEY (id)
);
190
MySQL Technical Reference for Version 4.1.1-alpha
CREATE TABLE shirt (
id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
style ENUM(’t-shirt’, ’polo’, ’dress’) NOT NULL,
colour ENUM(’red’, ’blue’, ’orange’, ’white’, ’black’) NOT NULL,
owner SMALLINT UNSIGNED NOT NULL REFERENCES person(id),
PRIMARY KEY (id)
);
INSERT INTO person VALUES (NULL, ’Antonio Paz’);
INSERT
(NULL,
(NULL,
(NULL,
INTO shirt VALUES
’polo’, ’blue’, LAST_INSERT_ID()),
’dress’, ’white’, LAST_INSERT_ID()),
’t-shirt’, ’blue’, LAST_INSERT_ID());
INSERT INTO person VALUES (NULL, ’Lilliana Angelovska’);
INSERT
(NULL,
(NULL,
(NULL,
(NULL,
INTO shirt VALUES
’dress’, ’orange’, LAST_INSERT_ID()),
’polo’, ’red’, LAST_INSERT_ID()),
’dress’, ’blue’, LAST_INSERT_ID()),
’t-shirt’, ’white’, LAST_INSERT_ID());
SELECT * FROM person;
+----+---------------------+
| id | name
|
+----+---------------------+
| 1 | Antonio Paz
|
| 2 | Lilliana Angelovska |
+----+---------------------+
SELECT * FROM shirt;
+----+---------+--------+-------+
| id | style
| colour | owner |
+----+---------+--------+-------+
| 1 | polo
| blue
|
1 |
| 2 | dress
| white |
1 |
| 3 | t-shirt | blue
|
1 |
| 4 | dress
| orange |
2 |
| 5 | polo
| red
|
2 |
| 6 | dress
| blue
|
2 |
| 7 | t-shirt | white |
2 |
+----+---------+--------+-------+
Chapter 3: MySQL Tutorial
SELECT
WHERE
AND
AND
191
s.* FROM person p, shirt s
p.name LIKE ’Lilliana%’
s.owner = p.id
s.colour <> ’white’;
+----+-------+--------+-------+
| id | style | colour | owner |
+----+-------+--------+-------+
| 4 | dress | orange |
2 |
| 5 | polo | red
|
2 |
| 6 | dress | blue
|
2 |
+----+-------+--------+-------+
3.6.7 Searching on Two Keys
MySQL doesn’t yet optimise when you search on two different keys combined with OR
(searching on one key with different OR parts is optimised quite well):
SELECT field1_index, field2_index FROM test_table
WHERE field1_index = ’1’ OR field2_index = ’1’
The reason is that we haven’t yet had time to come up with an efficient way to handle this
in the general case. (The AND handling is, in comparison, now completely general and works
very well.)
In MySQL 4.0 and up, you can solve this problem efficiently by using a UNION that combines
the output of two separate SELECT statements. See Section 6.4.1.2 [UNION], page 543. Each
SELECT searches only one key and can be optimised:
SELECT field1_index, field2_index FROM test_table WHERE field1_index = ’1’
UNION
SELECT field1_index, field2_index FROM test_table WHERE field2_index = ’1’;
Prior to MySQL 4.0, you can achieve the same effect by using a TEMPORARY table and
separate SELECT statements. This type of optimisation is also very good if you are using
very complicated queries where the SQL server does the optimisations in the wrong order.
CREATE TEMPORARY TABLE tmp
SELECT field1_index, field2_index FROM test_table WHERE field1_index = ’1’;
INSERT INTO tmp
SELECT field1_index, field2_index FROM test_table WHERE field2_index = ’1’;
SELECT * from tmp;
DROP TABLE tmp;
The above way to solve this query is in effect a UNION of two queries.
3.6.8 Calculating Visits Per Day
The following example shows how you can use the bit group functions to calculate the
number of days per month a user has visited a web page.
192
MySQL Technical Reference for Version 4.1.1-alpha
CREATE TABLE t1 (year YEAR(4), month INT(2) UNSIGNED ZEROFILL,
day INT(2) UNSIGNED ZEROFILL);
INSERT INTO t1 VALUES(2000,1,1),(2000,1,20),(2000,1,30),(2000,2,2),
(2000,2,23),(2000,2,23);
The example table contains year-month-day values representing visits by users to the page.
To determine how many different days in each month these visits occur, use this query:
SELECT year,month,BIT_COUNT(BIT_OR(1<<day)) AS days FROM t1
GROUP BY year,month;
Which returns:
+------+-------+------+
| year | month | days |
+------+-------+------+
| 2000 |
01 |
3 |
| 2000 |
02 |
2 |
+------+-------+------+
The query calculates how many different days appear in the table for each year/month
combination, with automatic removal of duplicate entries.
3.6.9 Using AUTO_INCREMENT
The AUTO_INCREMENT attribute can be used to generate a unique identity for new rows:
CREATE TABLE animals (
id MEDIUMINT NOT NULL AUTO_INCREMENT,
name CHAR(30) NOT NULL,
PRIMARY KEY (id)
);
INSERT INTO animals (name) VALUES ("dog"),("cat"),("penguin"),
("lax"),("whale"),("ostrich");
SELECT * FROM animals;
Which returns:
+----+---------+
| id | name
|
+----+---------+
| 1 | dog
|
| 2 | cat
|
| 3 | penguin |
| 4 | lax
|
| 5 | whale
|
| 6 | ostrich |
+----+---------+
You can retrieve the most recent AUTO_INCREMENT value with the LAST_INSERT_ID() SQL
function or the mysql_insert_id() C API function. Note: For a multiple-row insert, LAST_
INSERT_ID()/mysql_insert_id() will actually return the AUTO_INCREMENT key from the
first of the inserted rows. This allows multiple-row inserts to be reproduced correctly on
other servers in a replication setup.
Chapter 3: MySQL Tutorial
193
For MyISAM and BDB tables you can specify AUTO_INCREMENT on a secondary column in a
multiple-column index. In this case, the generated value for the AUTO_INCREMENT column
is calculated as MAX(auto_increment_column)+1) WHERE prefix=given-prefix. This is
useful when you want to put data into ordered groups.
CREATE TABLE animals (
grp ENUM(’fish’,’mammal’,’bird’) NOT NULL,
id MEDIUMINT NOT NULL AUTO_INCREMENT,
name CHAR(30) NOT NULL,
PRIMARY KEY (grp,id)
);
INSERT INTO animals (grp,name) VALUES("mammal","dog"),("mammal","cat"),
("bird","penguin"),("fish","lax"),("mammal","whale"),
("bird","ostrich");
SELECT * FROM animals ORDER BY grp,id;
Which returns:
+--------+----+---------+
| grp
| id | name
|
+--------+----+---------+
| fish
| 1 | lax
|
| mammal | 1 | dog
|
| mammal | 2 | cat
|
| mammal | 3 | whale
|
| bird
| 1 | penguin |
| bird
| 2 | ostrich |
+--------+----+---------+
Note that in this case (when the AUTO_INCREMENT column is part of a multiple-column
index), AUTO_INCREMENT values will be reused if you delete the row with the biggest AUTO_
INCREMENT value in any group. This happens even for MyISAM tables, for which AUTO_
INCREMENT values normally are not reused.)
3.7 Queries from the Twin Project
At Analytikerna and Lentus, we have been doing the systems and field work for a big
research project. This project is a collaboration between the Institute of Environmental
Medicine at Karolinska Institutet Stockholm and the Section on Clinical Research in Aging
and Psychology at the University of Southern California.
The project involves a screening part where all twins in Sweden older than 65 years are
interviewed by telephone. Twins who meet certain criteria are passed on to the next stage.
In this latter stage, twins who want to participate are visited by a doctor/nurse team.
Some of the examinations include physical and neuropsychological examination, laboratory
testing, neuroimaging, psychological status assessment, and family history collection. In
addition, data are collected on medical and environmental risk factors.
More information about Twin studies can be found at: http://www.mep.ki.se/twinreg/index_
en.html
194
MySQL Technical Reference for Version 4.1.1-alpha
The latter part of the project is administered with a web interface written using Perl and
MySQL.
Each night all data from the interviews is moved into a MySQL database.
3.7.1 Find All Non-distributed Twins
The following query is used to determine who goes into the second part of the project:
SELECT
CONCAT(p1.id, p1.tvab) + 0 AS tvid,
CONCAT(p1.christian_name, " ", p1.surname) AS Name,
p1.postal_code AS Code,
p1.city AS City,
pg.abrev AS Area,
IF(td.participation = "Aborted", "A", " ") AS A,
p1.dead AS dead1,
l.event AS event1,
td.suspect AS tsuspect1,
id.suspect AS isuspect1,
td.severe AS tsevere1,
id.severe AS isevere1,
p2.dead AS dead2,
l2.event AS event2,
h2.nurse AS nurse2,
h2.doctor AS doctor2,
td2.suspect AS tsuspect2,
id2.suspect AS isuspect2,
td2.severe AS tsevere2,
id2.severe AS isevere2,
l.finish_date
FROM
twin_project AS tp
/* For Twin 1 */
LEFT JOIN twin_data AS td ON tp.id = td.id
AND tp.tvab = td.tvab
LEFT JOIN informant_data AS id ON tp.id = id.id
AND tp.tvab = id.tvab
LEFT JOIN harmony AS h ON tp.id = h.id
AND tp.tvab = h.tvab
LEFT JOIN lentus AS l ON tp.id = l.id
AND tp.tvab = l.tvab
/* For Twin 2 */
LEFT JOIN twin_data AS td2 ON p2.id = td2.id
AND p2.tvab = td2.tvab
LEFT JOIN informant_data AS id2 ON p2.id = id2.id
AND p2.tvab = id2.tvab
LEFT JOIN harmony AS h2 ON p2.id = h2.id
Chapter 3: MySQL Tutorial
195
AND p2.tvab = h2.tvab
LEFT JOIN lentus AS l2 ON p2.id = l2.id
AND p2.tvab = l2.tvab,
person_data AS p1,
person_data AS p2,
postal_groups AS pg
WHERE
/* p1 gets main twin and p2 gets his/her twin. */
/* ptvab is a field inverted from tvab */
p1.id = tp.id AND p1.tvab = tp.tvab AND
p2.id = p1.id AND p2.ptvab = p1.tvab AND
/* Just the sceening survey */
tp.survey_no = 5 AND
/* Skip if partner died before 65 but allow emigration (dead=9) */
(p2.dead = 0 OR p2.dead = 9 OR
(p2.dead = 1 AND
(p2.death_date = 0 OR
(((TO_DAYS(p2.death_date) - TO_DAYS(p2.birthday)) / 365)
>= 65))))
AND
(
/* Twin is suspect */
(td.future_contact = ’Yes’ AND td.suspect = 2) OR
/* Twin is suspect - Informant is Blessed */
(td.future_contact = ’Yes’ AND td.suspect = 1
AND id.suspect = 1) OR
/* No twin - Informant is Blessed */
(ISNULL(td.suspect) AND id.suspect = 1
AND id.future_contact = ’Yes’) OR
/* Twin broken off - Informant is Blessed */
(td.participation = ’Aborted’
AND id.suspect = 1 AND id.future_contact = ’Yes’) OR
/* Twin broken off - No inform - Have partner */
(td.participation = ’Aborted’ AND ISNULL(id.suspect)
AND p2.dead = 0))
AND
l.event = ’Finished’
/* Get at area code */
AND SUBSTRING(p1.postal_code, 1, 2) = pg.code
/* Not already distributed */
AND (h.nurse IS NULL OR h.nurse=00 OR h.doctor=00)
/* Has not refused or been aborted */
AND NOT (h.status = ’Refused’ OR h.status = ’Aborted’
OR h.status = ’Died’ OR h.status = ’Other’)
ORDER BY
tvid;
196
MySQL Technical Reference for Version 4.1.1-alpha
Some explanations:
CONCAT(p1.id, p1.tvab) + 0 AS tvid
We want to sort on the concatenated id and tvab in numerical order. Adding
0 to the result causes MySQL to treat the result as a number.
column id This identifies a pair of twins. It is a key in all tables.
column tvab
This identifies a twin in a pair. It has a value of 1 or 2.
column ptvab
This is an inverse of tvab. When tvab is 1 this is 2, and vice versa. It exists
to save typing and to make it easier for MySQL to optimise the query.
This query demonstrates, among other things, how to do lookups on a table from the same
table with a join (p1 and p2). In the example, this is used to check whether a twin’s partner
died before the age of 65. If so, the row is not returned.
All of the above exist in all tables with twin-related information. We have a key on both
id,tvab (all tables), and id,ptvab (person_data) to make queries faster.
On our production machine (A 200MHz UltraSPARC), this query returns about 150-200
rows and takes less than one second.
The current number of records in the tables used above:
Table
person_data
lentus
twin_project
twin_data
informant_data
harmony
postal_groups
Rows
71074
5291
5286
2012
663
381
100
3.7.2 Show a Table of Twin Pair Status
Each interview ends with a status code called event. The query shown here is used to
display a table over all twin pairs combined by event. This indicates in how many pairs
both twins are finished, in how many pairs one twin is finished and the other refused, and
so on.
SELECT
t1.event,
t2.event,
COUNT(*)
FROM
lentus AS t1,
lentus AS t2,
twin_project AS tp
WHERE
/* We are looking at one pair at a time */
Chapter 3: MySQL Tutorial
197
t1.id = tp.id
AND t1.tvab=tp.tvab
AND t1.id = t2.id
/* Just the sceening survey */
AND tp.survey_no = 5
/* This makes each pair only appear once */
AND t1.tvab=’1’ AND t2.tvab=’2’
GROUP BY
t1.event, t2.event;
3.8 Using MySQL with Apache
There are programs that let you authenticate your users from a MySQL database and also
let you write your log files into a MySQL table.
You can change the Apache logging format to be easily readable by MySQL by putting the
following into the Apache configuration file:
LogFormat \
"\"%h\",%{%Y%m%d%H%M%S}t,%>s,\"%b\",\"%{Content-Type}o\", \
\"%U\",\"%{Referer}i\",\"%{User-Agent}i\""
To load a log file in that format into MySQL, you can use a statement something like this:
LOAD DATA INFILE ’/local/access_log’ INTO TABLE table_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.
198
MySQL Technical Reference for Version 4.1.1-alpha
4 Database Administration
4.1 Configuring MySQL
4.1.1 mysqld Command-line Options
In most cases you should manage mysqld options through option files. See Section 4.1.2
[Option files], page 206.
mysqld and mysqld.server read options from the mysqld and server groups. mysqld_
safe read options from the mysqld, server, mysqld_safe and safe_mysqld groups. An
embedded MySQL server usually reads options from the server, embedded and xxxxx_
SERVER, where xxxxx is the name of the application.
mysqld accepts a lot of command-line options. Here follows some of the most common ones.
For a full list execute mysqld --help. Options used for replication are listed in a separate
section, see Section 4.11.6 [Replication Options], page 373.
--ansi
Use SQL-99 syntax instead of MySQL syntax. See Section 1.8.2 [ANSI mode],
page 40.
-b, --basedir=path
Path to installation directory. All paths are usually resolved relative to this.
--big-tables
Allow big result sets by saving all temporary sets on file. It solves most ’table full’ errors, but also slows down the queries where in-memory tables would
suffice. Since Version 3.23.2, MySQL is able to solve it automatically by using
memory for small temporary tables and switching to disk tables where necessary.
--bind-address=IP
IP address to bind to.
--console
Write the error log messages to stderr/stdout even if --log-error is specified.
On Windows, mysqld will not close the console screen if this option is used.
--character-sets-dir=path
Directory where character sets are. See Section 4.7.1 [Character sets], page 309.
--chroot=path
Put mysqld daemon in chroot environment at startup. Recommended security
measure since MySQL 4.0 (MySQL 3.23 is not able to provide 100% closed chroot jail). It somewhat limits LOAD DATA INFILE and SELECT ... INTO OUTFILE
though.
--core-file
Write a core file if mysqld dies. For some systems you must also specify -core-file-size to mysqld_safe. See Section 4.8.2 [mysqld_safe], page 315.
Note that on some systems, like Solaris, you will not get a core file if you are
also using the --user option.
Chapter 4: Database Administration
199
-h, --datadir=path
Path to the database root.
--debug[...]=
If MySQL is configured with --with-debug, you can use this option to get
a trace file of what mysqld is doing. See Section E.1.2 [Making trace files],
page 1021.
--default-character-set=charset
Set the default character set. See Section 4.7.1 [Character sets], page 309.
--default-table-type=type
Set the default table type for tables. See Chapter 7 [Table types], page 600.
--delay-key-write[= OFF | ON | ALL]
How MyISAM DELAYED KEYS should be used. See Section 5.5.2 [Server parameters], page 431.
--delay-key-write-for-all-tables; In MySQL 4.0.3 you should use
--delay-key-write=ALL instead.
Don’t flush key buffers between writes for any MyISAM table. See Section 5.5.2
[Server parameters], page 431.
--des-key-file=filename
Read the default keys used by DES_ENCRYPT() and DES_DECRYPT() from this
file.
--enable-external-locking (was --enable-locking)
Enable system locking. Note that if you use this option on a system on which
lockd does not fully work (as on Linux), you will easily get mysqld to deadlock.
--enable-named-pipe
Enable support for named pipes (only on NT/Win2000/XP).
-T, --exit-info
This is a bit mask of different flags one can use for debugging the mysqld server;
one should not use this option if one doesn’t know exactly what it does!
--flush
Flush all changes to disk after each SQL command. Normally MySQL only does
a write of all changes to disk after each SQL command and lets the operating
system handle the syncing to disk. See Section A.4.1 [Crashing], page 870.
-?, --help
Display short help and exit.
--init-file=file
Read SQL commands from this file at startup.
-L, --language=...
Client error messages in given language. May be given as a full path. See
Section 4.7.2 [Languages], page 311.
-l, --log[=file]
Log connections and queries to file. See Section 4.10.2 [Query log], page 355.
200
MySQL Technical Reference for Version 4.1.1-alpha
--log-bin=[file]
Log all queries that change data to the file. Used for backup and replication.
See Section 4.10.4 [Binary log], page 356.
--log-bin-index[=file]
Index file for binary log file names. See Section 4.10.4 [Binary log], page 356.
--log-error[=file]
Log errors and startup messages to this file. See Section 4.10.1 [Error log],
page 354.
--log-isam[=file]
Log all ISAM/MyISAM changes to file (only used when debugging
ISAM/MyISAM).
--log-long-format
Log some extra information to the logfiles (update log, binary update log, and
slow queries log, whatever log has been activated). For example, username and
timestamp are logged for queries. If you are using --log-slow-queries and
--log-long-format, then also queries that are not using indexes are logged to
the slow query log. Note that --log-long-format is deprecated as of MySQL
version 4.1, when --log-short-format was introduced (the long log format is
the default setting since version 4.1). Also note that starting with MySQL 4.1
the --log-queries-not-using-indexes option is available for the purpose of
logging queries that do not use indexes to the slow queries log.
--log-queries-not-using-indexes
If you are using this option with --log-slow-queries, then also queries that
are not using indexes are logged to the slow query log. This option is available
as of MySQL 4.1. See Section 4.10.5 [Slow query log], page 359.
--log-short-format
Log less information to the logfiles (update log, binary update log, and slow
queries log, whatever log has been activated). For example, username and
timestamp are not logged for queries. This options was introduced in MySQL
4.1.
--log-slow-queries[=file]
Log all queries that have taken more than long_query_time seconds to execute
to file. Note that the default for the amount of information logged has changed
in MySQL 4.1. See the --log-long-format and --log-long-format options
for details. See Section 4.10.5 [Slow query log], page 359.
--log-update[=file]
Log updates to file.# where # is a unique number if not given. See Section 4.10.3 [Update log], page 355. The update log is deprecated and will be
removed in MySQL 5.0; you should use the binary log instead (--log-bin).
See Section 4.10.4 [Binary log], page 356. Starting from version 5.0, using
--log-update will just turn on the binlog instead.
--low-priority-updates
Table-modifying operations (INSERT/DELETE/UPDATE) will have lower priority
than selects. It can also be done via {INSERT | REPLACE | UPDATE | DELETE}
Chapter 4: Database Administration
201
LOW_PRIORITY ... to lower the priority of only one query, or by SET LOW_
PRIORITY_UPDATES=1 to change the priority in one thread. See Section 5.3.2
[Table locking], page 423.
--memlock
Lock the mysqld process in memory. This works only if your system supports
the mlockall() system call (like Solaris). This may help if you have a problem
where the operating system is causing mysqld to swap on disk. Note that use
of this option requires that you run the server as root, which is normally not
a good idea for security reasons.
--myisam-recover [=option[,option...]]]
Option is any combination of DEFAULT, BACKUP, FORCE or QUICK. You can also
set this explicitly to "" if you want to disable this option. If this option is
used, mysqld will on open check if the table is marked as crashed or if the table
wasn’t closed properly. (The last option only works if you are running with
--skip-external-locking.) If this is the case mysqld will run check on the
table. If the table was corrupted, mysqld will attempt to repair it.
The following options affects how the repair works.
Option
DEFAULT
BACKUP
Description
The same as not giving any option to --myisam-recover.
If the data table was changed during recover,
save a backup of the ‘table_name.MYD’ datafile as
‘table_name-datetime.BAK’.
FORCE
Run recover even if we will lose more than one row from the
.MYD file.
QUICK
Don’t check the rows in the table if there aren’t any delete
blocks.
Before a table is automatically repaired, MySQL will add a note about this in
the error log. If you want to be able to recover from most problems without
user intervention, you should use the options BACKUP,FORCE. This will force a
repair of a table even if some rows would be deleted, but it will keep the old
datafile as a backup so that you can later examine what happened.
--new
From version 4.0.12, the --new option can be used to make the server behave
as 4.1 in certain aspects, easing a 4.0 to 4.1 upgrade:
• TIMESTAMP is returned as a string with the format ’YYYY-MM-DD
HH:MM:SS’. See Section 6.2 [Column types], page 458.
--pid-file=path
Path to pid file used by mysqld_safe.
-P, --port=...
Port number to listen for TCP/IP connections.
-o, --old-protocol
Use the 3.20 protocol for compatibility with some very old clients. See Section 2.5.5 [Upgrading-from-3.20], page 122.
202
MySQL Technical Reference for Version 4.1.1-alpha
--one-thread
Only use one thread (for debugging under Linux). This option is available
only if the server is built with debugging enabled. See Section E.1 [Debugging
server], page 1020.
--open-files-limit=
To change the number of file descriptors available to mysqld. If this is not set
or set to 0, then mysqld will use this value to reserve file descriptors to use with
setrlimit(). If this value is 0 then mysqld will reserve max_connections*5 or
max_connections + table_cache*2 (whichever is larger) number of files. You
should try increasing this if mysqld gives you the error ’Too many open files’.
-O, --set-variable=name=value
Give a variable a value. --help lists variables. You can find a full description for all variables in the SHOW VARIABLES section in this manual. See Section 4.6.8.4 [SHOW VARIABLES], page 293. The tuning server parameters
section includes information of how to optimise these. Please note that --setvariable=name=value and -O name=value syntax is deprecated as of MySQL
4.0. Use --name=value instead. See Section 5.5.2 [Server parameters], page 431.
In MySQL 4.0.2 one can set a variable directly with --variable-name=option
and set-variable is no longer needed in option files.
If you want to restrict the maximum value a startup option can be set to with
SET, you can define this by using the --maximum-variable-name command line
option. See Section 5.5.6 [SET OPTION], page 437.
Note that when setting a variable to a value, MySQL may automatically correct
it to stay within a given range and also adjusts the value a little to fix for the
used algorithm.
--safe-mode
Skip some optimise stages.
--safe-show-database
With this option, the SHOW DATABASES command returns only those databases
for which the user has some kind of privilege. From version 4.0.2 this option
is deprecated and doesn’t do anything (the option is enabled by default) as we
now have the SHOW DATABASES privilege. See Section 4.4.1 [GRANT], page 242.
--safe-user-create
If this is enabled, a user can’t create new users with the GRANT command, if
the user doesn’t have INSERT privilege to the mysql.user table or any column
in this table.
--skip-bdb
Disable usage of BDB tables. This will save memory and may speed up some
operations.
--skip-concurrent-insert
Turn off the ability to select and insert at the same time on MyISAM tables.
(This is only to be used if you think you have found a bug in this feature.)
Chapter 4: Database Administration
203
--skip-delay-key-write
In MySQL 4.0.3 you should use –delay-key-write=OFF instead. Ignore the
DELAY_KEY_WRITE option for all tables. See Section 5.5.2 [Server parameters],
page 431.
--skip-grant-tables
This option causes the server not to use the privilege system at all. This gives
everyone full access to all databases! (You can tell a running server to start
using the grant tables again by executing mysqladmin flush-privileges or
mysqladmin reload.)
--skip-host-cache
Never use host name cache for faster name-ip resolution, but query DNS server
on every connect instead. See Section 5.5.5 [DNS], page 436.
--skip-innodb
Disable usage of Innodb tables. This will save memory and disk space and
speed up some operations.
--skip-external-locking (was --skip-locking)
Don’t use system locking. To use isamchk or myisamchk you must shut down
the server. See Section 1.2.3 [Stability], page 8. Note that in MySQL Version
3.23 you can use REPAIR and CHECK to repair/check MyISAM tables.
--skip-name-resolve
Hostnames are not resolved. All Host column values in the grant tables must
be IP numbers or localhost. See Section 5.5.5 [DNS], page 436.
--skip-networking
Don’t listen for TCP/IP connections at all. All interaction with mysqld must
be made via named pipes or Unix sockets. This option is highly recommended
for systems where only local requests are allowed. See Section 5.5.5 [DNS],
page 436.
--skip-new
Don’t use new, possibly wrong routines.
--skip-symlink
Deprecated option in 4.0.13; use --skip-symbolic-links instead.
--symbolic-links, --skip-symbolic-links
Enable or disable symbolic link support. This option has different effects on
Windows and Unix.
On Windows, enabling symbolic links allows you to establish a symbolic link to
a database directory by creating a directory.sym file that contains the path
to the real directory. See Section 5.6.1.3 [Windows symbolic links], page 444.
On Unix, enabling symbolic links means that you can link a MyISAM index file
or datafile to another directory with the INDEX DIRECTORY or DATA DIRECTORY
options of the CREATE TABLE statement. If you delete or rename the table, the
files that its symbolic links point to also will be deleted or renamed.
204
MySQL Technical Reference for Version 4.1.1-alpha
--skip-safemalloc
If MySQL is configured with --with-debug=full, all programs check memory
for overruns for every memory allocation and memory freeing operations. This
checking is very slow, so for the server you can avoid it when you don’t need it
by using the --skip-safemalloc option.
--skip-show-database
Don’t allow the SHOW DATABASES command, unless the user has the SHOW
DATABASES privilege.
--skip-stack-trace
Don’t write stack traces. This option is useful when you are running mysqld
under a debugger. On some systems, you also must use this option to get a
core file. See Section E.1 [Debugging server], page 1020.
--skip-thread-priority
Disable using thread priorities for faster response time.
--socket=path
On Unix, the socket file to use for local connections (default
‘/tmp/mysql.sock’).
On Windows, the pipe name to use for local
connections that use a named pipe (default MySQL).
--sql-mode=value[,value[,value...]]
The option values can be any combination of:
REAL_AS_FLOAT,
PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, ONLY_FULL_GROUP_BY,
NO_UNSIGNED_SUBTRACTION, NO_AUTO_VALUE_ON_ZERO, NO_TABLE_OPTIONS,
NO_FIELD_OPTIONS,
NO_KEY_OPTIONS,
NO_DIR_IN_CREATE,
MYSQL323,
MYSQL40, DB2, MAXDB, MSSQL, ORACLE, POSTGRESQL, or ANSI. The value also
can be empty (--sql-mode="") if you want to reset it.
NO_AUTO_VALUE_ON_ZERO affects handling of AUTO_INCREMENT columns. Normally, you generate the next sequence number for the column by inserting
either NULL or 0 into it. NO_AUTO_VALUE_ON_ZERO suppresses this behaviour for
0 so that only NULL generates the next sequence number. This mode can be
useful if 0 has been stored in a table’s AUTO_INCREMENT column (this is not recommended, by the way). For example, if you dump the table with mysqldump
and then reload it, normally MySQL will generate new sequence numbers when
it encounters the 0 values, resulting in a table with different contents than the
one that was dumped. Enabling NO_AUTO_VALUE_ON_ZERO before reloading the
dump file solves this problem. (As of MySQL 4.1.1, when this option value
became available, mysqldump automatically includes dump output to enable
NO_AUTO_VALUE_ON_ZERO.)
Several of the option values are used for compatibility with other servers. If
specified, they cause the server to omit from the output of SHOW CREATE TABLE
those parts of the statement that are not understood by earlier versions of
MySQL or other database servers. Using these option values results in CREATE
TABLE statements that are more portable for use with other servers:
• The NO_TABLE_OPTIONS, NO_FIELD_OPTIONS, NO_DIR_IN_CREATE, and NO_
KEY_OPTIONS values cause omission of table options, or options pertaining
to column or index definitions.
Chapter 4: Database Administration
205
• The values MYSQL323 and MYSQL40 are for compatibility with MySQL 3.23
and MySQL 4.0.
• The values used for compatibility with other servers are DB2, MAXDB, MSSQL,
ORACLE, and POSTGRESQL.
These options also affect the output of mysqldump, because that program uses
SHOW CREATE TABLE to obtain the table-creation statements that it includes in
its own output.
Several of the option values have a complex effect because they are shorthand
for a group or set of values. For example, you can tell the server to run in ANSI
mode by using the --sql-mode=ANSI (or --ansi) option, which is equivalent
to specifying both of the following command-line options:
--sql-mode=REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FUL
--transaction-isolation=SERIALIZABLE
Note that specifying ANSI mode in this way also has the effect of setting the
transaction isolation level. For more information about running the server in
ANSI mode, see Section 1.8.2 [ANSI mode], page 40.
Other “group” values are DB2, MAXDB, MSSQL, ORACLE, and POSTGRESQL. Specifying any of them turns on the PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE,
NO_TABLE_OPTIONS, NO_FIELD_OPTIONS, and NO_KEY_OPTIONS values.
The --sql-mode option was added in MySQL 3.23.41. The NO_UNSIGNED_
SUBTRACTION value was added in 4.0.0. NO_DIR_IN_CREATE was added in
4.0.15. NO_AUTO_VALUE_ON_ZERO, NO_TABLE_OPTIONS, NO_FIELD_OPTIONS,
NO_KEY_OPTIONS, MYSQL323, MYSQL40, DB2, MAXDB, MSSQL, ORACLE,
POSTGRESQL, and ANSI were added in 4.1.1.
--temp-pool
Using this option will cause most temporary files created by the server to use a
small set of names, rather than a unique name for each new file. This is to work
around a problem in the Linux kernel dealing with creating many new files with
different names. With the old behaviour, Linux seems to “leak” memory, as it’s
being allocated to the directory entry cache rather than to the disk cache.
--transaction-isolation={ READ-UNCOMMITTED | READ-COMMITTED | REPEATABLE-READ
| SERIALIZABLE }
Sets the default transaction isolation level.
See Section 6.7.6 [SET
TRANSACTION], page 590.
-t, --tmpdir=path
Path of the directory to use for creating temporary files. It may be useful if your
default /tmp directory resides on a partition that is too small to hold temporary
tables. Starting from MySQL 4.1, this option accepts several paths that are
used in round-robin fashion. Paths should be separated by colon characters
(‘:’) on Unix and semicolon characters (‘;’) on Windows. It is possible to set
tmpdir to point to a memory-based filesystem, except if the MySQL server is
a slave. If it is a slave, it needs some of its temporary files (for replication
of temporary tables or of LOAD DATA INFILE) to survive a machine’s reboot,
206
MySQL Technical Reference for Version 4.1.1-alpha
so a memory-based tmpdir which is cleared when the machine reboots is not
suitable; a disk-based tmpdir is necessary.
-u, --user={user_name | user_id}
Run the mysqld server as the user having the name user_name or numeric user
ID user_id. (“User” in this context refers to a system login account, not a
MySQL user listed in the grant tables.)
This option is mandatory when starting mysqld as root. The server will change
its user ID during its startup sequence, causing it to run as that particular user
rather than as root. See Section 4.3.2 [Security], page 219.
Starting from MySQL 3.23.56 and 4.0.12: To avoid a possible security hole
where a user adds a --user=root option to some ‘my.cnf’ file (thus causing
the server to run as root), mysqld uses only the first --user option specified and produces a warning if there are multiple --user options. Options in
‘/etc/my.cnf’ and ‘datadir/my.cnf’ are processed before command-line options, so it is recommended that you put a --user option in ‘/etc/my.cnf’ and
specify a value other than root. The option in ‘/etc/my.cnf’ will be found
before any other --user options, which ensures that the server runs as a user
other than root, and that a warning results if any other --user option is found.
-V, --version
Display version information and exit.
-W, --log-warnings
Print out warnings like Aborted connection... to the ‘.err’ file. Enabling
this option is recommended, for example, if you use replication (you will get
more information about what is happening, such as messages about network failures and reconnections). See Section A.2.10 [Communication errors], page 864.
This option used to be called --warnings.
You can change most values for a running server with the SET command. See Section 5.5.6
[SET OPTION], page 437.
4.1.2 ‘my.cnf’ Option Files
MySQL can, since Version 3.22, read default startup options for the server and for clients
from option files.
On Windows, MySQL reads default options from the following files:
Filename
windows-directory\my.ini
C:\my.cnf
Purpose
Global options
Global options
windows-directory is the location of your Windows directory.
On Unix, MySQL reads default options from the following files:
Filename
/etc/my.cnf
DATADIR/my.cnf
Purpose
Global options
Server-specific options
Chapter 4: Database Administration
defaults-extra-file
~/.my.cnf
207
The file specified with --defaults-extrafile=path
User-specific options
DATADIR is the MySQL data directory (typically ‘/usr/local/mysql/data’ for a binary
installation or ‘/usr/local/var’ for a source installation). Note that this is the directory
that was specified at configuration time, not the one specified with --datadir when mysqld
starts up! (--datadir has no effect on where the server looks for option files, because the
server looks for files before it processes any command-line arguments.)
Note that on Windows you should specify all paths in option files with ‘/’ instead of ‘\’. If
you use ‘\’, you need to specify it twice, because ‘\’ is the escape character in MySQL.
MySQL tries to read option files in the order listed above. If multiple option files exist, an
option specified in a file read later takes precedence over the same option specified in a file
read earlier. Options specified on the command-line take precedence over options specified
in any option file. Some options can be specified using environment variables. Options
specified on the command-line or in option files take precedence over environment variable
values. See Appendix F [Environment variables], page 1032.
The following programs support option files: mysql, mysqladmin, mysqld, mysqld_safe,
mysql.server, mysqldump, mysqlimport, mysqlshow, mysqlcheck, myisamchk, and
myisampack.
Since Version 4.0.2, you can use the loose prefix for command-line options (or options in
my.cnf). If an option is prefixed by loose, the program reading it will not exit with an
error if an option is unknown, but will rather only issue a warning:
shell> mysql --loose-no-such-option
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 (without the leading double dash). Run the program
with the --help option to get a list of available options.
An option file can contain lines of the following forms:
#comment
Comment lines start with ‘#’ or ‘;’. Comment can start from a middle of a line
too. Empty lines are ignored.
[group]
group is the name of the program or group for which you want to set options.
After a group line, any option or set-variable lines apply to the named group
until the end of the option file or another group line is given.
option
This is equivalent to --option on the command-line.
option=value
This is equivalent to --option=value on the command-line. Please note that
you must quote an argument using double quotes, if the argument for an option
contains a comment character.
set-variable = name=value
This is equivalent to --set-variable name=value on the command-line.
Please note that --set-variable is deprecated since MySQL 4.0; as of
that version, program variable names can be used as option names. On the
command line, just use --name=value. In an option file, use name=value.
208
MySQL Technical Reference for Version 4.1.1-alpha
The [client] group allows you to specify options that apply to all MySQL clients (not
mysqld). This is the perfect group to use to specify the password that you use to connect
to the server. (But make sure the option file is readable and writable only by yourself.)
If you want to create options that should only be read by one specific mysqld server version
you can do this with [mysqld-4.0], [mysqld-4.1] etc:
[mysqld-4.0]
new
The above new option will only be used with MySQL server versions 4.0.x.
Note that for options and values, all leading and trailing blanks are automatically deleted.
You may use the escape sequences ‘\b’, ‘\t’, ‘\n’, ‘\r’, ‘\\’, and ‘\s’ in your value string
(‘\s’ == blank).
Here is a typical global option file:
[client]
port=3306
socket=/tmp/mysql.sock
[mysqld]
port=3306
socket=/tmp/mysql.sock
set-variable = key_buffer_size=16M
set-variable = max_allowed_packet=1M
[mysqldump]
quick
Here is typical user option file:
[client]
# The following password will be sent to all standard MySQL clients
password="my_password"
[mysql]
no-auto-rehash
set-variable = connect_timeout=2
[mysqlhotcopy]
interactive-timeout
If you have a source distribution, you will find sample configuration files named
‘my-xxxx.cnf’ in the ‘support-files’ directory. If you have a binary distribution,
look in the ‘DIR/support-files’ directory, where DIR is the pathname to the MySQL
installation directory (typically ‘C:\mysql’ or ‘/usr/local/mysql’). Currently there are
sample configuration files for small, medium, large, and very large systems. You can copy
‘my-xxxx.cnf’ to your home directory (rename the copy to ‘.my.cnf’) to experiment with
this.
All MySQL programs that support option files support the following options:
Chapter 4: Database Administration
Option
--no-defaults
--print-defaults
--defaults-file=full-path-todefault-file
--defaults-extra-file=full-pathto-default-file
209
Description
Don’t read any option files.
Print the program name and all options that it
will get.
Only use the given configuration file.
Read this configuration file after the global configuration file but before the user configuration
file.
Note that the options just shown must be first on the command line to work, with the
exception that --print-defaults may be used immediately after --defaults-file or
--defaults-extra-file.
Note for developers: Option file handling is implemented simply by processing all matching
options (that is, options in the appropriate group) before any command-line arguments.
This works nicely for programs that use the last instance of an option that is specified
multiple times. If you have an old program that handles multiply specified options this way
but doesn’t read option files, you need add only two lines to give it that capability. Check
the source code of any of the standard MySQL clients to see how to do this.
In shell scripts, you can use the my_print_defaults command to parse the option files.
The following example shows the output that my_print_defaults might produce when
asked to show the options found in the [client] and [mysql] groups:
shell> my_print_defaults client mysql
--port=3306
--socket=/tmp/mysql.sock
--no-auto-rehash
4.2 Running Multiple MySQL Servers on the Same Machine
In some cases you might want to run multiple mysqld servers on the same machine. You
might want to test a new MySQL release while leaving your existing production setup
undisturbed. Or you may want to give different users access to different mysqld servers
that they manage themselves. (For example, you might be an Internet service provider that
wants to provide independent MySQL installations for different customers.)
To run multiple servers on a single machine, each server must have unique values for several operating parameters. These can be set on the command line or in option files. See
Section 4.1.1 [Command-line options], page 198, and Section 4.1.2 [Option files], page 206.
At least the following options must be different for each server:
• --port=port_num
• --socket=path
• --shared-memory-base-name=name (Windows only; new in MySQL 4.1)
• --pid-file=path (Unix only)
--port controls the port number for TCP/IP connections. --socket controls the socket file
path on Unix and the name of the named pipe on Windows. (It’s necessary to specify distinct
210
MySQL Technical Reference for Version 4.1.1-alpha
pipe names on Windows only for those servers that support named pipe connections.) -shared-memory-base-name designates the shared memory name used by a Windows server
to allow clients to connect via shared memory. --pid-file indicates the name of the file
in which a Unix server writes its process ID.
If you use the following options, they must be different for each server:
• --log=path
• --log-bin=path
• --log-update=path
• --log-error=path
• --log-isam=path
• --bdb-logdir=path
If you want more performance, you can also specify the following options differently for
each server, to spread load between several physical disks:
• --tmpdir=path
• --bdb-tmpdir=path
Having different temporary directories like above is also recommended because it will be
easier for you in case you want to know to which MySQL server a certain temporary file
belongs.
Generally, each server should also use a different data directory, which is specified using the
--datadir=path option.
Warning: Normally you should never have two servers that update data in the same
databases! This may lead to unpleasant surprises if your operating system doesn’t support fault-free system locking! If (despite this warning) you run multiple servers using the
same data directory and they have logging enabled, you must use the appropriate options
to specify log file names that are unique to each server. Otherwise, the servers will try to
log to the same files.
This warning against sharing a data directory among servers also applies in an NFS environment. Allowing multiple MySQL servers to access a common data directory over NFS
is a bad idea!
• The primary problem is that NFS will become the speed bottleneck. It is not meant
for such use.
• Another risk with NFS is that you will have to come up with a way to make sure
that two or more servers do not interfere with each other. Usually NFS file locking
is handled by the lockd daemon, but at the moment there is no platform that will
perform locking 100% reliably in every situation.
Make it easy for yourself: Forget about sharing a data directory among servers over NFS.
A better solution is to have one computer that contains several CPUs and use an operating
system that handles threads efficiently.
If you have multiple MySQL installations in different locations, normally you can specify
the base installation directory for each server with the --basedir=path option to cause
each server to use a different data directory, log files, and PID file. (The defaults for all
these values are determined relative to the base directory.) In that case, the only other
Chapter 4: Database Administration
211
options you need to specify are the --socket and --port options. For example, suppose
you install different versions of MySQL using ‘.tar’ file binary distributions. These will
install in different locations, so you can start the server for each installation using the
command ./bin/mysqld_safe under its corresponding base directory. mysqld_safe will
determine the proper --basedir option to pass to mysqld, and you need specify only the
--socket and --port options to mysqld_safe.
As discussed in the following sections, it is possible to start additional servers by setting
environment variables or by specifying appropriate command-line options. However, if you
need to run multiple servers on a more permanent basis, it will be more convenient to use
option files to specify for each server those option values that must be unique to it.
4.2.1 Running Multiple Servers on Windows
You can run multiple servers on Windows by starting them manually from the command
line, each with appropriate operating parameters. On Windows NT-based systems, you also
have the option of installing several servers as Windows services and running them that way.
General instructions for running MySQL servers from the command line or as services are
given in Section 2.6.1 [Windows], page 126. This section describes how to make sure you
start each server with different values for those startup options that must be unique per
server, such as the data directory. (These options are described in Section 4.2 [Multiple
servers], page 209.)
4.2.1.1 Starting Multiple Windows Servers at the Command Line
To start multiple servers manually from the command line, you can specify the appropriate
options on the command line or in an option file. It’s more convenient to place the options
in an option file, but it’s necessary to make sure that each server gets its own set of options.
To do this, create an option file for each server and tell the server the filename with a
--defaults-file option when you run it.
Suppose you want to run mysqld on port 3307 with a data directory of ‘C:\mydata1’, and
mysqld-max on port 3308 with a data directory of ‘C:\mydata2’. To accomplish this, create
two option files. For example, create one file named ‘C:\my-opts1.cnf’ that looks like this:
[mysqld]
datadir = C:/mydata1
port = 3307
Create a second file named ‘C:\my-opts2.cnf’ that looks like this:
[mysqld]
datadir = C:/mydata2
port = 3308
Then start each server with its own option file:
shell> mysqld --defaults-file=C:\my-opts1.cnf
shell> mysqld-max --defaults-file=C:\my-opts2.cnf
(On NT, the servers will start in the foreground, so you’ll need to issue those two commands
in separate console windows.)
To shut down the servers, you must connect to the appropriate port number:
212
MySQL Technical Reference for Version 4.1.1-alpha
shell> mysqladmin --port=3307 shutdown
shell> mysqladmin --port=3308 shutdown
Servers configured as just described will allow clients to connect over TCP/IP. If you
also want to allow named pipe connections, use the mysqld-nt or mysqld-max-nt servers
and specify options that enable the named pipe and specify its name. (Each server
that supports named pipe connections must use a unique pipe name.) For example, the
‘C:\my-opts1.cnf’ file might be written like this:
[mysqld]
datadir = C:/mydata1
port = 3307
enable-named-pipe
socket = mypipe1
Then start the server this way:
shell> mysqld-nt --defaults-file=C:\my-opts1.cnf
‘C:\my-opts2.cnf’ would be modified similarly for use by the second server.
4.2.1.2 Starting Multiple Windows Servers as Services
On NT-based systems, a MySQL server can be run as a Windows service. The procedures for
installing, controlling, and removing a single MySQL service are described in Section 2.1.1.7
[NT start], page 62.
As of MySQL 4.0.2, you can install multiple servers as services. In this case, you must make
sure that each server uses a different service name in addition to all the other parameters
that must be unique per server.
For the following instructions, assume that you want to run the mysqld-nt server from two
different versions of MySQL that are installed at ‘C:\mysql-4.0.8’ and ‘C:\mysql-4.0.17’,
respectively. (This might be the case if you’re running 4.0.8 as your production server, but
want to test 4.0.17 before upgrading to it.)
The following principles are relevant when installing a MySQL service with the --install
option:
• If you specify no service name, the server uses the default service name of MySQL and
the server reads options from the [mysqld] group in the standard option files.
• If you specify a service name after the --install option, the server ignores the
[mysqld] option group and instead reads options from the group that has the same
name as the service. The server reads options from the standard option files.
• If you specify a --defaults-file option after the service name, the server ignores the
standard option files and reads options only from the [mysqld] group of the named
file.
These principles also apply if you install a server using the --install-manual option.
Based on the preceding information, you have several ways to set up multiple services. The
following instructions describe some examples. Before trying any of them, be sure you shut
down and remove any existing MySQL services first.
Chapter 4: Database Administration
213
• Specify the options for all services in one of the standard option files. To do this, use
a different service name for each server. Suppose you want to run the 4.0.8 mysqld-nt
using the service name of mysqld1 and the 4.0.17 mysqld-nt using the service name
mysqld2. In this case, you can use the [mysqld1] group for 4.0.8 and the [mysqld2]
group for 4.0.17. For example, you can set up ‘C:\my.cnf’ like this:
# options for mysqld1 service
[mysqld1]
basedir = C:/mysql-4.0.8
port = 3307
enable-named-pipe
socket = mypipe1
# options for mysqld2 service
[mysqld2]
basedir = C:/mysql-4.0.17
port = 3308
enable-named-pipe
socket = mypipe2
Install the services as follows, using the full server pathnames to ensure that Windows
registers the correct executable program for each service:
shell> C:\mysql-4.0.8\bin\mysqld-nt --install mysqld1
shell> C:\mysql-4.0.17\bin\mysqld-nt --install mysqld2
To start the services, use the services manager, or use NET START with the appropriate
service names:
shell> NET START mysqld1
shell> NET START mysqld2
To stop the services, use the services manager, or use NET STOP with the appropriate
service names:
shell> NET STOP mysqld1
shell> NET STOP mysqld2
Note: Before MySQL 4.0.17, only a server installed using the default service name
(MySQL) or one installed explicitly with a service name of mysqld will read the [mysqld]
group in the standard option files. As of 4.0.17, all servers read the [mysqld group
if they read the standard option files, even if they are installed using another service
name. This allows you to use the [mysqld] group for options that should be used by
all MySQL services, and an option group named after each service for use by the server
installed with that service name.
• Specify options for each server in separate files and use --defaults-file when you
install the services to tell each server what file to use. In this case, each file should list
options using a [mysqld] group.
With this approach, to specify options for the 4.0.8 mysqld-nt, create a file
‘C:\my-opts1.cnf’ that looks like this:
[mysqld]
basedir = C:/mysql-4.0.8
port = 3307
214
MySQL Technical Reference for Version 4.1.1-alpha
enable-named-pipe
socket = mypipe1
For the 4.0.17 mysqld-nt, create a file ‘C:\my-opts2.cnf’ that looks like this:
[mysqld]
basedir = C:/mysql-4.0.17
port = 3308
enable-named-pipe
socket = mypipe2
Install the services as follows (enter each command on a single line):
shell> C:\mysql-4.0.8\bin\mysqld-nt --install mysqld1
--defaults-file=C:\my-opts1.cnf
shell> C:\mysql-4.0.17\bin\mysqld-nt --install mysqld2
--defaults-file=C:\my-opts2.cnf
To use a --defaults-file option when you install a MySQL server as a service, you
must precede the option with the service name.
After installing the services, start and stop them the same way as in the preceding
example.
To remove multiple services, use mysqld --remove for each one, specifying a service name
following the --remove option if the service to remove has a name different than the default.
4.2.2 Running Multiple Servers on Unix
The easiest way is to run multiple servers on Unix is to compile them with different TCP/IP
ports and socket files so that each one is listening on different network interfaces. Also, by
compiling in different base directories for each installation, that automatically results in
different compiled-in data directory, log file, and PID file locations for each of your servers.
Assume an existing server is configured for the default port number and socket file. To
configure a new server to have different operating parameters, use a configure command
something like this:
shell> ./configure --with-tcp-port=port_number \
--with-unix-socket-path=file_name \
--prefix=/usr/local/mysql-4.0.17
Here port_number and file_name should be different from the default port number and
socket file pathname, and the --prefix value should specify an installation directory different than the one under which the existing MySQL installation is located.
If you have a MySQL server listening on a given port number, you can use the following command to find out what operating parameters it is using for several important configurable
variables, including the base directory and socket name:
shell> mysqladmin --host=host_name --port=port_number variables
With the information displayed by that command, you can tell what option values not to
use when configuring an additional server.
Note that if you specify “localhost” as a hostname, mysqladmin will default to using
a Unix socket connection rather than TCP/IP. In MySQL 4.1, you can explicitly specify
Chapter 4: Database Administration
215
the connection protocol to use by using the --protocol={TCP | SOCKET | PIPE | MEMORY}
option.
You don’t have to compile a new MySQL server just to start with a different socket file and
TCP/IP port number. It is also possible to specify those values at runtime. One way to do
so is by using command-line options:
shell> /path/to/mysqld_safe --socket=file_name --port=port_number
To use another database directory for the second server, pass a --datadir=path option to
mysqld_safe.
Another way to achieve a similar effect is to use environment variables to set the socket
name and port number:
shell> MYSQL_UNIX_PORT=/tmp/mysqld-new.sock
shell> MYSQL_TCP_PORT=3307
shell> export MYSQL_UNIX_PORT MYSQL_TCP_PORT
shell> scripts/mysql_install_db
shell> bin/mysqld_safe &
This is a quick way of starting a second server to use for testing. The nice thing about this
method is that the environment variable settings will apply to any client programs that
you invoke from the above shell. Thus, connections for those clients automatically will be
directed to the second server!
Appendix F [Environment variables], page 1032 includes a list of other environment variables
you can use to affect mysqld.
For automatic server execution, your startup script that is executed at boot time should
execute the following command once for each server with an appropriate option file path
for each command:
mysqld_safe --defaults-file=path-to-option-file
Each option file should contain option values specific to a given server.
On Unix, the mysqld_multi script is another way to start multiple servers. See Section 4.8.3
[mysqld_multi], page 316.
4.2.3 Using Client Programs in a Multiple-Server Environment
When you want to connect with a client program to a MySQL server that is listening to
different network interfaces than those compiled into your client, you can use one of the
following methods:
• Start the client with --host=host_name --port=port_number to connect via TCP/IP
to a remote host, or with --host=localhost --socket=file_name to connect to a
local host via a Unix socket or a Windows named pipe.
• As of MySQL 4.1, start the client with --protocol=tcp to connect via TCP/IP, -protocol=socket to connect via a Unix socket, --protocol=pipe to connect via
a named pipe, or --protocol=memory to connect via shared memory. For TCP/IP
connections, you may also need to specify --host and --port options. For the other
types of connections, you may need to specify a --socket option to specify a socket
or named pipe name, or a --shared-memory-base-name option to specify the shared
memory name.
216
MySQL Technical Reference for Version 4.1.1-alpha
• On Unix, set the MYSQL_UNIX_PORT and MYSQL_TCP_PORT environment variables to
point to the Unix socket and TCP/IP port before you start your clients. If you normally use a specific socket or port, you can place commands to set these environment
variables in your ‘.login’ file so that they apply each time you log in. See Appendix F
[Environment variables], page 1032.
• Specify the default socket and TCP/IP port in the [client] group of an option file.
Foe example, you can use ‘C:\my.cnf’ on Windows, or the ‘.my.cnf’ file in your home
directory on Unix. See Section 4.1.2 [Option files], page 206.
• In a C program, you can specify the port or socket arguments in the mysql_real_
connect() call. You can also have the program read option files by calling mysql_
options(). See Section 11.1.3 [C API functions], page 732.
• If you are using the Perl DBD::mysql module, you can read the options from the MySQL
option files. For example:
$dsn = "DBI:mysql:test;mysql_read_default_group=client;"
. "mysql_read_default_file=/usr/local/mysql/data/my.cnf";
$dbh = DBI->connect($dsn, $user, $password);
See Section 11.5.2 [Perl DBI Class], page 828.
4.3 General Security Issues and the MySQL Access
Privilege System
MySQL has an advanced but non-standard security/privilege system. This section describes
how it works.
4.3.1 General Security Guidelines
Anyone using MySQL on a computer connected to the Internet should read this section to
avoid the most common security mistakes.
In discussing security, we emphasise the necessity of fully protecting the entire server host
(not simply the MySQL server) against all types of applicable attacks: eavesdropping,
altering, playback, and denial of service. We do not cover all aspects of availability and
fault tolerance here.
MySQL uses security based on Access Control Lists (ACLs) for all connections, queries,
and other operations that a user may attempt to perform. There is also some support
for SSL-encrypted connections between MySQL clients and servers. Many of the concepts
discussed here are not specific to MySQL at all; the same general ideas apply to almost all
applications.
When running MySQL, follow these guidelines whenever possible:
• Do not ever give anyone (except the mysql root user) access to the user table in
the mysql database! This is critical. The encrypted password is the real password in
MySQL. Anyone who knows the password which is listed in the user table and has
access to the host listed for the account can easily log in as that user.
Chapter 4: Database Administration
217
• Learn the MySQL access privilege system. The GRANT and REVOKE commands are used
for controlling access to MySQL. Do not grant any more privileges than necessary.
Never grant privileges to all hosts.
Checklist:
− Try mysql -u root. If you are able to connect successfully to the server without
being asked for a password, you have problems. Anyone can connect to your
MySQL server as the MySQL root user with full privileges! Review the MySQL
installation instructions, paying particular attention to the item about setting a
root password.
− Use the command SHOW GRANTS and check to see who has access to what. Remove
those privileges that are not necessary using the REVOKE command.
• Do not keep any plain-text passwords in your database. When your computer becomes
compromised, the intruder can take the full list of passwords and use them. Instead
use MD5(), SHA1() or another one-way hashing function.
• Do not choose passwords from dictionaries. There are special programs to break them.
Even passwords like “xfish98” are very bad. Much better is “duag98” which contains
the same word “fish” but typed one key to the left on a standard QWERTY keyboard.
Another method is to use “Mhall” which is taken from the first characters of each word
in the sentence “Mary had a little lamb.” This is easy to remember and type, but
difficult to guess for someone who does not know it.
• Invest in a firewall. This protects you from at least 50% of all types of exploits in any
software. Put MySQL behind the firewall or in a demilitarised zone (DMZ).
Checklist:
− Try to scan your ports from the Internet using a tool such as nmap. MySQL
uses port 3306 by default. This port should be inaccessible from untrusted hosts.
Another simple way to check whether or not your MySQL port is open is to try
the following command from some remote machine, where server_host is the
hostname of your MySQL server:
shell> telnet server_host 3306
If you get a connection and some garbage characters, the port is open, and should
be closed on your firewall or router, unless you really have a good reason to keep
it open. If telnet just hangs or the connection is refused, everything is OK; the
port is blocked.
• Do not trust any data entered by your users. They can try to trick your code by entering
special or escaped character sequences in web forms, URLs, or whatever application
you have built. Be sure that your application remains secure if a user enters something
like “; DROP DATABASE mysql;”. This is an extreme example, but large security leaks
and data loss may occur as a result of hackers using similar techniques, if you do not
prepare for them.
Also remember to check numeric data. A common mistake is to protect only strings.
Sometimes people think that if a database contains only publicly available data that it
need not be protected. This is incorrect. At least denial-of-service type attacks can be
performed on such databases. The simplest way to protect from this type of attack is to
use apostrophes around the numeric constants: SELECT * FROM table WHERE ID=’234’
218
MySQL Technical Reference for Version 4.1.1-alpha
rather than SELECT * FROM table WHERE ID=234. MySQL automatically converts this
string to a number and strips all non-numeric symbols from it.
Checklist:
− All web applications:
• Try to enter ‘’’ and ‘"’ in all your web forms. If you get any kind of MySQL
error, investigate the problem right away.
• Try to modify any dynamic URLs by adding %22 (‘"’), %23 (‘#’), and %27 (‘’’)
in the URL.
• Try to modify datatypes in dynamic URLs from numeric ones to character
ones containing characters from previous examples. Your application should
be safe against this and similar attacks.
• Try to enter characters, spaces, and special symbols instead of numbers in
numeric fields. Your application should remove them before passing them
to MySQL or your application should generate an error. Passing unchecked
values to MySQL is very dangerous!
• Check data sizes before passing them to MySQL.
• Consider having your application connect to the database using a different
user name than the one you use for administrative purposes. Do not give
your applications any more access privileges than they need.
− Users of PHP:
• Check out the addslashes() function. As of PHP 4.0.3, a mysql_escape_
string() function is available that is based on the function of the same name
in the MySQL C API.
− Users of MySQL C API:
• Check out the mysql_real_escape_string() API call.
− Users of MySQL++:
• Check out the escape and quote modifiers for query streams.
− Users of Perl DBI:
• Check out the quote() method or use placeholders.
− Users of Java JDBC:
• Use a PreparedStatement object and placeholders.
• Do not transmit plain (unencrypted) data over the Internet. These data are accessible
to everyone who has the time and ability to intercept it and use it for their own
purposes. Instead, use an encrypted protocol such as SSL or SSH. MySQL supports
internal SSL connections as of Version 4.0.0. SSH port-forwarding can be used to create
an encrypted (and compressed) tunnel for the communication.
• Learn to use the tcpdump and strings utilities. For most cases, you can check whether
MySQL data streams are unencrypted by issuing a command like the following:
shell> tcpdump -l -i eth0 -w - src or dst port 3306 | strings
(This works under Linux and should work with small modifications under other systems.) Warning: If you do not see data this doesn’t always actually mean that it is
encrypted. If you need high security, you should consult with a security expert.
Chapter 4: Database Administration
219
4.3.2 How to Make MySQL Secure Against Crackers
When you connect to a MySQL server, you normally should use a password. The password
is not transmitted in clear text over the connection, however the encryption algorithm is
not very strong, and with some effort a clever attacker can crack the password if he is able
to sniff the traffic between the client and the server. If the connection between the client
and the server goes through an untrusted network, you should use an SSH tunnel to encrypt
the communication.
All other information is transferred as text that can be read by anyone who is able to watch
the connection. If you are concerned about this, you can use the compressed protocol (in
MySQL Version 3.22 and above) to make traffic much more difficult to decipher. To make
things even more secure you should use ssh. You can find an Open Source ssh client at
http://www.openssh.org/, and a commercial ssh client at http://www.ssh.com/. With
this, you can get an encrypted TCP/IP connection between a MySQL server and a MySQL
client.
If you are using MySQL 4.0, you can also use internal OpenSSL support. See Section 4.4.10
[Secure connections], page 255.
To make a MySQL system secure, you should strongly consider the following suggestions:
• Use passwords for all MySQL users. Remember that anyone can log in as any other
person as simply as mysql -u other_user db_name if other_user has no password. It
is common behaviour with client/server applications that the client may specify any
user name. You can change the password of all users by editing the mysql_install_db
script before you run it, or only the password for the MySQL root user like this:
shell> mysql -u root mysql
mysql> UPDATE user SET Password=PASSWORD(’new_password’)
->
WHERE user=’root’;
mysql> FLUSH PRIVILEGES;
• Don’t run the MySQL daemon as the Unix root user. This is very dangerous, because
any user with the FILE privilege will be able to create files as root (for example,
~root/.bashrc). To prevent this, mysqld will refuse to run as root unless it is specified
directly using a --user=root option.
mysqld can be run as an ordinary unprivileged user instead. You can also create a new
Unix user mysql to make everything even more secure. If you run mysqld as another
Unix user, you don’t need to change the root user name in the user table, because
MySQL user names have nothing to do with Unix user names. To start mysqld as
another Unix user, add a user line that specifies the user name to the [mysqld] group
of the ‘/etc/my.cnf’ option file or the ‘my.cnf’ option file in the server’s data directory.
For example:
[mysqld]
user=mysql
This will cause the server to start as the designated user whether you start it manually or by using mysqld_safe or mysql.server. For more details, see Section A.3.2
[Changing MySQL user], page 869.
• Don’t support symlinks to tables (this can be disabled with the --skip-symlink option). This is especially important if you run mysqld as root as anyone that has write
220
•
•
•
•
•
MySQL Technical Reference for Version 4.1.1-alpha
access to the mysqld data directories could then delete any file in the system! See
Section 5.6.1.2 [Symbolic links to tables], page 443.
Check that the Unix user that mysqld runs as is the only user with read/write privileges
in the database directories.
Don’t give the PROCESS privilege to all users. The output of mysqladmin processlist
shows the text of the currently executing queries, so any user who is allowed to execute that command might be able to see if another user issues an UPDATE user SET
password=PASSWORD(’not_secure’) query.
mysqld reserves an extra connection for users who have the PROCESS privilege, so that
a MySQL root user can log in and check server activity even if all normal connections
are in use.
Don’t give the FILE privilege to all users. Any user that has this privilege can write a
file anywhere in the filesystem with the privileges of the mysqld daemon! To make this
a bit safer, all files generated with SELECT ... INTO OUTFILE are writeable by everyone,
and you cannot overwrite existing files.
The FILE privilege may also be used to read any world readable file that is accessible
to the Unix user that the server runs as. One can also read any file to the current
database (which the user need some privilege for). This could be abused, for example,
by using LOAD DATA to load ‘/etc/passwd’ into a table, which can then be read with
SELECT.
If you don’t trust your DNS, you should use IP numbers instead of hostnames in the
grant tables. In any case, you should be very careful about creating grant table entries
using hostname values that contain wildcards!
If you want to restrict the number of connections for a single user, you can do this by
setting the max_user_connections variable in mysqld.
4.3.3 Startup Options for mysqld Concerning Security
The following mysqld options affect security:
--local-infile[=(0|1)]
If one uses --local-infile=0 then one can’t use LOAD DATA LOCAL INFILE.
--safe-show-database
With this option, the SHOW DATABASES command returns only those databases
for which the user has some kind of privilege. From version 4.0.2 this option
is deprecated and doesn’t do anything (the option is enabled by default) as we
now have the SHOW DATABASES privilege. See Section 4.4.1 [GRANT], page 242.
--safe-user-create
If this is enabled, an user can’t create new users with the GRANT command, if
the user doesn’t have the INSERT privilege for the mysql.user table. If you
want to give a user access to just create new users with those privileges that
the user has right to grant, you should give the user the following privilege:
mysql> GRANT INSERT(user) ON mysql.user TO ’user’@’hostname’;
This will ensure that the user can’t change any privilege columns directly, but
has to use the GRANT command to give privileges to other users.
Chapter 4: Database Administration
221
--skip-grant-tables
This option causes the server not to use the privilege system at all. This gives
everyone full access to all databases! (You can tell a running server to start
using the grant tables again by executing mysqladmin flush-privileges or
mysqladmin reload.)
--skip-name-resolve
Hostnames are not resolved. All Host column values in the grant tables must
be IP numbers or localhost.
--skip-networking
Don’t allow TCP/IP connections over the network. All connections to mysqld
must be made via Unix sockets. This option is unsuitable when using a MySQL
version prior to 3.23.27 with the MIT-pthreads package, because Unix sockets
were not supported by MIT-pthreads at that time.
--skip-show-database
Don’t allow SHOW DATABASES command, unless the user has the SHOW DATABASES
privilege. From version 4.0.2 you should no longer need this option, since access
can now be granted specifically with the SHOW DATABASES privilege.
4.3.4 Security issues with LOAD DATA LOCAL
In MySQL 3.23.49 and MySQL 4.0.2 (4.0.13 on Windows), we added some new options to
deal with possible security issues when it comes to LOAD DATA LOCAL.
There are two possible problems with supporting this command:
As the reading of the file is initiated from the server, one could theoretically create a patched
MySQL server that could read any file on the client machine that the current user has read
access to, when the client issues a query against the table.
In a web environment where the clients are connecting from a web server, a user could use
LOAD DATA LOCAL to read any files that the web server process has read access to (assuming
a user could run any command against the SQL server).
There are two separate fixes for this:
If you don’t configure MySQL with --enable-local-infile, then LOAD DATA LOCAL will
be disabled by all clients, unless one calls mysql_options(... MYSQL_OPT_LOCAL_INFILE,
0) in the client. See Section 11.1.3.40 [mysql_options()], page 758.
For the mysql command-line client, LOAD DATA LOCAL can be enabled by specifying the
option --local-infile[=1], or disabled with --local-infile=0.
By default, all MySQL clients and libraries are compiled with --enable-local-infile, to
be compatible with MySQL 3.23.48 and before.
One can disable all LOAD DATA LOCAL commands in the MySQL server by starting mysqld
with --local-infile=0.
In the case that LOAD DATA LOCAL INFILE is disabled in the server or the client, you will get
the error message (1148):
The used command is not allowed with this MySQL version
222
MySQL Technical Reference for Version 4.1.1-alpha
4.3.5 What the Privilege System Does
The primary function of the MySQL privilege system is to authenticate a user connecting
from a given host, and to associate that user with privileges on a database such as SELECT,
INSERT, UPDATE and DELETE.
Additional functionality includes the ability to have an anonymous user and to grant privileges for MySQL-specific functions such as LOAD DATA INFILE and administrative operations.
4.3.6 How the Privilege System Works
The MySQL privilege system ensures that all users may perform exactly the operations
that they are supposed to be allowed to do. When you connect to a MySQL server, your
identity is determined by the host from which you connect and the user name you specify.
The system grants privileges according to your identity and what you want to do.
MySQL considers both your hostname and user name in identifying you because there is
little reason to assume that a given user name belongs to the same person everywhere on
the Internet. For example, the user joe who connects from office.com need not be the
same person as the user joe who connects from elsewhere.com. MySQL handles this by
allowing you to distinguish users on different hosts that happen to have the same name:
you can grant joe one set of privileges for connections from office.com, and a different
set of privileges for connections from elsewhere.com.
MySQL access control involves two stages:
• Stage 1: The server checks whether you are even allowed to connect.
• Stage 2: Assuming you can connect, the server checks each request you issue to see
whether you have sufficient privileges to perform it. For example, if you try to select
rows from a table in a database or drop a table from the database, the server makes
sure you have the SELECT privilege for the table or the DROP privilege for the database.
Note that if your privileges are changed (either by yourself or someone else) while you are
connected, those changes will not necessarily take effect with your next query or queries.
See Section 4.4.3 [Privilege changes], page 248 for details.
The server uses the user, db, and host tables in the mysql database at both stages of access
control. The fields in these grant tables are shown here:
Table name
user
db
host
Scope fields
Privilege fields
Host
User
Password
Select_priv
Insert_priv
Update_priv
Delete_priv
Index_priv
Alter_priv
Create_priv
Host
Db
User
Select_priv
Insert_priv
Update_priv
Delete_priv
Index_priv
Alter_priv
Create_priv
Host
Db
Select_priv
Insert_priv
Update_priv
Delete_priv
Index_priv
Alter_priv
Create_priv
Chapter 4: Database Administration
Drop_priv
Grant_priv
223
Drop_priv
Grant_priv
Drop_priv
Grant_priv
References_
References_
References_
priv
priv
priv
Reload_priv
Shutdown_
priv
Process_priv
File_priv
Show_db_priv
Super_priv
Create_tmp_
Create_tmp_
Create_tmp_
table_priv
table_priv
table_priv
Lock_tables_
Lock_tables_
Lock_tables_
priv
priv
priv
Execute_priv
Repl_slave_
priv
Repl_client_
priv
ssl_type
ssl_cypher
x509_issuer
x509_cubject
max_
questions
max_updates
max_
connections
For the second stage of access control (request verification), the server may, if the request
involves tables, additionally consult the tables_priv and columns_priv tables. The fields
in these tables are shown here:
Table name
tables priv
columns priv
Scope fields
Host
Db
User
Table_name
Host
Db
User
Table_name
Column_name
Privilege fields
Table_priv
Column_priv
Timestamp
Grantor
Column_priv
Other fields
Timestamp
Each grant table contains scope fields and privilege fields.
Scope fields determine the scope of each entry in the tables, that is, the context in
which the entry applies. For example, a user table entry with Host and User values
of ’thomas.loc.gov’ and ’bob’ would be used for authenticating connections made
224
MySQL Technical Reference for Version 4.1.1-alpha
to the server by bob from the host thomas.loc.gov. Similarly, a db table entry with
Host, User, and Db fields of ’thomas.loc.gov’, ’bob’ and ’reports’ would be used
when bob connects from the host thomas.loc.gov to access the reports database.
The tables_priv and columns_priv tables contain scope fields indicating tables or
table/column combinations to which each entry applies.
For access-checking purposes, comparisons of Host values are case-insensitive. User,
Password, Db, and Table_name values are case-sensitive. Column_name values are
case-insensitive in MySQL Version 3.22.12 or later.
Privilege fields indicate the privileges granted by a table entry, that is, what operations
can be performed. The server combines the information in the various grant tables to form
a complete description of a user’s privileges. The rules used to do this are described in
Section 4.3.10 [Request access], page 231.
Scope fields are strings, declared as shown here; the default value for each is the empty
string:
Field name
Host
User
Password
Db
Type
CHAR(60)
CHAR(16)
CHAR(16)
CHAR(64)
Table_name
Column_name
CHAR(60)
CHAR(60)
Notes
(CHAR(60) for the tables_priv and columns_priv
tables)
In the user, db and host tables, all privilege fields are declared as ENUM(’N’,’Y’)—each
can have a value of ’N’ or ’Y’, and the default value is ’N’.
In the tables_priv and columns_priv tables, the privilege fields are declared as SET fields:
Table name
tables_priv
Field name
Table_
priv
Possible set elements
’Select’, ’Insert’, ’Update’, ’Delete’,
’Create’, ’Drop’, ’Grant’, ’References’,
’Index’, ’Alter’
tables_priv Column_
’Select’, ’Insert’, ’Update’,
priv
’References’
columns_
Column_
’Select’, ’Insert’, ’Update’,
priv
priv
’References’
Briefly, the server uses the grant tables like this:
• The user table scope fields determine whether to allow or reject incoming connections.
For allowed connections, any privileges granted in the user table indicate the user’s
global (superuser) privileges. These privileges apply to all databases on the server.
• The db and host tables are used together:
− The db table scope fields determine which users can access which databases from
which hosts. The privilege fields determine which operations are allowed.
− The host table is used as an extension of the db table when you want a given db
table entry to apply to several hosts. For example, if you want a user to be able to
use a database from several hosts in your network, leave the Host value empty in
the user’s db table entry, then populate the host table with an entry for each of
Chapter 4: Database Administration
225
those hosts. This mechanism is described more detail in Section 4.3.10 [Request
access], page 231.
• The tables_priv and columns_priv tables are similar to the db table, but are more
fine-grained: they apply at the table and column levels rather than at the database
level.
Note that administrative privileges (RELOAD, SHUTDOWN, etc.) are specified only in the user
table. This is because administrative operations are operations on the server itself and are
not database-specific, so there is no reason to list such privileges in the other grant tables.
In fact, only the user table need be consulted to determine whether you can perform an
administrative operation.
The FILE privilege is specified only in the user table, too. It is not an administrative
privilege as such, but your ability to read or write files on the server host is independent of
the database you are accessing.
The mysqld server reads the contents of the grant tables once, when it starts up. Changes
to the grant tables take effect as indicated in Section 4.4.3 [Privilege changes], page 248.
When you modify the contents of the grant tables, it is a good idea to make sure that
your changes set up privileges the way you want. For help in diagnosing problems, see
Section 4.3.12 [Access denied], page 238. For advice on security issues, see Section 4.3.2
[Security], page 219.
A useful diagnostic tool is the mysqlaccess script, which Yves Carlier has provided for the
MySQL distribution. Invoke mysqlaccess with the --help option to find out how it works.
Note that mysqlaccess checks access using only the user, db and host tables. It does not
check table- or column-level privileges.
4.3.7 Privileges Provided by MySQL
Information about user privileges is stored in the user, db, host, tables_priv, and
columns_priv tables in the mysql database (that is, in the database named mysql). The
MySQL server reads the contents of these tables when it starts up and under the circumstances indicated in Section 4.4.3 [Privilege changes], page 248.
The names used in this manual to refer to the privileges provided by MySQL version 4.0.2
are shown here, along with the table column name associated with each privilege in the
grant tables and the context in which the privilege applies. Further information about the
meaning of each privilege may be found at Section 4.4.1 [GRANT], page 242.
Privilege
ALTER
DELETE
INDEX
INSERT
SELECT
UPDATE
CREATE
DROP
GRANT
Column
Alter_priv
Delete_priv
Index_priv
Insert_priv
Select_priv
Update_priv
Create_priv
Drop_priv
Grant_priv
Context
tables
tables
tables
tables
tables
tables
databases, tables, or indexes
databases or tables
databases or tables
226
MySQL Technical Reference for Version 4.1.1-alpha
REFERENCES
CREATE
TEMPORARY
TABLES
EXECUTE
FILE
LOCK TABLES
PROCESS
RELOAD
REPLICATION
CLIENT
REPLICATION
SLAVE
SHOW
DATABASES
SHUTDOWN
SUPER
References_
priv
Create_tmp_
table_priv
databases or tables
Execute_priv
File_priv
Lock_tables_
priv
Process_priv
Reload_priv
Repl_client_
priv
Repl_slave_
priv
Show_db_priv
server administration
file access on server
server administration
Shutdown_
priv
Super_priv
server administration
server administration
server administration
server administration
server administration
server administration
server administration
server administration
The SELECT, INSERT, UPDATE, and DELETE privileges allow you to perform operations on
rows in existing tables in a database.
SELECT statements require the SELECT privilege only if they actually retrieve rows from a
table. You can execute certain SELECT statements even without permission to access any
of the databases on the server. For example, you could use the mysql client as a simple
calculator:
mysql> SELECT 1+1;
mysql> SELECT PI()*2;
The INDEX privilege allows you to create or drop (remove) indexes.
The ALTER privilege allows you to use ALTER TABLE.
The CREATE and DROP privileges allow you to create new databases and tables, or to drop
(remove) existing databases and tables.
Note that if you grant the DROP privilege for the mysql database to a user, that user can
drop the database in which the MySQL access privileges are stored!
The GRANT privilege allows you to give to other users those privileges you yourself possess.
The FILE privilege gives you permission to read and write files on the server using the LOAD
DATA INFILE and SELECT ... INTO OUTFILE statements. Any user to whom this privilege
is granted can read any world readable file accessable by the MySQL server and create a
new world readable file in any directory where the MySQL server can write. The user can
also read any file in the current database directory. The user can however not change any
existing file.
The remaining privileges are used for administrative operations, which are performed using the mysqladmin program. The table here shows which mysqladmin commands each
administrative privilege allows you to execute:
Privilege
Commands permitted to privilege holders
Chapter 4: Database Administration
227
RELOAD
reload, refresh, flush-privileges, flush-hosts, flushlogs, and flush-tables
SHUTDOWN
shutdown
PROCESS
processlist
SUPER
kill
The reload command tells the server to re-read the grant tables. The refresh command
flushes all tables and opens and closes the log files. flush-privileges is a synonym for
reload. The other flush-* commands perform functions similar to refresh but are more
limited in scope, and may be preferable in some instances. For example, if you want to
flush just the log files, flush-logs is a better choice than refresh.
The shutdown command shuts down the server.
The processlist command displays information about the threads executing within the
server. The kill command kills server threads. You can always display or kill your own
threads, but you need the PROCESS privilege to display and SUPER privilege to kill threads
initiated by other users. See Section 4.6.7 [KILL], page 287.
It is a good idea in general to grant privileges only to those users who need them, but you
should exercise particular caution in granting certain privileges:
• The GRANT privilege allows users to give away their privileges to other users. Two users
with different privileges and with the GRANT privilege are able to combine privileges.
• The ALTER privilege may be used to subvert the privilege system by renaming tables.
• The FILE privilege can be abused to read any world-readable file on the server or any
file in the current database directory on the server into a database table, the contents
of which can then be accessed using SELECT.
• The SHUTDOWN privilege can be abused to deny service to other users entirely, by terminating the server.
• The PROCESS privilege can be used to view the plain text of currently executing queries,
including queries that set or change passwords.
• Privileges on the mysql database can be used to change passwords and other access
privilege information. (Passwords are stored encrypted, so a malicious user cannot
simply read them to know the plain text password.) If they can access the mysql.user
password column, they can use it to log into the MySQL server for the given user.
(With sufficient privileges, the same user can replace a password with a different one.)
There are some things that you cannot do with the MySQL privilege system:
• You cannot explicitly specify that a given user should be denied access. That is, you
cannot explicitly match a user and then refuse the connection.
• You cannot specify that a user has privileges to create or drop tables in a database but
not to create or drop the database itself.
4.3.8 Connecting to the MySQL Server
MySQL client programs generally require that you specify connection parameters when you
want to access a MySQL server: the host you want to connect to, your user name, and your
password. For example, the mysql client can be started like this (optional arguments are
enclosed between ‘[’ and ‘]’):
228
MySQL Technical Reference for Version 4.1.1-alpha
shell> mysql [-h host_name] [-u user_name] [-pyour_pass]
Alternate forms of the -h, -u, and -p options are --host=host_name, --user=user_name,
and --password=your_pass. Note that there is no space between -p or --password= and
the password following it.
Note: Specifying a password on the command-line is not secure! Any user on your system
may then find out your password by typing a command like: ps auxww. See Section 4.1.2
[Option files], page 206.
mysql uses default values for connection parameters that are missing from the commandline:
• The default hostname is localhost.
• The default user name is your Unix login name.
• No password is supplied if -p is missing.
Thus, for a Unix user joe, the following commands are equivalent:
shell> mysql -h localhost -u joe
shell> mysql -h localhost
shell> mysql -u joe
shell> mysql
Other MySQL clients behave similarly.
On Unix systems, you can specify different default values to be used when you make a
connection, so that you need not enter them on the command-line each time you invoke a
client program. This can be done in a couple of ways:
• You can specify connection parameters in the [client] section of the ‘.my.cnf’ configuration file in your home directory. The relevant section of the file might look like
this:
[client]
host=host_name
user=user_name
password=your_pass
See Section 4.1.2 [Option files], page 206.
• You can specify 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 only). The password can be specified using MYSQL_PWD
(but this is insecure; see the next section). See Appendix F [Environment variables],
page 1032.
4.3.9 Access Control, Stage 1: Connection Verification
When you attempt to connect to a MySQL server, the server accepts or rejects the connection based on your identity and whether you can verify your identity by supplying the
correct password. If not, the server denies access to you completely. Otherwise, the server
accepts the connection, then enters Stage 2 and waits for requests.
Your identity is based on two pieces of information:
• The host from which you connect
Chapter 4: Database Administration
229
• Your MySQL user name
Identity checking is performed using the three user table scope fields (Host, User, and
Password). The server accepts the connection only if a user table entry matches your
hostname and user name, and you supply the correct password.
Values in the user table scope fields may be specified as follows:
• A Host value may be a hostname or an IP number, or ’localhost’ to indicate the
local host.
• You can use the wildcard characters ‘%’ and ‘_’ in the Host field.
• A Host value of ’%’ matches any hostname.
• A blank Host value means that the privilege should be anded with the entry in the
host table that matches the given host name. You can find more information about
this in the next chapter.
• As of MySQL Version 3.23, for Host values specified as IP numbers, you can specify a
netmask indicating how many address bits to use for the network number. For example:
mysql> GRANT ALL PRIVILEGES ON db.*
-> TO [email protected]’192.58.197.0/255.255.255.0’;
This will allow everyone to connect from an IP where the following is true:
user_ip & netmask = host_ip.
In the above example all IP:s in the interval 192.58.197.0 - 192.58.197.255 can connect
to the MySQL server.
• Wildcard characters are not allowed in the User field, but you can specify a blank
value, which matches any name. If the user table entry that matches an incoming
connection has a blank user name, the user is considered to be the anonymous user
(the user with no name), rather than the name that the client actually specified. This
means that a blank user name is used for all further access checking for the duration
of the connection (that is, during Stage 2).
• The Password field can be blank. This does not mean that any password matches, it
means the user must connect without specifying a password.
Non-blank Password values represent encrypted passwords. MySQL does not store passwords in plaintext form for anyone to see. Rather, the password supplied by a user who
is attempting to connect is encrypted (using the PASSWORD() function). The encrypted
password is then used when the client/server is checking if the password is correct. (This is
done without the encrypted password ever traveling over the connection.) Note that from
MySQL’s point of view the encrypted password is the REAL password, so you should not
give anyone access to it! In particular, don’t give normal users read access to the tables
in the mysql database! From version 4.1, MySQL employs a different password and login
mechanism that is secure even if TCP/IP packets are sniffed and/or the mysql database is
captured.
The examples here show how various combinations of Host and User values in user table
entries apply to incoming connections:
Host value
’thomas.loc.gov’
User value
’fred’
Connections matched by entry
fred, connecting from thomas.loc.gov
230
’thomas.loc.gov’
MySQL Technical Reference for Version 4.1.1-alpha
’’
Any
user,
connecting
from
thomas.loc.gov
’%’
’fred’
fred, connecting from any host
’%’
’’
Any user, connecting from any host
’%.loc.gov’
’fred’
fred, connecting from any host in the
loc.gov domain
’x.y.%’
’fred’
fred,
connecting
from
x.y.net,
x.y.com,x.y.edu, etc. (this is probably
not useful)
’144.155.166.177’
’fred’
fred, connecting from the host with IP address 144.155.166.177
’144.155.166.%’
’fred’
fred, connecting from any host in the
144.155.166 class C subnet
’144.155.166.0/255.255.255.0’’fred’
Same as previous example
Because you can use IP wildcard values in the Host field (for example, ’144.155.166.%’ to
match every host on a subnet), there is the possibility that someone might try to exploit this
capability by naming a host 144.155.166.somewhere.com. To foil such attempts, MySQL
disallows matching on hostnames that start with digits and a dot. Thus, if you have a
host named something like 1.2.foo.com, its name will never match the Host column of the
grant tables. Only an IP number can match an IP wildcard value.
An incoming connection may be matched by more than one entry in the user table. For
example, a connection from thomas.loc.gov by fred would be matched by several of the
entries shown in the preceding table. How does the server choose which entry to use if more
than one matches? The server resolves this question by sorting the user table after reading
it at startup time, then looking through the entries in sorted order when a user attempts
to connect. The first matching entry is the one that is used.
user table sorting works as follows. Suppose the user table looks like this:
+-----------+----------+| Host
| User
| ...
+-----------+----------+| %
| root
| ...
| %
| jeffrey | ...
| localhost | root
| ...
| localhost |
| ...
+-----------+----------+When the server reads in the table, it orders the entries with the most-specific Host values
first (’%’ in the Host column means “any host” and is least specific). Entries with the same
Host value are ordered with the most-specific User values first (a blank User value means
“any user” and is least specific). The resulting sorted user table looks like this:
+-----------+----------+| Host
| User
| ...
+-----------+----------+| localhost | root
| ...
| localhost |
| ...
| %
| jeffrey | ...
| %
| root
| ...
+-----------+----------+-
Chapter 4: Database Administration
231
When a connection is attempted, the server looks through the sorted entries and uses
the first match found. For a connection from localhost by jeffrey, the entries with
’localhost’ in the Host column match first. Of those, the entry with the blank user name
matches both the connecting hostname and user name. (The ’%’/’jeffrey’ entry would
have matched, too, but it is not the first match in the table.)
Here is another example. Suppose the user table looks like this:
+----------------+----------+| Host
| User
| ...
+----------------+----------+| %
| jeffrey | ...
| thomas.loc.gov |
| ...
+----------------+----------+The sorted table looks like this:
+----------------+----------+| Host
| User
| ...
+----------------+----------+| thomas.loc.gov |
| ...
| %
| jeffrey | ...
+----------------+----------+A connection from thomas.loc.gov by jeffrey is matched by the first entry, whereas a
connection from whitehouse.gov by jeffrey is matched by the second.
A common misconception is to think that for a given user name, all entries that explicitly
name that user will be used first when the server attempts to find a match for the connection.
This is simply not true. The previous example illustrates this, where a connection from
thomas.loc.gov by jeffrey is first matched not by the entry containing ’jeffrey’ as the
User field value, but by the entry with no user name!
If you have problems connecting to the server, print out the user table and sort it by hand
to see where the first match is being made. If connection was successful, but your privileges
are not what you expected you may use CURRENT_USER() function (new in version 4.0.6)
to see what user/host combination your connection actually matched. See Section 6.3.6.2
[CURRENT_USER()], page 521.
4.3.10 Access Control, Stage 2: Request Verification
Once you establish a connection, the server enters Stage 2. For each request that comes in
on the connection, the server checks whether you have sufficient privileges to perform it,
based on the type of operation you wish to perform. This is where the privilege fields in
the grant tables come into play. These privileges can come from any of the user, db, host,
tables_priv, or columns_priv tables. The grant tables are manipulated with GRANT and
REVOKE commands. See Section 4.4.1 [GRANT], page 242. (You may find it helpful to refer
to Section 4.3.6 [Privileges], page 222, which lists the fields present in each of the grant
tables.)
The user table grants privileges that are assigned to you on a global basis and that apply no
matter what the current database is. For example, if the user table grants you the DELETE
privilege, you can delete rows from any database on the server host! In other words, user
232
MySQL Technical Reference for Version 4.1.1-alpha
table privileges are superuser privileges. It is wise to grant privileges in the user table only
to superusers such as server or database administrators. For other users, you should leave
the privileges in the user table set to ’N’ and grant privileges on a database-specific basis
only, using the db and host tables.
The db and host tables grant database-specific privileges. Values in the scope fields may
be specified as follows:
• The wildcard characters ‘%’ and ‘_’ can be used in the Host and Db fields of either table.
If you wish to use for instance a ‘_’ character as part of a database name, specify it as
‘\_’ in the GRANT command.
• A ’%’ Host value in the db table means “any host.” A blank Host value in the db
table means “consult the host table for further information.”
• A ’%’ or blank Host value in the host table means “any host.”
• A ’%’ or blank Db value in either table means “any database.”
• A blank User value in either table matches the anonymous user.
The db and host tables are read in and sorted when the server starts up (at the same time
that it reads the user table). The db table is sorted on the Host, Db, and User scope fields,
and the host table is sorted on the Host and Db scope fields. As with the user table, sorting
puts the most-specific values first and least-specific values last, and when the server looks
for matching entries, it uses the first match that it finds.
The tables_priv and columns_priv tables grant table- and column-specific privileges.
Values in the scope fields may be specified as follows:
• The wildcard characters ‘%’ and ‘_’ can be used in the Host field of either table.
• A ’%’ or blank Host value in either table means “any host.”
• The Db, Table_name and Column_name fields cannot contain wildcards or be blank in
either table.
The tables_priv and columns_priv tables are sorted on the Host, Db, and User fields.
This is similar to db table sorting, although the sorting is simpler because only the Host
field may contain wildcards.
The request verification process is described here. (If you are familiar with the accesschecking source code, you will notice that the description here differs slightly from the
algorithm used in the code. The description is equivalent to what the code actually does;
it differs only to make the explanation simpler.)
For administrative requests (SHUTDOWN, RELOAD, etc.), the server checks only the user table
entry, because that is the only table that specifies administrative privileges. Access is
granted if the entry allows the requested operation and denied otherwise. For example, if
you want to execute mysqladmin shutdown but your user table entry doesn’t grant the
SHUTDOWN privilege to you, access is denied without even checking the db or host tables.
(They contain no Shutdown_priv column, so there is no need to do so.)
For database-related requests (INSERT, UPDATE, etc.), the server first checks the user’s global
(superuser) privileges by looking in the user table entry. If the entry allows the requested
operation, access is granted. If the global privileges in the user table are insufficient, the
server determines the user’s database-specific privileges by checking the db and host tables:
Chapter 4: Database Administration
233
1. The server looks in the db table for a match on the Host, Db, and User fields. The
Host and User fields are matched to the connecting user’s hostname and MySQL user
name. The Db field is matched to the database the user wants to access. If there is no
entry for the Host and User, access is denied.
2. If there is a matching db table entry and its Host field is not blank, that entry defines
the user’s database-specific privileges.
3. If the matching db table entry’s Host field is blank, it signifies that the host table
enumerates which hosts should be allowed access to the database. In this case, a
further lookup is done in the host table to find a match on the Host and Db fields. If
no host table entry matches, access is denied. If there is a match, the user’s databasespecific privileges are computed as the intersection (not the union!) of the privileges
in the db and host table entries, that is, the privileges that are ’Y’ in both entries.
(This way you can grant general privileges in the db table entry and then selectively
restrict them on a host-by-host basis using the host table entries.)
After determining the database-specific privileges granted by the db and host table entries,
the server adds them to the global privileges granted by the user table. If the result allows
the requested operation, access is granted. Otherwise, the server checks the user’s table
and column privileges in the tables_priv and columns_priv tables and adds those to the
user’s privileges. Access is allowed or denied based on the result.
Expressed in boolean terms, the preceding description of how a user’s privileges are calculated may be summarised like this:
global privileges
OR (database privileges AND host privileges)
OR table privileges
OR column privileges
It may not be apparent why, if the global user entry privileges are initially found to be
insufficient for the requested operation, the server adds those privileges to the database-,
table-, and column-specific privileges later. The reason is that a request might require more
than one type of privilege. For example, if you execute an INSERT ... SELECT statement,
you need both INSERT and SELECT privileges. Your privileges might be such that the user
table entry grants one privilege and the db table entry grants the other. In this case, you
have the necessary privileges to perform the request, but the server cannot tell that from
either table by itself; the privileges granted by the entries in both tables must be combined.
The host table can be used to maintain a list of secure servers.
At TcX, the host table contains a list of all machines on the local network. These are
granted all privileges.
You can also use the host table to indicate hosts that are not secure. Suppose you have
a machine public.your.domain that is located in a public area that you do not consider
secure. You can allow access to all hosts on your network except that machine by using
host table entries like this:
+--------------------+----+| Host
| Db | ...
+--------------------+----+| public.your.domain | % | ... (all privileges set to ’N’)
234
MySQL Technical Reference for Version 4.1.1-alpha
| %.your.domain
| % | ... (all privileges set to ’Y’)
+--------------------+----+Naturally, you should always test your entries in the grant tables (for example, using
mysqlaccess) to make sure your access privileges are actually set up the way you think
they are.
4.3.11 Password Hashing in MySQL 4.1
MySQL user accounts are listed in the user table of the mysql database. Each MySQL
account is assigned a password, although what is stored in the Password column of the
user table is not the plaintext version of the password, but a hash value computed from it.
Password hash values are computed by the PASSWORD() function.
MySQL uses passwords in two phases of client/server communication:
• First, when a client attempts to connect to the server, there is an initial authentication
step in which the client must present a password that matches the hash value stored
in the user table for the account that the client wants to use.
• Second, after the client connects, it may set or change the password hashes for accounts
listed in the user table (if it has sufficient privileges). The client may do this by using
the PASSWORD() function to generate a password hash, or by using the GRANT or
SET PASSWORD statements.
In other words, the server uses hash values during authentication when a client first attempts
to connect. The server generates hash values if a connected client invokes the PASSWORD()
function or uses a GRANT or SET PASSWORD statement to set or change a password.
The password hashing mechanism was updated in MySQL 4.1 to provide better security and
to reduce the risk of passwords being stolen. However, this new mechanism is understood
only by the 4.1 server and 4.1 clients, which can result in some compatibility problems. A
4.1 client can connect to a pre-4.1 server, because the client understands both the old and
new password hashing mechanisms. However, a pre-4.1 client that attempts to connect to
a 4.1 server may run into difficulties. For example, a 4.0 mysql client that attempts to
connect to a 4.1 server may fail with the following error message:
shell> mysql
Client does not support authentication protocol requested
by server; consider upgrading MySQL client
The following discussion describes the differences between the old and new password mechanisms, and what you should do if you upgrade your server to 4.1 but need to maintain
backward compatibility with pre-4.1 clients.
Note: This discussion contrasts 4.1 behaviour with pre-4.1 behaviour, but the 4.1 behaviour
described here actually begins with 4.1.1. MySQL 4.1.0 is an “odd” release because it has
a slightly different mechanism than that implemented in 4.1.1 and up. Differences between
4.1.0 and more recent versions are described later.
Prior to MySQL 4.1, password hashes computed by the PASSWORD() function are 16 bytes
long. Such hashes look like this:
mysql> SELECT PASSWORD(’mypass’);
+--------------------+
Chapter 4: Database Administration
235
| PASSWORD(’mypass’) |
+--------------------+
| 6f8c114b58f2ce9e
|
+--------------------+
The Password column of the user table (in which these hashes are stored) also is 16 bytes
long before MySQL 4.1.
As of MySQL 4.1, the PASSWORD() function has been modified to produce a longer 41-byte
hash value:
mysql> SELECT PASSWORD(’mypass’);
+-----------------------------------------------+
| PASSWORD(’mypass’)
|
+-----------------------------------------------+
| *43c8aa34cdc98eddd3de1fe9a9c2c2a9f92bb2098d75 |
+-----------------------------------------------+
Accordingly, the Password column in the user table also must be 41 bytes long to store
these values:
• If you perform a new installation of MySQL 4.1, the Password column will be made
41 bytes long automatically.
• If you upgrade an older installation to 4.1, you should run the mysql_fix_privilege_
tables script to update the length of the Password column from 16 to 41 bytes. (The
script does not change existing password values, which remain 16 bytes long.)
A widened Password column can store password hashes in both the old and new formats.
The format of any given password hash value can be determined two ways:
• The obvious difference is the length (16 bytes versus 41 bytes)
• A second difference is that password hashes in the new format always begin with a ‘*’
character, whereas passwords in the old format never do
The longer password hash format has better cryptographic properties, and client authentication based on long hashes is more secure than that based on the older short hashes.
The differences between short and long password hashes are relevant both for how the
server uses passwords during authentication and for how it generates password hashes for
connected clients that perform password-changing operations.
The way in which the server uses password hashes during authentication is affected by the
width of the Password column:
• If the column is narrow, only short-hash authentication is used.
• If the column is wide, it can hold either short or long hashes, and the server can use
either format:
• Pre-4.1 clients can connect, though because they know only about the old hashing
mechanism, they can authenticate only for accounts that have short hashes.
• 4.1 clients can authenticate for accounts that have short or long hashes.
For short-hash accounts, the authentication process is actually a bit more secure for 4.1
clients than for older clients. In terms of security, the gradient from least to most secure is:
• Pre-4.1 client authenticating for account with short password hash
236
MySQL Technical Reference for Version 4.1.1-alpha
• 4.1 client authenticating for account with short password hash
• 4.1 client authenticating for account with long password hash
The way in which the server generates password hashes for connected clients is affected
by the width of the Password column and by the --old-passwords option. A 4.1 server
generates long hashes only if certain conditions are met: The Password column must be
wide enough to hold long values and the --old-passwords option must not be given. These
conditions apply as follows:
• The Password column must be wide enough to hold long hashes (41 bytes). If the
column has not been updated and still has the pre-4.1 width (16 bytes), the server
notices that long hashes cannot fit into it and generates only short hashes when a client
performs password-changing operations using PASSWORD(), GRANT, or SET PASSWORD.
(This behaviour occurs if you have upgraded to 4.1 but have not run the mysql_fix_
privilege_tables script to widen the Password column.)
• If the Password column is wide, it can store either short or long password hashes. In
this case, PASSWORD(), GRANT, and SET PASSWORD will generate long hashes unless the
server was started with the --old-passwords option. This option forces the server to
generate short passsword hashes instead.
The purpose of the --old-passwords option is to allow you to maintain backward compatibility with pre-4.1 clients under circumstances where the server would otherwise generate
long password hashes. It doesn’t affect authentication (4.1 clients can still use accounts
that have long password hashes), but it does prevent creation of a long password hash in
the user table as the result of a password-changing operation. Were that to occur, the
account no longer could be used by pre-4.1 clients. Without the --old-passwords option,
the following scenario is possible:
• An old client connects to an account that has a short password hash.
• The client changes the account’s password. Without --old-passwords, this results in
the account having a long password hash.
• The next time the old client attempts to connect to the account, it cannot, because
the account now requires the new hashing mechanism during authentication. (Once an
account has a long password hash in the user table, only 4.1 clients can authenticate
for it, because pre-4.1 clients do not understand long hashes.)
This scenario illustrates that it is dangerous to run a 4.1 server without using the --oldpasswords option if you must support older pre-4.1 clients. By running the server with
--old-passwords, password-changing operations will not generate long password hashes
and thus do not cause accounts to become inaccessible to older clients. (Those clients
cannot inadvertently lock themselves out by changing their password and ending up with a
long password hash.)
The downside of the --old-passwords option is that any passwords you create or change
will use short hashes, even for 4.1 clients. Thus, you lose the additional security provided by
long password hashes. If you want to create an account that has a long hash (for example,
for use by 4.1 clients), you must do so while running the server without --old-passwords.
The following scenarios are possible for running a 4.1 server:
Scenario 1) Narrow Password column in user table
Chapter 4: Database Administration
237
• Only short hashes can be stored in the Password column.
• The server uses only short hashes during client authentication.
• For connected clients, password hash-generating operations involving PASSWORD(),
GRANT, or SET PASSWORD use short hashes exclusively. Any change to an account’s
password results in that account having a short password hash.
• The --old-passwords option can be used but is superfluous because with a narrow
Password column, the server will be generating short password hashes anyway.
Scenario 2) Long Password column; server not started with --old-passwords option
• Short or long hashes can be stored in the Password column.
• 4.1 clients can authenticate for accounts that have short or long hashes.
• Pre-4.1 clients can authenticate only for accounts that have short hashes.
• For connected clients, password hash-generating operations involving PASSWORD(),
GRANT, or SET PASSWORD use long hashes exclusively. Any change to an account’s
password results in that account having a long password hash.
• OLD_PASSWORD() may be used to explicitly generate a short hash. For example, to
assign an account a short password, use UPDATE as follows:
mysql> UPDATE user SET Password = OLD_PASSWORD(’mypass’)
-> WHERE Host = ’some_host’ AND User = ’some_user’;
mysql> FLUSH PRIVILEGES;
As indicated earlier, a danger in this scenario is that it is possible for accounts that have
a short password hash to become inaccessible to pre-4.1 clients. Any change to such an
account’s password made via GRANT, SET PASSWORD, or PASSWORD() results in the account
being given a long password hash, and from that point on, no pre-4.1 client can authenticate
to that account until the client upgrades to 4.1.
Scenario 3) Long Password column; server started with --old-passwords option
• Short or long hashes can be stored in the Password column.
• 4.1 clients can authenticate for accounts that have short or long hashes (but note that
it is possible to create long hashes only when the server is started without --oldpasswords).
• Pre-4.1 clients can authenticate only for accounts that have short hashes.
• For connected clients, password hash-generating operations involving PASSWORD(),
GRANT, or SET PASSWORD use short hashes exclusively. Any change to an account’s
password results in that account having a short password hash.
In this scenario, you cannot create accounts that have long password hashes, because -old-passwords prevents generation of long hashes. Also, if you create an account with a
long hash before using the --old-passwords option, changing the account’s password while
--old-passwords is in effect results in the account being given a short password, causing
it to lose the security benefits of a longer hash.
The disadvantages for these scenarios may be summarized as follows:
Scenario 1) You cannot take advantage of longer hashes that provide more secure authentication.
238
MySQL Technical Reference for Version 4.1.1-alpha
Scenario 2) Accounts with short hashes become inaccessible to pre-4.1 clients if you change
their passwords without explicitly using OLD_PASSWORD().
Scenario 3) --old-passwords prevents accounts with short hashes from becoming inaccessible, but password-changing operations cause accounts with long hashes to revert to short
hashes, and you cannot change them back to long hashes while --old-passwords is in
effect.
Implications of Password Hashing Changes for Application
Programs
An upgrade to MySQL 4.1 can cause a compatibility issue for applications that use
PASSWORD() to generate passwords for their own purposes. (Applications really should
not do this, because PASSWORD() should be used only to manage passwords for MySQL
accounts. But some applications use PASSWORD() for their own purposes anyway.) If you
upgrade to 4.1 and run the server under conditions where it generates long password
hashes, an application that uses PASSWORD() for its own passwords will break. The
recommended course of action is to modify the application to use another function such
as SHA1() or MD5() to produce hashed values. If that is not possible, you can use the
OLD_PASSWORD() function, which is provided to generate short hashes in the old format.
(But note that OLD_PASSWORD() may one day no longer be supported.)
If the server is running under circumstances where it generates short hashes,
OLD_PASSWORD() is available but is equivalent to PASSWORD().
Password hashing in MySQL 4.1.0 differs from hashing in 4.1.1 and up. The 4.1.0 differences
are:
• Password hashes are 45 bytes long rather than 41 bytes.
• The PASSWORD() function is non-repeatable. That is, with a given argument X, successive calls to PASSWORD(X) generate different results.
4.3.12 Causes of Access denied Errors
If you encounter Access denied errors when you try to connect to the MySQL server, the
following list indicates some courses of action you can take to correct the problem:
• After installing MySQL, did you run the mysql_install_db script to set up the initial
grant table contents? If not, do so. See Section 4.4.4 [Default privileges], page 248.
Test the initial privileges by executing this command:
shell> mysql -u root test
The server should let you connect without error. You should also make sure
you have a file ‘user.MYD’ in the MySQL database directory. Ordinarily, this is
‘PATH/var/mysql/user.MYD’, where PATH is the pathname to the MySQL installation
root.
• After a fresh installation, you should connect to the server and set up your users and
their access permissions:
shell> mysql -u root mysql
Chapter 4: Database Administration
239
The server should let you connect because the MySQL root user has no password
initially. That is also a security risk, so setting the root password is something you
should do while you’re setting up your other MySQL users.
If you try to connect as root and get this error:
Access denied for user: ’@unknown’ to database mysql
this means that you don’t have an entry in the user table with a User column value of
’root’ and that mysqld cannot resolve the hostname for your client. In this case,
you must restart the server with the --skip-grant-tables option and edit your
‘/etc/hosts’ or ‘\windows\hosts’ file to add an entry for your host.
• If you get an error like the following:
shell> mysqladmin -u root -pxxxx ver
Access denied for user: ’[email protected]’ (Using password: YES)
It means that you are using an incorrect password. See Section 4.4.8 [Passwords],
page 253.
If you have forgot the root password, you can restart mysqld with --skip-granttables to change the password. See Section A.4.2 [Resetting permissions], page 872.
If you get the above error even if you haven’t specified a password, this means that
you have an incorrect password in some my.ini file. See Section 4.1.2 [Option files],
page 206. You can avoid using option files with the --no-defaults option, as follows:
shell> mysqladmin --no-defaults -u root ver
• If you updated an existing MySQL installation from a version earlier than Version
3.22.11 to Version 3.22.11 or later, did you run the mysql_fix_privilege_tables
script? If not, do so. The structure of the grant tables changed with MySQL Version
3.22.11 when the GRANT statement became functional. See Section 2.5.6 [Upgradinggrant-tables], page 123.
• If your privileges seem to have changed in the middle of a session, it may be that a
superuser has changed them. Reloading the grant tables affects new client connections,
but it also affects existing connections as indicated in Section 4.4.3 [Privilege changes],
page 248.
• If you can’t get your password to work, remember that you must use the PASSWORD()
function if you set the password with the INSERT, UPDATE, or SET PASSWORD statements. The PASSWORD() function is unnecessary if you specify the password using
the GRANT ... IDENTIFIED BY statement or the mysqladmin password command. See
Section 4.4.8 [Passwords], page 253.
• localhost is a synonym for your local hostname, and is also the default host to
which clients try to connect if you specify no host explicitly. However, connections
to localhost do not work if you are using a MySQL version prior to 3.23.27 that uses
MIT-pthreads (localhost connections are made using Unix sockets, which were not
supported by MIT-pthreads at that time). To avoid this problem on such systems,
you should use the --host option to name the server host explicitly. This will make
a TCP/IP connection to the mysqld server. In this case, you must have your real
hostname in user table entries on the server host. (This is true even if you are running
a client program on the same host as the server.)
240
MySQL Technical Reference for Version 4.1.1-alpha
• If you get an Access denied error when trying to connect to the database with mysql
-u user_name db_name, you may have a problem with the user table. Check this by
executing mysql -u root mysql and issuing this SQL statement:
mysql> SELECT * FROM user;
The result should include an entry with the Host and User columns matching your
computer’s hostname and your MySQL user name.
• The Access denied error message will tell you who you are trying to log in as, the
host from which you are trying to connect, and whether or not you were using a
password. Normally, you should have one entry in the user table that exactly matches
the hostname and user name that were given in the error message. For example if you
get an error message that contains Using password: NO, this means that you tried to
login without an password.
• If you get the following error when you try to connect from a different host than the
one on which the MySQL server is running, then there is no row in the user table that
matches that host:
Host ... is not allowed to connect to this MySQL server
You can fix this by using the command-line tool mysql (on the server host!) to add
a row to the user, db, or host table for the user/hostname combination from which
you are trying to connect and then execute mysqladmin flush-privileges. If you are
not running MySQL Version 3.22 and you don’t know the IP number or hostname of
the machine from which you are connecting, you should put an entry with ’%’ as the
Host column value in the user table and restart mysqld with the --log option on the
server machine. After trying to connect from the client machine, the information in
the MySQL log will indicate how you really did connect. (Then replace the ’%’ in the
user table entry with the actual hostname that shows up in the log. Otherwise, you’ll
have a system that is insecure.)
Another reason for this error on Linux is that you are using a binary MySQL version
that is compiled with a different glibc version than the one you are using. In this case
you should either upgrade your OS/glibc or download the source MySQL version and
compile this yourself. A source RPM is normally trivial to compile and install, so this
isn’t a big problem.
• If you get an error message where the hostname is not shown or where the hostname
is an IP, even if you try to connect with a hostname:
shell> mysqladmin -u root -pxxxx -h some-hostname ver
Access denied for user: ’[email protected]’ (Using password: YES)
This means that MySQL got some error when trying to resolve the IP to a hostname.
In this case you can execute mysqladmin flush-hosts to reset the internal DNS cache.
See Section 5.5.5 [DNS], page 436.
Some permanent solutions are:
− Try to find out what is wrong with your DNS server and fix this.
− Specify IPs instead of hostnames in the MySQL privilege tables.
− Start mysqld with --skip-name-resolve.
− Start mysqld with --skip-host-cache.
Chapter 4: Database Administration
•
•
•
•
•
•
241
− Connect to localhost if you are running the server and the client on the same
machine.
− Put the client machine names in /etc/hosts.
If mysql -u root test works but mysql -h your_hostname -u root test results in
Access denied, then you may not have the correct name for your host in the user table. A common problem here is that the Host value in the user table entry specifies an
unqualified hostname, but your system’s name resolution routines return a fully qualified domain name (or vice-versa). For example, if you have an entry with host ’tcx’ in
the user table, but your DNS tells MySQL that your hostname is ’tcx.subnet.se’,
the entry will not work. Try adding an entry to the user table that contains the IP
number of your host as the Host column value. (Alternatively, you could add an entry
to the user table with a Host value that contains a wildcard—for example, ’tcx.%’.
However, use of hostnames ending with ‘%’ is insecure and is not recommended!)
If mysql -u user_name test works but mysql -u user_name other_db_name doesn’t
work, you don’t have an entry for other_db_name listed in the db table.
If mysql -u user_name db_name works when executed on the server machine, but mysql
-h host_name -u user_name db_name doesn’t work when executed on another client
machine, you don’t have the client machine listed in the user table or the db table.
If you can’t figure out why you get Access denied, remove from the user table all
entries that have Host values containing wildcards (entries that contain ‘%’ or ‘_’). A
very common error is to insert a new entry with Host=’%’ and User=’some user’,
thinking that this will allow you to specify localhost to connect from the same machine. The reason that this doesn’t work is that the default privileges include an
entry with Host=’localhost’ and User=’’. Because that entry has a Host value
’localhost’ that is more specific than ’%’, it is used in preference to the new entry when connecting from localhost! The correct procedure is to insert a second
entry with Host=’localhost’ and User=’some_user’, or to remove the entry with
Host=’localhost’ and User=’’.
If you get the following error, you may have a problem with the db or host table:
Access to database denied
If the entry selected from the db table has an empty value in the Host column, make
sure there are one or more corresponding entries in the host table specifying which
hosts the db table entry applies to.
If you get the error when using the SQL commands SELECT ... INTO OUTFILE or LOAD
DATA INFILE, your entry in the user table probably doesn’t have the FILE privilege
enabled.
Remember that client programs will use connection parameters specified in configuration files or environment variables. See Appendix F [Environment variables], page 1032.
If a client seems to be sending the wrong default connection parameters when you don’t
specify them on the command-line, check your environment and the ‘.my.cnf’ file in
your home directory. You might also check the system-wide MySQL configuration files,
though it is far less likely that client connection parameters will be specified there. See
Section 4.1.2 [Option files], page 206. If you get Access denied when you run a client
without any options, make sure you haven’t specified an old password in any of your
option files! See Section 4.1.2 [Option files], page 206.
242
MySQL Technical Reference for Version 4.1.1-alpha
• If you make changes to the grant tables directly (using an INSERT or UPDATE statement) and your changes seem to be ignored, remember that you must issue a FLUSH
PRIVILEGES statement or execute a mysqladmin flush-privileges command to cause
the server to re-read the privilege tables. Otherwise, your changes have no effect until
the next time the server is restarted. Remember that after you set the root password with an UPDATE command, you won’t need to specify it until after you flush the
privileges, because the server won’t know you’ve changed the password yet!
• If you have access problems with a Perl, PHP, Python, or ODBC program, try to connect to the server with mysql -u user_name db_name or mysql -u user_name -pyour_
pass db_name. If you are able to connect using the mysql client, there is a problem
with your program and not with the access privileges. (Note that there is no space
between -p and the password; you can also use the --password=your_pass syntax to
specify the password. If you use the -p option alone, MySQL will prompt you for the
password.)
• For testing, start the mysqld daemon with the --skip-grant-tables option. Then
you can change the MySQL grant tables and use the mysqlaccess script to check
whether your modifications have the desired effect. When you are satisfied with your
changes, execute mysqladmin flush-privileges to tell the mysqld server to start
using the new grant tables. Note: reloading the grant tables overrides the --skipgrant-tables option. This allows you to tell the server to begin using the grant tables
again without bringing it down and restarting it.
• If everything else fails, start the mysqld daemon with a debugging option (for example, --debug=d,general,query). This will print host and user information about
attempted connections, as well as information about each command issued. See Section E.1.2 [Making trace files], page 1021.
• If you have any other problems with the MySQL grant tables and feel you must post
the problem to the mailing list, always provide a dump of the MySQL grant tables.
You can dump the tables with the mysqldump mysql command. As always, post your
problem using the mysqlbug script. See Section 1.7.1.3 [Bug reports], page 34. In some
cases you may need to restart mysqld with --skip-grant-tables to run mysqldump.
4.4 MySQL User Account Management
4.4.1 GRANT and REVOKE Syntax
GRANT priv_type [(column_list)] [, priv_type [(column_list)] ...]
ON {tbl_name | * | *.* | db_name.*}
TO user_name [IDENTIFIED BY [PASSWORD] ’password’]
[, user_name [IDENTIFIED BY [PASSWORD] ’password’] ...]
[REQUIRE
NONE |
[{SSL| X509}]
[CIPHER cipher [AND]]
[ISSUER issuer [AND]]
[SUBJECT subject]]
Chapter 4: Database Administration
243
[WITH [GRANT OPTION | MAX_QUERIES_PER_HOUR # |
MAX_UPDATES_PER_HOUR # |
MAX_CONNECTIONS_PER_HOUR #]]
REVOKE priv_type [(column_list)] [, priv_type [(column_list)] ...]
ON {tbl_name | * | *.* | db_name.*}
FROM user_name [, user_name ...]
GRANT is implemented in MySQL Version 3.22.11 or later. For earlier MySQL versions, the
GRANT statement does nothing.
The GRANT and REVOKE commands allow system administrators to create users and grant
and revoke rights to MySQL users at four privilege levels:
Global level
Global privileges apply to all databases on a given server. These privileges are
stored in the mysql.user table. GRANT ALL ON *.* and REVOKE ALL ON *.* will
grant and revoke only global privileges.
Database level
Database privileges apply to all tables in a given database. These privileges
are stored in the mysql.db and mysql.host tables. GRANT ALL ON db.* and
REVOKE ALL ON db.* will grant and revoke only database privileges.
Table level
Table privileges apply to all columns in a given table. These privileges are
stored in the mysql.tables_priv table. GRANT ALL ON db.table and REVOKE
ALL ON db.table will grant and revoke only table privileges.
Column level
Column privileges apply to single columns in a given table. These privileges
are stored in the mysql.columns_priv table. When using REVOKE you must
specify the same columns that were granted.
For the GRANT and REVOKE statements, priv_type may be specified as any of the following:
ALL [PRIVILEGES]
ALTER
CREATE
CREATE TEMPORARY TABLES
DELETE
DROP
EXECUTE
FILE
INDEX
INSERT
LOCK TABLES
PROCESS
REFERENCES
RELOAD
Sets all simple privileges except WITH GRANT OPTION
Allows usage of ALTER TABLE
Allows usage of CREATE TABLE
Allows usage of CREATE TEMPORARY TABLE
Allows usage of DELETE
Allows usage of DROP TABLE.
Allows the user to run stored procedures (MySQL 5.0)
Allows usage of SELECT ... INTO OUTFILE and LOAD DATA
INFILE.
Allows usage of CREATE INDEX and DROP INDEX
Allows usage of INSERT
Allows usage of LOCK TABLES on tables for which one has the
SELECT privilege.
Allows usage of SHOW FULL PROCESSLIST
For the future
Allows usage of FLUSH
244
MySQL Technical Reference for Version 4.1.1-alpha
REPLICATION CLIENT
REPLICATION SLAVE
SELECT
SHOW DATABASES
SHUTDOWN
SUPER
UPDATE
USAGE
GRANT OPTION
Gives the right to the user to ask where the slaves/masters
are.
Needed for the replication slaves (to read binlogs from
master).
Allows usage of SELECT
SHOW DATABASES shows all databases.
Allows usage of mysqladmin shutdown
Allows one connect (once) even if max connections is
reached and execute commands CHANGE MASTER, KILL
thread, mysqladmin debug, PURGE MASTER LOGS and SET
GLOBAL
Allows usage of UPDATE
Synonym for “no privileges.”
Synonym for WITH GRANT OPTION
USAGE can be used when you want to create a user that has no privileges.
The privileges CREATE TEMPORARY TABLES, EXECUTE, LOCK TABLES, REPLICATION ..., SHOW
DATABASES and SUPER are new for in version 4.0.2. To use these new privileges after upgrading to 4.0.2, you have to run the mysql_fix_privilege_tables script. See Section 2.5.6
[Upgrading-grant-tables], page 123.
In older MySQL versions, the PROCESS privilege gives the same rights as the new SUPER
privilege.
To revoke the GRANT privilege from a user, use a priv_type value of GRANT OPTION:
mysql> REVOKE GRANT OPTION ON ... FROM ...;
The only priv_type values you can specify for a table are SELECT, INSERT, UPDATE, DELETE,
CREATE, DROP, GRANT OPTION, INDEX, and ALTER.
The only priv_type values you can specify for a column (that is, when you use a column_
list clause) are SELECT, INSERT, and UPDATE.
MySQL allows you to create database level privileges even if the database doesn’t exist, to
make it easy to prepare for database usage. Currently MySQL does however not allow one
to create table level grants if the table doesn’t exist. MySQL will not automatically revoke
any privileges even if you drop a table or drop a database.
You can set global privileges by using ON *.* syntax. You can set database privileges by
using ON db_name.* syntax. If you specify ON * and you have a current database, you will
set the privileges for that database. (Warning: if you specify ON * and you don’t have a
current database, you will affect the global privileges!)
Please note: the ‘_’ and ‘%’ wildcards are allowed when specifying database names in GRANT
commands. This means that if you wish to use for instance a ‘_’ character as part of a
database name, you should specify it as ‘\_’ in the GRANT command, to prevent the user
from being able to access additional databases matching the wildcard pattern, for example,
GRANT ... ON ‘foo\_bar‘.* TO ....
In order to accommodate granting rights to users from arbitrary hosts, MySQL supports
specifying the user_name value in the form [email protected] If you want to specify a user string
containing special characters (such as ‘-’), or a host string containing special characters
or wildcard characters (such as ‘%’), you can quote the user or host name (for example,
’test-user’@’test-hostname’).
Chapter 4: Database Administration
245
You can specify wildcards in the hostname. For example, [email protected]’%.loc.gov’ applies to
user for any host in the loc.gov domain, and [email protected]’144.155.166.%’ applies to user for
any host in the 144.155.166 class C subnet.
The simple form user is a synonym for [email protected]"%".
MySQL doesn’t support wildcards in user names. Anonymous users are defined by inserting
entries with User=’’ into the mysql.user table or creating an user with an empty name
with the GRANT command.
Note: if you allow anonymous users to connect to the MySQL server, you should also grant
privileges to all local users as [email protected] because otherwise the anonymous user entry
for the local host in the mysql.user table will be used when the user tries to log into the
MySQL server from the local machine!
You can verify if this applies to you by executing this query:
mysql> SELECT Host,User FROM mysql.user WHERE User=’’;
For the moment, GRANT only supports host, table, database, and column names up to 60
characters long. A user name can be up to 16 characters.
The privileges for a table or column are formed from the logical OR of the privileges at
each of the four privilege levels. For example, if the mysql.user table specifies that a user
has a global SELECT privilege, this can’t be denied by an entry at the database, table, or
column level.
The privileges for a column can be calculated as follows:
global privileges
OR (database privileges AND host privileges)
OR table privileges
OR column privileges
In most cases, you grant rights to a user at only one of the privilege levels, so life isn’t
normally as complicated as above. The details of the privilege-checking procedure are
presented in Section 4.3 [Privilege system], page 216.
If you grant privileges for a user/hostname combination that does not exist in the
mysql.user table, an entry is added and remains there until deleted with a DELETE
command. In other words, GRANT may create user table entries, but REVOKE will not
remove them; you must do that explicitly using DELETE.
In MySQL Version 3.22.12 or later, if a new user is created or if you have global grant
privileges, the user’s password will be set to the password specified by the IDENTIFIED BY
clause, if one is given. If the user already had a password, it is replaced by the new one.
If you don’t want to send the password in clear text you can use the PASSWORD option
followed by a scrambled password from SQL function PASSWORD() or the C API function
make_scrambled_password(char *to, const char *password).
Warning: if you create a new user but do not specify an IDENTIFIED BY clause, the user
has no password. This is insecure.
Passwords can also be set with the SET PASSWORD command. See Section 5.5.6 [SET],
page 437.
If you grant privileges for a database, an entry in the mysql.db table is created if needed.
When all privileges for the database have been removed with REVOKE, this entry is deleted.
246
MySQL Technical Reference for Version 4.1.1-alpha
If a user doesn’t have any privileges on a table, the table is not displayed when the user
requests a list of tables (for example, with a SHOW TABLES statement). The same is true for
SHOW DATABASES.
The WITH GRANT OPTION clause gives the user the ability to give to other users any privileges
the user has at the specified privilege level. You should be careful to whom you give the
GRANT privilege, as two users with different privileges may be able to join privileges!
MAX_QUERIES_PER_HOUR #, MAX_UPDATES_PER_HOUR # and MAX_CONNECTIONS_PER_HOUR #
are new in MySQL version 4.0.2. These options limit the number of queries/updates and
logins the user can do during one hour. If # is 0 (default), then this means that there are no
limitations for that user. See Section 4.4.7 [User resources], page 253. Note: to specify any
of these options for an existing user without adding other additional privileges, use GRANT
USAGE ON *.* ... WITH MAX_....
You cannot grant another user a privilege you don’t have yourself; the GRANT privilege allows
you to give away only those privileges you possess.
Be aware that when you grant a user the GRANT privilege at a particular privilege level,
any privileges the user already possesses (or is given in the future!) at that level are also
grantable by that user. Suppose you grant a user the INSERT privilege on a database. If
you then grant the SELECT privilege on the database and specify WITH GRANT OPTION, the
user can give away not only the SELECT privilege, but also INSERT. If you then grant the
UPDATE privilege to the user on the database, the user can give away the INSERT, SELECT
and UPDATE.
You should not grant ALTER privileges to a normal user. If you do that, the user can try to
subvert the privilege system by renaming tables!
Note that if you are using table or column privileges for even one user, the server examines
table and column privileges for all users and this will slow down MySQL a bit.
When mysqld starts, all privileges are read into memory. Database, table, and column privileges take effect at once, and user-level privileges take effect the next time the user connects.
Modifications to the grant tables that you perform using GRANT or REVOKE are noticed by the
server immediately. If you modify the grant tables manually (using INSERT, UPDATE, etc.),
you should execute a FLUSH PRIVILEGES statement or run mysqladmin flush-privileges
to tell the server to reload the grant tables. See Section 4.4.3 [Privilege changes], page 248.
The biggest differences between the SQL standard and MySQL versions of GRANT are:
• In MySQL privileges are given for an username + hostname combination and not only
for an username.
• SQL-99 doesn’t have global or database-level privileges, nor does it support all the
privilege types that MySQL supports. MySQL doesn’t support the SQL-99 TRIGGER
or UNDER privileges.
• SQL-99 privileges are structured in a hierarchal manner. If you remove an user, all
privileges the user has granted are revoked. In MySQL the granted privileges are not
automatically revoked, but you have to revoke these yourself if needed.
• In MySQL, if you have the INSERT privilege on only some of the columns in a table,
you can execute INSERT statements on the table; the columns for which you don’t have
the INSERT privilege will be set to their default values. SQL-99 requires you to have
the INSERT privilege on all columns.
Chapter 4: Database Administration
247
• With SQL99, when you drop a table, all privileges for the table are revoked. With
SQL-99, when you revoke a privilege, all privileges that were granted based on the
privilege are also revoked. In MySQL, privileges can be dropped only with explicit
REVOKE commands or by manipulating the MySQL grant tables.
For a description of using REQUIRE, see Section 4.4.10 [Secure connections], page 255.
4.4.2 MySQL User Names and Passwords
There are several distinctions between the way user names and passwords are used by
MySQL and the way they are used by Unix or Windows:
• User names, as used by MySQL for authentication purposes, have nothing to do with
Unix user names (login names) or Windows user names. Most MySQL clients by default
try to log in using the current Unix user name as the MySQL user name, but that is
for convenience only. Client programs allow a different name to be specified with the
-u or --user options. This means that you can’t make a database secure in any way
unless all MySQL user names have passwords. Anyone may attempt to connect to the
server using any name, and they will succeed if they specify any name that doesn’t
have a password.
• MySQL user names can be up to 16 characters long; Unix user names typically are
limited to 8 characters.
• MySQL passwords have nothing to do with Unix passwords. There is no necessary
connection between the password you use to log in to a Unix machine and the password
you use to access a database on that machine.
• MySQL encrypts passwords using a different algorithm than the one used during the
Unix login process. See the descriptions of the PASSWORD() and ENCRYPT() functions
in Section 6.3.6.2 [Miscellaneous functions], page 521. Note that even if the password
is stored ’scrambled’, and knowing your ’scrambled’ password is enough to be able to
connect to the MySQL server! From version 4.1, MySQL employs a different password
and login mechanism that is secure even if TCP/IP packets are sniffed and/or the
mysql database is captured.
MySQL users and their privileges are normally created with the GRANT command. See
Section 4.4.1 [GRANT], page 242.
When you login to a MySQL server with a command-line client you should specify the
password with --password=your-password. See Section 4.3.8 [Connecting], page 227.
mysql --user=monty --password=guess database_name
If you want the client to prompt for a password, you should use --password without any
argument
mysql --user=monty --password database_name
or the short form:
mysql -u monty -p database_name
Note that in the last example the password is not ’database name’.
If you want to use the -p option to supply a password you should do so like this:
248
MySQL Technical Reference for Version 4.1.1-alpha
mysql -u monty -pguess database_name
On some systems, the library call that MySQL uses to prompt for a password will automatically cut the password to 8 characters. Internally MySQL doesn’t have any limit for
the length of the password.
4.4.3 When Privilege Changes Take Effect
When mysqld starts, all grant table contents are read into memory and become effective at
that point.
Modifications to the grant tables that you perform using GRANT, REVOKE, or SET PASSWORD
are noticed by the server immediately.
If you modify the grant tables manually (using INSERT, UPDATE, etc.), you should execute a FLUSH PRIVILEGES statement or run mysqladmin flush-privileges or mysqladmin
reload to tell the server to reload the grant tables. Otherwise, your changes will have
no effect until you restart the server. If you change the grant tables manually but forget
to reload the privileges, you will be wondering why your changes don’t seem to make any
difference!
When the server notices that the grant tables have been changed, existing client connections
are affected as follows:
• Table and column privilege changes take effect with the client’s next request.
• Database privilege changes take effect at the next USE db_name command.
• Global privilege changes and password changes take effect the next time the client
connects.
4.4.4 Setting Up the Initial MySQL Privileges
After installing MySQL, you set up the initial access privileges by running scripts/mysql_
install_db. See Section 2.3.1 [Quick install], page 90. The mysql_install_db script
starts up the mysqld server, then initialises the grant tables to contain the following set of
privileges:
• The MySQL root user is created as a superuser who can do anything. Connections
must be made from the local host.
Note: The initial root password is empty, so anyone can connect as root without a
password and be granted all privileges.
• An anonymous user is created that can do anything with databases that have a name of
’test’ or starting with ’test_’. Connections must be made from the local host. This
means any local user can connect without a password and be treated as the anonymous
user.
• Other privileges are denied. For example, normal users can’t use mysqladmin shutdown
or mysqladmin processlist.
Note: the default privileges are different for Windows. See Section 2.1.1.8 [Windows running], page 64.
Chapter 4: Database Administration
249
Because your installation is initially wide open, one of the first things you should do is
specify a password for the MySQL root user. You can do this as follows (note that you
specify the password using the PASSWORD() function):
shell> mysql -u root mysql
mysql> SET PASSWORD FOR [email protected]=PASSWORD(’new_password’);
Replace ’new_password’ with the password that you want to use.
If you know what you are doing, you can also directly manipulate the privilege tables:
shell> mysql -u root mysql
mysql> UPDATE user SET Password=PASSWORD(’new_password’)
->
WHERE user=’root’;
mysql> FLUSH PRIVILEGES;
Another way to set the password is by using the mysqladmin command:
shell> mysqladmin -u root password new_password
Only users with write/update access to the mysql database can change the password for
other users. All normal users (not anonymous ones) can only change their own password
with either of the above commands or with SET PASSWORD=PASSWORD(’new_password’).
Note that if you update the password in the user table directly using UPDATE, you must tell
the server to re-read the grant tables (with FLUSH PRIVILEGES), because the change will go
unnoticed otherwise.
Once the root password has been set, thereafter you must supply that password when you
connect to the server as root.
You may wish to leave the root password blank so that you don’t need to specify it while you
perform additional setup or testing. However, be sure to set it before using your installation
for any real production work.
See the scripts/mysql_install_db script to see how it sets up the default privileges. You
can use this as a basis to see how to add other users.
If you want the initial privileges to be different from those just described above, you can
modify mysql_install_db before you run it.
To re-create the grant tables completely, remove all the ‘.frm’, ‘.MYI’, and ‘.MYD’ files in
the directory containing the mysql database. (This is the directory named ‘mysql’ under
the database directory, which is listed when you run mysqld --help.) Then run the mysql_
install_db script, possibly after editing it first to have the privileges you want.
Note: for MySQL versions older than Version 3.22.10, you should not delete the ‘.frm’
files. If you accidentally do this, you should copy them back from your MySQL distribution
before running mysql_install_db.
4.4.5 Adding New Users to MySQL
You can add users two different ways: by using GRANT statements or by manipulating the
MySQL grant tables directly. The preferred method is to use GRANT statements, because
they are more concise and less error-prone. See Section 4.4.1 [GRANT], page 242.
There are also several contributed programs (such as phpMyAdmin) that can be used to
create and administer users.
250
MySQL Technical Reference for Version 4.1.1-alpha
The following examples show how to use the mysql client to set up new users. These examples assume that privileges are set up according to the defaults described in the previous
section. This means that to make changes, you must be on the same machine where mysqld
is running, you must connect as the MySQL root user, and the root user must have the
INSERT privilege for the mysql database and the RELOAD administrative privilege. Also, if
you have changed the root user password, you must specify it for the mysql commands
here.
First, use the mysql program to connect to the server as the MySQL root user:
shell> mysql --user=root mysql
Then you can add new users by issuing GRANT statements:
mysql> GRANT ALL PRIVILEGES ON *.* TO [email protected]
->
IDENTIFIED BY ’some_pass’ WITH GRANT OPTION;
mysql> GRANT ALL PRIVILEGES ON *.* TO [email protected]’%’
->
IDENTIFIED BY ’some_pass’ WITH GRANT OPTION;
mysql> GRANT RELOAD,PROCESS ON *.* TO [email protected];
mysql> GRANT USAGE ON *.* TO [email protected];
These GRANT statements set up three new users:
monty
A full superuser who can connect to the server from anywhere, but who must use
a password ’some_pass’ to do so. Note that we must issue GRANT statements
for both [email protected] and [email protected]"%". If we don’t add the entry with
localhost, the anonymous user entry for localhost that is created by mysql_
install_db takes precedence when we connect from the local host, because it
has a more specific Host field value and thus comes earlier in the user table
sort order.
admin
A user who can connect from localhost without a password and who is granted
the RELOAD and PROCESS administrative privileges. This allows the user to execute the mysqladmin reload, mysqladmin refresh, and mysqladmin flush-*
commands, as well as mysqladmin processlist . No database-level privileges
are granted. (They can be granted later by issuing additional GRANT statements.)
dummy
A user who can connect without a password, but only from the local host. No
privileges are granted—the USAGE privilege type allows you to create a user
with no privileges. It has the effect of setting all the global privileges to ’N’.
It is assumed that you will grant specific privileges to the account later.
You can also add the same user access information directly by issuing INSERT statements
and then telling the server to reload the grant tables:
shell> mysql --user=root mysql
mysql> INSERT INTO user VALUES(’localhost’,’monty’,PASSWORD(’some_pass’),
->
’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’);
mysql> INSERT INTO user VALUES(’%’,’monty’,PASSWORD(’some_pass’),
->
’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’);
mysql> INSERT INTO user SET Host=’localhost’,User=’admin’,
->
Reload_priv=’Y’, Process_priv=’Y’;
mysql> INSERT INTO user (Host,User,Password)
Chapter 4: Database Administration
251
->
VALUES(’localhost’,’dummy’,’’);
mysql> FLUSH PRIVILEGES;
Depending on your MySQL version, you may have to use a different number of ’Y’ values
above. (Versions prior to Version 3.22.11 have fewer privilege columns, and versions from
4.0.2 on have more.) For the admin user, the more readable extended INSERT syntax using
SET that is available starting with Version 3.22.11 is used.
Note that to set up a superuser, you need only create a user table entry with the privilege
fields set to ’Y’. No db or host table entries are necessary.
In the last INSERT statement (for the dummy user), only the Host, User, and Password
columns in the user table record are assigned values. None of the privilege columns are set
explicitly, so MySQL assigns them all the default value of ’N’. This is the same thing that
GRANT USAGE does.
The following example adds a user custom who can access the bankaccount database only
from the local host, the expenses database only from the host whitehouse.gov, and the
customer database only from the host server.domain. He wants to use the password
obscure from all three hosts.
To set up this user’s privileges using GRANT statements, run these commands:
shell>
mysql>
->
->
->
mysql>
->
->
->
mysql>
->
->
->
mysql --user=root mysql
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
ON bankaccount.*
TO [email protected]
IDENTIFIED BY ’obscure’;
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
ON expenses.*
TO [email protected]’whitehouse.gov’
IDENTIFIED BY ’obscure’;
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
ON customer.*
TO [email protected]’server.domain’
IDENTIFIED BY ’obscure’;
To set up the user’s privileges by modifying the grant tables directly, run these commands
(note the FLUSH PRIVILEGES at the end):
shell>
mysql>
->
mysql>
->
mysql>
->
mysql>
->
->
->
->
mysql>
mysql --user=root mysql
INSERT INTO user (Host,User,Password)
VALUES(’localhost’,’custom’,PASSWORD(’obscure’));
INSERT INTO user (Host,User,Password)
VALUES(’whitehouse.gov’,’custom’,PASSWORD(’obscure’));
INSERT INTO user (Host,User,Password)
VALUES(’server.domain’,’custom’,PASSWORD(’obscure’));
INSERT INTO db
(Host,Db,User,Select_priv,Insert_priv,Update_priv,Delete_priv,
Create_priv,Drop_priv)
VALUES
(’localhost’,’bankaccount’,’custom’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’);
INSERT INTO db
252
MySQL Technical Reference for Version 4.1.1-alpha
-> (Host,Db,User,Select_priv,Insert_priv,Update_priv,Delete_priv,
-> Create_priv,Drop_priv)
-> VALUES
-> (’whitehouse.gov’,’expenses’,’custom’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’);
mysql> INSERT INTO db
-> (Host,Db,User,Select_priv,Insert_priv,Update_priv,Delete_priv,
-> Create_priv,Drop_priv)
-> VALUES(’server.domain’,’customer’,’custom’,’Y’,’Y’,’Y’,’Y’,’Y’,’Y’);
mysql> FLUSH PRIVILEGES;
As in the preceding example that used INSERT statements, you may need to use a different
number of ’Y’ values, depending on your version of MySQL.
The first three INSERT statements add user table entries that allow user custom to connect from the various hosts with the given password, but grant no permissions to him (all
privileges are set to the default value of ’N’). The next three INSERT statements add db
table entries that grant privileges to custom for the bankaccount, expenses, and customer
databases, but only when accessed from the proper hosts. As usual, after you modify the
grant tables directly , you must tell the server to reload them (with FLUSH PRIVILEGES) so
that the privilege changes take effect.
If you want to give a specific user access from any machine in a given domain (for example,
mydomain.com), you can issue a GRANT statement like the following:
mysql> GRANT ...
->
ON *.*
->
TO [email protected]’%.mydomain.com’
->
IDENTIFIED BY ’mypassword’;
To do the same thing by modifying the grant tables directly, do this:
mysql> INSERT INTO user VALUES (’%.mydomain.com’, ’myusername’,
->
PASSWORD(’mypassword’),...);
mysql> FLUSH PRIVILEGES;
4.4.6 Deleting Users from MySQL
DROP USER user_name
This command was added to MySQL 4.1.1.
It deletes a user that doesn’t have any privileges.
To delete a user from MySQL, you should use the following procedure, performing the steps
in the order shown:
1. Check which privileges the user has with SHOW PRIVILEGES. See Section 4.6.8.11
[SHOW PRIVILEGES], page 309.
2. Delete all privileges from the user with REVOKE. See Section 4.4.1 [GRANT], page 242.
3. Delete the user with DROP USER.
If you are using and older MySQL version you should first revoke the privileges and then
delete the user with:
DELETE FROM mysql.user WHERE user=’username’ and host=’hostname’;
FLUSH PRIVILEGES;
Chapter 4: Database Administration
253
4.4.7 Limiting user resources
Starting from MySQL 4.0.2 one can limit certain resources per user.
So far, the only available method of limiting usage of MySQL server resources has been
setting the max_user_connections startup variable to a non-zero value. But this method
is strictly global and does not allow for management of individual users, which could be of
particular interest to Internet Service Providers.
Therefore, management of three resources is introduced on the individual user level:
• Number of all queries per hour: All commands that could be run by a user.
• Number of all updates per hour: Any command that changes any table or database.
• Number of connections made per hour: New connections opened per hour.
A user in the aforementioned context is a single entry in the user table, which is uniquely
identified by its user and host columns.
All users are by default not limited in using the above resources, unless the limits are granted
to them. These limits can be granted only via global GRANT (*.*), using this syntax:
GRANT ... WITH MAX_QUERIES_PER_HOUR N1
MAX_UPDATES_PER_HOUR N2
MAX_CONNECTIONS_PER_HOUR N3;
One can specify any combination of the above resources. N1, N2, and N3 are integers and
represent counts per hour.
If a user reaches the limit on number of connections within one hour, no further connections
will be accepted until that hour is up. Similarly, if the user reaches the limit on number of
queries or updates, further queries or updates will be rejected until the hour is up. In all
cases, an appropriate error message shall be issued.
Current usage values for a particular user can be flushed (set to zero) by issuing a GRANT
statement with any of the above clauses, including a GRANT statement with the current
values.
Also, current values for all users will be flushed if privileges are reloaded (in the server or
using mysqladmin reload) or if the FLUSH USER_RESOURCES command is issued.
The feature is enabled as soon as a single user is granted with any of the limiting GRANT
clauses.
As a prerequisite for enabling this feature, the user table in the mysql database must
contain the additional columns, as defined in the table creation scripts mysql_install_db
and mysql_install_db.sh in ‘scripts’ subdirectory.
4.4.8 Setting Up Passwords
In most cases you should use GRANT to set up your users/passwords, so the following only
applies for advanced users. See Section 4.4.1 [GRANT], page 242.
The examples in the preceding sections illustrate an important principle: when you store
a non-empty password using INSERT or UPDATE statements, you must use the PASSWORD()
function to encrypt it. This is because the user table stores passwords in encrypted form,
not as plaintext. If you forget that fact, you are likely to attempt to set passwords like this:
254
MySQL Technical Reference for Version 4.1.1-alpha
shell>
mysql>
->
mysql>
mysql -u root mysql
INSERT INTO user (Host,User,Password)
VALUES(’%’,’jeffrey’,’biscuit’);
FLUSH PRIVILEGES;
The result is that the plaintext value ’biscuit’ is stored as the password in the user
table. When the user jeffrey attempts to connect to the server using this password, the
mysql client encrypts it with PASSWORD(), generates an authentication vector based on
encrypted password and a random number, obtained from server, and sends the result to
the server. The server uses the password value in the user table (that is not encrypted
value ’biscuit’) to perform the same calculations, and compares results. The comparison
fails and the server rejects the connection:
shell> mysql -u jeffrey -pbiscuit test
Access denied
Passwords must be encrypted when they are inserted in the user table, so the INSERT
statement should have been specified like this instead:
mysql> INSERT INTO user (Host,User,Password)
-> VALUES(’%’,’jeffrey’,PASSWORD(’biscuit’));
You must also use the PASSWORD() function when you use SET PASSWORD statements:
mysql> SET PASSWORD FOR [email protected]"%" = PASSWORD(’biscuit’);
If you set passwords using the GRANT ... IDENTIFIED BY statement or the mysqladmin
password command, the PASSWORD() function is unnecessary. They both take care of
encrypting the password for you, so you would specify a password of ’biscuit’ like this:
mysql> GRANT USAGE ON *.* TO [email protected]"%" IDENTIFIED BY ’biscuit’;
or
shell> mysqladmin -u jeffrey password biscuit
Note: PASSWORD() is different from Unix password encryption. See Section 4.4.2 [User
names], page 247.
4.4.9 Keeping Your Password Secure
It is inadvisable to specify your password in a way that exposes it to discovery by other
users. The methods you can use to specify your password when you run client programs
are listed here, along with an assessment of the risks of each method:
• Never give a normal user access to the mysql.user table. Knowing the encrypted
password for a user makes it possible to login as this user. The passwords are only
scrambled so that one shouldn’t be able to see the real password you used (if you
happen to use a similar password with your other applications).
• Use a -pyour_pass or --password=your_pass option on the command line. This
is convenient but insecure, because your password becomes visible to system status
programs (such as ps) that may be invoked by other users to display command-lines.
(MySQL clients typically overwrite the command-line argument with zeroes during
their initialisation sequence, but there is still a brief interval during which the value is
visible.)
Chapter 4: Database Administration
255
• Use a -p or --password option (with no your_pass value specified). In this case, the
client program solicits the password from the terminal:
shell> mysql -u user_name -p
Enter password: ********
The ‘*’ characters represent your password.
It is more secure to enter your password this way than to specify it on the command-line
because it is not visible to other users. However, this method of entering a password
is suitable only for programs that you run interactively. If you want to invoke a client
from a script that runs non-interactively, there is no opportunity to enter the password
from the terminal. On some systems, you may even find that the first line of your
script is read and interpreted (incorrectly) as your password!
• Store your password in a configuration file. For example, you can list your password
in the [client] section of the ‘.my.cnf’ file in your home directory:
[client]
password=your_pass
If you store your password in ‘.my.cnf’, the file should not be group or world readable
or writable. Make sure the file’s access mode is 400 or 600.
See Section 4.1.2 [Option files], page 206.
• You can store your password in the MYSQL_PWD environment variable, but this method
must be considered extremely insecure and should not be used. Some versions of ps
include an option to display the environment of running processes; your password will
be in plain sight for all to see if you set MYSQL_PWD. Even on systems without such
a version of ps, it is unwise to assume there is no other method to observe process
environments. See Appendix F [Environment variables], page 1032.
All in all, the safest methods are to have the client program prompt for the password or to
specify the password in a properly protected ‘.my.cnf’ file.
4.4.10 Using Secure Connections
4.4.10.1 Basics
Beginning with version 4.0.0, MySQL has support for SSL encrypted connections. To
understand how MySQL uses SSL, it’s necessary to explain some basic SSL and X509
concepts. People who are already familiar with them can skip this part.
By default, MySQL uses unencrypted connections between the client and the server. This
means that someone could watch all your traffic and look at the data being sent or received.
They could even change the data while it is in transit between client and server. Sometimes
you need to move information over public networks in a secure fashion; in such cases, using
an unencrypted connection is unacceptable.
SSL is a protocol that uses different encryption algorithms to ensure that data received over
a public network can be trusted. It has mechanisms to detect any change, loss or replay of
data. SSL also incorporates algorithms to recognise and provide identity verification using
the X509 standard.
256
MySQL Technical Reference for Version 4.1.1-alpha
Encryption is the way to make any kind of data unreadable. In fact, today’s practice requires
many additional security elements from encryption algorithms. They should resist many
kind of known attacks like just messing with the order of encrypted messages or replaying
data twice.
X509 is a standard that makes it possible to identify someone on the Internet. It is most
commonly used in e-commerce applications. In basic terms, there should be some company
(called a “Certificate Authority”) that assigns electronic certificates to anyone who needs
them. Certificates rely on asymmetric encryption algorithms that have two encryption keys
(a public key and a secret key). A certificate owner can prove his identity by showing
his certificate to other party. A certificate consists of its owner’s public key. Any data
encrypted with this public key can be decrypted only using the corresponding secret key,
which is held by the owner of the certificate.
MySQL doesn’t use encrypted connections by default, because doing so would make the
client/server protocol much slower. Any kind of additional functionality requires the computer to do additional work and encrypting data is a CPU-intensive operation that requires
time and can delay MySQL main tasks. By default MySQL is tuned to be fast as possible.
If you need more information about SSL, X509, or encryption, you should use your favourite
Internet search engine and search for keywords in which you are interested.
4.4.10.2 Requirements
To get secure connections to work with MySQL you must do the following:
1. Install the OpenSSL library.
We have tested MySQL with OpenSSL 0.9.6.
http://www.openssl.org/.
2. Configure MySQL with --with-vio --with-openssl.
3. If you are using an old MySQL installation, you have to update your mysql.user table
with some new SSL-related columns. This is necessary if your grant tables date from a
version prior to MySQL 4.0.0. The procedure is described in Section 2.5.6 [Upgradinggrant-tables], page 123.
4. You can check if a running mysqld server supports OpenSSL by examining if SHOW
VARIABLES LIKE ’have_openssl’ returns YES.
4.4.10.3 Setting Up SSL Certificates for MySQL
Here is an example for setting up SSL certificates for MySQL:
DIR=‘pwd‘/openssl
PRIV=$DIR/private
mkdir $DIR $PRIV $DIR/newcerts
cp /usr/share/ssl/openssl.cnf $DIR
replace ./demoCA $DIR -- $DIR/openssl.cnf
# Create necessary files: $database, $serial and $new_certs_dir
# directory (optional)
Chapter 4: Database Administration
257
touch $DIR/index.txt
echo "01" > $DIR/serial
#
# Generation of Certificate Authority(CA)
#
openssl req -new -x509 -keyout $PRIV/cakey.pem -out $DIR/cacert.pem \
-config $DIR/openssl.cnf
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
Sample output:
Using configuration from /home/monty/openssl/openssl.cnf
Generating a 1024 bit RSA private key
................++++++
.........++++++
writing new private key to ’/home/monty/openssl/private/cakey.pem’
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
----You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ’.’, the field will be left blank.
----Country Name (2 letter code) [AU]:FI
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:MySQL admin
Email Address []:
#
# Create server request and key
#
openssl req -new -keyout $DIR/server-key.pem -out \
$DIR/server-req.pem -days 3600 -config $DIR/openssl.cnf
#
#
#
#
#
#
#
Sample output:
Using configuration from /home/monty/openssl/openssl.cnf
Generating a 1024 bit RSA private key
..++++++
..........++++++
writing new private key to ’/home/monty/openssl/server-key.pem’
Enter PEM pass phrase:
258
MySQL Technical Reference for Version 4.1.1-alpha
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
Verifying password - Enter PEM pass phrase:
----You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ’.’, the field will be left blank.
----Country Name (2 letter code) [AU]:FI
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:MySQL server
Email Address []:
Please enter the following ’extra’ attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
#
# Remove the passphrase from the key (optional)
#
openssl rsa -in $DIR/server-key.pem -out $DIR/server-key.pem
#
# Sign server cert
#
openssl ca -policy policy_anything -out $DIR/server-cert.pem \
-config $DIR/openssl.cnf -infiles $DIR/server-req.pem
#
#
#
#
#
#
#
#
#
#
#
#
#
Sample output:
Using configuration from /home/monty/openssl/openssl.cnf
Enter PEM pass phrase:
Check that the request matches the signature
Signature ok
The Subjects Distinguished Name is as follows
countryName
:PRINTABLE:’FI’
organizationName
:PRINTABLE:’MySQL AB’
commonName
:PRINTABLE:’MySQL admin’
Certificate is to be certified until Sep 13 14:22:46 2003 GMT (365 days)
Sign the certificate? [y/n]:y
Chapter 4: Database Administration
259
# 1 out of 1 certificate requests certified, commit? [y/n]y
# Write out database with 1 new entries
# Data Base Updated
#
# Create client request and key
#
openssl req -new -keyout $DIR/client-key.pem -out \
$DIR/client-req.pem -days 3600 -config $DIR/openssl.cnf
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
Sample output:
Using configuration from /home/monty/openssl/openssl.cnf
Generating a 1024 bit RSA private key
.....................................++++++
.............................................++++++
writing new private key to ’/home/monty/openssl/client-key.pem’
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
----You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ’.’, the field will be left blank.
----Country Name (2 letter code) [AU]:FI
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:MySQL user
Email Address []:
Please enter the following ’extra’ attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
#
# Remove a passphrase from the key (optional)
#
openssl rsa -in $DIR/client-key.pem -out $DIR/client-key.pem
#
# Sign client cert
#
260
MySQL Technical Reference for Version 4.1.1-alpha
openssl ca -policy policy_anything -out $DIR/client-cert.pem \
-config $DIR/openssl.cnf -infiles $DIR/client-req.pem
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
Sample output:
Using configuration from /home/monty/openssl/openssl.cnf
Enter PEM pass phrase:
Check that the request matches the signature
Signature ok
The Subjects Distinguished Name is as follows
countryName
:PRINTABLE:’FI’
organizationName
:PRINTABLE:’MySQL AB’
commonName
:PRINTABLE:’MySQL user’
Certificate is to be certified until Sep 13 16:45:17 2003 GMT (365 days)
Sign the certificate? [y/n]:y
1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated
#
# Create a my.cnf file that you can use to test the certificates
#
cnf=""
cnf="$cnf [client]"
cnf="$cnf ssl-ca=$DIR/cacert.pem"
cnf="$cnf ssl-cert=$DIR/client-cert.pem"
cnf="$cnf ssl-key=$DIR/client-key.pem"
cnf="$cnf [mysqld]"
cnf="$cnf ssl-ca=$DIR/cacert.pem"
cnf="$cnf ssl-cert=$DIR/server-cert.pem"
cnf="$cnf ssl-key=$DIR/server-key.pem"
echo $cnf | replace " " ’
’ > $DIR/my.cnf
#
# To test MySQL
mysqld --defaults-file=$DIR/my.cnf &
mysql --defaults-file=$DIR/my.cnf
You can also test your setup by modifying the above ‘my.cnf’ file to refer to the demo
certificates in the mysql-source-dist/SSL direcory.
Chapter 4: Database Administration
261
4.4.10.4 SSL GRANT Options
MySQL can check X509 certificate attributes in addition to the normal username/password
scheme. All the usual options are still required (username, password, IP address mask,
database/table name).
There are different possibilities to limit connections:
• Without any SSL or X509 options, all kind of encrypted/unencrypted connections are
allowed if the username and password are valid.
• REQUIRE SSL option limits the server to allow only SSL encrypted connections. Note
that this option can be omitted if there are any ACL records which allow non-SSL
connections.
mysql> GRANT ALL PRIVILEGES ON test.* TO [email protected]
-> IDENTIFIED BY ’goodsecret’ REQUIRE SSL;
• REQUIRE X509 means that the client should have a valid certificate but we do not care
about the exact certificate, issuer or subject. The only restriction is that it should be
possible to verify its signature with one of the CA certificates.
mysql> GRANT ALL PRIVILEGES ON test.* TO [email protected]
-> IDENTIFIED BY ’goodsecret’ REQUIRE X509;
• REQUIRE ISSUER ’issuer’ places a restriction on connection attempts: The client must
present a valid X509 certificate issued by CA ’issuer’. Using X509 certificates always
implies encryption, so the SSL option is unneccessary.
mysql> GRANT ALL PRIVILEGES ON test.* TO [email protected]
-> IDENTIFIED BY ’goodsecret’
-> REQUIRE ISSUER ’C=FI, ST=Some-State, L=Helsinki,
’> O=MySQL Finland AB, CN=Tonu Samuel/[email protected]’;
• REQUIRE SUBJECT ’subject’ requires clients to have valid X509 certificate with subject
’subject’ on it. If the client presents a certificate that is valid but has a different
’subject’, the connection is disallowed.
mysql> GRANT ALL PRIVILEGES ON test.* TO [email protected]
-> IDENTIFIED BY ’goodsecret’
-> REQUIRE SUBJECT ’C=EE, ST=Some-State, L=Tallinn,
’> O=MySQL demo client certificate,
’> CN=Tonu Samuel/[email protected]’;
• REQUIRE CIPHER ’cipher’ is needed to assure enough strong ciphers and keylengths
will be used. SSL itself can be weak if old algorithms with short encryption keys are
used. Using this option, we can ask for some exact cipher method to allow a connection.
mysql> GRANT ALL PRIVILEGES ON test.* TO [email protected]
-> IDENTIFIED BY ’goodsecret’
-> REQUIRE CIPHER ’EDH-RSA-DES-CBC3-SHA’;
The SUBJECT, ISSUER, and CIPHER options can be combined in the REQUIRE clause like
this:
mysql> GRANT ALL PRIVILEGES ON test.* TO [email protected]ocalhost
-> IDENTIFIED BY ’goodsecret’
-> REQUIRE SUBJECT ’C=EE, ST=Some-State, L=Tallinn,
262
MySQL Technical Reference for Version 4.1.1-alpha
’> O=MySQL demo client certificate,
’> CN=Tonu Samuel/[email protected]’
-> AND ISSUER ’C=FI, ST=Some-State, L=Helsinki,
’> O=MySQL Finland AB, CN=Tonu Samuel/[email protected]’
-> AND CIPHER ’EDH-RSA-DES-CBC3-SHA’;
Starting from MySQL 4.0.4 the AND keyword is optional between REQUIRE options.
The order of the options does not matter, but no option can be specified twice.
4.4.10.5 SSL Command-line Options
The following table lists options that are used for specifying the use of SSL, certificate files,
and key files. These options are available beginning with MySQL 4.0. They may be given
on the command line or in option files.
--ssl
For the server, specifies that the server allows SSL connections. For a client
program, allows the client to connect to the server using SSL. This option itself
is not sufficient to cause an SSL connection to be used. You must also specify
the --ssl-ca, --ssl-cert, and --ssl-key options.
Note that this option doesn’t require an SSL connection. For example, if the
server or client are compiled without SSL support, a normal unencrypted connection will be used.
The secure way to ensure that a SSL connection will be used is to create an
account on the server that includes a REQUIRE SSL clause in the GRANT statement. Then use this account to connect to the server, with both a server and
client that have SSL support enabled.
You can use this option to indicate that the connection should not use SSL. Do
this by specifying the option as --skip-ssl or --ssl=0.
--ssl-ca=file_name
The path to a file with a list of trusted SSL CAs.
--ssl-capath=directory_name
The path to a directory that contains trusted SSL CA certificates in pem format.
--ssl-cert=file_name
The name of the SSL certificate file to use used for establishing a secure connection.
--ssl-cipher=cipher_list
A list of allowable ciphers to use for SSL encryption. cipher_list has the
same format as the openssl ciphers command.
Example: --ssl-cipher=ALL:-AES:-EXP
--ssl-key=file_name
The name of the SSL key file to use used for establishing a secure connection.
4.5 Disaster Prevention and Recovery
Chapter 4: Database Administration
263
4.5.1 Database Backups
Because MySQL tables are stored as files, it is easy to do a backup. To get a consistent
backup, do a LOCK TABLES on the relevant tables followed by FLUSH TABLES for the tables.
See Section 6.7.5 [LOCK TABLES], page 588. See Section 4.6.4 [FLUSH], page 285. You only
need a read lock; this allows other threads to continue to query the tables while you are
making a copy of the files in the database directory. The FLUSH TABLE is needed to ensure
that the all active index pages is written to disk before you start the backup.
Starting from 3.23.56 and 4.0.12 BACKUP TABLE will not allow you to overwrite existing files
as this would be a security risk.
If you want to make an SQL level backup of a table, you can use SELECT INTO OUTFILE
or BACKUP TABLE. See Section 6.4.1 [SELECT], page 536. See Section 4.5.2 [BACKUP
TABLE], page 264.
Another way to back up a database is to use the mysqldump program or the mysqlhotcopy
script. See Section 4.9.7 [mysqldump], page 344. See Section 4.9.8 [mysqlhotcopy],
page 348.
1. Do a full backup of your database:
shell> mysqldump --tab=/path/to/some/dir --opt db_name
or
shell> mysqlhotcopy db_name /path/to/some/dir
You can also simply copy all table files (‘*.frm’, ‘*.MYD’, and ‘*.MYI’ files) as long as
the server isn’t updating anything. The script mysqlhotcopy does use this method.
(But note that these methods will not work if your database contains InnoDB tables.
InnoDB does not store table contents in database directories, and mysqlhotcopy works
only for MyISAM and ISAM tables.)
2. Stop mysqld if it’s running, then start it with the --log-bin[=file_name] option.
See Section 4.10.4 [Binary log], page 356. The binary log files provide you with the
information you need to replicate changes to the database that are made subsequent
to the point at which you executed mysqldump.
If your MySQL server is a slave, whatever backup method you choose, when you backup
your slave’s data, you should also backup the ‘master.info’ and ‘relay-log.info’ files
which are always needed to resume replication after you restore the slave’s data. If your
slave is subject to replicating LOAD DATA INFILE commands, you should also backup the
‘SQL_LOAD-*’ files which may exist in the directory specified by the --slave-load-tmpdir
option. (This location defaults to the value of the tmpdir variable if not specified.) The slave
will need these files to resume replication of any interrupted LOAD DATA INFILE operations.
If you have to restore something, try to recover your tables using REPAIR TABLE or
myisamchk -r first. That should work in 99.9% of all cases. If myisamchk fails, try the
following procedure (this will only work if you have started MySQL with --log-bin, see
Section 4.10.4 [Binary log], page 356):
1. Restore the original mysqldump backup, or binary backup.
2. Execute the following command to re-run the updates in the binary log:
264
MySQL Technical Reference for Version 4.1.1-alpha
shell> mysqlbinlog hostname-bin.[0-9]* | mysql
In your case you may want to re-run only certain binlogs, from certain positions (usually
you want to re-run all binlogs from the date of the restored backup, possibly excepted
some wrong queries). See Section 4.9.5 [mysqlbinlog], page 341 for more information
on the mysqlbinlog utility and how to use it.
If you are using the update log (which will be removed in MySQL 5.0) you can execute
the content of the update log like this:
shell> ls -1 -t -r hostname.[0-9]* | xargs cat | mysql
ls is used to get all the update log files in the right order.
You can also do selective backups with SELECT * INTO OUTFILE ’file_name’ FROM tbl_
name and restore with LOAD DATA INFILE ’file_name’ REPLACE ... To avoid duplicate
records, you need a PRIMARY KEY or a UNIQUE key in the table. The REPLACE keyword
causes old records to be replaced with new ones when a new record duplicates an old record
on a unique key value.
If you get performance problems in making backups on your system, you can solve this
by setting up replication and do the backups on the slave instead of on the master. See
Section 4.11.1 [Replication Intro], page 360.
If you are using a Veritas filesystem, you can do:
1. From a client (or Perl), execute: FLUSH TABLES WITH READ LOCK.
2. From another shell, execute: mount vxfs snapshot.
3. From the first client, execute: UNLOCK TABLES.
4. Copy files from snapshot.
5. Unmount snapshot.
4.5.2 BACKUP TABLE Syntax
BACKUP TABLE tbl_name[,tbl_name...] TO ’/path/to/backup/directory’
Copies to the backup directory the minimum number of table files needed to restore the
table, after flushing any buffered changes to disk. Currently works only for MyISAM tables.
For MyISAM tables, copies ‘.frm’ (definition) and ‘.MYD’ (data) files. The index file can be
rebuilt from those two.
Before using this command, please see Section 4.5.1 [Backup], page 263.
During the backup, a read lock will be held for each table, one at time, as they are being
backed up. If you want to back up several tables as a snapshot, you must first issue LOCK
TABLES obtaining a read lock for each table in the group.
The command returns a table with the following columns:
Column
Value
Table
Table name
Op
Always backup
Msg type
One of status, error, info, or
warning
Msg text
The message
Note that BACKUP TABLE is only available in MySQL version 3.23.25 and later.
Chapter 4: Database Administration
265
4.5.3 RESTORE TABLE Syntax
RESTORE TABLE tbl_name[,tbl_name...] FROM ’/path/to/backup/directory’
Restores the table or tables from the backup that was made with BACKUP TABLE. Existing
tables will not be overwritten; if you try to restore over an existing table, you will get an
error. Restoring will take longer than backing up due to the need to rebuild the index. The
more keys you have, the longer it will take. Just as BACKUP TABLE, RESTORE TABLE currently
works only for MyISAM tables.
The command returns a table with the following columns:
Column
Value
Table
Table name
Op
Always restore
Msg type
One of status, error, info, or
warning
Msg text
The message
4.5.4 CHECK TABLE Syntax
CHECK TABLE tbl_name[,tbl_name...] [option [option...]]
option = QUICK | FAST | MEDIUM | EXTENDED | CHANGED
CHECK TABLE works only on MyISAM and InnoDB tables. On MyISAM tables, it’s the same
thing as running myisamchk --medium-check table_name on the table.
If you don’t specify any option, MEDIUM is used.
Checks the table or tables for errors. For MyISAM tables, the key statistics are updated. The
command returns a table with the following columns:
Column
Value
Table
Table name
Op
Always check
Msg type
One of status, error, info, or
warning
Msg text
The message
Note that the statement may produce many rows of information for each checked table.
The last row will be of Msg_type status and should normally be OK. If you don’t get
OK, or Table is already up to date you should normally run a repair of the table. See
Section 4.5.6 [Table maintenance], page 267. Table is already up to date means that the
storage manager for the table indicated that there was no need to check the table.
The different check types are as follows:
Type
Meaning
QUICK
Don’t scan the rows to check for incorrect links.
FAST
Only check tables that haven’t been closed properly.
CHANGED
Only check tables that have been changed since the last check or haven’t
been closed properly.
MEDIUM
Scan rows to verify that deleted links are okay. This also calculates a key
checksum for the rows and verifies this with a calculated checksum for the
keys.
266
MySQL Technical Reference for Version 4.1.1-alpha
EXTENDED
Do a full key lookup for all keys for each row. This ensures that the table
is 100% consistent, but will take a long time!
For dynamically sized MyISAM tables, a started check will always do a MEDIUM check. For
statically sized rows, we skip the row scan for QUICK and FAST as the rows are very seldom
corrupted.
You can combine check options, as in the following example that does a quick check on the
table to see whether it was closed properly:
CHECK TABLE test_table FAST QUICK;
Note: that in some cases CHECK TABLE will change the table! This happens if the table is
marked as ’corrupted’ or ’not closed properly’ but CHECK TABLE didn’t find any problems
in the table. In this case, CHECK TABLE will mark the table as okay.
If a table is corrupted, then it’s most likely that the problem is in the indexes and not in
the data part. All of the above check types checks the indexes thoroughly and should thus
find most errors.
If you just want to check a table that you assume is okay, you should use no check options
or the QUICK option. The latter should be used when you are in a hurry and can take the
very small risk that QUICK didn’t find an error in the datafile. (In most cases MySQL should
find, under normal usage, any error in the datafile. If this happens then the table will be
marked as ’corrupted’, in which case the table can’t be used until it’s repaired.)
FAST and CHANGED are mostly intended to be used from a script (for example to be executed
from cron) if you want to check your table from time to time. In most cases, FAST is to
be prefered over CHANGED. (The only case when it isn’t is when you suspect that you have
found a bug in the MyISAM code.)
EXTENDED is only to be used after you have run a normal check but still get strange errors
from a table when MySQL tries to update a row or find a row by key (this is very unlikely
if a normal check has succeeded!).
Some problems reported by CHECK TABLE can’t be corrected automatically:
• Found row where the auto_increment column has the value 0.
This means that you have a row in the table where the AUTO_INCREMENT index column
contains the value 0. (It’s possible to create a row where the AUTO_INCREMENT column
is 0 by explicitly setting the column to 0 with an UPDATE statement.)
This isn’t an error in itself, but could cause trouble if you decide to dump the table
and restore it or do an ALTER TABLE on the table. In this case, the AUTO_INCREMENT
column will change value, according to the rules of AUTO_INCREMENT columns, which
could cause problems such as a duplicate key error.
To get rid of the warning, just execute an UPDATE statement to set the column to some
other value than 0.
4.5.5 REPAIR TABLE Syntax
REPAIR [LOCAL | NO_WRITE_TO_BINLOG] TABLE tbl_name[,tbl_name...] [QUICK] [EXTENDED]
REPAIR TABLE works only on MyISAM tables and is the same as running myisamchk -r
table_name on the table.
Chapter 4: Database Administration
267
Normally you should never have to run this command, but if disaster strikes you are very
likely to get back all your data from a MyISAM table with REPAIR TABLE. If your tables
get corrupted a lot, you should try to find the reason for it, to eliminate the need to use
REPAIR TABLE. See Section A.4.1 [Crashing], page 870. See Section 7.1.3 [MyISAM table
problems], page 606.
REPAIR TABLE repairs a possibly corrupted table. The command returns a table with the
following columns:
Column
Value
Table
Table name
Op
Always repair
Msg type
One of status, error, info, or
warning
Msg text
The message
Note that the statement may produce many rows of information for each repaired table.
The last one row will be of Msg_type status and should normally be OK. If you don’t get
OK, you should try repairing the table with myisamchk --safe-recover, as REPAIR TABLE
does not yet implement all the options of myisamchk. In the near future, we will make it
more flexible.
If QUICK is given, REPAIR TABLE tries to repair only the index tree.
If you use EXTENDED, MySQL will create the index row by row instead of creating one index
at a time with sorting; this may be better than sorting on fixed-length keys if you have
long CHAR keys that compress very well. This type of repair is like that done by myisamchk
--safe-recover.
As of MySQL 4.0.2, there is a USE_FRM mode for REPAIR. Use it if the ‘.MYI’ file is missing
or if its header is corrupted. In this mode MySQL will recreate the table, using information
from the ‘.frm’ file. This kind of repair cannot be done with myisamchk.
Warning: If mysqld dies during a REPAIR TABLE, it’s essential that you do at once another
REPAIR on the table before executing any other commands on it. (It’s of course always
good to start with a backup). In the worst case you can have a new clean index file without
information about the datafile and when the next command you do may overwrite the
datafile. This is not a likely, but possible scenario.
Before MySQL 4.1.1, REPAIR commands are not written to the binary log. Since MySQL
4.1.1 they are written to the binary log unless the optional NO_WRITE_TO_BINLOG keyword
(or its alias LOCAL) was used.
4.5.6 Using myisamchk for Table Maintenance and Crash Recovery
Starting with MySQL Version 3.23.13, you can check MyISAM tables with the CHECK TABLE
command. See Section 4.5.4 [CHECK TABLE], page 265. You can repair tables with the
REPAIR TABLE command. See Section 4.5.5 [REPAIR TABLE], page 266.
To check/repair MyISAM tables (‘.MYI’ and ‘.MYD’) you should use the myisamchk utility.
To check/repair ISAM tables (‘.ISM’ and ‘.ISD’) you should use the isamchk utility. See
Chapter 7 [Table types], page 600.
In the following text we will talk about myisamchk, but everything also applies to the old
isamchk.
268
MySQL Technical Reference for Version 4.1.1-alpha
You can use the myisamchk utility to get information about your database tables, check and
repair them, or optimise them. The following sections describe how to invoke myisamchk
(including a description of its options), how to set up a table maintenance schedule, and
how to use myisamchk to perform its various functions.
You can, in most cases, also use the command OPTIMIZE TABLES to optimise and repair
tables, but this is not as fast or reliable (in case of real fatal errors) as myisamchk. On the
other hand, OPTIMIZE TABLE is easier to use and you don’t have to worry about flushing
tables. See Section 4.6.1 [OPTIMIZE TABLE], page 284.
Even though the repair in myisamchk is quite secure, it’s always a good idea to make a
backup before doing a repair (or anything that could make a lot of changes to a table)
4.5.6.1 myisamchk Invocation Syntax
myisamchk is invoked like this:
shell> myisamchk [options] tbl_name
The options specify what you want myisamchk to do. They are described here. (You can
also get a list of options by invoking myisamchk --help.) With no options, myisamchk
simply checks your table. To get more information or to tell myisamchk to take corrective
action, specify options as described here and in the following sections.
tbl_name is the database table you want to check/repair. If you run myisamchk somewhere other than in the database directory, you must specify the path to the file, because
myisamchk has no idea where your database is located. Actually, myisamchk doesn’t care
whether the files you are working on are located in a database directory; you can copy
the files that correspond to a database table into another location and perform recovery
operations on them there.
You can name several tables on the myisamchk command-line if you wish. You can also
specify a name as an index file name (with the ‘.MYI’ suffix), which allows you to specify
all tables in a directory by using the pattern ‘*.MYI’. For example, if you are in a database
directory, you can check all the tables in the directory like this:
shell> myisamchk *.MYI
If you are not in the database directory, you can check all the tables there by specifying the
path to the directory:
shell> myisamchk /path/to/database_dir/*.MYI
You can even check all tables in all databases by specifying a wildcard with the path to the
MySQL data directory:
shell> myisamchk /path/to/datadir/*/*.MYI
The recommended way to quickly check all tables is:
myisamchk --silent --fast /path/to/datadir/*/*.MYI
isamchk --silent /path/to/datadir/*/*.ISM
If you want to check all tables and repair all tables that are corrupted, you can use the
following line:
myisamchk --silent --force --fast --update-state -O key_buffer=64M \
-O sort_buffer=64M -O read_buffer=1M -O write_buffer=1M \
Chapter 4: Database Administration
269
/path/to/datadir/*/*.MYI
isamchk --silent --force -O key_buffer=64M -O sort_buffer=64M \
-O read_buffer=1M -O write_buffer=1M /path/to/datadir/*/*.ISM
The above assumes that you have more than 64 M free.
Note that if you get an error like:
myisamchk: warning: 1 clients is using or hasn’t closed the table properly
This means that you are trying to check a table that has been updated by another program
(like the mysqld server) that hasn’t yet closed the file or that has died without closing the
file properly.
If mysqld is running, you must force a sync/close of all tables with FLUSH TABLES and ensure
that no one is using the tables while you are running myisamchk. In MySQL Version 3.23
the easiest way to avoid this problem is to use CHECK TABLE instead of myisamchk to check
tables.
4.5.6.2 General Options for myisamchk
myisamchk supports the following options.
-# or --debug=debug_options
Output debug log. The debug_options string often is ’d:t:o,filename’.
-? or --help
Display a help message and exit.
-O name=value, --set-variable=name=value
Set the value of a variable. Please note that --set-variable=name=value
and -O name=value syntax is deprecated as of MySQL 4.0. Use --name=value
instead. The possible variables and their default values for myisamchk can be
examined with myisamchk --help:
Variable
Value
key buffer size
523264
read buffer size
262136
write buffer size
262136
sort buffer size
2097144
sort key blocks
16
decode bits
9
sort_buffer_size is used when the keys are repaired by sorting keys, which
is the normal case when you use --recover.
key_buffer_size is used when you are checking the table with --extendedcheck or when the keys are repaired by inserting key row by row in to the table
(like when doing normal inserts). Repairing through the key buffer is used in
the following cases:
• If you use --safe-recover.
• If the temporary files needed to sort the keys would be more than twice as
big as when creating the key file directly. This is often the case when you
have big CHAR, VARCHAR or TEXT keys as the sort needs to store the whole
270
MySQL Technical Reference for Version 4.1.1-alpha
keys during sorting. If you have lots of temporary space and you can force
myisamchk to repair by sorting you can use the --sort-recover option.
Reparing through the key buffer takes much less disk space than using sorting,
but is also much slower.
If you want a faster repair, set the above variables to about 1/4 of your available
memory. You can set both variables to big values, as only one of the above
buffers will be used at a time.
-s or --silent
Silent mode. Write output only when errors occur. You can use -s twice (-ss)
to make myisamchk very silent.
-v or --verbose
Verbose mode. Print more information. This can be used with -d and -e. Use
-v multiple times (-vv, -vvv) for more verbosity!
-V or --version
Print the myisamchk version and exit.
-w or, --wait
Instead of giving an error if the table is locked, wait until the table is unlocked
before continuing. Note that if you are running mysqld on the table with -skip-external-locking, the table can only be locked by another myisamchk
command.
4.5.6.3 Check Options for myisamchk
-c or --check
Check table for errors. This is the default operation if you are not giving
myisamchk any options that override this.
-e or --extend-check
Check the table very thoroughly (which is quite slow if you have many indexes).
This option should only be used in extreme cases. Normally, myisamchk or
myisamchk --medium-check should, in most cases, be able to find out if there
are any errors in the table.
If you are using --extended-check and have much memory, you should increase
the value of key_buffer_size a lot!
-F or --fast
Check only tables that haven’t been closed properly.
-C or --check-only-changed
Check only tables that have changed since the last check.
-f or --force
Restart myisamchk with -r (repair) on the table, if myisamchk finds any errors
in the table.
-i or --information
Print informational statistics about the table that is checked.
Chapter 4: Database Administration
271
-m or --medium-check
Faster than extended-check, but only finds 99.99% of all errors. Should, however, be good enough for most cases.
-U or --update-state
Store in the ‘.MYI’ file when the table was checked and if the table crashed.
This should be used to get full benefit of the --check-only-changed option,
but you shouldn’t use this option if the mysqld server is using the table and
you are running mysqld with --skip-external-locking.
-T or --read-only
Don’t mark table as checked. This is useful if you use myisamchk to check a
table that is in use by some other application that doesn’t use locking (like
mysqld --skip-external-locking).
4.5.6.4 Repair Options for myisamchk
The following options are used if you start myisamchk with -r or -o:
-B or --backup
Make a backup of the ‘.MYD’ file as ‘filename-time.BAK’
--correct-checksum
Correct checksum information for table.
-D # or --data-file-length=#
Max length of datafile (when re-creating datafile when it’s ’full’).
-e or --extend-check
Try to recover every possible row from the datafile. Normally this will also find
a lot of garbage rows. Don’t use this option if you are not totally desperate.
-f or --force
Overwrite old temporary files (‘table_name.TMD’) instead of aborting.
-k # or --keys-used=#
If you are using ISAM, tells the ISAM storage engine to update only the first #
indexes. If you are using MyISAM, tells which keys to use, where each binary bit
stands for one key (first key is bit 0). This can be used to get faster inserts!
Deactivated indexes can be reactivated by using myisamchk -r.
-l or --no-symlinks
Do not follow symbolic links. Normally myisamchk repairs the table a symlink
points at. This option doesn’t exist in MySQL 4.0, as MySQL 4.0 will not
remove symlinks during repair.
-p or --parallel-recover
Uses the same technique as -r and -n, but creates all the keys in parallel, in
different threads. This option was added in MySQL 4.0.2. This is alpha code.
Use at your own risk!
-r or --recover
Can fix almost anything except unique keys that aren’t unique (which is an
extremely unlikely error with ISAM/MyISAM tables). If you want to recover a
272
MySQL Technical Reference for Version 4.1.1-alpha
table, this is the option to try first. Only if myisamchk reports that the table
can’t be recovered by -r, you should then try -o. (Note that in the unlikely
case that -r fails, the datafile is still intact.) If you have lots of memory, you
should increase the size of sort_buffer_size!
-o or --safe-recover
Uses an old recovery method (reads through all rows in order and updates all
index trees based on the found rows); this is an order of magnitude slower than
-r, but can handle a couple of very unlikely cases that -r cannot handle. This
recovery method also uses much less disk space than -r. Normally one should
always first repair with -r, and only if this fails use -o.
If you have lots of memory, you should increase the size of key_buffer_size!
-n or --sort-recover
Force myisamchk to use sorting to resolve the keys even if the temporary files
should be very big.
--character-sets-dir=...
Directory where character sets are stored.
--set-character-set=name
Change the character set used by the index
-t or --tmpdir=path
Path for storing temporary files. If this is not set, myisamchk will use the
environment variable TMPDIR for this. Starting from MySQL 4.1, tmpdir can
be set to a list of paths separated by colon : (semicolon ; on Windows). They
will be used in round-robin fashion.
-q or --quick
Faster repair by not modifying the datafile. One can give a second -q to force
myisamchk to modify the original datafile in case of duplicate keys
-u or --unpack
Unpack file packed with myisampack.
4.5.6.5 Other Options for myisamchk
Other actions that myisamchk can do, besides repair and check tables:
-a or --analyze
Analyse the distribution of keys. This improves join performance by enabling
the join optimiser to better choose in which order it should join the tables and
which keys it should use: myisamchk --describe --verbose table_name’ or
using SHOW KEYS in MySQL.
-d or --description
Prints some information about table.
-A or --set-auto-increment[=value]
Force AUTO_INCREMENT to start at this or higher value. If no value is given,
then sets the next AUTO_INCREMENT value to the highest used value for the auto
key + 1.
Chapter 4: Database Administration
273
-S or --sort-index
Sort the index tree blocks in high-low order. This will optimise seeks and will
make table scanning by key faster.
-R or --sort-records=#
Sorts records according to an index. This makes your data much more localised
and may speed up ranged SELECT and ORDER BY operations on this index. (It
may be very slow to do a sort the first time!) To find out a table’s index
numbers, use SHOW INDEX, which shows a table’s indexes in the same order that
myisamchk sees them. Indexes are numbered beginning with 1.
4.5.6.6 myisamchk Memory Usage
Memory allocation is important when you run myisamchk. myisamchk uses no more memory
than you specify with the -O options. If you are going to use myisamchk on very large files,
you should first decide how much memory you want it to use. The default is to use only
about 3M to perform repairs. By using larger values, you can get myisamchk to operate
faster. For example, if you have more than 32M RAM, you could use options such as these
(in addition to any other options you might specify):
shell> myisamchk -O sort=16M -O key=16M -O read=1M -O write=1M ...
Using -O sort=16M should probably be enough for most cases.
Be aware that myisamchk uses temporary files in TMPDIR. If TMPDIR points to a memory
filesystem, you may easily get out of memory errors. If this happens, set TMPDIR to point
at some directory with more space and restart myisamchk.
When repairing, myisamchk will also need a lot of disk space:
• Double the size of the record file (the original one and a copy). This space is not needed
if one does a repair with --quick, as in this case only the index file will be re-created.
This space is needed on the same disk as the original record file!
• Space for the new index file that replaces the old one. The old index file is truncated
at start, so one usually ignore this space. This space is needed on the same disk as the
original index file!
• When using --recover or --sort-recover (but not when using --safe-recover), you
will need space for a sort buffer for: (largest_key + row_pointer_length)*number_
of_rows * 2. You can check the length of the keys and the row pointer length with
myisamchk -dv table. This space is allocated on the temporary disk (specified by
TMPDIR or --tmpdir=#).
If you have a problem with disk space during repair, you can try to use --safe-recover
instead of --recover.
4.5.6.7 Using myisamchk for Crash Recovery
If you run mysqld with --skip-external-locking (which is the default on some systems,
like Linux), you can’t reliably use myisamchk to check a table when mysqld is using the
same table. If you can be sure that no one is accessing the tables through mysqld while you
run myisamchk, you only have to do mysqladmin flush-tables before you start checking
274
MySQL Technical Reference for Version 4.1.1-alpha
the tables. If you can’t guarantee the above, then you must take down mysqld while you
check the tables. If you run myisamchk while mysqld is updating the tables, you may get
a warning that a table is corrupt even if it isn’t.
If you are not using --skip-external-locking, you can use myisamchk to check tables
at any time. While you do this, all clients that try to update the table will wait until
myisamchk is ready before continuing.
If you use myisamchk to repair or optimise tables, you must always ensure that the mysqld
server is not using the table (this also applies if you are using --skip-external-locking).
If you don’t take down mysqld you should at least do a mysqladmin flush-tables before
you run myisamchk. Your tables may be corrupted if the server and myisamchk access the
tables simultaneously.
This chapter describes how to check for and deal with data corruption in MySQL databases.
If your tables get corrupted frequently you should try to find the reason for this! See
Section A.4.1 [Crashing], page 870.
The MyISAM table section contains reason for why a table could be corrupted. See Section 7.1.3 [MyISAM table problems], page 606.
When performing crash recovery, it is important to understand that each table tbl_name
in a database corresponds to three files in the database directory:
File
‘tbl_name.frm’
‘tbl_name.MYD’
‘tbl_name.MYI’
Purpose
Table definition (form)
file
Datafile
Index file
Each of these three file types is subject to corruption in various ways, but problems occur
most often in datafiles and index files.
myisamchk works by creating a copy of the ‘.MYD’ (data) file row by row. It ends the repair
stage by removing the old ‘.MYD’ file and renaming the new file to the original file name. If
you use --quick, myisamchk does not create a temporary ‘.MYD’ file, but instead assumes
that the ‘.MYD’ file is correct and only generates a new index file without touching the ‘.MYD’
file. This is safe, because myisamchk automatically detects if the ‘.MYD’ file is corrupt and
aborts the repair in this case. You can also give two --quick options to myisamchk. In
this case, myisamchk does not abort on some errors (like duplicate key) but instead tries
to resolve them by modifying the ‘.MYD’ file. Normally the use of two --quick options is
useful only if you have too little free disk space to perform a normal repair. In this case
you should at least make a backup before running myisamchk.
4.5.6.8 How to Check Tables for Errors
To check a MyISAM table, use the following commands:
myisamchk tbl_name
This finds 99.99% of all errors. What it can’t find is corruption that involves
only the datafile (which is very unusual). If you want to check a table, you
should normally run myisamchk without options or with either the -s or -silent option.
Chapter 4: Database Administration
275
myisamchk -m tbl_name
This finds 99.999% of all errors. It checks first all index entries for errors and
then it reads through all rows. It calculates a checksum for all keys in the rows
and verifies that they checksum matches the checksum for the keys in the index
tree.
myisamchk -e tbl_name
This does a complete and thorough check of all data (-e means “extended
check”). It does a check-read of every key for each row to verify that they
indeed point to the correct row. This may take a long time on a big table
with many keys. myisamchk will normally stop after the first error it finds. If
you want to obtain more information, you can add the --verbose (-v) option.
This causes myisamchk to keep going, up through a maximum of 20 errors. In
normal usage, a simple myisamchk (with no arguments other than the table
name) is sufficient.
myisamchk -e -i tbl_name
Like the previous command, but the -i option tells myisamchk to print some
informational statistics, too.
4.5.6.9 How to Repair Tables
In the following section we only talk about using myisamchk on MyISAM tables (extensions
‘.MYI’ and ‘.MYD’). If you are using ISAM tables (extensions ‘.ISM’ and ‘.ISD’), you should
use isamchk instead.
Starting with MySQL Version 3.23.14, you can repair MyISAM tables with the REPAIR
TABLE command. See Section 4.5.5 [REPAIR TABLE], page 266.
The symptoms of a corrupted table include queries that abort unexpectedly and observable
errors such as these:
• ‘tbl_name.frm’ is locked against change
• Can’t find file ‘tbl_name.MYI’ (Errcode: ###)
• Unexpected end of file
• Record file is crashed
• Got error ### from table handler
To get more information about the error you can run perror ###. Here is the most
common errors that indicates a problem with the table:
shell> perror 126 127 132 134 135 136 141 144 145
126 = Index file is crashed / Wrong file format
127 = Record-file is crashed
132 = Old database file
134 = Record was already deleted (or record file crashed)
135 = No more room in record file
136 = No more room in index file
141 = Duplicate unique key or constraint on write or update
144 = Table is crashed and last repair failed
145 = Table was marked as crashed and should be repaired
276
MySQL Technical Reference for Version 4.1.1-alpha
Note that error 135 (no more room in record file), is not an error that can be fixed by
a simple repair. In this case you have to do:
ALTER TABLE table MAX_ROWS=xxx AVG_ROW_LENGTH=yyy;
You can also use this technique for error 136 (no more room in index file).
In the other cases, you must repair your tables. myisamchk can usually detect and fix most
problems that occur.
The repair process involves up to four stages, described here. Before you begin, you should
cd to the database directory and check the permissions of the table files. Make sure they are
readable by the Unix user that mysqld runs as (and to you, because you need to access the
files you are checking). If it turns out you need to modify files, they must also be writable
by you.
If you are using MySQL Version 3.23.16 and above, you can (and should) use the CHECK and
REPAIR commands to check and repair MyISAM tables. See Section 4.5.4 [CHECK TABLE],
page 265. See Section 4.5.5 [REPAIR TABLE], page 266.
The manual section about table maintenance includes the options to isamchk/myisamchk.
See Section 4.5.6 [Table maintenance], page 267.
The following section is for the cases where the above command fails or if you want to use
the extended features that isamchk/myisamchk provides.
If you are going to repair a table from the command-line, you must first take down the
mysqld server. Note that when you do mysqladmin shutdown on a remote server, the
mysqld server will still be alive for a while after mysqladmin returns, until all queries are
stopped and all keys have been flushed to disk.
Stage 1: Checking your tables
Run myisamchk *.MYI or myisamchk -e *.MYI if you have more time. Use the -s (silent)
option to suppress unnecessary information.
If the mysqld server is done you should use the –update option to tell myisamchk to mark
the table as ’checked’.
You have to repair only those tables for which myisamchk announces an error. For such
tables, proceed to Stage 2.
If you get weird errors when checking (such as out of memory errors), or if myisamchk
crashes, go to Stage 3.
Stage 2: Easy safe repair
Note: If you want repairing to go much faster, you should add: -O sort_buffer=# -O
key_buffer=# (where # is about 1/4 of the available memory) to all isamchk/myisamchk
commands.
First, try myisamchk -r -q tbl_name (-r -q means “quick recovery mode”). This will
attempt to repair the index file without touching the datafile. If the datafile contains
everything that it should and the delete links point at the correct locations within the
datafile, this should work, and the table is fixed. Start repairing the next table. Otherwise,
use the following procedure:
1. Make a backup of the datafile before continuing.
2. Use myisamchk -r tbl_name (-r means “recovery mode”). This will remove incorrect
records and deleted records from the datafile and reconstruct the index file.
Chapter 4: Database Administration
277
3. If the preceding step fails, use myisamchk --safe-recover tbl_name. Safe recovery
mode uses an old recovery method that handles a few cases that regular recovery mode
doesn’t (but is slower).
If you get weird errors when repairing (such as out of memory errors), or if myisamchk
crashes, go to Stage 3.
Stage 3: Difficult repair
You should only reach this stage if the first 16K block in the index file is destroyed or
contains incorrect information, or if the index file is missing. In this case, it’s necessary to
create a new index file. Do so as follows:
1. Move the datafile to some safe place.
2. Use the table description file to create new (empty) data and index files:
shell> mysql db_name
mysql> SET AUTOCOMMIT=1;
mysql> TRUNCATE TABLE table_name;
mysql> quit
If your SQL version doesn’t have TRUNCATE TABLE, use DELETE FROM table_name instead.
3. Copy the old datafile back onto the newly created datafile. (Don’t just move the old
file back onto the new file; you want to retain a copy in case something goes wrong.)
Go back to Stage 2. myisamchk -r -q should work now. (This shouldn’t be an endless
loop.)
As of MySQL 4.0.2 you can also use REPAIR ... USE_FRM which performs the whole procedure
automatically.
Stage 4: Very difficult repair
You should reach this stage only if the description file has also crashed. That should never
happen, because the description file isn’t changed after the table is created:
1. Restore the description file from a backup and go back to Stage 3. You can also
restore the index file and go back to Stage 2. In the latter case, you should start with
myisamchk -r.
2. If you don’t have a backup but know exactly how the table was created, create a copy
of the table in another database. Remove the new datafile, then move the description
and index files from the other database to your crashed database. This gives you new
description and index files, but leaves the datafile alone. Go back to Stage 2 and
attempt to reconstruct the index file.
4.5.6.10 Table Optimisation
To coalesce fragmented records and eliminate wasted space resulting from deleting or updating records, run myisamchk in recovery mode:
shell> myisamchk -r tbl_name
You can optimise a table in the same way using the SQL OPTIMIZE TABLE statement.
OPTIMIZE TABLE does a repair of the table and a key analysis, and also sorts the index
tree to give faster key lookups. There is also no possibility of unwanted interaction between
278
MySQL Technical Reference for Version 4.1.1-alpha
a utility and the server, because the server does all the work when you use OPTIMIZE TABLE.
See Section 4.6.1 [OPTIMIZE TABLE], page 284.
myisamchk also has a number of other options you can use to improve the performance of
a table:
• -S, --sort-index
• -R index_num, --sort-records=index_num
• -a, --analyze
For a full description of the option. See Section 4.5.6.1 [myisamchk syntax], page 268.
4.5.7 Setting Up a Table Maintenance Regimen
Starting with MySQL Version 3.23.13, you can check MyISAM tables with the CHECK TABLE
command. See Section 4.5.4 [CHECK TABLE], page 265. You can repair tables with the
REPAIR TABLE command. See Section 4.5.5 [REPAIR TABLE], page 266.
It is a good idea to perform table checks on a regular basis rather than waiting for problems
to occur. For maintenance purposes, you can use myisamchk -s to check tables. The -s
option (short for --silent) causes myisamchk to run in silent mode, printing messages only
when errors occur.
It’s also a good idea to check tables when the server starts up. For example, whenever the
machine has done a reboot in the middle of an update, you usually need to check all the
tables that could have been affected. (This is an “expected crashed table”.) You could add
a test to mysqld_safe that runs myisamchk to check all tables that have been modified
during the last 24 hours if there is an old ‘.pid’ (process ID) file left after a reboot. (The
‘.pid’ file is created by mysqld when it starts up and removed when it terminates normally.
The presence of a ‘.pid’ file at system startup time indicates that mysqld terminated
abnormally.)
An even better test would be to check any table whose last-modified time is more recent
than that of the ‘.pid’ file.
You should also check your tables regularly during normal system operation. At MySQL
AB, we run a cron job to check all our important tables once a week, using a line like this
in a ‘crontab’ file:
35 0 * * 0 /path/to/myisamchk --fast --silent /path/to/datadir/*/*.MYI
This prints out information about crashed tables so we can examine and repair them when
needed.
As we haven’t had any unexpectedly crashed tables (tables that become corrupted for
reasons other than hardware trouble) for a couple of years now (this is really true), once a
week is more than enough for us.
We recommend that to start with, you execute myisamchk -s each night on all tables that
have been updated during the last 24 hours, until you come to trust MySQL as much as we
do.
Normally you don’t need to maintain MySQL tables that much. If you are changing tables
with dynamic size rows (tables with VARCHAR, BLOB or TEXT columns) or have tables with
many deleted rows you may want to from time to time (once a month?) defragment/reclaim
space from the tables.
Chapter 4: Database Administration
279
You can do this by using OPTIMIZE TABLE on the tables in question or if you can take down
the mysqld server for a while do:
isamchk -r --silent --sort-index -O sort_buffer_size=16M */*.ISM
myisamchk -r --silent --sort-index -O sort_buffer_size=16M */*.MYI
4.5.8 Getting Information About a Table
To get a description of a table or statistics about it, use the commands shown here. We
explain some of the information in more detail later:
• myisamchk -d tbl name Runs myisamchk in “describe mode” to produce a description of
your table. If you start the MySQL server using the --skip-external-locking option,
myisamchk may report an error for a table that is updated while it runs. However,
because myisamchk doesn’t change the table in describe mode, there isn’t any risk of
destroying data.
• myisamchk -d -v tbl name To produce more information about what myisamchk is
doing, add -v to tell it to run in verbose mode.
• myisamchk -eis tbl name Shows only the most important information from a table. It
is slow because it must read the whole table.
• myisamchk -eiv tbl name This is like -eis, but tells you what is being done.
Example of myisamchk -d output:
MyISAM file:
Record format:
Data records:
Recordlength:
company.MYI
Fixed length
1403698 Deleted blocks:
226
table description:
Key Start Len Index
1
2
8
unique
2
15
10 multip.
3
219
8
multip.
4
63
10 multip.
5
167
2
multip.
6
177
4
multip.
7
155
4
multip.
8
138
4
multip.
9
177
4
multip.
193
1
Type
double
text packed stripped
double
text packed stripped
unsigned short
unsigned long
text
unsigned long
unsigned long
text
Example of myisamchk -d -v output:
MyISAM file:
Record format:
File-version:
Creation time:
Recover time:
Status:
company
Fixed length
1
1999-10-30 12:12:51
1999-10-31 19:13:01
checked
0
280
MySQL Technical Reference for Version 4.1.1-alpha
Data records:
1403698
Datafile parts:
1403698
Datafilepointer (bytes):
3
Max datafile length: 3791650815
Recordlength:
226
table description:
Key Start Len Index
1
2
8
unique
2
15
10 multip.
3
219
8
multip.
4
63
10 multip.
5
167
2
multip.
6
177
4
multip.
7
155
4
multip.
8
138
4
multip.
9
177
4
multip.
193
1
Deleted blocks:
0
Deleted data:
0
Keyfile pointer (bytes):
3
Max keyfile length: 4294967294
Type
double
text packed stripped
double
text packed stripped
unsigned short
unsigned long
text
unsigned long
unsigned long
text
Rec/key
1
2
73
5
4840
1346
4995
87
178
Root Blocksize
15845376
1024
25062400
1024
40907776
1024
48097280
1024
55200768
1024
65145856
1024
75090944
1024
85036032
1024
96481280
1024
Example of myisamchk -eis output:
Checking MyISAM file: company
Key: 1: Keyblocks used: 97%
Key: 2: Keyblocks used: 98%
Key: 3: Keyblocks used: 97%
Key: 4: Keyblocks used: 99%
Key: 5: Keyblocks used: 99%
Key: 6: Keyblocks used: 99%
Key: 7: Keyblocks used: 99%
Key: 8: Keyblocks used: 99%
Key: 9: Keyblocks used: 98%
Total:
Keyblocks used: 98%
Records:
1403698
Packed:
0%
Recordspace used:
100%
Blocks/Record:
1.00
Record blocks:
1403698
Recorddata:
317235748
Lost space:
0
Packed:
Packed:
Packed:
Packed:
Packed:
Packed:
Packed:
Packed:
Packed:
Packed:
0%
50%
0%
60%
0%
0%
0%
0%
0%
17%
M.recordlength:
Max
Max
Max
Max
Max
Max
Max
Max
Max
levels:
levels:
levels:
levels:
levels:
levels:
levels:
levels:
levels:
4
4
4
3
3
3
3
3
4
226
Empty space:
0%
Delete blocks:
Deleted data:
Linkdata:
0
0
0
User time 1626.51, System time 232.36
Maximum resident set size 0, Integral resident set size 0
Non physical pagefaults 0, Physical pagefaults 627, Swaps 0
Blocks in 0 out 0, Messages in 0 out 0, Signals 0
Voluntary context switches 639, Involuntary context switches 28966
Example of myisamchk -eiv output:
Checking MyISAM file: company
Chapter 4: Database Administration
281
Data records: 1403698
Deleted blocks:
- check file-size
- check delete-chain
block_size 1024:
index 1:
index 2:
index 3:
index 4:
index 5:
index 6:
index 7:
index 8:
index 9:
No recordlinks
- check index reference
- check data record references index: 1
Key: 1: Keyblocks used: 97% Packed:
- check data record references index: 2
Key: 2: Keyblocks used: 98% Packed:
- check data record references index: 3
Key: 3: Keyblocks used: 97% Packed:
- check data record references index: 4
Key: 4: Keyblocks used: 99% Packed:
- check data record references index: 5
Key: 5: Keyblocks used: 99% Packed:
- check data record references index: 6
Key: 6: Keyblocks used: 99% Packed:
- check data record references index: 7
Key: 7: Keyblocks used: 99% Packed:
- check data record references index: 8
Key: 8: Keyblocks used: 99% Packed:
- check data record references index: 9
Key: 9: Keyblocks used: 98% Packed:
Total:
Keyblocks used:
9% Packed:
0
0%
Max levels:
4
50%
Max levels:
4
0%
Max levels:
4
60%
Max levels:
3
0%
Max levels:
3
0%
Max levels:
3
0%
Max levels:
3
0%
Max levels:
3
0%
17%
Max levels:
4
- check records and index references
[LOTS OF ROW NUMBERS DELETED]
Records:
1403698
Recordspace used:
100%
Record blocks:
1403698
Recorddata:
317235748
Lost space:
0
M.recordlength:
Empty space:
Delete blocks:
Deleted data:
Linkdata:
226
0%
0
0
0
Packed:
Blocks/Record:
User time 1639.63, System time 251.61
Maximum resident set size 0, Integral resident set size 0
Non physical pagefaults 0, Physical pagefaults 10580, Swaps 0
0%
1.00
282
MySQL Technical Reference for Version 4.1.1-alpha
Blocks in 4 out 0, Messages in 0 out 0, Signals 0
Voluntary context switches 10604, Involuntary context switches 122798
Here are the sizes of the data and index files for the table used in the preceding examples:
-rw-rw-r-1 monty
tcx
317235748 Jan 12 17:30 company.MYD
-rw-rw-r-1 davida
tcx
96482304 Jan 12 18:35 company.MYM
Explanations for the types of information myisamchk produces are given here. The “keyfile”
is the index file. “Record” and “row” are synonymous:
• ISAM file Name of the ISAM (index) file.
• Isam-version Version of ISAM format. Currently always 2.
• Creation time When the datafile was created.
• Recover time When the index/datafile was last reconstructed.
• Data records How many records are in the table.
• Deleted blocks How many deleted blocks still have reserved space. You can optimise
your table to minimise this space. See Section 4.5.6.10 [Optimisation], page 277.
• Data file: Parts For dynamic record format, this indicates how many data blocks there
are. For an optimised table without fragmented records, this is the same as Data
records.
• Deleted data How many bytes of non-reclaimed deleted data there are. You can optimise your table to minimise this space. See Section 4.5.6.10 [Optimisation], page 277.
• Data file pointer The size of the datafile pointer, in bytes. It is usually 2, 3, 4, or 5
bytes. Most tables manage with 2 bytes, but this cannot be controlled from MySQL
yet. For fixed tables, this is a record address. For dynamic tables, this is a byte address.
• Keyfile pointer The size of the index file pointer, in bytes. It is usually 1, 2, or 3 bytes.
Most tables manage with 2 bytes, but this is calculated automatically by MySQL. It
is always a block address.
• Max datafile length How long the table’s datafile (‘.MYD’ file) can become, in bytes.
• Max keyfile length How long the table’s key file (‘.MYI’ file) can become, in bytes.
• Recordlength How much space each record takes, in bytes.
• Record format The format used to store table rows. The preceding examples use Fixed
length. Other possible values are Compressed and Packed.
• table description A list of all keys in the table. For each key, some low-level information
is presented:
− Key This key’s number.
− Start Where in the record this index part starts.
− Len How long this index part is. For packed numbers, this should always be the
full length of the column. For strings, it may be shorter than the full length of the
indexed column, because you can index a prefix of a string column.
− Index unique or multip. (multiple). Indicates whether one value can exist multiple times in this index.
− Type What data-type this index part has. This is an ISAM data-type with the
options packed, stripped or empty.
− Root Address of the root index block.
Chapter 4: Database Administration
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
283
− Blocksize The size of each index block. By default this is 1024, but the value may
be changed at compile time.
− Rec/key This is a statistical value used by the optimiser. It tells how many records
there are per value for this key. A unique key always has a value of 1. This may
be updated after a table is loaded (or greatly changed) with myisamchk -a. If this
is not updated at all, a default value of 30 is given.
In the first example above, the 9th key is a multi-part key with two parts.
Keyblocks used What percentage of the keyblocks are used. Because the table used in
the examples had just been reorganised with myisamchk, the values are very high (very
near the theoretical maximum).
Packed MySQL tries to pack keys with a common suffix. This can only be used for
CHAR/VARCHAR/DECIMAL keys. For long strings like names, this can significantly reduce
the space used. In the third example above, the 4th key is 10 characters long and a
60% reduction in space is achieved.
Max levels How deep the B-tree for this key is. Large tables with long keys get high
values.
Records How many rows are in the table.
M.recordlength The average record length. For tables with fixed-length records, this is
the exact record length.
Packed MySQL strips spaces from the end of strings. The Packed value indicates the
percentage of savings achieved by doing this.
Recordspace used What percentage of the datafile is used.
Empty space What percentage of the datafile is unused.
Blocks/Record Average number of blocks per record (that is, how many links a fragmented record is composed of). This is always 1.0 for fixed-format tables. This value
should stay as close to 1.0 as possible. If it gets too big, you can reorganise the table
with myisamchk. See Section 4.5.6.10 [Optimisation], page 277.
Recordblocks How many blocks (links) are used. For fixed format, this is the same as
the number of records.
Deleteblocks How many blocks (links) are deleted.
Recorddata How many bytes in the datafile are used.
Deleted data How many bytes in the datafile are deleted (unused).
Lost space If a record is updated to a shorter length, some space is lost. This is the
sum of all such losses, in bytes.
Linkdata When the dynamic table format is used, record fragments are linked with
pointers (4 to 7 bytes each). Linkdata is the sum of the amount of storage used by all
such pointers.
If a table has been compressed with myisampack, myisamchk -d prints additional information about each table column. See Section 4.8.4 [myisampack], page 320, for an example of
this information and a description of what it means.
4.6 Database Administration Language Reference
284
MySQL Technical Reference for Version 4.1.1-alpha
4.6.1 OPTIMIZE TABLE Syntax
OPTIMIZE [LOCAL | NO_WRITE_TO_BINLOG] TABLE tbl_name[,tbl_name]...
OPTIMIZE TABLE should be used if you have deleted a large part of a table or if you have
made many changes to a table with variable-length rows (tables that have VARCHAR, BLOB,
or TEXT columns). Deleted records are maintained in a linked list and subsequent INSERT
operations reuse old record positions. You can use OPTIMIZE TABLE to reclaim the unused
space and to defragment the datafile.
In most setups you don’t have to run OPTIMIZE TABLE at all. Even if you do a lot of updates
to variable length rows it’s not likely that you need to do this more than once a month/week
and only on certain tables.
For the moment, OPTIMIZE TABLE works only on MyISAM and BDB tables. For BDB tables,
OPTIMIZE TABLE is currently mapped to ANALYZE TABLE. See Section 4.6.2 [ANALYZE TABLE],
page 284.
You can get OPTIMIZE TABLE to work on other table types by starting mysqld with --skipnew or --safe-mode, but in this case OPTIMIZE TABLE is just mapped to ALTER TABLE.
OPTIMIZE TABLE works the following way:
• If the table has deleted or split rows, repair the table.
• If the index pages are not sorted, sort them.
• If the statistics are not up to date (and the repair couldn’t be done by sorting the
index), update them.
Note that the table is locked during the time OPTIMIZE TABLE is running!
Before MySQL 4.1.1, OPTIMIZE commands are not written to the binary log. Since MySQL
4.1.1 they are written to the binary log unless the optional NO_WRITE_TO_BINLOG keyword
(or its alias LOCAL) was used.
4.6.2 ANALYZE TABLE Syntax
ANALYZE [LOCAL | NO_WRITE_TO_BINLOG] TABLE tbl_name[,tbl_name...]
Analyse and store the key distribution for the table. During the analysis, the table is locked
with a read lock. This works on MyISAM and BDB tables.
This is equivalent to running myisamchk -a on the table.
MySQL uses the stored key distribution to decide in which order tables should be joined
when one does a join on something else than a constant.
The command returns a table with the following columns:
Column
Value
Table
Table name
Op
Always analyze
Msg type
One of status, error, info, or
warning
Msg text
The message
You can check the stored key distribution with the SHOW INDEX command.
See
Section 4.6.8.1 [Show database info], page 288.
Chapter 4: Database Administration
285
If the table hasn’t changed since the last ANALYZE TABLE command, the table will not be
analysed again.
Before MySQL 4.1.1, ANALYZE commands are not written to the binary log. Since MySQL
4.1.1 they are written to the binary log unless the optional NO_WRITE_TO_BINLOG keyword
(or its alias LOCAL) was used.
4.6.3 CHECKSUM TABLE Syntax
CHECKSUM TABLE tbl_name[,tbl_name ...] [ QUICK | EXTENDED ]
Reports a table checksum. If QUICK is specified, live table checksum is reported, or NULL if
the table does not support live checksum. This is very fast. In EXTENDED mode the whole
table is read row by row and the checksum is calculated. This can be very slow for large
tables. By default - with neither QUICK nor EXTENDED - MySQL returns live checksum if
the table support it and scans the table otherwise.
This command is implemented in MySQL 4.1.1.
4.6.4 FLUSH Syntax
FLUSH [LOCAL | NO_WRITE_TO_BINLOG] flush_option [,flush_option] ...
You should use the FLUSH command if you want to clear some of the internal caches MySQL
uses. To execute FLUSH, you must have the RELOAD privilege.
flush_option can be any of the following:
Option
Description
HOSTS
Empties the host cache tables. You should flush the host tables
if some of your hosts change IP number or if you get the error
message Host ... is blocked. When more than max_connect_
errors errors occur in a row for a given host while connection
to the MySQL server, MySQL assumes something is wrong and
blocks the host from further connection requests. Flushing the
host tables allows the host to attempt to connect again. See Section A.2.5 [Blocked host], page 861. You can start mysqld with
-O max_connect_errors=999999999 to avoid this error message.
DES_KEY_FILE
Reloads the DES keys from the file that was specified with the
--des-key-file option at server startup time.
LOGS
Closes and reopens all log files. If you have specified an update log
file or a binary log file without an extension, the extension number
of the log file will be incremented by one relative to the previous
file. If you have used an extension in the file name, MySQL will
close and reopen the update log file. See Section 4.10.3 [Update
log], page 355. This is the same thing as sending the SIGHUP signal
to the mysqld server.
PRIVILEGES
Reloads the privileges from the grant tables in the mysql database.
286
MySQL Technical Reference for Version 4.1.1-alpha
QUERY CACHE
Defragment the query cache to better utilise its memory. This
command will not remove any queries from the cache, unlike RESET
QUERY CACHE.
TABLES
Closes all open tables and force all tables in use to be closed. This
also flushes the query cache.
[TABLE | TABLES]
tbl_name [,tbl_
name...]
TABLES WITH READ
LOCK
Flushes only the given tables.
STATUS
Resets most status variables to zero. This is something one should
only use when debugging a query.
Closes all open tables and locks all tables for all databases with
a read lock until you execute UNLOCK TABLES. This is very convenient way to get backups if you have a filesystem, like Veritas,
that can take snapshots in time.
USER_RESOURCES
Resets all user resources to zero. This will enable blocked users to
login again. See Section 4.4.7 [User resources], page 253.
Before MySQL 4.1.1, FLUSH commands are not written to the binary log. Since MySQL
4.1.1 they are written to the binary log unless the optional NO_WRITE_TO_BINLOG keyword
(or its alias LOCAL) was used, or unless the command contained one of these arguments:
LOGS, MASTER, SLAVE, TABLES WITH READ LOCK, because any of these arguments may cause
problems if replicated to a slave.
You can also access some of the commands shown above with the mysqladmin utility,
using the flush-hosts, flush-logs, flush-privileges, flush-status or flush-tables
commands.
Take also a look at the RESET command used with replication. See Section 4.6.5 [RESET],
page 286.
4.6.5 RESET Syntax
RESET reset_option [,reset_option] ...
The RESET command is used to clear things. It also acts as an stronger version of the FLUSH
command. See Section 4.6.4 [FLUSH], page 285.
To execute RESET, you must have the RELOAD privilege.
Option
Description
MASTER
Deletes all binary logs listed in the index file, resetting the binlog
index file to be empty. Previously named FLUSH MASTER. See
Section 4.11.7 [Replication Master SQL], page 381.
SLAVE
Makes the slave forget its replication position in the master binlogs. Previously named FLUSH SLAVE. See Section 4.11.8 [Replication Slave SQL], page 382.
QUERY CACHE
Removes all query results from the query cache.
Chapter 4: Database Administration
287
4.6.6 PURGE MASTER LOGS Syntax
PURGE {MASTER|BINARY} LOGS TO binlog_name
PURGE {MASTER|BINARY} LOGS BEFORE date
This command is used to delete all binary logs strictly prior to the specified binlog or date.
See Section 4.11.7 [Replication Master SQL], page 381.
PURGE BINARY LOGS is available as a synonym for PURGE MASTER LOGS as of MySQL 4.1.1.
4.6.7 KILL Syntax
KILL thread_id
Each connection to mysqld runs in a separate thread. You can see which threads are
running with the SHOW PROCESSLIST command and kill a thread with the KILL thread_id
command.
If you have the PROCESS privilege, you can see all threads. If you have the SUPER privilege,
you can kill all threads. Otherwise, you can only see and kill your own threads.
You can also use the mysqladmin processlist and mysqladmin kill commands to examine and kill threads.
Note: You currently cannot use KILL with the Embedded MySQL Server library, because
the embedded server merely runs inside the threads of the host application, it does not
create connection threads of its own.
When you do a KILL, a thread-specific kill flag is set for the thread.
In most cases it may take some time for the thread to die as the kill flag is only checked at
specific intervals.
• In SELECT, ORDER BY and GROUP BY loops, the flag is checked after reading a block of
rows. If the kill flag is set, the statement is aborted.
• When doing an ALTER TABLE the kill flag is checked before each block of rows are
read from the original table. If the kill flag was set the command is aborted and the
temporary table is deleted.
• When doing an UPDATE or DELETE, the kill flag is checked after each block read and
after each updated or deleted row. If the kill flag is set, the statement is aborted. Note
that if you are not using transactions, the changes will not be rolled back!
• GET_LOCK() will abort with NULL.
• An INSERT DELAYED thread will quickly flush all rows it has in memory and die.
• If the thread is in the table lock handler (state: Locked), the table lock will be quickly
aborted.
• If the thread is waiting for free disk space in a write call, the write is aborted with an
disk full error message.
4.6.8 SHOW Syntax
SHOW DATABASES [LIKE wild]
or SHOW [OPEN] TABLES [FROM db_name] [LIKE wild]
288
MySQL Technical Reference for Version 4.1.1-alpha
or
or
or
or
or
or
or
or
or
or
or
or
or
or
or
SHOW
SHOW
SHOW
SHOW
SHOW
SHOW
SHOW
SHOW
SHOW
SHOW
SHOW
SHOW
SHOW
SHOW
SHOW
[FULL] COLUMNS FROM tbl_name [FROM db_name] [LIKE wild]
INDEX FROM tbl_name [FROM db_name]
TABLE STATUS [FROM db_name] [LIKE wild]
STATUS [LIKE wild]
VARIABLES [LIKE wild]
[BDB] LOGS
[FULL] PROCESSLIST
GRANTS FOR user
CREATE TABLE table_name
MASTER STATUS
MASTER LOGS
SLAVE STATUS
WARNINGS [LIMIT row_count]
ERRORS [LIMIT row_count]
TABLE TYPES
SHOW provides information about databases, tables, columns, or status information about
the server. If the LIKE wild part is used, the wild string can be a string that uses the SQL
‘%’ and ‘_’ wildcard characters.
4.6.8.1 Retrieving information about Database, Tables, Columns,
and Indexes
You can use db_name.tbl_name as an alternative to the tbl_name FROM db_name syntax.
These two statements are equivalent:
mysql> SHOW INDEX FROM mytable FROM mydb;
mysql> SHOW INDEX FROM mydb.mytable;
SHOW DATABASES lists the databases on the MySQL server host. You can also get this list
using the mysqlshow command line tool. In version 4.0.2 you will only see those databases
for which you have some kind of privilege, if you don’t have the global SHOW DATABASES
privilege.
SHOW TABLES lists the tables in a given database. You can also get this list using the
mysqlshow db_name command.
Note: if a user doesn’t have any privileges for a table, the table will not show up in the
output from SHOW TABLES or mysqlshow db_name.
SHOW OPEN TABLES lists the tables that are currently open in the table cache. See Section 5.4.7 [Table cache], page 429. The Comment field tells how many times the table is
cached and in_use.
SHOW COLUMNS lists the columns in a given table. If you specify the FULL option, you will
also get the privileges you have for each column. If the column types are different from what
you expect them to be based on a CREATE TABLE statement, note that MySQL sometimes
changes column types. See Section 6.5.3.1 [Silent column changes], page 579. As of MySQL
4.1, the FULL keyword also causes any per-column comments to be displayed.
The DESCRIBE statement provides information similar to SHOW COLUMNS. See Section 6.6.2
[DESCRIBE], page 586.
Chapter 4: Database Administration
289
SHOW FIELDS is a synonym for SHOW COLUMNS, and SHOW KEYS is a synonym for SHOW INDEX.
You can also list a table’s columns or indexes with mysqlshow db_name tbl_name or
mysqlshow -k db_name tbl_name.
SHOW INDEX returns the index information in a format that closely resembles the
SQLStatistics call in ODBC. The following columns are returned:
Column
Table
Non_unique
Meaning
Name of the table.
0 if the index can’t contain duplicates, 1 if it
can.
Key_name
Name of the index.
Seq_in_
Column sequence number in index, starting
index
with 1.
Column_name Column name.
Collation
How the column is sorted in the index. In
MySQL, this can have values ‘A’ (Ascending)
or NULL (Not sorted).
Cardinality Number of unique values in the index. This is
updated by running isamchk -a.
Sub_part
Number of indexed characters if the column is
only partly indexed. NULL if the entire key is
indexed.
Null
Contains ’YES’ if the column may contain NULL.
Index_type
Index method used.
Comment
Various remarks. For now, it tells in MySQL <
4.0.2 whether index is FULLTEXT or not.
Note that as the Cardinality is counted based on statistics stored as integers, it’s not
necessarily accurate for small tables.
The Null and Index_type columns were added in MySQL 4.0.2.
4.6.8.2 SHOW TABLE STATUS
SHOW TABLE STATUS [FROM db_name] [LIKE wild]
SHOW TABLE STATUS (new in Version 3.23) works likes SHOW STATUS, but provides a lot of
information about each table. You can also get this list using the mysqlshow --status
db_name command. The following columns are returned:
Column
Name
Type
Row_format
Rows
Avg_row_length
Data_length
Max_data_length
Index_length
Meaning
Name of the table.
Type of table. See Chapter 7 [Table types], page 600.
The row storage format (Fixed, Dynamic, or Compressed).
Number of rows.
Average row length.
Length of the datafile.
Max length of the datafile. For fixed row formats, this is the
max number of rows in the table. For dynamic row formats,
this is the total number of data bytes that can be stored in
the table, given the data pointer size used.
Length of the index file.
290
MySQL Technical Reference for Version 4.1.1-alpha
Data_free
Auto_increment
Create_time
Update_time
Check_time
Collation
Checksum
Create_options
Comment
Number of allocated but not used bytes.
Next autoincrement value.
When the table was created.
When the datafile was last updated.
When the table was last checked.
Table’s character set and collation. (new 4.1.1)
Live checksum value (if any). (new in 4.1.1)
Extra options used with CREATE TABLE.
The comment used when creating the table (or some information why MySQL couldn’t access the table information).
InnoDB tables will report the free space in the tablespace in the table comment.
4.6.8.3 SHOW STATUS
SHOW STATUS provides server status information (like mysqladmin extended-status). The
output resembles that shown here, though the format and numbers probably differ:
+--------------------------+------------+
| Variable_name
| Value
|
+--------------------------+------------+
| Aborted_clients
| 0
|
| Aborted_connects
| 0
|
| Bytes_received
| 155372598 |
| Bytes_sent
| 1176560426 |
| Connections
| 30023
|
| Created_tmp_disk_tables | 0
|
| Created_tmp_tables
| 8340
|
| Created_tmp_files
| 60
|
| Delayed_insert_threads
| 0
|
| Delayed_writes
| 0
|
| Delayed_errors
| 0
|
| Flush_commands
| 1
|
| Handler_delete
| 462604
|
| Handler_read_first
| 105881
|
| Handler_read_key
| 27820558
|
| Handler_read_next
| 390681754 |
| Handler_read_prev
| 6022500
|
| Handler_read_rnd
| 30546748
|
| Handler_read_rnd_next
| 246216530 |
| Handler_update
| 16945404
|
| Handler_write
| 60356676
|
| Key_blocks_used
| 14955
|
| Key_read_requests
| 96854827
|
| Key_reads
| 162040
|
| Key_write_requests
| 7589728
|
| Key_writes
| 3813196
|
| Max_used_connections
| 0
|
Chapter 4: Database Administration
291
| Not_flushed_key_blocks
| 0
|
| Not_flushed_delayed_rows | 0
|
| Open_tables
| 1
|
| Open_files
| 2
|
| Open_streams
| 0
|
| Opened_tables
| 44600
|
| Questions
| 2026873
|
| Select_full_join
| 0
|
| Select_full_range_join
| 0
|
| Select_range
| 99646
|
| Select_range_check
| 0
|
| Select_scan
| 30802
|
| Slave_running
| OFF
|
| Slave_open_temp_tables
| 0
|
| Slow_launch_threads
| 0
|
| Slow_queries
| 0
|
| Sort_merge_passes
| 30
|
| Sort_range
| 500
|
| Sort_rows
| 30296250
|
| Sort_scan
| 4650
|
| Table_locks_immediate
| 1920382
|
| Table_locks_waited
| 0
|
| Threads_cached
| 0
|
| Threads_created
| 30022
|
| Threads_connected
| 1
|
| Threads_running
| 1
|
| Uptime
| 80380
|
+--------------------------+------------+
The status variables listed above have the following meaning:
Variable
Aborted_clients
Aborted_connects
Bytes_received
Bytes_sent
Com_xxx
Connections
Created_tmp_disk_
tables
Created_tmp_tables
Created_tmp_files
Delayed_insert_threads
Delayed_writes
Meaning
Number of connections aborted because the client died without closing the connection properly. See Section A.2.10 [Communication errors], page 864.
Number of tries to connect to the MySQL server that failed.
See Section A.2.10 [Communication errors], page 864.
Number of bytes received from all clients.
Number of bytes sent to all clients.
Number of times each xxx command has been executed.
Number of connection attempts to the MySQL server.
Number of implicit temporary tables on disk created while
executing statements.
Number of implicit temporary tables in memory created while
executing statements.
How many temporary files mysqld has created.
Number of delayed insert handler threads in use.
Number of rows written with INSERT DELAYED.
292
Delayed_errors
Flush_commands
Handler_commit
Handler_delete
Handler_read_first
Handler_read_key
Handler_read_next
Handler_read_prev
Handler_read_rnd
Handler_read_rnd_next
Handler_rollback
Handler_update
Handler_write
Key_blocks_used
Key_read_requests
Key_reads
Key_write_requests
Key_writes
Max_used_connections
Not_flushed_key_blocks
Not_flushed_delayed_
rows
Open_tables
Open_files
Open_streams
Opened_tables
Rpl_status
Select_full_join
Select_full_range_join
MySQL Technical Reference for Version 4.1.1-alpha
Number of rows written with INSERT DELAYED for which some
error occurred (probably duplicate key).
Number of executed FLUSH commands.
Number of internal COMMIT commands.
Number of times a row was deleted from a table.
Number of times the first entry was read from an index. If
this is high, it suggests that the server is doing a lot of full
index scans, for example, SELECT col1 FROM foo, assuming
that col1 is indexed.
Number of requests to read a row based on a key. If this is
high, it is a good indication that your queries and tables are
properly indexed.
Number of requests to read next row in key order. This will
be incremented if you are querying an index column with a
range constraint. This also will be incremented if you are
doing an index scan.
Number of requests to read previous row in key order. This
is mainly used to optimise ORDER BY ... DESC.
Number of requests to read a row based on a fixed position.
This will be high if you are doing a lot of queries that require
sorting of the result.
Number of requests to read the next row in the datafile. This
will be high if you are doing a lot of table scans. Generally
this suggests that your tables are not properly indexed or that
your queries are not written to take advantage of the indexes
you have.
Number of internal ROLLBACK commands.
Number of requests to update a row in a table.
Number of requests to insert a row in a table.
The number of used blocks in the key cache.
The number of requests to read a key block from the cache.
The number of physical reads of a key block from disk.
The number of requests to write a key block to the cache.
The number of physical writes of a key block to disk.
The maximum number of connections in use simultaneously.
Keys blocks in the key cache that has changed but hasn’t yet
been flushed to disk.
Number of rows waiting to be written in INSERT DELAY
queues.
Number of tables that are open.
Number of files that are open.
Number of streams that are open (used mainly for logging).
Number of tables that have been opened.
Status of failsafe replication. (Not yet in use).
Number of joins without keys (If this is not 0, you should
carefully check the indexes of your tables).
Number of joins where we used a range search on reference
table.
Chapter 4: Database Administration
Select_range
Select_scan
Select_range_check
Questions
Slave_open_temp_tables
Slave_running
Slow_launch_threads
Slow_queries
Sort_merge_passes
Sort_range
Sort_rows
Sort_scan
ssl_xxx
Table_locks_immediate
Table_locks_waited
Threads_cached
Threads_connected
Threads_created
Threads_running
Uptime
293
Number of joins where we used ranges on the first table. (It’s
normally not critical even if this is big.)
Number of joins where we did a full scan of the first table.
Number of joins without keys where we check for key usage
after each row (If this is not 0, you should carefully check the
indexes of your tables).
Number of queries sent to the server.
Number of temporary tables currently open by the slave
thread
Is ON if this is a slave that is connected to a master.
Number of threads that have taken more than slow_launch_
time to create.
Number of queries that have taken more than long_query_
time seconds. See Section 4.10.5 [Slow query log], page 359.
Number of merges passes the sort algoritm have had to do.
If this value is large you should consider increasing sort_
buffer.
Number of sorts that were done with ranges.
Number of sorted rows.
Number of sorts that were done by scanning the table.
Variables used by SSL; Not yet implemented.
Number of times a table lock was acquired immediately.
Available after 3.23.33.
Number of times a table lock could not be acquired immediately and a wait was needed. If this is high, and you have
performance problems, you should first optimise your queries,
and then either split your table or tables or use replication.
Available after 3.23.33.
Number of threads in the thread cache.
Number of currently open connections.
Number of threads created to handle connections.
Number of threads that are not sleeping.
How many seconds the server has been up.
Some comments about the above:
• If Opened_tables is big, then your table_cache variable is probably too small.
• If Key_reads is big, then your key_buffer_size variable is probably too small. The
cache miss rate can be calculated with Key_reads/Key_read_requests.
• If Handler_read_rnd is big, then you probably have a lot of queries that require MySQL
to scan whole tables or you have joins that don’t use keys properly.
• If Threads_created is big, you may want to increase the thread_cache_size variable.
The cache hit rate can be calculated with Threads_created/Connections.
• If Created_tmp_disk_tables is big, you may want to increase the tmp_table_size
variable to get the temporary tables memory-based instead of disk based.
4.6.8.4 SHOW VARIABLES
SHOW [GLOBAL | SESSION] VARIABLES [LIKE wild]
294
MySQL Technical Reference for Version 4.1.1-alpha
SHOW VARIABLES shows the values of some MySQL system variables. The options GLOBAL
and SESSION are new in MySQL 4.0.3. With GLOBAL you will get the variables that will
be used for new connections to MySQL. With SESSION you will get the values that are in
effect for the current connection. If you are not using either option, SESSION is used.
If the default values are unsuitable, you can set most of these variables using command-line
options when mysqld starts up. See Section 4.1.1 [Command-line options], page 198. It
is also possible to change most variables with the SET statement. See Section 5.5.6 [SET],
page 437.
The output from SHOW VARIABLES resembles that shown in the following list, though the
format and numbers may differ somewhat. You can also get this information using the
mysqladmin variables command.
+---------------------------------+------------------------------+
| Variable_name
| Value
|
+---------------------------------+------------------------------|
| back_log
| 50
|
| basedir
| /usr/local/mysql
|
| bdb_cache_size
| 8388572
|
| bdb_log_buffer_size
| 32768
|
| bdb_home
| /usr/local/mysql
|
| bdb_max_lock
| 10000
|
| bdb_logdir
|
|
| bdb_shared_data
| OFF
|
| bdb_tmpdir
| /tmp/
|
| bdb_version
| Sleepycat Software: ...
|
| binlog_cache_size
| 32768
|
| bulk_insert_buffer_size
| 8388608
|
| character_set
| latin1
|
| character_sets
| latin1 big5 czech euc_kr
|
| concurrent_insert
| ON
|
| connect_timeout
| 5
|
| convert_character_set
|
|
| datadir
| /usr/local/mysql/data/
|
| delay_key_write
| ON
|
| delayed_insert_limit
| 100
|
| delayed_insert_timeout
| 300
|
| delayed_queue_size
| 1000
|
| flush
| OFF
|
| flush_time
| 0
|
| ft_boolean_syntax
| + -><()~*:""&|
|
| ft_min_word_len
| 4
|
| ft_max_word_len
| 84
|
| ft_query_expansion_limit
| 20
|
| ft_stopword_file
| (built-in)
|
| have_bdb
| YES
|
| have_innodb
| YES
|
| have_isam
| YES
|
Chapter 4: Database Administration
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
have_raid
have_symlink
have_openssl
have_query_cache
init_file
innodb_additional_mem_pool_size
innodb_buffer_pool_size
innodb_data_file_path
innodb_data_home_dir
innodb_file_io_threads
innodb_force_recovery
innodb_thread_concurrency
innodb_flush_log_at_trx_commit
innodb_fast_shutdown
innodb_flush_method
innodb_lock_wait_timeout
innodb_log_arch_dir
innodb_log_archive
innodb_log_buffer_size
innodb_log_file_size
innodb_log_files_in_group
innodb_log_group_home_dir
innodb_mirrored_log_groups
interactive_timeout
join_buffer_size
key_buffer_size
language
large_files_support
local_infile
locked_in_memory
log
log_update
log_bin
log_slave_updates
log_slow_queries
log_warnings
long_query_time
low_priority_updates
lower_case_table_names
max_allowed_packet
max_binlog_cache_size
max_binlog_size
max_connections
max_connect_errors
max_delayed_threads
max_heap_table_size
max_join_size
295
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
NO
DISABLED
YES
YES
1048576
8388608
ibdata1:10M:autoextend
4
0
8
1
ON
50
OFF
1048576
5242880
2
./
1
28800
131072
16773120
/usr/local/mysql/share/...
ON
ON
OFF
OFF
OFF
OFF
OFF
OFF
OFF
10
OFF
OFF
1047552
4294967295
1073741824
100
10
20
16777216
4294967295
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
296
MySQL Technical Reference for Version 4.1.1-alpha
| max_relay_log_size
| 0
|
| max_sort_length
| 1024
|
| max_user_connections
| 0
|
| max_tmp_tables
| 32
|
| max_write_lock_count
| 4294967295
|
| myisam_max_extra_sort_file_size | 268435456
|
| myisam_repair_threads
| 1
|
| myisam_max_sort_file_size
| 2147483647
|
| myisam_recover_options
| force
|
| myisam_sort_buffer_size
| 8388608
|
| net_buffer_length
| 16384
|
| net_read_timeout
| 30
|
| net_retry_count
| 10
|
| net_write_timeout
| 60
|
| open_files_limit
| 1024
|
| pid_file
| /usr/local/mysql/name.pid
|
| port
| 3306
|
| protocol_version
| 10
|
| query_cache_limit
| 1048576
|
| query_cache_size
| 0
|
| query_cache_type
| ON
|
| read_buffer_size
| 131072
|
| read_rnd_buffer_size
| 262144
|
| rpl_recovery_rank
| 0
|
| safe_show_database
| OFF
|
| server_id
| 0
|
| slave_net_timeout
| 3600
|
| skip_external_locking
| ON
|
| skip_networking
| OFF
|
| skip_show_database
| OFF
|
| slow_launch_time
| 2
|
| socket
| /tmp/mysql.sock
|
| sort_buffer_size
| 2097116
|
| sql_mode
|
|
| table_cache
| 64
|
| table_type
| MYISAM
|
| thread_cache_size
| 3
|
| thread_stack
| 131072
|
| tx_isolation
| READ-COMMITTED
|
| timezone
| EEST
|
| tmp_table_size
| 33554432
|
| tmpdir
| /tmp/:/mnt/hd2/tmp/
|
| version
| 4.0.4-beta
|
| wait_timeout
| 28800
|
+---------------------------------+------------------------------+
Chapter 4: Database Administration
297
Each option is described here. Values for buffer sizes, lengths, and stack sizes are given in
bytes. You can specify values with a suffix of ‘K’ or ‘M’ to indicate kilobytes or megabytes.
For example, 16M indicates 16 megabytes. The case of suffix letters does not matter; 16M
and 16m are equivalent:
• ansi_mode. Is ON if mysqld was started with --ansi. See Section 1.8.2 [ANSI mode],
page 40.
• back_log The number of outstanding connection requests MySQL can have. This
comes into play when the main MySQL thread gets very many connection requests in
a very short time. It then takes some time (although very little) for the main thread
to check the connection and start a new thread. The back_log value indicates how
many requests can be stacked during this short time before MySQL momentarily stops
answering new requests. You need to increase this only if you expect a large number
of connections in a short period of time.
In other words, this value is the size of the listen queue for incoming TCP/IP connections. Your operating system has its own limit on the size of this queue. The manual
page for the Unix listen(2) system call should have more details. Check your OS
documentation for the maximum value for this variable. Attempting to set back_log
higher than your operating system limit will be ineffective.
• basedir The value of the --basedir option.
• bdb_cache_size The buffer that is allocated to cache index and rows for BDB tables.
If you don’t use BDB tables, you should start mysqld with --skip-bdb to not waste
memory for this cache.
• bdb_log_buffer_size The buffer that is allocated to cache index and rows for BDB
tables. If you don’t use BDB tables, you should set this to 0 or start mysqld with
--skip-bdb to not waste memory for this cache.
• bdb_home The value of the --bdb-home option.
• bdb_max_lock The maximum number of locks (10,000 by default) you can have active on a BDB table. You should increase this if you get errors of type bdb: Lock
table is out of available locks or Got error 12 from ... when you have do long
transactions or when mysqld has to examine a lot of rows to calculate the query.
• bdb_logdir The value of the --bdb-logdir option.
• bdb_shared_data Is ON if you are using --bdb-shared-data.
• bdb_tmpdir The value of the --bdb-tmpdir option.
• binlog_cache_size. The size of the cache to hold the SQL statements for the binary
log during a transaction. If you often use big, multi-statement transactions you can
increase this to get more performance. See Section 6.7.1 [COMMIT], page 586.
• bulk_insert_buffer_size (was myisam_bulk_insert_tree_size) MyISAM uses
special tree-like cache to make bulk inserts (that is, INSERT ... SELECT, INSERT ...
VALUES (...), (...), ..., and LOAD DATA INFILE) faster. This variable limits the
size of the cache tree in bytes per thread. Setting it to 0 will disable this optimisation.
Note: this cache is only used when adding data to non-empty table. Default value is
8 MB.
• character_set The default character set.
• character_sets The supported character sets.
298
MySQL Technical Reference for Version 4.1.1-alpha
• concurrent_inserts If ON (the default), MySQL will allow you to use INSERT on
MyISAM tables at the same time as you run SELECT queries on them. You can turn this
option off by starting mysqld with --safe or --skip-new.
• connect_timeout The number of seconds the mysqld server is waiting for a connect
packet before responding with Bad handshake.
• datadir The value of the --datadir option.
• delay_key_write Option for MyISAM tables. Can have one of the following values:
OFF
All CREATE TABLE ... DELAYED_KEY_WRITE are ignored.
ON
(default) MySQL will honor the DELAY_KEY_WRITE option for
CREATE TABLE.
ALL
All new opened tables are treated as if they were created with
the DELAY_KEY_WRITE option.
If DELAY_KEY_WRITE is enabled this means that the key buffer for tables with this option
will not get flushed on every index update, but only when a table is closed. This will
speed up writes on keys a lot, but you should add automatic checking of all tables with
myisamchk --fast --force if you use this.
• delayed_insert_limit After inserting delayed_insert_limit rows, the INSERT
DELAYED handler will check if there are any SELECT statements pending. If so, it
allows these to execute before continuing.
• delayed_insert_timeout How long a INSERT DELAYED thread should wait for INSERT
statements before terminating.
• delayed_queue_size What size queue (in rows) should be allocated for handling
INSERT DELAYED. If the queue becomes full, any client that does INSERT DELAYED will
wait until there is room in the queue again.
• flush This is ON if you have started MySQL with the --flush option.
• flush_time If this is set to a non-zero value, then every flush_time seconds all tables will be closed (to free up resources and sync unflushed data to disk). We only
recommend this option on Windows 9x/Me, or on systems where you have very little
resources.
• ft_boolean_syntax List of operators supported by MATCH ... AGAINST(... IN
BOOLEAN MODE). See Section 6.8 [Fulltext Search], page 590.
• ft_min_word_len The minimum length of the word to be included in a FULLTEXT
index. Note: FULLTEXT indexes must be rebuilt after changing this variable. (This
option is new for MySQL 4.0.)
• ft_max_word_len The maximum length of the word to be included in a FULLTEXT
index. Note: FULLTEXT indexes must be rebuilt after changing this variable. (This
option is new for MySQL 4.0.)
• ft_query_expansion_limit Number of top matches to use for query expansion (in
MATCH ... AGAINST (... WITH QUERY EXPANSION). (This option is new for MySQL
4.1.1)
• ft_stopword_file The file from which to read the list of stopwords for full-text
searches. All the words from the file will be used; comments are not honored. By
default, built-in list of stopwords is used (as defined in ‘myisam/ft_static.c’). Setting this parameter to an empty string ("") will disable stopword filtering. Note:
Chapter 4: Database Administration
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
299
FULLTEXT indexes must be rebuilt after changing this variable. (This option is new for
MySQL 4.0.10)
have_innodb YES if mysqld supports InnoDB tables. DISABLED if --skip-innodb is
used.
have_bdb YES if mysqld supports Berkeley DB tables. DISABLED if --skip-bdb is used.
have_raid YES if mysqld supports the RAID option.
have_openssl YES if mysqld supports SSL (encryption) on the client/server protocol.
init_file The name of the file specified with the --init-file option when you start
the server. This is a file of SQL statements you want the server to execute when it
starts.
interactive_timeout The number of seconds the server waits for activity on an interactive connection before closing it. An interactive client is defined as a client that uses
the CLIENT_INTERACTIVE option to mysql_real_connect(). See also wait_timeout.
join_buffer_size The size of the buffer that is used for full joins (joins that do not use
indexes). The buffer is allocated one time for each full join between two tables. Increase
this value to get a faster full join when adding indexes is not possible. (Normally the
best way to get fast joins is to add indexes.)
key_buffer_size Index blocks are buffered and are shared by all threads. key_
buffer_size is the size of the buffer used for index blocks.
Increase this to get better index handling (for all reads and multiple writes) to as
much as you can afford; 64M on a 256M machine that mainly runs MySQL is quite
common. If you, however, make this too big (for instance more than 50% of your total
memory) your system may start to page and become extremely slow. Remember that
because MySQL does not cache data reads, you will have to leave some room for the
OS filesystem cache.
You can check the performance of the key buffer by doing SHOW STATUS and examine the variables Key_read_requests, Key_reads, Key_write_requests, and Key_
writes. The Key_reads/Key_read_request ratio should normally be < 0.01. The Key_
write/Key_write_requests is usually near 1 if you are using mostly updates/deletes
but may be much smaller if you tend to do updates that affect many at the same time
or if you are using DELAY_KEY_WRITE. See Section 4.6.8 [SHOW], page 287.
To get even more speed when writing many rows at the same time, use LOCK TABLES.
See Section 6.7.5 [LOCK TABLES], page 588.
language The language used for error messages.
large_file_support If mysqld was compiled with options for big file support.
locked_in_memory If mysqld was locked in memory with --memlock
log If logging of all queries is enabled.
log_update If the update log is enabled.
log_bin If the binary log is enabled.
log_slave_updates If the updates from the slave should be logged.
long_query_time If a query takes longer than this (in seconds), the Slow_queries
counter will be incremented. If you are using --log-slow-queries, the query will be
logged to the slow query logfile. This value is measured in real time, not CPU time, so
300
•
•
•
•
•
•
•
•
•
•
MySQL Technical Reference for Version 4.1.1-alpha
a query that may be under the threshold on a lightly loaded system may be above the
threshold on a heavily loaded one. See Section 4.10.5 [Slow query log], page 359.
lower_case_table_names If set to 1 table names are stored in lowercase on disk and
table name comparisons will be case-insensitive. From version 4.0.2, this option also
applies to database names. From 4.1.1 this option also applies to table alias. See
Section 6.1.3 [Name case sensitivity], page 450.
max_allowed_packet The maximum size of one packet. The message buffer is initialised to net_buffer_length bytes, but can grow up to max_allowed_packet bytes
when needed. This value by default is small, to catch big (possibly wrong) packets.
You must increase this value if you are using big BLOB columns. It should be as big
as the biggest BLOB you want to use. The protocol limits for max_allowed_packet is
16M in MySQL 3.23 and 1G in MySQL 4.0.
max_binlog_cache_size If a multi-statement transaction requires more than this
amount of memory, one will get the error "Multi-statement transaction required more
than ’max binlog cache size’ bytes of storage".
max_binlog_size Available after 3.23.33. If a write to the binary (replication) log
exceeds the given value, rotate the logs. You cannot set it to less than 4096 bytes
(1024 in MySQL versions older than 4.0.14), or more than 1 GB. Default is 1 GB.
Note if you are using transactions: a transaction is written in one chunk to the binary
log, hence it is never split between several binary logs. Therefore, if you have big
transactions, you may see binlogs bigger than max_binlog_size. If max_relay_log_
size (available starting from MySQL 4.0.14) is 0, then max_binlog_size will apply
to relay logs as well.
max_connections The number of simultaneous clients allowed. Increasing this value
increases the number of file descriptors that mysqld requires. See below for comments
on file descriptor limits. See Section A.2.6 [Too many connections], page 862.
max_connect_errors If there is more than this number of interrupted connections from
a host this host will be blocked from further connections. You can unblock a host with
the command FLUSH HOSTS.
max_delayed_threads Don’t start more than this number of threads to handle INSERT
DELAYED statements. If you try to insert data into a new table after all INSERT DELAYED
threads are in use, the row will be inserted as if the DELAYED attribute wasn’t specified.
If you set this to 0, MySQL will never create a max delayed thread.
max_heap_table_size This variable sets the maximum size to which subsequently
created HEAP tables are allowed to grow. The value of the variable is used to calculate
a HEAP table’s MAX_ROWS value. Setting this variable has no effect on any existing HEAP
table, unless the table is recreated with a statement such as CREATE TABLE or TRUNCATE
TABLE, or altered with ALTER TABLE.
max_join_size Joins that are probably going to read more than max_join_size
records return an error. Set this value if your users tend to perform joins that lack a
WHERE clause, that take a long time, and that return millions of rows.
max_relay_log_size Available starting from 4.0.14. If a write to the relay log (a
kind of log used by replication slaves, see Section 4.11.3 [Replication Implementation
Details], page 362) exceeds the given value, rotate the relay log. This variable enables
you to put different size constraints on relay logs and binary logs. However, setting the
Chapter 4: Database Administration
301
variable to 0 will make MySQL use max_binlog_size for both binary logs and relay
logs. You have to set max_relay_log_size to 0 or more than 4096, and less than 1
GB. Default is 0.
• max_seeks_for_key Limit assumed max number of seeks when looking up rows based
on a key. The MySQL optimiser will assume that when searching after matching rows
in a table through scanning a key, we will not cause more than this number of key seeks
independent of the cardinality of the key. By setting this to a low value (100 ?) you
can force MySQL to prefer keys instead of table scans.
• max_sort_length The number of bytes to use when sorting BLOB or TEXT values (only
the first max_sort_length bytes of each value are used; the rest are ignored).
• max_user_connections The maximum number of active connections for a single user
(0 = no limit).
• max_tmp_tables (This option doesn’t yet do anything.) Maximum number of temporary tables a client can keep open at the same time.
• max_write_lock_count After this many write locks, allow some read locks to run in
between.
• myisam_recover_options The value of the --myisam-recover option.
• myisam_sort_buffer_size The buffer that is allocated when sorting the index when
doing a REPAIR or when creating indexes with CREATE INDEX or ALTER TABLE.
• myisam_max_extra_sort_file_size. If the temporary file used for fast index creation
would be bigger than using the key cache by the amount specified here, then prefer the
key cache method. This is mainly used to force long character keys in large tables to
use the slower key cache method to create the index. Note that this parameter is given
in megabytes before 4.0.3 and in bytes beginning with this version.
• myisam_repair_threads. If this value is greater than one, MyISAM table indexes
during Repair by sorting process will be created in parallel - each index in its own
thread. Note: multi-threaded repair is still alpha quality code.
• myisam_max_sort_file_size The maximum size of the temporary file MySQL is allowed to use while recreating the index (during REPAIR, ALTER TABLE or LOAD DATA
INFILE. If the file-size would be bigger than this, the index will be created through
the key cache (which is slower). Note that this parameter is given in megabytes before
4.0.3 and in bytes beginning with this version.
• net_buffer_length The communication buffer is reset to this size between queries.
This should not normally be changed, but if you have very little memory, you can set
it to the expected size of a query. (That is, the expected length of SQL statements
sent by clients. If statements exceed this length, the buffer is automatically enlarged,
up to max_allowed_packet bytes.)
• net_read_timeout Number of seconds to wait for more data from a connection before
aborting the read. Note that when we don’t expect data from a connection, the timeout
is defined by write_timeout. See also slave_net_timeout.
• net_retry_count If a read on a communication port is interrupted, retry this many
times before giving up. This value should be quite high on FreeBSD as internal interrupts are sent to all threads.
302
MySQL Technical Reference for Version 4.1.1-alpha
• net_write_timeout Number of seconds to wait for a block to be written to a connection
before aborting the write.
• open_files_limit Number of files the system allows mysqld to open. This is the real
value given for the system and may be different from the value you gave mysqld as a
startup parameter. This is 0 on systems where MySQL can’t change the number of
open files.
• pid_file The value of the --pid-file option.
• port The value of the --port option.
• protocol_version The protocol version used by the MySQL server.
• range_alloc_block_size Size of blocks that are allocated when doing range optimization.
• read_buffer_size (was record_buffer) Each thread that does a sequential scan allocates a buffer of this size for each table it scans. If you do many sequential scans,
you may want to increase this value.
• read_rnd_buffer_size (was record_rnd_buffer) When reading rows in sorted order
after a sort, the rows are read through this buffer to avoid a disk seeks. Can improve
ORDER BY by a lot if set to a high value. As this is a thread-specific variable, one should
not set this big globally, but just change this when running some specific big queries.
• query_alloc_block_size Size of memory allocation blocks that are allocated for objects created during query parsing and execution. If you have problem with memory
fragmentation it may help increasing this a bit.
• query_cache_limit Don’t cache results that are bigger than this. (Default 1M).
• query_cache_size The memory allocated to store results from old queries. If this is
0, the query cache is disabled (default).
• query_cache_type This may be set (only numeric) to
Value
0
1
2
Alias
OFF
ON
DEMAND
Comment
Don’t cache or retrieve results.
Cache all results except SELECT SQL_NO_CACHE ... queries.
Cache only SELECT SQL_CACHE ... queries.
• query_prealloc_size Persistent buffer for query parsing and execution. This one is
not freed between queries. In theory, by making this “big enough”, make MySQL run
queries without having to do a single malloc() call.
• safe_show_database Don’t show databases for which the user doesn’t have
any database or table privileges. This can improve security if you’re concerned
about people being able to see what databases other users have.
See also
skip_show_database.
• server_id The value of the --server-id option.
• skip_locking Is OFF if mysqld uses external locking.
• skip_networking Is ON if we only allow local (socket) connections.
• skip_show_database This prevents people from doing SHOW DATABASES if they don’t
have the PROCESS privilege. This can improve security if you’re concerned about people
being able to see what databases other users have. See also safe_show_database.
Chapter 4: Database Administration
303
• slave_net_timeout Number of seconds to wait for more data from a master/slave
connection before aborting the read.
• slow_launch_time If creating the thread takes longer than this value (in seconds), the
Slow_launch_threads counter will be incremented.
• socket The Unix socket used by the server.
• sort_buffer_size Each thread that needs to do a sort allocates a buffer of this size.
Increase this value for faster ORDER BY or GROUP BY operations. See Section A.4.4 [Temporary files], page 874.
• table_cache The number of open tables for all threads. Increasing this value increases
the number of file descriptors that mysqld requires. You can check if you need to
increase the table cache by checking the Opened_tables variable. See Section 4.6.8.3
[Opened_tables], page 290. If this variable is big and you don’t do FLUSH TABLES a
lot (which just forces all tables to be closed and reopenend), then you should increase
the value of this variable.
For more information about the table cache, see Section 5.4.7 [Table cache], page 429.
• table_type The default table type.
• thread_cache_size How many threads we should keep in a cache for reuse. When a
client disconnects, the client’s threads are put in the cache if there aren’t more than
thread_cache_size threads from before. All new threads are first taken from the
cache, and only when the cache is empty is a new thread created. This variable can be
increased to improve performance if you have a lot of new connections. (Normally this
doesn’t give a notable performance improvement if you have a good thread implementation.) By examing the difference between the Connections and Threads_created
status variables (see Section 4.6.8.3 [SHOW STATUS], page 290 for details) you can see
how efficient thread cache is.
• thread_concurrency On Solaris, mysqld will call thr_setconcurrency() with this
value. thr_setconcurrency() permits the application to give the threads system a
hint for the desired number of threads that should be run at the same time.
• thread_stack The stack size for each thread. Many of the limits detected by the
crash-me test are dependent on this value. The default is large enough for normal
operation. See Section 5.1.4 [MySQL Benchmarks], page 401.
• timezone The timezone for the server.
• tmp_table_size If an in-memory temporary table exceeds this size, MySQL will automatically convert it to an on-disk MyISAM table. Increase the value of tmp_table_size
if you do many advanced GROUP BY queries and you have lots of memory.
• tmpdir The directory used for temporary files and temporary tables. Starting from
MySQL 4.1, it can be set to a list of paths separated by colon : (semicolon ; on
Windows). They will be used in round-robin fashion. This feature can be used to
spread load between several physical disks. It is possible to set tmpdir to point to
a memory-based filesystem, except if the MySQL server is a slave. If it is a slave, it
needs some of its temporary files (for replication of temporary tables or of LOAD DATA
INFILE) to survive a machine’s reboot, so a memory-based tmpdir which is cleared
when the machine reboots is not suitable; a disk-based tmpdir is necessary.
304
MySQL Technical Reference for Version 4.1.1-alpha
• transaction_alloc_block_size Size of memory allocation blocks that are allocated
for storing queries that are part of a transaction that are to be stored in the binary log
when doing a commit.
• transaction_prealloc_block_size Persistent buffer for transaction_alloc_
blocks. that are not freed between queries. By making this “big enough” to fit all
queries in a common transaction you can avoid a lot of malloc() calls.
• version The version number for the server.
• wait_timeout The number of seconds the server waits for activity on a not interactive
connection before closing it.
On thread startup SESSION.WAIT_TIMEOUT is initialised from GLOBAL.WAIT_TIMEOUT
or GLOBAL.INTERACTIVE_TIMEOUT depending on the type of client (as defined by the
CLIENT_INTERACTIVE connect option). See also interactive_timeout.
The manual section that describes tuning MySQL contains some information of how to tune
the above variables. See Section 5.5.2 [Server parameters], page 431.
4.6.8.5 SHOW [BDB] LOGS
SHOW LOGS shows you status information about existing log files. It currently only displays
information about Berkeley DB log files, so an alias for it (available as of MySQL 4.1.1) is
SHOW BDB LOGS.
• File shows the full path to the log file
• Type shows the type of the log file (BDB for Berkeley DB log files)
• Status shows the status of the log file (FREE if the file can be removed, or IN USE if
the file is needed by the transaction subsystem)
4.6.8.6 SHOW PROCESSLIST
SHOW [FULL] PROCESSLIST shows you which threads are running. You can also get this
information using the mysqladmin processlist command. If you have the SUPER privilege,
you can see all threads. Otherwise, you can see only your own threads. See Section 4.6.7
[KILL], page 287. If you don’t use the FULL option, then only the first 100 characters of
each query will be shown.
Starting from 4.0.12, MySQL reports the hostname for TCP/IP connections in
hostname:client_port format to make it easier to find out which client is doing what.
This command is very useful if you get the ’too many connections’ error message and want
to find out what’s going on. MySQL reserves one extra connection for a client with the
SUPER privilege to ensure that you should always be able to login and check the system
(assuming you are not giving this privilege to all your users).
Some states commonly seen in mysqladmin processlist
• Checking table The thread is performing [automatic] checking of the table.
• Closing tables Means that the thread is flushing the changed table data to disk and
closing the used tables. This should be a fast operation. If not, then you should check
that you don’t have a full disk or that the disk is not in very heavy use.
Chapter 4: Database Administration
305
• Connect Out Slave connecting to master.
• Copying to tmp table on disk The temporary result set was larger than tmp_table_
size and the thread is now changing the in memory-based temporary table to a disk
based one to save memory.
• Creating tmp table The thread is creating a temporary table to hold a part of the
result for the query.
• deleting from main table When executing the first part of a multiple-table delete
and we are only deleting from the first table.
• deleting from reference tables When executing the second part of a multiple-table
delete and we are deleting the matched rows from the other tables.
• Flushing tables The thread is executing FLUSH TABLES and is waiting for all threads
to close their tables.
• Killed Someone has sent a kill to the thread and it should abort next time it checks
the kill flag. The flag is checked in each major loop in MySQL, but in some cases it
may still take a short time for the thread to die. If the thread is locked by some other
thread, the kill will take effect as soon as the other thread releases its lock.
• Sending data The thread is processing rows for a SELECT statement and is also sending
data to the client.
• Sorting for group The thread is doing a sort to satisfy a GROUP BY.
• Sorting for order The thread is doing a sort to satisfy a ORDER BY.
• Opening tables This simply means that the thread is trying to open a table. This
is should be very fast procedure, unless something prevents opening. For example
an ALTER TABLE or a LOCK TABLE can prevent opening a table until the command is
finished.
• Removing duplicates The query was using SELECT DISTINCT in such a way that
MySQL couldn’t optimise that distinct away at an early stage. Because of this MySQL
has to do an extra stage to remove all duplicated rows before sending the result to the
client.
• Reopen table The thread got a lock for the table, but noticed after getting the lock
that the underlying table structure changed. It has freed the lock, closed the table and
is now trying to reopen it.
• Repair by sorting The repair code is using sorting to create indexes.
• Repair with keycache The repair code is using creating keys one by one through the
key cache. This is much slower than Repair by sorting.
• Searching rows for update The thread is doing a first phase to find all matching rows
before updating them. This has to be done if the UPDATE is changing the index that is
used to find the involved rows.
• Sleeping The thread is wating for the client to send a new command to it.
• System lock The thread is waiting for getting to get a external system lock for the
table. If you are not using multiple mysqld servers that are accessing the same tables,
you can disable system locks with the --skip-external-locking option.
• Upgrading lock The INSERT DELAYED handler is trying to get a lock for the table to
insert rows.
306
MySQL Technical Reference for Version 4.1.1-alpha
• Updating The thread is searching for rows to update and updating them.
• User Lock The thread is waiting on a GET_LOCK().
• Waiting for tables The thread got a notification that the underlying structure for a
table has changed and it needs to reopen the table to get the new structure. To be
able to reopen the table it must however wait until all other threads have closed the
table in question.
This notification happens if another thread has used FLUSH TABLES or one of the following commands on the table in question: FLUSH TABLES table_name, ALTER TABLE,
RENAME TABLE, REPAIR TABLE, ANALYZE TABLE or OPTIMIZE TABLE.
• waiting for handler insert The INSERT DELAYED handler has processed all inserts
and are waiting to get new ones.
Most states are very quick operations. If threads last in any of these states for many seconds,
there may be a problem around that needs to be investigated.
There are some other states that are not mentioned previously, but most of these are only
useful to find bugs in mysqld.
4.6.8.7 SHOW GRANTS
SHOW GRANTS FOR user lists the grant commands that must be issued to duplicate the grants
for a user.
mysql> SHOW GRANTS FOR [email protected];
+---------------------------------------------------------------------+
| Grants for [email protected]
|
+---------------------------------------------------------------------+
| GRANT ALL PRIVILEGES ON *.* TO ’root’@’localhost’ WITH GRANT OPTION |
+---------------------------------------------------------------------+
To list grants for the current session one may use CURRENT_USER() function (new in version
4.0.6) to find out what user the session was authenticated as. See Section 6.3.6.2 [CURRENT_
USER()], page 521.
4.6.8.8 SHOW CREATE TABLE
Shows a CREATE TABLE statement that will create the given table:
mysql> SHOW CREATE TABLE t\G
*************************** 1. row ***************************
Table: t
Create Table: CREATE TABLE t (
id INT(11) default NULL auto_increment,
s char(60) default NULL,
PRIMARY KEY (id)
) TYPE=MyISAM
SHOW CREATE TABLE quotes table and column names according to the value of the SQL_
QUOTE_SHOW_CREATE option. Section 5.5.6 [SET SQL_QUOTE_SHOW_CREATE], page 437.
Chapter 4: Database Administration
307
4.6.8.9 SHOW WARNINGS | ERRORS
SHOW WARNINGS [LIMIT row_count]
SHOW ERRORS [LIMIT row_count]
This command is implemented in MySQL 4.1.0.
It shows the errors, warnings and notes that one got for the last command. The errors/warnings are reset for each new command that uses a table.
The MySQL server sends back the total number of warnings and errors you got for the last
commend; This can be retrieved by calling mysql_warning_count().
Up to max_error_count messages are stored (Global and thread specific variable).
You can retrieve the number of errors from @error_count and warnings from @warning_
count.
SHOW WARNINGS shows all errors, warnings and notes you got for the last command while
SHOW ERRORS only shows you the errors.
mysql> DROP TABLE IF EXISTS no_such_table;
mysql> SHOW WARNINGS;
+-------+------+-------------------------------+
| Level | Code | Message
|
+-------+------+-------------------------------+
| Note | 1051 | Unknown table ’no_such_table’ |
+-------+------+-------------------------------+
Note that in MySQL 4.1.0 we have just added the frame work for warnings and not many
MySQL command do yet generate warnings. 4.1.1 supports all kind of warnings for LOAD
DATA INFILE and DML statements such as INSERT, UPDATE and ALTER commands.
For example, here is a simple case which produces conversion warnings for a insert statement.
mysql> create table t1(a tinyint NOT NULL, b char(4));
Query OK, 0 rows affected (0.00 sec)
mysql> insert into t1 values(10,’mysql’),(NULL,’test’),(300,’open source’);
Query OK, 3 rows affected, 4 warnings (0.15 sec)
Records: 3 Duplicates: 0 Warnings: 4
mysql> show warnings;
+---------+------+---------------------------------------------------------------+
| Level
| Code | Message
|
+---------+------+---------------------------------------------------------------+
| Warning | 1263 | Data truncated for column ’b’ at row 1
|
| Warning | 1261 | Data truncated, NULL supplied to NOT NULL column ’a’ at row 2 |
| Warning | 1262 | Data truncated, out of range for column ’a’ at row 3
|
| Warning | 1263 | Data truncated for column ’b’ at row 3
|
+---------+------+---------------------------------------------------------------+
4 rows in set (0.00 sec)
Maximum number of warnings can be specified using the server variable ’max_error_
count’, SET max_error_count=[count]; By default it is 64. In case to disable warnings,
308
MySQL Technical Reference for Version 4.1.1-alpha
simply reset this variable to ’0’. In case if max_error_count is 0, then still the warning
count represents how many warnings have occurred, but none of the messages are stored.
For example, consider the following ALTER table statement for the above example, which
returns only one warning message even though total warnings occurred is 3 when you set
max error count=1.
mysql> show variables like ’max_error_count’;
+-----------------+-------+
| Variable_name
| Value |
+-----------------+-------+
| max_error_count | 64
|
+-----------------+-------+
1 row in set (0.00 sec)
mysql> set max_error_count=1;
Query OK, 0 rows affected (0.00 sec)
mysql> alter table t1 modify b char;
Query OK, 3 rows affected, 3 warnings (0.00 sec)
Records: 3 Duplicates: 0 Warnings: 3
mysql> show warnings;
+---------+------+----------------------------------------+
| Level
| Code | Message
|
+---------+------+----------------------------------------+
| Warning | 1263 | Data truncated for column ’b’ at row 1 |
+---------+------+----------------------------------------+
1 row in set (0.00 sec)
mysql>
4.6.8.10 SHOW TABLE TYPES
SHOW TABLE TYPES
This command is implemented in MySQL 4.1.0.
SHOW TABLE TYPES shows you status information about the table types. This is particulary
useful for checking if a table type is supported; or to see what is the default table type is.
mysql> SHOW TABLE TYPES;
+--------+---------+-----------------------------------------------------------+
| Type
| Support | Comment
|
+--------+---------+-----------------------------------------------------------+
| MyISAM | DEFAULT | Default type from 3.23 with great performance
|
| HEAP
| YES
| Hash based, stored in memory, useful for temporary tables |
| MERGE | YES
| Collection of identical MyISAM tables
|
| ISAM
| YES
| Obsolete table type; Is replaced by MyISAM
|
| InnoDB | YES
| Supports transactions, row-level locking and foreign keys |
Chapter 4: Database Administration
309
| BDB
| NO
| Supports transactions and page-level locking
|
+--------+---------+-----------------------------------------------------------+
6 rows in set (0.00 sec)
The ’Support’ option DEFAULT indicates whether the particular table type is supported, and
which is the default type. If the server is started with --default-table-type=InnoDB, then
the InnoDB ’Support’ field will have the value DEFAULT.
4.6.8.11 SHOW PRIVILEGES
SHOW PRIVILEGES
This command is implemented in MySQL 4.1.0.
SHOW PRIVILEGES shows the list of system privileges that the underlying MySQL server
supports.
mysql> show privileges;
+------------+--------------------------+------------------------------------------| Privilege | Context
| Comment
+------------+--------------------------+------------------------------------------| Select
| Tables
| To retrieve rows from table
| Insert
| Tables
| To insert data into tables
| Update
| Tables
| To update existing rows
| Delete
| Tables
| To delete existing rows
| Index
| Tables
| To create or drop indexes
| Alter
| Tables
| To alter the table
| Create
| Databases,Tables,Indexes | To create new databases and tables
| Drop
| Databases,Tables
| To drop databases and tables
| Grant
| Databases,Tables
| To give to other users those privileges yo
| References | Databases,Tables
| To have references on tables
| Reload
| Server Admin
| To reload or refresh tables, logs and priv
| Shutdown
| Server Admin
| To shutdown the server
| Process
| Server Admin
| To view the plain text of currently execut
| File
| File access on server
| To read and write files on the server
+------------+--------------------------+------------------------------------------14 rows in set (0.00 sec)
4.7 MySQL Localisation and International Usage
4.7.1 The Character Set Used for Data and Sorting
By default, MySQL uses the ISO-8859-1 (Latin1) character set with sorting according to
Swedish/Finnish. This is the character set suitable in the USA and western Europe.
All standard MySQL binaries are compiled with --with-extra-charsets=complex. This
will add code to all standard programs to be able to handle latin1 and all multi-byte
character sets within the binary. Other character sets will be loaded from a character-set
definition file when needed.
310
MySQL Technical Reference for Version 4.1.1-alpha
The character set determines what characters are allowed in names and how strings are
sorted by the ORDER BY and GROUP BY clauses of the SELECT statement.
You can change the character set with the --default-character-set option when you start
the server. The character sets available depend on the --with-charset=charset and -with-extra-charsets= list-of-charset | complex | all | none options to configure,
and the character set configuration files listed in ‘SHAREDIR/charsets/Index’. See Section 2.3.3 [configure options], page 93.
If you change the character set when running MySQL (which may also change the sort
order), you must run myisamchk -r -q --set-character-set=charset on all tables. Otherwise, your indexes may not be ordered correctly.
When a client connects to a MySQL server, the server sends the default character set in
use to the client. The client will switch to use this character set for this connection.
One should use mysql_real_escape_string() when escaping strings for an SQL query.
mysql_real_escape_string() is identical to the old mysql_escape_string() function,
except that it takes the MYSQL connection handle as the first parameter.
If the client is compiled with different paths than where the server is installed and the user
who configured MySQL didn’t include all character sets in the MySQL binary, one must
specify for the client where it can find the additional character sets it will need if the server
runs with a different character set than the client.
One can specify this by putting in a MySQL option file:
[client]
character-sets-dir=/usr/local/mysql/share/mysql/charsets
where the path points to the directory in which the dynamic MySQL character sets are
stored.
One can force the client to use specific character set by specifying:
[client]
default-character-set=character-set-name
but normally this is never needed.
4.7.1.1 German character set
To get German sorting order, you should start mysqld with --default-characterset=latin1_de. This will give you the following characteristics.
When sorting and comparing strings, the following mapping is done on the strings before
doing the comparison:
ä -> ae
ö -> oe
ü -> ue
ß -> ss
All accented characters, are converted to their un-accented uppercase counterpart. All
letters are converted to uppercase.
When comparing strings with LIKE the one -> two character mapping is not done. All
letters are converted to uppercase. Accent are removed from all letters except: Ü, ü, Ö, ö, Ä
and ä.
Chapter 4: Database Administration
311
4.7.2 Non-English Error Messages
mysqld can issue error messages in the following languages: Czech, Danish, Dutch, English
(the default), Estonian, French, German, Greek, Hungarian, Italian, Japanese, Korean,
Norwegian, Norwegian-ny, Polish, Portuguese, Romanian, Russian, Slovak, Spanish, and
Swedish.
To start mysqld with a particular language, use either the --language=lang or -L lang
options. For example:
shell> mysqld --language=swedish
or:
shell> mysqld --language=/usr/local/share/swedish
Note that all language names are specified in lowercase.
The language files are located (by default) in ‘mysql_base_dir /share/LANGUAGE /’.
To update the error message file, you should edit the ‘errmsg.txt’ file and execute the
following command to generate the ‘errmsg.sys’ file:
shell> comp_err errmsg.txt errmsg.sys
If you upgrade to a newer version of MySQL, remember to repeat your changes with the
new ‘errmsg.txt’ file.
4.7.3 Adding a New Character Set
To add another character set to MySQL, use the following procedure.
Decide if the set is simple or complex. If the character set does not need to use special
string collating routines for sorting and does not need multi-byte character support, it is
simple. If it needs either of those features, it is complex.
For example, latin1 and danish are simple charactersets while big5 or czech are complex
character sets.
In the following section, we have assumed that you name your character set MYSET.
For a simple character set do the following:
1. Add MYSET to the end of the ‘sql/share/charsets/Index’ file Assign a unique
number to it.
2. Create the file ‘sql/share/charsets/MYSET.conf’.
(You can use
‘sql/share/charsets/latin1.conf’ as a base for this.)
The syntax for the file is very simple:
• Comments start with a ’#’ character and proceed to the end of the line.
• Words are separated by arbitrary amounts of whitespace.
• When defining the character set, every word must be a number in hexadecimal
format
• The ctype array takes up the first 257 words. The to_lower[], to_upper[] and
sort_order[] arrays take up 256 words each after that.
See Section 4.7.4 [Character arrays], page 312.
312
MySQL Technical Reference for Version 4.1.1-alpha
3. Add the character set name to the CHARSETS_AVAILABLE and COMPILED_CHARSETS lists
in configure.in.
4. Reconfigure, recompile, and test.
For a complex character set do the following:
1. Create the file ‘strings/ctype-MYSET.c’ in the MySQL source distribution.
2. Add MYSET to the end of the ‘sql/share/charsets/Index’ file. Assign a unique
number to it.
3. Look at one of the existing ‘ctype-*.c’ files to see what needs to be defined, for
example ‘strings/ctype-big5.c’. Note that the arrays in your file must have names
like ctype_MYSET, to_lower_MYSET, and so on. This corresponds to the arrays in the
simple character set. See Section 4.7.4 [Character arrays], page 312.
4. Near the top of the file, place a special comment like this:
/*
* This comment is parsed by configure to create ctype.c,
* so don’t change it unless you know what you are doing.
*
* .configure. number_MYSET=MYNUMBER
* .configure. strxfrm_multiply_MYSET=N
* .configure. mbmaxlen_MYSET=N
*/
The configure program uses this comment to include the character set into the MySQL
library automatically.
The strxfrm multiply and mbmaxlen lines will be explained in the following sections.
Only include these if you need the string collating functions or the multi-byte character
set functions, respectively.
5. You should then create some of the following functions:
• my_strncoll_MYSET()
• my_strcoll_MYSET()
• my_strxfrm_MYSET()
• my_like_range_MYSET()
See Section 4.7.5 [String collating], page 313.
6. Add the character set name to the CHARSETS_AVAILABLE and COMPILED_CHARSETS lists
in configure.in.
7. Reconfigure, recompile, and test.
The file ‘sql/share/charsets/README’ includes some more instructions.
If you want to have the character set included in the MySQL distribution, mail a patch to
the MySQL internals mailing list. See Section 1.7.1.1 [Mailing-list], page 31.
4.7.4 The Character Definition Arrays
to_lower[] and to_upper[] are simple arrays that hold the lowercase and uppercase characters corresponding to each member of the character set. For example:
Chapter 4: Database Administration
313
to_lower[’A’] should contain ’a’
to_upper[’a’] should contain ’A’
sort_order[] is a map indicating how characters should be ordered for comparison and
sorting purposes. Quite often (but not for all character sets) this is the same as to_upper[]
(which means sorting will be case-insensitive). MySQL will sort characters based on the
value of sort_order[character]. For more complicated sorting rules, see the discussion
of string collating below. See Section 4.7.5 [String collating], page 313.
ctype[] is an array of bit values, with one element for one character. (Note that to_
lower[], to_upper[], and sort_order[] are indexed by character value, but ctype[] is
indexed by character value + 1. This is an old legacy to be able to handle EOF.)
You can find the following bitmask definitions in ‘m_ctype.h’:
#define
#define
#define
#define
#define
#define
#define
#define
_U
_L
_N
_S
_P
_C
_B
_X
01
02
04
010
020
040
0100
0200
/*
/*
/*
/*
/*
/*
/*
/*
Uppercase */
Lowercase */
Numeral (digit) */
Spacing character */
Punctuation */
Control character */
Blank */
heXadecimal digit */
The ctype[] entry for each character should be the union of the applicable bitmask values
that describe the character. For example, ’A’ is an uppercase character (_U) as well as a
hexadecimal digit (_X), so ctype[’A’+1] should contain the value:
_U + _X = 01 + 0200 = 0201
4.7.5 String Collating Support
If the sorting rules for your language are too complex to be handled with the simple sort_
order[] table, you need to use the string collating functions.
Right now the best documentation on this is the character sets that are already implemented. Look at the big5, czech, gbk, sjis, and tis160 character sets for examples.
You must specify the strxfrm_multiply_MYSET=N value in the special comment at the top
of the file. N should be set to the maximum ratio the strings may grow during my_strxfrm_
MYSET (it must be a positive integer).
4.7.6 Multi-byte Character Support
If your want to add support for a new character set that includes multi-byte characters,
you need to use the multi-byte character functions.
Right now the best documentation on this is the character sets that are already implemented. Look at the euc_kr, gb2312, gbk, sjis, and ujis character sets for examples.
These are implemented in the ‘ctype-’charset’.c’ files in the ‘strings’ directory.
You must specify the mbmaxlen_MYSET=N value in the special comment at the top of the
source file. N should be set to the size in bytes of the largest character in the set.
314
MySQL Technical Reference for Version 4.1.1-alpha
4.7.7 Problems With Character Sets
If you try to use a character set that is not compiled into your binary, you can run into a
couple of different problems:
• Your program has a wrong path to where the character sets are stored. (Default
‘/usr/local/mysql/share/mysql/charsets’). This can be fixed by using the -character-sets-dir option to the program in question.
• The character set is a multi-byte character set that can’t be loaded dynamically. In
this case you have to recompile the program with the support for the character set.
• The character set is a dynamic character set, but you don’t have a configure file for
it. In this case you should install the configure file for the character set from a new
MySQL distribution.
• Your ‘Index’ file doesn’t contain the name for the character set.
ERROR 1105: File ’/usr/local/share/mysql/charsets/?.conf’ not found
(Errcode: 2)
In this case you should either get a new Index file or add by hand the name of any
missing character sets.
For MyISAM tables, you can check the character set name and number for a table with
myisamchk -dvv table_name.
4.8 MySQL Server-Side Scripts and Utilities
4.8.1 Overview of the Server-Side Scripts and Utilities
All MySQL programs take many different options. However, every MySQL program provides a --help option that you can use to get a full description of the program’s different
options. For example, try mysql --help.
You can override default options for all standard programs with an option file. Section 4.1.2
[Option files], page 206.
The following list briefly describes the server-side MySQL programs:
myisamchk
Utility to describe, check, optimise, and repair MySQL tables. Because
myisamchk has many functions, it is described in its own chapter. See
Chapter 4 [MySQL Database Administration], page 198.
make_binary_distribution
Makes a binary release of a compiled MySQL. This could be sent by FTP to
‘/pub/mysql/Incoming’ on support.mysql.com for the convenience of other
MySQL users.
mysqlbug
The MySQL bug report script. This script should always be used when filing a
bug report to the MySQL list.
mysqld
The SQL daemon. This should always be running.
Chapter 4: Database Administration
315
mysql_install_db
Creates the MySQL grant tables with default privileges. This is usually executed only once, when first installing MySQL on a system.
4.8.2 mysqld_safe, The Wrapper Around mysqld
mysqld_safe is the recommended way to start a mysqld daemon on Unix. mysqld_safe
adds some safety features such as restarting the server when an error occurs and logging
run-time information to a log file.
Note: Before MySQL 4.0, mysqld_safe is named safe_mysqld. To preserve backward
compatibility, MySQL binary distributions for some time will include safe_mysqld as a
symbolic link to mysqld_safe.
If you don’t use --mysqld=# or --mysqld-version=# mysqld_safe will use an executable
named mysqld-max if it exists. If not, mysqld_safe will start mysqld. This makes it very
easy to test to use mysqld-max instead of mysqld; just copy mysqld-max to where you have
mysqld and it will be used.
Normally one should never edit the mysqld_safe script, but instead put the options to
mysqld_safe in the [mysqld_safe] section in the ‘my.cnf’ file. mysqld_safe reads all
options from the [mysqld], [server] and [mysqld_safe] sections from the option files.
(For backward compatibility, it also reads the [safe_mysqld] sections.) See Section 4.1.2
[Option files], page 206.
Note that all options on the command-line to mysqld_safe are passed to mysqld. If you
wants to use any options in mysqld_safe that mysqld doesn’t support, you must specify
these in the option file.
Most of the options to mysqld_safe are the same as the options to mysqld. See Section 4.1.1
[Command-line options], page 198.
mysqld_safe supports the following options:
--basedir=path
--core-file-size=#
Size of the core file mysqld should be able to create. Passed to ulimit -c.
--datadir=path
--defaults-extra-file=path
--defaults-file=path
--err-log=path (this is marked obsolete in 4.0; Use --log-error instead)
--log-error=path
Write the error log to the above file. See Section 4.10.1 [Error log], page 354.
--ledir=path
Path to mysqld
--log=path
--mysqld=mysqld-version
Name of the mysqld version in the ledir directory you want to start.
--mysqld-version=version
Similar to --mysqld= but here you only give the suffix for mysqld. For example
if you use --mysqld-version=max, mysqld_safe will start the ledir/mysqld-
316
MySQL Technical Reference for Version 4.1.1-alpha
max version. If the argument to --mysqld-version is empty, ledir/mysqld
will be used.
--nice=# (added in MySQL 4.0.14)
--no-defaults
--open-files-limit=#
Number of files mysqld should be able to open. Passed to ulimit -n. Note
that you need to start mysqld_safe as root for this to work properly!
--pid-file=path
--port=#
--socket=path
--timezone=#
Set the timezone (the TZ) variable to the value of this parameter.
--user=#
The mysqld_safe script is written so that it normally is able to start a server that was
installed from either a source or a binary version of MySQL, even if these install the server
in slightly different locations. mysqld_safe expects one of these conditions to be true:
• The server and databases can be found relative to the directory from which mysqld_
safe is invoked. mysqld_safe looks under its working directory for ‘bin’ and ‘data’
directories (for binary distributions) or for ‘libexec’ and ‘var’ directories (for source
distributions). 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 pathnames. Typical locations are
‘/usr/local/libexec’ and ‘/usr/local/var’. The actual locations are determined
when the distribution was built from which mysqld_safe comes. They should be
correct if MySQL was installed in a standard location.
Because mysqld_safe will try to find the server and databases relative to its own working
directory, you can install a binary distribution of MySQL anywhere, as long as you start
mysqld_safe from the MySQL installation directory:
shell> cd mysql_installation_directory
shell> bin/mysqld_safe &
If mysqld_safe fails, even when invoked from the MySQL installation directory, you can
modify it to use the path to mysqld and the pathname options that are correct for your
system. Note that if you upgrade MySQL in the future, your modified version of mysqld_
safe will be overwritten, so you should make a copy of your edited version that you can
reinstall.
4.8.3 mysqld_multi, A Program for Managing Multiple MySQL
Servers
mysqld_multi is meant for managing several mysqld processes that listen for connections
on different Unix sockets and TCP/IP ports.
Chapter 4: Database Administration
317
The program will search for groups named [mysqld#] from ‘my.cnf’ (or the file named
by the --config-file=... option), where # can be any positive number starting from 1.
This number is referred to in the following discussion as the option group number, or GNR.
Group numbers distinquish option groups from one another and are used as arguments to
mysqld_multi to specify which servers you want to start, stop, or obtain status for. Options
listed in these groups should be the same as you would use in the usual [mysqld] group
used for starting mysqld. (See, for example, Section 2.4.3 [Automatic start], page 113.)
However, for mysqld_multi, be sure that each group includes options for values such as the
port, socket, etc., to be used for each individual mysqld process.
mysqld_multi is invoked using the following syntax:
Usage: mysqld_multi [OPTIONS] {start|stop|report} [GNR,GNR,GNR...]
or
mysqld_multi [OPTIONS] {start|stop|report} [GNR-GNR,GNR,GNR-GNR,...]
Each GNR represents an option group number. You can start, stop or report any GNR, or
several of them at the same time. For an example of how you might set up an option file,
use this command:
shell> mysqld_multi --example
The GNR values in the list can be comma-separated or combined with a dash; in the latter
case, all the GNRs between GNR1-GNR2 will be affected. With no GNR argument, all
groups listed in the option file will be either started, stopped, or reported. Note that you
must not have any white spaces in the GNR list. Anything after a white space is ignored.
mysqld_multi supports the following options:
--config-file=...
Alternative config file. Note: This will not affect this program’s own options
(group [mysqld_multi]), but only groups [mysqld#]. Without this option,
everything will be searched from the ordinary ‘my.cnf’ file.
--example
Display an example option file.
--help
Print this help and exit.
--log=...
Log file. Full path to and the name for the log file. Note: If the file exists,
everything will be appended.
--mysqladmin=...
mysqladmin binary to be used for a server shutdown.
--mysqld=...
mysqld binary to be used. Note that you can give mysqld_safe to this option
also. The options are passed to mysqld. Just make sure you have mysqld in
your environment variable PATH or fix mysqld_safe.
--no-log
Print to stdout instead of the log file. By default the log file is turned on.
--password=...
Password for user for mysqladmin.
318
MySQL Technical Reference for Version 4.1.1-alpha
--tcp-ip
Connect to each MySQL server via the TCP/IP port instead of the Unix socket.
This affects stopping and reporting. If a socket file is missing, the server may
still be running, but can be accessed only via the TCP/IP port. By default,
connections are made using the Unix socket.
--user=...
MySQL user for mysqladmin.
--version
Print the version number and exit.
Some notes about mysqld_multi:
• Make sure that the MySQL user, who is stopping the mysqld services (e.g using the
mysqladmin program) have the same password and username for all the data directories
accessed (to the mysql database) And make sure that the user has the SHUTDOWN
privilege! If you have many data directories and many different mysql databases with
different passwords for the MySQL root user, you may want to create a common
multi_admin user for each using the same password (see below). Example how to do
it:
shell> mysql -u root -S /tmp/mysql.sock -proot_password -e
"GRANT SHUTDOWN ON *.* TO [email protected] IDENTIFIED BY ’multipass’"
See Section 4.3.6 [Privileges], page 222. You will have to do the above for each mysqld
running in each data directory, that you have (just change the socket, -S=...).
• pid-file is very important, if you are using mysqld_safe to start mysqld (for example,
--mysqld=mysqld_safe) Every mysqld should have its own pid-file. The advantage
using mysqld_safe instead of mysqld directly here is, that mysqld_safe “guards”
every mysqld process and will restart it, if a mysqld process terminates due to a signal
sent using kill -9, or for other reasons such as a segmentation fault (which MySQL
should never do, of course;). Please note that the mysqld_safe script may require that
you start it from a certain place. This means that you may have to cd to a certain
directory, before you start the 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 /data/mysql -a -f ./share/mysql/english/errmsg.sys
-a -x ./bin/mysqld
-------------------------------------------------------------------------See Section 4.8.2 [mysqld_safe], page 315. The above test should be successful, or you
may encounter problems.
• Beware of the dangers starting multiple mysqlds in the same data directory. Use
separate data directories, unless you know what you are doing!
• The socket file and the TCP/IP port must be different for every mysqld.
• The first and fifth mysqld group were intentionally left out from the example. You
may have ’gaps’ in the config file. This gives you more flexibility. The order in which
the mysqlds are started or stopped depends on the order in which they appear in the
config file.
Chapter 4: Database Administration
319
• When you want to refer to a certain group using GNR with this program, just use
the number in the end of the group name. For example, the GNR for a group named
[mysqld17] is 17.
• You may want to use option --user for mysqld, but in order to do this you need to
run the mysqld_multi script as the Unix root user. Having the option in the config
file doesn’t matter; you will just get a warning, if you are not the superuser and the
mysqlds are started under your Unix account. Important: Make sure that the pidfile and the data directory are read+write(+execute for the latter one) accessible for
that Unix user, who the specific mysqld process is started as. Do not use the Unix root
account for this, unless you know what you are doing!
• Most important: Make sure that you understand the meanings of the options that are
passed to the mysqlds and why one would want to have separate mysqld processes.
Starting multiple mysqlds in one data directory will not give you extra performance in
a threaded system!
See Section 4.2 [Multiple servers], page 209.
This is an example of the config file on behalf of mysqld_multi.
# This file should probably be in your home dir (~/.my.cnf) or /etc/my.cnf
# Version 2.1 by Jani Tolonen
[mysqld_multi]
mysqld
= /usr/local/bin/mysqld_safe
mysqladmin = /usr/local/bin/mysqladmin
user
= multi_admin
password
= multipass
[mysqld2]
socket
port
pid-file
datadir
language
user
=
=
=
=
=
=
/tmp/mysql.sock2
3307
/usr/local/mysql/var2/hostname.pid2
/usr/local/mysql/var2
/usr/local/share/mysql/english
john
[mysqld3]
socket
port
pid-file
datadir
language
user
=
=
=
=
=
=
/tmp/mysql.sock3
3308
/usr/local/mysql/var3/hostname.pid3
/usr/local/mysql/var3
/usr/local/share/mysql/swedish
monty
[mysqld4]
socket
port
pid-file
datadir
=
=
=
=
/tmp/mysql.sock4
3309
/usr/local/mysql/var4/hostname.pid4
/usr/local/mysql/var4
320
MySQL Technical Reference for Version 4.1.1-alpha
language
user
= /usr/local/share/mysql/estonia
= tonu
[mysqld6]
socket
= /tmp/mysql.sock6
port
= 3311
pid-file
= /usr/local/mysql/var6/hostname.pid6
datadir
= /usr/local/mysql/var6
language
= /usr/local/share/mysql/japanese
user
= jani
See Section 4.1.2 [Option files], page 206.
4.8.4 myisampack, The MySQL Compressed Read-only Table
Generator
myisampack is used to compress MyISAM tables, and pack_isam is used to compress ISAM
tables. Because ISAM tables are deprecated, we will only discuss myisampack here, but
everything said about myisampack should also be true for pack_isam.
myisampack works by compressing each column in the table separately. The information
needed to decompress columns is read into memory when the table is opened. This results
in much better performance when accessing individual records, because you only have to
uncompress exactly one record, not a much larger disk block as when using Stacker on
MS-DOS. Usually, myisampack packs the datafile 40%-70%.
MySQL uses memory mapping (mmap()) on compressed tables and falls back to normal
read/write file usage if mmap() doesn’t work.
Please note the following:
• After packing, the table is read-only. This is generally intended (such as when accessing
packed tables on a CD). Also allowing writes to a packed table is on our TODO list
but with low priority.
• myisampack can also pack BLOB or TEXT columns. The older pack_isam (for ISAM
tables) cannot do this.
myisampack is invoked like this:
shell> myisampack [options] filename ...
Each filename should be the name of an index (‘.MYI’) file. If you are not in the database
directory, you should specify the pathname to the file. It is permissible to omit the ‘.MYI’
extension.
myisampack supports the following options:
-b, --backup
Make a backup of the table as tbl_name.OLD.
-#, --debug=debug_options
Output debug log. The debug_options string often is ’d:t:o,filename’.
-f, --force
Force packing of the table even if it becomes bigger or if the temporary file exists.
myisampack creates a temporary file named ‘tbl_name.TMD’ while it compresses
Chapter 4: Database Administration
321
the table. If you kill myisampack, the ‘.TMD’ file may not be deleted. Normally,
myisampack exits with an error if it finds that ‘tbl_name.TMD’ exists. With
--force, myisampack packs the table anyway.
-?, --help
Display a help message and exit.
-j big_tbl_name, --join=big_tbl_name
Join all tables named on the command-line into a single table big_tbl_name.
All tables that are to be combined must be identical (same column names and
types, same indexes, etc.).
-p #, --packlength=#
Specify the record length storage size, in bytes. The value should be 1, 2, or 3.
(myisampack stores all rows with length pointers of 1, 2, or 3 bytes. In most
normal cases, myisampack can determine the right length value before it begins
packing the file, but it may notice during the packing process that it could have
used a shorter length. In this case, myisampack will print a note that the next
time you pack the same file, you could use a shorter record length.)
-s, --silent
Silent mode. Write output only when errors occur.
-t, --test
Don’t actually pack table, just test packing it.
-T dir_name, --tmp_dir=dir_name
Use the named directory as the location in which to write the temporary table.
-v, --verbose
Verbose mode. Write information about progress and packing result.
-V, --version
Display version information and exit.
-w, --wait
Wait and retry if table is in use. If the mysqld server was invoked with the
--skip-external-locking option, it is not a good idea to invoke myisampack
if the table might be updated during the packing process.
The sequence of commands shown here illustrates a typical table compression session:
shell> ls -l
-rw-rw-r--rw-rw-r--rw-rw-r--
station.*
1 monty
1 monty
1 monty
my
my
my
shell> myisamchk -dvv station
MyISAM file:
station
Isam-version: 2
Creation time: 1996-03-13 10:08:58
Recover time: 1997-02-02 3:06:43
994128 Apr 17 19:00 station.MYD
53248 Apr 17 19:00 station.MYI
5767 Apr 17 19:00 station.frm
322
MySQL Technical Reference for Version 4.1.1-alpha
Data records:
1192
Datafile: Parts:
1192
Datafile pointer (bytes):
2
Max datafile length:
54657023
Recordlength:
834
Record format: Fixed length
Deleted blocks:
0
Deleted data:
0
Keyfile pointer (bytes):
2
Max keyfile length:
33554431
table description:
Key Start Len Index
Type
1
2
4
unique unsigned long
2
32
30 multip. text
Field
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
Start
1
2
6
10
11
31
32
62
97
132
167
171
187
222
226
242
262
282
302
332
336
340
341
349
357
365
367
369
373
377
378
380
388
392
Length Type
1
4
4
1
20
1
30
35
35
35
4
16
35
4
16
20
20
20
30
4
4
1
8
8
8
2
2
4
4
1
2
8
4
4
Root
1024
10240
Blocksize
1024
1024
Rec/key
1
1
Chapter 4: Database Administration
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
396
400
404
405
409
413
417
421
425
429
449
479
480
481
560
639
718
797
805
806
807
827
831
323
4
4
1
4
4
4
4
4
4
20
30
1
1
79
79
79
79
8
1
1
20
4
4
shell> myisampack station.MYI
Compressing station.MYI: (1192 records)
- Calculating statistics
normal:
20 empty-space:
16
pre-space:
0 end-space:
12
Original trees: 57 After join: 17
- Compressing file
87.14%
shell> ls -l
-rw-rw-r--rw-rw-r--rw-rw-r--
station.*
1 monty
1 monty
1 monty
my
my
my
empty-zero:
table-lookups:
12
5
empty-fill:
zero:
127874 Apr 17 19:00 station.MYD
55296 Apr 17 19:04 station.MYI
5767 Apr 17 19:00 station.frm
shell> myisamchk -dvv station
MyISAM file:
station
Isam-version: 2
Creation time: 1996-03-13 10:08:58
Recover time: 1997-04-17 19:04:26
Data records:
1192 Deleted blocks:
Datafile: Parts:
1192 Deleted data:
0
0
11
7
324
MySQL Technical Reference for Version 4.1.1-alpha
Datafilepointer (bytes):
3
Max datafile length:
16777215
Recordlength:
834
Record format: Compressed
Keyfile pointer (bytes):
1
Max keyfile length:
131071
table description:
Key Start Len Index
Type
1
2
4
unique unsigned long
2
32
30 multip. text
Field
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
Start
1
2
6
10
11
31
32
62
97
132
167
171
187
222
226
242
262
282
302
332
336
340
341
349
357
365
367
369
373
377
378
380
388
392
396
400
Length
1
4
4
1
20
1
30
35
35
35
4
16
35
4
16
20
20
20
30
4
4
1
8
8
8
2
2
4
4
1
2
8
4
4
4
4
Type
constant
zerofill(1)
no zeros, zerofill(1)
table-lookup
no endspace,
no endspace,
no empty
no endspace,
zerofill(1)
no endspace,
no endspace,
zerofill(1)
no endspace,
no endspace,
no endspace,
no endspace,
no endspace,
always zero
always zero
not_always
not_always, no
not_always, no
not_always, no
not_always, no
not_always, no
not_always
no empty
no empty
no empty
table-lookup
table-lookup
always zero
no zeros, zerofill(1)
no zeros, zerofill(1)
table-lookup
no zeros, zerofill(1)
no zeros
always zero
table-lookup
no zeros, zerofill(1)
no zeros, zerofill(1)
Root
10240
54272
Blocksize
1024
1024
Huff tree
1
2
2
3
4
3
5
empty
6
7
empty
6
2
empty
5
empty
6
2
empty
5
8
8
5
6
2
2
3
9
10
2
2
2
2
11
3
2
2
2
12
13
2
Bits
0
9
9
9
0
9
9
9
9
9
9
9
9
9
9
9
9
9
9
9
9
9
0
0
9
9
9
9
0
9
9
9
9
0
9
9
Rec/key
1
1
Chapter 4: Database Administration
37
404
1
38
405
4
39
409
4
40
413
4
41
417
4
42
421
4
43
425
4
44
429
20
45
449
30
46
479
1
47
480
1
48
481
79
49
560
79
50
639
79
51
718
79
52
797
8
53
805
1
54
806
1
55
807
20
56
827
4
57
831
4
The information printed by
normal
no zeros
always zero
no zeros
always zero
no zeros
always zero
no empty
no empty
no
no
no
no
no
endspace, no empty
empty
empty
endspace
empty
no empty
no zeros, zerofill(2)
no zeros, zerofill(1)
myisampack is described here:
325
2
2
2
2
2
2
2
3
3
14
14
15
2
2
16
2
17
3
3
2
2
9
9
9
9
9
9
9
9
9
4
4
9
9
9
9
9
1
9
9
9
9
The number of columns for which no extra packing is used.
empty-space
The number of columns containing values that are only spaces; these will occupy
1 bit.
empty-zero
The number of columns containing values that are only binary 0’s; these will
occupy 1 bit.
empty-fill
The number of integer columns that don’t occupy the full byte range of their
type; these are changed to a smaller type (for example, an INTEGER column
may be changed to MEDIUMINT).
pre-space
The number of decimal columns that are stored with leading spaces. In this
case, each value will contain a count for the number of leading spaces.
end-space
The number of columns that have a lot of trailing spaces. In this case, each
value will contain a count for the number of trailing spaces.
table-lookup
The column had only a small number of different values, which were converted
to an ENUM before Huffman compression.
zero
The number of columns for which all values are zero.
326
MySQL Technical Reference for Version 4.1.1-alpha
Original trees
The initial number of Huffman trees.
After join
The number of distinct Huffman trees left after joining trees to save some header
space.
After a table has been compressed, myisamchk -dvv prints additional information about
each field:
Type
The field type may contain the following descriptors:
constant
All rows have the same value.
no endspace
Don’t store endspace.
no endspace, not_always
Don’t store endspace and don’t do end space compression for all
values.
no endspace, no empty
Don’t store endspace. Don’t store empty values.
table-lookup
The column was converted to an ENUM.
zerofill(n)
The most significant n bytes in the value are always 0 and are not
stored.
no zeros
Don’t store zeros.
always zero
0 values are stored in 1 bit.
Huff tree The Huffman tree associated with the field.
Bits
The number of bits used in the Huffman tree.
After you have run pack_isam/myisampack you must run isamchk/myisamchk to re-create
the index. At this time you can also sort the index blocks and create statistics needed for
the MySQL optimiser to work more efficiently:
myisamchk -rq --analyze --sort-index table_name.MYI
isamchk
-rq --analyze --sort-index table_name.ISM
After you have installed the packed table into the MySQL database directory you should
do mysqladmin flush-tables to force mysqld to start using the new table.
If you want to unpack a packed table, you can do this with the --unpack option to isamchk
or myisamchk.
4.8.5 mysqld-max, An Extended mysqld Server
mysqld-max is the MySQL server (mysqld) configured with the following configure options:
Option
Comment
Chapter 4: Database Administration
327
–with-server-suffix=-max
Add a suffix to the mysqld version string
–with-innodb
Support for InnoDB tables (MySQL 3.23 only)
–with-bdb
Support for Berkeley DB (BDB) tables
CFLAGS=Symbolic link support for Windows
DUSE SYMDIR
The option for enabling InnoDB support is needed only in MySQL 3.23. In MySQL 4 and
up, InnoDB is included by default.
You can find the MySQL-Max binaries at http://www.mysql.com/downloads/mysql-max-4.0.html.
The Windows MySQL binary distributions includes both the standard mysqld.exe binary
and the mysqld-max.exe binary. http://www.mysql.com/downloads/mysql-4.0.html.
See Section 2.1.1 [Windows installation], page 57.
Note that as BerkeleyDB (BDB) is not available for all platforms, so some of the Max binaries
may not have support for it. You can check which table types are supported by doing the
following query:
mysql> SHOW VARIABLES LIKE "have_%";
+------------------+----------+
| Variable_name
| Value
|
+------------------+----------+
| have_bdb
| NO
|
| have_crypt
| YES
|
| have_innodb
| YES
|
| have_isam
| YES
|
| have_raid
| NO
|
| have_symlink
| DISABLED |
| have_openssl
| NO
|
| have_query_cache | YES
|
+------------------+----------+
The meanings of the values in the second column are:
Value
YES
NO
DISABLED
Meaning
The option is activated and usable.
MySQL is not compiled with support for this option.
The xxxx option is disabled because one started mysqld with --skip-xxxx
or because one didn’t start mysqld with all needed options to enable the option. In this case the hostname.err file should contain a reason indicating
why the option is disabled.
Note: To be able to create InnoDB tables in MySQL version 3.23 you must edit your startup
options to include at least the innodb_data_file_path option. See Section 7.5.2 [InnoDB
in MySQL 3.23], page 612.
To get better performance for BDB tables, you should add some configuration options for
these, too. See Section 7.6.3 [BDB start], page 664.
mysqld_safe automatically tries to start any mysqld binary with the -max suffix. This
makes it very easy to test out another mysqld binary in an existing installation. Just run
configure with the options you want and then install the new mysqld binary as mysqldmax in the same directory where your old mysqld binary is. See Section 4.8.2 [mysqld_safe],
page 315.
328
MySQL Technical Reference for Version 4.1.1-alpha
On Linux, the MySQL-Max RPM uses the above mentioned mysqld_safe feature. (It just
installs the mysqld-max executable, so mysqld_safe automatically uses this executable
when mysqld_safe is restarted.)
The following table shows which table types our MySQL-Max binaries include:
System
Windows/NT
AIX 4.3
HP-UX 11.0
Linux-Alpha
Linux-Intel
Linux-IA-64
Solaris-Intel
SolarisSPARC
SCO OSR5
UnixWare
Mac OS X
BDB
Y
N
N
N
Y
N
N
Y
InnoDB
Y
Y
Y
Y
Y
Y
Y
Y
Y
Y
N
Y
Y
Y
Note that as of MySQL 4, you do not need a MySQL Max server for InnoDB, because
InnoDB is included by default.
4.9 MySQL Client-Side Scripts and Utilities
4.9.1 Overview of the Client-Side Scripts and Utilities
All MySQL clients that communicate with the server using the mysqlclient library use
the following environment variables:
Name
MYSQL_UNIX_PORT
Description
The default socket; used for connections to
localhost
MYSQL_TCP_PORT
The default TCP/IP port
MYSQL_PWD
The default password
MYSQL_DEBUG
Debug-trace options when debugging
TMPDIR
The directory where temporary tables/files are
created
Use of MYSQL_PWD is insecure. See Section 4.3.8 [Connecting], page 227.
On Unix, the ‘mysql’ client uses the file named in the MYSQL_HISTFILE environment
variable to save the command-line history. The default value for the history file is
‘$HOME/.mysql_history’, where $HOME is the value of the HOME environment variable. See
Appendix F [Environment variables], page 1032.
If you do not want to maintain a file that contains a record of your queries, first remove
‘.mysql_history’ if it exists, then use either of the following techniques:
• Set the MYSQL_HISTFILE variable to ‘/dev/null’. To cause this setting to take effect
each time you log in, put the setting in one of your shell’s startup files.
• Create ‘.mysql_histfile’ as a symbolic link to ‘/dev/null’:
Chapter 4: Database Administration
329
shell> ln -s /dev/null $HOME/.mysql_history
You need do this only once.
All MySQL programs take many different options. However, every MySQL program provides a --help option that you can use to get a full description of the program’s different
options. For example, try mysql --help.
You can override default options for all standard client programs with an option file. Section 4.1.2 [Option files], page 206.
The following list briefly describes the client-side MySQL programs:
msql2mysql
A shell script that converts mSQL programs to MySQL. It doesn’t handle all
cases, but it gives a good start when converting.
mysql
The command-line tool for interactively entering queries or executing queries
from a file in batch mode. See Section 4.9.2 [mysql], page 330.
mysqlcc
This program provides a graphical interface for interacting with the server. See
Section 4.9.3 [mysqlcc], page 337.
mysqlaccess
A script that checks the access privileges for a host, user, and database combination.
mysqladmin
Utility for performing 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.9.4 [mysqladmin], page 339.
mysqlbinlog
Utility for reading queries from a binary log. Can be used to recover from a
crash with an old backup. See Section 4.9.5 [mysqlbinlog], page 341.
mysqldump
Dumps a MySQL database into a file as SQL statements or as tab-separated
text files. Enhanced freeware originally by Igor Romanenko. See Section 4.9.7
[mysqldump], page 344.
mysqlimport
Imports text files into their respective tables using LOAD DATA INFILE. See
Section 4.9.9 [mysqlimport], page 349.
mysqlshow
Displays information about databases, tables, columns, and indexes.
replace
A utility program that is used by msql2mysql, but that has more general applicability as well. replace changes strings in place in files or on the standard
input. Uses a finite state machine to match longer strings first. Can be used to
swap strings. For example, this command swaps a and b in the given files:
shell> replace a b b a -- file1 file2 ...
330
MySQL Technical Reference for Version 4.1.1-alpha
4.9.2 mysql, The Command-line Tool
mysql is a simple SQL shell (with GNU readline capabilities). It supports interactive and
non-interactive use. When used interactively, query results are presented in an ASCII-table
format. When used non-interactively (for example, as a filter), the result is presented in
tab-separated format. (The output format can be changed using command-line options.)
You can run scripts simply like this:
shell> mysql database < script.sql > output.tab
If you have problems due to insufficient memory in the client, use the --quick option! This
forces mysql to use mysql_use_result() rather than mysql_store_result() to retrieve
the result set.
Using mysql is very easy. Just start it as follows: mysql database or mysql --user=user_
name --password=your_password database. Type an SQL statement, end it with ‘;’, ‘\g’,
or ‘\G’ and press Enter.
mysql supports the following options:
-?, --help
Display this help and exit.
-A, --no-auto-rehash
No automatic rehashing. One has to use ’rehash’ to get table and field completion. This gives a quicker start of mysql.
--prompt=...
Set the mysql prompt to specified format.
-b, --no-beep
Turn off beep-on-error.
-B, --batch
Print results with a tab as separator, each row on a new line. Doesn’t use
history file.
--character-sets-dir=...
Directory where character sets are located.
-C, --compress
Use compression in server/client protocol.
-#, --debug[=...]
Debug log. Default is ’d:t:o,/tmp/mysql.trace’.
-D, --database=...
Database to use. This is mainly useful in the ‘my.cnf’ file.
--default-character-set=...
Set the default character set.
-e, --execute=...
Execute command and quit. (Output like with –batch)
Chapter 4: Database Administration
331
-E, --vertical
Print the output of a query (rows) vertically. Without this option you can also
force this output by ending your statements with \G.
-f, --force
Continue even if we get an SQL error.
-g, --no-named-commands
Named commands are disabled. Use \* form only, or use named commands
only in the beginning of a line ending with a semicolon (‘;’). Since Version
10.9, the client now starts with this option enabled by default! With the -g
option, long format commands will still work from the first line, however.
-G, --enable-named-commands
Named commands are enabled. Long format commands are allowed as well as
shortened \* commands.
-i, --ignore-space
Ignore space after function names.
-h, --host=...
Connect to the given host.
-H, --html
Produce HTML output.
-X, --xml Produce XML output.
-L, --skip-line-numbers
Don’t write line number for errors. Useful when one wants to compare result
files that includes error messages
--no-pager
Disable pager and print to stdout. See interactive help (\h) also.
--no-tee
Disable outfile. See interactive help (\h) also.
-n, --unbuffered
Flush buffer after each query.
-N, --skip-column-names
Don’t write column names in results.
-O, --set-variable=name=value
Give a variable a value. --help lists variables. Please note that --setvariable=name=value and -O name=value syntax is deprecated as of MySQL
4.0. Use --name=value instead.
-o, --one-database
Only update the default database. This is useful for skipping updates to other
database in the binary log.
--pager[=...]
Output type. Default is your ENV variable PAGER. Valid pagers are less, more,
cat [> filename], etc. See interactive help (\h) also. This option does not work
in batch mode. Pager works only in Unix.
332
MySQL Technical Reference for Version 4.1.1-alpha
-p[password], --password[=...]
Password to use when connecting to server. If a password is not given on the
command-line, you will be prompted for it. Note that if you use the short form
-p you can’t have a space between the option and the password.
-P port_num, --port=port_num
TCP/IP port number to use for connection.
--protocol=(TCP | SOCKET | PIPE | MEMORY)
To specify the connect protocol to use. New in MySQL 4.1.
-q, --quick
Don’t cache result, print it row-by-row. This may slow down the server if the
output is suspended. Doesn’t use history file.
-r, --raw Write column values without escape conversion. Used with --batch
--reconnect
If the connection is lost, automatically try to reconnect to the server (but only
once).
-s, --silent
Be more silent.
-S --socket=...
Socket file to use for connection.
-t --table
Output in table format. This is default in non-batch mode.
-T, --debug-info
Print some debug information at exit.
--tee=...
Append everything into outfile. See interactive help (\h) also. Does not work
in batch mode.
-u, --user=#
User for login if not current user.
-U, --safe-updates[=#], --i-am-a-dummy[=#]
Only allow UPDATE and DELETE that uses keys. See below for more information
about this option. You can reset this option if you have it in your ‘my.cnf’ file
by using --safe-updates=0.
-v, --verbose
More verbose output (-v -v -v gives the table output format).
-V, --version
Output version information and exit.
-w, --wait
Wait and retry if connection is down instead of aborting.
You can also set the following variables with -O or --set-variable. Please note that
--set-variable=name=value and -O name=value syntax is deprecated as of MySQL 4.0.
Use --name=value instead.
Chapter 4: Database Administration
333
Variable Name
connect timeout
local-infile
Default Description
0
Number of seconds before connection timeout.
0
Disable (0) or enable (1) LOCAL capability for LOAD DATA
INFILE
max allowed packet
16777216Max packet length to send to/receive from server
net buffer length
16384 Buffer for TCP/IP and socket communication
1000
Automatic limit for SELECT when using --safe-updates
select limit
max join size
1000000 Automatic limit for rows in a join when using --safeupdates
If the mysql client loses connection to the server while sending it a query, it will immediately
and automatically try to reconnect once to the server and send the query again. Note that
even if it succeeds in reconnecting, as your first connection has ended, all your previous
session objects are lost: temporary tables, user and session variables. Therefore, the above
behaviour may be dangerous for you, as in this example where the server was shut down
and restarted without you knowing it:
mysql> set @a=1;
Query OK, 0 rows affected (0.05 sec)
mysql> insert into t values(@a);
ERROR 2006: MySQL server has gone away
No connection. Trying to reconnect...
Connection id:
1
Current database: test
Query OK, 1 row affected (1.30 sec)
mysql> select * from t;
+------+
| a
|
+------+
| NULL |
+------+
1 row in set (0.05 sec)
The @a user variable has been lost with the connection, and after the reconnection it is
undefined. To protect from this risk, you can start the mysql client with the --disablereconnect option.
If you type ’help’ on the command-line, mysql will print out the commands that it supports:
mysql> help
MySQL commands:
help
(\h)
?
(\h)
clear
(\c)
connect
(\r)
delimiter (\d)
Display this text.
Synonym for ‘help’.
Clear command.
Reconnect to the server.
Optional arguments are db and host.
Set query delimiter.
334
MySQL Technical Reference for Version 4.1.1-alpha
edit
ego
(\e)
(\G)
Edit command with $EDITOR.
Send command to mysql server,
display result vertically.
exit
(\q)
Exit mysql. Same as quit.
go
(\g)
Send command to mysql server.
nopager
(\n)
Disable pager, print to stdout.
notee
(\t)
Don’t write into outfile.
pager
(\P)
Set PAGER [to_pager].
Print the query results via PAGER.
print
(\p)
Print current command.
prompt
(\R)
Change your mysql prompt.
quit
(\q)
Quit mysql.
rehash
(\#)
Rebuild completion hash.
source
(\.)
Execute an SQL script file.
Takes a file name as an argument.
status
(\s)
Get status information from the server.
system
(\!)
Execute a system shell command.
tee
(\T)
Set outfile [to_outfile].
Append everything into given outfile.
use
(\u)
Use another database.
Takes database name as argument.
The edit, nopager, pager, and system commands work only in Unix.
The status command gives you some information about the connection and the server you
are using. If you are running in the --safe-updates mode, status will also print the
values for the mysql variables that affect your queries.
A useful startup option for beginners (introduced in MySQL Version 3.23.11) is --safeupdates (or --i-am-a-dummy for users that once may have done a DELETE FROM table_name
but forgot the WHERE clause). When using this option, mysql sends the following command
to the MySQL server when opening the connection:
SET SQL_SAFE_UPDATES=1,SQL_SELECT_LIMIT=#select_limit#,
SQL_MAX_JOIN_SIZE=#max_join_size#"
where #select_limit# and #max_join_size# are variables that can be set from the mysql
command-line. See Section 5.5.6 [SET OPTION], page 437.
The effect of the above is:
• You are not allowed to do an UPDATE or DELETE statement if you don’t have a key
constraint in the WHERE part. One can, however, force an UPDATE/DELETE by using
LIMIT:
UPDATE table_name SET not_key_column=# WHERE not_key_column=# LIMIT 1;
• All big results are automatically limited to #select_limit# rows.
• SELECTs that will probably need to examine more than #max_join_size row combinations will be aborted.
Some useful hints about the mysql client:
Some data is much more readable when displayed vertically, instead of the usual horizontal
box type output. For example longer text, which includes new lines, is often much easier
to be read with vertical output.
Chapter 4: Database Administration
335
mysql> SELECT * FROM mails WHERE LENGTH(txt) < 300 lIMIT 300,1\G
*************************** 1. row ***************************
msg_nro: 3068
date: 2000-03-01 23:29:50
time_zone: +0200
mail_from: Monty
reply: [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 with UTF-8
Thimble> or Unicode? Otherwise, I’ll put this on my TODO list and see what
Thimble> happens.
Yes, please do that.
Regards,
Monty
file: inbox-jani-1
hash: 190402944
1 row in set (0.09 sec)
For logging, you can use the tee option. The tee can be started with option --tee=...,
or from the command-line interactively with command tee. All the data displayed on the
screen will also be appended into a given file. This can be very useful for debugging purposes
also. The tee can be disabled from the command-line with command notee. Executing tee
again starts logging again. Without a parameter the previous file will be used. Note that
tee will flush the results into the file after each command, just before the command-line
appears again waiting for the next command.
Browsing, or searching the results in the interactive mode in Unix less, more, or any other
similar program, is now possible with option --pager[=...]. Without argument, mysql
client will look for the PAGER environment variable and set pager to that. pager can
be started from the interactive command-line with command pager and disabled with
command nopager. The command takes an argument optionally and the pager will be set
to that. Command pager can be called without an argument, but this requires that the
option --pager was used, or the pager will default to stdout. pager works only in Unix,
since it uses the popen() function, which doesn’t exist in Windows. In Windows, the tee
option can be used instead, although it may not be as handy as pager can be in some
situations.
A few tips about pager:
• You can use it to write to a file:
mysql> pager cat > /tmp/log.txt
and the results will only go to a file. You can also pass any options for the programs
that you want to use with the pager:
mysql> pager less -n -i -S
336
MySQL Technical Reference for Version 4.1.1-alpha
• From the above do note the option -S. You may find it very useful when browsing the
results; try the option with horizontal output (end commands with \g, or ‘;’) and with
vertical output (end commands with \G). Sometimes a very wide result set is hard to
be read from the screen, with option -S to less you can browse the results within the
interactive less from left to right, preventing lines longer than your screen from being
continued to the next line. This can make the result set much more readable. You can
switch the mode between on and off within the interactive less with -S. See the ’h’
for more help about less.
• You can combine very complex ways to handle the results, for example the following
would send the results to two files in two different directories, on two different harddisks mounted on /dr1 and /dr2, yet let the results still be seen on the screen via
less:
mysql> pager cat | tee /dr1/tmp/res.txt | \
tee /dr2/tmp/res2.txt | less -n -i -S
You can also combine the two functions above; have the tee enabled, pager set to ’less’
and you will be able to browse the results in Unix ’less’ and still have everything appended
into a file the same time. The difference between Unix tee used with the pager and the
mysql client in-built tee, is that the in-built tee works even if you don’t have the Unix
tee available. The in-built tee also logs everything that is printed on the screen, where the
Unix tee used with pager doesn’t log quite that much. Last, but not least, the interactive
tee is more handy to switch on and off, when you want to log something into a file, but
want to be able to turn the feature off sometimes.
From MySQL version 4.0.2 it is possible to change the prompt in the mysql command-line
client.
You can use the following prompt options:
Option
Description
\v
mysqld version
\d
database in use
\h
host connected to
\p
port connected on
\u
username
\U
full [email protected]
\\
‘\’
\n
new line break
\t
tab
\
space
\
space
\R
military hour time (0-23)
\r
standard hour time (1-12)
\m
minutes
\y
two digit year
\Y
four digit year
\D
full date format
\s
seconds
\w
day of the week in three letter format (Mon,
Tue, ...)
Chapter 4: Database Administration
337
\P
\o
\O
\c
am/pm
month in number format
month in three letter format (Jan, Feb, ...)
counter that counts up for each command
you do
‘\’ followed by any other letter just becomes that letter.
You may set the prompt in the following places:
Environment Variable
You may set the MYSQL_PS1 environment variable to a prompt string. For
example:
shell> export MYSQL_PS1="(\[email protected]\h) [\d]> "
‘my.cnf’
‘.my.cnf’
You may set the prompt option in any MySQL configuration file, in the mysql
group. For example:
[mysql]
prompt=(\[email protected]\h) [\d]>\_
Command Line
You may set the --prompt option on the command line to mysql. For example:
shell> mysql --prompt="(\[email protected]\h) [\d]> "
([email protected]) [database]>
Interactively
You may also use the prompt (or \R) command to change your prompt interactively. 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.9.3 mysqlcc, The MySQL Control Center
mysqlcc, the MySQL Control Center, is a platform-independent client that provides a
graphical user interface (GUI) to the MySQL database server. It supports interactive
use, including syntax highlighting and tab-completion. It provides database and table
management, and allows server administration.
Currently, mysqlcc runs on Windows and Linux platforms.
mysqlcc is not included with MySQL distributions, but can be downloaded separately at
http://www.mysql.com/downloads/.
mysqlcc supports the following options:
338
MySQL Technical Reference for Version 4.1.1-alpha
-?, --help
Display this help and exit.
-b, --blocking_queries
Use blocking queries.
-C, --compress
Use compression in server/client protocol.
-c, --connection_name=name
This is a synonym for --server.
-d, --database=...
Database to use. This is mainly useful in the ‘my.cnf’ file.
-H, --history_size=#
History size for the query window.
-h, --host=...
Connect to the given host.
-p[password], --password[=...]
Password to use when connecting to server. If a password is not given on the
command-line, you will be prompted for it. Note that if you use the short form
-p you can’t have a space between the option and the password.
-g, --plugins_path=name
Path to the directory where MySQL Control Center plugins are located.
-P port_num, --port=port_num
TCP/IP port number to use for connection.
-q, --query
Open a query window on startup.
-r, --register
Open the ’Register Server’ dialog on startup.
-s, --server=name
MySQL Control Center connection name.
-S --socket=...
Socket file to use for connection.
-y, --syntax
Enable syntax highlighting and completion.
-Y, --syntax_file=name
Syntax file for completion.
-T, --translations_path=name
Path to the directory where MySQL Control Center translations are located.
-u, --user=#
User for login if not current user.
-V, --version
Output version information and exit.
Chapter 4: Database Administration
339
You can also set the following variables with -O or --set-variable. please note that -set-variable Please note that --set-variable=name=value and -O name=value syntax
is deprecated as of MySQL 4.0. Use --name=value instead.
Variable Name
Default Description
connect timeout
0
Number of seconds before connection timeout.
local-infile
0
Disable (0) or enable (1) LOCAL capability for LOAD DATA
INFILE
max allowed packet
16777216Max packet length to send to/receive from server
net buffer length
16384 Buffer for TCP/IP and socket communication
select limit
1000
Automatic limit for SELECT when using --safe-updates
1000000 Automatic limit for rows in a join when using --safemax join size
updates
4.9.4 mysqladmin, Administering a MySQL Server
A utility for performing administrative operations. The syntax is:
shell> mysqladmin [OPTIONS] command [command-option] command ...
You can get a list of the options your version of mysqladmin supports by executing
mysqladmin --help.
The current mysqladmin supports the following commands:
create databasename
Create a new database.
drop databasename
Delete a database and all its tables.
extended-status
Gives an extended status message from the server.
flush-hosts
Flush all cached hosts.
flush-logs
Flush all logs.
flush-tables
Flush all tables.
flush-privileges
Reload grant tables (same as reload).
kill id,id,...
Kill mysql threads.
password
Set a new password. Change old password to new-password.
ping
Check if mysqld is alive.
processlist
Show list of active threads in server, as with the SHOW PROCESSLIST statement. If the --verbose option is given, the output is like that of SHOW FULL
PROCESSLIST.
340
MySQL Technical Reference for Version 4.1.1-alpha
reload
Reload grant tables.
refresh
Flush all tables and close and open logfiles.
shutdown
Take down the server.
slave-start
Start slave replication thread.
slave-stop
Stop slave replication thread.
status
Gives a short status message from the server.
variables
Prints variables available.
version
Get version information from server.
All commands can be shortened to their unique prefix. For example:
shell> mysqladmin proc stat
+----+-------+-----------+----+-------------+------+-------+------+
| Id | User | Host
| db | Command
| Time | State | Info |
+----+-------+-----------+----+-------------+------+-------+------+
| 6 | monty | localhost |
| Processlist | 0
|
|
|
+----+-------+-----------+----+-------------+------+-------+------+
Uptime: 10077 Threads: 1 Questions: 9 Slow queries: 0
Opens: 6 Flush tables: 1 Open tables: 2
Memory in use: 1092K Max memory used: 1116K
The mysqladmin status command result has the following columns:
Column
Uptime
Threads
Questions
Slow queries
Opens
Flush tables
Open tables
Memory in use
Max memory used
Description
Number of seconds the MySQL server has been up.
Number of active threads (clients).
Number of questions from clients since mysqld was
started.
Queries that have taken more than long_query_time
seconds. See Section 4.10.5 [Slow query log], page 359.
How many tables mysqld has opened.
Number of flush ..., refresh, and reload commands.
Number of tables that are open now.
Memory allocated directly by the mysqld code (only
available when MySQL is compiled with –withdebug=full).
Maximum memory allocated directly by the mysqld code
(only available when MySQL is compiled with –withdebug=full).
If you do mysqladmin shutdown on a socket (in other words, on a the computer where
mysqld is running), mysqladmin will wait until the MySQL pid-file is removed to ensure
that the mysqld server has stopped properly.
Chapter 4: Database Administration
341
4.9.5 mysqlbinlog, Executing the queries from a binary log
You can examine the binary log file (see Section 4.10.4 [Binary log], page 356) with the
mysqlbinlog utility.
shell> mysqlbinlog hostname-bin.001
will print all queries contained in binlog ‘hostname-bin.001’, together with information
(time the query took, ID of the thread which issued it, timestamp when it was issued etc).
You can pipe the output of mysqlbinlog into a mysql client; this is used to recover from a
crash when you have an old backup (see Section 4.5.1 [Backup], page 263):
shell> mysqlbinlog hostname-bin.001 | mysql
or
shell> mysqlbinlog hostname-bin.[0-9]* | mysql
You can also redirect the output of mysqlbinlog to a text file instead, modify this text file
(to cut queries you don’t want to execute for some reason), then execute the queries from
the text file into mysql.
mysqlbinlog has the position=# options which will print only queries whose offset in the
binlog is greater or equal to #.
If you have more than one binary log to execute on the MySQL server, the safe method is
to do it in one unique MySQL connection. Here is what may be UNsafe:
shell> mysqlbinlog hostname-bin.001 | mysql # DANGER!!
shell> mysqlbinlog hostname-bin.002 | mysql # DANGER!!
It will cause problems if the first binlog contains a CREATE TEMPORARY TABLE and the second
one contains a query which uses this temporary table: when the first mysql terminates, it
will drop the temporary table, so the second mysql will report “unknown table”. This is
why you should run all binlogs you want in one unique connection, especially if you use
temporary tables. Here are two possible ways:
shell> mysqlbinlog hostname-bin.001 hostname-bin.002 | mysql
shell> mysqlbinlog hostname-bin.001 > /tmp/queries.sql
shell> mysqlbinlog hostname-bin.002 >> /tmp/queries.sql
shell> mysql -e "source /tmp/queries.sql"
Starting from MySQL 4.0.14, mysqlbinlog can prepare suitable input for mysql to execute
a LOAD DATA INFILE from a binlog. As the binlog contains the data to load (this is true
for MySQL 4.0; MySQL 3.23 did not write the loaded data into the binlog, so the original
file was needed when one wanted to execute the content of the binlog), mysqlbinlog will
copy this data to a temporary file and print a LOAD DATA INFILE command for mysql to
load this temporary file. The location where the temporary file is created is by default the
temporary directory; it can be changed with the local-load option of mysqlbinlog.
Before MySQL 4.1, mysqlbinlog could not prepare suitable output for mysql when the
binary log contained queries from different threads using temporary tables of the same
name, if these queries were interlaced. This is solved in MySQL 4.1.
You can also use mysqlbinlog --read-from-remote-server to read the binary log directly
from a remote MySQL server. However, this is something that is deprecated as we instead
want to make it easy to to apply binary logs to a running MySQL server.
mysqlbinlog --help will give you more information.
342
MySQL Technical Reference for Version 4.1.1-alpha
4.9.6 Using mysqlcheck for Table Maintenance and Crash Recovery
Since MySQL version 3.23.38 you will be able to use a new checking and repairing tool for
MyISAM tables. The difference to myisamchk is that mysqlcheck should be used when the
mysqld server is running, whereas myisamchk should be used when it is not. The benefit is
that you no longer have to take down the server for checking or repairing your tables.
mysqlcheck uses MySQL server commands CHECK, REPAIR, ANALYZE and OPTIMIZE in a
convenient way for the user.
There are three alternative ways to invoke mysqlcheck:
shell> mysqlcheck [OPTIONS] database [tables]
shell> mysqlcheck [OPTIONS] --databases DB1 [DB2 DB3...]
shell> mysqlcheck [OPTIONS] --all-databases
So it can be used in a similar way as mysqldump when it comes to what databases and
tables you want to choose.
mysqlcheck does have a special feature compared to the other clients; the default behaviour,
checking tables (-c), can be changed by renaming the binary. So if you want to have a tool
that repairs tables by default, you should just copy mysqlcheck to your harddrive with a
new name, mysqlrepair, or alternatively make a symbolic link to mysqlrepair and name
the symbolic link as mysqlrepair. If you invoke mysqlrepair now, it will repair tables by
default.
The names that you can use to change mysqlcheck default behaviour are here:
mysqlrepair:
The default option will be -r
mysqlanalyze: The default option will be -a
mysqloptimize: The default option will be -o
The options available for mysqlcheck are listed here, please check what your version supports with mysqlcheck --help.
-A, --all-databases
Check all the databases. This will be same as –databases with all databases
selected
-1, --all-in-1
Instead of making one query for each table, execute all queries in 1 query
separately for each database. Table names will be in a comma separated list.
-a, --analyze
Analyse given tables.
--auto-repair
If a checked table is corrupted, automatically fix it. Repairing will be done
after all tables have been checked, if corrupted ones were found.
-#, --debug=...
Output debug log. Often this is ’d:t:o,filename’
--character-sets-dir=...
Directory where character sets are
Chapter 4: Database Administration
343
-c, --check
Check table for errors
-C, --check-only-changed
Check only tables that have changed since last check or haven’t been closed
properly.
--compress
Use compression in server/client protocol.
-?, --help
Display this help message and exit.
-B, --databases
To check several databases. Note the difference in usage; in this case no tables
are given. All name arguments are regarded as database names.
--default-character-set=...
Set the default character set
-F, --fast
Check only tables that hasn’t been closed properly
-f, --force
Continue even if we get an sql-error.
-e, --extended
If you are using this option with CHECK TABLE, it will ensure that the table
is 100 percent consistent, but will take a long time.
If you are using this option with REPAIR TABLE, it will run an extended
repair on the table, which may not only take a long time to execute, but may
produce a lot of garbage rows also!
-h, --host=...
Connect to host.
-m, --medium-check
Faster than extended-check, but only finds 99.99 percent of all errors. Should
be good enough for most cases.
-o, --optimize
Optimise table
-p, --password[=...]
Password to use when connecting to server. If password is not given it’s solicited
on the tty.
-P, --port=...
Port number to use for TCP/IP connections.
--protocol=(TCP | SOCKET | PIPE | MEMORY)
To specify the connect protocol to use. New in MySQL 4.1.
-q, --quick
If you are using this option with CHECK TABLE, it prevents the check from
scanning the rows to check for wrong links. This is the fastest check.
344
MySQL Technical Reference for Version 4.1.1-alpha
If you are using this option with REPAIR TABLE, it will try to repair only the
index tree. This is the fastest repair method for a table.
-r, --repair
Can fix almost anything except unique keys that aren’t unique.
-s, --silent
Print only error messages.
-S, --socket=...
Socket file to use for connection.
--tables
Overrides option –databases (-B).
-u, --user=#
User for login if not current user.
-v, --verbose
Print information about the various stages.
-V, --version
Output version information and exit.
4.9.7 mysqldump, Dumping Table Structure and Data
Utility to dump a database or a collection of database for backup or for transferring the
data to another SQL server (not necessarily a MySQL server). The dump will contain SQL
statements to create the table and/or populate the table.
If you are doing a backup on the server, you should consider using the mysqlhotcopy
instead. See Section 4.9.8 [mysqlhotcopy], page 348.
shell> mysqldump [OPTIONS] database [tables]
OR
mysqldump [OPTIONS] --databases [OPTIONS] DB1 [DB2 DB3...]
OR
mysqldump [OPTIONS] --all-databases [OPTIONS]
If you don’t give any tables or use the --databases or --all-databases option, entire
databases will be dumped.
You can get a list of the options your version of mysqldump supports by executing mysqldump
--help.
Note that if you run mysqldump without --quick or --opt, mysqldump will load the whole
result set into memory before dumping the result. This will probably be a problem if you
are dumping a big database.
Note that if you are using a new copy of the mysqldump program and you are going to do
a dump that will be read into a very old MySQL server, you should not use the --opt or
-e options.
mysqldump supports the following options:
--add-locks
Add LOCK TABLES before and UNLOCK TABLE after each table dump. (To get
faster inserts into MySQL.)
--add-drop-table
Add a drop table before each create statement.
Chapter 4: Database Administration
345
-A, --all-databases
Dump all the databases. This will be same as --databases with all databases
selected.
-a, --all Include all MySQL-specific create options.
--allow-keywords
Allow creation of column names that are keywords. This works by prefixing
each column name with the table name.
-c, --complete-insert
Use complete insert statements (with column names).
-C, --compress
Compress all information between the client and the server if both support
compression.
-B, --databases
To dump several databases. Note the difference in usage. In this case no tables
are given. All name arguments are regarded as database names. USE db_name;
will be included in the output before each new database.
--delayed
Insert rows with the INSERT DELAYED command.
-e, --extended-insert
Use the new multiline INSERT syntax. (Gives more compact and faster inserts
statements.)
-#, --debug[=option_string]
Trace usage of the program (for debugging).
--help
Display a help message and exit.
--fields-terminated-by=...
--fields-enclosed-by=...
--fields-optionally-enclosed-by=...
--fields-escaped-by=...
--lines-terminated-by=...
These options are used with the -T option and have the same meaning as the
corresponding clauses for LOAD DATA INFILE. See Section 6.4.8 [LOAD DATA],
page 561.
-F, --flush-logs
Flush log file in the MySQL server before starting the dump.
-f, --force,
Continue even if we get an SQL error during a table dump.
-h, --host=..
Dump data from the MySQL server on the named host. The default host is
localhost.
-l, --lock-tables.
Lock all tables before starting the dump. The tables are locked with READ
LOCAL to allow concurrent inserts in the case of MyISAM tables.
346
MySQL Technical Reference for Version 4.1.1-alpha
Please note that when dumping multiple databases, --lock-tables will lock
tables for each database separately. So using this option will not guarantee
your tables will be logically consistent between databases. Tables in different
databases may be dumped in completely different states.
-K, --disable-keys
/*!40000 ALTER TABLE tb_name DISABLE KEYS */;
and
/*!40000 ALTER
TABLE tb_name ENABLE KEYS */; will be put in the output. This will make
loading the data into a MySQL 4.0 server faster as the indexes are created
after all data are inserted.
-n, --no-create-db
CREATE DATABASE /*!32312 IF NOT EXISTS*/ db_name; will not be put in the
output. The above line will be added otherwise, if a --databases or --alldatabases option was given.
-t, --no-create-info
Don’t write table creation information (the CREATE TABLE statement).
-d, --no-data
Don’t write any row information for the table. This is very useful if you just
want to get a dump of the structure for a table!
--opt
Same
as
--quick --add-drop-table --add-locks --extended-insert
--lock-tables. Should give you the fastest possible dump for reading into a
MySQL server.
-pyour_pass, --password[=your_pass]
The password to use when connecting to the server. If you specify no
‘=your_pass’ part, mysqldump you will be prompted for a password.
-P, --port=...
Port number to use for TCP/IP connections.
--protocol=(TCP | SOCKET | PIPE | MEMORY)
To specify the connect protocol to use. New in MySQL 4.1.
-q, --quick
Don’t buffer query, dump directly to stdout. Uses mysql_use_result() to do
this.
-Q, --quote-names
Quote table and column names within ‘‘’ characters.
-r, --result-file=...
Direct output to a given file. This option should be used in MSDOS, because
it prevents new line ‘\n’ from being converted to ‘\n\r’ (new line + carriage
return).
--single-transaction
This option issues a BEGIN SQL command before dumping data from server. It
is mostly useful with InnoDB tables and READ_COMMITTED transaction isolation
level, as in this mode it will dump the consistent state of the database at the
time then BEGIN was issued without blocking any applications.
Chapter 4: Database Administration
347
When using this option you should keep in mind that only transactional tables
will be dumped in a consistent state, for example, any MyISAM or HEAP tables
dumped while using this option may still change state.
The --single-transaction option was added in version 4.0.2. This option
is mutually exclusive with the --lock-tables option as LOCK TABLES already
commits a previous transaction internally.
-S /path/to/socket, --socket=/path/to/socket
The socket file to use when connecting to localhost (which is the default host).
--tables
Overrides option –databases (-B).
-T, --tab=path-to-some-directory
Creates a table_name.sql file, that contains the SQL CREATE commands,
and a table_name.txt file, that contains the data, for each give table. The
format of the ‘.txt’ file is made according to the --fields-xxx and --lines-xxx options. Note: This option only works if mysqldump is run on the same
machine as the mysqld daemon. You must use a MySQL account that has the
FILE privilege, and the login user/group that mysqld is running as (normally
user mysql, group mysql) must have permission to create/write a file at the
location you specify.
-u user_name, --user=user_name
The MySQL user name to use when connecting to the server. The default value
is your Unix login name.
-O name=value, --set-variable=name=value
Set the value of a variable. The possible variables are listed below. Please note
that --set-variable=name=value and -O name=value syntax is deprecated as
of MySQL 4.0. Use --name=value instead.
-v, --verbose
Verbose mode. Print out more information on what the program does.
-V, --version
Print version information and exit.
-w, --where=’where-condition’
Dump only selected records. Note that quotes are mandatory:
"--where=user=’jimf’" "-wuserid>1" "-wuserid<1"
-X, --xml Dumps a database as well formed XML
-x, --first-slave
Locks all tables across all databases.
--master-data
Like --first-slave, but also prints some CHANGE MASTER TO commands which
will later make your slave start from the right position in the master’s binlogs,
if you have set up your slave using this SQL dump of the master.
-O net_buffer_length=#, where # < 16M
When creating multi-row-insert statements (as with option --extended-insert
or --opt), mysqldump will create rows up to net_buffer_length length. If you
348
MySQL Technical Reference for Version 4.1.1-alpha
increase this variable, you should also ensure that the max_allowed_packet
variable in the MySQL server is bigger than the net_buffer_length.
The most normal use of mysqldump is probably for making a backup of whole databases.
See Section 4.5.1 [Backup], page 263.
mysqldump --opt database > backup-file.sql
You can read this back into MySQL with:
mysql database < backup-file.sql
or
mysql -e "source /path-to-backup/backup-file.sql" database
However, it’s also very useful to populate another MySQL server with information from a
database:
mysqldump --opt database | mysql ---host=remote-host -C database
It is possible to dump several databases with one command:
mysqldump --databases database1 [database2 ...] > my_databases.sql
If all the databases are wanted, one can use:
mysqldump --all-databases > all_databases.sql
4.9.8 mysqlhotcopy, Copying MySQL Databases and Tables
mysqlhotcopy is a Perl script that uses LOCK TABLES, FLUSH TABLES and cp or scp to
quickly make a backup of a database. It’s the fastest way to make a backup of the database
or single tables, but it can only be run on the same machine where the database directories
are. mysqlhotcopy works only on Unix, and it works only for MyISAM and ISAM tables.
mysqlhotcopy db_name [/path/to/new_directory]
mysqlhotcopy db_name_1 ... db_name_n /path/to/new_directory
mysqlhotcopy db_name./regex/
mysqlhotcopy supports the following options:
-?, --help
Display a help screen and exit
-u, --user=#
User for database login
-p, --password=#
Password to use when connecting to server
-P, --port=#
Port to use when connecting to local server
-S, --socket=#
Socket to use when connecting to local server
--allowold
Don’t abort if target already exists (rename it old)
Chapter 4: Database Administration
349
--keepold
Don’t delete previous (now renamed) target when done
--noindices
Don’t include full index files in copy to make the backup smaller and faster The
indexes can later be reconstructed with myisamchk -rq..
--method=#
Method for copy (cp or scp).
-q, --quiet
Be silent except for errors
--debug
Enable debug
-n, --dryrun
Report actions without doing them
--regexp=#
Copy all databases with names matching regexp
--suffix=#
Suffix for names of copied databases
--checkpoint=#
Insert checkpoint entry into specified db.table
--flushlog
Flush logs once all tables are locked.
--tmpdir=#
Temporary directory (instead of /tmp).
You can use perldoc mysqlhotcopy to get more complete documentation for
mysqlhotcopy.
mysqlhotcopy reads the groups [client] and [mysqlhotcopy] from the option files.
To be able to execute mysqlhotcopy you need write access to the backup directory, the
SELECT privilege for the tables you are about to copy and the MySQL RELOAD privilege (to
be able to execute FLUSH TABLES).
4.9.9 mysqlimport, Importing Data from Text Files
mysqlimport provides a command-line interface to the LOAD DATA INFILE SQL statement.
Most options to mysqlimport correspond directly to the same options to LOAD DATA INFILE.
See Section 6.4.8 [LOAD DATA], page 561.
mysqlimport is invoked like this:
shell> mysqlimport [options] database textfile1 [textfile2 ...]
For each text file named on the command-line, mysqlimport strips any extension from the
filename and uses the result to determine which table to import the file’s contents into. For
example, files named ‘patient.txt’, ‘patient.text’, and ‘patient’ would all be imported
into a table named patient.
mysqlimport supports the following options:
350
MySQL Technical Reference for Version 4.1.1-alpha
-c, --columns=...
This option takes a comma-separated list of field names as an argument. The
field list is used to create a proper LOAD DATA INFILE command, which is then
passed to MySQL. See Section 6.4.8 [LOAD DATA], page 561.
-C, --compress
Compress all information between the client and the server if both support
compression.
-#, --debug[=option_string]
Trace usage of the program (for debugging).
-d, --delete
Empty the table before importing the text file.
--fields-terminated-by=...
--fields-enclosed-by=...
--fields-optionally-enclosed-by=...
--fields-escaped-by=...
--lines-terminated-by=...
These options have the same meaning as the corresponding clauses for LOAD
DATA INFILE. See Section 6.4.8 [LOAD DATA], page 561.
-f, --force
Ignore errors. For example, if a table for a text file doesn’t exist, continue
processing any remaining files. Without --force, mysqlimport exits if a table
doesn’t exist.
--help
Display a help message and exit.
-h host_name, --host=host_name
Import data to the MySQL server on the named host. The default host is
localhost.
-i, --ignore
See the description for the --replace option.
--ignore-lines=n
Ignore first n lines of the datafile.
-l, --lock-tables
Lock all tables for writing before processing any text files. This ensures that
all tables are synchronised on the server.
-L, --local
Read input files from the client. By default, text files are assumed to be on the
server if you connect to localhost (which is the default host).
-pyour_pass, --password[=your_pass]
The password to use when connecting to the server. If you specify no
‘=your_pass’ part, mysqlimport you will be prompted for a password.
-P port_num, --port=port_num
TCP/IP port number to use for connection.
Chapter 4: Database Administration
351
--protocol=(TCP | SOCKET | PIPE | MEMORY)
To specify the connect protocol to use. New in MySQL 4.1.
-r, --replace
The --replace and --ignore options control handling of input records that
duplicate existing records on unique key values. If you specify --replace, new
rows replace existing rows that have the same unique key value. If you specify
--ignore, input rows that duplicate an existing row on a unique key value are
skipped. If you don’t specify either option, an error occurs when a duplicate
key value is found, and the rest of the text file is ignored.
-s, --silent
Silent mode. Write output only when errors occur.
-S /path/to/socket, --socket=/path/to/socket
The socket file to use when connecting to localhost (which is the default host).
-u user_name, --user=user_name
The MySQL user name to use when connecting to the server. The default value
is your Unix login name.
-v, --verbose
Verbose mode. Print out more information what the program does.
-V, --version
Print version information and exit.
Here is a sample run using mysqlimport:
$ mysql --version
mysql Ver 9.33 Distrib 3.22.25, for pc-linux-gnu (i686)
$ uname -a
Linux xxx.com 2.2.5-15 #1 Mon Apr 19 22:21:09 EDT 1999 i586 unknown
$ mysql -e ’CREATE TABLE imptest(id INT, n VARCHAR(30))’ test
$ ed
a
100
Max Sydow
101
Count Dracula
.
w imptest.txt
32
q
$ od -c imptest.txt
0000000
1
0
0 \t
M
a
x
S
y
d
o
w \n
1
0000020
1 \t
C
o
u
n
t
D
r
a
c
u
l
a
0000040
$ mysqlimport --local test imptest.txt
test.imptest: Records: 2 Deleted: 0 Skipped: 0 Warnings: 0
$ mysql -e ’SELECT * FROM imptest’ test
+------+---------------+
| id
| n
|
+------+---------------+
0
\n
352
MySQL Technical Reference for Version 4.1.1-alpha
| 100 | Max Sydow
|
| 101 | Count Dracula |
+------+---------------+
4.9.10 mysqlshow, Showing Databases, Tables, and Columns
mysqlshow can be used to quickly look at which databases exist, their tables, and the table’s
columns.
With the mysql program you can get the same information with the SHOW commands. See
Section 4.6.8 [SHOW], page 287.
mysqlshow is invoked like this:
shell> mysqlshow [OPTIONS] [database [table [column]]]
• If no database is given, all matching databases are shown.
• If no table is given, all matching tables in the database are shown.
• If no column is given, all matching columns and column types in the table are shown.
Note that in newer MySQL versions, you only see those database/tables/columns for which
you have some privileges.
If the last argument contains a shell or SQL wildcard (*, ?, % or _) then only what’s matched
by the wildcard is shown. If a database name contains any underscores, those should be
escaped with backslash (some Unix shells will require two), in order to get tables / columns
properly. ’*’ are converted into SQL ’%’ wildcard and ’ ?’ into SQL ’ ’ wildcard. This may
cause some confusion when you try to display the columns for a table with a _ as in this
case mysqlshow only shows you the table names that match the pattern. This is easily fixed
by adding an extra % last on the command-line (as a separate argument).
4.9.11 mysql_config, Get compile options for compiling clients
mysql_config provides you with useful information how to compile your MySQL client and
connect it to MySQL.
mysql_config supports the following options:
--cflags
Compiler flags to find include files and critical ccompiler flags and defines used
when compiling the libmysqlclient library.
--include
Compiler options to find MySQL include files. (Normally one would use -cflags instead of this)
--libs
Libraries and options required to link with the MySQL client library.
--libs_r
Libraries and options required to link with the thread-safe MySQL client library.
--socket
The default socket name, defined when configuring MySQL.
--port
The default port number, defined when configuring MySQL.
--version
Version number and version for the MySQL distribution.
Chapter 4: Database Administration
353
--libmysqld-libs or --embedded
Libraries and options required to link with the MySQL embedded server.
If you execute mysql_config without any options it will print all options it supports plus
the value of all options:
shell> mysql_config
Usage: /usr/local/mysql/bin/mysql_config [OPTIONS]
Options:
--cflags
[-I/usr/local/mysql/include/mysql -mcpu=pentiumpro]
--include
[-I/usr/local/mysql/include/mysql]
--libs
[-L/usr/local/mysql/lib/mysql -lmysqlclient -lz -lcrypt -ln
--libs_r
[-L/usr/local/mysql/lib/mysql -lmysqlclient_r -lpthread -lz
--socket
[/tmp/mysql.sock]
--port
[3306]
--version
[4.0.16]
--libmysqld-libs [-L/usr/local/mysql/lib/mysql -lmysqld -lpthread -lz -lcryp
You can use this to compile a MySQL client by as follows:
CFG=/usr/local/mysql/bin/mysql_config
sh -c "gcc -o progname ‘$CFG --cflags‘ progname.c ‘$CFG --libs‘"
4.9.12 perror, Explaining Error Codes
For most system errors MySQL will, in addition to a internal text message, also print the
system error code in one of the following styles: message ... (errno: #) or message ...
(Errcode: #).
You can find out what the error code means by either examining the documentation for
your system or use the perror utility.
perror prints a description for a system error code, or an MyISAM/ISAM storage engine
(table handler) error code.
perror is invoked like this:
shell> perror [OPTIONS] [ERRORCODE [ERRORCODE...]]
Example:
shell> perror 13 64
Error code 13: Permission denied
Error code 64: Machine is not on the network
Note that the error messages are mostly system dependent!
4.9.13 How to Run SQL Commands from a Text File
The mysql client typically is used interactively, like this:
shell> mysql database
However, it’s also possible to put your SQL commands in a file and tell mysql to read its
input from that file. To do so, create a text file ‘text_file’ that contains the commands
you wish to execute. Then invoke mysql as shown here:
354
MySQL Technical Reference for Version 4.1.1-alpha
shell> mysql database < text_file
You can also start your text file with a USE db_name statement. In this case, it is unnecessary
to specify the database name on the command line:
shell> mysql < text_file
If you are already running mysql, you can execute an SQL script file using the source
command:
mysql> source filename;
For more information about batch mode, Section 3.5 [Batch mode], page 184.
4.10 The MySQL Log Files
MySQL has several different log files that can help you find out what’s going on inside
mysqld:
Log file
The error log
The isam log
Description
Problems encountering starting, running or stopping mysqld.
Logs all changes to the ISAM tables. Used only for debugging the isam
code.
The query log
Established connections and executed queries.
The update log
Deprecated: Stores all statements that changes data
The binary log
Stores all statements that changes something. Used also for replication
The slow log
Stores all queries that took more than long_query_time seconds to
execute or didn’t use indexes.
All logs can be found in the mysqld data directory. You can force mysqld to reopen the
log files (or in some cases switch to a new log) by executing FLUSH LOGS. See Section 4.6.4
[FLUSH], page 285.
4.10.1 The Error Log
The error log file contains information indicating when mysqld was started and stopped
and also any critical errors found when running.
If mysqld dies unexpectedly and mysqld_safe needs to restart mysqld, mysqld_safe will
write a restarted mysqld row in this file. This log also holds a warning if mysqld notices
a table that needs to be automatically checked or repaired.
On some operating systems, the error log will contain a stack trace for where mysqld died.
This can be used to find out where mysqld died. See Section E.1.4 [Using stack trace],
page 1023.
Beginning with MySQL 4.0.10 you can specify where mysqld stores the error log file with
the option --log-error[=filename]. If no file name is given mysqld will use mysql-datadir/’hostname’.err on Unix and ‘\mysql\data\mysql.err’ on Windows. If you execute
flush logs the old file will be prefixed with --old and mysqld will create a new empty log
file.
In older MySQL versions the error log handling was done by mysqld_safe which redirected
the error file to ’hostname’.err. One could change this file name with the option --errlog=filename.
Chapter 4: Database Administration
355
If you don’t specify --log-error or if you use the --console option the errors will be
written to stderr (the terminal).
On Windows, the output is always written to the .err file if --console is not given.
4.10.2 The General Query Log
If you want to know what happens within mysqld, you should start it with --log[=file].
This will log all connections and queries to the log file (by default named ‘’hostname’.log’).
This log can be very useful when you suspect an error in a client and want to know exactly
what mysqld thought the client sent to it.
Older versions of the mysql.server script (from MySQL 3.23.4 to 3.23.8) pass safe_mysqld
a --log option (enable general query log). If you need better performance when you
start using MySQL in a production environment, you can remove the --log option from
mysql.server or change it to --log-bin. See Section 4.10.4 [Binary log], page 356.
The entries in this log are written as mysqld receives the questions. This may be different
from the order in which the statements are executed. This is in contrast to the update log
and the binary log which are written after the query is executed, but before any locks are
released.
4.10.3 The Update Log
Note: the update log has been deprecated and replaced by the binary log. See Section 4.10.4
[Binary log], page 356. The binary log can do anything the old update log could do, and
more. The update log will be removed in MySQL 5.0.
When started with the --log-update[=file_name] option, mysqld writes a log file containing all SQL commands that update data. If no filename is given, it defaults to the name
of the host machine. If a filename is given, but it doesn’t contain a path, the file is written
in the data directory. If ‘file_name’ doesn’t have an extension, mysqld will create log file
names like so: ‘file_name.###’, where ### is a number that is incremented each time you
execute mysqladmin refresh, execute mysqladmin flush-logs, execute the FLUSH LOGS
statement, or restart the server.
Note: for the above scheme to work, you must not create your own files with the same
filename as the update log + some extensions that may be regarded as a number, in the
directory used by the update log!
If you use the --log or -l options, mysqld writes a general log with a filename of
‘hostname.log’, and restarts and refreshes do not cause a new log file to be generated
(although it is closed and reopened). In this case you can copy it (on Unix) by doing:
mv hostname.log hostname-old.log
mysqladmin flush-logs
cp hostname-old.log to-backup-directory
rm hostname-old.log
Update logging is smart because it logs only statements that really update data. So an
UPDATE or a DELETE with a WHERE that finds no rows is not written to the log. It even skips
UPDATE statements that set a column to the value it already has.
356
MySQL Technical Reference for Version 4.1.1-alpha
The update logging is done immediately after a query completes but before any locks are
released or any commit is done. This ensures that the log will be logged in the execution
order.
If you want to update a database from update log files, you could do the following (assuming
your update logs have names of the form ‘file_name.###’):
shell> ls -1 -t -r file_name.[0-9]* | xargs cat | mysql
ls is used to get all the log files in the right order.
This can be useful if you have to revert to backup files after a crash and you want to redo
the updates that occurred between the time of the backup and the crash.
4.10.4 The Binary Log
The binary log has replaced the old update log. The update log will be removed in MySQL
5.0. The binary log contains all information that is available in the update log in a more
efficient format and in a manner that is transactionally safe.
The binary log, like the old update log, only logs statements that really update data. So
an UPDATE or a DELETE with a WHERE that finds no rows is not written to the log. It even
skips UPDATE statements that set a column to the value it already has.
The primary purpose of the binary log is to be able to update the database during a restore
operation as fully as possible, as the binary log would contain all updates done after a
backup was made.
The binary log is also used when you are replicating a slave from a master. See Section 4.11
[Replication], page 360.
The binary log also contains information about how long each query took that updated the
database. It doesn’t contain queries that don’t modify any data. If you want to log all
queries (for example to find a problem query) you should use the general query log. See
Section 4.10.2 [Query log], page 355.
When started with the --log-bin[=file_name] option, mysqld writes a log file containing
all SQL commands that update data. If no file name is given, it defaults to the name of
the host machine followed by -bin. If file name is given, but it doesn’t contain a path, the
file is written in the data directory.
If you supply an extension to --log-bin=filename.extension, the extension will be silenty
removed.
To the binary log filename mysqld will append an extension that is a number that is incremented each time you execute mysqladmin refresh, execute mysqladmin flush-logs,
execute the FLUSH LOGS statement or restart the server. A new binary log will also automatically be created when the current one’s size reaches max_binlog_size. Note if you
are using transactions: a transaction is written in one chunk to the binary log, hence it is
never split between several binary logs. Therefore, if you have big transactions, you may
see binlogs bigger than max_binlog_size.
You can delete all binary log files with the RESET MASTER command (see Section 4.6.5
[RESET], page 286), or only some of them with PURGE MASTER LOGS (see Section 4.11.7 [Replication Master SQL], page 381).
Chapter 4: Database Administration
357
You can use the following options to mysqld to affect what is logged to the binary log
(please make sure to read the notes which follow this table):
Option
Description
binlog-do-db=database_name
Tells the master that it should log updates to the binary log if the current database (that is, the one selected by USE) database is ’database name’. All others databases which are not explicitly mentioned are
ignored. Note that if you use this you should ensure
that you only do updates in the current database. (Example: binlog-do-db=some_database)
Example of what does not work as you could expect
it: if the server is started with binlog-do-db=sales,
and you do USE prices; UPDATE sales.january SET
amount=amount+1000;, this query will not be written
into the binary log.
binlog-ignore-db=database_
name
Tells the master that updates where the current
database (that is, the one selected by USE) is
’database name’ should not be stored in the binary
log. Note that if you use this you should ensure that
you only do updates in the current database. (Example: binlog-ignore-db=some_database)
Example of what does not work as you could
expect it: if the server is started with binlogignore-db=sales, and you do USE prices; UPDATE
sales.january SET amount=amount+1000;,
this
query will be written into the binary log.
The rules are evaluated in the following order, to decide if the query should be written to
the binary log or not:
1. Are there binlog-do-db or binlog-ignore-db rules?
• No: write the query to the binlog and exit.
• Yes: go to step below.
2. So there are some rules (binlog-do-db or binlog-ignore-db or both). Is there a
current database (has any database been selected by USE?)?
• No: do NOT write the query, and exit.
• Yes: go to step below.
3. There is a current database. Are there some binlog-do-db rules?
• Yes: Does the current database match any of the binlog-do-db rules?
• Yes: write the query and exit.
• No: do NOT write the query, and exit.
• No: go to step below.
4. There are some binlog-ignore-db rules. Does the current database match any of the
binlog-ignore-db rules?
358
MySQL Technical Reference for Version 4.1.1-alpha
• Yes: do not write the query, and exit.
• No: write the query and exit.
So for example, a slave running with only binlog-do-db=sales will not write to the binlog
any query whose current database is different from sales (in other words, binlog-do-db
can sometimes mean “ignore other databases”).
To be able to know which different binary log files have been used, mysqld will also create
a binary log index file that contains the name of all used binary log files. By default this
has the same name as the binary log file, with the extension ’.index’. You can change
the name of the binary log index file with the --log-bin-index=[filename] option. You
should not manually edit this file while mysqld is running; doing this would confuse mysqld.
If you are using replication, you should not delete old binary log files until you are sure that
no slave will ever need to use them. One way to do this is to do mysqladmin flush-logs
once a day and then remove any logs that are more than 3 days old. You can remove them
manually, or preferably using PURGE MASTER LOGS (see Section 4.11.7 [Replication Master
SQL], page 381) which will also safely update the binary log index file for you (and which
can take a date argument since MySQL 4.1)
A connection with the SUPER privilege can disable the binary logging of its queries using
SET SQL_LOG_BIN=0. See Section 4.11.7 [Replication Master SQL], page 381.
You can examine the binary log file with the mysqlbinlog utility. For example, you can
update a MySQL server from the binary log as follows:
shell> mysqlbinlog log-file | mysql -h server_name
See Section 4.9.5 [mysqlbinlog], page 341 for more information on the mysqlbinlog utility
and how to use it.
If you are using BEGIN [WORK] or SET AUTOCOMMIT=0, you must use the MySQL binary log
for backups instead of the old update log, which will be removed in MySQL 5.0.
The binary logging is done immediately after a query completes but before any locks are
released or any commit is done. This ensures that the log will be logged in the execution
order.
Updates to non-transactional tables are stored in the binary log immediately after execution.
For transactional tables such as BDB or InnoDB tables, all updates (UPDATE, DELETE or
INSERT) that change tables are cached until a COMMIT command is sent to the server. At
this point mysqld writes the whole transaction to the binary log before the COMMIT is
executed. Every thread will, on start, allocate a buffer of binlog_cache_size to buffer
queries. If a query is bigger than this, the thread will open a temporary file to store the
transaction. The temporary file will be deleted when the thread ends.
The max_binlog_cache_size (default 4G) can be used to restrict the total size used to
cache a multi-query transaction. If a transaction is bigger than this it will fail and roll
back.
If you are using the update or binary log, concurrent inserts will be converted to normal
inserts when using CREATE ... SELECT or INSERT ... SELECT. This is to ensure that you
can recreate an exact copy of your tables by applying the log on a backup.
Chapter 4: Database Administration
359
4.10.5 The Slow Query Log
When started with the --log-slow-queries[=file_name] option, mysqld writes a log file
containing all SQL commands that took more than long_query_time seconds to execute.
The time to get the initial table locks are not counted as execution time.
The slow query log is logged after the query is executed and after all locks has been released.
This may be different from the order in which the statements are executed.
If no file name is given, it defaults to the name of the host machine suffixed with -slow.log.
If a filename is given, but doesn’t contain a path, the file is written in the data directory.
The slow query log can be used to find queries that take a long time to execute and are
thus candidates for optimisation. With a large log, that can become a difficult task. You
can pipe the slow query log through the mysqldumpslow command to get a summary of the
queries which appear in the log.
You are using --log-long-format then also queries that are not using indexes are printed.
See Section 4.1.1 [Command-line options], page 198.
4.10.6 Log File Maintenance
The MySQL Server can create a number of different log files, which make it easy to see
what is going on. See Section 4.10 [Log Files], page 354. However, you must clean up these
files regularly, to ensure that the logs don’t take up too much disk space.
When using MySQL with log files, you will want to remove/backup old log files from time
to time and tell MySQL to start logging to new files. See Section 4.5.1 [Backup], page 263.
On a Linux (Red Hat) installation, you can use the mysql-log-rotate script for this. If
you installed MySQL from an RPM distribution, the script should have been installed
automatically. Note that you should be careful with this script if you are using the binary
log for replication!
On other systems you must install a short script yourself that you start from cron to handle
log files.
You can force MySQL to start using new log files by using mysqladmin flush-logs or by
using the SQL command FLUSH LOGS. If you are using MySQL Version 3.21, you must use
mysqladmin refresh.
The above command does the following:
• If standard logging (--log) or slow query logging (--log-slow-queries) is used, closes
and reopens the log file (‘mysql.log’ and ‘‘hostname‘-slow.log’ as default).
• If update logging (--log-update) is used, closes the update log and opens a new log
file with a higher sequence number.
If you are using only an update log, you only have to flush the logs and then move away the
old update log files to a backup. If you are using the normal logging, you can do something
like:
shell> cd mysql-data-directory
shell> mv mysql.log mysql.old
shell> mysqladmin flush-logs
and then take a backup and remove ‘mysql.old’.
360
MySQL Technical Reference for Version 4.1.1-alpha
4.11 Replication in MySQL
Replication capabilities allowing the databases on one MySQL server to be duplicated on
another were introduced in MySQL version 3.23.15. This section describes the various replication features in MySQL. It serves as a reference to the options available with replication.
You will be introduced to replication and learn how to implement it. Toward that end,
there are some frequently asked questions, descriptions of problems, and how to solve them.
We suggest that you visit our website at http://www.mysql.com/ often and read updates to
this section. Replication is constantly being improved, and we update the manual frequently
with the most current information.
4.11.1 Introduction
Starting in Version 3.23.15, MySQL supports one-way replication internally. One server
acts as the master, while one or more other servers act as slaves. The master server keeps a
binary log of updates (see Section 4.10.4 [Binary log], page 356). It also maintains an index
file of the binary logs to keep track of log rotation. Each slave, upon connecting, informs
the master where it left off since the last successfully propagated update, catches up any
updates that have occurred since then, and then blocks and waits for the master to notify
it of new updates.
A slave can also serve as a master if you set up chained replication servers.
Note that when you are using replication, all updates to the tables that are replicated
should be performed on the master server. Otherwise, you must always be careful to avoid
conflicts between updates that users make to tables on the master and updates that they
make to tables on the slave.
One-way replication has benefits for robustness, speed, and system administration:
• Robustness is increased with a master/slave setup. In the event of problems with the
master, you can switch to the slave as a backup.
• The extra speed is achieved by splitting the load for processing client queries between
the master and slave servers, resulting in better client response time. SELECT queries
may be sent to the slave to reduce query processing load of the master. Queries that
modify data should still be sent to the master so that the master and slave to not get
out of sync. This load-balancing strategy if effective if non-updating queries dominate,
but that is the normal case.
• Another benefit of using replication is that one can get non-disturbing backups of the
system by doing a backup on a slave instead of doing it on the master. See Section 4.5.1
[Backup], page 263.
4.11.2 Replication Implementation Overview
MySQL replication is based on the master server keeping track of all changes to your
database (updates, deletes, etc) in the binary log (see Section 4.10.4 [Binary log], page 356).
Each slave server receives from the master the saved queries that the master has recorded
in its binary log, so that the slave can execute the same queries on its copy of the data.
Chapter 4: Database Administration
361
It is very important to realise that the binary log is simply a record starting from a fixed
point in time (the moment you enable binary logging). Any slaves that you set up will need
copies of the databases on your master as they existed at the moment you enabled binary
logging on the master. If you start your slaves with data that is not the same as what was
on the master when the binary log was started, your slaves may fail.
The following table indicates master/slave replication compatibility between different versions of MySQL.
Slave
Master
3.23.33
and up
yes
Master Master Master
4.0.0
4.0.1
4.0.3 and
up
no
no
no
3.23.33
and up
Slave
4.0.0
no
yes
no
no
Slave
4.0.1
yes
no
yes
no
Slave
4.0.3 and yes
no
no
yes
up
As a general rule, it’s always recommended to use recent MySQL versions, because replication capabilities are continually being improved. With regard to version 4.0, we recommend
using same version for both the master and the slave, with the exception that MySQL 4.0.2
is not recommended for replication.
Note that when you upgrade a master from MySQL 3.23 to MySQL 4.0 (or 4.1) you should
not restart replication using old 3.23 binary logs, because this will unfortunately confuse
the 4.0 slave. The upgrade can safely be done this way, assuming you have a 3.23 master
to upgrade and you have 4.0 slaves:
1. Block all updates on the master (FLUSH TABLES WITH READ LOCK).
2. Wait until all the slaves have caught up all changes from the master (use SHOW MASTER
STATUS on the master, and SELECT MASTER_POS_WAIT() on the slaves). Then run STOP
SLAVE on the slaves.
3. Shut down MySQL on the master and upgrade the master to MySQL 4.0.
4. Restart MySQL on the master. Record the name ‘<name>’ of the master’s newly created
binary log. You can obtain the name of the file by issuing SHOW MASTER STATUS on the
master. Then issue these commands on each slave:
mysql> CHANGE MASTER TO MASTER_LOG_FILE=’<name>’, MASTER_LOG_POS=4;
mysql> START SLAVE;
If you also must upgrade your slaves from 3.23 to 4.0, you should first upgrade your slaves:
Shut down each one, upgrade it, and restart it. Then upgrade the master as just described.
Starting from 4.0.0, you can use LOAD DATA FROM MASTER to set up a slave. Be aware that
LOAD DATA FROM MASTER currently works only if all the tables on the master are MyISAM type.
Also, this statement acquires a global read lock, so no writes are possible while the tables
are being transferred from the master. When we implement lock-free hot table backup (in
MySQL 5.0), this global read lock will no longer be necessary.
Due to these limitations, we recommend that at this point you use LOAD DATA FROM MASTER
only if the dataset on the master is relatively small, or if a prolonged read lock on the master
is acceptable. While the actual speed of LOAD DATA FROM MASTER may vary from system to
362
MySQL Technical Reference for Version 4.1.1-alpha
system, a good rule of thumb for how long it is going to take is 1 second per 1 MB of the
datafile. You will get close to the estimate if both master and slave are equivalent to 700
MHz Pentium and are connected through a 100 MBit/s network. Of course, this is only a
rough estimate.
Once a slave is properly configured and running, it will simply connect to the master and
wait for updates to process. If the master goes away or the slave loses connectivity with your
master, it will keep trying to connect periodically until it is able to reconnect and resume
listening for updates. The retry interval is controlled by the --master-connect-retry
option. The default is 60 seconds.
Each slave keeps track of where it left off. The master server has no knowledge of how many
slaves there are or which ones are up-to-date at any given time.
4.11.3 Replication Implementation Details
Three threads are involved in replication: one on the master and two on the slave. When
START SLAVE is issued, the I/O thread is created on the slave. It connects to the master
and asks it to send the queries recorded in its binlogs. Then one thread is created on the
master to send these binlogs. This thread is identified by Binlog Dump in SHOW PROCESSLIST
output on the master. The I/O thread reads what the master Binlog Dump thread sends
and simply copies it to some local files in the slave’s data directory called relay logs. The
last thread, the SQL thread, is created on the slave; it reads the relay logs and executes the
queries it contains.
Note that the master has one thread for each currently connected slave server.
With SHOW PROCESSLIST you can know what is happening on the master and on the slave
as regards replication.
The following example illustrates how the three threads show up in SHOW PROCESSLIST.
The output format is that used by SHOW PROCESSLIST as of MySQL version 4.0.15, when
the content of the State column was changed to be more meaningful compared to earlier
versions.
On the master server, the output looks like this:
mysql> SHOW PROCESSLIST\G
*************************** 1. row ***************************
Id: 2
User: root
Host: localhost:32931
db: NULL
Command: Binlog Dump
Time: 94
State: Has sent all binlog to slave; waiting for binlog to be updated
Info: NULL
On the slave server, the output looks like this:
mysql> SHOW PROCESSLIST\G
*************************** 1. row ***************************
Id: 10
User: system user
Chapter 4: Database Administration
363
Host:
db: NULL
Command: Connect
Time: 11
State: Waiting for master to send event
Info: NULL
*************************** 2. row ***************************
Id: 11
User: system user
Host:
db: NULL
Command: Connect
Time: 11
State: Has read all relay log; waiting for the slave I/O thread to update it
Info: NULL
Here thread 2 is on the master. Thread 10 is the I/O thread on the slave. Thread 11 is the
SQL thread on the slave; note that the value in the Time column can tell how late the slave
is compared to the master (see Section 4.11.9 [Replication FAQ], page 391).
The following list shows the most common states you will see in the State column for the
master’s Binlog Dump thread. If you don’t see this thread on a master server, replication
is not running.
Sending binlog event to slave
Binlogs consist of events, where an event is usually a query plus some other
information. The thread has read an event from the binlog and is sending it to
the slave.
Finished reading one binlog; switching to next binlog
The thread has finished reading a binlog file and is opening the next one to
send to the slave.
Has sent all binlog to slave; waiting for binlog to be updated
The thread has read all binary log files and is idle. It is waiting for new events
to appear in the binary log as a result of new update queries being executed on
the master.
Waiting to finalize termination
A very brief state that happens as the thread is stopping.
Here are the most common states you will see in the State column for the I/O thread of a
slave server. Beginning with MySQL 4.1.1, this state also appears in the Slave_IO_State
column of SHOW SLAVE STATUS output. This means that you can get a good view of what is
happening by using only SHOW SLAVE STATUS.
Connecting to master
The thread is attempting to connect to the master.
Checking master version
A very brief state that happens just after the connection to the master is established.
364
MySQL Technical Reference for Version 4.1.1-alpha
Registering slave on master
A very brief state that happens just after the connection to the master is established.
Requesting binlog dump
A very brief state that happens just after the connection to the master is established. The thread sends to the master a request for the contents of its binlogs,
starting from the requested binlog filename and position.
Waiting to reconnect after a failed binlog dump request
If the binlog dump request failed (due to disconnection), the thread goes into
this state while it sleeps. The thread sleeps for master-connect-retry seconds
before retrying.
Reconnecting after a failed binlog dump request
Then the thread tries to reconnect to the master.
Waiting for master to send event
The thread has connected and is waiting for binlog events to arrive. This can
last for a long time if the master is idle. If the wait lasts for slave_read_
timeout seconds, a timeout will occur. At that point, the thread will consider
the connection to be broken and make an attempt to reconnect.
Queueing master event to the relay log
The thread has read an event and is copying it to the relay log so the SQL
thread can process it.
Waiting to reconnect after a failed master event read
An error occurred while reading (due to disconnection). The thread is sleeping
for master-connect-retry seconds before attempting to reconnect.
Reconnecting after a failed master event read
Then the thread tries to reconnect. When connection is established again, the
state will become Waiting for master to send event.
Waiting for the slave SQL thread to free enough relay log space
You are using a non-zero relay_log_space_limit value, and the relay logs
have grown so much that their combined size exceeds this value. The I/O
thread is waiting until the SQL thread frees enough space by processing relay
log contents so that it can delete some relay log files.
Waiting for slave mutex on exit
A very brief state that happens as the thread is stopping.
Here are the most common states you will see in the State column for the SQL thread of
a slave server:
Reading event from the relay log
The thread has read an event from the relay log so that it can process it.
Has read all relay log; waiting for the slave I/O thread to update it
The thread has processed all events in the relay log files and is waiting for the
I/O thread to write new events to the relay log.
Chapter 4: Database Administration
365
Waiting for slave mutex on exit
A very brief state that happens as the thread is stopping.
The State column for the I/O thread may also show a query string. This indicates that the
thread has read an event from the relay log, extracted the query from it and is executing
the query.
Before MySQL 4.0.2, the slave I/O and SQL threads were combined as a single thread, and
no relay log files were used. The advantage of using two threads is that it separates query
reading and query execution into two independent tasks, so the task of reading queries is
not slowed down if query execution is slow. For example, if the slave server has not been
running for a while, its I/O thread can quickly fetch all the binlog contents from the master
when the slave starts, even if the SQL thread lags far behind and may take hours to catch
up. If the slave stops before the SQL thread has executed all the fetched queries, the I/O
thread has at least fetched everything so that a safe copy of the queries is locally stored in
the slave’s relay logs for execution when next the slave starts. This allows the binlogs to be
purged on the master, because it no longer need wait for the slave to fetch their contents.
By default, relay logs are named using filenames of the form ‘host_name-relay-bin.nnn’,
where host_name is the name of the slave server host, and nnn is a sequence number.
Successive relay log files are created using successive sequence numbers, beginning with
001. The slave keeps track of relay logs currently in use in an index file. The default relay
log index filename is ‘host_name-relay-bin.index’. By default these files are created in
the slave’s data directory. The default filenames may be overridden with the --relay-log
and --relay-log-index server options.
Relay logs have the same format as binary logs, so they can be read with mysqlbinlog. A
relay log is automatically deleted by the SQL thread as soon as it no longer needs it (that
is, as soon as it has executed all its events). There is no command to delete relay logs,
because the SQL thread takes care of doing so. However, from MySQL 4.0.14, FLUSH LOGS
rotates relay logs, which will influence when the SQL thread deletes them.
A new relay log is created under the following conditions:
• The first time the I/O thread starts after the slave server starts. (In MySQL 5.0, a
new relay log will be created each time the I/O thread starts, not just the first time.)
• A FLUSH LOGS statement is issued (4.0.14 and up only).
• The size of the current relay log file becomes too big. The meaning of “too big” is
determined as follows:
− max_relay_log_size, if max_relay_log_size > 0
− max_binlog_size, if max_relay_log_size = 0 or MySQL is older than 4.0.14
A slave replication server creates additional two small files in the data directory. These
files are named ‘master.info’ and ‘relay-log.info’ by default. They contain information
like that shown in the output of the SHOW SLAVE STATUS statement (see Section 4.11.8
[Replication Slave SQL], page 382 for a description of this command). As disk files they
survive slave’s shutdown. The next time the slave starts up, it can read these files to know
how far it has proceeded in reading binlogs from the master and in processing its own relay
logs.
The ‘master.info’ file is updated by the I/O thread. The correspondance between the
lines in the file and the columns displayed by SHOW SLAVE STATUS is as follows:
366
Line
1
2
3
4
5
6
7
MySQL Technical Reference for Version 4.1.1-alpha
Description
Master_Log_File
Read_Master_Log_Pos
Master_Host
Master_User
Password (not shown by SHOW SLAVE STATUS)
Master_Port
Connect_Retry
The ‘relay-log.info’ file is updated by the SQL thread. The correspondance between the
lines in the file and the columns displayed by SHOW SLAVE STATUS is as follows:
Line
1
2
3
4
Description
Relay_Log_File
Relay_Log_Pos
Relay_Master_Log_File
Exec_Master_Log_Pos
When you back up your slave’s data, you should back up these 2 small files as well, along
with the relay log files. because they are needed to resume replication after you restore the
slave’s data. If you lose the relay logs but still have the ‘relay-log.info’ file, you can
check it to determine how far the SQL thread has executed in the master binlogs. Then you
can use CHANGE MASTER TO with the MASTER_RELAY_LOG and MASTER_RELAY_POS options to
tell the slave to re-read the binlogs from that point. This requires that the binlogs still exist