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 Stability of MySQL 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 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 Do 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 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 Quick Standard MySQL Installation 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 on Windows MySQL on Windows Compared to MySQL on Unix Installing MySQL on Linux Installing MySQL on Mac OS X Installing MySQL on NetWare General Installation Issues How to Get MySQL Verifying Package Integrity Using `MD5 Checksums' or `GnuPG' Operating Systems Supported by MySQL Which MySQL Version to Use Installation Layouts How and When Updates Are Released Release Philosophy - No Known Bugs in Releases MySQL Binaries Compiled by MySQL AB Installing a MySQL Binary Distribution Installing a MySQL Source Distribution Quick Installation Overview Applying Patches 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 Problems Running `mysql_install_db' Problems Starting the MySQL Server Starting and Stopping MySQL Automatically Upgrading/Downgrading MySQL 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 the Grant Tables Upgrading to Another Architecture Upgrading MySQL under Windows Operating System Specific Notes Linux Notes (All Linux Versions) Linux Notes for Binary Distributions Linux x86 Notes Linux SPARC Notes Linux Alpha Notes Linux PowerPC Notes Linux MIPS Notes Linux IA-64 Notes 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 Mac OS X Notes Mac OS X 10.x Mac OS X Server 1.2 (Rhapsody) Other Unix Notes HP-UX Notes for Binary Distributions 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 Comments 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 Database Administration Configuring MySQL `mysqld' Command-line Options `my.cnf' Option Files 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 General Security Issues and the MySQL Access Privilege System General Security Guidelines How to Make MySQL Secure Against Crackers Startup Options for `mysqld' Concerning Security Security issues with `LOAD DATA LOCAL' 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 `GRANT' and `REVOKE' Syntax MySQL User Names 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 `BACKUP TABLE' Syntax `RESTORE TABLE' Syntax `CHECK TABLE' Syntax `REPAIR TABLE' Syntax 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 Database Administration Language Reference `OPTIMIZE TABLE' Syntax `ANALYZE TABLE' Syntax `CHECKSUM TABLE' Syntax `FLUSH' Syntax `RESET' Syntax `PURGE MASTER LOGS' Syntax `KILL' 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' 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 MySQL Server-Side Scripts and Utilities Overview of the Server-Side Scripts and Utilities `mysqld_safe', The Wrapper Around `mysqld' `mysqld_multi', A Program for Managing Multiple MySQL Servers `myisampack', The MySQL Compressed Read-only Table Generator `mysqld-max', An Extended `mysqld' Server MySQL Client-Side Scripts and Utilities Overview of the Client-Side Scripts and Utilities `mysql', The Command-line Tool `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 `mysql_config', Get compile options for compiling clients `perror', Explaining Error Codes How to Run SQL Commands from a Text File The MySQL Log Files The Error Log The General Query Log The Update Log The Binary Log The Slow Query Log Log File Maintenance Replication in MySQL Introduction 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 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' 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 `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 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 Language Reference Language Structure Literals: How to Write Strings and Numbers Strings Numbers Hexadecimal Values `NULL' Values Database, Table, Index, Column, and Alias Names Case Sensitivity in Names User Variables 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 for Use in `SELECT' and `WHERE' Clauses 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 Miscellaneous Functions Functions and Modifiers for Use with `GROUP BY' Clauses `GROUP BY' Functions `GROUP BY' Modifiers `GROUP BY' with Hidden Fields Data Manipulation: `SELECT', `INSERT', `UPDATE', `DELETE' `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 `INSERT' Syntax `INSERT ... SELECT' Syntax `INSERT DELAYED' Syntax `UPDATE' Syntax `DELETE' Syntax `TRUNCATE' Syntax `REPLACE' Syntax `LOAD DATA INFILE' Syntax `HANDLER' Syntax `DO' Syntax Data Definition: `CREATE', `DROP', `ALTER' `CREATE DATABASE' Syntax `DROP DATABASE' Syntax `CREATE TABLE' Syntax Silent Column Specification Changes `ALTER TABLE' Syntax `RENAME TABLE' Syntax `DROP TABLE' Syntax `CREATE INDEX' Syntax `DROP INDEX' Syntax Basic MySQL User Utility Commands `USE' Syntax `DESCRIBE' Syntax (Get Information About Columns) MySQL Transactional and Locking Commands `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 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 `ISAM' Tables `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-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 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 Functions to Convert Geometries Between Formats `Geometry' Property Analysis Functions General Geometry Property Analysis Functions `Point' Property Analysis Functions `LineString' Property Analysis Functions `MultiLineString' Property Analysis Functions `Polygon' Property Analysis Functions `MultiPolygon' Property Analysis Functions `GeometryCollection' Property Analysis 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 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 `DBI' with `DBD::mysql' The `DBI' Interface More `DBI'/`DBD' Information 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-definable Function UDF Calling Sequences for simple functions UDF Calling Sequences for aggregate functions Argument Processing Return Values and Error Handling Compiling and Installing User-definable 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 Contributed Programs APIs Converters Utilities Credits Developers at MySQL AB Contributors to MySQL Documenters and translators Libraries used by and included with MySQL Packages that support MySQL Tools that was used to create MySQL Supporters to MySQL MySQL Change History Changes in release 5.0.0 (Development) Changes in release 5.0.0 (not released yet) 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.18 (not released yet) 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 5.0.0-alpha 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', you should send an email to . About This Manual ================= This is the `MySQL' reference manual; it documents `MySQL' up to Version 5.0.0-alpha. Functional changes are always indicated with reference to the version, so this manual is also suitable if you are using an older version of the `MySQL' software (such as 3.23 or 4.0-production). There are also references for version 5.0 (development). Being a reference manual, it does not provide general instruction on `SQL' or relational database concepts. As the `MySQL Database Software' is under constant development, the manual is also updated frequently. The most recent version of this manual is available at `http://www.mysql.com/documentation/' in many different formats, including HTML, PDF, and Windows HLP versions. The primary document is the Texinfo file. The HTML version is produced automatically using a modified version of `texi2html'. The plain text and Info versions are produced with `makeinfo'. The PostScript version is produced using `texi2dvi' and `dvips'. The PDF version is produced with `pdftex'. If you have a hard time finding information in the manual, you can try our searchable version at `http://www.mysql.com/doc/'. If you have any suggestions concerning additions or corrections to this manual, please send them to the documentation team at . 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 (2003) 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 command that you execute from the `mysql' client program: shell> type a shell command here mysql> type a mysql command here The "shell" is your command interpreter. On Unix, this is typically a program such as `sh' or `csh'. On Windows, the equivalent is `command.com' or `cmd.exe', typically run in a Windows console. Shell commands are shown using Bourne shell syntax. If you are using a `csh'-style shell, you may need to issue commands slightly differently. For example, the sequence to set an environment variable and run a command looks like this in Bourne shell syntax: shell> VARNAME=value some_command For `csh' or `tcsh', you would execute the sequence like this: shell> setenv VARNAME value shell> some_command Database, table, and column names must often be substituted into commands. To indicate that such substitution is necessary, this manual uses `db_name', `tbl_name', and `col_name'. For example, you might see a statement like this: mysql> SELECT col_name FROM db_name.tbl_name; This means that if you were to enter a similar statement, you would supply your own database, table, and column names, perhaps like this: mysql> SELECT author_name FROM biblio_db.author_list; SQL keywords are not case sensitive and may be written in uppercase or lowercase. This manual uses uppercase. In syntax descriptions, square brackets (`[' and `]') are used to indicate optional words or clauses. For example, in the following statement, `IF EXISTS' is optional: DROP TABLE [IF EXISTS] tbl_name When a syntax element consists of a number of alternatives, the alternatives are separated by vertical bars (`|'). When one member from a set of choices *may* be chosen, the alternatives are listed within square brackets (`[' and `]'): TRIM([[BOTH | LEADING | TRAILING] [remstr] FROM] str) When one member from a set of choices *must* be chosen, the alternatives are listed within braces (`{' and `}'): {DESCRIBE | DESC} tbl_name {col_name | wild} 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 version of the standard that is expected to be released in mid-2003.We use the term "`the SQL standard'" to mean the current version of the SQL Standard at any time.) MySQL software is `Open Source'. `Open Source' means that it is possible for anyone to use and modify the software. Anybody can download the `MySQL' software from the Internet and use it without paying anything. If you wish, you may study the source code and change it to suit your needs. The `MySQL' software uses the `GPL' (`GNU General Public License'), `http://www.fsf.org/licenses/', to define what you may and may not do with the software in different situations. If you feel uncomfortable with the `GPL' or need to embed `MySQL' code into a commercial application, you can buy a commercially licensed version from us. *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 For advanced technical information, see *Note Reference::. 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 nor flexible enough for our needs. This resulted in a new SQL interface to our database but with almost the same API interface as `mSQL'. This API was chosen to allow third-party code that was written for use with `mSQL' to be ported easily for use with `MySQL'. The derivation of the name `MySQL' is not clear. Our base directory and a large number of our libraries and tools have had the prefix "my" for well over 10 years. However, co-founder Monty Widenius's daughter is also named My. Which of the two gave its name to `MySQL' is still a mystery, even for us. The name of the MySQL Dolphin (our logo) is `Sakila'. `Sakila' was chosen by the founders of MySQL AB from a huge list of names suggested by users in our "Name the Dolphin" contest. The winning name was submitted by Ambrose Twebaze, an open source software developer from Swaziland, Africa. According to Ambrose, the name Sakila has its roots in SiSwati, the local language of Swaziland. Sakila is also the name of a town in Arusha, Tanzania, near Ambrose's country of origin, Uganda. 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 through a highly optimized class library and should be as fast as possible. Usually there isn't any 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/'). * Available as client/server or embedded (linked) version. Column Types * Many column types: signed/unsigned integers 1, 2, 3, 4, and 8 bytes long, `FLOAT', `DOUBLE', `CHAR', `VARCHAR', `TEXT', `BLOB', `DATE', `TIME', `DATETIME', `TIMESTAMP', `YEAR', `SET', and `ENUM' types. *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::. 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. * 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. Stability of MySQL ------------------ This section addresses the questions "_How stable is MySQL Server?_" and "_Can I depend on MySQL Server in this project?_" We will try to clarify these issues and answer some important questions that concern many potential users. The information in this section is based on data gathered from the mailing list, which is very active in identifying problems as well as reporting types of use. The original code stems back from the early 1980s, providing a stable code base, and the ISAM table format remains backward-compatible. At TcX, the predecessor of `MySQL AB', `MySQL' code has worked in projects since mid-1996, without any problems. When the `MySQL Database Software' was released to a wider public, our new users quickly found some pieces of "untested code". Each new release since then has had fewer portability problems (even though each new release has also had many new features). Each release of the `MySQL Server' has been usable. Problems have occurred only when users try code from the "gray zones." Naturally, new users don't know what the gray zones are; this section therefore attempts to document those areas that are currently known. The descriptions mostly deal with Version 3.23 and 4.0 of `MySQL Server'. All known and reported bugs are fixed in the latest version, with the exception of those listed in the bugs section, which are design-related. *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. *`MyODBC 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' table type in `MySQL' Version 3.23, the maximum table size was increased to 8 million terabytes (2 ^ 63 bytes). With this larger allowed table size, the maximum effective table size for `MySQL' databases now normally is determined by operating system constraints on file sizes, not by MySQL internal limits. The following table lists some examples of operating system file-size limits: *Operating System* *File-Size Limit* Linux-Intel 32-bit 2 GB, much more when using LFS Linux-Alpha 8 TB (?) Solaris 2.5.1 2 GB (4GB possible with patch) Solaris 2.6 4 GB (can be changed with flag) Solaris 2.7 Intel 4 GB Solaris 2.7 512 GB UltraSPARC On Linux 2.2 you can get tables larger than 2 GB in size by using the LFS patch for the ext2 filesystem. On Linux 2.4 patches also exist for ReiserFS to get support for big files. Most current Linux distributions are based on kernel 2.4 and already include all the required Large File Support (LFS) patches. However, the maximum available file size still depends on several factors, one of them being the file system used to store MySQL tables. For a very detailed overview about LFS in Linux, have a look at Andreas Jaeger's "Large File Support in Linux" page at . 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 table that will be larger than 4 GB in size (and your operating system supports large files), the `CREATE TABLE' statement allows `AVG_ROW_LENGTH' and `MAX_ROWS' options. Use these options to create tables that can be larger than 4 GB. *Note `CREATE TABLE': CREATE TABLE. You can also set these options later, with `ALTER TABLE'. *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 identical tables as one. *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 stored in one file, `sql/time.cc', and are coded very carefully to be year 2000-safe. * In `MySQL' Version 3.22 and later, the `YEAR' column type can store years `0' and `1901' to `2155' in one byte and display them using two or four digits. All 2-digit years are considered to be in the range `1970' to `2069', which means that if you store `01' in a `YEAR' column, `MySQL Server' treats it as `2001'. The following simple demonstration illustrates that `MySQL Server' doesn't have any problems with dates until after the year 2030: mysql> DROP TABLE IF EXISTS y2k; Query OK, 0 rows affected (0.01 sec) mysql> CREATE TABLE y2k (date DATE, -> date_time DATETIME, -> time_stamp TIMESTAMP); Query OK, 0 rows affected (0.00 sec) mysql> INSERT INTO y2k VALUES -> ("1998-12-31","1998-12-31 23:59:59",19981231235959), -> ("1999-01-01","1999-01-01 00:00:00",19990101000000), -> ("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 Net every day with one another and with our users, supporters, and partners. We are dedicated to developing the `MySQL' software and spreading our database to new users. `MySQL AB' owns the copyright to the `MySQL' source code, the `MySQL' logo and trademark, and this manual. *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 giving support to customers and other users in order to stay in touch with their needs and problems. All our support is given by qualified developers. Really tricky questions are answered by Michael `Monty' Widenius, principal author of the `MySQL Server'. *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 programme that covers training courses, consulting and support, publications, plus reselling and distributing `MySQL' and related products. `MySQL AB Partners' get visibility on the `http://www.mysql.com/' web site and the right to use special versions of the `MySQL' trademarks to identify their products and promote their business. If you are interested in becoming a `MySQL AB Partner', please 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 October 2001, we served 10 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 an 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 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 an email message 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 an 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 an 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 an 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 the `MySQL Server', please send an email 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 an 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 an 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 operating system or networking impacts on `MySQL', set up best practices for backup and recovery, utilise APIs, and so on. Our support covers only the `MySQL' server and our own utilities, not third-party products that access the `MySQL' server, though we try to help with these where we can. Detailed information about our various support options is given at `http://www.mysql.com/support/', where support contracts can also be ordered online. If you have restricted access to the Internet, please contact our sales staff via email at . Technical support is like life insurance. You can live happily without it for years, but when your hour arrives it becomes critically important, yet it's too late to buy it. If you use `MySQL Server' for important applications and encounter sudden difficulties, it may be too time consuming to figure out all the answers yourself. You may need immediate access to the most experienced `MySQL' troubleshooters available, those employed by `MySQL AB'. 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 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 since it is a smart, fast, and lean animal, effortlessly navigating oceans of data. We also happen to like dolphins. The original `MySQL' logo may only be used by representatives of `MySQL AB' and by those having a written agreement allowing them to do so. 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 version series. 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. MySQL 4.0 was declared stable for production use as of Version 4.0.12, released in March 2003. This means that, in the future, only bug fixes will be done for the 4.0 series and only critical bug fixes will be done for the older 3.23 series. *Note Upgrading-from-3.23::. New features to the `MySQL' software are being added to MySQL 4.1 which is now also available (alpha version). *Note MySQL 4.1 Nutshell::. 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, creation of `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 on MySQL Server. *Note Fulltext Search::. Standards compliance, portability, and migration * Features to simplify migration from other database systems to MySQL Server include `TRUNCATE TABLE' (as in Oracle). * Many users will also be happy to learn that MySQL Server now supports the `UNION' statement, a long-awaited standard SQL feature. * MySQL now runs natively on the Novell NetWare 6.0 platform. *Note NetWare installation::. Internationalisation * Our German, Austrian, and Swiss users will note that `MySQL' now supports a new character set, `latin1_de', which ensures that the _German sorting order_ sorts words with umlauts in the same order as do German telephone books. Usability enhancements In the process of implementing features for new users, we have not forgotten requests from our loyal community of existing users. * Most `mysqld' parameters (startup options) can now be set without taking down the server. This is a convenient feature for database administrators (DBAs). *Note `SET OPTION': SET OPTION. * Multiple-table `DELETE' and `UPDATE' statements have been added.. * Support has been added to the `MyISAM' storage engine for symbolic linking at the table level (and not just the database level as before). Also, symbolic link handling at the database level is enabled by default on Windows. * `SQL_CALC_FOUND_ROWS' and `FOUND_ROWS()' are new functions that make it possible to find out the number of rows a `SELECT' query that includes a `LIMIT' clause would have returned without that clause. The news section of this manual includes a more in-depth list of features. *Note News-4.0.x::. Embedded MySQL Server ..................... `libmysqld' makes MySQL Server suitable for a vastly expanded realm of applications. Using the embedded MySQL server library, one can embed MySQL Server into various applications and electronics devices, where the end user has no knowledge of there actually being an underlying database. Embedded MySQL Server is ideal for use behind the scenes in Internet appliances, public kiosks, turnkey hardware/software combination units, high performance Internet servers, self-contained databases distributed on CD-ROM, and so on. Many users of `libmysqld' will benefit from the MySQL _Dual Licensing_. For those not wishing to be bound by the `GPL', the software is also made available under a commercial license. The embedded MySQL library uses the same interface as the normal client library, so it is convenient and easy to use. *Note `libmysqld': libmysqld. MySQL 4.1 in a Nutshell ----------------------- MySQL Server 4.0 laid the foundation for new features such as subqueries and Unicode (implemented in version 4.1) and for the work on SQL-99 stored procedures being done for version 5.0. These features come at the top of the wish list of many of our customers. With these additions, critics of the MySQL Database Server have to be more imaginative than ever in pointing out deficiencies in the MySQL database management system. Already well-known for its stability, speed, and ease of use, MySQL Server will be able to fulfill the requirement checklists of very demanding buyers. 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, such as stored procedures, 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 protocol with 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. * Support for OpenGIS spatial types (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 jobs such as bulk loading of data much easier to track. `SHOW WARNINGS' shows warnings for the last command. *Note `SHOW WARNINGS': SHOW WARNINGS. Internationalisation * To support our ever expanding user base using local languages in applications, the MySQL software now offers extensive Unicode support through the `utf8' and `ucs2' character sets. * Character sets can now be defined per column, table, and database. This allows for a high degree of flexibility in application design, particularly for multi-language web sites. * For documentation for this improved character set support, see *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 for that particular server version. Because this information is available by issuing a SQL statement, any client can be written to access it. For example, the `mysql' command line client has been modified to have this capability. * In the new client/server protocol, multiple statements can be issued with a single call. *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. (See previous item.) * A new `INSERT ... ON DUPLICATE KEY UPDATE ...' syntax has been implemented. This allows you to `UPDATE' an existing row if the `INSERT' would have caused a duplicate in a `PRIMARY' or `UNIQUE' key (index). *Note INSERT::. * We have implemented a new aggregate function, `GROUP_CONCAT()', that adds the extremely useful capability of concatenating columns from grouped rows into a single result string. *Note Group by functions and modifiers::. The news section in 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 have made 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 have made our BitKeeper repository for MySQL version 5.0 publicly available. *Note Installing source tree::. MySQL and the Future (The TODO) =============================== This section summarizes the features that we plan to implement in `MySQL Server'. The lists are broken up per version, and the items are approximately in the order they will be done. *Note*: If you are an enterprise level user with an urgent need for a particular feature, please contact 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. 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 have made our BitKeeper repository for MySQL version 5.0 publicly available. *Note Installing source tree::. Stored Procedures * Stored procedures are currently being implemented. This effort is based on SQL-99, which has a basic syntax similar (but not identical) to Oracle PL/SQL. We will also implement the SQL-99 framework to hook in external languages, and (where possible) compatibility with, for example, PL/SQL and T-SQL. New functionality * Elementary cursor support. * The ability to specify explicitly for `MyISAM' tables that an index should be created as an `RTREE' index. In 4.1, `RTREE' indexes are used internally for geometrical data (GIS datatypes), but cannot be created on request. * Dynamic length rows for `HEAP' tables. Standards compliance, portability and migration * Add true `VARCHAR' support (column lengths longer than 255, and no stripping of trailing whitespace). (There is already support for this in the `MyISAM' storage engine, but it is not yet available at the user level.) Speed enhancements * `SHOW COLUMNS FROM table_name' (used by `mysql' client to allow expansions of column names) should not open the table, only the definition file. This will require less memory and be much faster. * Allow `DELETE' on `MyISAM' tables to use the record cache. To do this, we need to update the threads record cache when we update the `.MYD' file. * Better in-memory (`HEAP') tables: * Dynamic size rows. * Faster row handling (less copying). Internationalisation * When using `SET CHARACTER SET' we should translate the whole query at once and not only strings. This will enable users to use the translated characters in database, table, and column names. Usability enhancements * Resolving the issue of `RENAME TABLE' on a table used in an active `MERGE' table possibly corrupting the table. New Features Planned for 5.1 ---------------------------- New functionality * `FOREIGN KEY' support for all table types. * Column-level constraints. * Fail-safe replication. * Online backup with very low performance penalty. The online backup will make it easy to add a new replication slave without taking down the master. Speed enhancements * New text based table definition file format (`.frm' files) and a table cache for table definitions. This will enable us to do faster queries of table structures and do more efficient foreign key support. * Optimize `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 update of variables 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/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' recover at the same time. * Change `INSERT ... SELECT' to optionally use concurrent inserts. * Add an option to periodically flush key pages for tables with delayed keys if they haven't been used in a while. * Allow join on key parts (optimization issue). * Add simulation of `pread()'/`pwrite()' on Windows to enable concurrent inserts. * Add a logfile analyzer that could parse out information about which tables are hit most often, how often multiple-table joins are executed, etc. This should help users identify areas or table design that could be optimized to execute much more efficient queries. Internationalisation Usability enhancements * Return the original field types() when doing `SELECT MIN(column) ... GROUP BY'. * Make it possible to specify `long_query_time' with a granularity in microseconds. * Link the `myisampack' code into the server so that it can perform `PACK' or `COMPRESS' operations. * Add a temporary key buffer cache during `INSERT/DELETE/UPDATE' so that we can gracefully recover if the index file gets full. * If you perform an `ALTER TABLE' on a table that is symlinked to another disk, create temporary tables on that disk. * Implement a `DATE/DATETIME' type that handles time zone information properly, to make dealing with dates in different time zones easier. * Fix `configure' so that one can compile all libraries (like `MyISAM') without threads. * Allow SQL variables as `LIMIT' arguments, for example, `LIMIT @a,@b'. * Automatic output from `mysql' to a web browser. * `LOCK DATABASES' (with various options). * Many more variables for `SHOW STATUS'. Records reads and updates. Selects on a single table and selects with joins. Mean number of tables in select. Number of `ORDER BY' and `GROUP BY' queries. * `mysqladmin copy database new-database'; this requires a `COPY' operation to be added to `mysqld'. * Processlist output should indicate the number of queries/threads. * `SHOW HOSTS' for printing information about the hostname cache. * Change table names from empty strings to `NULL' for calculated columns. * Don't use `Item_copy_string' on numerical values to avoid number->string->number conversion in case of: `SELECT COUNT(*)*(id+0) FROM table_name GROUP BY id' * Change so that `ALTER TABLE' doesn't abort clients that execute `INSERT DELAYED'. * Fix so that when columns are referenced in an `UPDATE' clause, they contain the old values from before the update started. New operating systems * Port of the MySQL clients to LynxOS. New Features Planned for the Mid-Term Future -------------------------------------------- * Implement function: `get_changed_tables(timeout,table1,table2,...)'. * Change reading through tables to use memmap when possible. Now only compressed tables use memmap. * Make the automatic timestamp code nicer. Add timestamps to the update log with `SET TIMESTAMP=#;'. * Use read/write mutex in some places to get more speed. * Simple views (stepwise implementation up to full functionality). *Note ANSI diff Views::. * Automatically close some tables if a table, temporary table, or temporary files gets error 23 (not enough open files). * Better constant propagation. When an occurrence of `col_name=n' is found in an expression, for some constant `n', replace other occurrences of `col_name' within the expression with `n'. Currently, this is done only for some simple cases. * Change all const expressions with calculated expressions if possible. * Optimize key = expression. At the moment only key = field or key = constant 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 (5 days). * Change the parser to use only one rule per different number of arguments in function. * Use of full calculation names in the order part (for ACCESS97). * `MINUS', `INTERSECT', and `FULL OUTER JOIN'. (Currently `UNION' [in 4.0] and `LEFT|RIGHT OUTER JOIN' are supported.) * Allow `SQL_OPTION MAX_SELECT_TIME=#', for placing a time limit on a query. * Make the update log write to a database. * Enhance `LIMIT' to allow retrieval of data from the end of a result set. * Alarm around client connect/read/write functions. * 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. * Add use of `zlib()' to `LOAD DATA INFILE', to allow the statement to read files that have been compressed with `gzip'. * Fix sorting and grouping of `BLOB' columns (partly solved now). * Change to use semaphores when counting threads. One should first implement a semaphore library for MIT-pthreads. * Add full support for `JOIN' with parentheses. * As an alternative for one thread/connection manage a pool of threads to handle the queries. * Allow `GET_LOCK()' to obtain more than one lock. When doing this, one must also handle the possible deadlocks this change will introduce. Time is given according to amount of work, not real time. New Features We Don't Plan to Do -------------------------------- We aim toward full compliance with SQL-92/SQL-99; there are no features we plan not to implement. 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, as email messages, all postings to the list. You will also be able 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 pay for 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, so we can't guarantee their quality. ` 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/solved. * Search the MySQL mailing list archives: `http://lists.mysql.com/' * You can also use `http://www.mysql.com/search/' to search all the web pages (including the manual) that are located at `http://www.mysql.com/'. If you can't find an answer in the manual or the archives, check with your local MySQL expert. If you still can't find an answer to your question, please follow the guidelines on sending mail to a MySQL mailing list, outlined in the next section, before contacting us. How to Report Bugs or Problems .............................. Our bugs database is public, and can be browsed and searched by anyone at `http://bugs.mysql.com/'. If you log into the system, you will also be able to enter new reports. Writing a good bug report takes patience, but doing it right the first time saves time both for us and for yourself. A good bug report, containing a full test case for the bug, makes it very likely that we will fix the bug in the next release. This section will help you write your report correctly so that you don't waste your time doing things that may not help us much or at all. We encourage everyone to use the `mysqlbug' script to generate a bug report (or a report about any problem). `mysqlbug' can be found in the `scripts' directory (source distribution) and in the `bin' directory under your MySQL installation directory (binary distribution). If you are unable to use `mysqlbug' (for instance, if you are running on Windows), it is still vital that you include all the necessary information noted in this section (most importantly a description of the operating system and the MySQL version). The `mysqlbug' script helps you generate a report by determining much of the following information automatically, but if something important is missing, please include it with your message. Please read this section carefully and make sure that all the information described here is included in your report. Preferably, you should test the problem using the latest production or development version of MySQL Server before posting. Anyone should be able to repeat the bug by just using '`mysql test < script'' on the included test case or run the shell or Perl script that is included in the bug report. All bugs posted in the bugs database at `http://bugs.mysql.com/' will be corrected or documented in the next MySQL release. If only minor code changes are needed to correct a problem, we will also post a patch that fixes the problem. The normal place to report bugs is `http://bugs.mysql.com/'. If you have found a sensitive security bug in MySQL, please send an email to . If you have a repeatable bug report, please report this into the bugs database at `http://bugs.mysql.com/'. Note that even in this case it's good to run the `mysqlbug' script first to find information about your system. Any bug that we are able to repeat has a high chance of being fixed in the next MySQL release. To report other problems, you can use one of the MySQL mailing lists. Remember that it is possible for us to respond to a message containing too much information, but not to one containing too little. People often omit facts because they think they know the cause of a problem and assume that some details don't matter. A good principle is: if you are in doubt about stating something, state it. It is a thousand times faster and less troublesome to write a couple of lines more in your report than to be forced to ask again and wait for the answer because you didn't include enough information the first time. The most common errors made in bug reports are (a) not including the version number of the MySQL distribution used and (b) not fully describing the platform on which the MySQL server is installed (including the platform type and version number). This is highly relevant information, and in 99 cases out of 100 the bug report is useless without it. Very often we get questions like, "Why doesn't this work for me?" Then we find that the feature requested wasn't implemented in that MySQL version, or that a bug described in a report has already been fixed in newer MySQL versions. Sometimes the error is platform-dependent; in such cases, it is next to impossible for us to fix anything without knowing the operating system and the version number of the platform. Remember also to provide information about your compiler, if it is related to the problem. Often people find bugs in compilers and think the problem is MySQL-related. Most compilers are under development all the time and become better version by version. To determine whether your problem depends on your compiler, we need to know what compiler you use. Note that every compiling problem should be regarded as a bug and reported accordingly. It is most helpful when a good description of the problem is included in the bug report. That is, give a good example of everything you did that led to the problem and describe, in exact detail, the problem itself. The best reports are those that include a full example showing how to reproduce the bug or problem. *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 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. For most operating systems, you can get this information by executing the Unix command `uname -a'. If you work with Windows, you can usually get the name and version number by double-clicking your "My Computer" icon and pulling down the "Help/About Windows" menu. * Sometimes the amount of memory (real and virtual) is relevant. If in doubt, include these values. * If you are using a source distribution of the MySQL software, the name and version number of the compiler used is needed. If you have a binary distribution, the distribution name is needed. * If the problem occurs during compilation, include the exact error messages and also a few lines of context around the offending code in the file where the error occurrs. * If `mysqld' died, you should also report the query that crashed `mysqld'. You can usually find this out by running `mysqld' with logging enabled. *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 of course be posted with the `mysqlbug' script). Example run using the `mysql' command-line tool (note the use of the `\G' statement terminator for statements whose output width would otherwise exceed that of an 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' daemon as well as the options that you use to run any MySQL client programs. The options to programs like `mysqld' and `mysql', and to the `configure' script, are often keys to answers and are very relevant. It is never a bad idea to include them. If you use any modules, such as Perl or PHP, please include the version numbers of those as well. * If your question is related to the privilege system, please include the output of `mysqlaccess', the output of `mysqladmin reload', and all the error messages you get when trying to connect. When you test your privileges, you should first run `mysqlaccess'. After this, execute `mysqladmin reload version' and try to connect with the program that gives you trouble. `mysqlaccess' can be found in the `bin' directory under your MySQL installation directory. * If you have a patch for a bug, do include it. But don't assume the patch is all we need, or that we will use it, if you don't provide some necessary information such as test cases showing the bug that your patch fixes. We might find problems with your patch or we might not understand it at all; if so, we can't use it. If we can't verify exactly what the patch is meant for, we won't use it. Test cases will help us here. Show that the patch will handle all the situations that may occur. If we find a borderline case (even a rare one) where the patch won't work, it may be useless. * Guesses about what the bug is, why it occurs, or what it depends on are usually wrong. Even the MySQL team can't guess such things without first using a debugger to determine the real cause of a bug. * Indicate in your bug report that you have checked the reference manual and mail archive so that others know you have tried to solve the problem yourself. * If you get a `parse error', please check your syntax closely. If you can't find something wrong with it, it's extremely likely that your current version of MySQL Server doesn't support the syntax you are using. If you are using the current version and the manual at `http://www.mysql.com/doc/' doesn't cover the syntax you are using, MySQL Server doesn't support your query. In this case, your only options are to implement the syntax yourself or 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 repairing your tables with `myisamchk' or `CHECK TABLE' and `REPAIR TABLE'. *Note MySQL Database Administration::. If you are running windows, please check that `lower_case_table_names is ON' 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 `mysql-data-directory/'hostname'.err' file may contain some information about what happened. *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 if 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, without a very good reason, restrict MySQL Server usability for any usage. Even if we don't have the resources to do development for every possible use, we are always willing to help and offer suggestions to people who are trying to use MySQL Server in new territories. One of our main goals with the product is to continue to work toward compliance with the SQL-99 standard, but without sacrificing speed or reliability. We are not afraid to add extensions to SQL or support for non-SQL features if this greatly increases the usability of MySQL Server for a big part of our users. (The new `HANDLER' interface in MySQL Server 4.0 is an example of this strategy. *Note `HANDLER': HANDLER.) We will continue to support transactional and non-transactional databases to satisfy both heavy web/logging usage and mission-critical 24/7 usage. MySQL Server was designed from the start to work with medium size databases (10-100 million rows, or about 100 MB per table) on small computer systems. We will continue to extend MySQL Server to work even better with terabyte-size databases, as well as to make it possible to compile a reduced MySQL version that is more suitable for hand-held devices and embedded usage. The compact design of the MySQL server makes both of these directions possible without any conflicts in the source tree. We are currently not targeting realtime support (even if you can already do a lot of things with our replication services). Database cluster support is planned to begin sometime in 2004 through implementation of a new storage engine. We are looking at providing XML support in the database server. What Standards MySQL Follows ---------------------------- Entry-level SQL-92. ODBC levels 0-3.51. We are aiming toward supporting the full SQL-99 standard, but without concessions to speed and quality of the code. Running MySQL in ANSI Mode -------------------------- If you start `mysqld' with the `--ansi' or `--sql-mode=ANSI' option, the following behaviors of MySQL Server change: * `||' is a string concatenation operator rather than a synonym for `OR'. * `"' is treated as an identifier quote character (like the MySQL Server ``' quote character) and not as a string quote character. You can still use ``' to quote identifers in ANSI mode. An implication of this is that you cannot use double quotes to quote a literal string, because it will be intepreted as an identifier. * You can have any number of spaces between a function name and the `(' character. This forces all function names to be treated as reserved words. As a result, if you want to access any database, table, or column name that is a reserved word, you must quote it. For example, because there is a `USER()' function, the name of the `user' table in the `mysql' database and the `User' column in that table become reserved, so you must quote them: SELECT "User" FROM mysql."user"; * `REAL' is a synonym for `FLOAT' instead of a synonym for `DOUBLE'. * The default transaction isolation level is `SERIALIZABLE'. *Note `SET TRANSACTION': SET TRANSACTION. * You can use a field/expression in `GROUP BY' that is not in the field list. Running the server in ANSI mode is the same as starting it with these options: --sql-mode=REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_BY --transaction-isolation=SERIALIZABLE In MySQL 4.1, you can achieve the same effect with these two statements: SET GLOBAL TRANSACTION ISOLATION LEVEL SERIALIZABLE; SET GLOBAL sql_mode = "REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_BY"; In MySQL 4.1.1, the `sql_mode' options shown can be also be set with: SET GLOBAL sql_mode="ansi"; In this case, the value of the `sql_mode' variable will be set to all options that are relevant for ANSI mode. You can check the result by doing: mysql> SET GLOBAL sql_mode="ansi"; mysql> SELECT @@GLOBAL.sql_mode; -> "REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_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 `'!'', the syntax will be executed only if the MySQL version is equal to or newer than the used version number: CREATE /*!32302 TEMPORARY */ TABLE t (a INT); This means that if you have Version 3.23.02 or newer, MySQL Server will use the `TEMPORARY' keyword. The following is a list of MySQL extensions: * The field types `MEDIUMINT', `SET', `ENUM', and the different `BLOB' and `TEXT' types. * The field attributes `AUTO_INCREMENT', `BINARY', `NULL', `UNSIGNED', and `ZEROFILL'. * All string comparisons are case-insensitive by default, with sort ordering determined by the current character set (ISO-8859-1 Latin1 by default). If you don't like this, you should declare your columns with the `BINARY' attribute or use the `BINARY' cast, which causes comparisons to be done according to the ASCII order used on the MySQL server host. * MySQL Server maps each database to a directory under the MySQL data directory, and tables within a database to filenames in the database directory. This has a few implications: - Database names and table names are case sensitive in MySQL Server on operating systems that have case sensitive filenames (like most Unix systems). *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. For example, to rename a table, rename the `.MYD', `.MYI', and `.frm' files to which the table corresponds. * In SQL statements, you can access tables from different databases with the `db_name.tbl_name' syntax. Some SQL servers provide the same functionality but call this `User space'. MySQL Server doesn't support tablespaces as in: `create table ralph.my_table...IN my_tablespace'. * `LIKE' is allowed on numeric columns. * Use of `INTO OUTFILE' and `STRAIGHT_JOIN' in a `SELECT' statement. *Note `SELECT': SELECT. * The `SQL_SMALL_RESULT' option in a `SELECT' statement. * `EXPLAIN SELECT' to get a description of how tables are joined. * Use of index names, indexes on a prefix of a field, and use of `INDEX' or `KEY' in a `CREATE TABLE' statement. *Note `CREATE TABLE': CREATE TABLE. * Use of `TEMPORARY' or `IF NOT EXISTS' with `CREATE TABLE'. * Use of `COUNT(DISTINCT list)' where `list' has more than one element. * Use of `CHANGE col_name', `DROP col_name', or `DROP INDEX', `IGNORE' or `RENAME' in an `ALTER TABLE' statement. *Note `ALTER TABLE': ALTER TABLE. * Use of `RENAME TABLE'. *Note `RENAME TABLE': RENAME TABLE. * Use of multiple `ADD', `ALTER', `DROP', or `CHANGE' clauses in an `ALTER TABLE' statement. * Use of `DROP TABLE' with the keywords `IF EXISTS'. * You can drop multiple tables with a single `DROP TABLE' statement. * The `ORDER BY' and `LIMIT' clauses of the `UPDATE' and `DELETE' statements. * `INSERT INTO ... SET col_name = ...' syntax. * The `DELAYED' clause of the `INSERT' and `REPLACE' statements. * The `LOW_PRIORITY' clause of the `INSERT', `REPLACE', `DELETE', and `UPDATE' statements. * Use of `LOAD DATA INFILE'. In many cases, this syntax is compatible with Oracle's `LOAD DATA INFILE'. *Note `LOAD DATA': LOAD DATA. * The `ANALYZE TABLE', `CHECK TABLE', `OPTIMIZE TABLE', and `REPAIR TABLE' statements. * The `SHOW' statement. *Note `SHOW': SHOW. * Strings may be enclosed by either `"' or `'', not just by `''. * Use of the escape `\' character. * The `SET' statement. *Note `SET': SET OPTION. * 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::. * One can specify `ASC' and `DESC' with `GROUP BY'. * To make it easier for users who come from other SQL environments, MySQL Server supports aliases for many functions. For example, all string functions support both standard SQL syntax and ODBC syntax. * MySQL Server understands the `||' and `&&' operators to mean logical OR and AND, as in the C programming language. In MySQL Server, `||' and `OR' are synonyms, as are `&&' and `AND'. Because of this nice syntax, MySQL Server doesn't support the standard SQL-99 `||' operator for string concatenation; use `CONCAT()' instead. Because `CONCAT()' takes any number of arguments, it's easy to convert use of the `||' operator to MySQL Server. * `CREATE DATABASE' or `DROP DATABASE'. *Note `CREATE DATABASE': CREATE DATABASE. * 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 `mysql_insert_id()': mysql_insert_id. * The `REGEXP' and `NOT REGEXP' extended regular expression operators. * `CONCAT()' or `CHAR()' with one argument or more than two arguments. (In MySQL Server, these functions can take any number of arguments.) * The `BIT_COUNT()', `CASE', `ELT()', `FROM_DAYS()', `FORMAT()', `IF()', `PASSWORD()', `ENCRYPT()', `MD5()', `ENCODE()', `DECODE()', `PERIOD_ADD()', `PERIOD_DIFF()', `TO_DAYS()', or `WEEKDAY()' functions. * Use of `TRIM()' to trim substrings. SQL-99 supports removal of single characters only. * The `GROUP BY' functions `STD()', `BIT_OR()', `BIT_AND()', `BIT_XOR()', and `GROUP_CONCAT()'. *Note Group by functions and modifiers::. * Use of `REPLACE' instead of `DELETE' + `INSERT'. *Note `REPLACE': REPLACE. * The `FLUSH', `RESET' and `DO' statements. * The ability to set variables in a statement with `:=': SELECT @a:=SUM(total),@b=COUNT(*),@a/@b AS avg FROM test_table; SELECT @t1:=(@t2:=1)+@t3:=4,@t1,@t2,@t3; MySQL Differences Compared to SQL-92 ------------------------------------ We try to make MySQL Server follow the ANSI SQL standard (SQL-92/SQL-99) and the ODBC SQL standard, but in some cases MySQL Server performs operations differently: * For `VARCHAR' columns, trailing spaces are removed when the value is stored. *Note Bugs::. * In some cases, `CHAR' columns are silently changed to `VARCHAR' columns. *Note Silent column changes::. * Privileges for a table are not automatically revoked when you delete a table. You must explicitly issue a `REVOKE' to revoke privileges for a table. *Note `GRANT': GRANT. 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::. Subqueries .......... MySQL Version 4.1 supports subqueries and derived tables (unnamed views). *Note Subqueries::. For MySQL versions prior to 4.1, most subqueries can be successfully rewritten using joins and and other methods. *Note Rewriting subqueries::. `SELECT INTO TABLE' ................... MySQL Server doesn't yet support the Sybase SQL extension: `SELECT ... INTO TABLE ...'. Instead, MySQL Server supports the SQL-99 syntax `INSERT INTO ... SELECT ...', which is basically the same thing. *Note 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'. 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 table types (such as `MyISAM') in MySQL Server follow a different paradigm for data integrity called "`Atomic Operations'." In transactional terms, `MyISAM' tables effectively always operate in `AUTOCOMMIT=1' mode. Atomic operations often offer comparable integrity with higher performance. With MySQL Server supporting both paradigms, the user is able to decide if he needs the speed of atomic operations or if he needs to use transactional features in his applications. This choice can be made on a per-table basis. As noted, the trade off for transactional vs. non-transactional table types lies mostly in performance. Transactional tables have significantly higher memory and diskspace requirements, and more CPU overhead. That said, transactional table types such as `InnoDB' do of course offer many unique features. MySQL Server's modular design allows the concurrent use of all these different storage engines to suit different requirements and deliver optimum performance in all situations. But how does one use the features of MySQL Server to maintain rigorous integrity even with the non-transactional `MyISAM' tables, and how do these features compare with the transactional table types? 1. In the transactional paradigm, if your applications are written in a way that is dependent on the calling of `ROLLBACK' instead of `COMMIT' in critical situations, transactions are more convenient. Transactions also ensure that unfinished updates or corrupting activities are not committed to the database; the server is given the opportunity to do an automatic rollback and your database is saved. MySQL Server, in almost all cases, allows you to resolve potential problems by including simple checks before updates and by running simple scripts that check the databases for inconsistencies and automatically repair or warn if such an inconsistency occurs. Note that just by using the MySQL log or even adding one extra log, one can normally fix tables perfectly with no data integrity loss. 2. More often than not, critical transactional updates can be rewritten to be atomic. Generally speaking, all integrity problems that transactions solve can be done with `LOCK TABLES' or atomic updates, ensuring that you never will get an automatic abort from the server, which is a common problem with transactional database systems. 3. Even a transactional system can lose data if the server goes down. The difference between different systems lies in just how small the time-lap is where they could lose data. No system is 100% secure, only "secure enough." Even Oracle, reputed to be the safest of transactional database systems, is reported to sometimes lose data in such situations. To be safe with MySQL Server, whether using transactional tables or not, you only need to have backups and have the binary logging turned on. With this you can recover from any situation that you could with any other transactional database system. It is, of course, always good to have backups, independent of which database system you use. The transactional paradigm has its benefits and its drawbacks. Many users and application developers depend on the ease with which they can code around problems where an abort appears to be, or is necessary. However, even if you are new to the atomic operations paradigm, or more familiar with transactions, do consider the speed benefit that 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 only obtain a read lock (as opposed to a write lock), reads and inserts are still allowed to happen. The new inserted records will not be seen by any of the clients that have a read lock until they release their read locks. With `INSERT DELAYED' you can queue inserts into a local queue, until the locks are released, without having the client wait for the insert to complete. *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 conditions. 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 `ROLLBACK' and/or `LOCK TABLES' for the purpose of managing unique identifiers for some tables. This can be handled much more efficiently by using an `AUTO_INCREMENT' column and either the SQL function `LAST_INSERT_ID()' or the C API function `mysql_insert_id()'. *Note `mysql_insert_id()': mysql_insert_id. You can generally code around row-level locking. Some situations really need it, and `InnoDB' tables support row-level locking. With MyISAM, you can use a flag column in the table and do something like the following: UPDATE tbl_name SET row_flag=1 WHERE id=ID; MySQL returns 1 for the number of affected rows if the row was found and `row_flag' wasn't already 1 in the original row. You can think of it as though MySQL Server changed the preceding query to: UPDATE tbl_name SET row_flag=1 WHERE id=ID AND row_flag <> 1; Stored Procedures and Triggers .............................. Stored procedures are being implemented in our version 5.0 development tree. *Note Installing source tree::. This effort is based on SQL-99, which has a basic syntax similar (but not identical) to Oracle PL/SQL. In addition to this, we are implementing the SQL-99 framework to hook in external languages. A stored procedure is a set of SQL commands that can be compiled and stored in the server. Once this has been done, clients don't need to keep re-issuing the entire query but can refer to the stored procedure. This provides better overall performance because the query has to be parsed only once, and less information needs to be sent between the server and the client. You can also raise the conceptual level by having libraries of functions in the server. However, stored procedures of course do increase the load on the database server system, as more of the work is done on the server side and less on the client (application) side. Triggers are scheduled for implementation in MySQL version 5.1. A trigger is effectively a type of stored procedure, one that is invoked when a particular event occurs. For example, you could set up a stored procedure that is triggered each time a record is deleted from a transactional table and that stored procedure automatically deletes the corresponding customer from a customer table when all their transactions are deleted. Foreign Keys ............ In MySQL Server 3.23.44 and up, `InnoDB' tables support checking of foreign key constraints, including `CASCADE', `ON DELETE', and `ON UPDATE'. *Note InnoDB foreign key constraints::. For other table types, MySQL Server currently only parses the `FOREIGN KEY' syntax in `CREATE TABLE' commands, but does not use/store this info. In the near future this implementation will be extended so that the information is stored in the table specification file and may be retrieved by `mysqldump' and ODBC. At a later stage, foreign key constraints will be implemented for `MyISAM' tables as well. Note that foreign keys in SQL are not used to join tables, but are used for checking and enforcing referential integrity (foreign key constraints). If you want to get results from multiple tables from a `SELECT' statement, you do this by joining tables: SELECT * FROM table1,table2 WHERE table1.id = table2.id; *Note `JOIN': JOIN. *Note example-Foreign keys::. When used as a constraint, foreign keys don't need to be used if the application inserts rows into `MyISAM' tables in the proper order. For `MyISAM' tables, you can work around the lack of `ON DELETE' by adding the appropriate `DELETE' statement to an application when you delete records from a table that has a foreign key. In practice this is as quick (in some cases quicker) and much more portable than using foreign keys. In MySQL Server 4.0 you can use multiple-table delete to delete rows from many tables with one command. *Note DELETE::. The `FOREIGN KEY' syntax without `ON DELETE ...' is often used by ODBC applications to produce automatic `WHERE' clauses. Do keep in mind that foreign keys are often misused, which can cause severe problems. Even when used properly, foreign key support is not a magic solution for the referential integrity problem, although it can help. Some advantages of foreign key enforcement: * Assuming proper design of the relationships, foreign key constraints will make it more difficult for a programmer to introduce an inconsistency into the database. * Using cascading updates and deletes can simplify the client code. * Properly designed foreign key rules aid in documenting relationships between tables. Disadvantages: * Mistakes, which are easy to make in designing key relationships, can cause severe problems--for example, circular rules, or the wrong combination of cascading deletes. * Additional checking on the database level affects performance, for this reason some major commercial applications have coded this logic on the application level. * It is not uncommon for a DBA to make such a complex topology of relationships that it becomes very difficult, and in some cases impossible, to back up or restore individual tables. Views ..... Views are currently being implemented, and will appear in the 5.0 or 5.1 version of MySQL Server. Historically, MySQL Server has been most used in applications and on web systems where the application writer has full control over database usage. Of course, usage has shifted over time, and so we find that an increasing number of users now regard views as an important aspect. Unnamed views (_derived tables_, a subquery in the `FROM' clause of a `SELECT') are already implemented in version 4.1. Views are useful for allowing users to access a set of relations (tables) as if it were a single table, and limiting their access to just that. Views can also be used to restrict access to rows (a subset of a particular table). One does not require views to restrict access to columns, as MySQL Server has a sophisticated privilege system. *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 our implementation of views, we aim toward (as fully as possible within the confines of SQL) compliance with "*Codd's Rule #6*" for relational database systems: all views that are theoretically updatable, should in practice also be updatable. `--' as the Start of a Comment .............................. Some other SQL databases use `--' to start comments. MySQL Server has `#' as the start comment character. You can also use the C comment style `/* this is a comment */' with MySQL Server. *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). This is because this comment style has caused many problems with automatically generated SQL queries that have used something like the following code, where we automatically insert the value of the payment for `!payment!': UPDATE tbl_name SET credit=credit-!payment! Think about what happens if the value of `payment' is negative. Because `1--1' is legal in SQL, the consequences of allowing comments to start with `--' are terrible. Using our implementation of this method of commenting in MySQL Server Version 3.23.3 and up, `1-- This is a comment' is actually safe. Another safe feature is that the `mysql' command-line client removes all lines that start with `--'. The following information is relevant only if you are running a MySQL version earlier than 3.23.3: If you have an SQL program in a text file that contains `--' comments you should use: shell> replace " --" " #" < text-file-with-funny-comments.sql \ | mysql database instead of the usual: shell> mysql database < text-file-with-funny-comments.sql You can also edit the command file "in place" to change the `--' comments to `#' comments: shell> replace " --" " #" -- text-file-with-funny-comments.sql Change them back with this command: shell> replace " #" " --" -- text-file-with-funny-comments.sql How MySQL deals with constraints -------------------------------- As MySQL allows you to work with both transactional and non-transactional tables (which don't allow rollback), constraint handling is a bit different in MySQL than in other databases. We have to handle the case when you have updated a lot of rows with a non-transactional table which can't rollback on errors. The basic philosophy is to try to give an error for anything that we can detect on compile time but try to recover from any errors we get run time. We do this in most cases, but not yet for all. *Note TODO future::. The basic options MySQL has is to stop the statement in the middle or do its best to recover from the problem and continue. Here follows what happens with the different types of constraints. Constraint PRIMARY KEY / UNIQUE ............................... Normally you will get an error when you try to `INSERT' / `UPDATE' a row that causes a primary key, unique key or foreign key violation. If you are using a transactional storage engine, like InnoDB, MySQL will automatically roll back the transaction. If you are using a non-transactional storage engine MySQL will stop at the wrong row and leave the rest of the rows unprocessed. To make life easier MySQL has added support for the `IGNORE' directive to most commands that can cause a key violation (like `INSERT IGNORE ...'). In this case MySQL will ignore any key violation and continue with processing the next row. You can get information of what MySQL did with the `mysql_info()' API function and in later MySQL 4.1 version with the `SHOW WARNINGS' command. *Note mysql_info::. *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 inclusion in the MySQL 5.0 source tree. Constraint `NOT NULL' and `DEFAULT' values .......................................... To be able to support easy handling of non-transactional tables all fields in MySQL have default values. If you insert a 'wrong' value in a column like a `NULL' in a `NOT NULL' column or a too big numerical value in a numerical column, MySQL will instead of giving an error instead set the column to the 'best possible value'. For numerical values this is 0, the smallest possible values or the largest possible value. For strings this is either the empty string or the longest possible string that can be in the column. This means that if you try to store `NULL' into a column that doesn't take `NULL' values, MySQL Server will store 0 or `''' (empty string) in it instead. This last behavior can, for single row inserts, be changed with the `-DDONT_USE_DEFAULT_FIELDS' compile option.) *Note 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 above rules is that we can't check these conditions before the query starts to execute. If we encounter a problem after updating a few rows, we can't just rollback as the table type may not support this. The option to stop is not that good as in this case the update would be 'half done' which is probably the worst possible scenario. In this case it's better to 'do the best you can' and then continue as if nothing happened. In MySQL 5.0 we plan to improve this by providing warnings for automatic field conversions, plus an option to let you roll back statements that only use transactional tables in case one such statement does a field assignment that is not allowed. The above means that one should generally not use MySQL to check field content, but instead handle this in the application. Constraint `ENUM' and `SET' ........................... In MySQL 4.x `ENUM' is not a real constraint but a more efficient way to store fields that can only contain a given set of values. This is because of the same reasons `NOT NULL' is not honored. *Note constraint NOT NULL::. If you insert an wrong value in an `ENUM' field, it will be set to the reserved enum number `0', which will be displayed as an empty string in string context. *Note ENUM::. If you insert an wrong option in a `SET' field, the wrong value will be ignored. *Note SET::. Known Errors and Design Deficiencies in MySQL --------------------------------------------- Errors in 3.23 Fixed in a Later MySQL Version ............................................. The following known errors/bugs are not fixed in MySQL 3.23 because fixing them would involve changing a lot of code that could introduce other even worse bugs. The bugs are also classified as "not fatal" or "bearable." * One can get a deadlock when doing `LOCK TABLE' on multiple tables and then in the same connection doing a `DROP TABLE' on one of them while another thread is trying to lock the table. One can however do a `KILL' on any of the involved threads to resolve this. Fixed in 4.0.12. * `SELECT MAX(key_column) FROM t1,t2,t3...' where one of the tables are empty doesn't return `NULL' but instead the maximum value for the column. Fixed in 4.0.11. * `DELETE FROM heap_table' without a `WHERE' doesn't work on a locked HEAP table. Errors in 4.0 Fixed in a Later MySQL Version ............................................ The following known errors/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' defines the type, `max_length' and `NULL' properties for the resulting columns. In MySQL 4.1.1, these properties are defined from the combination of all `UNION' parts. Open Bugs / Design Deficiencies in MySQL ........................................ The following problems are known and fixing them is a high priority: * You cannot mix `UNION ALL' and `UNION DISTINCT' in the same query. If you use `ALL' for one `UNION' then 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 fixed 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 will be 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'. When this happens you will see errors like the following in the MySQL error file: 001207 22:07:56 bdb: log_flush: LSN past current end-of-log * MySQL accepts parentheses in the `FROM' part, but silently ignores them. The reason for not giving an error is that many clients that automatically generate queries add parentheses in the `FROM' part even where they are not needed. * Concatenating many `RIGHT JOINS' or combining `LEFT' and `RIGHT' join in the same query may not give a correct answer as MySQL only generates `NULL' rows for the table preceding a `LEFT' or before a `RIGHT' join. This will be fixed in 5.0 at the same time we add support for parentheses in the `FROM' part. * Don't execute `ALTER TABLE' on a `BDB' table on which you are running multi-statement transactions until all those transactions complete. (The transaction will probably be ignored.) * `ANALYZE TABLE', `OPTIMIZE TABLE', and `REPAIR TABLE' may cause problems on tables for which you are using `INSERT DELAYED'. * Doing a `LOCK TABLE ...' and `FLUSH TABLES ...' doesn't guarantee that there isn't a half-finished transaction in progress on the table. * BDB tables are a bit slow to open. If you have many BDB tables in a database, it will take a long time to use the `mysql' client on the database if you are not using the `-A' option or if you are using `rehash'. This is especially notable when you have a big table cache. * Replication uses query-level logging: the master writes the executed queries to the binary log. This is a very fast, compact, and efficient logging method that works perfectly in most cases. Though we have never heard of it actually occurring, it is theoretically possible for the data on the master and slave to become different if a query is designed in such a way that the data modification is non-deterministic, that is, left to the will of the query optimizer (which generally is not a good practice, 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 (one can run with different storage engines on the slave and master: for example InnoDB on the master and MyISAM on the slave, if the slave has less available disk space). - The MySQL buffers' sizes (`key_buffer_size' etc) are different on the master and slave. - The master and slave run different MySQL versions, and the 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/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: * `mysqlbinlog' will not delete temporary files left after a `LOAD DATA INFILE' command. *Note mysqlbinlog::. * You cannot rename temporary tables. * When using `RPAD' function, or any other string function that ends up adding blanks to the right, in a query that has to use temporary table to be resolved, then all resulting strings will be RTRIM'ed. This is an example of the query: `SELECT RPAD(t1.field1, 50, ' ') AS f2, RPAD(t2.field2, 50, ' ') AS f1 FROM table1 as t1 LEFT JOIN table2 AS t2 ON t1.record=t2.joinID ORDER BY t2.record;' Final result of this bug is that use will not be able to get blanks on the right side of the resulting field. The above behavior exists in all versions of MySQL. The reason for this is due to the fact that HEAP tables, which are used first for temporary tables, are not capable of handling VARCHAR columns. This behavior will be fixed in one of the 4.1 series releases. * Because of how table definitions files are stored one can't use character 255 (`CHAR(255)') in table names, column names or enums. This is scheduled to be fixed in version 5.1 when we have new table definition format files. * When using `SET CHARACTER SET', one can't use translated characters in database, table, and column names. * One can't use `_' or `%' with `ESCAPE' in `LIKE ... ESCAPE'. * If you have a `DECIMAL' column with a number stored in different formats (+01.00, 1.00, 01.00), `GROUP BY' may regard each value as a different value. * `DELETE FROM merge_table' used without a `WHERE' will only clear the mapping for the table, not delete everything in the mapped tables. * You cannot build the server in another directory when using MIT-pthreads. Because this requires changes to MIT-pthreads, we are not likely to fix this. *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 (default 1024) are used when comparing `BLOB' values in these cases. This can be changed with the `-O max_sort_length' option to `mysqld'. A workaround for most cases is to use a substring: `SELECT DISTINCT LEFT(blob,2048) FROM tbl_name'. * Calculation is done with `BIGINT' or `DOUBLE' (both are normally 64 bits long). It depends on the function which precision one gets. The general rule is that bit functions are done with `BIGINT' precision, `IF', and `ELT()' with `BIGINT' or `DOUBLE' precision and the rest with `DOUBLE' precision. One should try to avoid using unsigned long long values if they resolve to be bigger than 63 bits (9223372036854775807) for anything else than bit fields. MySQL Server 4.0 has better `BIGINT' handling than 3.23. * All string columns, except `BLOB' and `TEXT' columns, automatically have all trailing spaces removed when retrieved. For `CHAR' types this is okay, and may be regarded as a feature according to SQL-92. The bug is that in MySQL Server, `VARCHAR' columns are treated the same way. * You can only have up to 255 `ENUM' and `SET' columns in one table. * In `MIN()', `MAX()' and other aggregate functions, MySQL currently compares `ENUM' and `SET' columns by their string value rather than by the string's relative position in the set. * `mysqld_safe' redirects all messages from `mysqld' to the `mysqld' log. One problem with this is that if you execute `mysqladmin refresh' to close and reopen the log, `stdout' and `stderr' are still redirected to the old log. If you use `--log' extensively, you should edit `mysqld_safe' to log to `'hostname'.err' instead of `'hostname'.log' so you can easily reclaim the space for the old log by deleting the old one and executing `mysqladmin refresh'. * In the `UPDATE' statement, columns are updated from left to right. If you refer to an updated column, you will get the updated value instead of the original value. For example: mysql> UPDATE tbl_name SET KEY=KEY+1,KEY=KEY+1; This will update `KEY' with `2' instead of with `1'. * You can refer to multiple temporary tables in the same query, but you cannot refer to any given temporary table more than once. For example, the following doesn't work: mysql> SELECT * FROM temporary_table, temporary_table AS t2; * `RENAME' doesn't work with `TEMPORARY' tables or tables used in a `MERGE' table. * The 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 hidden `id' column may differ). Note that this happens only for queries where you don't have the ORDER BY columns in the result, something that you are not allowed to do in SQL-92. * Because MySQL Server allows you to work with table types that don't support transactions, and thus can't `rollback' data, some things behave a little differently in MySQL Server than in other SQL servers. This is just to ensure that MySQL Server never needs to do a rollback for an SQL command. This may be a little awkward at times 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 will instead store the smallest or biggest possible value in the column. - If you try to store a string that doesn't start with a number into a numerical column, MySQL Server will store 0 into it. - If you try to store `NULL' into a column that doesn't take `NULL' values, MySQL Server will store 0 or `''' (empty string) in it instead. (This 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 SQL server job to validate date. If MySQL can store a date and retrieve exactly the same date, then MySQL will store the date. If the date is totally wrong (outside the server's ability to store it), then the special date value 0000-00-00 will be stored in the column. - If you set an `ENUM' column to an unsupported value, it will be set to the error value `empty string', with numeric value 0. - If you set a `SET' column to an unsupported value, the value will be ignored. * If you execute a `PROCEDURE' on a query that returns an empty set, in some cases the `PROCEDURE' will not transform the columns. * Creation of a table of type `MERGE' doesn't check if the underlying tables are of compatible types. * MySQL Server can't yet handle `NaN', `-Inf', and `Inf' values in double. Using these will cause problems when trying to export and import data. We should as an intermediate solution change `NaN' to `NULL' (if possible) and `-Inf' and `Inf' to the minimum respective maximum possible `double' value. * If you use `ALTER TABLE' to first add a `UNIQUE' index to a table used in a `MERGE' table and then use `ALTER TABLE' to add a normal index on the `MERGE' table, the key order will be different for the tables if there was an old key that was not unique in the table. This is because `ALTER TABLE' puts `UNIQUE' keys before normal keys to be able to detect duplicate keys as early as possible. The following are known bugs in earlier versions of MySQL: * You can get a hung thread if you do a `DROP TABLE' on a table that is one among many tables that is locked with `LOCK TABLES'. * In the following case you can get a core dump: - Delayed insert handler has pending inserts to a table. - `LOCK table' with `WRITE'. - `FLUSH TABLES'. * Before MySQL Server Version 3.23.2 an `UPDATE' that updated a key with a `WHERE' on the same key may have failed because the key was used to search for records and the same row may have been found multiple times: UPDATE tbl_name SET KEY=KEY+1 WHERE KEY > 100; A workaround is to use: mysql> UPDATE tbl_name SET KEY=KEY+1 WHERE KEY+0 > 100; This will work because MySQL Server will not use an index on expressions in the `WHERE' clause. * Before MySQL Server Version 3.23, all numeric types were treated as fixed-point fields. That means you had to specify how many decimals a floating-point field shall have. All results were returned with the correct number of decimals. For platform-specific bugs, see the sections about compiling and porting. *Note Installing source::. *Note Porting::. Installing MySQL **************** This chapter describes how to obtain and install MySQL: * For a list of sites from which you can obtain MySQL, see *Note Getting MySQL: Getting MySQL. * To see which platforms are supported, see *Note Which OS::. 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. * Several versions of MySQL are available in both binary and source distributions. We also provide public access to our current source tree for those who want to see our most recent developments and help us test new code. To determine which version and type of distribution you should use, see *Note Which version::. When in doubt, use a binary distribution. * Installation instructions for binary and source distributions are described in *Note Installing binary::, and *Note Installing source::. Each set of instructions includes a section on system-specific problems you may run into. * For post-installation procedures, see *Note Post-installation::. These procedures apply whether you install MySQL using a binary or source distribution. Quick Standard MySQL Installation ================================= This chapter covers the installation of MySQL on platforms where we offer packages using the native packaging format of the respective platform. However, binary distributions of MySQL are available for many other platforms as well, see *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. 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. *Note Windows source build::. Generally speaking, you should use the binary distribution. It's simpler, and you need no additional tools to get MySQL up and running. Windows System Requirements ........................... To run MySQL on Windows, you will need the following: * A 32-bit Windows operating system such as 9x, Me, NT, 2000, or XP. The NT family (Windows NT, 2000, and XP) permits you to run the MySQL server as a service. *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 will 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. 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. The `mysqld-nt' or `mysqld-max-nt' server support named pipe connections. If you use either of these servers, named pipe use is subject to these conditions: * The server must be run on a version of Windows that supports named pipes (NT, 2000, XP). * Starting from 3.23.50, named pipes are enabled only if you start the server with the `--enable-named-pipe' option. * These servers can be run on Windows 98 or Me, but only if TCP/IP is installed; named pipe connections cannot be used. * On Windows 95, these servers cannot be used. 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: shell> mysqld --console For servers that include `InnoDB' support, you should see the following messages as the server starts up: InnoDB: The first specified datafile c:\ibdata\ibdata1 did not exist: InnoDB: a new database to be created! InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200 InnoDB: Database physically writes the file full: wait... InnoDB: Log file c:\iblogs\ib_logfile0 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile0 size to 31457280 InnoDB: Log file c:\iblogs\ib_logfile1 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280 InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280 InnoDB: Doublewrite buffer not found: creating new InnoDB: Doublewrite buffer created InnoDB: creating foreign key constraint system tables InnoDB: foreign key constraint system tables created 011024 10:58:25 InnoDB: Started When the server finishes its startup sequence, you should see something like this, which indicates that the server is ready to service client connections:: mysqld: ready for connections Version: '4.0.14-log' socket: '' port: 3306 The server will continue to write to the console any further diagnostic output it produces. You can open a new console window in which to run client programs. If you omit the `--console' option, the server writes diagnostic output to the error log in the data directory. The error log is the file with the `.err' extension. 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 up, 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 if the server wrote any messages there to indicate the cause of the problem. The error log is located in the `C:\mysql\data' directory. It is the file with a suffix of `.err'. You can also try to start the server as `mysqld --console'; in this case, you may get some useful information on the screen that may help solve the problem. The last option is to start `mysqld' with `--standalone --debug'. In this case `mysqld' will write a log file `C:\mysqld.trace' that should contain the reason why `mysqld' doesn't start. *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 up. The rules that determine the service name and option files the server uses are as follows: * If you specify no service name, the server uses the default service name of `MySQL' and the server reads options from the `[mysqld]' group in the standard option files. * If you specify a service name after the `--install' option, the server ignores the `[mysqld]' option group and instead reads options from the group that has the same name as the service. The server reads options from the standard option files. * If you specify a `--defaults-file' option after the service name, the server ignores the standard option files and reads options only from the `[mysqld]' group of the named file. *Note:* Prior to MySQL 4.0.17, a server installed as a Windows service has problems starting if its pathname or the service name contains spaces. For this reason, avoid installing MySQL in a directory such as `C:\Program Files' or using a service name containing spaces. In the usual case that you install the server with `--install' but no service name, the server is installed with a service name of `MySQL'. As a more complex example, consider the following command: shell> C:\mysql\bin\mysqld --install mysql --defaults-file=C:\my-opts.cnf Here, a service name is given after the `--install' option. If no `--defaults-file' option had been given, this command would have the effect of causing the server to read the `[mysql]' group from the standard option files. (This would be a bad idea, because that option group is for use by the `mysql' client program.) However, because the `--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 if the server wrote any messages there to indicate the cause of the problem. The error log is located in the `C:\mysql\data' directory. It is the file with a suffix of `.err'. When `mysqld' is running as a service, it can be stopped by using the `Services' utility, the command `NET STOP MYSQL', or the command `mysqladmin shutdown'. If the service is running when Windows shuts down, Windows will stop the server automatically. From MySQL version 3.23.44, you have the choice of installing the server as a `Manual' service if you don't wish the service to be started automatically during the boot process. To do this, use the `--install-manual' option rather than the `--install' option: shell> C:\mysql\bin\mysqld --install-manual To remove a server that is installed as a service, first stop it if it is running. Then use the `--remove' option to remove it: shell> mysqld --remove One problem with automatic MySQL service shutdown is that, for MySQL versions older than 3.23.49, Windows waited only for a few seconds for the shutdown to complete, then killed the database server process if the time limit was exceeded. This had the potential to cause problems. (For example, the `InnoDB' storage engine had to perform crash recovery at the next startup.) Starting from MySQL version 3.23.49, Windows waits longer for the MySQL server shutdown to complete. If you notice this still is not enough for your installation, it is safest not to run the MySQL server as a service. Instead, start it from the command-line prompt, and stop it with `mysqladmin shutdown'. The change to tell Windows to wait longer when stopping the MySQL server works for Windows 2000 and XP, but not for Windows NT. On NT, Windows waits only 20 seconds for a service to shut down, and after that kills the service process. You can increase this default by opening the Registry Editor `\winnt\system32\regedt32.exe' and editing the value of `WaitToKillServiceTimeout' at `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control' in the Registry tree. Specify the new larger value in milliseconds (for example, the value 120000 tells Windows NT to wait up to 120 seconds). If you don't want to start `mysqld' as a service, you can start it from the command line the same way as for versions of Windows that are not based on NT. For instructions, see *Note Win95 start::. Running MySQL on Windows ........................ MySQL supports TCP/IP on all Windows platforms. The `mysqld-nt' and `mysql-max-nt' servers support named pipes on NT, 2000, and XP. However, the default is to use TCP/IP regardless of the platform: * Named pipes are actually slower than TCP/IP in many Windows configurations. * Some users have experienced problems shutting down the MySQL server when named pipes are used. Starting from 3.23.50, named pipes are enabled for `mysqld-nt' and `mysql-max-nt' only if they are started with the `--enable-named-pipe' option. You can force a MySQL client to use named pipes by specifying the `--pipe' option or by specifying `.' (period) as the host name. Use the `--socket' option to specify the name of the pipe. In MySQL 4.1, you should use the `--protocol=PIPE' option. You can test whether the MySQL server is working by executing any of the following commands: C:\> C:\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 answer to connections on Windows 9x/Me, there is probably a problem with your DNS. In this case, start `mysqld' with the `--skip-name-resolve' option and use only `localhost' and IP numbers in the `Host' column of the MySQL grant tables. There are two versions of the MySQL command-line tool: *Binary* *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). The default privileges on Windows give all local users full privileges to all databases without specifying a password. To make MySQL more secure, you should set a password for all users and remove the row in the `mysql.user' table that has `Host='localhost'' and `User='''. You should also add a password for the `root' user. The following example starts by removing the anonymous user that has all privileges, then sets a `root' user password: C:\> C:\mysql\bin\mysql mysql mysql> DELETE FROM user WHERE Host='localhost' AND User=''; mysql> FLUSH PRIVILEGES; mysql> QUIT C:\> C:\mysql\bin\mysqladmin -u root password your_password After you've set the password, if you want to shut down the `mysqld' server, you can do so using this command: C:\> mysqladmin --user=root --password=your_password shutdown If you are using a server from an old Windows shareware distribution of MySQL Version 3.21, the `mysqladmin' command to set the password will fail with an error: `parse error near 'SET password''. The solution to this problem is to upgrade to a newer version of MySQL. With the current MySQL versions you can easily add new users and change privileges with `GRANT' and `REVOKE' commands. *Note `GRANT': GRANT. 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 `\' directory character* Pathname components in Windows 95 are separated by the `\' character, which is also the escape character in MySQL. If you are using `LOAD DATA INFILE' or `SELECT ... INTO OUTFILE', use Unix style filenames with `/' characters: mysql> LOAD DATA INFILE "C:/tmp/skr.txt" INTO TABLE skr; mysql> SELECT * INTO OUTFILE 'C:/tmp/skr.txt' FROM skr; Alternatively, you must double the `\' character: mysql> LOAD DATA INFILE "C:\\tmp\\skr.txt" INTO TABLE skr; mysql> SELECT * INTO OUTFILE 'C:\\tmp\\skr.txt' FROM skr; *Problems with pipes.* Pipes doesn't work reliably in the Windows command-line prompt. If the pipe includes the character `^Z' / `CHAR(24)', Windows will think it has encountered end-of-file and abort the program. This is mainly a problem when you try to apply a binary log as follows: mysqlbinlog binary-log-name | mysql --user=root If you get a problem applying the log and suspect it's because of an `^Z' / `CHAR(24)' character you can use the following workaround: mysqlbinlog binary-log-file --result-file=/tmp/bin.sql mysql --user=root --execute "source /tmp/bin.sql" The latter command also can be used to reliably read in any SQL file that may contain binary data. *`Can't open named pipe' error* If you use a MySQL Version 3.22 server on NT with the newest MySQL client programs, you will get the following error: error 2017: can't open named pipe to host: . pipe... This is because the release version of MySQL uses named pipes on NT by default. You can avoid this error by using the `--host=localhost' option to the new MySQL clients or create an option file `C:\my.cnf' that contains the following information: [client] host = localhost Starting from 3.23.50, named pipes are enabled only if `mysqld-nt' or `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 host name 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 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 that this package was called `MySQL-VERSION.i386.rpm' before MySQL 4.0.10. * `MySQL-Max-VERSION.i386.rpm' The MySQL Max server. This server has additional capabilities that the one in the `MySQL-server' RPM does not. You must install the `MySQL-server' RPM first, because the `MySQL-Max' RPM depends on it. * `MySQL-client-VERSION.i386.rpm' The standard MySQL client programs. You probably always want to install this package. * `MySQL-bench-VERSION.i386.rpm' Tests and benchmarks. Requires Perl and the `DBD::mysql' module. * `MySQL-devel-VERSION.i386.rpm' The libraries and include files that are needed if you want to compile other MySQL clients, such as the Perl modules. * `MySQL-shared-VERSION.i386.rpm' This package contains the shared libraries (`libmysqlclient.so*') that certain languages and applications need to dynamically load and use MySQL. * `MySQL-shared-compat-VERSION.i386.rpm' This package includes the shared libraries for both MySQL 3.23 and MySQL 4.0. Install this package instead of `MySQL-shared', if you have applications installed that are dynamically linked against MySQL 3.23 but you want to upgrade to MySQL 4.0 without breaking the library dependencies. This package is available since MySQL 4.0.13. * `MySQL-embedded-VERSION.i386.rpm' The embedded MySQL server library (from MySQL 4.0). * `MySQL-VERSION.src.rpm' This contains the source code for all of the previous packages. It can also be used to rebuild the RPMs on other architectures (for example, Alpha or SPARC). To see all files in an RPM package (for example, a `MySQL-server' RPM), run: shell> rpm -qpl MySQL-server-VERSION.i386.rpm To perform a standard minimal installation, run: shell> rpm -i MySQL-server-VERSION.i386.rpm MySQL-client-VERSION.i386.rpm To install just the client package, run: shell> rpm -i MySQL-client-VERSION.i386.rpm RPM provides a feature to verify the integrity and authenticity of packages before installing them. If you would like to learn more about this feature please see *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' daemon 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 `PKG' binary package instead of the binary tarball distribution. Please note that older versions of Mac OS X (for example, 10.1.x) are not supported by this package. The package is located inside a disk image (`.dmg') file, that you first need to mount by double-clicking its icon in the Finder. It should then mount the image and display its contents. *NOTE*: Before proceeding with the installation, be sure to shut down all running MySQL server instances by either using the MySQL Manager Application (on Mac OS X Server) or via `mysqladmin shutdown' on the command line. To actually install the MySQL PKG, double click on the package icon. This launches the Mac OS Package Installer, which will guide you through the installation of MySQL. The Mac OS X PKG of MySQL will install itself into `/usr/local/mysql-' 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: * Mac OS X Server 10.2-10.2.2 come with MySQL 3.23.51 installed * Mac OS X Server 10.2.3-10.2.6 ship with MySQL 3.23.53 * Mac OS X Server 10.3 ships with MySQL 4.0.14 * Mac OS X Server 10.3.2 ships with MySQL 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 the pre-installed version of MySQL on Mac OS X Server is started with the command `safe_mysqld' instead of `mysqld_safe'. If you previously used Marc Liyanage's MySQL packages for Mac OS X from `http://www.entropy.ch', you can simply follow the update instructions for packages using the binary installation layout as given on his pages. If you are upgrading from Marc's 3.23.xx versions or from the Mac OS X Server version of MySQL to the official MySQL PKG, you also need to convert the existing MySQL privilege tables to the current format, because some new security privileges have been added. *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 this only has to be done once! There is no need to install the Startup Item every time you upgrade the MySQL package. Due to a bug in the Mac OS X package installer, you may sometimes see the error message `You cannot install this software on this disk. (null)' in the destination disk selection dialogue. If this error occurs, simply click the `Go Back' button once to return to the previous screen. Now click `Continue' to advance to the destination disk selection again - you should now be able to choose the destination disk correctly. We have reported this bug to Apple and they are investigating this problem. The Startup Item will be installed into `/Library/StartupItems/MySQL'. It adds a variable `MYSQLCOM=-YES-' to the system configuration file `/etc/hostconfig'. If you would like to disable the automatic startup of MySQL, simply change this variable to `MYSQLCOM=-NO-'. On Mac OS X Server, the Startup Item installation script will automatically disable the startup of the default MySQL installation by changing the variable `MYSQL' in `/etc/hostconfig' to `MYSQL=-NO-'. This is to avoid conflicts on bootup. However, it does not shut down an already running MySQL server. After the installation, you can start up MySQL by running the following commands in a terminal window. Please note that you need to have administrator privileges to perform this task. If you have installed the Startup Item: shell> sudo /Library/StartupItems/MySQL/MySQL start (Enter your password, if necessary) (Press Control-D or enter "exit" to exit the shell) If you don't use the Startup Item, enter the following command sequence: shell> 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 installed MySQL for the first time, *please remember to set a password for the MySQL `root' user!* This is done with the following two commands: /usr/local/mysql/bin/mysqladmin -u root password /usr/local/mysql/bin/mysqladmin -u root -h `hostname` password Please make sure that the `hostname' command in the second line is enclosed by *backticks* (`), so the shell can replace it with the output of this command (the host name of this system)! You might want to also add aliases to your shell's resource file to access `mysql' and `mysqladmin' from the command line: alias mysql '/usr/local/mysql/bin/mysql' alias mysqladmin '/usr/local/mysql/bin/mysqladmin' Alternatively, you could simply add `/usr/local/mysql/bin' to your `PATH' environment variable, for example, by adding the following to `$HOME/.tcshrc': setenv PATH ${PATH}:/usr/local/mysql/bin Please note that installing a new MySQL PKG does not remove the directory of an older installation. Unfortunately, the Mac OS X Installer does not yet offer the functionality required to properly upgrade previously installed packages. After you have copied over the MySQL database files from the previous version and have successfully started the new version, you should consider removing the old installation files to save disk space. Additionally, you should also remove older versions of the Package Receipt directories located in `/Library/Receipts/mysql-.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: 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. General Installation Issues =========================== 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 two means of integrity checking: `MD5 checksums' and cryptographic signatures using `GnuPG', the `GNU Privacy Guard'. Verifying the `MD5 Checksum' ---------------------------- After you have downloaded the package, you should check, if the MD5 checksum matches the one provided on the MySQL download pages. Each package has an individual checksum, that you can verify with the following command: shell> md5sum 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 ' instead. A DOS/Windows implementation of the `md5' command is available from `http://www.fourmilab.ch/md5/'. Example: shell> md5sum mysql-standard-4.0.10-gamma-pc-linux-i686.tar.gz 155836a7ed8c93aee6728a827a6aa153 mysql-standard-4.0.10-gamma-pc-linux-i686.tar.gz You should check, if the resulting checksum matches the one printed on the download page right below the respective package. Signature Checking Using `GnuPG' -------------------------------- A more reliable method of verifying the integrity of a package is using cryptographic signatures. MySQL AB uses the `GNU Privacy Guard' (`GnuPG'), an `Open Source' alternative to the very well-known `Pretty Good Privacy' (`PGP') by Phil Zimmermann. See `http://www.gnupg.org/' and `http://www.openpgp.org/' for more information about `OpenPGP'/`GnuPG' and how to obtain and install `GnuPG' on your system. Most Linux distributions already ship with `GnuPG' installed by default. Beginning with MySQL 4.0.10 (February 2003), MySQL AB has started signing their downloadable packages with `GnuPG'. Cryptographic signatures are a much more reliable method of verifying the integrity and authenticity of a file. To verify the signature for a specific package, you first need to obtain a copy of MySQL AB's public GPG build key . 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, now download your desired MySQL package and the corresponding signature, which is also available from the download page. The signature has the file name extension `.asc'. For example, the signature for `mysql-standard-4.0.10-gamma-pc-linux-i686.tar.gz' would be `mysql-standard-4.0.10-gamma-pc-linux-i686.tar.gz.asc'. Make sure that both files are stored in the same directory and then run the following command to verify the signature for this file: shell> gpg --verify .asc Example: shell> gpg --verify mysql-standard-4.0.10-gamma-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 them by running the following command: shell> rpm --checksig .rpm Example: shell> rpm --checksig MySQL-server-4.0.10-0.i386.rpm MySQL-server-4.0.10-0.i386.rpm: md5 gpg OK *Note:* If you are using RPM 4.1 and it complains about `(GPG) NOT OK (MISSING KEYS: GPG#5072e1f5)' (even though you have imported it into your GPG public keyring), you need to import the key into the RPM keyring first. RPM 4.1 no longer uses your GPG keyring (and GPG itself), but rather maintains its own keyring (because it's a system wide application and the GPG public keyring is user-specific file). To import the MySQL public key into the RPM keyring, please use the following command: shell> rpm --import Example: shell> rpm --import mysql_pubkey.asc In case you notice that the `MD5 checksum' or `GPG' signatures do not match, first try to download the respective package one more time, maybe from another mirror site. If you repeatedly cannot successfully verify the integrity of the package, please notify us about such incidents including the full package name and the download site you have been using at or . Operating Systems Supported by MySQL ------------------------------------ We use GNU Autoconf, so it is possible to port MySQL to all modern systems with working Posix threads and a C++ compiler. (To compile only the client code, a C++ compiler is required but not threads.) We use and develop the software ourselves primarily on Linux (SuSE and Red Hat), FreeBSD and Sun Solaris (Versions 8 and 9). Note that for many operating systems, the native thread support works only in the latest versions. MySQL has been reported to compile successfully on the following operating system/thread package combinations: * AIX 4.x, 5.x with native threads. *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::. * SCO OpenServer with a recent port of the FSU Pthreads package. *Note SCO::. * SCO UnixWare 7.1.x. *Note SCO UnixWare::. * 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::. * 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::. Note that not all platforms are suited equally well for running MySQL. How well a certain platform is suited for a high-load mission-critical MySQL server is determined by the following factors: * General stability of the thread library. A platform may have excellent reputation otherwise, but if the thread library is unstable in the code that is called by MySQL, even if everything else is perfect, MySQL will be only as stable as the thread library. * The ability of the kernel and/or thread library to take advantage of *SMP* on multi-processor systems. In other words, when a process creates a thread, it should be possible for that thread to run on a different CPU than the original process. * The ability of the kernel and/or the thread library to run many threads which acquire/release a mutex over a short critical region frequently without excessive context switches. In other words, if the implementation of `pthread_mutex_lock()' is too anxious to yield CPU time, this will hurt MySQL tremendously. If this issue is not taken care of, adding extra CPUs will actually make MySQL slower. * General filesystem stability/performance. * Ability of the filesystem to deal with large files at all and deal with them efficiently, if your tables are big. * Our level of expertise here at MySQL AB with the platform. If we know a platform well, we introduce platform-specific optimizations/fixes enabled at compile time. We can also provide advice on configuring your system optimally for MySQL. * The amount of testing of similar configurations we have done internally. * The number of users that have successfully run MySQL on that platform in similar configurations. If this number is high, the chances of hitting some platform-specific surprises are much smaller. Based on the preceding criteria, the best platforms for running MySQL at this point are x86 with SuSE Linux 8.2, 2.4 kernel, and ReiserFS (or any similar Linux distribution) and SPARC with Solaris (2.7-9). FreeBSD comes third, but we really hope it will join the top club once the thread library is improved. We also hope that at some point we will be able to include all other platforms on which MySQL compiles, runs okay, but not quite with the same level of stability and performance, into the top category. This will require some effort on our part in cooperation with the developers of the OS/library components MySQL depends upon. If you are interested in making one of those components better, are in a position to influence their development, and need more detailed instructions on what MySQL needs to run better, send an email to the MySQL internals mailing list. *Note Mailing-list::. Please note that the preceding comparison is not to say that one OS is better or worse than the other in general. We are talking about choosing a particular OS for a dedicated purpose--running MySQL, and compare platforms in that regard only. With this in mind, the result of this comparison would be different if we included more issues into it. And in some cases, the reason one OS is better than the other could simply be that we have put forth more effort into testing on and optimizing for that particular platform. We are just stating our observations to help you decide on which platform to use MySQL on in your setup. Which MySQL Version to Use -------------------------- The first decision to make is whether you want to use the latest development release or the last production (stable) release: * Normally, if you are beginning to use MySQL for the first time or trying to port it to some system for which there is no binary distribution, we recommend going with the production release (currently version 4.0). Note that all MySQL releases are checked with the MySQL benchmarks and an extensive test suite before each release (even the development releases). * Otherwise, if you are running an old system and want to upgrade, but don't want to take chances with a non-seamless upgrade, you should upgrade to the latest in the same branch you are using (where only the last version number is newer than yours). We have tried to fix only fatal bugs and make small, relatively safe changes to that version. The second decision to make is whether you want to use a source distribution or a binary distribution. In most cases you should probably use a binary distribution, if one exists for your platform, as this generally will be easier to install than a source distribution. In the following cases you probably will be better off with a source installation: * If you want to install MySQL at some explicit location. (The standard binary distributions are "ready to run" at any place, but you may want to get even more flexibility). * To be able to satisfy different user requirements, we are providing two different binary versions: one compiled with the non-transactional storage engines (a small, fast binary), and one configured with the most important extended options like transaction-safe tables. Both versions are compiled from the same source distribution. All native `MySQL' clients can connect to both MySQL versions. The extended MySQL binary distribution is marked with the `-max' suffix and is configured with the same options as `mysqld-max'. *Note `mysqld-max': mysqld-max. If you want to use the `MySQL-Max' RPM, you must first install the standard `MySQL-server' RPM. * If you want to configure `mysqld' with some extra features that are not in the standard binary distributions. Here is a list of the most common extra options that you may want to use: * `--with-innodb' (default for MySQL 4.0 and onwards) * `--with-berkeley-db' (not available on all platforms) * `--with-raid' * `--with-libwrap' * `--with-named-z-libs' (This is done for some of the binaries) * `--with-debug[=full]' * The default binary distribution is normally compiled with support for all character sets and should work on a variety of processors from the same processor family. If you want a faster MySQL server you may want to recompile it with support for only the character sets you need, use a better compiler (like `pgcc'), or use compiler options that are better optimized for your processor. * If you have found a bug and reported it to the MySQL development team you will probably receive a patch that you need to apply to the source distribution to get the bug fixed. * If you want to read (and/or modify) the C and C++ code that makes up MySQL, you should get a source distribution. The source code is always the ultimate manual. Source distributions also contain more tests and examples than binary distributions. The MySQL naming scheme uses release numbers that consist of three numbers and a suffix. For example, a release name like `mysql-4.1.0-alpha' is interpreted like this: * The first number (`4') is the major version and also describes the file format. All Version 4 releases have the same file format. * The second number (`1') is the release level. * The third number (`0') is the version number within the release level. This is incremented for each new distribution. Usually you want the latest version for the release level you have chosen. * The suffix (`alpha') indicates the stability level of the release. The possible suffixes are: - `alpha' indicates that the release contains some large section of new code that hasn't been 100% tested. Known bugs (usually there are none) should be documented in the News section. *Note News::. There are also new commands and extensions in most alpha releases. Active development that may involve major code changes can occur on an alpha release, but everything will be tested before doing a release. There should be no known bugs in any MySQL release. - `beta' means that all new code has been tested. No major new features that could cause corruption on old code are added. There should be no known bugs. A version changes from alpha to beta when there haven't been any reported fatal bugs within an alpha version for at least a month and we don't plan to add any features that could make any old command more unreliable. - `gamma' is a beta that has been around a while and seems to work fine. Only minor fixes are added. This is what many other companies call a release. - If there is no suffix, it means that the version has been run for a while at many different sites with no reports of bugs other than platform-specific bugs. Only critical bug fixes are applied to the release. This is what we call a production (stable) release. In the MySQL development process, multiple versions co-exist and are at a different stage. Naturally, relevant bugfixes from an earlier series also propagate upward. * For the old stable/production series `3.23', new versions are only released for critical bugs. * The current series `4.0') is stable/production quality, with new versions released for bugfixes. No new features are added that could influence the code stability. * In the alpha branch `4.1' major new features are added. Sources and binaries are available for use and testing on development systems. * The development branch `5.0' is only available from the BitKeeper tree. All versions of MySQL are run through our standard tests and benchmarks to ensure that they are relatively safe to use. Because the standard tests are extended over time to check for all previously found bugs, the test suite keeps getting better. Note that all releases have been tested at least with: An internal test suite The `mysql-test' directory contains an extensive set of test cases. We run these tests for virtually every server binary. The MySQL benchmark suite This 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 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. Installation Layouts -------------------- This section describes the default layout of the directories created by installing binary and source distributions. A binary distribution is installed by unpacking it at the installation location you choose (typically `/usr/local/mysql') and creates the following directories in that location: *Directory* *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 `/usr/local/bin' directory rather than in `/usr/local/mysql/scripts'. * The header file and library directories are `include/mysql' and `lib/mysql' rather than `include' and `lib'. You can create your own binary installation from a compiled source distribution by executing the script `scripts/make_binary_distribution'. How and When Updates Are Released --------------------------------- MySQL is evolving quite rapidly here at MySQL AB and we want to share this with other MySQL users. We try to make a release when we have very useful features that others seem to have a need for. 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: * For each minor update, the last number in the version string is incremented. When there are major new features or minor incompatibilities with previous versions, the second number in the version string is incremented. When the file format changes, the first number is increased. * Production (stable-tested) releases are meant to appear about 1-2 times a year, but if small bugs are found, a release with only bug fixes will be released. * Working releases/bug fixes to old releases are meant to appear about every 4-8 weeks. * Binary distributions for some platforms will be made by us for major releases. Other people may make binary distributions for other systems but probably less frequently. * We usually make patches available as soon as we have located and fixed small bugs. They usually are immediately available from our public BitKeeper repositories. They will also be included in the next release. * Non-critical but annoying bugs will be added to the MySQL source repository and they will be fixed in the next release. * If there is, by any chance, a fatal bug in a release we will make a new release as soon as possible. We would like other companies to do this, too. The current production release is Version 4.0; we have already moved active development to Version 4.1 and 5.0. Bugs will still be fixed in the 4.0 version, and critical bugs also in the 3.23 series. We don't believe in a complete freeze, as this also leaves out bug fixes and things that "must be done." "Somewhat frozen" means that we may add small things that "almost surely will not affect anything that's already working." MySQL uses a slightly different naming scheme from most other products. In general it's relatively safe to use any version that has been out for a couple of weeks without being replaced with a new version. *Note Which version::. Release Philosophy - No Known Bugs in Releases ---------------------------------------------- We put a lot of time and effort into making our releases bug free. To our knowledge, we have not released a single MySQL version with any _known_ 'fatal' repeatable bugs. A fatal bug is something that crashes MySQL under normal usage, gives wrong answers for normal queries, or has a security problem. We have documented all open problems, bugs, and issues that are dependent on design decisions. *Note Bugs::. Our aim is to fix everything that is fixable, but without risking making a stable MySQL version less stable. In certain cases, this means we can fix an issue in the development versions, but not in the stable (production) version. Naturally, we document such issues so that users are aware. Here is a description of how our build process works: * We monitor bugs from our customer support list, the MySQL external mailing lists and the bugs database at `http://bugs.mysql.com/'. * All reported bugs for live versions are entered into the bugs database. * When we fix a bug, we always try to make a test case of it and include this into our test system to ensure that the bug will never come back. (About 90% of all fixed bugs have a test case.) * We also create test cases for all new features we add to MySQL. * Before we start to build a new MySQL release, we ensure that all reported repeatable bugs for the MySQL version (3.23.x, 4.0.x, etc) are fixed. If something is impossible to fix (because some internal design decision in MySQL) we document this in the manual. *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. * If we, during the build and test process (which takes 2-3 days), receive a report regarding a fatal bug (for example, one that causes a core dump), we fix this and restart the build process. * After publishing the binaries on `http://www.mysql.com/', we send out an announce email on the `mysql' and `announce' mailing lists. *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 by means of compressed tar archives (`.tar.gz'). These distributions are generated using the script `Build-tools/Do-compile' which compiles the source code and creates the binary `tar.gz' archive using `scripts/make_binary_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 64bit with `gcc' 3.2 `CC=gcc CFLAGS="-O3 -m64 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -m64 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --enable-assembler --with-named-z-libs=no --with-named-curses-libs=-lcurses --disable-shared' Sun Solaris 9 sparc with `gcc' 2.95.3 `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-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 only provide 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 5.0 sparc64 with `gcc' 3.2.1 `CFLAGS=-DHAVE_BROKEN_REALPATH ./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared --with-innodb' The following compile options have been used for binary packages MySQL AB used to provide in the past. These binaries are no longer being updated, but the compile options are kept here for reference purposes. Linux 2.2.xx sparc with `egcs' 1.1.2 `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-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 s mailing list. *Note Mailing-list::. RPM distributions prior to MySQL Version 3.22 are user-contributed. Beginning with Version 3.22, the RPMs are generated by us at MySQL AB. If you want to compile a debug version of MySQL, you should add `--with-debug' or `--with-debug=full' to the preceding configure lines and remove any `-fomit-frame-pointer' options. For the Windows distribution, please see *Note Windows installation::. Installing a MySQL Binary Distribution -------------------------------------- This chapter covers the installation of MySQL binary distributions (`.tar.gz' Archives) for various platforms (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. The generic MySQL binary distributions are packaged as gzip-compressed GNU tar archives (`.tar.gz'). You need the following tools to install a MySQL binary distribution: * GNU `gunzip' to uncompress the distribution. * A reasonable `tar' to unpack the distribution. GNU `tar' is known to work. Some `tar' implementations that come pre-installed with the operating system (e.g. Sun `tar') are known to have problems (with long file names, for example). In that case, you should install GNU `tar' first. If you run into problems, *please always use `mysqlbug'* when posting questions to a MySQL mailing list. Even if the problem isn't a bug, `mysqlbug' gathers system information that will help others solve your problem. By not using `mysqlbug', you lessen the likelihood of getting a solution to your problem. You will find `mysqlbug' in the `bin' directory after you unpack the distribution. *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 & If your version of MySQL is older than 4.0, substitute `bin/safe_mysqld' for `bin/mysqld_safe' in the final command. You can add new users using the `bin/mysql_setpermission' script if you install the `DBI' and `DBD::mysql' Perl modules. A more detailed description follows. To install a binary distribution, follow these steps, then proceed to *Note Post-installation::, for post-installation setup and testing: 1. Pick the directory under which you want to unpack the distribution, and move into it. In the following example, we unpack the distribution under `/usr/local' (The following instructions, therefore, assume you have permission to create files and directories in `/usr/local'. If that directory is protected, you will need to perform the installation as `root'.) 2. Obtain a distribution file from one of the sites listed in *Note Getting MySQL: Getting MySQL. MySQL binary distributions are provided as compressed `tar' archives and have names like `mysql-VERSION-OS.tar.gz', where `VERSION' is a number (for example, `3.21.15'), and `OS' indicates the type of operating system for which the distribution is intended (for example, `pc-linux-gnu-i586'). Note that all binaries are built from the same MySQL source distribution. 3. Add a user and group for `mysqld' to run as: shell> groupadd mysql shell> useradd -g mysql mysql These commands add the `mysql' group and the `mysql' user. The syntax for `useradd' and `groupadd' may differ slightly on different versions of Unix. They may also be called `adduser' and `addgroup'. You may wish to call the user and group something else instead of `mysql'. 4. Change into the intended installation directory: shell> cd /usr/local 5. Unpack the distribution, which will create the installation directory. Then create a symbolic link to that directory: shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf - shell> ln -s full-path-to-mysql-VERSION-OS mysql Using GNU tar, you can also replace the first line with the following alternative command to decompress and extract the distribution in one go: shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz The first command creates a directory named `mysql-VERSION-OS'. The second command makes a symbolic link to that directory. This lets you refer more easily to the installation directory as `/usr/local/mysql'. 6. Change into the installation directory: shell> cd mysql You will find several files and subdirectories in the `mysql' directory. The most important for installation purposes are the `bin' and `scripts' subdirectories. `bin' 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 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'. 8. Create the MySQL grant tables (necessary only if you haven't installed MySQL before): shell> scripts/mysql_install_db Note that MySQL versions older than Version 3.22.10 started the MySQL server when you run `mysql_install_db'. This is no longer true. 9. Change ownership of binaries to `root' and ownership of the data directory to the user that you will run `mysqld' as: shell> chown -R root /usr/local/mysql/. shell> chown -R mysql /usr/local/mysql/data shell> chgrp -R mysql /usr/local/mysql/. The first command changes the `owner' attribute of the files to the `root' user, the second one changes the `owner' attribute of the data directory to the `mysql' user, and the third one changes the `group' attribute to the `mysql' group. 10. If you want to install support for the Perl `DBI'/`DBD' interface, see *Note Perl support::. 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::. After everything has been unpacked and installed, you should initialize and test your distribution. You can start the MySQL server with the following command: shell> bin/mysqld_safe --user=mysql & If your version of MySQL is older than 4.0, substitute `bin/safe_mysqld' for `bin/mysqld_safe' in the command. Now proceed to *Note `mysqld_safe': mysqld_safe, and *Note Post-installation::. Installing a MySQL Source Distribution ====================================== Before you proceed with the source installation, check first to see if our binary is available for your platform and if it will work for you. We put a lot of effort into making sure that our binaries are built with the best possible options. You need the following tools to build and install MySQL from source: * GNU `gunzip' to uncompress the distribution. * A reasonable `tar' to unpack the distribution. GNU `tar' is known to work. Some `tar' implementations that come pre-installed with the operating system (e.g. Sun `tar') are known to have problems (with long file names, for example). In that case, you should install GNU `tar' first. * A working ANSI C++ compiler. `gcc' >= 2.95.2, `egcs' >= 1.0.2 or `egcs 2.91.66', SGI C++, and SunPro C++ are some of the compilers that are known to work. `libg++' is not needed when using `gcc'. `gcc' 2.7.x has a bug that makes it impossible to compile some perfectly legal C++ files, such as `sql/sql_base.cc'. If you only have `gcc' 2.7.x, you must upgrade your `gcc' to be able to compile MySQL. `gcc' 2.8.1 is also known to have problems on some platforms, so it should be avoided if a new compiler exists for the platform. `gcc' >= 2.95.2 is recommended when compiling MySQL Version 3.23.x. * A good `make' program. GNU `make' is always recommended and is sometimes required. If you have problems, we recommend trying GNU `make' 3.75 or newer. If you are using a recent version of `gcc', recent enough to understand the `-fno-exceptions' option, it is *very important* that you use it. Otherwise, you may compile a binary that 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 Installation Overview --------------------------- The basic commands you must execute to install a MySQL source distribution are: shell> groupadd mysql shell> useradd -g mysql mysql shell> gunzip < mysql-VERSION.tar.gz | tar -xvf - shell> cd mysql-VERSION shell> ./configure --prefix=/usr/local/mysql shell> make shell> make install shell> scripts/mysql_install_db shell> chown -R root /usr/local/mysql shell> chown -R mysql /usr/local/mysql/var shell> chgrp -R mysql /usr/local/mysql shell> cp support-files/my-medium.cnf /etc/my.cnf shell> /usr/local/mysql/bin/mysqld_safe --user=mysql & If your version of MySQL is older than 4.0, substitute `bin/safe_mysqld' for `bin/mysqld_safe' in the final command. If you want to have support for InnoDB tables, you should edit the `/etc/my.cnf' file and remove the `#' character before the parameter that starts with `innodb_...'. *Note Option files::, and *Note InnoDB start::. If you start from a source RPM, do the following: shell> rpm --rebuild --clean MySQL-VERSION.src.rpm This will make a binary RPM that you can install. You can add new users using the `bin/mysql_setpermission' script if you install the `DBI' and `DBD::mysql' Perl modules. A more detailed description follows. To install a source distribution, follow these steps, then proceed to *Note Post-installation::, for post-installation initialization and testing: 1. Pick the directory under which you want to unpack the distribution, and move into it. 2. Obtain a distribution file from one of the sites listed in *Note Getting MySQL: Getting MySQL. 3. If you are interested in using Berkeley DB tables with MySQL, you will need to obtain a patched version of the Berkeley DB source code. Please read the chapter on Berkeley DB tables before proceeding. *Note BDB::. MySQL source distributions are provided as compressed `tar' archives and have names like `mysql-VERSION.tar.gz', where `VERSION' is a number like 5.0.0-alpha. 4. Add a user and group for `mysqld' to run as: shell> groupadd mysql shell> useradd -g mysql mysql These commands add the `mysql' group and the `mysql' user. The syntax for `useradd' and `groupadd' may differ slightly on different versions of Unix. They may also be called `adduser' and `addgroup'. You may wish to call the user and group something else instead of `mysql'. 5. Unpack the distribution into the current directory: shell> gunzip < /path/to/mysql-VERSION.tar.gz | tar xvf - This command creates a directory named `mysql-VERSION'. 6. Change into the top-level directory of the unpacked distribution: shell> cd mysql-VERSION Note that currently you must configure and build MySQL from this top-level directory. You cannot build it in a different directory. 7. Configure the release and compile everything: shell> ./configure --prefix=/usr/local/mysql shell> make When you run `configure', you might want to specify some options. Run `./configure --help' for a list of options. *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' if `configure' aborts. 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. 8. Install everything: shell> make install You might need to run this command as `root'. 9. Create the MySQL grant tables (necessary only if you haven't installed MySQL before): shell> scripts/mysql_install_db Note that MySQL versions older than Version 3.22.10 started the MySQL server when you run `mysql_install_db'. This is no longer true. 10. Change ownership of binaries to `root' and ownership of the data directory to the user that you will run `mysqld' as: shell> chown -R root /usr/local/mysql shell> chown -R mysql /usr/local/mysql/var shell> chgrp -R mysql /usr/local/mysql The first command changes the `owner' attribute of the files to the `root' user, the second one changes the `owner' attribute of the data directory to the `mysql' user, and the third one changes the `group' attribute to the `mysql' group. 11. If you want to install support for the Perl `DBI'/`DBD' interface, see *Note Perl support::. 12. If you would like MySQL to start automatically when you boot your machine, you can copy `support-files/mysql.server' to the location where your system has its startup files. More information can be found in the `support-files/mysql.server' script itself and in *Note Automatic start::. After everything has been installed, you should initialize and test your distribution using this command: shell> /usr/local/mysql/bin/mysqld_safe --user=mysql & If your version of MySQL is older than 4.0, substitute `safe_mysqld' for `mysqld_safe' in the command. If that command fails immediately with `mysqld daemon ended', you can find some information in the file `mysql-data-directory/'hostname'.err'. The likely reason is that you already have another `mysqld' server running. *Note Multiple servers::. Now proceed to *Note Post-installation::. Applying Patches ---------------- Sometimes patches appear on the mailing list or are placed in the patches area of the MySQL web site (`http://www.mysql.com/downloads/patches.html'). To apply a patch from the mailing list, save the message in which the patch appears in a file, change into the top-level directory of your MySQL source tree, and run these commands: shell> patch -p1 < patch-file-name shell> rm config.cache shell> make clean Patches from the FTP site are distributed as plain text files or as files compressed with `gzip'. Apply a plain patch as shown previously for mailing list patches. To apply a compressed patch, change into the top-level directory of your MySQL source tree and run these commands: shell> gunzip < patch-file-name.gz | patch -p1 shell> rm config.cache shell> make clean After applying a patch, follow the instructions for a normal source install, beginning with the `./configure' step. After running the `make install' step, restart your MySQL server. You may need to bring down any currently running server before you run `make install'. (Use `mysqladmin shutdown' to do this.) Some systems do not allow you to install a new version of a program if it replaces the version that is currently executing. Typical `configure' Options --------------------------- The `configure' script gives you a great deal of control over how you configure your MySQL distribution. Typically you do this using options on the `configure' command-line. You can also affect `configure' using certain environment variables. *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 `mysql.sock' by using the MySQL option files. *Note 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. Here are some common environment variables to set depending on the compiler you are using: *Compiler* *Recommended options* `gcc' CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors" 2.7.2.1 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' CFLAGS="-O3 -mpentiumpro -mstack-align-double" 2.90.29 or CXX=gcc \ CXXFLAGS="-O3 -mpentiumpro newer -mstack-align-double -felide-constructors \ -fno-exceptions -fno-rtti" In most cases you can get a reasonably optimal MySQL binary by using the options from the preceding table and adding the following options to the configure line: --prefix=/usr/local/mysql --enable-assembler \ --with-mysqld-ldflags=-all-static The full `configure' line would, in other words, be something like the following for all recent `gcc' versions: CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \ -felide-constructors -fno-exceptions -fno-rtti" ./configure \ --prefix=/usr/local/mysql --enable-assembler \ --with-mysqld-ldflags=-all-static The binaries we provide on the MySQL web site at `http://www.mysql.com/' are all compiled with full 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 * 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 option `--with-extra-charsets=LIST' you can define which additional character sets should be compiled into the server. Here `LIST' is either a list of character sets separated with spaces, `complex' to include all characters that can't be dynamically loaded, or `all' to include all character sets into the binaries. * To configure MySQL with debugging code, use the `--with-debug' option: shell> ./configure --with-debug This causes a safe memory allocator to be included that can find some errors and that provides output about what is happening. *Note Debugging server::. * If your client programs are using threads, you need to also compile a thread-safe version of the MySQL client library with the `--enable-thread-safe-client' configure options. This will create a `libmysqlclient_r' library with which you should link your threaded applications. *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 source or binary distribution will do). To obtain our most recent development source tree, use these instructions: 1. Download `BitKeeper' from `http://www.bitmover.com/cgi-bin/download.cgi'. You will need `Bitkeeper' 3.0 or newer to access our repository. 2. Follow the instructions to install it. 3. After `BitKeeper' is installed, first go to the directory you want to work from, and then use one of the following commands to clone the MySQL version branch of your choice: To clone the 3.23 (old) branch, use this command: shell> bk clone bk://mysql.bkbits.net/mysql-3.23 mysql-3.23 To clone the 4.0 (stable/production) branch, use this command: shell> bk clone bk://mysql.bkbits.net/mysql-4.0 mysql-4.0 To clone the 4.1 alpha branch, use this command: shell> bk clone bk://mysql.bkbits.net/mysql-4.1 mysql-4.1 To clone the 5.0 development branch, use this command: shell> bk clone bk://mysql.bkbits.net/mysql-5.0 mysql-5.0 In the preceding examples the source tree will be set up in the `mysql-3.23/', `mysql-4.0/', `mysql-4.1/', or `mysql-5.0/' subdirectory of your current directory. If you are behind a firewall and can only initiate HTTP connections, you can also use `BitKeeper' via HTTP. If you are required to use a proxy server, simply set the environment variable `http_proxy' to point to your proxy: shell> export http_proxy="http://your.proxy.server:8080/" Now, simply replace the `bk://' with `http://' when doing a clone. Example: shell> bk clone http://mysql.bkbits.net/mysql-4.1 mysql-4.1 The initial download of the source tree may take a while, depending on the speed of your connection - please be patient. 4. You will need *GNU* `make', `autoconf 2.53 (or newer)', `automake 1.5', `libtool 1.4', and `m4' to run the next set of commands. Even though many operating system already come with their own implementation of `make', chances are high that the compilation fails with strange error messages. Therefore it is highly recommended to use GNU `make' (sometimes also named `gmake') by all means. Fortunately, a large number of operating systems already ship with the GNU toolchain preinstalled or supply installable packages of these. In any case, they can also be downloaded from the following locations: * * * * If you are trying to configure MySQL 4.1, you will also need GNU `bison 1.75'. Older versions of `bison' may report this error: `sql_yacc.yy:#####: fatal error: maximum table size (32767) exceeded'. Note: the maximum table size is not actually exceeded, the error is caused by bugs in these earlier `bison' versions. Versions of MySQL before version 4.1 may also compile with other `yacc' implementations (e.g. BSD `yacc' 91.7.30). For later versions, GNU `bison' is a requirement. The typical command to do in a shell is: cd mysql-4.0 bk -r edit aclocal; autoheader; autoconf; automake (cd innobase; aclocal; autoheader; autoconf; automake) # for InnoDB (cd bdb/dist; sh s_all ) # for Berkeley DB ./configure # Add your favorite options here make If you get some strange error during this stage, check that you really have `libtool' installed. A collection of our standard configure scripts is located in the `BUILD/' subdirectory. 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 get the source tree, you should run `bk pull' periodically to get the updates. 9. You can examine the change history for the tree with all the diffs by using `bk sccstool'. If you see some funny diffs or code that you have a question about, do not hesitate to send 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 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 sourcecode online by browsing to for example, `http://mysql.bkbits.net:8080/mysql-4.1' For MySQL 4.1. The manual is in a separate tree which can be cloned with: shell> bk clone bk://mysql.bkbits.net/mysqldoc mysqldoc There are also public BitKeeper trees for MySQL Control Center and Connector/ODBC. They can be cloned respectively as follows. To clone MySQL Control center, use this command: shell> bk clone http://mysql.bkbits.net/mysqlcc mysqlcc To clone Connector/ODBC, use this command: shell> bk clone http://mysql.bkbits.net/myodbc3 myodbc3 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 rerunning `configure': shell> rm config.cache shell> make clean Alternatively, you can run `make distclean'. The following list describes some of the problems when compiling MySQL that have been found to occur most often: * If you get errors when compiling `sql_yacc.cc', such as the ones shown here, you have probably run out of memory or swap space: Internal compiler error: program cc1plus got fatal signal 11 or Out of virtual memory or Virtual memory exhausted The problem is that `gcc' requires huge amounts of memory to compile `sql_yacc.cc' with inline functions. Try running `configure' with the `--with-low-memory' option: shell> ./configure --with-low-memory This option causes `-fno-inline' to be added to the compile line if you are using `gcc' and `-O0' if you are using something else. You should try the `--with-low-memory' option even if you have so much memory and swap space that you think you can't possibly have run out. This problem has been observed to occur even on systems with generous hardware configurations, and the `--with-low-memory' option usually fixes it. * By default, `configure' picks `c++' as the compiler name and GNU `c++' links with `-lg++'. If you are using `gcc', that 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, of course, is to install `g++', `libg++', and `libstdc++'. We would however like to recommend you to not use `libg++' or `libstdc++' with MySQL as this will only increase the binary size of mysqld without giving you any benefits. Some versions of these libraries have also caused strange problems for MySQL users in the past. Using `gcc' as the C++ compiler is also required, if you want to compile MySQL with RAID functionality (see *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. * 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 sockets do not work under MIT-pthreads on some platforms, this means you will need to use `-h' or `--host' when you run client programs. * When MySQL is compiled using MIT-pthreads, system locking is disabled by default for performance reasons. You can tell the server to use system locking with the `--external-locking' option. This is only needed if you want to be able to run two MySQL servers against the same datafiles (not recommended). * Sometimes the pthread `bind()' command fails to bind to a socket without any error message (at least on Solaris). The result is that all connections to the server fail. For example: shell> mysqladmin version mysqladmin: connect to server at '' failed; error: 'Can't connect to mysql server on localhost (146)' 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 do this: copy lib_debug\mysqlclient.lib C:\mysql\lib\debug copy lib_debug\libmysql.* C:\mysql\lib\debug copy lib_debug\zlib.* C:\mysql\lib\debug copy lib_release\mysqlclient.lib C:\mysql\lib\opt copy lib_release\libmysql.* C:\mysql\lib\opt copy lib_release\zlib.* C:\mysql\lib\opt copy include\*.h C:\mysql\include copy libmysql\libmysql.def C:\mysql\include If you want to benchmark MySQL, you should also do this: 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 build the latest Windows source package from the current BitKeeper source tree, use the following instructions. Please note that this procedure must be performed on a system running a Unix or Unix-like operating system. (The procedure is known to work well on Linux, for example.) 1. Clone the BitKeeper source tree for MySQL (version 4.1 or above, as desired). For more information how to clone the source tree, see the instructions at *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 Debug, without creating the package --tmp Specify the temporary location --suffix Suffix name for the package --dirname Directory name to copy files (intermediate) --silent Do not list verbosely files processed --tar Create tar.gz package instead of .zip --help Show this help message By default, `make_win_src_distribution' creates a zipped archive with the name `mysql-VERSION-win-src.zip', where `VERSION' represents the version of your MySQL source tree. 4. Copy or upload to your Windows machine the Windows source package that you have just created. To compile it, use the instructions in *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 =================================== Once you've installed MySQL (from either a binary or source distribution), 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 up and shuts down. Normally you install the grant tables and start the server like this for installation from a source distribution: shell> ./scripts/mysql_install_db shell> cd mysql_installation_directory shell> ./bin/mysqld_safe --user=mysql & For a binary distribution (not RPM or pkg packages), do this: shell> cd mysql_installation_directory shell> ./scripts/mysql_install_db shell> ./bin/mysqld_safe --user=mysql & The `mysql_install_db' script creates the `mysql' database which will hold all database privileges, the `test' database which you can use to test MySQL, and also privilege entries for the user that runs `mysql_install_db' and a `root' user. The entries are created without passwords. The `mysqld_safe' script starts the `mysqld' server. (If your version of MySQL is older than 4.0, use `safe_mysqld' rather than `mysqld_safe'.) `mysql_install_db' will not overwrite any old privilege tables, so it should be safe to run in any circumstances. If you don't want to have the `test' database you can remove it with `mysqladmin -u root drop test' after starting the server. Testing is most easily done from the top-level directory of the MySQL distribution. For a binary distribution, this is your installation directory (typically something like `/usr/local/mysql'). For a source distribution, this is the main directory of your MySQL source tree. In the commands shown in this section and in the following subsections, `BINDIR' is the path to the location in which programs like `mysqladmin' and `mysqld_safe' are installed. For a binary distribution, this is the `bin' directory within the distribution. For a source distribution, `BINDIR' is probably `/usr/local/bin', unless you specified an installation directory other than `/usr/local' when you ran `configure'. `EXECDIR' is the location in which the `mysqld' server is installed. For a binary distribution, this is the same as `BINDIR'. For a source distribution, `EXECDIR' is probably `/usr/local/libexec'. Testing is described in detail: 1. If necessary, start the `mysqld' server and set up the initial MySQL grant tables containing the privileges that determine how users are allowed to connect to the server. This is normally done with the `mysql_install_db' script: shell> scripts/mysql_install_db Typically, `mysql_install_db' needs to be run only the first time you install MySQL. Therefore, if you are upgrading an existing installation, you can skip this step. (However, `mysql_install_db' is quite safe to use and will not update any tables that already exist, so if you are unsure of what to do, you can always run `mysql_install_db'.) `mysql_install_db' creates six tables (`user', `db', `host', `tables_priv', `columns_priv', and `func') in the `mysql' database. A description of the initial privileges is given in *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 & If your version of MySQL is older than 4.0, substitute `bin/safe_mysqld' for `bin/mysqld_safe' in the final command. If you have problems starting the server, see *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.14 Distrib 3.23.32, for linux on i586 Copyright (C) 2000 MySQL AB & MySQL Finland AB & TCX DataKonsult AB This software comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to modify and redistribute it under the GPL license. Server version 3.23.32-debug 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 get a feeling for what else you can do with `BINDIR/mysqladmin', invoke it with the `--help' option. 4. Verify that you can shut down the server: shell> BINDIR/mysqladmin -u root shutdown 5. Verify that you can restart the server. Do this using `mysqld_safe' or by invoking `mysqld' directly. For example: shell> BINDIR/mysqld_safe --log & If `mysqld_safe' fails, try running it from the MySQL installation directory (if you are not already there). If that doesn't work, see *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, using the Perl DBI module to provide a database-independent interface to the various databases. The following additional Perl modules are required to run the benchmark suite: DBI DBD::mysql Data::Dumper Data::ShowTable These modules can be obtained from CPAN `http://www.cpan.org/'. *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 are probably using an RPM for a binary distribution. (Source distribution RPMs include the benchmark directory.) In this case, you must first install the benchmark suite before you can use it. Beginning with MySQL Version 3.22, there are benchmark RPM files named `mysql-bench-VERSION-i386.rpm' that contain benchmark code and data. If you have a source distribution, you can also run the tests in the `tests' subdirectory. For example, to run `auto_increment.tst', do this: shell> BINDIR/mysql -vvf test < ./tests/auto_increment.tst The expected results are shown in the `./tests/auto_increment.res' file. Problems Running `mysql_install_db' ----------------------------------- The purpose of the `mysql_install_db' script is to generate new MySQL privilege tables. It will not affect any other data. It will also not do anything if you already have MySQL privilege tables installed. If you want to re-create your privilege tables, you should take down the `mysqld' server, if it's running, and then do something like: mv mysql-data-directory/mysql mysql-data-directory/mysql-old mysql_install_db This section lists problems you might encounter when you run `mysql_install_db': *`mysql_install_db' doesn't install the grant tables* You may find that `mysql_install_db' fails to install the grant tables and terminates after displaying the following messages: starting mysqld daemon with databases from XXXXXX mysql daemon ended In this case, you should examine the log file very carefully. The log should be located in the directory `XXXXXX' named by the error message, and should indicate why `mysqld' didn't start. If you don't understand what happened, include the log when you post a bug report using `mysqlbug'. *Note Bug reports::. *There is already a `mysqld' daemon running* In this case, you probably don't have to run `mysql_install_db' at all. You have to run `mysql_install_db' only once, when you install MySQL the first time. *Installing a second `mysqld' daemon doesn't work when one daemon is running* This can happen when you already have an existing MySQL installation, but want to put a new installation in a different place (for example, for testing, or perhaps you simply want to run two installations at the same time). Generally the problem that occurs when you try to run the second server is that it tries to use the same socket and port as the old one. In this case you will get the error message: `Can't start server: Bind on TCP/IP port: Address already in use' or `Can't start server: Bind on unix socket...'. *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::. `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. Problems Starting the MySQL Server ---------------------------------- If you are going to use tables that support transactions (InnoDB, BDB), you should first create a `my.cnf' file and set startup options for the table types you plan to use. *Note Table types::. Generally, you start the `mysqld' server in one of these ways: * By invoking `mysql.server'. This script is used primarily at system startup and shutdown, and is described more fully in *Note Automatic start::. * By invoking `mysqld_safe', which tries to determine the proper options for `mysqld' and then runs it with those options. *Note `mysqld_safe': mysqld_safe. * For Windows NT/2000/XP, please see *Note NT start::. * By invoking `mysqld' directly. When the `mysqld' daemon starts up, it changes the directory to the data directory. This is where it expects to write log files and the pid (process ID) file, and where it expects to find databases. The data directory location is hardwired in when the distribution is compiled. However, if `mysqld' expects to find the data directory somewhere other than where it really is on your system, it will not work properly. If you have problems with incorrect paths, you can find out what options `mysqld' allows and what the default path settings are by invoking `mysqld' with the `--help' option. You can override the defaults by specifying the correct pathnames as command-line arguments to `mysqld'. (These options can be used with `mysqld_safe' as well.) Normally you should need to tell `mysqld' only the base directory under which MySQL is installed. You can do this with the `--basedir' option. You can also use `--help' to check the effect of changing path options (note that `--help' *must* be the final option of the `mysqld' command). For example: shell> EXECDIR/mysqld --basedir=/usr/local --help Once you determine the path settings you want, start the server without the `--help' option. Whichever method you use to start the server, if it fails to start up correctly, check the log file to see if you can find out why. Log files are located in the data directory (typically `/usr/local/mysql/data' for a binary distribution, `/usr/local/var' for a source distribution, and `\mysql\data\mysql.err' on Windows). Look in the data directory for files with names of the form `host_name.err' and `host_name.log' where `host_name' is the name of your server host. Then check the last few lines of these files: shell> tail host_name.err shell> tail host_name.log Look for something like the following in the log file: 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 recover log. In this case you can try starting `mysqld' with `--bdb-no-recover'. If this helps, then you should remove all `log.*' files from the data directory and try starting `mysqld' again. If you get the following error, it means that some other program (or another `mysqld' server) is already using the TCP/IP port or socket `mysqld' is trying to use: Can't start server: Bind on TCP/IP port: Address already in use or Can't start server: Bind on unix socket... Use `ps' to make sure that you don't have another `mysqld' server running. If you can't find another server running, you can try to execute the command `telnet your-host-name tcp-ip-port-number' and press Enter a couple of times. If you don't get an error message like `telnet: Unable to connect to remote host: Connection refused', something is using the TCP/IP port `mysqld' is trying to use. See *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::. Starting and Stopping MySQL Automatically ----------------------------------------- The `mysql.server' and `mysqld_safe' scripts can be used to start the server automatically at system startup time. `mysql.server' can also be used to stop the server. The `mysql.server' script can be used to start or stop the server by invoking it with `start' or `stop' arguments: shell> mysql.server start shell> mysql.server stop `mysql.server' can be found in the `share/mysql' directory under the MySQL installation directory or in the `support-files' directory of the MySQL source tree. Note that if you use the Linux RPM package (`MySQL-server-VERSION.rpm'), the `mysql.server' script has already been installed as `/etc/init.d/mysql' - you don't have to install it manually. See *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 take down the server manually by executing `mysqladmin shutdown'. You need to add these start and stop commands to the appropriate places in your `/etc/rc*' files when you want to start up MySQL automatically on your server. On most current Linux distributions, it is sufficient to copy the file `mysql.server' into the `/etc/init.d' directory (or `/etc/rc.d/init.d' on older Red Hat systems). Afterwards, run the following command to enable the startup of MySQL on system bootup: shell> chkconfig --add mysql.server On FreeBSD startup scripts generally should go in `/usr/local/etc/rc.d/'. The `rc(8)' manual page also states that scripts in this directory are only executed, if their basename matches the shell globbing pattern `*.sh'. Any other files or directories present within the directory are silently ignored. In other words, on FreeBSD you should install the file `mysql.server' as `/usr/local/etc/rc.d/mysql.server.sh' to enable automatic startup. As an alternative to the above, some operating systems also use `/etc/rc.local' or `/etc/init.d/boot.local' to start additional services on bootup. To start up MySQL using this method, you could append something like the following to it: /bin/sh -c 'cd /usr/local/mysql; ./bin/mysqld_safe --user=mysql &' You can also add options for `mysql.server' in a global `/etc/my.cnf' file. A typical `/etc/my.cnf' file might look like this: [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::. Upgrading/Downgrading MySQL =========================== Before you do an upgrade, you should back up your old databases. You can always move the MySQL format files and datafiles between different versions on the same architecture as long as you have the same base version of MySQL. The current base version is 4. If you change the character set when running MySQL, you must run `myisamchk -r -q --set-character-set=charset' on all tables. Otherwise, your indexes may not be ordered correctly, because changing the character set may also change the sort order. If you are afraid of new versions, you can always rename your old `mysqld' to something like `mysqld-old-version-number'. If your new `mysqld' then does something unexpected, you can simply shut it down and restart with your old `mysqld'. If, after an upgrade, you experience problems with recompiled client programs, such as `Commands out of sync' or unexpected core dumps, you probably have used an old header or library file when compiling your programs. In this case you should check the date for your `mysql.h' file and `libmysqlclient.a' library to verify that they are from the new MySQL distribution. If not, please recompile your programs. If problems occur, such as that the new `mysqld' server doesn't want to start or that you can't connect without a password, check that you don't have some old `my.cnf' file from your old installation. You can check this with: `program-name --print-defaults'. If this outputs anything other than the program name, you have an active `my.cnf' file that affects server operation. It is a good idea to rebuild and reinstall the Perl `DBD::mysql' module whenever you install a new release of MySQL. The same applies to other MySQL interfaces as well, such as the Python `MySQLdb' module. 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 option value for the `sql_mode' variable. You should use `SET TRANSACTION ISOLATION LEVEL SERIALIZABLE' instead. `SERIALIZE' is no longer valid for the `--sql-mode' option for `mysqld', either. Use `--transaction-isolation=SERIALIZABLE' instead. * All tables and string columns now have a character set. *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 if there are any that may affect your applications. * Read the 4.1 news items to see what significant new features you can use in 4.1. *Note News-4.1.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. * 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 of course you cannot use any of the new features provided by the 4.1 client/server protocol, either. (MySQL 4.1 has an extended client/server protocol that offers such features as prepared statements and multiple result sets.) *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 4.0 from an earlier MySQL version: * After upgrading, update the grant tables to add new privileges and features. The procedure uses the `mysql_fix_privilege_tables' script and is described in *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 new Perl `DBI'/`DBD' interface also supports the old `mysqlperl' interface. The only change you have to make if you use `mysqlperl' is to change the arguments to the `connect()' function. The new arguments are: `host', `database', `user', and `password' (note that the `user' and `password' arguments have changed places). *Note Perl `DBI' Class: Perl DBI Class. 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 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 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. Upgrading to Another Architecture --------------------------------- If you are using MySQL Version 3.23, you can copy the `.frm', `.MYI', and `.MYD' files for `MyISAM' tables between different architectures that support the same floating-point format. (MySQL takes care of any byte-swapping issues.) *Note `MyISAM' Tables: MyISAM. The MySQL `ISAM' data and index files (`.ISD' and `*.ISM', respectively) are architecture-dependent and in some cases OS-dependent. If you want to move your applications to another machine that has a different architecture or OS than your current machine, you should not try to move a database by simply copying the files to the other machine. Use `mysqldump' instead. By default, `mysqldump' will create a file containing SQL statements. You can then transfer the file to the other machine and feed it as input to the `mysql' client. Try `mysqldump --help' to see what options are available. If you are moving the data to a newer version of MySQL, you should use `mysqldump --opt' with the newer version to get a fast, compact dump. The easiest (although not the fastest) way to move a database between two machines is to run the following commands on the machine on which the database is located: shell> mysqladmin -h 'other hostname' create db_name shell> mysqldump --opt db_name \ | mysql -h 'other hostname' db_name If you want to copy a database from a remote machine over a slow network, you can use: shell> mysqladmin create db_name shell> mysqldump -h 'other hostname' --opt --compress db_name \ | mysql db_name You can also store the result in a file, then transfer the file to the target machine and load the file into the database there. For example, you can dump a database to a file on the source machine like this: 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. Upgrading MySQL under Windows ----------------------------- When upgrading MySQL under Windows, please follow these steps: 1. Download the latest Windows distribution of MySQL. 2. Choose a time of day with low usage, where a maintenance break is acceptable. 3. Alert the users that still are active about the maintenance break. 4. Stop the running MySQL Server (for example, with `NET STOP mysql' or with the `Services' utility if you are running MySQL as a service, or with `mysqladmin shutdown' otherwise). 5. Exit the `WinMySQLAdmin' program if it is running. 6. Run the installation script of the Windows distribution, by clicking the "Install" button in WinZip and following the installation steps of the script. 7. You may either overwrite your old MySQL installation (usually located at `C:\mysql'), or install it into a different directory, such as `C:\mysql4'. Overwriting the old installation is recommended. 8. Restart the server (for example, with `NET START mysql' if you run MYSQL as a service, or by invoking `mysqld' directly otherwise). 9. Update the grant tables. The procedure is described in *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. Operating System Specific Notes =============================== Linux Notes (All Linux Versions) -------------------------------- The following notes regarding `glibc' apply only to the situation when you build MySQL yourself. If you are running Linux on an x86 machine, in most cases it is much better for you to just use our binary. We link our binaries against the best patched version of `glibc' we can come up with and with the best compiler options, in an attempt to make it suitable for a high-load server. For a typical user, even for setups with a lot of concurrent connections and/or tables exceeding the 2G limit, our binary in most cases is the best choice. So if you read the following text, and are in doubt about what you should do, try our binary first to see if it meets your needs, and worry about your own build only after you have discovered that our binary is not good enough. In that case, we would appreciate a note about it, so we can build a better binary next time. MySQL uses LinuxThreads on Linux. If you are using an old Linux version that doesn't have `glibc2', you must install LinuxThreads before trying to compile MySQL. You can get LinuxThreads at `http://www.mysql.com/downloads/os-linux.html'. *Note*: we have seen some strange problems with Linux 2.2.14 and MySQL on SMP systems. If you have a SMP system, we recommend you upgrade to Linux 2.4 as soon as possible. Your system will be faster and more stable. Note that `glibc' versions before and including Version 2.1.1 have a fatal bug in `pthread_mutex_timedwait' handling, which is used when you issue `INSERT DELAYED' statements. We recommend that you not use `INSERT DELAYED' before upgrading `glibc'. If you plan to have 1000+ concurrent connections, you will need to make some changes to LinuxThreads, recompile it, and relink MySQL against the new `libpthread.a'. Increase `PTHREAD_THREADS_MAX' in `sysdeps/unix/sysv/linux/bits/local_lim.h' to 4096 and decrease `STACK_SIZE' in `linuxthreads/internals.h' to 256 KB. The paths are relative to the root of `glibc' Note that MySQL will not be stable with around 600-1000 connections if `STACK_SIZE' is the default of 2 MB. If MySQL can't open enough files, or connections, it may be that you haven't configured Linux to handle enough files. In Linux 2.2 and onward, you can check the number of allocated file handles by doing: cat /proc/sys/fs/file-max cat /proc/sys/fs/dquot-max cat /proc/sys/fs/super-max If you have more than 16 MB of memory, you should add something like the following to your init scripts (for example, `/etc/init.d/boot.local' on SuSE Linux): echo 65536 > /proc/sys/fs/file-max echo 8192 > /proc/sys/fs/dquot-max echo 1024 > /proc/sys/fs/super-max You can also run the preceding commands from the command-line as root, but these settings will be lost the next time your computer reboots. Alternatively, you can set these parameters on bootup by using the `sysctl' tool, which is used by many Linux distributions (SuSE has added it as well, beginning with SuSE Linux 8.0). Just put the following values into a file named `/etc/sysctl.conf': # Increase some values for MySQL fs.file-max = 65536 fs.dquot-max = 8192 fs.super-max = 1024 You should also add the following to `/etc/my.cnf': [mysqld_safe] open-files-limit=8192 This should allow MySQL to create up to 8192 connections + files. The `STACK_SIZE' constant in LinuxThreads controls the spacing of thread stacks in the address space. It needs to be large enough so that there will be plenty of room for the stack of each individual thread, but small enough to keep the stack of some threads from running into the global `mysqld' data. Unfortunately, the Linux implementation of `mmap()', as we have experimentally discovered, will successfully unmap an already mapped region if you ask it to map out an address already in use, zeroing out the data on the entire page, instead of returning an error. So, the safety of `mysqld' or any other threaded application depends on the "gentleman" 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 "gentleman" behavior by setting a reasonable value for the `max_connections' variable. If you build MySQL yourself and do not want to mess with patching LinuxThreads, you should set `max_connections' to a value no higher than 500. It should be even less if you have a large key buffer, large heap tables, or some other things that make `mysqld' allocate a lot of memory, or if you are running a 2.2 kernel with a 2G patch. If you are using our binary or RPM version 3.23.25 or later, you can safely set `max_connections' at 1500, assuming no large key buffer or heap tables with lots of data. The more you reduce `STACK_SIZE' in LinuxThreads the more threads you can safely create. We recommend the values between 128K and 256K. If you use a lot of concurrent connections, you may suffer from a "feature" in the 2.2 kernel that penalises a process for forking or cloning a child in an attempt to prevent a fork bomb attack. This will cause MySQL not to scale well as you increase the number of concurrent clients. On single-CPU systems, we have seen this manifested in a very slow thread creation, which means it may take a long time to connect to MySQL (as long as 1 minute), and it may take just as long to shut it down. On multiple-CPU systems, we have observed a gradual drop in query speed as the number of clients increases. In the process of trying to find a solution, we have received a kernel patch from one of our users, who claimed it made a lot of difference for his site. The patch is available at `http://www.mysql.com/Downloads/Patches/linux-fork.patch'. We have now done rather extensive testing of this patch on both development and production systems. It has significantly improved `MySQL' performance without causing any problems and we now recommend it to our users who are still running high-load servers on 2.2 kernels. This issue has been fixed in the 2.4 kernel, so if you are not satisfied with the current performance of your system, rather than patching your 2.2 kernel, it might be easier to just upgrade to 2.4, which will also give you a nice SMP boost in addition to fixing this fairness bug. We have tested MySQL on the 2.4 kernel on a 2-CPU machine and found MySQL scales *much* better--there was virtually no slowdown on queries throughput all the way up to 1000 clients, and the MySQL scaling factor (computed as the ratio of maximum throughput to the throughput with one client) was 180%. We have observed similar results on a 4-CPU system--virtually no slowdown as the number of clients was increased up to 1000, and 300% scaling factor. So for a high-load SMP server we would definitely recommend the 2.4 kernel at this point. We have discovered that it is essential to run `mysqld' process with the highest possible priority on the 2.4 kernel to achieve maximum performance. This can be done by adding `renice -20 $$' command to `mysqld_safe'. In our testing on a 4-CPU machine, increasing the priority gave 60% increase in throughput with 400 clients. We are currently also trying to collect more information on how well `MySQL' performs on 2.4 kernel on 4-way and 8-way systems. If you have access such a system and have done some benchmarks, please send a mail to with the results - we will include them in the manual. There is another issue that greatly hurts MySQL performance, especially on SMP systems. The implementation of mutex in LinuxThreads in `glibc-2.1' is very bad for programs with many threads that only hold the mutex for a short time. On an SMP system, ironic as it is, if you link MySQL against unmodified `LinuxThreads', removing processors from the machine improves MySQL performance in many cases. We have made a patch available for `glibc 2.1.3' to correct this 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 chance of this condition can be reduced by renicing `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 CXX=gcc ./configure Linux SPARC Notes ................. In some implementations, `readdir_r()' is broken. The symptom is that `SHOW DATABASES' always returns an empty set. This can be fixed by removing `HAVE_READDIR_R' from `config.h' after configuring and before compiling. 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, instead of gcc, we get about 9-14% better performance with MySQL. Note that until MySQL version 3.23.52 and 4.0.2 we optimized the binary for the current CPU only (by using the `-fast' compile option); this meant that you could only use our binaries if you had an Alpha EV6 processor. Starting with all following releases we added the `-arch generic' flag to our compile options, which makes sure the binary runs on all Alpha processors. We also compile statically to avoid library problems. CC=ccc CFLAGS="-fast -arch generic" CXX=cxx \ CXXFLAGS="-fast -arch generic -noexceptions -nortti" \ ./configure --prefix=/usr/local/mysql --disable-shared \ --with-extra-charsets=complex --enable-thread-safe-client \ --with-mysqld-ldflags=-non_shared --with-client-ldflags=-non_shared If you want to use egcs the following configure line worked for us: CFLAGS="-O3 -fomit-frame-pointer" CXX=gcc \ CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \ -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql \ --disable-shared Some known problems when running MySQL on Linux-Alpha: * Debugging threaded applications like MySQL will not work with `gdb 4.18'. You should download and use gdb 5.1 instead! * If you try linking `mysqld' statically when using `gcc', the resulting image will core dump at start. In other words, *don't* use `--with-mysqld-ldflags=-all-static' with `gcc'. 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 compile line: Using `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 in some other place than `/usr/local/mysql' you need to add the path of the directory where you have `libmysqlclient.so' installed either to the `/etc/ld.so.conf' file or to the value of your `LD_LIBRARY_PATH' environment variable. *Note Link errors::. 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: checking for restartable system calls... configure: error can not run test programs while cross compiling This means that you have something wrong with your compiler installation! In this case you should upgrade your compiler to a newer version. You may also be able to solve this problem by inserting the following row into the `config.cache' file: ac_cv_sys_restartable_syscalls=${ac_cv_sys_restartable_syscalls='no'} If you are using Solaris on a SPARC, the recommended compiler is `gcc' 2.95.2 or 3.2. You can find this at `http://gcc.gnu.org/'. Note that `egcs' 1.1.1 and `gcc' 2.8.1 don't work reliably on SPARC! The recommended `configure' line when using `gcc' 2.95.2 is: CC=gcc CFLAGS="-O3" \ CXX=gcc CXXFLAGS="-O3 -felide-constructors -fno-exceptions -fno-rtti" \ ./configure --prefix=/usr/local/mysql --with-low-memory --enable-assembler If you have an UltraSPARC, you can get 4% more performance by adding "-mcpu=v8 -Wa,-xarch=v8plusa" to CFLAGS and CXXFLAGS. If you have Sun's Forte 5.0 (or newer) compiler, you can run `configure' like this: CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt" \ CXX=CC CXXFLAGS="-noex -mt" \ ./configure --prefix=/usr/local/mysql --enable-assembler You can create a 64-bit binary using Sun's Forte compiler with the following compile flags: CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt -xarch=v9" \ CXX=CC CXXFLAGS="-noex -mt -xarch=v9" ASFLAGS="-xarch=v9" \ ./configure --prefix=/usr/local/mysql --enable-assembler To create a 64bit Solaris binary using `gcc', add `-m64' to `CFLAGS' and `CXXFLAGS'. Note that this only works with MySQL 4.0 and up - MySQL 3.23 does not include the required modifications to support this. In the MySQL benchmarks, we got a 4% speedup on an UltraSPARC when using Forte 5.0 in 32-bit mode compared to using `gcc' 3.2 with `-mcpu' flags. If you create a 64-bit binary, it's 4 percent slower than the 32-bit binary, but `mysqld' can instead 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 The following paragraph is only relevant for older compilers than WorkShop 5.3: You may also have to edit the `configure' script to change this line: #if !defined(__STDC__) || __STDC__ != 1 to this: #if !defined(__STDC__) If you turn on `__STDC__' with the `-Xc' option, the Sun compiler can't compile with the Solaris `pthread.h' header file. This is a Sun bug (broken compiler or broken include file). If `mysqld' issues the error message shown here when you run it, you have tried to compile MySQL with the Sun compiler without enabling the multi-thread option (`-mt'): libc internal error: _rmutex_unlock: rmutex not held Add `-mt' to `CFLAGS' and `CXXFLAGS' and try again. If you are using the SFW version of `gcc' (which comes with Solaris 8), you must add `/opt/sfw/lib' to the environment variable `LD_LIBRARY_PATH' before running configure. If you are using the `gcc' available from `sunfreeware.com', you may have many problems. You should recompile `gcc' and GNU binutils on the machine you will be running them from to avoid any problems. If you get the following error when compiling MySQL with `gcc', it means that your `gcc' is not configured for your version of Solaris: shell> gcc -O3 -g -O2 -DDBUG_OFF -o thr_alarm ... ./thr_alarm.c: In function `signal_hand': ./thr_alarm.c:556: too many arguments to function `sigwait' The proper thing to do in this case is to get the newest version of `gcc' and compile it with your current `gcc' compiler! At least for Solaris 2.5, almost all binary versions of `gcc' have old, unusable include files that will break all programs that use threads (and possibly other programs)! Solaris doesn't provide static versions of all system libraries (`libpthreads' and `libdl'), so you can't compile MySQL with `--static'. If you try to do so, you will get the error: ld: fatal: library -ldl: not found or undefined reference to `dlopen' or cannot find -lrt If too many processes try to connect very rapidly to `mysqld', you will see this error in the MySQL log: Error in accept: Protocol error You might try starting the server with the `--set-variable back_log=50' option as a workaround for this. Please note that `--set-variable=name=value' and `-O name=value' syntax is deprecated as of MySQL 4.0. Use `--back_log=50' instead. *Note Command-line options::. If you are linking your own MySQL client, you might get the following error when you try to execute it: ld.so.1: ./my: fatal: libmysqlclient.so.#: open failed: No such file or directory The problem can be avoided by one of the following methods: * Link the client with the following flag (instead of `-Lpath'): `-Wl,r/full-path-to-libmysqlclient.so'. * Copy `libmysqclient.so' to `/usr/lib'. * Add the pathname of the directory where `libmysqlclient.so' is located to the `LD_RUN_PATH' environment variable before running your client. If you have problems with configure trying to link with `-lz' and you don't have `zlib' installed, you have two options: * If you want to be able to use the compressed communication protocol, you need to get and install zlib from ftp.gnu.org. * Configure with `--with-named-z-libs=no'. If you are using `gcc' and have problems with loading user defined functions (`UDF's) into MySQL, try adding `-lgcc' to the link line for the `UDF'. If you would like MySQL to start automatically, you can copy `support-files/mysql.server' to `/etc/init.d' and create a symbolic link to it named `/etc/rc3.d/S99mysql.server'. As Solaris doesn't support core files for `setuid()' applications, you can't get a core file from `mysqld' if you are using the `--user' option. Solaris 2.7/2.8 Notes ..................... You can normally use a Solaris 2.6 binary on Solaris 2.7 and 2.8. Most of the Solaris 2.6 issues also apply for Solaris 2.7 and 2.8. Note that MySQL Version 3.23.4 and above should be able to autodetect new versions of Solaris and enable workarounds for the following problems! Solaris 2.7 / 2.8 has some bugs in the include files. You may see the following error when you use `gcc': /usr/include/widec.h:42: warning: `getwc' redefined /usr/include/wchar.h:326: warning: this is the location of the previous definition If this occurs, you can do the following to fix the problem: Copy `/usr/include/widec.h' to `.../lib/gcc-lib/os/gcc-version/include' and change line 41 from: #if !defined(lint) && !defined(__lint) to #if !defined(lint) && !defined(__lint) && !defined(getwc) Alternatively, you can edit `/usr/include/widec.h' directly. Either way, after you make the fix, you should remove `config.cache' and run `configure' again! If you get errors like this when you run `make', it's because `configure' didn't detect the `curses.h' file (probably because of the error in `/usr/include/widec.h'): In file included from mysql.cc:50: /usr/include/term.h:1060: syntax error before `,' /usr/include/term.h:1081: syntax error before `;' The solution to this is to do one of the following: * Configure with `CFLAGS=-DHAVE_CURSES_H CXXFLAGS=-DHAVE_CURSES_H ./configure'. * Edit `/usr/include/widec.h' as indicted above and rerun configure. * Remove the `#define HAVE_TERM' line from `config.h' file and run `make' again. If you get a problem that your linker can't find `-lz' when linking your client program, the problem is probably that your `libz.so' file is installed in `/usr/local/lib'. You can fix this by one of the following methods: * Add `/usr/local/lib' to `LD_LIBRARY_PATH'. * Add a link to `libz.so' from `/lib'. * If you are using Solaris 8, you can install the optional zlib from your Solaris 8 CD distribution. * Configure MySQL with the `--with-named-z-libs=no' option. 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::. BSD Notes --------- This section provides information for the various BSD flavours, as well as specific versions within those. FreeBSD Notes ............. FreeBSD 4.x or newer is recommended for running MySQL since the thread package is much more integrated. The easiest and therefore the preferred way to install is to use the mysql-server and mysql-client ports available on `http://www.freebsd.org/'. Using these gives you: * A working MySQL with all optimizations known to work on your version of FreeBSD enabled. * Automatic configuration and build. * Startup scripts installed in /usr/local/etc/rc.d. * Ability to see which files that are installed with pkg_info -L. And to remove them all with pkg_delete if you no longer want MySQL on that machine. It is recommended you use MIT-pthreads on FreeBSD 2.x and native threads on Versions 3 and up. It is possible to run with native threads on some late 2.2.x versions but you may encounter problems shutting down `mysqld'. Unfortunately, certain function calls on FreeBSD are not yet fully thread-safe, most notably the `gethostbyname()' function, which is used by MySQL to convert host names into IP addresses. Under certain circumstances, the `mysqld' process will suddenly cause 100% CPU load and will be unresponsive. If you encounter this, try to start up MySQL using the `--skip-name-resolve' option. Alternatively, you can link MySQL on FreeBSD 4.x against the LinuxThreads library, which avoids a few of the problems that the native FreeBSD thread implementation has. For a very good comparison of LinuxThreads vs. native threads have a look at Jeremy Zawodny's article "FreeBSD or Linux for your MySQL Server?" at `http://jeremy.zawodny.com/blog/archives/000697.html' The known problems when using LinuxThreads on FreeBSD are: * `wait_timeout' is not working (probably signal handling problem in FreeBSD/LinuxThreads). This is supposed to get fixed in FreeBSD 5.0. The symptom is that persistent connections can hang for *a long* time without getting closed done. The MySQL `Makefile's require GNU make (`gmake') to work. If you want to compile MySQL you need to install GNU `make' first. Be sure to have your name resolver setup correct. Otherwise, you may experience resolver delays or failures when connecting to `mysqld'. Make sure that the `localhost' entry in the `/etc/hosts' file is correct (otherwise, you will have problems connecting to the database). The `/etc/hosts' file should start with a line: 127.0.0.1 localhost localhost.your.domain The recommended way to compile and install MySQL on FreeBSD with gcc (2.95.2 and up) is: CC=gcc CFLAGS="-O2 -fno-strength-reduce" \ CXX=gcc CXXFLAGS="-O2 -fno-rtti -fno-exceptions -felide-constructors \ -fno-strength-reduce" \ ./configure --prefix=/usr/local/mysql --enable-assembler gmake gmake install ./scripts/mysql_install_db cd /usr/local/mysql ./bin/mysqld_safe & If you notice that `configure' will use MIT-pthreads, you should read the MIT-pthreads notes. *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. This is fixed by executing these commands: shell> rm config.cache shell> ./configure --with-mit-threads FreeBSD is also known to have a very low default file handle limit. *Note Not enough file handles::. Uncomment the `ulimit -n' section in `mysqld_safe' or raise the limits for the `mysqld' user in /etc/login.conf (and rebuild it with cap_mkdb /etc/login.conf). Also be sure you set the appropriate class for this user in the password file if you are not using the default (use: chpass mysqld-user-name). *Note `mysqld_safe': mysqld_safe. If you have a lot of memory you should consider rebuilding the kernel to allow MySQL to take more than 512M of RAM. Take a look at `option MAXDSIZ' in the LINT config file for more info. If you get problems with the current date in MySQL, setting the `TZ' variable will probably help. *Note Environment variables::. To get a secure and stable system you should only use FreeBSD kernels that are marked `-RELEASE'. NetBSD Notes ............ To compile on NetBSD you need GNU `make'. Otherwise, the compile will crash 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 to 3.23.34 or after running `configure' remove the line `#define HAVE_REALPATH' from `config.h' before running make. Note that the above means that you can't symbolic link a database directories to another database directory or symbolic link a table to another database on BSDI! (Making a symbolic link to another disk is okay). Mac OS X Notes -------------- Mac OS X 10.x ............. MySQL should work without any problems on Mac OS X 10.x (Darwin). You don't need the pthread patches for this OS! This also applies to Mac OS X 10.x Server. Compiling for the Server platform is the same as for the client version of Mac OS X. However please note that MySQL comes preinstalled on the Server! Our binary for Mac OS X is compiled on Darwin 6.3 with the following configure line: CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc \ CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \ -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql \ --with-extra-charsets=complex --enable-thread-safe-client \ --enable-local-infile --disable-shared *Note Mac OS X installation::. Mac OS X Server 1.2 (Rhapsody) .............................. Before trying to configure MySQL on Mac OS X Server 1.2 (aka Rhapsody) you must first install the pthread package from `http://www.prnet.de/RegEx/mysql.html'. *Note Mac OS X installation::. Other Unix Notes ---------------- HP-UX Notes for Binary Distributions .................................... Some of the binary distributions of MySQL for HP-UX are distributed as an HP depot file and as a tar file. To use the depot file you must be running at least HP-UX 10.x to have access to HP's software depot tools. The HP version of MySQL was compiled on an HP 9000/8xx server under HP-UX 10.20, and uses MIT-pthreads. It is known to work well under this configuration. MySQL Version 3.22.26 and newer can also be built with HP's native thread package. Other configurations that may work: * HP 9000/7xx running HP-UX 10.20+ * HP 9000/8xx running HP-UX 10.30 The following configurations almost definitely won't work: * HP 9000/7xx or 8xx running HP-UX 10.x where x < 2 * HP 9000/7xx or 8xx running HP-UX 9.x To install the distribution, use one of the commands here, where `/path/to/depot' is the full pathname of the depot file: * To install everything, including the server, client and development tools: shell> /usr/sbin/swinstall -s /path/to/depot mysql.full * To install only the server: shell> /usr/sbin/swinstall -s /path/to/depot mysql.server * To install only the client package: shell> /usr/sbin/swinstall -s /path/to/depot mysql.client * To install only the development tools: shell> /usr/sbin/swinstall -s /path/to/depot mysql.developer The depot places binaries and libraries in `/opt/mysql' and data in `/var/opt/mysql'. The depot also creates the appropriate entries in `/etc/init.d' and `/etc/rc2.d' to start the server automatically at boot time. Obviously, this entails being `root' to install. To install the HP-UX tar.gz distribution, you must have a copy of GNU `tar'. 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 this may not be safe on HP-UX. The following `configure' line should work with `gcc' 2.95: CFLAGS="-I/opt/dce/include -fpic" \ CXXFLAGS="-I/opt/dce/include -felide-constructors -fno-exceptions \ -fno-rtti" CXX=gcc ./configure --with-pthread \ --with-named-thread-libs='-ldce' --prefix=/usr/local/mysql --disable-shared The following `configure' line should work with `gcc' 3.1: 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: (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' checking for cc option to accept ANSI C... no configure: error: MySQL requires a ANSI C compiler (and a C++ compiler). Try gcc. See the Installation chapter in the Reference Manual. Check that you don't have the path to the K&R compiler before the path to the HP-UX C and C++ compiler. Another reason for not beeing able to compile is that you didn't define the `+DD64' flags above. Another possibility for HP-UX 11 is to use MySQL binaries for HP-UX 10.20. We have received reports from some users that these binaries work fine on HP-UX 11.00. If you encounter problems, be sure to check your HP-UX patch level. IBM-AIX notes ............. Automatic detection of `xlC' is missing from Autoconf, so a `configure' command something like this is needed when compiling MySQL (This example uses the IBM compiler): export CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 " export CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192" export CFLAGS="-I /usr/local/include" export LDFLAGS="-L /usr/local/lib" export CPPFLAGS=$CFLAGS export CXXFLAGS=$CFLAGS ./configure --prefix=/usr/local \ --localstatedir=/var/mysql \ --sysconfdir=/etc/mysql \ --sbindir='/usr/local/bin' \ --libexecdir='/usr/local/bin' \ --enable-thread-safe-client \ --enable-large-files Above are the options used to compile the MySQL distribution that can be found at `http://www-frec.bull.com/'. If you change the `-O3' to `-O2' in the above configure line, you must also remove the `-qstrict' option (this is a limitation in the IBM C compiler). If you are using `gcc' or `egcs' to compile MySQL, you *must* use the `-fno-exceptions' flag, as the exception handling in `gcc'/`egcs' is not thread-safe! (This is tested with `egcs' 1.1.) There are also some known problems with IBM's assembler, which may cause it to generate bad code when used with gcc. We recommend the following `configure' line with `egcs' and `gcc 2.95' on AIX: CC="gcc -pipe -mcpu=power -Wa,-many" \ CXX="gcc -pipe -mcpu=power -Wa,-many" \ CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti" \ ./configure --prefix=/usr/local/mysql --with-low-memory The `-Wa,-many' is necessary for the compile to be successful. IBM is aware of this problem but is in to hurry to fix it because of the workaround available. We don't know if the `-fno-exceptions' is required with `gcc 2.95', but as MySQL doesn't use exceptions and the above option generates faster code, we recommend that you should always use this option with `egcs / gcc'. If you get a problem with assembler code try changing the -mcpu=xxx to match your CPU. Typically power2, power, or powerpc may need to be used, alternatively you might need to use 604 or 604e. I'm not positive but I would think using "power" would likely be safe most of the time, even on a power2 machine. If you don't know what your CPU is then do a "uname -m", this will give you back a string that looks like "000514676700", with a format of xxyyyyyymmss where xx and ss are always 0's, yyyyyy is a unique system ID and mm is the ID of the CPU Planar. A chart of these values can be found at `http://publib.boulder.ibm.com/doc_link/en_US/a_doc_lib/cmds/aixcmds5/uname.htm'. This will give you a machine type and a machine model you can use to determine what type of CPU you have. If you have problems with signals (MySQL dies unexpectedly under high load) you may have found an OS bug with threads and signals. In this case you can tell MySQL not to use signals by configuring with: shell> CFLAGS=-DDONT_USE_THR_ALARM CXX=gcc \ CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti \ -DDONT_USE_THR_ALARM" \ ./configure --prefix=/usr/local/mysql --with-debug --with-low-memory This doesn't affect the performance of MySQL, but has the side effect that you can't kill clients that are "sleeping" on a connection with `mysqladmin kill' or `mysqladmin shutdown'. Instead, the client will die when it issues its next command. On some versions of AIX, linking with `libbind.a' makes `getservbyname' core dump. This is an AIX bug and should be reported to IBM. For AIX 4.2.1 and `gcc' you have to do the following changes. After configuring, edit `config.h' and `include/my_config.h' and change the line that says #define HAVE_SNPRINTF 1 to #undef HAVE_SNPRINTF And finally, in `mysqld.cc' you need to add a prototype for initgoups. #ifdef _AIX41 extern "C" int initgroups(const char *,int); #endif If you need to allocate a lot of memory to the mysqld process, it's not enough to just set 'ulimit -d unlimited'. You may also have to set in `mysqld_safe' something like: export LDR_CNTRL='MAXDATA=0x80000000' You can find more about using a lot of memory at: `http://publib16.boulder.ibm.com/pseries/en_US/aixprggd/genprogc/lrg_prg_support.htm'. SunOS 4 Notes ............. On SunOS 4, MIT-pthreads is needed to compile MySQL, which in turn means you will need GNU `make'. Some SunOS 4 systems have problems with dynamic libraries and `libtool'. You can use the following `configure' line to avoid this problem: shell> ./configure --disable-shared --with-mysqld-ldflags=-all-static When compiling `readline', you may get warnings about duplicate defines. These may be ignored. When compiling `mysqld', there will be some `implicit declaration of function' warnings. These may be ignored. Alpha-DEC-UNIX Notes (Tru64) ............................ If you are using egcs 1.1.2 on Digital Unix, you should upgrade to gcc 2.95.2, as egcs on DEC has some serious bugs! When compiling threaded programs under Digital Unix, the documentation recommends using the `-pthread' option for `cc' and `cxx' and the libraries `-lmach -lexc' (in addition to `-lpthread'). You should run `configure' something like this: CC="cc -pthread" CXX="cxx -pthread -O" \ ./configure --with-named-thread-libs="-lpthread -lmach -lexc -lc" When compiling `mysqld', you may see a couple of warnings like this: mysqld.cc: In function void handle_connections()': mysqld.cc:626: passing long unsigned int *' as argument 3 of accept(int,sockadddr *, int *)' You can safely ignore these warnings. They occur because `configure' can detect only errors, not warnings. If you start the server directly from the command-line, you may have problems with it dying when you log out. (When you log out, your outstanding processes receive a `SIGHUP' signal.) If so, try starting the server like this: shell> nohup mysqld [options] & `nohup' causes the command following it to ignore any `SIGHUP' signal sent from the terminal. Alternatively, start the server by running `mysqld_safe', which invokes `mysqld' using `nohup' for you. *Note `mysqld_safe': mysqld_safe. If you get a problem when compiling mysys/get_opt.c, just remove the line #define _NO_PROTO from the start of that file! If you are using Compaq's CC compiler, the following configure line should work: CC="cc -pthread" CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all -arch host" CXX="cxx -pthread" CXXFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all -arch host \ -noexceptions -nortti" export CC CFLAGS CXX CXXFLAGS ./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 only be able to create threads if you run it as a user with `CAP_SCHED_MGT' privileges (like `root') or give the `mysqld' server this privilege with the following shell command: shell> chcap "CAP_SCHED_MGT+epi" /opt/mysql/libexec/mysqld You may have to undefine some symbols in `config.h' after running `configure' and before compiling. In some Irix implementations, the `alloca()' function is broken. If the `mysqld' server dies on some `SELECT' statements, remove the lines from `config.h' that define `HAVE_ALLOC' and `HAVE_ALLOCA_H'. If `mysqladmin create' doesn't work, remove the line from `config.h' that defines `HAVE_READDIR_R'. You may have to remove the `HAVE_TERM_H' line as well. 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 Comments ========================== Perl support for MySQL is provided by means of the `DBI'/`DBD' client interface. *Note Perl::. The Perl `DBD'/`DBI' client code requires Perl Version 5.6.0 or later. The interface *will not work* if you have an older version of Perl. 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 can fix this by any of the following methods: * Compile the `DBD::mysql' distribution with `perl Makefile.PL -static -config' rather than `perl Makefile.PL'. * Copy `libmysqlclient.so' to the directory where your other shared libraries are located (probably `/usr/lib' or `/lib'). * On Linux you can add the pathname of the directory where `libmysqlclient.so' is located to the `/etc/ld.so.conf' file. * Add the pathname of the directory where `libmysqlclient.so' is located to the `LD_RUN_PATH' environment variable. If you get the following errors from `DBD::mysql', you are probably using `gcc' (or using an old binary compiled with `gcc'): /usr/bin/perl: can't resolve symbol '__moddi3' /usr/bin/perl: can't resolve symbol '__divdi3' Add `-L/usr/lib/gcc-lib/... -lgcc' to the link command when the `mysql.so' library gets built (check the output from `make' for `mysql.so' when you compile the Perl client). The `-L' option should specify the pathname of the directory where `libgcc.a' is located on your system. Another cause of this problem may be that Perl and MySQL aren't both compiled with `gcc'. In this case, you can solve the mismatch by compiling both with `gcc'. 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 user name when you invoke `mysql' and, most likely, a password. If the server runs on a machine other than the one where you log in, you'll also need to specify a hostname. Contact your administrator to find out what connection parameters you should use to connect (that is, what host, user name, and password to use). Once you know the proper parameters, you should be able to connect like this: shell> mysql -h host -u user -p Enter password: ******** The `********' represents your password; enter it when `mysql' displays the `Enter password:' prompt. If that works, you should see some introductory information followed by a `mysql>' prompt: shell> mysql -h host -u user -p Enter password: ******** Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 25338 to server version: 4.0.14-log Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> The prompt tells you that `mysql' is ready for you to enter commands. Some MySQL installations allow users to connect as the anonymous (unnamed) user to the server running on the local host. If this is the case on your machine, you should be able to connect to that server by invoking `mysql' without any options: 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 user name 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 lot more typing involved to load your records initially using several `INSERT' statements rather than a single `LOAD DATA' statement. Retrieving Information from a Table ----------------------------------- The `SELECT' statement is used to pull information from a table. The general form of the statement is: SELECT what_to_select FROM which_table WHERE conditions_to_satisfy; `what_to_select' indicates what you want to see. This can be a list of columns, or `*' to indicate "all columns." `which_table' indicates the table from which you want to retrieve data. The `WHERE' clause is optional. If it's present, `conditions_to_satisfy' specifies conditions that rows must satisfy to qualify for retrieval. Selecting All Data .................. The simplest form of `SELECT' retrieves everything from a table: mysql> SELECT * FROM pet; +----------+--------+---------+------+------------+------------+ | name | owner | species | sex | birth | death | +----------+--------+---------+------+------------+------------+ | Fluffy | Harold | cat | f | 1993-02-04 | NULL | | Claws | Gwen | cat | m | 1994-03-17 | NULL | | Buffy | Harold | dog | f | 1989-05-13 | NULL | | Fang | Benny | dog | m | 1990-08-27 | NULL | | Bowser | Diane | dog | m | 1979-08-31 | 1995-07-29 | | Chirpy | Gwen | bird | f | 1998-09-11 | NULL | | Whistler | Gwen | bird | NULL | 1997-12-09 | NULL | | Slim | Benny | snake | m | 1996-04-29 | NULL | | Puffball | Diane | hamster | f | 1999-03-30 | NULL | +----------+--------+---------+------+------------+------------+ This form of `SELECT' is useful if you want to review your entire table, for instance, after you've just loaded it with your initial dataset. For example, you may happen to think that the birth date for Bowser doesn't seem quite right. Consulting your original pedigree papers, you find that the correct birth year should be 1989, not 1979. There are least a couple of ways to fix this: * Edit the file `pet.txt' to correct the error, then empty the table and reload it using `DELETE' and `LOAD DATA': mysql> DELETE FROM pet; mysql> LOAD DATA LOCAL INFILE "pet.txt" INTO TABLE pet; However, if you do this, you must also re-enter the record for Puffball. * Fix only the erroneous record with an `UPDATE' statement: mysql> UPDATE pet SET birth = "1989-08-31" WHERE name = "Bowser"; The `UPDATE' changes only the record in question and does not require you to reload the table. Selecting Particular Rows ......................... As shown in the preceding section, it is easy to retrieve an entire table. Just omit the `WHERE' clause from the `SELECT' statement. But typically you don't want to see the entire table, particularly when it becomes large. Instead, you're usually more interested in answering a particular question, in which case you specify some constraints on the information you want. Let's look at some selection queries in terms of questions about your pets that they answer. You can select only particular rows from your table. For example, if you want to verify the change that you made to Bowser's birth date, select Bowser's record like this: mysql> SELECT * FROM pet WHERE name = "Bowser"; +--------+-------+---------+------+------------+------------+ | name | owner | species | sex | birth | death | +--------+-------+---------+------+------------+------------+ | Bowser | Diane | dog | m | 1989-08-31 | 1995-07-29 | +--------+-------+---------+------+------------+------------+ The output confirms that the year is correctly recorded now as 1989, not 1979. String comparisons normally are case-insensitive, so you can specify the name as `"bowser"', `"BOWSER"', etc. The query result will be the same. You can specify conditions on any column, not just `name'. For example, if you want to know which animals were born after 1998, test the `birth' column: mysql> SELECT * FROM pet WHERE birth >= "1998-1-1"; +----------+-------+---------+------+------------+-------+ | name | owner | species | sex | birth | death | +----------+-------+---------+------+------------+-------+ | Chirpy | Gwen | bird | f | 1998-09-11 | NULL | | Puffball | Diane | hamster | f | 1999-03-30 | NULL | +----------+-------+---------+------+------------+-------+ You can combine conditions, for example, to locate female dogs: mysql> SELECT * FROM pet WHERE species = "dog" AND sex = "f"; +-------+--------+---------+------+------------+-------+ | name | owner | species | sex | birth | death | +-------+--------+---------+------+------------+-------+ | Buffy | Harold | dog | f | 1989-05-13 | NULL | +-------+--------+---------+------+------------+-------+ The preceding query uses the `AND' logical operator. There is also an `OR' operator: mysql> SELECT * FROM pet WHERE species = "snake" OR species = "bird"; +----------+-------+---------+------+------------+-------+ | name | owner | species | sex | birth | death | +----------+-------+---------+------+------------+-------+ | Chirpy | Gwen | bird | f | 1998-09-11 | NULL | | Whistler | Gwen | bird | NULL | 1997-12-09 | NULL | | Slim | Benny | snake | m | 1996-04-29 | NULL | +----------+-------+---------+------+------------+-------+ `AND' and `OR' may be intermixed, though `AND' has higher precedence than `OR'. If you use both operators, it's a good idea to use parentheses to indicate explicitly how conditions should be grouped: mysql> SELECT * FROM pet WHERE (species = "cat" AND sex = "m") -> OR (species = "dog" AND sex = "f"); +-------+--------+---------+------+------------+-------+ | name | owner | species | sex | birth | death | +-------+--------+---------+------+------------+-------+ | Claws | Gwen | cat | m | 1994-03-17 | NULL | | Buffy | Harold | dog | f | 1989-05-13 | NULL | +-------+--------+---------+------+------------+-------+ Selecting Particular Columns ............................ If you don't want to see entire rows from your table, just name the columns in which you're interested, separated by commas. For example, if you want to know when your animals were born, select the `name' and `birth' columns: mysql> SELECT name, birth FROM pet; +----------+------------+ | name | birth | +----------+------------+ | Fluffy | 1993-02-04 | | Claws | 1994-03-17 | | Buffy | 1989-05-13 | | Fang | 1990-08-27 | | Bowser | 1989-08-31 | | Chirpy | 1998-09-11 | | Whistler | 1997-12-09 | | Slim | 1996-04-29 | | Puffball | 1999-03-30 | +----------+------------+ To find out who owns pets, use this query: mysql> SELECT owner FROM pet; +--------+ | owner | +--------+ | Harold | | Gwen | | Harold | | Benny | | Diane | | Gwen | | Gwen | | Benny | | Diane | +--------+ However, notice that the query simply retrieves the `owner' field from each record, and some of them appear more than once. To minimise the output, retrieve each unique output record just once by adding the keyword `DISTINCT': mysql> SELECT DISTINCT owner FROM pet; +--------+ | owner | +--------+ | Benny | | Diane | | Gwen | | Harold | +--------+ You can use a `WHERE' clause to combine row selection with column selection. For example, to get birth dates for dogs and cats only, use this query: mysql> SELECT name, species, birth FROM pet -> WHERE species = "dog" OR species = "cat"; +--------+---------+------------+ | name | species | birth | +--------+---------+------------+ | Fluffy | cat | 1993-02-04 | | Claws | cat | 1994-03-17 | | Buffy | dog | 1989-05-13 | | Fang | dog | 1990-08-27 | | Bowser | dog | 1989-08-31 | +--------+---------+------------+ Sorting Rows ............ You may have noticed in the preceding examples that the result rows are displayed in no particular order. It's often easier to examine query output when the rows are sorted in some meaningful way. To sort a result, use an `ORDER BY' clause. Here are animal birthdays, sorted by date: mysql> SELECT name, birth FROM pet ORDER BY birth; +----------+------------+ | name | birth | +----------+------------+ | Buffy | 1989-05-13 | | Bowser | 1989-08-31 | | Fang | 1990-08-27 | | Fluffy | 1993-02-04 | | Claws | 1994-03-17 | | Slim | 1996-04-29 | | Whistler | 1997-12-09 | | Chirpy | 1998-09-11 | | Puffball | 1999-03-30 | +----------+------------+ On character type columns, sorting--like all other comparison operations--is normally performed in a case-insensitive fashion. This means that the order will be undefined for columns that are identical except for their case. You can force a case-sensitive sort for a column by using the `BINARY' cast: `ORDER BY BINARY col_name'. The default sort order is ascending, with smallest values first. To sort in reverse (descending) order, add the `DESC' keyword to the name of the column you are sorting by: mysql> SELECT name, birth FROM pet ORDER BY birth DESC; +----------+------------+ | name | birth | +----------+------------+ | Puffball | 1999-03-30 | | Chirpy | 1998-09-11 | | Whistler | 1997-12-09 | | Slim | 1996-04-29 | | Claws | 1994-03-17 | | Fluffy | 1993-02-04 | | Fang | 1990-08-27 | | Bowser | 1989-08-31 | | Buffy | 1989-05-13 | +----------+------------+ You can sort on multiple columns, and you can sort columns in different directions. For example, to sort by type of animal in ascending order, then by birth date within animal type in descending order (youngest animals first), use the following query: mysql> SELECT name, species, birth FROM pet ORDER BY species, birth DESC; +----------+---------+------------+ | name | species | birth | +----------+---------+------------+ | Chirpy | bird | 1998-09-11 | | Whistler | bird | 1997-12-09 | | Claws | cat | 1994-03-17 | | Fluffy | cat | 1993-02-04 | | Fang | dog | 1990-08-27 | | Bowser | dog | 1989-08-31 | | Buffy | dog | 1989-05-13 | | Puffball | hamster | 1999-03-30 | | Slim | snake | 1996-04-29 | +----------+---------+------------+ Note that the `DESC' keyword applies only to the column name immediately preceding it (`birth'); it does not affect the `species' column sort order. Date Calculations ................. MySQL provides several functions that you can use to perform calculations on dates, for example, to calculate ages or extract parts of dates. To determine how many years old each of your pets is, compute the difference in the year part of the current date and the birth date, then subtract one if the current date occurs earlier in the calendar year than the birth date. The following query shows, for each pet, the birth date, the current date, and the age in years. mysql> SELECT name, birth, CURDATE(), -> (YEAR(CURDATE())-YEAR(birth)) -> - (RIGHT(CURDATE(),5) AS age -> FROM pet; +----------+------------+------------+------+ | name | birth | CURDATE() | age | +----------+------------+------------+------+ | Fluffy | 1993-02-04 | 2003-08-19 | 10 | | Claws | 1994-03-17 | 2003-08-19 | 9 | | Buffy | 1989-05-13 | 2003-08-19 | 14 | | Fang | 1990-08-27 | 2003-08-19 | 12 | | Bowser | 1989-08-31 | 2003-08-19 | 13 | | Chirpy | 1998-09-11 | 2003-08-19 | 4 | | Whistler | 1997-12-09 | 2003-08-19 | 5 | | Slim | 1996-04-29 | 2003-08-19 | 7 | | Puffball | 1999-03-30 | 2003-08-19 | 4 | +----------+------------+------------+------+ Here, `YEAR()' pulls out the year part of a date and `RIGHT()' pulls off the rightmost five characters that represent the `MM-DD' (calendar year) part of the date. The part of the expression that compares the `MM-DD' values evaluates to 1 or 0, which adjusts the year difference down a year if `CURDATE()' occurs earlier in the year than `birth'. The full expression is somewhat ungainly, so an alias (`age') is used to make the output column label more meaningful. The query works, but the result could be scanned more easily if the rows were presented in some order. This can be done by adding an `ORDER BY name' clause to sort the output by name: mysql> SELECT name, birth, CURDATE(), -> (YEAR(CURDATE())-YEAR(birth)) -> - (RIGHT(CURDATE(),5) AS age -> FROM pet ORDER BY name; +----------+------------+------------+------+ | name | birth | CURDATE() | age | +----------+------------+------------+------+ | Bowser | 1989-08-31 | 2003-08-19 | 13 | | Buffy | 1989-05-13 | 2003-08-19 | 14 | | Chirpy | 1998-09-11 | 2003-08-19 | 4 | | Claws | 1994-03-17 | 2003-08-19 | 9 | | Fang | 1990-08-27 | 2003-08-19 | 12 | | Fluffy | 1993-02-04 | 2003-08-19 | 10 | | Puffball | 1999-03-30 | 2003-08-19 | 4 | | Slim | 1996-04-29 | 2003-08-19 | 7 | | Whistler | 1997-12-09 | 2003-08-19 | 5 | +----------+------------+------------+------+ To sort the output by `age' rather than `name', just use a different `ORDER BY' clause: mysql> SELECT name, birth, CURDATE(), -> (YEAR(CURDATE())-YEAR(birth)) -> - (RIGHT(CURDATE(),5) AS age -> FROM pet ORDER BY age; +----------+------------+------------+------+ | name | birth | CURDATE() | age | +----------+------------+------------+------+ | Chirpy | 1998-09-11 | 2003-08-19 | 4 | | Puffball | 1999-03-30 | 2003-08-19 | 4 | | Whistler | 1997-12-09 | 2003-08-19 | 5 | | Slim | 1996-04-29 | 2003-08-19 | 7 | | Claws | 1994-03-17 | 2003-08-19 | 9 | | Fluffy | 1993-02-04 | 2003-08-19 | 10 | | Fang | 1990-08-27 | 2003-08-19 | 12 | | Bowser | 1989-08-31 | 2003-08-19 | 13 | | Buffy | 1989-05-13 | 2003-08-19 | 14 | +----------+------------+------------+------+ A similar query can be used to determine age at death for animals that have died. You determine which animals these are by checking whether the `death' value is `NULL'. Then, for those with non-`NULL' values, compute the difference between the `death' and `birth' values: mysql> SELECT name, birth, death, -> (YEAR(death)-YEAR(birth)) - (RIGHT(death,5) AS age -> FROM pet WHERE death IS NOT NULL ORDER BY age; +--------+------------+------------+------+ | name | birth | death | age | +--------+------------+------------+------+ | Bowser | 1989-08-31 | 1995-07-29 | 5 | +--------+------------+------------+------+ The query uses `death IS NOT NULL' rather than `death <> NULL' because `NULL' is a special value that cannot be compared using the usual comparison operators. This is discussed later. *Note Working with `NULL': Working with NULL. What if you want to know which animals have birthdays next month? For this type of calculation, year and day are irrelevant; you simply want to extract the month part of the `birth' column. MySQL provides several date-part extraction functions, such as `YEAR()', `MONTH()', and `DAYOFMONTH()'. `MONTH()' is the appropriate function here. To see how it works, run a simple query that displays the value of both `birth' and `MONTH(birth)': mysql> SELECT name, birth, MONTH(birth) FROM pet; +----------+------------+--------------+ | name | birth | MONTH(birth) | +----------+------------+--------------+ | Fluffy | 1993-02-04 | 2 | | Claws | 1994-03-17 | 3 | | Buffy | 1989-05-13 | 5 | | Fang | 1990-08-27 | 8 | | Bowser | 1989-08-31 | 8 | | Chirpy | 1998-09-11 | 9 | | Whistler | 1997-12-09 | 12 | | Slim | 1996-04-29 | 4 | | Puffball | 1999-03-30 | 3 | +----------+------------+--------------+ Finding animals with birthdays in the upcoming month is easy, too. Suppose the current month is April. Then the month value is `4' and you look for animals born in May (month `5') like this: mysql> SELECT name, birth FROM pet WHERE MONTH(birth) = 5; +-------+------------+ | name | birth | +-------+------------+ | Buffy | 1989-05-13 | +-------+------------+ There is a small complication if the current month is December, of course. You don't just add one to the month number (`12') and look for animals born in month `13', because there is no such month. Instead, you look for animals born in January (month `1'). You can even write the query so that it works no matter what the current month is. That way you don't have to use a particular month number in the query. `DATE_ADD()' allows you to add a time interval to a given date. If you add a month to the value of `CURDATE()', then extract the month part with `MONTH()', the result produces the month in which to look for birthdays: mysql> SELECT name, birth FROM pet -> WHERE MONTH(birth) = MONTH(DATE_ADD(CURDATE(), INTERVAL 1 MONTH)); A different way to accomplish the same task is to add `1' to get the next month after the current one (after using the modulo function (`MOD') to wrap around the month value to `0' if it is currently `12'): mysql> SELECT name, birth FROM pet -> WHERE MONTH(birth) = MOD(MONTH(CURDATE()), 12) + 1; Note that `MONTH' returns a number between `1' and `12'. And `MOD(something,12)' returns a number between `0' and `11'. So the addition has to be after the `MOD()', otherwise we would go from November (`11') to January (`1'). Working with `NULL' Values .......................... The `NULL' value can be surprising until you get used to it. Conceptually, `NULL' means missing value or unknown value and it is treated somewhat differently than other values. To test for `NULL', you cannot use the arithmetic comparison operators such as `=', `<', or `<>'. To demonstrate this for yourself, try the following query: mysql> SELECT 1 = NULL, 1 <> NULL, 1 < NULL, 1 > NULL; +----------+-----------+----------+----------+ | 1 = NULL | 1 <> NULL | 1 < NULL | 1 > NULL | +----------+-----------+----------+----------+ | NULL | NULL | NULL | NULL | +----------+-----------+----------+----------+ Clearly you get no meaningful results from these comparisons. Use the `IS NULL' and `IS NOT NULL' operators instead: mysql> SELECT 1 IS NULL, 1 IS NOT NULL; +-----------+---------------+ | 1 IS NULL | 1 IS NOT NULL | +-----------+---------------+ | 0 | 1 | +-----------+---------------+ Note that in MySQL, `0' or `NULL' means false and anything else means true. The default truth value from a boolean operation is `1'. This special treatment of `NULL' is why, in the previous section, it was necessary to determine which animals are no longer alive using `death IS NOT NULL' instead of `death <> NULL'. Two `NULL' values are regarded as equal in a `GROUP BY'. When doing an `ORDER BY', `NULL' values are presented first if you do `ORDER BY ... ASC' and last if you do `ORDER BY ... DESC'. Note that MySQL 4.0.2 to 4.0.10 incorrectly always sorts `NULL' values first regardless of the sort direction. Pattern Matching ................ MySQL provides standard SQL pattern matching as well as a form of pattern matching based on extended regular expressions similar to those used by Unix utilities such as `vi', `grep', and `sed'. SQL pattern matching allows you to use `_' to match any single character and `%' to match an arbitrary number of characters (including zero characters). In MySQL, SQL patterns are case-insensitive by default. Some examples are shown here. Note that you do not use `=' or `<>' when you use SQL patterns; use the `LIKE' or `NOT LIKE' comparison operators instead. To find names beginning with `b': mysql> SELECT * FROM pet WHERE name LIKE "b%"; +-----