START-INFO-DIR-ENTRY * mysql: (mysql). MySQL documentation. END-INFO-DIR-ENTRY Table of Contents ***************** General Information About This Manual Conventions Used in This Manual Overview of the MySQL Database Management System History of MySQL The Main Features of MySQL MySQL Stability How Big MySQL Tables Can Be Year 2000 Compliance Overview of MySQL AB The Business Model and Services of MySQL AB Support Training and Certification Consulting Commercial Licenses Partnering Contact Information MySQL Support and Licensing Support Offered by MySQL AB Copyrights and Licenses Used by MySQL MySQL Licenses Using the MySQL Software Under a Commercial License Using the MySQL Software for Free Under GPL MySQL AB Logos and Trademarks The Original MySQL Logo MySQL Logos that may be Used Without Written Permission When You Need Written Permission to Use MySQL Logos MySQL AB Partnership Logos Using the Word `MySQL' in Printed Text or Presentations Using the Word `MySQL' in Company and Product Names MySQL Development Roadmap MySQL 4.0 in a Nutshell Features Available in MySQL 4.0 The Embedded MySQL Server MySQL 4.1 in a Nutshell Features Available in MySQL 4.1 Stepwise Rollout Ready for Immediate Development Use MySQL 5.0, The Next Development Release MySQL and the Future (The TODO) New Features Planned for 4.1 New Features Planned for 5.0 New Features Planned for 5.1 New Features Planned for the Near Future New Features Planned for the Mid-Term Future New Features We Don't Plan to Implement MySQL Information Sources MySQL Mailing Lists The MySQL Mailing Lists Asking Questions or Reporting Bugs How to Report Bugs or Problems Guidelines for Answering Questions on the Mailing List MySQL Community Support on IRC (Internet Relay Chat) MySQL Standards Compliance What Standards MySQL Follows Selecting SQL Modes Running MySQL in ANSI Mode MySQL Extensions to the SQL-92 Standard MySQL Differences Compared to SQL-92 Subqueries `SELECT INTO TABLE' Transactions and Atomic Operations Stored Procedures and Triggers Foreign Keys Views `--' as the Start of a Comment How MySQL Deals with Constraints Constraint PRIMARY KEY / UNIQUE Constraint `NOT NULL' and `DEFAULT' values Constraint `ENUM' and `SET' Known Errors and Design Deficiencies in MySQL Errors in 3.23 Fixed in a Later MySQL Version Errors in 4.0 Fixed in a Later MySQL Version Open Bugs / Design Deficiencies in MySQL Installing MySQL General Installation Issues Operating Systems Supported by MySQL Choosing Which MySQL Distribution to Install Choosing Which Version of MySQL to Install Choosing a Distribution Format How and When Updates Are Released Release Philosophy--No Known Bugs in Releases MySQL Binaries Compiled by MySQL AB How to Get MySQL Verifying Package Integrity Using MD5 Checksums or `GnuPG' Installation Layouts Standard MySQL Installation Using a Binary Distribution Installing MySQL on Windows Windows System Requirements Installing a Windows Binary Distribution Preparing the Windows MySQL Environment Selecting a Windows Server Starting the Server for the First Time Starting MySQL from the Windows Command Line Starting MySQL as a Windows Service Running MySQL Client Programs on Windows MySQL on Windows Compared to MySQL on Unix Installing MySQL on Linux Installing MySQL on Mac OS X Installing MySQL on NetWare Installing MySQL on HP-UX Installing MySQL on Other Unix-like Systems MySQL Installation Using a Source Distribution Quick Source Installation Overview Typical `configure' Options Installing from the Development Source Tree Dealing With Problems Compiling MySQL MIT-pthreads Notes Installing MySQL from Source on Windows Building MySQL Using VC++ Creating a Windows Source Package from the Latest Development Source Compiling MySQL Clients on Windows Post-installation Setup and Testing Windows Post-installation Procedures Unix Post-installation Procedures Problems Running `mysql_install_db' Starting and Stopping MySQL Automatically Starting and Troubleshooting the MySQL Server Upgrading/Downgrading MySQL Upgrading from Version 4.1 to 5.0 Upgrading from Version 4.0 to 4.1 Upgrading from Version 3.23 to 4.0 Upgrading from Version 3.22 to 3.23 Upgrading from Version 3.21 to 3.22 Upgrading from Version 3.20 to 3.21 Upgrading MySQL under Windows Upgrading the Grant Tables Copying MySQL Databases to Another Machine Operating System Specific Notes Linux Notes Linux Operating System Notes Linux Binary Distribution Notes Linux Source Distribution Notes Linux Post-installation Notes Linux x86 Notes Linux SPARC Notes Linux Alpha Notes Linux PowerPC Notes Linux MIPS Notes Linux IA-64 Notes Mac OS X Notes Mac OS X 10.x (Darwin) Mac OS X Server 1.2 (Rhapsody) Solaris Notes Solaris 2.7/2.8 Notes Solaris x86 Notes BSD Notes FreeBSD Notes NetBSD Notes OpenBSD 2.5 Notes OpenBSD 2.8 Notes BSD/OS Version 2.x Notes BSD/OS Version 3.x Notes BSD/OS Version 4.x Notes Other Unix Notes HP-UX Version 10.20 Notes HP-UX Version 11.x Notes IBM-AIX notes SunOS 4 Notes Alpha-DEC-UNIX Notes (Tru64) Alpha-DEC-OSF/1 Notes SGI Irix Notes SCO Notes SCO UnixWare Version 7.1.x Notes OS/2 Notes BeOS Notes Perl Installation Notes Installing Perl on Unix Installing ActiveState Perl on Windows Problems Using the Perl `DBI'/`DBD' Interface MySQL Tutorial Connecting to and Disconnecting from the Server Entering Queries Creating and Using a Database Creating and Selecting a Database Creating a Table Loading Data into a Table Retrieving Information from a Table Selecting All Data Selecting Particular Rows Selecting Particular Columns Sorting Rows Date Calculations Working with `NULL' Values Pattern Matching Counting Rows Using More Than one Table Getting Information About Databases and Tables Using `mysql' in Batch Mode Examples of Common Queries The Maximum Value for a Column The Row Holding the Maximum of a Certain Column Maximum of Column per Group The Rows Holding the Group-wise Maximum of a Certain Field Using User Variables Using Foreign Keys Searching on Two Keys Calculating Visits Per Day Using `AUTO_INCREMENT' Queries from the Twin Project Find All Non-distributed Twins Show a Table of Twin Pair Status Using MySQL with Apache Using MySQL Programs Overview of MySQL Programs Invoking MySQL Programs Specifying Program Options Using Options on the Command Line Using Option Files Using Environment Variables to Specify Options Using Options to Set Program Variables Database Administration The MySQL Server and Server Startup Scripts Overview of the Server-Side Scripts and Utilities `mysqld-max', An Extended `mysqld' Server `mysqld_safe', The Wrapper Around `mysqld' `mysql.server', A Server Startup Script for Run Directories `mysqld_multi', A Program for Managing Multiple MySQL Servers Configuring MySQL `mysqld' Command-line Options The Server SQL Mode General Security Issues General Security Guidelines Making MySQL Secure Against Attackers Startup Options for `mysqld' Concerning Security Security Issues with `LOAD DATA LOCAL' The MySQL Access Privilege System What the Privilege System Does How the Privilege System Works Privileges Provided by MySQL Connecting to the MySQL Server Access Control, Stage 1: Connection Verification Access Control, Stage 2: Request Verification Password Hashing in MySQL 4.1 Causes of `Access denied' Errors MySQL User Account Management MySQL Usernames and Passwords When Privilege Changes Take Effect Setting Up the Initial MySQL Privileges Adding New Users to MySQL Deleting Users from MySQL Limiting user resources Setting Up Passwords Keeping Your Password Secure Using Secure Connections Basics Requirements Setting Up SSL Certificates for MySQL SSL `GRANT' Options SSL Command-line Options Connecting to MySQL Remotely from Windows with SSH Disaster Prevention and Recovery Database Backups Using `myisamchk' for Table Maintenance and Crash Recovery `myisamchk' Invocation Syntax General Options for `myisamchk' Check Options for `myisamchk' Repair Options for myisamchk Other Options for `myisamchk' `myisamchk' Memory Usage Using `myisamchk' for Crash Recovery How to Check Tables for Errors How to Repair Tables Table Optimization Setting Up a Table Maintenance Regimen Getting Information About a Table MySQL Localization and International Usage The Character Set Used for Data and Sorting German character set Non-English Error Messages Adding a New Character Set The Character Definition Arrays String Collating Support Multi-byte Character Support Problems With Character Sets The MySQL Log Files The Error Log The General Query Log The Update Log The Binary Log The Slow Query Log Log File Maintenance Running Multiple MySQL Servers on the Same Machine Running Multiple Servers on Windows Starting Multiple Windows Servers at the Command Line Starting Multiple Windows Servers as Services Running Multiple Servers on Unix Using Client Programs in a Multiple-Server Environment Replication in MySQL Introduction to Replication Replication Implementation Overview Replication Implementation Details How to Set Up Replication Upgrading a Replication Setup - Mixing Different MySQL Versions Replication Features and Known Problems Replication Startup Options Replication FAQ Troubleshooting Replication Reporting Replication Bugs MySQL Optimization Optimization Overview MySQL Design Limitations/Tradeoffs Portability What We Have Used MySQL For The MySQL Benchmark Suite Using Your Own Benchmarks Optimizing `SELECT' Statements and Other Queries `EXPLAIN' Syntax (Get Information About a `SELECT') Estimating Query Performance Speed of `SELECT' Queries How MySQL Optimizes `WHERE' Clauses How MySQL Optimizes `OR' Clauses How MySQL Optimizes `IS NULL' How MySQL Optimizes `DISTINCT' How MySQL Optimizes `LEFT JOIN' and `RIGHT JOIN' How MySQL Optimizes `ORDER BY' How MySQL Optimizes `LIMIT' Speed of `INSERT' Queries Speed of `UPDATE' Queries Speed of `DELETE' Queries Other Optimization Tips Locking Issues How MySQL Locks Tables Table Locking Issues Optimizing Database Structure Design Choices Get Your Data as Small as Possible How MySQL Uses Indexes Column Indexes Multiple-Column Indexes The MyISAM Key Cache Shared Key Cache Access Multiple Key Caches Midpoint Insertion Strategy Index Preloading Key Cache Block Size Restructuring a Key Cache How MySQL Counts Open Tables How MySQL Opens and Closes Tables Drawbacks to Creating Large Numbers of Tables in the Same Database Optimizing the MySQL Server System/Compile Time and Startup Parameter Tuning Tuning Server Parameters How Compiling and Linking Affects the Speed of MySQL How MySQL Uses Memory How MySQL uses DNS `SET' Syntax Disk Issues Using Symbolic Links Using Symbolic Links for Databases on Unix Using Symbolic Links for Tables on Unix Using Symbolic Links for Databases on Windows MySQL Client and Utility Programs Overview of the Client-Side Scripts and Utilities `mysql', The Command-line Tool How to Run SQL Commands from a Text File `mysqlcc', The MySQL Control Center `mysqladmin', Administering a MySQL Server `mysqlbinlog', Executing the queries from a binary log Using `mysqlcheck' for Table Maintenance and Crash Recovery `mysqldump', Dumping Table Structure and Data `mysqlhotcopy', Copying MySQL Databases and Tables `mysqlimport', Importing Data from Text Files `mysqlshow', Showing Databases, Tables, and Columns `myisampack', The MySQL Compressed Read-only Table Generator `mysql_config', Get compile options for compiling clients `perror', Explaining Error Codes MySQL Language Reference Language Structure Literal Values Strings Numbers Hexadecimal Values Boolean Values `NULL' Values Database, Table, Index, Column, and Alias Names Identifier Qualifiers Identifier Case Sensitivity User Variables System Variables Dynamic System Variables Structured System Variables Comment Syntax Treatment of Reserved Words in MySQL Column Types Numeric Types Date and Time Types Y2K Issues and Date Types The `DATETIME', `DATE', and `TIMESTAMP' Types The `TIME' Type The `YEAR' Type String Types The `CHAR' and `VARCHAR' Types The `BLOB' and `TEXT' Types The `ENUM' Type The `SET' Type Choosing the Right Type for a Column Using Column Types from Other Database Engines Column Type Storage Requirements Functions and Operators Non-Type-Specific Operators and Functions Parentheses Comparison Operators Logical Operators Control Flow Functions String Functions String Comparison Functions Case-Sensitivity Numeric Functions Arithmetic Operations Mathematical Functions Date and Time Functions Cast Functions Other Functions Bit Functions Encryption Functions Information Functions Miscellaneous Functions Functions and Modifiers for Use with `GROUP BY' Clauses `GROUP BY' Functions `GROUP BY' Modifiers `GROUP BY' with Hidden Fields SQL Statement Syntax Data Manipulation Statements `DELETE' Syntax `DO' Syntax `HANDLER' Syntax `INSERT' Syntax `INSERT ... SELECT' Syntax `INSERT DELAYED' Syntax `LOAD DATA INFILE' Syntax `REPLACE' Syntax `SELECT' Syntax `JOIN' Syntax `UNION' Syntax Subquery Syntax The Subquery as Scalar Operand Comparisons Using Subqueries Subqueries with `ANY', `IN', and `SOME' Subqueries with `ALL' Correlated Subqueries `EXISTS' and `NOT EXISTS' Row Subqueries Subqueries in the `FROM' clause Subquery Errors Optimizing Subqueries Rewriting Subqueries for Earlier MySQL Versions `TRUNCATE' Syntax `UPDATE' Syntax Data Definition Statements `ALTER DATABASE' Syntax `ALTER TABLE' Syntax `CREATE DATABASE' Syntax `CREATE INDEX' Syntax `CREATE TABLE' Syntax Silent Column Specification Changes `DROP DATABASE' Syntax `DROP INDEX' Syntax `DROP TABLE' Syntax `RENAME TABLE' Syntax Basic MySQL User Utility Statements `DESCRIBE' Syntax (Get Information About Columns) `USE' Syntax MySQL Transactional and Locking Statements `START TRANSACTION', `COMMIT', and `ROLLBACK' Syntax Statements That Cannot Be Rolled Back Statements That Cause an Implicit Commit `SAVEPOINT' and `ROLLBACK TO SAVEPOINT' Syntax `LOCK TABLES' and `UNLOCK TABLES' Syntax `SET TRANSACTION' Syntax Database Administration Statements Account Management Statements `GRANT' and `REVOKE' Syntax Table Maintenance Statements `ANALYZE TABLE' Syntax `BACKUP TABLE' Syntax `CHECK TABLE' Syntax `CHECKSUM TABLE' Syntax `OPTIMIZE TABLE' Syntax `REPAIR TABLE' Syntax `RESTORE TABLE' Syntax `SHOW' Syntax Retrieving Information about Database, Tables, Columns, and Indexes `SHOW TABLE STATUS' `SHOW STATUS' `SHOW VARIABLES' `SHOW [BDB] LOGS' `SHOW PROCESSLIST' `SHOW GRANTS' `SHOW CREATE TABLE' `SHOW WARNINGS | ERRORS' `SHOW TABLE TYPES' `SHOW PRIVILEGES' Other Administrative Statements `CACHE INDEX' Syntax `FLUSH' Syntax `KILL' Syntax `LOAD INDEX INTO CACHE' Syntax `PURGE MASTER LOGS' Syntax `RESET' Syntax Replication Statements SQL Statements for Controlling Master Servers `PURGE MASTER LOGS' `RESET MASTER' `SET SQL_LOG_BIN' `SHOW BINLOG EVENTS' `SHOW MASTER STATUS' `SHOW MASTER LOGS' `SHOW SLAVE HOSTS' SQL Statements for Controlling Slave Servers `CHANGE MASTER TO' `LOAD DATA FROM MASTER' `LOAD TABLE tbl_name FROM MASTER' `MASTER_POS_WAIT()' `RESET SLAVE' `SET GLOBAL SQL_SLAVE_SKIP_COUNTER' `SHOW SLAVE STATUS' `START SLAVE' `STOP SLAVE' MySQL Full-text Search Full-text Restrictions Fine-tuning MySQL Full-text Search Full-text Search TODO MySQL Query Cache How the Query Cache Operates Query Cache Configuration Query Cache Options in `SELECT' Query Cache Status and Maintenance MySQL Table Types `MyISAM' Tables Space Needed for Keys `MyISAM' Table Formats Static (Fixed-length) Table Characteristics Dynamic Table Characteristics Compressed Table Characteristics `MyISAM' Table Problems Corrupted `MyISAM' Tables Clients is using or hasn't closed the table properly `MERGE' Tables `MERGE' Table Problems `HEAP' Tables `InnoDB' Tables InnoDB Tables Overview InnoDB in MySQL Version 3.23 InnoDB Startup Options Creating InnoDB Tablespace If Something Goes Wrong in Database Creation Creating InnoDB Tables Converting MyISAM Tables to InnoDB `FOREIGN KEY' Constraints Multiple tablespaces - putting each table into its own .ibd file Adding and Removing InnoDB Data and Log Files Backing up and Recovering an InnoDB Database Forcing recovery Checkpoints Moving an InnoDB Database to Another Machine InnoDB Transaction Model and Locking InnoDB and `SET ... TRANSACTION ISOLATION LEVEL ...' Consistent Non-Locking Read Locking Reads `SELECT ... FOR UPDATE' and `SELECT ... LOCK IN SHARE MODE' Next-key Locking: Avoiding the Phantom Problem Locks Set by Different SQL Statements in `InnoDB' Deadlock Detection and Rollback An Example of How the Consistent Read Works in `InnoDB' How to Cope With Deadlocks Performance Tuning Tips `SHOW INNODB STATUS' and the `InnoDB' Monitors Implementation of Multi-versioning Table and Index Structures Physical Structure of an Index Insert Buffering Adaptive Hash Indexes Physical Record Structure How an `AUTO_INCREMENT' Column Works in InnoDB File Space Management and Disk I/O Disk I/O File Space Management Defragmenting a Table Error Handling Restrictions on InnoDB Tables InnoDB Change History MySQL/InnoDB-5.0.0, December 24, 2003 MySQL/InnoDB-4.0.17, December 17, 2003 MySQL/InnoDB-4.1.1, December 4, 2003 MySQL/InnoDB-4.0.16, October 22, 2003 MySQL/InnoDB-3.23.58, September 15, 2003 MySQL/InnoDB-4.0.15, September 10, 2003 MySQL/InnoDB-4.0.14, July 22, 2003 MySQL/InnoDB-3.23.57, June 20, 2003 MySQL/InnoDB-4.0.13, May 20, 2003 MySQL/InnoDB-4.1.0, April 3, 2003 MySQL/InnoDB-3.23.56, March 17, 2003 MySQL/InnoDB-4.0.12, March 18, 2003 MySQL/InnoDB-4.0.11, February 25, 2003 MySQL/InnoDB-4.0.10, February 4, 2003 MySQL/InnoDB-3.23.55, January 24, 2003 MySQL/InnoDB-4.0.9, January 14, 2003 MySQL/InnoDB-4.0.8, January 7, 2003 MySQL/InnoDB-4.0.7, December 26, 2002 MySQL/InnoDB-4.0.6, December 19, 2002 MySQL/InnoDB-3.23.54, December 12, 2002 MySQL/InnoDB-4.0.5, November 18, 2002 MySQL/InnoDB-3.23.53, October 9, 2002 MySQL/InnoDB-4.0.4, October 2, 2002 MySQL/InnoDB-4.0.3, August 28, 2002 MySQL/InnoDB-3.23.52, August 16, 2002 MySQL/InnoDB-4.0.2, July 10, 2002 MySQL/InnoDB-3.23.51, June 12, 2002 MySQL/InnoDB-3.23.50, April 23, 2002 MySQL/InnoDB-3.23.49, February 17, 2002 MySQL/InnoDB-3.23.48, February 9, 2002 MySQL/InnoDB-3.23.47, December 28, 2001 MySQL/InnoDB-4.0.1, December 23, 2001 MySQL/InnoDB-3.23.46, November 30, 2001 MySQL/InnoDB-3.23.45, November 23, 2001 MySQL/InnoDB-3.23.44, November 2, 2001 MySQL/InnoDB-3.23.43, October 4, 2001 MySQL/InnoDB-3.23.42, September 9, 2001 MySQL/InnoDB-3.23.41, August 13, 2001 MySQL/InnoDB-3.23.40, July 16, 2001 MySQL/InnoDB-3.23.39, June 13, 2001 MySQL/InnoDB-3.23.38, May 12, 2001 `InnoDB' Contact Information `BDB' or `BerkeleyDB' Tables Overview of `BDB' Tables Installing `BDB' `BDB' Startup Options Characteristics of `BDB' Tables Things We Need to Fix for `BDB' in the Near Future Operating Systems Supported by `BDB' Restrictions on `BDB' Tables Errors That May Occur When Using `BDB' Tables `ISAM' Tables Introduction to MaxDB History of MaxDB Licensing and Support Basic Concepts of MaxDB Feature Differences between MaxDB and MySQL Interoperability Features between MaxDB and MySQL MaxDB-related Links Reserved Words in MaxDB Functions Column Types National Character Sets and Unicode Character Sets and Collations in General Character Sets and Collations in MySQL Determining the Default Character Set and Collation Server Character Set and Collation Database Character Set and Collation Table Character Set and Collation Column Character Set and Collation Examples of Character Set and Collation Assignment Connection Character Sets and Collations Character String Literal Character Set and Collation `COLLATE' Clause in Various Parts of an SQL Query `COLLATE' Clause Precedence `BINARY' Operator Some Special Cases Where the Collation Determination is Tricky Collations Must Be for the Right Character Set An example of the Effect of Collation Operations Affected by Character Set Support Result Strings `CONVERT()' `CAST()' `SHOW CHARACTER SET' `SHOW COLLATION' `SHOW CREATE DATABASE' `SHOW FULL COLUMNS' Unicode Support UTF8 for Metadata Compatibility with Other DBMSs New Character Set Configuration File format National Character Set Upgrading from MySQL 4.0 4.0 Character Sets and Corresponding 4.1 Character Set/Collation Pairs The Character Sets and Collations that MySQL Supports The Unicode Character Sets Platform Specific Character Sets Character Sets for South Europe and Middle East The Asian Character Sets The Baltic Character Sets The Cyrillic Character Sets The Central European Character Sets The West European Character Sets Spatial Extensions in MySQL Introduction The OpenGIS Geometry Model The Geometry Class Hierarchy Class `Geometry' Class `Point' Class `Curve' Class `LineString' Class `Surface' Class `Polygon' Class `GeometryCollection' Class `MultiPoint' Class `MultiCurve' Class `MultiLineString' Class `MultiSurface' Class `MultiPolygon' Supported Spatial Data Formats Well-Known Text (WKT) Format Well-Known Binary (WKB) Format Creating a Spatially Enabled MySQL Database MySQL Spatial Datatypes Creating Spatial Values Creating Geometry Values Using WKT Functions Creating Geometry Values Using WKB Functions Creating Geometry Values Using MySQL-Specific Functions Creating Spatial Columns Populating Spatial Columns Fetching Spatial Data Fetching Spatial Data in Internal Format Fetching Spatial Data in WKT Format Fetching Spatial Data in WKB Format Analyzing Spatial Information Geometry Format Conversion Functions `Geometry' Functions General Geometry Functions `Point' Functions `LineString' Functions `MultiLineString' Functions `Polygon' Functions `MultiPolygon' Functions `GeometryCollection' Functions Functions That Create New Geometries from Existing Ones Geometry Functions That Produce New Geometries Spatial Operators Functions for Testing Spatial Relations Between Geometric Objects Relations on Geometry Minimal Bounding Rectangles (MBRs) Functions That Test Spatial Relationships Between Geometries Optimizing Spatial Analysis Creating Spatial Indexes Using a Spatial Index MySQL Conformance and Compatibility GIS Features That Are Not Yet Implemented Stored Procedures and Functions Stored Procedure Syntax Maintaining Stored Procedures `CREATE PROCEDURE' and `CREATE FUNCTION' `ALTER PROCEDURE' and `ALTER FUNCTION' `DROP PROCEDURE' and `DROP FUNCTION' `SHOW CREATE PROCEDURE' and `SHOW CREATE FUNCTION' `SHOW PROCEDURE STATUS' and `SHOW FUNCTION STATUS' `CALL' `BEGIN ... END' Compound Statement `DECLARE' Statement Variables in Stored Procedures `DECLARE' Local Variables Variable `SET' Statement `SELECT ... INTO' Statement Conditions and Handlers `DECLARE' Conditions `DECLARE' Handlers Cursors Declaring Cursors Cursor `OPEN' Statement Cursor `FETCH' Statement Cursor `CLOSE' Statement Flow Control Constructs `IF' Statement `CASE' Statement `LOOP' Statement `LEAVE' Statement `ITERATE' Statement `REPEAT' Statement `WHILE' Statement MySQL APIs MySQL C API C API Datatypes C API Function Overview C API Function Descriptions `mysql_affected_rows()' `mysql_change_user()' `mysql_character_set_name()' `mysql_close()' `mysql_connect()' `mysql_create_db()' `mysql_data_seek()' `mysql_debug()' `mysql_drop_db()' `mysql_dump_debug_info()' `mysql_eof()' `mysql_errno()' `mysql_error()' `mysql_escape_string()' `mysql_fetch_field()' `mysql_fetch_fields()' `mysql_fetch_field_direct()' `mysql_fetch_lengths()' `mysql_fetch_row()' `mysql_field_count()' `mysql_field_seek()' `mysql_field_tell()' `mysql_free_result()' `mysql_get_client_info()' `mysql_get_client_version()' `mysql_get_host_info()' `mysql_get_proto_info()' `mysql_get_server_info()' `mysql_get_server_version()' `mysql_info()' `mysql_init()' `mysql_insert_id()' `mysql_kill()' `mysql_list_dbs()' `mysql_list_fields()' `mysql_list_processes()' `mysql_list_tables()' `mysql_num_fields()' `mysql_num_rows()' `mysql_options()' `mysql_ping()' `mysql_query()' `mysql_real_connect()' `mysql_real_escape_string()' `mysql_real_query()' `mysql_reload()' `mysql_row_seek()' `mysql_row_tell()' `mysql_select_db()' `mysql_set_server_option()' `mysql_shutdown()' `mysql_sqlstate()' `mysql_ssl_set()' `mysql_stat()' `mysql_store_result()' `mysql_thread_id()' `mysql_use_result()' `mysql_warning_count()' `mysql_commit()' `mysql_rollback()' `mysql_autocommit()' `mysql_more_results()' `mysql_next_result()' C API Prepared Statements C API Prepared Statement Datatypes C API Prepared Statement Function Overview C API Prepared Statement Function Descriptions `mysql_bind_param()' `mysql_bind_result()' `mysql_execute()' `mysql_fetch()' `mysql_fetch_column()' `mysql_get_metadata()' `mysql_param_count()' `mysql_param_result()' `mysql_prepare()' `mysql_send_long_data()' `mysql_stmt_affected_rows()' `mysql_stmt_close()' `mysql_stmt_data_seek()' `mysql_stmt_errno()' `mysql_stmt_error()' `mysql_stmt_free_result()' `mysql_stmt_num_rows()' `mysql_stmt_reset()' `mysql_stmt_row_seek()' `mysql_stmt_row_tell()' `mysql_stmt_sqlstate()' `mysql_stmt_store_result()' C API Handling of Multiple Query Execution C API Handling of Date and Time Values C API Threaded Function Descriptions `my_init()' `mysql_thread_init()' `mysql_thread_end()' `mysql_thread_safe()' C API Embedded Server Function Descriptions `mysql_server_init()' `mysql_server_end()' Common questions and problems when using the C API Why `mysql_store_result()' Sometimes Returns `NULL' After `mysql_query()' Returns Success What Results You Can Get from a Query How to Get the Unique ID for the Last Inserted Row Problems Linking with the C API Building Client Programs How to Make a Threaded Client libmysqld, the Embedded MySQL Server Library Overview of the Embedded MySQL Server Library Compiling Programs with `libmysqld' Restrictions when using the Embedded MySQL Server Using Option Files with the Embedded Server Things left to do in Embedded Server (TODO) A Simple Embedded Server Example Licensing the Embedded Server MySQL ODBC Support How to Install MyODBC How to Fill in the Various Fields in the ODBC Administrator Program Connect parameters for MyODBC How to Report Problems with MyODBC Programs Known to Work with MyODBC How to Get the Value of an `AUTO_INCREMENT' Column in ODBC Reporting Problems with MyODBC MySQL Java Connectivity (JDBC) MySQL PHP API Common Problems with MySQL and PHP MySQL Perl API MySQL C++ API Borland C++ MySQL Python API MySQL Tcl API MySQL Eiffel Wrapper Error Handling in MySQL Error Returns Extending MySQL MySQL Internals MySQL Threads MySQL Test Suite Running the MySQL Test Suite Extending the MySQL Test Suite Reporting Bugs in the MySQL Test Suite Adding New Functions to MySQL `CREATE FUNCTION/DROP FUNCTION' Syntax Adding a New User-defined Function UDF Calling Sequences for simple functions UDF Calling Sequences for aggregate functions Argument Processing Return Values and Error Handling Compiling and Installing User-defined Functions Adding a New Native Function Adding New Procedures to MySQL Procedure Analyse Writing a Procedure Problems and Common Errors How to Determine What Is Causing Problems Common Errors When Using MySQL `Access denied' Error `MySQL server has gone away' Error `Can't connect to [local] MySQL server' Error `Client does not support authentication protocol' error `Host '...' is blocked' Error `Too many connections' Error `Some non-transactional changed tables couldn't be rolled back' Error `Out of memory' Error `Packet too large' Error Communication Errors / Aborted Connection `The table is full' Error `Can't create/write to file' Error `Commands out of sync' Error in Client `Ignoring user' Error `Table 'xxx' doesn't exist' Error `Can't initialize character set xxx' error File Not Found Installation Related Issues Problems When Linking with the MySQL Client Library How to Run MySQL As a Normal User Problems with File Permissions Administration Related Issues What To Do If MySQL Keeps Crashing How to Reset a Forgotten Root Password How MySQL Handles a Full Disk Where MySQL Stores Temporary Files How to Protect or Change the MySQL Socket File `/tmp/mysql.sock' Time Zone Problems Query Related Issues Case-Sensitivity in Searches Problems Using `DATE' Columns Problems with `NULL' Values Problems with `alias' Deleting Rows from Related Tables Solving Problems with No Matching Rows Problems with Floating-Point Comparison Optimizer Related Issues How to avoid table scan,,, Table Definition Related Issues Problems with `ALTER TABLE'. How To Change the Order of Columns in a Table TEMPORARY TABLE problems Credits Developers at MySQL AB Contributors to MySQL Documenters and translators Libraries used by and included with MySQL Packages that support MySQL Tools that were used to create MySQL Supporters of MySQL MySQL Change History Changes in release 5.0.x (Development) Changes in release 5.0.1 (not released yet) Changes in release 5.0.0 (22 Dec 2003: Alpha) Changes in release 4.1.x (Alpha) Changes in release 4.1.2 (not released yet) Changes in release 4.1.1 (01 Dec 2003) Changes in release 4.1.0 (03 Apr 2003: Alpha) Changes in release 4.0.x (Production) Changes in release 4.0.19 (not released yet) Changes in release 4.0.18 (to be released soon) Changes in release 4.0.17 (14 Dec 2003) Changes in release 4.0.16 (17 Oct 2003) Changes in release 4.0.15 (03 Sep 2003) Changes in release 4.0.14 (18 Jul 2003) Changes in release 4.0.13 (16 May 2003) Changes in release 4.0.12 (15 Mar 2003: Production) Changes in release 4.0.11 (20 Feb 2003) Changes in release 4.0.10 (29 Jan 2003) Changes in release 4.0.9 (09 Jan 2003) Changes in release 4.0.8 (07 Jan 2003) Changes in release 4.0.7 (20 Dec 2002) Changes in release 4.0.6 (14 Dec 2002: Gamma) Changes in release 4.0.5 (13 Nov 2002) Changes in release 4.0.4 (29 Sep 2002) Changes in release 4.0.3 (26 Aug 2002: Beta) Changes in release 4.0.2 (01 Jul 2002) Changes in release 4.0.1 (23 Dec 2001) Changes in release 4.0.0 (Oct 2001: Alpha) Changes in release 3.23.x (Recent; still supported) Changes in release 3.23.59 (not released yet) Changes in release 3.23.58 (11 Sep 2003) Changes in release 3.23.57 (06 Jun 2003) Changes in release 3.23.56 (13 Mar 2003) Changes in release 3.23.55 (23 Jan 2003) Changes in release 3.23.54 (05 Dec 2002) Changes in release 3.23.53 (09 Oct 2002) Changes in release 3.23.52 (14 Aug 2002) Changes in release 3.23.51 (31 May 2002) Changes in release 3.23.50 (21 Apr 2002) Changes in release 3.23.49 Changes in release 3.23.48 (07 Feb 2002) Changes in release 3.23.47 (27 Dec 2001) Changes in release 3.23.46 (29 Nov 2001) Changes in release 3.23.45 (22 Nov 2001) Changes in release 3.23.44 (31 Oct 2001) Changes in release 3.23.43 (04 Oct 2001) Changes in release 3.23.42 (08 Sep 2001) Changes in release 3.23.41 (11 Aug 2001) Changes in release 3.23.40 Changes in release 3.23.39 (12 Jun 2001) Changes in release 3.23.38 (09 May 2001) Changes in release 3.23.37 (17 Apr 2001) Changes in release 3.23.36 (27 Mar 2001) Changes in release 3.23.35 (15 Mar 2001) Changes in release 3.23.34a Changes in release 3.23.34 (10 Mar 2001) Changes in release 3.23.33 (09 Feb 2001) Changes in release 3.23.32 (22 Jan 2001: Production) Changes in release 3.23.31 (17 Jan 2001) Changes in release 3.23.30 (04 Jan 2001) Changes in release 3.23.29 (16 Dec 2000) Changes in release 3.23.28 (22 Nov 2000: Gamma) Changes in release 3.23.27 (24 Oct 2000) Changes in release 3.23.26 (18 Oct 2000) Changes in release 3.23.25 (29 Sep 2000) Changes in release 3.23.24 (08 Sep 2000) Changes in release 3.23.23 (01 Sep 2000) Changes in release 3.23.22 (31 Jul 2000) Changes in release 3.23.21 Changes in release 3.23.20 Changes in release 3.23.19 Changes in release 3.23.18 Changes in release 3.23.17 Changes in release 3.23.16 Changes in release 3.23.15 (May 2000: Beta) Changes in release 3.23.14 Changes in release 3.23.13 Changes in release 3.23.12 (07 Mar 2000) Changes in release 3.23.11 Changes in release 3.23.10 Changes in release 3.23.9 Changes in release 3.23.8 (02 Jan 2000) Changes in release 3.23.7 (10 Dec 1999) Changes in release 3.23.6 Changes in release 3.23.5 (20 Oct 1999) Changes in release 3.23.4 (28 Sep 1999) Changes in release 3.23.3 Changes in release 3.23.2 (09 Aug 1999) Changes in release 3.23.1 Changes in release 3.23.0 (05 Aug 1999: Alpha) Changes in release 3.22.x (Old; discontinued) Changes in release 3.22.35 Changes in release 3.22.34 Changes in release 3.22.33 Changes in release 3.22.32 (14 Feb 2000) Changes in release 3.22.31 Changes in release 3.22.30 Changes in release 3.22.29 (02 Jan 2000) Changes in release 3.22.28 (20 Oct 1999) Changes in release 3.22.27 Changes in release 3.22.26 (16 Sep 1999) Changes in release 3.22.25 Changes in release 3.22.24 (05 Jul 1999) Changes in release 3.22.23 (08 Jun 1999) Changes in release 3.22.22 (30 Apr 1999) Changes in release 3.22.21 Changes in release 3.22.20 (18 Mar 1999) Changes in release 3.22.19 (Mar 1999: Production) Changes in release 3.22.18 Changes in release 3.22.17 Changes in release 3.22.16 (Feb 1999: Gamma) Changes in release 3.22.15 Changes in release 3.22.14 Changes in release 3.22.13 Changes in release 3.22.12 Changes in release 3.22.11 Changes in release 3.22.10 Changes in release 3.22.9 Changes in release 3.22.8 Changes in release 3.22.7 (Sep 1998: Beta) Changes in release 3.22.6 Changes in release 3.22.5 Changes in release 3.22.4 Changes in release 3.22.3 Changes in release 3.22.2 Changes in release 3.22.1 (Jun 1998: Alpha) Changes in release 3.22.0 Changes in release 3.21.x Changes in release 3.21.33 Changes in release 3.21.32 Changes in release 3.21.31 Changes in release 3.21.30 Changes in release 3.21.29 Changes in release 3.21.28 Changes in release 3.21.27 Changes in release 3.21.26 Changes in release 3.21.25 Changes in release 3.21.24 Changes in release 3.21.23 Changes in release 3.21.22 Changes in release 3.21.21a Changes in release 3.21.21 Changes in release 3.21.20 Changes in release 3.21.19 Changes in release 3.21.18 Changes in release 3.21.17 Changes in release 3.21.16 Changes in release 3.21.15 Changes in release 3.21.14b Changes in release 3.21.14a Changes in release 3.21.13 Changes in release 3.21.12 Changes in release 3.21.11 Changes in release 3.21.10 Changes in release 3.21.9 Changes in release 3.21.8 Changes in release 3.21.7 Changes in release 3.21.6 Changes in release 3.21.5 Changes in release 3.21.4 Changes in release 3.21.3 Changes in release 3.21.2 Changes in release 3.21.0 Changes in release 3.20.x Changes in release 3.20.18 Changes in release 3.20.17 Changes in release 3.20.16 Changes in release 3.20.15 Changes in release 3.20.14 Changes in release 3.20.13 Changes in release 3.20.11 Changes in release 3.20.10 Changes in release 3.20.9 Changes in release 3.20.8 Changes in release 3.20.7 Changes in release 3.20.6 Changes in release 3.20.3 Changes in release 3.20.0 Changes in release 3.19.x Changes in release 3.19.5 Changes in release 3.19.4 Changes in release 3.19.3 Porting to Other Systems Debugging a MySQL server Compiling MYSQL for Debugging Creating Trace Files Debugging mysqld under gdb Using a Stack Trace Using Log Files to Find Cause of Errors in mysqld Making a Test Case If You Experience Table Corruption Debugging a MySQL client The DBUG Package Locking methods Comments about RTS threads Differences between different thread packages Environment Variables MySQL Regular Expressions GNU General Public License SQL command, type and function index Concept Index This is the Reference Manual for the `MySQL Database System'. This version refers to the 4.0.18 version of `MySQL Server' but it is also applicable for any older version (such as 3.23 and 4.0-production) as changes are always indicated. There are also references for version 5.0 (development). General Information ******************* The `MySQL' (R) software delivers a very fast, multi-threaded, multi-user, and robust `SQL' (`Structured Query Language') database server. `MySQL Server' is intended for mission-critical, heavy-load production systems as well as for embedding into mass-deployed software. `MySQL' is a trademark of `MySQL AB'. The `MySQL' software is `Dual Licensed'. Users can choose to use the `MySQL' software as an `Open Source'/`Free Software' product under the terms of the `GNU General Public License' (`http://www.fsf.org/licenses/') or can purchase a standard commercial license from `MySQL AB'. *Note Licensing and Support::. The `MySQL' web site (`http://www.mysql.com/') provides the latest information about the `MySQL' software. The following list describes some sections of particular interest in this manual: * For information about the company behind the `MySQL Database Server', see *Note What is MySQL AB::. * For a discussion about the capabilities of the `MySQL Database Server', see *Note Features::. * For installation instructions, see *Note Installing::. * For tips on porting the `MySQL Database Software' to new architectures or operating systems, see *Note Porting::. * For information about upgrading from a Version 4.0 release, see *Note Upgrading-from-4.0::. * For information about upgrading from a Version 3.23 release, see *Note Upgrading-from-3.23::. * For information about upgrading from a Version 3.22 release, see *Note Upgrading-from-3.22::. * For a tutorial introduction to the `MySQL Database Server', see *Note Tutorial::. * For examples of `SQL' and benchmarking information, see the benchmarking directory (`sql-bench' in the distribution). * For a history of new features and bug fixes, see *Note News::. * For a list of currently known bugs and misfeatures, see *Note Bugs::. * For future plans, see *Note TODO::. * For a list of all the contributors to this project, see *Note Credits::. *Important*: Reports of errors (often called bugs), as well as questions and comments, should be sent to the general MySQL mailing list. *Note Mailing-list::. *Note Bug reports::. The `mysqlbug' script should be used to generate bug reports on Unix. (Windows distributions contain a file `mysqlbug.txt' in the base directory that can be used as a template for a bug report.) For source distributions, the `mysqlbug' script can be found in the `scripts' directory. For binary distributions, `mysqlbug' can be found in the `bin' directory (`/usr/bin' for the `MySQL-server' RPM package). If you have found a sensitive security bug in `MySQL Server', please let us know immediately by sending an email message to . About This Manual ================= This is the `MySQL' reference manual; it documents `MySQL' up to Version 4.0.18. Functional changes are always indicated with reference to the version, so this manual is also suitable if you are using an older version of the `MySQL' software (such as 3.23 or 4.0-production). There are also references for version 5.0 (development). Being a reference manual, it does not provide general instruction on `SQL' or relational database concepts. It also will not teach you how to use your operating system or command line interpreter. As the `MySQL Database Software' is under constant development, the manual is also updated frequently. The most recent version of this manual is available at `http://www.mysql.com/documentation/' in many different formats, including HTML, PDF, and Windows HLP versions. The primary document is the Texinfo file. The HTML version is produced automatically using a modified version of `texi2html'. The plain text and Info versions are produced with `makeinfo'. The PostScript version is produced using `texi2dvi' and `dvips'. The PDF version is produced with `pdftex'. The index can assist you in finding information in the manual. For online use, you can try the searchable version of the manual available at `http://www.mysql.com/doc/'. If you have any suggestions concerning additions or corrections to this manual, please send them to the documentation team at . This manual was initially written by David Axmark and Michael (Monty) Widenius. It is now maintained by the MySQL Documentation Team, consisting of Arjen Lentz, Paul DuBois and Stefan Hinz. For the many other contributors, see *Note Credits::. The copyright (2004) to this manual is owned by the Swedish company `MySQL AB'. *Note Copyright::. Conventions Used in This Manual ------------------------------- This manual uses certain typographical conventions: `constant' Constant-width font is used for command names and options; SQL statements; database, table, and column names; C and Perl code; and environment variables. Example: "To see how `mysqladmin' works, invoke it with the `--help' option." `filename' Constant-width font with surrounding quotes is used for filenames and pathnames. Example: "The distribution is installed under the `/usr/local/' directory." `c' Constant-width font with surrounding quotes is also used to indicate character sequences. Example: "To specify a wildcard, use the `%' character." _italic_ Italic font is used for emphasis, _like this_. *boldface* Boldface font is used in table headings and to convey *especially strong emphasis*. When commands are shown that are meant to be executed by a particular program, the program is indicated by a prompt shown before the command. For example, `shell>' indicates a command that you execute from your login shell, and `mysql>' indicates a 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' or `csh'. On Windows, the equivalent is `command.com' or `cmd.exe', typically run in a Windows console. Note that to enter a command or statement from an example, you do not type the prompt shown in the example. Commands to set shell variables are shown using Bourne shell syntax. If you are using `csh' or `tcsh', you will need to issue commands somewhat differently. For example, the sequence to set an environment variable and run a command looks like this in Bourne shell syntax: shell> VARNAME=value some_command For `csh' or `tcsh', you would execute the sequence like this: shell> setenv VARNAME value shell> some_command Database, table, and column names must often be substituted into commands. To indicate that such substitution is necessary, this manual uses `db_name', `tbl_name', and `col_name'. For example, you might see a statement like this: mysql> SELECT col_name FROM db_name.tbl_name; This means that if you were to enter a similar statement, you would supply your own database, table, and column names, perhaps like this: mysql> SELECT author_name FROM biblio_db.author_list; SQL keywords are not case sensitive and may be written in uppercase or lowercase. This manual uses uppercase. In syntax descriptions, square brackets (`[' and `]') are used to indicate optional words or clauses. For example, in the following statement, `IF EXISTS' is optional: DROP TABLE [IF EXISTS] tbl_name When a syntax element consists of a number of alternatives, the alternatives are separated by vertical bars (`|'). When one member from a set of choices *may* be chosen, the alternatives are listed within square brackets (`[' and `]'): TRIM([[BOTH | LEADING | TRAILING] [remstr] FROM] str) When one member from a set of choices *must* be chosen, the alternatives are listed within braces (`{' and `}'): {DESCRIBE | DESC} tbl_name {col_name | wild} 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] ... Overview of the MySQL Database Management System ================================================ `MySQL', the most popular `Open Source' SQL database management system, is developed, distributed, and supported by `MySQL AB'. `MySQL AB' is a commercial company, founded by the MySQL developers, that builds its business by providing services around the `MySQL' database management system. *Note What is MySQL AB::. The `MySQL' web site (`http://www.mysql.com/') provides the latest information about `MySQL' software and `MySQL AB'. `MySQL' is a database management system. A database is a structured collection of data. It may be anything from a simple shopping list to a picture gallery or the vast amounts of information in a corporate network. To add, access, and process data stored in a computer database, you need a database management system such as `MySQL' Server. Since computers are very good at handling large amounts of data, database management systems play a central role in computing, as stand-alone utilities or as parts of other applications. MySQL is a relational database management system. A relational database stores data in separate tables rather than putting all the data in one big storeroom. This adds speed and flexibility. The `SQL' part of "`MySQL'" stands for "`Structured Query Language'". SQL is the most common 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-99'" refers to the standard released in 1999, and "`SQL:2003'" refers to the next version of the standard. We use the term "`the SQL standard'" to mean the current version of the SQL Standard at any time.) MySQL software is `Open Source'. `Open Source' means that it is possible for anyone to use and modify the software. Anybody can download the `MySQL' software from the Internet and use it without paying anything. If you wish, you may study the source code and change it to suit your needs. The `MySQL' software uses the `GPL' (`GNU General Public License'), `http://www.fsf.org/licenses/', to define what you may and may not do with the software in different situations. If you feel uncomfortable with the `GPL' or need to embed `MySQL' code into a commercial application, you can buy a commercially licensed version from us. *Note MySQL licenses::. Why use the MySQL Database Server? The `MySQL Database Server' is very fast, reliable, and easy to use. If that is what you are looking for, you should give it a try. `MySQL Server' also has a practical set of features developed in close cooperation with our users. You can find a performance comparison of `MySQL Server' with other database managers on our benchmark page. *Note MySQL Benchmarks::. `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. Though under constant development, `MySQL Server' today offers a rich and useful set of functions. Its connectivity, speed, and security make `MySQL Server' highly suited for accessing databases on the Internet. The technical features of MySQL Server 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 a multi-threaded library which you can link into your application to get a smaller, faster, easier-to-manage product. There is a large amount of contributed MySQL software available. It is very likely that you will find that your favorite application or language already supports the `MySQL Database Server'. The official way to pronounce `MySQL' is "My Ess Que Ell" (not "my sequel"), but we don't mind if you pronounce it as "my sequel" or in some other localized way. History of MySQL ---------------- We started out with the intention of using `mSQL' to connect to our tables using our own fast low-level (ISAM) routines. However, after some testing, we came to the conclusion that `mSQL' was not fast enough or flexible enough for our needs. This resulted in a new SQL interface to our database but with almost the same API interface as `mSQL'. This API was designed to allow third-party code that was written for use with `mSQL' to be ported easily for use with `MySQL'. The derivation of the name `MySQL' is not clear. Our base directory and a large number of our libraries and tools have had the prefix "my" for well over 10 years. However, co-founder Monty Widenius's daughter is also named My. Which of the two gave its name to `MySQL' is still a mystery, even for us. The name of the MySQL Dolphin (our logo) is `Sakila'. `Sakila' was chosen by the founders of MySQL AB from a huge list of names suggested by users in our "Name the Dolphin" contest. The winning name was submitted by Ambrose Twebaze, an open source software developer from Swaziland, Africa. According to Ambrose, the name Sakila has its roots in SiSwati, the local language of Swaziland. Sakila is also the name of a town in Arusha, Tanzania, near Ambrose's country of origin, Uganda. The Main Features of MySQL -------------------------- The following list describes some of the important characteristics of the `MySQL Database Software'. *Note MySQL 4.0 Nutshell::. Internals and Portability * Written in C and C++. * Tested with a broad range of different compilers. * Works on many different platforms. *Note Which OS::. * Uses GNU Automake, Autoconf, and Libtool for portability. * APIs for C, C++, Eiffel, Java, Perl, PHP, Python, Ruby, and Tcl are available. *Note Clients::. * Fully multi-threaded using kernel threads. This means it can easily use multiple CPUs if they are available. * Provides transactional and non-transactional storage engines. * Uses very fast B-tree disk tables (`MyISAM') with index compression. * Relatively easy to add another storage engine. This is useful if you want to add an SQL interface to an in-house database. * A very fast thread-based memory allocation system. * Very fast joins using an optimized one-sweep multi-join. * In-memory hash tables which are used as temporary tables. * SQL functions are implemented using a highly optimized class library and should be as fast as possible. Usually there is no memory allocation at all after query initialization. * The `MySQL' code is tested with Purify (a commercial memory leakage detector) as well as with Valgrind, a `GPL' tool (`http://developer.kde.org/~sewardj/'). * The server is available as a separate program for use in a client/server networked environment. It is also available as a library that can be embedded (linked) into standalone applications. Such applications can be used in isolation or in environments where no network is available. Column Types * Many column types: signed/unsigned integers 1, 2, 3, 4, and 8 bytes long, `FLOAT', `DOUBLE', `CHAR', `VARCHAR', `TEXT', `BLOB', `DATE', `TIME', `DATETIME', `TIMESTAMP', `YEAR', `SET', `ENUM', and OpenGIS geometry types. *Note Column types::. * Fixed-length and variable-length records. Commands and Functions * Full operator and function support in the `SELECT' and `WHERE' clauses of queries. For example: mysql> SELECT CONCAT(first_name, ' ', last_name) -> FROM tbl_name -> WHERE income/dependents > 10000 AND age > 30; * Full support for SQL `GROUP BY' and `ORDER BY' clauses. Support for group functions (`COUNT()', `COUNT(DISTINCT ...)', `AVG()', `STD()', `SUM()', `MAX()', `MIN()', and `GROUP_CONCAT()'). * Support for `LEFT OUTER JOIN' and `RIGHT OUTER JOIN' with both standard SQL and ODBC syntax. * Support for aliases on tables and columns as required by SQL-92. * `DELETE', `INSERT', `REPLACE', and `UPDATE' return the number of rows that were changed (affected). It is possible to return the number of rows matched instead by setting a flag when connecting to the server. * The `MySQL'-specific `SHOW' command can be used to retrieve information about databases, tables, and indexes. The `EXPLAIN' command can be used to determine how the 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. *Note Reserved words::. * You can mix tables from different databases in the same query (as of Version 3.22). Security * A privilege and password system that is very flexible and secure, and allows host-based verification. Passwords are secure because all password traffic is encrypted when you connect to a server. Scalability and Limits * Handles large databases. We use `MySQL Server' with databases that contain 50 million records. We also know of users that use `MySQL Server' with 60,000 tables and about 5,000,000,000 rows. * Up to 32 indexes per table are allowed. Each index may consist of 1 to 16 columns or parts of columns. The maximum index width is 500 bytes (this may be changed when compiling `MySQL Server'). An index may use a prefix of a `CHAR' or `VARCHAR' column. Connectivity * Clients may connect to the `MySQL' server using TCP/IP sockets on any platform. On Windows systems in the NT family (NT, 2000, or XP), clients may connect using named pipes. On Unix systems, clients may connect using Unix domain socket files. * The Connector/ODBC interface provides `MySQL' support for client programs that use ODBC (Open-DataBase-Connectivity) connections. For example, you can use MS Access to connect to your `MySQL' server. Clients may be run on Windows or Unix. Connector/ODBC source is available. All ODBC 2.5 functions are supported, as are many others. *Note ODBC::. * The Connector/JDBC interface provides `MySQL' support for Java client programs that use JDBC connections. Clients may be run on Windows or Unix. Connector/JDBC source is available. *Note Java::. Localization * The server can provide error messages to clients in many languages. *Note Languages::. * Full support for several different character sets, including ISO-8859-1 (Latin1), german, big5, ujis, and more. For example, the Scandinavian characters `a^', `a"' and `o"' are allowed in table and column names. Unicode support is available as of `MySQL' 4.1. * All data is saved in the chosen character set. All comparisons for normal string columns are case-insensitive. * Sorting is done according to the chosen character set (the Swedish way by default). It is possible to change this when the `MySQL' server is started. To see an example of very advanced sorting, look at the Czech sorting code. `MySQL Server' supports many different character sets that can be specified at compile and runtime. Clients and Tools * The MySQL server has built-in support for SQL statements to check, 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. *Note MySQL Database Administration::. * All `MySQL' programs can be invoked with the `--help' or `-?' options to obtain online assistance. 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 list, which is very active in identifying problems as well as reporting types of use. The original code stems back to the early 1980s. It provides a stable code base, and the ISAM table format used by the original storage engine remains backward-compatible. At TcX, the predecessor of `MySQL AB', `MySQL' code has worked in projects since mid-1996, without any problems. When the `MySQL Database Software' initially was released to a wider public, our new users quickly found some pieces of "untested code". Each new release since then has had fewer portability problems (even though each new release has also had many new features). Each release of the `MySQL Server' has been usable. Problems have occurred only when users try code from the "gray zones." Naturally, new users don't know what the gray zones are; this section therefore attempts to document those areas that are currently known. The descriptions mostly deal with Version 3.23 and 4.0 of `MySQL Server'. All known and reported bugs are fixed in the latest version, with the exception of those listed in the bugs section, which are design-related. *Note Bugs::. The `MySQL Server' design is multi-layered with independent modules. Some of the newer modules are listed here with an indication of how well-tested each of them is: *Replication -- Gamma* Large groups of servers using replication are in production use, with good results. Work on enhanced replication features is continuing in `MySQL' 5.x. *`InnoDB' tables -- Stable (in 3.23 from 3.23.49)* The `InnoDB' transactional storage engine has been declared stable in the `MySQL' 3.23 tree, starting from version 3.23.49. `InnoDB' is being used in large, heavy-load production systems. *`BDB' tables -- Gamma* The `Berkeley DB' code is very stable, but we are still improving the `BDB' transactional storage engine interface in `MySQL Server', so it will take some time before this is as well tested as the other table types. *Full-text searches -- Beta* Full-text searching works but is not yet widely used. Important enhancements have been implemented in `MySQL' 4.0. *`Connector/ODBC 3.51' (uses ODBC SDK 3.51) -- Stable* In wide production use. Some issues brought up appear to be application-related and independent of the ODBC driver or underlying database server. *Automatic recovery of `MyISAM' tables -- Gamma* This status applies only to the new code in the `MyISAM' storage engine that checks if the table was closed properly on open and executes an automatic check/repair of the table if it wasn't. *Bulk-insert -- Alpha* New feature in `MyISAM' tables in `MySQL' 4.0 for faster insert of many rows. *Locking -- Gamma* This is very system-dependent. On some systems there are big problems using standard operating system locking (`fcntl()'). In these cases, you should run `mysqld' with the `--skip-external-locking' flag. Problems are known to occur on some Linux systems, and on SunOS when using NFS-mounted filesystems. Paying customers receive high-quality support directly from MySQL AB. MySQL AB also provides the MySQL mailing list as a community resource where anyone may ask questions. Bugs are usually fixed right away with a patch. For serious bugs, there is almost always a new release. How Big MySQL Tables Can Be --------------------------- `MySQL' Version 3.22 had a 4 GB (4 gigabyte) limit on table size. With the `MyISAM' storage engine in `MySQL' Version 3.23, the maximum table size was increased to 8 million terabytes (2 ^ 63 bytes). With this larger allowed table size, the maximum effective table size for `MySQL' databases now normally is determined by operating system constraints on file sizes, not by MySQL internal limits. The `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 64 TB. The following table lists some examples of operating system file-size limits: *Operating System* *File-Size Limit* Linux-Intel 32-bit 2 GB, much more when using LFS Linux-Alpha 8 TB (?) Solaris 2.5.1 2 GB (4GB possible with patch) Solaris 2.6 4 GB (can be changed with flag) Solaris 2.7 Intel 4 GB Solaris 2.7 512 GB UltraSPARC On Linux 2.2, you can get `MyISAM' tables larger than 2 GB in size by using the LFS patch for the ext2 filesystem. On Linux 2.4, patches also exist for ReiserFS to get support for big files. Most current Linux distributions are based on kernel 2.4 and already include all the required Large File Support (LFS) patches. However, the maximum available file size still depends on several factors, one of them being the file system used to store MySQL tables. For a very detailed overview about LFS in Linux, have a look at Andreas Jaeger's "Large File Support in Linux" page at . By default, `MySQL' creates `MyISAM' tables with an internal structure that allows a maximum size of about 4 GB. You can check the maximum table size for a table with the `SHOW TABLE STATUS' command or with the `myisamchk -dv table_name'. *Note `SHOW': SHOW. If you need a `MyISQM' table that will be larger than 4 GB in size (and your operating system supports large files), the `CREATE TABLE' statement allows `AVG_ROW_LENGTH' and `MAX_ROWS' options. *Note `CREATE TABLE': CREATE TABLE. You can also change these options with `ALTER TABLE' after the table has been created, to increase the table's maximum allowable size. *Note `ALTER TABLE': ALTER TABLE. 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. *Note `myisampack': myisampack. * Another way to get around the operating system file limit for `MyISAM' datafiles is by using the `RAID' options. *Note `CREATE TABLE': CREATE TABLE. * `MySQL' includes a `MERGE' library that allows you to handle a collection of `MyISAM' tables that have identical structure as a single `MERGE' table. *Note `MERGE' tables: MERGE. 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' Version 3.22 and later, the `YEAR' column type can store years `0' and `1901' to `2155' in one byte and display them using two or four digits. All 2-digit years are considered to be in the range `1970' to `2069', which means that if you store `01' in a `YEAR' column, `MySQL Server' treats it as `2001'. The following simple demonstration illustrates that `MySQL Server' doesn't have any problems with dates until after the year 2030: mysql> DROP TABLE IF EXISTS y2k; Query OK, 0 rows affected (0.01 sec) mysql> CREATE TABLE y2k (date DATE, -> date_time DATETIME, -> time_stamp TIMESTAMP); Query OK, 0 rows affected (0.00 sec) mysql> INSERT INTO y2k VALUES -> ('1998-12-31','1998-12-31 23:59:59',19981231235959), -> ('1999-01-01','1999-01-01 00:00:00',19990101000000), -> ('1999-09-09','1999-09-09 23:59:59',19990909235959), -> ('2000-01-01','2000-01-01 00:00:00',20000101000000), -> ('2000-02-28','2000-02-28 00:00:00',20000228000000), -> ('2000-02-29','2000-02-29 00:00:00',20000229000000), -> ('2000-03-01','2000-03-01 00:00:00',20000301000000), -> ('2000-12-31','2000-12-31 23:59:59',20001231235959), -> ('2001-01-01','2001-01-01 00:00:00',20010101000000), -> ('2004-12-31','2004-12-31 23:59:59',20041231235959), -> ('2005-01-01','2005-01-01 00:00:00',20050101000000), -> ('2030-01-01','2030-01-01 00:00:00',20300101000000), -> ('2050-01-01','2050-01-01 00:00:00',20500101000000); Query OK, 13 rows affected (0.01 sec) Records: 13 Duplicates: 0 Warnings: 0 mysql> SELECT * FROM y2k; +------------+---------------------+----------------+ | date | date_time | time_stamp | +------------+---------------------+----------------+ | 1998-12-31 | 1998-12-31 23:59:59 | 19981231235959 | | 1999-01-01 | 1999-01-01 00:00:00 | 19990101000000 | | 1999-09-09 | 1999-09-09 23:59:59 | 19990909235959 | | 2000-01-01 | 2000-01-01 00:00:00 | 20000101000000 | | 2000-02-28 | 2000-02-28 00:00:00 | 20000228000000 | | 2000-02-29 | 2000-02-29 00:00:00 | 20000229000000 | | 2000-03-01 | 2000-03-01 00:00:00 | 20000301000000 | | 2000-12-31 | 2000-12-31 23:59:59 | 20001231235959 | | 2001-01-01 | 2001-01-01 00:00:00 | 20010101000000 | | 2004-12-31 | 2004-12-31 23:59:59 | 20041231235959 | | 2005-01-01 | 2005-01-01 00:00:00 | 20050101000000 | | 2030-01-01 | 2030-01-01 00:00:00 | 20300101000000 | | 2050-01-01 | 2050-01-01 00:00:00 | 00000000000000 | +------------+---------------------+----------------+ 13 rows in set (0.00 sec) The final `TIMESTAMP' column value is zero because the final year (`2050') exceeds the `TIMESTAMP' maximum. The `TIMESTAMP' datatype, which is used to store the current time, supports values that range from `19700101000000' to `20300101000000' on 32-bit machines (signed value). On 64-bit machines, `TIMESTAMP' handles values up to `2106' (unsigned value). The example also shows that the `DATE' and `DATETIME' datatypes have no problems with the dates used. They handle dates through the year `9999'. Although `MySQL Server' itself is Y2K-safe, you may run into problems if you use it with applications that are not Y2K-safe. For example, many old applications store or manipulate years using 2-digit values (which are ambiguous) rather than 4-digit values. This problem may be compounded by applications that use values such as `00' or `99' as "missing" value indicators. Unfortunately, these problems may be difficult to fix because different 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 *Note Y2K issues:: for `MySQL Server''s rules for dealing with ambiguous date input data that contains 2-digit year values. Overview of MySQL AB ==================== `MySQL AB' is the company of the `MySQL' founders and main developers. `MySQL AB' was originally established in Sweden by David Axmark, Allan Larsson, and Michael "Monty" Widenius. The developers of the `MySQL' server are all employed by the company. We are a virtual organization with people in a dozen countries around the world. We communicate extensively over the Internet every day with one another and with our users, supporters, and partners. We are dedicated to developing the `MySQL' database software and promoting it to new users. `MySQL AB' owns the copyright to the `MySQL' source code, the `MySQL' logo and trademark, and this manual. *Note What-is::. The `MySQL' core values show our dedication to `MySQL' and `Open Source'. We want the `MySQL Database Software' to be: * The best and the most widely used database in the world * Available to, and affordable by all * Easy to use * Continuously improving while remaining fast and safe * Fun to use and improve * Free from bugs `MySQL AB' and the people at `MySQL AB': * Promote `Open Source' philosophy and support the `Open Source' community * Aim to be good citizens * Prefer partners that share our values and mind-set * Answer email and provide support * Are a virtual company, networking with others * Work against software patents The `MySQL' web site (`http://www.mysql.com/') provides the latest information about `MySQL' and `MySQL AB'. By the way, the "AB" part of the company name is the acronym for the Swedish "aktiebolag", or "stock company." It translates to "MySQL, Inc." In fact, MySQL Inc. and MySQL GmbH are examples of MySQL AB subsidiaries. They are located in the US and Germany, respectively. The Business Model and Services of MySQL AB ------------------------------------------- One of the most common questions we encounter is: "_How can you make a living from something you give away for free?_" This is how: * `MySQL AB' makes money on support, services, commercial licenses, and royalties. * We use these revenues to fund product development and to expand the `MySQL' business. The company has been profitable since its inception. In October 2001, we accepted venture financing from leading Scandinavian investors and a handful of business angels. This investment is used to solidify our business model and build a basis for sustainable growth. Support ....... `MySQL AB' is run and owned by the founders and main developers of the `MySQL' database. The developers are committed to providing support to customers and other users in order to stay in touch with their needs and problems. All our support is provided by qualified developers. Really tricky questions are answered by Michael `Monty' Widenius, principal author of the `MySQL Server'. *Note Support::. For more information and ordering support at various levels, see `http://www.mysql.com/support/' or contact our sales staff at . Training and Certification .......................... `MySQL AB' delivers `MySQL' and related training worldwide. We offer both open courses and in-house courses tailored to the specific needs of your company. `MySQL Training' is also available through our partners, the `Authorized MySQL Training Centers'. Our training material uses the same example databases used in our documentation and our sample applications, and is always updated to reflect the latest `MySQL' version. Our trainers are backed by the development team to guarantee the quality of the training and the continuous development of the course material. This also ensures that no questions raised during the courses remain unanswered. Attending our training courses will enable you to achieve your `MySQL' application goals. You will also: * Save time. * Improve the performance of your applications. * Reduce or eliminate the need for additional hardware, decreasing cost. * Enhance security. * Increase customers' and co-workers' satisfaction. * Prepare yourself for `MySQL Certification'. If you are interested in our training as a potential participant or as a training partner, please visit the training section at `http://www.mysql.com/training/' or contact us at: . For details about the `MySQL Certification Program', please see `http://www.mysql.com/certification/'. Consulting .......... `MySQL AB' and its `Authorized Partners' offer consulting services to users of `MySQL Server' and to those who embed `MySQL Server' in their own software, all over the world. Our consultants can help you design and tune your databases, construct efficient queries, tune your platform for optimal performance, resolve migration issues, set up replication, build robust transactional applications, and more. We also help customers embed `MySQL Server' in their products and applications for large-scale deployment. Our consultants work in close collaboration with our development team, which ensures the technical quality of our professional services. Consulting assignments range from 2-day power-start sessions to projects that span weeks and months. Our expertise not only covers `MySQL Server'--it also extends into programming and scripting languages such as PHP, Perl, and more. If you are interested in our consulting services or want to become a consulting partner, please visit the consulting section of our web site at `http://www.mysql.com/consulting/' or contact our consulting staff at . Commercial Licenses ................... The `MySQL' database is released under the `GNU General Public License' (`GPL'). This means that the `MySQL' software can be used free of charge under the `GPL'. If you do not want to be bound by the `GPL' terms (such as the requirement that your application must also be `GPL'), you may purchase a commercial license for the same product from `MySQL AB'; see `http://www.mysql.com/products/pricing.html'. Since `MySQL AB' owns the copyright to the `MySQL' source code, we are able to employ `Dual Licensing', which means that the same product is available under `GPL' and under a commercial license. This does not in any way affect the `Open Source' commitment of `MySQL AB'. For details about when a commercial license is required, please see *Note MySQL licenses::. We also sell commercial licenses of third-party `Open Source GPL' software that adds value to `MySQL Server'. A good example is the `InnoDB' transactional storage engine that offers `ACID' support, row-level locking, crash recovery, multi-versioning, foreign key support, and more. *Note InnoDB::. Partnering .......... `MySQL AB' has a worldwide partner program that covers training courses, consulting and support, publications, plus reselling and distributing `MySQL' and related products. `MySQL AB Partners' get visibility on the `http://www.mysql.com/' web site and the right to use special versions of the `MySQL' trademarks to identify their products and promote their business. If you are interested in becoming a `MySQL AB Partner', please email . The word `MySQL' and the `MySQL' dolphin logo are trademarks of `MySQL AB'. *Note MySQL AB Logos and Trademarks::. These trademarks represent a significant value that the `MySQL' founders have built over the years. The `MySQL' web site (`http://www.mysql.com/') is popular among developers and users. In December 2003, we served 16 million page views. Our visitors represent a group that makes purchase decisions and recommendations for both software and hardware. Twelve percent of our visitors authorize purchase decisions, and only nine percent are not involved in purchase decisions at all. More than 65% have made one or more online business purchases within the last half-year, and 70% plan to make one in the next few months. Contact Information ------------------- The `MySQL' web site (`http://www.mysql.com/') provides the latest information about `MySQL' and `MySQL AB'. For press services and inquiries not covered in our News releases (`http://www.mysql.com/news/'), please send email to . If you have a valid support contract with `MySQL AB', you will get timely, precise answers to your technical questions about the `MySQL' software. For more information, see *Note Support::. On our web site, see `http://www.mysql.com/support/', or send an email message to . For information about `MySQL' training, please visit the training section at `http://www.mysql.com/training/'. If you have restricted access to the Internet, please contact the `MySQL AB' training staff via email at . *Note Business Services Training::. For information on the `MySQL Certification Program', please see `http://www.mysql.com/certification/'. *Note Business Services Training::. If you're interested in consulting, please visit the consulting section of our web site at `http://www.mysql.com/consulting/'. If you have restricted access to the Internet, please contact the `MySQL AB' consulting staff via email at . *Note Business Services Consulting::. Commercial licenses may be purchased online at `https://order.mysql.com/'. There you will also find information on how to fax your purchase order to `MySQL AB'. More information about licensing can be found at `http://www.mysql.com/products/pricing.html'. If you have questions regarding licensing or you want a quote for a high-volume license deal, please fill in the contact form on our web site (`http://www.mysql.com/') or send email to (for licensing questions) or to (for sales inquiries). *Note MySQL licenses::. If you represent a business that is interested in partnering with `MySQL AB', please send email to . *Note Business Services Partnering::. For more information on the `MySQL' trademark policy, refer to `http://www.mysql.com/company/trademark.html' or send email to . *Note MySQL AB Logos and Trademarks::. If you are interested in any of the `MySQL AB' jobs listed in our jobs section (`http://www.mysql.com/company/jobs/'), please send email to . Please do not send your CV as an attachment, but rather as plain text at the end of your email message. For general discussion among our many users, please direct your attention to the appropriate mailing list. *Note Questions::. Reports of errors (often called bugs), as well as questions and comments, should be sent to the general MySQL mailing list. *Note Mailing-list::. If you have found a sensitive security bug in `MySQL Server', please let us know immediately by sending an email message to . *Note Bug reports::. If you have benchmark results that we can publish, please contact us via email at . If you have suggestions concerning additions or corrections to this manual, please send them to the manual team via email at . For questions or comments about the workings or content of the `MySQL' web site (`http://www.mysql.com/'), please send email to . `MySQL AB' has a privacy policy, which can be read at `http://www.mysql.com/company/privacy.html'. For any queries regarding this policy, please send email to . For all other inquires, please send an email to . MySQL Support and Licensing =========================== This section describes `MySQL' support and licensing arrangements. Support Offered by MySQL AB --------------------------- Technical support from `MySQL AB' means individualized answers to your unique problems direct from the software engineers who code the `MySQL' database engine. We try to take a broad and inclusive view of technical support. Almost any problem involving `MySQL' software is important to us if it's important to you. Typically customers seek help on how to get different commands and utilities to work, remove performance bottlenecks, restore crashed systems, understand the impact of operating system or networking issues on `MySQL', set up best practices for backup and recovery, utilize APIs, and so on. Our support covers only the `MySQL' server and our own utilities, not third-party products that access the `MySQL' server, though we try to help with these where we can. Detailed information about our various support options is given at `http://www.mysql.com/support/', where support contracts can also be ordered online. If you have restricted access to the Internet, please contact our sales staff via email at . Technical support is like life insurance. You can live happily without it for years. However, when your hour arrives, it becomes critically important, but it's too late to buy it. If you use `MySQL Server' for important applications and encounter sudden difficulties, it may be too time consuming to figure out all the answers yourself. You may need immediate access to the most experienced `MySQL' troubleshooters available, those employed by `MySQL AB'. Copyrights and Licenses Used by MySQL ------------------------------------- `MySQL AB' owns the copyright to the `MySQL' source code, the `MySQL' logos and trademarks and this manual. *Note What is MySQL AB::. Several different licenses are relevant to the `MySQL' distribution: 1. All the `MySQL'-specific source in the server, the `mysqlclient' library and the client, as well as the `GNU' `readline' library is covered by the `GNU General Public License'. *Note GPL license::. The text of this license can be found as the file `COPYING' in the distribution. 2. The `GNU' `getopt' library is covered by the `GNU Lesser General Public License'. See . 3. Some parts of the source (the `regexp' library) are covered by a Berkeley-style copyright. 4. Older versions of `MySQL' (3.22 and earlier) are subject to a stricter license (`http://www.mysql.com/products/mypl.html'). See the documentation of the specific version for information. 5. The `MySQL' reference manual is currently *not* distributed under a `GPL'-style license. Use of the manual is subject to the following terms: * Conversion to other formats is allowed, but the actual content may not be altered or edited in any way. * You may create a printed copy for your own personal use. * For all other uses, such as selling printed copies or using (parts of) the manual in another publication, prior written agreement from `MySQL AB' is required. Please send an email message to for more information or if you are interested in doing a translation. For information about how the `MySQL' licenses work in practice, please refer to *Note MySQL licenses::. Also see *Note MySQL AB Logos and Trademarks::. MySQL Licenses -------------- The `MySQL' software is released under the `GNU General Public License' (`GPL'), which is probably the best known `Open Source' license. The formal terms of the `GPL' license can be found at `http://www.fsf.org/licenses/'. See also `http://www.fsf.org/licenses/gpl-faq.html' and `http://www.gnu.org/philosophy/enforcing-gpl.html'. Since the `MySQL' software is released under the `GPL', it may often be used for free, but for certain uses you may want or need to buy commercial licenses from `MySQL AB' at `https://order.mysql.com/'. See `http://www.mysql.com/products/licensing.html' for more information. Older versions of `MySQL' (3.22 and earlier) are subject to a stricter license (`http://www.mysql.com/products/mypl.html'). See the documentation of the specific version for information. Please note that the use of the `MySQL' software under commercial license, `GPL', or the old `MySQL' license does not automatically give you the right to use `MySQL AB' trademarks. *Note MySQL AB Logos and Trademarks::. Using the MySQL Software Under a Commercial License ................................................... The `GPL' license is contagious in the sense that when a program is linked to a `GPL' program all the source code for all the parts of the resulting product must also be released under the `GPL'. If you do not follow this `GPL' requirement, you break the license terms and forfeit your right to use the `GPL' program altogether. You also risk damages. You need a commercial license: * When you link a program with any `GPL' code from the `MySQL' software and don't want the resulting product to be licensed under `GPL', perhaps because you want to build a commercial product or keep the added non-`GPL' code closed source for other reasons. When purchasing commercial licenses, you are not using the `MySQL' software under `GPL' even though it's the same code. * When you distribute a non-`GPL' application that *only* works with the `MySQL' software and ship it with the `MySQL' software. This type of solution is considered to be linking even if it's done over a network. * When you distribute copies of the `MySQL' software without providing the source code as required under the `GPL' license. * When you want to support the further development of the `MySQL' database even if you don't formally need a commercial license. Purchasing support directly from `MySQL AB' is another good way of contributing to the development of the `MySQL' software, with immediate advantages for you. *Note Support::. If you require a license, you will need one for each installation of the `MySQL' software. This covers any number of CPUs on a machine, and there is no artificial limit on the number of clients that connect to the server in any way. For commercial licenses, please visit our website at `http://www.mysql.com/products/licensing.html'. For support contracts, see `http://www.mysql.com/support/'. If you have special needs or you have restricted access to the Internet, please contact our sales staff via email at . Using the MySQL Software for Free Under GPL ........................................... You can use the `MySQL' software for free under the `GPL' if you adhere to the conditions of the `GPL'. For additional details, including answers to common questions about the `GPL', see the generic FAQ from the Free Software Foundation at `http://www.fsf.org/licenses/gpl-faq.html'. Common uses of the `GPL' include: * When you distribute both your own application and the `MySQL' source code under the `GPL' with your product. * When you distribute the `MySQL' source code bundled with other programs that are not linked to or dependent on the `MySQL' system for their functionality even if you sell the distribution commercially. This is called mere aggregation in the `GPL' license. * When you are not distributing *any* part of the `MySQL' system, you can use it for free. * When you are an Internet Service Provider (ISP), offering web hosting with `MySQL' servers for your customers. We encourage people to use ISPs that have MySQL support, as this will give them the confidence that their ISP will, in fact, have the resources to solve any problems they may experience with the `MySQL' installation. Even if an ISP does not have a commercial license for `MySQL Server', their customers should at least be given read access to the source of the `MySQL' installation so that the customers can verify that it is correctly patched. * When you use the `MySQL' database software in conjunction with a web server, you do not need a commercial license (so long as it is not a product you distribute). This is true even if you run a commercial web server that uses `MySQL Server', because you are not distributing any part of the `MySQL' system. However, in this case we would like you to purchase `MySQL' support because the `MySQL' software is helping your enterprise. If your use of `MySQL' database software does not require a commercial license, we encourage you to purchase support from `MySQL AB' anyway. This way you contribute toward `MySQL' development and also gain immediate advantages for yourself. *Note Support::. If you use the `MySQL' database software in a commercial context such that you profit by its use, we ask that you further the development of the `MySQL' software by purchasing some level of support. We feel that if the `MySQL' database helps your business, it is reasonable to ask that you help `MySQL AB'. (Otherwise, if you ask us support questions, you are not only using for free something into which we've put a lot a work, you're asking us to provide free support, too.) MySQL AB Logos and Trademarks ----------------------------- Many users of the `MySQL' database want to display the `MySQL AB' dolphin logo on their web sites, books, or boxed products. We welcome and encourage this, although it should be noted that the word `MySQL' and the `MySQL' dolphin logo are trademarks of `MySQL AB' and may only be used as stated in our trademark policy at `http://www.mysql.com/company/trademark.html'. The Original MySQL Logo ....................... The `MySQL' dolphin logo was designed by the Finnish advertising agency Priority in 2001. The dolphin was chosen as a suitable symbol for the `MySQL' database management system, which is like a smart, fast, and lean animal, effortlessly navigating oceans of data. We also happen to like dolphins. The original `MySQL' logo may only be used by representatives of `MySQL AB' and by those having a written agreement allowing them to do so. MySQL Logos that may be Used Without Written Permission ....................................................... We have designed a set of special _Conditional Use_ logos that may be downloaded from our web site at `http://www.mysql.com/press/logos.html' and used on third-party web sites without written permission from `MySQL AB'. The use of these logos is not entirely unrestricted but, as the name implies, subject to our trademark policy that is also available on our web site. You should read through the trademark policy if you plan to use them. The requirements are basically as follows: * Use the logo you need as displayed on the `http://www.mysql.com/' site. You may scale it to fit your needs, but may not change colors or design, or alter the graphics in any way. * Make it evident that you, and not `MySQL AB', are the creator and owner of the site that displays the `MySQL' trademark. * Don't use the trademark in a way that is detrimental to `MySQL AB' or to the value of `MySQL AB' trademarks. We reserve the right to revoke the right to use the `MySQL AB' trademark. * If you use the trademark on a web site, make it clickable, leading directly to `http://www.mysql.com/'. * If you use the `MySQL' database under `GPL' in an application, your application must be `Open Source' and must be able to connect to a `MySQL' server. Contact us via email at to inquire about special arrangements to fit your needs. When You Need Written Permission to Use MySQL Logos ................................................... You need written permission from `MySQL AB' before using `MySQL' logos in the following cases: * When displaying any `MySQL AB' logo anywhere except on your web site. * When displaying any `MySQL AB' logo except the _Conditional Use_ logos mentioned previously on web sites or elsewhere. Due to legal and commercial reasons we monitor the use of MySQL trademarks on products, books, and other items. We usually require a fee for displaying `MySQL AB' logos on commercial products, since we think it is reasonable that some of the revenue is returned to fund further development of the `MySQL' database. MySQL AB Partnership Logos .......................... `MySQL' partnership logos may be used only by companies and persons having a written partnership agreement with `MySQL AB'. Partnerships include certification as a `MySQL' trainer or consultant. For more information, please see *Note Partnering: Business Services Partnering. Using the Word `MySQL' in Printed Text or Presentations ....................................................... `MySQL AB' welcomes references to the `MySQL' database, but it should be noted that the word `MySQL' is a trademark of `MySQL AB'. Because of this, you must append the trademark symbol (`TM') to the first or most prominent use of the word `MySQL' in a text and, where appropriate, state that `MySQL' is a trademark of `MySQL AB'. For more information, please refer to our trademark policy at `http://www.mysql.com/company/trademark.html'. Using the Word `MySQL' in Company and Product Names ................................................... Use of the word `MySQL' in product or company names or in Internet domain names is not allowed without written permission from `MySQL AB'. MySQL Development Roadmap ========================= This section provides a snapshot of the MySQL development roadmap, including major features implemented or planned for MySQL 4.0, 4.1, 5.0, and 5.1. The following sections provide information for each release series. The production release series is MySQL 4.0, which was declared stable for production use as of Version 4.0.12, released in March 2003. This means that future 4.0 development will be limited only to making bug fixes. For the older MySQL 3.23 series, only critical bug fixes will be made. Active MySQL development currently is taking place in the MySQL 4.1 and 5.0 release series. This means that new features are being added to MySQL 4.1 and MySQL 5.0. Both 4.1 and 5.0 are available now in alpha status. Before upgrading from one release series to the next, please see the notes at *Note Upgrade::. Plans for some of the most requested features are summarized in the following table. *Feature* *MySQL version* Unions 4.0 Subqueries 4.1 R-trees 4.1 (for `MyISAM' tables) Stored procedures 5.0 Views 5.0 or 5.1 Cursors 5.0 Foreign keys 5.1 (already implemented in 3.23 for `InnoDB') Triggers 5.1 Full outer join 5.1 Constraints 5.1 MySQL 4.0 in a Nutshell ----------------------- Long awaited by our users, MySQL Server 4.0 is now available in production status. MySQL 4.0 is available for download from `http://www.mysql.com/' and from our mirrors. MySQL 4.0 has been tested by a large number of users and is in production use at many large sites. The major new features of MySQL Server 4.0 are geared toward our existing business and community users, enhancing the MySQL database software as the solution for mission-critical, heavy-load database systems. Other new features target the users of embedded databases. Features Available in MySQL 4.0 ............................... Speed enhancements * MySQL 4.0 has a query cache that can give a huge speed boost to applications with repetitive queries. *Note Query Cache::. * Version 4.0 further increases the speed of MySQL Server in a number of areas, such as bulk `INSERT' statements, searching on packed indexes, full-text searching (using `FULLTEXT' indexes), and `COUNT(DISTINCT)'. Embedded MySQL Server introduced * The new Embedded Server library can easily be used to create standalone and embedded applications. The embedded server provides an alternative to using MySQL in a client/server environment. *Note Nutshell Embedded MySQL::. InnoDB storage engine as standard * The `InnoDB' storage engine is now offered as a standard feature of the `MySQL' server. This means full support for ACID transactions, foreign keys with cascading `UPDATE' and `DELETE', and row-level locking are now standard features. *Note `InnoDB': InnoDB. New functionality * The enhanced `FULLTEXT' search properties of MySQL Server 4.0 enables `FULLTEXT' indexing of large text masses with both binary and natural-language searching logic. You can customize minimal word length and define your own stop word lists in any human language, enabling a new set of applications to be built with MySQL Server. *Note Fulltext Search::. Standards compliance, portability, and migration * Many users will also be happy to learn that MySQL Server now supports the `UNION' statement, a long-awaited standard SQL feature. * MySQL now runs natively on the Novell NetWare 6.0 platform. *Note NetWare installation::. * Features to simplify migration from other database systems to MySQL Server include `TRUNCATE TABLE' (as in Oracle). Internationalization * Our German, Austrian, and Swiss users will note that `MySQL' now supports a new character set, `latin1_de', which ensures that the _German sorting order_ sorts words with umlauts in the same order as do German telephone books. Usability enhancements In the process of implementing features for new users, we have not forgotten requests from our loyal community of existing users. * Most `mysqld' parameters (startup options) can now be set without taking down the server. This is a convenient feature for database administrators (DBAs). *Note `SET OPTION': SET OPTION. * Multiple-table `DELETE' and `UPDATE' statements have been added.. * On Windows, symbolic link handling at the database level is enabled by default. On Unix, the `MyISAM' storage engine now supports symbolic linking at the table level (and not just the database level as before). * `SQL_CALC_FOUND_ROWS' and `FOUND_ROWS()' are new functions that make it possible to find out the number of rows a `SELECT' query that includes a `LIMIT' clause would have returned without that clause. The news section of this manual includes a more in-depth list of features. *Note News-4.0.x::. The Embedded MySQL Server ......................... The `libmysqld' embedded server library makes MySQL Server suitable for a vastly expanded realm of applications. By using this library, developers can embed MySQL Server into various applications and electronics devices, where the end user has no knowledge of there actually being an underlying database. Embedded MySQL Server is ideal for use behind the scenes in Internet appliances, public kiosks, turnkey hardware/software combination units, high performance Internet servers, self-contained databases distributed on CD-ROM, and so on. Many users of `libmysqld' will benefit from the MySQL _Dual Licensing_. For those not wishing to be bound by the `GPL', the software is also made available under a commercial license. The embedded MySQL library uses the same interface as the normal client library, so it is convenient and easy to use. *Note `libmysqld': libmysqld. MySQL 4.1 in a Nutshell ----------------------- MySQL Server 4.0 laid the foundation for new features implemented in MySQL 4.1, such as subqueries and Unicode support, and for the work on stored procedures being done in version 5.0. These features come at the top of the wish list of many of our customers. With these additions, critics of the MySQL Database Server have to be more imaginative than ever in pointing out deficiencies in the MySQL database management system. Already well-known for its stability, speed, and ease of use, MySQL Server will be able to fulfill the requirement checklists of very demanding buyers. Features Available in MySQL 4.1 ............................... The features listed in this section are implemented in MySQL 4.1. A few other features are still planned for MySQL 4.1. *Note TODO MySQL 4.1::. Most new features being coded are or will be available in MySQL 5.0. *Note TODO 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. *Note Subqueries::. Speed enhancements * Faster binary client/server protocol with support for prepared statements and parameter binding. *Note C API Prepared statements::. * `BTREE' indexing is now supported for `HEAP' tables, significantly improving response time for non-exact searches. New functionality * `CREATE TABLE table_name2 LIKE table_name1' allows you to create, with a single statement, a new table with a structure exactly like that of an existing table. * The MyISAM storage engine now supports OpenGIS spatial types for storing geographical data. *Note Spatial extensions in MySQL::. * Replication can be done over SSL connections. Standards compliance, portability, and migration * The new client/server protocol adds the ability to pass multiple warnings to the client, rather than only a single result. This makes operations such as bulk data loading much easier to track. * `SHOW WARNINGS' shows warnings for the last command. *Note `SHOW WARNINGS': SHOW WARNINGS. Internationalization * To support applications that require the use of local languages, the MySQL software now offers extensive Unicode support through the `utf8' and `ucs2' character sets. * Character sets can now be defined per column, table, and database. This allows for a high degree of flexibility in application design, particularly for multi-language web sites. * For documentation for this improved character set support, see *Note Charset::. Usability enhancements * In response to popular demand, we have added a server-based `HELP' command that can be used to get help information for SQL statements. The advantage of having this information on the server side is that the information is always applicable to the particular server version that you actually are using. Because this information is available by issuing a SQL statement, any client can be written to access it. For example, the `help' command of the `mysql' command-line client has been modified to have this capability. * In the new client/server protocol, multiple statements can be issued with a single call. *Note C API multiple queries::. * The new client/server protocol also supports returning multiple result sets. This might occur as a result of sending multiple statements, for example. * A new `INSERT ... ON DUPLICATE KEY UPDATE ...' syntax has been implemented. This allows you to `UPDATE' an existing row if the `INSERT' would have caused a duplicate in a `PRIMARY' or `UNIQUE' key (index). *Note `INSERT': INSERT. * A new aggregate function, `GROUP_CONCAT()' adds the extremely useful capability of concatenating column values from grouped rows into a single result string. *Note Group by functions and modifiers::. The news section of this manual includes a more in-depth list of features. *Note News-4.1.x::. Stepwise Rollout ................ New features are being added to MySQL 4.1. The alpha version is already available for download. *Note Nutshell Ready for Immediate Use::. The set of features that are being added to version 4.1 is mostly fixed. Additional development is already ongoing for version 5.0. MySQL 4.1 will go through the steps of _Alpha_ (during which time new features might still be added/changed), _Beta_ (when we have feature freeze and only bug corrections will be done), and _Gamma_ (indicating that a production release is just weeks ahead). At the end of this process, MySQL 4.1 will become the new production release. Ready for Immediate Development Use ................................... MySQL 4.1 is currently in the alpha stage, and binaries are available for download at `http://www.mysql.com/downloads/mysql-4.1.html'. All binary releases pass our extensive test suite without any errors on the platforms on which we test. *Note News-4.1.x::. For those wishing to use the most recent development source for MySQL 4.1, we make our 4.1 BitKeeper repository publicly available. *Note Installing source tree::. MySQL 5.0, The Next Development Release --------------------------------------- New development for MySQL is focused on the 5.0 release, featuring Stored Procedures and other new features. *Note TODO MySQL 5.0::. For those wishing to take a look at the bleeding edge of MySQL development, we make our BitKeeper repository for MySQL version 5.0 publicly available. *Note Installing source tree::. As of December 2003, binary builds of version 5.0 are also available. MySQL and the Future (The TODO) =============================== This section summarizes the features that we plan to implement in `MySQL Server'. The items are ordered by release series. Within a list, items are shown in approximately the order they will be done. *Note:* If you are an enterprise level user with an urgent need for a particular feature, please contact to discuss sponsoring options. Targeted financing by sponsor companies allows us to allocate additional resources for specific purposes. One example of a feature sponsored in the past is replication. New Features Planned for 4.1 ---------------------------- The features below are not yet implemented in MySQL 4.1, but are planned for implementation before MySQL 4.1 moves into its beta phase. For a list what is already done in MySQL 4.1, see *Note Nutshell 4.1 features::. * Stable OpenSSL support (MySQL 4.0 supports rudimentary, not 100% tested, support for OpenSSL). * More testing of prepared statements. * More testing of multiple character sets for one table. New Features Planned for 5.0 ---------------------------- The following features are planned for inclusion into MySQL 5.0. Some of the features such as stored procedures are complete and are included in MySQL 5.0 alpha, which is available now. Others such as cursors are only partially available. Expect these and other features to mature and be fully supported in upcoming releases. Note that because we have many developers that are working on different projects, there will also be many additional features. There is also a small chance that some of these features will be added to MySQL 4.1. For a list what is already done in MySQL 4.1, see *Note Nutshell 4.1 features::. For those wishing to take a look at the bleeding edge of MySQL development, we make our BitKeeper repository for MySQL version 5.0 publicly available. *Note Installing source tree::. As of December 2003, binary builds of version 5.0 are also available. Stored Procedures * Stored procedures are currently implemented, based on the SQL:2003 standard. *Note Stored Procedures::. We will also implement a framework to hook in external languages, and (where possible) compatibility with, for example, PL/SQL and T-SQL. New functionality * Elementary cursor support. *Note Cursors::. * The ability to specify explicitly for `MyISAM' tables that an index should be created as an `RTREE' index. (In MySQL 4.1, `RTREE' indexes are used internally for geometrical data that use GIS datatypes, but cannot be created on request.) * Dynamic length rows for `HEAP' tables. Standards compliance, portability and migration * Add true `VARCHAR' support (column lengths longer than 255, and no stripping of trailing whitespace). (There is already support for this in the `MyISAM' storage engine, but it is not yet available at the user level.) Speed enhancements * `SHOW COLUMNS FROM table_name' (used by `mysql' client to allow expansions of column names) should not open the table, only the definition file. This will require less memory and be much faster. * Allow `DELETE' on `MyISAM' tables to use the record cache. To do this, we need to update the threads record cache when we update the `.MYD' file. * Better support for `MEMORY' (`HEAP') tables: * Dynamic length rows. * Faster row handling (less copying). Usability enhancements * Resolving the issue of `RENAME TABLE' on a table used in an active `MERGE' table possibly corrupting the table. The news section of this manual includes a more in-depth list of features. *Note News-5.0.x::. New Features Planned for 5.1 ---------------------------- New functionality * `FOREIGN KEY' support for all table types, not just `InnoDB'. * Column-level constraints. * Fail-safe replication. * Online backup with very low performance penalty. The online backup will make it easy to add a new replication slave without taking down the master. Speed enhancements * New text based table definition file format (`.frm' files) and a table cache for table definitions. This will enable us to do faster queries of table structures and do more efficient foreign key support. * Optimize the `BIT' type to take 1 bit. (`BIT' now takes 1 byte; it is treated as a synonym for `TINYINT'.) Usability enhancements * Add options to the client/server protocol to get progress notes for long running commands. * Implement `RENAME DATABASE'. To make this safe for all storage engines, it should work as follows: * Create the new database. * For every table do a rename of the table to another database, as we do with the `RENAME' command. * Drop the old database. * New internal file interface change. This will make all file handling much more general and make it easier to add extensions like RAID. New Features Planned for the Near Future ---------------------------------------- New functionality * Oracle-like `CONNECT BY PRIOR ...' to search tree-like (hierarchical) structures. * Add all missing SQL-92 and ODBC 3.0 types. * Add `SUM(DISTINCT)'. * `INSERT SQL_CONCURRENT' and `mysqld --concurrent-insert' to do a concurrent insert at the end of a table if the table is read-locked. * Allow variables to be updated in `UPDATE' statements. For example: `UPDATE TABLE foo SET @a=a+b,a=@a, b=@a+c'. * Change when user variables are updated so that one can use them with `GROUP BY', as in the following example: `SELECT id, @a:=COUNT(*), SUM(sum_col)/@a FROM table_name GROUP BY id'. * Add an `IMAGE' option to `LOAD DATA INFILE' to not update `TIMESTAMP' and `AUTO_INCREMENT' fields. * Add `LOAD DATA INFILE ... UPDATE' syntax that works like this: * For tables with primary keys, if an input record contains a primary key value, existing rows matching that primary key value are updated from the remainder of the input columns. However, columns corresponding to columns that are *missing* from the input record are not touched. * For tables with primary keys, if an input record does not contain the primary key value or is missing some part of the key, the record is treated as `LOAD DATA INFILE ... REPLACE INTO'. * Make `LOAD DATA INFILE' understand syntax like: LOAD DATA INFILE 'file_name.txt' INTO TABLE tbl_name TEXT_FIELDS (text_field1, text_field2, text_field3) SET table_field1=CONCAT(text_field1, text_field2), table_field3=23 IGNORE text_field3 This can be used to skip over extra columns in the text file, or update columns based on expressions of the read data. * New functions for working with `SET' type columns: * `ADD_TO_SET(value,set)' * `REMOVE_FROM_SET(value,set)' * If you abort `mysql' in the middle of a query, you should open another connection and kill the old running query. Alternatively, an attempt should be made to detect this in the server. * Add a storage engine interface for table information so that you can use it as a system table. This would be a bit slow if you requested information about all tables, but very flexible. `SHOW INFO FROM tbl_name' for basic table information should be implemented. * Allow `SELECT a FROM table_name1 LEFT JOIN table_name2 USING (a)'; in this case `a' is assumed to come from the `table_name1' table. * `DELETE' and `REPLACE' options to the `UPDATE' statement (this will delete rows when one gets a duplicate key error while updating). * Change the format of `DATETIME' to store fractions of seconds. * Make it possible to use the new GNU `regexp' library instead of the current one (the new library should be much faster than the current one). Standards compliance, portability and migration * Don't add automatic `DEFAULT' values to columns. Produce an error for any `INSERT' statement that is missing a value for a column that has no `DEFAULT'. * Add `ANY()', `EVERY()', and `SOME()' group functions. In standard SQL, these work only on boolean columns, but we can extend these to work on any columns or expressions by treating 0 values as FALSE and non-zero values as TRUE. * Fix the type of `MAX(column)' to be the same as the column type: mysql> CREATE TABLE t1 (a DATE); mysql> INSERT INTO t1 VALUES (NOW()); mysql> CREATE TABLE t2 SELECT MAX(a) FROM t1; mysql> SHOW COLUMNS FROM t2; Speed enhancements * Don't allow more than a defined number of threads to run `MyISAM' recovery at the same time. * Change `INSERT ... SELECT' to optionally use concurrent inserts. * Add an option to periodically flush key pages for tables with delayed keys if they haven't been used in a while. * Allow join on key parts (optimization issue). * Add a log file analyzer that can parse out information about which tables are hit most often, how often multiple-table joins are executed, etc. This should help users identify areas of table design that could be optimized to execute much more efficient queries. Internationalization Usability enhancements * Return the original column types when doing `SELECT MIN(column) ... GROUP BY'. * Make it possible to specify `long_query_time' with a granularity in microseconds. * Link the `myisampack' code into the server so that it can perform `PACK' or `COMPRESS' operations. * Add a temporary key buffer cache during `INSERT/DELETE/UPDATE' so that we can gracefully recover if the index file gets full. * If you perform an `ALTER TABLE' on a table that is symlinked to another disk, create temporary tables on that disk. * Implement a `DATE/DATETIME' type that handles time zone information properly, to make dealing with dates in different time zones easier. * Fix `configure' so that one can compile all libraries (like `MyISAM') without threads. * Allow SQL variables as `LIMIT' arguments, for example, `LIMIT @a,@b'. * Automatic output from `mysql' to a web browser. * `LOCK DATABASES' (with various options). * Many more variables for `SHOW STATUS'. Records reads and updates. Selects on a single table and selects with joins. Mean number of tables in select. Number of `ORDER BY' and `GROUP BY' queries. * `mysqladmin copy database new-database'; this requires a `COPY' operation to be added to `mysqld'. * Processlist output should indicate the number of queries/threads. * `SHOW HOSTS' for printing information about the hostname cache. * Change table names from empty strings to `NULL' for calculated columns. * Don't use `Item_copy_string' on numerical values to avoid number->string->number conversion in case of: `SELECT COUNT(*)*(id+0) FROM table_name GROUP BY id' * Change so that `ALTER TABLE' doesn't abort clients that execute `INSERT DELAYED'. * Fix so that when columns are referenced in an `UPDATE' clause, they contain the old values from before the update started. New operating systems * Port the MySQL clients to LynxOS. New Features Planned for the Mid-Term Future -------------------------------------------- * Implement function: `get_changed_tables(timeout,table1,table2,...)'. * Change reading through tables to use memmap when possible. Now only compressed tables use memmap. * Make the automatic timestamp code nicer. Add timestamps to the update log with `SET TIMESTAMP=#;'. * Use read/write mutex in some places to get more speed. * Simple views (implemented in stepwise fashion up to full functionality). *Note ANSI diff Views::. * Automatically close some tables if a table, temporary table, or temporary file gets error 23 (too many open files). * Better constant propagation. When an occurrence of `col_name=n' is found in an expression, for some constant `n', replace other occurrences of `col_name' within the expression with `n'. Currently, this is done only for some simple cases. * Change all const expressions with calculated expressions if possible. * Optimize key = expression comparisons. At the moment only key = field or key = constant comparisons are optimized. * Join some of the copy functions for nicer code. * Change `sql_yacc.yy' to an inline parser to reduce its size and get better error messages. * Change the parser to use only one rule per different number of arguments in function. * Use of full calculation names in the order part (for ACCESS97). * `MINUS', `INTERSECT', and `FULL OUTER JOIN'. (Currently `UNION' [in 4.0] and `LEFT|RIGHT OUTER JOIN' are supported.) * Allow `SQL_OPTION MAX_SELECT_TIME=#', for placing a time limit on a query. * Allow updates to be logged to a database. * Enhance `LIMIT' to allow retrieval of data from the end of a result set. * Alarm around client connect/read/write functions. * Please note the changes to `mysqld_safe': according to FSSTND (which Debian tries to follow) PID files should go into `/var/run/.pid' and log files into `/var/log'. It would be nice if you could put the "DATADIR" in the first declaration of "pidfile" and "log", so the placement of these files can be changed with a single statement. * Allow a client to request logging. * Allow the `LOAD DATA INFILE' statement to read files that have been compressed with `gzip'. * Fix sorting and grouping of `BLOB' columns (partly solved now). * Change to use semaphores when counting threads. One should first implement a semaphore library for MIT-pthreads. * Add full support for `JOIN' with parentheses. * As an alternative to the one-thread-per-connection model, manage a pool of threads to handle queries. * Allow `GET_LOCK()' to obtain more than one lock. When doing this, one must also handle the possible deadlocks this change will introduce. New Features We Don't Plan to Implement --------------------------------------- We aim toward full compliance with SQL-92/SQL-99, so there are no features we plan not to implement. MySQL Information Sources ========================= MySQL Mailing Lists ------------------- This section introduces you to the MySQL mailing lists and provides some guidelines as to how the lists should be used. When you subscribe to a mailing list, you will receive all postings to the list as email messages. You can also to send your own questions and answers to the list. The MySQL Mailing Lists ....................... To subscribe to or unsubscribe from any of the mailing lists described in this section, visit `http://lists.mysql.com/'. Please *do not* send messages about subscribing or unsubscribing to any of the mailing lists, because such messages are distributed automatically to thousands of other users. Your local site may have many subscribers to a MySQL mailing list. If so, the site may have a local mailing list, so that messages sent from `lists.mysql.com' to your site are propagated to the local list. In such cases, please contact your system administrator to be added to or dropped from the local MySQL list. If you wish to have traffic for a mailing list go to a separate mailbox in your mail program, set up a filter based on the message headers. You can use either the `List-ID:' or `Delivered-To:' headers to identify list messages. The MySQL mailing lists are as follows: ``announce'' This list is for announcements of new versions of MySQL and related programs. This is a low-volume list to which all MySQL users should subscribe. ``mysql'' This is the main list for general MySQL discussion. Please note that some topics are better discussed on the more-specialized lists. If you post to the wrong list, you may not get an answer. ``mysql-digest'' This is the `mysql' list in digest form. Subscribing to this list means you will get all list messages, sent as one large mail message once a day. ``bugs'' This list will be of interest to you if you want to stay informed about issues reported since the last release of `MySQL' or if you want to be actively involved in the process of bug hunting and fixing. *Note Bug reports::. ``bugs-digest'' This is the `bugs' list in digest form. ``internals'' This list is for people who work on the MySQL code. This is also the forum for discussions on MySQL development and post patches. ``internals-digest'' This is the `internals' list in digest form. ``mysqldoc'' This list is for people who work on the MySQL documentation: people from MySQL AB, translators, and other community members. ``mysqldoc-digest'' This is the `mysqldoc' list in digest form. ``benchmarks'' This list is for anyone interested in performance issues. Discussions concentrate on database performance (not limited to MySQL) but also include broader categories such as performance of the kernel, file system, disk system, and so on. ``benchmarks-digest'' This is the `benchmarks' list in digest form. ``packagers'' This list is for discussions on packaging and distributing MySQL. This is the forum used by distribution maintainers to exchange ideas on packaging MySQL and on ensuring that MySQL looks and feels as similar as possible on all supported platforms and operating systems. ``packagers-digest'' This is the `packagers' list in digest form. ``java'' This list is for discussions about the MySQL server and Java.It is mostly used to discuss JDBC drivers, including MySQL Connector/J. ``java-digest'' This is the `java' list in digest form. ``win32'' This list is for all topics concerning the MySQL software on Microsoft operating systems, such as Windows 9x/Me/NT/2000/XP. ``win32-digest'' This is the `win32' list in digest form. ``myodbc'' This list is for all topics concerning connecting to the MySQL server with ODBC. ``myodbc-digest'' This is the `myodbc' list in digest form. ``mysqlcc'' This list is for all topics concerning the `MySQL Control Center' graphical client. ``mysqlcc-digest'' This is the `mysqlcc' list in digest form. ``plusplus'' This list is for all topics concerning programming with the C++ API to MySQL. ``plusplus-digest'' This is the `plusplus' list in digest form. ``msql-mysql-modules'' This list is for all topics concerning the Perl support for MySQL with `msql-mysql-modules', which is now named `DBD::mysql'. ``msql-mysql-modules-digest'' This is the `msql-mysql-modules' list in digest form. If you're unable to get an answer to your questions from a `MySQL' mailing list, one option is to purchase support from MySQL AB. This will put you in direct contact with MySQL developers. *Note Support::. The following table shows some MySQL mailing lists in languages other than English. These lists are not operated by MySQL AB. `' A French mailing list. `' A Korean mailing list. Email `subscribe mysql your@email.address' to this list. `' A German mailing list. Email `subscribe mysql-de your@email.address' to this list. You can find information about this mailing list at `http://www.4t2.com/mysql/'. `' A Portuguese mailing list. Email `subscribe mysql-br your@email.address' to this list. `' A Spanish mailing list. Email `subscribe mysql your@email.address' to this list. Asking Questions or Reporting Bugs .................................. Before posting a bug report or question, please do the following: * Start by searching the MySQL online manual at `http://www.mysql.com/doc/'. We try to keep the manual up to date by updating it frequently with solutions to newly found problems. The change history appendix (`http://www.mysql.com/doc/en/News.html') can be particularly useful since it is quite possible that a newer version already contains a solution to your problem. * Search in the bugs database at `http://bugs.mysql.com/' to see whether the bug has already been reported 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. 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 into the system, you will also be able to enter new reports. Writing a good bug report takes patience, but doing it right the first time saves time both for us and for yourself. A good bug report, containing a full test case for the bug, makes it very likely that we will fix the bug in the next release. This section will help you write your report correctly so that you don't waste your time doing things that may not help us much or at all. We encourage everyone to use the `mysqlbug' script to generate a bug report (or a report about any problem). `mysqlbug' can be found in the `scripts' directory (source distribution) and in the `bin' directory under your MySQL installation directory (binary distribution). If you are unable to use `mysqlbug' (for instance, if you are running on Windows), it is still vital that you include all the necessary information noted in this section (most importantly a description of the operating system and the MySQL version). The `mysqlbug' script helps you generate a report by determining much of the following information automatically, but if something important is missing, please include it with your message. Please read this section carefully and make sure that all the information described here is included in your report. Preferably, you should test the problem using the latest production or development version of MySQL Server before posting. Anyone should be able to repeat the bug by just using '`mysql test < script'' on the included test case or by running the shell or Perl script that is included in the bug report. All bugs posted in the bugs database at `http://bugs.mysql.com/' will be corrected or documented in the next MySQL release. If only minor code changes are needed to correct a problem, we will also post a patch that fixes the problem. If you have found a sensitive security bug in MySQL, please send an email to . 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: If you are in doubt about stating something, state it. It is faster and less troublesome to write a couple more lines in your report than to wait longer for the answer if we must ask you to provide information that was missing from the initial report. The most common errors made in bug reports are (a) not including the version number of the MySQL distribution used and (b) not fully describing the platform on which the MySQL server is installed (including the platform type and version number). This is highly relevant information, and in 99 cases out of 100 the bug report is useless without it. Very often we get questions like, "Why doesn't this work for me?" Then we find that the feature requested wasn't implemented in that MySQL version, or that a bug described in a report has already been fixed in newer MySQL versions. Sometimes the error is platform-dependent; in such cases, it is next to impossible for us to fix anything without knowing the operating system and the version number of the platform. If you compiled MySQL from source, remember also to provide information about your compiler, if it is related to the problem. Often people find bugs in compilers and think the problem is MySQL-related. Most compilers are under development all the time and become better version by version. To determine whether your problem depends on your compiler, we need to know what compiler you use. Note that every compiling problem should be regarded as a bug and reported accordingly. It is most helpful when a good description of the problem is included in the bug report. That is, give a good example of everything you did that led to the problem and describe, in exact detail, the problem itself. The best reports are those that include a full example showing how to reproduce the bug or problem. *Note Reproduceable test case::. If a program produces an error message, it is very important to include the message in your report. If we try to search for something from the archives using programs, it is better that the error message reported exactly matches the one that the program produces. (Even the case should be observed.) You should never try to remember what the error message was; instead, copy and paste the entire message into your report. If you have a problem with Connector/ODBC (MyODBC), please try to generate a MyODBC trace file and send it with your report. *Note MyODBC bug report::. Please remember that many of the people who will read your report will do so using an 80-column display. When generating reports or examples using the `mysql' command-line tool, you should therefore use the `--vertical' option (or the `\G' statement terminator) for output that would exceed the available width for such a display (for example, with the `EXPLAIN SELECT' statement; see the example later in this section). Please include the following information in your report: * The version number of the MySQL distribution you are using (for example, MySQL Version 4.0.12). You can find out which version you are running by executing `mysqladmin version'. `mysqladmin' can be found in the `bin' directory under your MySQL installation directory. * The manufacturer and model of the machine on which you experience the problem. * The operating system name and version. 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 is needed. If you have a binary distribution, the distribution name is needed. * If the problem occurs during compilation, include the exact error messages and also a few lines of context around the offending code in the file where the error occurrs. * If `mysqld' died, you should also report the query that crashed `mysqld'. You can usually find this out by running `mysqld' with logging enabled. *Note Using log files::. * If a database table is related to the problem, include the output from `mysqldump --no-data db_name tbl_name1 tbl_name2 ...'. This is very easy to do and is a powerful way to get information about any table in a database. The information will help us create a situation matching the one you have. * For speed-related bugs or problems with `SELECT' statements, you should always include the output of `EXPLAIN SELECT ...', and at least the number of rows that the `SELECT' statement produces. You should also include the output from `SHOW CREATE TABLE tbl_name' for each involved table. The more information you give about your situation, the more likely it is that someone can help you. The following is an example of a very good bug report. It should 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 mysql> EXPLAIN SELECT ...\G mysql> FLUSH STATUS; mysql> SELECT ...; mysql> SHOW STATUS; * If a bug or problem occurs while running `mysqld', try to provide an input script that will reproduce the anomaly. This script should include any necessary source files. The more closely the script can reproduce your situation, the better. If you can make a reproducible test case, you should post it on `http://bugs.mysql.com/' for high-priority treatment. If you can't provide a script, you should at least include the output from `mysqladmin variables extended-status processlist' in your mail to provide some information on how your system is performing. * If you can't produce a test case with only a few rows, or if the test table is too big to be mailed to the mailing list (more than 10 rows), you should dump your tables using `mysqldump' and create a `README' file that describes your problem. Create a compressed archive of your files using `tar' and `gzip' or `zip', and use `ftp' to transfer the archive to `ftp://support.mysql.com/pub/mysql/secret/'. Then enter the problem into our bugs database at `http://bugs.mysql.com/'. * If you think that the MySQL server produces a strange result from a query, include not only the result, but also your opinion of what the result should be, and an account describing the basis for your opinion. * When giving an example of the problem, it's better to use the variable names, table names, etc., that exist in your actual situation than to come up with new names. The problem could be related to the name of a variable or table. These cases are rare, perhaps, but it is better to be safe than sorry. After all, it should be easier for you to provide an example that uses your actual situation, and it is by all means better for us. In case you have data you don't want to show to others, you can use `ftp' to transfer it to `ftp://support.mysql.com/pub/mysql/secret/'. If the data is really top secret and you don't want to show it even to us, then go ahead and provide an example using other names, but please regard this as the last choice. * Include all the options given to the relevant programs, if possible. For example, indicate the options that you use when you start the `mysqld' server as well as the options that you use to run any MySQL client programs. The options to programs like `mysqld' and `mysql', and to the `configure' script, are often keys to answers and are very relevant. It is never a bad idea to include them. If you use any modules, such as Perl or PHP, please include the version numbers of those as well. * If your question is related to the privilege system, please include the output of `mysqlaccess', the output of `mysqladmin reload', and all the error messages you get when trying to connect. When you test your privileges, you should first run `mysqlaccess'. After this, execute `mysqladmin reload version' and try to connect with the program that gives you trouble. `mysqlaccess' can be found in the `bin' directory under your MySQL installation directory. * If you have a patch for a bug, do include it. But don't assume the patch is all we need, or that we will use it, if you don't provide some necessary information such as test cases showing the bug that your patch fixes. We might find problems with your patch or we might not understand it at all; if so, we can't use it. If we can't verify exactly what the purpose of the patch is, we won't use it. Test cases will help us here. Show that the patch will handle all the situations that may occur. If we find a borderline case (even a rare one) where the patch won't work, it may be useless. * Guesses about what the bug is, why it occurs, or what it depends on are usually wrong. Even the MySQL team can't guess such things without first using a debugger to determine the real cause of a bug. * Indicate in your bug report that you have checked the reference manual and mail archive so that others know you have tried to solve the problem yourself. * If you get a `parse error', please check your syntax closely. If you can't find something wrong with it, it's extremely likely that your current version of MySQL Server doesn't support the syntax you are using. If you are using the current version and the manual at `http://www.mysql.com/doc/' doesn't cover the syntax you are using, MySQL Server doesn't support your query. In this case, your only options are to implement the syntax yourself or email 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. *Note News::. * 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'. *Note MySQL Database Administration::. If you are running Windows, please check that `lower_case_table_names is 1 or 2' with `SHOW VARIABLES LIKE 'lower_case_table_names''. * If you often get corrupted tables, you should try to find out when and why this happens. In this case, the error log in the MySQL data directory may contain some information about what happened. (This is the file with the `.err' suffix in the name.) *Note 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. *Note What is crashing::. * 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. *Note Which version::. If you are a support customer, please cross-post the bug report to 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 *Note ODBC Problems::. For solutions to some common problems, see *Note Problems::. 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. 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. MySQL Community Support on IRC (Internet Relay Chat) ---------------------------------------------------- In addition to the various MySQL mailing lists, you can find experienced community people on `IRC' (`Internet Relay Chat'). These are the best networks/channels currently known to us: * *freenode* (see `http://www.freenode.net/' for servers) * `#mysql' Primarily MySQL questions but other database and SQL questions welcome. * `#mysqlphp' Questions about MySQL+PHP, a popular combination. * `#mysqlperl' Questions about MySQL+Perl, another popular combination. * *EFnet* (see `http://www.efnet.org/' for servers) * `#mysql' MySQL questions. If you are looking for IRC client software to connect to an IRC network, take a look at `X-Chat' (`http://www.xchat.org/'). X-Chat (GPL licensed) is available for Unix as well as for Windows platforms. MySQL Standards Compliance ========================== This section describes how MySQL relates to the ANSI/ISO SQL standards. MySQL Server has many extensions to the SQL standard, and here you will find out what they are and how to use them. You will also find information about functionality missing from MySQL Server, and how to work around some differences. Our goal is to not 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-99 standard, but without sacrificing speed or reliability. We are not afraid to add extensions to SQL or support for non-SQL features if this greatly increases the usability of MySQL Server for a large segment of our user base. (The new `HANDLER' interface in MySQL Server 4.0 is an example of this strategy. *Note `HANDLER': HANDLER.) We will continue to support transactional and non-transactional databases to satisfy both mission-critical 24/7 usage and heavy web/logging usage. MySQL Server was designed from the start to work with medium size databases (10-100 million rows, or about 100 MB per table) on small computer systems. We will continue to extend MySQL Server to work even better with terabyte-size databases, as well as to make it possible to compile a reduced MySQL version that is more suitable for hand-held devices and embedded usage. The compact design of the MySQL server makes development in both of these directions possible without any conflicts in the source tree. We are currently not targeting realtime support, though you can already do a lot of things with our replication capabilities. Database cluster support is planned to begin sometime in 2004 through implementation of a new storage engine. We are looking at providing XML support in the database server. What Standards MySQL Follows ---------------------------- Entry-level SQL-92. ODBC levels 0-3.51. We are aiming toward supporting the full SQL-99 standard, but without making concessions to speed and quality of the code. Selecting SQL Modes ------------------- The MySQL server can operate in different SQL modes, and can apply these modes differentially for different clients. This allows applications to tailor server operation to their 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 *Note Server SQL mode::. Running MySQL in ANSI Mode -------------------------- You can tell `mysqld' to use the ANSI mode with the `--ansi' startup option. *Note Server options::. Running the server in ANSI mode is the same as starting it with these options: --sql-mode=REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_BY --transaction-isolation=SERIALIZABLE In MySQL 4.1, you can achieve the same effect with these two statements: SET GLOBAL TRANSACTION ISOLATION LEVEL SERIALIZABLE; SET GLOBAL sql_mode = "REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_BY"; *Note SQL mode::. In MySQL 4.1.1, the `sql_mode' options shown can be also be set with: SET GLOBAL sql_mode="ansi"; In this case, the value of the `sql_mode' variable will be set to all options that are relevant for ANSI mode. You can check the result by doing: mysql> SET GLOBAL sql_mode="ansi"; mysql> SELECT @@GLOBAL.sql_mode; -> "REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_BY,ANSI" MySQL Extensions to the SQL-92 Standard --------------------------------------- MySQL Server includes some extensions that you probably will not find in other SQL databases. Be warned that if you use them, your code will not be portable to other SQL servers. In some cases, you can write code that includes MySQL extensions, but is still portable, by using comments of the form `/*! ... */'. In this case, MySQL Server will parse and execute the code within the comment as it would any other MySQL statement, but other SQL servers will ignore the extensions. For example: SELECT /*! STRAIGHT_JOIN */ col_name FROM table1,table2 WHERE ... If you add a version number after the `'!'' character, the syntax within the comment will be executed only if the MySQL version is equal to or newer than the specified version number: CREATE /*!32302 TEMPORARY */ TABLE t (a INT); This means that if you have Version 3.23.02 or newer, MySQL Server will use the `TEMPORARY' keyword. The following descriptions list MySQL extensions, organized by category. Organization of data on disk MySQL Server maps each database to a directory under the MySQL data directory, and tables within a database to filenames in the database directory. This has a few implications: * Database names and table names are case sensitive in MySQL Server on operating systems that have case sensitive filenames (like most Unix systems). *Note Name case sensitivity::. * Database, table, index, column, or alias names may begin with a digit (but may not consist solely of digits). * You can use standard system commands to back up, rename, move, delete, and copy tables that are managed by the `MyISAM' or `ISAM' storage engines. For example, to rename a `MyISQM' table, rename the `.MYD', `.MYI', and `.frm' files to which the table corresponds. General language syntax * Strings may be enclosed by either `"' or `'', not just by `''. * Use of `\' as an escape character in strings. * In SQL statements, you can access tables from different databases with the `db_name.tbl_name' syntax. Some SQL servers provide the same functionality but call this `User space'. MySQL Server doesn't support tablespaces such as used in statements like this: `CREATE TABLE ralph.my_table...IN my_tablespace'. SQL statement syntax * The `ANALYZE TABLE', `CHECK TABLE', `OPTIMIZE TABLE', and `REPAIR TABLE' statements. * The `CREATE DATABASE' and `DROP DATABASE' statements. *Note `CREATE DATABASE': CREATE DATABASE. * The `DO' statement. * `EXPLAIN SELECT' to get a description of how tables are joined. * The `FLUSH' and `RESET' statements. * The `SET' statement. *Note `SET': SET OPTION. * The `SHOW' statement. *Note `SHOW': SHOW. * Use of `LOAD DATA INFILE'. In many cases, this syntax is compatible with Oracle's `LOAD DATA INFILE'. *Note `LOAD DATA': LOAD DATA. * Use of `RENAME TABLE'. *Note `RENAME TABLE': RENAME TABLE. * Use of `REPLACE' instead of `DELETE' + `INSERT'. *Note `REPLACE': REPLACE. * 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. *Note `ALTER TABLE': ALTER TABLE. * Use of index names, indexes on a prefix of a field, and use of `INDEX' or `KEY' in a `CREATE TABLE' statement. *Note `CREATE TABLE': CREATE TABLE. * 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. *Note `SELECT': SELECT. * 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. *Note Group by functions and modifiers::. * 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)+@t3:=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-99 `||' operator 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 (ISO-8859-1 Latin1 by default). If you don't like this, you should declare your columns with the `BINARY' attribute or use the `BINARY' cast, which causes comparisons to be done according to the ASCII order used on the MySQL server host. * 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. *Note 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()', or `WEEKDAY()' functions. * Use of `TRIM()' to trim substrings. SQL-99 supports removal of single characters only. * The `GROUP BY' functions `STD()', `BIT_OR()', `BIT_AND()', `BIT_XOR()', and `GROUP_CONCAT()'. *Note Group by functions and modifiers::. For a prioritized list indicating when new extensions will be added to MySQL Server, you should consult the online MySQL TODO list at `http://www.mysql.com/doc/en/TODO.html'. That is the latest version of the TODO list in this manual. *Note TODO::. MySQL Differences Compared to SQL-92 ------------------------------------ We try to make MySQL Server follow the ANSI SQL standard (SQL-92/SQL-99) and the ODBC SQL standard, but MySQL Server performs operations differently in some cases: * For `VARCHAR' columns, trailing spaces are removed when the value is stored. *Note Bugs::. * In some cases, `CHAR' columns are silently converted to `VARCHAR' columns when you define a table or alter its structure. *Note Silent column 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. *Note `GRANT': GRANT. Subqueries .......... MySQL Version 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. *Note Subqueries::. For MySQL versions older than 4.1, most subqueries can be rewritten using joins or other methods. See *Note Rewriting subqueries:: for examples that show how to do this. `SELECT INTO TABLE' ................... MySQL Server doesn't support the Sybase SQL extension: `SELECT ... INTO TABLE ...'. Instead, MySQL Server supports the SQL-99 syntax `INSERT INTO ... SELECT ...', which is basically the same thing. *Note `INSERT SELECT': INSERT SELECT. INSERT INTO tblTemp2 (fldID) SELECT tblTemp1.fldOrder_ID FROM tblTemp1 WHERE tblTemp1.fldOrder_ID > 100; Alternatively, you can use `SELECT INTO OUTFILE ...' or `CREATE TABLE ... SELECT'. 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. *Note SELECT INTO Statement::. 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. *Note 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 vs. 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 does one use the features of MySQL Server to maintain rigorous integrity even with the non-transactional `MyISAM' tables, and how do these features compare with the transactional table types? 1. If your applications are written in a way that is dependent on being able to call `ROLLBACK' rather than `COMMIT' in critical situations, transactions are more convenient. Transactions also ensure that unfinished updates or corrupting activities are not committed to the database; the server is given the opportunity to do an automatic rollback and your database is saved. If you use 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, one can normally fix tables perfectly with no data integrity loss. 2. More often than not, critical transactional updates can be rewritten to be atomic. Generally speaking, all integrity problems that transactions solve can be done with `LOCK TABLES' or atomic updates, ensuring that you never will get an automatic abort from the server, which is a common problem with transactional database systems. 3. Even a transactional system can lose data if the server goes down. The difference between different systems lies in just how small the time-lap is where they could lose data. No system is 100% secure, only "secure enough." Even Oracle, reputed to be the safest of transactional database systems, is reported to sometimes lose data in such situations. To be safe with MySQL Server, whether using transactional tables or not, you only need to have backups and have 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, independent of which database system you use. The transactional paradigm has its benefits and its drawbacks. Many users and application developers depend on the ease with which they can code around problems where an abort appears to be, or is necessary. However, even if you are new to the atomic operations paradigm, or more familiar with transactions, do consider the speed benefit that non-transactional tables can offer on the order of three to five times the speed of the fastest and most optimally tuned transactional tables. In situations where integrity is of highest importance, MySQL Server offers transaction-level reliability and integrity even for non-transactional tables. If you lock tables with `LOCK TABLES', all updates will stall until any integrity checks are made. If you obtain a `READ LOCAL' lock (as opposed to a write lock) for a table that allows concurrent inserts at the end of the table, reads are allowed, as are inserts by other clients. The new inserted records will not be seen by the client that has the read lock until it releases the lock. With `INSERT DELAYED' you can queue inserts into a local queue, until the locks are released, without having the client wait for the insert to complete. *Note INSERT DELAYED::. "Atomic," in the sense that we mean it, is nothing magical. It only means that you can be sure that while each specific update is running, no other user can interfere with it, and there will never be an automatic rollback (which can happen with transactional tables if you are not very careful). MySQL Server also guarantees that there will not be any dirty reads. Following are some techniques for working with non-transactional tables: * Loops that need transactions normally can be coded with the help of `LOCK TABLES', and you don't need cursors to update records on the fly. * To avoid using `ROLLBACK', you can use the following strategy: 1. Use `LOCK TABLES ...' to lock all the tables you want to access. 2. Test 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 will be released but some of the updates may not have been executed. * You can also use functions to update records in a single operation. You can get a very efficient application by using the following techniques: * Modify fields relative to their current value. * Update only those fields that actually have changed. For example, when we are doing updates to some customer information, we update only the customer data that has changed and test only that none of the changed data, or data that depends on the changed data, has changed compared to the original row. The test for changed data is done with the `WHERE' clause in the `UPDATE' statement. If the record wasn't updated, we give the client a message: "Some of the data you have changed has been changed by another user." Then we show the old row versus the new row in a window, so the user can decide which version of the customer record he should use. This gives us something that is similar to column locking but is actually even better because we only update some of the columns, using values that are relative to their current values. This means that typical `UPDATE' statements look something like these: UPDATE tablename SET pay_back=pay_back+125; UPDATE customer SET customer_date='current_date', address='new address', phone='new phone', money_he_owes_us=money_he_owes_us-125 WHERE customer_id=id AND address='old address' AND phone='old phone'; As you can see, this is very efficient and works even if another client has changed the values in the `pay_back' or `money_he_owes_us' columns. * In many cases, users have wanted `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 SQL function `LAST_INSERT_ID()' or the C API function `mysql_insert_id()'. *Note Information functions::. *Note `mysql_insert_id()': 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 already 1 in the original row. You can think of it as though MySQL Server changed the preceding query to: UPDATE tbl_name SET row_flag=1 WHERE id=ID AND row_flag <> 1; Stored Procedures and Triggers .............................. Stored procedures are implemented in MySQL version 5.0. *Note Stored Procedures::. Triggers are scheduled for implementation in MySQL version 5.1. A trigger is effectively a type of stored procedure, one that is invoked when a particular event occurs. For example, you could set up a stored procedure that is triggered each time a record is deleted from a transactional table and that stored procedure automatically deletes the corresponding customer from a customer table when all their transactions are deleted. 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'. *Note InnoDB foreign key constraints::. For storage engines other than `InnoDB', MySQL Server parses the `FOREIGN KEY' syntax in `CREATE TABLE' statements, but does not use or store it. In the future, the implementation will be extended to store this information in the table specification file so that it may be retrieved by `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. *Note Table locking::.) 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. *Note `DELETE': DELETE. * 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. *Note InnoDB foreign key constraints::. As of MySQL 4.1.1, `mysqldump' generates dump files that take advantage of this capability automatically when reloaded.) Note that foreign keys in SQL are used to check and enforce referential integrity, not to join tables. If you want to get results from multiple tables from a `SELECT' statement, you do this by performing a join between them: SELECT * FROM table1,table2 WHERE table1.id = table2.id; *Note `JOIN': JOIN. *Note example-Foreign keys::. The `FOREIGN KEY' syntax without `ON DELETE ...' is often used by ODBC applications to produce automatic `WHERE' clauses. Views ..... Views are currently being implemented, and will appear in the 5.0 or 5.1 version of MySQL Server. Unnamed views (_derived tables_, a subquery in the `FROM' clause of a `SELECT') are already implemented in version 4.1. Historically, MySQL Server has been most used in applications and on web systems where the application writer has full control over database usage. Usage has shifted over time, and so we find that an increasing number of users now regard views as an important feature. Views are useful for allowing users to access a set of relations (tables) as if it were a single table, and limiting their access to just that. Views can also be used to restrict access to rows (a subset of a particular table). One does not require views to restrict access to columns, as MySQL Server has a sophisticated privilege system. *Note Privilege system::. Many DBMS don't allow updates to a view. Instead, you have to perform the updates on the individual tables. In designing an implementation of views, our goal, as much as is possible within the confines of SQL, is full compliance with "*Codd's Rule #6*" for relational database systems: All views that are theoretically updatable, should in practice also be updatable. `--' 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. *Note Comments::. MySQL Server Version 3.23.3 and above support the `--' comment style, provided the comment is followed by a space (or by a control character such as a newline). 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 tbl_name SET credit=credit-!payment! Think about what happens if the value of `payment' is a negative value such as `-1': UPDATE tbl_name 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 tbl_name 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 Version 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: shell> replace " --" " #" < text-file-with-funny-comments.sql \ | mysql database instead of the usual: shell> mysql database < text-file-with-funny-comments.sql You can also edit the command file "in place" to change the `--' comments to `#' comments: shell> replace " --" " #" -- text-file-with-funny-comments.sql Change them back with this command: shell> replace " #" " --" -- text-file-with-funny-comments.sql How MySQL Deals with Constraints -------------------------------- MySQL allows you to work with both transactional tables that allow rollback and non-transactional tables that do not, so constraint handling is a bit different in MySQL than in other databases. We have to handle the case when you have updated a lot of rows in a non-transactional table that cannot roll back when an error occurs. The basic philosophy is to try to give an error for anything that we can detect at compile time but try to recover from any errors we get at runtime. We do this in most cases, but not yet for all. *Note TODO future::. The options MySQL has when an error occurs are to stop the statement in the middle or to recover as well as possible from the problem and continue. The following sections describe what happens for the different types of constraints. Constraint PRIMARY KEY / UNIQUE ............................... Normally you will get an error when you try to `INSERT' or `UPDATE' a row that causes a primary key, unique key or foreign key violation. If you are using a transactional storage engine such as `InnoDB', MySQL will automatically roll back the transaction. If you are using a non-transactional storage engine, MySQL will stop at the incorrect row and leave any remaining rows unprocessed. To make life easier, MySQL supports an `IGNORE' keyword for most commands that can cause a key violation (such as `INSERT IGNORE' and `UPDATE IGNORE'). In this case, MySQL will ignore any key violation and continue with processing the next row. You can get information about what MySQL did with the `mysql_info()' API function. *Note `mysql_info()': mysql_info. In MySQL 4.1 and up, you also can use the `SHOW WARNINGS' statement. *Note SHOW WARNINGS::. Note that for the moment only `InnoDB' tables support foreign keys. *Note InnoDB foreign key constraints::. Foreign key support in `MyISAM' tables is scheduled for implementation in MySQL 5.1. Constraint `NOT NULL' and `DEFAULT' values .......................................... To be able to support easy handling of non-transactional tables all columns in MySQL have default values. If you insert an "incorrect" value in a column, such as a `NULL' in a `NOT NULL' column or a too-large numerical value in a numerical column, MySQL sets the column to the "best possible value" instead of producing an error. For numerical values, this is either 0, the smallest possible value or the largest possible value. For strings, this is either the empty string or the longest possible string that can be in the column. This means that if you try to store `NULL' into a column that doesn't take `NULL' values, MySQL Server instead stores 0 or `''' (the empty string). This last behavior can, for single row inserts, be changed with the `-DDONT_USE_DEFAULT_FIELDS' compile option.) *Note `configure' options: configure options. This causes `INSERT' statements to generate an error unless you explicitly specify values for all columns that require a non-`NULL' value. The reason for the preceding rules is that we can't check these conditions until the query has begun executing. We can't just roll back if we encounter a problem after updating a few rows, because the table type 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. This means that you should generally not use MySQL to check column content. Instead, the application should ensure that is passes only legal values to MySQL. In MySQL 5.0, we plan to improve this by providing warnings when automatic column conversions occur, plus an option to let you roll back statements that attempt to perform a disallowed column value assignment, as long as the statement uses only transactional tables. Constraint `ENUM' and `SET' ........................... In MySQL 4.x, `ENUM' is not a real constraint, but is a more efficient way to define columns that can only contain a given set of values. This is because of the same reasons `NOT NULL' is not honored. *Note constraint NOT NULL::. If you insert an incorrect value into an `ENUM' column, it will be set to the reserved enumeration value `0', which will be displayed as an empty string in string context. *Note ENUM::. 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''. *Note SET::. Known Errors and Design Deficiencies in MySQL --------------------------------------------- Errors in 3.23 Fixed in a Later MySQL Version ............................................. The following known errors or bugs are not fixed in MySQL 3.23 because fixing them would involve changing a lot of code that could introduce other even worse bugs. The bugs are also classified as "not fatal" or "bearable." * You can get a deadlock if you use `LOCK TABLE' to lock multiple tables and then in the same connection use `DROP TABLE' to drop one of them while another thread is trying to lock it. (To break the deadlock, you can use `KILL' to terminate any of the threads involved.) This issue is resolved in MySQL 4.0.12. * `SELECT MAX(key_column) FROM t1,t2,t3...' where one of the tables are empty doesn't return `NULL' but instead returns the maximum value for the column. This issue is resolved in MySQL 4.0.11. * `DELETE FROM heap_table' without a `WHERE' clause doesn't work on a locked `HEAP' table. Errors in 4.0 Fixed in a Later MySQL Version ............................................ The following known errors or bugs are not fixed in MySQL 4.0 because fixing them would involve changing a lot of code that could introduce other even worse bugs. The bugs are also classified as "not fatal" or "bearable." * In a `UNION', the first `SELECT' determines the type, `max_length' and `NULL' properties for the resulting columns. This issue is resolved in MySQL 4.1.1; the property values are based on the rows from all `UNION' parts. Open Bugs / Design Deficiencies in MySQL ........................................ The following problems are known and fixing them is a high priority: * Dropping a `FOREIGN KEY' constraint doesn't work in replication as the constraint may have another name. * You cannot mix `UNION ALL' and `UNION DISTINCT' in the same query. If you use `ALL' for one `UNION', it is used for all of them. * If one user has a long running transaction and another user drops a table that is updated in the transaction, there is small chance that the binary log may contain the `DROP TABLE' command before the table is used in the transaction itself. We plan to fix this in 5.0 by having the `DROP TABLE' wait until the table is not used in any transaction. * When inserting a big integer value (between 2^63 and 2^64-1) into a decimal/string column, it is inserted as a negative value because the number is evaluated in a signed integer context. It is planned to be fixed in 4.1. * `FLUSH TABLES WITH READ LOCK' does not block `CREATE TABLE' or `COMMIT', which make cause a problem with the binary log position when doing a full backup of tables and the binary log. * `ANALYZE TABLE' on a `BDB' table may in some cases make the table unusable until one has restarted `mysqld'. If this happens, you will see errors of the following form in the MySQL error file: 001207 22:07:56 bdb: log_flush: LSN past current end-of-log * MySQL accepts parentheses in the `FROM' part of a `SELECT' statement, but silently ignores them. The reason for not giving an error is that many clients that automatically generate queries add parentheses in the `FROM' part even where they are not needed. * Concatenating many `RIGHT JOINS' or combining `LEFT' and `RIGHT' join in the same query may not give a correct answer as MySQL only generates `NULL' rows for the table preceding a `LEFT' or before a `RIGHT' join. This will be fixed in 5.0 at the same time we add support for parentheses in the `FROM' part. * Don't execute `ALTER TABLE' on a `BDB' table on which you are running multiple-statement transactions until all those transactions complete. (The transaction will probably be ignored.) * `ANALYZE TABLE', `OPTIMIZE TABLE', and `REPAIR TABLE' may cause problems on tables for which you are using `INSERT DELAYED'. * Doing a `LOCK TABLE ...' and `FLUSH TABLES ...' doesn't guarantee that there isn't a half-finished transaction in progress on the table. * `BDB' tables are a bit slow to open. If you have many `BDB' tables in a database, it will take a long time to use the `mysql' client on the database if you are not using the `-A' option or if you are using `rehash'. This is especially notable when you have a large table cache. * Replication uses query-level logging: The master writes the executed queries to the binary log. This is a very fast, compact, and efficient logging method that works perfectly in most cases. Though we have never heard of it actually occurring, it is theoretically possible for the data on the master and slave to become different if a query is designed in such a way that the data modification is non-deterministic, that is, left to the will of the query optimizer. (That generally is not a good practice anyway, even outside of replication!) For example: - `CREATE ... SELECT' or `INSERT ... SELECT' statements that insert zero or `NULL' values into an `AUTO_INCREMENT' column. - `DELETE' if you are deleting rows from a table which has foreign keys with `ON DELETE CASCADE' properties. - `REPLACE ... SELECT', `INSERT IGNORE ... SELECT' if you have duplicate key values in the inserted data. *IF and only if all these queries have NO `ORDER BY' clause guaranteeing a deterministic order*. Indeed, for example for `INSERT ... SELECT' with no `ORDER BY', the `SELECT' may return rows in a different order (which will result in a row having different ranks, hence getting a different number in the `auto_increment' column), depending on the choices made by the optimizers on the master and slave. A query will be optimized differently on the master and slave only if: - The files used by the two queries are not exactly the same; for example `OPTIMIZE TABLE' was run on the master tables and not on the slave tables (to fix this, since MySQL 4.1.1, `OPTIMIZE', `ANALYZE' and `REPAIR' are written to the binary log). - The table is stored in a different storage engine on the master than on the slave. (It is possible to use different storage engines on the master and slave. For example, you can use `InnoDB' on the master, but `MyISAM' on the slave if the slave has less available disk space.) - MySQL buffer sizes (`key_buffer_size', etc.) are different on the master and slave. - The master and slave run different MySQL versions, and the optimizer code is different between these versions. This problem may also affect database restoration using `mysqlbinlog|mysql'. The easiest way to avoid this problem in all cases is add an `ORDER BY' clause to such non-deterministic queries to ensure that the rows are always stored or modified in the same order. In future MySQL versions, we will automatically add an `ORDER BY' clause when needed. The following problems are known and will be fixed in due time: * Log files are based on hostnames (if you don't specify a file name with the startup option). For now you have to use options like `--log-bin=old_host_name-bin' if you change your host name to something else. Another option is to just rename the old files to reflect your hostname change. *Note Server options::. * `mysqlbinlog' will not delete temporary files left after a `LOAD DATA INFILE' command. *Note `mysqlbinlog': mysqlbinlog. * `RENAME' doesn't work with `TEMPORARY' tables or tables used in a `MERGE' table. * When using the `RPAD()' function in a query that has to be resolved by using a temporary table, all resulting strings will have rightmost spaces removed. This is an example of such a query: SELECT RPAD(t1.column1, 50, ' ') AS f2, RPAD(t2.column2, 50, ' ') AS f1 FROM table1 as t1 LEFT JOIN table2 AS t2 ON t1.record=t2.joinID ORDER BY t2.record; The final result of this bug is that you will not be able to get spaces on the right side of the resulting values. The problem also occurs for any other string function that adds spaces to the right. The reason for this is due to the fact that `HEAP' tables, which are used first for temporary tables, are not capable of handling `VARCHAR' columns. This behavior exists in all versions of MySQL. It will be fixed in one of the 4.1 series releases. * Due to the way table definition files are stored, you cannot use character 255 (`CHAR(255)') in table names, column names, or enumerations. This is scheduled to be fixed in version 5.1 when we have new table definition format files. * When using `SET CHARACTER SET', you can't use translated characters in database, table, and column names. * You can't use `_' or `%' with `ESCAPE' in `LIKE ... ESCAPE'. * If you have a `DECIMAL' column with a number stored in different formats (+01.00, 1.00, 01.00), `GROUP BY' may regard each value as a different value. * `DELETE FROM merge_table' used without a `WHERE' clause will clear only the mapping for the table, not delete everything in the mapped tables. * You cannot build the server in another directory when using MIT-pthreads. Because this requires changes to MIT-pthreads, we are not likely to fix this. *Note MIT-pthreads::. * `BLOB' values can't "reliably" be used in `GROUP BY' or `ORDER BY' or `DISTINCT'. Only the first `max_sort_length' bytes are used when comparing `BLOB' values in these cases. The default value of `max_sort_length' value is 1024. It can be changed at server startup time. A workaround for most cases is to use a substring. For example: `SELECT DISTINCT LEFT(blob,2048) FROM tbl_name'. * Numeric calculations are done with `BIGINT' or `DOUBLE' (both are normally 64 bits long). It depends on the function which precision one gets. The general rule is that bit functions are done with `BIGINT' precision, `IF', and `ELT()' with `BIGINT' or `DOUBLE' precision and the rest with `DOUBLE' precision. You should try to avoid using unsigned long long values if they resolve to be bigger than 63 bits (9223372036854775807) for anything other than bit fields. MySQL Server 4.0 has better `BIGINT' handling than 3.23. * All string columns, except `BLOB' and `TEXT' columns, automatically have all trailing spaces removed when retrieved. For `CHAR' types this is okay. The bug is that in MySQL Server, `VARCHAR' columns are treated the same way. * You can only have up to 255 `ENUM' and `SET' columns in one table. * In `MIN()', `MAX()', and other aggregate functions, MySQL currently compares `ENUM' and `SET' columns by their string value rather than by the string's relative position in the set. * `mysqld_safe' redirects all messages from `mysqld' to the `mysqld' log. One problem with this is that if you execute `mysqladmin refresh' to close and reopen the log, `stdout' and `stderr' are still redirected to the old log. If you use `--log' extensively, you should edit `mysqld_safe' to log to `'hostname'.err' instead of `'hostname'.log' so you can easily reclaim the space for the old log by deleting the old one and executing `mysqladmin refresh'. * In the `UPDATE' statement, columns are updated from left to right. If you refer to an updated column, you will get the updated value instead of the original value. For example: mysql> UPDATE tbl_name SET KEY=KEY+1,KEY=KEY+1; This will increment `KEY' by `2', not `1'. * You can refer to multiple temporary tables in the same query, but you cannot refer to any given temporary table more than once. For example, the following doesn't work: mysql> SELECT * FROM temporary_table, temporary_table AS t2; * The optimizer may handle `DISTINCT' differently if you are using 'hidden' columns in a join or not. In a join, hidden columns are counted as part of the result (even if they are not shown) while in normal queries hidden columns don't participate in the `DISTINCT' comparison. We will probably change this in the future to never compare the hidden columns when executing `DISTINCT'. An example of this is: SELECT DISTINCT mp3id FROM band_downloads WHERE userid = 9 ORDER BY id DESC; and SELECT DISTINCT band_downloads.mp3id FROM band_downloads,band_mp3 WHERE band_downloads.userid = 9 AND band_mp3.id = band_downloads.mp3id ORDER BY band_downloads.id DESC; In the second case you may in MySQL Server 3.23.x get two identical rows in the result set (because the values in the hidden `id' column may differ). Note that this happens only for queries where you don't have the `ORDER BY' columns in the result, something that you are not allowed to do in SQL-92. * Because MySQL Server allows you to work with table types that don't support transactions, and thus can't roll back data, some things behave a little differently in MySQL Server than in other SQL servers. This is just to ensure that MySQL Server never needs to do a rollback for an SQL statement. This may be a little awkward at times as column values must be checked in the application, but this will actually give you a nice speed increase as it allows MySQL Server to do some optimizations that otherwise would be very hard to do. If you set a column to an incorrect value, MySQL Server will, instead of doing a rollback, store the `best possible value' in the column: - If you try to store a value outside the range in a numerical column, MySQL Server instead stores the smallest or largest possible value in the column. - If you try to store a string that doesn't start with a number into a numerical column, MySQL Server stores 0. - If you try to store `NULL' into a column that doesn't allow `NULL' values, MySQL Server stores 0 or `''' (the empty string) in it instead. (This behavior can, however, be changed with the `-DDONT_USE_DEFAULT_FIELDS' compile option.) - MySQL allows you to store some wrong date values into `DATE' and `DATETIME' columns (like `'2000-02-31'' or `'2000-02-00''). The idea is that it's not the 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 set an `ENUM' column to an unsupported value, it is set to the error value `empty string', with numeric value 0. - If you set a `SET' column to an unsupported value, the value is ignored. * If you execute a `PROCEDURE' on a query that returns an empty set, in some cases the `PROCEDURE' will not transform the columns. * Creation of a table of type `MERGE' doesn't check if the underlying tables are of compatible types. * MySQL Server can't yet handle `NaN', `-Inf', and `Inf' values in `DOUBLE' columns. Using these will cause problems when trying to export and import data. We should as an intermediate solution change `NaN' to `NULL' (if possible) and `-Inf' and `Inf' to the minimum respective maximum possible `double' value. * If you use `ALTER TABLE' to first add a `UNIQUE' index to a table used in a `MERGE' table and then use `ALTER TABLE' to add a normal index on the `MERGE' table, the key order will be different for the tables if there was an old key that was not unique in the table. This is because `ALTER TABLE' puts `UNIQUE' indexes before normal indexes to be able to detect duplicate keys as early as possible. The following are known bugs in earlier versions of MySQL: * You can get a hung thread if you do a `DROP TABLE' on a table that is one among many tables that is locked with `LOCK TABLES'. * In the following case you can get a core dump: - Delayed insert handler has pending inserts to a table. - `LOCK table' with `WRITE'. - `FLUSH TABLES'. * Before MySQL Server Version 3.23.2 an `UPDATE' that updated a key with a `WHERE' on the same key may have failed because the key was used to search for records and the same row may have been found multiple times: UPDATE tbl_name SET KEY=KEY+1 WHERE KEY > 100; A workaround is to use: mysql> UPDATE tbl_name SET KEY=KEY+1 WHERE KEY+0 > 100; This will work because MySQL Server will not use an index on expressions in the `WHERE' clause. * Before MySQL Server Version 3.23, all numeric types were treated as fixed-point fields. That means you had to specify how many decimals a floating-point field should have. All results were returned with the correct number of decimals. For platform-specific bugs, see the sections about compiling and porting. *Note Installing source::. *Note Porting::. 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 *Note Which OS:: for details. 2. *Choose a distribution to install.* Several versions of MySQL are available, and most are available in serveral 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 *Note Which version::. 3. *Download the distribution that you want to install.* For a list of sites from which you can obtain MySQL, see *Note Getting MySQL: Getting MySQL. You can verify the integrity of the distribution using the instructions in *Note Verifying Package Integrity::. 4. *Install the distribution.* For binary distributions, use the instructions in in *Note Installing binary::. For source distributions, use the instructions in *Note Installing source::. Additional installation procedures include the following: * For post-installation procedures, see *Note Post-installation::. These procedures apply whether you install MySQL using a binary or source distribution. * If you plan to upgrade an existing version of MySQL to a newer version rather than installing MySQL for the first time, see *Note Upgrade:: for information about upgrade procedures and about issues that you should consider before upgrading. * If you want to run the MySQL benchmark scripts, Perl support for MySQL must be available. *Note Perl support::. The last part of the chapter provides information on system-specific problems you may run into. 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. Operating Systems Supported by MySQL ------------------------------------ This section lists the operating systems on which you can expect to be able to run MySQL. We use GNU Autoconf, so it is possible to port MySQL to all modern systems that have a C++ compiler and a working implementation of POSIX threads. (Thread suport 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. *Note IBM-AIX::. * Amiga. * BSDI 2.x with the MIT-pthreads package. *Note BSDI::. * BSDI 3.0, 3.1 and 4.x with native threads. *Note BSDI::. * DEC Unix 4.x with native threads. *Note Alpha-DEC-UNIX::. * FreeBSD 2.x with the MIT-pthreads package. *Note FreeBSD::. * FreeBSD 3.x and 4.x with native threads. *Note FreeBSD::. * FreeBSD 4.x with Linuxthreads. *Note FreeBSD::. * HP-UX 10.20 with the DCE threads or the MIT-pthreads package. *Note HP-UX 10.20::. * HP-UX 11.x with the native threads. *Note HP-UX 11.x::. * Linux 2.0+ with LinuxThreads 0.7.1+ or `glibc' 2.0.7+. *Note Linux::. * Mac OS X. *Note Mac OS X::. * NetBSD 1.3/1.4 Intel and NetBSD 1.3 Alpha (Requires GNU make). *Note NetBSD::. * Novell NetWare 6.0. *Note NetWare installation::. * OpenBSD > 2.5 with native threads. OpenBSD < 2.5 with the MIT-pthreads package. *Note OpenBSD::. * OS/2 Warp 3, FixPack 29 and OS/2 Warp 4, FixPack 4. *Note OS/2::. * SCO OpenServer with a recent port of the FSU Pthreads package. *Note SCO::. * SCO UnixWare 7.1.x. *Note SCO UnixWare::. * SGI Irix 6.x with native threads. *Note SGI-Irix::. * Solaris 2.5 and above with native threads on SPARC and x86. *Note Solaris::. * SunOS 4.x with the MIT-pthreads package. *Note Solaris::. * Tru64 Unix * Windows 9x, Me, NT, 2000, and XP. *Note Windows installation::. Not all platforms are equally well-suited for running MySQL. How well a certain platform is suited for a high-load mission-critical MySQL server is determined by the following factors: * General stability of the thread library. A platform may have an excellent reputation otherwise, but MySQL will be only as stable as the thread library if that library is unstable in the code that is called by MySQL, even if everything else is perfect. * The ability of the kernel and/or 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 ability of the kernel and/or the thread library to run many threads which acquire and release a mutex over a short critical region frequently without excessive context switches. In other words, if the implementation of `pthread_mutex_lock()' is too anxious to yield CPU time, this will hurt MySQL tremendously. If this issue is not taken care of, adding extra CPUs will actually make MySQL slower. * General filesystem stability 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 that 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 8.2, 2.4 kernel, and ReiserFS (or any similar Linux distribution) and SPARC with Solaris (2.7-9). FreeBSD comes third, but we really hope it will join the top club once the thread library is improved. We also hope that at some point we will be able to include into the top category all other platforms on which MySQL currently compiles and runs okay, but not quite with the same level of stability and performance. This will require some effort on our part in cooperation with the developers of the operating system and library components that MySQL depends on. If you are interested in improving one of those components, are in a position to influence its development, and need more detailed instructions on what MySQL needs to run better, send an email message to the MySQL internals mailing list. *Note Mailing-list::. 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. And in some cases, the reason one OS is better than the other could simply be that we have put forth more effort into testing on and optimizing for that particular platform. We are just stating our observations to help you decide which platform to use MySQL in your setup. 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. 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. Until recently it was available only in preview form from the BitKeeper source repository. An early alpha release has now been issued to allow more widespread testing. * MySQL 4.1 is a development release series to which major new features have been added. It is still at alpha status. Sources and binaries are available for use and testing on development systems. * MySQL 4.0 is the current stable/production-quality release series. New releases are issued for bugfixes. No new features are added that could diminish the code stability. * MySQL 3.23 is the old stable/production-quality release series. This series is retired, so new releases are issued only to fix critical bugs. We don't believe in a complete freeze, as this also leaves out bug fixes and things that "must be done." "Somewhat frozen" means that we may add small things that "almost surely will not affect anything that's already working." Naturally, relevant bugfixes from an earlier series propagate to later series. * Normally, if you are beginning to use MySQL for the first time or trying to port it to some system for which there is no binary distribution, we recommend going with the production release series. Currently this is MySQL 4.0. Note that 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 chances with a non-seamless upgrade, you should upgrade to the latest version in the same release series you are using (where only the last part of the version number is newer than yours). We have tried to fix only fatal bugs and make small, relatively safe changes to that version. * If you want to use new features not present in the production release series, you can use a version from a development series. Note that development releases are not as stable as production releases. * If you want to use the very latest sources containing all current patches and bugfixes, you can use one of our BitKeeper repositories. These are not "releases" as such, but are available as previews of the code on which future releases will be based. The MySQL naming scheme uses release names that consist of three numbers and a suffix, for example, `mysql-4.1.0-alpha'. The numbers within the release name are is interpreted like this: * The first number (`4') is the major version and also describes the file format. All Version 4 releases have the same file format. * The second number (`1') is the release level. Taken together, the major version and release level constitute the release series number. * The third number (`0') is the version number within the release series. This is incremented for each new release. Usually you want the latest version for the series you have chosen. For each minor update, the last number in the version string is incremented. When there are major new features or minor incompatibilities with previous versions, the second number in the version string is incremented. When the file format changes, the first number is increased. Release names also include a suffix to indicates the stability level of the release. Releases within a series progress through a set of suffixes to indicate how the stability level improves. The possible suffixes are: * `alpha' indicates that the release contains some large section of new code that hasn't been 100% tested. Known bugs (usually there are none) should be documented in the News section. *Note News::. There are also new commands and extensions in most alpha releases. Active development that may involve major code changes can occur in an alpha release, but everything will be tested before issuing a release. For this reason, there should be no known bugs in any MySQL release. * `beta' means that all new code has been tested. No major new features that could cause corruption in old code are added. There should be no known bugs. A version changes from alpha to beta when there haven't been any reported fatal bugs within an alpha version for at least a month and we have no plans to add any features that could make any old command unreliable. * `gamma' is a beta that has been around a while and seems to work fine. Only minor fixes are added. This is what many other companies call a release. * If there is no suffix, it means that the version has been run for a while at many different sites with no reports of bugs other than platform-specific bugs. Only critical bug fixes are applied to the release. This is what we call a production (stable) release. MySQL uses a naming scheme that is slightly different from most other products. In general, it's relatively safe to use any version that has been out for a couple of weeks without being replaced with a new version within the release series. All releases of MySQL are run through our standard tests and benchmarks to ensure that they are relatively safe to use. Because the standard tests are extended over time to check for all previously found bugs, the test suite keeps getting better. Note that 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 *Note 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. *Note MySQL Benchmarks::. The `crash-me' test This test tries to determine what features the database supports and what its capabilities and limitations are. *Note MySQL Benchmarks::. Another test is that we use the newest MySQL version in our internal production environment, on at least one machine. We have more than 100 gigabytes of data to work with. Choosing a Distribution Format .............................. After choosing which version of MySQL to install, you should decide whether to use a binary distribution or a source distribution. In most cases you should probably use a binary distribution, if one exists for your platform. Binary distributions are available in native format for many platforms, such as RPM files for Linux or DMG package installers for Mac OS X. Distributions also are available as Zip archives or compressed `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 both MySQL versions. The extended MySQL binary distribution is marked with the `-max' suffix and is configured with the same options as `mysqld-max'. *Note `mysqld-max': mysqld-max. If you want to use the `MySQL-Max' RPM, you must first install the standard `MySQL-server' RPM. Circumstances under which you probably will be better off with a source installation include the following: * 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 in the standard binary distributions. Here is a list of the most common extra options that you may want to use: * `--with-innodb' (default for MySQL 4.0 and onwards) * `--with-berkeley-db' (not available on all platforms) * `--with-raid' * `--with-libwrap' * `--with-named-z-libs' (This is done for some of the binaries) * `--with-debug[=full]' * 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 (like `pgcc') or want to use compiler options that are better optimized for your processor. Binary distributions are compiled with options that should work on a variety of processors from the same processor family. * You want to use the latest sources from one of the BitKeeper repositories to have access to all current bugfixes. For example, if you have found a bug and reported it to the MySQL development team, the bugfix will be committed to the source repository and you can access it there. The bugfix will not appear in a release until a release actually is issued. * You want to read (or modify) the C and C++ code that makes up MySQL. For this purpose, you should get a source distribution, because the source code is always the ultimate manual. Source distributions also contain more tests and examples than binary distributions. How and When Updates Are Released ................................. MySQL is evolving quite rapidly here at MySQL AB and we want to share new developments with other MySQL users. We try to make a release when we have very useful features that others seem to have a need for. We also try to help out users who request features that are easy to implement. We take note of what our licensed users want to have, and we especially take note of what our extended email supported customers want and try to help them out. No one has to download a new release. The News section will tell you if the new release has something you really want. *Note News::. We use the following policy when updating MySQL: * Releases are issued within each release 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, but if small bugs are found, a release with only bug fixes will be issued. * Working releases/bug fixes 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 usually make fixes available as soon as we have identified and corrected small or non-critical but annoying bugs. The fixes are available immediately from our public BitKeeper repositories, and will be included in the next release. * If by any chance a fatal bug is found in a release, we will make a new release as soon as possible. We would like other companies to do this, too. Release Philosophy--No Known Bugs in Releases ............................................. We put a lot of time and effort into making our releases bug free. To our knowledge, we have not released a single MySQL version with any _known_ "fatal" repeatable bugs. (A fatal bug is something that crashes MySQL under normal usage, produces incorrect answers for normal queries, or has a security problem.) We have documented all open problems, bugs, and issues that are dependent on design decisions. *Note Bugs::. 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. Here is a description of how our build process works: * We monitor bugs from our customer support list, the bugs database at `http://bugs.mysql.com/', and the MySQL external mailing lists. * All reported bugs for live versions are entered into the bugs database. * When we fix a bug, we always try to make a test case for it and include it into our test system to ensure that the bug will never recur without being detected. (About 90% of all fixed bugs have a test case.) * We also create test cases for all new features we add to MySQL. * Before we start to build a new MySQL release, we ensure that all reported repeatable bugs for the MySQL version (3.23.x, 4.0.x, etc) are fixed. If something is impossible to fix (due to some internal design decision in MySQL) we document this in the manual. *Note Bugs::. * We do a build on all platforms for which we support binaries (15+ platforms) and run our test suite and benchmark suite on all of them. * We will not publish a binary for a platform for which the test or benchmark suite fails. If it's a general error in the source, we fix this and do the build plus tests on all systems again, from scratch. * 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://www.mysql.com/', we send out an announcement message to the `mysql' and `announce' mailing lists. *Note Mailing-list::. The announcement message contains a list of all changes to the release and any known problems with the release. (The "known problems" section in the release notes has only been needed in a handful of releases.) * To quickly give our users access to the latest MySQL features, we do a new MySQL release every 4-8 weeks. Source code snapshots are built daily and are available at `http://downloads.mysql.com/snapshots.php'. * If we, after the release is done, get any bug reports that there was (after all) anything critically wrong with the build on a specific platform, we will fix this at once and build a new `'a'' release for that platform. Thanks to our large user base, problems are found quickly. * Our track record for making good releases is quite good. In the last 150 releases, we had to do a new build for less than 10 releases (in 3 of these cases, the bug was a faulty `glibc' library on one of our build machines that took us a long time to track down). MySQL Binaries Compiled by MySQL AB ................................... As a service, we at MySQL AB provide a set of binary distributions of MySQL that are compiled at our site or at sites where customers kindly have given us access to their machines. In addition to the binaries provided in platform-specific package formats (see *Note Quick Standard Installation::), we do offer binary distributions for a number of platforms in the form of of compressed tar files (`.tar.gz'). These distributions are generated using the script `Build-tools/Do-compile' which compiles the source code and creates the binary `tar.gz' archive using `scripts/make_binary_distribution' These binaries are configured and built with the following compilers and options. Binaries built on MySQL AB development systems: Linux 2.4.xx x86 with `gcc' 2.95.3: `CFLAGS="-O2 -mcpu=pentiumpro" CXX=gcc CXXFLAGS="-O2 -mcpu=pentiumpro -felide-constructors" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --enable-assembler --disable-shared --with-client-ldflags=-all-static --with-mysqld-ldflags=-all-static' Linux 2.4.xx Intel Itanium 2 with `ecc' (Intel C++ Itanium Compiler 7.0): `CC=ecc CFLAGS="-O2 -tpp2 -ip -nolib_inline" CXX=ecc CXXFLAGS="-O2 -tpp2 -ip -nolib_inline" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile' Linux 2.4.xx Intel Itanium with `ecc' (Intel C++ Itanium Compiler 7.0): `CC=ecc CFLAGS=-tpp1 CXX=ecc CXXFLAGS=-tpp1 ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --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.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 --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 --enable-assembler --with-named-z-libs=no --with-named-curses-libs=-lcurses --disable-shared' Sun Solaris 9 SPARC with `gcc' 2.95.3: `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-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 --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 --with-server-suffix="-pro" --enable-thread-safe-client --enable-local-infile --with-named-z-libs=no --disable-shared' HP-UX 10.20 pa-risc1.1 with `gcc' 3.1: `CFLAGS="-DHPUX -I/opt/dce/include -O3 -fPIC" CXX=gcc CXXFLAGS="-DHPUX -I/opt/dce /include -felide-constructors -fno-exceptions -fno-rtti -O3 -fPIC" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-pthread --with-named-thread-libs=-ldce --with-lib-ccflags=-fPIC --disable-shared' HP-UX 11.11 pa-risc2.0 64bit with `aCC' (HP ANSI C++ B3910B A.03.33): `CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --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' 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' 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. Please note that these are only provided as a courtesy. Since MySQL AB does not have full control over these systems, we can provide only limited support for the binaries built on these systems. SCO Unix 3.2v5.0.6 i386 with `gcc' 2.95.3: `CFLAGS="-O3 -mpentium" LDFLAGS=-static CXX=gcc CXXFLAGS="-O3 -mpentium -felide-constructors" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-named-z-libs=no --enable-thread-safe-client --disable-shared' SCO OpenUnix 8.0.0 i386 with `CC' 3.2: `CC=cc CFLAGS="-O" CXX=CC ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-named-z-libs=no --enable-thread-safe-client --disable-shared' Compaq Tru64 OSF/1 V5.1 732 alpha with `cc/cxx' (Compaq C V6.3-029i / DIGITAL C++ V6.1-027): `CC="cc -pthread" CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed -speculate all" CXX="cxx -pthread" CXXFLAGS="-O4 -ansi_alias -fast -inline speed -speculate all -noexceptions -nortti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-prefix=/usr/local/mysql --with-named-thread-libs="-lpthread -lmach -lexc -lc" --disable-shared --with-mysqld-ldflags=-all-static' SGI Irix 6.5 IP32 with `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 MySQL AB used to provide in the past. These binaries are no longer 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 `gcc' 2.95.2 and newer: `CC=gcc CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-low-memory --with-extra-charsets=complex --enable-assembler' SunOS 5.6 i86pc with `gcc' 2.8.1: `CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql --with-low-memory --with-extra-charsets=complex' BSDI BSD/OS 3.1 i386 with `gcc' 2.7.2.1: `CC=gcc CXX=gcc CXXFLAGS=-O ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex' BSDI BSD/OS 2.1 i386 with `gcc' 2.7.2: `CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex' AIX 2 4 with `gcc' 2.7.2.2: `CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex' Anyone who has more optimal options for any of the preceding configurations listed can always mail them to the MySQL internals mailing list. *Note Mailing-list::. RPM distributions prior to MySQL Version 3.22 are user-contributed. Beginning with Version 3.22, the RPM distributions are generated by us at MySQL AB. If you want to compile a debug version of MySQL, you should add `--with-debug' or `--with-debug=full' to the preceding configure lines and remove any `-fomit-frame-pointer' options. For the Windows distribution, please see *Note Windows installation::. How to Get MySQL ---------------- Check the MySQL homepage (`http://www.mysql.com/') for information about the current version and for downloading instructions. Our main mirror is located at `http://mirrors.sunsite.dk/mysql/'. For a complete up-to-date list of MySQL web/download mirrors, see `http://www.mysql.com/downloads/mirrors.html'. There you will also find information about becoming a MySQL mirror site and how to report a bad or out-of-date mirror. Verifying Package Integrity Using MD5 Checksums or `GnuPG' ---------------------------------------------------------- After you have downloaded the MySQL package that suits your needs and before you attempt to install it, you should make sure it is intact and has not been tampered with. MySQL AB offers three means of integrity checking: * MD5 checksums * Cryptographic signatures using `GnuPG', the GNU Privacy Guard * For RPM packages, the built-in RPM integrity verification mechanism The following sections describe how to use these methods. Verifying the `MD5 Checksum' ---------------------------- After you have downloaded the package, you should make sure that the MD5 checksum matches the one provided on the MySQL download pages. Each package has an individual checksum that you can verify with the following command, where `package_name' is the name of the package you downloaded: shell> md5sum package_name Note, that not all operating systems support the `md5sum' command--on some it is simply called `md5', others do not ship it at all. On Linux, it is part of the `GNU Text Utilities' package, which is available for a wide range of platforms. You can download the source code from `http://www.gnu.org/software/textutils/' as well. If you have `OpenSSL' installed, you can also use the command `openssl md5 package_name' instead. A DOS/Windows implementation of the `md5' command is available from `http://www.fourmilab.ch/md5/'. 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. Signature Checking Using `GnuPG' -------------------------------- Another method of verifying the integrity and authenticity of a package is to use cryptographic signatures. This is more reliable than using MD5 checksums, but requires more work. Beginning with MySQL 4.0.10 (February 2003), MySQL AB started signing downloadable packages with `GnuPG' (`GNU Privacy Guard'). `GnuPG' is an Open Source alternative to the very well-known `Pretty Good Privacy' (`PGP') by Phil Zimmermann. See `http://www.gnupg.org/' for more information about `GnuPG' and how to obtain and install it on your system. Most Linux distributions already ship with `GnuPG' installed by default. For more information about `OpenPGP', see `http://www.openpgp.org/'. To verify the signature for a specific package, you first need to obtain a copy of MySQL AB's public GPG build key . You can either cut and paste it directly from here, or obtain it from `http://www.keyserver.net/'. Key ID: pub 1024D/5072E1F5 2003-02-03 MySQL Package signing key (www.mysql.com) Fingerprint: A4A9 4068 76FC BD3C 4567 70C8 8C71 8D3B 5072 E1F5 Public Key (ASCII-armored): -----BEGIN PGP PUBLIC KEY BLOCK----- Version: GnuPG v1.0.6 (GNU/Linux) Comment: For info see http://www.gnupg.org mQGiBD4+owwRBAC14GIfUfCyEDSIePvEW3SAFUdJBtoQHH/nJKZyQT7h9bPlUWC3 RODjQReyCITRrdwyrKUGku2FmeVGwn2u2WmDMNABLnpprWPkBdCk96+OmSLN9brZ fw2vOUgCmYv2hW0hyDHuvYlQA/BThQoADgj8AW6/0Lo7V1W9/8VuHP0gQwCgvzV3 BqOxRznNCRCRxAuAuVztHRcEAJooQK1+iSiunZMYD1WufeXfshc57S/+yeJkegNW hxwR9pRWVArNYJdDRT+rf2RUe3vpquKNQU/hnEIUHJRQqYHo8gTxvxXNQc7fJYLV K2HtkrPbP72vwsEKMYhhr0eKCbtLGfls9krjJ6sBgACyP/Vb7hiPwxh6rDZ7ITnE kYpXBACmWpP8NJTkamEnPCia2ZoOHODANwpUkP43I7jsDmgtobZX9qnrAXw+uNDI QJEXM6FSbi0LLtZciNlYsafwAPEOMDKpMqAK6IyisNtPvaLd8lH0bPAnWqcyefep rv0sxxqUEMcM3o7wwgfN83POkDasDbs3pjwPhxvhz6//62zQJ7Q7TXlTUUwgUGFj a2FnZSBzaWduaW5nIGtleSAod3d3Lm15c3FsLmNvbSkgPGJ1aWxkQG15c3FsLmNv bT6IXQQTEQIAHQUCPj6jDAUJCWYBgAULBwoDBAMVAwIDFgIBAheAAAoJEIxxjTtQ cuH1cY4AnilUwTXn8MatQOiG0a/bPxrvK/gCAJ4oinSNZRYTnblChwFaazt7PF3q zIhMBBMRAgAMBQI+PqPRBYMJZgC7AAoJEElQ4SqycpHyJOEAn1mxHijft00bKXvu cSo/pECUmppiAJ41M9MRVj5VcdH/KN/KjRtW6tHFPYhMBBMRAgAMBQI+QoIDBYMJ YiKJAAoJELb1zU3GuiQ/lpEAoIhpp6BozKI8p6eaabzF5MlJH58pAKCu/ROofK8J Eg2aLos+5zEYrB/LsrkCDQQ+PqMdEAgA7+GJfxbMdY4wslPnjH9rF4N2qfWsEN/l xaZoJYc3a6M02WCnHl6ahT2/tBK2w1QI4YFteR47gCvtgb6O1JHffOo2HfLmRDRi Rjd1DTCHqeyX7CHhcghj/dNRlW2Z0l5QFEcmV9U0Vhp3aFfWC4Ujfs3LU+hkAWzE 7zaD5cH9J7yv/6xuZVw411x0h4UqsTcWMu0iM1BzELqX1DY7LwoPEb/O9Rkbf4fm Le11EzIaCa4PqARXQZc4dhSinMt6K3X4BrRsKTfozBu74F47D8Ilbf5vSYHbuE5p /1oIDznkg/p8kW+3FxuWrycciqFTcNz215yyX39LXFnlLzKUb/F5GwADBQf+Lwqq a8CGrRfsOAJxim63CHfty5mUc5rUSnTslGYEIOCR1BeQauyPZbPDsDD9MZ1ZaSaf anFvwFG6Llx9xkU7tzq+vKLoWkm4u5xf3vn55VjnSd1aQ9eQnUcXiL4cnBGoTbOW I39EcyzgslzBdC++MPjcQTcA7p6JUVsP6oAB3FQWg54tuUo0Ec8bsM8b3Ev42Lmu QT5NdKHGwHsXTPtl0klk4bQk4OajHsiy1BMahpT27jWjJlMiJc+IWJ0mghkKHt92 6s/ymfdf5HkdQ1cyvsz5tryVI3Fx78XeSYfQvuuwqp2H139pXGEkg0n6KdUOetdZ Whe70YGNPw1yjWJT1IhMBBgRAgAMBQI+PqMdBQkJZgGAAAoJEIxxjTtQcuH17p4A n3r1QpVC9yhnW2cSAjq+kr72GX0eAJ4295kl6NxYEuFApmr1+0uUq/SlsQ== =YJkx -----END PGP PUBLIC KEY BLOCK----- You can import this key into your public GPG keyring by using `gpg --import'. See the GPG documentation for more info on how to work with public keys. After you have downloaded and imported the public build key, download your desired MySQL package and the corresponding signature, which also is available from the download page. The signature file has the same name as the distribution file with an `.asc' extension. For example: Distribution file `mysql-standard-4.0.17-pc-linux-i686.tar.gz' Signature file `mysql-standard-4.0.17-pc-linux-i686.tar.gz.asc' Make sure that both files are stored in the same directory and then run the following command to verify the signature for the distribution file: shell> gpg --verify package_name.asc Example: shell> gpg --verify mysql-standard-4.0.17-pc-linux-i686.tar.gz.asc gpg: Warning: using insecure memory! gpg: Signature made Mon 03 Feb 2003 08:50:39 PM MET using DSA key ID 5072E1F5 gpg: Good signature from "MySQL Package signing key (www.mysql.com) " The "Good signature" message indicates that everything is all right. Signature Checking Using `RPM' ------------------------------ For RPM packages, there is no separate signature. RPM packages actually have a built-in GPG signature and MD5 checksum. You can verify 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 it into your GPG public keyring), you need to import the key into the RPM keyring first. RPM 4.1 no longer uses your GPG keyring (and GPG itself), but rather maintains its own keyring (because it's a system-wide application and the GPG public keyring is a user-specific file). To import the MySQL public key into the RPM keyring, use `rpm --import'. 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 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 or . Do not report downloading problems using the bug-reporting system. Installation Layouts -------------------- This section describes the default layout of the directories created by installing binary and source distributions. On Windows, the default installation directory is `C:\mysql', which 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* `/usr/bin' Client programs `/usr/sbin' `mysqld' server `/var/lib/mysql' Log files, databases `/usr/share/doc/packages' Documentation `include' Include (header) files `lib' Libraries `scripts' `mysql_install_db' `/usr/share/mysql' Error message and character set files `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 `scripts/make_binary_distribution' script from the top directory of the source distribution. Standard MySQL Installation Using a Binary Distribution ======================================================= This section covers the installation of MySQL on platforms where we offer packages using the native packaging format of the respective platform. (This is also known as performing a "binary install.") However, binary distributions of MySQL are available for many other platforms as well. See *Note Installing binary:: for generic installation instructions for these packages that apply to all platforms. See *Note General Installation Issues:: for more information on what other binary distributions are available and how to obtain them. Installing MySQL on Windows --------------------------- The installation process for MySQL on Windows has the following steps: 1. Install the distribution. 2. Set up an option file if necessary. 3. Select the server you want to use. 4. Start the server. 5. Assign passwords to the initial MySQL accounts. MySQL for Windows is available in two distribution formats: * The binary distribution contains a setup program that installs everything you need so that you can start the server immediately. * The source distribution contains all the code and support files for building the executables using the VC++ 6.0 compiler. Generally speaking, you should use the binary distribution. It's simpler, and you need no additional tools to get MySQL up and running. This section describes how to install MySQL on Windows using a binary distribution. To install using a source distribution, see *Note Windows source build::. Windows System Requirements ........................... To run MySQL on Windows, you need the following: * A 32-bit Windows operating system such as 9x, Me, NT, 2000, or XP. The NT family (Windows NT, 2000, and XP) permits you to run the MySQL server as a service. *Note NT start::. * TCP/IP protocol support. * A copy of the MySQL binary distribution for Windows, which can be downloaded from `http://www.mysql.com/downloads/'. Note: The distribution files are supplied with a zipped format and we recommend the use of an adequate FTP client with resume feature to avoid corruption of files during the download process. * A `ZIP' program to unpack the distribution file. * Enough space on the hard drive to unpack, install, and create the databases in accordance with your requirements. * If you plan to connect to the MySQL server via ODBC, you also need the `MyODBC' driver. *Note ODBC::. * If you need tables with a size larger than 4 GB, install MySQL on an NTFS or newer filesystem. Don't forget to use `MAX_ROWS' and `AVG_ROW_LENGTH' when you create tables. *Note `CREATE TABLE': CREATE TABLE. Installing a Windows Binary Distribution ........................................ To install MySQL on Windows using a binary distribution, follow this procedure: 1. If you are working on a Windows NT, 2000, or XP machine, make sure you have logged in as a user with administrator privileges. 2. If you are doing an upgrade of an earlier MySQL installation, it is necessary to stop the current server. On Windows NT, 2000, or XP machines, if you are running the server as a Windows service, stop it as follows from the command prompt: C:\> NET STOP MySQL If you plan to use a different server after the upgrade (for example, if you want to run `mysqld-max' rather than `mysqld'), remove the existing service: C:\mysql\bin> mysqld --remove You can reinstall the service to use the proper server after upgrading. If you are not running the MySQL server as a service, stop it like this: C:\mysql\bin> mysqladmin -u root shutdown 3. Exit the `WinMySQLAdmin' program if it is running. 4. Unzip the distribution file to a temporary directory. 5. Run the `setup.exe' program to begin the installation process. If you want to install MySQL into a location other than the default directory (`C:\mysql'), use the `Browse' button to specify your preferred directory. If you do not install MySQL into the default location, you will need to specify the location whenever you start the server. The easiest way to do this is to use an option file, as described in *Note Windows prepare environment::. 6. Finish the install process. *Important note:* Early alpha Windows distributions for MySQL 4.1 do not contain any installer program. A 4.1 distribution is a ZIP file that you just unzip in the location where you want to install MySQL. For example, to install `mysql-4.1.1-alpha-win.zip' as `C:\mysql', unzip the distribution file on the `C:' drive, then rename the resulting `mysql-4.1.1-alpha' directory to `mysql'. If you are upgrading to MySQL 4.1 from an earlier version, you will want to preserve your existing `data' directory that contains the grant tables in the `mysql' database and your own databases. Before installing 4.1, stop the server if it is running, and save your `data' directory to another location. Then either rename the existing `C:\mysql' directory or remove it. Install 4.1 as described in the preceding paragraph, and then replace its `data' directory with your old `data' directory. Start the new server and update the grant tables. This will avoid loss of your current databases. *Note Upgrading-grant-tables::. Preparing the Windows MySQL Environment ....................................... If you need to specify startup options when you run the server, you can indicate them on the command line or place them in an option file. For options that will be used every time the server starts, you will find it most convenient to use an option file to specify your MySQL configuration. This is true particularly under the following circumstances: * The installation or data directory locations are different from the default locations (`C:\mysql' and `C:\mysql\data'). * You need to tune the server settings. For example, to use the `InnoDB' transactional tables in MySQL version 3.23, you must manually create two new directories to hold the `InnoDB' data and log files--such as, `C:\ibdata' and `C:\iblogs'. You will also need to add some extra lines to the option file, as described in *Note `InnoDB' start: InnoDB start. (As of MySQL 4.0, InnoDB creates its datafiles and log files in the data directory by default. This means you need not configure InnoDB explicitly. You may still do so if you wish, and an option file will be useful in this case, too.) On Windows, the MySQL installer places the data directory directly under the directory where you install MySQL. If you would like to use a data directory in a different location, you should copy the entire contents of the `data' directory to the new location. For example, by default, the installer places MySQL in `C:\mysql' and the data directory in `C:\mysql\data'. If you want to use a data directory of `E:\mydata', you must do two things: * Move the data directory from `C:\mysql\data' to `E:\mydata'. * Use a `--datadir' option to specify the new data directory location each time you start the server. When the MySQL server starts on Windows, it looks for options in two files: The `my.ini' file in the Windows directory, and the `C:\my.cnf' file. The Windows directory typically is named something like `C:\WINDOWS' or `C:\WinNT'. You can determine its exact location from the value of the `WINDIR' environment variable using the following command: C:\> echo %WINDIR% MySQL looks for options first in the `my.ini' file, then in the `my.cnf' file. However, to avoid confusion, it's best if you use only one file. If your PC uses a boot loader where the `C:' drive isn't the boot drive, your only option is to use the `my.ini' file. Whichever one you use, it must be a plain text file. An option file can be created and modified with any text editor, such as the `Notepad' program. For example, if MySQL is installed at `D:\mysql' and the data directory is located as `D:\mydata\data', you can create the option file and set up a `[mysqld]' section to specify values for the `basedir' and `datadir' parameters: [mysqld] # set basedir to your installation path basedir=D:/mysql # set datadir to the location of your data directory datadir=D:/mydata/data Note that Windows pathnames are specified in option files using forward slashes rather than backslashes. If you do use backslashes, you must double them. Another way to manage an option file is to use the the `WinMySQLAdmin' tool. You can find `WinMySQLAdmin' in the `bin' directory of your MySQL installation, as well as a help file containing instructions for using it. `WinMySQLAdmin' has the capability of editing your option file, but note these points: * `WinMySQLAdmin' uses only the `my.ini' file. * If `WinMySQLAdmin' finds a `C:\my.cnf' file, it will in fact rename it to `C:\my_cnf.bak' to disable it. Now you are ready to test starting the server. Selecting a Windows Server .......................... Starting with MySQL 3.23.38, the Windows distribution includes both the normal and the MySQL-Max server binaries. Here is a list of the different MySQL servers from which you can choose: *Binary* *Description* `mysqld' Compiled with full debugging and automatic memory allocation checking, symbolic links, and `InnoDB' and `BDB' tables. `mysqld-opt' 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 NT/2000/XP with support for named pipes. `mysqld-max' Optimized binary with support for symbolic links, and `InnoDB' and `BDB' tables. `mysqld-max-nt'Like `mysqld-max', but compiled with support for named pipes. All of the preceding binaries are optimized for modern Intel processors but should work on any Intel i386-class or higher processor. MySQL supports TCP/IP on all Windows platforms. The `mysqld-nt' and `mysql-max-nt' servers support named pipes on NT, 2000, and XP. However, the default is to use TCP/IP regardless of the platform. (Named pipes are slower than TCP/IP in many Windows configurations.) Named pipe use is subject to these conditions: * Starting from MySQL 3.23.50, named pipes are enabled only if you start the server with the `--enable-named-pipe' option. It is now necessary to use this option explicitly because some users have experienced problems shutting down the MySQL server when named pipes are 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). * These servers can be run on Windows 98 or Me, but only if TCP/IP is installed; named pipe connections cannot be used. * On Windows 95, these servers cannot be used. Starting the Server for the First Time ...................................... On Windows 95, 98, or Me, MySQL clients always connect to the server using TCP/IP. (This will allow any machine on your network to connect to your MySQL server.) Because of this, you must make sure that TCP/IP support is installed on your machine before starting MySQL. You can find TCP/IP on your Windows CD-ROM. Note that if you are using an old Windows 95 release (for example, OSR2), it's likely that you have an old Winsock package; MySQL requires Winsock 2! You can get the newest Winsock from `http://www.microsoft.com/'. Windows 98 has the new Winsock 2 library, so it is unnecessary to update the library. On NT-based systems such as Windows NT, 2000, or XP, clients have two options. They can use TCP/IP, or they can use a named pipe if the server supports named pipe connections. For information about which server binary to run, see *Note Windows prepare environment::. This section gives a general overview of starting the MySQL server. The following sections provide more specific information for particular versions of Windows. The examples in these sections assume that MySQL is installed under the default location of `C:\mysql'. Adjust the pathnames shown in the examples if you have MySQL installed in a different location. Testing is best done from a command prompt in a console window (a "DOS window"). This way you can have the server display status messages in the window where they are easy to see. If something is wrong with your configuration, these messages will make it easier for you to identify and fix any problems. Make sure you are in the directory where the server is located, then enter this command: C:\mysql\bin> mysqld --console For servers that include `InnoDB' support, you should see the following messages as the server starts: InnoDB: The first specified datafile c:\ibdata\ibdata1 did not exist: InnoDB: a new database to be created! InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200 InnoDB: Database physically writes the file full: wait... InnoDB: Log file c:\iblogs\ib_logfile0 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile0 size to 31457280 InnoDB: Log file c:\iblogs\ib_logfile1 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280 InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280 InnoDB: Doublewrite buffer not found: creating new InnoDB: Doublewrite buffer created InnoDB: creating foreign key constraint system tables InnoDB: foreign key constraint system tables created 011024 10:58:25 InnoDB: Started When the server finishes its startup sequence, you should see something like this, which indicates that the server is ready to service client connections: mysqld: ready for connections Version: '4.0.14-log' socket: '' port: 3306 The server will continue to write to the console any further diagnostic output it produces. You can open a new console window in which to run client programs. If you omit the `--console' option, the server writes diagnostic output to the error log in the data directory. The error log is the file with the `.err' extension. 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 *Note Post-installation::. 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: shell> C:\mysql\bin\mysqld On non-NT versions of Windows, this will start `mysqld' in the background. That is, after the server starts, you should see another command prompt. If you start the server this way on Windows NT, 2000, or XP, the server will run in the foreground and no command prompt will appear until the server exits. Because of this, you should open another console window to run client programs while the server is running. You can stop the MySQL server by executing this command: shell> C:\mysql\bin\mysqladmin -u root shutdown This invokes the MySQL administrative utility `mysqladmin' to connect to the server and tell it to shut down. The command connects as `root', which is the default administrative account in the MySQL grant system. Please note that users in the MySQL grant system are wholly independent from any login users under Windows. If `mysqld' doesn't start, check the error log to see 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' will write a log file `C:\mysqld.trace' that should contain the reason why `mysqld' doesn't start. *Note Making trace files::. Use `mysqld --help' to display all the options that `mysqld' understands! Starting MySQL as a Windows Service ................................... On the NT family (Windows NT, 2000, or XP), the recommended way to run MySQL is to install it as a Windows service. Then Windows starts and stops the MySQL server automatically when Windows starts and stops. A server installed as a service can also be controlled from the command line using `NET' commands, or with the graphical `Services' utility. The `Services' utility (the Windows `Service Control Manager') can be found in the Windows `Control Panel' (under `Administrative Tools' on Windows 2000). It is advisable to close the `Services' utility while performing server installation or removal operations from this command line. This prevents some odd errors. To get MySQL to work with TCP/IP on Windows NT 4, you must install service pack 3 (or newer)! Before installing MySQL as a Windows service, you should first stop the current server if it is running by using the following command: shell> C:\mysql\bin\mysqladmin -u root shutdown This invokes the MySQL administrative utility `mysqladmin' to connect to the server and tell it to shut down. The command connects as `root', which is the default administrative account in the MySQL grant system. Please note that users in the MySQL grant system are wholly independent from any login users under Windows. Now install the server as a service: shell> mysqld --install If you have problems installing `mysqld' as a service using just the server name, try installing it using its full pathname: shell> C:\mysql\bin\mysqld --install As of MySQL 4.0.2, you can specify a specific service name after the `--install' option. As of MySQL 4.0.3, you can in addition specify a `--defaults-file' option after the service name to indicate where the server should obtain options when it starts. The rules that determine the service name and option files the server uses are as follows: * If you specify no service name, the server uses the default service name of `MySQL' and the server reads options from the `[mysqld]' group in the standard option files. * If you specify a service name after the `--install' option, the server ignores the `[mysqld]' option group and instead reads options from the group that has the same name as the service. The server reads options from the standard option files. * If you specify a `--defaults-file' option after the service name, the server ignores the standard option files and reads options only from the `[mysqld]' group of the named file. *Note:* Prior to MySQL 4.0.17, a server installed as a Windows service has problems starting if its pathname or the service name contains spaces. For this reason, avoid installing MySQL in a directory such as `C:\Program Files' or using a service name containing spaces. In the usual case that you install the server with `--install' but no service name, the server is installed with a service name of `MySQL'. As a more complex example, consider the following command (which should be entered on a single line): shell> C:\mysql\bin\mysqld --install mysql --defaults-file=C:\my-opts.cnf Here, a service name is given after the `--install' option. If no `--defaults-file' option had been given, this command would have the effect of causing the server to read the `[mysql]' group from the standard option files. (This would be a bad idea, because that option group is for use by the `mysql' client program.) However, because the `--defaults-file' option is present, the server reads options only from the named file, and only from the `[mysqld]' option group. You can also specify options as "`Start parameters'" in the Windows `Services' utility before you start the MySQL service. Once a MySQL server is installed as a service, Windows will start the service automatically whenever Windows starts. The service also can be started immediately from the `Services' utility, or by using the command `NET START MySQL'. The `NET' command is not case sensitive. Please note that when run as a service, `mysqld' has no access to a console window, so no messages can be seen there. If `mysqld' doesn't start, check the error log to see whether the server wrote any messages there to indicate the cause of the problem. The error log is located in the `C:\mysql\data' directory. It is the file with a suffix of `.err'. When `mysqld' is running as a service, it can be stopped by using the `Services' utility, the command `NET STOP MySQL', or the command `mysqladmin shutdown'. If the service is running when Windows shuts down, Windows will stop the server automatically. From MySQL version 3.23.44, you have the choice of installing the server as a `Manual' service if you don't wish the service to be started automatically during the boot process. To do this, use the `--install-manual' option rather than the `--install' option: shell> C:\mysql\bin\mysqld --install-manual To remove a server that is installed as a service, first stop it if it is running. Then use the `--remove' option to remove it: shell> mysqld --remove For MySQL versions older than 3.23.49, one problem with automatic MySQL service shutdown is that Windows waited only for a few seconds for the shutdown to complete, then killed the database server process if the time limit was exceeded. This had the potential to cause problems. (For example, the `InnoDB' storage engine had to perform crash recovery at the next startup.) Starting from MySQL version 3.23.49, Windows waits longer for the MySQL server shutdown to complete. If you notice this still is not enough for your installation, it is safest not to run the MySQL server as a service. Instead, start it from the command-line prompt, and stop it with `mysqladmin shutdown'. This change to tell Windows to wait longer when stopping the MySQL server works for Windows 2000 and XP. It does not work for Windows NT, where Windows waits only 20 seconds for a service to shut down, and after that kills the service process. You can increase this default by opening the Registry Editor `\winnt\system32\regedt32.exe' and editing the value of `WaitToKillServiceTimeout' at `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control' in the Registry tree. Specify the new larger value in milliseconds. For example, the value 120000 tells Windows NT to wait up to 120 seconds. If you don't want to start `mysqld' as a service, you can start it from the command line the same way as for versions of Windows that are not based on NT. For instructions, see *Note Win95 start::. Running MySQL Client Programs on Windows ........................................ You can test whether the MySQL server is working by executing any of the following commands: C:\> C:\mysql\bin\mysqlshow C:\> C:\mysql\bin\mysqlshow -u root mysql C:\> C:\mysql\bin\mysqladmin version status proc C:\> C:\mysql\bin\mysql test If `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 `--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. In MySQL 4.1, you should use the `--protocol=PIPE' option. There are two versions of the MySQL command-line tool: *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. If you want to use `mysqlc', you must have a copy of the `cygwinb19.dll' library installed somewhere that `mysqlc' can find it. Current distributions of MySQL include this library in the same directory as `mysqlc' (the `bin' directory under the base directory of your MySQL installation). If your distribution does not have the `cygwinb19.dll' library in the `bin' directory, look for it in the `lib' directory and copy it to your Windows system directory (`\Windows\system' or similar place). MySQL on Windows Compared to MySQL on Unix .......................................... MySQL for Windows has by now proven itself to be very stable. The Windows version of MySQL has the same features as the corresponding Unix version, with the following exceptions: *Windows 95 and threads* Windows 95 leaks about 200 bytes of main memory for each thread creation. Each connection in MySQL creates a new thread, so you shouldn't run `mysqld' for an extended time on Windows 95 if your server handles many connections! Other versions of Windows don't suffer from this bug. *Concurrent reads* MySQL depends on the `pread()' and `pwrite()' calls to be able to mix `INSERT' and `SELECT'. Currently we use mutexes to emulate `pread()'/`pwrite()'. We will, in the long run, replace the file level interface with a virtual interface so that we can use the `readfile()'/`writefile()' interface on NT/2000/XP to get more speed. The current implementation limits the number of open files MySQL can use to 1024, which means that you will not be able to run as many concurrent threads on NT/2000/XP as on Unix. *Blocking read* MySQL uses a blocking read for each connection, which has the following implications: * A connection will not be disconnected automatically after 8 hours, as happens with the Unix version of MySQL. * If a connection hangs, it's impossible to break it without killing MySQL. * `mysqladmin kill' will not work on a sleeping connection. * `mysqladmin shutdown' can't abort as long as there are sleeping connections. We plan to fix this problem when our Windows developers have figured out a nice workaround. *`DROP DATABASE'* You can't drop a database that is in use by some thread. *Killing MySQL from the task manager* You can't kill MySQL from the task manager or with the shutdown utility in Windows 95. You must take it down with `mysqladmin shutdown'. *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. *Note Name case sensitivity::. *The `\' pathname separator character* Pathname components in Windows 95 are separated by the `\' character, which is also the escape character in MySQL. If you are using `LOAD DATA INFILE' or `SELECT ... INTO OUTFILE', use Unix style filenames with `/' characters: mysql> LOAD DATA INFILE "C:/tmp/skr.txt" INTO TABLE skr; mysql> SELECT * INTO OUTFILE 'C:/tmp/skr.txt' FROM skr; Alternatively, you must double the `\' character: mysql> LOAD DATA INFILE "C:\\tmp\\skr.txt" INTO TABLE skr; mysql> SELECT * INTO OUTFILE 'C:\\tmp\\skr.txt' FROM skr; *Problems with pipes.* Pipes doesn't work reliably in the Windows command-line prompt. If the pipe includes the character `^Z' / `CHAR(24)', Windows will think it has encountered end-of-file and abort the program. This is mainly a problem when you try to apply a binary log as follows: mysqlbinlog binary-log-name | mysql --user=root If you get a problem applying the log and suspect it's because of an `^Z' / `CHAR(24)' character you can use the following workaround: mysqlbinlog binary-log-file --result-file=/tmp/bin.sql mysql --user=root --execute "source /tmp/bin.sql" The latter command also can be used to reliably read in any SQL file that may contain binary data. *`Can't open named pipe' error* If you use a MySQL Version 3.22 server on NT with the newest MySQL client programs, you will get the following error: error 2017: can't open named pipe to host: . pipe... This is because the release version of MySQL uses named pipes on NT by default. You can avoid this error by using the `--host=localhost' option to the new MySQL clients or create an option file `C:\my.cnf' that contains the following information: [client] host = localhost Starting from 3.23.50, named pipes are enabled only if `mysqld-nt' or `mysqld-max-nt' is started with `--enable-named-pipe'. *`Access denied for user' error* If you attempt to run a MySQL client program to connect to a server running on the same machine, but get the error `Access denied for user: 'some-user@unknown' to database 'mysql'', this means that MySQL can't resolve your hostname properly. To fix this, you should create a file `\windows\hosts' with the following information: 127.0.0.1 localhost *`ALTER TABLE'* While you are executing an `ALTER TABLE' statement, the table is locked from being used by other threads. This has to do with the fact that on Windows, you can't delete a file that is in use by another threads. In the future, we may find some way to work around this problem. *`DROP TABLE'* `DROP TABLE' on a table that is in use by a `MERGE' table will not work on Windows because the `MERGE' handler does the table mapping hidden from the upper layer of MySQL. Because Windows doesn't allow you to drop files that are open, you first must flush all `MERGE' tables (with `FLUSH TABLES') or drop the `MERGE' table before dropping the table. We will fix this at the same time we introduce views. *`DATA DIRECTORY' and `INDEX DIRECTORY'* The `DATA DIRECTORY' and `INDEX DIRECTORY' options for `CREATE TABLE' are ignored on Windows, because Windows doesn't support symbolic links. These options also are ignored on systems that have a non-functional `realpath()' call. Here are some open issues for anyone who might want to help us improve MySQL on Windows: * Add some nice start and shutdown icons to the MySQL installation. * It would be really nice to be able to kill `mysqld' from the task manager. For the moment, you must use `mysqladmin shutdown'. * Port `readline' to Windows for use in the `mysql' command-line tool. * GUI versions of the standard MySQL clients (`mysql', `mysqlshow', `mysqladmin', and `mysqldump') would be nice. * It would be nice if the socket read and write functions in `net.c' were interruptible. This would make it possible to kill open threads with `mysqladmin kill' on Windows. * Add macros to use the faster thread-safe increment/decrement methods provided by Windows. Installing MySQL on Linux ------------------------- The recommended way to install MySQL on Linux is by using the RPM packages. The MySQL RPMs are currently built on a SuSE Linux 7.3 system but should work on most versions of Linux that support `rpm' and use `glibc'. If you have problems with an RPM file (for example, if you receive the error "`Sorry, the host 'xxxx' could not be looked up'"), see *Note Binary notes-Linux::. In most cases, you only need to install the `MySQL-server' and `MySQL-client' packages to get a functional MySQL installation. The other packages are not required for a standard installation. If you want to run a MySQL-Max server that has additional capabilities, you should install the `MySQL-Max' RPM. However, you should do so only _ after_ installing the `MySQL-server' RPM. *Note `mysqld-max': mysqld-max. If you get a dependency failure when trying to install the MySQL 4.0 packages (for example, "`error: removing these packages would break dependencies: libmysqlclient.so.10 is needed by ...'"), you should also install the package `MySQL-shared-compat', which includes both the shared libraries for backward compatibility (`libmysqlclient.so.12' for MySQL 4.0 and `libmysqlclient.so.10' for MySQL 3.23). Many Linux distributions still ship with MySQL 3.23 and they usually link applications dynamically to save disk space. If these shared libraries are in a separate package (for example, `MySQL-shared'), it is sufficient to simply leave this package installed and just upgrade the MySQL server and client packages (which are statically linked and do not depend on the shared libraries). For distributions that include the shared libraries in the same package as the MySQL server (for example, Red Hat Linux), you could either install our 3.23 `MySQL-shared' RPM, or use the `MySQL-shared-compat' package instead. The following RPM packages are available: * `MySQL-server-VERSION.i386.rpm' The MySQL server. You will need this unless you only want to connect to a MySQL server running on another machine. Please 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. * `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 is available since MySQL 4.0.13. * `MySQL-embedded-VERSION.i386.rpm' The embedded MySQL server library (from MySQL 4.0). * `MySQL-VERSION.src.rpm' This contains the source code for all of the previous packages. It can also be used to rebuild the RPMs on other architectures (for example, Alpha or SPARC). To see all files in an RPM package (for example, a `MySQL-server' RPM), run: shell> rpm -qpl MySQL-server-VERSION.i386.rpm To perform a standard minimal installation, run: shell> rpm -i MySQL-server-VERSION.i386.rpm 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 please see *Note Verifying Package Integrity::. The server RPM places data under the `/var/lib/mysql' directory. The RPM also creates the appropriate entries in `/etc/init.d/' to start the server automatically at boot time. (This means that if you have performed a previous installation and have made changes to its startup script, you may want to make a copy of the script so you don't lose it when you install a newer RPM.) See *Note Automatic start:: 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; ln -s rc.d/init.d . However, all current major Linux distributions should already support the new directory layout that uses `/etc/init.d', because it is required for LSB (Linux Standard Base) compliance. If the RPM files that you install include `MySQL-server', the `mysqld' server should be up and running after installation. You should now be able to start using MySQL. *Note Post-installation::. If something goes wrong, you can find more information in the binary installation chapter. *Note Installing binary::. Installing MySQL on Mac OS X ---------------------------- Beginning with MySQL 4.0.11, you can install MySQL on Mac OS X 10.2 ("Jaguar") using a Mac OS X binary package in `PKG' format instead of the binary tarball distribution. Please note that older versions of Mac OS X (for example, 10.1.x) are not supported by this package. The package is located inside a disk image (`.dmg') file, that you first need to mount by double-clicking its icon in the Finder. It should then mount the image and display its contents. *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 will guide you through the installation of MySQL. Due to a bug in the Mac OS X package installer, you may sometimes see the error message `You cannot install this software on this disk. (null)' in the destination disk selection dialogue. If this error occurs, simply click the `Go Back' button once to return to the previous screen. 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 they are investigating this problem. The Mac OS X PKG of MySQL will install itself into `/usr/local/mysql-' and will also install a symbolic link `/usr/local/mysql', pointing to the new location. If a directory named `/usr/local/mysql' already exists, it will be renamed to `/usr/local/mysql.bak' first. Additionally, it will install the grant tables in the `mysql' database by executing `mysql_install_db' after the installation. The installation layout is similar to the one of the binary distribution; all MySQL binaries are located in the directory `/usr/local/mysql/bin'. The MySQL socket file is created as `/tmp/mysql.sock' by default. *Note Installation layouts::. MySQL installation requires a Mac OS X user account named `mysql' (a user account with this name should exist by default on Mac OS X 10.2 and up). If you are running Mac OS X Server, you already have a version of MySQL installed. The versions of MySQL that ship with Mac OS X Server versions are shown in the following table: *Mac OS X Server *MySQL Version* Version* 10.2-10.2.2 3.23.51 10.2.3-10.2.6 3.23.53 10.3 4.0.14 10.3.2 4.0.16 This manual section covers the installation of the official MySQL Mac OS X PKG only. Make sure to read Apple's help about installing MySQL (Run the "Help View" application, select "Mac OS X Server" help, and do a search for "MySQL" and read the item entitled "Installing MySQL"). Especially note that for pre-installed versions of MySQL on Mac OS X Server, you should start `mysqld' with `safe_mysqld' instead of `mysqld_safe' if the 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. *Note Upgrading-grant-tables::. If you would like to automatically start up MySQL during system bootup, you also need to install the MySQL Startup Item. Starting with MySQL 4.0.15, it is part of the Mac OS X installation disk images as a separate installation package. Simply double-click the `MySQLStartupItem.pkg' icon and follow the instructions to install it. Note that the Startup Item need be installed only once! There is no need to install it each time you upgrade the MySQL package later. The Startup Item will be installed into `/Library/StartupItems/MySQL'. It adds a variable `MYSQLCOM=-YES-' to the system configuration file `/etc/hostconfig'. If you would like to disable the automatic startup of MySQL, simply change this variable to `MYSQLCOM=-NO-'. On Mac OS X Server, the default MySQL installation uses the variable `MYSQL' in `/etc/hostconfig'. The MySQL AB Startup Item installer disables this variable by setting it to `MYSQL=-NO-'. This avoids boot time conflicts with the `MYSQLCOM' variable used by the MySQL AB Startup Item. However, it does not shut down an already running MySQL server. After the installation, you can start up MySQL by running the following commands in a terminal window. Please note that you must have administrator privileges to perform this task. If you have installed the Startup Item: shell> sudo /Library/StartupItems/MySQL/MySQL start (Enter your password, if necessary) (Press Control-D or enter "exit" to exit the shell) If you don't use the Startup Item, enter the following command sequence: shell> cd /usr/local/mysql shell> sudo ./bin/mysqld_safe (Enter your password, if necessary) (Press Control-Z) shell> bg (Press Control-D or enter "exit" to exit the shell) You should now be able to connect to the MySQL server, for example, by running `/usr/local/mysql/bin/mysql'. If you are installing MySQL for the first time, *please remember to set a password for the MySQL `root' user!* This is done with the following two commands: /usr/local/mysql/bin/mysqladmin -u root password /usr/local/mysql/bin/mysqladmin -u root -h `hostname` password Please make sure that the `hostname' command in the second line is enclosed by *backtick* characters (``'), so the shell can replace it with the output of the command (which is the hostname of your system)! You might want to also add aliases to your shell's resource file to access `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 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-.pkg'. Installing MySQL on NetWare --------------------------- Porting `MySQL' to `NetWare' was an effort spearheaded by `Novell'. Novell customers will be pleased to note that NetWare 6.5 will ship with bundled MySQL binaries, complete with an automatic commercial use license for all servers running that version of NetWare. As of version 4.0.11, the MySQL server is available for Novell NetWare in binary package form. MySQL for NetWare is compiled using a combination of `Metrowerks CodeWarrior for NetWare' and special cross-compilation versions of the GNU autotools. In order to host MySQL, the NetWare server must meet these requirements: * NetWare version 6.5, or NetWare 6.0 with Support Pack 3 installed (You can obtain this at `http://support.novell.com/filefinder/13659/index.html'). The system must meet Novell's minimum requirements to run the respective version of NetWare. * MySQL data, as well as the binaries themselves, must be installed on an NSS volume; traditional volumes are not supported. The binary package for NetWare can be obtained at `http://www.mysql.com/downloads/'. 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 will install MySQL. 3. Extract the binary package zip file onto the server. Be sure to allow the paths in the zip file to be used. It is safe to simply extract the file to `SYS:\'. If you are upgrading from a prior installation, you may need to copy the data directory (for example, `SYS:MYSQL\DATA') now, as well as `my.cnf' if you have customized it. You can then delete the old copy of MySQL. 4. You may wish to rename the directory to something more consistent and easy to use. We recommend using `SYS:MYSQL'; examples in the manual will use this to refer to the installation directory in general. 5. At the server console, add a search path for the directory containing the MySQL NLMs. For example: SERVER: SEARCH ADD SYS:MYSQL\BIN 6. Install the initial database, if needed, by executing `mysql_install_db' at the server console. 7. Start the MySQL server using `mysqld_safe' at the server console. 8. To finish the installation, you should also add the following commands to `autoexec.ncf'. For example, if your MySQL installation is in `SYS:MYSQL' and you want MySQL to start automatically, you could add these lines: #Starts the MySQL 4.0.x database server SEARCH ADD SYS:MYSQL\BIN MYSQLD_SAFE If you are running MySQL on NetWare 6.0, we strongly suggest that you use the `--skip-external-locking' option on the command line: #Starts the MySQL 4.0.x database server SEARCH ADD SYS:MYSQL\BIN MYSQLD_SAFE --skip-external-locking It will also be neccesary to use `CHECK TABLE' and `REPAIR TABLE' instead of `myisamchk', because `myisamchk' makes use of external locking. External locking is known to have problems on NetWare 6.0; the problem has been eliminated in NetWare 6.5. 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. Installing MySQL on HP-UX ------------------------- Binary distributions of MySQL for HP-UX are distributed as HP depot files or as `tar' files. To use the depot file you must be running at least HP-UX 10.x to have access to HP's software depot tools. To install the HP-UX `tar.gz' distribution, you must have a copy of GNU `tar'. The HP version of MySQL was compiled on an HP 9000/8xx server under HP-UX 10.20, and uses MIT-pthreads. It is known to work well under this configuration. MySQL Version 3.22.26 and newer can also be built with HP's native thread package. Other configurations that may work: * HP 9000/7xx running HP-UX 10.20+ * HP 9000/8xx running HP-UX 10.30 The following configurations almost definitely won't work: * HP 9000/7xx or 8xx running HP-UX 10.x where x < 2 * HP 9000/7xx or 8xx running HP-UX 9.x To install the distribution, use one of the commands here, where `/path/to/depot' is the full pathname of the depot file: * To install everything, including the server, client and development tools: shell> /usr/sbin/swinstall -s /path/to/depot mysql.full * To install only the server: shell> /usr/sbin/swinstall -s /path/to/depot mysql.server * To install only the client package: shell> /usr/sbin/swinstall -s /path/to/depot mysql.client * To install only the development tools: shell> /usr/sbin/swinstall -s /path/to/depot mysql.developer The depot places binaries and libraries in `/opt/mysql' and data in `/var/opt/mysql'. The depot also creates the appropriate entries in `/etc/init.d' and `/etc/rc2.d' to start the server automatically at boot time. Obviously, this entails being `root' to install. 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 `tar' files (files with a `.tar.gz' extension). See *Note MySQL binaries:: for a detailed list. In addition to these generic packages, we also offer binaries in platform-specific package formats for selected platforms. See *Note Quick Standard Installation:: 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, Sun `tar' and Mac OS X `tar' are known to have problems with long filenames. In such cases, you should install GNU `tar' first. On Mac OS X, you can use the pre-installed `gnutar' program. If you run into problems, *please always use `mysqlbug'* when posting questions to a MySQL mailing list. Even if the problem isn't a bug, `mysqlbug' gathers system information that will help others solve your problem. By not using `mysqlbug', you lessen the likelihood of getting a solution to your problem. You will find `mysqlbug' in the `bin' directory after you unpack the distribution. *Note Bug reports::. The basic commands you must execute to install and use a MySQL binary distribution are: shell> groupadd mysql shell> useradd -g mysql mysql shell> cd /usr/local shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf - shell> ln -s full-path-to-mysql-VERSION-OS mysql shell> cd mysql shell> scripts/mysql_install_db shell> chown -R root . shell> chown -R mysql data shell> chgrp -R mysql . shell> bin/mysqld_safe --user=mysql & For versions of MySQL older than 4.0, substitute `bin/safe_mysqld' for `bin/mysqld_safe' in the final command. A more detailed description follows. To install a binary distribution, follow these steps, then proceed to *Note Post-installation::, for post-installation setup and testing: 1. Add a user and group for `mysqld' to run as: shell> groupadd mysql shell> useradd -g mysql mysql These commands add the `mysql' group and the `mysql' user. The syntax for `useradd' and `groupadd' may differ slightly on different versions of Unix. They may also be called `adduser' and `addgroup'. You may wish to call the user and group something else instead of `mysql'. 2. Pick the directory under which you want to unpack the distribution, and move into it. In the following example, we unpack the distribution under `/usr/local' (The following instructions, therefore, assume you have permission to create files and directories in `/usr/local'. If that directory is protected, you will need to perform the installation as `root'.) 3. Obtain a distribution file from one of the sites listed in *Note Getting MySQL: Getting MySQL. MySQL `tar' file binary distributions have names like `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-gnu-i586'). For a given release, binary distributions for all platforms are built from the same MySQL source distribution. 4. Change into the intended installation directory: shell> cd /usr/local 5. Unpack the distribution, which will create the installation directory. Then create a symbolic link to that directory: shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf - shell> ln -s full-path-to-mysql-VERSION-OS mysql 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 6. Change into the installation directory: shell> cd mysql You will find several files and subdirectories in the `mysql' directory. The most important for installation purposes are the `bin' and `scripts' subdirectories. `bin' 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. *Note 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. 7. If you haven't installed MySQL before, you must create the MySQL grant tables: shell> scripts/mysql_install_db Note that for MySQL versions older than Version 3.22.10, `mysql_install_db' left the server running after creating the grant tables. This is no longer true; you will need to restart the server after performing the remaining steps in this procedure. 8. Change ownership of program binaries to `root' and ownership of the data directory to the user that you will 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. 9. 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 *Note Automatic start::. 10. 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 *Note Perl support::. 11. If you would like to use `mysqlaccess' and have the MySQL distribution in some non-standard place, you must change the location where `mysqlaccess' expects to find the `mysql' client. Edit the `bin/mysqlaccess' script at approximately line 18. Search for a line that looks like this: $MYSQL = '/usr/local/bin/mysql'; # path to mysql executable Change the path to reflect the location where `mysql' actually is stored on your system. If you do not do this, you will get a `Broken pipe' error when you run `mysqlaccess'. 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. Now proceed to *Note `mysqld_safe': mysqld_safe, and *Note Post-installation::. MySQL Installation Using a Source Distribution ============================================== Before you proceed with the source installation, check first to see whether our binary is available for your platform and whether it will work for you. We put a lot of effort into making sure that our binaries are built with the best possible options. You need the following tools to build and install MySQL from source: * GNU `gunzip' to uncompress the distribution. * A reasonable `tar' to unpack the distribution. GNU `tar' is known to work. Some `tar' implementations that come pre-installed with the operating system (for example, Sun `tar') is known to have problems with long file names). In that case, 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 only have `gcc' 2.7.x, you must upgrade your `gcc' to be able to compile MySQL. `gcc' 2.8.1 is also known to have problems on some platforms, so it should be avoided if a new compiler exists for the platform. `gcc' 2.95.2 or later is recommended when compiling MySQL Version 3.23.x. * A good `make' program. GNU `make' is always recommended and is sometimes required. If you have problems, we recommend trying GNU `make' 3.75 or newer. If you are using a recent version of `gcc', recent enough to understand the `-fno-exceptions' option, it is *very important* that you use it. Otherwise, you may compile a binary that crashes randomly. We also recommend that you use `-felide-constructors' and `-fno-rtti' along with `-fno-exceptions'. When in doubt, do the following: CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors \ -fno-exceptions -fno-rtti" ./configure \ --prefix=/usr/local/mysql --enable-assembler \ --with-mysqld-ldflags=-all-static On most systems this will give you a fast and stable binary. If you run into problems, *please always use `mysqlbug'* when posting questions to a MySQL mailing list. Even if the problem isn't a bug, `mysqlbug' gathers system information that will help others solve your problem. By not using `mysqlbug', you lessen the likelihood of getting a solution to your problem. You will find `mysqlbug' in the `scripts' directory after you unpack the distribution. *Note Bug reports::. Quick Source Installation Overview ---------------------------------- The basic commands you must execute to install a MySQL source distribution are: shell> groupadd mysql shell> useradd -g mysql mysql shell> gunzip < mysql-VERSION.tar.gz | tar -xvf - shell> cd mysql-VERSION shell> ./configure --prefix=/usr/local/mysql shell> make shell> make install shell> cp support-files/my-medium.cnf /etc/my.cnf shell> cd /usr/local/mysql shell> bin/mysql_install_db shell> chown -R root . shell> chown -R mysql var shell> chgrp -R mysql . shell> bin/mysqld_safe --user=mysql & For versions of MySQL older than 4.0, substitute `bin/safe_mysqld' for `bin/mysqld_safe' in the final command. If you start from a source RPM, do the following: shell> rpm --rebuild --clean MySQL-VERSION.src.rpm This will make a binary RPM that you can install. A more detailed description follows. To install a source distribution, follow these steps, then proceed to *Note Post-installation::, for post-installation initialization and testing: 1. Add a user and group for `mysqld' to run as: shell> groupadd mysql shell> useradd -g mysql mysql These commands add the `mysql' group and the `mysql' user. The syntax for `useradd' and `groupadd' may differ slightly on different versions of Unix. They may also be called `adduser' and `addgroup'. You may wish to call the user and group something else instead of `mysql'. 2. Pick the directory under which you want to unpack the distribution, and move into it. 3. Obtain a distribution file from one of the sites listed in *Note Getting MySQL: Getting MySQL. MySQL source distributions are provided as compressed `tar' archives and have names like `mysql-VERSION.tar.gz', where `VERSION' is a number like `4.0.18'. 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 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. *Note `configure' options: 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. *Note Bug reports::. If the compile fails, see *Note Compilation problems::, for help with a number of common problems. 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 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. *Note Option files::, and *Note InnoDB start::. 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: shell> bin/mysql_install_db Note that for MySQL versions older than Version 3.22.10, `mysql_install_db' left the server running after creating the grant tables. This is no longer true; you will need to restart the server after performing the remaining steps in this procedure. 10. Change ownership of binaries to `root' and ownership of the data directory to the user that you will 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 *Note Automatic start::. 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 *Note Perl support::. 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 `bin/safe_mysqld' for `bin/mysqld_safe' in the command. If that command fails immediately and prints `mysqld ended', you can find some information in the file `mysql-data-directory/'hostname'.err'. The likely reason is that you already have another `mysqld' server running. *Note Multiple servers::. Now proceed to *Note Post-installation::. 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. *Note Environment variables::. For a list of options supported by `configure', run this command: shell> ./configure --help Some of the more commonly used `configure' options are described here: * To compile just the MySQL client libraries and client programs and not the server, use the `--without-server' option: shell> ./configure --without-server If you don't have a C++ compiler, `mysql' will not compile (it is the one client program that requires C++). In this case, you can remove the code in `configure' that tests for the C++ compiler and then run `./configure' with the `--without-server' option. The compile step will still try to build `mysql', but you can ignore any warnings about `mysql.cc'. (If `make' stops, try `make -k' to tell it to continue with the rest of the build even if errors occur.) * If you want to get an embedded MySQL library (`libmysqld.a') you should use the `--with-embedded-server' option. * If you don't want your log files and database directories located under `/usr/local/var', use a `configure' command, something like one of these: shell> ./configure --prefix=/usr/local/mysql shell> ./configure --prefix=/usr/local \ --localstatedir=/usr/local/mysql/data The first command changes the installation prefix so that everything is installed under `/usr/local/mysql' rather than the default of `/usr/local'. The second command preserves the default installation prefix, but overrides the default location for database directories (normally `/usr/local/var') and changes it to `/usr/local/mysql/data'. After you have compiled MySQL, you can change these options with option files. *Note 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 Note that the given file must be an absolute pathname. You can also later change the location of `mysql.sock' by using a MySQL option file. *Note Problems with `mysql.sock': Problems with 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 will not attempt to link in `libg++' or `libstdc++'. This may be a good idea to do even if you have the above libraries installed, as some versions of these libraries have caused strange problems for MySQL users in the past. The following list indicates some compilers and environment variable settings that are commonly used with each one. `gcc' 2.7.2: `CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors"' `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 optimal 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. *Note MySQL binaries::. There are some configuration setings you can tweak to make an even faster binary, but this is only for advanced users. *Note Compile and link options::. If the build fails and produces errors about your compiler or linker not being able to create the shared library `libmysqlclient.so.#' (`#' is a version number), you can work around this problem by giving the `--disable-shared' option to `configure'. In this case, `configure' will not build a shared `libmysqlclient.so.#' library. * You can configure MySQL not to use `DEFAULT' column values for non-`NULL' columns (that is, columns that are not allowed to be `NULL'). *Note constraint NOT NULL::. shell> CXXFLAGS=-DDONT_USE_DEFAULT_FIELDS ./configure The effect of this flag is to cause any `INSERT' statement to fail unless it provides explicit values for all columns that require a non-`NULL' value. * By default, MySQL uses the ISO-8859-1 (Latin1) 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'. *Note Character sets::. If you want to convert characters between the server and the client, you should take a look at the `SET CHARACTER SET' command. *Note `SET': SET OPTION. *Warning:* If you change character sets after having created any tables, you will have to run `myisamchk -r -q --set-character-set=charset' on every table. Your indexes may be sorted incorrectly otherwise. (This can happen if you install MySQL, create some tables, then reconfigure MySQL to use a different character set and reinstall it.) With the `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 sets separated with spaces, `complex' to include all characters that can't be dynamically loaded, or `all' to include all character sets into the binaries. * To configure MySQL with debugging code, use the `--with-debug' option: shell> ./configure --with-debug This causes a safe memory allocator to be included that can find some errors and that provides output about what is happening. *Note Debugging 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 options. This will create a `libmysqlclient_r' library with which you should link your threaded applications. *Note Threaded clients::. * Options that pertain to particular systems can be found in the system-specific section of this manual. *Note Operating System Specific Notes::. Installing from the Development Source Tree ------------------------------------------- *Caution*: You should read this section only if you are interested in helping us test our new code. If you just want to get MySQL up and running on your system, you should use a standard release distribution (either a binary or source distribution will do). To obtain our most recent development source tree, use these instructions: 1. Download `BitKeeper' from `http://www.bitmover.com/cgi-bin/download.cgi'. You will need `Bitkeeper' 3.0 or newer to access our repository. 2. Follow the instructions to install it. 3. After `BitKeeper' is installed, first go to the directory you want to work from, and then use one of the following commands to clone the MySQL version branch of your choice: To clone the old 3.23 branch, use this command: shell> bk clone bk://mysql.bkbits.net/mysql-3.23 mysql-3.23 To clone the 4.0 stable (production) branch, use this command: shell> bk clone bk://mysql.bkbits.net/mysql-4.0 mysql-4.0 To clone the 4.1 alpha branch, use this command: shell> bk clone bk://mysql.bkbits.net/mysql-4.1 mysql-4.1 To clone the 5.0 development branch, use this command: shell> bk clone bk://mysql.bkbits.net/mysql-5.0 mysql-5.0 In the preceding examples the source tree will be set up in the `mysql-3.23/', `mysql-4.0/', `mysql-4.1/', or `mysql-5.0/' subdirectory of your current directory. If you are behind a firewall and can only initiate HTTP connections, you can also use `BitKeeper' via HTTP. If you are required to use a proxy server, set the environment variable `http_proxy' to point to your proxy: shell> export http_proxy="http://your.proxy.server:8080/" Now, simply replace the `bk://' with `http://' when doing a clone. Example: shell> bk clone http://mysql.bkbits.net/mysql-4.1 mysql-4.1 The initial download of the source tree may take a while, depending on the speed of your connection--please be patient. 4. You will need GNU `make', `autoconf' 2.53 (or newer), `automake' 1.5, `libtool' 1.4, and `m4' to run the next set of commands. Even though many operating systems already come with their own implementation of `make', chances are high that the compilation will fail 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 already ship with the GNU toolchain preinstalled or supply installable packages of these. In any case, they can also be downloaded from the following locations: * * * * If you are trying to configure MySQL 4.1 or later, you will 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 `mysql-4.0' with the appropriate directory name. shell> cd mysql-4.0 shell> bk -r edit shell> aclocal; autoheader; autoconf; automake shell> (cd innobase; aclocal; autoheader; autoconf; automake) shell> (cd bdb/dist; sh s_all) shell> ./configure # Add your favorite options here make The command lines that change directory into the `innobase' and `bdb/dist' directories are used to configure 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 error during this stage, check 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. 5. 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. 6. Play hard with your new installation and try to make the new features crash. Start by running `make test'. *Note MySQL test suite::. 7. If you have gotten to the `make' stage and the distribution does not compile, please report it in our bugs database at `http://bugs.mysql.com/'. If you have installed the latest versions of the required GNU tools, and they crash trying to process our configuration files, please report that also. However, if you execute `aclocal' and get a `command not found' error or a similar problem, do not report it. Instead, make sure all the necessary tools are installed and that your `PATH' variable is set correctly so that your shell can find them. 8. After the initial `bk clone' operation to obtain the source tree, you should run `bk pull' periodically to get updates. 9. You can examine the change history for the tree with all the diffs by using `bk revtool'. If you see some funny diffs or code that you have a question about, do not hesitate to send email to the MySQL internals mailing list. *Note Mailing-list::. Also, if you think you have a better idea on how to do something, send an email message to the same address with a patch. `bk diffs' will produce a patch for you after you have made changes to the source. If you do not have the time to code your idea, just send a description. 10. `BitKeeper' has a nice help utility that you can access via `bk helptool'. 11. Please note that any commits (`bk ci' or `bk citool') will trigger the posting of a message with the changeset to our internals mailing list, as well as the usual openlogging.org submission with just the changeset comments. Generally, you wouldn't need to use commit (since the public tree will not allow `bk push'), but rather use the `bk diffs' method described previously. You can also browse changesets, comments, and source code online. For example, to browse this information for MySQL 4.1, go to `http://mysql.bkbits.net:8080/mysql-4.1'. The manual is in a separate tree which can be cloned with: shell> bk clone bk://mysql.bkbits.net/mysqldoc mysqldoc There are also public BitKeeper trees for MySQL Control Center and Connector/ODBC. They can be cloned respectively as follows. To clone MySQL Control center, use this command: shell> bk clone http://mysql.bkbits.net/mysqlcc mysqlcc To clone Connector/ODBC, use this command: shell> bk clone http://mysql.bkbits.net/myodbc3 myodbc3 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 *Note MIT-pthreads:: 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 already has been run, it may use information that was gathered during its previous invocation. This information is stored in `config.cache'. When `configure' starts up, it looks for that file and reads its contents if it exists, on the assumption that the information is still correct. That assumption is invalid when you reconfigure. * Each time you run `configure', you must run `make' again to recompile. However, you may want to remove old object files from previous builds first because they were compiled using different configuration options. To prevent old configuration information or object files from being used, run these commands before 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 when compiling `sql_yacc.cc', such as the ones shown here, you have probably run out of memory or swap space: Internal compiler error: program cc1plus got fatal signal 11 or: Out of virtual memory or: Virtual memory exhausted The problem is that `gcc' requires huge amounts of memory to compile `sql_yacc.cc' with inline functions. Try running `configure' with the `--with-low-memory' option: shell> ./configure --with-low-memory This option causes `-fno-inline' to be added to the compile line if you are using `gcc' and `-O0' if you are using something else. You should try the `--with-low-memory' option even if you have so much memory and swap space that you think you can't possibly have run out. This problem has been observed to occur even on systems with generous hardware configurations, and the `--with-low-memory' option usually fixes it. * By default, `configure' picks `c++' as the compiler name and GNU `c++' links with `-lg++'. If you are using `gcc', that 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 you to not use `libg++' or `libstdc++' with MySQL as this will only increase the binary size of mysqld without giving you any benefits. Some versions of these libraries have also caused strange problems for MySQL users in the past. Using `gcc' as the C++ compiler is also required, if you want to compile MySQL with RAID functionality (see *Note CREATE TABLE:: for more info on RAID table type) and you are using GNU `gcc' version 3 and above. If you get errors like the ones below during the linking stage when you configure MySQL to compile with the option `--with-raid', try to use `gcc' as your C++ compiler by defining the above mentioned environment variable `CXX': gcc -O3 -DDBUG_OFF -rdynamic -o isamchk isamchk.o sort.o libnisam.a ../mysys/libmysys.a ../dbug/libdbug.a ../strings/libmystrings.a -lpthread -lz -lcrypt -lnsl -lm -lpthread ../mysys/libmysys.a(raid.o)(.text+0x79): In function `my_raid_create':: undefined reference to `operator new(unsigned)' ../mysys/libmysys.a(raid.o)(.text+0xdd): In function `my_raid_create':: undefined reference to `operator delete(void*)' ../mysys/libmysys.a(raid.o)(.text+0x129): In function `my_raid_open':: undefined reference to `operator new(unsigned)' ../mysys/libmysys.a(raid.o)(.text+0x189): In function `my_raid_open':: undefined reference to `operator delete(void*)' ../mysys/libmysys.a(raid.o)(.text+0x64b): In function `my_raid_close':: undefined reference to `operator delete(void*)' collect2: ld returned 1 exit status * If your compile fails with errors, such as any of the following, you must upgrade your version of `make' to GNU `make': making all in mit-pthreads make: Fatal error in reader: Makefile, line 18: Badly formed macro assignment or: make: file `Makefile' line 18: Must be a separator (: or: pthread.h: No such file or directory Solaris and FreeBSD are known to have troublesome `make' programs. GNU `make' Version 3.75 is known to work. * If you want to define flags to be used by your C or C++ compilers, do so by adding the flags to the `CFLAGS' and `CXXFLAGS' environment variables. You can also specify the compiler names this way using `CC' and `CXX'. For example: shell> CC=gcc shell> CFLAGS=-O3 shell> CXX=gcc shell> CXXFLAGS=-O3 shell> export CC CFLAGS CXX CXXFLAGS See *Note MySQL binaries::, for a list of flag definitions that have been found to be useful on various systems. * If you get an error message like this, you need to upgrade your `gcc' compiler: client/libmysql.c:273: parse error before `__attribute__' `gcc' 2.8.1 is known to work, but we recommend using `gcc' 2.95.2 or `egcs' 1.0.3a instead. * If you get errors such as those shown here when compiling `mysqld', `configure' didn't correctly detect the type of the last argument to `accept()', `getsockname()', or `getpeername()': cxx: Error: mysqld.cc, line 645: In this statement, the referenced type of the pointer value ''length'' is ''unsigned long'', which is not compatible with ''int''. new_sock = accept(sock, (struct sockaddr *)&cAddr, &length); To fix this, edit the `config.h' file (which is generated by `configure'). Look for these lines: /* Define as the base type of the last arg to accept */ #define SOCKET_SIZE_TYPE XXX Change `XXX' to `size_t' or `int', depending on your operating system. (Note that you will have to do this each time you run `configure' because `configure' regenerates `config.h'.) * The `sql_yacc.cc' file is generated from `sql_yacc.yy'. Normally the build process doesn't need to create `sql_yacc.cc', because MySQL comes with an already generated copy. However, if you do need to re-create it, you might encounter this error: "sql_yacc.yy", line xxx fatal: default action causes potential... This is a sign that your version of `yacc' is deficient. You probably need to install `bison' (the GNU version of `yacc') and use that instead. * 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. *Note Debugging client::. * If you get a compilation error on Linux (e.g. SuSE Linux 8.1 or Red Hat Linux 7.3) similar to the following one: libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from incompatible 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 afterwards. MIT-pthreads Notes ------------------ This section describes some of the issues involved in using MIT-pthreads. Note that on Linux you should *not* use MIT-pthreads but use the installed LinuxThreads implementation instead. *Note Linux::. If your system does not provide native thread support, you will need to build MySQL using the MIT-pthreads package. This includes older FreeBSD systems, SunOS 4.x, Solaris 2.4 and earlier, and some others. *Note Which OS::. Note that, beginning with MySQL 4.0.2, MIT-pthreads are no longer part of the source distribution. If you require this package, you need to download it separately from After downloading, extract this source archive into the top level of the MySQL source directory. It will create a new subdirectory `mit-pthreads'. * On most systems, you can force MIT-pthreads to be used by running `configure' with the `--with-mit-threads' option: shell> ./configure --with-mit-threads Building in a non-source directory is not supported when using MIT-pthreads because we want to minimise our changes to this code. * The checks that determine whether to use MIT-pthreads occur only during the part of the configuration process that deals with the server code. If you have configured the distribution using `--without-server' to build only the client code, clients will not know whether MIT-pthreads is being used and will use Unix socket connections by default. Because Unix socket files do not work under MIT-pthreads on some platforms, this means you will need to use `-h' or `--host' when you run client programs. * When MySQL is compiled using MIT-pthreads, system locking is disabled by default for performance reasons. You can tell the server to use system locking with the `--external-locking' option. This is only needed if you want to be able to run two MySQL servers against the same datafiles (not recommended). * Sometimes the pthread `bind()' command fails to bind to a socket without any error message (at least on Solaris). The result is that all connections to the server fail. For example: shell> mysqladmin version mysqladmin: connect to server at '' failed; error: 'Can't connect to mysql server on localhost (146)' The solution to this is to kill the `mysqld' server and restart it. This has only happened to us when we have forced down the server and done a restart immediately. * With MIT-pthreads, the `sleep()' system call isn't interruptible with `SIGINT' (break). This is only noticeable when you run `mysqladmin --sleep'. You must wait for the `sleep()' call to terminate before the interrupt is served and the process stops. * When linking, you may receive warning messages like these (at least on Solaris); they can be ignored: ld: warning: symbol `_iob' has differing sizes: (file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4; file /usr/lib/libc.so value=0x140); /my/local/pthreads/lib/libpthread.a(findfp.o) definition taken ld: warning: symbol `__iob' has differing sizes: (file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4; file /usr/lib/libc.so value=0x140); /my/local/pthreads/lib/libpthread.a(findfp.o) definition taken * Some other warnings also can be ignored: implicit declaration of function `int strtoll(...)' implicit declaration of function `int strtoul(...)' * We haven't gotten `readline' to work with MIT-pthreads. (This isn't needed, but may be interesting for someone.) 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 *Note Windows installation::. To build MySQL on Windows from source, you need the following compiler and resources available on your Windows system: * VC++ 6.0 compiler (updated with 4 or 5 SP and pre-processor package). The pre-processor package is necessary for the macro assembler. More details at: `http://msdn.microsoft.com/vstudio/downloads/updates/sp/vs6/sp5/faq.aspx'. * Approximately 45 MB disk space. * 64 MB RAM. You'll also need a MySQL source distribution for Windows. There are two ways you can get a source distribution for MySQL version 4.1 and above: 1. Obtain a source distribution packaged by MySQL AB for the particular version of MySQL in which you are interested. Prepackaged source distributions are available for released versions of MySQL and can be obtained from `http://www.mysql.com/downloads/'. 2. You can package a source distribution yourself from the latest BitKeeper developer source tree. If you plan to do this, you must create the package on a Unix system and then transfer it to your Windows system. (The reason for this is that some of the configuration and build steps require tools that work only on Unix.) The BitKeeper approach thus requires: * A system running Unix, or a Unix-like system such as Linux. * BitKeeper 3.0 installed on that system. You can obtain BitKeeper from `http://www.bitkeeper.com/'. If you are using a Windows source distribution, you can go directly to *Note Windows VC++ Build::. To build from the BitKeeper tree, proceed to *Note Windows BitKeeper Build::. 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. *Note Mailing-list::. Building MySQL Using VC++ ......................... *Note:* MySQL 4.1 and above VC++ workspace files are compatible with Microsoft Visual Studio 6.0 and above(7.0/.NET) editions and tested by MySQL AB staff before each release. Follow this procedure to build MySQL: 1. Create a work directory (for example, `workdir'). 2. Unpack the source distribution in the aforementioned directory using `WinZip' or other Windows tools that can read `.zip' files. 3. Start the VC++ 6.0 compiler. 4. In the `File' menu, select `Open Workspace'. 5. Open the `mysql.dsw' workspace you find in the work directory. 6. From the `Build' menu, select the `Set Active Configuration' menu. 7. Click over the screen selecting `mysqld - Win32 Debug' and click OK. 8. Press `F7' to begin the build of the debug server, libraries, and some client applications. 9. Compile the release versions that you want, in the same way. 10. Debug versions of the programs and libraries are placed in the `client_debug' and `lib_debug' directories. Release versions of the programs and libraries are placed in the `client_release' and `lib_release' directories. Note that if you want to build both debug and release versions, you can select the "build all" option from the `Build' menu. 11. Test the server. The server built using the preceding instructions will expect that the MySQL base directory and data directory are `C:\mysql' and `C:\mysql\data' by default. If you want to test your server using the source tree root directory and its data directory as the base directory and data directory, you will need to tell the server their pathnames. You can either do this on the command line with the `--basedir' and `--datadir' options, or place appropriate options in an option file (`C:\my.cnf' or the `my.ini' file in your Windows directory). If you have an existing data directory elsewhere that you want to use, you can specify its pathname instead. 12. Start your server from the `client_release' or `client_debug' directory, depending on which server you want to use. The general server startup instructions are at *Note Windows installation::. You'll need to to adapt the instructions appropriately if you want to use a different base directory or data directory. 13. When the server is running in standalone fashion or as a service based on your configuration, try to connect to it from the `mysql' interactive command line utility that exists in your `client_release' or `client_debug' directory. When you are satisifed that the programs you have built are working correctly, stop the server. Then install MySQL as follows: 1. Create the directories where you want to install MySQL. For example, to install into `C:\mysql', use these commands: C: mkdir \mysql mkdir \mysql\bin mkdir \mysql\data mkdir \mysql\share mkdir \mysql\scripts If you want to compile other clients and link them to MySQL, you should also create several additional directories: mkdir \mysql\include mkdir \mysql\lib mkdir \mysql\lib\debug mkdir \mysql\lib\opt If you want to benchmark MySQL, create this directory: mkdir \mysql\sql-bench Benchmarking requires Perl support. 2. From the `workdir' directory, copy into the `C:\mysql' directory the following directories: copy client_release\*.exe C:\mysql\bin copy client_debug\mysqld.exe C:\mysql\bin\mysqld-debug.exe xcopy scripts\*.* C:\mysql\scripts /E xcopy share\*.* C:\mysql\share /E If you want to compile other clients and link them to MySQL, you should also copy several libraries and header files: copy lib_debug\mysqlclient.lib C:\mysql\lib\debug copy lib_debug\libmysql.* C:\mysql\lib\debug copy lib_debug\zlib.* C:\mysql\lib\debug copy lib_release\mysqlclient.lib C:\mysql\lib\opt copy lib_release\libmysql.* C:\mysql\lib\opt copy lib_release\zlib.* C:\mysql\lib\opt copy include\*.h C:\mysql\include copy libmysql\libmysql.def C:\mysql\include If you want to benchmark MySQL, you should also do this: xcopy sql-bench\*.* C:\mysql\bench /E Set up and start the server in the same way as for the binary Windows distribution. *Note Windows installation::. Creating a Windows Source Package from the Latest Development Source .................................................................... To create a Windows source package from the current BitKeeper source tree, use the following instructions. Please note that this procedure must be performed on a system running a Unix or Unix-like operating system. (The procedure is known to work well on Linux, for example.) 1. Clone the BitKeeper source tree for MySQL (version 4.1 or above, as desired). For more information how to clone the source tree, see the instructions at *Note Installing source tree::. 2. Configure and build the distribution so that you have a server binary to work with. One way to do this is to run the following command in the top-level directory of your source tree: shell> ./BUILD/compile-pentium-max 3. After making sure that the build process completed successfully, run the following utility script from top-level directory of your source tree: shell> ./scripts/make_win_src_distribution This script creates a Windows source package, to be used on your Windows system. You can supply different options to the script based on your needs. It accepts the following options: --debug 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 --help Show this help message By default, `make_win_src_distribution' creates a zipped archive with the name `mysql-VERSION-win-src.zip', where `VERSION' represents the version of your MySQL source tree. 4. Copy or upload to your Windows machine the Windows source package that you have just created. To compile it, use the instructions in *Note Windows VC++ Build::. Compiling MySQL Clients on Windows ---------------------------------- In your source files, you should include `my_global.h' before `mysql.h': #include #include `my_global.h' includes any other files needed for Windows compatibility (such as `windows.h') if you compile your program on Windows. You can either link your code with the dynamic `libmysql.lib' library, which is just a wrapper to load in `libmysql.dll' on demand, or link with the static `mysqlclient.lib' library. Note that because the MySQL client libraries are compiled as threaded libraries, you should also compile your code to be multi-threaded! Post-installation Setup and Testing =================================== There are some issues you should address after installing MySQL. For example, on Unix, you should 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. The following sections describe post-installation procedures for Windows systems and for Unix systems. Windows Post-installation Procedures ------------------------------------ On Windows, the grant tables do not have to be created. MySQL Windows distributions include the grant tables already set up in the `mysql' database under the `data' directory. However, you should assign passwords to the accounts. The default privileges on Windows give all local users full privileges to all databases without specifying a password. To make MySQL more secure, you should set a password for all users and remove the row in the `mysql.user' table that has `Host='localhost'' and `User='''. You should also add a password for the `root' user. The following example starts by removing the anonymous user that has all privileges, then sets a `root' user password: C:\> C:\mysql\bin\mysql mysql mysql> DELETE FROM user WHERE Host='localhost' AND User=''; mysql> FLUSH PRIVILEGES; mysql> QUIT C:\> C:\mysql\bin\mysqladmin -u root password your_password After you've set the password, if you want to shut down the `mysqld' server, you can do so using this command: C:\> mysqladmin --user=root --password=your_password shutdown If you are using a server from a _very_ old version of MySQL, the `mysqladmin' command to set the password will fail with an error: `parse error near 'SET password''. The solution to this problem is to upgrade to a newer version of MySQL. With the current MySQL versions you can easily add new users and change privileges with `GRANT' and `REVOKE' commands. *Note `GRANT': GRANT. Unix Post-installation Procedures --------------------------------- After you install 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. Normally you install the grant tables and start the server like this for installation from a source distribution: shell> cd mysql_installation_directory shell> bin/mysql_install_db shell> bin/mysqld_safe --user=mysql & For a binary distribution (not RPM or PKG packages), do this: shell> cd mysql_installation_directory shell> scripts/mysql_install_db shell> bin/mysqld_safe --user=mysql & The `mysql_install_db' script creates the `mysql' database 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 entries are created without passwords. The `mysqld_safe' script starts the `mysqld' server. (For versions of MySQL older than 4.0, use `safe_mysqld' rather than `mysqld_safe'.) `mysql_install_db' will not overwrite any old privilege tables, so it should be safe to run in any circumstances. If you don't want to have the `test' database you can remove it with `mysqladmin -u root drop test' after starting the server. Testing is most easily done from the top-level directory of the MySQL distribution. For a binary distribution, this is your installation directory (typically something like `/usr/local/mysql'). For a source distribution, this is the main directory of your MySQL source tree. In the commands shown in this section and in the following subsections, `BINDIR' is the path to the location in which programs like `mysqladmin' and `mysqld_safe' are installed. For a binary distribution, this is the `bin' directory within the distribution. For a source distribution, `BINDIR' is probably `/usr/local/bin', unless you specified an installation directory other than `/usr/local' when you ran `configure'. `EXECDIR' is the location in which the `mysqld' server is installed. For a binary distribution, this is the same as `BINDIR'. For a source distribution, `EXECDIR' is probably `/usr/local/libexec'. Testing is described in detail: 1. If necessary, start the `mysqld' server and set up the initial MySQL grant tables containing the privileges that determine how users are allowed to connect to the server. This is normally done with the `mysql_install_db' script: shell> scripts/mysql_install_db Typically, `mysql_install_db' needs to be run only the first time you install MySQL. Therefore, if you are upgrading an existing installation, you can skip this step. (However, `mysql_install_db' is quite safe to use and will not update any tables that already exist, so if you are unsure of what to do, you can always run `mysql_install_db'.) `mysql_install_db' creates six tables (`user', `db', `host', `tables_priv', `columns_priv', and `func') in the `mysql' database. A description of the initial privileges is given in *Note Default privileges::. Briefly, these privileges allow the MySQL `root' user to do anything, and allow anybody to create or use databases with a name of `test' or starting with `test_'. If you don't set up the grant tables, the following error will appear in the log file when you start the server: mysqld: Can't find file: 'host.frm' This may also happen with a binary MySQL distribution if you don't start MySQL by executing exactly `./bin/mysqld_safe'. *Note `mysqld_safe': mysqld_safe. You might need to run `mysql_install_db' as `root'. However, if you prefer, you can run the MySQL server as an unprivileged (non-`root') user, provided that the user can read and write files in the database directory. Instructions for running MySQL as an unprivileged user are given in *Note Changing MySQL user: Changing MySQL user. If you have problems with `mysql_install_db', see *Note `mysql_install_db': mysql_install_db. There are some alternatives to running the `mysql_install_db' script as it is provided in the MySQL distribution: * You may want to edit `mysql_install_db' before running it, to change the initial privileges that are installed into the grant tables. This is useful if you want to install MySQL on a lot of machines with the same privileges. In this case you probably should need only to add a few extra `INSERT' statements to the `mysql.user' and `mysql.db' tables. * If you want to change the contents of the grant tables after installing them, you can run `mysql_install_db', then use `mysql -u root mysql' to connect to the grant tables as the MySQL `root' user and issue SQL statements to modify the grant tables directly. * It is possible to re-create the grant tables completely after they have already been created. You might want to do this if you've already installed the tables but then want to re-create them after editing `mysql_install_db'. For more information about these alternatives, see *Note Default privileges::. 2. Start the MySQL server like this: shell> cd mysql_installation_directory shell> bin/mysqld_safe & For versions of MySQL older than 4.0, substitute `bin/safe_mysqld' for `bin/mysqld_safe' in the final command. If you have problems starting the server, see *Note Starting server::. 3. Use `mysqladmin' to verify that the server is running. The following commands provide a simple test to check that the server is up and responding to connections: shell> BINDIR/mysqladmin version shell> BINDIR/mysqladmin variables The output from `mysqladmin version' varies slightly depending on your platform and version of MySQL, but should be similar to that shown here: shell> BINDIR/mysqladmin version mysqladmin Ver 8.40 Distrib 4.0.18, for linux on i586 Copyright (C) 2000 MySQL AB & MySQL Finland AB & TCX DataKonsult AB This software comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to modify and redistribute it under the GPL license Server version 4.0.18-log Protocol version 10 Connection Localhost via Unix socket TCP port 3306 UNIX socket /tmp/mysql.sock Uptime: 16 sec Threads: 1 Questions: 9 Slow queries: 0 Opens: 7 Flush tables: 2 Open tables: 0 Queries per second avg: 0.000 Memory in use: 132K Max memory used: 16773K To see what else you can do with `mysqladmin', invoke it with the `--help' option. 4. Verify that you can shut down the server: shell> BINDIR/mysqladmin -u root shutdown 5. Verify that you can restart the server. Do this using `mysqld_safe' or by invoking `mysqld' directly. For example: shell> BINDIR/mysqld_safe --log & If `mysqld_safe' fails, try running it from the MySQL installation directory (if you are not already there). If that doesn't work, see *Note Starting server::. 6. Run some simple tests to verify that the server is working. The output should be similar to what is shown here: shell> BINDIR/mysqlshow +-----------+ | Databases | +-----------+ | mysql | +-----------+ shell> BINDIR/mysqlshow mysql Database: mysql +--------------+ | Tables | +--------------+ | columns_priv | | db | | func | | host | | tables_priv | | user | +--------------+ shell> BINDIR/mysql -e "SELECT host,db,user FROM db" mysql +------+--------+------+ | host | db | user | +------+--------+------+ | % | test | | | % | test_% | | +------+--------+------+ There is also a benchmark suite in the `sql-bench' directory (under the MySQL installation directory) that you can use to compare how MySQL performs on different platforms. The benchmark suite is written in Perl. It uses the Perl DBI module to provide a database-independent interface to the various databases. The following additional Perl modules are required to run the benchmark suite: DBI DBD::mysql Data::Dumper Data::ShowTable These modules can be obtained from CPAN `http://www.cpan.org/'. *Note Perl installation::. The `sql-bench/Results' directory contains the results from many runs against different databases and platforms. To run all tests, execute these commands: shell> cd sql-bench shell> run-all-tests If you don't have the `sql-bench' directory, you probably installed MySQL using RPM files other than the source RPM. (The source RPM includes the `sql-bench' benchmark directory.) In this case, you must first install the benchmark suite before you can use it. Beginning with MySQL Version 3.22, there are separate benchmark RPM files named `mysql-bench-VERSION-i386.rpm' that contain benchmark code and data. If you have a source distribution, there are also tests in its `tests' subdirectory that you can run. For example, to run `auto_increment.tst', do this: shell> BINDIR/mysql -vvf test < ./tests/auto_increment.tst The expected result of the test can be found in the `./tests/auto_increment.res' file. Problems Running `mysql_install_db' ................................... The purpose of the `mysql_install_db' script is to generate new MySQL privilege tables. It will not overwrite existing MySQL privilege tables, and it will not affect any other data. If you want to re-create your privilege tables, you should take down the `mysqld' server, if it's running, and then do something like: mv mysql-data-directory/mysql mysql-data-directory/mysql-old mysql_install_db This section lists problems you might encounter when you run `mysql_install_db': *`mysql_install_db' doesn't install the grant tables* You may find that `mysql_install_db' fails to install the grant tables and terminates after displaying the following messages: Starting mysqld daemon with databases from XXXXXX mysqld ended In this case, you should examine the log file very carefully. The log should be located in the directory `XXXXXX' named by the error message, and should indicate why `mysqld' didn't start. If you don't understand what happened, include the log when you post a bug report. *Note Bug reports::. *There is already a `mysqld' process running* In this case, you probably don't have to run `mysql_install_db' at all. You have to run `mysql_install_db' only once, when you install MySQL the first time. *Installing a second `mysqld' server doesn't work when one server is running* This can happen when you already have an existing MySQL installation, but want to put a new installation in a different location (for example, for testing, or perhaps you simply want to run two installations at the same time). Generally the problem that occurs when you try to run the second server is that it tries to use the same socket and port as the old one. In this case you will get the error message: `Can't start server: Bind on TCP/IP port: Address already in use' or `Can't start server: Bind on unix socket...'. *Note Multiple servers::. *You don't have write access to `/tmp'* If you don't have write access to create a socket file at the default place (in `/tmp') or permission to create temporary files in `/tmp,' you will get an error when running `mysql_install_db' or when starting or using `mysqld'. You can specify a different socket and temporary directory as follows: shell> TMPDIR=/some_tmp_dir/ shell> MYSQL_UNIX_PORT=/some_tmp_dir/mysqld.sock shell> export TMPDIR MYSQL_UNIX_PORT See *Note Problems with `mysql.sock': Problems with mysql.sock. `some_tmp_dir' should be the path to some directory for which you have write permission. *Note Environment variables::. After this, you should be able to run `mysql_install_db' and start the server with these commands: shell> scripts/mysql_install_db shell> BINDIR/mysqld_safe & *`mysqld' crashes immediately* If you are running Red Hat Version 5.0 with a version of `glibc' older than 2.0.7-5, you should make sure you have installed all `glibc' patches. There is a lot of information about this in the MySQL mail archives. Links to the mail archives are available online at `http://lists.mysql.com/'. Also, see *Note Linux::. You can also start `mysqld' manually using the `--skip-grant-tables' option and add the privilege information yourself using `mysql': shell> BINDIR/mysqld_safe --skip-grant-tables & shell> BINDIR/mysql -u root mysql From `mysql', manually execute the SQL commands in `mysql_install_db'. Make sure you run `mysqladmin flush-privileges' or `mysqladmin reload' afterward to tell the server to reload the grant tables. 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 Windows NT, 2000, and XP. For instructions, see *Note NT start::. * By invoking `mysql.server'. This script is used primarily at system startup and shutdown on systems that use System V-style run directories. It is described more fully later in this section. * 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. It also is invoked by `mysql.server'. *Note `mysqld_safe': mysqld_safe. The `mysql.server' and `mysqld_safe' scripts can be used to start the server automatically at system startup time. `mysql.server' can also be used to stop the server. The `mysql.server' script can be used to start or stop the server by invoking it with `start' or `stop' arguments: shell> mysql.server start shell> mysql.server stop `mysql.server' can be found in the `share/mysql' directory under the MySQL installation directory or in the `support-files' directory of the MySQL source tree. Note that if you use the Linux RPM package (`MySQL-server-VERSION.rpm'), the `mysql.server' script has already been installed as `/etc/init.d/mysql'. You don't have to install it manually. See *Note Linux-RPM:: for more information on the Linux RPM packages. On Mac OS X, you can install a separate MySQL Startup Item package to enable the automatic startup of MySQL on system bootup. See *Note Mac OS X installation:: for details. Before `mysql.server' starts the server, it changes the directory to the MySQL installation directory, then invokes `mysqld_safe'. You might need to edit `mysql.server' if you have a binary distribution that you've installed in a non-standard location. Modify it to `cd' into the proper directory before it runs `mysqld_safe'. If you want the server to run as some specific user, add an appropriate `user' line to the `/etc/my.cnf' file, as shown later in this section. `mysql.server stop' brings down the server by sending a signal to it. You can also stop the server manually by executing `mysqladmin shutdown'. You need to add these start and stop commands to the appropriate places in your `/etc/rc*' files when you want to start up MySQL automatically on your server. On most current Linux distributions, it is sufficient to copy the file `mysql.server' into the `/etc/init.d' directory (or `/etc/rc.d/init.d' on older Red Hat systems). Afterwards, run the following command to enable the startup of MySQL on system bootup: shell> chkconfig --add mysql.server On FreeBSD startup scripts generally should go in `/usr/local/etc/rc.d/'. The `rc(8)' manual page also states that scripts in this directory are only executed, if their basename matches the shell globbing pattern `*.sh'. Any other files or directories present within the directory are silently ignored. In other words, on FreeBSD you should install the file `mysql.server' as `/usr/local/etc/rc.d/mysql.server.sh' to enable automatic startup. As an alternative to the above, some operating systems also use `/etc/rc.local' or `/etc/init.d/boot.local' to start additional services on bootup. To start up MySQL using this method, you could append something like the following to it: /bin/sh -c 'cd /usr/local/mysql; ./bin/mysqld_safe --user=mysql &' You can also add options for `mysql.server' in a global `/etc/my.cnf' file. A typical `/etc/my.cnf' file might look like this: [mysqld] datadir=/usr/local/mysql/var socket=/var/tmp/mysql.sock port=3306 user=mysql [mysql.server] basedir=/usr/local/mysql The `mysql.server' script understands the following options: `datadir', `basedir', and `pid-file'. The following table shows which option groups each startup script reads from option files: *Script* *Option groups* `mysqld' `[mysqld]', `[server]' and `[mysqld-major-version]' `mysql.server'`[mysql.server]', `[mysqld]', and `[server]' `mysqld_safe'`[mysqld]', `[server]', and `[mysqld_safe]' For backward compatibility, `mysql.server' also reads the `[mysql_server]' group and `mysqld_safe' also reads the `[safe_mysqld]' group. However, you should update your option files to use the `[mysql.server]' and `[mysqld_safe]' groups instead. *Note Option files::. Starting and Troubleshooting the MySQL Server ............................................. If you are going to use storage engines that support transactional tables (`InnoDB', `BDB'), you should first create a `my.cnf' file and set startup options for the engines you plan to use. *Note Table types::. When the `mysqld' server starts, it changes location to the data directory. This is where it expects to write log files and the pid (process ID) file, and where it expects to find databases. The data directory location is hardwired in when the distribution is compiled. However, if `mysqld' expects to find the data directory somewhere other than where it really is on your system, it will not work properly. If you have problems with incorrect paths, you can find out what options `mysqld' allows and what the default path settings are by invoking `mysqld' with the `--help' option. You can override the defaults by specifying the correct pathnames as command-line arguments to `mysqld'. (These options can be used with `mysqld_safe' as well.) Normally you should need to tell `mysqld' only the base directory under which MySQL is installed. You can do this with the `--basedir' option. You can also use `--help' to check the effect of changing path options (note that `--help' *must* be the final option of the `mysqld' command). For example: shell> EXECDIR/mysqld --basedir=/usr/local --help Once you determine the path settings you want, start the server without the `--help' option. Whichever method you use to start the server, if it fails to start up correctly, check the log file to see if you can find out why. Log files are located in the data directory (typically `/usr/local/mysql/data' for a binary distribution, `/usr/local/var' for a source distribution, and `\mysql\data\mysql.err' on Windows). Look in the data directory for files with names of the form `host_name.err' and `host_name.log' where `host_name' is the name of your server host. Then check the last few lines of these files: shell> tail host_name.err shell> tail host_name.log Look for something like the following in the log file: 000729 14:50:10 bdb: Recovery function for LSN 1 27595 failed 000729 14:50:10 bdb: warning: ./test/t1.db: No such file or directory 000729 14:50:10 Can't init databases This means that you didn't start `mysqld' with `--bdb-no-recover' and Berkeley DB found something wrong with its log files when it tried to recover your databases. To be able to continue, you should move away the old Berkeley DB log file from the database directory to some other place, where you can later examine it. The log files are named `log.0000000001', where the number will increase over time. If you are running `mysqld' with `BDB' table support and `mysqld' core dumps at start this could be because of some problems with the `BDB' recovery log. In this case you can try starting `mysqld' with `--bdb-no-recover'. If this helps, then you should remove all `log.*' files from the data directory and try starting `mysqld' again. If you get the following error, it means that some other program (or another `mysqld' server) is already using the TCP/IP port or socket `mysqld' is trying to use: Can't start server: Bind on TCP/IP port: Address already in use or: Can't start server: Bind on unix socket... Use `ps' to make sure that you don't have another `mysqld' server running. If you can't find another server running, you can try to execute the command `telnet your-host-name tcp-ip-port-number' and press Enter a couple of times. If you don't get an error message like `telnet: Unable to connect to remote host: Connection refused', something is using the TCP/IP port `mysqld' is trying to use. See *Note mysql_install_db:: and *Note Multiple servers::. If `mysqld' is currently running, you can find out what path settings it is using by executing this command: shell> mysqladmin variables or: shell> mysqladmin -h 'your-host-name' variables If you get `Errcode 13', which means `Permission denied', when starting `mysqld' this means that you didn't have the right to read/create files in the MySQL database or log directory. In this case you should either start `mysqld' as the `root' user or change the permissions for the involved files and directories so that you have the right to use them. If `mysqld_safe' starts the server but you can't connect to it, you should make sure you have an entry in `/etc/hosts' that looks like this: 127.0.0.1 localhost This problem occurs only on systems that don't have a working thread library and for which MySQL must be configured to use MIT-pthreads. If you can't get `mysqld' to start you can try to make a trace file to find the problem. *Note Making trace files::. If you are using `InnoDB' tables, refer to the `InnoDB'-specific startup options. *Note InnoDB start::. If you are using `BDB' (Berkeley DB) tables, you should familiarise yourself with the different `BDB'-specific startup options. *Note BDB start::. Upgrading/Downgrading MySQL =========================== As a general rule, we recommend that when upgrading from one release series to another, you should go to the next series rather than skipping a series. For example, if you currently are running MySQL 3.23 and wish to upgrade to a newer series, upgrade to MySQL 4.0 rather than to 4.1 or 5.0. Before you do an upgrade, you should back up your old databases. You can always move the MySQL format files and datafiles between different versions on the same architecture as long as you have the same base version of MySQL. The current base version is 4. If you change the character set when running MySQL, you must run `myisamchk -r -q --set-character-set=charset' on all tables. Otherwise, your indexes may not be ordered correctly, because changing the character set may also change the sort order. If you are cautious about using new versions, you can always rename your old `mysqld' to something like `mysqld-old-version-number'. If your new `mysqld' then does something unexpected, you can simply shut it down and restart with your old `mysqld'. If, after an upgrade, you experience problems with recompiled client programs, such as `Commands out of sync' or unexpected core dumps, you probably have used an old header or library file when compiling your programs. In this case you should check the date for your `mysql.h' file and `libmysqlclient.a' library to verify that they are from the new MySQL distribution. If not, please recompile your programs. If problems occur, such as that the new `mysqld' server doesn't want to start or that you can't connect without a password, check that you don't have some old `my.cnf' file from your old installation. You can check this with: `program-name --print-defaults'. If this outputs anything other than the program name, you have an active `my.cnf' file that affects server operation. It is a good idea to rebuild and reinstall the Perl `DBD::mysql' module whenever you install a new release of MySQL. The same applies to other MySQL interfaces as well, such as the Python `MySQLdb' module. Upgrading from Version 4.1 to 5.0 --------------------------------- In general, you should do the following when upgrading to MySQL 5.0 from an earlier version: * Read the 5.0 news items to see what significant new features you can use in 5.0. *Note News-5.0.x::. * If you are running MySQL Server on Windows, please also see *Note Windows upgrading::. * If you are using replication, please also see *Note Replication Upgrade:: for information on upgrading your replication setup. * 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. This is described in *Note Upgrading-grant-tables::. Upgrading from Version 4.0 to 4.1 --------------------------------- Several visible behaviors have changed between MySQL 4.0 and MySQL 4.1 to fix some critical bugs and make MySQL more compatible with the ANSI SQL standard. These changes may affect your applications. Some of the 4.1 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'. This option gives you the 4.1 behavior for the most critical changes. You can also enable these behaviors for a given client connection with the `SET @@new=1' command, or turn them off if they are on with `SET @@new=0'. If you believe that some of the 4.1 changes will affect you, we recommend that before upgrading to 4.1, you download the latest MySQL 4.0 version and run it with the `--new' option by adding the following to your config file: [mysqld-4.0] new That way you can test the new behaviors in 4.0 to make sure that your applications work with them. This will help you have a smooth painless transition when you perform a full upgrade to 4.1 later. Doing it the above way will ensure that you don't accidently later run the 4.1 version with the `--new' option. The following list describes changes that may affect applications and that you should watch out for when upgrading to version 4.1: * `TIMESTAMP' is now returned as a string in `'YYYY-MM-DD HH:MM:SS'' format. (The `--new' option can be used from 4.0.12 on to make a 4.0 server behave as 4.1 in this respect.) If you want to have the value returned as a number (like Version 4.0 does) you should add +0 to `TIMESTAMP' columns when you retrieve them: mysql> SELECT ts_col + 0 FROM tbl_name; Display widths for `TIMESTAMP' columns are no longer supported. For example, if you declare a column as `TIMESTAMP(10)', the `(10)' is ignored. These changes were necessary for SQL standards compliance. In a future version, a further change will be made (backward compatible with this change), allowing the timestamp length to indicate the desired number of digits for fractions of a second. * Binary values such as `0xFFDF' now are assumed to be strings instead of numbers. This fixes some problems with character sets where it's convenient to input a string as a binary value. With this change, you should use `CAST()' if you want to compare binary values numerically as integers: mysql> SELECT CAST(0xFEFF AS UNSIGNED INTEGER) < CAST(0xFF AS UNSIGNED INTEGER); -> 0 If you don't use `CAST()', a lexical string comparison will be done: mysql> SELECT 0xFEFF < 0xFF; -> 1 Using binary items in a numeric context or comparing them using the `=' operator should work as before. (The `--new' option can be used from 4.0.13 on to make a 4.0 server behave as 4.1 in this respect.) * For functions that produce a `DATE', `DATETIME', or `TIME' value, the result returned to the client now is fixed up to have a temporal type. For example, in MySQL 4.1, you get this result: mysql> SELECT CAST("2001-1-1" as DATETIME); -> '2001-01-01 00:00:00' In MySQL 4.0, the result is different: mysql> SELECT CAST("2001-1-1" as DATETIME); -> '2001-01-01' * `DEFAULT' values no longer can be specified for `AUTO_INCREMENT' columns. (In 4.0, a `DEFAULT' value is silently ignored; in 4.1, an error occurs). * `LIMIT' no longer accept negative arguments. Use 18446744073709551615 instead of -1. * `SERIALIZE' is no longer a valid 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. * All tables and string columns now have a character set. *Note Charset::. Character set information is displayed by `SHOW CREATE TABLE' and `mysqldump'. (MySQL versions 4.0.6 and above can read the new dump files; older versions cannot.) * The table definition format used in `.frm' files has changed slightly in 4.1. MySQL 4.0 versions from 4.0.11 on can read the new `.frm' format directly, but older versions cannot. If you need to move tables from 4.1 to a version earlier than 4.0.11, you should use `mysqldump'. *Note `mysqldump': mysqldump. * If you are running multiple servers on the same Windows machine, you should use a different `--shared_memory_base_name' option on all machines. * The interface to aggregated UDF functions has changed a bit. You must now declare a `xxx_clear()' function for each aggregate function `XXX()'. In general, upgrading to 4.1 from an earlier MySQL version involves the following steps: * Check the changes listed earlier in this section to see whether there are any that may affect your applications. * Read the 4.1 news items to see what significant new features you can use in 4.1. *Note News-4.1.x::. * If you are running MySQL Server on Windows, please also see *Note Windows upgrading::. *Important note:* Early alpha Windows distributions for MySQL 4.1 do not contain any installer program. See *Note Windows binary installation:: for instructions on how to install such a distribution. * If you are using replication, please also see *Note Replication Upgrade:: for information on upgrading your replication setup. * After upgrading, update the grant tables to generate the new longer `Password' column that is needed for secure handling of passwords. The procedure uses `mysql_fix_privilege_tables' and is described in *Note Upgrading-grant-tables::. The password hashing mechanism has changed in 4.1 to provide better security, but this may cause compatibility problems if you still have clients that use the client library from 4.0 or earlier. (It is very likely that you will have 4.0 clients in situations where clients connect from remote hosts that have not yet upgraded to 4.1). The following list indicates some possible upgrade strategies. They represent various tradeoffs between the goal of compatibility with old clients and the goal of security. * Don't upgrade to 4.1. No behavior will change, 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.) *Note 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. * Upgrade to 4.1 and run the `mysql_fix_privilege_tables' script to widen the `Password' column in the `user' table. If you know that all clients also have been upgraded to 4.1, don't run the server with the `--old-passwords' option. Instead, change the passwords on all existing accounts so that they have the new format. A pure-4.1 installation is the most secure. Further background on password hashing with respect to client authentication and password-changing operations may be found in *Note Password hashing::. Upgrading from Version 3.23 to 4.0 ---------------------------------- In general, you should do the following when upgrading to MySQL 4.0 from an earlier version: * After upgrading, update the grant tables to add new privileges and features. The procedure uses the `mysql_fix_privilege_tables' script and is described in *Note Upgrading-grant-tables::. * Edit any MySQL startup scripts or configure files to not use any of the deprecated options described later in this section. * Convert your old `ISAM' files to `MyISAM' files with the `mysql_convert_table_format database' script. (This is a Perl script; it requires that DBI be installed.) To convert the tables in a given database, use this command: shell> mysql_convert_table_format database db_name Note that this should only be used if all tables in the given database are `ISAM' or `MyISAM' tables. To avoid converting tables of other types to `MyISAM', you can explicitly list the names of your `ISAM' tables after the database name on the command line. You can also issue a `ALTER TABLE table_name TYPE=MyISAM' statement for each `ISAM' table to convert it to `MyISAM'. To find out the table type for a given table, use this statement: mysql> SHOW TABLE STATUS LIKE 'tbl_name'; * Ensure that you don't have any MySQL clients that use shared libraries (like the Perl `DBD::mysql' 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. * If you are running MySQL Server on Windows, please also see *Note Windows upgrading::. * If you are using replication, please also see *Note Replication Upgrade:: for information on upgrading your replication setup. MySQL 4.0 will work even if you don't do the above, but you will not be able to use the new security privileges that MySQL 4.0 and you may run into problems when upgrading later to MySQL 4.1 or newer. The `ISAM' file format still works in MySQL 4.0 but it's deprecated and will be disabled (not compiled in by default) in MySQL 4.1. `MyISAM' tables should be used instead. Old clients should work with a Version 4.0 server without any problems. Even if you do the above, you can still downgrade to MySQL 3.23.52 or newer if you run into problems with the MySQL 4.0 series. In this case, you must use `mysqldump' to dump any tables that use full-text indexes and reload the dump file into the 3.23 server. This is necessary because 4.0 uses a new format for full-text indexing. The following is a more complete list that tells what you must watch out for when upgrading to version 4.0: * MySQL 4.0 has a lot of new privileges in the `mysql.user' table. *Note `GRANT': GRANT. To get these new privileges to work, you must update the grant tables. The procedure is described in *Note Upgrading-grant-tables::. Until you do this, all users have the `SHOW DATABASES', `CREATE TEMPORARY TABLES', and `LOCK TABLES' privileges. `SUPER' and `EXECUTE' privileges take their value from `PROCESS'. `REPLICATION SLAVE' and `REPLICATION CLIENT' take their values from `FILE'. If you have any scripts that create new users, you may want to change them to use the new privileges. If you are not using `GRANT' commands in the scripts, this is a good time to change your scripts to use `GRANT' instead of modifying the grant tables directly.. From version 4.0.2 on, the option `--safe-show-database' is deprecated (and no longer does anything). *Note Privileges options::. If you get `Access denied' errors for new users in version 4.0.2 and up, you should check if you need some of the new grants that you didn't need before. In particular, you will need `REPLICATION SLAVE' (instead of `FILE') for new slaves. * `safe_mysqld' is renamed to `mysqld_safe'. For backward compatibility, binary distributions will for some time include `safe_mysqld' as a symlink to `mysqld_safe'. * InnoDB support is now included by default in binary distributions. If you build MySQL from source, InnoDB is configured in by default. If you do not use InnoDB and want to save memory when running a server that has InnoDB support enabled, use the `--skip-innodb' server startup option. To compile MySQL without InnoDB support, run `configure' with the `--without-innodb' option. * The startup parameters `myisam_max_extra_sort_file_size' and `myisam_max_extra_sort_file_size' are now given in bytes (they were given in megabytes before 4.0.3). * External system locking of `MyISAM'/`ISAM' files is now turned off by default. Your can turn this on by doing `--external-locking'. (However, this is never needed for most users.) * The following startup variables/options have been renamed: *Old Name* *New Name* `myisam_bulk_insert_tree_size' `bulk_insert_buffer_size' `query_cache_startup_type' `query_cache_type' `record_buffer' `read_buffer_size' `record_rnd_buffer' `read_rnd_buffer_size' `sort_buffer' `sort_buffer_size' `warnings' `log-warnings' `--err-log' `--log-error' (for `mysqld_safe') The startup options `record_buffer', `sort_buffer' and `warnings' will still work in MySQL 4.0 but are deprecated. * The following SQL variables have changed name. *Old Name* *New Name* `SQL_BIG_TABLES' `BIG_TABLES' `SQL_LOW_PRIORITY_UPDATES' `LOW_PRIORITY_UPDATES' `SQL_MAX_JOIN_SIZE' `MAX_JOIN_SIZE' `SQL_QUERY_CACHE_TYPE' `QUERY_CACHE_TYPE' The old names still work in MySQL 4.0 but are deprecated. * You have to use `SET GLOBAL SQL_SLAVE_SKIP_COUNTER=#' instead of `SET SQL_SLAVE_SKIP_COUNTER=#'. * The `mysqld' startup options `--skip-locking' and `--enable-locking' were renamed to `--skip-external-locking' and `--external-locking'. * `SHOW MASTER STATUS' now returns an empty set if binary logging is not enabled. * `SHOW SLAVE STATUS' now returns an empty set if slave is not initialized. * `mysqld' now has the option `--temp-pool' enabled by default as this gives better performance with some operating systems (most notably Linux). * `DOUBLE' and `FLOAT' columns now honor the `UNSIGNED' flag on storage (before, `UNSIGNED' was ignored for these columns). * `ORDER BY col_name DESC' sorts `NULL' values last, as of MySQL 4.0.11. In 3.23 and in earlier 4.0 versions, this was not always consistent. * `SHOW INDEX' has two more columns (`Null' and `Index_type') than it had in 3.23. * `CHECK', `LOCALTIME' and `LOCALTIMESTAMP' are now reserved words. * The result of all bitwise operators (`|', `&', `<<', `>>', and `~')) is now unsigned. This may cause problems if you are using them in a context where you want a signed result. *Note Cast Functions::. * *Note:* when you use subtraction between integer values where one is of type `UNSIGNED', the result will be unsigned. In other words, before upgrading to MySQL 4.0, you should check your application for cases where you are subtracting a value from an unsigned entity and want a negative answer or subtracting an unsigned value from an integer column. You can disable this behavior by using the `--sql-mode=NO_UNSIGNED_SUBTRACTION' option when starting `mysqld'. *Note Cast Functions::. * To use `MATCH ... AGAINST (... IN BOOLEAN MODE)' with your tables, you need to rebuild them with `REPAIR TABLE table_name USE_FRM'. * `LOCATE()' and `INSTR()' are case-sensitive if one of the arguments is a binary string. Otherwise they are case-insensitive. * `STRCMP()' now uses the current character set when performing comparisons. This makes the default comparison behavior case insensitive unless one or both of the operands are binary strings. * `HEX(string)' now returns the characters in `string' converted to hexadecimal. If you want to convert a number to hexadecimal, you should ensure that you call `HEX()' with a numeric argument. * In 3.23, `INSERT INTO ... SELECT' always had `IGNORE' enabled. In 4.0.1, MySQL will stop (and possibly roll back) by default in case of an error unless you specify `IGNORE'. * The old C API functions `mysql_drop_db()', `mysql_create_db()', and `mysql_connect()' are no longer supported unless you compile MySQL with `CFLAGS=-DUSE_OLD_FUNCTIONS'. However, it is preferable to change client programs to use the new 4.0 API instead. * In the `MYSQL_FIELD' structure, `length' and `max_length' have changed from `unsigned int' to `unsigned long'. This should not cause any problems, except that they may generate warning messages when used as arguments in the `printf()' class of functions. * You should use `TRUNCATE TABLE' when you want to delete all rows from a table and you don't need to obtain a count of the number of rows that were deleted. (`DELETE FROM table_name' returns a row count in 4.0, and `TRUNCATE TABLE' is faster.) * You will get an error if you have an active `LOCK TABLES' or transaction when trying to execute `TRUNCATE TABLE' or `DROP DATABASE'. * You should use integers to store values in `BIGINT' columns (instead of using strings, as you did in MySQL 3.23). Using strings will still work, but using integers is more efficient. * The format of `SHOW OPEN TABLES' has changed. * Multi-threaded clients should use `mysql_thread_init()' and `mysql_thread_end()'. *Note Threaded clients::. * 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. * `RAND(seed)' returns a different random number series in 4.0 than in 3.23; this was done to further differentiate `RAND(seed)' and `RAND(seed+1)'. * The default type returned by `IFNULL(A,B)' is now set to be the more 'general' of the types of `A' and `B'. (The general-to-specific order is string, `REAL' or `INTEGER'). Upgrading from Version 3.22 to 3.23 ----------------------------------- MySQL Version 3.23 supports tables of the new `MyISAM' type and the old `ISAM' type. You don't have to convert your old tables to use these with Version 3.23. By default, all new tables will be created with type `MyISAM' (unless you start `mysqld' with the `--default-table-type=isam' option). You can convert an `ISAM' table to `MyISAM' format with `ALTER TABLE table_name TYPE=MyISAM' or the Perl script `mysql_convert_table_format'. Version 3.22 and 3.21 clients will work without any problems with a Version 3.23 server. The following list tells what you have to watch out for when upgrading to Version 3.23: * All tables that use the `tis620' character set must be fixed with `myisamchk -r' or `REPAIR TABLE'. * If you do a `DROP DATABASE' on a symbolically linked database, both the link and the original database are deleted. (This didn't happen in 3.22 because `configure' didn't detect the availability of the `readlink()' system call.) * `OPTIMIZE TABLE' now works only for `MyISAM' tables. For other table types, you can use `ALTER TABLE' to optimize the table. During `OPTIMIZE TABLE', the table is now locked to prevent it from being used by other threads. * The MySQL client `mysql' is now by default started with the option `--no-named-commands (-g)'. This option can be disabled with `--enable-named-commands (-G)'. This may cause incompatibility problems in some cases--for example, in SQL scripts that use named commands without a semicolon. Long format commands still work from the first line. * Date functions that work on parts of dates (like `MONTH()') will now return 0 for `0000-00-00' dates. (In MySQL 3.22, these functions returned `NULL'.) * If you are using the `german' character sort order for `ISAM' tables, you must repair them with `isamchk -r', because we have made some changes in the sort order. * The default return type of `IF()' now depends on both arguments and not only the first argument. * `AUTO_INCREMENT' columns should not be used to store negative numbers. The reason for this is that negative numbers caused problems when wrapping from -1 to 0. You should not store 0 in `AUTO_INCREMENT' columns, either; `CHECK TABLE' will complain about 0 values because they may change if you dump and restore the table. `AUTO_INCREMENT' for `MyISAM' tables is now handled at a lower level and is much faster than before. In addition, for `MyISAM' tables, old numbers are no longer reused, even if you delete rows from the table. * `CASE', `DELAYED', `ELSE', `END', `FULLTEXT', `INNER', `RIGHT', `THEN', and `WHEN' are now reserved words. * `FLOAT(X)' is now a true floating-point type and not a value with a fixed number of decimals. * When declaring columns using a `DECIMAL(length,dec)' type, the `length' argument no longer includes a place for the sign or the decimal point. * A `TIME' string must now be of one of the following formats: `[[[DAYS] [H]H:]MM:]SS[.fraction]' or `[[[[[H]H]H]H]MM]SS[.fraction]'. * `LIKE' now compares strings using the same character comparison rules as for the `=' operator. If you require the old behavior, you can compile MySQL with the `CXXFLAGS=-DLIKE_CMP_TOUPPER' flag. * `REGEXP' is now case-insensitive if neither of the strings are binary strings. * When you check or repair `MyISAM' (`.MYI') tables, you should use the `CHECK TABLE' statement or the `myisamchk' command. For `ISAM' (`.ISM') tables, use the `isamchk' command. * If you want your `mysqldump' files to be compatible between MySQL Version 3.22 and Version 3.23, you should not use the `--opt' or `--all' option to `mysqldump'. * Check all your calls to `DATE_FORMAT()' to make sure there is a `%' before each format character. (MySQL Version 3.22 and later already allowed this syntax.) * `mysql_fetch_fields_direct()' is now a function (it used to be a macro) and it returns a pointer to a `MYSQL_FIELD' instead of a `MYSQL_FIELD'. * `mysql_num_fields()' can no longer be used on a `MYSQL*' object (it's now a function that takes a `MYSQL_RES*' value as an argument). With a `MYSQL*' object, you should now use `mysql_field_count()' instead. * In MySQL Version 3.22, the output of `SELECT DISTINCT ...' was almost always sorted. In Version 3.23, you must use `GROUP BY' or `ORDER BY' to obtain sorted output. * `SUM()' now returns `NULL' instead of 0 if there are no matching rows. This is required by SQL-99. * An `AND' or `OR' with `NULL' values will now return `NULL' instead of 0. This mostly affects queries that use `NOT' on an `AND/OR' expression as `NOT NULL' = `NULL'. * `LPAD()' and `RPAD()' now shorten the result string if it's longer than the length argument. Upgrading from Version 3.21 to 3.22 ----------------------------------- Nothing that affects compatibility has changed between versions 3.21 and 3.22. The only pitfall is that new tables that are created with `DATE' type columns will use the new way to store the date. You can't access these new columns from an old version of `mysqld'. After installing MySQL Version 3.22, you should start the new server and then run the `mysql_fix_privilege_tables' script. This will add the new privileges that you need to use the `GRANT' command. If you forget this, you will get `Access denied' when you try to use `ALTER TABLE', `CREATE INDEX', or `DROP INDEX'. The procedure for updating the grant tables is described in *Note Upgrading-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 place a `0' for the new `db' argument (or recode the client to send the `db' element for faster connections). You must also call `mysql_init()' before calling `mysql_real_connect()'. This change was done to allow the new `mysql_options()' function to save options in the `MYSQL' handler structure. The `mysqld' variable `key_buffer' has been renamed to `key_buffer_size', but you can still use the old name in your startup files. Upgrading from Version 3.20 to 3.21 ----------------------------------- If you are running a version older than Version 3.20.28 and want to switch to Version 3.21, you need to do the following: You can start the `mysqld' Version 3.21 server with the `--old-protocol' option to use it with clients from a Version 3.20 distribution. In this case, the new client function `mysql_errno()' will not return any server error, only `CR_UNKNOWN_ERROR' (but it works for client errors), and the server uses the old pre-3.21 `password()' checking rather than the new method. If you are *not* using the `--old-protocol' option to `mysqld', you will need to make the following changes: * All client code must be recompiled. If you are using ODBC, you must get the new `MyODBC' 2.x driver. * The script `scripts/add_long_password' must be run to convert the `Password' field in the `mysql.user' table to `CHAR(16)'. * All passwords must be reassigned in the `mysql.user' table (to get 62-bit rather than 31-bit passwords). * The table format hasn't changed, so you don't have to convert any tables. MySQL Version 3.20.28 and above can handle the new `user' table format without affecting clients. If you have a MySQL version earlier than Version 3.20.28, passwords will no longer work with it if you convert the `user' table. So to be safe, you should first upgrade to at least Version 3.20.28 and then upgrade to Version 3.21. The new client code works with a 3.20.x `mysqld' server, so if you experience problems with 3.21.x, you can use the old 3.20.x server without having to recompile the clients again. If you are not using the `--old-protocol' option to `mysqld', old clients will be unable to connect and will issue the following error message: ERROR: Protocol mismatch. Server Version = 10 Client Version = 9 The Perl DBI interface also supports the old `mysqlperl' interface. The only change you have to make if you use `mysqlperl' is to change the arguments to the `connect()' function. The new arguments are: `host', `database', `user', and `password' (note that the `user' and `password' arguments have changed places). The following changes may affect queries in old applications: * `HAVING' must now be specified before any `ORDER BY' clause. * The parameters to `LOCATE()' have been swapped. * There are some new reserved words. The most notable are `DATE', `TIME', and `TIMESTAMP'. Upgrading MySQL under Windows ----------------------------- When upgrading MySQL under Windows, please follow these steps: 1. Download the latest Windows distribution of MySQL. 2. Choose a time of day with low usage, where a maintenance break is acceptable. 3. Alert the users that still are active about the maintenance break. 4. Stop the running MySQL Server (for example, with `NET STOP MySQL' or with the `Services' utility if you are running MySQL as a service, or with `mysqladmin shutdown' otherwise). 5. Exit the `WinMySQLAdmin' program if it is running. 6. Run the installation script of the Windows distribution, by clicking the "Install" button in WinZip and following the installation steps of the script. *Important note:* Early alpha Windows distributions for MySQL 4.1 do not contain any installer program. See *Note Windows binary installation:: for instructions on how to install such a distribution. 7. You may either overwrite your old MySQL installation (usually located at `C:\mysql'), or install it into a different directory, such as `C:\mysql4'. Overwriting the old installation is recommended. 8. Restart the server (for example, with `NET START MySQL' if you run MySQL as a service, or by invoking `mysqld' directly otherwise). 9. Update the grant tables. The procedure is described in *Note Upgrading-grant-tables::. Possible error situations: A system error has occurred. System error 1067 has occurred. The process terminated unexpectedly. This error means that your `my.cnf' file (by default `C:\my.cnf') contains an option that cannot be recognized by MySQL. You can verify that this is the case by trying to restart MySQL with the `my.cnf' file renamed, for example, to `my_cnf.old' to prevent the server from using it. Once you have verified it, you need to identify which option is the culprit. Create a new `my.cnf' file and move parts of the old file to it (restarting the server after you move each part) until you determine which option causes server startup to fail. Upgrading the Grant Tables -------------------------- Some releases introduce changes to the structure of the grant tables (the tables in the `mysql' database) to add new privileges or features. To make sure that your grant tables are current when you update to a new version of MySQL, you should update your grant tables as well. On Unix or Unix-like systems, update the grant tables by running the `mysql_fix_privilege_tables' script: shell> mysql_fix_privilege_tables You must run this script while the server is running. It attempts to connect to the server running on the local host as `root'. If your `root' account requires a password, indicate the password on the command line. For MySQL 4.1 and up, specify the password like this: shell> mysql_fix_privilege_tables --password=root_password Prior to MySQL 4.1, specify the password like this: shell> mysql_fix_privilege_tables root_password The `mysql_fix_privilege_tables' script performs any actions necessary to convert your grant tables to the current format. You may see some `Duplicate column name' warnings as it runs; they can be ignored. After running the script, stop the server and restart it. On Windows systems, there isn't an easy way to update the grant tables until MySQL 4.0.15. From version 4.0.15 on, MySQL distributions include a `mysql_fix_privilege_tables.sql' SQL script that you can run using the `mysql' client. If your MySQL installation is located at `C:\mysql', the commands look like this: C:\mysql\bin> mysql -u root -p mysql mysql> SOURCE C:\mysql\scripts\mysql_fix_privilege_tables.sql If your installation is located in some other directory, adjust the pathnames appropriately. The `mysql' command will prompt you for the `root' password; enter it when prompted. As with the Unix procedure, you may see some `Duplicate column name' warnings as `mysql' processes the statements in the `mysql_fix_privilege_tables.sql' script; they can be ignored. After running the script, stop the server and restart it. Copying MySQL Databases to Another Machine ------------------------------------------ If you are using MySQL Version 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.) *Note `MyISAM' Tables: MyISAM. 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' will create a file containing SQL statements. You can then transfer the file to the other machine and feed it as input to the `mysql' client. Try `mysqldump --help' to see what options are available. If you are moving the data to a newer version of MySQL, you should use `mysqldump --opt' to take advantage of any optimizations that result in a dump file that is smaller and can be processed faster. The easiest (although not the fastest) way to move a database between two machines is to run the following commands on the machine on which the database is located: shell> mysqladmin -h 'other hostname' create db_name shell> mysqldump --opt db_name \ | mysql -h 'other hostname' db_name If you want to copy a database from a remote machine over a slow network, you can use: shell> mysqladmin create db_name shell> mysqldump -h 'other hostname' --opt --compress db_name \ | mysql db_name You can also store the result in a file, then transfer the file to the target machine and load the file into the database there. For example, you can dump a database to a file on the source machine like this: shell> mysqldump --quick db_name | gzip > db_name.contents.gz (The file created in this example is compressed.) Transfer the file containing the database contents to the target machine and run these commands there: shell> mysqladmin create db_name shell> gunzip < db_name.contents.gz | mysql db_name You can also use `mysqldump' and `mysqlimport' to transfer the database. For big tables, this is much faster than simply using `mysqldump'. In the following commands, `DUMPDIR' represents the full pathname of the directory you use to store the output from `mysqldump'. First, create the directory for the output files and dump the database: shell> mkdir DUMPDIR shell> mysqldump --tab=DUMPDIR db_name Then transfer the files in the `DUMPDIR' directory to some corresponding directory on the target machine and load the files into MySQL there: shell> mysqladmin create db_name # create database shell> cat DUMPDIR/*.sql | mysql db_name # create tables in database shell> mysqlimport db_name DUMPDIR/*.txt # load data into tables Also, don't forget to copy the `mysql' database because that's where the grant tables (`user', `db', `host') are stored. You may have to run commands as the MySQL `root' user on the new machine until you have the `mysql' database in place. After you import the `mysql' database on the new machine, execute `mysqladmin flush-privileges' so that the server reloads the grant table information. Operating System Specific Notes =============================== Linux Notes ----------- This section discusses issues that have been found to occur on Linux. The first few subsections describe general operating sytem-related issues, problems that can occur when using binary or source distributions, and post-installation issues. The remaining subsections discuss problems that occur with Linux on specific platforms. Note that most of these problems occur on older versions of Linux. If you are running a recent version, you likely will see none of them. 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 as this will give you a significant speed boost. Your system also will be more stable. When using LinuxThreads you will see a minimum of three `mysqld' processes running. These are in fact threads. There will be one thread for the LinuxThreads manager, one thread to handle connections, and one thread to handle alarms and signals. Linux Binary Distribution Notes ............................... The Linux-Intel binary and RPM releases of MySQL are configured for the highest possible speed. We are always trying to use the fastest stable compiler available. The binary release is linked with `-static', which means you do not normally need to worry about which version of the system libraries you have. You need not install LinuxThreads, either. A program linked with `-static' is slightly larger than a dynamically linked program, but also slightly faster (3-5%). However, one problem with a statically linked program is that you can't use user-defined functions (UDFs). If you are going to write or use UDFs (this is something for C or C++ programmers only), you must compile MySQL yourself using dynamic linking. A known issue with binary distributions is that on older Linux systems that use `libc' (such as Red Hat 4.x or Slackware), you will get some non-fatal problems with hostname resolution. If your system uses `libc' rather than `glibc2', you probably will encounter some difficulties with hostname resolution and `getpwnam()'. This happens because `glibc' unfortunately depends on some external libraries to implement hostname resolution and `getpwent()', even when compiled with `-static'). These problems manifest themselves in two ways: * You probably will see the following error message when you run `mysql_install_db': Sorry, the host 'xxxx' could not be looked up You can deal with this by executing `mysql_install_db --force', which will 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' with `su' 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 (an RPM or the `tar.gz' distribution) 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 only room for a finite number of TCP/IP slots, so you will encounter the resource-unavailable error if clients attempt too many new TCP/IP connections during a short time. For example, you may see the error when you run the MySQL `test-connect' benchmark over TCP/IP. We have inquired about this problem a few times on different Linux mailing lists but have never been able to find a suitable resolution. The only known "fix" is for the clients to use persistent connections, or, if you are running the database server and clients on the same machine, to use Unix socket file connections rather than TCP/IP connections. 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 2G 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 our binary is not good enough, then you may want to try your own build. In that case, we would appreciate a note about it, so 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://www.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 1024 threads. If you plan to have more than 1000 concurrent connections, you will need to make some changes to LinuxThreads: * Increase `PTHREAD_THREADS_MAX' in `sysdeps/unix/sysv/linux/bits/local_lim.h' to 4096 and decrease `STACK_SIZE' in `linuxthreads/internals.h' to 256 KB. The paths are relative to the root of `glibc'. (Note that MySQL will not be stable with around 600-1000 connections if `STACK_SIZE' is the default of 2 MB.) * 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 version 3.23.36 will use the adaptive mutex, which is much better than even the patched one in `glibc' 2.1.3. Be warned, however, that under some conditions, the current mutex code in `glibc' 2.2.2 overspins, which hurts MySQL performance. The likelihood that this condition will occur 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 will need to apply it in the `linuxthreads' directory with `patch -p0 cat /proc/sys/fs/file-max shell> cat /proc/sys/fs/dquot-max shell> cat /proc/sys/fs/super-max If you have more than 16 MB of memory, you should add something like the following to your init scripts (for example, `/etc/init.d/boot.local' on SuSE Linux): echo 65536 > /proc/sys/fs/file-max echo 8192 > /proc/sys/fs/dquot-max echo 1024 > /proc/sys/fs/super-max You can also run the `echo' commands from the command line as `root', but these settings will be lost the next time your computer reboots. Alternatively, you can set these parameters on bootup by using the `sysctl' tool, which is used by many Linux distributions (SuSE has added it as well, beginning with SuSE Linux 8.0). Just put the following values into a file named `/etc/sysctl.conf': # Increase some values for MySQL fs.file-max = 65536 fs.dquot-max = 8192 fs.super-max = 1024 You should also add the following to `/etc/my.cnf': [mysqld_safe] open-files-limit=8192 This should allow the server a limit of 8192 for the combined number of connections and open files. The `STACK_SIZE' constant in LinuxThreads controls the spacing of thread stacks in the address space. It needs to be large enough so that there will be plenty of room for the stack of each individual thread, 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()' will successfully unmap an already mapped region if you ask it to map out an address already in use, zeroing out the data on the entire page, instead of returning an error. So, the safety of `mysqld' or any other threaded application depends on "gentlemanly" behavior of the code that creates threads. The user must take measures to make sure the number of running threads at any time is sufficiently low for thread stacks to stay away from the global heap. With `mysqld', you should enforce this behavior by setting a reasonable value for the `max_connections' variable. If you build MySQL yourself, you can patch LinuxThreads for better stack use. *Note Source notes-Linux::. 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 2G patch. If you are using our binary or RPM version 3.23.25 or later, you can safely set `max_connections' at 1500, assuming no large key buffer or heap tables with lots of data. The more you reduce `STACK_SIZE' in LinuxThreads the more threads you can safely create. We recommend values between 128K and 256K. If you use a lot of concurrent connections, you may suffer from a "feature" in the 2.2 kernel that 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 1 minute), and it may take just as long to shut it down. On multiple-CPU systems, we have observed a gradual drop in query speed as the number of clients increases. In the process of trying to find a solution, we have received a kernel patch from one of our users who claimed it made a lot of difference for his site. The patch is available at `http://www.mysql.com/Downloads/Patches/linux-fork.patch'. We have now done rather extensive testing of this patch on both development and production systems. It has significantly improved MySQL performance without causing any problems and we now recommend it to our users who still run high-load servers on 2.2 kernels. This issue has been fixed in the 2.4 kernel, so if you are not satisfied with the current performance of your system, rather than patching your 2.2 kernel, it might be easier to upgrade to 2.4. On SMP systems, upgrading also will give you a nice SMP boost in addition to fixing the fairness bug. We have tested MySQL on the 2.4 kernel on a 2-CPU machine and found MySQL scales *much* better. There was virtually no slowdown on query throughput all the way up to 1000 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 4-CPU system: Virtually no slowdown as the number of clients was increased up to 1000, 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 `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 4-CPU machine, increasing the priority gave 60% throughput increase with 400 clients. We are currently also trying to collect more information on how well MySQL performs on 2.4 kernel on 4-way and 8-way systems. If you have access such a system and have done some benchmarks, please send an email message to 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. *Note 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'. *Note `mysqld_safe': mysqld_safe. Linux x86 Notes ............... MySQL requires `libc' Version 5.4.12 or newer. It's known to work with `libc' 5.4.46. `glibc' Version 2.0.6 and later should also work. There have been some problems with the `glibc' RPMs from Red Hat, so if you have problems, check whether there are any updates. The `glibc' 2.0.7-19 and 2.0.7-29 RPMs are known to work. If you are using Red Hat 8.0 or a new `glibc' 2.2.x library, you may see `mysqld' die in `gethostbyaddr()'. This happens because the new `glibc' library requires a stack size greater than 128K 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 now 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 will get an error about a missing `__cxa_pure_virtual' symbol during linking. On some older Linux distributions, `configure' may produce an error like this: Syntax error in sched.h. Change _P to __P in the /usr/include/sched.h file. See the Installation chapter in the Reference Manual. 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 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. Linux Alpha Notes ................. MySQL Version 3.23.12 is the first MySQL version that is tested on Linux-Alpha. If you plan to use MySQL on Linux-Alpha, you should ensure that you have this version or newer. We have tested MySQL on Alpha with our benchmarks and test suite, and it appears to work nicely. We currently build the MySQL binary packages on SuSE Linux 7.0 for AXP, kernel 2.4.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 above 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 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 will 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 will dump core at startup time. In other words, *don't* use `--with-mysqld-ldflags=-all-static' with `gcc'. Linux PowerPC Notes ................... MySQL should work on MkLinux with the newest `glibc' package (tested with `glibc' 2.0.7). Linux MIPS Notes ................ To get MySQL to work on Qube2 (Linux Mips), you need the newest `glibc' libraries. `glibc-2.0.7-29C2' is known to work. You must also use the `egcs' C++ compiler (`egcs-1.0.2-9', `gcc 2.95.2' or newer). Linux IA-64 Notes ................. To get MySQL to compile on Linux IA-64, we use the following `configure' command for building with `gcc' 2.96: CC=gcc \ CFLAGS="-O3 -fno-omit-frame-pointer" \ CXX=gcc \ CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \ -fno-exceptions -fno-rtti" \ ./configure --prefix=/usr/local/mysql \ "--with-comment=Official MySQL binary" \ --with-extra-charsets=complex On IA-64, the MySQL client binaries use shared libraries. This means that if you install our binary distribution at a location other than `/usr/local/mysql', you need to add the path of the directory where you have `libmysqlclient.so' installed either to the `/etc/ld.so.conf' file or to the value of your `LD_LIBRARY_PATH' environment variable. *Note Link errors::. 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. Mac OS X 10.x (Darwin) ...................... MySQL should work without any problems on Mac OS X 10.x (Darwin). Our binary for Mac OS X is compiled on Darwin 6.3 with the following `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 *Note Mac OS X installation::. 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. *Note Mac OS X installation::. Solaris Notes ------------- On Solaris, you may run into trouble even before you get the MySQL distribution unpacked! Solaris `tar' can't handle long file names, so you may see an error like this when you unpack MySQL: x mysql-3.22.12-beta/bench/Results/ATIS-mysql_odbc-NT_4.0-cmp-db2,\ informix,ms-sql,mysql,oracle,solid,sybase, 0 bytes, 0 tape blocks tar: directory checksum error In this case, you must use GNU `tar' (`gtar') to unpack the distribution. You can find a precompiled copy for Solaris at `http://www.mysql.com/downloads/os-solaris.html'. Sun native threads only work on Solaris 2.5 and higher. For Version 2.4 and earlier, MySQL will automatically use MIT-pthreads. *Note MIT-pthreads::. 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 64bit Solaris binary using `gcc', add `-m64' to `CFLAGS' and `CXXFLAGS'. Note that 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 `-mcpu' flags. If you create a 64-bit `mysqld' binary, it is 4% slower than the 32-bit binary, but can handle more threads and memory. If you get a problem with `fdatasync' or `sched_yield', you can fix this by adding `LIBS=-lrt' to the configure line For older compilers than WorkShop 5.3, you may have to edit the `configure' script to change this line: #if !defined(__STDC__) || __STDC__ != 1 To this: #if !defined(__STDC__) If you turn on `__STDC__' with the `-Xc' option, the Sun compiler can't compile with the Solaris `pthread.h' header file. This is a Sun bug (broken compiler or broken include file). If `mysqld' issues the following error message when you run it, you have tried to compile MySQL with the Sun compiler without enabling the multi-thread option (`-mt'): libc internal error: _rmutex_unlock: rmutex not held Add `-mt' to `CFLAGS' and `CXXFLAGS' and 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 will be 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 will break all programs that use threads, and possibly other programs! Solaris doesn't provide static versions of all system libraries (`libpthreads' and `libdl'), so you can't compile MySQL with `--static'. If you try to do so, you will get one of the following errors: ld: fatal: library -ldl: not found undefined reference to `dlopen' cannot find -lrt If you link your own MySQL client programs, you may see the following error at runtime: ld.so.1: fatal: libmysqlclient.so.#: open failed: No such file or directory This problem can be avoided by one of the following methods: * Link clients with the `-Wl,r/full-path-to-libmysqlclient.so' flag rather than with `-Lpath'). * Copy `libmysqclient.so' to `/usr/lib'. * Add the pathname of the directory where `libmysqlclient.so' is located to the `LD_RUN_PATH' environment variable before running your client. If you have problems with `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 `support-files/mysql.server' to `/etc/init.d' and create a symbolic link to it named `/etc/rc3.d/S99mysql.server'. If too many processes try to connect very rapidly to `mysqld', you will see this error in the MySQL log: Error in accept: Protocol error You might try starting the server with the `--back_log=50' option as a workaround for this. (Use `-O back_log=50' before MySQL 4.) Solaris doesn't support core files for `setuid()' applications, so you can't get a core file from `mysqld' if you are using the `--user' option. Solaris 2.7/2.8 Notes ..................... You can normally use a Solaris 2.6 binary on Solaris 2.7 and 2.8. Most of the Solaris 2.6 issues also apply for Solaris 2.7 and 2.8. MySQL Version 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 `;' The solution to this is to do one of the following: * Configure with `CFLAGS=-DHAVE_CURSES_H CXXFLAGS=-DHAVE_CURSES_H ./configure'. * Edit `/usr/include/widec.h' as indicated above and re-run `configure'. * Remove the `#define HAVE_TERM' line from the `config.h' file and run `make' again. If your linker can't find `-lz' when linking client programs, the problem is probably that your `libz.so' file is installed in `/usr/local/lib'. You can fix this 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. Solaris x86 Notes ................. On Solaris 8 on x86, `mysqld' will dump core if you remove the debug symbols using `strip'. If you are using `gcc' or `egcs' on Solaris x86 and you experience problems with core dumps under load, you should use the following `configure' command: CC=gcc CFLAGS="-O3 -fomit-frame-pointer -DHAVE_CURSES_H" \ CXX=gcc \ CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \ -fno-exceptions -fno-rtti -DHAVE_CURSES_H" \ ./configure --prefix=/usr/local/mysql This will avoid problems with the `libstdc++' library and with C++ exceptions. If this doesn't help, you should compile a debug version and run it with a trace file or under `gdb'. *Note Using `gdb' on `mysqld': Using gdb on mysqld. BSD Notes --------- This section provides information about using MySQL on BSD variants. FreeBSD Notes ............. FreeBSD 4.x or newer is recommended for running MySQL, because the thread package is much more integrated. To get a secure and stable system, you should use only FreeBSD kernels that are marked `-RELEASE'. The easiest (and preferred) way to install MySQL is to use the `mysql-server' and `mysql-client' ports available at `http://www.freebsd.org/'. Using these ports gives you the following benefits: * A working MySQL with all optimizations enabled that are known to work on your version of FreeBSD. * Automatic configuration and build. * Startup scripts installed in `/usr/local/etc/rc.d'. * The ability to use `pkg_info -L' to see which files are installed. * The ability to use `pkg_delete' to remove MySQL if you no longer want it on your machine. It is recommended you use MIT-pthreads on FreeBSD 2.x, and native threads on 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 will suddenly cause 100% CPU load and will be unresponsive. If you encounter this problem, try to start up MySQL using the `--skip-name-resolve' option. Alternatively, you can link MySQL on FreeBSD 4.x against the LinuxThreads library, which avoids a few of the problems that the native FreeBSD thread implementation has. For a very good comparison of LinuxThreads vs. native threads, see Jeremy Zawodny's article `FreeBSD or Linux for your MySQL Server?' at `http://jeremy.zawodny.com/blog/archives/000697.html'. A known problem when using LinuxThreads on FreeBSD is that `wait_timeout' is not working (probably a signal handling problem in FreeBSD/LinuxThreads). This is supposed to be fixed in FreeBSD 5.0. The symptom is that persistent connections can hang for a very long time without getting closed down. The MySQL build process require 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: shell> 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 shell> gmake shell> gmake install shell> cd /usr/local/mysql shell> bin/mysql_install_db shell> bin/mysqld_safe & If you notice that `configure' will use MIT-pthreads, you should read the MIT-pthreads notes. *Note MIT-pthreads::. 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 your name resolver setup is correct. Otherwise, you may experience resolver delays or failures when connecting to `mysqld'. Also make sure that the `localhost' entry in the `/etc/hosts' file is correct. The file should start with a line similar to this: 127.0.0.1 localhost localhost.your.domain FreeBSD is known to have a very low default file handle limit. *Note Not enough file handles::. 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 you set the appropriate class for this user in the password file if you are not using the default (use `chpass mysqld-user-name'). *Note `mysqld_safe': mysqld_safe. If you have a lot of memory, you should consider rebuilding the kernel to allow MySQL to use more than 512M of RAM. Take a look at `option MAXDSIZ' in the LINT config file for more information. If you get problems with the current date in MySQL, setting the `TZ' variable will probably help. *Note Environment variables::. NetBSD Notes ............ To compile on NetBSD you need GNU `make'. Otherwise, the build process will fail when `make' tries to run `lint' on C++ files. 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 OpenBSD 2.8 Notes ................. Our users have reported that OpenBSD 2.8 has a threading bug which causes problems with MySQL. The OpenBSD Developers have fixed the problem, but as of January 25th, 2001, it's only available in the "-current" branch. The symptoms of this threading bug are: slow response, high load, high CPU usage, and crashes. If you get an error like `Error in accept:: Bad file descriptor' or error 9 when trying to open tables or directories, the problem is probably that you haven't allocated enough file descriptors for MySQL. In this case, try starting `mysqld_safe' as `root' with the following options: shell> mysqld_safe --user=mysql --open-files-limit=2048 & BSD/OS Version 2.x Notes ........................ If you get the following error when compiling MySQL, your `ulimit' value for virtual memory is too low: item_func.h: In method `Item_func_ge::Item_func_ge(const Item_func_ge &)': item_func.h:28: virtual memory exhausted make[2]: *** [item_func.o] Error 1 Try using `ulimit -v 80000' and run `make' again. If this doesn't work and you are using `bash', try switching to `csh' or `sh'; some BSDI users have reported problems with `bash' and `ulimit'. If you are using `gcc', you may also use have to use the `--with-low-memory' flag for `configure' to be able to compile `sql_yacc.cc'. If you get problems with the current date in MySQL, setting the `TZ' variable will probably help. *Note Environment variables::. BSD/OS Version 3.x Notes ........................ Upgrade to BSD/OS Version 3.1. If that is not possible, install BSDIpatch M300-038. Use the following command when configuring MySQL: shell> env CXX=shlicc++ CC=shlicc2 \ ./configure \ --prefix=/usr/local/mysql \ --localstatedir=/var/mysql \ --without-perl \ --with-unix-socket-path=/var/mysql/mysql.sock The following is also known to work: shell> env CC=gcc CXX=gcc CXXFLAGS=-O3 \ ./configure \ --prefix=/usr/local/mysql \ --with-unix-socket-path=/var/mysql/mysql.sock You can change the directory locations if you wish, or just use the defaults by not specifying any locations. If you have problems with performance under heavy load, try using the `--skip-thread-priority' option to `mysqld'! This will run all threads with the same priority; on BSDI Version 3.1, this gives better performance (at least until BSDI fixes their thread scheduler). If you get the error `virtual memory exhausted' while compiling, you should try using `ulimit -v 80000' and run `make' again. If this doesn't work and you are using `bash', try switching to `csh' or `sh'; some BSDI users have reported problems with `bash' and `ulimit'. BSD/OS Version 4.x Notes ........................ BSDI Version 4.x has some thread-related bugs. If you want to use MySQL on this, you should install all thread-related patches. At least M400-023 should be installed. On some BSDI Version 4.x systems, you may get problems with shared libraries. The symptom is that you can't execute any client programs, for example, `mysqladmin'. In this case you need to reconfigure not to use shared libraries with the `--disable-shared' option to configure. Some customers have had problems on BSDI 4.0.1 that the `mysqld' binary after a while can't open tables. This is because some library/system related bug causes `mysqld' to change current directory without asking for this! The fix is to either upgrade 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 the above means that you can't symbolic link a database directories to another database directory or symbolic link a table to another database on BSDI! (Making a symbolic link to another disk is okay). Other Unix Notes ---------------- 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 (like `-O6') as they may not be safe on HP-UX. The following `configure' line should work with `gcc' 2.95: CFLAGS="-I/opt/dce/include -fpic" \ CXXFLAGS="-I/opt/dce/include -felide-constructors -fno-exceptions \ -fno-rtti" \ CXX=gcc \ ./configure --with-pthread \ --with-named-thread-libs='-ldce' \ --prefix=/usr/local/mysql --disable-shared The following `configure' line should work with `gcc' 3.1: CFLAGS="-DHPUX -I/opt/dce/include -O3 -fPIC" CXX=gcc \ CXXFLAGS="-DHPUX -I/opt/dce/include -felide-constructors \ -fno-exceptions -fno-rtti -O3 -fPIC" \ ./configure --prefix=/usr/local/mysql \ --with-extra-charsets=complex --enable-thread-safe-client \ --enable-local-infile --with-pthread \ --with-named-thread-libs=-ldce --with-lib-ccflags=-fPIC --disable-shared HP-UX Version 11.x Notes ........................ For HP-UX Version 11.x, we recommend MySQL Version 3.23.15 or later. Because of some critical bugs in the standard HP-UX libraries, you should install the following patches before trying to run MySQL on HP-UX 11.0: PHKL_22840 Streams cumulative PHNE_22397 ARPA cumulative This will solve the problem of getting `EWOULDBLOCK' from `recv()' and `EBADF' from `accept()' in threaded applications. If you are using `gcc' 2.95.1 on an unpatched HP-UX 11.x system, you will get the error: In file included from /usr/include/unistd.h:11, from ../include/global.h:125, from mysql_priv.h:15, from item.cc:19: /usr/include/sys/unistd.h:184: declaration of C function ... /usr/include/sys/pthread.h:440: previous declaration ... In file included from item.h:306, from mysql_priv.h:158, from item.cc:19: The problem is that HP-UX doesn't define `pthreads_atfork()' consistently. It has conflicting prototypes in `/usr/include/sys/unistd.h':184 and `/usr/include/sys/pthread.h':440 (details below). One solution is to copy `/usr/include/sys/unistd.h' into `mysql/include' and edit `unistd.h' and change it to match the definition in `pthread.h'. Here's the diff: 183,184c183,184 < extern int pthread_atfork(void (*prepare)(), void (*parent)(), < void (*child)()); --- > extern int pthread_atfork(void (*prepare)(void), void (*parent)(void), > void (*child)(void)); After this, the following `configure' line should work: CFLAGS="-fomit-frame-pointer -O3 -fpic" CXX=gcc \ CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti -O3" \ ./configure --prefix=/usr/local/mysql --disable-shared If you are using MySQL 4.0.5 with the HP-UX compiler, you can use 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', check 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 a 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 above. Another possibility for HP-UX 11 is to use MySQL binaries for HP-UX 10.20. We have received reports from some users that these binaries work fine on HP-UX 11.00. If you encounter problems, be sure to check your HP-UX patch level. 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 CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 " export CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192" export CFLAGS="-I /usr/local/include" export LDFLAGS="-L /usr/local/lib" export CPPFLAGS=$CFLAGS export CXXFLAGS=$CFLAGS ./configure --prefix=/usr/local \ --localstatedir=/var/mysql \ --sysconfdir=/etc/mysql \ --sbindir='/usr/local/bin' \ --libexecdir='/usr/local/bin' \ --enable-thread-safe-client \ --enable-large-files Above are the options used to compile the MySQL distribution that can be found at `http://www-frec.bull.com/'. If you change the `-O3' to `-O2' in the 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'. 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' is necessary for the compile to be successful. IBM is aware of this problem but is in to hurry to fix it because of the workaround available. We don't know if the `-fno-exceptions' is required with `gcc 2.95', but as MySQL doesn't use exceptions and the above option generates faster code, we recommend that you should always use this option with `egcs / gcc'. If you get a problem with assembler code, try changing the `-mcpu=xxx' option to match your CPU. Typically `power2', `power', or `powerpc' may need to be used. Alternatively, you might need to use `604' or `604e'. We are not positive but suspect that `power' would likely be safe most of the time, even on a power2 machine. If you don't know what your CPU is, execute a `uname -m' command. It will produce a string that looks like `000514676700', with a format of `xxyyyyyymmss' where `xx' and `ss' are always `00', `yyyyyy' is a unique system ID and `mm' is the ID of the CPU Planar. A chart of these values can be found at `http://publib.boulder.ibm.com/doc_link/en_US/a_doc_lib/cmds/aixcmds5/uname.htm'. This will give you a machine type and a machine model you can use to determine what type of CPU you have. If you have problems with signals (MySQL dies unexpectedly under high load) you may have found an OS bug with threads and signals. In this case you can tell MySQL not to use signals by configuring with: shell> CFLAGS=-DDONT_USE_THR_ALARM CXX=gcc \ CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti \ -DDONT_USE_THR_ALARM" \ ./configure --prefix=/usr/local/mysql --with-debug \ --with-low-memory This doesn't affect the performance of MySQL, but has the side effect that you can't kill clients that are "sleeping" on a connection with `mysqladmin kill' or `mysqladmin shutdown'. Instead, the client will die when it issues its next command. On some versions of AIX, linking with `libbind.a' makes `getservbyname' core dump. This is an AIX bug and should be reported to IBM. For AIX 4.2.1 and `gcc', you have to 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 initgoups. #ifdef _AIX41 extern "C" int initgroups(const char *,int); #endif If you need to allocate a lot of memory to the `mysqld' process, it's not enough to just use `ulimit -d unlimited'. You may also have to modify `mysqld_safe' to add a line something like this: export LDR_CNTRL='MAXDATA=0x80000000' You can find more about using a lot of memory at: `http://publib16.boulder.ibm.com/pseries/en_US/aixprggd/genprogc/lrg_prg_support.htm'. SunOS 4 Notes ............. On SunOS 4, MIT-pthreads is needed to compile MySQL. This in turn means you will need GNU `make'. Some SunOS 4 systems have problems with dynamic libraries and `libtool'. You can use the following `configure' line to avoid this problem: shell> ./configure --disable-shared --with-mysqld-ldflags=-all-static When compiling `readline', you may get warnings about duplicate defines. These may be ignored. When compiling `mysqld', there will be some `implicit declaration of function' warnings. These may be ignored. 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: shell> nohup mysqld [options] & `nohup' causes the command following it to ignore any `SIGHUP' signal sent from the terminal. Alternatively, start the server by running `mysqld_safe', which invokes `mysqld' using `nohup' for you. *Note `mysqld_safe': mysqld_safe. If you get a problem when compiling `mysys/get_opt.c', just remove the `#define _NO_PROTO' line from the start of that file! If you are using Compaq's CC compiler, the following `configure' line should work: CC="cc -pthread" CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all -arch host" CXX="cxx -pthread" CXXFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all \ -arch host -noexceptions -nortti" export CC CFLAGS CXX CXXFLAGS ./configure \ --prefix=/usr/local/mysql \ --with-low-memory \ --enable-large-files \ --enable-shared=yes \ --with-named-thread-libs="-lpthread -lmach -lexc -lc" gnumake If you get a problem with `libtool', when compiling with shared libraries as above, when linking `mysql', you should be able to get around this by issuing: cd mysql /bin/sh ../libtool --mode=link cxx -pthread -O3 -DDBUG_OFF \ -O4 -ansi_alias -ansi_args -fast -inline speed \ -speculate all \ -arch host -DUNDEF_HAVE_GETHOSTBYNAME_R \ -o mysql mysql.o readline.o sql_string.o completion_hash.o \ ../readline/libreadline.a -lcurses \ ../libmysql/.libs/libmysqlclient.so -lm cd .. gnumake gnumake install scripts/mysql_install_db Alpha-DEC-OSF/1 Notes ..................... If you have problems compiling and have DEC `CC' and `gcc' installed, try running `configure' like this: CC=cc CFLAGS=-O CXX=gcc CXXFLAGS=-O3 \ ./configure --prefix=/usr/local/mysql If you get problems with the `c_asm.h' file, you can create and use a 'dummy' `c_asm.h' file with: touch include/c_asm.h CC=gcc CFLAGS=-I./include \ CXX=gcc CXXFLAGS=-O3 \ ./configure --prefix=/usr/local/mysql Note that the following problems with the `ld' program can be fixed by downloading the latest DEC (Compaq) patch kit from: `http://ftp.support.compaq.com/public/unix/'. On OSF/1 V4.0D and compiler "DEC C V5.6-071 on Digital Unix V4.0 (Rev. 878)" the compiler had some strange behavior (undefined `asm' symbols). `/bin/ld' also appears to be broken (problems with `_exit undefined' errors occurring while linking `mysqld'). On this system, we have managed to compile MySQL with the following `configure' line, after replacing `/bin/ld' with the version from OSF 4.0C: CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql With the Digital compiler "C++ V6.1-029", the following should work: CC=cc -pthread CFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed -speculate all \ -arch host CXX=cxx -pthread CXXFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed -speculate all \ -arch host -noexceptions -nortti export CC CFLAGS CXX CXXFLAGS ./configure --prefix=/usr/mysql/mysql --with-mysqld-ldflags=-all-static \ --disable-shared --with-named-thread-libs="-lmach -lexc -lc" In some versions of OSF/1, the `alloca()' function is broken. Fix this by removing the line in `config.h' that defines `'HAVE_ALLOCA''. The `alloca()' function also may have an incorrect prototype in `/usr/include/alloca.h'. This warning resulting from this can be ignored. `configure' will use the following thread libraries automatically: `--with-named-thread-libs="-lpthread -lmach -lexc -lc"'. When using `gcc', you can also try running `configure' like this: shell> CFLAGS=-D_PTHREAD_USE_D4 CXX=gcc CXXFLAGS=-O3 ./configure ... If you have problems with signals (MySQL dies unexpectedly under high load), you may have found an OS bug with threads and signals. In this case you can tell MySQL not to use signals by configuring with: shell> CFLAGS=-DDONT_USE_THR_ALARM \ CXXFLAGS=-DDONT_USE_THR_ALARM \ ./configure ... This doesn't affect the performance of MySQL, but has the side effect that you can't kill clients that are "sleeping" on a connection with `mysqladmin kill' or `mysqladmin shutdown'. Instead, the client will die when it issues its next command. With `gcc' 2.95.2, you will probably run into the following compile error: sql_acl.cc:1456: Internal compiler error in `scan_region', at except.c:2566 Please submit a full bug report. To fix this you should change to the `sql' directory and do a "cut and paste" of the last `gcc' line, but change `-O3' to `-O0' (or add `-O0' immediately after `gcc' if you don't have any `-O' option on your compile line). After this is done you can just change back to the top-level directly and run `make' again. SGI Irix Notes .............. If you are using Irix Version 6.5.3 or newer `mysqld' will be able to create threads only if you run it as a user with `CAP_SCHED_MGT' privileges (like `root') or give the `mysqld' server this privilege with the following shell command: shell> chcap "CAP_SCHED_MGT+epi" /opt/mysql/libexec/mysqld You may have to undefine some symbols in `config.h' after running `configure' and before compiling. In some Irix implementations, the `alloca()' function is broken. If the `mysqld' server dies on some `SELECT' statements, remove the lines from `config.h' that define `HAVE_ALLOC' and `HAVE_ALLOCA_H'. If `mysqladmin create' doesn't work, remove the line from `config.h' that defines `HAVE_READDIR_R'. You may have to remove the `HAVE_TERM_H' line as well. SGI recommends that you install all of the patches on this page as a set: `http://support.sgi.com/surfzone/patches/patchset/6.2_indigo.rps.html' At the very minimum, you should install the latest kernel rollup, the latest `rld' rollup, and the latest `libc' rollup. You definitely need all the POSIX patches on this page, for pthreads support: `http://support.sgi.com/surfzone/patches/patchset/6.2_posix.rps.html' If you get the something like the following error when compiling `mysql.cc': "/usr/include/curses.h", line 82: error(1084): invalid combination of type Type the following in the top-level directory of your MySQL source tree: shell> extra/replace bool curses_bool < /usr/include/curses.h \ > include/curses.h shell> make There have also been reports of scheduling problems. If only one thread is running, performance is slow. Avoid this by starting another client. This may lead to a 2-to-10-fold increase in execution speed thereafter for the other thread. This is a poorly understood problem with Irix threads; you may have to improvise to find solutions until this can be fixed. If you are compiling with `gcc', you can use the following `configure' command: CC=gcc CXX=gcc CXXFLAGS=-O3 \ ./configure --prefix=/usr/local/mysql --enable-thread-safe-client \ --with-named-thread-libs=-lpthread On Irix 6.5.11 with native Irix C and C++ compilers ver. 7.3.1.2, the following is reported to work CC=cc CXX=CC CFLAGS='-O3 -n32 -TARG:platform=IP22 -I/usr/local/include \ -L/usr/local/lib' CXXFLAGS='-O3 -n32 -TARG:platform=IP22 \ -I/usr/local/include -L/usr/local/lib' \ ./configure --prefix=/usr/local/mysql --with-innodb --with-berkeley-db \ --with-libwrap=/usr/local \ --with-named-curses-libs=/usr/local/lib/libncurses.a SCO Notes ......... The current port is tested only on "sco3.2v5.0.5", "sco3.2v5.0.6" and "sco3.2v5.0.7" systems. There has also been a lot of progress on a port to "sco 3.2v4.2". For the moment the recommended compiler on OpenServer is `gcc' 2.95.2. With this you should be able to compile MySQL with just: CC=gcc CXX=gcc ./configure ... (options) 1. For OpenServer 5.0.x you need to use gcc-2.95.2p1 or newer from the Skunkware. `http://www.sco.com/skunkware/' and choose browser OpenServer packages or by ftp to ftp2.caldera.com in the `pub/skunkware/osr5/devtools/gcc' directory. 2. You need the port of GCC 2.5.x for this product and the Development system. They are required on this version of SCO Unix. You cannot just use the GCC Dev system. 3. You should get the FSU Pthreads package and install it first. This can be found at `http://moss.csc.ncsu.edu/~mueller/ftp/pub/PART/pthreads.tar.gz'. You can also get a precompiled package from `http://www.mysql.com/Downloads/SCO/FSU-threads-3.5c.tar.gz'. 4. FSU Pthreads can be compiled with SCO Unix 4.2 with tcpip. Or OpenServer 3.0 or Open Desktop 3.0 (OS 3.0 ODT 3.0), with the SCO Development System installed using a good port of GCC 2.5.x ODT or OS 3.0 you will need a good port of GCC 2.5.x There are a lot of problems without a good port. The port for this product requires the SCO Unix Development system. Without it, you are missing the libraries and the linker that is needed. 5. To build FSU Pthreads on your system, do the following: 1. Run `./configure' in the `threads/src' directory and select the SCO OpenServer option. This command copies `Makefile.SCO5' to `Makefile'. 2. Run `make'. 3. To install in the default `/usr/include' directory, login as root, then `cd' to the `thread/src' directory, and run `make install'. 6. Remember to use GNU `make' when making MySQL. 7. If you don't start `mysqld_safe' as `root', you probably will get only the default 110 open files per process. `mysqld' will write a note about this in the log file. 8. With SCO 3.2V5.0.5, you should use FSU Pthreads version 3.5c or newer. You should also use `gcc' 2.95.2 or newer! The following `configure' command should work: shell> ./configure --prefix=/usr/local/mysql --disable-shared 9. With SCO 3.2V4.2, you should use FSU Pthreads version 3.5c or newer. The following `configure' command should work: shell> CFLAGS="-D_XOPEN_XPG4" CXX=gcc CXXFLAGS="-D_XOPEN_XPG4" \ ./configure \ --prefix=/usr/local/mysql \ --with-named-thread-libs="-lgthreads -lsocket -lgen -lgthreads" \ --with-named-curses-libs="-lcurses" You may get some problems with some include files. In this case, you can find new SCO-specific include files at `http://www.mysql.com/Downloads/SCO/SCO-3.2v4.2-includes.tar.gz'. You should unpack this file in the `include' directory of your MySQL source tree. SCO development notes: * MySQL should automatically detect FSU Pthreads and link `mysqld' with `-lgthreads -lsocket -lgthreads'. * The SCO development libraries are re-entrant in FSU Pthreads. SCO claims that its libraries' 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 `http://www.mysql.com/') comes linked with GNU `malloc'. If you encounter problems with memory usage, make sure that `gmalloc.o' is included in `libgthreads.a' and `libgthreads.so'. * In FSU Pthreads, the following system calls are pthreads-aware: `read()', `write()', `getmsg()', `connect()', `accept()', `select()', and `wait()'. * The CSSA-2001-SCO.35.2 (the patch is listed in custom as erg711905-dscr_remap security patch (version 2.0.0) breaks FSU threads and makes `mysqld' unstable. You have to remove this one if you want to run `mysqld' on an OpenServer 5.0.6 machine. * SCO provides Operating Systems Patches at `ftp://ftp.sco.com/pub/openserver5' for OpenServer 5.0.x * SCO provides 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 the above patches before trying to compile/use MySQL. SCO UnixWare Version 7.1.x Notes ................................ On UnixWare 7.1.0, 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 CXX=CC ./configure --prefix=/usr/local/mysql If you want to use `gcc', you must use `gcc' 2.95.2 or newer. CC=gcc CXX=g++ ./configure --prefix=/usr/local/mysql 1. SCO provides Operating Systems Patches at `ftp://ftp.sco.com/pub/unixware7' for UnixWare 7.1.1 and 7.1.3 and at `ftp://ftp.sco.com/pub/openunix8' for OpenUNIX 8.0.0. 2. SCO provides information about Security Fixes at `ftp://ftp.sco.com/pub/security/OpenUNIX' for OpenUNIX and at `ftp://ftp.sco.com/pub/security/UnixWare' for UnixWare. OS/2 Notes ---------- MySQL uses quite a few open files. Because of this, you should add something like the following to your `CONFIG.SYS' file: SET EMXOPT=-c -n -h1024 If you don't do this, you will probably run into the following error: File 'xxxx' not found (Errcode: 24) When using MySQL with OS/2 Warp 3, FixPack 29 or above is required. With OS/2 Warp 4, FixPack 4 or above is required. This is a requirement of the Pthreads library. MySQL must be installed on a partition with a type that supports long filenames, such as HPFS, FAT32, etc. The `INSTALL.CMD' script must be run from OS/2's own `CMD.EXE' and may not work with replacement shells such as `4OS2.EXE'. The `scripts/mysql-install-db' script has been renamed. It is now called `install.cmd' and is a REXX script, which will set up the default MySQL security settings and create the WorkPlace Shell icons for MySQL. Dynamic module support is compiled in but not fully tested. Dynamic modules should be compiled using the Pthreads run-time library. gcc -Zdll -Zmt -Zcrtdll=pthrdrtl -I../include -I../regex -I.. \ -o example udf_example.cc -L../lib -lmysqlclient udf_example.def mv example.dll example.udf *Note:* Due to limitations in OS/2, UDF module name stems must not exceed 8 characters. Modules are stored in the `/mysql2/udf' directory; the `safe-mysqld.cmd' script will put this directory in the `BEGINLIBPATH' environment variable. When using UDF modules, specified extensions are ignored--it is assumed to be `.udf'. For example, in Unix, the shared module might be named `example.so' and you would load a function from it like this: mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME "example.so"; In OS/2, the module would be named `example.udf', but you would not specify the module extension: mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME "example"; BeOS Notes ---------- We have in the past talked with some BeOS developers that have said that MySQL is 80% ported to BeOS, but we haven't heard from them in a while. Perl Installation Notes ======================= Perl support for MySQL is provided by means of the `DBI'/`DBD' client interface. The interface requires Perl Version 5.6.0 or later. It *will not work* if you have an older version of Perl. If you want to use transactions with Perl DBI, you need to have `DBD::mysql' version 1.2216 or newer. Version 2.9003 or newer is recommended. As of Version 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 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. *Note MySQL Benchmarks::. 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 necesssary files. However, if you installed MySQL from RPM files on Linux, be sure that you've installed the developer RPM. The client programs are in the client RPM, but client programming support is in the developer RPM. If you want to install Perl support, the files you will need can be obtained from the CPAN (Comprehensive Perl Archive Network) at `http://search.cpan.org'. The easiest way to install Perl modules on Unix is to use the `CPAN' module. For example: shell> perl -MCPAN -e shell cpan> install DBI cpan> install DBD::mysql The `DBD::mysql' installation runs a number of tests. These tests require being able to connect to the local MySQL server as the anonymous user with no password. If you have removed anonymous accounts or assigned them passwords, the tests fail. You can use `force install DBD::mysql' to ignore the failed tests. `DBI' requires the `Data::Dumper' module. It may already be installed; if not, you should install it before installing `DBI'. It is also possible to download the module distributions in the form of compressed `tar' archives and build the modules manually. For example, to unpack and build a DBI distribution, use a procedure such as this: 1. Unpack the distribution into the current directory: shell> gunzip < DBI-VERSION.tar.gz | tar xvf - This command creates a directory named `DBI-VERSION'. 2. Change into the top-level directory of the unpacked distribution: shell> cd DBI-VERSION 3. Build the distribution and compile everything: shell> perl Makefile.PL shell> make shell> make test shell> make install The `make test' command is important because it verifies that the module is working. Note that when you run that command during the `DBD::mysql' installation to exercise the interface code, the MySQL server must be running or the test will fail. 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'. Installing ActiveState Perl on Windows -------------------------------------- On Windows, you should do the following to install the MySQL `DBD' module with ActiveState Perl: * Get ActiveState Perl from `http://www.activestate.com/Products/ActivePerl/' and install it. * Open a console window (a "DOS window"). * If required, set the `HTTP_proxy' variable. For example, you might try: set HTTP_proxy=my.proxy.com:3128 * Start the PPM program: C:\> c:\perl\bin\ppm.pl * If you have not already done so, install `DBI': ppm> install DBI * If this succeeds, run the following command: install \ ftp://ftp.de.uu.net/pub/CPAN/authors/id/JWIED/DBD-mysql-1.2212.x86.ppd The above should work at least with ActiveState Perl Version 5.6. If you can't get the above to work, you should instead install the `MyODBC' driver and connect to the MySQL server through ODBC: use DBI; $dbh= DBI->connect("DBI:ODBC:$dsn",$user,$password) || die "Got error $DBI::errstr when connecting to $dsn\n"; 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"; 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: NEW: CC = cc CC = gcc CCCDLFLAGS = -KPIC -W1,-Bexport CCCDLFLAGS = -fpic CCDLFLAGS = -wl,-Bexport CCDLFLAGS = LD = ld LD = gcc -G -fpic LDDLFLAGS = -G -L/usr/local/lib LDDLFLAGS = -L/usr/local/lib LDFLAGS = -belf -L/usr/local/lib LDFLAGS = -L/usr/local/lib LD = ld LD = gcc -G -fpic OPTIMISE = -Od OPTIMISE = -O1 OLD: CCCFLAGS = -belf -dy -w0 -U M_XENIX -DPERL_SCO5 -I/usr/local/include NEW: CCFLAGS = -U M_XENIX -DPERL_SCO5 -I/usr/local/include This is because the Perl dynaloader will 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 (like SCO) you can generate a static version of Perl that includes `DBI' and `DBD::mysql'. The way this works is that you generate a version of Perl with the `DBI' code linked in and install it on top of your current Perl. Then you use that to build a version of Perl that additionally has the `DBD' code linked in, and install that. On SCO, you must have the following environment variables set: shell> LD_LIBRARY_PATH=/lib:/usr/lib:/usr/local/lib:/usr/progressive/lib or: shell> LD_LIBRARY_PATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\ /usr/progressive/lib:/usr/skunk/lib shell> LIBPATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\ /usr/progressive/lib:/usr/skunk/lib shell> MANPATH=scohelp:/usr/man:/usr/local1/man:/usr/local/man:\ /usr/skunk/man: First, create a Perl that includes a statically linked `DBI' module by running these commands in the directory where your `DBI' distribution is located: shell> perl Makefile.PL -static -config shell> make shell> make install shell> make perl Then you must install the new Perl. The output of `make perl' will indicate the exact `make' command you will need to execute to perform the installation. On SCO, this is `make -f Makefile.aperl inst_perl MAP_TARGET=perl'. Next, use the just-created Perl to create another Perl that also includes a statically linked `DBD::mysql' by running these commands in the directory where your `DBD::mysql' distribution is located: shell> perl Makefile.PL -static -config shell> make shell> make install shell> make perl Finally, you should install this new Perl. Again, the output of `make perl' indicates the command to use. MySQL Tutorial ************** This chapter provides a tutorial introduction to MySQL by showing how to use the `mysql' client program to create and use a simple database. `mysql' (sometimes referred to as the "terminal monitor" or just "monitor") is an interactive program that allows you to connect to a MySQL server, run queries, and view the results. `mysql' may also be used in batch mode: you place your queries in a file beforehand, then tell `mysql' to execute the contents of the file. Both ways of using `mysql' are covered here. To see a list of options provided by `mysql', invoke it with the `--help' option: shell> mysql --help This chapter assumes that `mysql' is installed on your machine and that a MySQL server is available to which you can connect. If this is not true, contact your MySQL administrator. (If *you* are the administrator, you will need to consult other sections of this manual.) This chapter describes the entire process of setting up and using a database. If you are interested only in accessing an already-existing database, you may want to skip over the sections that describe how to create the database and the tables it contains. Because this chapter is tutorial in nature, many details are necessarily omitted. Consult the relevant sections of the manual for more information on the topics covered here. Connecting to and Disconnecting from the Server =============================================== To connect to the server, you'll 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'll also need to specify a hostname. Contact your administrator to find out what connection parameters you should use to connect (that is, what host, username, and password to use). Once you know the proper parameters, you should be able to connect like this: shell> mysql -h host -u user -p Enter password: ******** `host' and `user' represent the hostname where your MySQL server is running and the username of your MySQL account. Substitute appropriate values for your setup. The `********' represents your password; enter it when `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: shell> mysql After you have connected successfully, you can disconnect any time by typing `QUIT' (or `\q') at the `mysql>' prompt: mysql> QUIT Bye On Unix, you can also disconnect by pressing Control-D. Most examples in the following sections assume you are connected to the server. They indicate this by the `mysql>' prompt. Entering Queries ================ Make sure you are connected to the server, as discussed in the previous section. Doing so will not in itself select any database to work with, but that's okay. At this point, it's more important to find out a little about how to issue queries than to jump right in creating tables, loading data into them, and retrieving data from them. This section describes the basic principles of entering commands, using several queries you can try out to familiarise yourself with how `mysql' works. Here's a simple command that asks the server to tell you its version number and the current date. Type it in as shown here following the `mysql>' prompt and press Enter: mysql> SELECT VERSION(), CURRENT_DATE; +--------------+--------------+ | VERSION() | CURRENT_DATE | +--------------+--------------+ | 3.22.20a-log | 1999-03-19 | +--------------+--------------+ 1 row in set (0.01 sec) mysql> This query illustrates several things about `mysql': * A command normally consists of an SQL statement followed by a semicolon. (There are some exceptions where a semicolon may be omitted. `QUIT', mentioned earlier, is one of them. We'll get to others later.) * When you issue a command, `mysql' sends it to the server for execution and displays the results, then prints another `mysql>' prompt to indicate that it is ready for another command. * `mysql' displays query output in tabular form (rows and columns). The first row contains labels for the columns. The rows following are the query results. Normally, column labels are the names of the columns you fetch from database tables. If you're retrieving the value of an expression rather than a table column (as in the example just shown), `mysql' labels the column using the expression itself. * `mysql' shows how many rows were returned and how long the query took to execute, which gives you a rough idea of server performance. These values are imprecise because they represent wall clock time (not CPU or machine time), and because they are affected by factors such as server load and network latency. (For brevity, the "rows in set" line is not shown in the remaining examples in this chapter.) Keywords may be entered in any lettercase. The following queries are equivalent: mysql> SELECT VERSION(), CURRENT_DATE; mysql> select version(), current_date; mysql> SeLeCt vErSiOn(), current_DATE; Here's another query. It demonstrates that you can use `mysql' as a simple calculator: mysql> SELECT SIN(PI()/4), (4+1)*5; +-------------+---------+ | SIN(PI()/4) | (4+1)*5 | +-------------+---------+ | 0.707107 | 25 | +-------------+---------+ The queries shown thus far have been relatively short, single-line statements. You can even enter multiple statements on a single line. Just end each one with a semicolon: mysql> SELECT VERSION(); SELECT NOW(); +--------------+ | VERSION() | +--------------+ | 3.22.20a-log | +--------------+ +---------------------+ | NOW() | +---------------------+ | 1999-03-19 00:15:33 | +---------------------+ A command need not be given all on a single line, so lengthy commands that require several lines are not a problem. `mysql' determines where your statement ends by looking for the terminating semicolon, not by looking for the end of the input line. (In other words, `mysql' accepts free-format input: it collects input lines but does not execute them until it sees the semicolon.) Here's a simple multiple-line statement: mysql> SELECT -> USER() -> , -> CURRENT_DATE; +--------------------+--------------+ | USER() | CURRENT_DATE | +--------------------+--------------+ | joesmith@localhost | 1999-03-18 | +--------------------+--------------+ In this example, notice how the prompt changes from `mysql>' to `->' after you enter the first line of a multiple-line query. This is how `mysql' indicates that it hasn't seen a complete statement and is waiting for the rest. The prompt is your friend, because it provides valuable feedback. If you use that feedback, you will always be aware of what `mysql' is waiting for. If you decide you don't want to execute a command that you are in the process of entering, cancel it by typing `\c': mysql> SELECT -> USER() -> \c mysql> Here, too, notice the prompt. It switches back to `mysql>' after you type `\c', providing feedback to indicate that `mysql' is ready for a new command. The following table shows each of the prompts you may see and summarizes what they mean about the state that `mysql' is in: *Prompt**Meaning* `mysql>'Ready for new command. ` Waiting for next line of multiple-line command. ->' ` Waiting for next line, collecting a string that begins '>' with a single quote (`''). ` Waiting for next line, collecting a string that begins ">' with a double quote (`"'). ` Waiting for next line, collecting an identifier that `>' begins with a backtick (``'). Multiple-line statements commonly occur by accident when you intend to issue a command on a single line, but forget the terminating semicolon. In this case, `mysql' waits for more input: mysql> SELECT USER() -> If this happens to you (you think you've entered a statement but the only response is a `->' prompt), most likely `mysql' is waiting for the semicolon. If you don't notice what the prompt is telling you, you might sit there for a while before realising what you need to do. Enter a semicolon to complete the statement, and `mysql' will execute it: mysql> SELECT USER() -> ; +--------------------+ | USER() | +--------------------+ | joesmith@localhost | +--------------------+ The `'>' and `">' prompts occur during string collection. In MySQL, you can write strings surrounded by either `'' or `"' characters (for example, `'hello'' or `"goodbye"'), and `mysql' lets you enter strings that span multiple lines. When you see a `'>' or `">' prompt, it means that you've entered a line containing a string that begins with a `'' or `"' quote character, but have not yet entered the matching quote that terminates the string. That's fine if you really are entering a multiple-line string, but how likely is that? Not very. More often, the `'>' and `">' prompts indicate that you've inadvertantly left out a quote character. For example: mysql> SELECT * FROM my_table WHERE name = "Smith AND age < 30; "> If you enter this `SELECT' statement, then press Enter and wait for the result, nothing will happen. Instead of wondering why this query takes so long, notice the clue provided by the `">' prompt. It tells you that `mysql' expects to see the rest of an unterminated string. (Do you see the error in the statement? The string `"Smith' is missing the second quote.) At this point, what do you do? The simplest thing is to cancel the command. However, you cannot just type `\c' in this case, because `mysql' interprets it as part of the string that it is collecting! Instead, enter the closing quote character (so `mysql' knows you've finished the string), then type `\c': mysql> SELECT * FROM my_table WHERE name = "Smith AND age < 30; "> "\c mysql> The prompt changes back to `mysql>', indicating that `mysql' is ready for a new command. The ``>' prompt is similar to th `'>' and `">' prompts, but indicates that you have begun but not completed a backtick-quoted identifier. It's important to know what the `'>', `">', and ``>' prompts signify, because if you mistakenly enter an unterminated string, any further lines you type will appear to be ignored by `mysql'--including a line containing `QUIT'! This can be quite confusing, especially if you don't know that you need to supply the terminating quote before you can cancel the current command. Creating and Using a Database ============================= Now that you know how to enter commands, it's time to access a database. Suppose you have several pets in your home (your menagerie) and you'd like to keep track of various types of information about them. You can do so by creating tables to hold your data and loading them with the desired information. Then you can answer different sorts of questions about your animals by retrieving data from the tables. This section shows you how to: * Create a database * Create a table * Load data into the table * Retrieve data from the table in various ways * Use multiple tables The menagerie database will be simple (deliberately), but it is not difficult to think of real-world situations in which a similar type of database might be used. For example, a database like this could be used by a farmer to keep track of livestock, or by a veterinarian to keep track of patient records. A menagerie distribution containing some of the queries and sample data used in the following sections can be obtained from the MySQL web site. It's available in either compressed `tar' format (`http://www.mysql.com/Downloads/Contrib/Examples/menagerie.tar.gz') or Zip format (`http://www.mysql.com/Downloads/Contrib/Examples/menagerie.zip'). Use the `SHOW' statement to find out what databases currently exist on the server: mysql> SHOW DATABASES; +----------+ | Database | +----------+ | mysql | | test | | tmp | +----------+ The list of databases is probably different on your machine, but the `mysql' and `test' databases are likely to be among them. The `mysql' database is required because it describes user access privileges. The `test' database is often provided as a workspace for users to try things out. Note that you may not see all databases if you don't have the `SHOW DATABASES' privilege. *Note `GRANT': GRANT. If the `test' database exists, try to access it: mysql> USE test Database changed Note that `USE', like `QUIT', does not require a semicolon. (You can terminate such statements with a semicolon if you like; it does no harm.) The `USE' statement is special in another way, too: it must be given on a single line. You can use the `test' database (if you have access to it) for the examples that follow, but anything you create in that database can be removed by anyone else with access to it. For this reason, you should probably ask your MySQL administrator for permission to use a database of your own. Suppose you want to call yours `menagerie'. The administrator needs to execute a command like this: mysql> GRANT ALL ON menagerie.* TO 'your_mysql_name'@'your_client_host'; where `your_mysql_name' is the MySQL username assigned to you and `your_client_host' is the host from which you connect to the server. 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' is not your password on the command just shown. If you want to supply your password on the command-line after the `-p' option, you must do so with no intervening space (for example, as `-pmypassword', not as `-p mypassword'). However, putting your password on the command-line is not recommended, because doing so exposes it to snooping by other users logged in on your machine. Creating a Table ---------------- Creating the database is the easy part, but at this point it's empty, as `SHOW TABLES' will tell you: mysql> SHOW TABLES; Empty set (0.00 sec) The harder part is deciding what the structure of your database should be: what tables you will need and what columns will be in each of them. You'll want a table that contains a record for each of your pets. This can be called the `pet' table, and it should contain, as a bare minimum, each animal's name. Because the name by itself is not very interesting, the table should contain other information. For example, if more than one person in your family keeps pets, you might want to list each animal's owner. You might also want to record some basic descriptive information such as species and sex. How about age? That might be of interest, but it's not a good thing to store in a database. Age changes as time passes, which means you'd have to update your records often. Instead, it's better to store a fixed value such as date of birth. Then, whenever you need age, you can calculate it as the difference between the current date and the birth date. MySQL provides functions for doing date arithmetic, so this is not difficult. Storing birth date rather than age has other advantages, too: * You can use the database for tasks such as generating reminders for upcoming pet birthdays. (If you think this type of query is somewhat silly, note that it is the same question you might ask in the context of a business database to identify clients to whom you'll soon need to send out birthday greetings, for that computer-assisted personal touch.) * You can calculate age in relation to dates other than the current date. For example, if you store death date in the database, you can easily calculate how old a pet was when it died. You can probably think of other types of information that would be useful in the `pet' table, but the ones identified so far are sufficient for now: name, owner, species, sex, birth, and death. Use a `CREATE TABLE' statement to specify the layout of your table: mysql> CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20), -> species VARCHAR(20), sex CHAR(1), birth DATE, death DATE); `VARCHAR' is a good choice for the `name', `owner', and `species' columns because the column values will vary in length. The lengths of those columns need not all be the same, and need not be `20'. You can pick any length from `1' to `255', whatever seems most reasonable to you. (If you make a poor choice and it turns out later that you need a longer field, MySQL provides an `ALTER TABLE' statement.) Several types of values can be chosen to represent sex in animal records, such as `"m"' and `"f"', or perhaps `"male"' and `"female"'. It's simplest to use the single characters `"m"' and `"f"'. The use of the `DATE' datatype for the `birth' and `death' columns is a fairly obvious choice. Now that you have created a table, `SHOW TABLES' should produce some output: mysql> SHOW TABLES; +---------------------+ | Tables in menagerie | +---------------------+ | pet | +---------------------+ To verify that your table was created the way you expected, use a `DESCRIBE' statement: mysql> DESCRIBE pet; +---------+-------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +---------+-------------+------+-----+---------+-------+ | name | varchar(20) | YES | | NULL | | | owner | varchar(20) | YES | | NULL | | | species | varchar(20) | YES | | NULL | | | sex | char(1) | YES | | NULL | | | birth | date | YES | | NULL | | | death | date | YES | | NULL | | +---------+-------------+------+-----+---------+-------+ You can use `DESCRIBE' any time, for example, if you forget the names of the columns in your table or what types they have. Loading Data into a Table ------------------------- After creating your table, you need to populate it. The `LOAD DATA' and `INSERT' statements are useful for this. Suppose your pet records can be described as shown here. (Observe that MySQL expects dates in `'YYYY-MM-DD'' format; this may be different from what you are used to.) *name* *owner* *species**sex**birth* *death* Fluffy Harold cat f 1993-02-04 Claws Gwen cat m 1994-03-17 Buffy Harold dog f 1989-05-13 Fang Benny dog m 1990-08-27 Bowser Diane dog m 1979-08-31 1995-07-29 Chirpy Gwen bird f 1998-09-11 WhistlerGwen bird 1997-12-09 Slim Benny snake m 1996-04-29 Because you are beginning with an empty table, an easy way to populate it is to create a text file containing a row for each of your animals, then load the contents of the file into the table with a single statement. You could create a text file `pet.txt' containing one record per line, with values separated by tabs, and given in the order in which the columns were listed in the `CREATE TABLE' statement. For missing values (such as unknown sexes or death dates for animals that are still living), you can use `NULL' values. To represent these in your text file, use `\N' (backslash, capital-N). For example, the record for Whistler the bird would look like this (where the whitespace between values is a single tab character): *name* *owner* *species**sex**birth* *death* `Whistler'`Gwen' `bird' `\N' `1997-12-09' `\N' To load the text file `pet.txt' into the `pet' table, use this command: mysql> LOAD DATA LOCAL INFILE "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 "pet.txt" INTO TABLE pet -> LINES TERMINATED BY '\r\n'; You can specify the column value separator and end of line marker explicitly in the `LOAD DATA' statement if you wish, but the defaults are tab and linefeed. These are sufficient for the statement to read the file `pet.txt' properly. If the statement fails, it is likely that your MySQL installation does not have local file capability enabled by default. See *Note `LOAD DATA LOCAL': LOAD DATA LOCAL for information on how to change this. When you want to add new records one at a time, the `INSERT' statement is useful. In its simplest form, you supply values for each column, in the order in which the columns were listed in the `CREATE TABLE' statement. Suppose 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