MySQL Reference Manual
MySQL Reference Manual
MySQL Reference Manual
Table of Contents
Preface ............................................................................................................ xxiv
1. General Information ........................................................................................... 1
1.1. About This Manual .................................................................................. 1
1.2. Conventions Used in This Manual .............................................................. 2
1.3. Overview of MySQL AB .......................................................................... 3
1.4. Overview of the MySQL Database Management System ................................ 4
1.4.1. History of MySQL ........................................................................ 5
1.4.2. The Main Features of MySQL ......................................................... 6
1.4.3. MySQL Stability .......................................................................... 8
1.4.4. How Big MySQL Tables Can Be ..................................................... 9
1.4.5. Year 2000 Compliance .................................................................10
1.5. Overview of the MaxDB Database Management System ................................11
1.5.1. What is MaxDB? .........................................................................12
1.5.2. History of MaxDB .......................................................................12
1.5.3. Features of MaxDB ......................................................................13
1.5.4. Licensing and Support ..................................................................13
1.5.5. Feature Differences Between MaxDB and MySQL ............................13
1.5.6. Interoperability Features Between MaxDB and MySQL ......................14
1.5.7. MaxDB-Related Links ..................................................................14
1.6. MySQL Development Roadmap ................................................................15
1.6.1. MySQL 4.0 in a Nutshell ...............................................................15
1.6.2. MySQL 4.1 in a Nutshell ...............................................................17
1.6.3. What's New in MySQL 5.0 ............................................................19
1.7. MySQL Information Sources ....................................................................20
1.7.1. MySQL Mailing Lists ...................................................................20
1.7.2. MySQL Community Support on IRC (Internet Relay Chat) ..................26
1.7.3. MySQL Community Support at the MySQL Forums ..........................26
1.8. MySQL Standards Compliance .................................................................27
1.8.1. What Standards MySQL Follows ....................................................28
1.8.2. Selecting SQL Modes ...................................................................28
1.8.3. Running MySQL in ANSI Mode ....................................................28
1.8.4. MySQL Extensions to Standard SQL ...............................................28
1.8.5. MySQL Differences from Standard SQL ..........................................31
1.8.6. How MySQL Deals with Constraints ...............................................37
2. Installing MySQL .............................................................................................40
2.1. General Installation Issues .......................................................................40
2.1.1. Operating Systems Supported by MySQL .........................................40
2.1.2. Choosing Which MySQL Distribution to Install .................................42
2.1.3. How to Get MySQL .....................................................................53
2.1.4. Verifying Package Integrity Using MD5 Checksums or GnuPG ............53
2.1.5. Installation Layouts ......................................................................56
2.2. Standard MySQL Installation Using a Binary Distribution .............................58
2.3. Installing MySQL on Windows .................................................................58
2.3.1. Windows System Requirements ......................................................58
2.3.2. Choosing An Installation Package ...................................................59
2.3.3. Installing MySQL with the Automated Installer .................................60
2.3.4. Using the MySQL Installation Wizard .............................................60
2.3.5. Using the Configuration Wizard .....................................................63
2.3.6. Installing MySQL from a Noinstall Zip Archive ................................67
2.3.7. Extracting the Install Archive .........................................................67
2.3.8. Creating an Option File .................................................................68
2.3.9. Selecting a MySQL Server type ......................................................69
2.3.10. Starting the Server for the First Time .............................................70
2.3.11. Starting MySQL from the Windows Command Line .........................71
2.3.12. Starting MySQL as a Windows Service ..........................................72
2.3.13. Testing The MySQL Installation ...................................................74
2.3.14. Troubleshooting a MySQL Installation Under Windows ....................75
iv
MySQL Reference Manual
2.3.15. Upgrading MySQL on Windows ...................................................76
2.3.16. MySQL on Windows Compared to MySQL on Unix ........................77
2.4. Installing MySQL on Linux ......................................................................80
2.5. Installing MySQL on Mac OS X ...............................................................82
2.6. Installing MySQL on NetWare .................................................................84
2.7. Installing MySQL on Other Unix-Like Systems ...........................................86
2.8. MySQL Installation Using a Source Distribution ..........................................89
2.8.1. Source Installation Overview .........................................................90
2.8.2. Typical configure Options ........................................................92
2.8.3. Installing from the Development Source Tree ....................................95
2.8.4. Dealing with Problems Compiling MySQL .......................................98
2.8.5. MIT-pthreads Notes ................................................................... 101
2.8.6. Installing MySQL from Source on Windows ................................... 103
2.8.7. Compiling MySQL Clients on Windows ........................................ 106
2.9. Post-Installation Setup and Testing .......................................................... 106
2.9.1. Windows Post-Installation Procedures ........................................... 107
2.9.2. Unix Post-Installation Procedures ................................................. 108
2.9.3. Securing the Initial MySQL Accounts ............................................ 118
2.10. Upgrading MySQL ............................................................................. 121
2.10.1. Upgrading from Version 5.0 ....................................................... 122
2.10.2. Upgrading from Version 4.1 to 5.0 .............................................. 122
2.10.3. Upgrading from Version 4.0 to 4.1 .............................................. 125
2.10.4. Upgrading from Version 3.23 to 4.0 ............................................. 131
2.10.5. Upgrading from Version 3.22 to 3.23 ........................................... 135
2.10.6. Upgrading from Version 3.21 to 3.22 ........................................... 137
2.10.7. Upgrading from Version 3.20 to 3.21 ........................................... 137
2.10.8. Upgrading the Grant Tables ....................................................... 138
2.10.9. Copying MySQL Databases to Another Machine ........................... 139
2.11. Downgrading MySQL ......................................................................... 140
2.11.1. Downgrading to 4.1 .................................................................. 141
2.11.2. Downgrading to 4.0 .................................................................. 141
2.12. Operating System-Specific Notes ........................................................... 142
2.12.1. Linux Notes ............................................................................ 142
2.12.2. Mac OS X Notes ...................................................................... 149
2.12.3. Solaris Notes ........................................................................... 149
2.12.4. BSD Notes .............................................................................. 153
2.12.5. Other Unix Notes ..................................................................... 156
2.12.6. OS/2 Notes ............................................................................. 171
2.12.7. BeOS Notes ............................................................................ 172
2.13. Perl Installation Notes ......................................................................... 172
2.13.1. Installing Perl on Unix .............................................................. 172
2.13.2. Installing ActiveState Perl on Windows ........................................ 173
2.13.3. Problems Using the Perl DBI/DBD Interface .................................. 174
3. MySQL Tutorial ............................................................................................. 177
3.1. Connecting to and Disconnecting from the Server ....................................... 177
3.2. Entering Queries .................................................................................. 178
3.3. Creating and Using a Database ................................................................ 181
3.3.1. Creating and Selecting a Database ................................................. 182
3.3.2. Creating a Table ........................................................................ 182
3.3.3. Loading Data into a Table ........................................................... 184
3.3.4. Retrieving Information from a Table ............................................. 185
3.4. Getting Information About Databases and Tables ....................................... 198
3.5. Using mysql in Batch Mode ................................................................. 199
3.6. Examples of Common Queries ................................................................ 200
3.6.1. The Maximum Value for a Column ............................................... 201
3.6.2. The Row Holding the Maximum of a Certain Column ...................... 201
3.6.3. Maximum of Column per Group ................................................... 202
3.6.4. The Rows Holding the Group-wise Maximum of a Certain Field ......... 202
3.6.5. Using User Variables .................................................................. 203
3.6.6. Using Foreign Keys ................................................................... 203
3.6.7. Searching on Two Keys .............................................................. 205
3.6.8. Calculating Visits Per Day ........................................................... 206
3.6.9. Using AUTO_INCREMENT .......................................................... 206
v
MySQL Reference Manual
3.7. Queries from the Twin Project ................................................................ 207
3.7.1. Find All Non-distributed Twins .................................................... 208
3.7.2. Show a Table of Twin Pair Status ................................................. 210
3.8. Using MySQL with Apache ................................................................... 210
4. Using MySQL Programs .................................................................................. 212
4.1. Overview of MySQL Programs ............................................................... 212
4.2. Invoking MySQL Programs ................................................................... 213
4.3. Specifying Program Options ................................................................... 213
4.3.1. Using Options on the Command Line ............................................ 214
4.3.2. Using Option Files ..................................................................... 216
4.3.3. Using Environment Variables to Specify Options ............................. 220
4.3.4. Using Options to Set Program Variables ......................................... 221
5. Database Administration .................................................................................. 222
5.1. The MySQL Server and Server Startup Scripts ........................................... 222
5.1.1. Overview of the Server-Side Scripts and Utilities ............................. 222
5.1.2. The mysqld-max Extended MySQL Server .................................. 223
5.1.3. mysqld_safe — MySQL Server Startup Script ................................. 226
5.1.4. mysql.server — MySQL Server Startup Script ................................ 229
5.1.5. mysqld_multi — Program for Managing Multiple MySQL Servers ..... 230
5.2. mysqlmanager — The MySQL Instance Manager ....................................... 233
5.2.1. Starting the MySQL Server with MySQL Instance Manager .............. 233
5.2.2. Connecting to the MySQL Instance Manager and Creating User Accounts
........................................................................................................ 234
5.2.3. MySQL Instance Manager Command-Line Options ......................... 235
5.2.4. MySQL Instance Manager Configuration Files ................................ 236
5.2.5. Commands Recognized by the MySQL Instance Manager ................. 237
5.3. mysqld — The MySQL Server ................................................................ 239
5.3.1. mysqld Command-Line Options ................................................. 239
5.3.2. The Server SQL Mode ................................................................ 250
5.3.3. Server System Variables ............................................................. 254
5.3.4. Server Status Variables ............................................................... 285
5.4. The MySQL Server Shutdown Process ..................................................... 295
5.5. General Security Issues ......................................................................... 296
5.5.1. General Security Guidelines ......................................................... 296
5.5.2. Making MySQL Secure Against Attackers ..................................... 298
5.5.3. Startup Options for mysqld Concerning Security ........................... 300
5.5.4. Security Issues with LOAD DATA LOCAL ..................................... 301
5.6. The MySQL Access Privilege System ...................................................... 302
5.6.1. What the Privilege System Does ................................................... 302
5.6.2. How the Privilege System Works .................................................. 302
5.6.3. Privileges Provided by MySQL .................................................... 307
5.6.4. Connecting to the MySQL Server ................................................. 310
5.6.5. Access Control, Stage 1: Connection Verification ............................ 311
5.6.6. Access Control, Stage 2: Request Verification ................................. 314
5.6.7. When Privilege Changes Take Effect ............................................. 317
5.6.8. Causes of Access denied Errors ............................................. 317
5.6.9. Password Hashing in MySQL 4.1 ................................................. 322
5.7. MySQL User Account Management ........................................................ 326
5.7.1. MySQL Usernames and Passwords ............................................... 327
5.7.2. Adding New User Accounts to MySQL ......................................... 328
5.7.3. Removing User Accounts from MySQL ......................................... 331
5.7.4. Limiting Account Resources ........................................................ 331
5.7.5. Assigning Account Passwords ...................................................... 333
5.7.6. Keeping Your Password Secure .................................................... 334
5.7.7. Using Secure Connections ........................................................... 335
5.8. Backup and Recovery ........................................................................... 343
5.8.1. Database Backups ...................................................................... 343
5.8.2. Example Backup and Recovery Strategy ........................................ 345
5.8.3. Point-in-Time Recovery .............................................................. 348
5.8.4. Table Maintenance and Crash Recovery ......................................... 349
5.8.5. myisamchk — MyISAM Table-Maintenance Utility ......................... 350
5.8.6. Setting Up a Table Maintenance Schedule ...................................... 361
5.8.7. Getting Information About a Table ................................................ 362
vi
MySQL Reference Manual
5.9. MySQL Localization and International Usage ............................................ 368
5.9.1. The Character Set Used for Data and Sorting .................................. 368
5.9.2. Setting the Error Message Language .............................................. 369
5.9.3. Adding a New Character Set ........................................................ 370
5.9.4. The Character Definition Arrays ................................................... 371
5.9.5. String Collating Support .............................................................. 372
5.9.6. Multi-Byte Character Support ...................................................... 372
5.9.7. Problems With Character Sets ...................................................... 372
5.9.8. MySQL Server Time Zone Support ............................................... 373
5.10. The MySQL Log Files ......................................................................... 374
5.10.1. The Error Log ......................................................................... 374
5.10.2. The General Query Log ............................................................. 375
5.10.3. The Update Log ....................................................................... 375
5.10.4. The Binary Log ....................................................................... 376
5.10.5. The Slow Query Log ................................................................ 379
5.10.6. Log File Maintenance ............................................................... 380
5.11. Running Multiple MySQL Servers on the Same Machine ........................... 381
5.11.1. Running Multiple Servers on Windows ........................................ 382
5.11.2. Running Multiple Servers on Unix .............................................. 385
5.11.3. Using Client Programs in a Multiple-Server Environment ................ 387
5.12. The MySQL Query Cache .................................................................... 387
5.12.1. How the Query Cache Operates .................................................. 388
5.12.2. Query Cache SELECT Options ................................................... 389
5.12.3. Query Cache Configuration ........................................................ 390
5.12.4. Query Cache Status and Maintenance .......................................... 391
6. Replication in MySQL ..................................................................................... 393
6.1. Introduction to Replication ..................................................................... 393
6.2. Replication Implementation Overview ...................................................... 393
6.3. Replication Implementation Details ......................................................... 394
6.3.1. Replication Master Thread States .................................................. 395
6.3.2. Replication Slave I/O Thread States .............................................. 396
6.3.3. Replication Slave SQL Thread States ............................................. 397
6.3.4. Replication Relay and Status Files ................................................ 397
6.4. How to Set Up Replication ..................................................................... 399
6.5. Replication Compatibility Between MySQL Versions ................................. 403
6.6. Upgrading a Replication Setup ................................................................ 404
6.6.1. Upgrading Replication to 4.0 or 4.1 ............................................... 404
6.6.2. Upgrading Replication to 5.0 ....................................................... 404
6.7. Replication Features and Known Problems ................................................ 405
6.8. Replication Startup Options .................................................................... 409
6.9. Replication FAQ .................................................................................. 417
6.10. Troubleshooting Replication ................................................................. 422
6.11. Reporting Replication Bugs .................................................................. 423
7. MySQL Optimization ...................................................................................... 425
7.1. Optimization Overview ......................................................................... 425
7.1.1. MySQL Design Limitations and Tradeoffs ..................................... 425
7.1.2. Designing Applications for Portability ........................................... 426
7.1.3. What We Have Used MySQL For ................................................. 427
7.1.4. The MySQL Benchmark Suite ...................................................... 427
7.1.5. Using Your Own Benchmarks ...................................................... 428
7.2. Optimizing SELECT Statements and Other Queries .................................... 429
7.2.1. EXPLAIN Syntax (Get Information About a SELECT) ..................... 429
7.2.2. Estimating Query Performance ..................................................... 437
7.2.3. Speed of SELECT Queries ........................................................... 438
7.2.4. How MySQL Optimizes WHERE Clauses ........................................ 438
7.2.5. Range Optimization ................................................................... 440
7.2.6. Index Merge Optimization ........................................................... 443
7.2.7. How MySQL Optimizes IS NULL ............................................... 446
7.2.8. How MySQL Optimizes DISTINCT ............................................. 447
7.2.9. How MySQL Optimizes LEFT JOIN and RIGHT JOIN ................ 447
7.2.10. How MySQL Optimizes Nested Joins .......................................... 448
7.2.11. How MySQL Simplifies Outer Joins ............................................ 454
7.2.12. How MySQL Optimizes ORDER BY ........................................... 457
vii
MySQL Reference Manual
7.2.13. How MySQL Optimizes GROUP BY ........................................... 459
7.2.14. How MySQL Optimizes LIMIT ................................................. 461
7.2.15. How to Avoid Table Scans ......................................................... 461
7.2.16. Speed of INSERT Statements ..................................................... 462
7.2.17. Speed of UPDATE Statements ..................................................... 464
7.2.18. Speed of DELETE Statements ..................................................... 464
7.2.19. Other Optimization Tips ............................................................ 464
7.3. Locking Issues ..................................................................................... 467
7.3.1. Locking Methods ....................................................................... 467
7.3.2. Table Locking Issues .................................................................. 469
7.4. Optimizing Database Structure ................................................................ 470
7.4.1. Design Choices ......................................................................... 470
7.4.2. Make Your Data as Small as Possible ............................................ 471
7.4.3. Column Indexes ........................................................................ 472
7.4.4. Multiple-Column Indexes ............................................................ 472
7.4.5. How MySQL Uses Indexes .......................................................... 473
7.4.6. The MyISAM Key Cache ............................................................. 475
7.4.7. How MySQL Counts Open Tables ................................................ 480
7.4.8. How MySQL Opens and Closes Tables .......................................... 480
7.4.9. Drawbacks to Creating Many Tables in the Same Database ................ 482
7.5. Optimizing the MySQL Server ............................................................... 482
7.5.1. System Factors and Startup Parameter Tuning ................................. 482
7.5.2. Tuning Server Parameters ............................................................ 483
7.5.3. Controlling Query Optimizer Performance ...................................... 485
7.5.4. How Compiling and Linking Affects the Speed of MySQL ................ 485
7.5.5. How MySQL Uses Memory ........................................................ 487
7.5.6. How MySQL Uses DNS ............................................................. 488
7.6. Disk Issues .......................................................................................... 488
7.6.1. Using Symbolic Links ................................................................ 489
8. MySQL Client and Utility Programs ................................................................... 493
8.1. Overview of the Client-Side Scripts and Utilities ........................................ 493
8.2. myisampack — Generate Compressed, Read-Only MyISAM Tables .............. 494
8.3. mysql — The MySQL Command-Line Tool .............................................. 500
8.3.1. Options .................................................................................... 501
8.3.2. mysql Commands .................................................................... 505
8.3.3. Executing SQL Statements from a Text File .................................... 508
8.3.4. mysql Tips .............................................................................. 509
8.4. mysqladmin — Client for Administering a MySQL Server ........................... 511
8.5. mysqlbinlog — Utility for Processing Binary Log Files ............................... 515
8.6. mysqlcheck — A Table Maintenance and Repair Program ........................... 519
8.7. mysqldump — A Database Backup Program ............................................. 521
8.8. mysqlhotcopy — A Database Backup Program .......................................... 529
8.9. mysqlimport — A Data Import Program ................................................... 530
8.10. mysqlshow — Display Database, Table, and Column Information ............... 533
8.11. perror — Explain Error Codes ............................................................... 534
8.12. replace — A String-Replacement Utility ................................................. 535
9. Language Structure ......................................................................................... 536
9.1. Literal Values ...................................................................................... 536
9.1.1. Strings ..................................................................................... 536
9.1.2. Numbers .................................................................................. 538
9.1.3. Hexadecimal Values ................................................................... 538
9.1.4. Boolean Values ......................................................................... 539
9.1.5. Bit-Field Values ........................................................................ 539
9.1.6. NULL Values ............................................................................ 539
9.2. Database, Table, Index, Column, and Alias Names ..................................... 539
9.2.1. Identifier Qualifiers .................................................................... 541
9.2.2. Identifier Case Sensitivity ............................................................ 541
9.3. User Variables ..................................................................................... 543
9.4. System Variables ................................................................................. 544
9.4.1. Structured System Variables ........................................................ 545
9.5. Comment Syntax .................................................................................. 547
9.6. Treatment of Reserved Words in MySQL ................................................. 548
10. Character Set Support .................................................................................... 553
viii
MySQL Reference Manual
10.1. Character Sets and Collations in General ................................................. 553
10.2. Character Sets and Collations in MySQL ................................................ 554
10.3. Determining the Default Character Set and Collation ................................. 555
10.3.1. Server Character Set and Collation .............................................. 555
10.3.2. Database Character Set and Collation ........................................... 556
10.3.3. Table Character Set and Collation ............................................... 556
10.3.4. Column Character Set and Collation ............................................ 557
10.3.5. Examples of Character Set and Collation Assignment ..................... 558
10.3.6. Connection Character Sets and Collations ..................................... 558
10.3.7. Character String Literal Character Set and Collation ....................... 560
10.3.8. Using COLLATE in SQL Statements ............................................ 561
10.3.9. COLLATE Clause Precedence ..................................................... 562
10.3.10. BINARY Operator .................................................................. 562
10.3.11. Some Special Cases Where the Collation Determination Is Tricky ... 562
10.3.12. Collations Must Be for the Right Character Set ............................ 563
10.3.13. An Example of the Effect of Collation ........................................ 564
10.4. Operations Affected by Character Set Support .......................................... 565
10.4.1. Result Strings .......................................................................... 565
10.4.2. CONVERT() ........................................................................... 566
10.4.3. CAST() ................................................................................. 566
10.4.4. SHOW Statements ..................................................................... 567
10.5. Unicode Support ................................................................................ 568
10.6. UTF8 for Metadata ............................................................................. 568
10.7. Compatibility with Other DBMSs .......................................................... 570
10.8. New Character Set Configuration File Format .......................................... 570
10.9. National Character Set ......................................................................... 570
10.10. Upgrading Character Sets from MySQL 4.0 ........................................... 570
10.10.1. 4.0 Character Sets and Corresponding 4.1 Character Set/Collation Pairs
........................................................................................................ 571
10.10.2. Converting 4.0 Character Columns to 4.1 Format ......................... 572
10.11. Character Sets and Collations That MySQL Supports ............................... 573
10.11.1. Unicode Character Sets ............................................................ 574
10.11.2. West European Character Sets .................................................. 576
10.11.3. Central European Character Sets ............................................... 577
10.11.4. South European and Middle East Character Sets ........................... 578
10.11.5. Baltic Character Sets ............................................................... 579
10.11.6. Cyrillic Character Sets ............................................................. 579
10.11.7. Asian Character Sets ............................................................... 580
11. Column Types .............................................................................................. 584
11.1. Column Type Overview ....................................................................... 584
11.1.1. Overview of Numeric Types ...................................................... 584
11.1.2. Overview of Date and Time Types .............................................. 587
11.1.3. Overview of String Types .......................................................... 588
11.2. Numeric Types ................................................................................... 591
11.3. Date and Time Types .......................................................................... 593
11.3.1. The DATETIME, DATE, and TIMESTAMP Types ........................... 595
11.3.2. The TIME Type ....................................................................... 601
11.3.3. The YEAR Type ....................................................................... 602
11.3.4. Y2K Issues and Date Types ....................................................... 602
11.4. String Types ...................................................................................... 603
11.4.1. The CHAR and VARCHAR Types ................................................. 603
11.4.2. The BINARY and VARBINARY Types ......................................... 604
11.4.3. The BLOB and TEXT Types ....................................................... 605
11.4.4. The ENUM Type ....................................................................... 606
11.4.5. The SET Type ......................................................................... 608
11.5. Column Type Storage Requirements ...................................................... 610
11.6. Choosing the Right Type for a Column ................................................... 612
11.7. Using Column Types from Other Database Engines .................................. 612
12. Functions and Operators ................................................................................. 614
12.1. Operators .......................................................................................... 614
12.1.1. Operator Precedence ................................................................. 614
12.1.2. Parentheses ............................................................................. 615
12.1.3. Comparison Functions and Operators ........................................... 615
ix
MySQL Reference Manual
12.1.4. Logical Operators ..................................................................... 620
12.2. Control Flow Functions ....................................................................... 621
12.3. String Functions ................................................................................. 623
12.3.1. String Comparison Functions ..................................................... 634
12.4. Numeric Functions .............................................................................. 636
12.4.1. Arithmetic Operators ................................................................ 636
12.4.2. Mathematical Functions ............................................................ 637
12.5. Date and Time Functions ..................................................................... 644
12.6. What Calendar Is Used By MySQL? ...................................................... 661
12.7. Full-Text Search Functions ................................................................... 661
12.7.1. Boolean Full-Text Searches ....................................................... 664
12.7.2. Full-Text Searches with Query Expansion ..................................... 666
12.7.3. Full-Text Restrictions ............................................................... 666
12.7.4. Fine-Tuning MySQL Full-Text Search ......................................... 667
12.7.5. Full-Text Search TODO ............................................................ 669
12.8. Cast Functions and Operators ................................................................ 669
12.9. Other Functions .................................................................................. 672
12.9.1. Bit Functions ........................................................................... 672
12.9.2. Encryption Functions ................................................................ 673
12.9.3. Information Functions ............................................................... 676
12.9.4. Miscellaneous Functions ........................................................... 682
12.10. Functions and Modifiers for Use with GROUP BY Clauses ....................... 685
12.10.1. GROUP BY (Aggregate) Functions ............................................ 685
12.10.2. GROUP BY Modifiers ............................................................. 688
12.10.3. GROUP BY with Hidden Fields ................................................. 691
13. SQL Statement Syntax ................................................................................... 692
13.1. Data Definition Statements ................................................................... 692
13.1.1. ALTER DATABASE Syntax ....................................................... 692
13.1.2. ALTER TABLE Syntax ............................................................. 692
13.1.3. CREATE DATABASE Syntax ..................................................... 697
13.1.4. CREATE INDEX Syntax ........................................................... 697
13.1.5. CREATE TABLE Syntax ........................................................... 699
13.1.6. DROP DATABASE Syntax ......................................................... 710
13.1.7. DROP INDEX Syntax ............................................................... 711
13.1.8. DROP TABLE Syntax ............................................................... 711
13.1.9. RENAME TABLE Syntax ........................................................... 712
13.2. Data Manipulation Statements ............................................................... 712
13.2.1. DELETE Syntax ....................................................................... 712
13.2.2. DO Syntax ............................................................................... 715
13.2.3. HANDLER Syntax ..................................................................... 715
13.2.4. INSERT Syntax ....................................................................... 717
13.2.5. LOAD DATA INFILE Syntax ................................................... 723
13.2.6. REPLACE Syntax ..................................................................... 731
13.2.7. SELECT Syntax ....................................................................... 732
13.2.8. Subquery Syntax ...................................................................... 742
13.2.9. TRUNCATE Syntax ................................................................... 752
13.2.10. UPDATE Syntax ..................................................................... 752
13.3. MySQL Utility Statements ................................................................... 754
13.3.1. DESCRIBE Syntax (Get Information About Columns) .................... 754
13.3.2. USE Syntax ............................................................................. 755
13.4. MySQL Transactional and Locking Statements ........................................ 755
13.4.1. START TRANSACTION, COMMIT, and ROLLBACK Syntax ............ 756
13.4.2. Statements That Cannot Be Rolled Back ....................................... 757
13.4.3. Statements That Cause an Implicit Commit ................................... 757
13.4.4. SAVEPOINT and ROLLBACK TO SAVEPOINT Syntax ................ 758
13.4.5. LOCK TABLES and UNLOCK TABLES Syntax ............................ 758
13.4.6. SET TRANSACTION Syntax ..................................................... 761
13.4.7. XA Transactions ...................................................................... 761
13.5. Database Administration Statements ...................................................... 765
13.5.1. Account Management Statements ................................................ 765
13.5.2. Table Maintenance Statements .................................................... 774
13.5.3. SET Syntax ............................................................................. 779
13.5.4. SHOW Syntax ........................................................................... 784
x
MySQL Reference Manual
13.5.5. Other Administrative Statements ................................................. 802
13.6. Replication Statements ........................................................................ 806
13.6.1. SQL Statements for Controlling Master Servers ............................. 806
13.6.2. SQL Statements for Controlling Slave Servers ............................... 808
13.7. SQL Syntax for Prepared Statements ...................................................... 816
14. MySQL Storage Engines and Table Types ......................................................... 819
14.1. The MyISAM Storage Engine ................................................................ 821
14.1.1. MyISAM Startup Options ........................................................... 823
14.1.2. Space Needed for Keys ............................................................. 824
14.1.3. MyISAM Table Storage Formats ................................................. 824
14.1.4. MyISAM Table Problems ........................................................... 826
14.2. The MERGE Storage Engine .................................................................. 828
14.2.1. MERGE Table Problems ............................................................. 830
14.3. The MEMORY (HEAP) Storage Engine ..................................................... 831
14.4. The BDB (BerkeleyDB) Storage Engine ............................................... 833
14.4.1. Operating Systems Supported by BDB .......................................... 833
14.4.2. Installing BDB ......................................................................... 834
14.4.3. BDB Startup Options ................................................................. 834
14.4.4. Characteristics of BDB Tables ..................................................... 836
14.4.5. Things We Need to Fix for BDB .................................................. 837
14.4.6. Restrictions on BDB Tables ........................................................ 838
14.4.7. Errors That May Occur When Using BDB Tables ........................... 838
14.5. The EXAMPLE Storage Engine .............................................................. 839
14.6. The FEDERATED Storage Engine .......................................................... 839
14.6.1. Installing the FEDERATED Storage Engine ................................... 839
14.6.2. Description of the FEDERATED Storage Engine ............................ 839
14.6.3. How to use FEDERATED Tables ................................................. 840
14.6.4. Limitations of the FEDERATED Storage Engine ............................. 841
14.7. The ARCHIVE Storage Engine .............................................................. 842
14.8. The CSV Storage Engine ...................................................................... 842
14.9. The BLACKHOLE Storage Engine .......................................................... 843
14.10. The ISAM Storage Engine .................................................................. 844
15. The InnoDB Storage Engine .......................................................................... 846
15.1. InnoDB Overview ............................................................................. 846
15.2. InnoDB Contact Information ............................................................... 846
15.3. InnoDB in MySQL 3.23 ..................................................................... 846
15.4. InnoDB Configuration ........................................................................ 847
15.5. InnoDB Startup Options ..................................................................... 851
15.6. Creating the InnoDB Tablespace .......................................................... 857
15.6.1. Dealing with InnoDB Initialization Problems ............................... 858
15.7. Creating InnoDB Tables ..................................................................... 859
15.7.1. How to Use Transactions in InnoDB with Different APIs ............... 859
15.7.2. Converting MyISAM Tables to InnoDB ....................................... 860
15.7.3. How an AUTO_INCREMENT Column Works in InnoDB ................ 861
15.7.4. FOREIGN KEY Constraints ....................................................... 861
15.7.5. InnoDB and MySQL Replication ............................................... 865
15.7.6. Using Per-Table Tablespaces ...................................................... 866
15.8. Adding and Removing InnoDB Data and Log Files .................................. 868
15.9. Backing Up and Recovering an InnoDB Database ................................... 869
15.9.1. Forcing Recovery ..................................................................... 870
15.9.2. Checkpoints ............................................................................ 871
15.10. Moving an InnoDB Database to Another Machine ................................. 872
15.11. InnoDB Transaction Model and Locking .............................................. 872
15.11.1. InnoDB Lock Modes ............................................................. 872
15.11.2. InnoDB and AUTOCOMMIT ..................................................... 873
15.11.3. InnoDB and TRANSACTION ISOLATION LEVEL ................... 874
15.11.4. Consistent Non-Locking Read .................................................. 875
15.11.5. Locking Reads SELECT ... FOR UPDATE and SELECT ...
LOCK IN SHARE MODE ................................................................... 875
15.11.6. Next-Key Locking: Avoiding the Phantom Problem ...................... 876
15.11.7. An Example of How the Consistent Read Works in InnoDB .......... 877
15.11.8. Locks Set by Different SQL Statements in InnoDB ...................... 878
15.11.9. When Does MySQL Implicitly Commit or Roll Back a Transaction? 879
xi
MySQL Reference Manual
15.11.10. Deadlock Detection and Rollback ............................................ 879
15.11.11. How to Cope with Deadlocks .................................................. 880
15.12. InnoDB Performance Tuning Tips ...................................................... 881
15.12.1. SHOW INNODB STATUS and the InnoDB Monitors ................... 883
15.13. Implementation of Multi-Versioning ..................................................... 887
15.14. Table and Index Structures ................................................................. 887
15.14.1. Physical Structure of an Index ................................................... 888
15.14.2. Insert Buffering ...................................................................... 888
15.14.3. Adaptive Hash Indexes ............................................................ 888
15.14.4. Physical Record Structure ........................................................ 889
15.15. File Space Management and Disk I/O ................................................... 889
15.15.1. Disk I/O ............................................................................... 889
15.15.2. Using Raw Devices for the Tablespace ....................................... 890
15.15.3. File Space Management ........................................................... 890
15.15.4. Defragmenting a Table ............................................................ 891
15.16. InnoDB Error Handling ...................................................................... 891
15.16.1. InnoDB Error Codes .............................................................. 892
15.16.2. Operating System Error Codes .................................................. 892
15.17. Restrictions on InnoDB Tables ........................................................... 897
15.18. InnoDB Troubleshooting ................................................................... 899
15.18.1. Troubleshooting InnoDB Data Dictionary Operations .................. 900
16. MySQL Cluster ............................................................................................ 902
16.1. MySQL Cluster Overview .................................................................... 902
16.2. Basic MySQL Cluster Concepts ............................................................ 903
16.3. Simple Multi-Computer How-To ........................................................... 905
16.3.1. Hardware, Software, and Networking ........................................... 906
16.3.2. Installation .............................................................................. 907
16.3.3. Configuration .......................................................................... 908
16.3.4. Initial Startup .......................................................................... 910
16.3.5. Loading Sample Data and Performing Queries ............................... 911
16.3.6. Safe Shutdown and Restart ........................................................ 915
16.4. MySQL Cluster Configuration .............................................................. 915
16.4.1. Building MySQL Cluster from Source Code .................................. 915
16.4.2. Installing the Software .............................................................. 916
16.4.3. Quick Test Setup of MySQL Cluster ............................................ 916
16.4.4. Configuration File .................................................................... 918
16.5. Process Management in MySQL Cluster ................................................. 942
16.5.1. MySQL Server Process Usage for MySQL Cluster ......................... 942
16.5.2. ndbd, the Storage Engine Node Process ....................................... 943
16.5.3. ndb_mgmd, the Management Server Process ................................ 944
16.5.4. ndb_mgm, the Management Client Process ................................... 945
16.5.5. Command Options for MySQL Cluster Processes ........................... 945
16.6. Management of MySQL Cluster ............................................................ 948
16.6.1. MySQL Cluster Startup Phases ................................................... 948
16.6.2. Commands in the Management Client .......................................... 950
16.6.3. Event Reports Generated in MySQL Cluster .................................. 951
16.6.4. Single User Mode .................................................................... 956
16.6.5. On-line Backup of MySQL Cluster .............................................. 957
16.7. Using High-Speed Interconnects with MySQL Cluster ............................... 959
16.7.1. Configuring MySQL Cluster to use SCI Sockets ............................ 960
16.7.2. Understanding the Impact of Cluster Interconnects ......................... 963
16.8. Cluster Limitations in MySQL 4.1 ......................................................... 964
16.9. MySQL Cluster in 5.0 and 5.1 ............................................................... 967
16.9.1. MySQL Cluster Changes in MySQL 5.0 ....................................... 967
16.9.2. MySQL 5.1 Development Roadmap for MySQL Cluster ................. 968
16.10. MySQL Cluster FAQ ......................................................................... 968
16.11. MySQL Cluster Glossary ................................................................... 975
17. Spatial Extensions in MySQL .......................................................................... 978
17.1. Introduction ....................................................................................... 978
17.2. The OpenGIS Geometry Model ............................................................. 979
17.2.1. The Geometry Class Hierarchy ................................................... 979
17.2.2. Class Geometry ..................................................................... 980
17.2.3. Class Point ........................................................................... 981
xii
MySQL Reference Manual
17.2.4. Class Curve ........................................................................... 981
17.2.5. Class LineString ................................................................. 982
17.2.6. Class Surface ....................................................................... 982
17.2.7. Class Polygon ....................................................................... 982
17.2.8. Class GeometryCollection ................................................. 983
17.2.9. Class MultiPoint ................................................................. 983
17.2.10. Class MultiCurve ............................................................... 983
17.2.11. Class MultiLineString ..................................................... 984
17.2.12. Class MultiSurface ........................................................... 984
17.2.13. Class MultiPolygon ........................................................... 984
17.3. Supported Spatial Data Formats ............................................................ 985
17.3.1. Well-Known Text (WKT) Format ............................................... 985
17.3.2. Well-Known Binary (WKB) Format ............................................ 986
17.4. Creating a Spatially Enabled MySQL Database ........................................ 987
17.4.1. MySQL Spatial Data Types ........................................................ 987
17.4.2. Creating Spatial Values ............................................................. 987
17.4.3. Creating Spatial Columns .......................................................... 990
17.4.4. Populating Spatial Columns ....................................................... 990
17.4.5. Fetching Spatial Data ................................................................ 991
17.5. Analyzing Spatial Information .............................................................. 992
17.5.1. Geometry Format Conversion Functions ....................................... 992
17.5.2. Geometry Functions ............................................................... 993
17.5.3. Functions That Create New Geometries from Existing Ones ............. 999
17.5.4. Functions for Testing Spatial Relations Between Geometric Objects 1000
17.5.5. Relations on Geometry Minimal Bounding Rectangles (MBRs) ...... 1000
17.5.6. Functions That Test Spatial Relationships Between Geometries ...... 1001
17.6. Optimizing Spatial Analysis ............................................................... 1002
17.6.1. Creating Spatial Indexes .......................................................... 1002
17.6.2. Using a Spatial Index .............................................................. 1003
17.7. MySQL Conformance and Compatibility .............................................. 1004
17.7.1. GIS Features That Are Not Yet Implemented .............................. 1005
18. Stored Procedures and Functions .................................................................... 1006
18.1. Stored Procedures and the Grant Tables ................................................ 1006
18.2. Stored Procedure Syntax .................................................................... 1007
18.2.1. CREATE PROCEDURE and CREATE FUNCTION ...................... 1007
18.2.2. ALTER PROCEDURE and ALTER FUNCTION .......................... 1010
18.2.3. DROP PROCEDURE and DROP FUNCTION .............................. 1010
18.2.4. SHOW CREATE PROCEDURE and SHOW CREATE FUNCTION .. 1010
18.2.5. SHOW PROCEDURE STATUS and SHOW FUNCTION STATUS .. 1011
18.2.6. CALL Statement ..................................................................... 1011
18.2.7. BEGIN ... END Compound Statement ................................... 1011
18.2.8. DECLARE Statement ............................................................... 1011
18.2.9. Variables in Stored Procedures ................................................. 1012
18.2.10. Conditions and Handlers ........................................................ 1013
18.2.11. Cursors ............................................................................... 1014
18.2.12. Flow Control Constructs ........................................................ 1015
18.3. Stored Procedures, Functions, Triggers, and Replication: Frequently Asked Questions ...................................................................................................... 1018
18.4. Binary Logging of Stored Routines and Triggers .................................... 1019
19. Triggers .................................................................................................... 1024
19.1. CREATE TRIGGER Syntax ............................................................... 1024
19.2. DROP TRIGGER Syntax ................................................................... 1026
19.3. Using Triggers ................................................................................. 1026
20. Views ....................................................................................................... 1030
20.1. ALTER VIEW Syntax ....................................................................... 1030
20.2. CREATE VIEW Syntax ..................................................................... 1030
20.3. DROP VIEW Syntax ......................................................................... 1035
20.4. SHOW CREATE VIEW Syntax ........................................................... 1035
21. The INFORMATION_SCHEMA Information Database ........................................ 1037
21.1. INFORMATION_SCHEMA Tables ....................................................... 1038
21.1.1. The INFORMATION_SCHEMA SCHEMATA Table ...................... 1039
21.1.2. The INFORMATION_SCHEMA TABLES Table .......................... 1039
21.1.3. The INFORMATION_SCHEMA COLUMNS Table ........................ 1040
xiii
MySQL Reference Manual
21.1.4. The INFORMATION_SCHEMA STATISTICS Table .................. 1041
21.1.5. The INFORMATION_SCHEMA USER_PRIVILEGES Table ........ 1042
21.1.6. The INFORMATION_SCHEMA SCHEMA_PRIVILEGES Table .... 1042
21.1.7. The INFORMATION_SCHEMA TABLE_PRIVILEGES Table ...... 1043
21.1.8. The INFORMATION_SCHEMA COLUMN_PRIVILEGES Table .... 1043
21.1.9. The INFORMATION_SCHEMA CHARACTER_SETS Table .......... 1044
21.1.10. The INFORMATION_SCHEMA COLLATIONS Table ................. 1044
21.1.11.
The
INFORMATION_SCHEMA
COLLATION_CHARACTER_SET_APPLICABILITY Table ............................ 1045
21.1.12. The INFORMATION_SCHEMA TABLE_CONSTRAINTS Table ... 1045
21.1.13. The INFORMATION_SCHEMA KEY_COLUMN_USAGE Table ..... 1045
21.1.14. The INFORMATION_SCHEMA ROUTINES Table ..................... 1046
21.1.15. The INFORMATION_SCHEMA VIEWS Table ........................... 1047
21.1.16. The INFORMATION_SCHEMA TRIGGERS Table ..................... 1048
21.1.17. Other INFORMATION_SCHEMA Tables ................................... 1049
21.2. Extensions to SHOW Statements ........................................................... 1050
22. Precision Math ........................................................................................... 1052
22.1. Types of Numeric Values ................................................................... 1052
22.2. DECIMAL Data Type Changes ............................................................ 1053
22.3. Expression Handling ......................................................................... 1054
22.4. Rounding Behavior ........................................................................... 1056
22.5. Precision Math Examples ................................................................... 1057
23. MySQL APIs and Libraries ........................................................................... 1062
23.1. libmysqld, the Embedded MySQL Server Library ................................... 1062
23.1.1. Overview of the Embedded MySQL Server Library ...................... 1062
23.1.2. Compiling Programs with libmysqld ..................................... 1062
23.1.3. Restrictions when using the Embedded MySQL Server ................. 1063
23.1.4. Options with the Embedded Server ............................................ 1063
23.1.5. Things left to do in Embedded Server (TODO) ............................ 1064
23.1.6. Embedded Server Examples ..................................................... 1064
23.1.7. Licensing the Embedded Server ................................................ 1067
23.2. MySQL C API ................................................................................. 1067
23.2.1. C API Data types ................................................................... 1068
23.2.2. C API Function Overview ........................................................ 1072
23.2.3. C API Function Descriptions .................................................... 1075
23.2.4. C API Prepared Statements ...................................................... 1118
23.2.5. C API Prepared Statement Data types ........................................ 1119
23.2.6. C API Prepared Statement Function Overview ............................. 1122
23.2.7. C API Prepared Statement Function Descriptions ......................... 1124
23.2.8. C API Prepared statement problems ........................................... 1146
23.2.9. C API Handling of Multiple Query Execution .............................. 1146
23.2.10. C API Handling of Date and Time Values ................................. 1147
23.2.11. C API Threaded Function Descriptions ..................................... 1148
23.2.12. C API Embedded Server Function Descriptions .......................... 1149
23.2.13. Common questions and problems when using the C API .............. 1151
23.2.14. Building Client Programs ....................................................... 1152
23.2.15. How to Make a Threaded Client .............................................. 1153
23.3. MySQL PHP API ............................................................................. 1154
23.3.1. Common Problems with MySQL and PHP .................................. 1155
23.4. MySQL Perl API .............................................................................. 1155
23.5. MySQL C++ API ............................................................................. 1156
23.5.1. Borland C++ ......................................................................... 1156
23.6. MySQL Python API .......................................................................... 1156
23.7. MySQL Tcl API ............................................................................... 1156
23.8. MySQL Eiffel Wrapper ..................................................................... 1156
23.9. MySQL Program Development Utilities ................................................ 1156
23.9.1. msql2mysql — Convert mSQL Programs for Use with MySQL ...... 1157
23.9.2. mysql_config — Get Compile Options for Compiling Clients ......... 1157
24. MySQL Connectors ..................................................................................... 1159
24.1. MySQL Connector/ODBC ................................................................. 1159
24.1.1. Introduction to MyODBC ........................................................ 1159
24.1.2. General Information About ODBC and MyODBC ........................ 1161
24.1.3. How to Install MyODBC ......................................................... 1164
xiv
MySQL Reference Manual
24.1.4. Installing MyODBC from a Binary Distribution on Windows ......... 1164
24.1.5. Installing MyODBC from a Binary Distribution on Unix ............... 1165
24.1.6. Installing MyODBC from a Source Distribution on Windows ......... 1166
24.1.7. Installing MyODBC from a Source Distribution on Unix ............... 1167
24.1.8. Installing MyODBC from the BitKeeper Development Source Tree . 1172
24.1.9. MyODBC Configuration ......................................................... 1174
24.1.10. MyODBC Connection-Related Issues ....................................... 1191
24.1.11. MyODBC and Microsoft Access ............................................. 1191
24.1.12. MyODBC and Microsoft VBA and ASP ................................... 1196
24.1.13. MyODBC and Third-Party ODBC Tools ................................... 1197
24.1.14. MyODBC General Functionality ............................................. 1198
24.1.15. Basic MyODBC Application Steps .......................................... 1202
24.1.16. MyODBC API Reference ....................................................... 1203
24.1.17. MyODBC Data Types ........................................................... 1207
24.1.18. MyODBC Error Codes .......................................................... 1208
24.1.19. MyODBC With VB: ADO, DAO and RDO ............................... 1210
24.1.20. MyODBC with Microsoft .NET .............................................. 1214
24.1.21. Credits ............................................................................... 1217
24.2. MySQL Connector/NET .................................................................... 1217
24.2.1. Introduction .......................................................................... 1217
24.2.2. Downloading and Installing MySQL Connector/NET .................... 1218
24.2.3. Connector/NET Architecture .................................................... 1218
24.2.4. Using MySQL Connector/NET ................................................. 1232
24.2.5. MySQL Connector/NET Change History .................................... 1250
24.3. MySQL Connector/J ......................................................................... 1265
24.3.1. Basic JDBC concepts .............................................................. 1265
24.3.2. Installing Connector/J ............................................................. 1275
24.3.3. JDBC Reference .................................................................... 1278
24.3.4. Using Connector/J with J2EE and Other Java Frameworks ............. 1301
24.3.5. Diagnosing Connector/J Problems ............................................. 1307
24.3.6. Changelog ............................................................................ 1312
24.4. MySQL Connector/MXJ .................................................................... 1346
24.4.1. Introduction .......................................................................... 1346
24.4.2. Support Platforms: ................................................................. 1347
24.4.3. JUnit Test Requirements .......................................................... 1347
24.4.4. Running the JUnit Tests .......................................................... 1347
24.4.5. Running as part of the JDBC Driver ........................................... 1348
24.4.6. Running within a Java Object ................................................... 1349
24.4.7. The MysqldResource API ........................................................ 1350
24.4.8. Running within a JMX Agent (custom) ...................................... 1351
24.4.9. Deployment in a standard JMX Agent environment (JBoss) ........... 1352
24.4.10. Installation .......................................................................... 1354
25. Extending MySQL ...................................................................................... 1355
25.1. MySQL Internals .............................................................................. 1355
25.1.1. MySQL Threads .................................................................... 1355
25.1.2. MySQL Test Suite ................................................................. 1355
25.2. Adding New Functions to MySQL ....................................................... 1358
25.2.1. Features of the User-Defined Function Interface ........................... 1358
25.2.2. CREATE FUNCTION/DROP FUNCTION Syntax ....................... 1359
25.2.3. Adding a New User-defined Function ........................................ 1359
25.2.4. Adding a New Native Function ................................................. 1368
25.3. Adding New Procedures to MySQL ..................................................... 1369
25.3.1. Procedure Analyse ................................................................. 1369
25.3.2. Writing a Procedure ................................................................ 1369
A. Problems and Common Errors ........................................................................ 1371
A.1. How to Determine What Is Causing a Problem ........................................ 1371
A.2. Common Errors When Using MySQL Programs ...................................... 1372
A.2.1. Access denied .................................................................. 1372
A.2.2. Can't connect to [local] MySQL server .................. 1372
A.2.3. Client does not support authentication protocol 1375
A.2.4. Password Fails When Entered Interactively .................................. 1376
A.2.5. Host 'host_name' is blocked ...................................... 1376
A.2.6. Too many connections .................................................... 1377
xv
MySQL Reference Manual
A.2.7. Out of memory .................................................................. 1377
A.2.8. MySQL server has gone away ........................................ 1377
A.2.9. Packet too large ............................................................ 1379
A.2.10. Communication Errors and Aborted Connections ........................ 1380
A.2.11. The table is full ........................................................ 1381
A.2.12. Can't create/write to file ...................................... 1382
A.2.13. Commands out of sync .................................................. 1382
A.2.14. Ignoring user ................................................................ 1382
A.2.15. Table 'tbl_name' doesn't exist .............................. 1383
A.2.16. Can't initialize character set .............................. 1383
A.2.17. File Not Found ...................................................................... 1384
A.3. Installation-Related Issues ................................................................... 1384
A.3.1. Problems Linking to the MySQL Client Library ............................ 1384
A.3.2. How to Run MySQL as a Normal User ....................................... 1385
A.3.3. Problems with File Permissions ................................................. 1386
A.4. Administration-Related Issues .............................................................. 1387
A.4.1. How to Reset the Root Password ................................................ 1387
A.4.2. What to Do If MySQL Keeps Crashing ....................................... 1389
A.4.3. How MySQL Handles a Full Disk .............................................. 1391
A.4.4. Where MySQL Stores Temporary Files ....................................... 1391
A.4.5. How to Protect or Change the MySQL Socket File /tmp/mysql.sock
...................................................................................................... 1392
A.4.6. Time Zone Problems ............................................................... 1393
A.5. Query-Related Issues ......................................................................... 1393
A.5.1. Case Sensitivity in Searches ...................................................... 1393
A.5.2. Problems Using DATE Columns ................................................ 1394
A.5.3. Problems with NULL Values ..................................................... 1395
A.5.4. Problems with Column Aliases .................................................. 1396
A.5.5. Rollback Failure for Non-Transactional Tables ............................. 1396
A.5.6. Deleting Rows from Related Tables ............................................ 1397
A.5.7. Solving Problems with No Matching Rows .................................. 1397
A.5.8. Problems with Floating-Point Comparisons .................................. 1398
A.6. Optimizer-Related Issues .................................................................... 1400
A.7. Table Definition-Related Issues ............................................................ 1401
A.7.1. Problems with ALTER TABLE ................................................. 1401
A.7.2. How to Change the Order of Columns in a Table ........................... 1401
A.7.3. TEMPORARY TABLE Problems ................................................ 1402
A.8. Known Issues in MySQL .................................................................... 1402
A.8.1. Issues in MySQL 3.23 Fixed in a Later MySQL Version ................ 1402
A.8.2. Issues in 4.0 Fixed in a Later MySQL Version .............................. 1403
A.8.3. Issues in 4.1 Fixed in a Later MySQL Version .............................. 1403
A.8.4. Open Issues in MySQL ............................................................ 1403
B. Error Codes and Messages ............................................................................. 1408
C. Credits ....................................................................................................... 1441
C.1. Developers at MySQL AB ................................................................... 1441
C.2. Contributors to MySQL ...................................................................... 1446
C.3. Documenters and translators ................................................................ 1450
C.4. Libraries used by and included with MySQL ........................................... 1451
C.5. Packages that support MySQL ............................................................. 1452
C.6. Tools that were used to create MySQL ................................................... 1453
C.7. Supporters of MySQL ........................................................................ 1453
D. MySQL and the Future (the TODO) ................................................................ 1455
D.1. New Features in MySQL 5.0 ............................................................... 1455
D.2. New Features Planned for 5.1 .............................................................. 1455
D.3. New Features Planned for the Near Future .............................................. 1455
D.4. New Features Planned for the Mid-Term Future ...................................... 1455
D.5. New Features We Don't Plan to Implement ............................................. 1455
E. MySQL Change History ................................................................................ 1456
E.1. Changes in release 5.0.x (Development) ................................................. 1456
E.1.1. Changes in release 5.0.13 (Not yet released) ................................. 1457
E.1.2. Changes in release 5.0.12 (02 Sept 2005) ..................................... 1461
E.1.3. Changes in release 5.0.11 (06 Aug 2005) ..................................... 1467
E.1.4. Changes in release 5.0.10 (27 July 2005) ...................................... 1469
xvi
MySQL Reference Manual
E.1.5. Changes in release 5.0.9 (15 July 2005) ....................................... 1473
E.1.6. Changes in release 5.0.8 (not released) ........................................ 1475
E.1.7. Changes in release 5.0.7 (10 June 2005) ....................................... 1480
E.1.8. Changes in release 5.0.6 (26 May 2005) ....................................... 1483
E.1.9. Changes in release 5.0.5 (not released) ........................................ 1488
E.1.10. Changes in release 5.0.4 (16 Apr 2005) ...................................... 1490
E.1.11. Changes in release 5.0.3 (23 Mar 2005: Beta) .............................. 1493
E.1.12. Changes in release 5.0.2 (01 Dec 2004) ...................................... 1503
E.1.13. Changes in release 5.0.1 (27 Jul 2004) ....................................... 1506
E.1.14. Changes in release 5.0.0 (22 Dec 2003: Alpha) ............................ 1510
E.2. Changes in release 4.1.x (Production) .................................................... 1511
E.2.1. ............................................................................................. 1512
E.2.2. Changes in release 4.1.14 (17 Aug 2005) ..................................... 1514
E.2.3. Changes in release 4.1.13 (15 Jul 2005) ....................................... 1518
E.2.4. Changes in release 4.1.12 (13 May 2005) ..................................... 1524
E.2.5. Changes in release 4.1.11 (01 Apr 2005) ...................................... 1528
E.2.6. Changes in release 4.1.10 (12 Feb 2005) ...................................... 1534
E.2.7. Changes in release 4.1.9 (11 Jan 2005) ........................................ 1539
E.2.8. Changes in release 4.1.8 (14 Dec 2004) ....................................... 1541
E.2.9. Changes in release 4.1.7 (23 Oct 2004: Production) ........................ 1545
E.2.10. Changes in release 4.1.6 (10 Oct 2004) ...................................... 1546
E.2.11. Changes in release 4.1.5 (16 Sep 2004) ...................................... 1548
E.2.12. Changes in release 4.1.4 (26 Aug 2004: Gamma) ......................... 1549
E.2.13. Changes in release 4.1.3 (28 Jun 2004: Beta) ............................... 1552
E.2.14. Changes in release 4.1.2 (28 May 2004) ..................................... 1555
E.2.15. Changes in release 4.1.1 (01 Dec 2003) ...................................... 1564
E.2.16. Changes in release 4.1.0 (03 Apr 2003: Alpha) ............................ 1569
E.3. Changes in release 4.0.x (Production) .................................................... 1572
E.3.1. Changes in release 4.0.27 (Not yet released) ................................. 1573
E.3.2. Changes in release 4.0.26 (08 Sept 2005) ..................................... 1573
E.3.3. Changes in release 4.0.25 (05 July 2005) ...................................... 1573
E.3.4. Changes in release 4.0.24 (04 Mar 2005) ...................................... 1575
E.3.5. Changes in release 4.0.23 (18 Dec 2004) ...................................... 1578
E.3.6. Changes in release 4.0.22 (27 Oct 2004) ...................................... 1579
E.3.7. Changes in release 4.0.21 (06 Sep 2004) ...................................... 1581
E.3.8. Changes in release 4.0.20 (17 May 2004) ..................................... 1583
E.3.9. Changes in release 4.0.19 (04 May 2004) ..................................... 1584
E.3.10. Changes in release 4.0.18 (12 Feb 2004) .................................... 1587
E.3.11. Changes in release 4.0.17 (14 Dec 2003) .................................... 1590
E.3.12. Changes in release 4.0.16 (17 Oct 2003) ..................................... 1593
E.3.13. Changes in release 4.0.15 (03 Sep 2003) .................................... 1595
E.3.14. Changes in release 4.0.14 (18 Jul 2003) ...................................... 1599
E.3.15. Changes in release 4.0.13 (16 May 2003) ................................... 1603
E.3.16. Changes in release 4.0.12 (15 Mar 2003: Production) ................... 1607
E.3.17. Changes in release 4.0.11 (20 Feb 2003) .................................... 1608
E.3.18. Changes in release 4.0.10 (29 Jan 2003) ..................................... 1609
E.3.19. Changes in release 4.0.9 (09 Jan 2003) ....................................... 1611
E.3.20. Changes in release 4.0.8 (07 Jan 2003) ....................................... 1611
E.3.21. Changes in release 4.0.7 (20 Dec 2002) ...................................... 1612
E.3.22. Changes in release 4.0.6 (14 Dec 2002: Gamma) ......................... 1612
E.3.23. Changes in release 4.0.5 (13 Nov 2002) ..................................... 1614
E.3.24. Changes in release 4.0.4 (29 Sep 2002) ...................................... 1616
E.3.25. Changes in release 4.0.3 (26 Aug 2002: Beta) ............................. 1617
E.3.26. Changes in release 4.0.2 (01 Jul 2002) ....................................... 1619
E.3.27. Changes in release 4.0.1 (23 Dec 2001) ...................................... 1623
E.3.28. Changes in release 4.0.0 (Oct 2001: Alpha) ................................. 1624
E.4. Changes in release 3.23.x (Recent; still supported) ................................... 1626
E.4.1. Changes in release 3.23.59 (not released yet) ................................ 1627
E.4.2. Changes in release 3.23.58 (11 Sep 2003) .................................... 1627
E.4.3. Changes in release 3.23.57 (06 Jun 2003) ..................................... 1628
E.4.4. Changes in release 3.23.56 (13 Mar 2003) .................................... 1629
E.4.5. Changes in release 3.23.55 (23 Jan 2003) ..................................... 1630
E.4.6. Changes in release 3.23.54 (05 Dec 2002) .................................... 1631
xvii
MySQL Reference Manual
E.4.7. Changes in release 3.23.53 (09 Oct 2002) ..................................... 1632
E.4.8. Changes in release 3.23.52 (14 Aug 2002) .................................... 1632
E.4.9. Changes in release 3.23.51 (31 May 2002) ................................... 1633
E.4.10. Changes in release 3.23.50 (21 Apr 2002) ................................... 1634
E.4.11. Changes in release 3.23.49 (14 Feb 2002) ................................... 1635
E.4.12. Changes in release 3.23.48 (07 Feb 2002) ................................... 1635
E.4.13. Changes in release 3.23.47 (27 Dec 2001) .................................. 1636
E.4.14. Changes in release 3.23.46 (29 Nov 2001) .................................. 1637
E.4.15. Changes in release 3.23.45 (22 Nov 2001) .................................. 1637
E.4.16. Changes in release 3.23.44 (31 Oct 2001) ................................... 1637
E.4.17. Changes in release 3.23.43 (04 Oct 2001) ................................... 1639
E.4.18. Changes in release 3.23.42 (08 Sep 2001) ................................... 1639
E.4.19. Changes in release 3.23.41 (11 Aug 2001) .................................. 1640
E.4.20. Changes in release 3.23.40 (18 Jul 2001) .................................... 1640
E.4.21. Changes in release 3.23.39 (12 Jun 2001) ................................... 1641
E.4.22. Changes in release 3.23.38 (09 May 2001) .................................. 1642
E.4.23. Changes in release 3.23.37 (17 Apr 2001) ................................... 1642
E.4.24. Changes in release 3.23.36 (27 Mar 2001) .................................. 1643
E.4.25. Changes in release 3.23.35 (15 Mar 2001) .................................. 1644
E.4.26. Changes in release 3.23.34a (11 Mar 2001) ................................. 1644
E.4.27. Changes in release 3.23.34 (10 Mar 2001) .................................. 1644
E.4.28. Changes in release 3.23.33 (09 Feb 2001) ................................... 1645
E.4.29. Changes in release 3.23.32 (22 Jan 2001) ................................... 1647
E.4.30. Changes in release 3.23.31 (17 Jan 2001: Production) ................... 1647
E.4.31. Changes in release 3.23.30 (04 Jan 2001) ................................... 1648
E.4.32. Changes in release 3.23.29 (16 Dec 2000) .................................. 1649
E.4.33. Changes in release 3.23.28 (22 Nov 2000: Gamma) ...................... 1651
E.4.34. Changes in release 3.23.27 (24 Oct 2000) ................................... 1652
E.4.35. Changes in release 3.23.26 (18 Oct 2000) ................................... 1653
E.4.36. Changes in release 3.23.25 (29 Sep 2000) ................................... 1654
E.4.37. Changes in release 3.23.24 (08 Sep 2000) ................................... 1655
E.4.38. Changes in release 3.23.23 (01 Sep 2000) ................................... 1655
E.4.39. Changes in release 3.23.22 (31 Jul 2000) .................................... 1657
E.4.40. Changes in release 3.23.21 (04 Jul 2000) .................................... 1657
E.4.41. Changes in release 3.23.20 (28 Jun 2000: Beta) ........................... 1658
E.4.42. Changes in release 3.23.19 ...................................................... 1658
E.4.43. Changes in release 3.23.18 (11 Jun 2000) ................................... 1659
E.4.44. Changes in release 3.23.17 (07 Jun 2000) ................................... 1659
E.4.45. Changes in release 3.23.16 (16 May 2000) .................................. 1660
E.4.46. Changes in release 3.23.15 (08 May 2000) .................................. 1660
E.4.47. Changes in release 3.23.14 (09 Apr 2000) ................................... 1661
E.4.48. Changes in release 3.23.13 (14 Mar 2000) .................................. 1662
E.4.49. Changes in release 3.23.12 (07 Mar 2000) .................................. 1662
E.4.50. Changes in release 3.23.11 (16 Feb 2000) ................................... 1663
E.4.51. Changes in release 3.23.10 (30 Jan 2000) ................................... 1664
E.4.52. Changes in release 3.23.9 (29 Jan 2000) ..................................... 1664
E.4.53. Changes in release 3.23.8 (02 Jan 2000) ..................................... 1665
E.4.54. Changes in release 3.23.7 (10 Dec 1999) .................................... 1665
E.4.55. Changes in release 3.23.6 (15 Nov 1999) .................................... 1666
E.4.56. Changes in release 3.23.5 (20 Oct 1999) ..................................... 1667
E.4.57. Changes in release 3.23.4 (28 Sep 1999) .................................... 1668
E.4.58. Changes in release 3.23.3 (13 Sep 1999) .................................... 1668
E.4.59. Changes in release 3.23.2 (09 Aug 1999) .................................... 1669
E.4.60. Changes in release 3.23.1 (08 Jul 1999) ...................................... 1670
E.4.61. Changes in release 3.23.0 (05 Jul 1999: Alpha) ............................ 1670
E.5. Changes in release 3.22.x (Old; discontinued) ......................................... 1672
E.5.1. Changes in release 3.22.35 ........................................................ 1672
E.5.2. Changes in release 3.22.34 ........................................................ 1672
E.5.3. Changes in release 3.22.33 ........................................................ 1672
E.5.4. Changes in release 3.22.32 (14 Feb 2000) .................................... 1672
E.5.5. Changes in release 3.22.31 ........................................................ 1673
E.5.6. Changes in release 3.22.30 (11 Jan 2000) ..................................... 1673
E.5.7. Changes in release 3.22.29 (02 Jan 2000) ..................................... 1673
xviii
MySQL Reference Manual
E.5.8. Changes in release 3.22.28 (20 Oct 1999) ..................................... 1673
E.5.9. Changes in release 3.22.27 (05 Oct 1999) ..................................... 1674
E.5.10. Changes in release 3.22.26 (16 Sep 1999) ................................... 1674
E.5.11. Changes in release 3.22.25 (07 Jun 1999) ................................... 1674
E.5.12. Changes in release 3.22.24 (05 Jul 1999) .................................... 1674
E.5.13. Changes in release 3.22.23 (08 Jun 1999) ................................... 1675
E.5.14. Changes in release 3.22.22 (30 Apr 1999) ................................... 1675
E.5.15. Changes in release 3.22.21 (04 Apr 1999) ................................... 1675
E.5.16. Changes in release 3.22.20 (18 Mar 1999) .................................. 1676
E.5.17. Changes in release 3.22.19 (01 Mar 1999) .................................. 1676
E.5.18. Changes in release 3.22.18 (26 Feb 1999) ................................... 1676
E.5.19. Changes in release 3.22.17 (22 Feb 1999: Production) .................. 1676
E.5.20. Changes in release 3.22.16 (05 Feb 1999) ................................... 1676
E.5.21. Changes in release 3.22.15 (27 Jan 1999) ................................... 1677
E.5.22. Changes in release 3.22.14 (01 Jan 1999: Gamma) ....................... 1677
E.5.23. Changes in release 3.22.13 (16 Dec 1998) .................................. 1677
E.5.24. Changes in release 3.22.12 (09 Dec 1998) .................................. 1678
E.5.25. Changes in release 3.22.11 (24 Nov 1998) .................................. 1678
E.5.26. Changes in release 3.22.10 (04 Nov 1998) .................................. 1679
E.5.27. Changes in release 3.22.9 (19 Oct 1998) ..................................... 1680
E.5.28. Changes in release 3.22.8 (06 Oct 1998) ..................................... 1680
E.5.29. Changes in release 3.22.7 (21 Sep 1998: Beta) ............................. 1681
E.5.30. Changes in release 3.22.6 (31 Aug 1998) .................................... 1681
E.5.31. Changes in release 3.22.5 (20 Aug 1998: Alpha) .......................... 1681
E.5.32. Changes in release 3.22.4 (06 Jul 1998: Beta) .............................. 1683
E.5.33. Changes in release 3.22.3 (30 Jun 1998) ..................................... 1684
E.5.34. Changes in release 3.22.2 ........................................................ 1684
E.5.35. Changes in release 3.22.1 (Jun 1998) ......................................... 1684
E.5.36. Changes in release 3.22.0 (18 May 1998: Alpha) ......................... 1685
E.6. Changes in release 3.21.x .................................................................... 1686
E.6.1. Changes in release 3.21.33 (08 Jul 1998) ...................................... 1686
E.6.2. Changes in release 3.21.32 (30 Jun 1998) ..................................... 1687
E.6.3. Changes in release 3.21.31 (10 Jun 1998) ..................................... 1687
E.6.4. Changes in release 3.21.30 ........................................................ 1687
E.6.5. Changes in release 3.21.29 ........................................................ 1688
E.6.6. Changes in release 3.21.28 ........................................................ 1688
E.6.7. Changes in release 3.21.27 ........................................................ 1688
E.6.8. Changes in release 3.21.26 ........................................................ 1689
E.6.9. Changes in release 3.21.25 ........................................................ 1689
E.6.10. Changes in release 3.21.24 ...................................................... 1689
E.6.11. Changes in release 3.21.23 ...................................................... 1690
E.6.12. Changes in release 3.21.22 ...................................................... 1690
E.6.13. Changes in release 3.21.21a ..................................................... 1691
E.6.14. Changes in release 3.21.21 ...................................................... 1691
E.6.15. Changes in release 3.21.20 ...................................................... 1691
E.6.16. Changes in release 3.21.19 ...................................................... 1692
E.6.17. Changes in release 3.21.18 ...................................................... 1692
E.6.18. Changes in release 3.21.17 ...................................................... 1692
E.6.19. Changes in release 3.21.16 ...................................................... 1693
E.6.20. Changes in release 3.21.15 ...................................................... 1693
E.6.21. Changes in release 3.21.14b ..................................................... 1694
E.6.22. Changes in release 3.21.14a ..................................................... 1694
E.6.23. Changes in release 3.21.13 ...................................................... 1694
E.6.24. Changes in release 3.21.12 ...................................................... 1695
E.6.25. Changes in release 3.21.11 ...................................................... 1696
E.6.26. Changes in release 3.21.10 ...................................................... 1696
E.6.27. Changes in release 3.21.9 ........................................................ 1697
E.6.28. Changes in release 3.21.8 ........................................................ 1697
E.6.29. Changes in release 3.21.7 ........................................................ 1697
E.6.30. Changes in release 3.21.6 ........................................................ 1698
E.6.31. Changes in release 3.21.5 ........................................................ 1698
E.6.32. Changes in release 3.21.4 ........................................................ 1698
E.6.33. Changes in release 3.21.3 ........................................................ 1698
xix
MySQL Reference Manual
E.6.34. Changes in release 3.21.2 ........................................................ 1699
E.6.35. Changes in release 3.21.0 ........................................................ 1700
E.7. Changes in release 3.20.x .................................................................... 1701
E.7.1. Changes in release 3.20.18 ........................................................ 1701
E.7.2. Changes in release 3.20.17 ........................................................ 1702
E.7.3. Changes in release 3.20.16 ........................................................ 1703
E.7.4. Changes in release 3.20.15 ........................................................ 1703
E.7.5. Changes in release 3.20.14 ........................................................ 1703
E.7.6. Changes in release 3.20.13 ........................................................ 1704
E.7.7. Changes in release 3.20.11 ........................................................ 1704
E.7.8. Changes in release 3.20.10 ........................................................ 1705
E.7.9. Changes in release 3.20.9 .......................................................... 1705
E.7.10. Changes in release 3.20.8 ........................................................ 1705
E.7.11. Changes in release 3.20.7 ........................................................ 1705
E.7.12. Changes in release 3.20.6 ........................................................ 1706
E.7.13. Changes in release 3.20.3 ........................................................ 1707
E.7.14. Changes in release 3.20.0 ........................................................ 1708
E.8. Changes in release 3.19.x .................................................................... 1708
E.8.1. Changes in release 3.19.5 .......................................................... 1708
E.8.2. Changes in release 3.19.4 .......................................................... 1709
E.8.3. Changes in release 3.19.3 .......................................................... 1709
E.9. InnoDB Change History ..................................................................... 1709
E.9.1. MySQL/InnoDB-4.0.21, September 10, 2004 ................................ 1709
E.9.2. MySQL/InnoDB-4.1.4, August 31, 2004 ...................................... 1711
E.9.3. MySQL/InnoDB-4.1.3, June 28, 2004 ......................................... 1712
E.9.4. MySQL/InnoDB-4.1.2, May 30, 2004 ......................................... 1713
E.9.5. MySQL/InnoDB-4.0.20, May 18, 2004 ........................................ 1713
E.9.6. MySQL/InnoDB-4.0.19, May 4, 2004 ......................................... 1714
E.9.7. MySQL/InnoDB-4.0.18, February 13, 2004 .................................. 1715
E.9.8. MySQL/InnoDB-5.0.0, December 24, 2003 .................................. 1716
E.9.9. MySQL/InnoDB-4.0.17, December 17, 2003 ................................ 1716
E.9.10. MySQL/InnoDB-4.1.1, December 4, 2003 .................................. 1716
E.9.11. MySQL/InnoDB-4.0.16, October 22, 2003 ................................. 1716
E.9.12. MySQL/InnoDB-3.23.58, September 15, 2003 ............................ 1717
E.9.13. MySQL/InnoDB-4.0.15, September 10, 2003 .............................. 1717
E.9.14. MySQL/InnoDB-4.0.14, July 22, 2003 ....................................... 1717
E.9.15. MySQL/InnoDB-3.23.57, June 20, 2003 .................................... 1719
E.9.16. MySQL/InnoDB-4.0.13, May 20, 2003 ...................................... 1719
E.9.17. MySQL/InnoDB-4.1.0, April 3, 2003 ........................................ 1720
E.9.18. MySQL/InnoDB-3.23.56, March 17, 2003 .................................. 1720
E.9.19. MySQL/InnoDB-4.0.12, March 18, 2003 ................................... 1720
E.9.20. MySQL/InnoDB-4.0.11, February 25, 2003 ................................ 1720
E.9.21. MySQL/InnoDB-4.0.10, February 4, 2003 .................................. 1721
E.9.22. MySQL/InnoDB-3.23.55, January 24, 2003 ................................ 1721
E.9.23. MySQL/InnoDB-4.0.9, January 14, 2003 ................................... 1722
E.9.24. MySQL/InnoDB-4.0.8, January 7, 2003 ..................................... 1722
E.9.25. MySQL/InnoDB-4.0.7, December 26, 2002 ................................ 1722
E.9.26. MySQL/InnoDB-4.0.6, December 19, 2002 ................................ 1723
E.9.27. MySQL/InnoDB-3.23.54, December 12, 2002 ............................. 1723
E.9.28. MySQL/InnoDB-4.0.5, November 18, 2002 ................................ 1723
E.9.29. MySQL/InnoDB-3.23.53, October 9, 2002 ................................. 1724
E.9.30. MySQL/InnoDB-4.0.4, October 2, 2002 ..................................... 1725
E.9.31. MySQL/InnoDB-4.0.3, August 28, 2002 .................................... 1725
E.9.32. MySQL/InnoDB-3.23.52, August 16, 2002 ................................. 1726
E.9.33. MySQL/InnoDB-4.0.2, July 10, 2002 ........................................ 1727
E.9.34. MySQL/InnoDB-3.23.51, June 12, 2002 .................................... 1727
E.9.35. MySQL/InnoDB-3.23.50, April 23, 2002 ................................... 1728
E.9.36. MySQL/InnoDB-3.23.49, February 17, 2002 .............................. 1728
E.9.37. MySQL/InnoDB-3.23.48, February 9, 2002 ................................ 1729
E.9.38. MySQL/InnoDB-3.23.47, December 28, 2001 ............................. 1729
E.9.39. MySQL/InnoDB-4.0.1, December 23, 2001 ................................ 1730
E.9.40. MySQL/InnoDB-3.23.46, November 30, 2001 ............................ 1730
E.9.41. MySQL/InnoDB-3.23.45, November 23, 2001 ............................ 1730
xx
MySQL Reference Manual
E.9.42. MySQL/InnoDB-3.23.44, November 2, 2001 .............................. 1731
E.9.43. MySQL/InnoDB-3.23.43, October 4, 2001 ................................. 1731
E.9.44. MySQL/InnoDB-3.23.42, September 9, 2001 .............................. 1732
E.9.45. MySQL/InnoDB-3.23.41, August 13, 2001 ................................. 1732
E.9.46. MySQL/InnoDB-3.23.40, July 16, 2001 ..................................... 1732
E.9.47. MySQL/InnoDB-3.23.39, June 13, 2001 .................................... 1732
E.9.48. MySQL/InnoDB-3.23.38, May 12, 2001 .................................... 1732
E.10. MySQL Cluster Change History ..................................................... 1733
E.10.1. MySQL Cluster-5.0.7 (not released yet) ..................................... 1733
E.10.2. MySQL Cluster-5.0.6 (26 May 2005) ........................................ 1733
E.10.3. MySQL Cluster-5.0.5 (not released) .......................................... 1733
E.10.4. MySQL Cluster-5.0.4 (16 Apr 2005) ......................................... 1734
E.10.5. MySQL Cluster-5.0.3 (23 Mar 2005: Beta) ................................. 1734
E.10.6. MySQL Cluster-5.0.1 (27 Jul 2004) ........................................... 1735
E.10.7. MySQL Cluster-4.1.13 (15 Jul 2005) ......................................... 1735
E.10.8. MySQL Cluster-4.1.12 (13 May 2005) ....................................... 1736
E.10.9. MySQL Cluster-4.1.11 (01 Apr 2005) ........................................ 1737
E.10.10. MySQL Cluster-4.1.10 (12 Feb 2005) ...................................... 1737
E.10.11. MySQL Cluster-4.1.9 (13 Jan 2005) ........................................ 1738
E.10.12. MySQL Cluster-4.1.8 (14 Dec 2004) ....................................... 1738
E.10.13. MySQL Cluster-4.1.7 (23 Oct 2004) ........................................ 1741
E.10.14. MySQL Cluster-4.1.6 (10 Oct 2004) ........................................ 1741
E.10.15. MySQL Cluster-4.1.5 (16 Sep 2004) ........................................ 1742
E.10.16. MySQL Cluster-4.1.4 (31 Aug 2004) ....................................... 1744
E.10.17. MySQL Cluster-4.1.3 (28 Jun 2004) ........................................ 1744
E.11. Changes in MyODBC ....................................................................... 1744
E.11.1. Changes in MyODBC 3.51.12 .................................................. 1744
E.11.2. Changes in MyODBC 3.51.11 .................................................. 1744
F. Porting to Other Systems ................................................................................ 1746
F.1. Debugging a MySQL Server ................................................................ 1747
F.1.1. Compiling MySQL for Debugging .............................................. 1747
F.1.2. Creating Trace Files ................................................................. 1748
F.1.3. Debugging mysqld under gdb ................................................. 1748
F.1.4. Using a Stack Trace ................................................................. 1750
F.1.5. Using Log Files to Find Cause of Errors in mysqld ...................... 1750
F.1.6. Making a Test Case If You Experience Table Corruption ................ 1751
F.2. Debugging a MySQL Client ................................................................. 1752
F.3. The DBUG Package ........................................................................... 1752
F.4. Comments about RTS Threads ............................................................. 1754
F.5. Differences Between Thread Packages ................................................... 1755
G. Environment Variables .................................................................................. 1756
H. MySQL Regular Expressions ......................................................................... 1757
I. MySQL Feature Restrictions ........................................................................... 1761
I.1. Restrictions on Stored Routines and Triggers ........................................... 1761
I.2. Restrictions on Server-Side Cursors ........................................................ 1762
I.3. Restrictions on Subqueries .................................................................... 1762
I.4. Restrictions on Views .......................................................................... 1765
I.5. Restrictions on XA Transactions ............................................................ 1766
J. GNU General Public License ........................................................................... 1767
K. MySQL FLOSS License Exception ................................................................. 1772
Index ............................................................................................................. 1774
xxi
List of Tables
24.1. Connection Properties ............................................................................... 1279
24.2. Conversion Table ..................................................................................... 1294
24.3. MySQL Types to Java Types for ResultSet.getObject() .................................... 1295
24.4. MySQL to Java Encoding Name Translations ................................................ 1296
xxii
List of Examples
24.1. Obtaining a Connection From the DriverManager ........................................... 1266
24.2. Using java.sql.Statement to Execute a SELECT Query .................................... 1267
24.3. Stored Procedure Example ......................................................................... 1268
24.4. Using Connection.prepareCall() .................................................................. 1268
24.5. Registering Output Parameters .................................................................... 1269
24.6. Setting CallableStatement Input Parameters ................................................... 1270
24.7. Retrieving Results and Output Parameter Values ............................................ 1270
24.8. Retrieving AUTO_INCREMENT Column Values using Statement.getGeneratedKeys()
...................................................................................................................... 1271
24.9.
Retrieving
AUTO_INCREMENT
Column
Values
using
'SELECT
LAST_INSERT_ID()' ....................................................................................... 1272
24.10. Retrieving AUTO_INCREMENT Column Values in Updatable ResultSets ........ 1273
24.11. Setting the CLASSPATH Under UNIX ....................................................... 1276
24.12. Using a Connection Pool with a J2EE Application Server ............................... 1302
24.13. Example of transaction with retry logic ....................................................... 1309
xxiii
Preface
This is the Reference Manual for the MySQL Database System. It documents MySQL up to Version
5.0.11-beta, but is also applicable for older versions of the MySQL software (such as 3.23 or
4.0-production) because functional changes are indicated with reference to a version number.
xxiv
Chapter 1. General Information
The MySQL® software delivers a very fast, multi-threaded, multi-user, and robust SQL (Structured
Query Language) database server. MySQL Server is intended for mission-critical, heavy-load production systems as well as for embedding into mass-deployed software. MySQL is a registered
trademark of MySQL AB.
The MySQL software is Dual Licensed. Users can choose to use the MySQL software as an Open
Source product under the terms of the GNU General Public License (http://www.fsf.org/licenses/) or
can purchase a standard commercial license from MySQL AB. See http://www.mysql.com/company/legal/licensing/ for more information on our licensing policies.
The following list describes some sections of particular interest in this manual:
•
For a discussion about the capabilities of the MySQL Database Server, see Section 1.4.2, “The
Main Features of MySQL”.
•
For installation instructions, see Chapter 2, Installing MySQL.
•
For tips on porting the MySQL Database Software to new architectures or operating systems,
see Appendix F, Porting to Other Systems.
•
For information about upgrading from a Version 4.1 release, see Section 2.10.2, “Upgrading
from Version 4.1 to 5.0”.
•
For information about upgrading from a Version 4.0 release, see Section 2.10.3, “Upgrading
from Version 4.0 to 4.1”.
•
For information about upgrading from a Version 3.23 release, see Section 2.10.4, “Upgrading
from Version 3.23 to 4.0”.
•
For a tutorial introduction to the MySQL Database Server, see Chapter 3, MySQL Tutorial.
•
For examples of SQL and benchmarking information, see the benchmarking directory (sqlbench in the distribution).
•
For a history of new features and bugfixes, see Appendix E, MySQL Change History.
•
For a list of currently known bugs and misfeatures, see Section A.8, “Known Issues in MySQL”.
•
For future plans, see Appendix D, MySQL and the Future (the TODO).
•
For a list of all the contributors to this project, see Appendix C, Credits.
Important:
Reports of errors (often called “bugs”), as well as questions and comments, should be sent to http://bugs.mysql.com. See Section 1.7.1.3, “How to Report Bugs or Problems”.
If you have found a sensitive security bug in MySQL Server, please let us know immediately by
sending an email message to <[email protected]>.
1.1. About This Manual
This is the Reference Manual for all releases of the MySQL Database System through Version
5.0.11-beta. It is also applicable for all previous versions of the MySQL software (such as 3.23 or
4.0) because functional changes are indicated with reference to version numbers. Because this
manual serves as a reference, it does not provide general instruction on SQL or relational database
concepts. It also does not teach you how to use your operating system or command-line interpreter.
1
General Information
The MySQL Database Software is under constant development, and the Reference Manual is updated frequently as well. The most recent version of the manual is available online in searchable
form at http://dev.mysql.com/doc/. Other formats also are available, including HTML, PDF, and
Windows CHM versions.
The primary document is a set of DocBook [http://docbook.org/] XML files. The HTML version
and other formats are produced automatically using, among other tools, the DocBook XSL
stylesheets [http://docbook.sourceforge.net/release/xsl/current/doc/reference.html].
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 maintained by the MySQL Documentation Team, consisting of Paul DuBois, Stefan Hinz, Mike Hillyer,
and Jon Stephens. For the many other contributors, see Appendix C, Credits.
The copyright to this manual is owned by the Swedish company MySQL AB. MySQL® and the
MySQL logo are registered trademarks of MySQL AB. Other trademarks and registered trademarks
referred to in this manual are the property of their respective owners, and are used for identification
purposes only.
1.2. Conventions Used in This Manual
This manual uses certain typographical conventions:
•
Text in this style is used for SQL statements; database, table, and column names; C
and Perl code; and environment variables. Example: “To reload the grant tables, use the FLUSH
PRIVILEGES statement”.
Text in this style is used to indicate input that you type in examples.
•
Text in this style is used to indicate the names of executable programs and scripts, examples being mysql (the MySQL command line client program) and mysqld (the MySQL
server executable).
•
Text in this style is used for variable input for which you should substitute a value of
your own choosing.
•
Filenames and directory names are written like this: “The global my.cnf file is located in the /
etc directory”.
•
Character sequences are written like this: “To specify a wildcard, use the ‘%’ character”.
•
Text in this style is used for emphasis.
•
Text in this style is used in table headings and to convey especially strong emphasis.
When commands are shown that are meant to be executed from within a particular program, the program is indicated by a prompt shown before the command. For example, shell> indicates a command that you execute from your login shell, and mysql> indicates a statement that you execute
from the mysql client program:
shell> type a shell command here
mysql> type a mysql statement here
The “shell” is your command interpreter. On Unix, this is typically a program such as sh, csh, or
bash. On Windows, the equivalent program is command.com or cmd.exe, typically run in a
console window.
When you enter a command or statement shown in an example, do not type the prompt shown in the
2
General Information
example.
Database, table, and column names must often be substituted into statements. To indicate that such
substitution is necessary, this manual uses db_name, tbl_name, and col_name. For example,
you might see a statement like this:
mysql> SELECT col_name FROM db_name.tbl_name;
This means that if you were to enter a similar statement, you would supply your own database, table, and column names, perhaps like this:
mysql> SELECT author_name FROM biblio_db.author_list;
SQL keywords are not case sensitive and may be written in uppercase or lowercase. This manual
uses uppercase.
In syntax descriptions, square brackets (‘[’ and ‘]’) are used to indicate optional words or clauses.
For example, in the following statement, IF EXISTS is optional:
DROP TABLE [IF EXISTS] tbl_name
When a syntax element consists of a number of alternatives, the alternatives are separated by vertical bars (‘|’). When one member from a set of choices may be chosen, the alternatives are listed
within square brackets (‘[’ and ‘]’):
TRIM([[BOTH | LEADING | TRAILING] [remstr] FROM] str)
When one member from a set of choices must be chosen, the alternatives are listed within braces
(‘{’ and ‘}’):
{DESCRIBE | DESC} tbl_name [col_name | wild]
An ellipsis (...) indicates the omission of a section of a statement, typically to provide a shorter
version of more complex syntax. For example, INSERT ... SELECT is shorthand for the form
of INSERT statement that is followed by a SELECT statement.
An ellipsis can also indicate that the preceding syntax element of a statement may be repeated. In
the following example, multiple reset_option values may be given, with each of those after the
first preceded by commas:
RESET reset_option [,reset_option] ...
Commands for setting shell variables are shown using Bourne shell syntax. For example, the sequence to set an environment variable and run a command looks like this in Bourne shell syntax:
shell> VARNAME=value some_command
If you are using csh or tcsh, you must issue commands somewhat differently. You would execute
the sequence just shown like this:
shell> setenv VARNAME value
shell> some_command
1.3. Overview of MySQL AB
MySQL AB is the company of the MySQL founders and main developers. MySQL AB was origin3
General Information
ally established in Sweden by David Axmark, Allan Larsson, and Michael “Monty” Widenius.
We are dedicated to developing the MySQL database software and promoting it to new users.
MySQL AB owns the copyright to the MySQL source code, the MySQL logo and (registered) trademark, and this manual. See Section 1.4, “Overview of the MySQL Database Management System”.
The MySQL core values show our dedication to MySQL and Open Source.
These core values direct how MySQL AB works with the MySQL server software:
•
To be the best and the most widely used database in the world
•
To be available and affordable by all
•
To be easy to use
•
To be continuously improved while remaining fast and safe
•
To be fun to use and improve
•
To be free from bugs
These are the core values of the company MySQL AB and its employees:
•
We subscribe to the Open Source philosophy and support the Open Source community
•
We aim to be good citizens
•
We prefer partners that share our values and mindset
•
We answer email and provide support
•
We are a virtual company, networking with others
•
We work against software patents
The MySQL Web site (http://www.mysql.com/) provides the latest information about MySQL and
MySQL AB.
By the way, the “AB” part of the company name is the acronym for the Swedish “aktiebolag,” or
“stock company.” It translates to “MySQL, Inc.” In fact, MySQL, Inc. and MySQL GmbH are examples of MySQL AB subsidiaries. They are located in the US and Germany, respectively.
1.4. Overview of the MySQL Database Management System
MySQL, the most popular Open Source SQL database management system, is developed, distributed, and supported by MySQL AB. MySQL AB is a commercial company, founded by the MySQL
developers. It is a second generation Open Source company that unites Open Source values and
methodology with a successful business model.
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
4
General Information
picture gallery or the vast amounts of information in a corporate network. To add, access, and
process data stored in a computer database, you need a database management system such as
MySQL Server. Since computers are very good at handling large amounts of data, database
management systems play a central role in computing, as standalone utilities or as parts of other
applications.
•
MySQL is a relational database management system.
A relational database stores data in separate tables rather than putting all the data in one big storeroom. This adds speed and flexibility. The SQL part of “MySQL” stands for “Structured Query
Language.” SQL is the most common standardized language used to access databases and is
defined by the ANSI/ISO SQL Standard. The SQL standard has been evolving since 1986 and
several versions exist. In this manual, “SQL-92” refers to the standard released in 1992,
“SQL:1999” refers to the standard released in 1999, and “SQL:2003” refers to the current version of the standard. We use the phrase “the SQL standard” to mean the current version of the
SQL Standard at any time.
•
MySQL software is Open Source.
Open Source means that it is possible for anyone to use and modify the software. Anybody can
download the MySQL software from the Internet and use it without paying anything. If you
wish, you may study the source code and change it to suit your needs. The MySQL software
uses the GPL (GNU General Public License), http://www.fsf.org/licenses/, to define what you
may and may not do with the software in different situations. If you feel uncomfortable with the
GPL or need to embed MySQL code into a commercial application, you can buy a commercially
licensed version from us. See the MySQL Licensing Overview for more information (http://www.mysql.com/company/legal/licensing/).
•
The MySQL Database Server is very fast, reliable, and easy to use.
If that is what you are looking for, you should give it a try. MySQL Server also has a practical
set of features developed in close cooperation with our users. You can find a performance comparison of MySQL Server with other database managers on our benchmark page. See Section 7.1.4, “The MySQL Benchmark Suite”.
MySQL Server was originally developed to handle large databases much faster than existing
solutions and has been successfully used in highly demanding production environments for several years. Although under constant development, MySQL Server today offers a rich and useful
set of functions. Its connectivity, speed, and security make MySQL Server highly suited for accessing databases on the Internet.
•
MySQL Server works in client/server or embedded systems.
The MySQL Database Software is a client/server system that consists of a multi-threaded SQL
server that supports different backends, several different client programs and libraries, administrative tools, and a wide range of application programming interfaces (APIs).
We also provide MySQL Server as an embedded multi-threaded library that you can link into
your application to get a smaller, faster, easier-to-manage product.
•
A large amount of contributed MySQL software is available.
It is very likely that your favorite application or language supports the MySQL Database Server.
The official way to pronounce “MySQL” is “My Ess Que Ell” (not “my sequel”), but we don't mind
if you pronounce it as “my sequel” or in some other localized way.
1.4.1. History of MySQL
We started out with the intention of using mSQL to connect to our tables using our own fast lowlevel (ISAM) routines. However, after some testing, we came to the conclusion that mSQL was not
5
General Information
fast enough or flexible enough for our needs. This resulted in a new SQL interface to our database
but with almost the same API interface as mSQL. This API was designed to allow third-party code
that was written for use with mSQL to be ported easily for use with MySQL.
The derivation of the name MySQL is not clear. Our base directory and a large number of our libraries and tools have had the prefix “my” for well over 10 years. However, co-founder Monty Widenius's daughter is also named My. Which of the two gave its name to MySQL is still a mystery, even
for us.
The name of the MySQL Dolphin (our logo) is “Sakila,” which was chosen by the founders of
MySQL AB from a huge list of names suggested by users in our “Name the Dolphin” contest. The
winning name was submitted by Ambrose Twebaze, an Open Source software developer from
Swaziland, Africa. According to Ambrose, the feminine name Sakila has its roots in SiSwati, the
local language of Swaziland. Sakila is also the name of a town in Arusha, Tanzania, near Ambrose's
country of origin, Uganda.
1.4.2. The Main Features of MySQL
The following list describes some of the important characteristics of the MySQL Database Software.
See also Section 1.6, “MySQL Development Roadmap” for more information about current and upcoming features.
•
Internals and Portability
•
Written in C and C++.
•
Tested with a broad range of different compilers.
•
Works on many different platforms. See Section 2.1.1, “Operating Systems Supported by
MySQL”.
•
Uses GNU Automake, Autoconf, and Libtool for portability.
•
APIs for C, C++, Eiffel, Java, Perl, PHP, Python, Ruby, and Tcl are available. See
Chapter 23, MySQL APIs and Libraries.
•
Fully multi-threaded using kernel threads. It can easily use multiple CPUs if they are available.
•
Provides transactional and non-transactional storage engines.
•
Uses very fast B-tree disk tables (MyISAM) with index compression.
•
Relatively easy to add another storage engine. This is useful if you want to add an SQL interface to an in-house database.
•
A very fast thread-based memory allocation system.
•
Very fast joins using an optimized one-sweep multi-join.
•
In-memory hash tables, which are used as temporary tables.
•
SQL functions are implemented using a highly optimized class library and should be as fast
as possible. Usually there is no memory allocation at all after query initialization.
•
The MySQL code is tested with Purify (a commercial memory leakage detector) as well as
with Valgrind, a GPL tool (http://developer.kde.org/~sewardj/).
•
The server is available as a separate program for use in a client/server networked environment. It is also available as a library that can be embedded (linked) into standalone applications. Such applications can be used in isolation or in environments where no network is
available.
6
General Information
•
•
Column Types
•
Many column types: signed/unsigned integers 1, 2, 3, 4, and 8 bytes long, FLOAT, DOUBLE,
CHAR, VARCHAR, TEXT, BLOB, DATE, TIME, DATETIME, TIMESTAMP, YEAR, SET,
ENUM, and OpenGIS spatial types. See Chapter 11, Column Types.
•
Fixed-length and variable-length records.
Statements 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 citizen
-> 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 standard SQL.
•
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.
•
The MySQL-specific SHOW command can be used to retrieve information about databases,
database engines, tables, and indexes. The EXPLAIN command can be used to determine
how the optimizer resolves a query.
•
Function names do not clash with table or column names. For example, ABS is a valid
column name. The only restriction is that for a function call, no spaces are allowed between
the function name and the ‘(’ that follows it. See Section 9.6, “Treatment of Reserved
Words in MySQL”.
•
You can mix tables from different databases in the same query (as of MySQL 3.22).
Security
•
•
•
A privilege and password system that is very flexible and secure, and that allows host-based
verification. Passwords are secure because all password traffic is encrypted when you connect to a server.
Scalability and Limits
•
Handles large databases. We use MySQL Server with databases that contain 50 million records. We also know of users who use MySQL Server with 60,000 tables and about
5,000,000,000 rows.
•
Up to 64 indexes per table are allowed (32 before MySQL 4.1.2). Each index may consist of
1 to 16 columns or parts of columns. The maximum index width is 1000 bytes (500 before
MySQL 4.1.2). An index may use a prefix of a column for CHAR, VARCHAR, BLOB, or
TEXT column types.
Connectivity
•
Clients can connect to the MySQL server using TCP/IP sockets on any platform. On Windows systems in the NT family (NT, 2000, XP, or 2003), clients can connect using named
pipes. On Unix systems, clients can connect using Unix domain socket files.
7
General Information
•
•
•
In MySQL versions 4.1 and higher, Windows servers also support shared-memory connections if started with the --shared-memory option. Clients can connect through shared
memory by using the --protocol=memory option.
•
The Connector/ODBC (MyODBC) interface provides MySQL support for client programs
that use ODBC (Open Database Connectivity) connections. For example, you can use MS
Access to connect to your MySQL server. Clients can be run on Windows or Unix. MyODBC source is available. All ODBC 2.5 functions are supported, as are many others. See
Chapter 24, MySQL Connectors.
•
The Connector/J interface provides MySQL support for Java client programs that use JDBC
connections. Clients can be run on Windows or Unix. Connector/J source is available. See
Chapter 24, MySQL Connectors.
Localization
•
The server can provide error messages to clients in many languages. See Section 5.9.2,
“Setting the Error Message Language”.
•
Full support for several different character sets, including latin1 (cp1252), german,
big5, ujis, and more. For example, the Scandinavian characters ‘å’, ‘ä’ and ‘ö’ are allowed in table and column names. Unicode support is available as of MySQL 4.1.
•
All data is saved in the chosen character set. All comparisons for normal string columns are
case-insensitive.
•
Sorting is done according to the chosen character set (using Swedish collation by default). It
is possible to change this when the MySQL server is started. To see an example of very advanced sorting, look at the Czech sorting code. MySQL Server supports many different character sets that can be specified at compile time and runtime.
Clients and Tools
•
The MySQL server has built-in support for SQL statements to check, optimize, and repair
tables. These statements are available from the command line through the mysqlcheck client. MySQL also includes myisamchk, a very fast command-line utility for performing
these operations on MyISAM tables. See Chapter 5, Database Administration.
•
All MySQL programs can be invoked with the --help or -? options to obtain online assistance.
1.4.3. MySQL Stability
This section addresses the questions, “How stable is MySQL Server?” and, “Can I depend on
MySQL Server in this project?” We will try to clarify these issues and answer some important questions that concern many potential users. The information in this section is based on data gathered
from the mailing lists, which are very active in identifying problems as well as reporting types of
use.
The original code stems back to the early 1980s. It provides a stable code base, and the ISAM table
format used by the original storage engine remains backward-compatible. At TcX, the predecessor
of MySQL AB, MySQL code has worked in projects since mid-1996, without any problems. When
the MySQL Database Software initially was released to a wider public, our new users quickly found
some pieces of untested code. Each new release since then has had fewer portability problems, even
though each new release has also had many new features.
Each release of the MySQL Server has been usable. Problems have occurred only when users try
code from the “gray zones.” Naturally, new users don't know what the gray zones are; this section
therefore attempts to document those areas that are currently known. The descriptions mostly deal
with Versions 3.23 and later 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 Sec8
General Information
tion A.8, “Known Issues in MySQL”.
The MySQL Server design is multi-layered with independent modules. Some of the newer modules
are listed here with an indication of how well-tested each of them is:
•
Replication (Stable)
Large groups of servers using replication are in production use, with good results. Work on enhanced replication features is continuing in MySQL 5.x.
•
InnoDB tables (Stable)
The InnoDB transactional storage engine has been stable since version 3.23.49. InnoDB is being used in large, heavy-load production systems.
•
BDB tables (Stable)
The Berkeley DB code is very stable, but we are still improving the BDB transactional storage engine interface in MySQL Server.
•
Full-text searches (Stable)
Full-text searching is widely used. Important feature enhancements were added in MySQL 4.0
and 4.1.
•
MyODBC 3.51 (Stable)
MyODBC 3.51 uses ODBC SDK 3.51 and is in wide production use. Some issues brought up appear to be application-related and independent of the ODBC driver or underlying database server.
1.4.4. How Big MySQL Tables Can Be
MySQL 3.22 had a 4GB (4 gigabyte) limit on table size. With the MyISAM storage engine in
MySQL 3.23, the maximum table size was increased to 65536 terabytes (2567 – 1 bytes). With this
larger allowed table size, the maximum effective table size for MySQL databases is usually determined by operating system constraints on file sizes, not by MySQL internal limits.
The InnoDB storage engine maintains InnoDB tables within a tablespace that can be created from
several files. This allows a table to exceed the maximum individual file size. The tablespace can include raw disk partitions, which allows extremely large tables. The maximum tablespace size is
64TB.
The following table lists some examples of operating system file-size limits. This is only a rough
guide and is not intended to be definitive. For the most up-to-date information, be sure to check the
documentation specific to your operating system.
Operating System
File-size Limit
Linux 2.2-Intel 32-bit
2GB (LFS: 4GB)
Linux 2.4+
(using ext3 filesystem) 4TB
Solaris 9/10
16TB
NetWare w/NSS filesystem
8TB
win32 w/ FAT/FAT32
2GB/4GB
win32 w/ NTFS
2TB (possibly larger)
MacOS X w/ HFS+
2TB
On Linux 2.2, you can get MyISAM tables larger than 2GB in size by using the Large File Support
(LFS) patch for the ext2 filesystem. On Linux 2.4, patches also exist for ReiserFS to get support for
9
General Information
big files (up to 2TB). Most current Linux distributions are based on kernel 2.4 and include all the required LFS patches. With JFS and XFS, petabyte and larger files are possible on Linux. However,
the maximum available file size still depends on several factors, one of them being the filesystem
used to store MySQL tables.
For a detailed overview about LFS in Linux, have a look at Andreas Jaeger's Large File Support in
Linux page at http://www.suse.de/~aj/linux_lfs.html.
Windows users please note: FAT and VFAT (FAT32) are not considered suitable for production use
with MySQL. Use NTFS instead.
By default, MySQL creates MyISAM tables with an internal structure that allows a maximum size of
about 4GB. You can check the maximum table size for a table with the SHOW TABLE STATUS
statement or with myisamchk -dv tbl_name. See Section 13.5.4, “SHOW Syntax”.
If you need a MyISAM table that is larger than 4GB in size (and your operating system supports
large files), the CREATE TABLE statement allows AVG_ROW_LENGTH and MAX_ROWS options.
See Section 13.1.5, “CREATE TABLE Syntax”. You can also change these options with ALTER
TABLE after the table has been created, to increase the table's maximum allowable size. See Section 13.1.2, “ALTER TABLE Syntax”.
Other ways to work around file-size limits for MyISAM tables are as follows:
•
If your large table is read-only, you can use myisampack to compress it. myisampack usually compresses a table by at least 50%, so you can have, in effect, much bigger tables. myisampack also can merge multiple tables into a single table. See Section 8.2, “myisampack —
Generate Compressed, Read-Only MyISAM Tables”.
•
MySQL includes a MERGE library that allows you to handle a collection of MyISAM tables that
have identical structure as a single MERGE table. See Section 14.2, “The MERGE Storage Engine”.
1.4.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 implemented in one source file, sql/time.cc, and are coded
very carefully to be year 2000-safe.
•
In MySQL 3.22 and later, the YEAR column type can store the years 0 and 1901 to 2155 in
one byte and display them using two or four digits. All two-digit years are considered to be in
the range 1970 to 2069, which means that if you store 01 in a YEAR column, MySQL Server
treats it as 2001.
The following simple demonstration illustrates that MySQL Server has no problems with DATE or
DATETIME values through the year 9999, and no problems with TIMESTAMP values until after the
year 2030:
mysql> DROP TABLE IF EXISTS y2k;
Query OK, 0 rows affected (0.01 sec)
mysql> CREATE TABLE y2k (date DATE,
->
date_time DATETIME,
->
time_stamp TIMESTAMP);
Query OK, 0 rows affected (0.01 sec)
mysql> INSERT INTO y2k VALUES
-> ('1998-12-31','1998-12-31 23:59:59',19981231235959),
10
General Information
-> ('1999-01-01','1999-01-01 00:00:00',19990101000000),
-> ('1999-09-09','1999-09-09 23:59:59',19990909235959),
-> ('2000-01-01','2000-01-01 00:00:00',20000101000000),
-> ('2000-02-28','2000-02-28 00:00:00',20000228000000),
-> ('2000-02-29','2000-02-29 00:00:00',20000229000000),
-> ('2000-03-01','2000-03-01 00:00:00',20000301000000),
-> ('2000-12-31','2000-12-31 23:59:59',20001231235959),
-> ('2001-01-01','2001-01-01 00:00:00',20010101000000),
-> ('2004-12-31','2004-12-31 23:59:59',20041231235959),
-> ('2005-01-01','2005-01-01 00:00:00',20050101000000),
-> ('2030-01-01','2030-01-01 00:00:00',20300101000000),
-> ('2040-01-01','2040-01-01 00:00:00',20400101000000),
-> ('9999-12-31','9999-12-31 23:59:59',99991231235959);
Query OK, 14 rows affected (0.01 sec)
Records: 14 Duplicates: 0 Warnings: 2
mysql> SELECT * FROM y2k;
+------------+---------------------+----------------+
| date
| date_time
| time_stamp
|
+------------+---------------------+----------------+
| 1998-12-31 | 1998-12-31 23:59:59 | 19981231235959 |
| 1999-01-01 | 1999-01-01 00:00:00 | 19990101000000 |
| 1999-09-09 | 1999-09-09 23:59:59 | 19990909235959 |
| 2000-01-01 | 2000-01-01 00:00:00 | 20000101000000 |
| 2000-02-28 | 2000-02-28 00:00:00 | 20000228000000 |
| 2000-02-29 | 2000-02-29 00:00:00 | 20000229000000 |
| 2000-03-01 | 2000-03-01 00:00:00 | 20000301000000 |
| 2000-12-31 | 2000-12-31 23:59:59 | 20001231235959 |
| 2001-01-01 | 2001-01-01 00:00:00 | 20010101000000 |
| 2004-12-31 | 2004-12-31 23:59:59 | 20041231235959 |
| 2005-01-01 | 2005-01-01 00:00:00 | 20050101000000 |
| 2030-01-01 | 2030-01-01 00:00:00 | 20300101000000 |
| 2040-01-01 | 2040-01-01 00:00:00 | 00000000000000 |
| 9999-12-31 | 9999-12-31 23:59:59 | 00000000000000 |
+------------+---------------------+----------------+
14 rows in set (0.00 sec)
The final two TIMESTAMP column values are zero because the year values (2040, 9999) exceed
the TIMESTAMP maximum. The TIMESTAMP data type, which is used to store the current time,
supports values that range from 19700101000000 to 20300101000000 on 32-bit machines
(signed value). On 64-bit machines, TIMESTAMP handles values up to 2106 (unsigned value).
Although MySQL Server itself is Y2K-safe, you may run into problems if you use it with applications that are not Y2K-safe. For example, many old applications store or manipulate years using
two-digit values (which are ambiguous) rather than four-digit values. This problem may be compounded by applications that use values such as 00 or 99 as “missing” value indicators. Unfortunately, these problems may be difficult to fix because different applications may be written by different programmers, each of whom may use a different set of conventions and date-handling functions.
Thus, even though MySQL Server has no Y2K problems, it is the application's responsibility to
provide unambiguous input. See Section 11.3.4, “Y2K Issues and Date Types” for MySQL Server's
rules for dealing with ambiguous date input data that contains two-digit year values.
1.5. Overview of the MaxDB Database Management System
MaxDB is an heavy-duty enterprise database. The database management system is SAP-certified.
MaxDB is the new name of a database management system formerly called SAP DB. In 2003 SAP
AG and MySQL AB joined a partnership and re-branded the database system to MaxDB. The development of MaxDB has continued since then as it was done before – through the SAP developer
team.
11
General Information
MySQL AB co-operates closely with the MaxDB team at SAP around delivering improvements to
the MaxDB product. Joint efforts include development of new native drivers to enable more efficient usage of MaxDB in the Open Source community, and improvement of various documentation
to expand the MaxDB user base. Also interoperability features between MySQL and MaxDB database are seen as important, and for instance the new MaxDB Synchronization Manager supports
data synchronization from MaxDB to MySQL.
The MaxDB database management system does not share a common code-base with the MySQL
database management system. The MaxDB and MySQL database management systems are independed products provided by MySQL AB.
MySQL AB offers a complete portfolio of Professional Services for MaxDB.
1.5.1. What is MaxDB?
MaxDB is a ANSI SQL-92 (entry level) compliant relational database management system
(RDBMS) from SAP AG, that is delivered by MySQL AB as well. MaxDB fulfills the needs for enterprise usage: safety, scalability high concurrency and performance . It runs on all major operating
systems. Over the years it has proven able to run SAP R/3 and terabytes of data in 24x7 operation.
The database development started in 1977 as a research project at the Technical University of Berlin
. In the early 80s it became a database product that subsequently was owned by Nixdorf, Siemens
Nixdorf, Software AG and today – by SAP AG. Along this line it has been named VDN, Reflex,
Supra 2, DDB/4, Entire SQL-DB-Server and ADABAS. In 1997 SAP took over the software from
software AG and renamed it to SAP DB. Since October 2000 SAP DB sources additionally were released as open source under the GNU General Public License (see Appendix J, GNU General Public
License).
In 2003 SAP AG and MySQL AB joined a partnership and re-branded the database system to
MaxDB.
1.5.2. History of MaxDB
The history of MaxDB goes back to SAP DB, SAP AG's DBMS, i.e. MaxDB is a re-branded and
enhanced version of SAP DB. For many years, MaxDB has been used for small, medium, and large
installations of the mySAP Business Suite and other demanding SQL applications requiring an enterprise-class DBMS with regard to the number of users, the transactional workload, and the size of
the database.
SAP DB was meant to provide an alternative to third-party database systems such as Oracle, Microsoft SQL Server, and DB2 by IBM. In October 2000, SAP AG released SAP DB under the GNU
GPL license (see Appendix J, GNU General Public License), thus making it open source software.
Today, MaxDB is used in about 3,500 SAP customer installations worldwide. Moreover, the majority of all DBMS installations on Unix and Linux within SAP’s IT department rely on MaxDB.
MaxDB is tuned towards heavy-duty online transaction processing (OLTP) with several thousand
users and database sizes ranging from several hundred GB to multiple TB.
In 2003 SAP and MySQL concluded a partnership and development cooperation agreement. As a
result, SAP's database system SAP DB has been delivered under the name of MaxDB by MySQL
since the release of version 7.5 (November 2003).
Version 7.5 of MaxDB is a direct advancement of the SAP DB 7.4 code base. Therefore, the
MaxDB software version 7.5 can be used as a direct upgrade of previous SAP DB versions starting
7.2.04 and higher.
Now, as before, the former SAP DB development team at SAP AG is responsible for developing
and supporting MaxDB. MySQL AB co-operates closely with the MaxDB team at SAP around delivering improvements to the MaxDB product, see Section 1.5, “Overview of the MaxDB Database
Management System”. Both SAP AG and MySQL AB handle the sale and distribution of MaxDB.
The advancement of MaxDB and the MySQL Server leverages synergies that benefit both product
lines.
12
General Information
MaxDB is subjected to SAP AG's complete quality assurance process before it is shipped with SAP
solutions or provided as a download from the MySQL site.
1.5.3. Features of MaxDB
MaxDB is a heavy-duty, SAP-certified open source database for OLTP and OLAP usage which offers high reliability, availability, scalability and a very comprehensive feature set. It is targetted for
large mySAP Business Suite environments and other applications that require maximum enterpriselevel database functionality and complements the MySQL database server.
MaxDB operates as a client/server product. It was developed to meet the needs of installations in
OLTP and Data Warehouse/OLAP/Decision Support scenarios. Benefits:
•
Easy configuration and administration: GUI-based Installation Manager and Database Manager as single admin tools for DBMS operations
•
Around-the-clock operation, no planned downtimes, no permanent attendance required:
Automatic space management, no need for reorganizations
•
Elaborate backup and restore capabilities: Online and incremental backups, recovery wizard
to guide you through the recovery scenario
•
Supports large number of users, database sizes in the terabytes, and demanding workloads: Proven reliability, performance, and scalability
•
High availability: Cluster support, standby configuration, hot standby configuration
1.5.4. Licensing and Support
MaxDB can be used under the same licenses available for the other products distributed by MySQL
AB. Thus, MaxDB is available under the GNU General Public License, and a commercial license.
For more information on licensing, see http://www.mysql.com/company/legal/licensing/.
MySQL AB offers MaxDB technical support to non-SAP customers. The MaxDB support is available on various levels (Basic, Silver and Gold), which expand from unlimited email/web-support to
24x7 phone support for business critical systems.
MySQL AB also offers Licenses and Support for MaxDB when used with SAP Applications, like
SAP
NetWeaver
and
mySAP
Business
Suite.
Please
contact
[http://www.mysql.com/company/contact/] MySQL AB for more information on licenses and support for your needs.
Consulting and training services are available. MySQL gives classes on MaxDB in regular intervals,
see http://www.mysql.com/training/ for a list of classes.
1.5.5. Feature Differences Between MaxDB and MySQL
MaxDB is MySQL AB's SAP-certified database. The MaxDB database server complements the
MySQL AB product portfolio. Some MaxDB features are not availabe on the MySQL database
management server and vice versa.
The following list provides a short summary of the main differences between MaxDB and MySQL;
it is not complete.
•
MaxDB runs as a client/server system. MySQL can run as a client/server system or as an embedded system.
•
MaxDB might not run on all platforms supported by MySQL. For example, MaxDB does not
run on IBM's OS/2.
13
General Information
•
MaxDB uses a proprietary network protocol for client/server communication. MySQL uses
either TCP/IP (with or without SSL encryption), sockets (under Unix-like systems), or named
pipes (under Windows NT-family systems).
•
MaxDB supports stored procedures. For MySQL, stored procedures are implemented in version
5.0. MaxDB also supports programming of triggers through an SQL extension, which is scheduled for MySQL 5.1. MaxDB contains a debugger for stored procedure languages, can cascade
nested triggers, and supports multiple triggers per action and row.
•
MaxDB is distributed with user interfaces that are text-based, graphical, or Web-based. MySQL
is distributed with text-based user interfaces only; graphical user interface (MySQL Control
Center, MySQL Administrator) are shipped separately from the main distributions. Web-based
user interfaces for MySQL are offered by third parties.
•
MaxDB supports a number of programming interfaces that also are supported by MySQL. For
developing with MaxDB, the MaxDB ODBC Driver, SQL Database Connectivity (SQLDBC),
JDBC Driver, Perl and Python modules and a MaxDB PHP extension, which provides access to
the MySQL MaxDB databases using PHP, are available. Third Party Programming Interfaces:
Support for OLE DB, ADO, DAO, RDO and .NET through ODBC. MaxDB supports embedded
SQL with C/C++.
•
MaxDB includes administrative features that MySQL does not have: job scheduling by time,
event, and alert, and sending messages to a database administrator on alert thresholds.
1.5.6. Interoperability Features Between MaxDB and
MySQL
MaxDB and MySQL are independed database management servers. The interoperation of the systems is possible in a way that the systems can exchange their data. To exchange data between
MaxDB and MySQL you can use the im- and export tools of the systems or the MaxDB Synchronization Manager. The im- and export tools can be used to transfer data in a in-frequently, manual
fashion. The MaxDB Sychronization Manager offers faster, automatic data transfer capabilities.
The MaxDB Loader can be used to export data and object definitions. The Loader can export data
using MaxDB internal, binary formats and text formats (CSV). Data exported from MaxDB in text
formats can be re-imported to MySQL using the mysqldump database backup program. In order to
import MySQL data into MaxDB you can either use mysqldump to create INSERT statements or
SELECT ... INTO OUTFILE to create a text file (CSV). Use the MaxDB Loader to load the
data files generated by MySQL.
Object definitions can be exchanged between the systems using MaxDB Loader and the MySQL
tool mysqldump. As the SQL dialects of both systems differ slightly and MaxDB has features currently not supported by MySQL like SQL constraints, we recommend to hand-tune the definition
files. The mysqldump tool offers an option --compatible-name = maxdb to produce output that is compatible to MaxDB to make porting easier.
As part of MaxDB 7.6, the MaxDB Synchronization Manager is released. The Synchronization
Manager supports creation of asynchronous replication scenarios between several MaxDB instances.
However, interoperability features also are planned, so that the Synchronization Manager supports
replication to and from a MySQL server.
In the first release, the Synchronization Manager supports inserting data into MySQL. This means
that initially only replication from MaxDB to MySQL is supported. In the course of 2005, exporting
of data from a MySQL server to the Synchronization Manager will be added, thus adding support
for MySQL to MaxDB replication scenarios.
1.5.7. MaxDB-Related Links
The main page for information about MaxDB is http://www.mysql.com/products/maxdb. The page
gives details about the features of the MaxDB database management systems and has pointers to
14
General Information
documentation available.
The MySQL Reference Manaul does not contain any MaxDB documentation but the introduction
given in this section. MaxDB has it's own documentation, called the MaxDB library. The MaxDB
library is available on http://dev.mysql.com/doc/maxdb/index.html.
MySQL AB runs a community mailinglist on MaxDB, see http://lists.mysql.com/maxdb. The list
shows a vivid community discussion. Many of the core developers contribute to it. Product announcements are send to list.
A web forum on MaxDB is on http://forums.mysql.com/. The forum is for questions on MaxDB not
related to SAP application.
1.6. MySQL Development Roadmap
This section provides a snapshot of the MySQL development roadmap, including major features implemented in or planned for the various MySQL releases. The following sections provide information for each release series.
The current production release series is MySQL 4.1, which was declared stable for production use
as of Version 4.1.7, released in October 2004. The previous production release series is MySQL 4.0,
which was declared stable for production use as of Version 4.0.12, released in March 2003. Production status means that future 4.1 and 4.0 development is limited only to bugfixes. For the older
MySQL 3.23 series, only critical bugfixes are made.
Active MySQL development currently is taking place in the MySQL 5.0 release series; this means
that new features are being added there. MySQL 5.0 is available in beta status.
Before upgrading from one release series to the next, please see the notes at Section 2.10,
“Upgrading MySQL”.
The most requested features and the versions in which they were implemented or are scheduled for
implementation are summarized in the following table:
Feature
MySQL Series
Foreign keys
3.23 (for the InnoDB storage engine)
Unions
4.0
Subqueries
4.1
R-trees
4.1 (for the MyISAM storage engine)
Stored procedures
5.0
Views
5.0
Cursors
5.0
XA transactions
5.0
Foreign keys
5.1 (implemented in 3.23 for InnoDB)
Triggers
5.0 and 5.1
Full outer joins
5.1
Constraints
5.1 (implemented in 3.23 for InnoDB)
Partitioning
5.1
Row-Based Replication
5.1
1.6.1. MySQL 4.0 in a Nutshell
MySQL Server 4.0 is available in production status.
MySQL 4.0 is available for download at http://dev.mysql.com/ and from our mirrors. MySQL 4.0
15
General Information
has been tested by a large number of users and is in production use at many large sites.
1.6.1.1. Features Available in MySQL 4.0
•
•
Speed enhancements
•
MySQL 4.0 implemented a query cache that can give a major speed boost to applications
with repetitive queries. See Section 5.12, “The MySQL Query Cache”.
•
Version 4.0 further increased the speed of MySQL Server in a number of areas, such as bulk
INSERT statements, searching on packed indexes, full-text searching (using FULLTEXT indexes), and COUNT(DISTINCT).
Introduction of Embedded MySQL Server
•
•
InnoDB storage engine as standard
•
•
•
The enhanced FULLTEXT search capabilities of MySQL Server 4.0 enabled FULLTEXT indexing of large text masses with both binary and natural-language searching logic. It became
possible to customize minimal word length and define your own stop word lists in most human languages, enabling a broader class of applications to be built with MySQL Server. See
Section 12.7, “Full-Text Search Functions”.
Standards compliance, portability, and migration
•
MySQL Server added support for the UNION statement, a standard SQL feature.
•
Starting with version 4.0, MySQL runs natively on Novell NetWare 6.0 and higher. See Section 2.6, “Installing MySQL on NetWare”.
•
Features to simplify migration from other database systems to MySQL Server include
TRUNCATE TABLE (as in Oracle) .
Internationalization
•
•
The InnoDB storage engine began to be offered as a standard feature of the MySQL server.
This provided full support for ACID transactions, foreign keys with cascading UPDATE and
DELETE, and row-level locking as standard features. See Chapter 15, The InnoDB Storage
Engine.
New functionality
•
•
The Embedded Server library added in this release 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.6.1.2, “The Embedded MySQL Server”.
German-speaking users should note that MySQL 4.0 added support for a new character set,
latin1_de, which ensures that words with umlauts are sorted in the same order as in German telephone books.
Usability enhancements
•
As of Version 4.0, most mysqld parameters (startup options) can be set without taking
down the server. This is a convenient feature for database administrators. See Section 13.5.3,
“SET Syntax”.
•
Multiple-table DELETE and UPDATE statements were added.
•
On Windows, symbolic link handling at the database level was enabled by default. On Unix,
the MyISAM storage engine added support for symbolic linking at the table level (and not
just the database level as before).
•
The addition of the SQL_CALC_FOUND_ROWS and FOUND_ROWS() functions made it
16
General Information
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 MySQL 4.0 features. See Section E.3, “Changes in release 4.0.x (Production)”.
1.6.1.2. The Embedded MySQL Server
The libmysqld embedded server library made MySQL Server suitable for a wider range of applications. Using this library, developers can embed MySQL Server into various applications and
electronics devices, where the end user has no knowledge of there actually being an underlying database. Embedded MySQL Server is ideal for use in Internet appliances, public kiosks, turnkey hardware/software combination units, high performance Internet servers, self-contained databases distributed on CD-ROM, and so on.
The embedded MySQL library uses the same interface as the normal client library. See Section 23.1,
“libmysqld, the Embedded MySQL Server Library”. Embedded MySQL is available under the same
dual-licensing model as the MySQL Server; see http://www.mysql.com/company/legal/licensing/
for more information.
On Windows there are two different libraries:
libmysqld.lib
Dynamic library for threaded applications.
mysqldemb.lib
Static library for not threaded applications.
1.6.2. MySQL 4.1 in a Nutshell
MySQL Server 4.0 laid the foundation for new features implemented in MySQL 4.1, such as subqueries and Unicode support, which were desired by many of our customers.
MySQL Server 4.1 is currently in production status, and binaries are available for download at http://dev.mysql.com/downloads/mysql/4.1.html. All binary releases pass our extensive test suite
without any errors on the platforms on which we test. See Section E.2, “Changes in release 4.1.x
(Production)”.
For those wishing to use the most recent development source for MySQL 4.1, we also make our BitKeeper repositories publicly available. See Section 2.8.3, “Installing from the Development Source
Tree”.
1.6.2.1. Features Available in MySQL 4.1
This section lists features implemented in MySQL 4.1. Features that are available in MySQL 5.0 are
described in Section D.1, “New Features in MySQL 5.0”.
•
Support for subqueries and derived tables:
•
•
A “subquery” is a SELECT statement nested within another statement. A “derived table” (an
unnamed view) is a subquery in the FROM clause of another statement. See Section 13.2.8,
“Subquery Syntax”.
Speed enhancements:
•
Faster binary client/server protocol with support for prepared statements and parameter binding. See Section 23.2.4, “C API Prepared Statements”.
•
BTREE indexing is supported for HEAP tables, significantly improving response time for
non-exact searches.
17
General Information
•
Added functionality:
•
CREATE TABLE tbl_name2 LIKE tbl_name1 allows you to create, with a single
statement, a new table with a structure exactly like that of an existing table.
•
The MyISAM storage engine added support for OpenGIS spatial types for storing geographical data. See Chapter 17, Spatial Extensions in MySQL.
•
Support was added for replication over SSL connections.
•
Support for a number of additional storage engines was implemented in the MySQL 4.1 release series:
•
The EXAMPLE storage engine is a “stub” engine that serves as an example in the
MySQL source code for writing new storage engines, and is primarily of interest to developers. See Section 14.5, “The EXAMPLE Storage Engine”.
•
NDB Cluster is the storage engine used by MySQL Cluster to implement tables that
are partitioned over many computers. See Chapter 16, MySQL Cluster.
•
The ARCHIVE storage engine is used for storing large amounts of data without indexes
in a very small footprint. See Section 14.7, “The ARCHIVE Storage Engine”.
•
The CSV storage engine stores data in text files using comma-separated-values format.
See Section 14.8, “The CSV Storage Engine”.
•
The BLACKHOLE storage engine accepts but does not store data, and always returns an
empty result set. It is for use primarily in replication. See Section 14.9, “The BLACKHOLE Storage Engine”.
Note: These engines were implemented at different points in the development of MySQL
4.1. Please see the indicated sections for particulars in each case.
•
•
•
Standards compliance, portability, and migration:
•
The enhanced client/server protocol available beginning with MySQL 4.1.1 provides the
ability to pass multiple warnings to the client, rather than only a single result, making it
much easier to track problems that occur in operations such as bulk data loading.
•
SHOW WARNINGS shows warnings for the last command. See Section 13.5.4.22, “SHOW
WARNINGS Syntax”.
Internationalization and Localization:
•
To support applications that require the use of local languages, the MySQL software added
extensive Unicode support through the utf8 and ucs2 character sets.
•
Definition of character sets by column, table, and database. This allows for a high degree of
flexibility in application design, particularly for multi-language Web sites. See Chapter 10,
Character Set Support.
•
Per-connection time zones support, allowing individual clients to select their own time zones
when necessary.
Usability enhancements:
•
The addition of a server-based HELP command that can be used to get help information for
SQL statements. This information is always applicable to the particular server version being
used. Because this information is available by issuing an SQL statement, any client can access it. For example, the help command of the mysql command-line client has been modified to have this capability.
•
The improved client/server protocol allows multiple statements to be issued with a single
call, and for returning multiple result sets. See Section 23.2.9, “C API Handling of Multiple
Query Execution”.
18
General Information
•
The syntax INSERT ... ON DUPLICATE KEY UPDATE ... was implemented. This
allows you to update an existing row if the insert would have caused a duplicate value for a
primary or unique index. See Section 13.2.4, “INSERT Syntax”.
•
The aggregate function GROUP_CONCAT(), added the capability to concatenate column
values from grouped rows into a single result string. See Section 12.10, “Functions and
Modifiers for Use with GROUP BY Clauses”.
The News section of this manual includes a more in-depth list of MySQL 4.1 features. See Section E.2, “Changes in release 4.1.x (Production)”.
1.6.3. What's New in MySQL 5.0
The following features are implemented in MySQL 5.0.
•
BIT Data Type: Can be used to store numbers in binary notation. See Section 11.1.1,
“Overview of Numeric Types”.
•
Cursors: Elementary support for server-side cursors. See Section 18.2.11, “Cursors”.
•
Data Dictionary (Information Schema): The introduction of the INFORMATION_SCHEMA
database in MySQL 5.0 provided a standards-compliant means for accessing the MySQL Server's metadata, that is, data about the databases (schemas) on the server and the objects which
they contain. See Chapter 21, The INFORMATION_SCHEMA Information Database.
•
Instance Manager: Can be used to start and stop the MySQL Server, even from a remote host.
See Section 5.2, “mysqlmanager — The MySQL Instance Manager”.
•
Precision Math: MySQL 5.0 introduced stricter criteria for acceptance or rejection of data, and
implemented a new library for fixed-point arithmetic. These contributed to a much higher degree
of accuracy for mathematical operations and greater control over invalid values. See Chapter 22,
Precision Math.
•
Storage Engines: Storage engines added in MySQL 5.0 include ARCHIVE and FEDERATED.
See Section 14.7, “The ARCHIVE Storage Engine” and Section 14.6, “The FEDERATED Storage Engine”.
•
Stored Routines: Support for named stored procedures and stored functions was implemented
in MySQL 5.0. See Chapter 18, Stored Procedures and Functions.
•
Strict Mode and Standard Error Handling: MySQL 5.0 added a strict mode where by it follows standard SQL in a number of ways in which it did not previously. Support for standard
SQLSTATE error messages was also implemented. See Section 5.3.2, “The Server SQL Mode”.
•
Triggers: MySQL 5.0 added limited support for triggers. See Chapter 19, Triggers and Section 1.8.5.4, “Stored Procedures and Triggers”.
•
VARCHAR Data Type: The maximum effective length of a VARCHAR column was increased to
65,532 bytes, and stripping of trailing whitespace was eliminated. See Section 11.4, “String
Types”.
•
Views: MySQL 5.0 added support for named, updateable views. See Chapter 20, Views and Section 1.8.5.6, “Views”.
•
XA Transactions: See Section 13.4.7, “XA Transactions”.
For more detailed information on changes in MySQL 5.0, see Section E.1, “Changes in release 5.0.x
(Development)”.
19
General Information
For those wishing to take a look at the bleeding edge of MySQL development, we make our BitKeeper repository for MySQL publicly available. See Section 2.8.3, “Installing from the Development Source Tree”.
1.7. MySQL Information Sources
1.7.1. MySQL Mailing Lists
This section introduces the MySQL mailing lists and provides guidelines as to how the lists should
be used. When you subscribe to a mailing list, you receive all postings to the list as email messages.
You can also send your own questions and answers to the list.
1.7.1.1. The MySQL Mailing Lists
To subscribe to or unsubscribe from any of the mailing lists described in this section, visit http://lists.mysql.com/. For most of them, you can select the regular version of the list where you get
individual messages, or a digest version where you get one large message per day.
Please do not send messages about subscribing or unsubscribing to any of the mailing lists, because
such messages are distributed automatically to thousands of other users.
Your local site may have many subscribers to a MySQL mailing list. If so, the site may have a local
mailing list, so that messages sent from lists.mysql.com to your site are propagated to the local list. In such cases, please contact your system administrator to be added to or dropped from the
local MySQL list.
If you wish to have traffic for a mailing list go to a separate mailbox in your mail program, set up a
filter based on the message headers. You can use either the List-ID: or Delivered-To: headers to identify list messages.
The MySQL mailing lists are as follows:
•
announce
This list is for announcements of new versions of MySQL and related programs. This is a lowvolume list to which all MySQL users should subscribe.
•
mysql
This is the main list for general MySQL discussion. Please note that some topics are better discussed on the more-specialized lists. If you post to the wrong list, you may not get an answer.
•
bugs
This list is for people who want to stay informed about issues reported since the last release of
MySQL or who want to be actively involved in the process of bug hunting and fixing. See Section 1.7.1.3, “How to Report Bugs or Problems”.
•
internals
This list is for people who work on the MySQL code. This is also the forum for discussions on
MySQL development and for posting patches.
•
mysqldoc
This list is for people who work on the MySQL documentation: people from MySQL AB, translators, and other community members.
•
benchmarks
This list is for anyone interested in performance issues. Discussions concentrate on database per20
General Information
formance (not limited to MySQL), but also include broader categories such as performance of
the kernel, filesystem, disk system, and so on.
•
packagers
This list is for discussions on packaging and distributing MySQL. This is the forum used by distribution maintainers to exchange ideas on packaging MySQL and on ensuring that MySQL
looks and feels as similar as possible on all supported platforms and operating systems.
•
java
This list is for discussions about the MySQL server and Java. It is mostly used to discuss JDBC
drivers, including MySQL Connector/J.
•
win32
This list is for all topics concerning the MySQL software on Microsoft operating systems, such
as Windows 9x, Me, NT, 2000, XP, and 2003.
•
myodbc
This list is for all topics concerning connecting to the MySQL server with ODBC.
•
gui-tools
This list is for all topics concerning MySQL GUI tools, including MySQL Administrator
and the MySQL Control Center graphical client.
•
cluster
This list is for discussion of MySQL Cluster.
•
dotnet
This list is for discussion of the MySQL server and the .NET platform. Mostly related to the
MySQL Connector/Net provider.
•
plusplus
This list is for all topics concerning programming with the C++ API for MySQL.
•
perl
This list is for all topics concerning the Perl support for MySQL with DBD::mysql.
If you're unable to get an answer to your questions from a MySQL mailing list or forum, one option
is to purchase support from MySQL AB. This puts you in direct contact with MySQL developers.
The following table shows some MySQL mailing lists in languages other than English. These lists
are not operated by MySQL AB.
•
<[email protected]>
A French mailing list.
•
<[email protected]>
A Korean mailing list. Email subscribe mysql [email protected] to this list.
•
<[email protected]>
A German mailing list. Email subscribe mysql-de [email protected] to this list.
21
General Information
You can find information about this mailing list at http://www.4t2.com/mysql/.
•
<[email protected]>
A Portuguese mailing list. Email subscribe mysql-br [email protected] to this
list.
•
<[email protected]>
A Spanish mailing list. Email subscribe mysql [email protected] to this list.
1.7.1.2. Asking Questions or Reporting Bugs
Before posting a bug report or question, please do the following:
•
Start by searching the MySQL online manual at http://dev.mysql.com/doc/. We try to keep the
manual up to date by updating it frequently with solutions to newly found problems. The change
history (http://dev.mysql.com/doc/mysql/en/News.html) can be particularly useful since it is
quite possible that a newer version contains a solution to your problem.
•
Search in the bugs database at http://bugs.mysql.com/ to see whether the bug has been reported
and fixed.
•
Search the MySQL mailing list archives at http://lists.mysql.com/.
•
You can also use http://www.mysql.com/search/ to search all the Web pages (including the
manual) that are located at the MySQL AB Web site.
If you can't find an answer in the manual or the archives, check with your local MySQL expert. If
you still can't find an answer to your question, please follow the guidelines on sending mail to a
MySQL mailing list, outlined in the next section, before contacting us.
1.7.1.3. How to Report Bugs or Problems
The normal place to report bugs is http://bugs.mysql.com/, which is the address for our bugs database. This database is public, and can be browsed and searched by anyone. If you log in to the system, you can enter new reports.
Writing a good bug report takes patience, but doing it right the first time saves time both for us and
for yourself. A good bug report, containing a full test case for the bug, makes it very likely that we
will fix the bug in the next release. This section helps you write your report correctly so that you
don't waste your time doing things that may not help us much or at all.
We encourage everyone to use the mysqlbug script to generate a bug report (or a report about any
problem). mysqlbug can be found in the scripts directory (source distribution) and in the bin
directory under your MySQL installation directory (binary distribution). If you are unable to use
mysqlbug (for example, if you are running on Windows), it is still vital that you include all the necessary information noted in this section (most importantly, a description of the operating system
and the MySQL version).
The mysqlbug script helps you generate a report by determining much of the following information automatically, but if something important is missing, please include it with your message.
Please read this section carefully and make sure that all the information described here is included in
your report.
Preferably, you should test the problem using the latest production or development version of
MySQL Server before posting. Anyone should be able to repeat the bug by just using mysql
test < script_file on the included test case or by running the shell or Perl script that is included in the bug report.
22
General Information
All bugs posted in the bugs database at http://bugs.mysql.com/ are corrected or documented in the
next MySQL release. If only minor code changes are needed to correct a problem, we may also post
a patch that fixes the problem.
If you have found a sensitive security bug in MySQL, you can send email to
<[email protected]>.
If you have a repeatable bug report, please report it to the bugs database at http://bugs.mysql.com/.
Note that even in this case it's good to run the mysqlbug script first to find information about your
system. Any bug that we are able to repeat has a high chance of being fixed in the next MySQL release.
To report other problems, you can use one of the MySQL mailing lists.
Remember that it is possible for us to respond to a message containing too much information, but
not to one containing too little. People often omit facts because they think they know the cause of a
problem and assume that some details don't matter. A good principle is this: If you are in doubt
about stating something, state it. It is faster and less troublesome to write a couple more lines in
your report than to wait longer for the answer if we must ask you to provide information that was
missing from the initial report.
The most common errors made in bug reports are (a) not including the version number of the
MySQL distribution used, and (b) not fully describing the platform on which the MySQL server is
installed (including the platform type and version number). This is highly relevant information, and
in 99 cases out of 100, the bug report is useless without it. Very often we get questions like, “Why
doesn't this work for me?” Then we find that the feature requested wasn't implemented in that
MySQL version, or that a bug described in a report has been fixed in newer MySQL versions.
Sometimes the error is platform-dependent; in such cases, it is next to impossible for us to fix anything without knowing the operating system and the version number of the platform.
If you compiled MySQL from source, remember also to provide information about your compiler, if
it is related to the problem. Often people find bugs in compilers and think the problem is MySQL-related. Most compilers are under development all the time and become better version by version. To
determine whether your problem depends on your compiler, we need to know what compiler you
use. Note that every compiling problem should be regarded as a bug and reported accordingly.
It is most helpful when a good description of the problem is included in the bug report. That is, give
a good example of everything you did that led to the problem and describe, in exact detail, the problem itself. The best reports are those that include a full example showing how to reproduce the bug
or problem. See Section F.1.6, “Making a Test Case If You Experience Table Corruption”.
If a program produces an error message, it is very important to include the message in your report. If
we try to search for something from the archives using programs, it is better that the error message
reported exactly matches the one that the program produces. (Even the lettercase should be observed.) You should never try to reproduce from memory what the error message was; instead, copy
and paste the entire message into your report.
If you have a problem with Connector/ODBC (MyODBC), please try to generate a trace file and
send it with your report. See Section 24.1.1.9, “How to Report MyODBC Problems or Bugs”.
Please remember that many of the people who read your report do so using an 80-column display.
When generating reports or examples using the mysql command-line tool, you should therefore use
the --vertical option (or the \G statement terminator) for output that would exceed the available width for such a display (for example, with the EXPLAIN SELECT statement; see the example
later in this section).
Please include the following information in your report:
•
The version number of the MySQL distribution you are using (for example, MySQL 4.0.12).
You can find out which version you are running by executing mysqladmin version. The
mysqladmin program can be found in the bin directory under your MySQL installation directory.
23
General Information
•
The manufacturer and model of the machine on which you experience the problem.
•
The operating system name and version. If you work with Windows, you can usually get the
name and version number by double-clicking your My Computer icon and pulling down the
“Help/About Windows” menu. For most Unix-like operating systems, you can get this information by executing the command uname -a.
•
Sometimes the amount of memory (real and virtual) is relevant. If in doubt, include these values.
•
If you are using a source distribution of the MySQL software, the name and version number of
the compiler used are needed. If you have a binary distribution, the distribution name is needed.
•
If the problem occurs during compilation, include the exact error messages and also a few lines
of context around the offending code in the file where the error occurs.
•
If mysqld died, you should also report the query that crashed mysqld. You can usually find
this out by running mysqld with query logging enabled, and then looking in the log after
mysqld crashes See Section F.1.5, “Using Log Files to Find Cause of Errors in mysqld”.
•
If a database table is related to the problem, include the output from mysqldump --no-data
db_name tbl_name. This is very easy to do and is a powerful way to get information about
any table in a database. The information helps us create a situation matching the one you have
experienced.
•
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 be posted with the mysqlbug
script. The example uses the mysql command-line tool. Note the use of the \G statement terminator for statements whose output width would otherwise exceed that of an 80-column display
device.
mysql> SHOW VARIABLES;
mysql> SHOW COLUMNS FROM ...\G
<output from SHOW COLUMNS>
mysql> EXPLAIN SELECT ...\G
<output from EXPLAIN>
mysql> FLUSH STATUS;
mysql> SELECT ...;
<A short version of the output from SELECT,
including the time taken to run the query>
mysql> SHOW STATUS;
<output from SHOW STATUS>
•
If a bug or problem occurs while running mysqld, try to provide an input script that reproduces
the anomaly. This script should include any necessary source files. The more closely the script
can reproduce your situation, the better. If you can make a reproducible test case, you should
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://ftp.mysql.com/pub/mysql/upload/. Then enter the problem into our bugs
database at http://bugs.mysql.com/.
24
General Information
•
If you think that the MySQL server produces a strange result from a query, include not only the
result, but also your opinion of what the result should be, and an account describing the basis for
your opinion.
•
When giving an example of the problem, it's better to use the variable names, table names, and
so on that exist in your actual situation than to come up with new names. The problem could be
related to the name of a variable or table. These cases are rare, perhaps, but it is better to be safe
than sorry. After all, it should be easier for you to provide an example that uses your actual situation, and it is by all means better for us. In case you have data that you don't want to show to
others, you can use FTP to transfer it to ftp://ftp.mysql.com/pub/mysql/upload/. If the information is really top secret and you don't want to show it even to us, then go ahead and provide an
example using other names, but please regard this as the last choice.
•
Include all the options given to the relevant programs, if possible. For example, indicate the options that you use when you start the mysqld server as well as the options that you use to run
any MySQL client programs. The options to programs such as mysqld and mysql, and to the
configure script, are often keys to answers and are very relevant. It is never a bad idea to include them. If you use any modules, such as Perl or PHP, please include the version numbers of
those as well.
•
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 that the patch is all we need, or that
we can use it, if you don't provide some necessary information such as test cases showing the
bug that your patch fixes. We might find problems with your patch or we might not understand
it at all; if so, we can't use it.
If we can't verify exactly what the purpose of the patch is, we won't use it. Test cases help us
here. Show that the patch handles all the situations that may occur. If we find a borderline case
(even a rare one) where the patch won't work, it may be useless.
•
Guesses about what the bug is, why it occurs, or what it depends on are usually wrong. Even the
MySQL team can't guess such things without first using a debugger to determine the real cause
of a bug.
•
Indicate in your bug report that you have checked the reference manual and mail archive so that
others know you have tried to solve the problem yourself.
•
If you get a parse error, please check your syntax closely. If you can't find something
wrong with it, it's extremely likely that your current version of MySQL Server doesn't support
the syntax you are using. If you are using the current version and the manual at http://dev.mysql.com/doc/ doesn't cover the syntax you are using, MySQL Server doesn't support
your query. In this case, your only options are to implement the syntax yourself or email
<[email protected]> and ask for an offer to implement it.
If the manual covers the syntax you are using, but you have an older version of MySQL Server,
you should check the MySQL change history to see when the syntax was implemented. In this
case, you have the option of upgrading to a newer version of MySQL Server. See Appendix E,
MySQL Change History.
•
If your problem is that your data appears corrupt or you get errors when you access a particular
table, you should first check and then try to repair your tables with CHECK TABLE and REPAIR TABLE or with myisamchk. See Chapter 5, Database Administration.
If you are running Windows, please verify the value of lower_case_table_names using
the SHOW VARIABLES LIKE 'lower_case_table_names' command.
•
If you often get corrupted tables, you should try to find out when and why this happens. In this
case, the error log in the MySQL data directory may contain some information about what
25
General Information
happened. (This is the file with the .err suffix in the name.) See Section 5.10.1, “The Error
Log”. Please include any relevant information from this file in your bug report. Normally
mysqld should never crash a table if nothing killed it in the middle of an update. If you can
find the cause of mysqld dying, it's much easier for us to provide you with a fix for the problem. See Section A.1, “How to Determine What Is Causing a Problem”.
•
If possible, download and install the most recent version of MySQL Server and check whether it
solves your problem. All versions of the MySQL software are thoroughly tested and should
work without problems. We believe in making everything as backward-compatible as possible,
and you should be able to switch MySQL versions without difficulty. See Section 2.1.2,
“Choosing Which MySQL Distribution to Install”.
If
you
are
a
support
customer,
please
cross-post
the
bug
report
to
<[email protected]> for higher-priority treatment, as well as to the appropriate
mailing list to see whether someone else has experienced (and perhaps solved) the problem.
For information on reporting bugs in MyODBC, see Section 24.1.1.9, “How to Report MyODBC
Problems or Bugs”.
For solutions to some common problems, see Appendix A, Problems and Common Errors.
When answers are sent to you individually and not to the mailing list, it is considered good etiquette
to summarize the answers and send the summary to the mailing list so that others may have the benefit of responses you received that helped you solve your problem.
1.7.1.4. Guidelines for Answering Questions on the Mailing List
If you consider your answer to have broad interest, you may want to post it to the mailing list instead of replying directly to the individual who asked. Try to make your answer general enough that
people other than the original poster may benefit from it. When you post to the list, please make
sure that your answer is not a duplication of a previous answer.
Try to summarize the essential part of the question in your reply; don't feel obliged to quote the entire original message.
Please don't post mail messages from your browser with HTML mode turned on. Many users don't
read mail with a browser.
1.7.2. MySQL Community Support on IRC (Internet Relay Chat)
In addition to the various MySQL mailing lists, you can find experienced community people on
IRC (Internet Relay Chat). These are the best networks/channels currently known to us:
•
freenode (see http://www.freenode.net/ for servers)
•
#mysql Primarily MySQL questions, but other database and general SQL questions are
welcome. Questions about PHP, Perl or C in combination with MySQL are also common.
If you are looking for IRC client software to connect to an IRC network, take a look at xChat (http://www.xchat.org/). X-Chat (GPL licensed) is available for Unix as well as for Windows platforms
(a free Windows build of X-Chat is available at http://www.silverex.org/download/).
1.7.3. MySQL Community Support at the MySQL Forums
The latest community support resource are the forums at http://forums.mysql.com.
26
General Information
There are a variety of forums available, grouped in the following general categories:
•
Migration
•
MySQL Usage
•
MySQL Connectors
•
Programming Languages
•
Tools
•
3rd-Party Applications
•
Storage Engines
•
MySQL Technology
•
SQL Standards
•
Business
1.8. MySQL Standards Compliance
This section describes how MySQL relates to the ANSI/ISO SQL standards. MySQL Server has
many extensions to the SQL standard, and here you can find out what they are and how to use them.
You can also find information about functionality missing from MySQL Server, and how to work
around some differences.
The SQL standard has been evolving since 1986 and several versions exist. In this manual,
“SQL-92” refers to the standard released in 1992, “SQL:1999” refers to the standard released in
1999, and “SQL:2003” refers to the current version of the standard. We use the phrase “the SQL
standard” to mean the current version of the SQL Standard at any time.
Our goal is to not restrict MySQL Server usability for any usage without a very good reason for doing so. Even if we don't have the resources to perform development for every possible use, we are
always willing to help and offer suggestions to people who are trying to use MySQL Server in new
territories.
One of our main goals with the product is to continue to work toward compliance with the SQL
standard, but without sacrificing speed or reliability. We are not afraid to add extensions to SQL or
support for non-SQL features if this greatly increases the usability of MySQL Server for a large segment of our user base. The HANDLER interface in MySQL Server 4.0 is an example of this strategy.
See Section 13.2.3, “HANDLER Syntax”.
We continue to support transactional and non-transactional databases to satisfy both mission-critical
24/7 usage and heavy Web or logging usage.
MySQL Server was originally designed to work with medium size databases (10-100 million rows,
or about 100MB per table) on small computer systems. Today MySQL Server handles terabyte-size
databases, but the code can also be compiled in a reduced version suitable for hand-held and embedded devices. The compact design of the MySQL server makes development in both directions possible without any conflicts in the source tree.
Currently, we are not targeting realtime support, although MySQL replication capabilities offer significant functionality.
Database cluster support exists through third-party clustering solutions as well as the integration of
our acquired NDB Cluster technology, available from version 4.1.2. See Chapter 16, MySQL
Cluster.
27
General Information
We are also looking at providing XML support in the database server.
1.8.1. What Standards MySQL Follows
We are aiming toward supporting the full ANSI/ISO SQL standard, but without making concessions
to speed and quality of the code.
ODBC levels 0-3.51.
1.8.2. Selecting SQL Modes
The MySQL server can operate in different SQL modes, and can apply these modes differentially
for different clients. This allows an application to tailor server operation to its own requirements.
Modes define what SQL syntax MySQL should support and what kind of validation checks it should
perform on the data. This makes it easier to use MySQL in a lot of different environments and to use
MySQL together with other database servers.
You can set the default SQL mode by starting mysqld with the --sql-mode="modes" option.
Beginning with MySQL 4.1, you can also change the mode after startup time by setting the
sql_mode variable with a SET [SESSION|GLOBAL] sql_mode='modes' statement.
For more information on setting the server mode, see Section 5.3.2, “The Server SQL Mode”.
1.8.3. Running MySQL in ANSI Mode
You can tell mysqld to use the ANSI mode with the --ansi startup option. See Section 5.3.1,
“mysqld Command-Line Options”.
Running the server in ANSI mode is the same as starting it with these options (specify the -sql_mode value on a single line):
--transaction-isolation=SERIALIZABLE
--sql-mode=REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,
IGNORE_SPACE
In MySQL 4.1, you can achieve the same effect with these two statements (specify the sql_mode
value on a single line):
SET GLOBAL TRANSACTION ISOLATION LEVEL SERIALIZABLE;
SET GLOBAL sql_mode = 'REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,
IGNORE_SPACE';
See Section 1.8.2, “Selecting SQL Modes”.
In MySQL 4.1.1, the sql_mode options shown can be also be set with this statement:
SET GLOBAL sql_mode='ansi';
In this case, the value of the sql_mode variable is set to all options that are relevant for ANSI
mode. You can check the result like this:
mysql> SET GLOBAL sql_mode='ansi';
mysql> SELECT @@global.sql_mode;
-> 'REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,
IGNORE_SPACE,ANSI';
1.8.4. MySQL Extensions to Standard SQL
28
General Information
The MySQL Server includes some extensions that you probably won't find in other SQL DBMSs.
Be warned that if you use them, your code won't be portable to other SQL servers. In some cases,
you can write code that includes MySQL extensions, but is still portable, by using comments of the
form /*! ... */. In this case, MySQL Server parses and execute the code within the comment
as it would any other MySQL statement, but other SQL servers will ignore the extensions. For example:
SELECT /*! STRAIGHT_JOIN */ col_name FROM table1,table2 WHERE ...
If you add a version number after the ‘!’ character, the syntax within the comment is executed only
if the MySQL version is equal to or newer than the specified version number:
CREATE /*!32302 TEMPORARY */ TABLE t (a INT);
This means that if you have Version 3.23.02 or newer, MySQL Server uses the TEMPORARY
keyword.
The following descriptions list MySQL extensions, organized by category.
•
Organization of data on disk
MySQL Server maps each database to a directory under the MySQL data directory, and tables
within a database to filenames in the database directory. This has a few implications:
•
Database names and table names are case sensitive in MySQL Server on operating systems
that have case-sensitive filenames (such as most Unix systems). See Section 9.2.2,
“Identifier Case Sensitivity”.
•
You can use standard system commands to back up, rename, move, delete, and copy tables
that are managed by the MyISAM or ISAM storage engines. For example, to rename a MyISAM table, rename the .MYD, .MYI, and .frm files to which the table corresponds.
Database, table, index, column, or alias names may begin with a digit (but may not consist
solely of digits).
•
•
General language syntax
•
Strings may be enclosed by either ‘"’ or ‘'’, not just by ‘'’.
•
Use of ‘\’ as an escape character in strings.
•
In SQL statements, you can access tables from different databases with the
db_name.tbl_name syntax. Some SQL servers provide the same functionality but call
this User space. MySQL Server doesn't support tablespaces such as used in statements
like this: CREATE TABLE ralph.my_table...IN my_tablespace.
SQL statement syntax
•
The ANALYZE TABLE, CHECK TABLE, OPTIMIZE TABLE, and REPAIR TABLE
statements.
•
The CREATE DATABASE and DROP DATABASE statements. See Section 13.1.3, “CREATE DATABASE Syntax”.
•
The DO statement.
•
EXPLAIN SELECT to get a description of how tables are joined.
•
The FLUSH and RESET statements.
•
The SET statement. See Section 13.5.3, “SET Syntax”.
29
General Information
•
The SHOW statement. See Section 13.5.4, “SHOW Syntax”.
•
Use of LOAD DATA INFILE. In many cases, this syntax is compatible with Oracle's LOAD
DATA INFILE. See Section 13.2.5, “LOAD DATA INFILE Syntax”.
•
Use of RENAME TABLE. See Section 13.1.9, “RENAME TABLE Syntax”.
•
Use of REPLACE instead of DELETE + INSERT. See Section 13.2.6, “REPLACE Syntax”.
•
Use of CHANGE col_name, DROP col_name, or DROP INDEX, IGNORE or RENAME
in an ALTER TABLE statement. Use of multiple ADD, ALTER, DROP, or CHANGE clauses
in an ALTER TABLE statement. See Section 13.1.2, “ALTER TABLE Syntax”.
•
Use of index names, indexes on a prefix of a field, and use of INDEX or KEY in a CREATE
TABLE statement. See Section 13.1.5, “CREATE TABLE Syntax”.
•
Use of TEMPORARY or IF NOT EXISTS with CREATE TABLE.
•
Use of IF EXISTS with DROP TABLE.
•
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 INTO OUTFILE and STRAIGHT_JOIN in a SELECT statement. See Section 13.2.7, “SELECT Syntax”.
•
The SQL_SMALL_RESULT option in a SELECT statement.
•
You don't need to name all selected columns in the GROUP BY part. This gives better performance for some very specific, but quite normal queries. See Section 12.10, “Functions
and Modifiers for Use with GROUP BY Clauses”.
•
You can specify ASC and DESC with GROUP BY.
•
The ability to set variables in a statement with the := assignment operator:
mysql> SELECT @a:=SUM(total),@b=COUNT(*),@a/@b AS avg
-> FROM test_table;
mysql> SELECT @t1:=(@t2:=1)[email protected]:=4,@t1,@t2,@t3;
•
•
Column types
•
The column types MEDIUMINT, SET, ENUM, and the different BLOB and TEXT types.
•
The column attributes AUTO_INCREMENT, BINARY, NULL, UNSIGNED, and ZEROFILL.
Functions and operators
•
To make it easier for users who come from other SQL environments, MySQL Server supports aliases for many functions. For example, all string functions support both standard
SQL syntax and ODBC syntax.
•
MySQL Server understands the || and && operators to mean logical OR and AND, as in the
C programming language. In MySQL Server, || and OR are synonyms, as are && and AND.
Because of this nice syntax, MySQL Server doesn't support the standard SQL || operator
30
General Information
for string concatenation; use CONCAT() instead. Because CONCAT() takes any number of
arguments, it's easy to convert use of the || operator to MySQL Server.
•
Use of COUNT(DISTINCT list) where list has more than one element.
•
All string comparisons are case-insensitive by default, with sort ordering determined by the
current character set (cp1252 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 using the underlying character code values rather then a lexical ordering.
•
The % operator is a synonym for MOD(). That is, N % M is equivalent to MOD(N,M). % is
supported for C programmers and for compatibility with PostgreSQL.
•
The =, <>, <= ,<, >=,>, <<, >>, <=>, AND, OR, or LIKE operators may be used in 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 that returns the most recent AUTO_INCREMENT
value. See Section 12.9.3, “Information Functions”.
•
LIKE is allowed on numeric columns.
•
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(), and WEEKDAY() functions.
•
Use of TRIM() to trim substrings. Standard SQL supports removal of single characters
only.
•
The GROUP BY functions STD(), BIT_OR(), BIT_AND(), BIT_XOR(), and
GROUP_CONCAT(). See Section 12.10, “Functions and Modifiers for Use with GROUP BY
Clauses”.
For a prioritized list indicating when new extensions are added to MySQL Server, you should consult the online MySQL TODO list at http://dev.mysql.com/doc/mysql/en/TODO.html. That is the
latest version of the TODO list in this manual. See Appendix D, MySQL and the Future (the
TODO).
1.8.5. MySQL Differences from Standard SQL
We try to make MySQL Server follow the ANSI SQL standard and the ODBC SQL standard, but
MySQL Server performs operations differently in some cases:
•
For VARCHAR columns, trailing spaces are removed when the value is stored. (Fixed in MySQL
5.0.3). See Section A.8, “Known Issues in MySQL”.
•
In some cases, CHAR columns are silently converted to VARCHAR columns when you define a
table or alter its structure. (Fixed in MySQL 5.0.3). See Section 13.1.5.1, “Silent Column Specification Changes”.
•
Privileges for a table are not automatically revoked when you delete a table. You must explicitly
issue a REVOKE statement to revoke privileges for a table. See Section 13.5.1.3, “GRANT and
REVOKE Syntax”.
31
General Information
•
The CAST() function does not support cast to REAL or BIGINT. See Section 12.8, “Cast Functions and Operators”.
•
Standard SQL requires that a HAVING clause in a SELECT statement be able to refer to columns
in the GROUP BY clause. This cannot be done before MySQL 5.0.2.
1.8.5.1. Subqueries
MySQL 4.1 supports subqueries and derived tables. A “subquery” is a SELECT statement nested
within another statement. A “derived table” (an unnamed view) is a subquery in the FROM clause of
another statement. See Section 13.2.8, “Subquery Syntax”.
For MySQL versions older than 4.1, most subqueries can be rewritten using joins or other methods.
See Section 13.2.8.11, “Rewriting Subqueries as Joins for Earlier MySQL Versions” for examples
that show how to do this.
1.8.5.2. SELECT INTO TABLE
MySQL Server doesn't support the Sybase SQL extension: SELECT ... INTO TABLE ....
Instead, MySQL Server supports the standard SQL syntax INSERT INTO ... SELECT ...,
which is basically the same thing. See Section 13.2.4.1, “INSERT ... SELECT Syntax”.
INSERT INTO tbl_temp2 (fld_id)
SELECT tbl_temp1.fld_order_id
FROM tbl_temp1 WHERE tbl_temp1.fld_order_id > 100;
Alternatively, you can use SELECT INTO OUTFILE ... or CREATE TABLE ... SELECT.
From version 5.0, MySQL supports SELECT ... INTO with user variables. The same syntax
may also be used inside stored procedures using cursors and local variables. See Section 18.2.9.3,
“SELECT ... INTO Statement”.
1.8.5.3. Transactions and Atomic Operations
MySQL Server (version 3.23-max and all versions 4.0 and above) supports transactions with the
InnoDB and BDB transactional storage engines. InnoDB provides full ACID compliance. See
Chapter 14, MySQL Storage Engines and Table Types.
The other non-transactional storage engines in MySQL Server (such as MyISAM) follow a different
paradigm for data integrity called “atomic operations.” In transactional terms, MyISAM tables effectively always operate in AUTOCOMMIT=1 mode. Atomic operations often offer comparable integrity with higher performance.
With MySQL Server supporting both paradigms, you can decide whether your applications are best
served by the speed of atomic operations or the use of transactional features. This choice can be
made on a per-table basis.
As noted, the trade-off for transactional versus non-transactional table types lies mostly in performance. Transactional tables have significantly higher memory and diskspace requirements, and more
CPU overhead. On the other hand, transactional table types such as InnoDB also offer many significant features. MySQL Server's modular design allows the concurrent use of different storage engines to suit different requirements and deliver optimum performance in all situations.
But how do you use the features of MySQL Server to maintain rigorous integrity even with the nontransactional MyISAM tables, and how do these features compare with the transactional table types?
1.
If your applications are written in a way that is dependent on being able to call ROLLBACK
rather than COMMIT in critical situations, transactions are more convenient. Transactions also
ensure that unfinished updates or corrupting activities are not committed to the database; the
server is given the opportunity to do an automatic rollback and your database is saved.
32
General Information
If you use non-transactional tables, MySQL Server in almost all cases allows you to resolve
potential problems by including simple checks before updates and by running simple scripts
that check the databases for inconsistencies and automatically repair or warn if such an inconsistency occurs. Note that just by using the MySQL log or even adding one extra log, you can
normally fix tables perfectly with no data integrity loss.
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 there are no automatic aborts from the server, which is a common
problem with transactional database systems.
3.
To be safe with MySQL Server, whether or not using transactional tables, you only need to
have backups and have binary logging turned on. With this you can recover from any situation
that you could with any other transactional database system. It is always good to have backups,
regardless of which database system you use.
The transactional paradigm has its benefits and its drawbacks. Many users and application developers depend on the ease with which they can code around problems where an abort appears to
be, or is necessary. However, even if you are new to the atomic operations paradigm, or more familiar with transactions, do consider the speed benefit that non-transactional tables can offer on the order of three to five times the speed of the fastest and most optimally tuned transactional tables.
In situations where integrity is of highest importance, MySQL Server offers transaction-level reliability and integrity even for non-transactional tables. If you lock tables with LOCK TABLES, all updates stall until integrity checks are made. If you obtain a READ LOCAL lock (as opposed to a write
lock) for a table that allows concurrent inserts at the end of the table, reads are allowed, as are inserts by other clients. The newly inserted records are not be seen by the client that has the read lock
until it releases the lock. With INSERT DELAYED, you can queue inserts into a local queue, until
the locks are released, without having the client wait for the insert to complete. See Section 13.2.4.2,
“INSERT DELAYED Syntax”.
“Atomic,” in the sense that we mean it, is nothing magical. It only means that you can be sure that
while each specific update is running, no other user can interfere with it, and there can never be an
automatic rollback (which can happen with transactional tables if you are not very careful). MySQL
Server also guarantees that there are no dirty reads.
Following are some techniques for working with non-transactional tables:
•
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 the conditions that must be true before performing the update.
3.
Update if everything is okay.
4.
Use UNLOCK TABLES to release your locks.
This is usually a much faster method than using transactions with possible rollbacks, although
not always. The only situation this solution doesn't handle is when someone kills the threads in
the middle of an update. In this case, all locks are released but some of the updates may not have
been executed.
•
You can also use functions to update records in a single operation. You can get a very efficient
application by using the following techniques:
•
Modify columns relative to their current value.
33
General Information
•
Update only those columns 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 that the user can decide which version
of the customer record to use.
This gives us something that is similar to column locking but is actually even better because we
only update some of the columns, using values that are relative to their current values. This
means that typical UPDATE statements look something like these:
UPDATE tablename SET pay_back=pay_back+125;
UPDATE customer
SET
customer_date='current_date',
address='new address',
phone='new phone',
money_owed_to_us=money_owed_to_us-125
WHERE
customer_id=id AND address='old address' AND phone='old phone';
This is very efficient and works even if another client has changed the values in the pay_back
or money_owed_to_us columns.
•
In many cases, users have wanted LOCK TABLES and/or ROLLBACK for the purpose of managing unique identifiers. This can be handled much more efficiently without locking or rolling
back by using an AUTO_INCREMENT column and either the LAST_INSERT_ID() SQL function or the mysql_insert_id() C API function. See Section 12.9.3, “Information Functions”. See Section 23.2.3.36, “mysql_insert_id()”.
You can generally code around the need for row-level locking. Some situations really do need it,
and InnoDB tables support row-level locking. With MyISAM tables, you can use a flag column
in the table and do something like the following:
UPDATE tbl_name SET row_flag=1 WHERE id=ID;
MySQL returns 1 for the number of affected rows if the row was found and row_flag wasn't
1 in the original row.
You can think of it as though MySQL Server changed the preceding query to:
UPDATE tbl_name SET row_flag=1 WHERE id=ID AND row_flag <> 1;
1.8.5.4. Stored Procedures and Triggers
Stored procedures are implemented in MySQL version 5.0. See Chapter 18, Stored Procedures and
Functions.
Basic triggers functionality is implemented in MySQL beginning with version 5.0.2, with further
development planned in MySQL 5.1. See Chapter 19, Triggers.
1.8.5.5. Foreign Keys
In MySQL Server 3.23.44 and up, the InnoDB storage engine supports checking of foreign key
constraints, including CASCADE, ON DELETE, and ON UPDATE. See Section 15.7.4, “FOREIGN
34
General Information
KEY Constraints”.
For storage engines other than InnoDB, MySQL Server parses the FOREIGN KEY syntax in CREATE TABLE statements, but does not use or store it. In the future, the implementation will be extended to store this information in the table specification file so that it may be retrieved by mysqldump and ODBC. At a later stage, foreign key constraints will be implemented for MyISAM tables
as well.
Foreign key enforcement offers several benefits to database developers:
•
Assuming proper design of the relationships, foreign key constraints make it more difficult for a
programmer to introduce an inconsistency into the database.
•
Centralized checking of constraints by the database server makes it unnecessary to perform these
checks on the application side. This eliminates the possibility that different applications may not
all check the constraints in the same way.
•
Using cascading updates and deletes can simplify the application code.
•
Properly designed foreign key rules aid in documenting relationships between tables.
Do keep in mind that these benefits come at the cost of additional overhead for the database server
to perform the necessary checks. Additional checking by the server affects performance, which for
some applications may be sufficiently undesirable as to be avoided if possible. (Some major commercial applications have coded the foreign-key logic at the application level for this reason.)
MySQL gives database developers the choice of which approach to use. If you don't need foreign
keys and want to avoid the overhead associated with enforcing referential integrity, you can choose
another table type instead, such as MyISAM. (For example, the MyISAM storage engine offers very
fast performance for applications that perform only INSERT and SELECT operations, because the
inserts can be performed concurrently with retrievals. See Section 7.3.2, “Table Locking Issues”.)
If you choose not to take advantage of referential integrity checks, keep the following considerations
in mind:
•
In the absence of server-side foreign key relationship checking, the application itself must
handle relationship issues. For example, it must take care to insert rows into tables in the proper
order, and to avoid creating orphaned child records. It must also be able to recover from errors
that occur in the middle of multiple-record insert operations.
•
If ON DELETE is the only referential integrity capability an application needs, note that as of
MySQL Server 4.0, you can use multiple-table DELETE statements to delete rows from many
tables with a single statement. See Section 13.2.1, “DELETE Syntax”.
•
A workaround for the lack of ON DELETE is to add the appropriate DELETE statement to your
application when you delete records from a table that has a foreign key. In practice, this is often
as quick as using foreign keys, and is more portable.
Be aware that the use of foreign keys can in some instances lead to problems:
•
Foreign key support addresses many referential integrity issues, but it is still necessary to design
key relationships carefully to avoid circular rules or incorrect combinations of cascading deletes.
•
It is not uncommon for a DBA to create a topology of relationships that makes it difficult to restore individual tables from a backup. (MySQL alleviates this difficulty by allowing you to temporarily disable foreign key checks when reloading a table that depends on other tables. See Section 15.7.4, “FOREIGN KEY Constraints”. As of MySQL 4.1.1, mysqldump generates dump
files that take advantage of this capability automatically when reloaded.)
35
General Information
Note that foreign keys in SQL are used to check and enforce referential integrity, not to join tables.
If you want to get results from multiple tables from a SELECT statement, you do this by performing
a join between them:
SELECT * FROM t1, t2 WHERE t1.id = t2.id;
See Section 13.2.7.1, “JOIN Syntax”. See Section 3.6.6, “Using Foreign Keys”.
The FOREIGN KEY syntax without ON DELETE ... is often used by ODBC applications to produce automatic WHERE clauses.
1.8.5.6. Views
Views (including updatable views) are implemented in the 5.0 version of MySQL Server. Views are
available in binary releases from 5.0.1 and up. See Chapter 20, Views.
Views are useful for allowing users to access a set of relations (tables) as if it were a single table,
and limiting their access to just that. Views can also be used to restrict access to rows (a subset of a
particular table). For access control to columns, you can also use the sophisticated privilege system
in MySQL Server. See Section 5.6, “The MySQL Access Privilege System”.
In designing an implementation of views, our ambitious goal, as much as is possible within the confines of SQL, has been full compliance with “Codd's Rule #6” for relational database systems: “All
views that are theoretically updatable, should in practice also be updatable.”
1.8.5.7. '--' as the Start of a Comment
Some other SQL databases use ‘--’ to start comments. MySQL Server uses ‘#’ as the start comment character. You can also use the C comment style /* this is a comment */ with
MySQL Server. See Section 9.5, “Comment Syntax”.
MySQL Server 3.23.3 and above support the ‘--’ comment style, provided the comment is followed by a space (or by a control character such as a newline). The requirement for a space is to
prevent problems with automatically generated SQL queries that have used something like the following code, where we automatically insert the value of the payment for !payment!:
UPDATE account SET credit=credit-!payment!
Think about what happens if the value of payment is a negative value such as -1:
UPDATE account SET credit=credit--1
credit--1 is a legal expression in SQL, but if -- is interpreted as the start of a comment, part of
the expression is discarded. The result is a statement that has a completely different meaning than
intended:
UPDATE account SET credit=credit
The statement produces no change in value at all! This illustrates that allowing comments to start
with ‘--’ can have serious consequences.
Using our implementation of this method of commenting in MySQL Server 3.23.3 and up, credit--1 is actually safe.
Another safe feature is that the mysql command-line client removes all lines that start with ‘--’.
The following information is relevant only if you are running a MySQL version earlier than 3.23.3:
If you have an SQL program in a text file that contains ‘--’ comments, you should use the replace utility as follows to convert the comments to use ‘#’ characters:
36
General Information
shell> replace " --" " #" < text-file-with-funny-comments.sql \
| mysql db_name
instead of the usual:
shell> mysql db_name < text-file-with-funny-comments.sql
You can also edit the command file “in place” to change the ‘--’ comments to ‘#’ comments:
shell> replace " --" " #" -- text-file-with-funny-comments.sql
Change them back with this command:
shell> replace " #" " --" -- text-file-with-funny-comments.sql
1.8.6. How MySQL Deals with Constraints
MySQL allows you to work both with transactional tables that allow rollback and with nontransactional tables that do not. Because of this, constraint handling is a bit different in MySQL than
in other DBMSs. We must handle the case when you have inserted or updated a lot of rows in a nontransactional table for which changes cannot be rolled back when an error occurs.
The basic philosophy is that MySQL Server tries to produce an error for anything that it can detect
while parsing a statement to be executed, and tries to recover from any errors that occur while executing the statement. We do this in most cases, but not yet for all. See Section D.3, “New Features
Planned for the Near Future”.
The options MySQL has when an error occurs are to stop the statement in the middle or to recover
as well as possible from the problem and continue. By default, the server follows the latter course.
This means, for example, that the server may coerce illegal values to the closest legal values.
Beginning with MySQL 5.0.2, several SQL mode options are available to provide greater control
over how accepting to be of bad data values and whether to continue executing a statement or abort
it when errors occur. Using these options, you can configure MySQL Server to act in a more traditional fashion that is like other DBMSs that reject improper input. The SQL mode can be set at
runtime, which enables individual clients to select the behavior most appropriate for their requirements. See Section 5.3.2, “The Server SQL Mode”.
The following sections describe what happens for the different types of constraints.
1.8.6.1. PRIMARY KEY and UNIQUE Index Constraints
Normally, an error occurs when you try to INSERT or UPDATE a row that causes a primary key,
unique key, or foreign key violation. If you are using a transactional storage engine such as
InnoDB, MySQL automatically rolls back the statement. If you are using a non-transactional storage engine, MySQL stops processing the statement at the row for which the error occurred and
leaves any remaining rows unprocessed.
If you wish to ignore such key violations, MySQL supports an IGNORE keyword for INSERT and
UPDATE. In this case, MySQL ignores any key violations and continues processing with the next
row. See Section 13.2.4, “INSERT Syntax”. See Section 13.2.10, “UPDATE Syntax”.
You can get information about the number of rows actually inserted or updated with the
mysql_info() C API function. See Section 23.2.3.34, “mysql_info()”. In MySQL 4.1 and
up, you also can use the SHOW WARNINGS statement. See Section 13.5.4.22, “SHOW WARNINGS
Syntax”.
For the moment, only InnoDB tables support foreign keys. See Section 15.7.4, “FOREIGN KEY
Constraints”. Foreign key support in MyISAM tables is scheduled for implementation in MySQL
37
General Information
5.1.
1.8.6.2. Constraints on Invalid Data
Before MySQL 5.0.2, MySQL is forgiving of illegal or improper data values and coerces them to
legal values for data entry. In MySQL 5.0.2 and up, that remains the default behavior, but you can
select more traditional treatment of bad values such that the server rejects them and aborts the statement in which they occur. This section describes the default (forgiving) behavior of MySQL, as well
as the newer strict SQL mode and how it differs.
The following holds true when you are not using strict mode. If you insert an “incorrect” value into
a column, such as a NULL into a NOT NULL column or a too-large numeric value into a numeric
column, MySQL sets the column to the “best possible value” instead of producing an error:
•
If you try to store an out of range value in a numeric column, MySQL Server instead stores zero,
the smallest possible value, or the largest possible value in the column.
•
For strings, MySQL stores either the empty string or as much of the string as can be stored in the
column.
•
If you try to store a string that doesn't start with a number into a numeric column, MySQL Server stores 0.
•
MySQL allows you to store certain incorrect date values into DATE and DATETIME columns
(such as '2000-02-31' or '2000-02-00'). The idea is that it's not the job of the SQL
server to validate dates. If MySQL can store a date value and retrieve exactly the same value,
MySQL stores it as given. If the date is totally wrong (outside the server's ability to store it), the
special date value '0000-00-00' is stored in the column instead.
•
If you try to store NULL into a column that doesn't take NULL values, an error occurs for singlerow INSERT statements. For multiple-row INSERT statements or for INSERT INTO ...
SELECT statements, MySQL Server stores the implicit default value for the column data type.
In general, this is 0 for numeric types, the empty string ('') for string types, and the “zero”
value for date and time types. Implicit default values are discussed in Section 13.1.5, “CREATE
TABLE Syntax”.
•
If an INSERT statement specifies no value for a column, MySQL inserts its default value if the
column definition includes an explicit DEFAULT clause. If the definition has no such DEFAULT
clause, MySQL inserts the implicit default value for the column data type.
The reason for the preceding rules is that we can't check these conditions until the statement has begun executing. We can't just roll back if we encounter a problem after updating a few rows, because
the storage engine may not support rollback. The option of terminating the statement is not that
good; in this case, the update would be “half done,” which is probably the worst possible scenario.
In this case, it's better to “do the best you can” and then continue as if nothing happened.
In MySQL 5.0.2 and up, you can select stricter treatment of input values by using the
STRICT_TRANS_TABLES or STRICT_ALL_TABLES SQL modes. See Section 5.3.2, “The Server SQL Mode”.
STRICT_TRANS_TABLES works like this:
•
For transactional storage engines, bad data values occurring anywhere in the statement cause the
statement to abort and roll back.
•
For non-transactional storage engines, the statement aborts if the error occurs in the first row to
be inserted or updated. (In this case, the statement can be regarded to leave the table unchanged,
just as for a transactional table.) Errors in rows after the first do not abort the statement. Instead,
bad data values are adjusted and result in warnings rather than errors. In other words, with
STRICT_TRANS_TABLES, a wrong value causes MySQL to roll back, if it can, all updates
done so far.
38
General Information
For stricter checking, enable STRICT_ALL_TABLES. This is the same as
STRICT_TRANS_TABLES except that for non-transactional storage engines, errors abort the statement even for bad data in rows following the first row. This means that if an error occurs partway
through a multiple-row insert or update for a non-transactional table, a partial update results. Earlier
rows are inserted or updated, but those from the point of the error on are not. To avoid this for nontransactional tables, either use single-row statements or else use STRICT_TRANS_TABLES if conversion warnings rather than errors are acceptable. To avoid problems in the first place, do not use
MySQL to check column content. It is safest (and often faster) to let the application ensure that it
passes only legal values to the database.
With either of the strict mode options, you can cause errors to be treated as warnings by using INSERT IGNORE or UPDATE IGNORE rather than INSERT or UPDATE without IGNORE.
1.8.6.3. ENUM and SET Constraints
ENUM and SET columns provide an efficient way to define columns that can contain only a given
set of values. However, before MySQL 5.0.2, ENUM and SET are not real constraints. This is for the
same reasons that NOT NULL is not honored. See Section 1.8.6.2, “Constraints on Invalid Data”.
ENUM columns always have a default value. If you don't specify a default value, then it is NULL for
columns that can have NULL, otherwise the first enumeration value is used as the default value.
If you insert an incorrect value into an ENUM column or if you force a value into an ENUM column
with IGNORE, it is set to the reserved enumeration value of 0, which is displayed as an empty string
in string context. See Section 11.4.4, “The ENUM Type”.
If you insert an incorrect value into a SET column, the incorrect value is ignored. For example, if
the column can contain the values 'a', 'b', and 'c', an attempt to assign 'a,x,b,y' results in
a value of 'a,b'. See Section 11.4.5, “The SET Type”.
As of MySQL 5.0.2, you can configure the server to use strict SQL mode. See Section 5.3.2, “The
Server SQL Mode”. When strict mode is enabled, the definition of a ENUM or SET column does act
as a constraint on values entered into the column. An error occurs for values that do not satisfy these
conditions:
•
An ENUM value must be one of those listed in the column definition, or the internal numeric
equivalent thereof. The value cannot be the error value (that is, 0 or the empty string). For a
column defined as ENUM('a','b','c'), values such as '', 'd', and 'ax' are illegal and
are rejected.
•
A SET value must be the empty string or a value consisting of one or more of the values listed in
the column definition separated by commas. For a column defined as SET('a','b','c'),
values such as 'd', and 'a,b,c,d' are illegal and are rejected.
Errors for invalid values can be suppressed in strict mode if you use INSERT IGNORE or UPDATE
IGNORE. In this case, a warning is generated rather than an error. For ENUM, the value is inserted as
the error member (0). For SET, the value is inserted as given except that any invalid substrings are
deleted. For example, 'a,x,b,y' results in a value of 'a,b', as described earlier.
39
Chapter 2. Installing MySQL
This chapter describes how to obtain and install MySQL:
1.
Determine whether your platform is supported. Please note that not all supported systems
are equally good for running MySQL on them. On some it is much more robust and efficient
than others. See Section 2.1.1, “Operating Systems Supported by MySQL” for details.
2.
Choose which distribution to install. Several versions of MySQL are available, and most are
available in several distribution formats. You can choose from pre-packaged distributions containing binary (precompiled) programs or source code. When in doubt, use a binary distribution. We also provide public access to our current source tree for those who want to see our
most recent developments and help us test new code. To determine which version and type of
distribution you should use, see Section 2.1.2, “Choosing Which MySQL Distribution to Install”.
3.
Download the distribution that you want to install. For a list of sites from which you can
obtain MySQL, see Section 2.1.3, “How to Get MySQL”. You can verify the integrity of the
distribution using the instructions in Section 2.1.4, “Verifying Package Integrity Using MD5
Checksums or GnuPG”.
4.
Install the distribution. To install MySQL from a binary distribution, use the instructions in
Section 2.2, “Standard MySQL Installation Using a Binary Distribution”. To install MySQL
from a source distribution or from the current development source tree, use the instructions in
Section 2.8, “MySQL Installation Using a Source Distribution”.
Note: If you plan to upgrade an existing version of MySQL to a newer version rather than installing MySQL for the first time, see Section 2.10, “Upgrading MySQL” for information
about upgrade procedures and about issues that you should consider before upgrading.
If you encounter installation difficulties, see Section 2.12, “Operating System-Specific Notes”
for information on solving problems for particular platforms.
5.
Perform any necessary post-installation setup. After installing MySQL, read Section 2.9,
“Post-Installation Setup and Testing”. This section contains important information about making sure the MySQL server is working properly. It also describes how to secure the initial
MySQL user accounts, which have no passwords until you assign passwords. The section applies whether you install MySQL using a binary or source distribution.
6.
If you want to run the MySQL benchmark scripts, Perl support for MySQL must be available.
See Section 2.13, “Perl Installation Notes”.
2.1. General Installation Issues
Before installing MySQL, you should do the following:
1.
Determine whether or not MySQL runs on your platform.
2.
Choose a distribution to install.
3.
Download the distribution and verify its integrity.
This section contains the information necessary to carry out these steps. After doing so, you can use
the instructions in later sections of the chapter to install the distribution that you choose.
2.1.1. Operating Systems Supported by MySQL
40
Installing MySQL
This section lists the operating systems on which you can expect to be able to run MySQL.
We use GNU Autoconf, so it is possible to port MySQL to all modern systems that have a C++
compiler and a working implementation of POSIX threads. (Thread support is needed for the server.
To compile only the client code, the only requirement is a C++ compiler.) We use and develop the
software ourselves primarily on Linux (SuSE and Red Hat), FreeBSD, and Sun Solaris (Versions 8
and 9).
MySQL has been reported to compile successfully on the following combinations of operating system and thread package. Note that for many operating systems, native thread support works only in
the latest versions.
•
AIX 4.x, 5.x with native threads. See Section 2.12.5.3, “IBM-AIX notes”.
•
Amiga.
•
BSDI 2.x with the MIT-pthreads package. See Section 2.12.4.5, “BSD/OS Version 2.x Notes”.
•
BSDI 3.0, 3.1 and 4.x with native threads. See Section 2.12.4.5, “BSD/OS Version 2.x Notes”.
•
Digital Unix 4.x with native threads. See Section 2.12.5.5, “Alpha-DEC-UNIX Notes (Tru64)”.
•
FreeBSD 2.x with the MIT-pthreads package. See Section 2.12.4.1, “FreeBSD Notes”.
•
FreeBSD 3.x and 4.x with native threads. See Section 2.12.4.1, “FreeBSD Notes”.
•
FreeBSD 4.x with LinuxThreads. See Section 2.12.4.1, “FreeBSD Notes”.
•
HP-UX 10.20 with the DCE threads or the MIT-pthreads package. See Section 2.12.5.1,
“HP-UX Version 10.20 Notes”.
•
HP-UX 11.x with the native threads. See Section 2.12.5.2, “HP-UX Version 11.x Notes”.
•
Linux 2.0+ with LinuxThreads 0.7.1+ or glibc 2.0.7+ for various CPU architectures. See Section 2.12.1, “Linux Notes”.
•
Mac OS X. See Section 2.12.2, “Mac OS X Notes”.
•
NetBSD 1.3/1.4 Intel and NetBSD 1.3 Alpha (requires GNU make). See Section 2.12.4.2,
“NetBSD Notes”.
•
Novell NetWare 6.0. See Section 2.6, “Installing MySQL on NetWare”.
•
OpenBSD > 2.5 with native threads. OpenBSD < 2.5 with the MIT-pthreads package. See Section 2.12.4.3, “OpenBSD 2.5 Notes”.
•
OS/2 Warp 3, FixPack 29 and OS/2 Warp 4, FixPack 4. See Section 2.12.6, “OS/2 Notes”.
•
SCO OpenServer 5.0.X with a recent port of the FSU Pthreads package. See Section 2.12.5.8,
“SCO UNIX and OpenServer 5.0.x Notes”.
•
SCO UnixWare 7.1.x. See Section 2.12.5.9, “SCO UnixWare 7.1.x and OpenUNIX 8.0.0
Notes”.
•
SCO Openserver 6.0.x. See Section 2.12.5.10, “SCO OpenServer 6.0.x Notes”.
•
SGI Irix 6.x with native threads. See Section 2.12.5.7, “SGI Irix Notes”.
•
Solaris 2.5 and above with native threads on SPARC and x86. See Section 2.12.3, “Solaris
Notes”.
•
SunOS 4.x with the MIT-pthreads package. See Section 2.12.3, “Solaris Notes”.
41
Installing MySQL
•
Tru64 Unix. See Section 2.12.5.5, “Alpha-DEC-UNIX Notes (Tru64)”.
•
Windows 9x, Me, NT, 2000, XP, and 2003. See Section 2.3, “Installing MySQL on Windows”.
Not all platforms are equally well-suited for running MySQL. How well a certain platform is suited
for a high-load mission-critical MySQL server is determined by the following factors:
•
General stability of the thread library. A platform may have an excellent reputation otherwise,
but MySQL is only as stable as the thread library it calls, even if everything else is perfect.
•
The capability of the kernel and the thread library to take advantage of symmetric multi-processor (SMP) systems. In other words, when a process creates a thread, it should be possible for
that thread to run on a different CPU than the original process.
•
The capability of the kernel and the thread library to run many threads that acquire and release a
mutex over a short critical region frequently without excessive context switches. If the implementation of pthread_mutex_lock() is too anxious to yield CPU time, this hurts MySQL
tremendously. If this issue is not taken care of, adding extra CPUs actually makes MySQL
slower.
•
General filesystem stability and performance.
•
If your tables are big, the ability of the filesystem to deal with large files at all and to deal with
them efficiently.
•
Our level of expertise here at MySQL AB with the platform. If we know a platform well, we enable platform-specific optimizations and fixes at compile time. We can also provide advice on
configuring your system optimally for MySQL.
•
The amount of testing we have done internally for similar configurations.
•
The number of users that have successfully run MySQL on the platform in similar configurations. If this number is high, the chances of encountering platform-specific surprises are much
smaller.
Based on the preceding criteria, the best platforms for running MySQL at this point are x86 with
SuSE Linux using a 2.4 kernel, and ReiserFS (or any similar Linux distribution) and SPARC with
Solaris (2.7-9). FreeBSD comes third, but we really hope it joins the top club once the thread library
is improved. We also hope that at some point we is able to include into the top category all other
platforms on which MySQL currently compiles and runs okay, but not quite with the same level of
stability and performance. This requires some effort on our part in cooperation with the developers
of the operating system and library components that MySQL depends on. If you are interested in improving one of those components, are in a position to influence its development, and need more detailed instructions on what MySQL needs to run better, send an email message to the MySQL internals mailing list. See Section 1.7.1.1, “The MySQL Mailing Lists”.
Please note that the purpose of the preceding comparison is not to say that one operating system is
better or worse than another in general. We are talking only about choosing an OS for the specific
purpose of running MySQL. With this in mind, the result of this comparison would be different if
we considered more factors. In some cases, the reason one OS is better than the other could simply
be that we have been able to put more effort into testing and optimizing for a particular platform.
We are just stating our observations to help you decide which platform to use for running MySQL.
2.1.2. Choosing Which MySQL Distribution to Install
When preparing to install MySQL, you should decide which version to use. MySQL development
occurs in several release series, and you can pick the one that best fits your needs. After deciding
which version to install, you can choose a distribution format. Releases are available in binary or
source format.
42
Installing MySQL
2.1.2.1. Choosing Which Version of MySQL to Install
The first decision to make is whether you want to use a production (stable) release or a development
release. In the MySQL development process, multiple release series co-exist, each at a different
stage of maturity:
•
MySQL 5.0 is the newest development release series and is under very active development for
new features. Alpha releases have been issued to allow more widespread testing.
•
MySQL 4.1 is the current stable (production-quality) release series. New releases are issued for
bugfixes. No new features are added that could diminish the code stability.
•
MySQL 4.0 is the previous stable (production-quality) release series. New releases are issued for
bugfixes. No new features are added that could diminish the code stability.
•
MySQL 3.23 is the old stable (production-quality) release series. This series is retired, so new
releases are issued only to fix critical bugs.
We don't believe in a complete freeze, as this also leaves out bugfixes and things that “must be
done.” “Somewhat frozen” means that we may add small things that “almost surely do not affect
anything that's currently working.” Naturally, relevant bugfixes from an earlier series propagate to
later series.
Normally, if you are beginning to use MySQL for the first time or trying to port it to some system
for which there is no binary distribution, we recommend going with the production release series.
Currently this is MySQL 4.1. All MySQL releases, even those from development series, are checked
with the MySQL benchmarks and an extensive test suite before being issued.
If you are running an old system and want to upgrade, but don't want to take the chance of having a
non-seamless upgrade, you should upgrade to the latest version in the same release series you are
using (where only the last part of the version number is newer than yours). We have tried to fix only
fatal bugs and make small, relatively safe changes to that version.
If you want to use new features not present in the production release series, you can use a version
from a development series. Note that development releases are not as stable as production releases.
If you want to use the very latest sources containing all current patches and bugfixes, you can use
one of our BitKeeper repositories. These are not “releases” as such, but are available as previews of
the code on which future releases are based.
The MySQL naming scheme uses release names that consist of three numbers and a suffix; for example, mysql-4.1.2-alpha. The numbers within the release name are interpreted like this:
•
The first number (4) is the major version and also describes the file format. All Version 4 releases have the same file format.
•
The second number (1) is the release level. Taken together, the major version and release level
constitute the release series number.
•
The third number (2) is the version number within the release series. This is incremented for
each new release. Usually you want the latest version for the series you have chosen.
For each minor update, the last number in the version string is incremented. When there are major
new features or minor incompatibilities with previous versions, the second number in the version
string is incremented. When the file format changes, the first number is increased.
Release names also include a suffix to indicates the stability level of the release. Releases within a
series progress through a set of suffixes to indicate how the stability level improves. The possible
suffixes are:
43
Installing MySQL
•
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 E, MySQL Change History. There are also new commands and extensions in most alpha
releases. Active development that may involve major code changes can occur in an alpha release, but everything is tested before issuing a release. For this reason, there should be no known
bugs in any MySQL release.
•
beta means that we are feature complete and that all new code has been tested. No major new
features that could cause corruption in old code are added. There should be no known critical
bugs. A version changes from alpha to beta when there haven't been any reported fatal bugs
within an alpha version for at least a month and we have no plans to add any features that could
make any old command unreliable.
All API's, extern visible structures and columns for SQL commands will not change during future beta, release candidate, or production releases.
•
rc is a release candidate; that is, a beta that has been around a while and seems to work fine.
Only minor fixes are added. (A release candidate is what formerly was known as a gamma 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 critical repeatable bugs other than platform-specific bugs. Only critical bugfixes are applied to the release. This is what we call a production (stable) or `General Availability' (GA) release.
MySQL uses a naming scheme that is slightly different from most other products. In general, it's relatively safe to use any version that has been out for a couple of weeks without being replaced with a
new version within the release series.
All releases of MySQL are run through our standard tests and benchmarks to ensure that they are relatively safe to use. Because the standard tests are extended over time to check for all previously
found bugs, the test suite keeps getting better.
All releases have been tested at least with:
•
An internal test suite
The mysql-test directory contains an extensive set of test cases. We run these tests for virtually every server binary. See Section 25.1.2, “MySQL Test Suite” for more information about
this test suite.
•
The MySQL benchmark suite
This suite runs a range of common queries. It is also a test to see whether the latest batch of optimizations actually made the code faster. See Section 7.1.4, “The MySQL Benchmark Suite”.
•
The crash-me test
This test tries to determine what features the database supports and what its capabilities and limitations are. See Section 7.1.4, “The MySQL Benchmark Suite”.
Another test is that we use the newest MySQL version in our internal production environment, on at
least one machine. We have more than 100GB of data to work with.
2.1.2.2. Choosing a Distribution Format
After choosing which version of MySQL to install, you should decide whether to use a binary distribution or a source distribution. In most cases, you should probably use a binary distribution, if one
exists for your platform. Binary distributions are available in native format for many platforms, such
as RPM files for Linux or DMG package installers for Mac OS X. Distributions also are available as
44
Installing MySQL
Zip archives or compressed tar files.
Reasons to choose a binary distribution include the following:
•
Binary distributions generally are easier to install than source distributions.
•
To satisfy different user requirements, we provide two different binary versions: one compiled
with the non-transactional storage engines (a small, fast binary), and one configured with the
most important extended options like transaction-safe tables. Both versions are compiled from
the same source distribution. All native MySQL clients can connect to servers from either
MySQL version.
The extended MySQL binary distribution is marked with the -max suffix and is configured with
the same options as mysqld-max. See Section 5.1.2, “The mysqld-max Extended MySQL
Server”.
If you want to use the MySQL-Max RPM, you must first install the standard MySQL-server
RPM.
Under some circumstances, you may be better off installing MySQL from a source distribution:
•
You want to install MySQL at some explicit location. The standard binary distributions are
“ready to run” at any place, but you may want to have even more flexibility to place MySQL
components where you want.
•
You want to configure mysqld with some extra features that are not included in the standard
binary distributions. Here is a list of the most common extra options that you may want to use:
•
--with-innodb (default for MySQL 4.0 and up)
•
--with-berkeley-db (not available on all platforms)
•
--with-raid
•
--with-libwrap
•
--with-named-z-libs (this is done for some of the binaries)
•
--with-debug[=full]
•
You want to configure mysqld without some features that are included in the standard binary
distributions. For example, distributions normally are compiled with support for all character
sets. If you want a smaller MySQL server, you can recompile it with support for only the character sets you need.
•
You have a special compiler (such as pgcc) or want to use compiler options that are better optimized for your processor. Binary distributions are compiled with options that should work on a
variety of processors from the same processor family.
•
You want to use the latest sources from one of the BitKeeper repositories to have access to all
current bugfixes. For example, if you have found a bug and reported it to the MySQL development team, the bugfix is committed to the source repository and you can access it there. The
bugfix does not appear in a release until a release actually is issued.
•
You want to read (or modify) the C and C++ code that makes up MySQL. For this purpose, you
should get a source distribution, because the source code is always the ultimate manual.
•
Source distributions contain more tests and examples than binary distributions.
2.1.2.3. How and When Updates Are Released
45
Installing MySQL
MySQL is evolving quite rapidly here at MySQL AB and we want to share new developments with
other MySQL users. We try to make a release when we have very useful features that others seem to
have a need for.
We also try to help out users who request features that are easy to implement. We take note of what
our licensed users want to have, and we especially take note of what our support customers want and
try to help them out.
No one has to download a new release. The News section tells you if the new release has something
you really want. See Appendix E, MySQL Change History.
We use the following policy when updating MySQL:
•
Releases are issued within each series. For each release, the last number in the version is one
more than the previous release within the same series.
•
Production (stable) releases are meant to appear about 1-2 times a year. However, if small bugs
are found, a release with only bugfixes is issued.
•
Working releases/bugfixes to old releases are meant to appear about every 4-8 weeks.
•
Binary distributions for some platforms are made by us for major releases. Other people may
make binary distributions for other systems, but probably less frequently.
•
We make fixes available as soon as we have identified and corrected small or non-critical but
annoying bugs. The fixes are available immediately from our public BitKeeper repositories, and
will be included in the next release.
•
If by any chance a fatal bug is found in a release, we make a new release as soon as possible.
(We would like other companies to do this, too!)
2.1.2.4. Release Philosophy—No Known Bugs in Releases
We put a lot of time and effort into making our releases bug-free. To our knowledge, we have not
knowingly released a single MySQL version with any known “fatal” repeatable bugs. (A “fatal” bug
is something that crashes MySQL under normal usage, produces incorrect answers for normal queries, or has a security problem.)
We have documented all open problems, bugs, and issues that are dependent on design decisions.
See Section A.8, “Known Issues in MySQL”.
Our aim is to fix everything that is fixable without risk of making a stable MySQL version less
stable. In certain cases, this means we can fix an issue in the development versions, but not in the
stable (production) version. Naturally, we document such issues so that users are aware of them.
Here is a description of how our build process works:
•
We monitor bugs from our customer support list, the bugs database at http://bugs.mysql.com/,
and the MySQL external mailing lists.
•
All reported bugs for live versions are entered into the bugs database.
•
When we fix a bug, we always try to make a test case for it and include it into our test system to
ensure that the bug can never recur without being detected. (About 90% of all fixed bugs have a
test case.)
•
We create test cases for all new features we add to MySQL.
•
Before we start to build a new MySQL release, we ensure that all reported repeatable bugs for
the MySQL version (3.23.x, 4.0.x, etc) are fixed. If something is impossible to fix (due to some
46
Installing MySQL
internal design decision in MySQL), we document this in the manual. See Section A.8, “Known
Issues in MySQL”.
•
We do a build on all platforms for which we support binaries (15+ platforms) and run our test
suite and benchmark suite on all of them.
•
We do not publish a binary for a platform for which the test or benchmark suite fails. If the problem is due to a general error in the source, we fix it and do the build plus tests on all systems
again from scratch.
•
The build and test process takes 2-3 days. If we receive a report regarding a fatal bug during this
process (for example, one that causes a core dump), we fix the problem and restart the build process.
•
After publishing the binaries on http://dev.mysql.com/, we send out an announcement message
to the mysql and announce mailing lists. See Section 1.7.1.1, “The MySQL Mailing Lists”.
The announcement message contains a list of all changes to the release and any known problems
with the release. The Known Problems section in the release notes has been needed for only a
handful of releases.
•
To quickly give our users access to the latest MySQL features, we do a new MySQL release
every 4-8 weeks. Source code snapshots are built daily and are available at http://downloads.mysql.com/snapshots.php.
•
If, despite our best efforts, we get any bug reports after the release is done that there was
something critically wrong with the build on a specific platform, we fix it at once and build a
new 'a' release for that platform. Thanks to our large user base, problems are found quickly.
•
Our track record for making stable releases is quite good. In the last 150 releases, we had to do a
new build for fewer than 10 releases. In three of these cases, the bug was a faulty glibc library
on one of our build machines that took us a long time to track down.
2.1.2.5. MySQL Binaries Compiled by MySQL AB
As a service of MySQL AB, we provide a set of binary distributions of MySQL that are compiled
on systems at our site or on systems where supporters of MySQL kindly have given us access to
their machines.
In addition to the binaries provided in platform-specific package formats, we offer binary distributions for a number of platforms in the form of compressed tar files (.tar.gz files). See Section 2.2, “Standard MySQL Installation Using a Binary Distribution”.
For Windows distributions, see Section 2.3, “Installing MySQL on Windows”.
These distributions are generated using the script Build-tools/Do-compile, which compiles
the source code and creates the binary tar.gz archive using scripts/
make_binary_distribution.
These binaries are configured and built with the following compilers and options. This information
can also be obtained by looking at the variables COMP_ENV_INFO and CONFIGURE_LINE inside
the script bin/mysqlbug of every binary tar file distribution.
The following binaries are built on MySQL AB development systems:
•
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
47
-
Installing MySQL
-with-client-ldflags=-all-static
-with-mysqld-ldflags=-all-static
•
-
Linux 2.4.x x86 with icc (Intel C++ Compiler 8.1 or later releases):
CC=icc CXX=icpc CFLAGS="-O3 -unroll2 -ip -mp -no-gcc -restrict"
CXXFLAGS="-O3 -unroll2 -ip -mp -no-gcc -restrict" ./configure -prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data -libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex -enable-thread-safe-client
--enable-local-infile
-enable-assembler
--disable-shared
-with-client-ldflags=-all-static
-with-mysqld-ldflags=-all-static
--with-embedded-server
-with-innodb
Note that versions 8.1 and newer of the Intel compiler have separate drivers for 'pure' C (icc)
and C++ (icpc); if you use icc version 8.0 or older for building MySQL, you will need to set
CXX=icc.
•
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
-enable-thread-safe-client --enable-local-infile
•
Linux 2.4.xx alpha with ccc (Compaq C V6.2-505 / Compaq C++ V6.3-006):
CC=ccc CFLAGS="-fast -arch generic" CXX=cxx CXXFLAGS="-fast
arch
generic
-noexceptions
-nortti"
./configure
-prefix=/usr/local/mysql
--with-extra-charsets=complex
-enable-thread-safe-client
--enable-local-infile
-with-mysqld-ldflags=-non_shared
-with-client-ldflags=-non_shared --disable-shared
•
-
-
Linux 2.x.xx ppc with gcc 2.95.4:
CC=gcc
CFLAGS="-O3
-fno-omit-frame-pointer"
CXX=gcc
CXXFLAGS="-O3
-fno-omit-frame-pointer
-felide-constructors
fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
--localstatedir=/usr/local/mysql/data
-libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex -enable-thread-safe-client
--enable-local-infile
-disable-shared --with-embedded-server --with-innodb
•
Linux 2.4.xx s390 with gcc 2.95.3:
CFLAGS="-O2"
CXX=gcc
CXXFLAGS="-O2
-felide-constructors"
./configure
--prefix=/usr/local/mysql
-with-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile
--disable-shared
-with-client-ldflags=-all-static
-with-mysqld-ldflags=-all-static
•
Linux 2.4.xx x86_64 (AMD64) with gcc 3.2.1:
CXX=gcc
./configure
--prefix=/usr/local/mysql
48
-
Installing MySQL
-with-extra-charsets=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
fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
--localstatedir=/usr/local/mysql/data
-libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex -enable-thread-safe-client
--enable-local-infile
-disable-shared --with-innodb
•
Sun Solaris 8 SPARC with gcc 3.2:
CC=gcc
CFLAGS="-O3
-fno-omit-frame-pointer"
CXX=gcc
CXXFLAGS="-O3
-fno-omit-frame-pointer
-felide-constructors
fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile --enable-assembler --with-named-z-libs=no -with-named-curses-libs=-lcurses --disable-shared
•
Sun Solaris 8 SPARC 64-bit with gcc 3.2:
CC=gcc
CFLAGS="-O3
-m64
-fno-omit-frame-pointer"
CXX=gcc
CXXFLAGS="-O3 -m64 -fno-omit-frame-pointer -felide-constructors
-fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile
--with-named-z-libs=no
-with-named-curses-libs=-lcurses --disable-shared
•
Sun Solaris 9 SPARC with gcc 2.95.3:
CC=gcc
CFLAGS="-O3
-fno-omit-frame-pointer"
CXX=gcc
CXXFLAGS="-O3
-fno-omit-frame-pointer
-felide-constructors
fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile
--enable-assembler
-with-named-curses-libs=-lcurses --disable-shared
•
Sun Solaris 9 SPARC with cc-5.0 (Sun Forte 5.0):
CC=cc-5.0 CXX=CC ASFLAGS="-xarch=v9" CFLAGS="-Xa -xstrconst -mt
-D_FORTEC_ -xarch=v9" CXXFLAGS="-noex -mt -D_FORTEC_ -xarch=v9"
./configure
--prefix=/usr/local/mysql
-with-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile --enable-assembler --with-named-z-libs=no -enable-thread-safe-client --disable-shared
•
IBM AIX 4.3.2 ppc with gcc 3.2.3:
CFLAGS="-O2 -mcpu=powerpc -Wa,-many " CXX=gcc CXXFLAGS="-O2
mcpu=powerpc -Wa,-many -felide-constructors -fno-exceptions
fno-rtti"
./configure
--prefix=/usr/local/mysql
-with-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile --with-named-z-libs=no --disable-shared
•
-
IBM AIX 4.3.3 ppc with xlC_r (IBM Visual Age C/C++ 6.0):
CC=xlc_r CFLAGS="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192"
CXX=xlC_r
CXXFLAGS
="-ma
-O2
-qstrict
-qoptimize=2
qmaxmem=8192"
./configure
--prefix=/usr/local/mysql
-localstatedir=/usr/local/mysql/data
49
Installing MySQL
-libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex -enable-thread-safe-client
--enable-local-infile
-with-named-z-libs=no --disable-shared --with-innodb
•
IBM AIX 5.1.0 ppc with gcc 3.3:
CFLAGS="-O2 -mcpu=powerpc -Wa,-many" CXX=gcc CXXFLAGS="-O2
mcpu=powerpc -Wa,-many -felide-constructors -fno-exceptions
fno-rtti"
./configure
--prefix=/usr/local/mysql
-with-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile --with-named-z-libs=no --disable-shared
•
-
IBM AIX 5.2.0 ppc with xlC_r (IBM Visual Age C/C++ 6.0):
CC=xlc_r CFLAGS="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192"
CXX=xlC_r CXXFLAGS="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192"
./configure
--prefix=/usr/local/mysql
-localstatedir=/usr/local/mysql/data
-libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex -enable-thread-safe-client
--enable-local-infile
-with-named-z-libs=no --disable-shared --with-embedded-server -with-innodb
•
HP-UX 10.20 pa-risc1.1 with gcc 3.1:
CFLAGS="-DHPUX
-I/opt/dce/include
-O3
-fPIC"
CXX=gcc
CXXFLAGS="-DHPUX -I/opt/dce /include -felide-constructors fno-exceptions
-fno-rtti
-O3
-fPIC"
./configure
-prefix=/usr/local/mysql
--with-extra-charsets=complex
-enable-thread-safe-client --enable-local-infile --with-pthread
--with-named-thread-libs=-ldce
--with-lib-ccflags=-fPIC
-disable-shared
•
HP-UX 11.00 pa-risc with aCC (HP ANSI C++ B3910B A.03.50):
CC=cc
CXX=aCC
CFLAGS=+DAportable
CXXFLAGS=+DAportable
./configure
--prefix=/usr/local/mysql
-localstatedir=/usr/local/mysql/data
-libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex -enable-thread-safe-client
--enable-local-infile
-disable-shared --with-embedded-server --with-innodb
•
HP-UX 11.11 pa-risc2.0 64bit with aCC (HP ANSI C++ B3910B A.03.33):
CC=cc
CXX=aCC
CFLAGS=+DD64
CXXFLAGS=+DD64
./configure
-prefix=/usr/local/mysql
--with-extra-charsets=complex
-enable-thread-safe-client
--enable-local-infile
-disable-shared
•
-
HP-UX 11.11 pa-risc2.0 32bit with aCC (HP ANSI C++ B3910B A.03.33):
CC=cc
CXX=aCC
CFLAGS="+DAportable"
CXXFLAGS="+DAportable"
./configure
--prefix=/usr/local/mysql
-localstatedir=/usr/local/mysql/data
-libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex -enable-thread-safe-client
--enable-local-infile
-disable-shared --with-innodb
•
HP-UX 11.22 ia64 64bit with aCC (HP aC++/ANSI C B3910B A.05.50):
CC=cc
CXX=aCC
CFLAGS="+DD64
+DSitanium2"
CXXFLAGS="+DD64
+DSitanium2"
./configure
--prefix=/usr/local/mysql
-localstatedir=/usr/local/mysql/data
50
Installing MySQL
-libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex -enable-thread-safe-client
--enable-local-infile
-disable-shared --with-embedded-server --with-innodb
•
Apple Mac OS X 10.2 powerpc with gcc 3.1:
CC=gcc
CFLAGS="-O3
-fno-omit-frame-pointer"
CXX=gcc
CXXFLAGS="-O3
-fno-omit-frame-pointer
-felide-constructors
fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile --disable-shared
•
FreeBSD 4.7 i386 with gcc 2.95.4:
CFLAGS=-DHAVE_BROKEN_REALPATH
./configure
-prefix=/usr/local/mysql
--with-extra-charsets=complex
-enable-thread-safe-client
--enable-local-infile
-enable-assembler --with-named-z-libs=not-used --disable-shared
•
FreeBSD 4.7 i386 using LinuxThreads with gcc 2.95.4:
CFLAGS="-DHAVE_BROKEN_REALPATH
-D__USE_UNIX98
-D_REENTRANT
D_THREAD_SAFE
-I/usr/local/include/pthread/linuxthreads"
CXXFLAGS="-DHAVE_BROKEN_REALPATH -D__USE_UNIX98 -D_REENTRANT D_THREAD_SAFE
-I/usr/local/include/pthread/linuxthreads"
./configure
--prefix=/usr/local/mysql
-localstatedir=/usr/local/mysql/data
-libexecdir=/usr/local/mysql/bin --enable-thread-safe-client -enable-local-infile
--enable-assembler
-with-named-thread-libs="-DHAVE_GLIBC2_STYLE_GETHOSTBYNAME_R
D_THREAD_SAFE
-I
/usr/local/include/pthread/linuxthreads
L/usr/local/lib
-llthread
-llgcc_r"
--disable-shared
-with-embedded-server --with-innodb
•
QNX Neutrino 6.2.1 i386 with gcc 2.95.3qnx-nto 20010315:
CC=gcc
CFLAGS="-O3
-fno-omit-frame-pointer"
CXX=gcc
CXXFLAGS="-O3
-fno-omit-frame-pointer
-felide-constructors
fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile --disable-shared
The following binaries are built on third-party systems kindly provided to MySQL AB by other
users. These are provided only as a courtesy; MySQL AB does not have full control over these systems, so we can provide only limited support for the binaries built on them.
•
SCO Unix 3.2v5.0.7 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-safe-client
-disable-shared
•
-
SCO UnixWare 7.1.4 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-safe-client --disable-shared --with-readline
51
Installing MySQL
•
SCO OpenServer 6.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-safe-client --disable-shared --with-readline
•
Compaq Tru64 OSF/1 V5.1 732 alpha with cc/cxx (Compaq C V6.3-029i / DIGITAL C++
V6.1-027):
CC="cc -pthread" CFLAGS="-O4 -ansi_alias -ansi_args -fast inline speed -speculate all" CXX="cxx -pthread" CXXFLAGS="-O4 ansi_alias -fast -inline speed -speculate all -noexceptions nortti"
./configure
--prefix=/usr/local/mysql
-with-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile --with-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-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile --disable-shared
•
-
FreeBSD/sparc64 5.0 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 that MySQL AB provided in the
past. These binaries no longer are being updated, but the compile options are listed here for reference purposes.
•
Linux 2.2.xx SPARC with egcs 1.1.2:
CC=gcc
CFLAGS="-O3
-fno-omit-frame-pointer"
CXX=gcc
CXXFLAGS="-O3
-fno-omit-frame-pointer
-felide-constructors
fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
--with-extra-charsets=complex
--enable-thread-safe-client
-enable-local-infile --enable-assembler --disable-shared
•
Linux 2.2.x with x686 with gcc 2.95.2:
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro
felide-constructors -fno-exceptions -fno-rtti" ./configure
-prefix=/usr/local/mysql
--enable-assembler
-with-mysqld-ldflags=-all-static
--disable-shared
-with-extra-charsets=complex
•
-
SunOS 4.1.4 2 sun4c with gcc 2.7.2.1:
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors" ./configure -prefix=/usr/local/mysql
--disable-shared
-with-extra-charsets=complex --enable-assembler
•
SunOS 5.5.1 (and above) sun4u with egcs 1.0.3a or 2.90.27 or
52
Installing MySQL
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 4.2 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 mailing list. See Section 1.7.1.1, “The MySQL Mailing
Lists”.
RPM distributions prior to MySQL 3.22 are user-contributed. Beginning with MySQL 3.22, RPM
distributions are generated by MySQL AB.
If you want to compile a debug version of MySQL, you should add --with-debug or -with-debug=full to the preceding configure commands and remove any fomit-frame-pointer options.
2.1.3. How to Get MySQL
Check the MySQL downloads page (http://dev.mysql.com/downloads/) for information about the
current version and for downloading instructions. For a complete up-to-date list of MySQL download mirror sites, see http://dev.mysql.com/downloads/mirrors.html. There you can also find information about becoming a MySQL mirror site and how to report a bad or out-of-date mirror.
Our main mirror is located at http://mirrors.sunsite.dk/mysql/.
2.1.4. Verifying Package Integrity Using MD5 Checksums or GnuPG
After you have downloaded the MySQL package that suits your needs and before you attempt to install it, you should make sure that it is intact and has not been tampered with. MySQL AB offers
three means of integrity checking:
•
MD5 checksums
•
Cryptographic signatures using GnuPG, the GNU Privacy Guard
•
For RPM packages, the built-in RPM integrity verification mechanism
53
Installing MySQL
The following sections describe how to use these methods.
If you notice that the MD5 checksum or GPG signatures do not match, first try to download the respective package one more time, perhaps from another mirror site. If you repeatedly cannot successfully verify the integrity of the package, please notify us about such incidents, including the full
package name and the download site you have been using, at <[email protected]> or
<[email protected]>. Do not report downloading problems using the bug-reporting system.
2.1.4.1. Verifying the MD5 Checksum
After you have downloaded a MySQL package, you should make sure that its MD5 checksum
matches the one provided on the MySQL download pages. Each package has an individual checksum that you can verify with the following command, where package_name is the name of the
package you downloaded:
shell> md5sum package_name
Example:
shell> md5sum mysql-standard-4.0.17-pc-linux-i686.tar.gz
60f5fe969d61c8f82e4f7f62657e1f06 mysql-standard-4.0.17-pc-linux-i686.tar.gz
You should verify that the resulting checksum (the string of hexadecimal digits) matches the one
displayed on the download page immediately below the respective package.
Note: Make sure to verify the checksum of the archive file (e.g. the .zip or .tar.gz file) and
not of the files that are contained inside of the archive!
Note that not all operating systems support the md5sum command. On some, it is simply called
md5 and others do not ship it at all. On Linux, it is part of the GNU Text Utilities package,
which is available for a wide range of platforms. You can download the source code from http://www.gnu.org/software/textutils/ as well. If you have OpenSSL installed, you can also use the
command openssl md5 package_name instead. A DOS/Windows implementation of the
md5 command line utility is available from http://www.fourmilab.ch/md5/. A graphical MD5
checking
tool
is
winMd5Sum,
which
can
be
obtained
from
http://www.nullriver.com/index/products/winmd5sum.
2.1.4.2. Signature Checking Using GnuPG
Another method of verifying the integrity and authenticity of a package is to use cryptographic signatures. This is more reliable than using MD5 checksums, but requires more work.
Beginning with MySQL 4.0.10 (February 2003), MySQL AB started signing downloadable packages with GnuPG (GNU Privacy Guard). GnuPG is an Open Source alternative to the very
well-known Pretty Good Privacy (PGP) by Phil Zimmermann. See http://www.gnupg.org/
for more information about GnuPG and how to obtain and install it on your system. Most Linux distributions ship with GnuPG installed by default. For more information about OpenPGP, see http://www.openpgp.org/.
To verify the signature for a specific package, you first need to obtain a copy of MySQL AB's public GPG build key. You can download the key from http://www.keyserver.net/. The key that you
want to obtain is named [email protected] Alternatively, you can cut and paste the key directly
from the following text:
Key ID:
pub 1024D/5072E1F5 2003-02-03
MySQL Package signing key (www.mysql.com) <[email protected]>
Fingerprint: A4A9 4068 76FC BD3C 4567 70C8 8C71 8D3B 5072 E1F5
Public Key (ASCII-armored):
54
Installing MySQL
-----BEGIN PGP PUBLIC KEY BLOCK----Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org
mQGiBD4+owwRBAC14GIfUfCyEDSIePvEW3SAFUdJBtoQHH/nJKZyQT7h9bPlUWC3
RODjQReyCITRrdwyrKUGku2FmeVGwn2u2WmDMNABLnpprWPkBdCk96+OmSLN9brZ
fw2vOUgCmYv2hW0hyDHuvYlQA/BThQoADgj8AW6/0Lo7V1W9/8VuHP0gQwCgvzV3
BqOxRznNCRCRxAuAuVztHRcEAJooQK1+iSiunZMYD1WufeXfshc57S/+yeJkegNW
hxwR9pRWVArNYJdDRT+rf2RUe3vpquKNQU/hnEIUHJRQqYHo8gTxvxXNQc7fJYLV
K2HtkrPbP72vwsEKMYhhr0eKCbtLGfls9krjJ6sBgACyP/Vb7hiPwxh6rDZ7ITnE
kYpXBACmWpP8NJTkamEnPCia2ZoOHODANwpUkP43I7jsDmgtobZX9qnrAXw+uNDI
QJEXM6FSbi0LLtZciNlYsafwAPEOMDKpMqAK6IyisNtPvaLd8lH0bPAnWqcyefep
rv0sxxqUEMcM3o7wwgfN83POkDasDbs3pjwPhxvhz6//62zQJ7Q7TXlTUUwgUGFj
a2FnZSBzaWduaW5nIGtleSAod3d3Lm15c3FsLmNvbSkgPGJ1aWxkQG15c3FsLmNv
bT6IXQQTEQIAHQUCPj6jDAUJCWYBgAULBwoDBAMVAwIDFgIBAheAAAoJEIxxjTtQ
cuH1cY4AnilUwTXn8MatQOiG0a/bPxrvK/gCAJ4oinSNZRYTnblChwFaazt7PF3q
zIhMBBMRAgAMBQI+PqPRBYMJZgC7AAoJEElQ4SqycpHyJOEAn1mxHijft00bKXvu
cSo/pECUmppiAJ41M9MRVj5VcdH/KN/KjRtW6tHFPYhMBBMRAgAMBQI+QoIDBYMJ
YiKJAAoJELb1zU3GuiQ/lpEAoIhpp6BozKI8p6eaabzF5MlJH58pAKCu/ROofK8J
Eg2aLos+5zEYrB/LsrkCDQQ+PqMdEAgA7+GJfxbMdY4wslPnjH9rF4N2qfWsEN/l
xaZoJYc3a6M02WCnHl6ahT2/tBK2w1QI4YFteR47gCvtgb6O1JHffOo2HfLmRDRi
Rjd1DTCHqeyX7CHhcghj/dNRlW2Z0l5QFEcmV9U0Vhp3aFfWC4Ujfs3LU+hkAWzE
7zaD5cH9J7yv/6xuZVw411x0h4UqsTcWMu0iM1BzELqX1DY7LwoPEb/O9Rkbf4fm
Le11EzIaCa4PqARXQZc4dhSinMt6K3X4BrRsKTfozBu74F47D8Ilbf5vSYHbuE5p
/1oIDznkg/p8kW+3FxuWrycciqFTcNz215yyX39LXFnlLzKUb/F5GwADBQf+Lwqq
a8CGrRfsOAJxim63CHfty5mUc5rUSnTslGYEIOCR1BeQauyPZbPDsDD9MZ1ZaSaf
anFvwFG6Llx9xkU7tzq+vKLoWkm4u5xf3vn55VjnSd1aQ9eQnUcXiL4cnBGoTbOW
I39EcyzgslzBdC++MPjcQTcA7p6JUVsP6oAB3FQWg54tuUo0Ec8bsM8b3Ev42Lmu
QT5NdKHGwHsXTPtl0klk4bQk4OajHsiy1BMahpT27jWjJlMiJc+IWJ0mghkKHt92
6s/ymfdf5HkdQ1cyvsz5tryVI3Fx78XeSYfQvuuwqp2H139pXGEkg0n6KdUOetdZ
Whe70YGNPw1yjWJT1IhMBBgRAgAMBQI+PqMdBQkJZgGAAAoJEIxxjTtQcuH17p4A
n3r1QpVC9yhnW2cSAjq+kr72GX0eAJ4295kl6NxYEuFApmr1+0uUq/SlsQ==
=YJkx
-----END PGP PUBLIC KEY BLOCK----You can import the build key into your personal public GPG keyring by using gpg --import.
For example, if you save the key in a file named mysql_pubkey.asc, the import command
looks like this:
shell> gpg --import mysql_pubkey.asc
See the GPG documentation for more information on how to work with public keys.
After you have downloaded and imported the public build key, download your desired MySQL
package and the corresponding signature, which also is available from the download page. The signature file has the same name as the distribution file with an .asc extension. For example:
Distribution file
mysql-standard-4.0.17-pc-linux-i686.tar.gz
Signature file
mysql-standard-4.0.17-pc-linux-i686.tar.gz.asc
Make sure that both files are stored in the same directory and then run the following command to
verify the signature for the distribution file:
shell> gpg --verify package_name.asc
Example:
shell> gpg --verify mysql-standard-4.0.17-pc-linux-i686.tar.gz.asc
gpg: Warning: using insecure memory!
gpg: Signature made Mon 03 Feb 2003 08:50:39 PM MET
using DSA key ID 5072E1F5
55
Installing MySQL
gpg: Good signature from
"MySQL Package signing key (www.mysql.com) <[email protected]>"
The Good signature message indicates that everything is all right. You can ignore the insecure memory warning.
2.1.4.3. Signature Checking Using RPM
For RPM packages, there is no separate signature. RPM packages have a built-in GPG signature and
MD5 checksum. You can verify a package by running the following command:
shell> rpm --checksig package_name.rpm
Example:
shell> rpm --checksig MySQL-server-4.0.10-0.i386.rpm
MySQL-server-4.0.10-0.i386.rpm: md5 gpg OK
Note: If you are using RPM 4.1 and it complains about (GPG) NOT OK (MISSING KEYS:
GPG#5072e1f5), even though you have imported the MySQL public build key into your own
GPG keyring, you need to import the key into the RPM keyring first. RPM 4.1 no longer uses your
personal GPG keyring (or GPG itself). Rather, it maintains its own keyring because it is a systemwide application and a user's GPG public keyring is a user-specific file. To import the MySQL public key into the RPM keyring, first obtain the key as described in the previous section. Then use rpm
--import to import the key. For example, if you have the public key stored in a file named
mysql_pubkey.asc, import it using this command:
shell> rpm --import mysql_pubkey.asc
If you need to obtain the MySQL public key, see Section 2.1.4.2, “Signature Checking Using
GnuPG”.
2.1.5. Installation Layouts
This section describes the default layout of the directories created by installing binary or source distributions provided by MySQL AB. If you install a distribution provided by another vendor, some
other layout might be used.
On Windows, the default installation directory is C:\mysql. With MySQL version 4.1.5 and higher, this has changed to C:\Program Files\MySQL\MySQL Server 4.1, where 4.1 is the
major version of the installation. The folder has the following subdirectories:
Directory
Contents of Directory
bin
Client programs and the mysqld server
data
Log files, databases
Docs
Documentation
examples
Example programs and scripts
include
Include (header) files
lib
Libraries
scripts
Utility scripts
share
Error message files
Installations created from Linux RPM distributions result in files under the following system directories:
Directory
Contents of Directory
56
Installing MySQL
/usr/bin
Client programs and scripts
/usr/sbin
The mysqld server
/var/lib/mysql
Log files, databases
/usr/share/doc/packages
Documentation
/usr/include/mysql
Include (header) files
/usr/lib/mysql
Libraries
/usr/share/mysql
Error message and character set files
/usr/share/sql-bench
Benchmarks
On Unix, a tar file binary distribution is installed by unpacking it at the installation location you
choose (typically /usr/local/mysql) and creates the following directories in that location:
Directory
Contents of Directory
bin
Client programs and the mysqld server
data
Log files, databases
docs
Documentation, ChangeLog
include
Include (header) files
lib
Libraries
scripts
mysql_install_db
share/mysql
Error message files
sql-bench
Benchmarks
A source distribution is installed after you configure and compile it. By default, the installation step
installs files under /usr/local, in the following subdirectories:
Directory
Contents of Directory
bin
Client programs and scripts
include/mysql
Include (header) files
info
Documentation in Info format
lib/mysql
Libraries
libexec
The mysqld server
share/mysql
Error message files
sql-bench
Benchmarks and crash-me test
var
Databases and log files
Within an installation directory, the layout of a source installation differs from that of a binary installation in the following ways:
•
The mysqld server is installed in the libexec directory rather than in the bin directory.
•
The data directory is var rather than data.
•
mysql_install_db is installed in the bin directory rather than in the scripts directory.
•
The header file and library directories are include/mysql and lib/mysql rather than include and lib.
You can create your own binary installation from a compiled source distribution by executing the
57
Installing MySQL
scripts/make_binary_distribution script from the top directory of the source distribution.
2.2. Standard MySQL Installation Using a Binary Distribution
The next several sections cover the installation of MySQL on platforms where we offer packages
using the native packaging format of the respective platform. (This is also known as performing a
“binary install.”) However, binary distributions of MySQL are available for many other platforms as
well. See Section 2.7, “Installing MySQL on Other Unix-Like Systems” for generic installation instructions for these packages that apply to all platforms.
See Section 2.1, “General Installation Issues” for more information on what other binary distributions are available and how to obtain them.
2.3. Installing MySQL on Windows
A native Windows version of MySQL has been available from MySQL AB since version 3.21 and
represents a sizable percentage of the daily downloads of MySQL. This section describes the process for installing MySQL on Windows.
With the release of MySQL 4.1.5, MySQL AB has introduced a new installer for the Windows version of MySQL, combined with a new GUI Configuration Wizard. This combination automatically
installs MySQL, creates an option file, starts the server, and secures the default user accounts.
If you have installed a version of MySQL prior to version 4.1.5, you must perform the following
steps:
1.
Obtain and install the distribution.
2.
Set up an option file if necessary.
3.
Select the server that you want to use.
4.
Start the server.
5.
Assign passwords to the initial MySQL accounts.
This process also must be followed with newer MySQL installations where the installation package
does not include an installer.
MySQL for Windows is available in two distribution formats:
•
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 Visual Studio 2003 compiler system.
Generally speaking, you should use the binary distribution. It's simpler, and you need no additional
tools to get MySQL up and running.
This section describes how to install MySQL on Windows using a binary distribution. To install using a source distribution, see Section 2.8.6, “Installing MySQL from Source on Windows”.
2.3.1. Windows System Requirements
58
Installing MySQL
To run MySQL on Windows, you need the following:
•
A 32-bit Windows operating system such as 9x, Me, NT, 2000, XP, or Windows Server 2003.
A Windows NT based operating system (NT, 2000, XP, 2003) permits you to run the MySQL
server as a service. The use of a Windows NT based operating system is strongly recommended.
See Section 2.3.12, “Starting MySQL as a Windows Service”.
•
TCP/IP protocol support.
•
A copy of the MySQL binary distribution for Windows, which can be downloaded from http://dev.mysql.com/downloads/. See Section 2.1.3, “How to Get MySQL”.
Note: If you download the distribution via FTP, we recommend the use of an adequate FTP client with a resume feature to avoid corruption of files during the download process.
•
A tool that can read .zip files, to unpack the distribution file.
•
Enough space on the hard drive to unpack, install, and create the databases in accordance with
your requirements (generally a minimum of 200 megabytes is recommended.)
You may also have the following optional requirements:
•
If you plan to connect to the MySQL server via ODBC, you also need a Connector/ODBC
driver. See Section 24.1, “MySQL Connector/ODBC”.
•
If you need tables with a size larger than 4GB, install MySQL on an NTFS or newer filesystem.
Don't forget to use MAX_ROWS and AVG_ROW_LENGTH when you create tables. See Section 13.1.5, “CREATE TABLE Syntax”.
2.3.2. Choosing An Installation Package
Starting with MySQL version 4.1.5, there are three install packages to choose from when installing
MySQL on Windows. The Packages are as follows:
•
The Essentials Package: This package has a filename similar to mysql-essential-4.1.9-win32.msi and contains the minimum set of files needed to install MySQL
on Windows, including the Configuration Wizard. This package does not include optional components such as the embedded server and benchmark suite.
•
The Complete Package: This package has a filename similar to mysql-4.1.9-win32.zip
and contains all files needed for a complete Windows installation, including the Configuration
Wizard. This package includes optional components such as the embedded server and benchmark suite.
•
The Noinstall Archive: This package has a filename similar to mysql-noinstall-4.1.9-win32.zip and contains all the files found in the Complete install package,
with the exception of the Configuration Wizard. This package does not include an automated installer, and must be manually installed and configured.
The Essentials package is recommended for most users.
Your choice of install package affects the installation process you must follow. If you choose to install either the Essentials or Complete install packages, see Section 2.3.3, “Installing MySQL with
the Automated Installer”. If you choose to install MySQL from the Noinstall archive, see Section 2.3.6, “Installing MySQL from a Noinstall Zip Archive”.
59
Installing MySQL
2.3.3. Installing MySQL with the Automated Installer
Starting with MySQL 4.1.5, users can use the new MySQL Installation Wizard and MySQL Configuration Wizard to install MySQL on Windows. The MySQL Installation Wizard and MySQL Configuration Wizard are designed to install and configure MySQL in such a way that new users can
immediately get started using MySQL.
The MySQL Installation Wizard and MySQL Configuration Wizard are available in the Essentials
and Complete install packages, and are recommended for most standard MySQL installations. Exceptions include users who need to install multiple instances of MySQL on a single server and advanced users who want complete control of server configuration.
If you are installing a version of MySQL prior to MySQL 4.1.5, please follow the instructions for
installing MySQL from the Noinstall installation package. See Section 2.3.6, “Installing MySQL
from a Noinstall Zip Archive”.
2.3.4. Using the MySQL Installation Wizard
2.3.4.1. Introduction
MySQL Installation Wizard is a new installer for the MySQL server that uses the latest installer
technologies for Microsoft Windows. The MySQL Installation Wizard, in combination with the
MySQL Configuration Wizard, allows a user to install and configure a MySQL server that is ready
for use immediately after installation.
The MySQL Installation Wizard is the standard installer for all MySQL server distributions, version
4.1.5 and higher. Users of previous versions of MySQL need to manually shut down and remove
their existing MySQL installations before installing MySQL with the MySQL Installation Wizard.
See Section 2.3.4.7, “Upgrading MySQL” for more information on upgrading from a previous version.
Microsoft has included an improved version of their Microsoft Windows Installer (MSI) in the recent versions of Windows. Using the MSI has become the de-facto standard for application installations on Windows 2000, Windows XP, and Windows Server 2003. The MySQL Installation Wizard
makes use of this technology to provide a smoother and more flexible installation progress.
The Microsoft Windows Installer Engine was updated with the release of Windows XP; those using
a previous version of Windows can reference this Microsoft Knowledge Base article
[http://support.microsoft.com/default.aspx?scid=kb;EN-US;292539] for information on upgrading
to the latest version of the Windows Installer Engine.
Further, Microsoft has introduced the WiX (Windows Installer XML) tool set recently. It is the first
highly acknowledged Open Source project from Microsoft. We switched to WiX because it is an
Open Source project and it allows us to handle the complete Windows installation process in a flexible way with scripts.
Improving the MySQL Installation Wizard depends on the support and feedback of users like you. If
you find that the MySQL Installation Wizard is lacking some feature important to you, or if you discover a bug, please use our MySQL Bug System [http://bugs.mysql.com] to request features or report problems.
2.3.4.2. Downloading and Starting the MySQL Installation Wizard
The MySQL server install packages can be downloaded from http://dev.mysql.com/downloads/. If
the package you download is contained within a Zip archive, you need to extract the archive first.
The process for starting the wizard depends on the contents of the install package you download. If
there is a setup.exe file present, double-click it to start the install process. If there is a .msi file
present, double-click it to start the install process.
2.3.4.3. Choosing an Install Type
60
Installing MySQL
There are up three installation types available: Typical, Complete, and Custom.
The Typical installation type installs the MySQL server, the mysql command-line client, and
the command-line utilities. The command-line clients and utilities include mysqldump, myisamchk, and several other tools to help you manage the MySQL server.
The Complete installation type installs all components included in the installation package. The
full installation package includes components such as the embedded server library, the benchmark
suite, support scripts, and documentation.
The Custom installation type gives you complete control over which packages you wish to install
and the installation path that is used. See Section 2.3.4.4, “The Custom Install Dialog” for more information on performing a custom install.
If you choose the Typical or Complete installation types and click the Next button, you advance to the confirmation screen to confirm your choices and begin the installation. If you choose
the Custom installation type and click the Next button, you advance to the custom install dialog,
described in Section 2.3.4.4, “The Custom Install Dialog”
2.3.4.4. The Custom Install Dialog
If you wish to change the installation path or the specific components that are installed by the
MySQL Installation Wizard, you should choose the Custom installation type.
All available components are listed in a tree view on the left side of the custom install dialog. Components that are not installed have a red X icon, components that are installed have a gray icon. To
change whether a component is installed, click on the component's icon and choose an new option
from the drop-down list that appears.
You can change the default installation path by clicking the Change... button to the right of the displayed installation path.
After choosing your install components and installation path, click the Next button to advance to the
confirmation dialog.
2.3.4.5. The Confirmation Dialog
Once you choose an installation type and optionally choose your installation components, you advance to the confirmation dialog. Your installation type and installation path are displayed for you
to review.
To install MySQL if you are satisfied with your settings, click the Install button. To change your
settings, click the Back button. To exit the MySQL Installation Wizard without installing MySQL,
click the Cancel button.
After installation is complete, you are given the option of registering with the MySQL web site. Registration gives you access to post in the MySQL forums at forums.mysql.com
[http://forums.mysql.com], along with the ability to report bugs at bugs.mysql.com
[http://bugs.mysql.com] and to subscribe to the newsletter. The final screen of the installer provides
a summary of the installation and gives you the option to launch the MySQL Configuration Wizard,
which you can use to create a configuration file, install the MySQL service, and configure security.
2.3.4.6. Changes Made by MySQL Installation Wizard
Once you click the Install button, the MySQL Installation Wizard begins the installation process and
makes certain changes to your system which are described in the sections that follow.
Changes to the Registry
The MySQL Installation Wizard creates one Windows registry key in a typical install situation, located in HKEY_LOCAL_MACHINE\SOFTWARE\MySQL AB.
61
Installing MySQL
The MySQL Installation Wizard creates a key named after the major version of the server that is being installed, such as MySQL Server 4.1. It contains two string values, Location and Version. The Location string contains the path to the installation directory. In a default installation
it contains C:\Program Files\MySQL\MySQL Server 4.1\. The Version string contains the release number. For example, for an installation of MySQL Server 4.1.5 the key contains a
value of 4.1.5.
These registry keys are used to help external tools identify the installed location of the MySQL server, preventing a complete scan of the hard-disk to determine the installation path of the MySQL
server. The registry keys are not required to run the server and when using the noinstall Zip
archive the registry keys are not created.
Changes to the Start Menu
The MySQL Installation Wizard creates a new entry in the Windows Start menu under a common
MySQL menu heading named after the major version of MySQL that you have installed. For example, if you install MySQL 4.1, the MySQL Installation Wizard creates a MySQL Server 4.1 section in the start menu.
The following entries are created within the new Start menu section:
•
MySQL Command Line Client: This is a shortcut to the mysql command-line client and
is configured to connect as the root user. The shortcut prompts for a root user password
when connecting.
•
MySQL Server Instance Config Wizard: This is a shortcut to the MySQL Configuration Wizard. Use this shortcut to configure a newly installed server, or to re-configure an existing server.
•
MySQL Documentation: This is a link to the MySQL server documentation that is stored
locally in the MySQL server installation directory. This option is not available when the MySQL
server is installed from the essential installation package.
Changes to the File System
The MySQL Installation Wizard by default installs the MySQL server to C:\Program
Files\MySQL\MySQL Server 4.1, where Program Files is the default location for applications in your system, and 4.1 is the major version of your MySQL server. This is the new recommended location for the MySQL server, replacing the previous default location of c:\mysql.
By default, all MySQL applications are stored in a common directory at C:\Program
Files\MySQL, where Program Files is the default location for applications in your Windows
installation. A typical MySQL installation on a developer machine may look like this:
C:\Program
C:\Program
C:\Program
C:\Program
Files\MySQL\MySQL
Files\MySQL\MySQL
Files\MySQL\MySQL
Files\MySQL\MySQL
Server 4.1
Server 5.0
Administrator 1.0
Query Browser 1.0
This approach makes it easier to manage and maintain all MySQL applications installed on a particular system.
2.3.4.7. Upgrading MySQL
From MySQL version 4.1.5, the new MySQL Installation Wizard can perform server upgrades automatically using the upgrade capabilities of MSI. That means you do not need to remove a previous
installation manually before installing a new release. The installer automatically shuts down and removes the previous MySQL service before installing the new version.
Automatic upgrades are only available when upgrading between installations that have the same major and minor version numbers. For example, you can upgrade automatically from MySQL 4.1.5 to
62
Installing MySQL
MySQL 4.1.6, but not from MySQL 4.1 to MySQL 5.0.
If you are upgrading MySQL version 4.1.4 or earlier to version 4.1.5 or later, you must first manually shut down and remove the older installation before upgrading. Be sure to back up your databases before performing such an upgrade, so that you can restore the databases after the upgrade is
completed. It is always recommended that you back up your data before performing any upgrades.
See Section 2.3.15, “Upgrading MySQL on Windows”.
2.3.5. Using the Configuration Wizard
2.3.5.1. Introduction
The MySQL Configuration Wizard helps automate the process of configuring your server under
Windows. The MySQL Configuration Wizard creates a custom my.ini file by asking you a series
of questions and then applying your responses to a template to generate a my.ini file that is tuned
to your installation.
The MySQL Configuration Wizard is included with the MySQL server starting with MySQL version 4.1.5, but is designed to work with MySQL servers versions 4.1 and higher. The MySQL Configuration Wizard is currently available for Windows users only.
MySQL Configuration Wizard is to a large extent the result of feedback MySQL AB has received
from many users over a period of several years. However, if you find it's lacking some feature important to you, or if you discover a bug, please use our MySQL Bug System [http://bugs.mysql.com]
to request features or report problems.
2.3.5.2. Starting the MySQL Configuration Wizard
The MySQL Configuration Wizard is typically launched from the MySQL Installation Wizard, as
the MySQL Installation Wizard exits. You can also launch the MySQL Configuration Wizard by
clicking the MySQL Server Instance Config Wizard entry in the MySQL section of the Start
menu.
In addition, you can navigate to the bin directory of your MySQL installation and launch the
MySQLInstanceConfig.exe file directly.
2.3.5.3. Choosing a Maintenance Option
If the MySQL Configuration Wizard detects an existing my.ini file, you have the option of either
re-configuring your existing server, or removing the server instance by deleting the my.ini file
and stopping and removing the MySQL service.
To reconfigure an existing server, choose the Re-configure Instance option and click the
Next button. Your existing my.ini file is renamed to my timestamp.ini.bak, where
timestamp is the date and time the existing my.ini file was created. To remove the existing
server instance, choose the Remove Instance option and click the Next button.
If you choose the Remove Instance option, you advance to a confirmation window. Click the
Execute button and the MySQL Configuration Wizard stops and removes the MySQL service and
deletes the my.ini file. The server installation and its data folder are not removed.
If you choose the Re-configure Instance option, you advance to the Configuration
Type dialog where you can choose the type of installation you wish to configure.
2.3.5.4. Choosing a Configuration Type
When you start the MySQL Configuration Wizard for a new MySQL installation, or choose the Reconfigure Instance option for an existing installation, you advance to the Configuration Type dialog.
63
Installing MySQL
There are two configuration types available: Detailed Configuration and Standard
Configuration. The Standard Configuration option is intended for new users who
want to get started with MySQL quickly without having to make a lot of decisions in regards to
server configuration. The Detailed Configuration option is intended for advanced users
who want more fine-grained control of server configuration.
If you are new to MySQL and need a server configured as a single-user developer machine the
Standard Configuration should suit your needs. Choosing the Standard Configuration option causes the MySQL Configuration Wizard to automatically set all configuration options
with the exception of the Service Options and Security Options.
The Standard Configuration sets options that may be incompatible with systems where
there are existing MySQL installations. If you have an existing MySQL installation on your system
in addition to the installation you wish to configure, the Detailed Configuration option is
recommended.
To complete the Standard Configuration, please refer to the sections on Service Options and Security Options, located at Section 2.3.5.11, “The Service Options Dialog” and
Section 2.3.5.12, “The Security Options Dialog” respectively.
2.3.5.5. The Server Type Dialog
There are three different server types available to choose from, and the server type you choose affects the decisions the MySQL Configuration Wizard makes with regards to memory, disk, and processor usage.
•
Developer Machine: Choose this option for a typical desktop workstation where MySQL is
intended only for personal use. It is assumed that many other desktop applications are running.
The MySQL server is configured to use minimal system resources.
•
Server Machine: Choose this option for a server machine where the MySQL server is running alongside other server applications such as FTP, email, and web servers. The MySQL server is configured to use a medium portion of the system resources.
•
Dedicated MySQL Server Machine: Choose this option for a server machine that is intended to run only the MySQL server. It is assumed that no other applications are running. The
MySQL server is configured to use all available system resources.
2.3.5.6. The Database Usage Dialog
The Database Usage dialog allows you to indicate the table handlers you expect to use when
creating MySQL tables. The option you choose determines whether the InnoDB table handler is
available and what percentage of the server resources are available to InnoDB.
•
Multifunctional Database: This option enables both the InnoDB and MyISAM table
handlers and divides resources evenly between the two. This option is recommended for users
that use both table handlers on a regular basis.
•
Transactional Database Only: This option enables both the InnoDB and MyISAM table handlers but dedicates most server resources toward the InnoDB table handler. This option is
recommended for users that use InnoDB almost exclusively and make only minimal use of MyISAM.
•
Non-Transactional Database Only: This option disables the InnoDB table handler
completely and dedicates all server resources to the MyISAM table handler. This option is recommended for users who do not use InnoDB.
2.3.5.7. The InnoDB Tablespace Dialog
64
Installing MySQL
Some users may want to locate the InnoDB tablespace files in a different location than the MySQL
server data directory. Placing the tablespace files in a separate location can be desirable if your system has a higher capacity or higher performance storage device available, such as a RAID storage
system.
To change the default location for the InnoDB tablespace files, choose a new drive from the dropdown list of drive letters and choose a new path from the drop-down list of paths. To create a custom path, click the ... button.
If you are modifying the configuration of an existing server, you must click the Modify button before you change the path. In this situation you have to manually move the existing tablespace files to
the new location before starting the server.
2.3.5.8. The Concurrent Connections Dialog
It is important to set a limit to the number of concurrent connections to the MySQL server that can
be established to prevent the server from running out of resources. The Concurrent Connections dialog allows you to choose the expected usage of your server, and sets the limit for concurrent connections accordingly. It is also possible to manually set the concurrent connection limit.
•
Decision Support (DSS)/OLAP: Choose this option if your server does not require a
large number of concurrent connections. The maximum number of connections is set at 100,
with an average of 20 concurrent connections assumed.
•
Online Transaction Processing (OLTP): Choose this option if your server requires
a large number of concurrent connections. The maximum number of connections is set at 500.
•
Manual Setting: Choose this option to manually set the maximum number of concurrent
connections to the server. Choose the number of concurrent connections from the drop-down
box provided, or type the maximum number of connections into the drop-down box if the number you desire is not listed.
2.3.5.9. The Networking Options Dialog
Use the Networking Options dialog to enable or disable TCP/IP networking and to configure
the port number that is used to connect to the MySQL server.
TCP/IP networking is enabled by default. To disable TCP/IP networking, uncheck the box next to
the Enable TCP/IP Networking option.
Port 3306 is used by default. To change the port used to access MySQL, choose a new port number
from the drop-down box or type a new port number directly into the drop-down box. If the port
number you choose is in use you are prompted to confirm your choice of port number.
2.3.5.10. The Character Set Dialog
The MySQL server supports multiple character sets and it is possible to set a default server character
set that is applied to all tables, columns, and databases unless overridden. Use the Character
Set dialog to change the default character set of the MySQL server.
•
Standard Character Set: Choose this option if you want to use Latin1 as the default
server character set. Latin1 is used for English and many Western European languages.
•
Best Support For Multilingualism: Choose this option if you want to use UTF8 as
the default server character set. UTF8 can store characters from many different languages in a
single character set.
•
Manual Selected Default Character Set / Collation: Choose this option if
you want to pick the server's default character set manually. Choose the desired character set
65
Installing MySQL
from the provided drop-down list.
2.3.5.11. The Service Options Dialog
On Windows NT based platforms, the MySQL server can be installed as a service. When installed
as a service, the MySQL server can be started automatically during system startup, and even restarted automatically by Windows in the event of a service failure.
The MySQL Configuration Wizard installs the MySQL server as a service by default, using the service name MySQL. If you do not wish to install the service, un-check the box next to the Install
As Windows Service option. You can change the service name by picking a new service name
from the drop-down box provided or by typing a new service name into the drop-down box.
To install the MySQL server as a service but not have it started automatically at startup, un-check
the box next to the Launch the MySQL Server automatically option.
2.3.5.12. The Security Options Dialog
It is strongly recommended that you set a root password for your MySQL server, and the MySQL
Configuration Wizard requires you set a root password by default. If you do not wish to set a
root password, un-check the box next to the Modify Security Settings option.
To set the root password, type the desired password into both the New root password and
Confirm boxes. If you are re-configuring an existing server, you also need to enter the existing
root password into the Current root password box.
To prevent root logins from across the network, check the box next to the Root may only
connect from localhost option. This increases the security of your root account.
To create an anonymous user account, check the box next to the Create An Anonymous Account option. Creating an anonymous account can decrease server security and cause login and
permission difficulties and is not recommended.
2.3.5.13. The Confirmation Dialog
The final dialog in the MySQL Configuration Wizard is the Confirmation Dialog. To start
the configuration process, click the Execute button. To return to a previous dialog, click the Back
button. To exit the MySQL Configuration Wizard without configuring the server, click the Cancel
button.
After you click the Execute button, the MySQL Configuration Wizard performs a series of tasks
with progress displayed onscreen as the tasks are performed.
The MySQL Configuration Wizard firsts determines various configuration file options based on
your choices using a template prepared by MySQL AB developers and engineers. This template is
named my-template.ini and is located in your server installation directory.
The MySQL Configuration Wizard then writes these options to a my.ini file. The final location of
the my.ini file is displayed next to the Write configuration file task.
If you chose to create a service for the MySQL server the MySQL Configuration Wizard creates and
starts the service. If you are re-configuring an existing service, the MySQL Configuration Wizard
restarts the service to apply your configuration changes.
If you chose to set a root password, the MySQL Configuration Wizard connects to the server, sets
your new root password and applies any other security settings you may have selected.
After the MySQL Configuration Wizard has completed its tasks, a summary is shown. Click the
Finish button to exit the MySQL Configuration Wizard.
2.3.5.14. The Location of the my.ini File
66
Installing MySQL
In MySQL installations prior to version 4.1.5 it was customary to name the server configuration file
my.cnf or my.ini and locate the file either at c:\my.cnf or c:\Windows\my.ini.
The new MySQL Configuration Wizard places the my.ini file in the installation directory of the
MySQL server. This helps associate configuration files with particular server instances.
To ensure that the MySQL server knows where to look for the my.ini file, an argument similar to
this is passed to the MySQL server as part of the service installation:
--defaults-file="C:\Program Files\MySQL\MySQL Server 4.1\my.ini",
where C:\Program Files\MySQL\MySQL Server 4.1 is replaced with the installation
path to the MySQL Server.
The --defaults-file instructs the MySQL server to read the specified file for configuration
options.
2.3.5.15. Editing The my.ini File
To modify the my.ini file, open it with a text editor and make any necessary changes. You can
also
modify
the
server
configuration
with
the
MySQL
Administrator
[http://www.mysql.com/products/administrator/] utility.
MySQL clients and utilities such as the mysql command-line client and mysqldump are not able
to locate the my.ini file located in the server installation directory. To configure the client and
utility applications, create a new my.ini file in the c:\Windows directory.
2.3.6. Installing MySQL from a Noinstall Zip Archive
Users who are installing from the Noinstall package, or who are installing a version of MySQL prior
to 4.1.5 can use the instructions in this section to manually install MySQL. If you are installing a
version prior to 4.1.5 with an install package that includes a Setup program, substitute running the
Setup program for extracting the archive.
The process for installing MySQL from a Zip archive is as follows:
1.
Extract the archive to the desired install directory.
2.
Create an option file.
3.
Choose a MySQL server type.
4.
Start the MySQL server.
5.
Secure the default user accounts.
This process is described in the sections that follow.
2.3.7. Extracting the Install Archive
To install MySQL manually, do the following:
1.
If you are upgrading from a previous version please refer to Section 2.3.15, “Upgrading
MySQL on Windows” before beginning the upgrade process.
2.
If you are using a Windows NT-based operating system such as Windows NT, Windows 2000,
Windows XP, or Windows Server 2003, make sure that you are logged in as a user with administrator privileges.
3.
Choose an installation location. Traditionally the MySQL server is installed at C:\mysql, and
the new MySQL Installation Wizard installs MySQL to C:\Program Files\MySQL. If
67
Installing MySQL
you do not install MySQL at C:\mysql, you must specify the path to the install directory during startup or in an option file. See Section 2.3.8, “Creating an Option File”.
4.
Extract the install archive to the chosen installation location using your preferred Zip archive
tool. Some tools may extract the archive to a folder within your chosen installation location. If
this occurs you can move the contents of the subfolder into the chosen installation location.
2.3.8. Creating an Option File
If you need to specify startup options when you run the server, you can indicate them on the command line or place them in an option file. For options that are used every time the server starts, you
may find it most convenient to use an option file to specify your MySQL configuration. This is particularly true under the following circumstances:
•
The installation or data directory locations are different from the default locations (C:\mysql
and C:\mysql\data).
•
You need to tune the server settings. For example, to use the InnoDB transactional tables in
MySQL 3.23, you must manually add some extra lines to the option file, as described in Section 15.4, “InnoDB Configuration”. (As of MySQL 4.0, InnoDB creates its data files and log
files in the data directory by default. This means you need not configure InnoDB explicitly.
You may still do so if you wish, and an option file is useful in this case, too.)
When the MySQL server starts on Windows, it looks for options in two files: the my.ini file in the
Windows directory, and the C:\my.cnf file. The Windows directory typically is named
something like C:\WINDOWS or C:\WinNT. You can determine its exact location from the value
of the WINDIR environment variable using the following command:
C:\> echo %WINDIR%
MySQL looks for options first in the my.ini file, then in the my.cnf file. However, to avoid confusion, it's best if you use only one file. If your PC uses a boot loader where the C: drive isn't the
boot drive, your only option is to use the my.ini file. Whichever option file you use, it must be a
plain text file.
You can also make use of the example option files included with your MySQL distribution. Look in
your install directory for files such as my-small.cnf, my-medium.cnf, my-large.cnf, etc., which you
can rename and copy to the appropriate location for use as a base configuration file.
An option file can be created and modified with any text editor, such as the Notepad program. For
example, if MySQL is installed at E:\mysql and the data directory is located at
E:\mydata\data, you can create the option file and set up a [mysqld] section to specify values for the basedir and datadir parameters:
[mysqld]
# set basedir to your installation path
basedir=E:/mysql
# set datadir to the location of your data directory
datadir=E:/mydata/data
Note that Windows pathnames are specified in option files using forward slashes rather than backslashes. If you do use backslashes, you must double them:
[mysqld]
# set basedir to your installation path
basedir=E:\\mysql
# set datadir to the location of your data directory
datadir=E:\\mydata\\data
68
Installing MySQL
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.
2.3.9. Selecting a MySQL Server type
Starting with MySQL 3.23.38, the Windows distribution includes both the normal and the MySQLMax server binaries.
Up through the early releases of MySQL 4.1, the servers included in Windows distributions are
named like this:
Binary
Description
mysqld
Compiled with full debugging and automatic memory allocation checking, and
InnoDB and BDB tables.
mysqld-opt
Optimized binary. From version 4.0 on, InnoDB is enabled. Before 4.0, this
server includes no transactional table support.
mysqld-nt
Optimized binary for Windows NT, 2000, and XP with support for named
pipes.
mysqld-max
Optimized binary with support for InnoDB and BDB tables.
mysqldmax-nt
Like mysqld-max, but compiled with support for named pipes.
We have found that the server with the most generic name (mysqld) is the one that many users are
likely to choose by default. However, that is also the server that results in the highest memory and
CPU use due to the inclusion of full debugging support. The server named mysqld-opt is a better
general-use server choice to make instead if you don't need debugging support and don't want the
maximal feature set offered by the -max servers or named pipe support offered by the -nt servers.
To make it less likely that the debugging server would be chosen inadvertently, some name changes
were made from MySQL 4.1.2 to 4.1.4: mysqld has been renamed to mysqld-debug and
mysqld-opt has been renamed to mysqld. Thus, the server that includes debugging support indicates that in its name, and the server named mysqld is an efficient default choice. The other servers still have their same names. The resulting servers are named like this:
Binary
Description
mysqld-debug Compiled with full debugging and automatic memory allocation checking, and
InnoDB and BDB tables.
mysqld
Optimized binary with InnoDB support.
mysqld-nt
Optimized binary for Windows NT, 2000, and XP with support for named
pipes.
mysqld-max
Optimized binary with support for InnoDB and BDB tables.
mysqldmax-nt
Like mysqld-max, but compiled with support for named pipes.
The name changes were not both instituted at the same time. If you have MySQL 4.1.2 or 4.1.3, it
might be that you have a server named mysqld-debug but not one named mysqld. In this case,
69
Installing MySQL
you should have a server mysqld-opt, which you should choose as your default server unless you
need maximal features, named pipes, or debugging support.
All of the preceding binaries are optimized for modern Intel processors, but should work on any Intel i386-class or higher processor.
As of MySQL 4.0, all Windows servers have support for symbolic linking of database directories.
Before MySQL 4.0, only the debugging and Max server versions include this feature.
MySQL supports TCP/IP on all Windows platforms. The mysqld-nt and mysql-max-nt servers support named pipes on Windows NT, 2000, XP, and 2003. However, the default is to use TCP/
IP regardless of the platform. (Named pipes are slower than TCP/IP in many Windows configurations.)
Named pipe use is subject to these conditions:
•
Starting from MySQL 3.23.50, named pipes are enabled only if you start the server with the -enable-named-pipe option. It is necessary to use this option explicitly because some
users have experienced problems shutting down the MySQL server when named pipes were
used.
•
Named pipe connections are allowed only by the mysqld-nt or mysqld-max-nt servers,
and only if the server is run on a version of Windows that supports named pipes (NT, 2000, XP,
2003).
•
These servers can be run on Windows 98 or Me, but only if TCP/IP is installed; named pipe connections cannot be used.
•
These servers can not be run on Windows 95.
Note: Most of the examples in reference manual use mysqld as the server name. If you choose to
use a different server, such as mysqld-nt, make the appropriate substitutions in the commands
that are shown in the examples.
2.3.10. Starting the Server for the First Time
On Windows 95, 98, or Me, MySQL clients always connect to the server using TCP/IP. (This allows any machine on your network to connect to your MySQL server.) Because of this, you must
make sure that TCP/IP support is installed on your machine before starting MySQL. You can find
TCP/IP on your Windows CD-ROM.
Note that if you are using an old Windows 95 release (for example, OSR2), it's likely that you have
an old Winsock package; MySQL requires Winsock 2! You can get the newest Winsock from http://www.microsoft.com/. Windows 98 has the new Winsock 2 library, so it is unnecessary to update the library.
On NT-based systems such as Windows NT, 2000, XP, or 2003, clients have two options. They can
use TCP/IP, or they can use a named pipe if the server supports named pipe connections. To get
MySQL to work with TCP/IP on Windows NT 4, you must install service pack 3 (or newer).
In MySQL versions 4.1 and higher, Windows servers also support shared-memory connections if
started with the --shared-memory option. Clients can connect through shared memory by using
the --protocol=memory option.
For information about which server binary to run, see Section 2.3.9, “Selecting a MySQL Server
type”.
This section gives a general overview of starting the MySQL server. The following sections provide
more specific information for starting the MySQL server from the command line or as a Windows
service.
The examples in these sections assume that MySQL is installed under the default location of
70
Installing MySQL
C:\mysql. Adjust the pathnames shown in the examples if you have MySQL installed in a different location.
Testing is best done from a command prompt in a console window (a “DOS window”). This way
you can have the server display status messages in the window where they are easy to see. If
something is wrong with your configuration, these messages make it easier for you to identify and
fix any problems.
To start the server, enter this command:
C:\> C:\mysql\bin\mysqld --console
For servers that include InnoDB support, you should see the following messages as the server
starts:
InnoDB: The first specified datafile c:\ibdata\ibdata1 did not exist:
InnoDB: a new database to be created!
InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200
InnoDB: Database physically writes the file full: wait...
InnoDB: Log file c:\iblogs\ib_logfile0 did not exist: new to be created
InnoDB: Setting log file c:\iblogs\ib_logfile0 size to 31457280
InnoDB: Log file c:\iblogs\ib_logfile1 did not exist: new to be created
InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280
InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be created
InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280
InnoDB: Doublewrite buffer not found: creating new
InnoDB: Doublewrite buffer created
InnoDB: creating foreign key constraint system tables
InnoDB: foreign key constraint system tables created
011024 10:58:25 InnoDB: Started
When the server finishes its startup sequence, you should see something like this, which indicates
that the server is ready to service client connections:
mysqld: ready for connections
Version: '4.0.14-log' socket: ''
port: 3306
The server continues to write to the console any further diagnostic output it produces. You can open
a new console window in which to run client programs.
If you omit the --console option, the server writes diagnostic output to the error log in the data
directory (C:\mysql\data by default). The error log is the file with the .err extension.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After
starting the server, you should set up passwords for them using the instructions in Section 2.9,
“Post-Installation Setup and Testing”.
2.3.11. Starting MySQL from the Windows Command
Line
The MySQL server can be started manually from the command line. This can be done on any version of Windows.
To start the mysqld server from the command line, you should start a console window (a “DOS
window”) and enter this command:
C:\> C:\Program Files\MySQL\MySQL Server 4.1\bin\mysqld
The path used in the preceding example may vary depending on the install location of MySQL on
your system.
71
Installing MySQL
On non-NT versions of Windows, this starts mysqld in the background. That is, after the server
starts, you should see another command prompt. If you start the server this way on Windows NT,
2000, XP, or 2003, the server runs in the foreground and no command prompt appears until the server exits. Because of this, you should open another console window to run client programs while the
server is running.
You can stop the MySQL server by executing this command:
C:\> C:\Program Files\MySQL\MySQL Server 4.1\bin\mysqladmin -u root shutdown
This invokes the MySQL administrative utility mysqladmin to connect to the server and tell it to
shut down. The command connects as the MySQL root user, which is the default administrative
account in the MySQL grant system. Note that users in the MySQL grant system are wholly independent from any login users under Windows.
If mysqld doesn't start, check the error log to see whether the server wrote any messages there to
indicate the cause of the problem. The error log is located in the C:\mysql\data directory. It is
the file with a suffix of .err. You can also try to start the server as mysqld --console; in this
case, you may get some useful information on the screen that may help solve the problem.
The last option is to start mysqld with --standalone --debug. In this case, mysqld writes
a log file C:\mysqld.trace that should contain the reason why mysqld doesn't start. See Section F.1.2, “Creating Trace Files”.
Use mysqld --verbose --help to display all the options that mysqld understands. (Prior to
MySQL 4.1, omit the --verbose option.)
2.3.12. Starting MySQL as a Windows Service
On the NT family (Windows NT, 2000, XP, 2003), the recommended way to run MySQL is to install it as a Windows service. With the MySQL server installed as a service, Windows starts and
stops it server automatically when Windows starts and stops. A MySQL server installed as a service
can also be controlled from the command line using NET commands, or with the graphical Services utility.
The Services utility (the Windows Service Control Manager) can be found in the Windows Control Panel (under Administrative Tools on Windows 2000, XP, and Server
2003). It is advisable to close the Services utility while performing server installation or removal
operations from this command line. This prevents some odd errors.
Before installing MySQL as a Windows service, you should first stop the current server if it is running by using the following command:
C:\> C:\mysql\bin\mysqladmin -u root shutdown
This invokes the MySQL administrative utility mysqladmin to connect to the server and tell it to
shut down. The command connects as the MySQL root user, which is the default administrative
account in the MySQL grant system. Note that users in the MySQL grant system are wholly independent from any login users under Windows.
Install the server as a service using this command:
C:\> mysqld --install
If you have problems installing mysqld as a service using just the server name, try installing it using its full pathname. For example:
C:\> C:\mysql\bin\mysqld --install
The service-installation command does not start the server. Instructions for that are given later in
72
Installing MySQL
this section.
Before MySQL 4.0.2, no command-line arguments can be given following the --install option.
MySQL 4.0.2 and up offers limited support for additional arguments:
•
You can specify a service name immediately following the --install option. The default
service name is MySQL.
•
As of MySQL 4.0.3, if a service name is given, it can be followed by a single option. By convention, this should be --defaults-file=file_name to specify the name of an option
file from which the server should read options when it starts.
It is possible to use a single option other than --defaults-file, but this is discouraged. -defaults-file is more flexible because it enables you to specify multiple startup options
for the server by placing them in the named option file. Also, in MySQL 5.0, use of an option
different from --defaults-file is not supported until 5.0.3.
•
As of MySQL 5.0.1, you can also specify a --local-service option following the service
name. This causes the server to run using the LocalService Windows account that has limited system privileges. This account is available only for Windows XP or newer. If both -defaults-file and --local-service are given following the service name, they can
be in any order.
For a MySQL server that is installed as a Windows service, the following rules determine the service name and option files that the server uses:
•
If the service-installation command specifies no service name or the default service name
(MySQL) following the --install option, the server uses the a service name of MySQL and
reads options from the [mysqld] group in the standard option files.
•
If the service-installation command specifies a service name other than MySQL following the -install option, the server uses that service name. It reads options from the group that has
the same name as the service, and reads options from the standard option files.
As of MySQL 4.0.17, the server also reads options from the [mysqld] group from the standard option files. This allows you to use the [mysqld] group for options that should be used by
all MySQL services, and an option group with the same name as a service for use by the server
installed with that service name.
•
If the service-installation command specifies a --defaults-file option after the service
name, the server reads options only from the [mysqld] group of the named file and ignores
the standard option files.
As a more complex example, consider the following command:
C:\> C:\mysql\bin\mysqld --install MySQL --defaults-file=C:\my-opts.cnf
Here, the default service name (MySQL) is given after the --install option. If no -defaults-file option had been given, this command would have the effect of causing the
server to read the [mysqld] group from the standard option files. However, because the -defaults-file option is present, the server reads options from the [mysqld] option group,
but only from the named file.
You can also specify options as “Start parameters” in the Windows Services utility before you start the MySQL service.
Note: Prior to MySQL 4.0.17, a server installed as a Windows service has problems starting if its
pathname or the service name contains spaces. For this reason, with older versions, avoid installing
MySQL in a directory such as C:\Program Files or using a service name containing spaces.
73
Installing MySQL
Once a MySQL server has been installed as a service, Windows starts the service automatically
whenever Windows starts. The service also can be started immediately from the Services utility,
or by using the command NET START MySQL. The NET command is not case sensitive.
When run as a service, mysqld has no access to a console window, so no messages can be seen
there. If mysqld doesn't start, check the error log to see whether the server wrote any messages
there to indicate the cause of the problem. The error log is located in the MySQL data directory (for
example, C:\mysql\data). It is the file with a suffix of .err.
When a MySQL server has been installed as a service, and the service is running, Windows stops
the service automatically when Windows shuts down. The server also can be stopped manually by
using the Services utility, the command NET STOP MySQL, or the command mysqladmin
shutdown.
From MySQL 3.23.44 on, you have the choice of installing the server as a Manual service if you
don't wish the service to be started automatically during the boot process. To do this, use the -install-manual option rather than the --install option:
C:\> C:\mysql\bin\mysqld --install-manual
To remove a server that is installed as a service, first stop it if it is running. Then use the -remove option to remove it:
C:\> C:\mysql\bin\mysqld --remove
For MySQL versions older than 3.23.49, one problem with automatic MySQL service shutdown is
that Windows waited only for a few seconds for the shutdown to complete, then killed the database
server process if the time limit was exceeded. This had the potential to cause problems. (For example, the InnoDB storage engine would have to perform crash recovery at the next startup.) Starting from MySQL 3.23.49, Windows waits longer for the MySQL server shutdown to complete. If
you notice this still is not enough for your installation, it is safest not to run the MySQL server as a
service. Instead, start it from the command-line prompt, and stop it with mysqladmin shutdown.
This change to tell Windows to wait longer when stopping the MySQL server works for Windows
2000 and XP. It does not work for Windows NT, where Windows waits only 20 seconds for a service to shut down, and after that kills the service process. You can increase this default by opening
the Registry Editor \winnt\system32\regedt32.exe and editing the value of WaitToKillServiceTimeout
at
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control in the Registry tree.
Specify the new larger value in milliseconds. For example, the value 120000 tells Windows NT to
wait up to 120 seconds.
If mysqld is not running as a service, you can start it from the command line. For instructions, see
Section 2.3.11, “Starting MySQL from the Windows Command Line”.
Please see Section 2.3.14, “Troubleshooting a MySQL Installation Under Windows” if you encounter difficulties during installation.
2.3.13. Testing The MySQL Installation
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 respond to TCP/IP connections from client programs on Windows 9x/Me,
there is probably a problem with your DNS. In this case, start mysqld with the 74
Installing MySQL
-skip-name-resolve option and use only localhost and IP numbers in the Host column
of the MySQL grant tables.
You can force a MySQL client to use a named pipe connection rather than TCP/IP by specifying the
--pipe option or by specifying . (period) as the host name. Use the --socket option to specify
the name of the pipe. As of MySQL 4.1, you can use the --protocol=PIPE option instead.
There are two versions of the MySQL command-line tool on Windows:
Binary
Description
mysql
Compiled on native Windows, offering limited text editing capabilities.
mysqlc
Compiled with the Cygnus GNU compiler and libraries, which offers readline
editing. mysqlc was intended for use primarily with Windows 9x/Me. It does not
support the updated authentication protocol used beginning with MySQL 4.1, and is
not supported in MySQL 4.1 and above. Beginning with MySQL 4.1.8, it is no
longer included in MySQL Windows distributions.
To use mysqlc, you must have a copy of the cygwinb19.dll library installed somewhere that
mysqlc can find it. If your distribution does not have the cygwinb19.dll library in the bin
directory under the base directory of your MySQL installation, look for it in the lib directory and
copy it to your Windows system directory (\Windows\system or a similar place).
2.3.14. Troubleshooting a MySQL Installation Under
Windows
When installing and running MySQL for the first time, you may encounter certain errors that prevent the MySQL server from starting. The purpose of this section is to help you diagnose and correct some of these errors.
Your first resource when troubleshooting server issues is the error log. The MySQL server uses the
error log to record information relevant to the error that is preventing the server from starting. The
error log is located in the data directory specified in your my.ini file. The default data directory
location is C:\mysql\data. See Section 5.10.1, “The Error Log”.
Another source of information regarding possible errors is the console messages displayed when the
MySQL service is starting. Use the NET START mysql command from the command line after
installing mysqld as a service to see any error messages regarding the starting of the MySQL server as a service. See Section 2.3.12, “Starting MySQL as a Windows Service”.
The following are examples of some of the more common error messages you may encounter when
installing MySQL and starting the server for the first time:
•
System error 1067 has occurred.
Fatal error: Can't open privilege tables: Table 'mysql.host' doesn't exist
These messages occur when the MySQL server cannot find the mysql privileges database or
other critical files. This error is often encountered when the MySQL base or data directories are
installed in different locations than the default locations (C:\mysql and C:\mysql\data,
respectively).
One situation when this may occur is when MySQL is upgraded and installed to a new location,
but the configuration file is not updated to reflect the new install location. In addition there may
be old and new configuration files that conflict, be sure to delete or rename any old configuration files when upgrading MySQL.
If you have installed MySQL to a directory other than C:\mysql you need to ensure that the
MySQL server is aware of this through the use of a configuration (my.ini) file. The my.ini
file needs to be located in your Windows directory, typically located at C:\WinNT or
75
Installing MySQL
C:\WINDOWS. You can determine its exact location from the value of the WINDIR environment variable by issuing the following command from the command prompt:
C:\> echo %WINDIR%
An option file can be created and modified with any text editor, such as the Notepad program.
For example, if MySQL is installed at E:\mysql and the data directory is located at
D:\MySQLdata, you can create the option file and set up a [mysqld] section to specify values for the basedir and datadir parameters:
[mysqld]
# set basedir to your installation path
basedir=E:/mysql
# set datadir to the location of your data directory
datadir=D:/MySQLdata
Note that Windows pathnames are specified in option files using forward slashes rather than
backslashes. If you do use backslashes, you must double them:
[mysqld]
# set basedir to your installation path
basedir=C:\\Program Files\\mysql
# set datadir to the location of your data directory
datadir=D:\\MySQLdata
If you change the datadir value in your MySQL configuration file, you must move the contents of the existing MySQL data directory before restarting the MySQL server.
See Section 2.3.8, “Creating an Option File”.
•
Error: Cannot create Windows service for MySql. Error: 0
This error is encountered when you re-install or upgrade MySQL without first stopping and removing the existing MySQL service and install MySQL using the MySQL Configuration Wizard. This happens because when the Configuration Wizard tries to install the service it finds an
existing service with the same name.
One solution to this problem is to choose a service name other than mysql when using the configuration wizard. This will allow the new service to be installed correctly, but leaves the outdated service in place. While this is harmless it is best to remove old services that are no longer
in use.
To permanently remove the old mysql service, execute the following command as a user with
administrative privileges, on the command-line:
C:\>sc delete mysql
[SC] DeleteService SUCCESS
If the sc utility is not available for your version of Windows, download the delsrv utility
from http://www.microsoft.com/windows2000/techinfo/reskit/tools/existing/delsrv-o.asp and
use the delsrv mysql syntax.
2.3.15. Upgrading MySQL on Windows
This section lists some of the steps you should take when upgrading MySQL on Windows.
1.
You should always back up your current MySQL installation before performing an upgrade.
76
Installing MySQL
See Section 5.8.1, “Database Backups”.
2.
Download the latest Windows distribution of MySQL from http://dev.mysql.com.
3.
Before upgrading MySQL, you must stop the server.
If the server is installed as a service, stop the service with the following command from the
command prompt:
C:\> NET STOP MySQL
If you are not running the MySQL server as a service, use the following command to stop the
server:
C:\> C:\mysql\bin\mysqladmin -u root shutdown
4.
When upgrading to MySQL 4.1.5 or higher from a previous version, or when upgrading from a
version of MySQL installed from a Zip archive to a version of MySQL installed with the
MySQL Installation Wizard, you must manually remove the previous installation and MySQL
service (if the server is installed as a service).
To remove the MySQL service, use the following command:
C:\> C:\mysql\bin\mysqld --remove
If you do not remove the existing service, the MySQL Installation Wizard may fail to
properly install the new MySQL service.
5.
If you are using the MySQL Installation Wizard, start the wizard as described in Section 2.3.4,
“Using the MySQL Installation Wizard”.
6.
If you are installing MySQL from a Zip archive, extract the archive. You may either overwrite
your existing MySQL installation (usually located at C:\mysql), or install it into a different
directory, such as C:\mysql4. Overwriting the existing installation is recommended.
7.
Restart the server. For example, use NET START MySQL if you run MySQL as a service, or
invoke mysqld directly otherwise.
8.
Refer to Section 2.10, “Upgrading MySQL” for additional information on upgrading MySQL
that is not specific to Windows.
9.
If you encounter errors, see Section 2.3.14, “Troubleshooting a MySQL Installation Under
Windows”.
2.3.16. MySQL on Windows Compared to MySQL on
Unix
MySQL for Windows has proven itself to be very stable. The Windows version of MySQL has the
same features as the corresponding Unix version, with the following exceptions:
•
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.
•
Limited number of ports
77
Installing MySQL
Windows systems have about 4,000 ports available for client connections, and after a connection
on a port closes, it takes two to four minutes before the port can be reused. In situations where
clients connect to and disconnect from the server at a high rate, it is possible for all available
ports to be used up before closed ports become available again. If this happens, the MySQL
server appears to be unresponsive even though it is running. Note that ports may be used by other applications running on the machine as well, in which case the number of ports available to
MySQL is lower.
For more information, see http://support.microsoft.com/default.aspx?scid=kb;en-us;196271.
•
Concurrent reads
MySQL depends on the pread() and pwrite() calls to be able to mix INSERT and SELECT. Currently we use mutexes to emulate pread()/pwrite(). We will, in the long run,
replace the file level interface with a virtual interface so that we can use the
readfile()/writefile() interface on NT, 2000, and XP to get more speed. The current
implementation limits the number of open files MySQL can use to 2,048 (1,024 before MySQL
4.0.19), which means that you cannot run as many concurrent threads on NT, 2000, XP, and
2003 as on Unix.
•
Blocking read
MySQL uses a blocking read for each connection, which has the following implications if
named pipe connections are enabled:
•
A connection is not disconnected automatically after eight hours, as happens with the Unix
version of MySQL.
•
If a connection hangs, it's impossible to break it without killing MySQL.
•
mysqladmin kill does 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.
•
ALTER TABLE
While you are executing an ALTER TABLE statement, the table is locked from being used by
other threads. This has to do with the fact that on Windows, you can't delete a file that is in use
by another thread. In the future, we may find some way to work around this problem.
•
DROP TABLE
DROP TABLE on a table that is in use by a MERGE table does not work on Windows because
the MERGE handler does the table mapping hidden from the upper layer of MySQL. Because
Windows doesn't allow you to drop files that are open, you first must flush all MERGE tables
(with FLUSH TABLES) or drop the MERGE table before dropping the table. We will fix this at
the same time we introduce views.
•
DATA DIRECTORY and INDEX DIRECTORY
The DATA DIRECTORY and INDEX DIRECTORY options for CREATE TABLE are ignored
on Windows, because Windows doesn't support symbolic links. These options also are ignored
on systems that have a non-functional realpath() call.
•
DROP DATABASE
You cannot drop a database that is in use by some thread.
•
Killing MySQL from the Task Manager
You cannot kill MySQL from the Task Manager or with the shutdown utility in Windows 95.
78
Installing MySQL
You must stop it with mysqladmin shutdown.
•
Case-insensitive names
Filenames are not case sensitive on Windows, so MySQL database and table names are also not
case sensitive on Windows. The only restriction is that database and table names must be specified using the same case throughout a given statement. See Section 9.2.2, “Identifier Case
Sensitivity”.
•
The ‘\’ pathname separator character
Pathname components in Windows 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 do not work reliably from the Windows command-line prompt. If the pipe includes the
character ^Z / CHAR(24), Windows thinks it has encountered end-of-file and aborts the program.
This is mainly a problem when you try to apply a binary log as follows:
C:\> mysqlbinlog binary-log-name | mysql --user=root
If you have a problem applying the log and suspect that it is because of a ^Z / CHAR(24) character, you can use the following workaround:
C:\> mysqlbinlog binary-log-file --result-file=/tmp/bin.sql
C:\> mysql --user=root --execute "source /tmp/bin.sql"
The latter command also can be used to reliably read in any SQL file that may contain binary
data.
•
Access denied for user error
If you attempt to run a MySQL client program to connect to a server running on the same machine, but get the error Access denied for user 'some-user'@'unknown' to
database 'mysql', this means that MySQL cannot resolve your hostname properly.
To fix this, you should create a file named \windows\hosts containing the following information:
127.0.0.1
localhost
Here are some open issues for anyone who might want to help us improve MySQL on Windows:
•
Add macros to use the faster thread-safe increment/decrement methods provided by Windows.
79
Installing MySQL
2.4. 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. To obtain RPM packages, see Section 2.1.3, “How to Get
MySQL”.
MySQL AB does provide some platform-specific RPMs; the difference between a platform-specific
RPM and a generic RPM is that the platform-specific RPMs are built on the targeted platform and
are linked dynamically whereas the generic RPM is linked statically with LinuxThreads.
Note: RPM distributions of MySQL often are provided by other vendors. Be aware that they may
differ in features and capabilities from those built by MySQL AB, and that the instructions in this
manual do not necessarily apply to installing them. The vendor's instructions should be consulted instead.
If you have problems with an RPM file (for example, if you receive the error “Sorry, the
host 'xxxx' could not be looked up”), see Section 2.12.1.2, “Linux Binary Distribution Notes”.
In most cases, you only need to install the MySQL-server and MySQL-client packages to get
a functional MySQL installation. The other packages are not required for a standard installation. If
you want to run a MySQL-Max server that has additional capabilities, you should also install the
MySQL-Max RPM. However, you should do so only after installing the MySQL-server RPM.
See Section 5.1.2, “The mysqld-max Extended MySQL Server”.
If you get a dependency failure when trying to install the MySQL 4.0 packages (for example, “error: removing these packages would break dependencies: libmysqlclient.so.10 is needed by ...”), you should also install the package MySQLshared-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, MySQLshared), 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 MySQLshared-compat package instead.
The following RPM packages are available:
•
MySQL-server-VERSION.i386.rpm
The MySQL server. You need this unless you only want to connect to a MySQL server running
on another machine. Note: Server RPM files were called MySQL-VERSION.i386.rpm before MySQL 4.0.10. That is, they did not have -server in the name.
•
MySQL-Max-VERSION.i386.rpm
The MySQL-Max server. This server has additional capabilities that the one provided in the
MySQL-server RPM does not. You must install the MySQL-server RPM first, because the
MySQL-Max RPM depends on it.
•
MySQL-client-VERSION.i386.rpm
The standard MySQL client programs. You probably always want to install this package.
•
MySQL-bench-VERSION.i386.rpm
Tests and benchmarks. Requires Perl and the DBD::mysql module.
80
Installing MySQL
•
MySQL-devel-VERSION.i386.rpm
The libraries and include files that are needed if you want to compile other MySQL clients, such
as the Perl modules.
•
MySQL-shared-VERSION.i386.rpm
This package contains the shared libraries (libmysqlclient.so*) that certain languages
and applications need to dynamically load and use MySQL.
•
MySQL-shared-compat-VERSION.i386.rpm
This package includes the shared libraries for both MySQL 3.23 and MySQL 4.0. Install this
package instead of MySQL-shared if you have applications installed that are dynamically
linked against MySQL 3.23 but you want to upgrade to MySQL 4.0 without breaking the library
dependencies. This package has been available since MySQL 4.0.13.
•
MySQL-embedded-VERSION.i386.rpm
The embedded MySQL server library (from MySQL 4.0).
•
MySQL-VERSION.src.rpm
This contains the source code for all of the previous packages. It can also be used to rebuild the
RPMs on other architectures (for example, Alpha or SPARC).
To see all files in an RPM package (for example, a MySQL-server RPM), run:
shell> rpm -qpl MySQL-server-VERSION.i386.rpm
To perform a standard minimal installation, run:
shell> rpm -i MySQL-server-VERSION.i386.rpm
shell> rpm -i MySQL-client-VERSION.i386.rpm
To install just the client package, run:
shell> rpm -i MySQL-client-VERSION.i386.rpm
RPM provides a feature to verify the integrity and authenticity of packages before installing them. If
you would like to learn more about this feature, see Section 2.1.4, “Verifying Package Integrity Using MD5 Checksums or GnuPG”.
The server RPM places data under the /var/lib/mysql directory. The RPM also creates a login
account for a user named mysql (if one does not exist) to use for running the MySQL server, and
creates the appropriate entries in /etc/init.d/ to start the server automatically at boot time.
(This means that if you have performed a previous installation and have made changes to its startup
script, you may want to make a copy of the script so that you don't lose it when you install a newer
RPM.) See Section 2.9.2.2, “Starting and Stopping MySQL Automatically” for more information on
how MySQL can be started automatically on system startup.
If you want to install the MySQL RPM on older Linux distributions that do not support initialization
scripts in /etc/init.d (directly or via a symlink), you should create a symbolic link that points
to the location where your initialization scripts actually are installed. For example, if that location is
/etc/rc.d/init.d, use these commands before installing the RPM to create /etc/init.d
as a symbolic link that points there:
shell> cd /etc
shell> ln -s rc.d/init.d .
81
Installing MySQL
However, all current major Linux distributions should support the new directory layout that uses /
etc/init.d, because it is required for LSB (Linux Standard Base) compliance.
If the RPM files that you install include MySQL-server, the mysqld server should be up and
running after installation. You should be able to start using MySQL.
If something goes wrong, you can find more information in the binary installation section. See Section 2.7, “Installing MySQL on Other Unix-Like Systems”.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After
starting the server, you should set up passwords for them using the instructions in Section 2.9,
“Post-Installation Setup and Testing”.
2.5. Installing MySQL on Mac OS X
Beginning with MySQL 4.0.11, you can install MySQL on Mac OS X 10.2.x (“Jaguar”) and up using a Mac OS X binary package in PKG format instead of the binary tarball distribution. Please note
that older versions of Mac OS X (for example, 10.1.x) are not supported by this package.
The package is located inside a disk image (.dmg) file that you first need to mount by doubleclicking its icon in the Finder. It should then mount the image and display its contents.
To obtain MySQL, see Section 2.1.3, “How to Get MySQL”.
Note: Before proceeding with the installation, be sure to shut down all running MySQL server instances by either using the MySQL Manager Application (on Mac OS X Server) or via mysqladmin shutdown on the command line.
To actually install the MySQL PKG file, double-click on the package icon. This launches the Mac
OS X Package Installer, which guides you through the installation of MySQL.
Due to a bug in the Mac OS X package installer, you may see this error message in the destination
disk selection dialog:
You cannot install this software on this disk. (null)
If this error occurs, simply click the Go Back button once to return to the previous screen. Then
click Continue to advance to the destination disk selection again, and you should be able to
choose the destination disk correctly. We have reported this bug to Apple and it is investigating this
problem.
The Mac OS X PKG of MySQL installs itself into /usr/local/mysql-VERSION and also installs a symbolic link, /usr/local/mysql, pointing to the new location. If a directory named /
usr/local/mysql exists, it is renamed to /usr/local/mysql.bak first. Additionally, the
installer creates the grant tables in the mysql database by executing mysql_install_db after
the installation.
The installation layout is similar to that of a tar file binary distribution; all MySQL binaries are
located in the directory /usr/local/mysql/bin. The MySQL socket file is created as /
tmp/mysql.sock by default. See Section 2.1.5, “Installation Layouts”.
MySQL installation requires a Mac OS X user account named mysql. A user account with this
name should exist by default on Mac OS X 10.2 and up.
If you are running Mac OS X Server, you have a version of MySQL installed. The versions of
MySQL that ship with Mac OS X Server versions are shown in the following table:
Mac OS X Server Version
MySQL Version
10.2-10.2.2
3.23.51
10.2.3-10.2.6
3.23.53
82
Installing MySQL
10.3
4.0.14
10.3.2
4.0.16
10.4.0
4.1.10a
This manual section covers the installation of the official MySQL Mac OS X PKG only. Make sure
to read Apple's help information about installing MySQL: Run the “Help View” application, select
“Mac OS X Server” help, do a search for “MySQL,” and read the item entitled “Installing MySQL.”
For pre-installed versions of MySQL on Mac OS X Server, note especially that you should start
mysqld with safe_mysqld instead of mysqld_safe if MySQL is older than version 4.0.
If you previously used Marc Liyanage's MySQL packages for Mac OS X from http://www.entropy.ch, you can simply follow the update instructions for packages using the binary
installation layout as given on his pages.
If you are upgrading from Marc's 3.23.xx versions or from the Mac OS X Server version of MySQL
to the official MySQL PKG, you also need to convert the existing MySQL privilege tables to the
current format, because some new security privileges have been added. See Section 2.10.8,
“Upgrading the Grant Tables”.
If you would like to automatically start up MySQL during system startup, you also need to install
the MySQL Startup Item. Starting with MySQL 4.0.15, it is part of the Mac OS X installation disk
images as a separate installation package. Simply double-click the MySQLStartupItem.pkg
icon and follow the instructions to install it.
Note that the Startup Item need be installed only once! There is no need to install it each time you
upgrade the MySQL package later.
The Startup Item is installed into /Library/StartupItems/MySQLCOM. (Before MySQL
4.1.2, the location was /Library/StartupItems/MySQL, but that collided with the MySQL
Startup Item installed by Mac OS X Server.) Startup Item installation adds a variable MYSQLCOM=-YES- to the system configuration file /etc/hostconfig. If you would like to disable
the automatic startup of MySQL, simply change this variable to MYSQLCOM=-NO-.
On Mac OS X Server, the default MySQL installation uses the variable MYSQL in the /
etc/hostconfig file. The MySQL AB Startup Item installer disables this variable by setting it
to MYSQL=-NO-. This avoids boot time conflicts with the MYSQLCOM variable used by the MySQL
AB Startup Item. However, it does not shut down a running MySQL server. You should do that
yourself.
After the installation, you can start up MySQL by running the following commands in a terminal
window. You must have administrator privileges to perform this task.
If you have installed the Startup Item:
shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM start
(Enter your password, if necessary)
(Press Control-D or enter "exit" to exit the shell)
For
versions
of
MySQL
older
rary/StartupItems/MySQLCOM/MySQLCOM
rary/StartupItems/MySQL/MySQL above.
than
4.1.3,
with
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)
83
substitute
/Lib/Lib-
Installing MySQL
You should be able to connect to the MySQL server, for example, by running /
usr/local/mysql/bin/mysql.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After
starting the server, you should set up passwords for them using the instructions in Section 2.9,
“Post-Installation Setup and Testing”.
You might want to add aliases to your shell's resource file to make it easier to access commonly
used programs such as mysql and mysqladmin from the command line. The syntax for tcsh is:
alias mysql /usr/local/mysql/bin/mysql
alias mysqladmin /usr/local/mysql/bin/mysqladmin
For bash, use:
alias mysql=/usr/local/mysql/bin/mysql
alias mysqladmin=/usr/local/mysql/bin/mysqladmin
Even better, add /usr/local/mysql/bin to your PATH environment variable. For example,
add the following line to your $HOME/.tcshrc file if your shell is tcsh:
setenv PATH ${PATH}:/usr/local/mysql/bin
If no .tcshrc file exists in your home directory, create it with a text editor.
If you are upgrading an existing installation, please note that installing a new MySQL PKG does not
remove the directory of an older installation. Unfortunately, the Mac OS X Installer does not yet offer the functionality required to properly upgrade previously installed packages.
To use your existing databases with the new installation, you'll need to copy the contents of the old
data directory to the new data directory. Make sure that neither the old server nor the new one is
running when you do this. After you have copied over the MySQL database files from the previous
installation and have successfully started the new server, you should consider removing the old installation files to save disk space. Additionally, you should also remove older versions of the Package Receipt directories located in /Library/Receipts/mysql-VERSION.pkg.
2.6. Installing MySQL on NetWare
Porting MySQL to NetWare was an effort spearheaded by Novell. Novell customers should be
pleased to note that NetWare 6.5 ships with bundled MySQL binaries, complete with an automatic
commercial use license for all servers running that version of NetWare.
MySQL for NetWare is compiled using a combination of Metrowerks CodeWarrior for
NetWare and special cross-compilation versions of the GNU autotools.
The latest binary packages for NetWare can be obtained at http://dev.mysql.com/downloads/. See
Section 2.1.3, “How to Get MySQL”.
In order to host MySQL, the NetWare server must meet these requirements:
•
Latest Support Pack of NetWare 6.5 [http://support.novell.com/filefinder/18197/index.html] or
NetWare 6.0 [http://support.novell.com/filefinder/13659/index.html] installed.
•
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.
84
Installing MySQL
To install MySQL for NetWare, use the following procedure:
1.
If you are upgrading from a prior installation, stop the MySQL server. This is done from the
server console, using the following command:
SERVER:
mysqladmin -u root shutdown
2.
Log on to the target server from a client machine with access to the location where you are installing MySQL.
3.
Extract the binary package Zip file onto the server. Be sure to allow the paths in the Zip file to
be used. It is safe to simply extract the file to SYS:\.
If you are upgrading from a prior installation, you may need to copy the data directory (for example, SYS:MYSQL\DATA), as well as my.cnf, if you have customized it. You can then delete the old copy of MySQL.
4.
You might want to rename the directory to something more consistent and easy to use. The examples iin this manual use SYS:MYSQL to refer to the installation directory.
Note that MySQL installation on NetWare does not detect if a version of MySQL is already installed outside the NetWare release. Therefore, if you have installed the latest MySQL version
from the Web (for example, MySQL 4.1 or later) in SYS:\MYSQL, you must rename the
folder before upgrading the NetWare server; otherwise, files in SYS:\MySQL are overwritten
by the MySQL version present in NetWare Support Pack.
5.
At the server console, add a search path for the directory containing the MySQL NLMs. For
example:
SERVER:
SEARCH ADD SYS:MYSQL\BIN
6.
Initialize the data directory and the
mysql_install_db at the server console.
grant
tables,
if
needed,
by
executing
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 running MySQL on NetWare 6.0, we strongly suggest that you use the -skip-external-locking option on the command line:
#Starts the MySQL 4.0.x database server
SEARCH ADD SYS:MYSQL\BIN
MYSQLD_SAFE --skip-external-locking
It is also necessary to use CHECK TABLE and REPAIR TABLE instead of myisamchk, because myisamchk makes use of external locking. External locking is known to have problems
on NetWare 6.0; the problem has been eliminated in NetWare 6.5.
mysqld_safe on NetWare provides a screen presence. When you unload (shut down) the
mysqld_safe NLM, the screen does not by default go away. Instead, it prompts for user input:
*<NLM has terminated; Press any key to close the screen>*
85
Installing MySQL
If you want NetWare to close the screen automatically instead, use the --autoclose option
to mysqld_safe. For example:
#Starts the MySQL 4.0.x database server
SEARCH ADD SYS:MYSQL\BIN
MYSQLD_SAFE --autoclose
9.
When installing MySQL version 4.1.x or later either for the first time or upgrading the 4.0.x
version to 4.1.x or later, download and install the latest and appropriate Perl module and PHP
extension:
•
Perl for NetWare: http://forge.novell.com/modules/xfcontent/downloads.php/perl/Modules/
•
PHP for NetWare: http://forge.novell.com/modules/xfcontent/downloads.php/php/Modules/
The behavior of mysqld_safe on NetWare is described further in Section 5.1.3, “mysqld_safe —
MySQL Server Startup Script”.
If there was an existing installation of MySQL on the server, be sure to check for existing MySQL
startup commands in autoexec.ncf, and edit or delete them as necessary.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After
starting the server, you should set up passwords for them using the instructions in Section 2.9,
“Post-Installation Setup and Testing”.
2.7. Installing MySQL on Other Unix-Like Systems
This section covers the installation of MySQL binary distributions that are provided for various platforms in the form of compressed tar files (files with a .tar.gz extension). See Section 2.1.2.5,
“MySQL Binaries Compiled by MySQL AB” for a detailed list.
To obtain MySQL, see Section 2.1.3, “How to Get MySQL”.
MySQL tar file binary distributions have names of the form mysql-VERSION-OS.tar.gz,
where VERSION is a number (for example, 4.0.17), and OS indicates the type of operating system for which the distribution is intended (for example, pc-linux-i686).
In addition to these generic packages, we also offer binaries in platform-specific package formats
for selected platforms. See Section 2.2, “Standard MySQL Installation Using a Binary Distribution”
for more information on how to install these.
You need the following tools to install a MySQL tar file binary distribution:
•
GNU gunzip to uncompress the distribution.
•
A reasonable tar to unpack the distribution. GNU tar is known to work. Some operating systems come with a pre-installed version of tar that is known to have problems. For example,
Mac OS X tar and Sun tar are known to have problems with long filenames. On Mac OS X,
you can use the pre-installed gnutar program. On other systems with a deficient tar, you
should install GNU tar first.
If you run into problems, please always use mysqlbug when posting questions to a MySQL mailing list. Even if the problem isn't a bug, mysqlbug gathers system information that helps others
solve your problem. By not using mysqlbug, you lessen the likelihood of getting a solution to your
86
Installing MySQL
problem. You can find mysqlbug in the bin directory after you unpack the distribution. See Section 1.7.1.3, “How to Report Bugs or Problems”.
The basic commands you must execute to install and use a MySQL binary distribution are:
shell>
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 --user=mysql
chown -R root .
chown -R mysql data
chgrp -R mysql .
bin/mysqld_safe --user=mysql &
For versions of MySQL older than 4.0, substitute bin/safe_mysqld for bin/mysqld_safe
in the final command.
Note: This procedure does not set up any passwords for MySQL accounts. After following the procedure, proceed to Section 2.9, “Post-Installation Setup and Testing”.
A more detailed version of the preceding description for installing a binary distribution follows:
1.
Add a login 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 might want to call the user and group something else instead of mysql. If so, substitute
the appropriate name in the following steps.
2.
Pick the directory under which you want to unpack the distribution, and change location into it.
In the following example, we unpack the distribution under /usr/local. (The instructions,
therefore, assume that you have permission to create files and directories in /usr/local. If
that directory is protected, you need to perform the installation as root.)
shell> cd /usr/local
3.
Obtain a distribution file from one of the sites listed in Section 2.1.3, “How to Get MySQL”.
For a given release, binary distributions for all platforms are built from the same MySQL
source distribution.
4.
Unpack the distribution, which creates the installation directory. Then create a symbolic link to
that directory:
shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf shell> ln -s full-path-to-mysql-VERSION-OS mysql
The tar command creates a directory named mysql-VERSION-OS. The ln command
makes a symbolic link to that directory. This lets you refer more easily to the installation directory as /usr/local/mysql.
With GNU tar, no separate invocation of gunzip is necessary. You can replace the first line
with the following alternative command to uncompress and extract the distribution:
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
87
Installing MySQL
5.
Change location into the installation directory:
shell> cd mysql
You can find several files and subdirectories in the mysql directory. The most important for
installation purposes are the bin and scripts subdirectories.
•
bin
This directory contains client programs and the server. You should add the full pathname of
this directory to your PATH environment variable so that your shell finds the MySQL programs properly. See Appendix G, Environment Variables.
•
scripts
This directory contains the mysql_install_db script used to initialize the mysql
database containing the grant tables that store the server access permissions.
6.
If you haven't installed MySQL before, you must create the MySQL grant tables:
shell> scripts/mysql_install_db --user=mysql
If you run the command as root, you should use the --user option as shown. The value of
the option should be the name of the login account that you created in the first step to use for
running the server. If you run the command while logged in as that user, you can omit the -user option.
Note that for MySQL versions older than 3.22.10, mysql_install_db left the server running after creating the grant tables. This is no longer true; you need to restart the server after
performing the remaining steps in this procedure.
7.
Change the ownership of program binaries to root and ownership of the data directory to the
user that you run mysqld as. Assuming that you are located in the installation directory (/
usr/local/mysql), the commands look like this:
shell> chown -R root .
shell> chown -R mysql data
shell> chgrp -R mysql .
The first command changes the owner attribute of the files to the root user. The second
changes the owner attribute of the data directory to the mysql user. The third changes the
group attribute to the mysql group.
8.
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.9.2.2, “Starting and Stopping MySQL Automatically”.
9.
You can set up new accounts using the bin/mysql_setpermission script if you install
the DBI and DBD::mysql Perl modules. For instructions, see Section 2.13, “Perl Installation
Notes”.
10. 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';
88
# path to mysql executable
Installing MySQL
Change the path to reflect the location where mysql actually is stored on your system. If you
do not do this, you get a Broken pipe error when you run mysqlaccess.
After everything has been unpacked and installed, you should test your distribution.
You can start the MySQL server with the following command:
shell> bin/mysqld_safe --user=mysql &
For versions of MySQL older than 4.0, substitute bin/safe_mysqld for bin/mysqld_safe
in the command.
More information about mysqld_safe is given in Section 5.1.3, “mysqld_safe — MySQL Server
Startup Script”.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After
starting the server, you should set up passwords for them using the instructions in Section 2.9,
“Post-Installation Setup and Testing”.
2.8. MySQL Installation Using a Source Distribution
Before you proceed with the source installation, check first to see whether our binary is available for
your platform and whether it works for you. We put a lot of effort into making sure that our binaries
are built with the best possible options.
To obtain a source distribution for MySQL, Section 2.1.3, “How to Get MySQL”.
MySQL source distributions are provided as compressed tar archives and have names of the form
mysql-VERSION.tar.gz, where VERSION is a number like 5.0.6-beta.
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 operating systems come with a pre-installed version of tar that is known to have problems. For example,
Mac OS X tar and Sun tar are known to have problems with long filenames. On Mac OS X,
you can use the pre-installed gnutar program. On other systems with a deficient tar, you
should install GNU tar first.
•
A working ANSI C++ compiler. gcc 2.95.2 or later, egcs 1.0.2 or later or egcs 2.91.66,
SGI C++, and SunPro C++ are some of the compilers that are known to work. libg++ is not
needed when using gcc. gcc 2.7.x has a bug that makes it impossible to compile some perfectly legal C++ files, such as sql/sql_base.cc. If you have only gcc 2.7.x, you must upgrade your gcc to be able to compile MySQL. gcc 2.8.1 is also known to have problems on
some platforms, so it should be avoided if a new compiler exists for the platform.
gcc 2.95.2 or later is recommended when compiling MySQL 3.23.x.
•
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 version of gcc recent enough to understand the -fno-exceptions option, it
is very important that you use this option. Otherwise, you may compile a binary that crashes randomly. We also recommend that you use -felide-constructors and -fno-rtti along
with -fno-exceptions. When in doubt, do the following:
89
Installing MySQL
CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors \
-fno-exceptions -fno-rtti" ./configure \
--prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static
On most systems, this gives you a fast and stable binary.
If you run into problems, please always use mysqlbug when posting questions to a MySQL mailing list. Even if the problem isn't a bug, mysqlbug gathers system information that helps others
solve your problem. By not using mysqlbug, you lessen the likelihood of getting a solution to your
problem. You can find mysqlbug in the scripts directory after you unpack the distribution. See
Section 1.7.1.3, “How to Report Bugs or Problems”.
2.8.1. Source Installation Overview
The basic commands you must execute to install a MySQL source distribution are:
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
groupadd mysql
useradd -g mysql mysql
gunzip < mysql-VERSION.tar.gz | tar -xvf cd mysql-VERSION
./configure --prefix=/usr/local/mysql
make
make install
cp support-files/my-medium.cnf /etc/my.cnf
cd /usr/local/mysql
bin/mysql_install_db --user=mysql
chown -R root .
chown -R mysql var
chgrp -R mysql .
bin/mysqld_safe --user=mysql &
For versions of MySQL older than 4.0, substitute bin/safe_mysqld for bin/mysqld_safe
in the final command.
If you start from a source RPM, do the following:
shell> rpmbuild --rebuild --clean MySQL-VERSION.src.rpm
This makes a binary RPM that you can install. For older versions of RPM, you may have to replace
the command rpmbuild with rpm instead.
Note: This procedure does not set up any passwords for MySQL accounts. After following the procedure, proceed to Section 2.9, “Post-Installation Setup and Testing”, for post-installation setup and
testing.
A more detailed version of the preceding description for installing MySQL from a source distribution follows:
1.
Add a login 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 might want to call the user and group something else instead of mysql. If so, substitute
the appropriate name in the following steps.
90
Installing MySQL
2.
Pick the directory under which you want to unpack the distribution, and change location into it.
3.
Obtain a distribution file from one of the sites listed in Section 2.1.3, “How to Get MySQL”.
4.
Unpack the distribution into the current directory:
shell> gunzip < /path/to/mysql-VERSION.tar.gz | tar xvf This command creates a directory named mysql-VERSION.
With GNU tar, no separate invocation of gunzip is necessary. You can use the following alternative command to uncompress and extract the distribution:
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
5.
Change location into the top-level directory of the unpacked distribution:
shell> cd mysql-VERSION
Note that currently you must configure and build MySQL from this top-level directory. You
cannot build it in a different directory.
6.
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.8.2, “Typical configure Options”, discusses some of
the more useful options.
If configure fails and you are going to send mail to a MySQL mailing list to ask for assistance, please include any lines from config.log that you think can help solve the problem.
Also include the last couple of lines of output from configure. Post the bug report using the
mysqlbug script. See Section 1.7.1.3, “How to Report Bugs or Problems”.
If the compile fails, see Section 2.8.4, “Dealing with Problems Compiling MySQL” for help.
7.
Install the distribution:
shell> make install
If you want to set up an option file, use one of those present in the support-files directory as a template. For example:
shell> cp support-files/my-medium.cnf /etc/my.cnf
You might need to run these commands as root.
If you want to configure support for InnoDB tables, you should edit the /etc/my.cnf file,
remove the # character before the option lines that start with innodb_..., and modify the
option values to be what you want. See Section 4.3.2, “Using Option Files” and Section 15.4,
“InnoDB Configuration”.
8.
Change location into the installation directory:
shell> cd /usr/local/mysql
9.
If you haven't installed MySQL before, you must create the MySQL grant tables:
91
Installing MySQL
shell> bin/mysql_install_db --user=mysql
If you run the command as root, you should use the --user option as shown. The value of
the option should be the name of the login account that you created in the first step to use for
running the server. If you run the command while logged in as that user, you can omit the -user option.
Note that for MySQL versions older than 3.22.10, mysql_install_db left the server running after creating the grant tables. This is no longer true; you need to restart the server after
performing the remaining steps in this procedure.
10. Change the ownership of program binaries to root and ownership of the data directory to the
user that you run mysqld as. Assuming that you are located in the installation directory (/
usr/local/mysql), the commands look like this:
shell> chown -R root .
shell> chown -R mysql var
shell> chgrp -R mysql .
The first command changes the owner attribute of the files to the root user. The second
changes the owner attribute of the data directory to the mysql user. The third changes the
group attribute to the mysql group.
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.9.2.2, “Starting and Stopping MySQL Automatically”.
12. You can set up new accounts using the bin/mysql_setpermission script if you install
the DBI and DBD::mysql Perl modules. For instructions, see Section 2.13, “Perl Installation
Notes”.
After everything has been installed, you should initialize and test your distribution using this command:
shell> /usr/local/mysql/bin/mysqld_safe --user=mysql &
For versions of MySQL older than 4.0, substitute safe_mysqld for mysqld_safe in the command.
If that command fails immediately and prints mysqld ended, you can find some information in
the host_name.err file in the data directory.
More information about mysqld_safe is given in Section 5.1.3, “mysqld_safe — MySQL Server
Startup Script”.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After
starting the server, you should set up passwords for them using the instructions in Section 2.9,
“Post-Installation Setup and Testing”.
2.8.2. Typical configure Options
The configure script gives you a great deal of control over how you configure a MySQL source
distribution. Typically you do this using options on the configure command line. You can also
affect configure using certain environment variables. See Appendix G, Environment Variables.
For a list of options supported by configure, run this command:
shell> ./configure --help
92
Installing MySQL
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 cannot be compiled (it is the one client program that
requires C++). In this case, you can remove the code in configure that tests for the C++ compiler and then run ./configure with the --without-server option. The compile step
should still try to build mysql, but you can ignore any warnings about mysql.cc. (If make
stops, try make -k to tell it to continue with the rest of the build even if errors occur.)
•
If you want to build the embedded MySQL library (libmysqld.a) you should use the -with-embedded-server option.
•
If you don't want your log files and database directories located under /usr/local/var, use
a configure command something like one of these:
shell> ./configure --prefix=/usr/local/mysql
shell> ./configure --prefix=/usr/local \
--localstatedir=/usr/local/mysql/data
The first command changes the installation prefix so that everything is installed under /
usr/local/mysql rather than the default of /usr/local. The second command preserves
the default installation prefix, but overrides the default location for database directories
(normally /usr/local/var) and changes it to /usr/local/mysql/data. After you
have compiled MySQL, you can change these options with option files. See Section 4.3.2,
“Using Option Files”.
•
If you are using Unix and you want the MySQL socket located somewhere other than the default
location (normally in the directory /tmp or /var/run), use a configure command like
this:
shell> ./configure \
--with-unix-socket-path=/usr/local/mysql/tmp/mysql.sock
The socket filename must be an absolute pathname. You can also change the location of
mysql.sock later by using a MySQL option file. See Section A.4.5, “How to Protect or
Change the MySQL Socket File /tmp/mysql.sock”.
•
If you want to compile statically linked programs (for example, to make a binary distribution, to
get more speed, or to work around problems with some Red Hat Linux distributions), run configure like this:
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 does not attempt to link in libg++ or libstdc++. This may be a good idea to do even if you have these libraries installed, because some
versions of them have caused strange problems for MySQL users in the past.
The following list indicates some compilers and environment variable settings that are commonly used with each one.
93
Installing MySQL
•
gcc 2.7.2:
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors"
•
egcs 1.0.3a:
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors \
-fno-exceptions -fno-rtti"
•
gcc 2.95.2:
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
-felide-constructors -fno-exceptions -fno-rtti"
•
pgcc 2.90.29 or newer:
CFLAGS="-O3 -mpentiumpro -mstack-align-double" CXX=gcc \
CXXFLAGS="-O3 -mpentiumpro -mstack-align-double \
-felide-constructors -fno-exceptions -fno-rtti"
In most cases, you can get a reasonably optimized MySQL binary by using the options from the
preceding list and adding the following options to the configure line:
--prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static
The full configure line would, in other words, be something like the following for all recent
gcc versions:
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
-felide-constructors -fno-exceptions -fno-rtti" ./configure \
--prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static
The binaries we provide on the MySQL Web site at http://www.mysql.com/ are all compiled
with full optimization and should be perfect for most users. See Section 2.1.2.5, “MySQL Binaries Compiled by MySQL AB”. There are some configuration settings you can tweak to make an
even faster binary, but these are only for advanced users. See Section 7.5.4, “How Compiling
and Linking Affects the Speed of MySQL”.
If the build fails and produces errors about your compiler or linker not being able to create the
shared library libmysqlclient.so.N (where N is a version number), you can work around
this problem by giving the --disable-shared option to configure. In this case, configure does not build a shared libmysqlclient.so.N library.
•
By default, MySQL uses the latin1 (cp1252) character set. To change the default set, use the
--with-charset option:
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 5.9.1, “The
Character Set Used for Data and Sorting”.
As of MySQL 4.1.1, the default collation may also be specified. MySQL uses the latin1_swedish_ci collation. To change this, use the --with-collation option:
94
Installing MySQL
shell> ./configure --with-collation=COLLATION
To change both the character set and the collation, use both the --with-charset and -with-collation options. The collation must be a legal collation for the character set. (Use
the SHOW COLLATION statement to determine which collations are available for each character
set.)
If you want to convert characters between the server and the client, you should take a look at the
SET CHARACTER SET statement. See Section 13.5.3, “SET Syntax”.
Warning: If you change character sets after having created any tables, you have to run myisamchk -r -q --set-character-set=charset on every table. Your indexes may be
sorted incorrectly otherwise. (This can happen if you install MySQL, create some tables, then reconfigure MySQL to use a different character set and reinstall it.)
With the configure option --with-extra-charsets=LIST, you can define which additional character sets should be compiled into the server. LIST is either a list of character set
names separated by spaces, complex to include all character sets that can't be dynamically
loaded, or all to include all character sets into the binaries.
•
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 F.1, “Debugging a MySQL Server”.
•
If your client programs are using threads, you also must compile a thread-safe version of the
MySQL client library with the --enable-thread-safe-client configure option. This
creates a libmysqlclient_r library with which you should link your threaded applications.
See Section 23.2.15, “How to Make a Threaded Client”.
•
It is now possible to build MySQL with big table support using the --with-big-tables option, beginning with the following MySQL versions:
•
4.0 series: 4.0.25
•
4.1 series: 4.1.11
•
5.0 series: 5.0.4
This option causes the variables used to keep table row counts to be stored using unsigned
long long rather than unsigned long. What this does is to allow tables to hold up to approximately 1.844E+19 ((232)2) rows rather than 232 (~4.295E+09) rows. Previously it was necessary to pass -DBIG_TABLES to the compiler manually in order to enable this feature.
•
Options that pertain to particular systems can be found in the system-specific section of this
manual. See Section 2.12, “Operating System-Specific Notes”.
2.8.3. Installing from the Development Source Tree
Caution: You should read this section only if you are interested in helping us test our new code. If
you just want to get MySQL up and running on your system, you should use a standard release distribution (either a binary or source distribution).
To obtain our most recent development source tree, use these instructions:
1.
Download the BitKeeper free client from http://www.bitmover.com/bk-client.shar.
95
Installing MySQL
2.
On Unix, install the free client like this:
shell>
shell>
shell>
shell>
sh bk-client.shar
cd bk_client-1.1
make all
PATH=$PWD:$PATH
On Windows, install it like this:
•
Download and install Cygwin from http://cygwin.com [http://cygwin.com/].
•
Make sure gcc has been installed under Cygwin. You can test this by issuing which
gcc. If it's not installed, run Cygwin's package manager, select gcc, and install it.
•
Under Cygwin, perform these steps:
shell> sh bk-client.shar
shell> cd bk_client-1.1
Then edit the Makefile and change the line that reads $(CC) $(CFLAGS) -o sfio
-lz sfio.c to this:
$(CC) $(CFLAGS) -o sfio sfio.c -lz
Now run the make command and set the path:
shell> make all
shell> PATH=$PWD:$PATH
3.
After the BitKeeper free client has been installed, first go to the directory you want to work
from, and then use one of the following commands to make a local copy of the MySQL version
branch of your choice:
To copy the 3.23 branch, use this command:
shell> sfioball -r+ bk://mysql.bkbits.net/mysql-3.23 mysql-3.23
To copy the 4.0 branch, use this command:
shell> sfioball -r+ bk://mysql.bkbits.net/mysql-4.0 mysql-4.0
To copy the 4.1 branch, use this command:
shell> sfioball -r+ bk://mysql.bkbits.net/mysql-4.1 mysql-4.1
To copy the 5.0 branch, use this command:
shell> sfioball -r+ bk://mysql.bkbits.net/mysql-5.0 mysql-5.0
Normally, you don't have to build the documentation yourself, because we're providing it in
various formats on http://dev.mysql.com/doc/. The formats you can download there (HTML,
PDF, etc.) are being built on a daily basis, so you gain little by creating them yourself from the
DocBook XML base format in the mysqldoc tree. If you would like to copy the documentation repository, anyway, use the following command:
shell> sfioball -r+ bk://mysql.bkbits.net/mysqldoc mysqldoc
96
Installing MySQL
In the preceding examples, the source tree is set up in the mysql-3.23/, mysql-4.0/,
mysql-4.1/, or mysql-5.0/ subdirectory of your current directory.
The initial download of the source tree may take a while, depending on the speed of your connection. Please be patient.
4.
To update the local copy of a repository, use this command (the example is for updating the 5.0
branch):
shell> update bk://mysql.bkbits.net/mysql-5.0 mysql-5.0
5.
You need GNU make, autoconf 2.58 (or newer), automake 1.8, libtool 1.5, and m4 to
run the next set of commands. Even though many operating systems come with their own implementation of make, chances are high that the compilation fails with strange error messages.
Therefore, it is highly recommended that you use GNU make (sometimes named gmake) instead.
Fortunately, a large number of operating systems ship with the GNU toolchain preinstalled or
supply installable packages of these. In any case, they can also be downloaded from the following locations:
•
http://www.gnu.org/software/autoconf/
•
http://www.gnu.org/software/automake/
•
http://www.gnu.org/software/libtool/
•
http://www.gnu.org/software/m4/
•
http://www.gnu.org/software/make/
If you are trying to configure MySQL 4.1 or later, you also need GNU bison 1.75 or later.
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 older
versions of bison.
Versions of MySQL before version 4.1 may also compile with other yacc implementations
(for example, BSD yacc 91.7.30). For later versions, GNU bison is required.
The following example shows the typical commands required to configure a source tree. The
first cd command changes location into the top-level directory of the tree; replace mysql5.0 with the appropriate directory name.
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
cd mysql-5.0
bk -r edit
aclocal; autoheader
libtoolize --automake --force
automake --force --add-missing; autoconf
(cd innobase; aclocal; autoheader; autoconf; automake)
(cd bdb/dist; sh s_all)
./configure # Add your favorite options here
make
Or you can use BUILD/autorun.sh as a shortcut for the following sequence of commands:
shell> aclocal; autoheader
shell> libtoolize --automake --force
shell> automake --force --add-missing; autoconf
97
Installing MySQL
shell> (cd innobase; aclocal; autoheader; autoconf; automake)
shell> (cd bdb/dist; sh s_all)
The command lines that change directory into the innobase and bdb/dist directories are
used to configure the InnoDB and Berkeley DB (BDB) storage engines. You can omit these
command lines if you to not require InnoDB or BDB support.
If you get some strange errors during this stage, verify that you really have libtool installed.
A collection of our standard configuration scripts is located in the BUILD/ subdirectory. You
may find it more convenient to use the BUILD/compile-pentium-debug script than the
preceding set of shell commands. To compile on a different architecture, modify the script by
removing flags that are Pentium-specific.
6.
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.
7.
Play hard with your new installation and try to make the new features crash. Start by running
make test. See Section 25.1.2, “MySQL Test Suite”.
8.
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 that all the necessary tools are installed and that
your PATH variable is set correctly so that your shell can find them.
9.
After the initial copying of the repository (sfioball) to obtain the source tree, you should
update the repository (update) periodically to get updates.
10. You can examine the change history for the tree with all the diffs by viewing the BK/
ChangeLog file in the source tree and looking at the ChangeSet descriptions listed there.
To examine a particular changeset, you would have to use the sfioball command to extract
two particular revisions of the source tree, then use an external diff command to compare
them. If you see some funny diffs or code that you have a question about, do not hesitate to
send email to the MySQL internals mailing list. See Section 1.7.1.1, “The MySQL Mailing Lists”. Also, if you think you have a better idea on how to do something, send an email
message to the same address with a patch.
11. The BitKeeper free client is shipped with its source code. The only documentation available for
the free client is the source code itself.
You can also browse changesets, comments, and source code online. For example, to browse this information for MySQL 5.0, go to http://mysql.bkbits.net:8080/mysql-5.0.
2.8.4. Dealing with Problems Compiling MySQL
All MySQL programs compile cleanly for us with no warnings on Solaris or Linux using gcc. On
other systems, warnings may occur due to differences in system include files. See Section 2.8.5,
“MIT-pthreads Notes” for warnings that may occur when using MIT-pthreads. For other problems,
check the following list.
The solution to many problems involves reconfiguring. If you do need to reconfigure, take note of
the following:
•
If configure is run after it has previously been run, it may use information that was gathered
during its previous invocation. This information is stored in config.cache. When config98
Installing MySQL
ure starts up, it looks for that file and reads its contents if it exists, on the assumption that the
information is still correct. That assumption is invalid when you reconfigure.
•
Each time you run configure, you must run make again to recompile. However, you may
want to remove old object files from previous builds first because they were compiled using different configuration options.
To prevent old configuration information or object files from being used, run these commands before re-running configure:
shell> rm config.cache
shell> make clean
Alternatively, you can run make distclean.
The following list describes some of the problems when compiling MySQL that have been found to
occur most often:
•
If you get errors such as the ones shown here when compiling sql_yacc.cc, you probably
have run out of memory or swap space:
Internal compiler error: program cc1plus got fatal signal 11
Out of virtual memory
Virtual memory exhausted
The problem is that gcc requires a huge amount of memory to compile sql_yacc.cc with
inline functions. Try running configure with the --with-low-memory option:
shell> ./configure --with-low-memory
This option causes -fno-inline to be added to the compile line if you are using gcc and O0 if you are using something else. You should try the --with-low-memory option even if
you have so much memory and swap space that you think you can't possibly have run out. This
problem has been observed to occur even on systems with generous hardware configurations and
the --with-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 behavior can cause problems during configuration such as this:
configure: error: installation or configuration problem:
C++ compiler cannot create executables.
You might also observe problems during compilation related to g++, libg++, or libstdc++.
One cause of these problems is that you may not have g++, or you may have g++ but not
libg++, or libstdc++. Take a look at the config.log file. It should contain the exact
reason why your C++ compiler didn't work. To work around these problems, you can use gcc
as your C++ compiler. Try setting the environment variable CXX to "gcc -O3". For example:
shell> CXX="gcc -O3" ./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 is to install g++, libg++, and libstdc++. We would,
however, like to recommend that you not use libg++ or libstdc++ with MySQL because
this only increases the binary size of mysqld without giving you any benefits. Some versions of
these libraries have also caused strange problems for MySQL users in the past.
99
Installing MySQL
Using gcc as the C++ compiler is also required if you want to compile MySQL with RAID
functionality (see Section 13.1.5, “CREATE TABLE Syntax” for more info on RAID table type)
and you are using GNU gcc version 3 and above. If you get errors like those following during
the linking stage when you configure MySQL to compile with the option --with-raid, try to
use gcc as your C++ compiler by defining the CXX environment variable:
gcc -O3 -DDBUG_OFF -rdynamic -o isamchk isamchk.o sort.o libnisam.a
../mysys/libmysys.a ../dbug/libdbug.a ../strings/libmystrings.a
-lpthread -lz -lcrypt -lnsl -lm -lpthread
../mysys/libmysys.a(raid.o)(.text+0x79): In function
`my_raid_create':: undefined reference to `operator new(unsigned)'
../mysys/libmysys.a(raid.o)(.text+0xdd): In function
`my_raid_create':: undefined reference to `operator delete(void*)'
../mysys/libmysys.a(raid.o)(.text+0x129): In function
`my_raid_open':: undefined reference to `operator new(unsigned)'
../mysys/libmysys.a(raid.o)(.text+0x189): In function
`my_raid_open':: undefined reference to `operator delete(void*)'
../mysys/libmysys.a(raid.o)(.text+0x64b): In function
`my_raid_close':: undefined reference to `operator delete(void*)'
collect2: ld returned 1 exit status
•
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.
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>
shell>
shell>
shell>
shell>
CC=gcc
CFLAGS=-O3
CXX=gcc
CXXFLAGS=-O3
export CC CFLAGS CXX CXXFLAGS
See Section 2.1.2.5, “MySQL Binaries Compiled by MySQL AB”, for a list of flag definitions
that have been found to be useful on various systems.
•
If you get an error message like this, you need to upgrade your 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 cor100
Installing MySQL
rectly 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 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 pre-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.
•
On Debian Linux 3.0, you need to install gawk instead of the default mawk if you want to compile MySQL 4.1 or higher with Berkeley DB support.
•
If you need to debug mysqld or a MySQL client, run configure with the --with-debug
option, then recompile and link your clients with the new client library. See Section F.2,
“Debugging a MySQL Client”.
•
If you get a compilation error on Linux (for example, SuSE Linux 8.1 or Red Hat Linux 7.3)
similar to the following one:
libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from
incompatible pointer type
libmysql.c:1329: too few arguments to function `gethostbyname_r'
libmysql.c:1329: warning: assignment makes pointer from integer
without a cast
make[2]: *** [libmysql.lo] Error 1
By default, the 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 afterward.
2.8.5. MIT-pthreads Notes
This section describes some of the issues involved in using MIT-pthreads.
101
Installing MySQL
On Linux, you should not use MIT-pthreads. Use the installed LinuxThreads implementation instead. See Section 2.12.1, “Linux Notes”.
If your system does not provide native thread support, you need to build MySQL using the MITpthreads package. This includes older FreeBSD systems, SunOS 4.x, Solaris 2.4 and earlier, and
some others. See Section 2.1.1, “Operating Systems Supported by MySQL”.
Beginning with MySQL 4.0.2, MIT-pthreads is no longer part of the source distribution. If you require
this
package,
you
need
to
download
it
separately
from
http://www.mysql.com/Downloads/Contrib/pthreads-1_60_beta6-mysql.tar.gz
After downloading, extract this source archive into the top level of the MySQL source directory. It
creates a new subdirectory named mit-pthreads.
•
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 minimize our changes to this code.
•
The checks that determine whether to use MIT-pthreads occur only during the part of the configuration process that deals with the server code. If you have configured the distribution using -without-server to build only the client code, clients do not know whether MIT-pthreads
is being used and use Unix socket connections by default. Because Unix socket files do not work
under MIT-pthreads on some platforms, this means you need to use -h or --host when you
run client programs.
•
When MySQL is compiled using MIT-pthreads, system locking is disabled by default for performance reasons. You can tell the server to use system locking with the -external-locking option. This is needed only if you want to be able to run two MySQL
servers against the same data files, which is not recommended.
•
Sometimes the pthread bind() command fails to bind to a socket without any error message
(at least on Solaris). The result is that all connections to the server fail. For example:
shell> mysqladmin version
mysqladmin: connect to server at '' failed;
error: 'Can't connect to mysql server on localhost (146)'
The solution to this is to kill the 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:
102
Installing MySQL
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.8.6. Installing MySQL from Source on Windows
These instructions describe how to build MySQL binaries from source for versions 4.1 and above on
Windows. Instructions are provided for building binaries from a standard source distribution or from
the BitKeeper tree that contains the latest development source.
Note: The instructions in this document are strictly for users who want to test MySQL on Windows
from the latest source distribution or from the BitKeeper tree. For production use, MySQL AB does
not advise using a MySQL server built by yourself from source. Normally, it is best to use precompiled binary distributions of MySQL that are built specifically for optimal performance on Windows
by MySQL AB. Instructions for installing a binary distributions are available at Section 2.3,
“Installing MySQL on Windows”.
To build MySQL on Windows from source, you need the following compiler and resources available on your Windows system:
•
Visual Studio 2003 compiler system (VC++ 7.0).
•
Between 3 and 5 GB disk space.
•
Windows 2000 or higher.
The
exact
system
requirements
can
be
tp://msdn.microsoft.com/vstudio/productinfo/sysreqs/default.aspx
found
here:
ht-
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 distributions are available for released versions
of MySQL and can be obtained from http://dev.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. See Section 2.8.3, “Installing from the Development
Source Tree” for instructions how to download and install BitKeeper.
If you are using a Windows source distribution, you can go directly to Section 2.8.6.1, “Building
MySQL Using VC++”. To build from the BitKeeper tree, proceed to Section 2.8.6.2, “Creating a
Windows Source Package from the Latest Development Source”.
If you find something not working as expected, or you have suggestions about ways to improve the
current build process on Windows, please send a message to the win32 mailing list. See Section 1.7.1.1, “The MySQL Mailing Lists”.
103
Installing MySQL
2.8.6.1. Building MySQL Using VC++
Note: VC++ workspace files for MySQL 4.1 and above are compatible with Microsoft Visual Studio 2003 editions and tested by MySQL AB staff before each release.
Follow this procedure to build MySQL:
1.
Create a work directory (for example, C:\workdir).
2.
Unpack the source distribution in the aforementioned directory using WinZip or other Windows tool that can read .zip files.
3.
Start Visual Studio.
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 expects 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 need to tell the server their pathnames. You can either do this on the
command line with the --basedir and --datadir options, or place appropriate options in
an option file (the my.ini file in your Windows directory or C:\my.cnf). If you have an
existing data directory elsewhere that you want to use, you can specify its pathname instead.
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.3,
“Installing MySQL on Windows”. You'll need 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 satisfied 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:\>
C:\>
C:\>
C:\>
C:\>
mkdir
mkdir
mkdir
mkdir
mkdir
C:\mysql
C:\mysql\bin
C:\mysql\data
C:\mysql\share
C:\mysql\scripts
104
Installing MySQL
If you want to compile other clients and link them to MySQL, you should also create several
additional directories:
C:\>
C:\>
C:\>
C:\>
mkdir
mkdir
mkdir
mkdir
C:\mysql\include
C:\mysql\lib
C:\mysql\lib\debug
C:\mysql\lib\opt
If you want to benchmark MySQL, create this directory:
C:\> mkdir C:\mysql\sql-bench
Benchmarking requires Perl support.
2.
From the workdir directory, copy into the C:\mysql directory the following directories:
C:\> cd \workdir
C:\workdir> copy client_release\*.exe C:\mysql\bin
C:\workdir> copy client_debug\mysqld.exe C:\mysql\bin\mysqld-debug.exe
C:\workdir> xcopy scripts\*.* C:\mysql\scripts /E
C:\workdir> xcopy share\*.* C:\mysql\share /E
If you want to compile other clients and link them to MySQL, you should also copy several libraries and header files:
C:\workdir>
C:\workdir>
C:\workdir>
C:\workdir>
C:\workdir>
C:\workdir>
C:\workdir>
C:\workdir>
copy
copy
copy
copy
copy
copy
copy
copy
lib_debug\mysqlclient.lib C:\mysql\lib\debug
lib_debug\libmysql.* C:\mysql\lib\debug
lib_debug\zlib.* C:\mysql\lib\debug
lib_release\mysqlclient.lib C:\mysql\lib\opt
lib_release\libmysql.* C:\mysql\lib\opt
lib_release\zlib.* C:\mysql\lib\opt
include\*.h C:\mysql\include
libmysql\libmysql.def C:\mysql\include
If you want to benchmark MySQL, you should also do this:
C:\workdir> xcopy sql-bench\*.* C:\mysql\bench /E
Set up and start the server in the same way as for the binary Windows distribution. See Section 2.3,
“Installing MySQL on Windows”.
2.8.6.2. Creating a Windows Source Package from the Latest Development Source
To create a Windows source package from the current BitKeeper source tree, use the following instructions. Please note that this procedure must be performed on a system running a Unix or Unixlike operating system. For example, the procedure is known to work well on Linux.
1.
Copy the BitKeeper source tree for MySQL (version 4.1 or above, as desired). For more information on how To copy the source tree, see the instructions at Section 2.8.3, “Installing
from the Development Source Tree”.
2.
Configure and build the distribution so that you have a server binary to work with. One way to
do this is to run the following command in the top-level directory of your source tree:
shell> ./BUILD/compile-pentium-max
105
Installing MySQL
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:
•
--help
Display a help message.
•
--debug
Print information about script operations, do not create package.
•
--tmp
Specify the temporary location.
•
--suffix
Suffix name for the package.
•
--dirname
Directory name to copy files (intermediate).
•
--silent
Do not print verbose list of files processed.
•
--tar
Create tar.gz package instead of .zip package.
By default, make_win_src_distribution creates a Zip-format archive with the name
mysql-VERSION-win-src.zip, where VERSION represents the version of your MySQL
source tree.
4.
Copy or upload to your Windows machine the Windows source package that you have just created. To compile it, use the instructions in Section 2.8.6.1, “Building MySQL Using VC++”.
2.8.7. Compiling MySQL Clients on Windows
In your source files, you should include my_global.h before mysql.h:
#include <my_global.h>
#include <mysql.h>
my_global.h includes any other files needed for Windows compatibility (such as windows.h)
if you compile your program on Windows.
You can either link your code with the dynamic libmysql.lib library, which is just a wrapper to
load in libmysql.dll on demand, or link with the static mysqlclient.lib library.
The MySQL client libraries are compiled as threaded libraries, so you should also compile your
code to be multi-threaded.
2.9. Post-Installation Setup and Testing
106
Installing MySQL
After installing MySQL, there are some issues you should address. For example, on Unix, you
should initialize the data directory and create the MySQL grant tables. On all platforms, an important security concern is that the initial accounts in the grant tables have no passwords. You should assign passwords to prevent unauthorized access to the MySQL server. For MySQL 4.1.3 and up, you
can create time zone tables to enable recognition of named time zones. (Currently, these tables can
be populated only on Unix. This problem will be addressed soon for Windows.)
The following sections include post-installation procedures that are specific to Windows systems
and to Unix systems. Another section, Section 2.9.2.3, “Starting and Troubleshooting the MySQL
Server”, applies to all platforms; it describes what to do if you have trouble getting the server to
start. Section 2.9.3, “Securing the Initial MySQL Accounts” also applies to all platforms. You
should follow its instructions to make sure that you have properly protected your MySQL accounts
by assigning passwords to them.
When you are ready to create additional user accounts, you can find information on the MySQL access control system and account management in Section 5.6, “The MySQL Access Privilege System” and Section 5.7, “MySQL User Account Management”.
2.9.1. Windows Post-Installation Procedures
On Windows, the data directory and the grant tables do not have to be created. MySQL Windows
distributions include the grant tables with a set of preinitialized accounts in the mysql database under the data directory. You do not run the mysql_install_db script that is used on Unix.
However, if you did not install MySQL using the Windows Installation Wizard, you should assign
passwords to the accounts. See Section 2.3.4.1, “Introduction”. The procedure for this is given in
Section 2.9.3, “Securing the Initial MySQL Accounts”.
Before setting up passwords, you might want to try running some client programs to make sure that
you can connect to the server and that it is operating properly. Make sure the server is running (see
Section 2.3.10, “Starting the Server for the First Time”), then issue the following commands to verify that you can retrieve information from the server. The output should be similar to what is shown
here:
C:\> C:\mysql\bin\mysqlshow
+-----------+
| Databases |
+-----------+
| mysql
|
| test
|
+-----------+
C:\> C:\mysql\bin\mysqlshow mysql
Database: mysql
+--------------+
|
Tables
|
+--------------+
| columns_priv |
| db
|
| func
|
| host
|
| tables_priv |
| user
|
+--------------+
C:\> C:\mysql\bin\mysql -e "SELECT Host,Db,User FROM db" mysql
+------+-------+------+
| host | db
| user |
+------+-------+------+
| %
| test% |
|
+------+-------+------+
If you are running a version of Windows that supports services and you want the MySQL server to
run automatically when Windows starts, see Section 2.3.12, “Starting MySQL as a Windows Service”.
107
Installing MySQL
2.9.2. Unix Post-Installation Procedures
After installing MySQL on Unix, you need to initialize the grant tables, start the server, and make
sure that the server works okay. You may also wish to arrange for the server to be started and
stopped automatically when your system starts and stops. You should also assign passwords to the
accounts in the grant tables.
On Unix, the grant tables are set up by the mysql_install_db program. For some installation
methods, this program is run for you automatically:
•
If you install MySQL on Linux using RPM distributions, the server RPM runs
mysql_install_db.
•
If you install MySQL on Mac OS X using a PKG distribution, the installer runs
mysql_install_db.
Otherwise, you'll need to run mysql_install_db yourself.
The following procedure describes how to initialize the grant tables (if that has not previously been
done) and then start the server. It also suggests some commands that you can use to test whether the
server is accessible and working properly. For information about starting and stopping the server
automatically, see Section 2.9.2.2, “Starting and Stopping MySQL Automatically”.
After you complete the procedure and have the server running, you should assign passwords to the
accounts created by mysql_install_db. Instructions for doing so are given in Section 2.9.3,
“Securing the Initial MySQL Accounts”.
In the examples shown here, the server runs under the user ID of the mysql login account. This assumes that such an account exists. Either create the account if it does not exist, or substitute the
name of a different existing login account that you plan to use for running the server.
1.
Change location into the top-level directory of your MySQL installation, represented here by
BASEDIR:
shell> cd BASEDIR
BASEDIR is likely to be something like /usr/local/mysql or /usr/local. The following steps assume that you are located in this directory.
2.
If necessary, run the mysql_install_db program to set up the initial MySQL grant tables
containing the privileges that determine how users are allowed to connect to the server. You'll
need to do this if you used a distribution type that doesn't run the program for you.
Typically, mysql_install_db needs to be run only the first time you install MySQL, so
you can skip this step if you are upgrading an existing installation, However,
mysql_install_db does not overwrite any existing privilege tables, so it should be safe to
run in any circumstances.
To initialize the grant tables, use one of the following commands, depending on whether
mysql_install_db is located in the bin or scripts directory:
shell> bin/mysql_install_db --user=mysql
shell> scripts/mysql_install_db --user=mysql
The mysql_install_db script creates the data directory, the mysql database that holds all
database privileges, and the test database that you can use to test MySQL. The script also
creates privilege table entries for root accounts and anonymous-user accounts. The accounts
have no passwords initially. A description of their initial privileges is given in Section 2.9.3,
“Securing the Initial MySQL Accounts”. Briefly, these privileges allow the MySQL root user
108
Installing MySQL
to do anything, and allow anybody to create or use databases with a name of test or starting
with test_.
It is important to make sure that the database directories and files are owned by the mysql login account so that the server has read and write access to them when you run it later. To ensure this, the --user option should be used as shown if you run mysql_install_db as
root. Otherwise, you should execute the script while logged in as mysql, in which case you
can omit the --user option from the command.
mysql_install_db creates several tables in the mysql database: user, db, host,
tables_priv, columns_priv, func, and possibly others depending on your version of
MySQL.
If you don't want to have the test database, you can remove it with mysqladmin -u
root drop test after starting the server.
If you have problems with mysql_install_db, see Section 2.9.2.1, “Problems Running
mysql_install_db”.
There are some alternatives to running the mysql_install_db script as it is provided in the
MySQL distribution:
•
If you want the initial privileges to be different from the standard defaults, you can modify
mysql_install_db before you run it. However, a preferable technique is to use
GRANT and REVOKE to change the privileges after the grant tables have been set up. In
other words, you can run mysql_install_db, and then use mysql -u root
mysql to connect to the server as the MySQL root user so that you can issue the GRANT
and REVOKE statements.
If you want to install MySQL on a lot of machines with the same privileges, you can put
the GRANT and REVOKE statements in a file and execute the file as a script using mysql
after running mysql_install_db. For example:
shell> bin/mysql_install_db --user=mysql
shell> bin/mysql -u root < your_script_file
By doing this, you can avoid having to issue the statements manually on each machine.
•
It is possible to re-create the grant tables completely after they have previously been created. You might want to do this if you're just learning how to use GRANT and REVOKE and
have made so many modifications after running mysql_install_db that you want to
wipe out the tables and start over.
To re-create the grant tables, remove all the .frm, .MYI, and .MYD files in the directory
containing the mysql database. (This is the directory named mysql under the data directory, which is listed as the datadir value when you run mysqld --help.) Then run the
mysql_install_db script again.
Note: For MySQL versions older than 3.22.10, you should not delete the .frm files. If you
accidentally do this, you should copy them back into the mysql directory from your
MySQL distribution before running mysql_install_db.
•
You can start mysqld manually using the --skip-grant-tables option and add the
privilege information yourself using mysql:
shell> bin/mysqld_safe --user=mysql --skip-grant-tables &
shell> bin/mysql mysql
From mysql, manually execute the SQL commands contained in mysql_install_db.
Make sure that you run mysqladmin flush-privileges or mysqladmin reload afterward to tell the server to reload the grant tables.
109
Installing MySQL
Note that by not using mysql_install_db, you not only have to populate the grant
tables manually, you also have to create them first.
3.
Start the MySQL server:
shell> bin/mysqld_safe --user=mysql &
For versions of MySQL older than 4.0, substitute bin/safe_mysqld for bin/
mysqld_safe in this command.
It is important that the MySQL server be run using an unprivileged (non-root) login account.
To ensure this, the --user option should be used as shown if you run mysql_safe as
root. Otherwise, you should execute the script while logged in as mysql, in which case you
can omit the --user option from the command.
Further instructions for running MySQL as an unprivileged user are given in Section A.3.2,
“How to Run MySQL as a Normal User”.
If you neglected to create the grant tables before proceeding to this step, the following message
appears in the error log file when you start the server:
mysqld: Can't find file: 'host.frm'
If you have other problems starting the server, see Section 2.9.2.3, “Starting and Troubleshooting the MySQL Server”.
4.
Use mysqladmin to verify that the server is running. The following commands provide
simple tests to check whether the server is up and responding to connections:
shell> bin/mysqladmin version
shell> bin/mysqladmin variables
The output from mysqladmin version varies slightly depending on your platform and
version of MySQL, but should be similar to that shown here:
shell> bin/mysqladmin version
mysqladmin Ver 8.40 Distrib 4.0.18, for linux on i586
Copyright (C) 2000 MySQL AB & MySQL Finland AB & TCX DataKonsult AB
This software comes with ABSOLUTELY NO WARRANTY. This is free software,
and you are welcome to modify and redistribute it under the GPL license
Server version
Protocol version
Connection
TCP port
UNIX socket
Uptime:
4.0.18-log
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 see what else you can do with mysqladmin, invoke it with the --help option.
5.
Verify that you can shut down the server:
shell> bin/mysqladmin -u root shutdown
110
Installing MySQL
6.
Verify that you can restart the server. Do this by using mysqld_safe or by invoking
mysqld directly. For example:
shell> bin/mysqld_safe --user=mysql --log &
If mysqld_safe fails, see Section 2.9.2.3, “Starting and Troubleshooting the MySQL Server”.
7.
Run some simple tests to verify that you can retrieve information from the server. The output
should be similar to what is shown here:
shell> bin/mysqlshow
+-----------+
| Databases |
+-----------+
| mysql
|
| test
|
+-----------+
shell> bin/mysqlshow mysql
Database: mysql
+--------------+
|
Tables
|
+--------------+
| columns_priv |
| db
|
| func
|
| host
|
| tables_priv |
| user
|
+--------------+
shell> bin/mysql -e "SELECT Host,Db,User FROM db" mysql
+------+--------+------+
| host | db
| user |
+------+--------+------+
| %
| test
|
|
| %
| test_% |
|
+------+--------+------+
8.
There is a benchmark suite in the sql-bench directory (under the MySQL installation directory) that you can use to compare how MySQL performs on different platforms. The benchmark
suite is written in Perl. It uses the Perl DBI module to provide a database-independent interface
to the various databases, and some other additional Perl modules are required to run the benchmark suite. You must have the following modules installed:
DBI
DBD::mysql
Data::Dumper
Data::ShowTable
These modules can be obtained from CPAN (http://www.cpan.org/). See Section 2.13.1,
“Installing Perl on Unix”.
The sql-bench/Results directory contains the results from many runs against different
databases and platforms. To run all tests, execute these commands:
shell> cd sql-bench
shell> perl run-all-tests
If you don't have the sql-bench directory, you probably installed MySQL using RPM files
other than the source RPM. (The source RPM includes the sql-bench benchmark directory.)
In this case, you must first install the benchmark suite before you can use it. Beginning with
111
Installing MySQL
MySQL 3.22, there are separate benchmark RPM files named mysql-bench-VERSIONi386.rpm that contain benchmark code and data.
If you have a source distribution, there are also tests in its tests subdirectory that you can
run. For example, to run auto_increment.tst, execute this command from the top-level
directory of your source distribution:
shell> mysql -vvf test < ./tests/auto_increment.tst
The expected result of the test can be found in the ./tests/auto_increment.res file.
9.
At this point, you should have the server running. However, none of the initial MySQL accounts have a password, so you should assign passwords using the instructions in Section 2.9.3,
“Securing the Initial MySQL Accounts”.
As of MySQL 4.1.3, the installation procedure creates time zone tables in the mysql database.
However, you must populate the tables manually. Instructions to do this are given in Section 5.9.8,
“MySQL Server Time Zone Support”.
2.9.2.1. Problems Running mysql_install_db
The purpose of the mysql_install_db script is to generate new MySQL privilege tables. It
does not overwrite existing MySQL privilege tables, and it does not affect any other data.
If you want to re-create your privilege tables, first stop the mysqld server if it's running. Then rename the mysql directory under the data directory to save it, and then run mysql_install_db.
For example:
shell> mv mysql-data-directory/mysql mysql-data-directory/mysql-old
shell> mysql_install_db --user=mysql
This section lists problems you might encounter when you run mysql_install_db:
•
mysql_install_db doesn't install the grant tables
You may find that mysql_install_db fails to install the grant tables and terminates after
displaying the following messages:
Starting mysqld daemon with databases from XXXXXX
mysqld ended
In this case, you should examine the error log file very carefully. The log should be located in
the directory XXXXXX named by the error message, and should indicate why mysqld didn't
start. If you don't understand what happened, include the log when you post a bug report. See
Section 1.7.1.3, “How to Report Bugs or Problems”.
•
There is a mysqld process running
This indicates that the server is running, in which case the grant tables have probably been created. If so, you don't have to run mysql_install_db at all because it need be run only once
(when you install MySQL the first time).
•
Installing a second mysqld server doesn't work when one server is running
This can happen when you have an existing MySQL installation, but want to put a new installation in a different location. For example, you might have a production installation, but you want
to create a second installation for testing purposes. Generally the problem that occurs when you
try to run a second server is that it tries to use a network interface that is in use by the first server. In this case, you should see one of the following error messages:
112
Installing MySQL
Can't start server: Bind on TCP/IP port:
Address already in use
Can't start server: Bind on unix socket...
For instructions on setting up multiple servers, see Section 5.11, “Running Multiple MySQL
Servers on the Same Machine”.
•
You don't have write access to /tmp
If you don't have write access to create temporary files or a Unix socket file in the default location (the /tmp directory), an error occurs when you run mysql_install_db or the mysqld
server.
You can specify different temporary directory and Unix socket file locations by executing these
commands prior to starting mysql_install_db or mysqld:
shell> TMPDIR=/some_tmp_dir/
shell> MYSQL_UNIX_PORT=/some_tmp_dir/mysql.sock
shell> export TMPDIR MYSQL_UNIX_PORT
some_tmp_dir should be the full pathname to some directory for which you have write permission.
After this, you should be able to run mysql_install_db and start the server with these commands:
shell> bin/mysql_install_db --user=mysql
shell> bin/mysqld_safe --user=mysql &
If mysql_install_db is located in the scripts directory, modify the first command to
use scripts/mysql_install_db.
See Section A.4.5, “How to Protect or Change the MySQL Socket File /tmp/mysql.sock”.
See Appendix G, Environment Variables.
2.9.2.2. Starting and Stopping MySQL Automatically
Generally, you start the mysqld server in one of these ways:
•
By invoking mysqld directly. This works on any platform.
•
By running the MySQL server as a Windows service. This can be done on versions of Windows
that support services (such as NT, 2000, XP, and 2003). The service can be set to start the server
automatically when Windows starts, or as a manual service that you start on request. For instructions, see Section 2.3.12, “Starting MySQL as a Windows Service”.
•
By invoking mysqld_safe, which tries to determine the proper options for mysqld and then
runs it with those options. This script is used on systems based on BSD Unix. See Section 5.1.3,
“mysqld_safe — MySQL Server Startup Script”.
•
By invoking mysql.server. This script is used primarily at system startup and shutdown on
systems that use System V-style run directories, where it usually is installed under the name
mysql. The mysql.server script starts the server by invoking mysqld_safe. See Section 5.1.4, “mysql.server — MySQL Server Startup Script”.
•
On Mac OS X, you can install a separate MySQL Startup Item package to enable the automatic
startup of MySQL on system startup. The Startup Item starts the server by invoking
mysql.server. See Section 2.5, “Installing MySQL on Mac OS X” for details.
113
Installing MySQL
The mysql.server and mysqld_safe scripts and the Mac OS X Startup Item can be used to
start the server manually, or automatically at system startup time. mysql.server and the Startup
Item also can be used to stop the server.
To start or stop the server manually using the mysql.server script, invoke it with start or
stop arguments:
shell> mysql.server start
shell> mysql.server stop
Before mysql.server starts the server, it changes location to the MySQL installation directory,
and then invokes mysqld_safe. If you want the server to run as some specific user, add an appropriate user option to the [mysqld] group of the /etc/my.cnf option file, as shown later in
this section. (It is possible that you'll need to edit mysql.server if you've installed a binary distribution of MySQL in a non-standard location. Modify it to cd into the proper directory before it
runs mysqld_safe. If you do this, your modified version of mysql.server may be overwritten if you upgrade MySQL in the future, so you should make a copy of your edited version that you
can reinstall.)
mysql.server stop brings down the server by sending a signal to it. You can also stop the
server manually by executing mysqladmin shutdown.
To start and stop MySQL automatically on your server, you need to add start and stop commands to
the appropriate places in your /etc/rc* files.
If you use the Linux server RPM package (MySQL-server-VERSION.rpm), the
mysql.server script is installed in the /etc/init.d directory with the name mysql. You
need not install it manually. See Section 2.4, “Installing MySQL on Linux” for more information on
the Linux RPM packages.
Some vendors provide RPM packages that install a startup script under a different name such as
mysqld.
If you install MySQL from a source distribution or using a binary distribution format that does not
install mysql.server automatically, you can install it manually. The script can be found in the
support-files directory under the MySQL installation directory or in a MySQL source tree.
To install mysql.server manually, copy it to the /etc/init.d directory with the name
mysql, and then make it executable. Do this by changing location into the appropriate directory
where mysql.server is located and executing these commands:
shell> cp mysql.server /etc/init.d/mysql
shell> chmod +x /etc/init.d/mysql
Older Red Hat systems use the /etc/rc.d/init.d directory rather than /etc/init.d. Adjust the preceding commands accordingly. Alternatively, first create /etc/init.d as a symbolic
link that points to /etc/rc.d/init.d:
shell> cd /etc
shell> ln -s rc.d/init.d .
After installing the script, the commands needed to activate it to run at system startup depend on
your operating system. On Linux, you can use chkconfig:
shell> chkconfig --add mysql
On some Linux systems, the following command also seems to be necessary to fully enable the
mysql script:
shell> chkconfig --level 345 mysql on
114
Installing MySQL
On FreeBSD, startup scripts generally should go in /usr/local/etc/rc.d/. The rc(8)
manual page states that scripts in this directory are executed only if their basename matches the
*.sh shell filename pattern. Any other files or directories present within the directory are silently
ignored. In other words, on FreeBSD, you should install the mysql.server script as /
usr/local/etc/rc.d/mysql.server.sh to enable automatic startup.
As an alternative to the preceding setup, some operating systems also use /etc/rc.local or /
etc/init.d/boot.local to start additional services on startup. To start up MySQL using this
method, you could append a command like the one following to the appropriate startup file:
/bin/sh -c 'cd /usr/local/mysql; ./bin/mysqld_safe --user=mysql &'
For other systems, consult your operating system documentation to see how to install startup scripts.
You can add options for mysql.server in a global /etc/my.cnf file. A typical /
etc/my.cnf file might look like this:
[mysqld]
datadir=/usr/local/mysql/var
socket=/var/tmp/mysql.sock
port=3306
user=mysql
[mysql.server]
basedir=/usr/local/mysql
The mysql.server script understands the following options: basedir, datadir, and pidfile. If specified, they must be placed in an option file, not on the command line.
mysql.server understands only start and stop as command-line arguments.
The following table shows which option groups the server and each startup script read from option
files:
Script
Option Groups
mysqld
[mysqld], [server], [mysqld-major-version]
mysql.server [mysqld], [mysql.server]
mysqld_safe
[mysqld], [server], [mysqld_safe]
[mysqld-major-version] means that groups with names like [mysqld-4.0],
[mysqld-4.1], and [mysqld-5.0] are read by servers having versions 4.0.x, 4.1.x, 5.0.x, and
so forth. This feature was added in MySQL 4.0.14. It can be used to specify options that can be read
only by servers within a given release series.
For backward compatibility, mysql.server also reads the [mysql_server] group and
mysqld_safe also reads the [safe_mysqld] group. However, you should update your option
files to use the [mysql.server] and [mysqld_safe] groups instead when you begin using
MySQL 4.0 or later.
See Section 4.3.2, “Using Option Files”.
2.9.2.3. Starting and Troubleshooting the MySQL Server
If you have problems starting the server, here are some things you can try:
•
Specify any special options needed by the storage engines you are using.
•
Make sure that the server knows where to find the data directory.
•
Make sure the server can use the data directory. The ownership and permissions of the data dir115
Installing MySQL
ectory and its contents must be set such that the server can access and modify them.
•
Check the error log to see why the server doesn't start.
•
Verify that the network interfaces the server wants to use are available.
Some storage engines have options that control their behavior. You can create a my.cnf file and
set startup options for the engines you plan to use. If you are going to use storage engines that support transactional tables (InnoDB, BDB), be sure that you have them configured the way you want
before starting the server:
•
If you are using InnoDB tables, refer to the InnoDB-specific startup options. In MySQL 3.23,
you must configure InnoDB explicitly or the server fails to start. From MySQL 4.0 on, InnoDB uses default values for its configuration options if you specify none. See Section 15.4,
“InnoDB Configuration”.
•
If you are using BDB (Berkeley DB) tables, you should familiarize yourself with the different
BDB-specific startup options. See Section 14.4.3, “BDB Startup Options”.
When the mysqld server starts, it changes location to the data directory. This is where it expects to
find databases and where it expects to write log files. On Unix, the server also writes the pid
(process ID) file in the data directory.
The data directory location is hardwired in when the server is compiled. This is where the server
looks for the data directory by default. If the data directory is located somewhere else on your system, the server does not work properly. You can find out what the default path settings are by invoking mysqld with the --verbose and --help options. (Prior to MySQL 4.1, omit the -verbose option.)
If the defaults don't match the MySQL installation layout on your system, you can override them by
specifying options on the command line to mysqld or mysqld_safe. You can also list the options in an option file.
To specify the location of the data directory explicitly, use the --datadir option. However, normally you can tell mysqld the location of the base directory under which MySQL is installed and it
looks for the data directory there. You can do this with the --basedir option.
To check the effect of specifying path options, invoke mysqld with those options followed by the
--verbose and --help options. For example, if you change location into the directory where
mysqld is installed, and then run the following command, it shows the effect of starting the server
with a base directory of /usr/local:
shell> ./mysqld --basedir=/usr/local --verbose --help
You can specify other options such as --datadir as well, but note that --verbose and -help must be the last options. (Prior to MySQL 4.1, omit the --verbose option.)
Once you determine the path settings you want, start the server without --verbose and --help.
If mysqld is currently running, you can find out what path settings it is using by executing this
command:
shell> mysqladmin variables
Or:
shell> mysqladmin -h host_name variables
116
Installing MySQL
host_name is the name of the MySQL server host.
If you get Errcode 13 (which means Permission denied) when starting mysqld, this
means that the access privileges of the data directory or its contents do not allow the server access.
In this case, you change the permissions for the involved files and directories so that the server has
the right to use them. You can also start the server as root, but this can raise security issues and
should be avoided.
On Unix, change location into the data directory and check the ownership of the data directory and
its contents to make sure the server has access. For example, if the data directory is /
usr/local/mysql/var, use this command:
shell> ls -la /usr/local/mysql/var
If the data directory or its files or subdirectories are not owned by the account that you use for running the server, change their ownership to that account:
shell> chown -R mysql /usr/local/mysql/var
shell> chgrp -R mysql /usr/local/mysql/var
If the server fails to start up correctly, check the error log file to see if you can find out why. Log
files are located in the data directory (typically C:\mysql\data on Windows, /
usr/local/mysql/data for a Unix binary distribution, and /usr/local/var for a Unix
source distribution). Look in the data directory for files with names of the form host_name.err
and host_name.log, where host_name is the name of your server host. (Older servers on
Windows use mysql.err as the error log name.) Then check the last few lines of these files. On
Unix, you can use tail to display the last few lines:
shell> tail host_name.err
shell> tail host_name.log
The error log contains information that indicates why the server couldn't start. For example, you
might see something like this in the log:
000729 14:50:10
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 the --bdb-no-recover option and Berkeley DB
found something wrong with its own log files when it tried to recover your databases. To be able to
continue, you should move away the old Berkeley DB log files from the database directory to some
other place, where you can later examine them. The BDB log files are named in sequence beginning
with log.0000000001, where the number increases over time.
If you are running mysqld with BDB table support and mysqld dumps core at startup, this could
be due to problems with the BDB recovery log. In this case, you can try starting mysqld with -bdb-no-recover. If that helps, then you should remove all BDB log files from the data directory and try starting mysqld again without the --bdb-no-recover option.
If either of the following errors occur, it means that some other program (perhaps another mysqld
server) is using the TCP/IP port or Unix socket file that mysqld is trying to use:
Can't start server: Bind on TCP/IP port: Address already in use
Can't start server: Bind on unix socket...
Use ps to determine whether you have another mysqld server running. If so, shut down the server
before starting mysqld again. (If another server is running, and you really want to run multiple
servers, you can find information about how to do so in Section 5.11, “Running Multiple MySQL
Servers on the Same Machine”.)
117
Installing MySQL
If no other server is running, try to execute the command telnet your-host-name tcpip-port-number. (The default MySQL port number is 3306.) Then press Enter a couple of
times. If you don't get an error message like telnet: Unable to connect to remote
host: Connection refused, some other program is using the TCP/IP port that mysqld is
trying to use. You'll need to track down what program this is and disable it, or else tell mysqld to
listen to a different port with the --port option. In this case, you'll also need to specify the port
number for client programs when connecting to the server via TCP/IP.
Another reason the port might be inaccessible is that you have a firewall running that blocks connections to it. If so, modify the firewall settings to allow access to the port.
If the server starts but you can't connect to it, you should make sure that you have an entry in /
etc/hosts that looks like this:
127.0.0.1
localhost
This problem occurs only on systems that don't have a working thread library and for which MySQL
must be configured to use MIT-pthreads.
If you can't get mysqld to start, you can try to make a trace file to find the problem by using the -debug option. See Section F.1.2, “Creating Trace Files”.
See Section 2.3.14, “Troubleshooting a MySQL Installation Under Windows”, for more information
on troubleshooting Windows installations.
2.9.3. Securing the Initial MySQL Accounts
Part of the MySQL installation process is to set up the mysql database containing the grant tables:
•
Windows distributions contain preinitialized grant tables that are installed automatically.
•
On Unix, the grant tables are populated by the mysql_install_db program. Some installation methods run this program for you. Others require that you execute it manually. For details,
see Section 2.9.2, “Unix Post-Installation Procedures”.
The grant tables define the initial MySQL user accounts and their access privileges. These accounts
are set up as follows:
•
•
Two accounts are created with a username of root. These are superuser accounts that can do
anything. The initial root account passwords are empty, so anyone can connect to the MySQL
server as root without a password and be granted all privileges.
•
On Windows, one root account is for connecting from the local host and the other allows
connections from any host.
•
On Unix, both root accounts are for connections from the local host. Connections must be
made from the local host by specifying a hostname of localhost for one account, or the
actual hostname or IP number for the other.
Two anonymous-user accounts are created, each with an empty username. The anonymous accounts have no passwords, so anyone can use them to connect to the MySQL server.
•
On Windows, one anonymous account is for connections from the local host. It has all privileges, just like the root accounts. The other is for connections from any host and has all
privileges for the test database or other databases with names that start with test.
•
On Unix, both anonymous accounts are for connections from the local host. Connections
must be made from the local host by specifying a hostname of localhost for one account,
or the actual hostname or IP number for the other. These accounts have all privileges for the
118
Installing MySQL
test database or other databases with names that start with test_.
As noted, none of the initial accounts have passwords. This means that your MySQL installation is
unprotected until you do something about it:
•
If you want to prevent clients from connecting as anonymous users without a password, you
should either assign passwords to the anonymous accounts or else remove them.
•
You should assign passwords to the MySQL root accounts.
The following instructions describe how to set up passwords for the initial MySQL accounts, first
for the anonymous accounts and then for the root accounts. Replace “newpwd” in the examples
with the actual password that you want to use. The instructions also cover how to remove the anonymous accounts, should you prefer not to allow anonymous access at all.
You might want to defer setting the passwords until later, so that you don't need to specify them
while you perform additional setup or testing. However, be sure to set them before using your installation for any real production work.
To assign passwords to the anonymous accounts, you can use either SET PASSWORD or UPDATE.
In both cases, be sure to encrypt the password using the PASSWORD() function.
To use SET PASSWORD on Windows, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR ''@'%' = PASSWORD('newpwd');
To use SET PASSWORD on Unix, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR ''@'host_name' = PASSWORD('newpwd');
In the second SET PASSWORD statement, replace host_name with the name of the server host.
This is the name that is specified in the Host column of the non-localhost record for root in
the user table. If you don't know what hostname this is, issue the following statement before using
SET PASSWORD:
mysql> SELECT Host, User FROM mysql.user;
Look for the record that has root in the User column and something other than localhost in
the Host column. Then use that Host value in the second SET PASSWORD statement.
The other way to assign passwords to the anonymous accounts is by using UPDATE to modify the
user table directly. Connect to the server as root and issue an UPDATE statement that assigns a
value to the Password column of the appropriate user table records. The procedure is the same
for Windows and Unix. The following UPDATE statement assigns a password to both anonymous
accounts at once:
shell> mysql -u root
mysql> UPDATE mysql.user SET Password = PASSWORD('newpwd')
->
WHERE User = '';
mysql> FLUSH PRIVILEGES;
After you update the passwords in the user table directly using UPDATE, you must tell the server
to re-read the grant tables with FLUSH PRIVILEGES. Otherwise, the change goes unnoticed until
119
Installing MySQL
you restart the server.
If you prefer to remove the anonymous accounts instead, do so as follows:
shell> mysql -u root
mysql> DELETE FROM mysql.user WHERE User = '';
mysql> FLUSH PRIVILEGES;
The DELETE statement applies both to Windows and to Unix. On Windows, if you want to remove
only the anonymous account that has the same privileges as root, do this instead:
shell> mysql -u root
mysql> DELETE FROM mysql.user WHERE Host='localhost' AND User='';
mysql> FLUSH PRIVILEGES;
This account allows anonymous access but has full privileges, so removing it improves security.
You can assign passwords to the root accounts in several ways. The following discussion demonstrates three methods:
•
Use the SET PASSWORD statement
•
Use the mysqladmin command-line client program
•
Use the UPDATE statement
To assign passwords using SET PASSWORD, connect to the server as root and issue two SET
PASSWORD statements. Be sure to encrypt the password using the PASSWORD() function.
For Windows, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR 'root'@'%' = PASSWORD('newpwd');
For Unix, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR 'root'@'host_name' = PASSWORD('newpwd');
In the second SET PASSWORD statement, replace host_name with the name of the server host.
This is the same hostname that you used when you assigned the anonymous account passwords.
To assign passwords to the root accounts using mysqladmin, execute the following commands:
shell> mysqladmin -u root password "newpwd"
shell> mysqladmin -u root -h host_name password "newpwd"
These commands apply both to Windows and to Unix. In the second command, replace
host_name with the name of the server host. The double quotes around the password are not always necessary, but you should use them if the password contains spaces or other characters that are
special to your command interpreter.
If you are using a server from a very old version of MySQL, the mysqladmin commands to set the
password fail with the message parse error near 'SET password'. The solution to this
problem is to upgrade the server to a newer version of MySQL.
You can also use UPDATE to modify the user table directly. The following UPDATE statement assigns a password to both root accounts at once:
120
Installing MySQL
shell> mysql -u root
mysql> UPDATE mysql.user SET Password = PASSWORD('newpwd')
->
WHERE User = 'root';
mysql> FLUSH PRIVILEGES;
The UPDATE statement applies both to Windows and to Unix.
After the passwords have been set, you must supply the appropriate password whenever you connect
to the server. For example, if you want to use mysqladmin to shut down the server, you can do so
using this command:
shell> mysqladmin -u root -p shutdown
Enter password: (enter root password here)
Note: If you forget your root password after setting it up, the procedure for resetting it is covered
in Section A.4.1, “How to Reset the Root Password”.
To set up new accounts, you can use the GRANT statement. For instructions, see Section 5.7.2,
“Adding New User Accounts to MySQL”.
2.10. Upgrading MySQL
As a general rule, we recommend that when upgrading from one release series to another, you
should go to the next series rather than skipping a series. For example, if you currently are running
MySQL 3.23 and wish to upgrade to a newer series, upgrade to MySQL 4.0 rather than to 4.1 or 5.0.
The following items form a checklist of things you should do whenever you perform an upgrade:
•
Read the upgrading section for the release series to which you are upgrading. Read the change
notes as well. These provide information about new features you can use. For example, before
upgrading from MySQL 4.1 to 5.0, read the 5.0 upgrading section (see Section 2.10.2,
“Upgrading from Version 4.1 to 5.0”) and read the 5.0 change notes (see Appendix E, MySQL
Change History).
•
Before you do an upgrade, back up your databases.
•
If you are running MySQL Server on Windows, see Section 2.3.15, “Upgrading MySQL on
Windows”.
•
An upgrade may involve changes to the grant tables that are stored in the mysql database. Occasionally new columns or tables are added to support new features. To take advantage of these
features, be sure that your grant tables are up to date. The upgrade procedure is described in Section 2.10.8, “Upgrading the Grant Tables”.
•
If you are using replication, see Section 6.6, “Upgrading a Replication Setup” for information on
upgrading your replication setup.
•
If you install a MySQL-Max distribution that includes a server named mysqld-max, then upgrade later to a non-Max version of MySQL, mysqld_safe still attempts to run the old
mysqld-max server. If you perform such an upgrade, you should manually remove the old
mysqld-max server to ensure that mysqld_safe runs the new mysqld server.
You can always move the MySQL format files and data files between different versions on the same
architecture as long as you stay within versions for the same release series of MySQL. The current
production release series is 4.1. If you change the character set when running MySQL, you must run
myisamchk -r -q --set-character-set=charset on all MyISAM tables. Otherwise,
your indexes may not be ordered correctly, because changing the character set may also change the
sort order.
121
Installing MySQL
Normally you can upgrade MySQL to a newer MySQL version without having to do any changes to
your tables. Please confirm if the upgrade notes to the particular version you are upgrading to tells
you anything about this. If there would be any incompatibilities you can use mysqldump to dump
your tables before upgrading. After upgrading, reload the dump file using mysql or
mysqlimport to re-create your tables.
If you are cautious about using new versions, you can always rename your old mysqld before installing a newer one. For example, if you are using MySQL 4.0.18 and want to upgrade to 4.1.1, rename your current server from mysqld to mysqld-4.0.18. If your new mysqld then does
something unexpected, you can simply shut it down and restart with your old mysqld.
If, after an upgrade, you experience problems with recompiled client programs, such as Commands
out of sync or unexpected core dumps, you probably have used old header or library files when
compiling your programs. In this case, you should check the date for your mysql.h file and
libmysqlclient.a library to verify that they are from the new MySQL distribution. If not, recompile your programs with the new headers and libraries.
If problems occur, such as that the new mysqld server doesn't want to start or that you can't connect without a password, verify that you don't have some old my.cnf file from your previous installation. You can check this with the --print-defaults option (for example, mysqld -print-defaults). If this displays anything other than the program name, you have an active
my.cnf file that affects server or client operation.
It is a good idea to rebuild and reinstall the Perl DBD::mysql module whenever you install a new
release of MySQL. The same applies to other MySQL interfaces as well, such as the PHP mysql
extension and the Python MySQLdb module.
2.10.1. Upgrading from Version 5.0
When upgrading a 5.0 installation to 5.0.10 or above note that it is necessary to run
mysql_fix_privilege_tables (or the mysql_fix_privilege_tables.sql script
on Windows). Otherwise, creating stored procedures might not work. The procedure for doing this
is described in Section 2.10.8, “Upgrading the Grant Tables”.
2.10.2. Upgrading from Version 4.1 to 5.0
Note: Currently, MySQL 5.0 is at Beta status and, as for any other pre-production release, should
not be installed on “production” level systems or systems with critical data. It is good practice to
back up your data before installing any new version of software. Although MySQL has done its best
to ensure a high level of quality, protect your data by making a backup as you would for any software beta release.
In general, you should do the following when upgrading to MySQL 5.0 from 4.1:
•
Check the items in the change list found later in this section to see whether any of them might
affect your applications. Note particularly any that are marked Incompatible change; these result in incompatibilities with earlier versions of MySQL, and may require your attention before
you upgrade.
•
Read the 5.0 news items to see what significant new features you can use in 5.0. See Section E.1, “Changes in release 5.0.x (Development)”.
•
If you are running MySQL Server on Windows, see Section 2.3.15, “Upgrading MySQL on
Windows”. Also, two of the Windows MySQL servers were renamed. See Section 2.3.9,
“Selecting a MySQL Server type”.
•
MySQL 5.0 adds support for stored procedures. This support requires the proc table in the
mysql database. To create this file, you should run the mysql_fix_privilege_tables
script as described in Section 2.10.8, “Upgrading the Grant Tables”.
•
MySQL 5.0 adds support for views. This support requires extra privilege columns in the user
122
Installing MySQL
and db tables in the mysql database. To create these columns, you should run the
mysql_fix_privilege_tables script as described in Section 2.10.8, “Upgrading the
Grant Tables”.
•
If you are using replication, see Section 6.6, “Upgrading a Replication Setup” for information on
upgrading your replication setup.
Several visible behaviors have changed between MySQL 4.1 and mySQL 5.0 to make MySQL more
compatible with standard SQL. These changes may affect your applications.
The following list describes changes that may affect applications and that you should watch out for
when upgrading to version 5.0.
Server Changes:
•
Incompatible change: The indexing order for end-space in TEXT columns for InnoDB and
MyISAM tables has changed. Starting from 5.0.3, TEXT indexes are compared as space-padded
at the end (just like the way MySQL sorts CHAR, VARCHAR and TEXT fields). If you have a index on a TEXT column, you should run CHECK TABLE on it. If the check reports errors, rebuild the indexes: Dump and reload the table if it is an InnoDB table, or run OPTIMIZE TABLE or REPAIR TABLE if it is a MyISAM table.
•
Incompatible change: MyISAM and InnoDB tables created with DECIMAL columns in
MySQL 5.0.3 to 5.0.5 will appear corrupt after an upgrade to MySQL 5.0.6. Dump such tables
with mysqldump before upgrading, and then reload them after upgrading. (The same incompatibility will occur for these tables created in MySQL 5.0.6 after a downgrade to MySQL 5.0.3
to 5.0.5.)
•
Incompatible change: As of MySQL 5.0.3, the server by default no longer loads user-defined
functions unless they have at least one auxiliary symbol (for example, an xxx_init or
xxx_deinit symbol) defined in addition to the main function symbol. This behavior can be
overridden with the --allow-suspicious-udfs option. See Section 25.2.3.6,
“User-defined Function Security Precautions”.
•
Incompatible change: The update log is removed, so if you enabled it in the past, you should
enable the binary log instead. See Section E.1, “Changes in release 5.0.x (Development)”.
•
Incompatible change: Support for the ISAM storage engine has been removed. If you have
ISAM tables, you should convert them before upgrading. For example, to convert an ISAM table
to use the MyISAM storage engine, use this statement:
ALTER TABLE tbl_name ENGINE = MyISAM;
Use a similar statement for each ISAM table.
•
Incompatible change: Support for RAID options in MyISAM tables has been removed. If you
have tables that use these options, you should convert them before upgrading. One way to do
this is to dump them with mysqldump, edit the dump file to remove the RAID options in the
CREATE TABLE statements, and reload the dump file. Another possibility is to use CREATE
TABLE new_tbl ... SELECT raid_tbl to create a new table from the RAID table.
However, the CREATE TABLE part of the statement must contain sufficient information to recreate column attributes as well as indexes, or column attributes may be lost and indexes will not
appear in the new table. See Section 13.1.5, “CREATE TABLE Syntax”.
The .MYD files for RAID tables in a given database are stored under the database directory in
subdirectories that have names consisting of two hex digits in the range from 00 to ff. After
converting all tables that use RAID options, these RAID-related subdirectories still will exist but
can be removed. Verify that they are empty, and then remove them manually. (If they are not
empty, there is some RAID table that has not been converted.)
•
In MySQL 5.0.6, binary logging of stored routines and triggers was changed. This change has
123
Installing MySQL
implications for security, replication, and data recovery, as discussed in Section 18.4, “Binary
Logging of Stored Routines and Triggers”.
SQL Changes:
•
Incompatible change: The namespace for triggers has changed. Previously, trigger names had
to be unique per table. Now they must be unique within the schema (database). An implication
of this change is that DROP TRIGGER syntax now uses a schema name instead of a table name
(schema name is optional and, if omitted, the current schema will be used).
When upgrading from a previous version of MySQL 5 to MySQL 5.0.10 or newer, you must
drop all triggers and re-create them or DROP TRIGGER will not work after the upgrade. Here is
a suggested procedure for doing this:
1.
Upgrade to MySQL 5.0.10 to be able to access trigger information in the INFORMATION_SCHEMA.TRIGGERS table. (It should work even for pre-5.0.10 triggers.)
2.
Dump all trigger definitions using the following SELECT statement:
SELECT CONCAT('CREATE TRIGGER ', t.TRIGGER_SCHEMA, '.', t.TRIGGER_NAME,
' ', t.ACTION_TIMING, ' ', t.EVENT_MANIPULATION , ' ON ',
t.EVENT_OBJECT_SCHEMA, '.', t.EVENT_OBJECT_TABLE,
' FOR EACH ROW ', t.ACTION_STATEMENT, '//' )
INTO OUTFILE '/tmp/triggers.sql'
FROM INFORMATION_SCHEMA.TRIGGERS AS t;
The statement uses INTO OUTFILE, so you must have the FILE privilege. The file will
be created on the server host; use a different filename if you like. To be 100% safe, inspect
the trigger definitions in the triggers.sql file, and perhaps make a backup of the file.
3.
Stop the server and drop all triggers by removing all .TRG files in your database directories. Change location to your data directory and issue this command:
shell> rm */*.TRG
4.
Start the server and recreate all triggers using the triggers.sql file: For example in my
case it was:
mysql> delimiter // ;
mysql> source /tmp/triggers.sql //
5.
•
Check that all triggers were successfully created using the SHOW TRIGGERS statement.
Note: As of MySQL 5.0.12, natural joins and joins with USING, including outer join variants,
are processed according to the SQL:2003 standard. This change may necessitate that certain
queries be rewritten. For example, the following query will work as written before 5.0.12, but as
of 5.0.12 will fail with an Unknown column 't1.id' in 'on clause' error:
SELECT t1.id,t2.id,t3.id FROM t1,t2 LEFT JOIN t3 ON (t3.id=t1.id)
WHERE t1.id=t2.id;
To rewrite the query, use parentheses to group the tables in the inner join:
SELECT t1.id,t2.id,t3.id FROM (t1,t2) LEFT JOIN t3 ON (t3.id=t1.id)
WHERE t1.id=t2.id;
For that particular query, it is also possible to rewrite it as a natural join:
SELECT t1.id,t2.id,t3.id FROM t1,t2 NATURAL LEFT JOIN t3
124
Installing MySQL
WHERE t1.id=t2.id;
•
DECIMAL columns now are stored in a more efficient format. To convert a table to use the new
DECIMAL type, you should do an ALTER TABLE on it. The ALTER TABLE also will change
the table's VARCHAR columns to use the new VARCHAR column type. For information about
possible incompatibilities with old applications, see Chapter 22, Precision Math.
•
MySQL 5.0.3 and up uses precision math when calculating with DECIMAL values (64 decimal
digits) and for rounding exact-value numbers. See Chapter 22, Precision Math.
•
As of MySQL 5.0.3, trailing spaces no longer are removed from values stored in VARCHAR and
VARBINARY columns. The maximum length for VARCHAR or VARBINARY now is 65,535
characters or bytes, respectively.
Note: If you create a table with new VARCHAR or VARBINARY columns in MySQL 5.0.3 or up,
the table will not be usable if you downgrade to a version older than 5.0.3. Dump the table before downgrading and then reload it after downgrading.
•
As of MySQL 5.0.3, BIT is a separate data type, not a synonym for TINYINT(1). See Section 11.1.1, “Overview of Numeric Types”.
•
MySQL 5.0.2 adds several SQL modes that allow stricter control over rejecting records that
have invalid or missing values. See Section 5.3.2, “The Server SQL Mode”. See Section 1.8.6.2,
“Constraints on Invalid Data”. If you want to enable this control but continue to use MySQL's
capability for storing incorrect dates such as '2004-02-31', you should start the server with
--sql_mode=TRADITIONAL,ALLOW_INVALID_DATES.
•
As of MySQL 5.0.2, the SCHEMA and SCHEMAS keywords are accepted as synonyms for
DATABASE and DATABASES.
•
User variables are not case sensitive. In MySQL 4.1, SET @x = 0; SET @X = 1; SELECT @x; creates two variables and returns 0. In MySQL 5.0, it creates one variable and returns 1.
C API Changes:
•
The reconnect flag in the MYSQL structure is set to 0 by mysql_real_connect(). Only
those client programs which didn't explicitly set this flag to 0 or 1 after
mysql_real_connect() experience a change. Having automatic reconnection enabled by
default was considered too dangerous (after reconnection, table locks, temporary tables, user and
session variables are lost).
2.10.3. Upgrading from Version 4.0 to 4.1
In general, you should do the following when upgrading to MySQL 4.1 from 4.0:
•
Check the items in the change list found later in this section to see whether any of them might
affect your applications. Note particularly any that are marked Incompatible change; these result in incompatibilities with earlier versions of MySQL and you should consider the implications
of these incompatibilities before you upgrade. Note particularly the items under “Server
Changes” that related to changes in character set support.
•
Read the 4.1 news items to see what significant new features you can use in 4.1. See Section E.2, “Changes in release 4.1.x (Production)”.
•
If you are running MySQL Server on Windows, see Section 2.3.15, “Upgrading MySQL on
Windows”.
125
Installing MySQL
•
After upgrading, update the grant tables to have the new longer Password column that is
needed
for
more
secure
handling
of
passwords.
The
procedure
uses
mysql_fix_privilege_tables and is described in Section 2.10.8, “Upgrading the Grant
Tables”. If you don't do this, MySQL does not use the new more secure protocol to authenticate.
Implications of the password-handling change for applications are given later in this section.
•
If you are using replication, see Section 6.6, “Upgrading a Replication Setup” for information on
upgrading your replication setup.
•
The Berkeley DB table handler is updated to DB 4.1 (from 3.2) which has a new log format. If
you have to downgrade back to 4.0 you must use mysqldump to dump your BDB tables in text
format and delete all log.XXXXXXXXXX files before you start MySQL 4.0 and reload the data.
•
MySQL 4.1.3 introduces support for per-connection time zones. See Section 5.9.8, “MySQL
Server Time Zone Support”. To enable recognition of named time zones, you should create the
time zone tables in the mysql database. For instructions, see Section 2.9, “Post-Installation
Setup and Testing”.
•
If you are using an old DBD-mysql module (Msql-MySQL-modules) you have to upgrade
to use the newer DBD-mysql module. Anything above DBD-mysql 2.xx should be fine.
If you don't upgrade, some methods (such as DBI->do()) do not notice error conditions correctly.
•
The --defaults-file=option_file_name option gives an error if the option file
doesn't exist.
•
Some notes about upgrading from MySQL 4.0 to MySQL 4.1 on Netware: Make sure to upgrade
Perl
and
PHP
versions.
Download
Perl
5
for
Netware
from
http://forge.novell.com/modules/xfmod/project/?perl5
and
PHP
from
http://forge.novell.com/modules/xfmod/project/?php. Download and install Perl module for
MySQL 4.1 from http://forge.novell.com/modules/xfmod/project/showfiles.php?group_id=1126
and
PHP
Extension
for
MySQL
4.1
from
http://forge.novell.com/modules/xfmod/project/showfiles.php?group_id=1078.
Several visible behaviors have changed between MySQL 4.0 and MySQL 4.1 to fix some critical
bugs and make MySQL more compatible with standard SQL. These changes may affect your applications.
Some of the 4.1 behaviors can be tested in 4.0 before performing a full upgrade to 4.1. We have added to later MySQL 4.0 releases (from 4.0.12 on) a --new startup option for mysqld. See Section 5.3.1, “mysqld Command-Line Options”.
This option gives you the 4.1 behavior for the most critical changes. You can also enable these behaviors for a given client connection with the SET @@new=1 command, or turn them off if they
are on with SET @@new=0.
If you believe that some of the 4.1 changes affect you, we recommend that before upgrading to 4.1,
you download the latest MySQL 4.0 version and run it with the --new option by adding the following to your config file:
[mysqld-4.0]
new
That way you can test the new behaviors in 4.0 to make sure that your applications work with them.
This helps you have a smooth, painless transition when you perform a full upgrade to 4.1 later. Putting the --new option in the [mysqld-4.0] option group ensures that you don't accidentally
later run the 4.1 version with the --new option.
The following lists describe changes that may affect applications and that you should watch out for
when upgrading to version 4.1.
126
Installing MySQL
Server Changes:
The most notable change is that character set support has been improved. The server supports multiple character sets, and all tables and non-binary string columns (CHAR, VARCHAR, and TEXT)
have a character set. See Chapter 10, Character Set Support. Binary string columns (BINARY,
VARBINARY, and BLOB) contain strings of bytes and do not have a character set. Note: This
change in character set support results in the potential for table damage if you do not upgrade properly, so consider carefully the incompatibilities noted here.
•
Incompatible change: There are conditions under which you should rebuild tables. In general,
to rebuild a table, dump it with mysqldump and reload the dump file. Some items in the following list indicate alternatives means for rebuilding.
•
If you have created or used InnoDB tables with TIMESTAMP columns in MySQL versions
4.1.0 to 4.1.3, you have to rebuild those tables when you upgrade to MySQL 4.1.4 or later.
The storage format in those MySQL versions for a TIMESTAMP column was incorrect. If
you upgrade from MySQL 4.0 to 4.1.4 or later, then no rebuild of tables with TIMESTAMP
columns is needed.
•
Starting from MySQL 4.1.3, InnoDB uses the same character set comparison functions as
MySQL for non-latin1_swedish_ci character strings that are not BINARY. This
changes the sorting order of space and characters with a code < ASCII(32) in those character
sets. For latin1_swedish_ci character strings and BINARY strings, InnoDB uses its
own pad-spaces-at-end comparison method, which stays unchanged. Note that latin1_swedish_ci is the default collation order for latin1 in 4.0. If you have an InnoDB table created with MySQL 4.1.2 or earlier, with an index on a non-latin1_swedish_ci character set and collation order column that is not BINARY (in the
case of 4.1.0 and 4.1.1, with any character set and collation), and that column may contain
characters with a code < ASCII(32), then you should do ALTER TABLE or OPTIMIZE
TABLE on it to regenerate the index, after upgrading to MySQL 4.1.3 or later. You can also
rebuild the table from a dump.
MyISAM tables also have to be rebuilt or repaired in these cases. You can use mysqldump
to dump them in 4.0 and then reload them in 4.1. An alternative is to use OPTIMIZE TABLE after upgrading, but this must be done before any updates are made in 4.1.
•
•
If you have used column prefix indexes on UTF8 columns or other multi-byte character set
columns in MySQL 4.1.0 to 4.1.5, you must rebuild the tables when you upgrade to MySQL
4.1.6 or later.
•
If you have used accent characters (characters with byte values of 128 to 255) in database
names, table names, constraint names, or column names in versions of MySQL earlier than
4.1, you cannot upgrade to MySQL 4.1 directly, because 4.1 uses UTF8 to store metadata
names. Use RENAME TABLE to overcome this if the accent character is in the table name or
the database name, or rebuild the table.
•
String comparison works according to SQL standard: Instead of stripping end spaces before
comparison, we now extend the shorter string with spaces. The problem with this is that now
'a' > 'a\t', which it wasn't before. If you have any tables where you have an indexed
CHAR, VARCHAR or TEXT column in which the last character in the index may be less than
ASCII(32), you should use REPAIR TABLE or mysqlcheck to ensure that the table is
correct.
•
MyISAM tables now use a better checksum algorithm. If you have MyISAM tables with live
checksum enabled (you used CHECKSUM=1 in CREATE TABLE or ALTER TABLE), these
tables will appear corrupted. Use REPAIR TABLE to recalculate the checksum.
Incompatible change: MySQL interprets length specifications in character column definitions
in characters. (Earlier versions interpret them in bytes.) For example, CHAR(N) means N characters, not N bytes.
For single-byte character sets, this change makes no difference. However, if you upgrade to
127
Installing MySQL
MySQL 4.1 and configure the server to use a multi-byte character set, the apparent length of
character columns changes. Suppose that a 4.0 table contains a CHAR(8) column used to store
ujis characters. Eight bytes can store from two to four ujis characters. If you upgrade to 4.1
and configure the server to use ujis as its default character set, the server interprets character
column lengths based on the maximum size of a ujis character, which is three bytes. The number of three-byte characters that fit in eight bytes is two. Consequently, if you use SHOW CREATE TABLE to view the table definition, MySQL displays CHAR(2). You can retrieve existing
data from the table, but you can only store new values containing up to two characters. To correct this issue, use ALTER TABLE to change the column definition. For example:
ALTER TABLE tbl_name MODIFY col_name CHAR(8);
•
Important note: MySQL 4.1 stores table names and column names in UTF8. If you have table
names or column names that use characters outside of the standard 7-bit US-ASCII range, you
may have to do a mysqldump of your tables in MySQL 4.0 and restore them after upgrading to
MySQL 4.1. The symptom for this problem is that you get a table not found error when
trying to access your tables. In this case, you should be able to downgrade back to MySQL 4.0
and access your data.
•
Important note: If you upgrade to MySQL 4.1.1 or higher, it is difficult to downgrade back to
4.0 or 4.1.0! That is because, for earlier versions, InnoDB is not aware of multiple tablespaces.
•
Incompatible change: In connection with the support for per-connection time zones in MySQL
4.1.3, the timezone system variable was renamed to system_time_zone.
•
All tables and non-binary string columns (CHAR, VARCHAR, and TEXT) have a character set.
See Chapter 10, Character Set Support. Binary string columns (BINARY, VARBINARY, and
BLOB) contain strings of bytes and do not have a character set.
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.) This change
should not affect applications that use only one character set.
•
If you were using columns with the CHAR BINARY or VARCHAR BINARY data types in
MySQL 4.0, these were treated as binary strings. To have them treated as binary strings in
MySQL 4.1, you should convert them to use the BINARY and VARBINARY data types, respectively.
•
If you have table columns that store character data represented in a character set that the 4.1
server supports directly, you can convert the columns to the proper character set using the instructions in Section 10.10.2, “Converting 4.0 Character Columns to 4.1 Format”. Also, database, table, and column identifiers are stored internally using Unicode (UTF8) regardless of the
default character set. See Section 9.2, “Database, Table, Index, Column, and Alias Names”.
•
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 8.7, “mysqldump — A Database Backup Program”.
•
Windows servers support connections from local clients using shared memory if run with the -shared-memory option. If you are running multiple servers this way on the same Windows
machine, you should use a different --shared-memory-base-name option for each server.
•
Incompatible change: The interface to aggregate user-defined functions has changed a bit as of
MySQL 4.1.1. You must declare a xxx_clear() function for each aggregate function
XXX(). xxx_clear() is used instead of xxx_reset(). See Section 25.2.3.2, “UDF Calling Sequences for aggregate functions”.
•
As of MySQL 4.1.10a, the server by default no longer loads user-defined functions unless they
have at least one auxiliary symbol defined in addition to the main function symbol. This behavior can be overridden with the --allow-suspicious-udfs option. See Section 25.2.3.6,
128
Installing MySQL
“User-defined Function Security Precautions”.
•
A new startup option named innodb_table_locks was added that causes LOCK TABLE to
also acquire InnoDB table locks. This option is enabled by default. This can cause deadlocks in
applications that use AUTOCOMMIT=1 and LOCK TABLES. If you application encounters deadlocks after upgrading, you may need to add innodb_table_locks=0 to your my.cnf file.
Client Changes:
•
mysqldump has the --opt and --quote-names options enabled by default. You can turn
them off with --skip-opt and --skip-quote-names.
SQL Changes:
•
Incompatible change: String comparison works according to SQL standard: Instead of stripping end spaces before comparison, we now extend the shorter string with spaces. The problem
with this is that now 'a' > 'a\t', which it wasn't before. If you have any tables where you
have an indexed CHAR, VARCHAR or TEXT column in which the last character in the index may
be less than ASCII(32), you should use REPAIR TABLE or mysqlcheck to ensure that the
table is correct.
•
Incompatible change: TIMESTAMP is returned as a string in 'YYYY-MM-DD HH:MM:SS'
format. See Section 11.3.1.2, “TIMESTAMP Properties as of MySQL 4.1”. From 4.0.12 on, the
--new option can be used to make a 4.0 server behave as 4.1 in this respect. The effect of this
option is described in Section 11.3.1.1, “TIMESTAMP Properties Prior to MySQL 4.1”.
When running the server with --new, if you want to have a TIMESTAMP column returned as a
number (as MySQL 4.0 does by default), you should add +0 when you retrieve it:
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.
•
Incompatible change: Binary values such as 0xFFDF are assumed to be strings instead of
numbers. This fixes some problems with character sets where it's convenient to input a string as
a binary value. With this change, you should use CAST() if you want to compare binary values
numerically as integers:
mysql> SELECT CAST(0xFEFF AS UNSIGNED INTEGER)
->
< CAST(0xFF AS UNSIGNED INTEGER);
-> 0
If you don't use CAST(), a lexical string comparison is done:
mysql> SELECT 0xFEFF < 0xFF;
-> 1
Using binary items in a numeric context or comparing them using the = operator should work as
before. (The --new option can be used from 4.0.13 on to make a 4.0 server behave as 4.1 in this
respect.)
•
Incompatible change: Before MySQL 4.1.1, the statement parser was less strict and its stringto-date conversion would ignore everything up to the first digit. As a result, invalid statements
129
Installing MySQL
such as the following were accepted:
INSERT INTO t (datetime_col) VALUES ('stuff 2005-02-11 10:17:01');
As of MySQL 4.1.1, the parser is more strict and treats the string as an invalid date, so the preceding statement results in a warning.
•
Incompatible change: In MySQL 4.1.2, the Type column in the output from SHOW TABLE
STATUS was renamed to Engine. This affects applications that identify output columns by
name rather than by position.
•
When using multiple-table DELETE statements, you should use the alias of the tables from
which you want to delete, not the actual table name. For example, instead of doing this:
DELETE test FROM test AS t1, test2 WHERE ...
Do this:
DELETE t1 FROM test AS t1, test2 WHERE ...
This corrects a problem that was present in MySQL 4.0.
•
For functions that produce a DATE, DATETIME, or TIME value, the result returned to the client
is fixed up to have a temporal type. For example, in MySQL 4.1, you get this result:
mysql> SELECT CAST('2001-1-1' AS DATETIME);
-> '2001-01-01 00:00:00'
In MySQL 4.0, the result is different:
mysql> SELECT CAST('2001-1-1' AS DATETIME);
-> '2001-01-01'
•
DEFAULT values no longer can be specified for AUTO_INCREMENT columns. (In 4.0, a DEFAULT value is silently ignored; in 4.1, an error occurs.)
•
LIMIT no longer accepts negative arguments. Use some large number (maximum
18446744073709551615) instead of -1.
•
SERIALIZE is no longer a valid mode value for the sql_mode variable. You should use SET
TRANSACTION ISOLATION LEVEL SERIALIZABLE instead. SERIALIZE is no longer
valid
for
the
--sql-mode
option
for
mysqld,
either.
Use
-transaction-isolation=SERIALIZABLE instead.
C API Changes:
•
Incompatible change: The mysql_shutdown() C API function has an extra parameter as of
MySQL 4.1.3: SHUTDOWN-level. You should convert any mysql_shutdown(X) call you
have in your application to mysql_shutdown(X,SHUTDOWN_DEFAULT). Any third-party
API that links against the C API library must be modified to account for this change or it will
not compile.
•
Some C API calls such as mysql_real_query() return 1 on error, not -1. You may have
to change some old applications if they use constructs like this:
if (mysql_real_query(mysql_object, query, query_length) == -1)
{
printf("Got error");
130
Installing MySQL
}
Change the call to test for a non-zero value instead:
if (mysql_real_query(mysql_object, query, query_length) != 0)
{
printf("Got error");
}
Password-Handling Changes:
The password hashing mechanism has changed in 4.1 to provide better security, but this may cause
compatibility problems if you still have clients that use the client library from 4.0 or earlier. (It is
very likely that you have 4.0 clients in situations where clients connect from remote hosts that have
not yet upgraded to 4.1.) The following list indicates some possible upgrade strategies. They represent various tradeoffs between the goal of compatibility with old clients and the goal of security.
•
Only upgrade the client to use 4.1 client libraries (not the server). No behavior changes (except
the return value of some API calls), but you cannot use any of the new features provided by the
4.1 client/server protocol, either. (MySQL 4.1 has an extended client/server protocol that offers
such features as prepared statements and multiple result sets.) See Section 23.2.4, “C API Prepared Statements”.
•
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. A pure-4.1 installation is the most secure.
Further background on password hashing with respect to client authentication and password-changing operations may be found in Section 5.6.9, “Password Hashing in MySQL 4.1” and Section A.2.3, “Client does not support authentication protocol”.
2.10.4. Upgrading from Version 3.23 to 4.0
In general, you should do the following when upgrading to MySQL 4.0 from 3.23:
•
Check the items in the change list found later in this section to see whether any of them might
affect your applications. Note particularly any that are marked Incompatible change; these result in incompatibilities with earlier versions of MySQL.
•
Read the 4.0 news items to see what significant new features you can use in 4.0. See Section E.3, “Changes in release 4.0.x (Production)”.
•
If you are running MySQL Server on Windows, see Section 2.3.15, “Upgrading MySQL on
Windows”.
•
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.10.8, “Upgrading
the Grant Tables”.
•
If you are using replication, see Section 6.6, “Upgrading a Replication Setup” for information on
upgrading your replication setup.
•
Edit any MySQL startup scripts or option files to not use any of the deprecated options de131
Installing MySQL
scribed later in this section.
•
Convert your old ISAM files to MyISAM files. One way to do this is with the
mysql_convert_table_format script. (This is a Perl script; it requires that DBI be installed.) To convert the tables in a given database, use this command:
shell> mysql_convert_table_format database db_name
Note that this should be used only if all tables in the given database are ISAM or MyISAM
tables. To avoid converting tables of other types to MyISAM, you can explicitly list the names of
your ISAM tables after the database name on the command line.
Individual tables can be changed to MyISAM by using the following ALTER TABLE statement
for each table to be converted:
mysql> ALTER TABLE tbl_name TYPE=MyISAM;
If you are not sure of the table type for a given table, use this statement:
mysql> SHOW TABLE STATUS LIKE 'tbl_name';
•
Ensure that you don't have any MySQL clients that use shared libraries (like the Perl
DBD::mysql module). If you do, you should recompile them, because the data structures used
in libmysqlclient.so have changed. The same applies to other MySQL interfaces as well,
such as the Python MySQLdb module.
MySQL 4.0 works even if you don't perform the preceding actions, but you cannot use the new security privileges in MySQL 4.0 and you may run into problems when upgrading later to MySQL 4.1
or newer. The ISAM file format still works in MySQL 4.0, but is deprecated and is not compiled in
by default as of MySQL 4.1. MyISAM tables should be used instead.
Old clients should work with a MySQL 4.0 server without any problems.
Even if you perform the preceding actions, you can still downgrade to MySQL 3.23.52 or newer if
you run into problems with the MySQL 4.0 series. In this case, you must use mysqldump to dump
any tables that use full-text indexes and reload the dump file into the 3.23 server. This is necessary
because 4.0 uses a new format for full-text indexing.
The following lists describe changes that may affect applications and that you should watch out for
when upgrading to version 4.0.
Server Changes:
•
As of MySQL 4.0.24, the server by default no longer loads user-defined functions unless they
have at least one auxiliary symbol defined in addition to the main function symbol. This behavior can be overridden with the --allow-suspicious-udfs option. See Section 25.2.3.6,
“User-defined Function Security Precautions”.
•
MySQL 4.0 has a lot of new privileges in the mysql.user table. See Section 5.6.3,
“Privileges Provided by MySQL”.
To get these new privileges to work, you must update the grant tables. The procedure is described in Section 2.10.8, “Upgrading the Grant Tables”. Until you do this, all accounts have the
SHOW DATABASES, CREATE TEMPORARY TABLES, and LOCK TABLES privileges. SUPER and EXECUTE privileges take their value from PROCESS. REPLICATION SLAVE and
REPLICATION CLIENT take their values from FILE.
If you have any scripts that create new MySQL user accounts, you may want to change them to
use the new privileges. If you are not using GRANT commands in the scripts, this is a good time
132
Installing MySQL
to change your scripts to use GRANT instead of modifying the grant tables directly.
From version 4.0.2 on, the option --safe-show-database is deprecated (and no longer
does anything). See Section 5.5.3, “Startup Options for mysqld Concerning Security”.
If you get Access denied errors for new users in version 4.0.2 and up, you should check
whether you need some of the new grants that you didn't need before. In particular, you need
REPLICATION SLAVE (instead of FILE) for new slave servers.
•
safe_mysqld has been renamed to mysqld_safe. For backward compatibility, binary distributions will for some time include safe_mysqld as a symlink to mysqld_safe.
•
InnoDB support is included by default in binary distributions. If you build MySQL from
source, InnoDB is configured in by default. If you do not use InnoDB and want to save
memory when running a server that has InnoDB support enabled, use the --skip-innodb
server startup option. To compile MySQL without InnoDB support, run configure with the
--without-innodb option.
•
Values for the startup parameters myisam_max_extra_sort_file_size and myisam_max_extra_sort_file_size are given in bytes (they were given in megabytes before 4.0.3).
•
mysqld has the option --temp-pool enabled by default because this gives better performance with some operating systems (most notably Linux).
•
The mysqld startup options --skip-locking and --enable-locking were renamed to
--skip-external-locking and --external-locking.
•
External system locking of MyISAM/ISAM files is turned off by default. You can turn this on
with --external-locking. (However, this is never needed for most users.)
•
The following startup variables and options have been renamed:
Old Name
New Name
myisam_bulk_insert_tree_size
bulk_insert_buffer_size
query_cache_startup_type
query_cache_type
record_buffer
read_buffer_size
record_rnd_buffer
read_rnd_buffer_size
sort_buffer
sort_buffer_size
warnings
log-warnings
--err-log
--log-error (for mysqld_safe)
The startup options record_buffer, sort_buffer, and warnings still work in MySQL
4.0 but are deprecated.
SQL Changes:
•
The following SQL variables have been renamed:
Old Name
New Name
SQL_BIG_TABLES
BIG_TABLES
SQL_LOW_PRIORITY_UPDATES
LOW_PRIORITY_UPDATES
SQL_MAX_JOIN_SIZE
MAX_JOIN_SIZE
SQL_QUERY_CACHE_TYPE
QUERY_CACHE_TYPE
133
Installing MySQL
The old names still work in MySQL 4.0 but are deprecated.
•
You have to use SET GLOBAL SQL_SLAVE_SKIP_COUNTER=skip_count instead of
SET SQL_SLAVE_SKIP_COUNTER=skip_count.
•
SHOW MASTER STATUS returns an empty set if binary logging is not enabled.
•
SHOW SLAVE STATUS returns an empty set if the slave is not initialized.
•
SHOW INDEX has two more columns than it had in 3.23 (Null and Index_type).
•
The format of SHOW OPEN TABLES has changed.
•
ORDER BY col_name DESC sorts NULL values last, as of MySQL 4.0.11. In 3.23 and in
earlier 4.0 versions, this was not always consistent.
•
CHECK, LOCALTIME, and LOCALTIMESTAMP are reserved words.
•
DOUBLE and FLOAT columns honor the UNSIGNED flag on storage (before, UNSIGNED was
ignored for these columns).
•
The result of all bitwise operators (|, &, <<, >>, and ~) is unsigned. This may cause problems if
you are using them in a context where you want a signed result. See Section 12.8, “Cast Functions and Operators”.
Note: When you use subtraction between integer values where one is of type UNSIGNED, the
result is unsigned. In other words, before upgrading to MySQL 4.0, you should check your application for cases in which you are subtracting a value from an unsigned entity and want a negative answer or subtracting an unsigned value from an integer column. You can disable this behavior by using the --sql-mode=NO_UNSIGNED_SUBTRACTION option when starting
mysqld. See Section 5.3.2, “The Server SQL Mode”.
•
You should use integers to store values in BIGINT columns (instead of using strings, as you did
in MySQL 3.23). Using strings still works, but using integers is more efficient.
•
In MySQL 3.23, INSERT INTO ... SELECT always had IGNORE enabled. As of 4.0.1,
MySQL stops (and possibly rolls back) by default in case of an error unless you specify IGNORE.
•
You should use TRUNCATE TABLE when you want to delete all rows from a table and you
don't need to obtain a count of the number of rows that were deleted. (DELETE FROM
tbl_name returns a row count in 4.0 and doesn't reset the AUTO_INCREMENT counter, and
TRUNCATE TABLE is faster.)
•
You get an error if you have an active transaction or LOCK TABLES statement when trying to
execute TRUNCATE TABLE or DROP DATABASE.
•
To use MATCH ... AGAINST (... IN BOOLEAN MODE) full-text searches with your
tables, you must rebuild their indexes with REPAIR TABLE tbl_name USE_FRM. If you
attempt a boolean full-text search without rebuilding the indexes this way, the search returns incorrect results. See Section 12.7.4, “Fine-Tuning MySQL Full-Text Search”.
•
LOCATE() and INSTR() are case sensitive if one of the arguments is a binary string. Otherwise they are case insensitive.
•
STRCMP() uses the current character set when performing comparisons. This makes the default
comparison behavior not case sensitive unless one or both of the operands are binary strings.
•
HEX(str) returns the characters in str converted to hexadecimal. If you want to convert a
number to hexadecimal, you should ensure that you call HEX() with a numeric argument.
•
RAND(seed) returns a different random number series in 4.0 than in 3.23; this was done to
further differentiate RAND(seed) and RAND(seed+1).
134
Installing MySQL
•
The default type returned by IFNULL(A,B) is set to be the more “general” of the types of A
and B. (The general-to-specific order is string, REAL, INTEGER).
C API Changes:
•
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.
•
Multi-threaded clients should use mysql_thread_init() and mysql_thread_end().
See Section 23.2.15, “How to Make a Threaded Client”.
Other Changes:
•
If you want to recompile the Perl DBD::mysql module, use a recent version. Version 2.9003 is
recommended. Versions older than 1.2218 should not be used because they use the deprecated
mysql_drop_db() call.
2.10.5. Upgrading from Version 3.22 to 3.23
MySQL 3.22 and 3.21 clients work without any problems with a MySQL 3.23 server.
When upgrading to MySQL 3.23 from an earlier version, note the following changes:
Table Changes:
•
MySQL 3.23 supports tables of the new MyISAM type and the old ISAM type. By default, all
new tables are created with type MyISAM unless you start mysqld with the -default-table-type=isam option. You don't have to convert your old ISAM tables to
use them with MySQL 3.23. You can convert an ISAM table to MyISAM format with ALTER
TABLE tbl_name TYPE=MyISAM or the Perl script mysql_convert_table_format.
•
All tables that use the tis620 character set must be fixed with myisamchk -r or REPAIR
TABLE.
•
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.
Client Program Changes:
•
The MySQL client mysql is by default started with the --no-named-commands (-g) option. This option can be disabled with --enable-named-commands (-G). This may cause
incompatibility problems in some cases---for example, in SQL scripts that use named commands
without a semicolon. Long format commands still work from the first line.
•
If you want your mysqldump files to be compatible between MySQL 3.22 and 3.23, you
should not use the --opt or --all option to mysqldump.
SQL Changes:
135
Installing MySQL
•
If you do a DROP DATABASE on a symbolically linked database, both the link and the original
database are deleted. This didn't happen in MySQL 3.22 because configure didn't detect the
availability of the readlink() system call.
•
OPTIMIZE TABLE works only for MyISAM tables. For other table types, you can use ALTER
TABLE to optimize the table. During OPTIMIZE TABLE, the table is locked to prevent it from
being used by other threads.
•
Date functions that work on parts of dates (such as MONTH()) return 0 for 0000-00-00 dates.
In MySQL 3.22, these functions returned NULL.
•
The default return type of IF() depends on both arguments, not just the first one.
•
AUTO_INCREMENT columns should not be used to store negative numbers. The reason for this
is that negative numbers caused problems when wrapping from -1 to 0. You should not store 0
in AUTO_INCREMENT columns, either; CHECK TABLE complains about 0 values because they
may change if you dump and restore the table. AUTO_INCREMENT for MyISAM tables is
handled at a lower level and is much faster than before. In addition, for MyISAM tables, old
numbers are not reused, even if you delete rows from the table.
•
CASE, DELAYED, ELSE, END, FULLTEXT, INNER, RIGHT, THEN, and WHEN are reserved
words.
•
FLOAT(p) is a true floating-point type and not a value with a fixed number of decimals.
•
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 be of one of the following formats:
[H]H:]MM:]SS[.fraction] or [[[[[H]H]H]H]MM]SS[.fraction].
•
LIKE compares strings using the same character comparison rules as for the = operator. If you
require
the
old
behavior,
you
can
compile
MySQL
with
the
CXXFLAGS=-DLIKE_CMP_TOUPPER flag.
•
REGEXP is case insensitive if neither of the strings is a binary string.
•
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.
•
Check all your calls to DATE_FORMAT() to make sure that there is a ‘%’ before each format
character.
•
In MySQL 3.22, the output of SELECT DISTINCT ... was almost always sorted. In
MySQL 3.23, you must use GROUP BY or ORDER BY to obtain sorted output.
•
SUM() returns NULL instead of 0 if there are no matching rows. This is required by standard
SQL.
•
An AND or OR with NULL values returns NULL instead of 0. This mostly affects queries that use
NOT on an AND/OR expression as NOT NULL = NULL.
•
LPAD() and RPAD() shorten the result string if it's longer than the length argument.
[[[DAYS]
C API Changes:
•
mysql_fetch_fields_direct() is a function instead of a macro. It returns a pointer to a
MYSQL_FIELD instead of a MYSQL_FIELD.
•
mysql_num_fields() cannot be used on a MYSQL* object (it's a function that takes a
MYSQL_RES* value as an argument). With a MYSQL* object, you should use
mysql_field_count() instead.
136
Installing MySQL
2.10.6. 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 use the new way to store the date. You
can't access these new columns from an old version of mysqld.
When upgrading to MySQL 3.23 from an earlier version, note the following changes:
•
After installing MySQL Version 3.22, you should start the new server and then run the
mysql_fix_privilege_tables script. This adds the new privileges that you need to use
the GRANT command. If you forget this, you get Access denied when you try to use ALTER
TABLE, CREATE INDEX, or DROP INDEX. The procedure for updating the grant tables is described in Section 2.10.8, “Upgrading the Grant Tables”.
•
The C API interface to mysql_real_connect() has changed. If you have an old client program that calls this function, you must pass 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.10.7. 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 server uses the old pre-3.21 password()
checking rather than the new method. Also, the new client function mysql_errno() does not return any server error, only CR_UNKNOWN_ERROR. The function does work for client errors.
If you are not using the --old-protocol option to mysqld, you need to make the following
changes:
•
All client code must be recompiled. If you are using ODBC, you must get the MyODBC 2.x
driver.
•
The scripts/add_long_password script must be run to convert 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 3.20.28 and above can handle the new user table format without affecting clients. If you
have a MySQL version earlier than 3.20.28, passwords no longer work with it if you convert the
user table. So to be safe, you should first upgrade to at least Version 3.20.28 and then upgrade to
Version 3.21.
The new client code works with a 3.20.x mysqld server, so if you experience problems with
3.21.x, you can use the old 3.20.x server without having to recompile the clients again.
If you are not using the --old-protocol option to mysqld, old clients are unable to connect
and should issue the following error message:
ERROR: Protocol mismatch. Server Version = 10 Client Version = 9
137
Installing MySQL
The Perl DBI interface also supports the old mysqlperl interface. The only change you have to
make if you use mysqlperl is to change the arguments to the connect() function. The new arguments are: host, database, user, and password (note that the user and password arguments have changed places).
The following changes may affect queries in old applications:
•
HAVING must be specified before any ORDER BY clause.
•
The parameters to LOCATE() have been swapped.
•
There are some new reserved words. The most noticeable are DATE, TIME, and TIMESTAMP.
2.10.8. Upgrading the Grant Tables
Some releases introduce changes to the structure of the grant tables (the tables in the mysql database) to add new privileges or features. To make sure that your grant tables are current when you
update to a new version of MySQL, you should update your grant tables as well. First make a
backup of your mysql database, and then use the following procedure.
On Unix or Unix-like systems, update
mysql_fix_privilege_tables script:
the
grant
tables
by
running
the
shell> mysql_fix_privilege_tables
You must run this script while the server is running. It attempts to connect to the server running on
the local host as root. If your root account requires a password, indicate the password on the
command line. For MySQL 4.1 and up, specify the password like this:
shell> mysql_fix_privilege_tables --password=root_password
Prior to MySQL 4.1, specify the password like this:
shell> mysql_fix_privilege_tables root_password
The mysql_fix_privilege_tables script performs any actions necessary to convert your
grant tables to the current format. You might see some Duplicate column name warnings as
it runs; you can ignore them.
After running the script, stop the server and restart it.
On Windows systems, there isn't an easy way to update the grant tables until MySQL 4.0.15. From
version 4.0.15 on, MySQL distributions include a mysql_fix_privilege_tables.sql SQL
script that you can run using the mysql client. If your MySQL installation is located at
C:\mysql, the commands look like this:
C:\> C:\mysql\bin\mysql -u root -p mysql
mysql> SOURCE C:/mysql/scripts/mysql_fix_privilege_tables.sql
If your installation is located in some other directory, adjust the pathnames appropriately.
The mysql command will prompt you for the root password; enter it when prompted.
As with the Unix procedure, you might see some Duplicate column name warnings as
mysql processes the statements in the mysql_fix_privilege_tables.sql script; you can
ignore them.
138
Installing MySQL
After running the script, stop the server and restart it.
If you are upgrading to MySQL 5.0.1 or later, the grant table upgrade procedure just described adds
view-related columns for the CREATE VIEW and SHOW VIEW privileges. These privileges exist at
the global and database levels. Their initial values are assigned as follows:
•
In MySQL 5.0.2 or later, mysql_fix_privilege_tables copies the Create_priv
value in the user table to the Create_view_priv and Show_view_priv columns.
•
In 5.0.1, the view-related privileges are not enabled for any accounts, so you cannot immediately
use GRANT to give them to accounts that should have them. To deal with this, first connect to
the server as root and issue the following statements to give the privileges to the root accounts manually with UPDATE:
mysql> UPDATE mysql.user SET Show_view_priv = 'Y', Create_view_priv = 'Y'
-> WHERE User = 'root';
mysql> FLUSH PRIVILEGES;
After this, root can use GRANT to give the view privileges to other accounts. Note: You should
issue the statements just shown, GRANT ALL does not work at the global and database levels,
because GRANT requires that you actually possess the privileges you are granting.
2.10.9. Copying MySQL Databases to Another Machine
If you are using MySQL 3.23 or later, you can copy the .frm, .MYI, and .MYD files for MyISAM
tables between different architectures that support the same floating-point format. (MySQL takes
care of any byte-swapping issues.) See Section 14.1, “The MyISAM Storage Engine”.
The MySQL ISAM data and index files (.ISD and *.ISM, respectively) are architecture dependent
and in some cases operating system dependent. If you want to move your applications to another
machine that has a different architecture or operating system than your current machine, you should
not try to move a database by simply copying the files to the other machine. Use mysqldump instead.
By default, mysqldump creates a file containing SQL statements. You can then transfer the file to
the other machine and feed it as input to the mysql client.
Try mysqldump --help to see what options are available. If you are moving the data to a newer
version of MySQL, you should use mysqldump --opt to take advantage of any optimizations
that result in a dump file that is smaller and can be processed faster.
The easiest (although not the fastest) way to move a database between two machines is to run the
following commands on the machine on which the database is located:
shell> mysqladmin -h 'other_hostname' create db_name
shell> mysqldump --opt db_name | mysql -h 'other_hostname' db_name
If you want to copy a database from a remote machine over a slow network, you can use:
shell> mysqladmin create db_name
shell> mysqldump -h 'other_hostname' --opt --compress db_name | mysql db_name
You can also store the result in a file, then transfer the file to the target machine and load the file into the database there. For example, you can dump a database to a file on the source machine like
this:
shell> mysqldump --quick db_name | gzip > db_name.contents.gz
139
Installing MySQL
(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
shell> cat DUMPDIR/*.sql | mysql db_name
shell> mysqlimport db_name DUMPDIR/*.txt
# create database
# create tables in database
# load data into tables
Also, don't forget to copy the mysql database because that is where the user, db, and host grant
tables are stored. You might have to run commands as the MySQL root user on the new machine
until you have the mysql database in place.
After you import the mysql database on the new machine, execute mysqladmin flushprivileges so that the server reloads the grant table information.
2.11. Downgrading MySQL
This section describes what you should do if you are downgrading to an older MySQL version in the
unlikely case that the previous version worked better than the new one.
If you are downgrading within the same release series (for example, from 4.0.20 to 4.0.19) the general rule is that you just have to install the new binaries on top of the old ones. There is no need to
do anything with the databases. As always, however, it's always a good idea to make a backup.
The following items form a checklist of things you should do whenever you perform an downgrade:
•
Read the upgrading section for the release series from which you are downgrading to be sure
that it doesn't have any features you really need. Section 2.10, “Upgrading MySQL”.
•
If there is a downgrading section for that version, please read it, too!
You can always move the MySQL format files and data files between different versions on the same
architecture as long as you stay within versions for the same release series of MySQL. The current
production release series is 4.1.
If you downgrade from one release series to another, there may be incompatibilities in table storage
formats. In this case, you can use mysqldump to dump your tables before downgrading. After
downgrading, reload the dump file using mysql or mysqlimport to re-create your tables. See
Section 2.10.9, “Copying MySQL Databases to Another Machine” for examples.
The normal symptom of a downward-incompatible table format change when you downgrade is that
you can't open tables. In that case, use the following procedure:
1.
Stop the older MySQL server that you are trying to downgrade to.
140
Installing MySQL
2.
Restart the newer MySQL server you are trying to downgrade from.
3.
Dump any tables that were inaccessible to the older server by using mysqldump to create a
dump file.
4.
Stop the newer MySQL server and restart the older one.
5.
Reload the dump file into the older server. Your tables should be accessible.
2.11.1. Downgrading to 4.1
After downgrading from MySQL 5.0, you may see the following information in the mysql.err
file:
Incorrect information in file: './mysql/user.frm'
In this case, you can do the following:
1.
Start MySQL 5.0.4 (or newer).
2.
Run mysql_fix_privilege_tables, which will change the mysql.user table to a
format that both MySQL 4.1 and 5.0 can use.
3.
Stop the MySQL server.
4.
Start MySQL 4.1.
If the preceding procedure fails, then you should be able to do the following instead:
1.
Start MySQL 5.0.4 (or newer).
2.
Run mysqldump --opt --add-drop-table mysql > /tmp/mysql.dump.
3.
Stop the MySQL server.
4.
Start MySQL 4.1 with the --skip-grant option.
5.
Run mysql mysql < /tmp/mysql.dump.
6.
Run mysqladmin flush-privileges.
2.11.2. Downgrading to 4.0
The table format in 4.1 changed to include more and new character set information. Because of this,
you must use mysqldump to dump any tables you have created with the newer MySQL server. For
example, if all the tables in a particular database need to be dumped to be reverted back to MySQL
4.0 format, use this command:
shell> mysqldump --create-options --compatible=mysql40 db_name > dump_file
Then stop the newer server, restart the older server, and read in the dump file:
shell> mysql db_name < dump_file
In the special case that you're downgrading MyISAM tables, no special treatment is necessary if all
columns in the tables contain only numeric columns or string columns (CHAR, VARCHAR, TEXT,
141
Installing MySQL
and so forth) that contain only latin1 data. Your 4.1 tables should be directly usable with a 4.0
server.
If you used the mysql_fix_privilege_tables script to upgrade the grant tables, you can
either use the preceding method to convert them to back to MySQL 4.0 or do the following in
MySQL 4.1 (or above):
ALTER
ALTER
ALTER
ALTER
ALTER
ALTER
TABLE
TABLE
TABLE
TABLE
TABLE
TABLE
mysql.user CONVERT TO CHARACTER SET latin1 COLLATE latin1_swedish_ci
mysql.db CONVERT TO CHARACTER SET latin1 COLLATE latin1_swedish_ci;
mysql.host CONVERT TO CHARACTER SET latin1 COLLATE latin1_swedish_ci
mysql.tables_priv CONVERT TO CHARACTER SET latin1 COLLATE latin1_swe
mysql.columns_priv CONVERT TO CHARACTER SET latin1 COLLATE latin1_sw
mysql.func CONVERT TO CHARACTER SET latin1 COLLATE latin1_swedish_ci
2.12. Operating System-Specific Notes
2.12.1. Linux Notes
This section discusses issues that have been found to occur on Linux. The first few subsections describe general operating system-related issues, problems that can occur when using binary or source
distributions, and post-installation issues. The remaining subsections discuss problems that occur
with Linux on specific platforms.
Note that most of these problems occur on older versions of Linux. If you are running a recent version, you may see none of them.
2.12.1.1. Linux Operating System Notes
MySQL needs at least Linux Version 2.0.
Warning: We have seen some strange problems with Linux 2.2.14 and MySQL on SMP systems.
We also have reports from some MySQL users that they have encountered serious stability problems
using MySQL with kernel 2.2.14. If you are using this kernel, you should upgrade to 2.2.19 (or newer) or to a 2.4 kernel. If you have a multiple-CPU box, then you should seriously consider using 2.4
because it gives you a significant speed boost. Your system should be more stable.
When using LinuxThreads, you should see a minimum of three mysqld processes running. These
are in fact threads. There is one thread for the LinuxThreads manager, one thread to handle connections, and one thread to handle alarms and signals.
2.12.1.2. Linux Binary Distribution Notes
The Linux-Intel binary and RPM releases of MySQL are configured for the highest possible speed.
We are always trying to use the fastest stable compiler available.
The binary release is linked with -static, which means you do not normally need to worry about
which version of the system libraries you have. You need not install LinuxThreads, either. A program linked with -static is slightly larger than a dynamically linked program, but also slightly
faster (3-5%). However, one problem with a statically linked program is that you can't use userdefined functions (UDFs). If you are going to write or use UDFs (this is something for C or C++
programmers only), you must compile MySQL yourself using dynamic linking.
A known issue with binary distributions is that on older Linux systems that use libc (such as Red
Hat 4.x or Slackware), you get some non-fatal problems with hostname resolution. If your system
uses libc rather than glibc2, you probably will encounter some difficulties with hostname resolution and getpwnam(). This happens because glibc unfortunately depends on some external
libraries to implement hostname resolution and getpwent(), even when compiled with static. These problems manifest themselves in two ways:
•
You may see the following error message when you run mysql_install_db:
142
Installing MySQL
Sorry, the host 'xxxx' could not be looked up
You can deal with this by executing mysql_install_db --force, which does not execute the resolveip test in mysql_install_db. The downside is that you can't use hostnames in the grant tables: Except for localhost, you must use IP numbers instead. If you are
using an old version of MySQL that doesn't support --force, you must manually remove the
resolveip test in mysql_install using an editor.
•
You also may see the following error when you try to run mysqld with the --user option:
getpwnam: No such file or directory
To work around this, start mysqld by using the su command rather than by specifying the -user option. This causes the system itself to change the user ID of the mysqld process so
that mysqld need not do so.
Another solution, which solves both problems, is to not use a binary distribution. Get a MySQL
source distribution (in RPM or tar.gz format) and install that instead.
On some Linux 2.2 versions, you may get the error Resource temporarily unavailable
when clients make a lot of new connections to a mysqld server over TCP/IP. The problem is that
Linux has a delay between the time that you close a TCP/IP socket and the time that the system actually frees it. There is room for only a finite number of TCP/IP slots, so you encounter the resource-unavailable error if clients attempt too many new TCP/IP connections during a short time.
For example, you may see the error when you run the MySQL test-connect benchmark over
TCP/IP.
We have inquired about this problem a few times on different Linux mailing lists but have never
been able to find a suitable resolution. The only known “fix” is for the clients to use persistent connections, or, if you are running the database server and clients on the same machine, to use Unix
socket file connections rather than TCP/IP connections.
2.12.1.3. Linux Source Distribution Notes
The following notes regarding glibc apply only to the situation when you build MySQL yourself.
If you are running Linux on an x86 machine, in most cases it is much better for you to just use our
binary. We link our binaries against the best patched version of glibc we can come up with and
with the best compiler options, in an attempt to make it suitable for a high-load server. For a typical
user, even for setups with a lot of concurrent connections or tables exceeding the 2GB limit, our binary is the best choice in most cases. After reading the following text, if you are in doubt about what
to do, try our binary first to see whether it meets your needs. If you discover that it is not good
enough, then you may want to try your own build. In that case, we would appreciate a note about it
so that we can build a better binary next time.
MySQL uses LinuxThreads on Linux. If you are using an old Linux version that doesn't have
glibc2, you must install LinuxThreads before trying to compile MySQL. You can get
LinuxThreads at http://dev.mysql.com/downloads/os-linux.html.
Note that glibc versions before and including Version 2.1.1 have a fatal bug in
pthread_mutex_timedwait() handling, which is used when you issue INSERT DELAYED
statements. We recommend that you not use INSERT DELAYED before upgrading glibc.
Note that Linux kernel and the LinuxThread library can by default only have 1,024 threads. If you
plan to have more than 1,000 concurrent connections, you need to make some changes to
LinuxThreads:
•
Increase
PTHREAD_THREADS_MAX
in
sysdeps/
unix/sysv/linux/bits/local_lim.h to 4096 and decrease STACK_SIZE in
143
Installing MySQL
linuxthreads/internals.h to 256KB. The paths are relative to the root of glibc.
(Note that MySQL is not stable with around 600-1000 connections if STACK_SIZE is the default of 2MB.)
•
Recompile LinuxThreads to produce a new libpthread.a library, and relink MySQL against
it.
The page http://www.volano.com/linuxnotes.html contains additional information about circumventing thread limits in LinuxThreads.
There is another issue that greatly hurts MySQL performance, especially on SMP systems. The mutex implementation in LinuxThreads in glibc 2.1 is very bad for programs with many threads that
hold the mutex only for a short time. This produces a paradoxical result: If you link MySQL against
an unmodified LinuxThreads, removing processors from an SMP actually improves MySQL performance in many cases. We have made a patch available for glibc 2.1.3 to correct this behavior
(http://www.mysql.com/Downloads/Linux/linuxthreads-2.1-patch).
With glibc 2.2.2, MySQL 3.23.36 uses the adaptive mutex, which is much better than even the
patched one in glibc 2.1.3. Be warned, however, that under some conditions, the current mutex
code in glibc 2.2.2 overspins, which hurts MySQL performance. The likelihood that this condition occurs can be reduced by renicing the mysqld process to the highest priority. We have also
been able to correct the overspin behavior with a patch, available at http://www.mysql.com/Downloads/Linux/linuxthreads-2.2.2.patch. It combines the correction of
overspin, maximum number of threads, and stack spacing all in one. You need to apply it in the
linuxthreads directory with patch -p0 </tmp/linuxthreads-2.2.2.patch. We
hope it is included in some form in future releases of glibc 2.2. In any case, if you link against
glibc 2.2.2, you still need to correct STACK_SIZE and PTHREAD_THREADS_MAX. We hope
that the defaults is corrected to some more acceptable values for high-load MySQL setup in the future, so that the commands needed to produce your own build can be reduced to ./configure;
make; make install.
We recommend that you use these patches to build a special static version of libpthread.a and
use it only for statically linking against MySQL. We know that the patches are safe for MySQL and
significantly improve its performance, but we cannot say anything about other applications. If you
link other applications that require LinuxThreads against the patched static version of the library, or
build a patched shared version and install it on your system, you do so at your own risk.
If you experience any strange problems during the installation of MySQL, or with some common
utilities hanging, it is very likely that they are either library or compiler related. If this is the case,
using our binary resolves them.
If you link your own MySQL client programs, you may see the following error at runtime:
ld.so.1: fatal: libmysqlclient.so.#:
open failed: No such file or directory
This problem can be avoided by one of the following methods:
•
Link clients with the -Wl,r/full/path/to/libmysqlclient.so flag rather than with
-Lpath).
•
Copy libmysqclient.so to /usr/lib.
•
Add the pathname of the directory where libmysqlclient.so is located to the
LD_RUN_PATH environment variable before running your client.
If you are using the Fujitsu compiler (fcc/FCC), you may have some problems compiling MySQL
because the Linux header files are very gcc oriented. The following configure line should work
with fcc/FCC:
144
Installing MySQL
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.12.1.4. Linux Post-Installation Notes
mysql.server can be found in the support-files directory under the MySQL installation
directory or in a MySQL source tree. You can install it as /etc/init.d/mysql for automatic
MySQL startup and shutdown. See Section 2.9.2.2, “Starting and Stopping MySQL Automatically”.
If MySQL can't open enough files or connections, it may be that you haven't configured Linux to
handle enough files.
In Linux 2.2 and onward, you can check the number of allocated file handles as follows:
shell> cat /proc/sys/fs/file-max
shell> cat /proc/sys/fs/dquot-max
shell> cat /proc/sys/fs/super-max
If you have more than 16MB of memory, you should add something like the following to your init
scripts (for example, /etc/init.d/boot.local on SuSE Linux):
echo 65536 > /proc/sys/fs/file-max
echo 8192 > /proc/sys/fs/dquot-max
echo 1024 > /proc/sys/fs/super-max
You can also run the echo commands from the command line as root, but these settings are lost
the next time your computer restarts.
Alternatively, you can set these parameters on startup by using the sysctl tool, which is used by
many Linux distributions (SuSE has added it as well, beginning with SuSE Linux 8.0). Just put the
following values into a file named /etc/sysctl.conf:
# Increase some values for MySQL
fs.file-max = 65536
fs.dquot-max = 8192
fs.super-max = 1024
You should also add the following to /etc/my.cnf:
[mysqld_safe]
open-files-limit=8192
This should allow the server a limit of 8,192 for the combined number of connections and open
files.
The STACK_SIZE constant in LinuxThreads controls the spacing of thread stacks in the address
space. It needs to be large enough so that there is plenty of room for each individual thread stack,
but small enough to keep the stack of some threads from running into the global mysqld data. Unfortunately, as we have experimentally discovered, the Linux implementation of mmap() successfully unmaps a mapped region if you ask it to map out an address currently in use, zeroing out the
data on the entire page instead of returning an error. So, the safety of mysqld or any other threaded
application depends on “gentlemanly” behavior of the code that creates threads. The user must take
145
Installing MySQL
measures to make sure that the number of running threads at any time is sufficiently low for thread
stacks to stay away from the global heap. With mysqld, you should enforce this behavior by setting a reasonable value for the max_connections variable.
If you build MySQL yourself, you can patch LinuxThreads for better stack use. See Section 2.12.1.3, “Linux Source Distribution Notes”. If you do not want to patch LinuxThreads, you
should set max_connections to a value no higher than 500. It should be even less if you have a
large key buffer, large heap tables, or some other things that make mysqld allocate a lot of
memory, or if you are running a 2.2 kernel with a 2GB patch. If you are using our binary or RPM
version 3.23.25 or later, you can safely set max_connections at 1500, assuming no large key
buffer or heap tables with lots of data. The more you reduce STACK_SIZE in LinuxThreads the
more threads you can safely create. We recommend values between 128KB and 256KB.
If you use a lot of concurrent connections, you may suffer from a “feature” in the 2.2 kernel that attempts to prevent fork bomb attacks by penalizing a process for forking or cloning a child. This
causes MySQL not to scale well as you increase the number of concurrent clients. On single-CPU
systems, we have seen this manifested as very slow thread creation: It may take a long time to connect to MySQL (as long as one minute), and it may take just as long to shut it down. On multipleCPU systems, we have observed a gradual drop in query speed as the number of clients increases. In
the process of trying to find a solution, we have received a kernel patch from one of our users who
claimed it made a lot of difference for his site. The patch is available at http://www.mysql.com/Downloads/Patches/linux-fork.patch. We have done rather extensive testing of
this patch on both development and production systems. It has significantly improved MySQL performance without causing any problems and we recommend it to our users who still run high-load
servers on 2.2 kernels.
This issue has been fixed in the 2.4 kernel, so if you are not satisfied with the current performance
of your system, rather than patching your 2.2 kernel, it might be easier to upgrade to 2.4. On SMP
systems, upgrading also gives you a nice SMP boost in addition to fixing the fairness bug.
We have tested MySQL on the 2.4 kernel on a two-CPU machine and found MySQL scales much
better. There was virtually no slowdown on query throughput all the way up to 1,000 clients, and the
MySQL scaling factor (computed as the ratio of maximum throughput to the throughput for one client) was 180%. We have observed similar results on a four-CPU system: Virtually no slowdown as
the number of clients was increased up to 1,000, and a 300% scaling factor. Based on these results,
for a high-load SMP server using a 2.2 kernel, we definitely recommend upgrading to the 2.4 kernel
at this point.
We have discovered that it is essential to run the mysqld process with the highest possible priority
on the 2.4 kernel to achieve maximum performance. This can be done by adding a renice -20
$$ command to mysqld_safe. In our testing on a four-CPU machine, increasing the priority resulted in a 60% throughput increase with 400 clients.
We are currently also trying to collect more information on how well MySQL performs with a 2.4
kernel on four-way and eight-way systems. If you have access such a system and have done some
benchmarks, please send an email message to <[email protected]> with the results. We
will review them for inclusion in the manual.
If you see a dead mysqld server process with ps, this usually means that you have found a bug in
MySQL or you have a corrupted table. See Section A.4.2, “What to Do If MySQL Keeps Crashing”.
To get a core dump on Linux if mysqld dies with a SIGSEGV signal, you can start mysqld with
the --core-file option. Note that you also probably need to raise the core file size by adding
ulimit
-c
1000000 to mysqld_safe or starting mysqld_safe with -core-file-size=1000000. See Section 5.1.3, “mysqld_safe — MySQL Server Startup
Script”.
2.12.1.5. Linux x86 Notes
MySQL requires libc Version 5.4.12 or newer. It's known to work with libc 5.4.46. glibc
Version 2.0.6 and later should also work. There have been some problems with the glibc RPMs
from Red Hat, so if you have problems, check whether there are any updates. The glibc 2.0.7-19
and 2.0.7-29 RPMs are known to work.
146
Installing MySQL
If you are using Red Hat 8.0 or a new glibc 2.2.x library, you may see mysqld die in gethostbyaddr(). This happens because the new glibc library requires a stack size greater than
128KB for this call. To fix the problem, start mysqld with the --thread-stack=192K option.
(Use -O thread_stack=192K before MySQL 4.) This stack size is the default on MySQL
4.0.10 and above, so you should not see the problem.
If you are using gcc 3.0 and above to compile MySQL, you must install the libstdc++v3 library before compiling MySQL; if you don't do this, you get an error about a missing
__cxa_pure_virtual symbol during linking.
On some older Linux distributions, configure may produce an error like this:
Syntax error in sched.h. Change _P to __P in the
/usr/include/sched.h file.
See the Installation chapter in the Reference Manual.
Just do what the error message says. Add an extra underscore to the _P macro name that has only
one underscore, then try again.
You may get some warnings when compiling. Those shown here can be ignored:
mysqld.cc -o objs-thread/mysqld.o
mysqld.cc: In function `void init_signals()':
mysqld.cc:315: warning: assignment of negative value `-1' to
`long unsigned int'
mysqld.cc: In function `void * signal_hand(void *)':
mysqld.cc:346: warning: assignment of negative value `-1' to
`long unsigned int'
If mysqld always dumps core when it starts, the problem may be that you have an old /
lib/libc.a. Try renaming it, then remove sql/mysqld and do a new make install and
try again. This problem has been reported on some Slackware installations.
If you get the following error when linking mysqld, it means that your libg++.a is not installed
correctly:
/usr/lib/libc.a(putc.o): In function `_IO_putc':
putc.o(.text+0x0): multiple definition of `_IO_putc'
You can avoid using libg++.a by running configure like this:
shell> CXX=gcc ./configure
If mysqld crashes immediately and you are running Red Hat Version 5.0 with a version of glibc
older than 2.0.7-5, you should make sure that you have installed all glibc patches. There is a lot of
information about this in the MySQL mail archives, available online at http://lists.mysql.com/.
2.12.1.6. Linux SPARC Notes
In some implementations, readdir_r() is broken. The symptom is that the SHOW DATABASES
statement always returns an empty set. This can be fixed by removing HAVE_READDIR_R from
config.h after configuring and before compiling.
2.12.1.7. Linux Alpha Notes
MySQL 3.23.12 is the first MySQL version that is tested on Linux-Alpha. If you plan to use
MySQL on Linux-Alpha, you should ensure that you have this version or newer.
We have tested MySQL on Alpha with our benchmarks and test suite, and it appears to work nicely.
147
Installing MySQL
We currently build the MySQL binary packages on SuSE Linux 7.0 for AXP, kernel 2.4.4-SMP,
Compaq C compiler (V6.2-505) and Compaq C++ compiler (V6.3-006) on a Compaq DS20 machine with an Alpha EV6 processor.
You can find the preceding compilers at http://www.support.compaq.com/alpha-tools/. By using
these compilers rather than gcc, we get about 9-14% better MySQL performance.
Note that until MySQL version 3.23.52 and 4.0.2, we optimized the binary for the current CPU only
(by using the -fast compile option). This means that for older versions, you can use our Alpha
binaries only if you have an Alpha EV6 processor.
For all following releases, we added the -arch generic flag to our compile options, which
makes sure that the binary runs on all Alpha processors. We also compile statically to avoid library
problems. The configure command looks like this:
CC=ccc CFLAGS="-fast -arch generic" CXX=cxx \
CXXFLAGS="-fast -arch generic -noexceptions -nortti" \
./configure --prefix=/usr/local/mysql --disable-shared \
--with-extra-charsets=complex --enable-thread-safe-client \
--with-mysqld-ldflags=-non_shared --with-client-ldflags=-non_shared
If you want to use egcs, the following configure line worked for us:
CFLAGS="-O3 -fomit-frame-pointer" CXX=gcc \
CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql --disable-shared
Some known problems when running MySQL on Linux-Alpha:
•
Debugging threaded applications like MySQL does not work with gdb 4.18. You should use
gdb 5.1 instead.
•
If you try linking mysqld statically when using gcc, the resulting image dumps core at startup
time. In other words, do not use --with-mysqld-ldflags=-all-static with gcc.
2.12.1.8. Linux PowerPC Notes
MySQL should work on MkLinux with the newest glibc package (tested with glibc 2.0.7).
2.12.1.9. Linux MIPS Notes
To get MySQL to work on Qube2 (Linux Mips), you need the newest glibc libraries. glibc2.0.7-29C2 is known to work. You must also use the egcs C++ compiler (egcs 1.0.2-9, gcc
2.95.2 or newer).
2.12.1.10. Linux IA-64 Notes
To get MySQL to compile on Linux IA-64, we use the following configure command for building with gcc 2.96:
CC=gcc \
CFLAGS="-O3 -fno-omit-frame-pointer" \
CXX=gcc \
CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql \
"--with-comment=Official MySQL binary" \
--with-extra-charsets=complex
148
Installing MySQL
On IA-64, the MySQL client binaries use shared libraries. This means that if you install our binary
distribution at a location other than /usr/local/mysql, you need to add the path of the directory where you have libmysqlclient.so installed either to the /etc/ld.so.conf file or to
the value of your LD_LIBRARY_PATH environment variable.
See Section A.3.1, “Problems Linking to the MySQL Client Library”.
2.12.2. Mac OS X Notes
On Mac OS X, tar cannot handle long filenames. If you need to unpack a .tar.gz distribution,
use gnutar instead.
2.12.2.1. Mac OS X 10.x (Darwin)
MySQL should work without bigger problems on Mac OS X 10.x (Darwin).
The known problems are:
•
The
connection
times
(wait_timeout,
interactive_timeout
and
net_read_timeout) values are not honored. The symptom is that persistent connections can
hang for a very long time without getting closed down and that a 'kill' for a thread will not take
affect until the thread does it a new command
This is probably a signal handling problem in the thread library where the signal doesn't break a
pending read and we hope that a future update to the thread libraries will fix this.
Our binary for Mac OS X is compiled on Darwin 6.3 with the following configure line:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc \
CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql \
--with-extra-charsets=complex --enable-thread-safe-client \
--enable-local-infile --disable-shared
See Section 2.5, “Installing MySQL on Mac OS X”.
2.12.2.2. Mac OS X Server 1.2 (Rhapsody)
For current versions of Mac OS X Server, no operating system changes are necessary before compiling MySQL. Compiling for the Server platform is the same as for the client version of Mac OS X.
(However, note that MySQL comes preinstalled on Mac OS X Server, so you need not build it yourself.)
For older versions (Mac OS X Server 1.2, a.k.a. Rhapsody), you must first install a pthread package
before trying to configure MySQL.
See Section 2.5, “Installing MySQL on Mac OS X”.
2.12.3. Solaris Notes
On Solaris, you may run into trouble even before you get the MySQL distribution unpacked! Solaris
tar can't handle long filenames, so you may see an error like this when you unpack MySQL:
x mysql-3.22.12-beta/bench/Results/ATIS-mysql_odbc-NT_4.0-cmp-db2,
informix,ms-sql,mysql,oracle,solid,sybase, 0 bytes, 0 tape blocks
tar: directory checksum error
149
Installing MySQL
In this case, you must use GNU tar (gtar) to unpack the distribution. You can find a precompiled
copy for Solaris at http://dev.mysql.com/downloads/os-solaris.html.
Sun native threads work only on Solaris 2.5 and higher. For Version 2.4 and earlier, MySQL automatically uses MIT-pthreads. See Section 2.8.5, “MIT-pthreads Notes”.
If you get the following error from configure, it means that you have something wrong with
your compiler installation:
checking for restartable system calls... configure: error can not
run test programs while cross compiling
In this case, you should upgrade your compiler to a newer version. You may also be able to solve
this problem by inserting the following row into the config.cache file:
ac_cv_sys_restartable_syscalls=${ac_cv_sys_restartable_syscalls='no'}
If you are using Solaris on a SPARC, the recommended compiler is gcc 2.95.2 or 3.2. You can find
this at http://gcc.gnu.org/. Note that egcs 1.1.1 and gcc 2.8.1 don't work reliably on SPARC!
The recommended configure line when using gcc 2.95.2 is:
CC=gcc CFLAGS="-O3" \
CXX=gcc CXXFLAGS="-O3 -felide-constructors -fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql --with-low-memory \
--enable-assembler
If you have an UltraSPARC system, you can get 4% better performance by adding -mcpu=v8 Wa,-xarch=v8plusa to the CFLAGS and CXXFLAGS environment variables.
If you have Sun's Forte 5.0 (or newer) compiler, you can run configure like this:
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt" \
CXX=CC CXXFLAGS="-noex -mt" \
./configure --prefix=/usr/local/mysql --enable-assembler
To create a 64-bit binary with Sun's Forte compiler, use the following configuration options:
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt -xarch=v9" \
CXX=CC CXXFLAGS="-noex -mt -xarch=v9" ASFLAGS="-xarch=v9" \
./configure --prefix=/usr/local/mysql --enable-assembler
To create a 64-bit Solaris binary using gcc, add -m64 to CFLAGS and CXXFLAGS and remove -enable-assembler from the configure line. This works only with MySQL 4.0 and up;
MySQL 3.23 does not include the required modifications to support this.
In the MySQL benchmarks, we got a 4% speedup on an UltraSPARC when using Forte 5.0 in 32-bit
mode compared to using gcc 3.2 with the -mcpu flag.
If you create a 64-bit mysqld binary, it is 4% slower than the 32-bit binary, but can handle more
threads and memory.
When using Solaris 10 for x86_64, you should mount any filesystems on which you intend to store
InnoDB files with the forcedirectio option. (By default mounting is done without this option.)
Failing to do so will cause a significant drop in performance when using the InnoDB storage engine
on this platform.
If you get a problem with fdatasync or sched_yield, you can fix this by adding
LIBS=-lrt to the configure line
150
Installing MySQL
For compilers older than WorkShop 5.3, you might have to edit the configure script. Change this
line:
#if !defined(__STDC__) || __STDC__ != 1
To this:
#if !defined(__STDC__)
If you turn on __STDC__ with the -Xc option, the Sun compiler can't compile with the Solaris
pthread.h header file. This is a Sun bug (broken compiler or broken include file).
If mysqld issues the following error message when you run it, you have tried to compile MySQL
with the Sun compiler without enabling the -mt multi-thread option:
libc internal error: _rmutex_unlock: rmutex not held
Add -mt to CFLAGS and CXXFLAGS and recompile.
If you are using the SFW version of gcc (which comes with Solaris 8), you must add /
opt/sfw/lib to the environment variable LD_LIBRARY_PATH before running configure.
If you are using the gcc available from sunfreeware.com, you may have many problems. To
avoid this, you should recompile gcc and GNU binutils on the machine where you are running
them.
If you get the following error when compiling MySQL with gcc, it means that your gcc is not configured for your version of Solaris:
shell> gcc -O3 -g -O2 -DDBUG_OFF -o thr_alarm ...
./thr_alarm.c: In function `signal_hand':
./thr_alarm.c:556: too many arguments to function `sigwait'
The proper thing to do in this case is to get the newest version of gcc and compile it with your current gcc compiler. At least for Solaris 2.5, almost all binary versions of gcc have old, unusable include files that break all programs that use threads, and possibly other programs!
Solaris doesn't provide static versions of all system libraries (libpthreads and libdl), so you
can't compile MySQL with --static. If you try to do so, you get one of the following errors:
ld: fatal: library -ldl: not found
undefined reference to `dlopen'
cannot find -lrt
If you link your own MySQL client programs, you may see the following error at runtime:
ld.so.1: fatal: libmysqlclient.so.#:
open failed: No such file or directory
This problem can be avoided by one of the following methods:
•
Link clients with the -Wl,r/full/path/to/libmysqlclient.so flag rather than with
-Lpath).
•
Copy libmysqclient.so to /usr/lib.
•
Add the pathname of the directory where libmysqlclient.so is located to the
LD_RUN_PATH environment variable before running your client.
151
Installing MySQL
If you have problems with configure trying to link with -lz when you don't have zlib installed, you have two options:
•
If you want to be able to use the compressed communication protocol, you need to get and install zlib from ftp.gnu.org.
•
Run configure with the --with-named-z-libs=no option when building MySQL.
If you are using gcc and have problems with loading user-defined functions (UDFs) into MySQL,
try adding -lgcc to the link line for the UDF.
If you would like MySQL to start automatically, you can copy supportfiles/mysql.server to /etc/init.d and create a symbolic link to it named /
etc/rc3.d/S99mysql.server.
If too many processes try to connect very rapidly to mysqld, you should see this error in the
MySQL log:
Error in accept: Protocol error
You might try starting the server with the --back_log=50 option as a workaround for this. (Use
-O back_log=50 before MySQL 4.)
Solaris doesn't support core files for setuid() applications, so you can't get a core file from
mysqld if you are using the --user option.
2.12.3.1. Solaris 2.7/2.8 Notes
Normally, you can use a Solaris 2.6 binary on Solaris 2.7 and 2.8. Most of the Solaris 2.6 issues also
apply for Solaris 2.7 and 2.8.
MySQL 3.23.4 and above should be able to detect new versions of Solaris automatically and enable
workarounds for the following problems.
Solaris 2.7 / 2.8 has some bugs in the include files. You may see the following error when you use
gcc:
/usr/include/widec.h:42: warning: `getwc' redefined
/usr/include/wchar.h:326: warning: this is the location of the previous
definition
If this occurs, you can fix the problem by copying /usr/include/widec.h to
.../lib/gcc-lib/os/gcc-version/include and changing line 41 from this:
#if
!defined(lint) && !defined(__lint)
To this:
#if
!defined(lint) && !defined(__lint) && !defined(getwc)
Alternatively, you can edit /usr/include/widec.h directly. Either way, after you make the
fix, you should remove config.cache and run configure again.
If you get the following errors when you run make, it's because configure didn't detect the
curses.h file (probably because of the error in /usr/include/widec.h):
In file included from mysql.cc:50:
/usr/include/term.h:1060: syntax error before `,'
/usr/include/term.h:1081: syntax error before `;'
152
Installing MySQL
The solution to this problem is to do one of the following:
•
Configure
with
./configure.
•
Edit /usr/include/widec.h as indicated in the preceding discussion and re-run configure.
•
Remove the #define HAVE_TERM line from the config.h file and run make again.
CFLAGS=-DHAVE_CURSES_H
CXXFLAGS=-DHAVE_CURSES_H
If your linker can't find -lz when linking client programs, the problem is probably that your
libz.so file is installed in /usr/local/lib. You can fix this problem by one of the following
methods:
•
Add /usr/local/lib to LD_LIBRARY_PATH.
•
Add a link to libz.so from /lib.
•
If you are using Solaris 8, you can install the optional zlib from your Solaris 8 CD distribution.
•
Run configure with the --with-named-z-libs=no option when building MySQL.
2.12.3.2. Solaris x86 Notes
On Solaris 8 on x86, mysqld dumps core if you remove the debug symbols using strip.
If you are using gcc or egcs on Solaris x86 and you experience problems with core dumps under
load, you should use the following configure command:
CC=gcc CFLAGS="-O3 -fomit-frame-pointer -DHAVE_CURSES_H" \
CXX=gcc \
CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti -DHAVE_CURSES_H" \
./configure --prefix=/usr/local/mysql
This avoids problems with the libstdc++ library and with C++ exceptions.
If this doesn't help, you should compile a debug version and run it with a trace file or under gdb.
See Section F.1.3, “Debugging mysqld under gdb”.
2.12.4. BSD Notes
This section provides information about using MySQL on variants of BSD Unix.
2.12.4.1. FreeBSD Notes
FreeBSD 4.x or newer is recommended for running MySQL, because the thread package is much
more integrated. To get a secure and stable system, you should use only FreeBSD kernels that are
marked -RELEASE.
The easiest (and preferred) way to install MySQL is to use the mysql-server and mysqlclient ports available at http://www.freebsd.org/. Using these ports gives you the following benefits:
153
Installing MySQL
•
A working MySQL with all optimizations enabled that are known to work on your version of
FreeBSD.
•
Automatic configuration and build.
•
Startup scripts installed in /usr/local/etc/rc.d.
•
The ability to use pkg_info -L to see which files are installed.
•
The ability to use pkg_delete to remove MySQL if you no longer want it on your machine.
It is recommended you use MIT-pthreads on FreeBSD 2.x, and native threads on Versions 3 and up.
It is possible to run with native threads on some late 2.2.x versions, but you may encounter problems shutting down mysqld.
Unfortunately, certain function calls on FreeBSD are not yet fully thread-safe. Most notably, this includes the gethostbyname() function, which is used by MySQL to convert hostnames into IP
addresses. Under certain circumstances, the mysqld process suddenly causes 100% CPU load and
is unresponsive. If you encounter this problem, try to start MySQL using the -skip-name-resolve option.
Alternatively, you can link MySQL on FreeBSD 4.x against the LinuxThreads library, which avoids
a few of the problems that the native FreeBSD thread implementation has. For a very good comparison of LinuxThreads versus native threads, see Jeremy Zawodny's article FreeBSD or Linux for
your MySQL Server? at http://jeremy.zawodny.com/blog/archives/000697.html.
Known problem when using LinuxThreads on FreeBSD is:
•
The
connection
times
(wait_timeout,
interactive_timeout
and
net_read_timeout) values are not honored. The symptom is that persistent connections can
hang for a very long time without getting closed down and that a 'kill' for a thread will not take
affect until the thread does it a new command
This is probably a signal handling problem in the thread library where the signal doesn't break a
pending read. This is supposed to be fixed in FreeBSD 5.0
The MySQL build process requires GNU make (gmake) to work. If GNU make is not available,
you must install it first before compiling MySQL.
The recommended way to compile and install MySQL on FreeBSD with gcc (2.95.2 and up) is:
CC=gcc CFLAGS="-O2 -fno-strength-reduce" \
CXX=gcc CXXFLAGS="-O2 -fno-rtti -fno-exceptions \
-felide-constructors -fno-strength-reduce" \
./configure --prefix=/usr/local/mysql --enable-assembler
gmake
gmake install
cd /usr/local/mysql
bin/mysql_install_db --user=mysql
bin/mysqld_safe &
If you notice that configure uses MIT-pthreads, you should read the MIT-pthreads notes. See
Section 2.8.5, “MIT-pthreads Notes”.
If you get an error from make install that it can't find /usr/include/pthreads, configure didn't detect that you need MIT-pthreads. To fix this problem, remove config.cache,
then re-run configure with the --with-mit-threads option.
Be sure that your name resolver setup is correct. Otherwise, you may experience resolver delays or
failures when connecting to mysqld. Also make sure that the localhost entry in the /
etc/hosts file is correct. The file should start with a line similar to this:
154
Installing MySQL
127.0.0.1
localhost localhost.your.domain
FreeBSD is known to have a very low default file handle limit. See Section A.2.17, “File Not
Found”. Start the server by using the --open-files-limit option for mysqld_safe, or raise
the limits for the mysqld user in /etc/login.conf and rebuild it with cap_mkdb /
etc/login.conf. Also be sure that you set the appropriate class for this user in the password
file if you are not using the default (use chpass mysqld-user-name). See Section 5.1.3,
“mysqld_safe — MySQL Server Startup Script”.
If you have a lot of memory, you should consider rebuilding the kernel to allow MySQL to use more
than 512MB of RAM. Take a look at option MAXDSIZ in the LINT config file for more information.
If you get problems with the current date in MySQL, setting the TZ variable should help. See Appendix G, Environment Variables.
2.12.4.2. NetBSD Notes
To compile on NetBSD, you need GNU make. Otherwise, the build process fails when make tries
to run lint on C++ files.
2.12.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.12.4.4. OpenBSD 2.8 Notes
Our users have reported that OpenBSD 2.8 has a threading bug that causes problems with MySQL.
The OpenBSD Developers have fixed the problem, but as of January 25, 2001, it's only available in
the “-current” branch. The symptoms of this threading bug are slow response, high load, high CPU
usage, and crashes.
If you get an error like Error in accept:: Bad file descriptor or error 9 when trying to open tables or directories, the problem is probably that you have not allocated enough file
descriptors for MySQL.
In this case, try starting mysqld_safe as root with the following options:
mysqld_safe --user=mysql --open-files-limit=2048 &
2.12.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 should help. See Ap155
Installing MySQL
pendix G, Environment Variables.
2.12.4.6. BSD/OS Version 3.x Notes
Upgrade to BSD/OS Version 3.1. If that is not possible, install BSDIpatch M300-038.
Use the following command when configuring MySQL:
env CXX=shlicc++ CC=shlicc2 \
./configure \
--prefix=/usr/local/mysql \
--localstatedir=/var/mysql \
--without-perl \
--with-unix-socket-path=/var/mysql/mysql.sock
The following is also known to work:
env CC=gcc CXX=gcc CXXFLAGS=-O3 \
./configure \
--prefix=/usr/local/mysql \
--with-unix-socket-path=/var/mysql/mysql.sock
You can change the directory locations if you wish, or just use the defaults by not specifying any
locations.
If you have problems with performance under heavy load, try using the -skip-thread-priority option to mysqld. This runs all threads with the same priority. On
BSDI Version 3.1, this gives better performance, at least until BSDI fixes its thread scheduler.
If you get the error virtual memory exhausted while compiling, you should try using
ulimit -v 80000 and running make again. If this doesn't work and you are using bash, try
switching to csh or sh; some BSDI users have reported problems with bash and ulimit.
2.12.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 having asked for that to happen.
The fix is to either upgrade MySQL to at least version 3.23.34 or, after running configure, remove the line #define HAVE_REALPATH from config.h before running make.
Note that this means that you can't symbolically link a database directories to another database directory or symbolic link a table to another database on BSDI. (Making a symbolic link to another
disk is okay).
2.12.5. Other Unix Notes
2.12.5.1. HP-UX Version 10.20 Notes
There are a couple of small problems when compiling MySQL on HP-UX. We recommend that you
use gcc instead of the HP-UX native compiler, because gcc produces better code.
We recommend using gcc 2.95 on HP-UX. Don't use high optimization flags (such as -O6) because they may not be safe on HP-UX.
156
Installing MySQL
The following configure line should work with gcc 2.95:
CFLAGS="-I/opt/dce/include -fpic" \
CXXFLAGS="-I/opt/dce/include -felide-constructors -fno-exceptions \
-fno-rtti" \
CXX=gcc \
./configure --with-pthread \
--with-named-thread-libs='-ldce' \
--prefix=/usr/local/mysql --disable-shared
The following configure line should work with gcc 3.1:
CFLAGS="-DHPUX -I/opt/dce/include -O3 -fPIC" CXX=gcc \
CXXFLAGS="-DHPUX -I/opt/dce/include -felide-constructors \
-fno-exceptions -fno-rtti -O3 -fPIC" \
./configure --prefix=/usr/local/mysql \
--with-extra-charsets=complex --enable-thread-safe-client \
--enable-local-infile --with-pthread \
--with-named-thread-libs=-ldce --with-lib-ccflags=-fPIC
--disable-shared
2.12.5.2. HP-UX Version 11.x Notes
For HP-UX Version 11.x, we recommend MySQL 3.23.15 or later.
Because of some critical bugs in the standard HP-UX libraries, you should install the following
patches before trying to run MySQL on HP-UX 11.0:
PHKL_22840 Streams cumulative
PHNE_22397 ARPA cumulative
This solves the problem of getting EWOULDBLOCK from recv() and EBADF from accept() in
threaded applications.
If you are using gcc 2.95.1 on an unpatched HP-UX 11.x system, you may get the following error:
In file included from /usr/include/unistd.h:11,
from ../include/global.h:125,
from mysql_priv.h:15,
from item.cc:19:
/usr/include/sys/unistd.h:184: declaration of C function ...
/usr/include/sys/pthread.h:440: previous declaration ...
In file included from item.h:306,
from mysql_priv.h:158,
from item.cc:19:
The problem is that HP-UX doesn't define pthreads_atfork() consistently. It has conflicting
prototypes
in
/usr/include/sys/unistd.h:184
and
/usr/include/sys/pthread.h:440.
One solution is to copy /usr/include/sys/unistd.h into mysql/include and edit unistd.h and change it to match the definition in pthread.h. Look for this line:
extern int pthread_atfork(void (*prepare)(), void (*parent)(),
void (*child)());
Change it to look like this:
extern int pthread_atfork(void (*prepare)(void), void (*parent)(void),
void (*child)(void));
157
Installing MySQL
After making the change, the following configure line should work:
CFLAGS="-fomit-frame-pointer -O3 -fpic" CXX=gcc \
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti -O3" \
./configure --prefix=/usr/local/mysql --disable-shared
If you are using MySQL 4.0.5 with the HP-UX compiler, you can use the following command
(which has been tested with cc B.11.11.04):
CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure \
--with-extra-character-set=complex
You can ignore any errors of the following type:
aCC: warning 901: unknown option: `-3': use +help for online
documentation
If you get the following error from configure, verify that you don't have the path to the K&R
compiler before the path to the HP-UX C and C++ compiler:
checking for cc option to accept ANSI C... no
configure: error: MySQL requires an ANSI C compiler (and a C++ compiler).
Try gcc. See the Installation chapter in the Reference Manual.
Another reason for not being able to compile is that you didn't define the +DD64 flags as just described.
Another possibility for HP-UX 11 is to use MySQL binaries for HP-UX 10.20. We have received
reports from some users that these binaries work fine on HP-UX 11.00. If you encounter problems,
be sure to check your HP-UX patch level.
2.12.5.3. IBM-AIX notes
Automatic detection of xlC is missing from Autoconf, so a number of variables need to be set before running configure. The following example uses the IBM compiler:
export
export
export
export
export
export
CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 "
CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192"
CFLAGS="-I /usr/local/include"
LDFLAGS="-L /usr/local/lib"
CPPFLAGS=$CFLAGS
CXXFLAGS=$CFLAGS
./configure --prefix=/usr/local \
--localstatedir=/var/mysql \
--sbindir='/usr/local/bin' \
--libexecdir='/usr/local/bin' \
--enable-thread-safe-client \
--enable-large-files
The preceding options are used to compile the MySQL distribution that can be found at http://www-frec.bull.com/.
If you change the -O3 to -O2 in the preceding configure line, you must also remove the qstrict option. This is a limitation in the IBM C compiler.
If you are using gcc or egcs to compile MySQL, you must use the -fno-exceptions flag, because the exception handling in gcc/egcs is not thread-safe! (This is tested with egcs 1.1.) There
are also some known problems with IBM's assembler that may cause it to generate bad code when
used with gcc.
158
Installing MySQL
We recommend the following configure line with egcs and gcc 2.95 on AIX:
CC="gcc -pipe -mcpu=power -Wa,-many" \
CXX="gcc -pipe -mcpu=power -Wa,-many" \
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql --with-low-memory
The -Wa,-many option is necessary for the compile to be successful. IBM is aware of this problem
but is in no hurry to fix it because of the workaround that is available. We don't know if the fno-exceptions is required with gcc 2.95, but because MySQL doesn't use exceptions and the
option generates faster code, we recommend that you should always use it with egcs / gcc.
If you get a problem with assembler code, try changing the -mcpu=xxx option to match your CPU.
Typically power2, power, or powerpc may need to be used. Alternatively, you might need to
use 604 or 604e. We are not positive but suspect that power would likely be safe most of the
time, even on a power2 machine.
If you don't know what your CPU is, execute a uname -m command. It produces a string that
looks like 000514676700, with a format of xxyyyyyymmss where xx and ss are always 00,
yyyyyy is a unique system ID and mm is the ID of the CPU Planar. A chart of these values can be
found at http://www16.boulder.ibm.com/pseries/en_US/cmds/aixcmds5/uname.htm.
This gives you a machine type and a machine model you can use to determine what type of CPU
you have.
If you have problems with signals (MySQL dies unexpectedly under high load), you may have
found an OS bug with threads and signals. In this case, you can tell MySQL not to use signals by
configuring as follows:
CFLAGS=-DDONT_USE_THR_ALARM CXX=gcc \
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti \
-DDONT_USE_THR_ALARM" \
./configure --prefix=/usr/local/mysql --with-debug \
--with-low-memory
This doesn't affect the performance of MySQL, but has the side effect that you can't kill clients that
are “sleeping” on a connection with mysqladmin kill or mysqladmin shutdown. Instead,
the client dies when it issues its next command.
On some versions of AIX, linking with libbind.a makes getservbyname() dump core. This
is an AIX bug and should be reported to IBM.
For AIX 4.2.1 and gcc, you have to make the following changes.
After configuring, edit config.h and include/my_config.h and change the line that says
this:
#define HAVE_SNPRINTF 1
to this:
#undef HAVE_SNPRINTF
And finally, in mysqld.cc, you need to add a prototype for initgroups().
#ifdef _AIX41
extern "C" int initgroups(const char *,int);
#endif
If you need to allocate a lot of memory to the mysqld process, it's not enough to just use ulimit
159
Installing MySQL
-d unlimited. You may also have to modify mysqld_safe to add a line something like this:
export LDR_CNTRL='MAXDATA=0x80000000'
You can find more information about using a lot of memory
tp://publib16.boulder.ibm.com/pseries/en_US/aixprggd/genprogc/lrg_prg_support.htm.
at
ht-
2.12.5.4. SunOS 4 Notes
On SunOS 4, MIT-pthreads is needed to compile MySQL. This in turn means you need GNU make.
Some SunOS 4 systems have problems with dynamic libraries and libtool. You can use the following configure line to avoid this problem:
./configure --disable-shared --with-mysqld-ldflags=-all-static
When compiling readline, you may get warnings about duplicate defines. These can be ignored.
When compiling mysqld, there are some implicit declaration of function warnings. These can be ignored.
2.12.5.5. Alpha-DEC-UNIX Notes (Tru64)
If you are using egcs 1.1.2 on Digital Unix, you should upgrade to gcc 2.95.2, because egcs on
DEC has some serious bugs!
When compiling threaded programs under Digital Unix, the documentation recommends using the pthread option for cc and cxx and the -lmach -lexc libraries (in addition to -lpthread).
You should run configure something like this:
CC="cc -pthread" CXX="cxx -pthread -O" \
./configure --with-named-thread-libs="-lpthread -lmach -lexc -lc"
When compiling mysqld, you may see a couple of warnings like this:
mysqld.cc: In function void handle_connections()':
mysqld.cc:626: passing long unsigned int *' as argument 3 of
accept(int,sockadddr *, int *)'
You can safely ignore these warnings. They occur because configure can detect only errors, not
warnings.
If you start the server directly from the command line, you may have problems with it dying when
you log out. (When you log out, your outstanding processes receive a SIGHUP signal.) If so, try
starting the server like this:
nohup mysqld [options] &
nohup causes the command following it to ignore any SIGHUP signal sent from the terminal. Alternatively, start the server by running mysqld_safe, which invokes mysqld using nohup for
you. See Section 5.1.3, “mysqld_safe — MySQL Server Startup Script”.
If you get a problem when compiling mysys/get_opt.c, just remove the #define
_NO_PROTO line from the start of that file.
If you are using Compaq's CC compiler, the following configure line should work:
CC="cc -pthread"
CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all -arch host"
CXX="cxx -pthread"
160
Installing MySQL
CXXFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all \
-arch host -noexceptions -nortti"
export CC CFLAGS CXX CXXFLAGS
./configure \
--prefix=/usr/local/mysql \
--with-low-memory \
--enable-large-files \
--enable-shared=yes \
--with-named-thread-libs="-lpthread -lmach -lexc -lc"
gnumake
If you get a problem with libtool when compiling with shared libraries as just shown, when linking mysql, you should be able to get around this by issuing these commands:
cd mysql
/bin/sh ../libtool --mode=link cxx -pthread -O3 -DDBUG_OFF \
-O4 -ansi_alias -ansi_args -fast -inline speed \
-speculate all \ -arch host -DUNDEF_HAVE_GETHOSTBYNAME_R \
-o mysql mysql.o readline.o sql_string.o completion_hash.o \
../readline/libreadline.a -lcurses \
../libmysql/.libs/libmysqlclient.so -lm
cd ..
gnumake
gnumake install
scripts/mysql_install_db
2.12.5.6. Alpha-DEC-OSF/1 Notes
If you have problems compiling and have DEC CC and gcc installed, try running configure like
this:
CC=cc CFLAGS=-O CXX=gcc CXXFLAGS=-O3 \
./configure --prefix=/usr/local/mysql
If you get problems with the c_asm.h file, you can create and use a 'dummy' c_asm.h file with:
touch include/c_asm.h
CC=gcc CFLAGS=-I./include \
CXX=gcc CXXFLAGS=-O3 \
./configure --prefix=/usr/local/mysql
Note that the following problems with the ld program can be fixed by downloading the latest DEC
(Compaq) patch kit from: http://ftp.support.compaq.com/public/unix/.
On OSF/1 V4.0D and compiler "DEC C V5.6-071 on Digital Unix V4.0 (Rev. 878)," the compiler
had some strange behavior (undefined asm symbols). /bin/ld also appears to be broken
(problems with _exit undefined errors occurring while linking mysqld). On this system, we
have managed to compile MySQL with the following configure line, after replacing /bin/ld
with the version from OSF 4.0C:
CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql
With the Digital compiler "C++ V6.1-029," the following should work:
CC=cc -pthread
CFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed \
-speculate all -arch host
CXX=cxx -pthread
CXXFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed \
-speculate all -arch host -noexceptions -nortti
export CC CFLAGS CXX CXXFLAGS
./configure --prefix=/usr/mysql/mysql \
161
Installing MySQL
--with-mysqld-ldflags=-all-static --disable-shared \
--with-named-thread-libs="-lmach -lexc -lc"
In some versions of OSF/1, the alloca() function is broken. Fix this by removing the line in
config.h that defines 'HAVE_ALLOCA'.
The alloca() function also may have an incorrect prototype in /usr/include/alloca.h.
This warning resulting from this can be ignored.
configure
uses
the
following
thread
libraries
automatically:
-with-named-thread-libs="-lpthread -lmach -lexc -lc".
-
When using gcc, you can also try running configure like this:
CFLAGS=-D_PTHREAD_USE_D4 CXX=gcc CXXFLAGS=-O3 ./configure ...
If you have problems with signals (MySQL dies unexpectedly under high load), you may have
found an OS bug with threads and signals. In this case, you can tell MySQL not to use signals by
configuring with:
CFLAGS=-DDONT_USE_THR_ALARM \
CXXFLAGS=-DDONT_USE_THR_ALARM \
./configure ...
This doesn't affect the performance of MySQL, but has the side effect that you can't kill clients that
are “sleeping” on a connection with mysqladmin kill or mysqladmin shutdown. Instead,
the client dies when it issues its next command.
With gcc 2.95.2, you may encounter the following compile error:
sql_acl.cc:1456: Internal compiler error in `scan_region',
at except.c:2566
Please submit a full bug report.
To fix this, you should change to the sql directory and do a cut-and-paste of the last gcc line, but
change -O3 to -O0 (or add -O0 immediately after gcc if you don't have any -O option on your
compile line). After this is done, you can just change back to the top-level directory and run make
again.
2.12.5.7. SGI Irix Notes
If you are using Irix Version 6.5.3 or newer, mysqld is able to create threads only if you run it as a
user that has CAP_SCHED_MGT privileges (such as root) or give the mysqld server this privilege
with the following shell command:
chcap "CAP_SCHED_MGT+epi" /opt/mysql/libexec/mysqld
You may have to undefine some symbols in config.h after running configure and before
compiling.
In some Irix implementations, the alloca() function is broken. If the mysqld server dies on
some SELECT statements, remove the lines from config.h that define HAVE_ALLOC and
HAVE_ALLOCA_H. If mysqladmin create doesn't work, remove the line from config.h
that defines HAVE_READDIR_R. You may have to remove the HAVE_TERM_H line as well.
SGI recommends that you install all the patches on
tp://support.sgi.com/surfzone/patches/patchset/6.2_indigo.rps.html
this
page
as
a
set:
ht-
At the very minimum, you should install the latest kernel rollup, the latest rld rollup, and the latest
libc rollup.
162
Installing MySQL
You definitely need all the POSIX patches on this page, for pthreads support:
http://support.sgi.com/surfzone/patches/patchset/6.2_posix.rps.html
If you get the something like the following error when compiling mysql.cc:
"/usr/include/curses.h", line 82: error(1084):
invalid combination of type
Type the following in the top-level directory of your MySQL source tree:
extra/replace bool curses_bool < /usr/include/curses.h > include/curses.h
make
There have also been reports of scheduling problems. If only one thread is running, performance is
slow. Avoid this by starting another client. This may lead to a two-to-tenfold increase in execution
speed thereafter for the other thread. This is a poorly understood problem with Irix threads; you may
have to improvise to find solutions until this can be fixed.
If you are compiling with gcc, you can use the following configure command:
CC=gcc CXX=gcc CXXFLAGS=-O3 \
./configure --prefix=/usr/local/mysql --enable-thread-safe-client \
--with-named-thread-libs=-lpthread
On Irix 6.5.11 with native Irix C and C++ compilers ver. 7.3.1.2, the following is reported to work
CC=cc CXX=CC CFLAGS='-O3 -n32 -TARG:platform=IP22 -I/usr/local/include \
-L/usr/local/lib' CXXFLAGS='-O3 -n32 -TARG:platform=IP22 \
-I/usr/local/include -L/usr/local/lib' \
./configure --prefix=/usr/local/mysql --with-innodb --with-berkeley-db \
--with-libwrap=/usr/local \
--with-named-curses-libs=/usr/local/lib/libncurses.a
2.12.5.8. SCO UNIX and OpenServer 5.0.x Notes
The current port is tested only on “sco3.2v5.0.5,” “sco3.2v5.0.6,” and “sco3.2v5.0.7” systems.
There has also been a lot of progress on a port to “sco 3.2v4.2.” Open Server 5.0.8(Legend) has native threads and allows files greater than 2GB. The current maximum file size is 2GB.
We have been able to compile MySQL with the following configure command on OpenServer
with gcc 2.95.3.
CC=gcc CXX=gcc ./configure --prefix=/usr/local/mysql \
--enable-thread-safe-client --with-innodb \
--with-openssl --with-vio --with-extra-charsets=complex
gcc is available at ftp://ftp.sco.com/pub/openserver5/opensrc/gnutools-5.0.7Kj.
This development system requires the OpenServer Execution Environment Supplement oss646B on
OpenServer 5.0.6 and oss656B and The OpenSource libraries found in gwxlibs. All OpenSource
tools
are
in
the
opensrc
directory.
They
are
available
at
ftp://ftp.sco.com/pub/openserver5/opensrc/.
We recommend using the latest production release of MySQL.
SCO provides operating system patches at ftp://ftp.sco.com/pub/openserver5 for OpenServer
5.0.[0-6] and ftp://ftp.sco.com/pub/openserverv5/507 for OpenServer 5.0.7.
SCO provides information about security fixes at ftp://ftp.sco.com/pub/security/OpenServer for
163
Installing MySQL
OpenServer 5.0.x.
The maximum file size on an OpenSever 5.0.x system is 2GB.
The total memory which could be allocated for streams buffers, clists and lock records cannot exceed 60MB on OpenServer 5.0.x.
Streams buffers are allocated in units of 4096 byte pages, clists are 70 bytes each, and lock records
are 64 bytes each, so:
(NSTRPAGES * 4096) + (NCLIST * 70) + (MAX_FLCKREC * 64) <= 62914560
Follow this procedure to configure the Database Services option. If you are unsure whether an application requires this, see the documentation provided with the application.
1.
Log in as root.
2.
Enable the SUDS driver by editing the /etc/conf/sdevice.d/suds file. Change the N
in the second field to a Y.
3.
Use mkdev aio or the Hardware/Kernel Manager to enable support for asynchronous I/O
and relink the kernel. To allow users to lock down memory for use with this type of I/O, update
the aiomemlock(F) file. This file should be updated to include the names of users that can use
AIO and the maximum amounts of memory they can lock down.
4.
Many applications use setuid binaries so that you need to specify only a single user. See the
documentation provided with the application to see if this is the case for your application.
After you complete this process, reboot the system to create a new kernel incorporating these
changes.
By default, the entries in /etc/conf/cf.d/mtune are set as follows:
Value
Default
----------NBUF
0
NHBUF
0
NMPBUF
0
MAX_INODE
0
MAX_FILE
0
CTBUFSIZE
128
MAX_PROC
0
MAX_REGION
0
NCLIST
170
MAXUP
100
NOFILES
110
NHINODE
128
NAUTOUP
10
NGROUPS
8
BDFLUSHR
30
MAX_FLCKREC
0
PUTBUFSZ
8000
MAXSLICE
100
ULIMIT
4194303
* Streams Parameters
NSTREAM
64
NSTRPUSH
9
NMUXLINK
192
STRMSGSZ
16384
STRCTLSZ
1024
STRMAXBLK
524288
NSTRPAGES
500
STRSPLITFRAC
80
NLOG
3
NUMSP
64
164
Min
--24
32
12
100
100
0
50
500
120
15
60
64
0
0
1
50
2000
25
2048
Max
--450000
524288
512
64000
64000
256
16000
160000
16640
16000
11000
8192
60
128
300
16000
20000
100
4194303
1
9
1
4096
1024
4096
0
50
3
1
32768
9
4096
524288
1024
524288
8000
100
3
256
Installing MySQL
NUMTIM
16
NUMTRW
16
* Semaphore Parameters
SEMMAP
10
SEMMNI
10
SEMMNS
60
SEMMNU
30
SEMMSL
25
SEMOPM
10
SEMUME
10
SEMVMX
32767
SEMAEM
16384
* Shared Memory Parameters
SHMMAX
524288
SHMMIN
1
SHMMNI
100
FILE
0
NMOUNT
0
NPROC
0
NREGION
0
1
1
8192
8192
10
10
60
10
25
10
10
32767
16384
8192
8192
8192
8192
150
1024
25
32767
16384
131072
1
100
100
4
50
500
2147483647
1
2000
64000
256
16000
160000
We recommend setting these values as follows:
NOFILES should be 4096 or 2048.
MAXUP should be 2048.
To make changes to the kernel, cd to /etc/conf/bin and use ./idtune name parameter
to make the changes. For example, to change SEMMS to 200, execute these commands as root:
# cd /etc/conf/bin
# ./idtune SEMMNS 200
We recommend tuning the system, but the proper parameter values to use depend on the number of
users accessing the application or database and size the of the database (that is, the used buffer
pool). The following affects the kernel parameters defined in /etc/conf/cf.d/stune:
SHMMAX (recommended setting: 128MB) and SHMSEG (recommended setting: 15). These parameters have influence on the MySQL database engine to create user buffer pools.
NOFILES and MAXUP should be at to at least 2048.
MAXPROC should be set to at least 3000/4000 (depends on number of users) or more.
Also is recommended to use following formula to count value for SEMMSL, SEMMNS and SEMMNU:
SEMMSL = 13
The 13 is what has been found to be the best for both Progress and MySQL.
SEMMNS = SEMMSL * number of db servers to be run on the system.
Set SEMMNS to the value of SEMMSL multiplied by the number of db servers (maximum) that you
are running on the system at one time.
SEMMNU = SEMMNS
Set the value of SEMMNU to equal the value of SEMMNS. You could probably set this to 75% of
SEMMNS, but this is a conservative estimate.
You need to at least install the "SCO OpenServer Linker and Application Development Libraries" or
the OpenServer Development System to use gcc. You cannot just use the GCC Dev system without
165
Installing MySQL
installing one of these.
You should get the FSU Pthreads package and install it first. This can be found at http://moss.csc.ncsu.edu/~mueller/ftp/pub/PART/pthreads.tar.gz. You can also get a precompiled
package from ftp://ftp.zenez.com/pub/zenez/prgms/FSU-threads-3.14.tar.gz.
FSU Pthreads can be compiled with SCO Unix 4.2 with tcpip, or using OpenServer 3.0 or Open
Desktop 3.0 (OS 3.0 ODT 3.0) with the SCO Development System installed using a good port of
GCC 2.5.x. For ODT or OS 3.0, you need a good port of GCC 2.5.x. There are a lot of problems
without a good port. The port for this product requires the SCO Unix Development system. Without
it, you are missing the libraries and the linker that is needed. You also need SCO3.2v4.2-includes.tar.gz. This file contains the changes to the SCO Development include
files that are needed to get MySQL to build. You need to replace the existing system include files
with
these
modified
header
files.
They
can
be
obtained
from
ftp://ftp.zenez.com/pub/zenez/prgms/SCO-3.2v4.2-includes.tar.gz.
To build FSU Pthreads on your system, all you should need to do is run GNU make. The Makefile in FSU-threads-3.14.tar.gz is set up to make FSU-threads.
You can run ./configure in the threads/src directory and select the SCO OpenServer option. This command copies Makefile.SCO5 to Makefile. Then run make.
To install in the default /usr/include directory, log in as root, then cd to the thread/src
directory and run make install.
Remember that you must use GNU make when making MySQL.
Note: If you don't start mysqld_safe as root, you should get only the default 110 open files per
process. mysqld writes a note about this in the log file.
With SCO 3.2V4.2, you should use FSU Pthreads version 3.14 or newer. The following configure command should work:
CFLAGS="-D_XOPEN_XPG4" CXX=gcc CXXFLAGS="-D_XOPEN_XPG4" \
./configure \
--prefix=/usr/local/mysql \
--with-named-thread-libs="-lgthreads -lsocket -lgen -lgthreads" \
--with-named-curses-libs="-lcurses"
You may get some problems with some include files. In this case, you can find new SCO-specific
include files at ftp://ftp.zenez.com/pub/zenez/prgms/SCO-3.2v4.2-includes.tar.gz.
You should unpack this file in the include directory of your MySQL source tree.
SCO development notes:
•
MySQL should automatically detect FSU Pthreads and link mysqld with -lgthreads lsocket -lgthreads.
•
The SCO development libraries are re-entrant in FSU Pthreads. SCO claims that its library functions are re-entrant, so they must be re-entrant with FSU Pthreads. FSU Pthreads on OpenServer
tries to use the SCO scheme to make re-entrant libraries.
•
FSU Pthreads (at least the version at ftp::/ftp.zenez.com) comes linked with GNU malloc. If
you encounter problems with memory usage, make sure that gmalloc.o is included in libgthreads.a and libgthreads.so.
•
In FSU Pthreads, the following system calls are pthreads-aware: read(), write(),
getmsg(), connect(), accept(), select(), and wait().
•
The CSSA-2001-SCO.35.2 (the patch is listed in custom as erg711905-dscr_remap security
patch (version 2.0.0)) breaks FSU threads and makes mysqld unstable. You have to remove
this one if you want to run mysqld on an OpenServer 5.0.6 machine.
166
Installing MySQL
•
If you use SCO OpenServer 5, you may need to recompile FSU pthreads with -DDRAFT7 in
CFLAGS. Otherwise, InnoDB may hang at a mysqld startup.
•
SCO provides operating system patches at ftp://ftp.sco.com/pub/openserver5 for OpenServer
5.0.x.
•
SCO
provides
security
fixes
and
libsocket.so.2
at
ftp://ftp.sco.com/pub/security/OpenServer and ftp://ftp.sco.com/pub/security/sse for OpenServer
5.0.x.
•
Pre-OSR506
security
fixes.
Also,
the
telnetd
fix
at
ftp://stage.caldera.com/pub/security/openserver/
or
ftp://stage.caldera.com/pub/security/openserver/CSSA-2001-SCO.10/ as both libsocket.so.2 and libresolv.so.1 with instructions for installing on pre-OSR506 systems.
It's probably a good idea to install these patches before trying to compile/use MySQL.
Beginning with Legend/OpenServer 6.0.0 has native threads and no 2GB file size limit.
2.12.5.9. SCO UnixWare 7.1.x and OpenUNIX 8.0.0 Notes
We recommend using the latest production release of MySQL. Should you choose to use an older
release of MySQL on UnixWare 7.1.x, you must use a version of MySQL at least as recent as
3.22.13 to get fixes for some portability and OS problems.
We have been able to compile MySQL with the following configure command on UnixWare
Version 7.1.x:
CC="cc" CFLAGS="-I/usr/local/include" \
CXX="CC" CXXFLAGS="-I/usr/local/include" \
./configure --prefix=/usr/local/mysql \
--enable-thread-safe-client --with-berkeley-db=./bdb \
--with-innodb --with-openssl --with-extra-charsets=complex
If you want to use gcc, you must use gcc 2.95.3 or newer.
CC=gcc CXX=g++ ./configure --prefix=/usr/local/mysql
The version of Berkeley DB that comes with either UnixWare 7.1.4 or OpenServer 6.0.0 is not used
when building MySQL. MySQL instead uses its own version of Berkeley DB. The configure
command needs to build both a static and a dynamic library in src_directory/
bdb/build_unix/, but it doesn't with MySQL's own BDB version. The workaround is as follows.
1.
Configure as normal for MySQL.
2.
cd bdb/build_unix/
3.
cp -p Makefile to Makefile.sav
4.
Use same options and run ../dist/configure.
5.
Run gmake.
6.
cp -p Makefile.sav Makefile
7.
Change to top source directory and run gmake.
This allows both the shared and dynamic libraries to be made and work.
167
Installing MySQL
SCO provides operating system patches at ftp://ftp.sco.com/pub/unixware7 for UnixWare 7.1.1,
ftp://ftp.sco.com/pub/unixware7/713/ for UnixWare 7.1.3, ftp://ftp.sco.com/pub/unixware7/714/ for
UnixWare 7.1.4, and ftp://ftp.sco.com/pub/openunix8 for OpenUNIX 8.0.0.
SCO provides information about security fixes at ftp://ftp.sco.com/pub/security/OpenUNIX for
OpenUNIX and ftp://ftp.sco.com/pub/security/UnixWare for UnixWare.
By default, the maximum file size on a UnixWare 7.1.1 system is 1GB, but UnixWare 7.1.4 file size
limit is 1 TB with VXFS. Some OS utilities have a limitation of 2GB. The maximum possible file
size on UnixWare 7 is 1TB with VXFS.
On UnixWare 7.1.4 you do not need to do anything to get large file support, but to enable large file
support on prior versions of UnixWare 7.1.x, run fsadm.
#
#
#
#
#
#
#
fsadm -Fvxfs -o largefiles /
fsadm /
* Note
ulimit unlimited
cd /etc/conf/bin
./idtune SFSZLIM 0x7FFFFFFF
./idtune HFSZLIM 0x7FFFFFFF
./idbuild -B
** Note
** Note
* This should report "largefiles".
** 0x7FFFFFFF represents infinity for these values.
Reboot the system using shutdown.
By default, the entries in /etc/conf/cf.d/mtune are set to:
Value
----SVMMLIM
HVMMLIM
SSTKLIM
HSTKLIM
Default
------0x9000000
0x9000000
0x1000000
0x1000000
Min
--0x1000000
0x1000000
0x2000
0x2000
Max
--0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
We recommend setting these values as follows:
SDATLIM
HDATLIM
SSTKLIM
HSTKLIM
SVMMLIM
HVMMLIM
SFNOLIM
HFNOLIM
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
2048
2048
We recommend tuning the system, but the proper parameter values to use depend on the number of
users accessing the application or database and size the of the database (that is, the used buffer
pool). The following affects the kernel parameters defined in /etc/conf/cf.d/stune:
SHMMAX (recommended setting: 128MB) and SHMSEG (recommended setting: 15). These parameters have influence on the MySQL database engine to create user buffer pools.
SFNOLIM and HFNOLIM should be at maximum 2048.
NPROC should be set to at least 3000/4000 (depends on number of users).
Also is recommended to use following formula to count value for SEMMSL, SEMMNS, and SEMMNU:
SEMMSL = 13
168
Installing MySQL
13 is what has been found to be the best for both Progress and MySQL.
SEMMNS = SEMMSL * number of db servers to be run on the system.
Set SEMMNS to the value of SEMMSL multiplied by the number of db servers (maximum) that you
are running on the system at one time.
SEMMNU = SEMMNS
Set the value of SEMMNU to equal the value of SEMMNS. You could probably set this to 75% of
SEMMNS, but this is a conservative estimate.
2.12.5.10. SCO OpenServer 6.0.x Notes
Key improvements of OpenServer 6 include:
•
Larger file support up to 1 TB
•
Multiprocessor support increased from 4 to 32 processors
•
Increased memory support up to 64 GB
•
Extending the power of UnixWare into OpenServer 6
•
Dramatic performance improvement
OpenServer 6.0.0 has the following:
•
/bin is for commands that behave exactly the same as on OpenServer 5.0.x.
•
/u95/bin is for commands that have better standards conformance, for example Large File
System (LFS) support.
•
/udk/bin is for commands that behave the same as on UnixWare 7.1.4. The default is for the
LFS support.
The following is a guide to setting PATH on OpenServer 6. If the user wants the traditional
OpenServer 5.0.x then PATH should be /bin first. If the user wants LFS support then the path
should be /u95/bin:/bin. If the user want UnixWare 7 support first then the path would be /
udk/bin:/u95/bin:/bin:.
We recommend using the latest production release of MySQL. Should you choose to use an older
release of MySQL on OpenServer 6.0.x, you must use a version of MySQL at least as recent as
3.22.13 to get fixes for some portability and OS problems.
We have been able to compile MySQL with the following configure command on OpenServer
Version 6.0.x:
CC="cc" CFLAGS="-I/usr/local/include" \
CXX="CC" CXXFLAGS="-I/usr/local/include" \
./configure --prefix=/usr/local/mysql \
--enable-thread-safe-client --with-berkeley-db=./bdb \
--with-innodb --with-openssl --with-extra-charsets=complex \
--enable-readline
If you want to use gcc, you must use gcc 2.95.3 or newer.
CC=gcc CXX=g++ ./configure --prefix=/usr/local/mysql
169
Installing MySQL
The version of Berkeley DB that comes with either UnixWare 7.1.4 or OpenServer 6.0.0 is not used
when building MySQL. MySQL instead uses its own version of Berkeley DB. The configure
command needs to build both a static and a dynamic library in src_directory/
bdb/build_unix/, but it doesn't with MySQL's own BDB version. The workaround is as follows.
1.
Configure as normal for MySQL.
2.
cd bdb/build_unix/
3.
cp -p Makefile to Makefile.sav
4.
Use same options and run ../dist/configure.
5.
Run gmake.
6.
cp -p Makefile.sav Makefile
7.
Change to top source directory and run gmake.
This allows both the shared and dynamic libraries to be made and work. OpenServer 6.0.0 also
needs patches to the MySQL source tree and the patch for config.guess applied to bdb/
dist/config.guess.
You
can
download
the
patches
from
ftp://ftp.zenez.com/pub/zenez/prgms/mysql-4.1.12-osr6-patches.tar.gz
and
from
ftp://ftp.zenez.com/pub/zenez/prgms/mysql-4.x.x-osr6-patches. There is a README file there to assist.
SCO provides OpenServer 6 operating system patches at ftp://ftp.sco.com/pub/openserver6.
SCO provides information about security fixes at ftp://ftp.sco.com/pub/security/OpenServer.
By default, the maximum file size on a OpenServer 6.0.0 system is 1TB. Some operating system
utilities have a limitation of 2GB. The maximum possible file size on UnixWare 7 is 1TB with
VXFS or HTFS.
By default, the entries in /etc/conf/cf.d/mtune are set to:
Value
----SVMMLIM
HVMMLIM
SSTKLIM
HSTKLIM
Default
------0x9000000
0x9000000
0x1000000
0x1000000
Min
--0x1000000
0x1000000
0x2000
0x2000
Max
--0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
We recommend setting these values as follows:
SDATLIM
HDATLIM
SSTKLIM
HSTKLIM
SVMMLIM
HVMMLIM
SFNOLIM
HFNOLIM
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
2048
2048
We recommend tuning the system, but the proper parameter values to use depend on the number of
users accessing the application or database and size the of the database (that is, the used buffer
pool). The following affects the kernel parameters defined in /etc/conf/cf.d/stune:
SHMMAX (recommended setting: 128MB) and SHMSEG (recommended setting: 15). These parameters have influence on the MySQL database engine to create user buffer pools.
170
Installing MySQL
SFNOLIM and HFNOLIM should be at maximum 2048.
NPROC should be set to at least 3000/4000 (depends on number of users).
Also is recommended to use following formula to count value for SEMMSL, SEMMNS, and SEMMNU:
SEMMSL = 13
13 is what has been found to be the best for both Progress and MySQL.
SEMMNS = SEMMSL * number of db servers to be run on the system.
Set SEMMNS to the value of SEMMSL multiplied by the number of db servers (maximum) that you
are running on the system at one time.
SEMMNU = SEMMNS
Set the value of SEMMNU to equal the value of SEMMNS. You could probably set this to 75% of
SEMMNS, but this is a conservative estimate.
2.12.6. OS/2 Notes
MySQL uses quite a few open files. Because of this, you should add something like the following to
your CONFIG.SYS file:
SET EMXOPT=-c -n -h1024
If you don't do this, you may encounter the following error:
File 'xxxx' not found (Errcode: 24)
When using MySQL with OS/2 Warp 3, FixPack 29 or above is required. With OS/2 Warp 4, FixPack 4 or above is required. This is a requirement of the Pthreads library. MySQL must be installed
on a partition with a type that supports long filenames, such as HPFS, FAT32, and so on.
The INSTALL.CMD script must be run from OS/2's own CMD.EXE and may not work with replacement shells such as 4OS2.EXE.
The scripts/mysql-install-db script has been renamed. It is called install.cmd and is
a REXX script, which sets up the default MySQL security settings and creates the WorkPlace Shell
icons for MySQL.
Dynamic module support is compiled in but not fully tested. Dynamic modules should be compiled
using the Pthreads runtime library.
gcc -Zdll -Zmt -Zcrtdll=pthrdrtl -I../include -I../regex -I.. \
-o example udf_example.cc -L../lib -lmysqlclient udf_example.def
mv example.dll example.udf
Note: Due to limitations in OS/2, UDF module name stems must not exceed eight characters. Modules are stored in the /mysql2/udf directory; the safe-mysqld.cmd script puts this directory
in the BEGINLIBPATH environment variable. When using UDF modules, specified extensions are
ignored---it is assumed to be .udf. For example, in Unix, the shared module might be named example.so and you would load a function from it like this:
mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME 'example.so';
In OS/2, the module would be named example.udf, but you would not specify the module extension:
171
Installing MySQL
mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME 'example';
2.12.7. BeOS Notes
We have in the past talked with some BeOS developers who have said that MySQL is 80% ported to
BeOS, but we haven't heard from them in a while.
2.13. Perl Installation Notes
Perl support for MySQL is provided by means of the DBI/DBD client interface. The interface requires Perl Version 5.6.0 or later. It does not work if you have an older version of Perl.
If you want to use transactions with Perl DBI, you need to have DBD::mysql version 1.2216 or
newer. Version 2.9003 or newer is recommended.
If you are using the MySQL 4.1 client library, you must use DBD::mysql 2.9003 or newer.
As of MySQL 3.22.8, Perl support is no longer included with MySQL distributions. You can obtain
the necessary modules from http://search.cpan.org for Unix, or by using the ActiveState ppm program on Windows. The following sections describe how to do this.
Perl support for MySQL must be installed if you want to run the MySQL benchmark scripts. See
Section 7.1.4, “The MySQL Benchmark Suite”.
2.13.1. Installing Perl on Unix
MySQL Perl support requires that you've installed MySQL client programming support (libraries
and header files). Most installation methods install the necessary files. However, if you installed
MySQL from RPM files on Linux, be sure that you've installed the developer RPM. The client programs are in the client RPM, but client programming support is in the developer RPM.
If you want to install Perl support, the files you need can be obtained from the CPAN
(Comprehensive Perl Archive Network) at http://search.cpan.org.
The easiest way to install Perl modules on Unix is to use the CPAN module. For example:
shell> perl -MCPAN -e shell
cpan> install DBI
cpan> install DBD::mysql
The DBD::mysql installation runs a number of tests. These tests attempt to connect to the local
MySQL server using the default username and password. (The default username is your login name
on Unix, and ODBC on Windows. The default password is “no password.”) If you can't connect to
the server with those values (for example, if your account has a password), the tests fail. You can
use force install DBD::mysql to ignore the failed tests.
DBI requires the Data::Dumper module. It may be installed; if not, you should install it before
installing DBI.
It is also possible to download the module distributions in the form of compressed tar archives and
build the modules manually. For example, to unpack and build a DBI distribution, use a procedure
such as this:
1.
Unpack the distribution into the current directory:
shell> gunzip < DBI-VERSION.tar.gz | tar xvf This command creates a directory named DBI-VERSION.
172
Installing MySQL
2.
Change location into the top-level directory of the unpacked distribution:
shell> cd DBI-VERSION
3.
Build the distribution and compile everything:
shell>
shell>
shell>
shell>
perl Makefile.PL
make
make test
make install
The make test command is important because it verifies that the module is working. Note that
when you run that command during the DBD::mysql installation to exercise the interface code,
the MySQL server must be running or the test fails.
It is a good idea to rebuild and reinstall the DBD::mysql distribution whenever you install a new
release of MySQL, particularly if you notice symptoms such as that all your DBI scripts fail after
you upgrade MySQL.
If you don't have access rights to install Perl modules in the system directory or if you want to install
local
Perl
modules,
the
following
reference
may
be
useful:
http://servers.digitaldaze.com/extensions/perl/modules.html#modules
Look under the heading “Installing New Modules that Require Locally Installed Modules.”
2.13.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 previously done so, install DBI:
ppm> install DBI
•
If this succeeds, run the following command:
install \
ftp://ftp.de.uu.net/pub/CPAN/authors/id/JWIED/DBD-mysql-1.2212.x86.ppd
This procedure should work at least with ActiveState Perl Version 5.6.
If you can't get the procedure to work, you should instead install the MyODBC driver and connect
to the MySQL server through ODBC:
use DBI;
173
Installing MySQL
$dbh= DBI->connect("DBI:ODBC:$dsn",$user,$password) ||
die "Got error $DBI::errstr when connecting to $dsn\n";
2.13.3. Problems Using the Perl DBI/DBD Interface
If Perl reports that it can't find the ../mysql/mysql.so module, then the problem is probably
that Perl can't locate the shared library libmysqlclient.so.
You should be able to fix this by one of the following methods:
•
Compile the DBD::mysql distribution with perl Makefile.PL -static -config
rather than perl Makefile.PL.
•
Copy libmysqlclient.so to the directory where your other shared libraries are located
(probably /usr/lib or /lib).
•
Modify the -L options used to compile DBD::mysql to reflect the actual location of
libmysqlclient.so.
•
On Linux, you can add the pathname of the directory where libmysqlclient.so is located
to the /etc/ld.so.conf file.
•
Add the pathname of the directory where libmysqlclient.so is located to the
LD_RUN_PATH environment variable. Some systems use LD_LIBRARY_PATH instead.
Note that you may also need to modify the -L options if there are other libraries that the linker fails
to find. For example, if the linker cannot find libc because it is in /lib and the link command
specifies -L/usr/lib, change the -L option to -L/lib or add -L/lib to the existing link
command.
If you get the following errors from DBD::mysql, you are probably using gcc (or using an old
binary compiled with gcc):
/usr/bin/perl: can't resolve symbol '__moddi3'
/usr/bin/perl: can't resolve symbol '__divdi3'
Add -L/usr/lib/gcc-lib/... -lgcc to the link command when the mysql.so library
gets built (check the output from make for mysql.so when you compile the Perl client). The -L
option should specify the pathname of the directory where libgcc.a is located on your system.
Another cause of this problem may be that Perl and MySQL aren't both compiled with gcc. In this
case, you can solve the mismatch by compiling both with gcc.
You may see the following error from DBD::mysql when you run the tests:
t/00base............install_driver(mysql) failed:
Can't load '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol:
uncompress at /usr/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 169.
This means that you need to include the -lz compression library on the link line. That can be done
by changing the following line in the file lib/DBD/mysql/Install.pm:
$sysliblist .= " -lm";
Change that line to:
$sysliblist .= " -lm -lz";
174
Installing MySQL
After this, you must run make realclean and then proceed with the installation from the beginning.
If you want to install DBI on SCO, you have to edit the Makefile in DBI-xxx and each subdirectory. Note that the following assumes gcc 2.95.2 or newer:
OLD:
CC = cc
CCCDLFLAGS = -KPIC -W1,-Bexport
CCDLFLAGS = -wl,-Bexport
NEW:
CC = gcc
CCCDLFLAGS = -fpic
CCDLFLAGS =
LD = ld
LDDLFLAGS = -G -L/usr/local/lib
LDFLAGS = -belf -L/usr/local/lib
LD = gcc -G -fpic
LDDLFLAGS = -L/usr/local/lib
LDFLAGS = -L/usr/local/lib
LD = ld
OPTIMISE = -Od
LD = gcc -G -fpic
OPTIMISE = -O1
OLD:
CCCFLAGS = -belf -dy -w0 -U M_XENIX -DPERL_SCO5 -I/usr/local/include
NEW:
CCFLAGS = -U M_XENIX -DPERL_SCO5 -I/usr/local/include
These changes are necessary because the Perl dynaloader does not load the DBI modules if they
were compiled with icc or cc.
If you want to use the Perl module on a system that doesn't support dynamic linking (such as SCO),
you can generate a static version of Perl that includes DBI and DBD::mysql. The way this works
is that you generate a version of Perl with the DBI code linked in and install it on top of your current
Perl. Then you use that to build a version of Perl that additionally has the DBD code linked in, and
install that.
On SCO, you must have the following environment variables set:
LD_LIBRARY_PATH=/lib:/usr/lib:/usr/local/lib:/usr/progressive/lib
Or:
LD_LIBRARY_PATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
/usr/progressive/lib:/usr/skunk/lib
LIBPATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
/usr/progressive/lib:/usr/skunk/lib
MANPATH=scohelp:/usr/man:/usr/local1/man:/usr/local/man:\
/usr/skunk/man:
First, create a Perl that includes a statically linked DBI module by running these commands in the
directory where your DBI distribution is located:
shell>
shell>
shell>
shell>
perl Makefile.PL -static -config
make
make install
make perl
Then you must install the new Perl. The output of make perl indicates the exact make command
you need to execute to perform the installation. On SCO, this is make -f Makefile.aperl
inst_perl MAP_TARGET=perl.
Next, use the just-created Perl to create another Perl that also includes a statically linked
DBD::mysql by running these commands in the directory where your DBD::mysql distribution
175
Installing MySQL
is located:
shell>
shell>
shell>
shell>
perl Makefile.PL -static -config
make
make install
make perl
Finally, you should install this new Perl. Again, the output of make perl indicates the command
to use.
176
Chapter 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 need to consult the relevant portions of this manual, such as Chapter 5, Database
Administration.)
This chapter describes the entire process of setting up and using a database. If you are interested
only in accessing an existing database, you may want to skip over the sections that describe how to
create the database and the tables it contains.
Because this chapter is tutorial in nature, many details are necessarily omitted. Consult the relevant
sections of the manual for more information on the topics covered here.
3.1. Connecting to and Disconnecting from
the Server
To connect to the server, you will usually need to provide a MySQL username when you invoke
mysql and, most likely, a password. If the server runs on a machine other than the one where you
log in, you will also need to specify a hostname. Contact your administrator to find out what connection parameters you should use to connect (that is, what host, username, and password to use).
Once you know the proper parameters, you should be able to connect like this:
shell> mysql -h host -u user -p
Enter password: ********
host and user represent the hostname where your MySQL server is running and the username of
your MySQL account. Substitute appropriate values for your setup. The ******** represents your
password; enter it when mysql displays the Enter password: prompt.
If that works, you should see some introductory information followed by a mysql> prompt:
shell> mysql -h host -u user -p
Enter password: ********
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 25338 to server version: 4.0.14-log
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql>
The prompt tells you that mysql is ready for you to enter commands.
Some MySQL installations allow users to connect as the anonymous (unnamed) user to the server
running on the local host. If this is the case on your machine, you should be able to connect to that
server by invoking mysql without any options:
177
MySQL Tutorial
shell> mysql
After you have connected successfully, you can disconnect any time by typing QUIT (or \q) at the
mysql> prompt:
mysql> QUIT
Bye
On Unix, you can also disconnect by pressing Control-D.
Most examples in the following sections assume that you are connected to the server. They indicate
this by the mysql> prompt.
3.2. Entering Queries
Make sure that you are connected to the server, as discussed in the previous section. Doing so does
not in itself select any database to work with, but that's okay. At this point, it's more important to
find out a little about how to issue queries than to jump right in creating tables, loading data into
them, and retrieving data from them. This section describes the basic principles of entering commands, using several queries you can try out to familiarize yourself with how mysql works.
Here's a simple command that asks the server to tell you its version number and the current date.
Type it in as shown here following the mysql> prompt and press Enter:
mysql> SELECT VERSION(), CURRENT_DATE;
+------------+--------------+
| VERSION() | CURRENT_DATE |
+------------+--------------+
| 4.1.14-Max | 2005-09-03
|
+------------+--------------+
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.)
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;
178
MySQL Tutorial
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() |
+------------+
| 4.1.14-Max |
+------------+
+---------------------+
| NOW()
|
+---------------------+
| 2005-09-03 12:27:16 |
+---------------------+
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]
| 2005-09-03
|
+---------------+--------------+
In this example, notice how the prompt changes from mysql> to -> after you enter the first line of
a multiple-line query. This is how mysql indicates that it has not yet seen a complete statement and
is waiting for the rest. The prompt is your friend, because it provides valuable feedback. If you use
that feedback, you can always be aware of what mysql is waiting for.
If you decide you do not want to execute a command that you are in the process of entering, cancel
it by typing \c:
mysql> SELECT
-> USER()
-> \c
mysql>
Here, too, notice the prompt. It switches back to mysql> after you type \c, providing feedback to
indicate that mysql is ready for a new command.
The following table shows each of the prompts you may see and summarizes what they mean about
the state that mysql is in:
Prompt
Meaning
179
MySQL Tutorial
mysql> Ready for new command.
  Â
 ->
Waiting for next line of multiple-line command.
  Â
 '>
Waiting for next line, waiting for completion of a string that began with a single quote
(‘'’).
  Â
 ">
Waiting for next line, waiting for completion of a string that began with a double quote
(‘"’).
  Â
 `>
Waiting for next line, waiting for completion of an identifier that began with a backtick
(‘`’).
  Â
/*>
Waiting for next line, waiting for completion of a comment that began with /*.
The `> prompt was implemented MySQL 4.0.16. The /*> prompt was implemented in MySQL
4.1.12 and 5.0.6.
Multiple-line statements commonly occur by accident when you intend to issue a command on a
single line, but forget the terminating semicolon. In this case, mysql waits for more input:
mysql> SELECT USER()
->
If this happens to you (you think you've entered a statement but the only response is a -> prompt),
most likely mysql is waiting for the semicolon. If you don't notice what the prompt is telling you,
you might sit there for a while before realizing what you need to do. Enter a semicolon to complete
the statement, and mysql executes it:
mysql> SELECT USER()
-> ;
+-------------+
| USER()
|
+-------------+
| [email protected] |
+-------------+
The '> and "> prompts occur during string collection (another way of saying that MySQL is waiting for completion of a string). In MySQL, you can write strings surrounded by either ‘'’ or ‘"’
characters (for example, 'hello' or "goodbye"), and mysql lets you enter strings that span
multiple lines. When you see a '> or "> prompt, it means that you have entered a line containing a
string that begins with a ‘'’ or ‘"’ quote character, but have not yet entered the matching quote that
terminates the string. This often indicates that you have inadvertently left out a quote character. For
example:
mysql> SELECT * FROM my_table WHERE name = 'Smith AND age < 30;
'>
If you enter this SELECT statement, then press Enter and wait for the result, nothing happens. Instead of wondering why this query takes so long, notice the clue provided by the '> prompt. It tells
you that mysql expects to see the rest of an unterminated string. (Do you see the error in the statement? The string 'Smith is missing the second single quote mark.)
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>
180
MySQL Tutorial
The prompt changes back to mysql>, indicating that mysql is ready for a new command.
The `> prompt is similar to the '> and "> prompts, but indicates that you have begun but not completed a backtick-quoted identifier.
It is important to know what the '>, ">, and `> prompts signify, because if you mistakenly enter an
unterminated string, any further lines you type appear to be ignored by mysql — including a line
containing QUIT. This can be quite confusing, especially if you do not know that you need to supply the terminating quote before you can cancel the current command.
3.3. Creating and Using a Database
Once you know how to enter commands, you are ready to access a database.
Suppose that you have several pets in your home (your menagerie) and you would like to keep track
of various types of information about them. You can do so by creating tables to hold your data and
loading them with the desired information. Then you can answer different sorts of questions about
your animals by retrieving data from the tables. This section shows you how to:
•
Create a database
•
Create a table
•
Load data into the table
•
Retrieve data from the table in various ways
•
Use multiple tables
The menagerie database is simple (deliberately), but it is not difficult to think of real-world situations in which a similar type of database might be used. For example, a database like this could be
used by a farmer to keep track of livestock, or by a veterinarian to keep track of patient records. A
menagerie distribution containing some of the queries and sample data used in the following sections can be obtained from the MySQL Web site. It is available in both compressed tar (http://www.mysql.com/Downloads/Contrib/Examples/menagerie.tar.gz)
and
Zip
(http://www.mysql.com/Downloads/Contrib/Examples/menagerie.zip) formats.
Use the SHOW statement to find out what databases currently exist on the server:
mysql> SHOW DATABASES;
+----------+
| Database |
+----------+
| mysql
|
| test
|
| tmp
|
+----------+
The list of databases is probably different on your machine, but the mysql and test databases are
likely to be among them. The mysql database is required because it describes user access privileges. The test database is often provided as a workspace for users to try things out.
Note that you may not see all databases if you do not have the SHOW DATABASES privilege. See
Section 13.5.1.3, “GRANT and REVOKE Syntax”.
If the test database exists, try to access it:
mysql> USE test
Database changed
181
MySQL Tutorial
Note that USE, like QUIT, does not require a semicolon. (You can terminate such statements with a
semicolon if you like; it does no harm.) The USE statement is special in another way, too: it must be
given on a single line.
You can use the test database (if you have access to it) for the examples that follow, but anything
you create in that database can be removed by anyone else with access to it. For this reason, you
should probably ask your MySQL administrator for permission to use a database of your own. Suppose that you want to call yours menagerie. The administrator needs to execute a command like
this:
mysql> GRANT ALL ON menagerie.* TO 'your_mysql_name'@'your_client_host';
where your_mysql_name is the MySQL username assigned to you and your_client_host
is the host from which you connect to the server.
3.3.1. Creating and Selecting a Database
If the administrator creates your database for you when setting up your permissions, you can begin
using it. Otherwise, you need to create it yourself:
mysql> CREATE DATABASE menagerie;
Under Unix, database names are case sensitive (unlike SQL keywords), so you must always refer to
your database as menagerie, not as Menagerie, MENAGERIE, or some other variant. This is
also true for table names. (Under Windows, this restriction does not apply, although you must refer
to databases and tables using the same lettercase throughout a given query.)
Creating a database does not select it for use; you must do that explicitly. To make menagerie the
current database, use this command:
mysql> USE menagerie
Database changed
Your database needs to be created only once, but you must select it for use each time you begin a
mysql session. You can do this by issuing a USE statement as shown in the example. Alternatively,
you can select the database on the command line when you invoke mysql. Just specify its name
after any connection parameters that you might need to provide. For example:
shell> mysql -h host -u user -p menagerie
Enter password: ********
Note that menagerie in the command just shown is not your password. If you want to supply
your password on the command line after the -p option, you must do so with no intervening space
(for example, as -pmypassword, not as -p mypassword). However, putting your password on
the command line is not recommended, because doing so exposes it to snooping by other users
logged in on your machine.
3.3.2. Creating a Table
Creating the database is the easy part, but at this point it's empty, as SHOW TABLES tells you:
mysql> SHOW TABLES;
Empty set (0.00 sec)
The harder part is deciding what the structure of your database should be: what tables you need and
what columns should be in each of them.
You want a table that contains a record for each of your pets. This can be called the pet table, and
182
MySQL Tutorial
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: name, owner, species, sex, birth, and death.
Use a CREATE TABLE statement to specify the layout of your table:
mysql> CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20),
-> species VARCHAR(20), sex CHAR(1), birth DATE, death DATE);
VARCHAR is a good choice for the name, owner, and species columns because the column values vary in length. The lengths of those columns need not all be the same, and need not be 20. In
MySQL 5.0.3 and later versions, you can normally pick any length from 1 to 65535, whatever
seems most reasonable to you. (Note: Prior to MySQL 5.0.3, the upper limit was 255.) If you make
a poor choice and it turns out later that you need a longer field, MySQL provides an ALTER TABLE statement.
Several types of values can be chosen to represent sex in animal records, such as 'm' and 'f', or
perhaps 'male' and 'female'. It is simplest to use the single characters 'm' and 'f'.
The use of the DATE data type for the birth and death columns is a fairly obvious choice.
Once you have created a table, SHOW TABLES should produce some output:
mysql> SHOW TABLES;
+---------------------+
| Tables in menagerie |
+---------------------+
| pet
|
+---------------------+
To verify that your table was created the way you expected, use a DESCRIBE statement:
mysql> DESCRIBE pet;
+---------+-------------+------+-----+---------+-------+
| Field
| Type
| Null | Key | Default | Extra |
+---------+-------------+------+-----+---------+-------+
| name
| varchar(20) | YES |
| NULL
|
|
| owner
| varchar(20) | YES |
| NULL
|
|
| species | varchar(20) | YES |
| NULL
|
|
| sex
| char(1)
| YES |
| NULL
|
|
| birth
| date
| YES |
| NULL
|
|
| death
| date
| YES |
| NULL
|
|
+---------+-------------+------+-----+---------+-------+
183
MySQL Tutorial
You can use DESCRIBE any time, for example, if you forget the names of the columns in your table
or what types they have.
3.3.3. Loading Data into a Table
After creating your table, you need to populate it. The LOAD DATA and INSERT statements are
useful for this.
Suppose that your pet records can be described as shown here. (Observe that MySQL expects dates
in 'YYYY-MM-DD' format; this may be different from what you are used to.)
name
owner
species
sex
birth
Fluffy
Harold
cat
f
1993-02-04
Claws
Gwen
cat
m
1994-03-17
Buffy
Harold
dog
f
1989-05-13
Fang
Benny
dog
m
1990-08-27
Bowser
Diane
dog
m
1979-08-31
Chirpy
Gwen
bird
f
1998-09-11
Whistler
Gwen
bird
Slim
Benny
snake
death
1995-07-29
1997-12-09
m
1996-04-29
Because you are beginning with an empty table, an easy way to populate it is to create a text file
containing a row for each of your animals, then load the contents of the file into the table with a
single statement.
You could create a text file pet.txt containing one record per line, with values separated by tabs,
and given in the order in which the columns were listed in the CREATE TABLE statement. For
missing values (such as unknown sexes or death dates for animals that are still living), you can use
NULL values. To represent these in your text file, use \N (backslash, capital-N). For example, the
record for Whistler the bird would look like this (where the whitespace between values is a single
tab character):
name
owner
Whistler Gwen
species
sex
birth
death
bird
\N
1997-12-09
\N
To load the text file pet.txt into the pet table, use this command:
mysql> LOAD DATA LOCAL INFILE '/path/pet.txt' INTO TABLE pet;
Note that if you created the file on Windows with an editor that uses \r\n as a line terminator, you
should use:
mysql> LOAD DATA LOCAL INFILE '/path/pet.txt' INTO TABLE pet
-> LINES TERMINATED BY '\r\n';
(On an Apple machine running OS X, you would likely want to use LINES TERMINATED BY
'\r'.)
You can specify the column value separator and end of line marker explicitly in the LOAD DATA
statement if you wish, but the defaults are tab and linefeed. These are sufficient for the statement to
read the file pet.txt properly.
If the statement fails, it is likely that your MySQL installation does not have local file capability enabled by default. See Section 5.5.4, “Security Issues with LOAD DATA LOCAL” for information on
how to change this.
184
MySQL Tutorial
When you want to add new records one at a time, the INSERT statement is useful. In its simplest
form, you supply values for each column, in the order in which the columns were listed in the CREATE TABLE statement. Suppose that Diane gets a new hamster named "Puffball". You could add a
new record using an INSERT statement like this:
mysql> INSERT INTO pet
-> VALUES ('Puffball','Diane','hamster','f','1999-03-30',NULL);
Note that string and date values are specified as quoted strings here. Also, with INSERT, you can
insert NULL directly to represent a missing value. You do not use \N like you do with LOAD DATA.
From this example, you should be able to see that there would be a lot more typing involved to load
your records initially using several INSERT statements rather than a single LOAD DATA statement.
3.3.4. Retrieving Information from a Table
The SELECT statement is used to pull information from a table. The general form of the statement
is:
SELECT what_to_select
FROM which_table
WHERE conditions_to_satisfy;
what_to_select indicates what you want to see. This can be a list of columns, or * to indicate
“all columns.” which_table indicates the table from which you want to retrieve data. The
WHERE clause is optional. If it is present, conditions_to_satisfy specifies one or more conditions that rows must satisfy to qualify for retrieval.
3.3.4.1. Selecting All Data
The simplest form of SELECT retrieves everything from a table:
mysql> SELECT * FROM pet;
+----------+--------+---------+------+------------+------------+
| name
| owner | species | sex | birth
| death
|
+----------+--------+---------+------+------------+------------+
| Fluffy
| Harold | cat
| f
| 1993-02-04 | NULL
|
| Claws
| Gwen
| cat
| m
| 1994-03-17 | NULL
|
| Buffy
| Harold | dog
| f
| 1989-05-13 | NULL
|
| Fang
| Benny | dog
| m
| 1990-08-27 | NULL
|
| Bowser
| Diane | dog
| m
| 1979-08-31 | 1995-07-29 |
| Chirpy
| Gwen
| bird
| f
| 1998-09-11 | NULL
|
| Whistler | Gwen
| bird
| NULL | 1997-12-09 | NULL
|
| Slim
| Benny | snake
| m
| 1996-04-29 | NULL
|
| Puffball | Diane | hamster | f
| 1999-03-30 | NULL
|
+----------+--------+---------+------+------------+------------+
This form of SELECT is useful if you want to review your entire table, for example, after you've
just loaded it with your initial 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 two ways to fix this:
•
Edit the file pet.txt to correct the error, then empty the table and reload it using DELETE and
LOAD DATA:
185
MySQL Tutorial
mysql> DELETE FROM pet;
mysql> LOAD DATA LOCAL INFILE 'pet.txt' INTO TABLE pet;
However, if you do this, you must also re-enter the record for Puffball.
•
Fix only the erroneous record with an UPDATE statement:
mysql> UPDATE pet SET birth = '1989-08-31' WHERE name = 'Bowser';
The UPDATE changes only the record in question and does not require you to reload the table.
3.3.4.2. Selecting Particular Rows
As shown in the preceding section, it is easy to retrieve an entire table. Just omit the WHERE clause
from the SELECT statement. But typically you don't want to see the entire table, particularly when it
becomes large. Instead, you're usually more interested in answering a particular question, in which
case you specify some constraints on the information you want. Let's look at some selection queries
in terms of questions about your pets that they answer.
You can select only particular rows from your table. For example, if you want to verify the change
that you made to Bowser's birth date, select Bowser's record like this:
mysql> SELECT * FROM pet WHERE name = 'Bowser';
+--------+-------+---------+------+------------+------------+
| name
| owner | species | sex | birth
| death
|
+--------+-------+---------+------+------------+------------+
| Bowser | Diane | dog
| m
| 1989-08-31 | 1995-07-29 |
+--------+-------+---------+------+------------+------------+
The output confirms that the year is correctly recorded as 1989, not 1979.
String comparisons normally are case-insensitive, so you can specify the name as 'bowser',
'BOWSER', etc. The query result is the same.
You can specify conditions on any column, not just name. For example, if you want to know which
animals were born after 1998, test the birth column:
mysql> SELECT * FROM pet WHERE birth > '1998-1-1';
+----------+-------+---------+------+------------+-------+
| name
| owner | species | sex | birth
| death |
+----------+-------+---------+------+------------+-------+
| Chirpy
| Gwen | bird
| f
| 1998-09-11 | NULL |
| Puffball | Diane | hamster | f
| 1999-03-30 | NULL |
+----------+-------+---------+------+------------+-------+
You can combine conditions, for example, to locate female dogs:
mysql> SELECT * FROM pet WHERE species = 'dog' AND sex = 'f';
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
The preceding query uses the AND logical operator. There is also an OR operator:
mysql> SELECT * FROM pet WHERE species = 'snake' OR species = 'bird';
+----------+-------+---------+------+------------+-------+
| name
| owner | species | sex | birth
| death |
186
MySQL Tutorial
+----------+-------+---------+------+------------+-------+
| Chirpy
| Gwen | bird
| f
| 1998-09-11 | NULL |
| Whistler | Gwen | bird
| NULL | 1997-12-09 | NULL |
| Slim
| Benny | snake
| m
| 1996-04-29 | NULL |
+----------+-------+---------+------+------------+-------+
AND and OR may be intermixed, although AND has higher precedence than OR. If you use both operators, it is a good idea to use parentheses to indicate explicitly how conditions should be grouped:
mysql> SELECT * FROM pet WHERE (species = 'cat' AND sex = 'm')
-> OR (species = 'dog' AND sex = 'f');
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
| Claws | Gwen
| cat
| m
| 1994-03-17 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
3.3.4.3. Selecting Particular Columns
If you do not want to see entire rows from your table, just name the columns in which you are interested, separated by commas. For example, if you want to know when your animals were born, select
the name and birth columns:
mysql> SELECT name, birth FROM pet;
+----------+------------+
| name
| birth
|
+----------+------------+
| Fluffy
| 1993-02-04 |
| Claws
| 1994-03-17 |
| Buffy
| 1989-05-13 |
| Fang
| 1990-08-27 |
| Bowser
| 1989-08-31 |
| Chirpy
| 1998-09-11 |
| Whistler | 1997-12-09 |
| Slim
| 1996-04-29 |
| Puffball | 1999-03-30 |
+----------+------------+
To find out who owns pets, use this query:
mysql> SELECT owner FROM pet;
+--------+
| owner |
+--------+
| Harold |
| Gwen
|
| Harold |
| Benny |
| Diane |
| Gwen
|
| Gwen
|
| Benny |
| Diane |
+--------+
Notice that the query simply retrieves the owner column from each record, and some of them appear more than once. To minimize the output, retrieve each unique output record just once by adding
the keyword DISTINCT:
mysql> SELECT DISTINCT owner FROM pet;
+--------+
| owner |
+--------+
187
MySQL Tutorial
| 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 is undefined for columns that are
identical except for their case. You can force a case-sensitive sort for a column by using BINARY
like so: ORDER BY BINARY col_name.
The default sort order is ascending, with smallest values first. To sort in reverse (descending) order,
add the DESC keyword to the name of the column you are sorting by:
mysql> SELECT name, birth FROM pet ORDER BY birth DESC;
+----------+------------+
| name
| birth
|
+----------+------------+
| Puffball | 1999-03-30 |
| Chirpy
| 1998-09-11 |
| Whistler | 1997-12-09 |
| Slim
| 1996-04-29 |
| Claws
| 1994-03-17 |
| Fluffy
| 1993-02-04 |
| Fang
| 1990-08-27 |
| Bowser
| 1989-08-31 |
| Buffy
| 1989-05-13 |
188
MySQL Tutorial
+----------+------------+
You can sort on multiple columns, and you can sort columns in different directions. For example, to
sort by type of animal in ascending order, then by birth date within animal type in descending order
(youngest animals first), use the following query:
mysql> SELECT name, species, birth FROM pet
-> ORDER BY species, birth DESC;
+----------+---------+------------+
| name
| species | birth
|
+----------+---------+------------+
| Chirpy
| bird
| 1998-09-11 |
| Whistler | bird
| 1997-12-09 |
| Claws
| cat
| 1994-03-17 |
| Fluffy
| cat
| 1993-02-04 |
| Fang
| dog
| 1990-08-27 |
| Bowser
| dog
| 1989-08-31 |
| Buffy
| dog
| 1989-05-13 |
| Puffball | hamster | 1999-03-30 |
| Slim
| snake
| 1996-04-29 |
+----------+---------+------------+
Note that the DESC keyword applies only to the column name immediately preceding it (birth); it
does not affect the species column sort order.
3.3.4.5. Date Calculations
MySQL provides several functions that you can use to perform calculations on dates, for example,
to calculate ages or extract parts of dates.
To determine how many years old each of your pets is, compute the difference in the year part of the
current date and the birth date, then subtract one if the current date occurs earlier in the calendar
year than the birth date. The following query shows, for each pet, the birth date, the current date,
and the age in years.
mysql> SELECT name, birth, CURDATE(),
-> (YEAR(CURDATE())-YEAR(birth))
-> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
-> AS age
-> FROM pet;
+----------+------------+------------+------+
| name
| birth
| CURDATE() | age |
+----------+------------+------------+------+
| Fluffy
| 1993-02-04 | 2003-08-19 |
10 |
| Claws
| 1994-03-17 | 2003-08-19 |
9 |
| Buffy
| 1989-05-13 | 2003-08-19 |
14 |
| Fang
| 1990-08-27 | 2003-08-19 |
12 |
| Bowser
| 1989-08-31 | 2003-08-19 |
13 |
| Chirpy
| 1998-09-11 | 2003-08-19 |
4 |
| Whistler | 1997-12-09 | 2003-08-19 |
5 |
| Slim
| 1996-04-29 | 2003-08-19 |
7 |
| Puffball | 1999-03-30 | 2003-08-19 |
4 |
+----------+------------+------------+------+
Here, YEAR() pulls out the year part of a date and RIGHT() pulls off the rightmost five characters
that represent the MM-DD (calendar year) part of the date. The part of the expression that compares
the MM-DD values evaluates to 1 or 0, which adjusts the year difference down a year if CURDATE()
occurs earlier in the year than birth. The full expression is somewhat ungainly, so an alias (age)
is used to make the output column label more meaningful.
The query works, but the result could be scanned more easily if the rows were presented in some order. This can be done by adding an ORDER BY name clause to sort the output by name:
mysql> SELECT name, birth, CURDATE(),
189
MySQL Tutorial
-> (YEAR(CURDATE())-YEAR(birth))
-> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
-> AS age
-> FROM pet ORDER BY name;
+----------+------------+------------+------+
| name
| birth
| CURDATE() | age |
+----------+------------+------------+------+
| Bowser
| 1989-08-31 | 2003-08-19 |
13 |
| Buffy
| 1989-05-13 | 2003-08-19 |
14 |
| Chirpy
| 1998-09-11 | 2003-08-19 |
4 |
| Claws
| 1994-03-17 | 2003-08-19 |
9 |
| Fang
| 1990-08-27 | 2003-08-19 |
12 |
| Fluffy
| 1993-02-04 | 2003-08-19 |
10 |
| Puffball | 1999-03-30 | 2003-08-19 |
4 |
| Slim
| 1996-04-29 | 2003-08-19 |
7 |
| Whistler | 1997-12-09 | 2003-08-19 |
5 |
+----------+------------+------------+------+
To sort the output by age rather than name, just use a different ORDER BY clause:
mysql> SELECT name, birth, CURDATE(),
-> (YEAR(CURDATE())-YEAR(birth))
-> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
-> AS age
-> FROM pet ORDER BY age;
+----------+------------+------------+------+
| name
| birth
| CURDATE() | age |
+----------+------------+------------+------+
| Chirpy
| 1998-09-11 | 2003-08-19 |
4 |
| Puffball | 1999-03-30 | 2003-08-19 |
4 |
| Whistler | 1997-12-09 | 2003-08-19 |
5 |
| Slim
| 1996-04-29 | 2003-08-19 |
7 |
| Claws
| 1994-03-17 | 2003-08-19 |
9 |
| Fluffy
| 1993-02-04 | 2003-08-19 |
10 |
| Fang
| 1990-08-27 | 2003-08-19 |
12 |
| Bowser
| 1989-08-31 | 2003-08-19 |
13 |
| Buffy
| 1989-05-13 | 2003-08-19 |
14 |
+----------+------------+------------+------+
A similar query can be used to determine age at death for animals that have died. You determine
which animals these are by checking whether the death value is NULL. Then, for those with
non-NULL values, compute the difference between the death and birth values:
mysql> SELECT name, birth, death,
-> (YEAR(death)-YEAR(birth)) - (RIGHT(death,5)<RIGHT(birth,5))
-> AS age
-> FROM pet WHERE death IS NOT NULL ORDER BY age;
+--------+------------+------------+------+
| name
| birth
| death
| age |
+--------+------------+------------+------+
| Bowser | 1989-08-31 | 1995-07-29 |
5 |
+--------+------------+------------+------+
The query uses death IS NOT NULL rather than death <> NULL because NULL is a special
value that cannot be compared using the usual comparison operators. This is discussed later. See
Section 3.3.4.6, “Working with NULL Values”.
What if you want to know which animals have birthdays next month? For this type of calculation,
year and day are irrelevant; you simply want to extract the month part of the birth column.
MySQL provides several functions for extracting parts of dates, such as YEAR(), MONTH(), and
DAYOFMONTH(). MONTH() is the appropriate function here. To see how it works, run a simple
query that displays the value of both birth and MONTH(birth):
mysql> SELECT name, birth, MONTH(birth) FROM pet;
+----------+------------+--------------+
| name
| birth
| MONTH(birth) |
190
MySQL Tutorial
+----------+------------+--------------+
| Fluffy
| 1993-02-04 |
2 |
| Claws
| 1994-03-17 |
3 |
| Buffy
| 1989-05-13 |
5 |
| Fang
| 1990-08-27 |
8 |
| Bowser
| 1989-08-31 |
8 |
| Chirpy
| 1998-09-11 |
9 |
| Whistler | 1997-12-09 |
12 |
| Slim
| 1996-04-29 |
4 |
| Puffball | 1999-03-30 |
3 |
+----------+------------+--------------+
Finding animals with birthdays in the upcoming month is also simple. Suppose that the current
month is April. Then the month value is 4 and you can look for animals born in May (month 5) like
this:
mysql> SELECT name, birth FROM pet WHERE MONTH(birth) = 5;
+-------+------------+
| name | birth
|
+-------+------------+
| Buffy | 1989-05-13 |
+-------+------------+
There is a small complication if the current month is December. You cannot merely add one to the
month number (12) and look for animals born in month 13, because there is no such month. Instead, you look for animals born in January (month 1).
You can write the query so that it works no matter what the current month is, so that you do not
have to use the number for a particular month. DATE_ADD() 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 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 a missing 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:
191
MySQL Tutorial
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.
A common error when working with NULL is to assume that it is not possible to insert a zero or an
empty string into a column defined as NOT NULL, but this is not the case. These are in fact values,
whereas NULL means "not having a value". You can test this easily enough by using IS [NOT]
NULL as shown:
mysql> SELECT 0 IS NULL, 0 IS NOT NULL, '' IS NULL, '' IS NOT NULL;
+-----------+---------------+------------+----------------+
| 0 IS NULL | 0 IS NOT NULL | '' IS NULL | '' IS NOT NULL |
+-----------+---------------+------------+----------------+
|
0 |
1 |
0 |
1 |
+-----------+---------------+------------+----------------+
Thus it is entirely possible to insert a zero or empty string into a NOT NULL column, as these are in
fact NOT NULL. See Section A.5.3, “Problems with NULL Values”.
3.3.4.7. Pattern Matching
MySQL provides standard SQL pattern matching as well as a form of pattern matching based on extended regular expressions similar to those used by Unix utilities such as vi, grep, and sed.
SQL pattern matching 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 |
+--------+--------+---------+------+------------+-------+
192
MySQL Tutorial
| Fluffy | Harold | cat
| f
| 1993-02-04 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+--------+--------+---------+------+------------+-------+
To find names containing a ‘w’:
mysql> SELECT * FROM pet WHERE name LIKE '%w%';
+----------+-------+---------+------+------------+------------+
| name
| owner | species | sex | birth
| death
|
+----------+-------+---------+------+------------+------------+
| Claws
| Gwen | cat
| m
| 1994-03-17 | NULL
|
| Bowser
| Diane | dog
| m
| 1989-08-31 | 1995-07-29 |
| Whistler | Gwen | bird
| NULL | 1997-12-09 | NULL
|
+----------+-------+---------+------+------------+------------+
To find names containing exactly five characters, use five instances of the ‘_’ pattern character:
mysql> SELECT * FROM pet WHERE name LIKE '_____';
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
| Claws | Gwen
| cat
| m
| 1994-03-17 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
The other type of pattern matching provided by MySQL uses extended regular expressions. When
you test for a match for this type of pattern, use the REGEXP and NOT REGEXP operators (or
RLIKE and NOT RLIKE, which are synonyms).
Some characteristics of extended regular expressions are:
•
‘.’ matches any single character.
•
A character class ‘[...]’ matches any character within the brackets. For example, ‘[abc]’
matches ‘a’, ‘b’, or ‘c’. To name a range of characters, use a dash. ‘[a-z]’ matches any letter,
whereas ‘[0-9]’ matches any digit.
•
‘*’ matches zero or more instances of the thing preceding it. For example, ‘x*’ matches any
number of ‘x’ characters, ‘[0-9]*’ matches any number of digits, and ‘.*’ matches any number of anything.
•
A REGEXP pattern match succeed if the pattern matches anywhere in the value being tested.
(This differs from 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 |
+--------+--------+---------+------+------------+------------+
193
MySQL Tutorial
Prior to MySQL Version 3.23.4, REGEXP is case sensitive, and the previous query will return no
rows. In this case, to match either lowercase or uppercase ‘b’, use this query instead:
mysql> SELECT * FROM pet WHERE name REGEXP '^[bB]';
From MySQL 3.23.4 on, if you really want to force a REGEXP comparison to be case sensitive, use
the BINARY keyword to make one of the strings a binary string. This query matches only lowercase
‘b’ at the beginning of a name:
mysql> SELECT * FROM pet WHERE name REGEXP BINARY '^b';
To find names ending with ‘fy’, use ‘$’ to match the end of the name:
mysql> SELECT * FROM pet WHERE name REGEXP 'fy$';
+--------+--------+---------+------+------------+-------+
| name
| owner | species | sex | birth
| death |
+--------+--------+---------+------+------------+-------+
| Fluffy | Harold | cat
| f
| 1993-02-04 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+--------+--------+---------+------+------------+-------+
To find names containing a ‘w’, use this query:
mysql> SELECT * FROM pet WHERE name REGEXP 'w';
+----------+-------+---------+------+------------+------------+
| name
| owner | species | sex | birth
| death
|
+----------+-------+---------+------+------------+------------+
| Claws
| Gwen | cat
| m
| 1994-03-17 | NULL
|
| Bowser
| Diane | dog
| m
| 1989-08-31 | 1995-07-29 |
| Whistler | Gwen | bird
| NULL | 1997-12-09 | NULL
|
+----------+-------+---------+------+------------+------------+
Because a regular expression pattern matches if it occurs anywhere in the value, it is not necessary
in the previous query to put a wildcard on either side of the pattern to get it to match the entire value
like it would be if you used an SQL pattern.
To find names containing exactly five characters, use ‘^’ and ‘$’ to match the beginning and end of
the name, and five instances of ‘.’ in between:
mysql> SELECT * FROM pet WHERE name REGEXP '^.....$';
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
| Claws | Gwen
| cat
| m
| 1994-03-17 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
You could also write the previous query using the ‘{n}’ “repeat-n-times” operator:
mysql> SELECT * FROM pet WHERE name REGEXP '^.{5}$';
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
| Claws | Gwen
| cat
| m
| 1994-03-17 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
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
194
MySQL Tutorial
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 (42000): Mixing of GROUP columns (MIN(),MAX(),COUNT(),...)
with no GROUP columns is illegal if there is no GROUP BY clause
COUNT() and GROUP BY are useful for characterizing your data in various ways. The following
examples show different ways to perform animal census operations.
Number of animals per species:
mysql> SELECT species, COUNT(*) FROM pet GROUP BY species;
+---------+----------+
| species | COUNT(*) |
+---------+----------+
| bird
|
2 |
| cat
|
2 |
| dog
|
3 |
| hamster |
1 |
| snake
|
1 |
+---------+----------+
Number of animals per sex:
mysql> SELECT sex, COUNT(*) FROM pet GROUP BY sex;
+------+----------+
| sex | COUNT(*) |
+------+----------+
| NULL |
1 |
| f
|
4 |
| m
|
4 |
+------+----------+
(In this output, NULL indicates that the sex is unknown.)
195
MySQL Tutorial
Number of animals per combination of species and sex:
mysql> SELECT species, sex, COUNT(*) FROM pet GROUP BY species, sex;
+---------+------+----------+
| species | sex | COUNT(*) |
+---------+------+----------+
| bird
| NULL |
1 |
| bird
| f
|
1 |
| cat
| f
|
1 |
| cat
| m
|
1 |
| dog
| f
|
1 |
| dog
| m
|
2 |
| hamster | f
|
1 |
| snake
| m
|
1 |
+---------+------+----------+
You need not retrieve an entire table when you use COUNT(). For example, the previous query,
when performed just on dogs and cats, looks like this:
mysql> SELECT species, sex, COUNT(*) FROM pet
-> WHERE species = 'dog' OR species = 'cat'
-> GROUP BY species, sex;
+---------+------+----------+
| species | sex | COUNT(*) |
+---------+------+----------+
| cat
| f
|
1 |
| cat
| m
|
1 |
| dog
| f
|
1 |
| dog
| m
|
2 |
+---------+------+----------+
Or, if you wanted the number of animals per sex only for animals whose sex is known:
mysql> SELECT species, sex, COUNT(*) FROM pet
-> WHERE sex IS NOT NULL
-> GROUP BY species, sex;
+---------+------+----------+
| species | sex | COUNT(*) |
+---------+------+----------+
| bird
| f
|
1 |
| cat
| f
|
1 |
| cat
| m
|
1 |
| dog
| f
|
1 |
| dog
| m
|
2 |
| hamster | f
|
1 |
| snake
| m
|
1 |
+---------+------+----------+
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 that you know which animal each event pertains to.
•
A date so that you know when the event occurred.
•
A field to describe the event.
•
An event type field, if you want to be able to categorize events.
196
MySQL Tutorial
Given these considerations, the CREATE TABLE statement for the event table might look like
this:
mysql> CREATE TABLE event (name VARCHAR(20), date DATE,
-> type VARCHAR(15), remark VARCHAR(255));
As with the pet table, it's easiest to load the initial records by creating a tab-delimited text file containing the information:
name
date
type
remark
Fluffy
1995-05-15
litter
4 kittens, 3 female, 1 male
Buffy
1993-06-23
litter
5 puppies, 2 female, 3 male
Buffy
1994-06-19
litter
3 puppies, 3 female
Chirpy
1999-03-21
vet
needed beak straightened
Slim
1997-08-03
vet
broken rib
Bowser
1991-10-12
kennel
Fang
1991-10-12
kennel
Fang
1998-08-28
birthday
Gave him a new chew toy
Claws
1998-03-17
birthday
Gave him a new flea collar
Whistler
1998-12-09
birthday
First birthday
Load the records like this:
mysql> LOAD DATA LOCAL INFILE 'event.txt' INTO TABLE event;
Based on what you have learned from the queries that you have run on the pet table, you should be
able to perform retrievals on the records in the event table; the principles are the same. But when
is the event table by itself insufficient to answer questions you might ask?
Suppose that you want to find out the ages at which each pet had its litters. We saw earlier how to
calculate ages from two dates. The litter date of the mother is in the event table, but to calculate
her age on that date you need her birth date, which is stored in the pet table. This means the query
requires both tables:
mysql> SELECT pet.name,
-> (YEAR(date)-YEAR(birth)) - (RIGHT(date,5)<RIGHT(birth,5)) AS age,
-> remark
-> FROM pet, event
-> WHERE pet.name = event.name AND event.type = 'litter';
+--------+------+-----------------------------+
| name
| age | remark
|
+--------+------+-----------------------------+
| Fluffy |
2 | 4 kittens, 3 female, 1 male |
| Buffy |
4 | 5 puppies, 2 female, 3 male |
| Buffy |
5 | 3 puppies, 3 female
|
+--------+------+-----------------------------+
There are several things to note about this query:
•
The FROM clause 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.
197
MySQL Tutorial
•
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 previously seen SHOW DATABASES, which lists the databases managed by the server. To
find out which database is currently selected, use the DATABASE() function:
mysql> SELECT DATABASE();
+------------+
| DATABASE() |
+------------+
| menagerie |
+------------+
If you haven't selected any database yet, the result is NULL (or the empty string before MySQL
4.1.1).
To find out what tables the current database contains (for example, when you are 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 |
198
MySQL Tutorial
+---------+-------------+------+-----+---------+-------+
| name
| varchar(20) | YES |
| NULL
|
|
| owner
| varchar(20) | YES |
| NULL
|
|
| species | varchar(20) | YES |
| NULL
|
|
| sex
| char(1)
| YES |
| NULL
|
|
| birth
| date
| YES |
| NULL
|
|
| death
| date
| YES |
| NULL
|
|
+---------+-------------+------+-----+---------+-------+
Field indicates the column name, Type is the data type for the column, NULL indicates whether
the column can contain NULL values, Key indicates whether the column is indexed, and Default
specifies the column's default value.
If you have indexes on a table, SHOW INDEX FROM tbl_name produces information about
them.
3.5. Using mysql in Batch Mode
In the previous sections, you used mysql interactively to enter queries and view the results. You
can also run mysql in batch mode. To do this, put the commands you want to run in a file, then tell
mysql to read its input from the file:
shell> mysql < batch-file
If you are running mysql under Windows and have some special characters in the file that cause
problems, you can do this:
C:\> mysql -e "source batch-file"
If you need to specify connection parameters on the command line, the command might look like
this:
shell> mysql -h host -u user -p < batch-file
Enter password: ********
When you use mysql this way, you are creating a script file, then executing the script.
If you want the script to continue even if some of the statements in it produce errors, you should use
the --force command-line option.
Why use a script? Here are a few reasons:
•
If you run a query repeatedly (say, every day or every week), making it a script allows you to
avoid retyping it each time you execute it.
•
You can generate new queries from existing ones that are similar by copying and editing script
files.
•
Batch mode can also be useful while you're developing a query, particularly for multiple-line
commands or multiple-statement sequences of commands. If you make a mistake, you don't
have to retype everything. Just edit your script to correct the error, then tell 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:
199
MySQL Tutorial
shell> mysql < batch-file > mysql.out
•
You can distribute your script to other people so that they can also run the commands.
•
Some situations do not allow for interactive use, for example, when you run a query from a
cron job. In this case, you must use batch mode.
The default output format is different (more concise) when you run mysql in batch mode than
when you use it interactively. For example, the output of SELECT DISTINCT species FROM
pet looks like this when mysql is run interactively:
+---------+
| species |
+---------+
| bird
|
| cat
|
| dog
|
| hamster |
| snake
|
+---------+
In batch mode, the output looks like this instead:
species
bird
cat
dog
hamster
snake
If you want to get the interactive output format in batch mode, use mysql -t. To echo to the output the commands that are executed, use mysql -vvv.
You can also use scripts from the mysql prompt by using the source or \. command:
mysql> source filename;
mysql> \. filename
3.6. Examples of Common Queries
Here are examples of how to solve some common problems with MySQL.
Some of the examples use the table shop to hold the price of each article (item number) for certain
traders (dealers). Supposing that each trader has a single fixed price per article, then (article,
dealer) is a primary key for the records.
Start the command-line tool mysql and select a database:
shell> mysql your-database-name
(In most MySQL installations, you can use the database named test).
You can create and populate the example table with these statements:
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,
200
MySQL Tutorial
->
mysql>
->
->
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;
+---------+
| article |
+---------+
|
4 |
+---------+
3.6.2. The Row Holding the Maximum of a Certain
Column
Task: Find the number, dealer, and price of the most expensive article.
In standard SQL (and as of MySQL 4.1), this is easily done with a subquery:
SELECT article, dealer, price
FROM
shop
WHERE price=(SELECT MAX(price) FROM shop);
In MySQL versions prior to 4.1, just do it in two steps:
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;
201
MySQL Tutorial
+---------+--------+-------+
| 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 MySQLspecific 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
Task: Find the highest price per article.
SELECT article, MAX(price) AS price
FROM
shop
GROUP BY article
+---------+-------+
| article | price |
+---------+-------+
|
0001 | 3.99 |
|
0002 | 10.99 |
|
0003 | 1.69 |
|
0004 | 19.95 |
+---------+-------+
3.6.4. The Rows Holding the Group-wise Maximum of a
Certain Field
Task: For each article, find the dealer or dealers with the most expensive price.
In standard SQL (and as of MySQL 4.1), the problem can be solved with a subquery like this:
SELECT article, dealer, price
FROM
shop s1
WHERE price=(SELECT MAX(s2.price)
FROM shop s2
WHERE s1.article = s2.article);
In MySQL versions prior to 4.1, it's best do it in several steps:
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);
202
MySQL Tutorial
LOCK TABLES shop READ;
INSERT INTO tmp SELECT article, MAX(price) FROM shop GROUP BY article;
SELECT shop.article, dealer, shop.price FROM shop, tmp
WHERE shop.article=tmp.article AND shop.price=tmp.price;
UNLOCK TABLES;
DROP TABLE tmp;
If you don't use a TEMPORARY table, you must also lock the tmp table.
“Can it be done with a single query?”
Yes, but only by using a quite inefficient trick called the “MAX-CONCAT trick”:
SELECT article,
SUBSTRING( MAX( CONCAT(LPAD(price,6,'0'),dealer) ), 7) AS dealer,
0.00+LEFT(
MAX( CONCAT(LPAD(price,6,'0'),dealer) ), 6) AS price
FROM
shop
GROUP BY article;
+---------+--------+-------+
| article | dealer | price |
+---------+--------+-------+
|
0001 | B
| 3.99 |
|
0002 | A
| 10.99 |
|
0003 | C
| 1.69 |
|
0004 | D
| 19.95 |
+---------+--------+-------+
The last example can be made a bit more efficient by doing the splitting of the concatenated column
in the client.
3.6.5. Using User Variables
You can employ MySQL user variables to remember results without having to store them in temporary variables in the client. (See Section 9.3, “User Variables”.)
For example, to find the articles with the highest and lowest price you can do this:
mysql> SELECT @min_price:=MIN(price),@max_price:=MAX(price) FROM shop;
mysql> SELECT * FROM shop WHERE [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
Chapter 15, The InnoDB Storage Engine. See also Section 1.8.5.5, “Foreign Keys”.
A foreign key constraint is not required merely to join two tables. For table types other than InnoDB, it is possible when defining a column to use a REFERENCES tbl_name(col_name)
clause, which has no actual effect, and serves only as a memo or comment to you that the column
which you are currently defining is intended to refer to a column in another table. It is extremely
important to realize when using this syntax that:
203
MySQL Tutorial
•
MySQL does not perform any sort of CHECK to make sure that col_name actually exists in
tbl_name (or even that tbl_name itself exists).
•
MySQL does not perform any sort of action on tbl_name such as deleting rows in response to
actions taken on rows in the table which you are defining; in other words, this syntax induces no
ON DELETE or ON UPDATE behavior whatsoever. (While you can write an ON DELETE or
ON UPDATE clause as part of the REFERENCES clause, it is also ignored.)
•
This syntax creates a column; it does not create any sort of index or key.
•
This syntax will cause an error if used in trying to define an InnoDB table.
You can use a column so created as a join column, as shown here:
CREATE TABLE person (
id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
name CHAR(60) NOT NULL,
PRIMARY KEY (id)
);
CREATE TABLE shirt (
id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
style ENUM('t-shirt', 'polo', 'dress') NOT NULL,
color ENUM('red', 'blue', 'orange', 'white', 'black') NOT NULL,
owner SMALLINT UNSIGNED NOT NULL REFERENCES person(id),
PRIMARY KEY (id)
);
INSERT INTO person VALUES (NULL, 'Antonio Paz');
SELECT @last := LAST_INSERT_ID();
INSERT
(NULL,
(NULL,
(NULL,
INTO shirt VALUES
'polo', 'blue', @last),
'dress', 'white', @last),
't-shirt', 'blue', @last);
INSERT INTO person VALUES (NULL, 'Lilliana Angelovska');
SELECT @last := LAST_INSERT_ID();
INSERT
(NULL,
(NULL,
(NULL,
(NULL,
INTO shirt VALUES
'dress', 'orange', @last),
'polo', 'red', @last),
'dress', 'blue', @last),
't-shirt', 'white', @last);
SELECT * FROM person;
+----+---------------------+
| id | name
|
+----+---------------------+
| 1 | Antonio Paz
|
| 2 | Lilliana Angelovska |
+----+---------------------+
SELECT * FROM shirt;
+----+---------+--------+-------+
| id | style
| color | owner |
+----+---------+--------+-------+
| 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 |
+----+---------+--------+-------+
204
MySQL Tutorial
SELECT
WHERE
AND
AND
s.* FROM person p, shirt s
p.name LIKE 'Lilliana%'
s.owner = p.id
s.color <> 'white';
+----+-------+--------+-------+
| id | style | color | owner |
+----+-------+--------+-------+
| 4 | dress | orange |
2 |
| 5 | polo | red
|
2 |
| 6 | dress | blue
|
2 |
+----+-------+--------+-------+
When used in this fashion, the REFERENCES clause is not displayed in the output of SHOW CREATE TABLE or DESCRIBE:
SHOW CREATE TABLE shirt\G
*************************** 1. row ***************************
Table: shirt
Create Table: CREATE TABLE `shirt` (
`id` smallint(5) unsigned NOT NULL auto_increment,
`style` enum('t-shirt','polo','dress') NOT NULL,
`color` enum('red','blue','orange','white','black') NOT NULL,
`owner` smallint(5) unsigned NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1
The use of REFERENCES in this way as a comment or "reminder" in a column definition works
with both MyISAM and BerkeleyDB tables.
3.6.7. Searching on Two Keys
An OR using a single key is well optimized, as is the handling of AND.
The one tricky case is that of searching on two different keys combined with OR:
SELECT field1_index, field2_index FROM test_table
WHERE field1_index = '1' OR field2_index = '1'
This case is optimized from MySQL 5.0.0. See Section 7.2.6, “Index Merge Optimization”.
In MySQL 4.0 and up, you can also solve the problem efficiently by using a UNION that combines
the output of two separate SELECT statements. See Section 13.2.7.2, “UNION Syntax”.
Each SELECT searches only one key and can be optimized:
SELECT field1_index, field2_index
FROM test_table WHERE field1_index = '1'
UNION
SELECT field1_index, field2_index
FROM test_table WHERE field2_index = '1';
Prior to MySQL 4.0, you can achieve the same effect by using a TEMPORARY table and separate
SELECT statements. This type of optimization is also very good if you are using very complicated
queries where the SQL server does the optimizations in the wrong order.
CREATE TEMPORARY TABLE tmp
SELECT field1_index, field2_index
FROM test_table WHERE field1_index = '1';
INSERT INTO tmp
205
MySQL Tutorial
SELECT field1_index, field2_index
FROM test_table WHERE field2_index = '1';
SELECT * from tmp;
DROP TABLE tmp;
This method of solving the problem is in effect a UNION of two queries.
3.6.8. Calculating Visits Per Day
The following example shows how you can use the bit group functions to calculate the number of
days per month a user has visited a Web page.
CREATE TABLE t1 (year YEAR(4), month INT(2) UNSIGNED ZEROFILL,
day INT(2) UNSIGNED ZEROFILL);
INSERT INTO t1 VALUES(2000,1,1),(2000,1,20),(2000,1,30),(2000,2,2),
(2000,2,23),(2000,2,23);
The example table contains year-month-day values representing visits by users to the page. To determine how many different days in each month these visits occur, use this query:
SELECT year,month,BIT_COUNT(BIT_OR(1<<day)) AS days FROM t1
GROUP BY year,month;
Which returns:
+------+-------+------+
| year | month | days |
+------+-------+------+
| 2000 |
01 |
3 |
| 2000 |
02 |
2 |
+------+-------+------+
The query calculates how many different days appear in the table for each year/month combination,
with automatic removal of duplicate entries.
3.6.9. Using AUTO_INCREMENT
The AUTO_INCREMENT attribute can be used to generate a unique identity for new rows:
CREATE TABLE animals (
id MEDIUMINT NOT NULL AUTO_INCREMENT,
name CHAR(30) NOT NULL,
PRIMARY KEY (id)
);
INSERT INTO animals (name) VALUES ('dog'),('cat'),('penguin'),
('lax'),('whale'),('ostrich');
SELECT * FROM animals;
Which returns:
+----+---------+
| id | name
|
+----+---------+
| 1 | dog
|
| 2 | cat
|
| 3 | penguin |
| 4 | lax
|
| 5 | whale
|
| 6 | ostrich |
+----+---------+
206
MySQL Tutorial
You can retrieve the most recent AUTO_INCREMENT value with the LAST_INSERT_ID() SQL
function or the mysql_insert_id() C API function. These functions are connection-specific,
so their return value is not affected by another connection also doing inserts.
Note: For a multiple-row insert, LAST_INSERT_ID()/mysql_insert_id() actually returns
the AUTO_INCREMENT key from the first of the inserted rows. This allows multiple-row inserts to
be reproduced correctly on other servers in a replication setup.
For MyISAM and BDB tables you can specify AUTO_INCREMENT on a secondary column in a multiple-column index. In this case, the generated value for the AUTO_INCREMENT column is calculated as MAX(auto_increment_column)+1 WHERE prefix=given-prefix. This is
useful when you want to put data into ordered groups.
CREATE TABLE animals (
grp ENUM('fish','mammal','bird') NOT NULL,
id MEDIUMINT NOT NULL AUTO_INCREMENT,
name CHAR(30) NOT NULL,
PRIMARY KEY (grp,id)
);
INSERT INTO animals (grp,name) VALUES('mammal','dog'),('mammal','cat'),
('bird','penguin'),('fish','lax'),('mammal','whale'),
('bird','ostrich');
SELECT * FROM animals ORDER BY grp,id;
Which returns:
+--------+----+---------+
| grp
| id | name
|
+--------+----+---------+
| fish
| 1 | lax
|
| mammal | 1 | dog
|
| mammal | 2 | cat
|
| mammal | 3 | whale
|
| bird
| 1 | penguin |
| bird
| 2 | ostrich |
+--------+----+---------+
Note that in this case (when the AUTO_INCREMENT column is part of a multiple-column index),
AUTO_INCREMENT values are reused if you delete the row with the biggest AUTO_INCREMENT
value in any group. This happens even for MyISAM tables, for which AUTO_INCREMENT values
normally are not reused.)
If the AUTO_INCREMENT column is part of multiple indexes, MySQL will generate sequence values using the index that begins with the AUTO_INCREMENT column, if there is one. For example, if
the animals table contained indexes PRIMARY KEY (grp, id) and INDEX (id), MySQL
would ignore the PRIMARY KEY for generating sequence values. As a result, the table would contain a single sequence, not a sequence per grp value.
To start with an AUTO_INCREMENT value other than 1, you can set that value with CREATE TABLE or ALTER TABLE, like this:
mysql> ALTER TABLE tbl AUTOINCREMENT = 100;
Note that this feature is available for InnoDB tables only as of MySQL version 4.1.12 and 5.0.3.
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.
207
MySQL Tutorial
The project involves a screening part where all twins in Sweden older than 65 years are interviewed
by telephone. Twins who meet certain criteria are passed on to the next stage. In this latter stage,
twins who want to participate are visited by a doctor/nurse team. Some of the examinations include
physical and neuropsychological examination, laboratory testing, neuroimaging, psychological
status assessment, and family history collection. In addition, data are collected on medical and environmental risk factors.
More information about Twin studies can be found at: http://www.mep.ki.se/twinreg/index_en.html
The latter part of the project is administered with a Web interface written using Perl and MySQL.
Each night all data from the interviews is moved into a MySQL database.
3.7.1. Find All Non-distributed Twins
The following query is used to determine who goes into the second part of the project:
SELECT
CONCAT(p1.id, p1.tvab) + 0 AS tvid,
CONCAT(p1.christian_name, ' ', p1.surname) AS Name,
p1.postal_code AS Code,
p1.city AS City,
pg.abrev AS Area,
IF(td.participation = 'Aborted', 'A', ' ') AS A,
p1.dead AS dead1,
l.event AS event1,
td.suspect AS tsuspect1,
id.suspect AS isuspect1,
td.severe AS tsevere1,
id.severe AS isevere1,
p2.dead AS dead2,
l2.event AS event2,
h2.nurse AS nurse2,
h2.doctor AS doctor2,
td2.suspect AS tsuspect2,
id2.suspect AS isuspect2,
td2.severe AS tsevere2,
id2.severe AS isevere2,
l.finish_date
FROM
twin_project AS tp
/* For Twin 1 */
LEFT JOIN twin_data AS td ON tp.id = td.id
AND tp.tvab = td.tvab
LEFT JOIN informant_data AS id ON tp.id = id.id
AND tp.tvab = id.tvab
LEFT JOIN harmony AS h ON tp.id = h.id
AND tp.tvab = h.tvab
LEFT JOIN lentus AS l ON tp.id = l.id
AND tp.tvab = l.tvab
/* For Twin 2 */
LEFT JOIN twin_data AS td2 ON p2.id = td2.id
AND p2.tvab = td2.tvab
LEFT JOIN informant_data AS id2 ON p2.id = id2.id
AND p2.tvab = id2.tvab
LEFT JOIN harmony AS h2 ON p2.id = h2.id
AND p2.tvab = h2.tvab
LEFT JOIN lentus AS l2 ON p2.id = l2.id
AND p2.tvab = l2.tvab,
person_data AS p1,
person_data AS p2,
postal_groups AS pg
WHERE
/* p1 gets main twin and p2 gets his/her twin. */
/* ptvab is a field inverted from tvab */
p1.id = tp.id AND p1.tvab = tp.tvab AND
p2.id = p1.id AND p2.ptvab = p1.tvab AND
208
MySQL Tutorial
/* Just the screening survey */
tp.survey_no = 5 AND
/* Skip if partner died before 65 but allow emigration (dead=9) */
(p2.dead = 0 OR p2.dead = 9 OR
(p2.dead = 1 AND
(p2.death_date = 0 OR
(((TO_DAYS(p2.death_date) - TO_DAYS(p2.birthday)) / 365)
>= 65))))
AND
(
/* Twin is suspect */
(td.future_contact = 'Yes' AND td.suspect = 2) OR
/* Twin is suspect - Informant is Blessed */
(td.future_contact = 'Yes' AND td.suspect = 1
AND id.suspect = 1) OR
/* No twin - Informant is Blessed */
(ISNULL(td.suspect) AND id.suspect = 1
AND id.future_contact = 'Yes') OR
/* Twin broken off - Informant is Blessed */
(td.participation = 'Aborted'
AND id.suspect = 1 AND id.future_contact = 'Yes') OR
/* Twin broken off - No inform - Have partner */
(td.participation = 'Aborted' AND ISNULL(id.suspect)
AND p2.dead = 0))
AND
l.event = 'Finished'
/* Get at area code */
AND SUBSTRING(p1.postal_code, 1, 2) = pg.code
/* Not already distributed */
AND (h.nurse IS NULL OR h.nurse=00 OR h.doctor=00)
/* Has not refused or been aborted */
AND NOT (h.status = 'Refused' OR h.status = 'Aborted'
OR h.status = 'Died' OR h.status = 'Other')
ORDER BY
tvid;
Some explanations:
•
CONCAT(p1.id, p1.tvab) + 0 AS tvid
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 optimize the query.
This query demonstrates, among other things, how to do lookups on a table from the same table with
a join (p1 and p2). In the example, this is used to check whether a twin's partner died before the age
of 65. If so, the row is not returned.
All of the above exist in all tables with twin-related information. We have a key on both id,tvab
(all tables), and id,ptvab (person_data) to make queries faster.
On our production machine (A 200MHz UltraSPARC), this query returns about 150-200 rows and
209
MySQL Tutorial
takes less than one second.
The current number of records in the tables used in the query:
Table
Rows
person_data
71074
lentus
5291
twin_project
5286
twin_data
2012
informant_data
663
harmony
381
postal_groups
100
3.7.2. Show a Table of Twin Pair Status
Each interview ends with a status code called event. The query shown here is used to display a table over all twin pairs combined by event. This indicates in how many pairs both twins are finished,
in how many pairs one twin is finished and the other refused, and so on.
SELECT
t1.event,
t2.event,
COUNT(*)
FROM
lentus AS t1,
lentus AS t2,
twin_project AS tp
WHERE
/* We are looking at one pair at a time */
t1.id = tp.id
AND t1.tvab=tp.tvab
AND t1.id = t2.id
/* Just the screening survey */
AND tp.survey_no = 5
/* This makes each pair only appear once */
AND t1.tvab='1' AND t2.tvab='2'
GROUP BY
t1.event, t2.event;
3.8. Using MySQL with Apache
There are programs that let you authenticate your users from a MySQL database and also let you
write your log files into a MySQL table.
You can change the Apache logging format to be easily readable by MySQL by putting the following into the Apache configuration file:
LogFormat \
"\"%h\",%{%Y%m%d%H%M%S}t,%>s,\"%b\",\"%{Content-Type}o\",
\"%U\",\"%{Referer}i\",\"%{User-Agent}i\""
To load a log file in that format into MySQL, you can use a statement something like this:
\
LOAD DATA INFILE '/local/access_log' INTO TABLE tbl_name
FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"' ESCAPED BY '\\'
210
MySQL Tutorial
The named table should be created to have columns that correspond to those that the LogFormat
line writes to the log file.
211
Chapter 4. Using MySQL Programs
This chapter provides a brief overview of the command-line programs provided by MySQL AB and
discusses how to specify options when you run these programs. Most programs have options that are
specific to their own operation, but the syntax for specifying options is similar for all of them. Later
chapters provide more detailed descriptions of individual programs, including which options they
recognize.
MySQL AB also provide three GUI client programs for use with the MySQL server:
•
MySQL Administrator [http://dev.mysql.com/doc/administrator/en/]: This tool is used for administering MySQL servers, databases, tables, and users.
•
MySQL Query Browser [http://dev.mysql.com/doc/query-browser/en/]: This graphical tool is
provided by MySQL AB for creating, executing, and optimizing queries on MySQL databases.
•
MySQL Migration Toolkit [http://dev.mysql.com/doc/migration-toolkit/en/]: This tool is intended to help you with migrating schemas and data from other relational database management
systems to MySQL.
4.1. Overview of MySQL Programs
MySQL AB provides several types of programs:
•
The MYSQL server and server startup scripts:
•
mysqld is the MySQL server
•
mysqld_safe, mysql.server, and mysqld_multi are server startup scripts
•
mysql_install_db initializes the data directory and the initial databases
These programs are discussed further in Chapter 5, Database Administration.
•
Client programs that access the server:
•
mysql is a command-line client for executing SQL statements interactively or in batch
mode.
•
mysqladmin is an administrative client.
•
mysqlcheck performs table maintenance operations
•
mysqldump and mysqlhotcopy make database backups.
•
mysqlimport imports data files.
•
mysqlshow displays information about databases and tables.
These programs are discussed further in Chapter 8, MySQL Client and Utility Programs.
•
Utility programs that operate independently of the server:
•
myisamchk performs table maintenance operations.
•
myisampack produces compressed, read-only tables.
•
mysqlbinlog is a tool for processing binary log files.
212
Using MySQL Programs
•
perror displays error code meanings.
myisamchk is discussed further in Chapter 5, Database Administration. The other programs
are further in Chapter 8, MySQL Client and Utility Programs.
Most MySQL distributions include all of these programs, except for those programs that are platform-specific. (For example, the server startup scripts are not used on Windows.) The exception is
that RPM distributions are more specialized. There is one RPM for the server, another for the client
programs, and so forth. If you appear to be missing one or more programs, see Chapter 2, Installing
MySQL for information on types of distributions and what they contain. It may be that you need to
install something else.
4.2. Invoking MySQL Programs
To invoke a MySQL program from the command line (that is, from your shell or command prompt),
enter the program name followed by any options or other arguments needed to instruct the program
what you want it to do. The following commands show some sample program invocations.
“shell>” represents the prompt for your command interpreter; it is not part of what you type. The
particular prompt you see depends on your command interpreter. Typical prompts are $ for sh or
bash, % for csh or tcsh, and C:\> for Windows command.com or cmd.exe.
shell>
shell>
shell>
shell>
mysql test
mysqladmin extended-status variables
mysqlshow --help
mysqldump --user=root personnel
Arguments that begin with a dash are option arguments. They typically specify the type of connection a program should make to the server or affect its operational mode. Options have a syntax that
is described in Section 4.3, “Specifying Program Options”.
Non-option arguments (arguments with no leading dash) provide additional information to the program. For example, the mysql program interprets the first non-option argument as a database
name, so the command mysql test indicates that you want to use the test database.
Later sections that describe individual programs indicate which options a program understands and
describe the meaning of any additional non-option arguments.
Some options are common to a number of programs. The most common of these are the --host, -user, and --password options that specify connection parameters. They indicate the host
where the MySQL server is running, and the username and password of your MySQL account. All
MySQL client programs understand these options; they allow you to specify which server to connect to and the account to use on that server.
You may find it necessary to invoke MySQL programs using the pathname to the bin directory in
which they are installed. This is likely to be the case if you get a “program not found” error whenever you attempt to run a MySQL program from any directory other than the bin directory. To make
it more convenient to use MySQL, you can add the pathname of the bin directory to your PATH
environment variable setting. Then to run a program you need only type its name, not its entire pathname.
Consult the documentation for your command interpreter for instructions on setting your PATH. The
syntax for setting environment variables is interpreter-specific.
4.3. Specifying Program Options
You can provide options for MySQL programs in several ways:
•
On the command line following the program name. This is most common for options that apply
213
Using MySQL Programs
to a specific invocation of the program.
•
In an option file that the program reads when it starts. This is common for options that you want
the program to use each time it runs.
•
In environment variables. These are useful for options that you want to apply each time the program runs, although in practice option files are used more commonly for this purpose. (Section 5.11.2, “Running Multiple Servers on Unix” discusses one situation in which environment
variables can be very helpful. It describes a handy technique that uses such variables to specify
the TCP/IP port number and Unix socket file for both the server and client programs.)
MySQL programs determine which options are given first by examining environment variables,
then option files, and then the command line. If an option is specified multiple times, the last occurrence takes precedence. This means that environment variables have the lowest precedence and
command-line options the highest.
You can take advantage of the way that MySQL programs process options by specifying the default
values for a program's options in an option file. Then you need not type them each time you run the
program, but can override the defaults if necessary by using command-line options.
4.3.1. Using Options on the Command Line
Program options specified on the command line follow these rules:
•
Options are given after the command name.
•
An option argument begins with one dash or two dashes, depending on whether it has a short
name or a long name. Many options have both forms. For example, -? and --help are the
short and long forms of the option that instructs a MySQL program to display a help message.
•
Option names are case sensitive. -v and -V are both legal and have different meanings. (They
are the corresponding short forms of the --verbose and --version options.)
•
Some options take a value following the option name. For example, -h localhost or -host=localhost indicate the MySQL server host to a client program. The option value
tells the program the name of the host where the MySQL server is running.
•
For a long option that takes a value, separate the option name and the value by an ‘=’ sign. For a
short option that takes a value, the option value can immediately follow the option letter, or
there can be a space between. (-hlocalhost and -h localhost are equivalent.) An exception to this rule is the option for specifying your MySQL password. This option can be given
in long form as --password=pass_val or as --password. In the latter case (with no
password value given), the program prompts you for the password. The password option also
may be given in short form as -ppass_val or as -p. However, for the short form, if the password value is given, it must follow the option letter with no intervening space. The reason for
this is that if a space follows the option letter, the program has no way to tell whether a following argument is supposed to be the password value or some other kind of argument. Consequently, the following two commands have two completely different meanings:
shell> mysql -ptest
shell> mysql -p test
The first command instructs mysql to use a password value of test, but specifies no default
database. The second instructs mysql to prompt for the password value and to use test as the
default database.
MySQL 4.0 introduced some additional flexibility in the way you specify options. These changes
were made in MySQL 4.0.2. Some of them relate to the way you specify options that have
“enabled” and “disabled” states, and to the use of options that might be present in one version of
214
Using MySQL Programs
MySQL but not another. Those capabilities are discussed in this section. Another change pertains to
the way you use options to set program variables. Section 4.3.4, “Using Options to Set Program
Variables” discusses that topic further.
Some options control behavior that can be turned on or off. For example, the mysql client supports
a --column-names option that determines whether or not to display a row of column names at
the beginning of query results. By default, this option is enabled. However, you may want to disable
it in some instances, such as when sending the output of mysql into another program that expects
to see only data and not an initial header line.
To disable column names, you can specify the option using any of these forms:
--disable-column-names
--skip-column-names
--column-names=0
The --disable and --skip prefixes and the =0 suffix all have the same effect: They turn the
option off.
The “enabled” form of the option may be specified in any of these ways:
--column-names
--enable-column-names
--column-names=1
Another change to option processing introduced in MySQL 4.0 is that you can use the --loose
prefix for command-line options. If an option is prefixed by --loose, the program does not exit
with an error if it does not recognize the option, but instead issues only a warning:
shell> mysql --loose-no-such-option
mysql: WARNING: unknown option '--no-such-option'
The --loose prefix can be useful when you run programs from multiple installations of MySQL
on the same machine, at least if all the versions are as recent as 4.0.2. This prefix is particularly useful when you list options in an option file. An option that may not be recognized by all versions of a
program can be given using the --loose prefix (or loose in an option file). Versions of the program that do not recognize the option issue a warning and ignore the option. This strategy requires
that versions involved be 4.0.2 or later, because earlier versions know nothing of the --loose convention.
Another option which may be occasionally useful with mysql is the -e or --execute option,
which can be used to pass SQL statements to the server. The statements must be surrounded by
(single or double) quotation marks. (However, if you wish to use quoted values within the query,
then you should use double quotes for the query, and single quotes for any quoted values within the
query.) When this option is used, the statements are executed, and then mysql exits to the command shell immediately thereafter.
For example, you can use the following to obtain a list of user accounts:
shell> mysql -u root -p -e "SELECT User, Host FROM user" mysql
Enter password: ******
+------+-----------+
| User | Host
|
+------+-----------+
|
| gigan
|
| root | gigan
|
|
| localhost |
| jon | localhost |
| root | localhost |
+------+-----------+
shell>
215
Using MySQL Programs
Note that the name of the mysql database was passed as a separate argument. However, the same
query could have been executed using mysql -u root -p -e "SELECT User, Host
FROM mysql.user" from the shell prompt.
Multiple SQL statements may be passed in this way, separated by semicolons:
shell> mysql -u root -p --execute="SELECT Name FROM Country WHERE Name LIKE 'AU%
Enter password: ******
+-----------+
| Name
|
+-----------+
| Australia |
| Austria
|
+-----------+
+----------+
| COUNT(*) |
+----------+
|
4079 |
+----------+
Note that the long form (--execute) must be followed by an equals sign (=).
The -e option may also be used to pass commands in an analogous fashion to the ndb_mgm management client for MySQL Cluster. See Section 16.3.6, “Safe Shutdown and Restart” for an example.
4.3.2. Using Option Files
MySQL programs can read startup options from option files (also sometimes called configuration
files). Option files provide a convenient way to specify commonly used options so that they need
not be entered on the command line each time you run a program. Option file capability is available
from MySQL 3.22 on.
The following programs support option files: myisamchk, myisampack, mysql,
mysql.server, mysqladmin, mysqlbinlog, mysqlcc, mysqlcheck, mysqld_safe,
mysqldump, mysqld, mysqlhotcopy, mysqlimport, and mysqlshow.
Note: Option files used with MySQL Cluster programs are covered in Section 16.4, “MySQL
Cluster Configuration”.
On Windows, MySQL programs read startup options from the following files:
Filename
Purpose
WINDIR\my.ini
Global options
C:\my.cnf
Global options
INSTALLDIR\my.ini
Global Options
defaults-extra-file The file specified with --defaults-extra-file=path, if any
WINDIR represents the location of your Windows directory. This is commonly C:\WINDOWS or
C:\WINNT. You can determine its exact location from the value of the WINDIR environment variable using the following command:
C:\> echo %WINDIR%
INSTALLDIR represents the installation directory of MySQL. This is typically the case with
MySQL 4.1.5 and higher, when installed using the installation and configuration wizards. See Section 2.3.5.14, “The Location of the my.ini File”.
On Unix, MySQL programs read startup options from the following files:
216
Using MySQL Programs
Filename
Purpose
/etc/my.cnf
Global options
$MYSQL_HOME/my.cnf
Server-specific options
defaults-extra-file The file specified with --defaults-extra-file=path, if any
~/.my.cnf
User-specific options
MYSQL_HOME is an environment variable containing the path to the directory in which the serverspecific my.cnf file resides. (This was DATADIR prior to MySQL version 5.0.3.)
If MYSQL_HOME is not set and there is a my.cnf file in DATADIR and there is no my.cnf file in
BASEDIR, mysqld_safe sets MYSQL_HOME to DATADIR. Otherwise, if MYSQL_HOME is not
set and there is no my.cnf in DATADIR, then mysqld_safe sets MYSQL_HOME to BASEDIR.
Typically this is /usr/local/mysql/data for a binary installation or /usr/local/var for
a source installation. Note that this is the data directory location that was specified at configuration
time, not the one specified with --datadir when mysqld starts. Use of --datadir at runtime
has no effect on where the server looks for option files, because it looks for them before processing
any command-line arguments.
MySQL looks for option files in the order just described and reads any that exist. If an option file
that you want to use does not exist, create it with a plain text editor. If multiple option files exist, an
option specified in a file read later takes precedence over the same option specified in a file read
earlier.
Note: On Unix platforms, MySQL ignores configuration files that are world-writable. This is intentional, and acts as a security measure.
Any long option that may be given on the command line when running a MySQL program can be
given in an option file as well. To get the list of available options for a program, run it with the -help option.
The syntax for specifying options in an option file is similar to command-line syntax, except that
you omit the leading two dashes. For example, --quick or --host=localhost on the command line should be specified as quick or host=localhost in an option file. To specify an option of the form --loose-opt_name in an option file, write it as loose-opt_name.
Empty lines in option files are ignored. Non-empty lines can take any of the following forms:
•
#comment , ;comment
Comment lines start with ‘#’ or ‘;’. As of MySQL 4.0.14, a ‘#’ comment can start in the middle
of a line as well.
•
[group]
group is the name of the program or group for which you want to set options. After a group
line, any opt_name or set-variable lines apply to the named group until the end of the
option file or another group line is given.
•
opt_name
This is equivalent to --opt_name on the command line.
•
opt_name=value
This is equivalent to --opt_name=value on the command line. In an option file, you can
have spaces around the ‘=’ character, something that is not true on the command line. As of
MySQL 4.0.16, you can quote the value with double quotes or single quotes. This is useful if the
value contains a ‘#’ comment character or whitespace.
217
Using MySQL Programs
•
set-variable = var_name=value
Set the program variable var_name to the given value. This is equivalent to -set-variable=var_name=value on the command line. Spaces are allowed around the
first ‘=’ character but not around the second. This syntax is deprecated as of MySQL 4.0. See
Section 4.3.4, “Using Options to Set Program Variables” for more information on setting program variables.
Leading and trailing blanks are automatically deleted from option names and values. You may use
the escape sequences ‘\b’, ‘\t’, ‘\n’, ‘\r’, ‘\\’, and ‘\s’ in option values to represent the backspace, tab, newline, carriage return, and space characters.
On Windows, if an option value represents a pathname, you should specify the value using ‘/’
rather than ‘\’ as the pathname separator. If you use ‘\’, you must double it as ‘\\’, because ‘\’ is
the escape character in MySQL.
If an option group name is the same as a program name, options in the group apply specifically to
that program.
The [client] option group is read by all client programs (but not by mysqld). This allows you
to specify options that apply to all clients. For example, [client] is the perfect group to use to
specify the password that you use to connect to the server. (But make sure that the option file is
readable and writable only by yourself, so that other people cannot find out your password.) Be sure
not to put an option in the [client] group unless it is recognized by all client programs that you
use. Programs that do not understand the option quit after displaying an error message if you try to
run them.
Beginning with MySQL 4.1.11 in the 4.1 series and MySQL 5.0.4 in the 5.0 series, it is possible to
use !include directives in option files to include specific files and !includedir to search specific directories for option files. For example, to include the file /home/mydir/myopt.cnf,
you can use the following:
!include /home/me/myopt.cnf
To search the directory /home/mydir for all files ending in .cnf and to read these as option
files, you would use:
!includedir /home/mydir
Note that these options are section-specific. For example, suppose that you were to use something in
my.cnf such as the following:
[mysqld]
!include /home/mydir/myopt.cnf
In such a case, the file myopt.cnf would be processed only for the server, and the !include
directive would be ignored by any client applications. However, if you were to use the following:
[mysqldump]
!includedir /home/mydir/my-dump-options
then the directory /home/mydir/my-dump-options would be checked for option files ending
in .cnf by mysqldump only, and not by the server or by any other client applications.
Note: Currently, any files to be found and included using the !includedir directive on Unix operating systems must have filenames ending in .cnf. On Windows, this directive also checks for
files with a .ini extension (in addition to .cnf).
As of MySQL 4.0.14, if you want to create option groups that should be read only by one specific
218
Using MySQL Programs
mysqld server release series only, you can do this by using groups with names of
[mysqld-4.0], [mysqld-4.1], [mysqld-5.0], and so forth. The following group indicates that the --new option should be used only by MySQL servers with 4.0.x version numbers:
[mysqld-4.0]
new
Here is a typical global option file:
[client]
port=3306
socket=/tmp/mysql.sock
[mysqld]
port=3306
socket=/tmp/mysql.sock
key_buffer_size=16M
max_allowed_packet=8M
[mysqldump]
quick
The preceding option file uses var_name=value syntax for the lines that set the
key_buffer_size and max_allowed_packet variables. Prior to MySQL 4.0.2, you would
need to use set-variable syntax instead (described earlier in this section).
Here is a typical user option file:
[client]
# The following password will be sent to all standard MySQL clients
password="my_password"
[mysql]
no-auto-rehash
set-variable = connect_timeout=2
[mysqlhotcopy]
interactive-timeout
This option file uses set-variable syntax to set the connect_timeout variable. For
MySQL 4.0.2 and up, you can also set the variable using just connect_timeout=2.
If you have a source distribution, you can find sample option files named my-xxxx.cnf in the
support-files directory. If you have a binary distribution, look in the support-files directory under your MySQL installation directory. On Windows the sample option files may also be
located in the MySQL installation directory (see earlier in this section or Chapter 2, Installing
MySQL if you do not know where this is). Currently there are sample option files for small, medium, large, and very large systems. To experiment with one of these files, copy it to C:\my.cnf on
Windows or to .my.cnf in your home directory on Unix.
Note: On Windows, the .cnf option file extension might not be displayed.
All MySQL programs that support option files handle the following command-line options:
•
--no-defaults
Don't read any option files.
•
--print-defaults
Print the program name and all options that it gets from option files.
219
Using MySQL Programs
•
--defaults-file=path_name
Use only the given option file. path_name is the full pathname to the file.
•
--defaults-extra-file=path_name
Read this option file after the global option file but before the user option file. path_name is
the full pathname to the file.
To work properly, each of these options must immediately follow the command name on the command line, with the exception that --print-defaults may be used immediately after -defaults-file or --defaults-extra-file.
In shell scripts, you can use the my_print_defaults program to parse option files. The following example shows the output that my_print_defaults might produce when asked to show the
options found in the [client] and [mysql] groups:
shell> my_print_defaults client mysql
--port=3306
--socket=/tmp/mysql.sock
--no-auto-rehash
Note for developers: Option file handling is implemented in the C client library simply by processing all matching options (that is, options in the appropriate group) before any command-line arguments. This works well for programs that use the last instance of an option that is specified multiple times. If you have a C or C++ program that handles multiply-specified options this way but
that doesn't read option files, you need add only two lines to give it that capability. Check the source
code of any of the standard MySQL clients to see how to do this.
Several other language interfaces to MySQL are based on the C client library, and some of them
provide a way to access option file contents. These include Perl and Python. See the documentation
for your preferred interface for details.
4.3.3. Using Environment Variables to Specify Options
To specify an option using an environment variable, set the variable using the syntax appropriate for
your comment processor. For example, on Windows or NetWare, you can set the USER variable to
specify your MySQL account name. To do so, use this syntax:
SET USER=your_name
The syntax on Unix depends on your shell. Suppose that you want to specify the TCP/IP port number using the MYSQL_TCP_PORT variable. Typical syntax (such as for sh, bash, zsh, and so on)
is as follows:
MYSQL_TCP_PORT=3306
export MYSQL_TCP_PORT
The first command sets the variable, and the export command exports the variable to the shell environment so that its value becomes accessible to MySQL and other processes.
For csh and tcsh there are similar issues. When running these shells, use setenv to make the
shell variable available to the environment:
setenv MYSQL_TCP_PORT 3306
The commands to set environment variables can be executed at your command prompt to take effect
immediately. These settings persist until you log out. To have the settings take effect each time you
log in, place the appropriate command or commands in a startup file that your command interpreter
220
Using MySQL Programs
reads each time it starts. Typical startup files are AUTOEXEC.BAT for Windows,
.bash_profile for bash, or .tcshrc for tcsh. Consult the documentation for your command interpreter for specific details.
Appendix G, Environment Variables lists all environment variables that affect MySQL program operation.
4.3.4. Using Options to Set Program Variables
Many MySQL programs have internal variables that can be set at runtime. As of MySQL 4.0.2, program variables are set the same way as any other long option that takes a value. For example,
mysql has a max_allowed_packet variable that controls the maximum size of its communication buffer. To set the max_allowed_packet variable for mysql to a value of 16MB, use either
of the following commands:
shell> mysql --max_allowed_packet=16777216
shell> mysql --max_allowed_packet=16M
The first command specifies the value in bytes. The second specifies the value in megabytes. Variable values can have a suffix of K, M, or G (either uppercase or lowercase) to indicate units of kilobytes, megabytes, or gigabytes.
In an option file, the variable setting is given without the leading dashes:
[mysql]
max_allowed_packet=16777216
Or:
[mysql]
max_allowed_packet=16M
If you like, underscores in a variable name can be specified as dashes.
Note: The older syntax --set-variable = option=value is still recognized in MySQL
5.0, but is now deprecated.
In an option file, omit the leading dashes:
[mysql]
set-variable = max_allowed_packet=16777216
Or:
[mysql]
set-variable = max_allowed_packet=16M
With --set-variable, underscores in variable names cannot be given as dashes for versions of
MySQL older than 4.0.2.
The --set-variable option is still recognized in MySQL 4.0.2 and up, but is deprecated.
Some server variables can be set at runtime. For details, see Section 5.3.3.1, “Dynamic System Variables”.
221
Chapter 5. Database Administration
This chapter covers topics that deal with administering a MySQL installation, such as configuring
the server, managing user accounts, and performing backups.
5.1. The MySQL Server and Server Startup
Scripts
The MySQL server, mysqld, is the main program that does most of the work in a MySQL installation. The server is accompanied by several related scripts that perform setup operations when you
install MySQL or that are helper programs to assist you in starting and stopping the server.
This section provides an overview of the server and related programs, and information about server
startup scripts. Information about configuring the server itself is given in Section 5.3, “mysqld —
The MySQL Server”.
5.1.1. Overview of the Server-Side Scripts and Utilities
All MySQL programs take many different options. However, every MySQL program provides a -help option that you can use to get a description of the program's options. For example, try
mysqld --help.
You can override default options for all standard programs by specifying options on the command
line or in an option file. Section 4.3, “Specifying Program Options”.
The following list briefly describes the MySQL server and server-related programs:
•
mysqld
The SQL daemon (that is, the MySQL server). To use client programs, this program must be
running, because clients gain access to databases by connecting to the server. See Section 5.3,
“mysqld — The MySQL Server”.
•
mysqld-max
A version of the server that includes additional features. See Section 5.1.2, “The mysqld-max
Extended MySQL Server”.
•
mysqld_safe
A server startup script. mysqld_safe attempts to start mysqld-max if it exists, and
mysqld otherwise. See Section 5.1.3, “mysqld_safe — MySQL Server Startup Script”.
•
mysql.server
A server startup script. This script is used on systems that use run directories containing scripts
that start system services for particular run levels. It invokes mysqld_safe to start the
MySQL server. See Section 5.1.4, “mysql.server — MySQL Server Startup Script”.
•
mysqld_multi
A server startup script that can start or stop multiple servers installed on the system. See Section 5.1.5, “mysqld_multi — Program for Managing Multiple MySQL Servers”.
•
mysql_install_db
This script creates the MySQL grant tables with default privileges. It is usually executed only
once, when first installing MySQL on a system. See Section 2.9.2, “Unix Post-Installation Pro222
Database Administration
cedures”.
•
mysql_fix_privilege_tables
This script is used after an upgrade install operation, to update the grant tables with any changes
that have been made in newer versions of MySQL. See Section 2.10.8, “Upgrading the Grant
Tables”.
There are several other programs that also are run on the server host:
•
myisamchk
A utility to describe, check, optimize, and repair MyISAM tables. myisamchk is described in
Section 5.8.5, “myisamchk — MyISAM Table-Maintenance Utility”.
•
make_binary_distribution
This program makes a binary release of a compiled MySQL. This could be sent by FTP to /
pub/mysql/upload/ on ftp.mysql.com for the convenience of other MySQL users.
•
mysqlbug
The MySQL bug reporting script. It can be used to send a bug report to the MySQL mailing list.
(You can also visit http://bugs.mysql.com/ to file a bug report online. See Section 1.7.1.3, “How
to Report Bugs or Problems”.)
5.1.2. The mysqld-max Extended MySQL Server
A MySQL-Max server is a version of the mysqld MySQL server that has been built to include additional features.
The distribution to use depends on your platform:
•
For Windows, MySQL binary distributions include both the standard server (mysqld.exe)
and the MySQL-Max server (mysqld-max.exe), so you need not get a special distribution.
Just use a regular Windows distribution, available at http://dev.mysql.com/downloads/. See Section 2.3, “Installing MySQL on Windows”.
•
For Linux, if you install MySQL using RPM distributions, use the regular MySQL-server
RPM first to install a standard server named mysqld. Then use the MySQL-Max RPM to install a server named mysqld-max. The MySQL-Max RPM presupposes that you have installed
the regular server RPM. See Section 2.4, “Installing MySQL on Linux” for more information on
the Linux RPM packages.
•
All other MySQL-Max distributions contain a single server that is named mysqld but that has
the additional features included.
You can find the MySQL-Max binaries
tp://dev.mysql.com/downloads/mysql-4.0.html.
on
the
MySQL
AB
Web
site
MySQL AB builds the MySQL-Max servers by using the following configure options:
•
--with-server-suffix=-max
This option adds a -max suffix to the mysqld version string.
•
--with-innodb
223
at
ht-
Database Administration
This option enables support for the InnoDB storage engine. MySQL-Max servers always include
InnoDB support, but this option actually is needed only for MySQL 3.23. From MySQL 4 onwards, InnoDB is included by default in binary distributions, so you do not need a MySQL-Max
server merely to obtain InnoDB support.
•
--with-bdb
This option enables support for the Berkeley DB (BDB) storage engine.
•
--with-blackhole-storage-engine
This option enables support for the BLACKHOLE storage engine in MySQL 4.1.11 and newer.
•
USE_SYMDIR
This define is enabled to turn on database symbolic link support for Windows. (This applies
only before MySQL 4.0. As of MySQL 4.0, symbolic link support is available for all Windows
servers, so a Max server is not needed to take advantage of this feature.)
•
--with-ndbcluster
This option enables support for the NDB Cluster storage engine in MySQL 4.1.2 and newer.
Note that as of MySQL 5.0.3, Cluster is supported on Linux, Solaris, and Mac OS X only.
MySQL-Max binary distributions are a convenience for those who wish to install precompiled programs. If you build MySQL using a source distribution, you can build your own Max-like server by
enabling the same features at configuration time that the MySQL-Max binary distributions are built
with.
MySQL-Max servers include the BerkeleyDB (BDB) storage engine whenever possible, but not all
platforms support BDB.
MySQL-Max servers for Solaris, Mac OS X, and Linux (on most platforms) include support for the
NDB Cluster storage engine. Note that the server must be started with the ndbcluster option in
order to run the server as part of a MySQL Cluster. (For details, see Section 16.4, “MySQL Cluster
Configuration”.)
The following table shows on which platforms allow MySQL-Max binaries include support for
BDB and/or NDB Cluster:
System
BDB Support
NDB Support
AIX 4.3
N
N
HP-UX 11.0
N
N
Linux-Alpha
N
Y
Linux-IA-64
N
N
Linux-Intel
Y
Y
Mac OS X
N
N
NetWare
N
N
SCO OSR5
Y
N
Solaris-SPARC
Y
Y
Solaris-Intel
N
Y
UnixWare
Y
N
Windows NT/2000/XP
Y
N
To find out which storage engines your server supports, issue the following statement:
224
Database Administration
mysql> SHOW ENGINES;
+------------+---------+-------------------------------------------------------| Engine
| Support | Comment
+------------+---------+-------------------------------------------------------| MyISAM
| DEFAULT | Default engine as of MySQL 3.23 with great performance
| HEAP
| YES
| Alias for MEMORY
| MEMORY
| YES
| Hash based, stored in memory, useful for temporary tabl
| MERGE
| YES
| Collection of identical MyISAM tables
| MRG_MYISAM | YES
| Alias for MERGE
| ISAM
| NO
| Obsolete storage engine, now replaced by MyISAM
| MRG_ISAM
| NO
| Obsolete storage engine, now replaced by MERGE
| InnoDB
| YES
| Supports transactions, row-level locking, and foreign k
| INNOBASE
| YES
| Alias for INNODB
| BDB
| YES
| Supports transactions and page-level locking
| BERKELEYDB | YES
| Alias for BDB
| NDBCLUSTER | NO
| Clustered, fault-tolerant, memory-based tables
| NDB
| NO
| Alias for NDBCLUSTER
| EXAMPLE
| NO
| Example storage engine
| ARCHIVE
| NO
| Archive storage engine
| CSV
| NO
| CSV storage engine
+------------+---------+-------------------------------------------------------16 rows in set (0.02 sec)
(See also Section 13.5.4.8, “SHOW ENGINES Syntax”.)
Before MySQL 4.1.2, SHOW ENGINES is unavailable. Use the following statement instead and
check the value of the variable for the storage engine in which you are interested:
mysql> SHOW VARIABLES LIKE 'have_%';
+---------------------+-------+
| Variable_name
| Value |
+---------------------+-------+
| have_archive
| NO
|
| have_bdb
| YES
|
| have_compress
| YES
|
| have_crypt
| NO
|
| have_csv
| NO
|
| have_example_engine | NO
|
| have_geometry
| YES
|
| have_innodb
| YES
|
| have_isam
| NO
|
| have_ndbcluster
| NO
|
| have_openssl
| NO
|
| have_query_cache
| YES
|
| have_raid
| NO
|
| have_rtree_keys
| YES
|
| have_symlink
| YES
|
+---------------------+-------+
15 rows in set (0.15 sec)
The precise output from these SHOW commands will vary according to the MySQL version used
(and the features which are enabled). The values in the second column indicate the server's level of
support for each feature, as shown here:
Value
Meaning
YES
The feature is supported and is active.
NO
The feature is not supported.
DISABLED
The feature is supported but has been disabled.
A value of NO means that the server was compiled without support for the feature, so it cannot be
activated at runtime.
A value of DISABLED occurs either because the server was started with an option that disables the
225
Database Administration
feature, or because not all options required to enable it were given. In the latter case, the
host_name.err error log file should contain a reason indicating why the option is disabled.
One situation in which you might see DISABLED occurs with MySQL 3.23 when the InnoDB storage engine is compiled in. In MySQL 3.23, you must supply at least the innodb_data_file_path option at runtime to set up the InnoDB tablespace. Without this option, InnoDB disables itself. See Section 15.3, “InnoDB in MySQL 3.23”. You can specify configuration options for the BDB storage engine, too, but BDB does not disable itself if you do not provide
them. See Section 14.4.3, “BDB Startup Options”.
You might also see DISABLED for the InnoDB, BDB, or ISAM storage engines if the server was
compiled to support them, but was started with the --skip-innodb, --skip-bdb, or -skip-isam options at runtime.
As of Version 3.23, all MySQL servers support MyISAM tables, because MyISAM is the default
storage engine.
5.1.3. mysqld_safe — MySQL Server Startup Script
mysqld_safe is the recommended way to start a mysqld server on Unix and NetWare.
mysqld_safe adds some safety features such as restarting the server when an error occurs and
logging runtime information to an error log file. NetWare-specific behaviors are listed later in this
section.
Note: Before MySQL 4.0, mysqld_safe is named safe_mysqld. To preserve backward compatibility, MySQL binary distributions for some time will include safe_mysqld as a symbolic
link to mysqld_safe.
By default, mysqld_safe tries to start an executable named mysqld-max if it exists, or
mysqld otherwise. Be aware of the implications of this behavior:
•
On Linux, the MySQL-Max RPM relies on this mysqld_safe behavior. The RPM installs an
executable named mysqld-max, which causes mysqld_safe to automatically use that executable from that point on.
•
If you install a MySQL-Max distribution that includes a server named mysqld-max, then upgrade later to a non-Max version of MySQL, mysqld_safe still attempts to run the old
mysqld-max server. If you perform such an upgrade, you should manually remove the old
mysqld-max server to ensure that mysqld_safe runs the new mysqld server.
To override the default behavior and specify explicitly which server you want to run, specify a -mysqld or --mysqld-version option to mysqld_safe.
Many of the options to mysqld_safe are the same as the options to mysqld. See Section 5.3.1,
“mysqld Command-Line Options”.
All options specified to mysqld_safe on the command line are passed to mysqld. If you want to
use any options that are specific to mysqld_safe and that mysqld doesn't support, do not specify them on the command line. Instead, list them in the [mysqld_safe] group of an option file.
See Section 4.3.2, “Using Option Files”.
mysqld_safe reads all options from the [mysqld], [server], and [mysqld_safe] sections in option files. For backward compatibility, it also reads [safe_mysqld] sections, although
you should rename such sections to [mysqld_safe] when you begin using MySQL 4.0 or later.
mysqld_safe supports the following options:
•
--help
Display a help message and exit. (New in 5.0.3)
226
Database Administration
•
--autoclose
(NetWare only) On NetWare, mysqld_safe provides a screen presence. When you unload
(shut down) the mysqld_safe NLM, the screen does not by default go away. Instead, it
prompts for user input:
*<NLM has terminated; Press any key to close the screen>*
If you want NetWare to close the screen automatically instead, use the --autoclose option
to mysqld_safe.
•
--basedir=path
The path to the MySQL installation directory.
•
--core-file-size=size
The size of the core file mysqld should be able to create. The option value is passed to ulimit -c.
•
--datadir=path
The path to the data directory.
•
--defaults-extra-file=path
The name of an option file to be read in addition to the usual option files. If given, this option
must be first.
•
--defaults-file=path
The name of an option file to be read instead of the usual option files. If given, this option must
be first.
•
--err-log=path
The old form of the --log-error option, to be used before MySQL 4.0.
•
--ledir=path
The path to the directory containing the mysqld program. Use this option to explicitly indicate
the location of the server.
•
--log-error=path
Write the error log to the given file. See Section 5.10.1, “The Error Log”.
•
--mysqld=prog_name
The name of the server program (in the ledir directory) that you want to start. This option is
needed if you use the MySQL binary distribution but have the data directory outside of the binary distribution.
•
--mysqld-version=suffix
This option is similar to the --mysqld option, but you specify only the suffix for the server
program name. The basename is assumed to be mysqld. For example, if you use -mysqld-version=max, mysqld_safe starts the mysqld-max program in the ledir
directory. If the argument to --mysqld-version is empty, mysqld_safe uses mysqld in
the ledir directory.
•
--nice=priority
227
Database Administration
Use the nice program to set the server's scheduling priority to the given value. This option was
added in MySQL 4.0.14.
•
--no-defaults
Do not read any option files. If given, this option must be first.
•
--open-files-limit=count
The number of files mysqld should be able to open. The option value is passed to ulimit
-n. Note that you need to start mysqld_safe as root for this to work properly!
•
--pid-file=path
The path to the process ID file.
•
--port=port_num
The port number to use when listening for TCP/IP connections. The port number must be 1024
or higher unless MySQL is run as the root system user.
•
--skip-character-set-client-handshake
Ignore character set information sent by the client and use the default server character set. This
option makes MySQL 4.1 and higher behave like MySQL 4.0.
•
--socket=path
The Unix socket file to use for local connections.
•
--timezone=zone
Set the TZ time zone environment variable to the given option value. Consult your operating
system documentation for legal time zone specification formats.
•
--user={user_name | user_id}
Run the mysqld server as the user having the name user_name or the numeric user ID
user_id. (“User” in this context refers to a system login account, not a MySQL user listed in
the grant tables.)
When executing mysqld_safe, the --defaults-file or --defaults-extra-option
must be given first, or the option file will not be used. For example, this command will not use the
named option file:
mysqld_safe --port=port_num --defaults-file=file_name
Instead, use the following command:
mysqld_safe --defaults-file=file_name --port=port_num
The mysqld_safe script is written so that it normally can start a server that was installed from
either a source or a binary distribution of MySQL, even though these types of distributions typically
install the server in slightly different locations. (See Section 2.1.5, “Installation Layouts”.)
mysqld_safe expects one of the following conditions to be true:
•
The server and databases can be found relative to the directory from which mysqld_safe is
invoked. For binary distributions, mysqld_safe looks under its working directory for bin
and data directories. For source distributions, it looks for libexec and var directories. This
condition should be met if you execute mysqld_safe from your MySQL installation directory
228
Database Administration
(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 from the values configured into
the distribution at the time it was built. They should be correct if MySQL is installed in the location specified at configuration time.
Because mysqld_safe tries to find the server and databases relative to its own working directory,
you can install a binary distribution of MySQL anywhere, as long as you run mysqld_safe from
the MySQL installation directory:
shell> cd mysql_installation_directory
shell> bin/mysqld_safe &
If mysqld_safe fails, even when invoked from the MySQL installation directory, you can specify
the --ledir and --datadir options to indicate the directories in which the server and databases
are located on your system.
Normally, you should not edit the mysqld_safe script. Instead, configure mysqld_safe by using command-line options or options in the [mysqld_safe] section of a my.cnf option file. In
rare cases, it might be necessary to edit mysqld_safe to get it to start the server properly.
However, if you do this, your modified version of mysqld_safe might be overwritten if you upgrade MySQL in the future, so you should make a copy of your edited version that you can reinstall.
On NetWare, mysqld_safe is a NetWare Loadable Module (NLM) that is ported from the original Unix shell script. It does the following:
1.
Runs a number of system and option checks.
2.
Runs a check on MyISAM and ISAM tables.
3.
Provides a screen presence for the MySQL server.
4.
Starts mysqld, monitors it, and restarts it if it terminates in error.
5.
Sends error messages from mysqld to the host_name.err file in the data directory.
6.
Sends mysqld_safe screen output to the host_name.safe file in the data directory.
5.1.4. mysql.server — MySQL Server Startup Script
MySQL distributions on Unix include a script named mysql.server. It can be used on systems
such as Linux and Solaris that use System V-style run directories to start and stop system services. It
is also used by the Mac OS X Startup Item for MySQL.
mysql.server can be found in the support-files directory under your MySQL installation
directory or in a MySQL source tree.
If you use the Linux server RPM package (MySQL-server-VERSION.rpm), the
mysql.server script will be installed in the /etc/init.d directory with the name mysql.
You need not install it manually. See Section 2.4, “Installing MySQL on Linux” for more information on the Linux RPM packages.
Some vendors provide RPM packages that install a startup script under a different name such as
mysqld.
If you install MySQL from a source distribution or using a binary distribution format that does not
install mysql.server automatically, you can install it manually. Instructions are provided in Sec229
Database Administration
tion 2.9.2.2, “Starting and Stopping MySQL Automatically”.
mysql.server reads options from the [mysql.server] and [mysqld] sections of option
files. (For backward compatibility, it also reads [mysql_server] sections, although you should
rename such sections to [mysql.server] when you begin using MySQL 4.0 or later.)
5.1.5. mysqld_multi — Program for Managing Multiple
MySQL Servers
mysqld_multi is meant for managing several mysqld processes that listen for connections on
different Unix socket files and TCP/IP ports. It can start or stop servers, or report their current
status.
The program searches for groups named [mysqldN] in my.cnf (or in the file named by the -config-file option). N can be any positive integer. This number is referred to in the following
discussion as the option group number, or GNR. Group numbers distinguish option groups from one
another and are used as arguments to mysqld_multi to specify which servers you want to start,
stop, or obtain a status report for. Options listed in these groups are the same that you would use in
the [mysqld] group used for starting mysqld. (See, for example, Section 2.9.2.2, “Starting and
Stopping MySQL Automatically”.) However, when using multiple servers it is necessary that each
one use its own value for options such as the Unix socket file and TCP/IP port number. For more information on which options must be unique per server in a multiple-server environment, see Section 5.11, “Running Multiple MySQL Servers on the Same Machine”.
To invoke mysqld_multi, use the following syntax:
shell> mysqld_multi [options] {start|stop|report} [GNR[,GNR] ...]
start, stop, and report indicate which operation you want to perform. You can perform the
designated operation on a single server or multiple servers, depending on the GNR list that follows
the option name. If there is no list, mysqld_multi performs the operation for all servers in the
option file.
Each GNR value represents an option group number or range of group numbers. The value should be
the number at the end of the group name in the option file. For example, the GNR for a group named
[mysqld17] is 17. To specify a range of numbers, separate the first and last numbers by a dash.
The GNR value 10-13 represents groups [mysqld10] through [mysqld13]. Multiple groups
or group ranges can be specified on the command line, separated by commas. There must be no
whitespace characters (spaces or tabs) in the GNR list; anything after a whitespace character is ignored.
This command starts a single server using option group [mysqld17]:
shell> mysqld_multi start 17
This command stops several servers, using option groups [mysql8] and [mysqld10] through
[mysqld13]:
shell> mysqld_multi stop 8,10-13
For an example of how you might set up an option file, use this command:
shell> mysqld_multi --example
mysqld_multi supports the following options:
•
--config-file=name
Specify the name of an alternative option file. This affects where mysqld_multi looks for
230
Database Administration
[mysqldN] option groups. Without this option, all options are read from the usual my.cnf
file. The option does not affect where mysqld_multi reads its own options, which are always
taken from the [mysqld_multi] group in the usual my.cnf file.
•
--example
Display a sample option file.
•
--help
Display a help message and exit.
•
--log=name
Specify the name of the log file. If the file exists, log output is appended to it.
•
--mysqladmin=prog_name
The mysqladmin binary to be used to stop servers.
•
--mysqld=prog_name
The mysqld binary to be used. Note that you can specify mysqld_safe as the value for this
option also. The options are passed to mysqld. Just make sure that you have the directory
where mysqld is located in your PATH environment variable setting or fix mysqld_safe.
•
--no-log
Print log information to stdout rather than to the log file. By default, output goes to the log file.
•
--password=password
The password of the MySQL account to use when invoking mysqladmin. Note that the password value is not optional for this option, unlike for other MySQL programs.
•
--silent
Disable warnings. This option was added in MySQL 4.1.6.
•
--tcp-ip
Connect to each MySQL server via the TCP/IP port instead of the Unix socket file. (If a socket
file is missing, the server might still be running, but accessible only via the TCP/IP port.) By default, connections are made using the Unix socket file. This option affects stop and report
operations.
•
--user=user_name
The username of the MySQL account to use when invoking mysqladmin.
•
--verbose
Be more verbose. This option was added in MySQL 4.1.6.
•
--version
Display version information and exit.
Some notes about mysqld_multi:
•
Make sure that the MySQL account used for stopping the mysqld servers (with the mysqladmin program) has the same username and password for each server. Also, make sure that the ac231
Database Administration
count has the SHUTDOWN privilege. If the servers that you want to manage have many different
usernames or passwords for the administrative accounts, you might want to create an account on
each server that has the same username and password. For example, you might set up a common
multi_admin account by executing the following commands for each server:
shell> mysql -u root -S /tmp/mysql.sock -proot_password
mysql> GRANT SHUTDOWN ON *.*
-> TO 'multi_admin'@'localhost' IDENTIFIED BY 'multipass';
See Section 5.6.2, “How the Privilege System Works”. You have to do this for each mysqld
server. Change the connection parameters appropriately when connecting to each one. Note that
the host part of the account name must allow you to connect as multi_admin from the host
where you want to run mysqld_multi.
•
The --pid-file option is very important if you are using mysqld_safe to start mysqld
(for example, --mysqld=mysqld_safe) Every mysqld should have its own process ID
file. The advantage of using mysqld_safe instead of mysqld is that mysqld_safe
“guards” its mysqld process and restarts it if the process terminates due to a signal sent using
kill -9 or for other reasons, such as a segmentation fault. Please note that the
mysqld_safe script might require that you start it from a certain place. This means that you
might have to change location to a certain directory before running mysqld_multi. If you
have problems starting, please see the mysqld_safe script. Check especially the lines:
---------------------------------------------------------------MY_PWD=`pwd`
# Check if we are starting this relative (for the binary release)
if test -d $MY_PWD/data/mysql -a -f ./share/mysql/english/errmsg.sys -a \
-x ./bin/mysqld
---------------------------------------------------------------See Section 5.1.3, “mysqld_safe — MySQL Server Startup Script”. The test performed by these
lines should be successful, or you might encounter problems.
•
The Unix socket file and the TCP/IP port number must be different for every mysqld.
•
You might want to use the --user option for mysqld, but in order to do this you need to run
the mysqld_multi script as the Unix root user. Having the option in the option file doesn't
matter; you just get a warning if you are not the superuser and the mysqld processes are started
under your own Unix account.
•
Important: Make sure that the data directory is fully accessible to the Unix account that the specific mysqld process is started as. Do not use the Unix root account for this, unless you know
what you are doing.
•
Most important: Before using mysqld_multi be sure that you understand the meanings of
the options that are passed to the mysqld servers and why you would want to have separate
mysqld processes. Beware of the dangers of using multiple mysqld servers with the same
data directory. Use separate data directories, unless you know what you are doing. Starting multiple servers with the same data directory does not give you extra performance in a threaded system. See Section 5.11, “Running Multiple MySQL Servers on the Same Machine”.
The following example shows how you might set up an option file for use with mysqld_multi.
The first and fifth [mysqldN] group were intentionally left out from the example to illustrate that
you can have “gaps” in the option file. This gives you more flexibility. The order in which the
mysqld programs are started or stopped depends on the order in which they appear in the option
file.
# This file should probably be in your home dir (~/.my.cnf)
# or /etc/my.cnf
# Version 2.1 by Jani Tolonen
[mysqld_multi]
232
Database Administration
mysqld
mysqladmin
user
password
=
=
=
=
/usr/local/bin/mysqld_safe
/usr/local/bin/mysqladmin
multi_admin
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
language
user
=
=
=
=
=
=
/tmp/mysql.sock4
3309
/usr/local/mysql/var4/hostname.pid4
/usr/local/mysql/var4
/usr/local/share/mysql/estonia
tonu
[mysqld6]
socket
port
pid-file
datadir
language
user
=
=
=
=
=
=
/tmp/mysql.sock6
3311
/usr/local/mysql/var6/hostname.pid6
/usr/local/mysql/var6
/usr/local/share/mysql/japanese
jani
See Section 4.3.2, “Using Option Files”.
5.2. mysqlmanager — The MySQL Instance
Manager
The MySQL Instance Manager (IM) is a daemon running on a TCP/IP port, which serves for monitoring and management of MySQL Database Server instances. MySQL Instance Manager is currently available for Unix-like operating systems.
MySQL Instance Manager is included in MySQL distributions from version 5.0.3. MySQL Instance
Manager can be used to start and stop the MySQL Server, even from a remote host, instead of the
mysqld_safe script. MySQL Instance Manager also implements the functionality (and most of the
syntax) of the mysqld_multi script. A more detailed description of the MySQL Instance Manager follows.
5.2.1. Starting the MySQL Server with MySQL Instance
Manager
Normally, the MySQL Database Server is started with the mysql.server script, which usually
resides in the /etc/init.d/ folder. In MySQL 5.0.3 this script invokes mysqlmanager (the
MySQL Instance Manager binary) to start MySQL. In prior versions of MySQL the
mysqld_safe script is used for this purpose. Starting from MySQL 5.0.4 the behavior of the init
script was changed again to incorporate both setup schemes. In 5.0.4 the init startup script uses the
old scheme (invoking mysqld_safe) by default, but one can set the use_mysqld_safe variable in the script to 0 (zero) to use the MySQL Instance Manager to start a server.
233
Database Administration
As of MySQL 5.0.10 the MySQL Instance Manager only reads one configuration and will ignore
options and instances defined in any additional configuration files. For details see Section 5.2.4,
“MySQL Instance Manager Configuration Files”
Instance Manager behavior in this case depends on the options given in the MySQL configuration
file. If there is no configuration file, the MySQL Instance Manager creates an instance named
mysqld and attempts to start it with default (compiled-in) configuration values. This means that the
IM cannot guess the placement of mysqld if it is not installed in the default location. If you have
installed the MySQL server in a non-standard location you should use a configuration file.
If there is a configuration file, the IM will parse the configuration file in search of [mysqld] sections (E.g. [mysqld], [mysqld1], [mysqld2], etc.) Each such section specifies an instance.
At startup the IM will start all found instances. The IM stops all instances at shutdown by default.
Note that there is a special option which is recognized only by the IM called mysqld-path
(mysqld-path = <path-to-mysqld-binary>). Use this variable to let the IM know
where the mysqld binary resides. You should also set basedir and datadir options for the server.
The typical startup/shutdown cycle for a MySQL server with the MySQL Instance Manager enabled
is as follows:
•
The MySQL Instance Manager is started with /etc/init.d/mysql script.
•
The MySQL Instance Manager starts all instances and monitors them.
•
If a server instance fails the MySQL Instance Manager restarts it.
•
If the MySQL Instance Manager is shut down (for instance with the /etc/init.d/mysql
stop command), all instances are shut down by the MySQL Instance Manager.
5.2.2. Connecting to the MySQL Instance Manager and
Creating User Accounts
Communication with the MySQL Instance Manager is handled using the MySQL client-server protocol. As such, you can connect to the IM using the standard mysql client program, as well as the
MySQL C API. The IM supports the new version of the MySQL client-server protocol, so one
should use client tools and libraries distributed along with mysql-4.1 or later.
The IM stores its user information in a password file. Default placement for the password file is /
etc/mysqlmanager.passwd
Password entries look like the following:
petr:*35110DC9B4D8140F5DE667E28C72DD2597B5C848
To generate such an entry one should invoke IM with the --passwd option. Then the output can
be redirected to the /etc/mysqlmanager.passwd file to add a new user. The sample command is given below.
./mysqlmanager --passwd >> /etc/mysqlmanager.passwd
Creating record for new user.
Enter user name: mike
Enter password: <password>
Re-type password: <password>
The following line is added to /etc/mysqlmanager.passwd:
mike:*00A51F3F48415C7D4E8908980D443C29C69B60C9
234
Database Administration
If there are no entries in the /etc/mysqlmanager.passwd file one cannot connect to the IM.
5.2.3. MySQL Instance Manager Command-Line Options
The MySQL Instance Manager supports a number of command line options. A brief listing is available by executing the ./mysqlmanager --help command. The following commands are
available:
•
--help, -?
Display the help message and exit.
•
--bind-address=name
Bind address to use for connections.
•
--default-mysqld-path=name
Where to look for the MySQL Server binary, if no path was provided in the instance section. Example: default-mysqld-path = /usr/sbin/mysqld
•
--defaults-file=file_name
Read Instance Manager and MySQL Server settings from the given file. All configuration
changes by the Instance Manager will be made to this file. This should be used only as the first
option to Instance Manager.
•
--log=name
The path to the IM log file. This is used with the --run-as-service option.
•
--monitoring-interval=seconds
Interval to monitor instances in seconds. Instance manager will try to connect to each of monitored instances to check whether they are alive/not hanging. In the case of a failure IM will perform several (in fact many) attempts to restart the instance. One can disable this behavior for
particular instances with the nonguarded option in the appropriate instance section. If no
value was given, the default of 20 seconds will be used.
•
--passwd, -P
Prepare entry for passwd file and exit.
•
--password-file=name
Look for the Instance Manager users and passwords in this file. The default file is /
etc/mysqlmanager.passwd.
•
--pid-file=name
The process ID file to use. By default, this file is named mysqlmanager.pid.
•
--port=port_num
The port number to use for connections. (The efault port number, assigned by IANA, is 2273).
•
--print-defaults
Print the current defaults and exit. This should be used only as the first option to Instance Man235
Database Administration
ager.
•
--run-as-service
Daemonize and start the angel process. The angel process is simple and unlikely to crash. It will
restart the IM itself in case of a failure.
•
--socket=name
The socket file to use for the connection. By default, the file is named /
tmp/mysqlmanager.sock.
•
--user=name
Username to start and run the mysqlmanager under. It is recommended to run mysqlmanager under the same user account used to run the mysqld server.
•
--version, -V
Output version information and exit.
5.2.4. MySQL Instance Manager Configuration Files
Instance Manager uses the standard my.cnf file. It uses the [manager] section to read options
for itself and the [mysqld] sections to create instances. The [manager] section contains any of
the options listed above. An example [manager] section is shown below:
# MySQL Instance Manager options section
[manager]
default-mysqld-path = /usr/local/mysql/libexec/mysqld
socket=/tmp/manager.sock
pid-file=/tmp/manager.pid
password-file = /home/cps/.mysqlmanager.passwd
monitoring-interval = 2
port = 1999
bind-address = 192.168.1.5
Prior to MySQL 5.0.10, the MySQL Instance Manager read the same configuration files as the
MySQL Server, including /etc/my.cnf, ~/.my.cnf, etc. As of MySQL 5.0.10, the MySQL
Instance Manager only reads and manages the /etc/my.cnf file (but this can be changed with
the --defaults-file=file_name option).
Instance sections specify options given to each instance at startup. These are mainly common
MySQL server options, but there are some IM-specific options:
•
mysqld-path = <path-to-mysqld-binary>
The path to the mysqld server binary.
•
shutdown-delay = seconds
A number of seconds IM should wait for the instance to shut down. Default time is 35 seconds.
After the delay expires, the IM assumes that the instance is hanging and attempts to kill -9 it. If
you use InnoDB with large tables, you should increase this value.
•
nonguarded
This option should be set if you want to disable IM monitoring functionality for a certain instance.
236
Database Administration
Several sample instance sections are given below.
[mysqld]
mysqld-path=/usr/local/mysql/libexec/mysqld
socket=/tmp/mysql.sock
port=3307
server_id=1
skip-stack-trace
core-file
skip-bdb
log-bin
log-error
log=mylog
log-slow-queries
[mysqld2]
nonguarded
port=3308
server_id=2
mysqld-path= /home/cps/mysql/trees/mysql-4.1/sql/mysqld
socket
= /tmp/mysql.sock4
pid-file
= /tmp/hostname.pid4
datadir= /home/cps/mysql_data/data_dir1
language=/home/cps/mysql/trees/mysql-4.1/sql/share/english
log-bin
log=/tmp/fordel.log
5.2.5. Commands Recognized by the MySQL Instance
Manager
Once you've set up a password file for the MySQL Instance Manager and the IM is running, you can
connect to it. You can use the mysql client tool connect through a standard MySQL API. Below
goes the list of commands the MySQL Instance Manager currently accepts, with samples.
•
START INSTANCE <instance_name>
This command will attempt to start an instance:
mysql> start instance mysqld4;
Query OK, 0 rows affected (0,00 sec)
•
STOP INSTANCE <instance_name>
This will attempt to stop an instance:
mysql> stop instance mysqld4;
Query OK, 0 rows affected (0,00 sec)
•
SHOW INSTANCES
Show the names of all loaded instances:
mysql> show instances;
+---------------+---------+
| instance_name | status |
+---------------+---------+
| mysqld3
| offline |
| mysqld4
| online |
| mysqld2
| offline |
+---------------+---------+
3 rows in set (0,04 sec)
237
Database Administration
•
SHOW INSTANCE STATUS <instance_name>
Show the status and the version info of selected instance:
mysql> show instance status mysqld3;
+---------------+--------+---------+
| instance_name | status | version |
+---------------+--------+---------+
| mysqld3
| online | unknown |
+---------------+--------+---------+
1 row in set (0.00 sec)
•
SHOW INSTANCE OPTIONS <instance_name>
Show options used by an instance:
mysql> show instance options mysqld3;
+---------------+---------------------------------------------------+
| option_name
| value
|
+---------------+---------------------------------------------------+
| instance_name | mysqld3
|
| mysqld-path
| /home/cps/mysql/trees/mysql-4.1/sql/mysqld
|
| port
| 3309
|
| socket
| /tmp/mysql.sock3
|
| pid-file
| hostname.pid3
|
| datadir
| /home/cps/mysql_data/data_dir1/
|
| language
| /home/cps/mysql/trees/mysql-4.1/sql/share/english |
+---------------+---------------------------------------------------+
7 rows in set (0.01 sec)
•
SHOW <instance_name> LOG FILES
The command provides a listing of all log files used by the instance. The result set contains the
path to the log file and the log file size. If no log file path is specified in the configuration file
(i.e. log=/var/mysql.log), the IM tries to guess its placement. If the IM is unable to guess
the logfile placement you should specify the log file location explicitly.
mysql> show mysqld log files;
+-------------+------------------------------------+----------+
| Logfile
| Path
| Filesize |
+-------------+------------------------------------+----------+
| ERROR LOG
| /home/cps/var/mysql/owlet.err
| 9186
|
| GENERAL LOG | /home/cps/var/mysql/owlet.log
| 471503
|
| SLOW LOG
| /home/cps/var/mysql/owlet-slow.log | 4463
|
+-------------+------------------------------------+----------+
3 rows in set (0.01 sec)
•
SHOW
<instance_name>
size[,offset_from_end]
LOG
{ERROR
|
SLOW
|
GENERAL}
This command retrieves a portion of the specified log file. Because most users are interested in
the latest log messages, the size parameter defines the number of bytes you would like to retrieve starting from the log end. You can retrieve data from the middle of the log file by specifying the optional offset_from_end parameter. The following example retrieves 21 bytes of
data, starting 23 bytes from the end of the log file and ending 2 bytes from the end of the log
file:
mysql> show mysqld log general 21, 2;
+---------------------+
| Log
|
+---------------------+
| using password: YES |
+---------------------+
1 row in set (0.00 sec)
238
Database Administration
•
SET instance_name.option_name=option_value
This commands edits the specified instance's configuration file to change/add instance options.
The IM assumes that the configuration file is located at /etc/my.cnf (the default configuration file can be overridden with the --defaults-file=file_name option). You should
check that the file exists and has appropriate permissions.
mysql> set mysqld2.port=3322;
Query OK, 0 rows affected (0.00 sec)
Changes made to the configuration file will not take effect until the MySQL server is restarted.
In addition, these changes are not stored in the instance manager's local cache of instance settings until a FLUSH INSTANCES command is executed.
•
UNSET instance_name.option_name
This command removes an option from an instance's configuration file.
mysql> unset mysqld2.port;
Query OK, 0 rows affected (0.00 sec)
Changes made to the configuration file will not take effect until the MySQL server is restarted.
In addition, these changes are not stored in the instance manager's local cache of instance settings until a FLUSH INSTANCES command is executed.
•
FLUSH INSTANCES
This command forces IM to reread the configuration file and to refresh internal structures. This
command should be performed after editing the configuration file. This command does not restart instances:
mysql> flush instances;
Query OK, 0 rows affected (0.04 sec)
5.3. mysqld — The MySQL Server
mysqld is the MySQL server. The following discussion covers these MySQL server configuration
topics:
•
Startup options that the server supports
•
How to set the server SQL mode
•
Server system variables
•
Server status variables
5.3.1. mysqld Command-Line Options
When you start the mysqld server, you can specify program options using any of the methods described in Section 4.3, “Specifying Program Options”. The most common methods are to provide
options in an option file or on the command line. However, in most cases it is desirable to make sure
that the server uses the same options each time it runs. The best way to ensure this is to list them in
an option file. See Section 4.3.2, “Using Option Files”.
239
Database Administration
mysqld reads options from the [mysqld] and [server] groups. mysqld_safe reads options
from the [mysqld], [server], [mysqld_safe], and [safe_mysqld] groups.
mysql.server reads options from the [mysqld] and [mysql.server] groups. An embedded MySQL server usually reads options from the [server], [embedded], and
[xxxxx_SERVER] groups, where xxxxx is the name of the application into which the server is
embedded.
mysqld accepts many command-line options. For a list, execute mysqld --help. Before
MySQL 4.1.1, --help prints the full help message. As of 4.1.1, it prints a brief message; to see the
full list, use mysqld --verbose --help.
The following list shows some of the most common server options. Additional options are described
elsewhere:
•
Options that affect security: See Section 5.5.3, “Startup Options for mysqld Concerning Security”.
•
SSL-related options: See Section 5.7.7.6, “SSL Command-Line Options”.
•
Binary log control options: See Section 5.10.4, “The Binary Log”.
•
Replication-related options: See Section 6.8, “Replication Startup Options”.
•
Options specific to particular storage engines: See Section 14.1.1, “MyISAM Startup Options”,
Section 14.4.3, “BDB Startup Options”, Section 15.5, “InnoDB Startup Options”.
You can also set the value of a server system variable by using the variable name as an option, as
described later in this section.
•
--help, -?
Display a short help message and exit. Before MySQL 4.1.1, --help displays the full help
message. As of 4.1.1, it displays an abbreviated message only. Use both the --verbose and -help options to see the full message.
•
--allow-suspicious-udfs
This option controls whether user-defined functions that have only an xxx symbol for the main
function can be loaded. By default, the option is off and only UDFs that have at least one auxiliary symbol can be loaded. This prevents attempts at loading functions from shared object files
other than those containing legitimate UDFs. This option was added in MySQL 4.0.24, 4.1.10a,
and 5.0.3. See Section 25.2.3.6, “User-defined Function Security Precautions”.
•
--ansi
Use standard SQL syntax instead of MySQL syntax. See Section 1.8.3, “Running MySQL in
ANSI Mode”. For more precise control over the server SQL mode, use the --sql-mode option instead.
•
--basedir=path, -b path
The path to the MySQL installation directory. All paths are usually resolved relative to this.
•
--big-tables
Allow large result sets by saving all temporary sets in files. This option prevents most “table
full” errors, but also slows down queries for which in-memory tables would suffice. Since
MySQL 3.23.2, the server is able to handle large result sets automatically by using memory for
small temporary tables and switching to disk tables where necessary.
•
--bind-address=IP
240
Database Administration
The IP address to bind to.
•
--bootstrap
This option is used by the mysql_install_db script to create the MySQL privilege tables
without having to start a full MySQL server.
•
--console
Write the error log messages to stderr/stdout even if --log-error is specified. On Windows,
mysqld does not close the console screen if this option is used.
•
--character-sets-dir=path
The directory where character sets are installed. See Section 5.9.1, “The Character Set Used for
Data and Sorting”.
•
--chroot=path
Put the mysqld server in a closed environment during startup by using the chroot() system
call. This is a recommended security measure as of MySQL 4.0. (MySQL 3.23 is not able to
provide a chroot() jail that is 100% closed.) Note that use of this option somewhat limits
LOAD DATA INFILE and SELECT ... INTO OUTFILE.
•
--character-set-server=charset
Use charset as the default server character set. This option is available as of MySQL 4.1.3.
See Section 5.9.1, “The Character Set Used for Data and Sorting”.
•
--core-file
Write a core file if mysqld dies. For some systems, you must also specify the -core-file-size option to mysqld_safe. See Section 5.1.3, “mysqld_safe — MySQL
Server Startup Script”. Note that on some systems, such as Solaris, you do not get a core file if
you are also using the --user option.
•
--collation-server=collation
Use collation as the default server collation. This option is available as of MySQL 4.1.3.
See Section 5.9.1, “The Character Set Used for Data and Sorting”.
•
--datadir=path, -h path
The path to the data directory.
•
--debug[=debug_options], -# [debug_options]
If MySQL is configured with --with-debug, you can use this option to get a trace file of
what mysqld is doing. The debug_options string often is 'd:t:o,file_name'. See
Section F.1.2, “Creating Trace Files”.
•
--default-character-set=charset
Use charset as the default character set. This option is deprecated in favor of -character-set-server as of MySQL 4.1.3. See Section 5.9.1, “The Character Set Used
for Data and Sorting”.
•
--default-collation=collation
Use collation as the default collation. This option is deprecated in favor of -collation-server as of MySQL 4.1.3. See Section 5.9.1, “The Character Set Used for
Data and Sorting”.
241
Database Administration
•
--default-storage-engine=type
This option is a synonym for --default-table-type. It is available as of MySQL 4.1.2.
•
--default-table-type=type
Set the default table type for tables. See Chapter 14, MySQL Storage Engines and Table Types.
•
--default-time-zone=type
Set the default server time zone. This option sets the global time_zone system variable. If this
option is not given, the default time zone is the same as the system time zone (given by the value
of the system_time_zone system variable. This option is available as of MySQL 4.1.3.
•
--delay-key-write[= OFF | ON | ALL]
How the DELAYED KEYS option should be used. Delayed key writing causes key buffers not to
be flushed between writes for MyISAM tables. OFF disables delayed key writes. ON enables
delayed key writes for those tables that were created with the DELAYED KEYS option. ALL
delays key writes for all MyISAM tables. Available as of MySQL 4.0.3. See Section 7.5.2,
“Tuning Server Parameters”. See Section 14.1.1, “MyISAM Startup Options”.
Note: If you set this variable to ALL, you should not use MyISAM tables from within another
program (such as from another MySQL server or with myisamchk) when the table is in use.
Doing so leads to index corruption.
•
--delay-key-write-for-all-tables
Old form of --delay-key-write=ALL for use prior to MySQL 4.0.3. As of 4.0.3, use -delay-key-write instead.
•
--des-key-file=file_name
Read the default keys used by DES_ENCRYPT() and DES_DECRYPT() from this file.
•
--enable-named-pipe
Enable support for named pipes. This option applies only on Windows NT, 2000, XP, and 2003
systems, and can be used only with the mysqld-nt and mysqld-max-nt servers that support named pipe connections.
•
--exit-info[=flags], -T [flags]
This is a bit mask of different flags you can use for debugging the mysqld server. Do not use
this option unless you know exactly what it does!
•
--external-locking
Enable system locking. Note that if you use this option on a system on which lockd does not
fully work (as on Linux), it is easy for mysqld to deadlock. This option previously was named
--enable-locking.
Note: If you use this option to enable updates to MyISAM tables from many MySQL processes,
you have to ensure that these conditions are satisfied:
•
You should not use the query cache for queries that use tables that are updated by another
process.
•
You should not use --delay-key-write=ALL or DELAY_KEY_WRITE=1 on any
shared tables.
The easiest way to ensure this is to always use --external-locking together with -delay-key-write=OFF --query-cache-size=0.
242
Database Administration
(This is not done by default because in many setups it's useful to have a mixture of the above options.)
•
--flush
Flush all changes to disk after each SQL statement. Normally MySQL does a write of all
changes to disk only after each SQL statement and lets the operating system handle the synching
to disk. See Section A.4.2, “What to Do If MySQL Keeps Crashing”.
•
--init-file=file
Read SQL statements from this file at startup. Each statement must be on a single line and
should not include comments.
•
--innodb-safe-binlog
Adds consistency guarantees between the content of InnoDB tables and the binary log. See Section 5.10.4, “The Binary Log”. This option was removed in MySQL 5.0.3, having been made
obsolete by the introduction of XA transaction support.
•
--language=lang_name, -L lang_name
Client error messages in given language. lang_name can be given as the language name or as
the full pathname to the directory where the language files are installed. See Section 5.9.2,
“Setting the Error Message Language”.
•
--large-pages
Some hardware/operating system architectures support memory pages greater than the default
(usually 4 KB). The actual implementation of this support depends on the underlying hardware
and OS. Applications that perform a lot of memory access may obtain performance improvements by using large pages due to reduced Translation Lookaside Buffer (TLB) misses.
Currently, MySQL supports only the Linux implementation of large pages support (which is
called HugeTLB in Linux). We have plans to extend this support to FreeBSD, Solaris and possibly other platforms.
Before large pages can be used on Linux, it is necessary to configure the HugeTLB memory
pool. For reference, consult the hugetlbpage.txt file in the Linux kernel source.
This option is disabled by default. It was added in MySQL 5.0.3.
•
--log[=file], -l [file]
Log connections and queries to this file. See Section 5.10.2, “The General Query Log”. If you
don't specify a filename, MySQL uses host_name.log as the filename.
•
--log-bin=[file]
The binary log file. Log all queries that change data to this file. Used for backup and replication.
See Section 5.10.4, “The Binary Log”. It is recommended to specify a filename (see Section A.8.4, “Open Issues in MySQL” for the reason) otherwise MySQL uses host_name-bin
as the log file basename.
•
--log-bin-index[=file]
The index file for binary log filenames. See Section 5.10.4, “The Binary Log”. If you don't specify a filename, and if you didn't specify one in --log-bin, MySQL uses host_namebin.index as the filename.
•
--log-bin-trust-routine-creators[={0|1}]
With
no
argument
or
an
argument
243
of
1,
this
option
sets
the
Database Administration
log_bin_trust_routine_creators system variable to 1. With an argument of 0, this
option sets the system variable to 0. log_bin_trust_routine_creators affects how
MySQL enforces restrictions on stored routine creation. See Section 18.4, “Binary Logging of
Stored Routines and Triggers”.
This option was added in MySQL 5.0.6.
•
--log-error[=file]
Log errors and startup messages to this file. See Section 5.10.1, “The Error Log”. If you don't
specify a filename, MySQL uses host_name.err as the filename. If the filename has no extension, an extension of .err is added to the name.
•
--log-isam[=file]
Log all ISAM/MyISAM changes to this file (used only when debugging ISAM/MyISAM).
•
--log-long-format
Log some extra information to the log files (update log, binary update log, and slow queries log,
whatever log has been activated). For example, username and timestamp are logged for queries.
Before MySQL 4.1, if you are using --log-slow-queries and --log-long-format,
queries that are not using indexes also are logged to the slow query log. -log-long-format is deprecated as of MySQL version 4.1, when -log-short-format was introduced. (Long log format is the default setting since version
4.1.) Also note that starting with MySQL 4.1, the --log-queries-not-using-indexes
option is available for the purpose of logging queries that do not use indexes to the slow query
log.
•
--log-queries-not-using-indexes
If you are using this option with --log-slow-queries, then queries that are not using indexes also are logged to the slow query log. This option is available as of MySQL 4.1. See Section 5.10.5, “The Slow Query Log”.
•
--log-short-format
Log less information to the log files (update log, binary update log, and slow queries log,
whatever log has been activated). For example, username and timestamp are not logged for queries. This option was introduced in MySQL 4.1.
•
--log-slow-admin-statements
Log slow administrative statements such as OPTIMIZE TABLE, ANALYZE TABLE, and ALTER TABLE to the slow query log.
This option was added in MySQL 4.1.13. (It is unnecessary in MySQL 4.0 because slow administrative statements are logged by default.)
•
--log-slow-queries[=file]
Log all queries that have taken more than long_query_time seconds to execute to this file.
See Section 5.10.5, “The Slow Query Log”. Note that the default for the amount of information
logged has changed in MySQL 4.1. See the --log-long-format and -log-short-format options for details.
•
--log-update[=file]
Log updates to fileN where N is a unique number if not given. See Section 5.10.3, “The Update Log”. The update log is deprecated and is removed in MySQL 5.0.0; you should use the
binary log instead (--log-bin). See Section 5.10.4, “The Binary Log”. Starting from version
5.0.0, using --log-update turns on the binary log instead (see Section E.1.14, “Changes in
release 5.0.0 (22 Dec 2003: Alpha)”).
244
Database Administration
•
--log-warnings, -W
Print out warnings such as Aborted connection... to the error log. Enabling this option
is recommended, for example, if you use replication (you get more information about what is
happening, such as messages about network failures and reconnections). This option is enabled
by default as of MySQL 4.0.19 and 4.1.2; to disable it, use --skip-log-warnings. As of
MySQL 4.0.21 and 4.1.3, aborted connections are not logged to the error log unless the value is
greater than 1. See Section A.2.10, “Communication Errors and Aborted Connections”.
This option was named --warnings before MySQL 4.0.
•
--low-priority-updates
Table-modifying operations (INSERT, REPLACE, DELETE, UPDATE) have lower priority than
selects. This can also be done via {INSERT | REPLACE | DELETE | UPDATE}
LOW_PRIORITY ... to lower the priority of only one query, or by SET
LOW_PRIORITY_UPDATES=1 to change the priority in one thread. See Section 7.3.2, “Table
Locking Issues”.
•
--memlock
Lock the mysqld process in memory. This works on systems such as Solaris that support the
mlockall() system call. This might help if you have a problem where the operating system is
causing mysqld to swap on disk. Note that use of this option requires that you run the server as
root, which is normally not a good idea for security reasons.
•
--myisam-recover [=option[,option...]]]
Set the MyISAM storage engine recovery mode. The option value is any combination of the values of DEFAULT, BACKUP, FORCE, or QUICK. If you specify multiple values, separate them by
commas. You can also use a value of "" to disable this option. If this option is used, mysqld,
when it opens a MyISAM table, checks whether the table is marked as crashed or wasn't closed
properly.
(The
last
option
works
only
if
you
are
running
with
--skip-external-locking.) If this is the case, mysqld runs a check on the table. If the
table was corrupted, mysqld attempts to repair it.
The following options affect how the repair works:
Option
Description
DEFAULT
The same as not giving any option to --myisam-recover.
BACKUP
If the data file was changed during recovery, save a backup of the
tbl_name.MYD file as tbl_name-datetime.BAK.
FORCE
Run recovery even if we would lose more than one row from the .MYD file.
QUICK
Don't check the rows in the table if there aren't any delete blocks.
Before a table is automatically repaired, MySQL adds 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 forces a repair of a table even if some rows would be deleted, but
it keeps the old data file as a backup so that you can later examine what happened.
This option is available as of MySQL 3.23.25.
•
--ndb-connectstring=connect_string
When using the NDB storage engine, it is possible to point out the management server that distributes the cluster configuration by setting the connect string option. See Section 16.4.4.2, “The
MySQL Cluster connectstring” for syntax.
•
--ndbcluster
245
Database Administration
If the binary includes support for the NDB Cluster storage engine (from version 4.1.3, the
MySQL-Max binaries are built with NDB Cluster enabled) the default disabling of support
for the NDB Cluster storage engine can be overruled by using this option. Using the NDB
Cluster storage engine is necessary for using MySQL Cluster. See Chapter 16, MySQL
Cluster.
•
--new
The --new option can be used to make the server behave as 4.1 in certain respects, easing a 4.0
to 4.1 upgrade:
•
Hexadecimal strings such as 0xFF are treated as strings by default rather than as numbers.
(Works in 4.0.12 and up.)
•
TIMESTAMP is returned as a string with the format 'YYYY-MM-DD HH:MM:SS'. (Works
in 4.0.13 and up.) See Chapter 11, Column Types.
This option can be used to help you see how your applications behave in MySQL 4.1, without
actually upgrading to 4.1.
•
--old-passwords
Force the server to generate short (pre-4.1) password hashes for new passwords. This is useful
for compatibility when the server must support older client programs. See Section 5.6.9,
“Password Hashing in MySQL 4.1”.
•
--old-protocol, -o
Use the 3.20 protocol for compatibility with some very old clients. See Section 2.10.7,
“Upgrading from Version 3.20 to 3.21”.
•
--one-thread
Only use one thread (for debugging under Linux). This option is available only if the server is
built with debugging enabled. See Section F.1, “Debugging a MySQL Server”.
•
--open-files-limit=count
To change the number of file descriptors available to mysqld. If this is not set or set to 0, then
mysqld uses this value to reserve file descriptors to use with setrlimit(). If this value is 0
then mysqld reserves max_connections*5 or max_connections + table_cache*2 (whichever is larger) number of files. You should try increasing this if mysqld
gives you the error "Too many open files."
•
--pid-file=path
The path to the process ID file used by mysqld_safe.
•
--port=port_num, -P port_num
The port number to use when listening for TCP/IP connections.
•
--safe-mode
Skip some optimization stages.
•
--safe-show-database
With this option, the SHOW DATABASES statement displays only the names of those databases
for which the user has some kind of privilege. As of MySQL 4.0.2, this option is deprecated and
doesn't do anything (it is enabled by default), because there is a SHOW DATABASES privilege
that can be used to control access to database names on a per-account basis. See Section 5.6.3,
“Privileges Provided by MySQL”.
246
Database Administration
•
--safe-user-create
If this is enabled, a user can't create new users with the GRANT statement, if the user doesn't
have the INSERT privilege for the mysql.user table or any column in the table.
•
--secure-auth
Disallow authentication for accounts that have old (pre-4.1) passwords. This option is available
as of MySQL 4.1.1.
•
--shared-memory
Enable shared-memory connections by local clients. This option is available only on Windows.
It was added in MySQL 4.1.0.
•
--shared-memory-base-name=name
The name to use for shared-memory connections. This option is available only on Windows. It
was added in MySQL 4.1.0.
•
--skip-bdb
Disable the BDB storage engine. This saves memory and might speed up some operations. Do
not use this option if you require BDB tables.
•
--skip-concurrent-insert
Turn off the ability to select and insert at the same time on MyISAM tables. (This is to be used
only if you think you have found a bug in this feature.)
•
--skip-delay-key-write
Ignore the DELAY_KEY_WRITE option for all tables. As of MySQL 4.0.3, you should use -delay-key-write=OFF instead. See Section 7.5.2, “Tuning Server Parameters”.
•
--skip-external-locking
Don't use system locking. To use isamchk or myisamchk, you must shut down the server.
See Section 1.4.3, “MySQL Stability”. In MySQL 3.23, you can use CHECK TABLE and REPAIR TABLE to check and repair MyISAM tables. This option previously was named -skip-locking.
•
--skip-grant-tables
This option causes the server not to use the privilege system at all. This gives everyone full access to all databases! (You can tell a running server to start using the grant tables again by executing a mysqladmin flush-privileges or mysqladmin reload command, or by
issuing a FLUSH PRIVILEGES statement.)
•
--skip-host-cache
Do not use the internal hostname cache for faster name-to-IP resolution. Instead, query the DNS
server every time a client connects. See Section 7.5.6, “How MySQL Uses DNS”.
•
--skip-innodb
Disable the InnoDB storage engine. This saves memory and disk space and might speed up
some operations. Do not use this option if you require InnoDB tables.
•
--skip-isam
Disable the ISAM storage engine. As of MySQL 4.1, ISAM is disabled by default, so this option
applies only if the server was configured with support for ISAM. This option was added in
MySQL 4.1.1.
247
Database Administration
•
--skip-name-resolve
Do not resolve hostnames when checking client connections. Use only IP numbers. If you use
this option, all Host column values in the grant tables must be IP numbers or localhost. See
Section 7.5.6, “How MySQL Uses DNS”.
•
--skip-ndbcluster
Disable the NDB Cluster storage engine. This is the default for binaries that were built with
NDB Cluster storage engine support, this means that the system only allocates memory and
other resources for this storage engine if it is explicitly enabled.
•
--skip-networking
Don't listen for TCP/IP connections at all. All interaction with mysqld must be made via
named pipes or shared memory (on Windows) or Unix socket files (on Unix). This option is
highly recommended for systems where only local clients are allowed. See Section 7.5.6, “How
MySQL Uses DNS”.
•
--skip-new
Don't use new, possibly wrong routines.
•
--skip-symlink
This is the old form of --skip-symbolic-links, for use before MySQL 4.0.13.
•
--standalone
Windows-NT based systems only, instructs MySQL server to not run as a service.
•
--symbolic-links, --skip-symbolic-links
Enable or disable symbolic link support. This option has different effects on Windows and Unix:
•
On Windows, enabling symbolic links allows you to establish a symbolic link to a database
directory by creating a directory.sym file that contains the path to the real directory.
See Section 7.6.1.3, “Using Symbolic Links for Databases on Windows”.
•
On Unix, enabling symbolic links means that you can link a MyISAM index file or data file
to another directory with the INDEX DIRECTORY or DATA DIRECTORY options of the
CREATE TABLE statement. If you delete or rename the table, the files that its symbolic
links point to also are deleted or renamed. See Section 13.1.5, “CREATE TABLE Syntax”.
This option was added in MySQL 4.0.13.
•
--skip-safemalloc
If MySQL is configured with --with-debug=full, all MySQL programs check for memory
overruns during each memory allocation and memory freeing operation. This checking is very
slow, so for the server you can avoid it when you don't need it by using the -skip-safemalloc option.
•
--skip-show-database
With this option, the SHOW DATABASES statement is allowed only to users who have the
SHOW DATABASES privilege, and the statement displays all database names. Without this option, SHOW DATABASES is allowed to all users, but displays each database name only if the
user has the SHOW DATABASES privilege or some privilege for the database.
•
--skip-stack-trace
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 F.1, “Debugging a
248
Database Administration
MySQL Server”.
•
--skip-thread-priority
Disable using thread priorities for faster response time.
•
--socket=path
On Unix, this option specifies the Unix socket file to use for local connections. The default
value is /tmp/mysql.sock. On Windows, the option specifies the pipe name to use for local
connections that use a named pipe. The default value is MySQL.
•
--sql-mode=value[,value[,value...]]
Set the SQL mode for MySQL. See Section 5.3.2, “The Server SQL Mode”. This option was added in 3.23.41.
•
--temp-pool
This option causes most temporary files created by the server to use a small set of names, rather
than a unique name for each new file. This works around a problem in the Linux kernel dealing
with creating many new files with different names. With the old behavior, Linux seems to “leak”
memory, because it's being allocated to the directory entry cache rather than to the disk cache.
•
--transaction-isolation=level
Sets the default transaction isolation level, which can be READ-UNCOMMITTED, READCOMMITTED, REPEATABLE-READ, or SERIALIZABLE. See Section 13.4.6, “SET TRANSACTION Syntax”.
•
--tmpdir=path, -t path
The path of the directory to use for creating temporary files. It might be useful if your default /
tmp directory resides on a partition that is too small to hold temporary tables. Starting from
MySQL 4.1, this option accepts several paths that are used in round-robin fashion. Paths should
be separated by colon characters (‘:’) on Unix and semicolon characters (‘;’) on Windows, NetWare, and OS/2. If the MySQL server is acting as a replication slave, you should not set -tmpdir to point to a directory on a memory-based filesystem or to a directory that is cleared
when the server host restarts. A replication slave needs some of its temporary files to survive a
machine restart so that it can replicate temporary tables or LOAD DATA INFILE operations. If
files in the temporary file directory are lost when the server restarts, replication fails.
•
--user={user_name | user_id}, -u {user_name | user_id}
Run the mysqld server as the user having the name user_name or the numeric user ID
user_id. (“User” in this context refers to a system login account, not a MySQL user listed in
the grant tables.)
This option is mandatory when starting mysqld as root. The server changes its user ID during its startup sequence, causing it to run as that particular user rather than as root. See Section 5.5.1, “General Security Guidelines”.
Starting from MySQL 3.23.56 and 4.0.12: To avoid a possible security hole where a user adds a
--user=root option to some my.cnf file (thus causing the server to run as root), mysqld
uses only the first --user option specified and produces a warning if there are multiple -user options. Options in /etc/my.cnf and $MYSQL_HOME/my.cnf are processed before command-line options, so it is recommended that you put a --user option in /
etc/my.cnf and specify a value other than root. The option in /etc/my.cnf is found before any other --user options, which ensures that the server runs as a user other than root,
and that a warning results if any other --user option is found.
•
--version, -V
Display version information and exit.
249
Database Administration
As of MySQL 4.0, you can assign a value to a server system variable by using an option of the form
--var_name=value.
For
example,
--key_buffer_size=32M
sets
the
key_buffer_size variable to a value of 32MB.
Note that when setting a variable to a value, MySQL might automatically correct it to stay within a
given range, or adjust the value to the closest allowable value if only certain values are allowed.
It is also possible to set variables by using --set-variable=var_name=value or -O
var_name=value syntax. However, this syntax is deprecated as of MySQL 4.0.
You can find a full description for all variables in Section 5.3.3, “Server System Variables”. The
section on tuning server parameters includes information on how to optimize them. See Section 7.5.2, “Tuning Server Parameters”.
You can change the values of most system variables for a running server with the SET statement.
See Section 13.5.3, “SET Syntax”.
If you want to restrict the maximum value that a startup option can be set to with SET, you can
define this by using the --maximum-var_name command-line option.
5.3.2. The Server SQL Mode
The MySQL server can operate in different SQL modes, and (as of MySQL 4.1) can apply these
modes differentially for different clients. This allows an application to tailor server operation to its
own requirements.
Modes define what SQL syntax MySQL should support and what kind of data validation checks it
should perform. This makes it easier to use MySQL in different environments and to use MySQL
together with other database servers.
You can set the default SQL mode by starting mysqld with the --sql-mode="modes" option.
The value also can be empty (--sql-mode="") if you want to reset it.
Beginning with MySQL 4.1, you can also change the SQL mode after startup time by setting the
sql_mode variable with a SET [SESSION|GLOBAL] sql_mode='modes' statement. Setting the GLOBAL variable requires the SUPER privilege and affects the operation of all clients that
connect from that time on. Setting the SESSION variable affects only the current client. Any client
can change its session sql_mode value.
modes is a list of different modes separated by comma (‘,’) characters. You can retrieve the current mode by issuing a SELECT @@sql_mode statement. The default value is empty (no modes
set).
The most important sql_mode values are probably these:
•
ANSI
Change syntax and behavior to be more conformant to standard SQL. (New in MySQL 4.1.1)
•
STRICT_TRANS_TABLES
If a value could not be inserted as given into a transactional table, abort the statement. For a nontransactional table, abort the statement if the value occurs in a single-row statement or the first
row of a multiple-row statement. More detail is given later in this section. (New in MySQL
5.0.2)
•
TRADITIONAL
Make MySQL behave like a “traditional” SQL database system. A simple description of this
mode is “give an error instead of a warning” when inserting an incorrect value into a column.
Note: The INSERT/UPDATE aborts as soon as the error is noticed. This may not be what you
want if you are using a non-transactional storage engine, because data changes made prior to the
250
Database Administration
error are not be rolled back, resulting in a “partially done” update. (New in MySQL 5.0.2)
When this manual refers to “strict mode,” it means a mode where at least one of
STRICT_TRANS_TABLES or STRICT_ALL_TABLES is enabled.
The following list describes all the supported modes:
•
ALLOW_INVALID_DATES
Don't do full checking of dates in strict mode. Check only that the month is in the range from 1
to 12 and the day is in the range from 1 to 31. This is very convenient for Web applications
where you obtain year, month, and day in three different fields and you want to store exactly
what the user inserted (without date validation). This mode applies to DATE and DATETIME
columns. It does not apply TIMESTAMP columns, which always require a valid date.
This mode is new in MySQL 5.0.2. Before 5.0.2, this was the default MySQL date-handling
mode. As of 5.0.2, enabling strict mode causes the server to require that month and day values
be legal, not just in the range from 1 to 12 and 1 to 31. For example, '2004-04-31' is legal
with strict mode disabled, but illegal with strict mode enabled. To allow such dates in strict
mode, enable ALLOW_INVALID_DATES as well.
•
ANSI_QUOTES
Treat ‘"’ as an identifier quote character (like the ‘`’ quote character) and not as a string quote
character. You can still use ‘`’ to quote identifiers in ANSI mode. With ANSI_QUOTES enabled, you cannot use double quotes to quote a literal string, because it is interpreted as an identifier. (New in MySQL 4.0.0)
•
ERROR_FOR_DIVISION_BY_ZERO
Produce an error in strict mode (otherwise a warning) when we encounter a division by zero (or
MOD(X,0)) during an INSERT or UPDATE, or in any expression (for example, in a select list
or WHERE clause) that involves table data and a division by zero. If this mode is not given,
MySQL instead returns NULL for divisions by zero. If used in INSERT IGNORE or UPDATE
IGNORE, MySQL generates a warning for divisions by zero, but the result of the operation is
NULL. (New in MySQL 5.0.2)
•
HIGH_NOT_PRECEDENCE
From MySQL 5.0.2 on, the NOT operator precedence is handled so that expressions such as NOT
a BETWEEN b AND c are parsed as NOT (a BETWEEN b AND c). Before MySQL
5.0.2, the expression is parsed as (NOT a) BETWEEN b AND c. The old higher-precedence
behavior can be obtained by enabling the HIGH_NOT_PRECEDENCE SQL mode. (New in
MySQL 5.0.2)
mysql> SET sql_mode
mysql> SELECT NOT 1
-> 0
mysql> SET sql_mode
mysql> SELECT NOT 1
-> 1
•
= '';
BETWEEN -5 AND 5;
= 'broken_not';
BETWEEN -5 AND 5;
IGNORE_SPACE
Allow spaces between a function name and the ‘(’ character. This forces all function names to
be treated as reserved words. As a result, if you want to access any database, table, or column
name that is a reserved word, you must quote it. For example, because there is a USER() function, the name of 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";
251
Database Administration
(New in MySQL 4.0.0)
•
NO_AUTO_CREATE_USER
Prevent GRANT from automatically creating new users if it would otherwise do so, unless a
password also is specified. (New in MySQL 5.0.2)
•
NO_AUTO_VALUE_ON_ZERO
NO_AUTO_VALUE_ON_ZERO affects handling of AUTO_INCREMENT columns. Normally,
you generate the next sequence number for the column by inserting either NULL or 0 into it.
NO_AUTO_VALUE_ON_ZERO suppresses this behavior for 0 so that only NULL generates the
next sequence number. (New in MySQL 4.1.1)
This mode can be useful if 0 has been stored in a table's AUTO_INCREMENT column. (This is
not a recommended practice, by the way.) For example, if you dump the table with mysqldump
and then reload it, MySQL normally generates new sequence numbers when it encounters the 0
values, resulting in a table with different contents than the one that was dumped. Enabling
NO_AUTO_VALUE_ON_ZERO before reloading the dump file solves this problem. As of
MySQL 4.1.1, mysqldump automatically includes a statement in the dump output to enable
NO_AUTO_VALUE_ON_ZERO.
•
NO_BACKSLASH_ESCAPES
Disable the use of the backslash character (‘\’) as an escape character within strings. With this
mode enabled, backslash becomes any ordinary character like any other. (New in MySQL 5.0.1)
•
NO_DIR_IN_CREATE
When creating a table, ignore all INDEX DIRECTORY and DATA DIRECTORY directives.
This option is useful on slave replication servers. (New in MySQL 4.0.15)
•
NO_ENGINE_SUBSTITUTION
Prevents automatic substitution of storage engine when the requested storage engine is disabled
or not compiled in.
•
NO_FIELD_OPTIONS
Don't print MySQL-specific column options in the output of SHOW CREATE TABLE. This
mode is used by mysqldump in portability mode. (New in MySQL 4.1.1)
•
NO_KEY_OPTIONS
Don't print MySQL-specific index options in the output of SHOW CREATE TABLE. This mode
is used by mysqldump in portability mode. (New in MySQL 4.1.1)
•
NO_TABLE_OPTIONS
Don't print MySQL-specific table options (such as ENGINE) in the output of SHOW CREATE
TABLE. This mode is used by mysqldump in portability mode. (New in MySQL 4.1.1)
•
NO_UNSIGNED_SUBTRACTION
In subtraction operations, don't mark the result as UNSIGNED if one of the operands is unsigned.
Note that this makes UNSIGNED BIGINT not 100% usable in all contexts. See Section 12.8,
“Cast Functions and Operators”. (New in MySQL 4.0.2)
•
NO_ZERO_DATE
In strict mode, don't allow '0000-00-00' as a valid date. You can still insert zero dates with
252
Database Administration
the IGNORE option. When not in strict mode, the date is accepted but a warning is generated.
(New in MySQL 5.0.2)
•
NO_ZERO_IN_DATE
In strict mode, don't accept dates where the month or day part is 0. If used with the IGNORE option, we insert a '0000-00-00' date for any such date. When not in strict mode, the date is
accepted but a warning is generated. (New in MySQL 5.0.2)
•
ONLY_FULL_GROUP_BY
Don't allow queries that in the GROUP BY part refer to a not selected column. (New in MySQL
4.0.0)
•
PIPES_AS_CONCAT
Treat || as a string concatenation operator (same as CONCAT()) rather than as a synonym for
OR. (New in MySQL 4.0.0)
•
REAL_AS_FLOAT
Treat REAL as a synonym for FLOAT rather than as a synonym for DOUBLE. (New in MySQL
4.0.0)
•
STRICT_ALL_TABLES
Enable strict mode for all storage engines. Invalid data values are rejected. Additional detail follows. (New in MySQL 5.0.2)
•
STRICT_TRANS_TABLES
Enable strict mode for transactional storage engines, and when possible for non-transactional
storage engines. Additional detail follows. (New in MySQL 5.0.2)
Strict mode controls how MySQL handles input values that are invalid or missing. A value can be
invalid for several reasons. For example, it might have the wrong data type for the column, or it
might be out of range. A value is missing when a new row to be inserted does not contain a value for
a column that has no explicit DEFAULT clause in its definition.
For transactional tables, an error occurs for invalid or missing values in a statement when either of
the STRICT_ALL_TABLES or STRICT_TRANS_TABLES modes are enabled. The statement is
aborted and rolled back.
For non-transactional tables, the behavior is the same for either mode, if the bad value occurs in the
first row to be inserted or updated. The statement is aborted and the table remains unchanged. If the
statement inserts or modifies multiple rows and the bad value occurs in the second or later row, the
result depends on which strict option is enabled:
•
For STRICT_ALL_TABLES, MySQL returns an error and ignores the rest of the rows.
However, in this case, the earlier rows still have been inserted or updated. This means that you
might get a partial update, which might not be what you want. To avoid this, it's best to use
single-row statements because these can be aborted without changing the table.
•
For STRICT_TRANS_TABLES, MySQL converts an invalid value to the closest valid value for
the column and insert the adjusted value. If a value is missing, MySQL inserts the implicit default value for the column data type. In either case, MySQL generates a warning rather than an
error and continues processing the statement. Implicit defaults are described in Section 13.1.5,
“CREATE TABLE Syntax”.
Strict mode disallows invalid date values such as '2004-04-31'. It does not disallow dates with
zero parts such as 2004-04-00' or “zero” dates. To disallow these as well, enable the
253
Database Administration
NO_ZERO_IN_DATE and NO_ZERO_DATE SQL modes in addition to strict mode.
If you are not using strict mode (that is, neither STRICT_TRANS_TABLES nor
STRICT_ALL_TABLES is enabled), MySQL inserts adjusted values for invalid or missing values
and produces warnings. In strict mode, you can produce this behavior by using INSERT IGNORE
or UPDATE IGNORE. See Section 13.5.4.22, “SHOW WARNINGS Syntax”.
The following special modes are provided as shorthand for combinations of mode values from the
preceding list. All are available as of MySQL 4.1.1, except TRADITIONAL (5.0.2).
The descriptions include all mode values that are available in the most recent version of MySQL.
For older versions, a combination mode does not include individual mode values that are not available except in newer versions.
•
ANSI
Equivalent to REAL_AS_FLOAT, PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE.
Before MySQL 4.1.11 and 5.0.3, ANSI also includes ONLY_FULL_GROUP_BY. See Section 1.8.3, “Running MySQL in ANSI Mode”.
•
DB2
Equivalent to PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS,
NO_TABLE_OPTIONS, NO_FIELD_OPTIONS.
•
MAXDB
Equivalent to PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS,
NO_TABLE_OPTIONS, NO_FIELD_OPTIONS, NO_AUTO_CREATE_USER.
•
MSSQL
Equivalent to PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS,
NO_TABLE_OPTIONS, NO_FIELD_OPTIONS.
•
MYSQL323
Equivalent to NO_FIELD_OPTIONS, HIGH_NOT_PRECEDENCE.
•
MYSQL40
Equivalent to NO_FIELD_OPTIONS, HIGH_NOT_PRECEDENCE.
•
ORACLE
Equivalent to PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS,
NO_TABLE_OPTIONS, NO_FIELD_OPTIONS, NO_AUTO_CREATE_USER.
•
POSTGRESQL
Equivalent to PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS,
NO_TABLE_OPTIONS, NO_FIELD_OPTIONS.
•
TRADITIONAL
Equivalent to STRICT_TRANS_TABLES, STRICT_ALL_TABLES, NO_ZERO_IN_DATE,
NO_ZERO_DATE, ERROR_FOR_DIVISION_BY_ZERO, NO_AUTO_CREATE_USER.
5.3.3. Server System Variables
The server maintains many system variables that indicate how it is configured. All of them have default values. They can be set at server startup using options on the command line or in option files.
254
Database Administration
Most of them can be set at runtime using the SET statement.
Beginning with MySQL 4.0.3, the mysqld server maintains two kinds of variables. Global variables affect the overall operation of the server. Session variables affect its operation for individual
client connections.
When the server starts, it initializes all global variables to their default values. These defaults can be
changed by options specified in option files or on the command line. After the server starts, those
global variables that are dynamic can be changed by connecting to the server and issuing a SET
GLOBAL var_name statement. To change a global variable, you must have the SUPER privilege.
The server also maintains a set of session variables for each client that connects. The client's session
variables are initialized at connect time using the current values of the corresponding global variables. For those session variables that are dynamic, the client can change them by issuing a SET
SESSION var_name statement. Setting a session variable requires no special privilege, but a client can change only its own session variables, not those of any other client.
A change to a global variable is visible to any client that accesses that global variable. However, it
affects the corresponding session variable that is initialized from the global variable only for clients
that connect after the change. It does not affect the session variable for any client that is currently
connected (not even that of the client that issues the SET GLOBAL statement).
When setting a variable using a startup option, variable values can be given with a suffix of K, M, or
G to indicate kilobytes, megabytes, or gigabytes, respectively. For example, the following command
starts the server with a key buffer size of 16 megabytes:
mysqld --key_buffer_size=16M
Before MySQL 4.0, use this syntax instead:
mysqld --set-variable=key_buffer_size=16M
The lettercase of suffix letters does not matter; 16M and 16m are equivalent.
At runtime, use the SET statement to set system variables. In this context, suffix letters cannot be
used, but the value can take the form of an expression:
mysql> SET sort_buffer_size = 10 * 1024 * 1024;
To specify explicitly whether to set the global or session variable, use the GLOBAL or SESSION options:
mysql> SET GLOBAL sort_buffer_size = 10 * 1024 * 1024;
mysql> SET SESSION sort_buffer_size = 10 * 1024 * 1024;
Without either option, the statement sets the session variable.
The variables that can be set at runtime are listed in Section 5.3.3.1, “Dynamic System Variables”.
If you want to restrict the maximum value to which a system variable can be set with the SET statement, you can specify this maximum by using an option of the form --maximum-var_name at
server startup. For example, to prevent the value of query_cache_size from being increased to
more than 32MB at runtime, use the option --maximum-query_cache_size=32M. This feature is available as of MySQL 4.0.2.
You can view system variables and their values by using the SHOW VARIABLES statement. See
Section 9.4, “System Variables” for more information.
mysql> SHOW VARIABLES;
+---------------------------------+--------------------------------------------| Variable_name
| Value
255
Database Administration
+---------------------------------+--------------------------------------------| auto_increment_increment
| 1
| auto_increment_offset
| 1
| back_log
| 50
| basedir
| /usr/local/mysql
| bdb_cache_size
| 8388600
| bdb_home
| /usr/local/mysql
| bdb_log_buffer_size
| 131072
| bdb_logdir
|
| bdb_max_lock
| 10000
| bdb_shared_data
| OFF
| bdb_tmpdir
| /tmp/
| binlog_cache_size
| 32768
| bulk_insert_buffer_size
| 8388608
| character_set_client
| latin1
| character_set_connection
| latin1
| character_set_database
| latin1
| character_set_results
| latin1
| character_set_server
| latin1
| character_set_system
| utf8
| character_sets_dir
| /usr/local/mysql/share/charsets/
| collation_connection
| latin1_swedish_ci
| collation_database
| latin1_swedish_ci
| collation_server
| latin1_swedish_ci
| completion_type
| 0
| concurrent_insert
| 1
| connect_timeout
| 5
| datadir
| /usr/local/mysql/data/
| date_format
| %Y-%m-%d
| datetime_format
| %Y-%m-%d %H:%i:%s
| default_week_format
| 0
| delay_key_write
| ON
| delayed_insert_limit
| 100
| delayed_insert_timeout
| 300
| delayed_queue_size
| 1000
| div_precision_increment
| 4
| engine_condition_pushdown
| OFF
| expire_logs_days
| 0
| flush
| OFF
| flush_time
| 1800
| ft_boolean_syntax
| + -><()~*:""&|
| ft_max_word_len
| 84
| ft_min_word_len
| 4
| ft_query_expansion_limit
| 20
| ft_stopword_file
| (built-in)
| group_concat_max_len
| 1024
| have_archive
| NO
| have_bdb
| YES
| have_compress
| YES
| have_crypt
| NO
| have_csv
| NO
| have_example_engine
| NO
| have_geometry
| YES
| have_innodb
| YES
| have_isam
| NO
| have_ndbcluster
| NO
| have_openssl
| YES
| have_query_cache
| YES
| have_raid
| NO
| have_rtree_keys
| YES
| have_symlink
| YES
| init_connect
|
| init_file
|
| init_slave
|
| innodb_additional_mem_pool_size | 2097152
| innodb_autoextend_increment
| 8
| innodb_buffer_pool_awe_mem_mb
| 0
| innodb_buffer_pool_size
| 8388608
| innodb_data_file_path
| ibdata1:10M:autoextend
| innodb_data_home_dir
|
256
Database Administration
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
innodb_fast_shutdown
innodb_file_io_threads
innodb_file_per_table
innodb_locks_unsafe_for_binlog
innodb_flush_log_at_trx_commit
innodb_flush_method
innodb_force_recovery
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_max_dirty_pages_pct
innodb_max_purge_lag
innodb_mirrored_log_groups
innodb_open_files
innodb_support_xa
innodb_table_locks
innodb_thread_concurrency
interactive_timeout
join_buffer_size
key_buffer_size
key_cache_age_threshold
key_cache_block_size
key_cache_division_limit
language
large_files_support
license
local_infile
log
log_bin
log_error
log_slave_updates
log_slow_queries
log_update
log_warnings
long_query_time
low_priority_updates
lower_case_file_system
lower_case_table_names
max_allowed_packet
max_binlog_cache_size
max_binlog_size
max_connect_errors
max_connections
max_delayed_threads
max_error_count
max_heap_table_size
max_insert_delayed_threads
max_join_size
max_length_for_sort_data
max_relay_log_size
max_seeks_for_key
max_sort_length
max_tmp_tables
max_user_connections
max_write_lock_count
myisam_data_pointer_size
myisam_max_sort_file_size
myisam_recover_options
myisam_repair_threads
myisam_sort_buffer_size
named_pipe
net_buffer_length
net_read_timeout
net_retry_count
net_write_timeout
new
257
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1
4
OFF
OFF
1
0
50
OFF
1048576
10485760
2
./
90
0
1
300
ON
ON
8
28800
131072
4194304
300
1024
100
/usr/local/mysql/share/english/
ON
GPL
ON
OFF
OFF
./gigan.err
OFF
OFF
OFF
1
10
OFF
OFF
1
1048576
4294967295
1073741824
10
100
20
64
16777216
20
4294967295
1024
0
4294967295
1024
32
0
4294967295
6
107374182400
OFF
1
8388608
OFF
16384
30
10
60
OFF
Database Administration
| old_passwords
| OFF
| open_files_limit
| 622
| optimizer_prune_level
| 1
| optimizer_search_depth
| 62
| pid_file
| /usr/local/mysql/gigan.pid
| port
| 3306
| preload_buffer_size
| 32768
| protocol_version
| 10
| query_alloc_block_size
| 8192
| query_cache_limit
| 1048576
| query_cache_min_res_unit
| 4096
| query_cache_size
| 0
| query_cache_type
| ON
| query_cache_wlock_invalidate
| OFF
| query_prealloc_size
| 8192
| range_alloc_block_size
| 2048
| read_buffer_size
| 61440
| read_only
| OFF
| read_rnd_buffer_size
| 258048
| relay_log_purge
| ON
| rpl_recovery_rank
| 0
| secure_auth
| OFF
| shared_memory
| OFF
| shared_memory_base_name
| MYSQL
| server_id
| 0
| skip_external_locking
| ON
| skip_networking
| OFF
| skip_show_database
| OFF
| slave_net_timeout
| 3600
| slow_launch_time
| 2
| socket
| /tmp/mysql.sock
| sort_buffer_size
| 217080
| sql_mode
|
| storage_engine
| MyISAM
| sync_binlog
| 0
| sync_frm
| ON
| system_time_zone
| E. Australia Standard Time
| table_cache
| 256
| table_type
| MyISAM
| thread_cache_size
| 0
| thread_stack
| 196608
| time_format
| %H:%i:%s
| time_zone
| SYSTEM
| tmp_table_size
| 5242880
| tmpdir
| /tmp/
| transaction_alloc_block_size
| 8192
| transaction_prealloc_size
| 4096
| tx_isolation
| REPEATABLE-READ
| updatable_views_with_limit
| YES
| version
| 5.0.2-alpha-max
| version_bdb
| Sleepycat Software: Berkeley DB 4.1.24: (Dec
| version_comment
| Source distribution
| wait_timeout
| 28800
+---------------------------------+--------------------------------------------Most system variables are described here. Variables with no version indicated have been present
since at least MySQL 3.22. InnoDB system variables are listed at Section 15.5, “InnoDB Startup
Options”.
Values for buffer sizes, lengths, and stack sizes are given in bytes unless otherwise specified.
Information on tuning these variables can be found in Section 7.5.2, “Tuning Server Parameters”.
•
auto_increment_increment
auto_increment_increment and auto_increment_offset are intended for use
with master-to-master replication, and can be used to control the operation of
258
Database Administration
AUTO_INCREMENT columns. Both variables can be set globally or locally, and each can assume an integer value between 1 and 65,535 inclusive. Setting the value of either of these two
variables to 0 will cause its value to be set to 1 instead. Attempting to set the value of either of
these two variables to an integer greater than 65,535 or less than 0 will cause its value to be set
to 65,535 instead. Attempting to set the value of auto_increment_increment or of
auto_increment_offset to a non-integer value gives rise to an error, and the actual value
of the variable remains unchanged in such a case.
These two variables effect AUTO_INCREMENT column behavior as follows:
•
auto_increment_increment controls the interval by which the column value is incremented. For example:
mysql> SHOW VARIABLES LIKE 'auto_inc%';
+--------------------------+-------+
| Variable_name
| Value |
+--------------------------+-------+
| auto_increment_increment | 1
|
| auto_increment_offset
| 1
|
+--------------------------+-------+
2 rows in set (0.00 sec)
mysql> CREATE TABLE autoinc1 (col INT NOT NULL AUTO_INCREMENT PRIMARY KEY
Query OK, 0 rows affected (0.04 sec)
mysql> SET @auto_increment_increment=10;
Query OK, 0 rows affected (0.00 sec)
mysql> SHOW VARIABLES LIKE 'auto_inc%';
+--------------------------+-------+
| Variable_name
| Value |
+--------------------------+-------+
| auto_increment_increment | 10
|
| auto_increment_offset
| 1
|
+--------------------------+-------+
2 rows in set (0.01 sec)
mysql> INSERT INTO autoinc1 VALUES (NULL), (NULL), (NULL), (NULL);
Query OK, 4 rows affected (0.00 sec)
Records: 4 Duplicates: 0 Warnings: 0
mysql> SELECT col FROM autoinc1;
+-----+
| col |
+-----+
|
1 |
| 11 |
| 21 |
| 31 |
+-----+
4 rows in set (0.00 sec)
(Note how SHOW VARIABLES is used here to obtain the current values for these variables.)
•
auto_increment_offset determines the starting point for the AUTO_INCREMENT
column value. Consider the following, assuming that these commands are executed during
the same session as the previous example:
mysql> SET @auto_increment_offset=5;
Query OK, 0 rows affected (0.00 sec)
mysql> SHOW VARIABLES LIKE 'auto_inc%';
+--------------------------+-------+
| Variable_name
| Value |
+--------------------------+-------+
| auto_increment_increment | 10
|
259
Database Administration
| auto_increment_offset
| 5
|
+--------------------------+-------+
2 rows in set (0.00 sec)
mysql> CREATE TABLE autoinc2 (col INT NOT NULL AUTO_INCREMENT PRIMARY KEY
Query OK, 0 rows affected (0.06 sec)
mysql> INSERT INTO autoinc2 VALUES (NULL), (NULL), (NULL), (NULL);
Query OK, 4 rows affected (0.00 sec)
Records: 4 Duplicates: 0 Warnings: 0
mysql> SELECT col FROM autoinc2;
+-----+
| col |
+-----+
|
5 |
| 15 |
| 25 |
| 35 |
+-----+
4 rows in set (0.02 sec)
If the value of auto_increment_offset is greater than that of
auto_increment_increment, then the value of auto_increment_offset is ignored.
Should one or both of these variables be changed and then new rows inserted into a table containing an AUTO_INCREMENT column, the results may seem counterintuitive, as the series of
AUTO_INCREMENT values is calculated without regard to any values already present in the
column, and the next value inserted is the least value in the series that is greater than the maximum existing value in the AUTO_INCREMENT column. In other words, the series is calculated
like so:
auto_increment_offset + N * auto_increment_increment
where N is a positive integer value in the series [1, 2, 3, ...]. For example:
mysql> SHOW VARIABLES LIKE 'auto_inc%';
+--------------------------+-------+
| Variable_name
| Value |
+--------------------------+-------+
| auto_increment_increment | 10
|
| auto_increment_offset
| 5
|
+--------------------------+-------+
2 rows in set (0.00 sec)
mysql> SELECT col FROM autoinc1;
+-----+
| col |
+-----+
|
1 |
| 11 |
| 21 |
| 31 |
+-----+
4 rows in set (0.00 sec)
mysql> INSERT INTO autoinc1 VALUES (NULL), (NULL), (NULL), (NULL);
Query OK, 4 rows affected (0.00 sec)
Records: 4 Duplicates: 0 Warnings: 0
mysql> SELECT col FROM autoinc1;
+-----+
| col |
260
Database Administration
+-----+
|
1 |
| 11 |
| 21 |
| 31 |
| 35 |
| 45 |
| 55 |
| 65 |
+-----+
8 rows in set (0.00 sec)
The values shown for auto_increment_increment and auto_increment_offset
generate the series 5 + N * 10, that is, [5, 15, 25, 35, 45, ...]. The greatest value present in the
col column prior to the INSERT is 31, and the next available value in the AUTO_INCREMENT
series is 35, so the inserted values for col begin at that point and the results are as shown for the
SELECT query.
It is important to remember that it is not possible to confine the effects of these two variables to
a single table, and thus they do not take the place of the sequences offered by some other database management systems; these variables control the behavior of all AUTO_INCREMENT
columns in all tables on the MySQL server. If one of these variables is set globally, then its effects persist until the global value is changed or overridden by setting them locally, or until
mysqld is restarted; if set locally, then the new value affects AUTO_INCREMENT columns for
all tables into which new rows are inserted by the current user for the duration of the session, unless the values are changed during that session.
The auto_increment_increment variable was added in MySQL 5.0.2. Its default value is
1. See Chapter 6, Replication in MySQL.
•
auto_increment_offset
This variable was introduced in MySQL 5.0.2. Its default value is 1. For particulars, see the description for auto_increment_increment.
•
ansi_mode
This is ON if mysqld was started with --ansi. See Section 1.8.3, “Running MySQL in ANSI
Mode”. This variable was added in MySQL 3.23.6 and removed in 3.23.41. See the description
for sql_mode.
•
back_log
The number of outstanding connection requests MySQL can have. This comes into play when
the main MySQL thread gets very many connection requests in a very short time. It then takes
some time (although very little) for the main thread to check the connection and start a new
thread. The back_log value indicates how many requests can be stacked during this short time
before MySQL momentarily stops answering new requests. You need to increase this only if you
expect a large number of connections in a short period of time.
In other words, this value is the size of the listen queue for incoming TCP/IP connections. Your
operating system has its own limit on the size of this queue. The manual page for the Unix
listen() system call should have more details. Check your OS documentation for the maximum value for this variable. Attempting to set back_log higher than your operating system
limit is ineffective.
•
basedir
The MySQL installation base directory. This variable can be set with the --basedir option.
•
bdb_cache_size
The size of the buffer that is allocated for caching indexes and rows for BDB tables. If you don't
261
Database Administration
use BDB tables, you should start mysqld with --skip-bdb to not waste memory for this
cache. This variable was added in MySQL 3.23.14.
•
bdb_home
The base directory for BDB tables. This should be assigned the same value as the datadir
variable. This variable was added in MySQL 3.23.14.
•
bdb_log_buffer_size
The size of the buffer that is allocated for caching indexes 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. This variable was added in MySQL 3.23.31.
•
bdb_logdir
The directory where the BDB storage engine writes its log files. This variable can be set with the
--bdb-logdir option. This variable was added in MySQL 3.23.14.
•
bdb_max_lock
The maximum number of locks you can have active on a BDB table (10,000 by default). You
should increase this if errors such as the following occur when you perform long transactions or
when mysqld has to examine many rows to calculate a query:
bdb: Lock table is out of available locks
Got error 12 from ...
This variable was added in MySQL 3.23.29.
•
bdb_shared_data
This is ON if you are using --bdb-shared-data. This variable was added in MySQL
3.23.29.
•
bdb_tmpdir
The value of the --bdb-tmpdir option. This variable was added in MySQL 3.23.14.
•
bdb_version
See the description for version_bdb.
•
binlog_cache_size
The size of the cache to hold the SQL statements for the binary log during a transaction. A binary log cache is allocated for each client if the server supports any transactional storage engines
and, starting from MySQL 4.1.2, if the server has binary log enabled (--log-bin option). If
you often use big, multiple-statement transactions, you can increase this to get more performance. The Binlog_cache_use and Binlog_cache_disk_use status variables can be
useful for tuning the size of this variable. This variable was added in MySQL 3.23.29. See Section 5.10.4, “The Binary Log”.
•
bulk_insert_buffer_size
MyISAM uses a special tree-like cache to make bulk inserts faster for INSERT ... SELECT,
INSERT ... VALUES (...), (...), ..., and LOAD DATA INFILE. This variable
limits the size of the cache tree in bytes per thread. Setting it to 0 disables this optimization.
Note: This cache is used only when adding data to a non-empty table. The default value is 8MB.
This variable was added in MySQL 4.0.3. This variable previously was named myisam_bulk_insert_tree_size.
•
character_set
262
Database Administration
The default character set. This variable was added in MySQL 3.23.3, then removed in MySQL
4.1.1 and replaced by the various character_set_xxx variables.
•
character_set_client
The character set for statements that arrive from the client. This variable was added in MySQL
4.1.1.
•
character_set_connection
The character set used for literals that do not have a character set introducer and for numberto-string conversion. This variable was added in MySQL 4.1.1.
•
character_set_database
The character set used by the default database. The server sets this variable whenever the default
database changes. If there is no default database, the variable has the same value as character_set_server. This variable was added in MySQL 4.1.1.
•
character_set_results
The character set used for returning query results to the client. This variable was added in
MySQL 4.1.1.
•
character_set_server
The server default character set. This variable was added in MySQL 4.1.1.
•
character_set_system
The character set used by the server for storing identifiers. The value is always utf8. This variable was added in MySQL 4.1.1.
•
character_sets
The supported character sets. This variable was added in MySQL 3.23.15 and removed in
MySQL 4.1.1. (Use SHOW CHARACTER SET for a list of character sets.)
•
character_sets_dir
The directory where character sets are installed. This variable was added in MySQL 4.1.2.
•
collation_connection
The collation of the connection character set. This variable was added in MySQL 4.1.1.
•
collation_database
The collation used by the default database. The server sets this variable whenever the default
database changes. If there is no default database, the variable has the same value as collation_server. This variable was added in MySQL 4.1.1.
•
collation_server
The server default collation. This variable was added in MySQL 4.1.1.
•
completion_type
The transaction completion type:
•
If the value is 0 (the default), COMMIT and ROLLBACK are unaffected.
•
If the value is 1, COMMIT and ROLLBACK are equivalent to COMMIT AND CHAIN and
263
Database Administration
ROLLBACK AND CHAIN, respectively. (A new transaction starts immediately with the
same isolation level as the just-terminated transaction.)
•
If the value is 2, COMMIT and ROLLBACK are equivalent to COMMIT RELEASE and
ROLLBACK RELEASE, respectively. (The server disconnects after terminating the transaction.)
This variable was added in MySQL 5.0.3
•
concurrent_insert
If ON (the default), MySQL allows INSERT and SELECT statements to run concurrently for
MyISAM tables that have no free blocks in the middle. You can turn this option off by starting
mysqld with --safe or --skip-new. This variable was added in MySQL 3.23.7.
In MySQL 5.0.6 this variable was changed to an integer that takes 3 values:
•
Value
Description
0
Off
1
(Default) Enables concurrent insert for MyISAM tables that doesn't have holes
2
Enables concurrent inserts for all MyISAM tables. If table has a hole and is in use
by another thread the new row will be inserted at end of table. If table is not in use
then MySQL will do a normal read lock and insert the new row into the hole.
connect_timeout
The number of seconds the mysqld server waits for a connect packet before responding with
Bad handshake.
•
convert_character_set
The current character set mapping that was set by SET CHARACTER SET. This variable was
removed in MySQL 4.1.
•
datadir
The MySQL data directory. This variable can be set with the --datadir option.
•
date_format
This variable is not implemented.
•
datetime_format
This variable is not implemented.
•
default_week_format
The default mode value to use for the WEEK() function. This variable is available as of MySQL
4.0.14.
•
delay_key_write
This option applies only to MyISAM tables. It can have one of the following values to affect
handling of the DELAY_KEY_WRITE table option that can be used in CREATE TABLE statements.
Option
Description
OFF
DELAY_KEY_WRITE is ignored.
264
Database Administration
ON
MySQL honors the DELAY_KEY_WRITE option for CREATE TABLE. This is the
default value.
ALL
All new opened tables are treated as if they were created with the
DELAY_KEY_WRITE option enabled.
If DELAY_KEY_WRITE is enabled, this means that the key buffer for tables with this option are
not flushed on every index update, but only when a table is closed. This speeds up writes on
keys a lot, but if you use this feature, you should add automatic checking of all MyISAM tables
by starting the server with the --myisam-recover option (for example, -myisam-recover=BACKUP,FORCE). See Section 5.3.1, “mysqld Command-Line Options” and Section 14.1.1, “MyISAM Startup Options”.
Note that --external-locking doesn't offer any protection against index corruption for
tables that use delayed key writes.
This variable was added in MySQL 3.23.8.
•
delayed_insert_limit
After inserting delayed_insert_limit delayed rows, the INSERT DELAYED handler
thread checks whether there are any SELECT statements pending. If so, it allows them to execute before continuing to insert delayed rows.
•
delayed_insert_timeout
How long an INSERT DELAYED handler thread should wait for INSERT statements before
terminating.
•
delayed_queue_size
This is a per-table limit on the number of rows to queue when handling INSERT DELAYED
statements. If the queue becomes full, any client that issues an INSERT DELAYED statement
waits until there is room in the queue again.
•
div_precision_increment
This variable indicates the number of digits of precision by which to increase the result of division operations performed with the / operator. The default value is 4. The minimum and maximum values are 0 and 30, respectively. The following example illustrates the effect of increasing the default value.
mysql> SELECT 1/7;
+--------+
| 1/7
|
+--------+
| 0.1429 |
+--------+
mysql> SET div_precision_increment = 12;
mysql> SELECT 1/7;
+----------------+
| 1/7
|
+----------------+
| 0.142857142857 |
+----------------+
This variable was added in MySQL 5.0.6.
•
engine_condition_pushdown
This variable applies to NDB. By default it is 0 (OFF): If you execute a query such as SELECT
* FROM t WHERE mycol = 42, where mycol is an unindexed column, the query is ex265
Database Administration
ecuted as a full table scan on every NDB node. Each node sends every row to the MySQL server, which applies the WHERE condition. If engine_condition_pushdown is set to 1 (ON),
the condition is “pushed down” to the storage engine and sent to the NDB nodes. Each node performs the scan, and only sends back to the MySQL server the rows that match the condition.
This variable was added in MySQL 5.0.3. Before that, the default NDB behavior is the same as
for a value of OFF.
•
expire_logs_days
The number of days for automatic binary log removal. The default is 0, which means “no automatic removal”. Possible removals happen at startup and at binary log rotation. This variable
was added in MySQL 4.1.0.
•
flush
This is ON if you have started mysqld with the --flush option. This variable was added in
MySQL 3.22.9.
•
flush_time
If this is set to a non-zero value, all tables are closed every flush_time seconds to free up resources and sync unflushed data to disk. We recommend this option only on Windows 9x or Me,
or on systems with minimal resources available. This variable was added in MySQL 3.22.18.
•
ft_boolean_syntax
The list of operators supported by boolean full-text searches performed using IN BOOLEAN
MODE. This variable was added in MySQL 4.0.1. See Section 12.7.1, “Boolean Full-Text
Searches”.
The default variable value is '+ -><()~*:""&|'. The rules for changing the value are as
follows:
•
•
Operator function is determined by position within the string.
•
The replacement value must be 14 characters.
•
Each character must be an ASCII non-alphanumeric character.
•
Either the first or second character must be a space.
•
No duplicates are allowed except the phrase quoting operators in positions 11 and 12. These
two characters are not required to be the same, but they are the only two that may be.
•
Positions 10, 13, and 14 (which by default are set to ‘:’, ‘&’, and ‘|’) are reserved for future
extensions.
ft_max_word_len
The maximum length of the word to be included in a FULLTEXT index. This variable was added
in MySQL 4.0.0.
Note: FULLTEXT indexes must be rebuilt after changing this variable. Use REPAIR TABLE
tbl_name QUICK.
•
ft_min_word_len
The minimum length of the word to be included in a FULLTEXT index. This variable was added
in MySQL 4.0.0.
Note: FULLTEXT indexes must be rebuilt after changing this variable. Use REPAIR TABLE
tbl_name QUICK.
266
Database Administration
•
ft_query_expansion_limit
The number of top matches to use for full-text searches performed using WITH QUERY EXPANSION. This variable was added in MySQL 4.1.1.
•
ft_stopword_file
The file from which to read the list of stopwords for full-text searches. All the words from the
file are used; comments are not honored. By default, a built-in list of stopwords is used (as
defined in the myisam/ft_static.c file). Setting this variable to the empty string ('') disables stopword filtering. This variable was added in MySQL 4.0.10.
Note: FULLTEXT indexes must be rebuilt after changing this variable or the contents of the
stopword file. Use REPAIR TABLE tbl_name QUICK.
•
group_concat_max_len
The maximum allowed result length for the GROUP_CONCAT() function. This variable was added in MySQL 4.1.0.
•
have_archive
YES if mysqld supports ARCHIVE tables, NO if not. This variable was added in MySQL 4.1.3.
•
have_bdb
YES if mysqld supports BDB tables. DISABLED if --skip-bdb is used. This variable was
added in MySQL 3.23.30.
•
have_blackhole_engine
YES if mysqld supports BLACKHOLE tables, NO if not. This variable was added in MySQL
4.1.11.
•
have_compress
Whether the zlib compression library is available to the server. If not, the COMPRESS() and
UNCOMPRESS() functions cannot be used. This variable was added in MySQL 4.1.1.
•
have_crypt
Whether the crypt() system call is available to the server. If not, the CRYPT() function cannot be used. This variable was added in MySQL 4.0.10.
•
have_csv
YES if mysqld supports ARCHIVE tables, NO if not. This variable was added in MySQL 4.1.4.
•
have_example_engine
YES if mysqld supports EXAMPLE tables, NO if not. This variable was added in MySQL 4.1.4.
•
have_federated_engine
YES if mysqld supports FEDERATED tables, NO if not. This variable was added in MySQL
5.0.3.
•
have_geometry
Whether the server supports spatial data types. This variable was added in MySQL 4.1.3.
•
have_innodb
YES if mysqld supports InnoDB tables. DISABLED if --skip-innodb is used. This vari267
Database Administration
able was added in MySQL 3.23.37.
•
have_isam
YES if mysqld supports ISAM tables. DISABLED if --skip-isam is used. This variable
was added in MySQL 3.23.30.
•
have_ndbcluster
YES if mysqld supports NDB Cluster tables. DISABLED if --skip-ndbcluster is
used. This variable was added in MySQL 4.1.2.
•
have_openssl
YES if mysqld supports SSL (encryption) of the client/server protocol. This variable was added in MySQL 3.23.43.
•
have_query_cache
YES if mysqld supports the query cache. This variable was added in MySQL 4.0.2.
•
have_raid
YES if mysqld supports the RAID option. This variable was added in MySQL 3.23.30.
•
have_rtree_keys
Whether RTREE indexes are available. (These are used for spatial indexed in MyISAM tables.)
This variable was added in MySQL 4.1.3.
•
have_symlink
Whether symbolic link support is enabled. This is required on Unix for support of the DATA
DIRECTORY and INDEX DIRECTORY table options.
This variable was added in MySQL 4.0.0.
•
init_connect
A string to be executed by the server for each client that connects. The string consists of one or
more SQL statements. To specify multiple statements, separate them by semicolon characters.
For example, each client begins by default with autocommit mode enabled. There is no global
server variable to specify that autocommit should be disabled by default, but init_connect
can be used to achieve the same effect:
SET GLOBAL init_connect='SET AUTOCOMMIT=0';
This variable can also be set on the command line or in an option file. To set the variable as just
shown using an option file, include these lines:
[mysqld]
init_connect='SET AUTOCOMMIT=0'
Note that the content of init_connect is not executed for users having the SUPER privilege;
this is in case that content has been wrongly set (contains a wrong query, for example with a
syntax error), thus making all connections fail. Not executing it for SUPER users enables those
to open a connection and fix init_connect. This variable was added in MySQL 4.1.2.
•
init_file
The name of the file specified with the --init-file option when you start the server. This is
a file containing SQL statements that you want the server to execute when it starts. Each statement must be on a single line and should not include comments. This variable was added in
268
Database Administration
MySQL 3.23.2.
•
init_slave
This variable is similar to init_connect, but is a string to be executed by a slave server each
time the SQL thread starts. The format of the string is the same as for the init_connect variable. This variable was added in MySQL 4.1.2.
•
innodb_xxx
The InnoDB system variables are listed at Section 15.5, “InnoDB Startup Options”.
•
interactive_timeout
The number of seconds the server waits for activity on an interactive connection before closing
it. An interactive client is defined as a client that uses the CLIENT_INTERACTIVE option 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). Normally the best
way to get fast joins is to add indexes. Increase the value of join_buffer_size to get a
faster full join when adding indexes is not possible. One join buffer is allocated for each full join
between two tables. For a complex join between several tables for which indexes are not used,
multiple join buffers might be necessary.
•
key_buffer_size
Index blocks for MyISAM and ISAM tables are buffered and are shared by all threads.
key_buffer_size is the size of the buffer used for index blocks. The key buffer is also
known as the key cache.
The maximum allowable setting for key_buffer_size is 4GB. The effective maximum size
might be less, depending on your available physical RAM and per-process RAM limits imposed
by your operating system or hardware platform.
Increase the value to get better index handling (for all reads and multiple writes) to as much as
you can afford. Using a value that is 25% of total memory on a machine that mainly runs
MySQL is quite common. However, if you make the value too large (for example, more than
50% of your total memory) your system might start to page and become extremely slow.
MySQL relies on the operating system to perform filesystem caching for data reads, so you must
leave some room for the filesystem cache.
For even more speed when writing many rows at the same time, use LOCK TABLES. See Section 13.4.5, “LOCK TABLES and UNLOCK TABLES Syntax”.
You can check the performance of the key buffer by issuing a SHOW STATUS statement and
examining the Key_read_requests, Key_reads, Key_write_requests, and
Key_writes status variables. See Section 13.5.4, “SHOW Syntax”.
The Key_reads/Key_read_requests ratio should normally be less than 0.01. The
Key_writes/Key_write_requests ratio is usually near 1 if you are using mostly updates and deletes, but might be much smaller if you tend to do updates that affect many rows at
the same time or if you are using the DELAY_KEY_WRITE table option.
The fraction of the key buffer in use can be determined using key_buffer_size in conjunction with the Key_blocks_unused status variable and the buffer block size. From MySQL
4.1.1 on, the buffer block size is available from the key_cache_block_size server variable. The fraction of the buffer in use is:
1 - ((Key_blocks_unused * key_cache_block_size) / key_buffer_size)
This value is an approximation because some space in the key buffer may be allocated internally
269
Database Administration
for administrative structures.
Before MySQL 4.1.1, key cache blocks are 1024 bytes, and before MySQL 4.1.2,
Key_blocks_unused is unavailable. The Key_blocks_used variable can be used as follows to determine the fraction of the key buffer in use:
(Key_blocks_used * 1024) / key_buffer_size
However, Key_blocks_used indicates the maximum number of blocks that have ever been
in use at once, so this formula does not necessary represent the current fraction of the buffer that
is in use.
As of MySQL 4.1, it is possible to create multiple MyISAM key caches. The size limit of 4GB
applies to each cache individually, not as a group. See Section 7.4.6, “The MyISAM Key
Cache”.
•
key_cache_age_threshold
This value controls the demotion of buffers from the hot sub-chain of a key cache to the warm
sub-chain. Lower values cause demotion to happen more quickly. The minimum value is 100.
The default value is 300. This variable was added in MySQL 4.1.1. See Section 7.4.6, “The MyISAM Key Cache”.
•
key_cache_block_size
The size in bytes of blocks in the key cache. The default value is 1024. This variable was added
in MySQL 4.1.1. See Section 7.4.6, “The MyISAM Key Cache”.
•
key_cache_division_limit
The division point between the hot and warm sub-chains of the key cache buffer chain. The
value is the percentage of the buffer chain to use for the warm sub-chain. Allowable values
range from 1 to 100. The default value is 100. This variable was added in MySQL 4.1.1. See
Section 7.4.6, “The MyISAM Key Cache”.
•
language
The language used for error messages.
•
large_file_support
Whether mysqld was compiled with options for large file support. This variable was added in
MySQL 3.23.28.
•
large_pages
Indicates whether large page support is enabled. This variable was added in MySQL 5.0.3.
•
license
The type of license the server has. This variable was added in MySQL 4.0.19.
•
local_infile
Whether LOCAL is supported for LOAD DATA INFILE statements. This variable was added in
MySQL 4.0.3.
•
locked_in_memory
Whether mysqld was locked in memory with --memlock. This variable was added in
MySQL 3.23.25.
270
Database Administration
•
log
Whether logging of all queries to the general query log is enabled. See Section 5.10.2, “The
General Query Log”.
•
log_bin
Whether the binary log is enabled. This variable was added in MySQL 3.23.14. See Section 5.10.4, “The Binary Log”.
•
log_bin_trust_routine_creators
This variable applies when binary logging is enabled. It controls whether stored routine creators
can be trusted not to create stored routines that will cause unsafe events to be written to the binary log. If set to 0 (the default), users are not allowed to create or alter stored routines unless
they have the SUPER privilege in addition to the CREATE ROUTINE or ALTER ROUTINE
privilege.
A setting of 0 also enforces the restriction that a routine must be declared with the DETERMINISTIC characteristic, or with the READS SQL DATA or NO SQL characteristic. If the variable
is set to 1, MySQL does not enforce these restrictions on stored routine creation.
See Section 18.4, “Binary Logging of Stored Routines and Triggers”.
This variable was added in MySQL 5.0.6.
•
log_error
The location of the error log. This variable was added in MySQL 4.0.10.
•
log_slave_updates
Whether updates received by a slave server from a master server should be logged to the slave's
own binary log. Binary logging must be enabled on the slave for this to have any effect. This
variable was added in MySQL 3.23.17. See Section 6.8, “Replication Startup Options”.
•
log_slow_queries
Whether slow queries should be logged. “Slow” is determined by the value of the
long_query_time variable. This variable was added in MySQL 4.0.2. See Section 5.10.5,
“The Slow Query Log”.
•
log_update
Whether the update log is enabled. This variable was added in MySQL 3.22.18. Note that the
binary log is preferable to the update log, which is unavailable as of MySQL 5.0. See Section 5.10.3, “The Update Log”.
•
log_warnings
Whether to produce additional warning messages. This variable was added in MySQL 4.0.3. It is
enabled by default as of MySQL 4.0.19 and 4.1.2. As of MySQL 4.0.21 and 4.1.3, aborted connections are not logged to the error log unless the value is greater than 1.
•
long_query_time
If a query takes longer than this many seconds, the Slow_queries status variable is incremented. If you are using the --log-slow-queries option, the query is logged to the slow
query log file. This value is measured in real time, not CPU time, so a query that is under the
threshold on a lightly loaded system might be above the threshold on a heavily loaded one. See
Section 5.10.5, “The Slow Query Log”.
•
low_priority_updates
271
Database Administration
If set to 1, all INSERT, UPDATE, DELETE, and LOCK TABLE WRITE statements wait until
there is no pending SELECT or LOCK TABLE READ on the affected table. This variable previously was named sql_low_priority_updates. It was added in MySQL 3.22.5.
•
lower_case_file_system
This variable indicates whether the filesystem where the data directory is located has case insensitive filenames. ON means filenames are case insensitive, OFF means they are case sensitive.
This variable was added in MySQL 4.0.19.
•
lower_case_table_names
If set to 1, table names are stored in lowercase on disk and table name comparisons are not case
sensitive. This variable was added in MySQL 3.23.6. If set to 2 (new in 4.0.18), table names are
stored as given but compared in lowercase. From MySQL 4.0.2, this option also applies to database names. From 4.1.1, it also applies to table aliases. See Section 9.2.2, “Identifier Case Sensitivity”.
If you are using InnoDB tables, you should set this variable to 1 on all platforms to force names
to be converted to lowercase.
You should not set this variable to 0 if you are running MySQL on a system that does not have
case-sensitive filenames (such as Windows or Mac OS X). New in 4.0.18: If this variable is not
set at startup and the filesystem on which the data directory is located does not have casesensitive filenames, MySQL automatically sets lower_case_table_names to 2.
•
max_allowed_packet
The maximum size of one packet or any generated/intermediate string.
The packet message buffer is initialized to net_buffer_length bytes, but can grow up to
max_allowed_packet bytes when needed. This value by default is small, to catch big
(possibly wrong) packets.
You must increase this value if you are using big BLOB columns or long strings. It should be as
big as the biggest BLOB you want to use. The protocol limit for max_allowed_packet is
16MB before MySQL 4.0 and 1GB thereafter.
•
max_binlog_cache_size
If a multiple-statement transaction requires more than this amount of memory, you get the error
Multi-statement
transaction
required
more
than
'max_binlog_cache_size' bytes of storage. This variable was added in MySQL
3.23.29.
•
max_binlog_size
If a write to the binary log exceeds the given value, rotate the binary logs. You cannot set this
variable to more than 1GB or to less than 4096 bytes. (The minimum before MYSQL 4.0.14 is
1024 bytes.) The default value is 1GB. This variable was added in MySQL 3.23.33.
Note if you are using transactions: A transaction is written in one chunk to the binary log, hence
it is never split between several binary logs. Therefore, if you have big transactions, you might
see binary logs bigger than max_binlog_size.
If max_relay_log_size is 0, the value of max_binlog_size applies to relay logs as
well. max_relay_log_size was added in MySQL 4.0.14.
•
max_connect_errors
If there are more than this number of interrupted connections from a host, that host is blocked
from further connections. You can unblock blocked hosts with the FLUSH HOSTS statement.
272
Database Administration
•
max_connections
The number of simultaneous client connections allowed. Increasing this value increases the
number of file descriptors that mysqld requires. See Section 7.4.8, “How MySQL Opens and
Closes Tables” for comments on file descriptor limits. Also see Section A.2.6, “Too many
connections”.
•
max_delayed_threads
Don't start more than this number of threads to handle INSERT DELAYED statements. If you
try to insert data into a new table after all INSERT DELAYED threads are in use, the row is inserted as if the DELAYED attribute wasn't specified. If you set this to 0, MySQL never creates a
thread to handle DELAYED rows; in effect, this disables DELAYED entirely. This variable was
added in MySQL 3.23.0.
•
max_error_count
The maximum number of error, warning, and note messages to be stored for display by SHOW
ERRORS or SHOW WARNINGS. This variable was added in MySQL 4.1.0.
•
max_heap_table_size
This variable sets the maximum size to which MEMORY (HEAP) tables are allowed to grow. The
value of the variable is used to calculate MEMORY table MAX_ROWS values. Setting this variable
has no effect on any existing MEMORY table, unless the table is re-created with a statement such
as CREATE TABLE or TRUNCATE TABLE, or altered with ALTER TABLE. This variable was
added in MySQL 3.23.0.
•
max_insert_delayed_threads
This variable is a synonym for max_delayed_threads. It was added in MySQL 4.0.19.
•
max_join_size
Don't allow SELECT statements that probably need to examine more than max_join_size
rows (for single-table statements) or row combinations (for multiple-table statements) or that are
likely to do more than max_join_size disk seeks. By setting this value, you can catch SELECT statements where keys are not used properly and that would probably take a long time. Set
it if your users tend to perform joins that lack a WHERE clause, that take a long time, or that return millions of rows.
Setting this variable to a value other than DEFAULT resets the SQL_BIG_SELECTS value to 0.
If you set the SQL_BIG_SELECTS value again, the max_join_size variable is ignored.
If a query result is in the query cache, no result size check is performed, because the result has
previously been computed and it does not burden the server to send it to the client.
This variable previously was named sql_max_join_size.
•
max_length_for_sort_data
The cutoff on the size of index values that determines which filesort algorithm to use. See
Section 7.2.12, “How MySQL Optimizes ORDER BY”. This variable was added in MySQL
4.1.1
•
max_relay_log_size
If a write by a replication slave to its relay log exceeds the given value, rotate the relay log. This
variable enables you to put different size constraints on relay logs and binary logs. However, setting the variable to 0 makes MySQL use max_binlog_size for both binary logs and relay
logs. You must set max_relay_log_size to between 4096 bytes and 1GB (inclusive), or to
0. The default value is 0. This variable was added in MySQL 4.0.14. See Section 6.3,
“Replication Implementation Details”.
273
Database Administration
•
max_seeks_for_key
Limit the assumed maximum number of seeks when looking up rows based on a key. The
MySQL optimizer assumes that no more than this number of key seeks are required when
searching for matching rows in a table by scanning a key, regardless of the actual cardinality of
the key (see Section 13.5.4.11, “SHOW INDEX Syntax”). By setting this to a low value (100?),
you can force MySQL to prefer keys instead of table scans.
This variable was added in MySQL 4.0.14.
•
max_sort_length
The number of bytes to use when sorting BLOB or TEXT values. Only the first
max_sort_length bytes of each value are used; the rest are ignored.
•
max_tmp_tables
The maximum number of temporary tables a client can keep open at the same time. (This option
doesn't yet do anything.)
•
max_user_connections
The maximum number of simultaneous connections allowed to any given MySQL account. A
value of 0 means “no limit.” This variable was added in MySQL 3.23.34.
Before MySQL 5.0.3, this variable has only a global form. Beginning with MySQL 5.0.3, it also
has a read-only session form. The session variable has the same value as the global variable unless the current account has a non-zero MAX_USER_CONNECTIONS resource limit. In that case,
the session value reflects the account limit.
•
max_write_lock_count
After this many write locks, allow some read locks to run in between. This variable was added in
MySQL 3.23.7.
•
multi_read_range
Specifies the maximum number of ranges to send to a storage engine during range selects. The
default value is 256. Sending multiple ranges to an engine is a feature that can improve the performance of certain selects dramatically, particularly for NDBCLUSTER. This engine needs to
send the range requests to all nodes, and sending many of those requests at once reduces the
communication costs significantly. This variable was added in MySQL 5.0.3.
•
myisam_data_pointer_size
The default pointer size in bytes, to be used by CREATE TABLE for MyISAM tables when no
MAX_ROWS option is specified. This variable cannot be less than 2 or larger than 7. The default
value is 6 (4 before MySQL 5.0.6). This variable was added in MySQL 4.1.2. See Section A.2.11, “The table is full”.
•
myisam_max_extra_sort_file_size
If the temporary file used for fast MyISAM index creation would be larger than using the key
cache by the amount specified here, prefer the key cache method. This is mainly used to force
long character keys in large tables to use the slower key cache method to create the index. This
variable was added in MySQL 3.23.37. Note: The value is given in megabytes before 4.0.3 and
in bytes thereafter. This variable was removed in MySQL 5.0.6.
•
myisam_max_sort_file_size
The maximum size of the temporary file MySQL is allowed to use while re-creating a MyISAM
index (during REPAIR TABLE, ALTER TABLE, or LOAD DATA INFILE). If the file size
would be bigger than this value, the index is created using the key cache instead, which is
slower. This variable was added in MySQL 3.23.37. Note: The value is given in megabytes be274
Database Administration
fore 4.0.3 and in bytes thereafter.
•
myisam_recover_options
The value of the --myisam-recover option. This variable was added in MySQL 3.23.36.
•
myisam_repair_threads
If this value is greater than 1, MyISAM table indexes are created in parallel (each index in its
own thread) during the Repair by sorting process. The default value is 1. Note: Multithreaded repair is still alpha quality code. This variable was added in MySQL 4.0.13.
•
myisam_sort_buffer_size
The buffer that is allocated when sorting MyISAM indexes during a REPAIR TABLE or when
creating indexes with CREATE INDEX or ALTER TABLE. This variable was added in MySQL
3.23.16.
•
named_pipe
On Windows, indicates whether the server supports connections over named pipes. This variable
was added in MySQL 3.23.50.
•
net_buffer_length
The communication buffer is reset to this size between queries. This should not normally be
changed, but if you have very little memory, you can set it to the expected length of SQL statements sent by clients. If statements exceed this length, the buffer is automatically enlarged, up to
max_allowed_packet bytes.
•
net_read_timeout
The number of seconds to wait for more data from a connection before aborting the read. When
the server is reading from the client, net_read_timeout is the timeout value controlling
when to abort. When the server is writing to the client, net_write_timeout is the timeout
value controlling when to abort. See also slave_net_timeout. This variable was added in
MySQL 3.23.20.
•
net_retry_count
If a read on a communication port is interrupted, retry this many times before giving up. This
value should be set quite high on FreeBSD because internal interrupts are sent to all threads.
This variable was added in MySQL 3.23.7.
•
net_write_timeout
The number of seconds to wait for a block to be written to a connection before aborting the
write. See also net_read_timeout. This variable was added in MySQL 3.23.20.
•
new
This variable is used in MySQL 4.0 to turn on some 4.1 behaviors. This variable was added in
MySQL 4.0.12.
•
old_passwords
Whether the server should use pre-4.1-style passwords for MySQL user accounts. This variable
was added in MySQL 4.1.1.
•
one_shot
This is not a variable, but it can be used when setting some variables. It's described in Section 13.5.3, “SET Syntax”.
275
Database Administration
•
open_files_limit
The number of files that the operating system allows mysqld to open. This is the real value allowed by the system and might be different from the value you gave mysqld as a startup option. The value is 0 on systems where MySQL can't change the number of open files. This variable was added in MySQL 3.23.20.
•
optimizer_prune_level
Controls the heuristics applied during query optimization to prune less-promising partial plans
from the optimizer search space. A value of 0 disables heuristics so that the optimizer performs
an exhaustive search. A value of 1 causes the optimizer to prune plans based on the number of
rows retrieved by intermediate plans. This variable was added in MySQL 5.0.1.
•
optimizer_search_depth
The maximum depth of search performed by the query optimizer. Values larger than the number
of relations in a query result in better query plans, but take longer to generate an execution plan
for a query. Values smaller than the number of relations in a query return an execution plan
quicker, but the resulting plan may be far from being optimal. If set to 0, the system automatically picks a reasonable value. If set to the maximum number of tables used in a query plus 2, the
optimizer switches to the original algorithm used before MySQL 5.0.1 that performs an exhaustive search. This variable was added in MySQL 5.0.1.
•
pid_file
The pathname of the process ID (PID) file. This variable can be set with the --pid-file option. This variable was added in MySQL 3.23.23.
•
port
The port on which the server listens for TCP/IP connections. This variable can be set with the -port option.
•
preload_buffer_size
The size of the buffer that is allocated when preloading indexes. This variable was added in
MySQL 4.1.1.
•
protocol_version
The version of the client/server protocol used by the MySQL server. This variable was added in
MySQL 3.23.18.
•
query_alloc_block_size
The allocation size of memory blocks that are allocated for objects created during query parsing
and execution. If you have problems with memory fragmentation, it might help to increase this a
bit. This variable was added in MySQL 4.0.16.
•
query_cache_limit
Don't cache results that are bigger than this. The default value is 1MB. This variable was added
in MySQL 4.0.1.
•
query_cache_min_res_unit
The minimum size for blocks allocated by the query cache. The default value is 4KB. Tuning information for this variable is given in Section 5.12.3, “Query Cache Configuration”. This variable is present from MySQL 4.1.
•
query_cache_size
The amount of memory allocated for caching query results. The default value is 0, which dis276
Database Administration
ables the query cache. Note that this amount of memory is allocated even if
query_cache_type is set to 0. This variable was added in MySQL 4.0.1.
•
query_cache_type
Set query cache type. Setting the GLOBAL value sets the type for all clients that connect thereafter. Individual clients can set the SESSION value to affect their own use of the query cache.
Option
Description
0 or OFF
Don't cache or retrieve results. Note that this does not deallocate the query
cache buffer. To do that, you should set query_cache_size to 0.
1 or ON
Cache all query results except for those that begin with SELECT
SQL_NO_CACHE.
2 or DEMAND
Cache results only for queries that begin with SELECT SQL_CACHE.
This variable was added in MySQL 4.0.3.
•
query_cache_wlock_invalidate
Normally, when one client acquires a WRITE lock on a MyISAM table, other clients are not
blocked from issuing queries for the table if the query results are present in the query cache. Setting this variable to 1 causes acquisition of a WRITE lock for a table to invalidate any queries in
the query cache that refer to the table. This forces other clients that attempt to access the table to
wait while the lock is in effect. This variable was added in MySQL 4.0.19.
•
query_prealloc_size
The size of the persistent buffer used for query parsing and execution. This buffer is not freed
between queries. If you are running complex queries, a larger query_prealloc_size value
might be helpful in improving performance, because it can reduce the need for the server to perform memory allocation during query execution operations.
This variable was added in MySQL 4.0.16.
•
range_alloc_block_size
The size of blocks that are allocated when doing range optimization. This variable was added in
MySQL 4.0.16.
•
read_buffer_size
Each thread that does a sequential scan allocates a buffer of this size for each table it scans. If
you do many sequential scans, you might want to increase this value. This variable was added in
MySQL 4.0.3. Previously, it was named record_buffer.
•
read_only
When the variable is set to ON for a replication slave server, it causes the slave to allow no updates except from slave threads or from users with the SUPER privilege. This can be useful to
ensure that a slave server accepts no updates from clients. This variable was added in MySQL
4.0.14.
•
relay_log_purge
Disables or enables automatic purging of relay logs as soon as they are not needed any more.
The default value is 1 (enabled). This variable was added in MySQL 4.1.1.
•
read_rnd_buffer_size
277
Database Administration
When reading rows in sorted order after a sort, the rows are read through this buffer to avoid
disk seeks. Setting the variable to a large value can improve ORDER BY performance by a lot.
However, this is a buffer allocated for each client, so you should not set the global variable to a
large value. Instead, change the session variable only from within those clients that need to run
large queries. This variable was added in MySQL 4.0.3. Previously, it was named record_rnd_buffer.
•
safe_show_database
Don't show databases for which the user has no database or table privileges. This can improve
security if you're concerned about people being able to see what databases other users have. See
also skip_show_database.
This variable was removed in MySQL 4.0.5. Instead, use the SHOW DATABASES privilege to
control access by MySQL accounts to database names.
•
secure_auth
If the MySQL server has been started with the --secure-auth option, it blocks connections
from all accounts that have passwords stored in the old (pre-4.1) format. In that case, the value
of this variable is ON, otherwise it is OFF.
You should enable this option if you want to prevent all usage of passwords in old format (and
hence insecure communication over the network). This variable was added in MySQL 4.1.1.
Server startup fails with an error if this option is enabled and the privilege tables are in pre-4.1
format.
When used as a client-side option, the client refuses to connect to a server if the server requires a
password in old format for the client account.
•
server_id
The value of the --server-id option. It is used for master and slave replication servers. This
variable was added in MySQL 3.23.26.
•
shared_memory
Whether or not the server allows shared-memory connections. Currently, only Windows servers
support this. This variable was added in MySQL 4.1.1.
•
shared_memory_base_name
Indicates whether or not the server allows shared-memory connections, and sets the identifier for
the shared memory. This is useful when running multiple MYSQL instances on a single physical
machine. Currently, only Windows servers support this. This variable was added in MySQL
4.1.0.
•
skip_external_locking
This is OFF if mysqld uses external locking. This variable was added in MySQL 4.0.3. Previously, it was named skip_locking.
•
skip_networking
This is ON if the server allows only local (non-TCP/IP) connections. On Unix, local connections
use a Unix socket file. On Windows, local connections use a named pipe or shared memory. On
NetWare, only TCP/IP connections are supported, so do not set this variable to ON. This variable
was added in MySQL 3.22.23.
•
skip_show_database
This prevents people from using the SHOW DATABASES statement if they don't have the SHOW
278
Database Administration
DATABASES privilege. This can improve security if you're concerned about people being able
to see what databases other users have. See also safe_show_database. This variable was
added in MySQL 3.23.4. As of MySQL 4.0.2, its effect also depends on the SHOW DATABASES privilege: If the variable value is ON, the SHOW DATABASES statement is allowed only
to users who have the SHOW DATABASES privilege, and the statement displays all database
names. If the value is OFF, SHOW DATABASES is allowed to all users, but displays each database name only if the user has the SHOW DATABASES privilege or some privilege for the database.
•
slave_compressed_protocol
Whether to use compression of the slave/master protocol if both the slave and the master support
it. This variable was added in MySQL 4.0.3.
•
slave_load_tmpdir
The name of the directory where the slave creates temporary files for replicating LOAD DATA
INFILE statement. This variable was added in MySQL 4.0.0.
•
slave_net_timeout
The number of seconds to wait for more data from a master/slave connection before aborting the
read. This variable was added in MySQL 3.23.40.
•
slave_skip_errors
The replication errors that the slave should skip (ignore). This variable was added in MySQL
3.23.47.
•
slave_transaction_retries
If a replication slave SQL thread fails to execute a transaction because of an InnoDB deadlock
or exceeded InnoDB's innodb_lock_wait_timeout or NDBCluster's TransactionDeadlockDetectionTimeout or TransactionInactiveTimeout, it automatically
retries slave_transaction_retries times before stopping with an error. The default in
MySQL 4.1 is 0. You must explicitly set the value greater than 0 to enable the “retry” behavior,
which is probably a good idea. In MySQL 5.0.3 or newer, the default is 10.
•
slow_launch_time
If creating a thread takes longer than this many seconds, the server increments the
Slow_launch_threads status variable. This variable was added in MySQL 3.23.15.
•
socket
On Unix, this is the Unix socket file used for local client connections. On Windows, this is the
name of the named pipe used for local client connections.
•
sort_buffer_size
Each thread that needs to do a sort allocates a buffer of this size. Increase this value for faster
ORDER BY or GROUP BY operations. See Section A.4.4, “Where MySQL Stores Temporary
Files”.
•
sql_mode
The current server SQL mode. This variable was added in MySQL 3.23.41. It can be set dynamically as of MySQL 4.1.1. See Section 5.3.2, “The Server SQL Mode”.
•
sql_slave_skip_counter
The number of events from the master that a slave server should skip. It was added in MySQL
3.23.33.
279
Database Administration
•
storage_engine
This variable is a synonym for table_type. It was added in MySQL 4.1.2.
•
sync_binlog
If positive, the MySQL server synchronizes its binary log to disk (fdatasync()) after every
sync_binlog'th write to this binary log. Note that there is one write to the binary log per
statement if in autocommit mode, and otherwise one write per transaction. The default value is 0
which does no sync'ing to disk. A value of 1 is the safest choice, because in case of crash you
lose at most one statement/transaction from the binary log; but it is also the slowest choice
(unless the disk has a battery-backed cache, which makes sync'ing very fast). This variable was
added in MySQL 4.1.3.
•
sync_frm
This was added as a command-line option in MySQL 4.0.18, and is also a settable global variable since MySQL 4.1.3. If set to 1, when a non-temporary table is created it synchronizes its
.frm file to disk (fdatasync()); this is slower but safer in case of crash. Default is 1.
•
system_time_zone
The server system time zone. When the server begins executing, it inherits a time zone setting
from the machine defaults, possibly modified by the environment of the account used for running the server or the startup script. The value is used to set system_time_zone. Typically
the time zone is specified by the TZ environment variable. It also can be specified using the -timezone option of the mysqld_safe script. This variable was added in MySQL 4.1.3.
•
table_cache
The number of open tables for all threads. Increasing this value increases the number of file
descriptors that mysqld requires. You can check whether you need to increase the table cache
by checking the Opened_tables status variable. See Section 5.3.4, “Server Status
Variables”. If the value of Opened_tables is large and you don't do FLUSH TABLES a lot
(which just forces all tables to be closed and reopened), then you should increase the value of the
table_cache variable.
For more information about the table cache, see Section 7.4.8, “How MySQL Opens and Closes
Tables”.
•
table_type
The default table type (storage engine). To set the table type at server startup, use the -default-table-type option. This variable was added in MySQL 3.23.0. See Section 5.3.1, “mysqld Command-Line Options”.
•
thread_cache_size
How many threads the server should cache for reuse. When a client disconnects, the client's
threads are put in the cache if there are fewer than thread_cache_size threads there. Requests for threads are satisfied by reusing threads taken from the cache if possible, and only
when the cache is empty is a new thread created. This variable can be increased to improve performance if you have a lot of new connections. (Normally this doesn't give a notable performance improvement if you have a good thread implementation.) By examining the difference
between the Connections and Threads_created status variables (see Section 5.3.4,
“Server Status Variables” for details) you can see how efficient the thread cache is. This variable
was added in MySQL 3.23.16.
•
thread_concurrency
On Solaris, mysqld calls thr_setconcurrency() with this value. This function allows
applications to give the threads system a hint about the desired number of threads that should be
run at the same time. This variable was added in MySQL 3.23.7.
280
Database Administration
•
thread_stack
The stack size for each thread. Many of the limits detected by the crash-me test are dependent
on this value. The default is large enough for normal operation. See Section 7.1.4, “The MySQL
Benchmark Suite”.
•
time_format
This variable is not implemented.
•
time_zone
The current time zone. The initial value of this is 'SYSTEM' (use the value of system_time_zone), but can be specified explicitly at server startup time with the -default-time-zone option. This variable was added in MySQL 4.1.3.
•
timezone
The time zone for the server. This is set from the TZ environment variable when mysqld is
started. The time zone also can be set by giving a --timezone argument to mysqld_safe.
This variable was added in MySQL 3.23.15. As of MySQL 4.1.3, it is obsolete and has been replaced by the system_time_zone variable. See Section A.4.6, “Time Zone Problems”.
•
tmp_table_size
If an in-memory temporary table exceeds this size, MySQL automatically converts it to an ondisk 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, this
variable can be set to a list of several paths that are used in round-robin fashion. Paths should be
separated by colon characters (‘:’) on Unix and semicolon characters (‘;’) on Windows, NetWare, and OS/2.
This feature can be used to spread the load between several physical disks. If the MySQL server
is acting as a replication slave, you should not set tmpdir to point to a directory on a memorybased filesystem or to a directory that is cleared when the server host restarts. A replication slave
needs some of its temporary files to survive a machine restart so that it can replicate temporary
tables or LOAD DATA INFILE operations. If files in the temporary file directory are lost when
the server restarts, replication fails. However, if you're using MySQL 4.0.0 or later, you may set
the slave's temporary directory using the slave_load_tmpdir variable. In that case, the
slave won't use the general tmpdir any more, which means you can set tmpdir to a nonpermanent location then.
This variable was added in MySQL 3.22.4.
•
transaction_alloc_block_size
The allocation size of memory blocks that are allocated for storing queries that are part of a
transaction to be stored in the binary log when doing a commit. This variable was added in
MySQL 4.0.16.
•
transaction_prealloc_size
The size of the persistent buffer for transaction_alloc_blocks that is not freed
between queries. By making this big enough to fit all queries in a common transaction, you can
avoid a lot of malloc() calls. This variable was added in MySQL 4.0.16.
•
tx_isolation
The default transaction isolation level. This variable was added in MySQL 4.0.3.
281
Database Administration
•
updatable_views_with_limit
This variable controls whether updates can be made using a view that does not contain a primary
key in the underlying table, if the update contains a LIMIT clause. (Such updates often are generated by GUI tools.) An update is an UPDATE or DELETE statement. Primary key here means a
PRIMARY KEY, or a UNIQUE index in which no column can contain NULL.
The variable can have two values:
•
1 or YES: Issue a warning only (not an error message). This is the default value.
•
0 or NO: Prohibit the update.
This variable was added in MySQL 5.0.2.
•
version
The version number for the server.
•
version_bdb
The BDB storage engine version. This variable was added in MySQL 3.23.31 with the name
bdb_version and renamed to version_bdb in MySQL 4.1.1.
•
version_comment
The configure script has a --with-comment option that allows a comment to be specified
when building MySQL. This variable contains the value of that comment. This variable was added in MySQL 4.0.17.
•
version_compile_machine
The type of machine MySQL was built on. This variable was added in MySQL 4.1.1.
•
version_compile_os
The type of operating system MySQL was built on. This variable was added in MySQL 4.0.19.
•
wait_timeout
The number of seconds the server waits for activity on a non-interactive connection before closing it.
On thread startup, the session wait_timeout value is initialized from the global
wait_timeout value or from the global interactive_timeout value, depending on the
type of client (as defined by the CLIENT_INTERACTIVE connect option to
mysql_real_connect()). See also interactive_timeout.
5.3.3.1. Dynamic System Variables
Beginning with MySQL 4.0.3, many server system variables are dynamic and can be set at runtime
using SET GLOBAL or SET SESSION. You can also select their values using SELECT. See Section 9.4, “System Variables”.
The following table shows the full list of all dynamic system variables. The last column indicates for
each variable whether GLOBAL or SESSION (or both) apply.
Variable Name
Value Type
Type
autocommit
boolean
SESSION
big_tables
boolean
SESSION
binlog_cache_size
numeric
GLOBAL
282
Database Administration
bulk_insert_buffer_size
numeric
GLOBAL | SESSION
character_set_client
string
GLOBAL | SESSION
character_set_connection
string
GLOBAL | SESSION
character_set_results
string
GLOBAL | SESSION
character_set_server
string
GLOBAL | SESSION
collation_connection
string
GLOBAL | SESSION
collation_server
string
GLOBAL | SESSION
completion_type
numeric
GLOBAL | SESSION
concurrent_insert
boolean
GLOBAL
connect_timeout
numeric
GLOBAL
convert_character_set
string
GLOBAL | SESSION
default_week_format
numeric
GLOBAL | SESSION
delay_key_write
OFF | ON | ALL
GLOBAL
delayed_insert_limit
numeric
GLOBAL
delayed_insert_timeout
numeric
GLOBAL
delayed_queue_size
numeric
GLOBAL
div_precision_increment
numeric
GLOBAL | SESSION
engine_condition_pushdown
boolean
GLOBAL | SESSION
error_count
numeric
SESSION
expire_logs_days
numeric
GLOBAL
flush
boolean
GLOBAL
flush_time
numeric
GLOBAL
foreign_key_checks
boolean
SESSION
ft_boolean_syntax
numeric
GLOBAL
group_concat_max_len
numeric
GLOBAL | SESSION
identity
numeric
SESSION
innodb_autoextend_increment
numeric
GLOBAL
innodb_concurrency_tickets
numeric
GLOBAL
innodb_max_dirty_pages_pct
numeric
GLOBAL
innodb_max_purge_lag
numeric
GLOBAL
innodb_support_xa
boolean
GLOBAL | SESSION
innodb_sync_spin_loops
numeric
GLOBAL
innodb_table_locks
boolean
GLOBAL | SESSION
innodb_thread_concurrency
numeric GLOBAL
innodb_thread_sleep_delay
numeric GLOBAL
insert_id
boolean
SESSION
interactive_timeout
numeric
GLOBAL | SESSION
join_buffer_size
numeric
GLOBAL | SESSION
key_buffer_size
numeric
GLOBAL
last_insert_id
numeric
SESSION
local_infile
boolean
GLOBAL
log_bin_trust_routine_creator boolean
s
GLOBAL
log_warnings
numeric
GLOBAL
long_query_time
numeric
GLOBAL | SESSION
283
Database Administration
low_priority_updates
boolean
GLOBAL | SESSION
max_allowed_packet
numeric
GLOBAL | SESSION
max_binlog_cache_size
numeric
GLOBAL
max_binlog_size
numeric
GLOBAL
max_connect_errors
numeric
GLOBAL
max_connections
numeric
GLOBAL
max_delayed_threads
numeric
GLOBAL
max_error_count
numeric
GLOBAL | SESSION
max_heap_table_size
numeric
GLOBAL | SESSION
max_insert_delayed_threads
numeric
GLOBAL
max_join_size
numeric
GLOBAL | SESSION
max_relay_log_size
numeric
GLOBAL
max_seeks_for_key
numeric
GLOBAL | SESSION
max_sort_length
numeric
GLOBAL | SESSION
max_tmp_tables
numeric
GLOBAL | SESSION
max_user_connections
numeric
GLOBAL
max_write_lock_count
numeric
GLOBAL
multi_read_range
numeric
GLOBAL | SESSION
myisam_data_pointer_size
numeric
GLOBAL
myisam_max_sort_file_size
numeric
GLOBAL | SESSION
myisam_repair_threads
numeric
GLOBAL | SESSION
myisam_sort_buffer_size
numeric
GLOBAL | SESSION
net_buffer_length
numeric
GLOBAL | SESSION
net_read_timeout
numeric
GLOBAL | SESSION
net_retry_count
numeric
GLOBAL | SESSION
net_write_timeout
numeric
GLOBAL | SESSION
old_passwords
numeric
GLOBAL | SESSION
optimizer_prune_level
numeric
GLOBAL | SESSION
optimizer_search_depth
numeric
GLOBAL | SESSION
preload_buffer_size
numeric
GLOBAL | SESSION
query_alloc_block_size
numeric
GLOBAL | SESSION
query_cache_limit
numeric
GLOBAL
query_cache_size
numeric
GLOBAL
query_cache_type
enumeration
GLOBAL | SESSION
query_cache_wlock_invalidate
boolean
GLOBAL | SESSION
query_prealloc_size
numeric
GLOBAL | SESSION
range_alloc_block_size
numeric
GLOBAL | SESSION
read_buffer_size
numeric
GLOBAL | SESSION
read_only
numeric
GLOBAL
read_rnd_buffer_size
numeric
GLOBAL | SESSION
rpl_recovery_rank
numeric
GLOBAL
safe_show_database
boolean
GLOBAL
secure_auth
boolean
GLOBAL
server_id
numeric
GLOBAL
slave_compressed_protocol
boolean
GLOBAL
284
Database Administration
slave_net_timeout
numeric
GLOBAL
slave_transaction_retries
numeric
GLOBAL
slow_launch_time
numeric
GLOBAL
sort_buffer_size
numeric
GLOBAL | SESSION
sql_auto_is_null
boolean
SESSION
sql_big_selects
boolean
SESSION
sql_big_tables
boolean
SESSION
sql_buffer_result
boolean
SESSION
sql_log_bin
boolean
SESSION
sql_log_off
boolean
SESSION
sql_log_update
boolean
SESSION
sql_low_priority_updates
boolean
GLOBAL | SESSION
sql_max_join_size
numeric
GLOBAL | SESSION
sql_mode
enumeration
GLOBAL | SESSION
sql_notes
boolean
SESSION
sql_quote_show_create
boolean
SESSION
sql_safe_updates
boolean
SESSION
sql_select_limit
numeric
SESSION
sql_slave_skip_counter
numeric
GLOBAL
updatable_views_with_limit
enumeration
GLOBAL | SESSION
sql_warnings
boolean
SESSION
sync_binlog
numeric
GLOBAL
sync_frm
boolean
GLOBAL
storage_engine
enumeration
GLOBAL | SESSION
table_cache
numeric
GLOBAL
table_type
enumeration
GLOBAL | SESSION
thread_cache_size
numeric
GLOBAL
time_zone
string
GLOBAL | SESSION
timestamp
boolean
SESSION
tmp_table_size
enumeration
GLOBAL | SESSION
transaction_alloc_block_size
numeric
GLOBAL | SESSION
transaction_prealloc_size
numeric
GLOBAL | SESSION
tx_isolation
enumeration
GLOBAL | SESSION
unique_checks
boolean
SESSION
wait_timeout
numeric
GLOBAL | SESSION
warning_count
numeric
SESSION
Variables that are marked as “string” take a string value. Variables that are marked as “numeric”
take a numeric value. Variables that are marked as “boolean” can be set to 0, 1, ON or OFF. Variables that are marked as “enumeration” normally should be set to one of the available values for the
variable, but can also be set to the number that corresponds to the desired enumeration value. For
enumeration-valued system variables, the first enumeration value corresponds to 0. This differs from
ENUM columns, for which the first enumeration value corresponds to 1.
5.3.4. Server Status Variables
The server maintains many status variables that provide information about its operations. You can
285
Database Administration
view these variables and their values by using the SHOW STATUS statement:
mysql> SHOW STATUS;
+--------------------------+------------+
| Variable_name
| Value
|
+--------------------------+------------+
| Aborted_clients
| 0
|
| Aborted_connects
| 0
|
| Bytes_received
| 155372598 |
| Bytes_sent
| 1176560426 |
| Connections
| 30023
|
…
Many status variables are reset to 0 by the FLUSH STATUS statement.
The status variables have the following meanings. The Com_xxx statement counter variables were
added beginning with MySQL 3.23.47. The Qcache_xxx query cache variables were added beginning with MySQL 4.0.1. Otherwise, variables with no version indicated have been present since at
least MySQL 3.22.
•
Aborted_clients
The number of connections that were aborted because the client died without closing the connection properly. See Section A.2.10, “Communication Errors and Aborted Connections”.
•
Aborted_connects
The number of tries to connect to the MySQL server that failed. See Section A.2.10,
“Communication Errors and Aborted Connections”.
•
Binlog_cache_disk_use
The number of transactions that used the temporary binary log cache but that exceeded the value
of binlog_cache_size and used a temporary file to store statements from the transaction.
This variable was added in MySQL 4.1.2.
•
Binlog_cache_use
The number of transactions that used the temporary binary log cache. This variable was added in
MySQL 4.1.2.
•
Bytes_received
The number of bytes received from all clients. This variable was added in MySQL 3.23.7.
•
Bytes_sent
The number of bytes sent to all clients. This variable was added in MySQL 3.23.7.
•
Com_xxx
The Com_xxx statement counter variables were added beginning with MySQL 3.23.47. They
indicate the number of times each xxx statement has been executed. There is one status variable
for each type of statement. For example, Com_delete and Com_insert count DELETE and
INSERT statements.
New Com_stmt_xxx status variables have been added in MySQL 4.1.13 or 5.0.8, respectively.
•
Com_stmt_prepare
•
Com_stmt_execute
286
Database Administration
•
Com_stmt_fetch (not available in versions before 5.0)
•
Com_stmt_send_long_data
•
Com_stmt_reset
•
Com_stmt_close
Those variables stand for prepared statements commands. Their names refer to the COM_xxx
command set used in the network layer; in other words: Their values are being increased
whenever prepared statements API calls such as mysql_stmt_prepare(),
mysql_stmt_execute(), and so forth are executed. However, Com_stmt_prepare,
Com_stmt_execute and Com_stmt_close are also increased when one issues the following SQL statements: PREPARE, EXECUTE, or DEALLOCATE PREPARE respectively. Additionally, the values of the older (available since MySQL 4.1.3) statement counter variables
Com_prepare_sql, Com_execute_sql, and Com_dealloc_sql are increased for the
PREPARE, EXECUTE, and DEALLOCATE PREPARE statements. Com_stmt_fetch stands
for the total number of network round-trips issued when fetching from cursors.
All of the Com_stmt_xxx variables are increased even if their argument (a prepared statement) is unknown or an error occurred during execution; in other words: Their values correspond to the number of requests issued, not to the number of requests successfully completed.
•
Connections
The number of connection attempts (successful or not) to the MySQL server.
•
Created_tmp_disk_tables
The number of temporary tables on disk created automatically by the server while executing
statements. This variable was added in MySQL 3.23.24.
•
Created_tmp_files
How many temporary files mysqld has created. This variable was added in MySQL 3.23.28.
•
Created_tmp_tables
The number of in-memory temporary tables created automatically by the server while executing
statements. If Created_tmp_disk_tables is big, you may want to increase the
tmp_table_size value to cause temporary tables to be memory-based instead of disk-based.
•
Delayed_errors
The number of rows written with INSERT DELAYED for which some error occurred (probably
duplicate key).
•
Delayed_insert_threads
The number of INSERT DELAYED handler threads in use.
•
Delayed_writes
The number of INSERT DELAYED rows written.
•
Flush_commands
The number of executed FLUSH statements.
•
Handler_commit
The number of internal COMMIT statements. This variable was added in MySQL 4.0.2.
287
Database Administration
•
Handler_discover
The MySQL server can ask the NDB Cluster storage engine if it knows about a table with a
given name. This is called discovery. Handler_discover indicates the number of time
tables have been discovered. This variable was added in MySQL 4.1.2.
•
Handler_delete
The number of times a row was deleted from a table.
•
Handler_read_first
The number of times the first entry was read from an index. If this is high, it suggests that the
server is doing a lot of full index scans; for example, SELECT col1 FROM foo, assuming
that col1 is indexed.
•
Handler_read_key
The number of requests to read a row based on a key. If this is high, it is a good indication that
your queries and tables are properly indexed.
•
Handler_read_next
The number of requests to read the next row in key order. This is incremented if you are querying an index column with a range constraint or if you are doing an index scan.
•
Handler_read_prev
The number of requests to read the previous row in key order. This read method is mainly used
to optimize ORDER BY ... DESC. This variable was added in MySQL 3.23.6.
•
Handler_read_rnd
The number of requests to read a row based on a fixed position. This is high if you are doing a
lot of queries that require sorting of the result. You probably have a lot of queries that require
MySQL to scan whole tables or you have joins that don't use keys properly.
•
Handler_read_rnd_next
The number of requests to read the next row in the data file. This is high if you are doing a lot of
table scans. Generally this suggests that your tables are not properly indexed or that your queries
are not written to take advantage of the indexes you have.
•
Handler_rollback
The number of internal ROLLBACK statements. This variable was added in MySQL 4.0.2.
•
Handler_update
The number of requests to update a row in a table.
•
Handler_write
The number of requests to insert a row in a table.
•
Innodb_buffer_pool_pages_data
The number of pages containing data (dirty or clean). Added in MySQL 5.0.2.
•
Innodb_buffer_pool_pages_dirty
The number of pages currently dirty. Added in MySQL 5.0.2.
•
Innodb_buffer_pool_pages_flushed
288
Database Administration
The number of buffer pool pages that have been requested to be flushed. Added in MySQL
5.0.2.
•
Innodb_buffer_pool_pages_free
The number of free pages. Added in MySQL 5.0.2.
•
Innodb_buffer_pool_pages_latched
The number of latched pages in InnoDB buffer pool. These are pages currently being read or
written or that can't be flushed or removed for some other reason. Added in MySQL 5.0.2.
•
Innodb_buffer_pool_pages_misc
The number of pages busy because they have been allocated for administrative overhead such as
row locks or the adaptive hash index. This value can also be calculated as Innodb_buffer_pool_pages_total - Innodb_buffer_pool_pages_free - Innodb_buffer_pool_pages_data. Added in MySQL 5.0.2.
•
Innodb_buffer_pool_pages_total
Total size of buffer pool, in pages. Added in MySQL 5.0.2.
•
Innodb_buffer_pool_read_ahead_rnd
The number of “random” read-aheads InnoDB initiated. This happens when a query is to scan a
large portion of a table but in random order. Added in MySQL 5.0.2.
•
Innodb_buffer_pool_read_ahead_seq
The number of sequential read-aheads InnoDB initiated. This happens when InnoDB does a
sequential full table scan. Added in MySQL 5.0.2.
•
Innodb_buffer_pool_read_requests
The number of logical read requests InnoDB has done. Added in MySQL 5.0.2.
•
Innodb_buffer_pool_reads
The number of logical reads that InnoDB could not satisfy from buffer pool and had to do a
single-page read. Added in MySQL 5.0.2.
•
Innodb_buffer_pool_wait_free
Normally, writes to the InnoDB buffer pool happen in the background. However, if it's necessary to read or create a page and no clean pages are available, it's necessary to wait for pages to
be flushed first. This counter counts instances of these waits. If the buffer pool size was set properly, this value should be small. Added in MySQL 5.0.2.
•
Innodb_buffer_pool_write_requests
The number writes done to the InnoDB buffer pool. Added in MySQL 5.0.2.
•
Innodb_data_fsyncs
The number of fsync() operations so far. Added in MySQL 5.0.2.
•
Innodb_data_pending_fsyncs
The current number of pending fsync() operations. Added in MySQL 5.0.2.
•
Innodb_data_pending_reads
289
Database Administration
The current number of pending reads. Added in MySQL 5.0.2.
•
Innodb_data_pending_writes
The current number of pending writes. Added in MySQL 5.0.2.
•
Innodb_data_read
The amount of data read so far, in bytes. Added in MySQL 5.0.2.
•
Innodb_data_reads
The total number of data reads. Added in MySQL 5.0.2.
•
Innodb_data_writes
The total number of data writes. Added in MySQL 5.0.2.
•
Innodb_data_written
The amount of data written so far, in bytes. Added in MySQL 5.0.2.
•
Innodb_dblwr_writes , Innodb_dblwr_pages_written
The number of doublewrite writes that have been performed and the number of pages that have
been written for this purpose. Added in MySQL 5.0.2.
•
Innodb_log_waits
The number of waits we had because log buffer was too small and we had to wait for it to be
flushed before continuing. Added in MySQL 5.0.2.
•
Innodb_log_write_requests
The number of log write requests. Added in MySQL 5.0.2.
•
Innodb_log_writes
The number of physical writes to the log file. Added in MySQL 5.0.2.
•
Innodb_os_log_fsyncs
The number of fsyncs writes done to the log file. Added in MySQL 5.0.2.
•
Innodb_os_log_pending_fsyncs
The number of pending log file fsyncs. Added in MySQL 5.0.2.
•
Innodb_os_log_pending_writes
Pending log file writes. Added in MySQL 5.0.2.
•
Innodb_os_log_written
The number of bytes written to the log file. Added in MySQL 5.0.2.
•
Innodb_page_size
The compiled-in InnoDB page size (default 16KB). Many values are counted in pages; the page
size allows them to be easily converted to bytes. Added in MySQL 5.0.2.
•
Innodb_pages_created
The number of pages created. Added in MySQL 5.0.2.
290
Database Administration
•
Innodb_pages_read
The number of pages read. Added in MySQL 5.0.2.
•
Innodb_pages_written
The number of pages written. Added in MySQL 5.0.2.
•
Innodb_row_lock_current_waits
The number of row locks currently being waited for. Added in MySQL 5.0.3.
•
Innodb_row_lock_time
The total time spent in acquiring row locks, in milliseconds. Added in MySQL 5.0.3.
•
Innodb_row_lock_time_avg
The average time to acquire a row lock, in milliseconds. Added in MySQL 5.0.3.
•
Innodb_row_lock_time_max
The maximum time to acquire a row lock, in milliseconds. Added in MySQL 5.0.3.
•
Innodb_row_lock_waits
The number of times a row lock had to be waited for. Added in MySQL 5.0.3.
•
Innodb_rows_deleted
The number of rows deleted from InnoDB tables. Added in MySQL 5.0.2.
•
Innodb_rows_inserted
The number of rows inserted in InnoDB tables. Added in MySQL 5.0.2.
•
Innodb_rows_read
The number of rows read from InnoDB tables. Added in MySQL 5.0.2.
•
Innodb_rows_updated
The number of rows updated in InnoDB tables. Added in MySQL 5.0.2.
•
Key_blocks_not_flushed
The number of key blocks in the key cache that have changed but haven't yet been flushed to
disk. This variable was added in MySQL 4.1.1. It used to be known as
Not_flushed_key_blocks.
•
Key_blocks_unused
The number of unused blocks in the key cache. You can use this value to determine how much
of the key cache is in use; see the discussion of key_buffer_size in Section 5.3.3, “Server
System Variables”. This variable was added in MySQL 4.1.2. Section 5.3.3, “Server System
Variables”.
•
Key_blocks_used
The number of used blocks in the key cache. This value is a high-water mark that indicates the
maximum number of blocks that have ever been in use at one time.
•
Key_read_requests
The number of requests to read a key block from the cache.
291
Database Administration
•
Key_reads
The number of physical reads of a key block from disk. If Key_reads is big, then your
key_buffer_size value is probably too small. The cache miss rate can be calculated as
Key_reads/Key_read_requests.
•
Key_write_requests
The number of requests to write a key block to the cache.
•
Key_writes
The number of physical writes of a key block to disk.
•
Last_query_cost
The total cost of the last compiled query as computed by the query optimizer. Useful for comparing the cost of different query plans for the same query. The default value of 0 means that no
query has been compiled yet. This variable was added in MySQL 5.0.1, with a default value of 1. In MySQL 5.0.7, the default was changed to 0; also in version 5.0.7, the scope of
Last_query_cost was changed to session rather than a global.
•
Max_used_connections
The maximum number of connections that have been in use simultaneously since the server started.
•
Not_flushed_delayed_rows
The number of rows waiting to be written in INSERT DELAY queues.
•
Not_flushed_key_blocks
The old name for Key_blocks_not_flushed before MySQL 4.1.1.
•
Open_files
The number of files that are open.
•
Open_streams
The number of streams that are open (used mainly for logging).
•
Open_tables
The number of tables that are open.
•
Opened_tables
The number of tables that have been opened. If Opened_tables is big, your table_cache
value is probably too small.
•
Qcache_free_blocks
The number of free memory blocks in query cache.
•
Qcache_free_memory
The amount of free memory for query cache.
•
Qcache_hits
The number of cache hits.
292
Database Administration
•
Qcache_inserts
The number of queries added to the cache.
•
Qcache_lowmem_prunes
The number of queries that were deleted from the cache because of low memory.
•
Qcache_not_cached
The number of non-cached
query_cache_type setting).
•
queries
(not
cachable,
or
not
cached
due
to
the
Qcache_queries_in_cache
The number of queries registered in the cache.
•
Qcache_total_blocks
The total number of blocks in the query cache.
•
Questions
The number of queries that have been sent to the server.
•
Rpl_status
The status of failsafe replication (not yet implemented).
•
Select_full_join
The number of joins that do not use indexes. If this value is not 0, you should carefully check the
indexes of your tables. This variable was added in MySQL 3.23.25.
•
Select_full_range_join
The number of joins that used a range search on a reference table. This variable was added in
MySQL 3.23.25.
•
Select_range
The number of joins that used ranges on the first table. (It's normally not critical even if this is
big.) This variable was added in MySQL 3.23.25.
•
Select_range_check
The number of joins without keys that check for key usage after each row. (If this is not 0, you
should carefully check the indexes of your tables.) This variable was added in MySQL 3.23.25.
•
Select_scan
The number of joins that did a full scan of the first table. This variable was added in MySQL
3.23.25.
•
Slave_open_temp_tables
The number of temporary tables currently open by the slave SQL thread. This variable was added in MySQL 3.23.29.
•
Slave_running
This is ON if this server is a slave that is connected to a master. This variable was added in
MySQL 3.23.16.
293
Database Administration
•
Slave_retried_transactions
Total (since startup) number of times the replication slave SQL thread has retried transactions.
This variable was added in MySQL 4.1.11 and 5.0.4.
•
Slow_launch_threads
The number of threads that have taken more than slow_launch_time seconds to create.
This variable was added in MySQL 3.23.15.
•
Slow_queries
The number of queries that have taken more than long_query_time seconds. See Section 5.10.5, “The Slow Query Log”.
•
Sort_merge_passes
The number of merge passes the sort algorithm has had to do. If this value is large, you should
consider increasing the value of the sort_buffer_size system variable. This variable was
added in MySQL 3.23.28.
•
Sort_range
The number of sorts that were done with ranges. This variable was added in MySQL 3.23.25.
•
Sort_rows
The number of sorted rows. This variable was added in MySQL 3.23.25.
•
Sort_scan
The number of sorts that were done by scanning the table. This variable was added in MySQL
3.23.25.
•
Ssl_xxx
Variables used for SSL connections. These variables were added in MySQL 4.0.0.
•
Table_locks_immediate
The number of times that a table lock was acquired immediately. This variable was added as of
MySQL 3.23.33.
•
Table_locks_waited
The number of times that a table lock could not be acquired immediately and a wait was needed.
If this is high, and you have performance problems, you should first optimize your queries, and
then either split your table or tables or use replication. This variable was added as of MySQL
3.23.33.
•
Threads_cached
The number of threads in the thread cache. This variable was added in MySQL 3.23.17.
•
Threads_connected
The number of currently open connections.
•
Threads_created
The number of threads created to handle connections. If Threads_created is big, you may
want to increase the thread_cache_size value. The cache hit rate can be calculated as
Threads_created/Connections. This variable was added in MySQL 3.23.31.
294
Database Administration
•
Threads_running
The number of threads that are not sleeping.
•
Uptime
The number of seconds the server has been up.
5.4. The MySQL Server Shutdown Process
The server shutdown process can be summarized like this:
1.
The shutdown process is initiated
2.
The server creates a shutdown thread if necessary
3.
The server stops accepting new connections
4.
The server terminates current activity
5.
Storage engines are shut down or closed
6.
The server exits
A more detailed description of the process follows:
1.
The shutdown process is initiated.
Server shutdown can be initiated several ways. For example, a user with the SHUTDOWN privilege can execute a mysqladmin shutdown command. mysqladmin can be used on any
platform supported by MySQL. Other operating system-specific shutdown initiation methods
are possible as well: The server shuts down on Unix when it receives a SIGTERM signal. A
server running as a service on Windows shuts down when the services manager tells it to.
2.
The server creates a shutdown thread if necessary.
Depending on how shutdown was initiated, the server might create a thread to handle the shutdown process. If shutdown was requested by a client, a shutdown thread is created. If shutdown
is the result of receiving a SIGTERM signal, the signal thread might handle shutdown itself, or
it might create a separate thread to do so. If the server tries to create a shutdown thread and
cannot (for example, if memory is exhausted), it issues a diagnostic message that appears in the
error log:
Error: Can't create thread to kill server
3.
The server stops accepting new connections.
To prevent new activity from being initiated during shutdown, the server stops accepting new
client connections. It does this by closing the network connections to which it normally listens
for connections: the TCP/IP port, the Unix socket file, the Windows named pipe, and shared
memory on Windows.
4.
The server terminates current activity.
For each thread that is associated with a client connection, the connection to the client is
broken and the thread is marked as killed. Threads die when they notice that they are so
marked. Threads for idle connections die quickly. Threads that currently are processing queries
check their state periodically and take longer to die. For additional information about thread
295
Database Administration
termination, see Section 13.5.5.3, “KILL Syntax”, in particular for the instructions about killed
REPAIR TABLE or OPTIMIZE TABLE operations on MyISAM tables.
For threads that have an open transaction, the transaction is rolled back. Note that if a thread is
updating a non-transactional table, an operation such as a multiple-row UPDATE or INSERT
may leave the table partially updated, because the operation can terminate before completion.
If the server is a master replication server, threads associated with currently connected slaves
are treated like other client threads. That is, each one is marked as killed and exits when it next
checks its state.
If the server is a slave replication server, the I/O and SQL threads, if active, are stopped before
client threads are marked as killed. The SQL thread is allowed to finish its current statement (to
avoid causing replication problems) then stops. If the SQL thread was in the middle of a transaction at this point, the transaction is rolled back.
5.
Storage engines are shut down or closed.
At this stage, the table cache is flushed and all open tables are closed.
Each storage engine performs any actions necessary for tables that it manages. For example,
MyISAM flushes any pending index writes for a table. InnoDB flushes its buffer pool to disk
(starting from 5.0.5: unless innodb_fast_shutdown is 2), writes the current LSN to the
tablespace, and terminates its own internal threads.
6.
The server exits.
5.5. General Security Issues
This section describes some general security issues to be aware of and what you can do to make
your MySQL installation more secure against attack or misuse. For information specifically about
the access control system that MySQL uses for setting up user accounts and checking database access, see Section 5.6, “The MySQL Access Privilege System”.
5.5.1. General Security Guidelines
Anyone using MySQL on a computer connected to the Internet should read this section to avoid the
most common security mistakes.
In discussing security, we emphasize the necessity of fully protecting the entire server host (not just
the MySQL server) against all types of applicable attacks: eavesdropping, altering, playback, and
denial of service. We do not cover all aspects of availability and fault tolerance here.
MySQL uses security based on Access Control Lists (ACLs) for all connections, queries, and other
operations that users can attempt to perform. There is also some support for SSL-encrypted connections between MySQL clients and servers. Many of the concepts discussed here are not specific to
MySQL at all; the same general ideas apply to almost all applications.
When running MySQL, follow these guidelines whenever possible:
•
Do not ever give anyone (except MySQL root accounts) access to the user table in the
mysql database! This is critical. The encrypted password is the real password in MySQL.
Anyone who knows the password that is listed in the user table and has access to the host listed for the account can easily log in as that user.
•
Learn the MySQL access privilege system. The GRANT and REVOKE statements are used for
controlling access to MySQL. Do not grant any more privileges than necessary. Never grant
privileges to all hosts.
296
Database Administration
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 information about setting a root password. See Section 2.9.3,
“Securing the Initial MySQL Accounts”.
•
Use the SHOW GRANTS statement and check to see who has access to what. Then use the
REVOKE statement to remove those privileges that are not necessary.
•
Do not store any plain-text passwords in your database. If your computer becomes compromised, the intruder can take the full list of passwords and use them. Instead, use MD5(), SHA1(),
or some other one-way hashing function.
•
Do not choose passwords from dictionaries. There are special programs to break them. Even
passwords like “xfish98” are very bad. Much better is “duag98” which contains the same word
“fish” but typed one key to the left on a standard QWERTY keyboard. Another method is to use
“Mhall” which is taken from the first characters of each word in the sentence “Mary had a little
lamb.” This is easy to remember and type, but difficult to guess for someone who does not know
it.
•
Invest in a firewall. This protects you from at least 50% of all types of exploits in any software.
Put MySQL behind the firewall or in a demilitarized zone (DMZ).
Checklist:
•
Try to scan your ports from the Internet using a tool such as nmap. MySQL uses port 3306
by default. This port should not be accessible from untrusted hosts. Another simple way to
check whether or not your MySQL port is open is to try the following command from some
remote machine, where server_host is the host on which your MySQL server runs:
shell> telnet server_host 3306
If you get a connection and some garbage characters, the port is open, and should be closed
on your firewall or router, unless you really have a good reason to keep it open. If telnet
just hangs or the connection is refused, everything is OK; the port is blocked.
•
Do not trust any data entered by users of your applications. They can try to trick your code by
entering special or escaped character sequences in Web forms, URLs, or whatever application
you have built. Be sure that your application remains secure if a user enters something like “;
DROP DATABASE mysql;”. This is an extreme example, but large security leaks and data
loss might occur as a result of hackers using similar techniques, if you do not prepare for them.
A common mistake is to protect only string data values. Remember to check numeric data as
well. If an application generates a query such as SELECT * FROM table WHERE ID=234
when a user enters the value 234, the user can enter the value 234 OR 1=1 to cause the application to generate the query SELECT * FROM table WHERE ID=234 OR 1=1. As a
result, the server retrieves every record in the table. This exposes every record and causes excessive server load. The simplest way to protect from this type of attack is to use apostrophes
around the numeric constants: SELECT * FROM table WHERE ID='234'. If the user
enters extra information, it all becomes part of the string. In numeric context, MySQL automatically converts this string to a number and strips any trailing non-numeric characters from it.
Sometimes people think that if a database contains only publicly available data, it need not be
protected. This is incorrect. Even if it is allowable to display any record in the database, you
should still protect against denial of service attacks (for example, those that are based on the
technique in the preceding paragraph that causes the server to waste resources). Otherwise, your
server becomes unresponsive to legitimate users.
Checklist:
297
Database Administration
•
•
Try to enter ‘'’ and ‘"’ in all your Web forms. If you get any kind of MySQL error, investigate the problem right away.
•
Try to modify any dynamic URLs by adding %22 (‘"’), %23 (‘#’), and %27 (‘'’) in the
URL.
•
Try to modify data types in dynamic URLs from numeric ones to character ones containing
characters from previous examples. Your application should be safe against this and similar
attacks.
•
Try to enter characters, spaces, and special symbols rather than numbers in numeric fields.
Your application should remove them before passing them to MySQL or else generate an error. Passing unchecked values to MySQL is very dangerous!
•
Check data sizes before passing them to MySQL.
•
Consider having your application connect to the database using a different username than the
one you use for administrative purposes. Do not give your applications any access privileges
they do not need.
Many application programming interfaces provide a means of escaping special characters in data
values. Properly used, this prevents application users from entering values that cause the application to generate statements that have a different effect than you intend:
•
MySQL C API: Use the mysql_real_escape_string() API call.
•
MySQL++: Use the escape and quote modifiers for query streams.
•
PHP: Use the mysql_escape_string() function, which is based on the function of the
same name in the MySQL C API. Prior to PHP 4.0.3, use addslashes() instead.
•
Perl DBI: Use the quote() method or use placeholders.
•
Java JDBC: Use a PreparedStatement object and placeholders.
Other programming interfaces might have similar capabilities.
•
Do not transmit plain (unencrypted) data over the Internet. This information is accessible to
everyone who has the time and ability to intercept it and use it for their own purposes. Instead,
use an encrypted protocol such as SSL or SSH. MySQL supports internal SSL connections as of
Version 4.0.0. SSH port-forwarding can be used to create an encrypted (and compressed) tunnel
for the communication.
•
Learn to use the tcpdump and strings utilities. For most cases, you can check whether
MySQL data streams are unencrypted by issuing a command like the following:
shell> tcpdump -l -i eth0 -w - src or dst port 3306 | strings
(This works under Linux and should work with small modifications under other systems.) Warning: If you do not see plaintext data, this doesn't always mean that the information actually is encrypted. If you need high security, you should consult with a security expert.
5.5.2. Making MySQL Secure Against Attackers
When you connect to a MySQL server, you should use a password. The password is not transmitted
in clear text over the connection. Password handling during the client connection sequence was upgraded in MySQL 4.1.1 to be very secure. If you are using an older version of MySQL, or are still
using pre-4.1.1-style passwords, the encryption algorithm is less strong and with some effort a clever attacker who can sniff the traffic between the client and the server can crack the password. (See
Section 5.6.9, “Password Hashing in MySQL 4.1” for a discussion of the different password hand298
Database Administration
ling methods.) If the connection between the client and the server goes through an untrusted network, you should use an SSH tunnel to encrypt the communication.
All other information is transferred as text that can be read by anyone who is able to watch the connection. If you are concerned about this, you can use the compressed protocol (in MySQL 3.22 and
above) to make traffic much more difficult to decipher. To make the connection even more secure,
you should use SSH to get an encrypted TCP/IP connection between a MySQL server and a MySQL
client. You can find an Open Source SSH client at http://www.openssh.org/, and a commercial SSH
client at http://www.ssh.com/.
If you are using MySQL 4.0 or newer, you can also use internal OpenSSL support. See Section 5.7.7, “Using Secure Connections”.
To make a MySQL system secure, you should strongly consider the following suggestions:
•
Use passwords for all MySQL users. A client program does not necessarily know the identity of
the person running it. It is common for client/server applications that the user can specify any
username to the client program. For example, anyone can use the mysql program to connect as
any other person simply by invoking it as mysql -u other_user db_name if other_user has no password. If all users have a password, connecting using another user's account becomes much more difficult.
To change the password for a user, use the SET PASSWORD statement. It is also possible to update the user table in the mysql database directly. For example, to change the password of all
MySQL accounts that have a username of root, do this:
shell>
mysql>
->
mysql>
•
mysql -u root
UPDATE mysql.user SET Password=PASSWORD('newpwd')
WHERE User='root';
FLUSH PRIVILEGES;
Don't run the MySQL server as the Unix root user. This is very dangerous, because any user
with the FILE privilege is able to create files as root (for example, ~root/.bashrc). To
prevent this, mysqld refuses to run as root unless that is specified explicitly using a -user=root option.
mysqld can be run as an ordinary unprivileged user instead. You can also create a separate
Unix account named mysql to make everything even more secure. Use the account only for administering MySQL. To start mysqld as another Unix user, add a user option that specifies
the username to the [mysqld] group of the /etc/my.cnf option file or the my.cnf option
file in the server's data directory. For example:
[mysqld]
user=mysql
This causes the server to start as the designated user whether you start it manually or by using
mysqld_safe or mysql.server. For more details, see Section A.3.2, “How to Run
MySQL as a Normal User”.
Running mysqld as a Unix user other than root does not mean that you need to change the
root username in the user table. Usernames for MySQL accounts have nothing to do with
usernames for Unix accounts.
•
Don't allow the use of symlinks to tables. (This can be disabled with the -skip-symbolic-links option.) This is especially important if you run mysqld as root,
because anyone that has write access to the server's data directory then could delete any file in
the system! See Section 7.6.1.2, “Using Symbolic Links for Tables on Unix”.
•
Make sure that the only Unix user with read or write privileges in the database directories is the
user that mysqld runs as.
•
Don't grant the PROCESS or SUPER privilege to non-administrative users. The output of
299
Database Administration
mysqladmin processlist shows the text of the currently executing queries, so any user
who is allowed to execute that command might be able to see if another user issues an UPDATE
user SET password=PASSWORD('not_secure') query.
mysqld reserves an extra connection for users who have the SUPER privilege (PROCESS before MySQL 4.0.2), so that a MySQL root user can log in and check server activity even if all
normal connections are in use.
The SUPER privilege can be used to terminate client connections, change server operation by
changing the value of system variables, and control replication servers.
•
Don't grant the FILE privilege to non-administrative users. Any user that has this privilege can
write a file anywhere in the filesystem with the privileges of the mysqld daemon! To make this
a bit safer, files generated with SELECT ... INTO OUTFILE do not overwrite existing files
and are writable by everyone.
The FILE privilege may also be used to read any file that is world-readable or accessible to the
Unix user that the server runs as. With this privilege, you can read any file into a database table.
This could be abused, for example, by using LOAD DATA to load /etc/passwd into a table,
which then can be displayed with SELECT.
•
If you don't trust your DNS, you should use IP numbers rather than hostnames in the grant
tables. In any case, you should be very careful about creating grant table entries using hostname
values that contain wildcards!
•
If you want to restrict the number of connections allowed to a single account, you can do so by
setting the max_user_connections variable in mysqld. The GRANT statement also supports resource control options for limiting the extent of server use allowed to an account.
5.5.3. Startup Options for mysqld Concerning Security
The following mysqld options affect security:
•
--allow-suspicious-udfs
This option controls whether user-defined functions that have only an xxx symbol for the main
function can be loaded. By default, the option is off and only UDFs that have at least one auxiliary symbol can be loaded. This prevents attempts at loading functions from shared object files
other than those containing legitimate UDFs. This option was added in MySQL 4.0.24, 4.1.10a,
and 5.0.3. See Section 25.2.3.6, “User-defined Function Security Precautions”.
•
--local-infile[={0|1}]
If you start the server with --local-infile=0, clients cannot use LOCAL in LOAD DATA
statements. See Section 5.5.4, “Security Issues with LOAD DATA LOCAL”.
•
--old-passwords
Force the server to generate short (pre-4.1) password hashes for new passwords. This is useful
for compatibility when the server must support older client programs. See Section 5.6.9,
“Password Hashing in MySQL 4.1”.
•
--safe-show-database
With this option, the SHOW DATABASES statement displays the names of only those databases
for which the user has some kind of privilege. As of MySQL 4.0.2, this option is deprecated and
doesn't do anything (it is enabled by default), because there is a SHOW DATABASES privilege
that can be used to control access to database names on a per-account basis. See Section 13.5.1.3, “GRANT and REVOKE Syntax”.
•
--safe-user-create
300
Database Administration
If this is enabled, a user cannot create new users with the GRANT statement unless the user has
the INSERT privilege for the mysql.user table. If you want a user to have the ability to create new users with those privileges that the user has right to grant, you should grant the user the
following privilege:
mysql> GRANT INSERT(user) ON mysql.user TO 'user_name'@'host_name';
This ensures that the user can't change any privilege columns directly, but has to use the GRANT
statement to give privileges to other users.
•
--secure-auth
Disallow authentication for accounts that have old (pre-4.1) passwords. This option is available
as of MySQL 4.1.1.
•
--skip-grant-tables
This option causes the server not to use the privilege system at all. This gives everyone full access to all databases! (You can tell a running server to start using the grant tables again by executing a mysqladmin flush-privileges or mysqladmin reload command, or by
issuing a FLUSH PRIVILEGES statement.)
•
--skip-name-resolve
Hostnames are not resolved. All Host column values in the grant tables must be IP numbers or
localhost.
•
--skip-networking
Don't allow TCP/IP connections over the network. All connections to mysqld must be made
via Unix socket files. This option is unsuitable when using a MySQL version prior to 3.23.27
with the MIT-pthreads package, because Unix socket files were not supported by MIT-pthreads
at that time.
•
--skip-show-database
With this option, the SHOW DATABASES statement is allowed only to users who have the
SHOW DATABASES privilege, and the statement displays all database names. Without this option, SHOW DATABASES is allowed to all users, but displays each database name only if the
user has the SHOW DATABASES privilege or some privilege for the database.
5.5.4. Security Issues with LOAD DATA LOCAL
The LOAD DATA statement can load a file that is located on the server host, or it can load a file that
is located on the client host when the LOCAL keyword is specified.
There are two potential security issues with supporting the LOCAL version of LOAD DATA statements:
•
The transfer of the file from the client host to the server host is initiated by the MySQL server.
In theory, a patched server could be built that would tell the client program to transfer a file of
the server's choosing rather than the file named by the client in the LOAD DATA statement. Such
a server could access any file on the client host to which the client user has read access.
•
In a Web environment where the clients are connecting from a Web server, a user could use
LOAD DATA LOCAL to read any files that the Web server process has read access to (assuming
that a user could run any command against the SQL server). In this environment, the client with
respect to the MySQL server actually is the Web server, not the program being run by the user
connecting to the Web server.
301
Database Administration
To deal with these problems, we changed how LOAD DATA LOCAL is handled as of MySQL
3.23.49 and MySQL 4.0.2 (4.0.13 on Windows):
•
By default, all MySQL clients and libraries in binary distributions are compiled with the -enable-local-infile option, to be compatible with MySQL 3.23.48 and before.
•
If you build MySQL from source but don't use the --enable-local-infile option to
configure, LOAD DATA LOCAL cannot be used by any client unless it is written explicitly
to invoke mysql_options(... MYSQL_OPT_LOCAL_INFILE, 0). See Section 23.2.3.48, “mysql_options()”.
•
You can disable all LOAD DATA LOCAL commands from the server side by starting mysqld
with the --local-infile=0 option.
•
For the mysql command-line client, LOAD DATA LOCAL can be enabled by specifying the -local-infile[=1] option, or disabled with the --local-infile=0 option. Similarly,
for mysqlimport, the --local or -L option enables local data file loading. In any case,
successful use of a local loading operation requires that the server is enabled to allow it.
•
If you use LOAD DATA LOCAL in Perl scripts or other programs that read the [client]
group from option files, you can add the local-infile=1 option to that group. However, to
keep this from causing problems for programs that do not understand local-infile, specify
it using the loose- prefix:
[client]
loose-local-infile=1
The loose- prefix can be used as of MySQL 4.0.2.
•
If LOAD DATA LOCAL INFILE is disabled, either in the server or the client, a client that attempts to issue such a statement receives the following error message:
ERROR 1148: The used command is not allowed with this MySQL version
5.6. The MySQL Access Privilege System
MySQL has an advanced but non-standard security and privilege system. This section describes how
it works.
5.6.1. What the Privilege System Does
The primary function of the MySQL privilege system is to authenticate a user connecting from a
given host, and to associate that user with privileges on a database such as SELECT, INSERT, UPDATE, and DELETE.
Additional functionality includes the ability to have anonymous users and to grant privileges for
MySQL-specific functions such as LOAD DATA INFILE and administrative operations.
5.6.2. How the Privilege System Works
The MySQL privilege system ensures that all users may perform only the operations allowed to
them. As a user, when you connect to a MySQL server, your identity is determined by the host from
which you connect and the username you specify. When you issue requests after connecting, the system grants privileges according to your identity and what you want to do.
MySQL considers both your hostname and username in identifying you because there is little reason
to assume that a given username belongs to the same person everywhere on the Internet. For example, the user joe who connects from office.com need not be the same person as the user
302
Database Administration
joe who connects from elsewhere.com. MySQL handles this by allowing you to distinguish
users on different hosts that happen to have the same name: You can grant one set of privileges for
connections by joe from office.com, and a different set of privileges for connections by joe
from elsewhere.com.
MySQL access control involves two stages:
•
Stage 1: The server checks whether it should allow you to connect.
•
Stage 2: Assuming that you can connect, the server checks each statement you issue to see
whether you have sufficient privileges to perform it. For example, if you try to select rows from
a table in a database or drop a table from the database, the server verifies that you have the SELECT privilege for the table or the DROP privilege for the database.
If your privileges are changed (either by yourself or someone else) while you are connected, those
changes do not necessarily take effect immediately for the next statement you issue. See Section 5.6.7, “When Privilege Changes Take Effect” for details.
The server stores privilege information in the grant tables of the mysql database (that is, in the
database named mysql). The MySQL server reads the contents of these tables into memory when it
starts and re-reads them under the circumstances indicated in Section 5.6.7, “When Privilege
Changes Take Effect”. Access-control decisions are based on the in-memory copies of the grant
tables.
Normally, you manipulate the contents of the grant tables indirectly by using the GRANT and REVOKE statements to set up accounts and control the privileges available to each one. See Section 13.5.1.3, “GRANT and REVOKE Syntax”. The discussion here describes the underlying structure
of the grant tables and how the server uses their contents when interacting with clients.
The server uses the user, db, and host tables in the mysql database at both stages of access control. The columns in these grant tables are shown here:
Table Name
user
db
host
Scope columns
Host
Host
Host
User
Db
Db
Password
User
Select_priv
Select_priv
Select_priv
Insert_priv
Insert_priv
Insert_priv
Update_priv
Update_priv
Update_priv
Delete_priv
Delete_priv
Delete_priv
Index_priv
Index_priv
Index_priv
Alter_priv
Alter_priv
Alter_priv
Create_priv
Create_priv
Create_priv
Drop_priv
Drop_priv
Drop_priv
Grant_priv
Grant_priv
Grant_priv
Privilege columns
Create_view_priv Create_view_priv Create_view_priv
Show_view_priv
Show_view_priv
Show_view_priv
CreCreate_routine_priv ate_routine_priv
AlAlter_routine_priv ter_routine_priv
References_priv
Reload_priv
Shutdown_priv
303
References_priv
References_priv
Database Administration
Process_priv
File_priv
Show_db_priv
Super_priv
CreCreCreate_tmp_table_pr ate_tmp_table_pr ate_tmp_table_pr
iv
iv
iv
Lock_tables_priv Lock_tables_priv Lock_tables_priv
Execute_priv
Repl_slave_priv
Repl_client_priv
Security columns
ssl_type
ssl_cipher
x509_issuer
x509_subject
Resource
columns
control max_questions
max_updates
max_connections
max_user_connect
ions
The ssl_type, ssl_cipher, x509_issuer, and x509_subject columns were added in
MySQL 4.0.0.
The
Create_tmp_table_priv,
Execute_priv,
Lock_tables_priv,
Repl_client_priv,
Repl_slave_priv,
Show_db_priv,
Super_priv,
max_questions, max_updates, and max_connections columns were added in MySQL
4.0.2. Execute_priv is not operational until MySQL 5.0.3, however.
The Create_view_priv and Show_view_priv columns were added in MySQL 5.0.1.
The Create_routine_priv, Alter_routine_priv, and max_user_connections
columns were added in MySQL 5.0.3.
During the second stage of access control, the server performs request verification to make sure that
each client has sufficient privileges for each request that it issues. In addition to the user, db, and
host grant tables, the server may also consult the tables_priv and columns_priv tables for
requests that involve tables. The tables_priv and columns_priv tables provide finer privilege control at the table and column levels. They have the following columns:
Table Name
tables_priv
columns_priv
Scope columns
Host
Host
Db
Db
User
User
Table_name
Table_name
Column_name
Privilege columns
Table_priv
Column_priv
Column_priv
Other columns
Timestamp
Grantor
304
Timestamp
Database Administration
The Timestamp and Grantor columns currently are unused and are discussed no further here.
For verification of requests that involve stored routines, the server may consult the procs_priv
table. This table has the following columns:
Table Name
procs_priv
Scope columns
Host
Db
User
Routine_name
Routine_type
Privilege columns
Proc_priv
Other columns
Timestamp
Grantor
The procs_priv table exists as of MySQL 5.0.3. The Routine_type column was added in
MySQL 5.0.6. It is an ENUM column with values of 'FUNCTION' or 'PROCEDURE' to indicate
the type of routine the row refers to. This column allows privileges to be granted separately for a
function and a procedure with the same name.
The Timestamp and Grantor columns currently are unused and are discussed no further here.
Each grant table contains scope columns and privilege columns:
•
Scope columns determine the scope of each entry (row) in the tables; that is, the context in
which the row applies. For example, a user table row with Host and User values of
'thomas.loc.gov' and 'bob' would be used for authenticating connections made to the
server from the host thomas.loc.gov by a client that specifies a username of bob. Similarly, a db table row with Host, User, and Db column values of 'thomas.loc.gov',
'bob' and 'reports' would be used when bob connects from the host thomas.loc.gov
to access the reports database. The tables_priv and columns_priv tables contain
scope columns indicating tables or table/column combinations to which each row applies. The
procs_priv scope columns indicate the store routine to which each row applies.
•
Privilege columns indicate which privileges are granted by a table row; that is, what operations
can be performed. The server combines the information in the various grant tables to form a
complete description of a user's privileges. The rules used to do this are described in Section 5.6.6, “Access Control, Stage 2: Request Verification”.
Scope columns contain strings. They are declared as shown here; the default value for each is the
empty string:
Column Name
Type
Host
CHAR(60)
User
CHAR(16)
Password
CHAR(16)
Db
CHAR(64)
Table_name
CHAR(64)
Column_name
CHAR(64)
Routine_name
CHAR(64)
Before MySQL 3.23, the Db column is CHAR(32) in some tables and CHAR(60) in others.
305
Database Administration
For access-checking purposes, comparisons of Host values are case-insensitive. User,
Password, Db, and Table_name values are case sensitive. Column_name values are case insensitive in MySQL 3.22.12 or later.
In the user, db, and host tables, each privilege is listed in a separate column that is declared as
ENUM('N','Y') DEFAULT 'N'. In other words, each privilege can be disabled or enabled,
with the default being disabled.
In the tables_priv, columns_priv, and procs_priv tables, the privilege columns are declared as SET columns. Values in these columns can contain any combination of the privileges controlled by the table:
Table Name
Column Name Possible Set Elements
tables_priv Table_priv
'Select', 'Insert', 'Update', 'Delete',
'Create', 'Drop', 'Grant', 'References',
'Index', 'Alter'
tables_priv Column_priv 'Select', 'Insert', 'Update', 'References'
columns_pri Column_priv 'Select', 'Insert', 'Update', 'References'
v
procs_priv
Proc_priv
'Execute', 'Alter Routine', 'Grant'
Briefly, the server uses the grant tables as follows:
•
The user table scope columns determine whether to reject or allow incoming connections. For
allowed connections, any privileges granted in the user table indicate the user's global
(superuser) privileges. These privileges apply to all databases on the server.
•
The db table scope columns determine which users can access which databases from which
hosts. The privilege columns determine which operations are allowed. A privilege granted at the
database level applies to the database and to all its tables.
•
The host table is used in conjunction with the db table when you want a given db table row to
apply to several hosts. For example, if you want a user to be able to use a database from several
hosts in your network, leave the Host value empty in the user's db table row, then populate the
host table with a row for each of those hosts. This mechanism is described more detail in Section 5.6.6, “Access Control, Stage 2: Request Verification”.
Note: The host table is not affected by the GRANT and REVOKE statements. Most MySQL installations need not use this table at all.
•
The tables_priv and columns_priv tables are similar to the db table, but are more finegrained: They apply at the table and column levels rather than at the database level. A privilege
granted at the table level applies to the table and to all its columns. A privilege granted at the
column level applies only to a specific column.
•
The procs_priv table applies to stored routines. A privilege granted at the routine level applies only to a single routine.
Administrative privileges (such as RELOAD or SHUTDOWN) are specified only in the user table.
This is because administrative operations are operations on the server itself and are not database-specific, so there is no reason to list these privileges in the other grant tables. In fact, to determine
whether you can perform an administrative operation, the server need consult only the user table.
The FILE privilege also is specified only in the user table. It is not an administrative privilege as
such, but your ability to read or write files on the server host is independent of the database you are
accessing.
The mysqld server reads the contents of the grant tables into memory when it starts. You can tell it
306
Database Administration
to re-read the tables by issuing a FLUSH PRIVILEGES statement or executing a mysqladmin
flush-privileges or mysqladmin reload command. Changes to the grant tables take effect as indicated in Section 5.6.7, “When Privilege Changes Take Effect”.
When you modify the contents of the grant tables, it is a good idea to make sure that your changes
set up privileges the way you want. To check the privileges for a given account, use the SHOW
GRANTS statement. For example, to determine the privileges that are granted to an account with
Host and User values of pc84.example.com and bob, issue this statement:
mysql> SHOW GRANTS FOR 'bob'@'pc84.example.com';
A useful diagnostic tool is the mysqlaccess script, which Yves Carlier has provided for the
MySQL distribution. Invoke mysqlaccess with the --help option to find out how it works.
Note that mysqlaccess checks access using only the user, db, and host tables. It does not
check table, column, or routine privileges specified in the tables_priv, columns_priv, or
procs_priv tables.
For additional help in diagnosing privilege-related problems, see Section 5.6.8, “Causes of Access
denied Errors”. For general advice on security issues, see Section 5.5, “General Security Issues”.
5.6.3. Privileges Provided by MySQL
Information about account privileges is stored in the user, db, host, tables_priv,
columns_priv, and procs_priv tables in the mysql database. The MySQL server reads the
contents of these tables into memory when it starts and re-reads them under the circumstances indicated in Section 5.6.7, “When Privilege Changes Take Effect”. Access-control decisions are based on
the in-memory copies of the grant tables.
The names used in the GRANT and REVOKE statements to refer to privileges are shown in the following table, along with the column name associated with each privilege in the grant tables and the
context in which the privilege applies. Further information about the meaning of each privilege may
be found at Section 13.5.1.3, “GRANT and REVOKE Syntax”.
Privilege
Column
Context
CREATE
Create_priv
databases, tables, or indexes
DROP
Drop_priv
databases or tables
GRANT OPTION
Grant_priv
databases,
routines
REFERENCES
References_priv
databases or tables
ALTER
Alter_priv
tables
DELETE
Delete_priv
tables
INDEX
Index_priv
tables
INSERT
Insert_priv
tables
SELECT
Select_priv
tables
UPDATE
Update_priv
tables
CREATE VIEW
Create_view_priv
views
SHOW VIEW
Show_view_priv
views
ALTER ROUTINE
Alter_routine_priv
stored routines
CREATE ROUTINE
Create_routine_priv
stored routines
EXECUTE
Execute_priv
stored routines
FILE
File_priv
file access on server host
CREATE
TABLES
tables,
TEMPORARY Create_tmp_table_priv server administration
LOCK TABLES
Lock_tables_priv
server administration
CREATE USER
Create_user_priv
server administration
307
or
stored
Database Administration
PROCESS
Process_priv
server administration
RELOAD
Reload_priv
server administration
REPLICATION CLIENT
Repl_client_priv
server administration
REPLICATION SLAVE
Repl_slave_priv
server administration
SHOW DATABASES
Show_db_priv
server administration
SHUTDOWN
Shutdown_priv
server administration
SUPER
Super_priv
server administration
The CREATE TEMPORARY TABLES, EXECUTE, LOCK TABLES, REPLICATION CLIENT,
REPLICATION SLAVE, SHOW DATABASES, and SUPER privileges were added in MySQL
4.0.2. (EXECUTE is not operational until MySQL 5.0.3.) CREATE VIEW and SHOW VIEW were
added in MySQL 5.0.1. CREATE USER, CREATE ROUTINE, and ALTER ROUTINE were added
in MySQL 5.0.3. To use these privileges when upgrading from an earlier version of MySQL that
does not have them, you must upgrade your grant tables. See Section 2.10.8, “Upgrading the Grant
Tables”.
To create or alter stored routines if binary logging is enabled, you may also need the SUPER privilege, as described in Section 18.4, “Binary Logging of Stored Routines and Triggers”.
The CREATE and DROP privileges allow you to create new databases and tables, or to drop
(remove) existing databases and tables. If you grant the DROP privilege for the mysql database to a
user, that user can drop the database in which the MySQL access privileges are stored!
The SELECT, INSERT, UPDATE, and DELETE privileges allow you to perform operations on rows
in existing tables in a database.
SELECT statements require the SELECT privilege only if they actually retrieve rows from a table.
Some SELECT statements do not access tables and can be executed without permission for any
database. For example, you can use the mysql client as a simple calculator to evaluate expressions
that make no reference to tables:
mysql> SELECT 1+1;
mysql> SELECT PI()*2;
The INDEX privilege allows you to create or drop (remove) indexes. INDEX applies to existing
tables. If you have the CREATE privilege for a table, you can include index definitions in the CREATE TABLE statement.
The ALTER privilege allows you to use ALTER TABLE to change the structure of or rename tables.
The CREATE ROUTINE privilege is needed for creating stored routines (functions and procedures).
ALTER ROUTINE privilege is needed for altering or dropping stored routines, and EXECUTE is
needed for executing stored routines.
The GRANT privilege allows you to give to other users those privileges that you yourself possess. It
can be used for databases, tables, and stored routines.
The FILE privilege gives you permission to read and write files on the server host using the LOAD
DATA INFILE and SELECT ... INTO OUTFILE statements. A user who has the FILE privilege can read any file on the server host that is either world-readable or readable by the MySQL
server. (This implies the user can read any file in any database directory, because the server can access any of those files.) The FILE privilege also allows the user to create new files in any directory
where the MySQL server has write access. Existing files cannot be overwritten.
The remaining privileges are used for administrative operations. Many of them can be performed by
using the mysqladmin program or by issuing SQL statements. The following table shows which
mysqladmin commands each administrative privilege allows you to execute:
Privilege
Commands Permitted to Privilege Holders
308
Database Administration
RELOAD
flush-hosts, flush-logs, flush-privileges, flush-status,
flush-tables, flush-threads, refresh, reload
SHUTDOWN
shutdown
PROCESS
processlist
SUPER
kill
The reload command tells the server to re-read the grant tables into memory. flushprivileges is a synonym for reload. The refresh command closes and reopens the log files
and flushes all tables. The other flush-xxx commands perform functions similar to refresh,
but are more specific and may be preferable in some instances. For example, if you want to flush
just the log files, flush-logs is a better choice than refresh.
The shutdown command shuts down the server. This command can be issued only from mysqladmin. There is no corresponding SQL statement.
The processlist command displays information about the threads executing within the server
(that is, about the statements being executed by clients associated with other accounts). The kill
command terminates server threads. You can always display or kill your own threads, but you need
the PROCESS privilege to display threads initiated by other users and the SUPER privilege to kill
them. See Section 13.5.5.3, “KILL Syntax”. Prior to MySQL 4.0.2 when SUPER was introduced,
the PROCESS privilege controls the ability to both see and terminate threads for other clients.
The CREATE TEMPORARY TABLES privilege allows the use of the keyword TEMPORARY in
CREATE TABLE statements.
The LOCK TABLES privilege allows the use of explicit LOCK TABLES statements to lock tables
for which you have the SELECT privilege. This includes the use of write locks, which prevents anyone else from reading the locked table.
The REPLICATION CLIENT privilege allows the use of SHOW MASTER STATUS and SHOW
SLAVE STATUS.
The REPLICATION SLAVE privilege should be granted to accounts that are used by slave servers
to connect to the current server as their master. Without this privilege, the slave cannot request updates that have been made to databases on the master server.
The SHOW DATABASES privilege allows the account to see database names by issuing the SHOW
DATABASE statement. Accounts that do not have this privilege see only databases for which they
have some privileges, and cannot use the statement at all if the server was started with the -skip-show-database option.
It is a good idea in general to grant to an account only those privileges that it needs. You should exercise particular caution in granting the FILE and administrative privileges:
•
The FILE privilege can be abused to read into a database table any files that the MySQL server
can read on the server host. This includes all world-readable files and files in the server's data
directory. The table can then be accessed using SELECT to transfer its contents to the client
host.
•
The GRANT privilege allows users to give their privileges to other users. Two users with different privileges and with the GRANT privilege are able to combine privileges.
•
The ALTER privilege may be used to subvert the privilege system by renaming tables.
•
The SHUTDOWN privilege can be abused to deny service to other users entirely by terminating
the server.
•
The PROCESS privilege can be used to view the plain text of currently executing queries, including queries that set or change passwords.
309
Database Administration
•
The SUPER privilege can be used to terminate other clients or change how the server operates.
•
Privileges granted for the mysql database itself can be used to change passwords and other access privilege information. Passwords are stored encrypted, so a malicious user cannot simply
read them to know the plain text password. However, a user with write access to the user table
Password column can change an account's password, and then connect to the MySQL server
using that account.
There are some things that you cannot do with the MySQL privilege system:
•
You cannot explicitly specify that a given user should be denied access. That is, you cannot explicitly match a user and then refuse the connection.
•
You cannot specify that a user has privileges to create or drop tables in a database but not to create or drop the database itself.
5.6.4. Connecting to the MySQL Server
MySQL client programs generally expect you to specify connection parameters when you want to
access a MySQL server:
•
The name of the host where the MySQL server is running
•
Your username
•
Your password
For example, the mysql client can be started as follows from a command-line prompt (indicated
here by shell>):
shell> mysql -h host_name -u user_name -pyour_pass
Alternate forms of the -h, -u, and -p options are --host=host_name, --user=user_name,
and --password=your_pass. Note that there is no space between -p or --password= and
the password following it.
If you use a -p or --password option but do not specify the password value, the client program
prompts you to enter the password. The password is not displayed as you enter it. This is more secure than giving the password on the command line. Any user on your system may be able to see a
password specified on the command line by executing a command such as ps auxww. See Section 5.7.6, “Keeping Your Password Secure”.
MySQL client programs use default values for any connection parameter option that you do not specify:
•
The default hostname is localhost.
•
The default username is ODBC on Windows and your Unix login name on Unix.
•
No password is supplied if -p is missing.
Thus, for a Unix user with a login name of joe, all of the following commands are equivalent:
shell> mysql -h localhost -u joe
shell> mysql -h localhost
shell> mysql -u joe
310
Database Administration
shell> mysql
Other MySQL clients behave similarly.
You can specify different default values to be used when you make a connection so that you need
not enter them on the command line each time you invoke a client program. This can be done in a
couple of ways:
•
You can specify connection parameters in the [client] section of an option file. The relevant
section of the file might look like this:
[client]
host=host_name
user=user_name
password=your_pass
Option files are discussed further in Section 4.3.2, “Using Option Files”.
•
You can specify some connection parameters using environment variables. The host can be specified for mysql using MYSQL_HOST. The MySQL username can be specified using USER
(this is for Windows and NetWare only). The password can be specified using MYSQL_PWD, although this is insecure; see Section 5.7.6, “Keeping Your Password Secure”. For a list of variables, see Appendix G, Environment Variables.
5.6.5. Access Control, Stage 1: Connection Verification
When you attempt to connect to a MySQL server, the server accepts or rejects the connection based
on your identity and whether you can verify your identity by supplying the correct password. If not,
the server denies access to you completely. Otherwise, the server accepts the connection, then enters
Stage 2 and waits for requests.
Your identity is based on two pieces of information:
•
The client host from which you connect
•
Your MySQL username
Identity checking is performed using the three user table scope columns (Host, User, and
Password). The server accepts the connection only if the Host and User columns in some user
table record match the client hostname and username, and the client supplies the password specified
in that record.
Host values in the user table may be specified as follows:
•
A Host value may be a hostname or an IP number, or 'localhost' to indicate the local
host.
•
You can use the wildcard characters ‘%’ and ‘_’ in Host column values. These have the same
meaning as for pattern-matching operations performed with the LIKE operator. For example, a
Host value of '%' matches any hostname, whereas a value of '%.mysql.com' matches any
host in the mysql.com domain.
•
As of MySQL 3.23, for Host values specified as IP numbers, you can specify a netmask indicating how many address bits to use for the network number. For example:
mysql> GRANT ALL PRIVILEGES ON db.*
-> TO [email protected]'192.58.197.0/255.255.255.0';
311
Database Administration
This allows david to connect from any client host having an IP number client_ip for
which the following condition is true:
client_ip & netmask = host_ip
That is, for the GRANT statement just shown:
client_ip & 255.255.255.0 = 192.58.197.0
IP numbers that satisfy this condition and can connect to the MySQL server are those that lie in
the range from 192.58.197.0 to 192.58.197.255.
•
Note: The netmask can only be used to tell the server to use 8, 16, 24, or 32 bits of the address,
for example:
192.0.0.0/255.0.0.0 (anything on the 192 class A network)
192.168.0.0/255.255.0.0 (anything on the 192.168 class B network)
192.168.1.0/255.255.255.0 (anything on the 192.168.1 class C network)
192.168.1.1 (only this specific IP)
The following netmask (28 bits) will not work:
192.168.0.1/255.255.255.240
•
A blank Host value in a db table record means that its privileges should be combined with
those in the row in the host table that matches the client hostname. The privileges are combined using an AND (intersection) operation, not OR (union). You can find more information
about the host table in Section 5.6.6, “Access Control, Stage 2: Request Verification”.
A blank Host value in the other grant tables is the same as '%'.
Because you can use IP wildcard values in the Host column (for example, '144.155.166.%' to
match every host on a subnet), someone could try to exploit this capability by naming a host
144.155.166.somewhere.com. To foil such attempts, MySQL disallows matching on hostnames that start with digits and a dot. Thus, if you have a host named something like
1.2.foo.com, its name never matches the Host column of the grant tables. An IP wildcard value
can match only IP numbers, not hostnames.
In the User column, wildcard characters are not allowed, but you can specify a blank value, which
matches any name. If the user table row that matches an incoming connection has a blank username, the user is considered to be an anonymous user with no name, not a user with the name that
the client actually specified. This means that a blank username is used for all further access checking for the duration of the connection (that is, during Stage 2).
The Password column can be blank. This is not a wildcard and does not mean that any password
matches. It means that the user must connect without specifying a password.
Non-blank Password values in the user table represent encrypted passwords. MySQL does not
store passwords in plaintext form for anyone to see. Rather, the password supplied by a user who is
attempting to connect is encrypted (using the PASSWORD() function). The encrypted password
then is used during the connection process when checking whether the password is correct. (This is
done without the encrypted password ever traveling over the connection.) From MySQL's point of
view, the encrypted password is the REAL password, so you should not give anyone access to it! In
particular, don't give non-administrative users read access to the tables in the mysql database!
From version 4.1 on, MySQL employs a stronger authentication method that has better password
protection during the connection process than in earlier versions. It is secure even if TCP/IP packets
are sniffed or the mysql database is captured. Password encryption is discussed further in Section 5.6.9, “Password Hashing in MySQL 4.1”.
312
Database Administration
The following examples show how various combinations of Host and User values in the user table apply to incoming connections:
Host Value
User Value Connections Matched by Entry
'thomas.loc.gov'
'fred'
fred, connecting from thomas.loc.gov
'thomas.loc.gov'
''
Any user, connecting from thomas.loc.gov
'%'
'fred'
fred, connecting from any host
'%'
''
Any user, connecting from any host
'%.loc.gov'
'fred'
fred, connecting from any host in the
loc.gov domain
'x.y.%'
'fred'
fred, connecting from x.y.net, x.y.com,
x.y.edu, and so on. (this is probably not useful)
'144.155.166.177'
'fred'
fred, connecting from the host with IP address
144.155.166.177
'144.155.166.%'
'fred'
fred, connecting from any host in the
144.155.166 class C subnet
'144.155.166.0/255.255 'fred'
.255.0'
Same as previous example
It is possible for the client hostname and username of an incoming connection to match more than
one row in the user table. The preceding set of examples demonstrates this: Several of the entries
shown match a connection from thomas.loc.gov by fred.
When multiple matches are possible, the server must determine which of them to use. It resolves
this issue as follows:
•
Whenever the server reads the user table into memory, it sorts the entries.
•
When a client attempts to connect, the server looks through the entries in sorted order.
•
The server uses the first row that matches the client hostname and username.
To see how this works, suppose that the user table looks like this:
+-----------+----------+| Host
| User
| ...
+-----------+----------+| %
| root
| ...
| %
| jeffrey | ...
| localhost | root
| ...
| localhost |
| ...
+-----------+----------+When the server reads in the table, it orders the entries with the most-specific Host values first. Literal hostnames and IP numbers are the most specific. The pattern '%' means “any host” and is least
specific. Entries with the same Host value are ordered with the most-specific User values first (a
blank User value means “any user” and is least specific). For the user table just shown, the result
after sorting looks like this:
+-----------+----------+| Host
| User
| ...
+-----------+----------+| localhost | root
| ...
| localhost |
| ...
| %
| jeffrey | ...
| %
| root
| ...
313
Database Administration
+-----------+----------+When a client attempts to connect, the server looks through the sorted entries and uses the first
match found. For a connection from localhost by jeffrey, two of the entries in the table
match: the one with Host and User values of 'localhost' and '', and the one with values of
'%' and 'jeffrey'. The 'localhost' row appears first in sorted order, so that is the one the
server uses.
Here is another example. Suppose that the user table looks like this:
+----------------+----------+| Host
| User
| ...
+----------------+----------+| %
| jeffrey | ...
| thomas.loc.gov |
| ...
+----------------+----------+The sorted table looks like this:
+----------------+----------+| Host
| User
| ...
+----------------+----------+| thomas.loc.gov |
| ...
| %
| jeffrey | ...
+----------------+----------+A connection by jeffrey from thomas.loc.gov is matched by the first row, whereas a connection by jeffrey from whitehouse.gov is matched by the second.
It is a common misconception to think that, for a given username, all entries that explicitly name
that user are used first when the server attempts to find a match for the connection. This is simply
not true. The previous example illustrates this, where a connection from thomas.loc.gov by
jeffrey is first matched not by the row containing 'jeffrey' as the User column value, but
by the row with no username. As a result, jeffrey is authenticated as an anonymous user, even
though he specified a username when connecting.
If you are able to connect to the server, but your privileges are not what you expect, you probably
are being authenticated as some other account. To find out what account the server used to authenticate you, use the CURRENT_USER() function. It returns a value in [email protected]_name
format that indicates the User and Host values from the matching user table record. Suppose
that jeffrey connects and issues the following query:
mysql> SELECT CURRENT_USER();
+----------------+
| CURRENT_USER() |
+----------------+
| @localhost
|
+----------------+
The result shown here indicates that the matching user table row had a blank User column value.
In other words, the server is treating jeffrey as an anonymous user.
The CURRENT_USER() function is available as of MySQL 4.0.6. See Section 12.9.3, “Information
Functions”. Another thing you can do to diagnose authentication problems is to print out the user
table and sort it by hand to see where the first match is being made.
5.6.6. Access Control, Stage 2: Request Verification
Once you establish a connection, the server enters Stage 2 of access control. For each request that
comes in on the connection, the server determines what operation you want to perform, then checks
whether you have sufficient privileges to do so. This is where the privilege columns in the grant
314
Database Administration
tables come into play. These privileges can come from any of the user, db, host,
tables_priv, or columns_priv tables. (You may find it helpful to refer to Section 5.6.2,
“How the Privilege System Works”, which lists the columns present in each of the grant tables.)
The user table grants privileges that are assigned to you on a global basis and that apply no matter
what the current database is. For example, if the user table grants you the DELETE privilege, you
can delete rows from any table in any database on the server host! In other words, user table privileges are superuser privileges. It is wise to grant privileges in the user table only to superusers
such as database administrators. For other users, you should leave the privileges in the user table
set to 'N' and grant privileges at more specific levels only. You can grant privileges for particular
databases, tables, or columns.
The db and host tables grant database-specific privileges. Values in the scope columns of these
tables can take the following forms:
•
The wildcard characters ‘%’ and ‘_’ can be used in the Host and Db columns of either table.
These have the same meaning as for pattern-matching operations performed with the LIKE operator. If you want to use either character literally when granting privileges, you must escape it
with a backslash. For example, to include ‘_’ character as part of a database name, specify it as
‘\_’ in the GRANT statement.
•
A '%' Host value in the db table means “any host.” A blank Host value in the db table
means “consult the host table for further information” (a process that is described later in this
section).
•
A '%' or blank Host value in the host table means “any host.”
•
A '%' or blank Db value in either table means “any database.”
•
A blank User value in either table matches the anonymous user.
The server reads in and sorts the db and host tables at the same time that it reads the user table.
The server sorts the db table based on the Host, Db, and User scope columns, and sorts the host
table based on the Host and Db scope columns. As with the user table, sorting puts the mostspecific values first and least-specific values last, and when the server looks for matching entries, it
uses the first match that it finds.
The tables_priv and columns_priv tables grant table-specific and column-specific privileges. Values in the scope columns of these tables can take the following form:
•
The wildcard characters ‘%’ and ‘_’ can be used in the Host column of either table. These have
the same meaning as for pattern-matching operations performed with the LIKE operator.
•
A '%' or blank Host value in either table means “any host.”
•
The Db, Table_name, and Column_name columns cannot contain wildcards or be blank in
either table.
The server sorts the tables_priv and columns_priv tables based on the Host, Db, and
User columns. This is similar to db table sorting, but simpler because only the Host column can
contain wildcards.
The request verification process is described here. (If you are familiar with the access-checking
source code, you may notice that the description here differs slightly from the algorithm used in the
code. The description is equivalent to what the code actually does; it differs only to make the explanation simpler.)
For requests that require administrative privileges such as SHUTDOWN or RELOAD, the server
checks only the user table row because that is the only table that specifies administrative privileges. Access is granted if the row allows the requested operation and denied otherwise. For ex315
Database Administration
ample, if you want to execute mysqladmin shutdown but your user table row doesn't grant
the SHUTDOWN privilege to you, the server denies access without even checking the db or host
tables. (They contain no Shutdown_priv column, so there is no need to do so.)
For database-related requests (INSERT, UPDATE, and so on), the server first checks the user's global (superuser) privileges by looking in the user table row. If the row allows the requested operation, access is granted. If the global privileges in the user table are insufficient, the server determines the user's database-specific privileges by checking the db and host tables:
1.
The server looks in the db table for a match on the Host, Db, and User columns. The Host
and User columns are matched to the connecting user's hostname and MySQL username. The
Db column is matched to the database that the user wants to access. If there is no row for the
Host and User, access is denied.
2.
If there is a matching db table row and its Host column is not blank, that row defines the
user's database-specific privileges.
3.
If the matching db table row's Host column is blank, it signifies that the host table enumerates which hosts should be allowed access to the database. In this case, a further lookup is done
in the host table to find a match on the Host and Db columns. If no host table row
matches, access is denied. If there is a match, the user's database-specific privileges are computed as the intersection (not the union!) of the privileges in the db and host table entries;
that is, the privileges that are 'Y' in both entries. (This way you can grant general privileges in
the db table row and then selectively restrict them on a host-by-host basis using the host table
entries.)
After determining the database-specific privileges granted by the db and host table entries, the
server adds them to the global privileges granted by the user table. If the result allows the requested operation, access is granted. Otherwise, the server successively checks the user's table and
column privileges in the tables_priv and columns_priv tables, adds those to the user's privileges, and allows or denies access based on the result.
Expressed in boolean terms, the preceding description of how a user's privileges are calculated may
be summarized like this:
global privileges
OR (database privileges AND host privileges)
OR table privileges
OR column privileges
It may not be apparent why, if the global user row privileges are initially found to be insufficient
for the requested operation, the server adds those privileges to the database, table, and column privileges later. The reason is that a request might require more than one type of privilege. For example,
if you execute an INSERT INTO ... SELECT statement, you need both the INSERT and the
SELECT privileges. Your privileges might be such that the user table row grants one privilege and
the db table row grants the other. In this case, you have the necessary privileges to perform the request, but the server cannot tell that from either table by itself; the privileges granted by the entries
in both tables must be combined.
The host table is not affected by the GRANT or REVOKE statements, so it is unused in most
MySQL installations. If you modify it directly, you can use it for some specialized purposes, such as
to maintain a list of secure servers. For example, at TcX, the host table contains a list of all machines on the local network. These are granted all privileges.
You can also use the host table to indicate hosts that are not secure. Suppose that you have a machine public.your.domain that is located in a public area that you do not consider secure.
You can allow access to all hosts on your network except that machine by using host table entries
like this:
+--------------------+----+| Host
| Db | ...
+--------------------+----+316
Database Administration
| public.your.domain | % | ... (all privileges set to 'N')
| %.your.domain
| % | ... (all privileges set to 'Y')
+--------------------+----+Naturally, you should always test your entries in the grant tables (for example, by using SHOW
GRANTS or mysqlaccess) to make sure that your access privileges are actually set up the way
you think they are.
5.6.7. When Privilege Changes Take Effect
When mysqld starts, all grant table contents are read into memory and become effective for access
control at that point.
When the server reloads the grant tables, privileges for existing client connections are affected as
follows:
•
Table and column privilege changes take effect with the client's next request.
•
Database privilege changes take effect at the next USE db_name statement.
•
Changes to global privileges and passwords take effect the next time the client connects.
If you modify the grant tables using GRANT, REVOKE, or SET PASSWORD, the server notices these
changes and reloads the grant tables into memory again immediately.
If you modify the grant tables directly using statements such as INSERT, UPDATE, or DELETE,
your changes have no effect on privilege checking until you either restart the server or tell it to reload the tables. To reload the grant tables manually, issue a FLUSH PRIVILEGES statement or execute a mysqladmin flush-privileges or mysqladmin reload command.
If you change the grant tables directly but forget to reload them, your changes have no effect until
you restart the server. This may leave you wondering why your changes don't seem to make any difference!
5.6.8. Causes of Access denied Errors
If you encounter problems when you try to connect to the MySQL server, the following items describe some courses of action you can take to correct the problem.
•
Make sure that the server is running. If it is not running, you cannot connect to it. For example,
if you attempt to connect to the server and see a message such as one of those following, one
cause might be that the server is not running:
shell> mysql
ERROR 2003: Can't connect to MySQL server on 'host_name' (111)
shell> mysql
ERROR 2002: Can't connect to local MySQL server through socket
'/tmp/mysql.sock' (111)
It might also be that the server is running, but you are trying to connect using a TCP/IP port,
named pipe, or Unix socket file different from those on which the server is listening. To correct
this when you invoke a client program, specify a --port option to indicate the proper port, or a
--socket option to indicate the proper named pipe or Unix socket file. To find out where the
socket file is, you can do:
shell> netstat -ln | grep mysql
317
Database Administration
•
The grant tables must be properly set up so that the server can use them for access control. For
some distribution types (such as binary distributions on Windows on RPM distributions on
Linux), the installation process initializes the mysql database containing the grant tables. For
distributions that do not do this, you should initialize the grant tables manually by running the
mysql_install_db script. For details, see Section 2.9.2, “Unix Post-Installation Procedures”.
One way to determine whether you need to initialize the grant tables is to look for a mysql directory under the data directory. (The data directory normally is named data or var and is located under your MySQL installation directory.) Make sure that you have a file named
user.MYD in the mysql database directory. If you do not, execute the mysql_install_db
script. After running this script and starting the server, test the initial privileges by executing this
command:
shell> mysql -u root test
The server should let you connect without error.
•
After a fresh installation, you should connect to the server and set up your users and their access
permissions:
shell> mysql -u root mysql
The server should let you connect because the MySQL root user has no password initially.
That is also a security risk, so setting the password for the root accounts is something you
should do while you're setting up your other MySQL users. For instructions on setting the initial
passwords, see Section 2.9.3, “Securing the Initial MySQL Accounts”.
•
If you have updated an existing MySQL installation to a newer version, did you run the
mysql_fix_privilege_tables script? If not, do so. The structure of the grant tables
changes occasionally when new capabilities are added, so after an upgrade you should always
make sure that your tables have the current structure. For instructions, see Section 2.10.8,
“Upgrading the Grant Tables”.
•
If a client program receives the following error message when it tries to connect, it means that
the server expects passwords in a newer format than the client is capable of generating:
shell> mysql
Client does not support authentication protocol requested
by server; consider upgrading MySQL client
For information on how to deal with this, see Section 5.6.9, “Password Hashing in MySQL 4.1”
and Section A.2.3, “Client does not support authentication protocol”.
•
If you try to connect as root and get the following error, it means that you don't have an row in
the user table with a User column value of 'root' and that mysqld cannot resolve the
hostname for your client:
Access denied for user ''@'unknown' to database mysql
In this case, you must restart the server with the --skip-grant-tables option and edit
your /etc/hosts or \windows\hosts file to add an entry for your host.
•
Remember that client programs use connection parameters specified in option files or environment variables. If a client program seems to be sending incorrect default connection parameters
when you don't specify them on the command line, check your environment and any applicable
option files. For example, if you get Access denied when you run a client without any options, make sure that you haven't specified an old password in any of your option files!
You can suppress the use of option files by a client program by invoking it with the 318
Database Administration
-no-defaults option. For example:
shell> mysqladmin --no-defaults -u root version
The option files that clients use are listed in Section 4.3.2, “Using Option Files”. Environment
variables are listed in Appendix G, Environment Variables.
•
If you get the following error, it means that you are using an incorrect root password:
shell> mysqladmin -u root -pxxxx ver
Access denied for user 'root'@'localhost' (using password: YES)
If the preceding error occurs even when you haven't specified a password, it means that you
have an incorrect password listed in some option file. Try the --no-defaults option as described in the previous item.
For information on changing passwords, see Section 5.7.5, “Assigning Account Passwords”.
If you have lost or forgotten the root password, you can restart mysqld with -skip-grant-tables to change the password. See Section A.4.1, “How to Reset the Root
Password”.
•
If you change a password by using SET PASSWORD, INSERT, or UPDATE, you must encrypt
the password using the PASSWORD() function. If you do not use PASSWORD() for these statements, the password does not work. For example, the following statement sets a password, but
fails to encrypt it, so the user is not able to connect afterward:
mysql> SET PASSWORD FOR 'abe'@'host_name' = 'eagle';
Instead, set the password like this:
mysql> SET PASSWORD FOR 'abe'@'host_name' = PASSWORD('eagle');
The PASSWORD() function is unnecessary when you specify a password using the GRANT or
(beginning with MySQL 5.0.2) CREATE USER statements, or the mysqladmin password
command, all of which automatically use PASSWORD() to encrypt the password. See Section 5.7.5, “Assigning Account Passwords”.
•
localhost is a synonym for your local hostname, and is also the default host to which clients
try to connect if you specify no host explicitly. However, connections to localhost on Unix
systems do not work if you are using a MySQL version older than 3.23.27 that uses MITpthreads: localhost connections are made using Unix socket files, which were not supported
by MIT-pthreads at that time.
To avoid this problem on such systems, you can use a --host=127.0.0.1 option to name
the server host explicitly. This will make a TCP/IP connection to the local mysqld server. You
can also use TCP/IP by specifying a --host option that uses the actual hostname of the local
host. In this case, the hostname must be specified in a user table row on the server host, even
though you are running the client program on the same host as the server.
•
If you get an Access denied error when trying to connect to the database with mysql -u
user_name, you may have a problem with the user table. Check this by executing mysql u root mysql and issuing this SQL statement:
mysql> SELECT * FROM user;
The result should include an row with the Host and User columns matching your computer's
hostname and your MySQL username.
•
The Access denied error message tells you who you are trying to log in as, the client host
319
Database Administration
from which you are trying to connect, and whether or not you were using a password. Normally,
you should have one row in the user table that exactly matches the hostname and username
that were given in the error message. For example, if you get an error message that contains using password: NO, it means that you tried to log in without an password.
•
If the following error occurs when you try to connect from a host other than the one on which
the MySQL server is running, it means that there is no row in the user table with a Host value
that matches the client host:
Host ... is not allowed to connect to this MySQL server
You can fix this by setting up an account for the combination of client hostname and username
that you are using when trying to connect.
If you do not know the IP number or hostname of the machine from which you are connecting,
you should put a row with '%' as the Host column value in the user table. After trying to
connect from the client machine, use a SELECT USER() query to see how you really did connect. (Then change the '%' in the user table row to the actual hostname that shows up in the
log. Otherwise, your system is left insecure because it allows connections from any host for the
given username.)
(Note that if you are running a version of MySQL older than 3.23.11, the output from USER()
does not include the hostname. In this case, you must restart the server with the --log option,
then obtain the hostname from the log.)
On Linux, another reason that this error might occur is that you are using a binary MySQL version that is compiled with a different version of the glibc library than the one you are using. In
this case, you should either upgrade your operating system or glibc, or download a source distribution of MySQL version and compile it yourself. A source RPM is normally trivial to compile and install, so this isn't a big problem.
•
If you specify a hostname when trying to connect, but get an error message where the hostname
is not shown or is an IP number, it means that the MySQL server got an error when trying to resolve the IP number of the client host to a name:
shell> mysqladmin -u root -pxxxx -h some-hostname ver
Access denied for user 'root'@'' (using password: YES)
This indicates a DNS problem. To fix it, execute mysqladmin flush-hosts to reset the
internal DNS hostname cache. See Section 7.5.6, “How MySQL Uses DNS”.
Some permanent solutions are:
•
•
Try to find out what is wrong with your DNS server and fix it.
•
Specify IP numbers rather than hostnames in the MySQL grant tables.
•
Put an entry for the client machine name in /etc/hosts.
•
Start mysqld with the --skip-name-resolve option.
•
Start mysqld with the --skip-host-cache option.
•
On Unix, if you are running the server and the client on the same machine, connect to localhost. Unix connections to localhost use a Unix socket file rather than TCP/IP.
•
On Windows, if you are running the server and the client on the same machine and the server
supports named pipe connections, connect to the hostname . (period). Connections to . use
a named pipe rather than TCP/IP.
If mysql -u root test works but mysql -h your_hostname -u root test
results in Access denied (where your_hostname is the actual hostname of the local
320
Database Administration
host), you may not have the correct name for your host in the user table. A common problem
here is that the Host value in the user table row specifies an unqualified hostname, but your
system's name resolution routines return a fully qualified domain name (or vice versa). For example, if you have an entry with host 'tcx' in the user table, but your DNS tells MySQL that
your hostname is 'tcx.subnet.se', the entry does not work. Try adding an entry to the
user table that contains the IP number of your host as the Host column value. (Alternatively,
you could add an entry to the user table with a Host value that contains a wildcard; for example, 'tcx.%'. However, use of hostnames ending with ‘%’ is insecure and is not recommended!)
•
If mysql -u user_name test works but mysql -u user_name other_db_name
does not, you have not granted database access for other_db_name to the given user.
•
If mysql -u user_name works when executed on the server host, but mysql -h
host_name -u user_name doesn't work when executed on a remote client host, you have
not enabled access to the server for the given username from the remote host.
•
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 allows you to specify localhost to connect from the same machine. The reason that this
doesn't work is that the default privileges include an entry with Host='localhost' and
User=''. Because that entry has a Host value 'localhost' that is more specific than
'%', it is used in preference to the new entry when connecting from localhost! The correct
procedure is to insert a second entry with Host='localhost' and User='some_user',
or to delete the entry with Host='localhost' and User=''. After deleting the entry, remember to issue a FLUSH PRIVILEGES statement to reload the grant tables.
•
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 that
there are one or more corresponding entries in the host table specifying which hosts the db table entry applies to.
•
If you are able to connect to the MySQL server, but get an Access denied message whenever you issue a SELECT ... INTO OUTFILE or LOAD DATA INFILE statement, your
entry in the user table doesn't have the FILE privilege enabled.
•
If you change the grant tables directly (for example, by using INSERT, UPDATE, or DELETE
statements) and your changes seem to be ignored, remember that you must execute a FLUSH
PRIVILEGES statement or a mysqladmin flush-privileges command to cause the
server to re-read the privilege tables. Otherwise, your changes have no effect until the next time
the server is restarted. Remember that after you change the root password with an UPDATE
command, you won't need to specify the new password until after you flush the privileges, because the server won't know you've changed the password yet!
•
If your privileges seem to have changed in the middle of a session, it may be that a MySQL administrator has changed them. Reloading the grant tables affects new client connections, but it
also affects existing connections as indicated in Section 5.6.7, “When Privilege Changes Take
Effect”.
•
If you have access problems with a Perl, PHP, Python, or ODBC program, try to connect to the
server with mysql -u user_name db_name or mysql -u user_name
-pyour_pass db_name. If you are able to connect using the mysql client, the problem lies
with your program, not with the access privileges. (There is no space between -p and the password; you can also use the --password=your_pass syntax to specify the password. If you
use the -p option alone, MySQL prompts you for the password.)
•
For testing, start the mysqld server with the --skip-grant-tables option. Then you can
change the MySQL grant tables and use the mysqlaccess script to check whether your modi321
Database Administration
fications have the desired effect. When you are satisfied with your changes, execute mysqladmin flush-privileges to tell the mysqld server to start using the new grant tables.
(Reloading the grant tables overrides the --skip-grant-tables option. This allows you to
tell the server to begin using the grant tables again without stopping and restarting it.)
•
If everything else fails, start the mysqld server with a debugging option (for example, -debug=d,general,query). This prints host and user information about attempted connections, as well as information about each command issued. See Section F.1.2, “Creating Trace
Files”.
•
If you have any other problems with the MySQL grant tables and feel you must post the problem
to the mailing list, always provide a dump of the MySQL grant tables. You can dump the tables
with the mysqldump mysql command. As always, post your problem using the mysqlbug
script. See Section 1.7.1.3, “How to Report Bugs or Problems”. In some cases, you may need to
restart mysqld with --skip-grant-tables to run mysqldump.
5.6.9. Password Hashing in MySQL 4.1
MySQL user accounts are listed in the user table of the mysql database. Each MySQL account is
assigned a password, although what is stored in the Password column of the user table is not the
plaintext version of the password, but a hash value computed from it. Password hash values are
computed by the PASSWORD() function.
MySQL uses passwords in two phases of client/server communication:
•
When a client attempts to connect to the server, there is an initial authentication step in which
the client must present a password that has a hash value matching the hash value stored in the
user table for the account that the client wants to use.
•
After the client connects, it can (if it has sufficient privileges) set or change the password hashes
for accounts listed in the user table. The client can do this by using the PASSWORD() function
to generate a password hash, or by using the GRANT or SET PASSWORD statements.
In other words, the server uses hash values during authentication when a client first attempts to connect. The server generates hash values if a connected client invokes the PASSWORD() function or
uses a GRANT or SET PASSWORD statement to set or change a password.
The password hashing mechanism was updated in MySQL 4.1 to provide better security and to reduce the risk of passwords being intercepted. However, this new mechanism is understood only by
the 4.1 server and 4.1 clients, which can result in some compatibility problems. A 4.1 client can
connect to a pre-4.1 server, because the client understands both the old and new password hashing
mechanisms. However, a pre-4.1 client that attempts to connect to a 4.1 server may run into difficulties. For example, a 4.0 mysql client that attempts to connect to a 4.1 server may fail with the
following error message:
shell> mysql -h localhost -u root
Client does not support authentication protocol requested
by server; consider upgrading MySQL client
Another common example of this occurs when trying to use the older PHP mysql extension after
upgrading to MySQL 4.1 or newer. (See Section 23.3.1, “Common Problems with MySQL and
PHP”.)
The following discussion describes the differences between the old and new password mechanisms,
and what you should do if you upgrade your server to 4.1 but need to maintain backward compatibility with pre-4.1 clients. Additional information can be found in Section A.2.3, “Client does
not support authentication protocol”. This information is of particular importance
to PHP programmers migrating MySQL databases from version 4.0 or lower to version 4.1 or higher.
322
Database Administration
Note: This discussion contrasts 4.1 behavior with pre-4.1 behavior, but the 4.1 behavior described
here actually begins with 4.1.1. MySQL 4.1.0 is an “odd” release because it has a slightly different
mechanism than that implemented in 4.1.1 and up. Differences between 4.1.0 and more recent versions are described further in Section 5.6.9.2, “Password Hashing in MySQL 4.1.0”.
Prior to MySQL 4.1, password hashes computed by the PASSWORD() function are 16 bytes long.
Such hashes look like this:
mysql> SELECT PASSWORD('mypass');
+--------------------+
| PASSWORD('mypass') |
+--------------------+
| 6f8c114b58f2ce9e
|
+--------------------+
The Password column of the user table (in which these hashes are stored) also is 16 bytes long
before MySQL 4.1.
As of MySQL 4.1, the PASSWORD() function has been modified to produce a longer 41-byte hash
value:
mysql> SELECT PASSWORD('mypass');
+-----------------------------------------------+
| PASSWORD('mypass')
|
+-----------------------------------------------+
| *43c8aa34cdc98eddd3de1fe9a9c2c2a9f92bb2098d75 |
+-----------------------------------------------+
Accordingly, the Password column in the user table also must be 41 bytes long to store these
values:
•
If you perform a new installation of MySQL 4.1, the Password column is made 41 bytes long
automatically.
•
If
you
upgrade
an
older
installation
to
4.1,
you
should
run
the
mysql_fix_privilege_tables script to increase the length of the Password column
from 16 to 41 bytes. (The script does not change existing password values, which remain 16
bytes long.)
A widened Password column can store password hashes in both the old and new formats. The
format of any given password hash value can be determined two ways:
•
The obvious difference is the length (16 bytes versus 41 bytes).
•
A second difference is that password hashes in the new format always begin with a ‘*’ character, whereas passwords in the old format never do.
The longer password hash format has better cryptographic properties, and client authentication
based on long hashes is more secure than that based on the older short hashes.
The differences between short and long password hashes are relevant both for how the server uses
passwords during authentication and for how it generates password hashes for connected clients that
perform password-changing operations.
The way in which the server uses password hashes during authentication is affected by the width of
the Password column:
•
If the column is short, only short-hash authentication is used.
323
Database Administration
•
If the column is long, it can hold either short or long hashes, and the server can use either
format:
•
Pre-4.1 clients can connect, although because they know only about the old hashing mechanism, they can authenticate only for accounts that have short hashes.
•
4.1 clients can authenticate for accounts that have short or long hashes.
For short-hash accounts, the authentication process is actually a bit more secure for 4.1 clients than
for older clients. In terms of security, the gradient from least to most secure is:
•
Pre-4.1 client authenticating for account with short password hash
•
4.1 client authenticating for account with short password hash
•
4.1 client authenticating for account with long password hash
The way in which the server generates password hashes for connected clients is affected by the
width of the Password column and by the --old-passwords option. A 4.1 server generates
long hashes only if certain conditions are met: The Password column must be wide enough to
hold long values and the --old-passwords option must not be given. These conditions apply as
follows:
•
The Password column must be wide enough to hold long hashes (41 bytes). If the column has
not been updated and still has the pre-4.1 width of 16 bytes, the server notices that long hashes
cannot fit into it and generates only short hashes when a client performs password-changing operations using PASSWORD(), GRANT, or SET PASSWORD. This is the behavior that occurs if
you have upgraded to 4.1 but have not yet run the mysql_fix_privilege_tables script
to widen the Password column.
•
If the Password column is wide, it can store either short or long password hashes. In this case,
PASSWORD(), GRANT, and SET PASSWORD generate long hashes unless the server was started with the --old-passwords option. That option forces the server to generate short password hashes instead.
The purpose of the --old-passwords option is to allow you to maintain backward compatibility
with pre-4.1 clients under circumstances where the server would otherwise generate long password
hashes. The option doesn't affect authentication (4.1 clients can still use accounts that have long
password hashes), but it does prevent creation of a long password hash in the user table as the result of a password-changing operation. Were that to occur, the account no longer could be used by
pre-4.1 clients. Without the --old-passwords option, the following undesirable scenario is possible:
•
An old client connects to an account that has a short password hash.
•
The client changes its own password. Without --old-passwords, this results in the account
having a long password hash.
•
The next time the old client attempts to connect to the account, it cannot, because the account
has a long password hash that requires the new hashing mechanism during authentication. (Once
an account has a long password hash in the user table, only 4.1 clients can authenticate for it, because pre-4.1 clients do not understand long hashes.)
This scenario illustrates that, if you must support older pre-4.1 clients, it is dangerous to run a 4.1
server without using the --old-passwords option. By running the server with -old-passwords, password-changing operations do not generate long password hashes and thus
do not cause accounts to become inaccessible to older clients. (Those clients cannot inadvertently
324
Database Administration
lock themselves out by changing their password and ending up with a long password hash.)
The downside of the --old-passwords option is that any passwords you create or change use
short hashes, even for 4.1 clients. Thus, you lose the additional security provided by long password
hashes. If you want to create an account that has a long hash (for example, for use by 4.1 clients),
you must do so while running the server without --old-passwords.
The following scenarios are possible for running a 4.1 server:
Scenario 1: Short Password column in user table:
•
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 short Password column, the server generates only short password hashes anyway.
Scenario 2: Long Password column; server not started with --old-passwords option:
•
Short or long hashes can be stored in the Password column.
•
4.1 clients can authenticate for accounts that have short or long hashes.
•
Pre-4.1 clients can authenticate only for accounts that have short hashes.
•
For connected clients, password hash-generating operations involving PASSWORD(), GRANT,
or SET PASSWORD use long hashes exclusively. A change to an account's password results in
that account having a long password hash.
As indicated earlier, a danger in this scenario is that it is possible for accounts that have a short password hash to become inaccessible to pre-4.1 clients. A change to such an account's password made
via GRANT, PASSWORD(), or SET PASSWORD results in the account being given a long password
hash. From that point on, no pre-4.1 client can authenticate to that account until the client upgrades
to 4.1.
To deal with this problem, you can change a password in a special way. For example, normally you
use SET PASSWORD as follows to change an account password:
mysql> SET PASSWORD FOR 'some_user'@'some_host' = PASSWORD('mypass');
To change the password but create a short hash, use the OLD_PASSWORD() function instead:
mysql> SET PASSWORD FOR 'some_user'@'some_host' = OLD_PASSWORD('mypass');
OLD_PASSWORD() is useful for situations in which you explicitly want to generate a short hash.
Scenario 3: Long Password column; server started with --old-passwords option:
•
Short or long hashes can be stored in the Password column.
•
4.1 clients can authenticate for accounts that have short or long hashes (but note that it is possible to create long hashes only when the server is started without --old-passwords).
•
Pre-4.1 clients can authenticate only for accounts that have short hashes.
325
Database Administration
•
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 the -old-passwords option prevents generation of long hashes. Also, if you create an account with
a long hash before using the --old-passwords option, changing the account's password while -old-passwords is in effect results in the account being given a short password, causing it to
lose the security benefits of a longer hash.
The disadvantages for these scenarios may be summarized as follows:
In scenario 1, you cannot take advantage of longer hashes that provide more secure authentication.
In scenario 2, accounts with short hashes become inaccessible to pre-4.1 clients if you change their
passwords without explicitly using OLD_PASSWORD().
In scenario 3, --old-passwords prevents accounts with short hashes from becoming inaccessible, but password-changing operations cause accounts with long hashes to revert to short hashes,
and you cannot change them back to long hashes while --old-passwords is in effect.
5.6.9.1. Implications of Password Hashing Changes for Application Programs
An upgrade to MySQL 4.1 can cause a compatibility issue for applications that use PASSWORD()
to generate passwords for their own purposes. Applications really should not do this, because
PASSWORD() should be used only to manage passwords for MySQL accounts. But some applications use PASSWORD() for their own purposes anyway.
If you upgrade to 4.1 and run the server under conditions where it generates long password hashes,
an application that uses PASSWORD() for its own passwords breaks. The recommended course of
action is to modify the application to use another function, such as SHA1() or MD5(), to produce
hashed values. If that is not possible, you can use the OLD_PASSWORD() function, which is
provided to generate short hashes in the old format. But note that OLD_PASSWORD() may one day
no longer be supported.
If the server is running under circumstances where it generates short hashes, OLD_PASSWORD() is
available but is equivalent to PASSWORD().
PHP programmers migrating their MySQL databases from version 4.0 or lower to version 4.1 or
higher should see Old Client.
5.6.9.2. Password Hashing in MySQL 4.1.0
Password hashing in MySQL 4.1.0 differs from hashing in 4.1.1 and up. The 4.1.0 differences are:
•
Password hashes are 45 bytes long rather than 41 bytes.
•
The PASSWORD() function is non-repeatable. That is, with a given argument X, successive
calls to PASSWORD(X) generate different results.
These differences make authentication in 4.1.0 incompatible with that of releases that follow it. If
you have upgraded to MySQL 4.1.0, it is recommended that you upgrade to a newer version as soon
as possible. After you do, reassign any long passwords in the user table so that they are compatible
with the 41-byte format.
5.7. MySQL User Account Management
326
Database Administration
This section describes how to set up accounts for clients of your MySQL server. It discusses the following topics:
•
The meaning of account names and passwords as used in MySQL and how that compares to
names and passwords used by your operating system
•
How to set up new accounts and remove existing accounts
•
How to change passwords
•
Guidelines for using passwords securely
•
How to use secure connections with SSL
5.7.1. MySQL Usernames and Passwords
A MySQL account is defined in terms of a username and the client host or hosts from which the
user can connect to the server. The account also has a password. There are several distinctions
between the way usernames and passwords are used by MySQL and the way they are used by your
operating system:
•
Usernames, as used by MySQL for authentication purposes, have nothing to do with usernames
(login names) as used by Windows or Unix. On Unix, most MySQL clients by default try to log
in using the current Unix username as the MySQL username, but that is for convenience only.
The default can be overridden easily, because client programs allow any username to be specified with a -u or --user option. Because this means that anyone can attempt to connect to
the server using any username, you can't make a database secure in any way unless all MySQL
accounts have passwords. Anyone who specifies a username for an account that has no password
is able to connect successfully to the server.
•
MySQL usernames can be up to 16 characters long. Operating system usernames might have a
different maximum length. For example, Unix usernames typically are limited to eight characters.
•
MySQL usernames can be up to 16 characters long. Changing the maximum length is not supported. If you still try to change it, for example by changing the length of the User column in
the mysql database tables, this will likely result in strange and unpredictable effects. (Altering
privilege tables isn't supported, anyway.) Operating system usernames might have a different
maximum length. For example, Unix usernames typically are limited to eight characters.
•
MySQL passwords have nothing to do with passwords for logging in to your operating system.
There is no necessary connection between the password you use to log in to a Windows or Unix
machine and the password you use to access the MySQL server on that machine.
•
MySQL encrypts passwords using its own algorithm. This encryption is different from that used
during the Unix login process. MySQL password encryption is the same as that implemented by
the PASSWORD() SQL function. Unix password encryption is the same as that implemented by
the ENCRYPT() SQL function. See the descriptions of the PASSWORD() and ENCRYPT()
functions in Section 12.9.2, “Encryption Functions”. From version 4.1 on, MySQL employs a
stronger authentication method that has better password protection during the connection process than in earlier versions. It is secure even if TCP/IP packets are sniffed or the mysql database is captured. (In earlier versions, even though passwords are stored in encrypted form in the
user table, knowledge of the encrypted password value could be used to connect to the
MySQL server.)
When you install MySQL, the grant tables are populated with an initial set of accounts. These accounts have names and access privileges that are described in Section 2.9.3, “Securing the Initial
MySQL Accounts”, which also discusses how to assign passwords to them. Thereafter, you normally set up, modify, and remove MySQL accounts using the GRANT and REVOKE statements. See
327
Database Administration
Section 13.5.1.3, “GRANT and REVOKE Syntax”.
When you connect to a MySQL server with a command-line client, you should specify the username
and password for the account that you want to use:
shell> mysql --user=monty --password=guess db_name
If you prefer short options, the command looks like this:
shell> mysql -u monty -pguess db_name
There must be no space between the -p option and the following password value. See Section 5.6.4,
“Connecting to the MySQL Server”.
The preceding commands include the password value on the command line, which can be a security
risk. See Section 5.7.6, “Keeping Your Password Secure”. To avoid this, specify the --password
or -p option without any following password value:
shell> mysql --user=monty --password db_name
shell> mysql -u monty -p db_name
Then the client program prints a prompt and waits for you to enter the password. (In these examples,
db_name is not interpreted as a password, because it is separated from the preceding password option by a space.)
On some systems, the library call that MySQL uses to prompt for a password automatically limits
the password to eight characters. That is a problem with the system library, not with MySQL. Internally, MySQL doesn't have any limit for the length of the password. To work around the problem,
change your MySQL password to a value that is eight or fewer characters long, or put your password in an option file.
5.7.2. Adding New User Accounts to MySQL
You can create MySQL accounts in two ways:
•
By using GRANT statements
•
By manipulating the MySQL grant tables directly
The preferred method is to use GRANT statements, because they are more concise and less errorprone. GRANT is available as of MySQL 3.22.11; its syntax is described in Section 13.5.1.3,
“GRANT and REVOKE Syntax”.
Another option for creating accounts is to use one of several available third-party programs that offer capabilities for MySQL account administration. phpMyAdmin is one such program.
The following examples show how to use the mysql client program to set up new users. These examples assume that privileges are set up according to the defaults described in Section 2.9.3,
“Securing the Initial MySQL Accounts”. This means that to make changes, you must connect to the
MySQL server as the MySQL root user, and the root account must have the INSERT privilege
for the mysql database and the RELOAD administrative privilege.
First, use the mysql program to connect to the server as the MySQL root user:
shell> mysql --user=root mysql
If you have assigned a password to the root account, you'll also need to supply a --password or
-p option for this mysql command and also for those later in this section.
328
Database Administration
After connecting to the server as root, you can add new accounts. The following statements use
GRANT to set up four new accounts:
mysql>
->
mysql>
->
mysql>
mysql>
GRANT ALL PRIVILEGES ON *.* TO 'monty'@'localhost'
IDENTIFIED BY 'some_pass' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO 'monty'@'%'
IDENTIFIED BY 'some_pass' WITH GRANT OPTION;
GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost';
GRANT USAGE ON *.* TO 'dummy'@'localhost';
The accounts created by these GRANT statements have the following properties:
•
Two of the accounts have a username of monty and a password of some_pass. Both accounts
are superuser accounts with full privileges to do anything. One account
('monty'@'localhost') can be used only when connecting from the local host. The other
('monty'@'%') can be used to connect from any other host. Note that it is necessary to have
both accounts for monty to be able to connect from anywhere as monty. Without the localhost account, the anonymous-user account for localhost that is created by
mysql_install_db would take precedence when monty connects from the local host. As a
result, monty would be treated as an anonymous user. The reason for this is that the anonymous-user account has a more specific Host column value than the 'monty'@'%' account and
thus comes earlier in the user table sort order. (user table sorting is discussed in Section 5.6.5, “Access Control, Stage 1: Connection Verification”.)
•
One account has a username of admin and no password. This account can be used only by connecting from the local host. It is granted the RELOAD and PROCESS administrative privileges.
These privileges allow the admin user to execute the mysqladmin reload, mysqladmin
refresh, and mysqladmin flush-xxx commands, as well as mysqladmin processlist . No privileges are granted for accessing any databases. You could add such privileges later by issuing additional GRANT statements.
•
One account has a username of dummy and no password. This account can be used only by connecting from the local host. No privileges are granted. The USAGE privilege in the GRANT statement allows you to create an account without giving it any privileges. It has the effect of setting
all the global privileges to 'N'. It is assumed that you will grant specific privileges to the account later.
As an alternative to GRANT, you can create the same accounts directly by issuing INSERT statements and then telling the server to reload the grant tables:
shell>
mysql>
->
->
mysql>
->
->
mysql>
->
mysql>
->
mysql>
mysql --user=root mysql
INSERT INTO user
VALUES('localhost','monty',PASSWORD('some_pass'),
'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
INSERT INTO