Internet Magazine 2004 July/INTERNET119.ISO/pc/software/windows/building/mysql/data1.cab/Documentation/Docs/manual.txt

Text File | 2004-02-11 | 2.9 MB | 74,780 lines

START-INFO-DIR-ENTRY
* mysql: (mysql).               MySQL documentation.
END-INFO-DIR-ENTRY

Table of Contents
*****************


General Information
  About This Manual
    Conventions Used in This Manual
  Overview of the MySQL Database Management System
    History of MySQL
    The Main Features of MySQL
    MySQL Stability
    How Big MySQL Tables Can Be
    Year 2000 Compliance
  Overview of MySQL AB
    The Business Model and Services of MySQL AB
      Support
      Training and Certification
      Consulting
      Commercial Licenses
      Partnering
    Contact Information
  MySQL Support and Licensing
    Support Offered by MySQL AB
    Copyrights and Licenses Used by MySQL
    MySQL Licenses
      Using the MySQL Software Under a Commercial License
      Using the MySQL Software for Free Under GPL
    MySQL AB Logos and Trademarks
      The Original MySQL Logo
      MySQL Logos that may be Used Without Written Permission
      When You Need Written Permission to Use MySQL Logos
      MySQL AB Partnership Logos
      Using the Word `MySQL' in Printed Text or Presentations
      Using the Word `MySQL' in Company and Product Names
  MySQL Development Roadmap
    MySQL 4.0 in a Nutshell
      Features Available in MySQL 4.0
      The Embedded MySQL Server
    MySQL 4.1 in a Nutshell
      Features Available in MySQL 4.1
      Stepwise Rollout
      Ready for Immediate Development Use
    MySQL 5.0, The Next Development Release
  MySQL and the Future (The TODO)
    New Features Planned for 4.1
    New Features Planned for 5.0
    New Features Planned for 5.1
    New Features Planned for the Near Future
    New Features Planned for the Mid-Term Future
    New Features We Don't Plan to Implement
  MySQL Information Sources
    MySQL Mailing Lists
      The MySQL Mailing Lists
      Asking Questions or Reporting Bugs
      How to Report Bugs or Problems
      Guidelines for Answering Questions on the Mailing List
    MySQL Community Support on IRC (Internet Relay Chat)
  MySQL Standards Compliance
    What Standards MySQL Follows
    Selecting SQL Modes
    Running MySQL in ANSI Mode
    MySQL Extensions to the SQL-92 Standard
    MySQL Differences Compared to SQL-92
      Subqueries
      `SELECT INTO TABLE'
      Transactions and Atomic Operations
      Stored Procedures and Triggers
      Foreign Keys
      Views
      `--' as the Start of a Comment
    How MySQL Deals with Constraints
      Constraint PRIMARY KEY / UNIQUE
      Constraint `NOT NULL' and `DEFAULT' values
      Constraint `ENUM' and `SET'
    Known Errors and Design Deficiencies in MySQL
      Errors in 3.23 Fixed in a Later MySQL Version
      Errors in 4.0 Fixed in a Later MySQL Version
      Open Bugs / Design Deficiencies in MySQL

Installing MySQL
  General Installation Issues
    Operating Systems Supported by MySQL
    Choosing Which MySQL Distribution to Install
      Choosing Which Version of MySQL to Install
      Choosing a Distribution Format
      How and When Updates Are Released
      Release Philosophy--No Known Bugs in Releases
      MySQL Binaries Compiled by MySQL AB
    How to Get MySQL
    Verifying Package Integrity Using MD5 Checksums or `GnuPG'
    Installation Layouts
  Standard MySQL Installation Using a Binary Distribution
    Installing MySQL on Windows
      Windows System Requirements
      Installing a Windows Binary Distribution
      Preparing the Windows MySQL Environment
      Selecting a Windows Server
      Starting the Server for the First Time
      Starting MySQL from the Windows Command Line
      Starting MySQL as a Windows Service
      Running MySQL Client Programs on Windows
      MySQL on Windows Compared to MySQL on Unix
    Installing MySQL on Linux
    Installing MySQL on Mac OS X
    Installing MySQL on NetWare
    Installing MySQL on HP-UX
    Installing MySQL on Other Unix-like Systems
  MySQL Installation Using a Source Distribution
    Quick Source Installation Overview
    Typical `configure' Options
    Installing from the Development Source Tree
    Dealing With Problems Compiling MySQL
    MIT-pthreads Notes
    Installing MySQL from Source on Windows
      Building MySQL Using VC++
      Creating a Windows Source Package from the Latest Development Source
    Compiling MySQL Clients on Windows
  Post-installation Setup and Testing
    Windows Post-installation Procedures
    Unix Post-installation Procedures
      Problems Running `mysql_install_db'
      Starting and Stopping MySQL Automatically
      Starting and Troubleshooting the MySQL Server
  Upgrading/Downgrading MySQL
    Upgrading from Version 4.1 to 5.0
    Upgrading from Version 4.0 to 4.1
    Upgrading from Version 3.23 to 4.0
    Upgrading from Version 3.22 to 3.23
    Upgrading from Version 3.21 to 3.22
    Upgrading from Version 3.20 to 3.21
    Upgrading MySQL under Windows
    Upgrading the Grant Tables
    Copying MySQL Databases to Another Machine
  Operating System Specific Notes
    Linux Notes
      Linux Operating System Notes
      Linux Binary Distribution Notes
      Linux Source Distribution Notes
      Linux Post-installation Notes
      Linux x86 Notes
      Linux SPARC Notes
      Linux Alpha Notes
      Linux PowerPC Notes
      Linux MIPS Notes
      Linux IA-64 Notes
    Mac OS X Notes
      Mac OS X 10.x (Darwin)
      Mac OS X Server 1.2 (Rhapsody)
    Solaris Notes
      Solaris 2.7/2.8 Notes
      Solaris x86 Notes
    BSD Notes
      FreeBSD Notes
      NetBSD Notes
      OpenBSD 2.5 Notes
      OpenBSD 2.8 Notes
      BSD/OS Version 2.x Notes
      BSD/OS Version 3.x Notes
      BSD/OS Version 4.x Notes
    Other Unix Notes
      HP-UX Version 10.20 Notes
      HP-UX Version 11.x Notes
      IBM-AIX notes
      SunOS 4 Notes
      Alpha-DEC-UNIX Notes (Tru64)
      Alpha-DEC-OSF/1 Notes
      SGI Irix Notes
      SCO Notes
      SCO UnixWare Version 7.1.x Notes
    OS/2 Notes
    BeOS Notes
  Perl Installation Notes
    Installing Perl on Unix
    Installing ActiveState Perl on Windows
    Problems Using the Perl `DBI'/`DBD' Interface

MySQL Tutorial
  Connecting to and Disconnecting from the Server
  Entering Queries
  Creating and Using a Database
    Creating and Selecting a Database
    Creating a Table
    Loading Data into a Table
    Retrieving Information from a Table
      Selecting All Data
      Selecting Particular Rows
      Selecting Particular Columns
      Sorting Rows
      Date Calculations
      Working with `NULL' Values
      Pattern Matching
      Counting Rows
      Using More Than one Table
  Getting Information About Databases and Tables
  Using `mysql' in Batch Mode
  Examples of Common Queries
    The Maximum Value for a Column
    The Row Holding the Maximum of a Certain Column
    Maximum of Column per Group
    The Rows Holding the Group-wise Maximum of a Certain Field
    Using User Variables
    Using Foreign Keys
    Searching on Two Keys
    Calculating Visits Per Day
    Using `AUTO_INCREMENT'
  Queries from the Twin Project
    Find All Non-distributed Twins
    Show a Table of Twin Pair Status
  Using MySQL with Apache

Using MySQL Programs
  Overview of MySQL Programs
  Invoking MySQL Programs
  Specifying Program Options
    Using Options on the Command Line
    Using Option Files
    Using Environment Variables to Specify Options
    Using Options to Set Program Variables

Database Administration
  The MySQL Server and Server Startup Scripts
    Overview of the Server-Side Scripts and Utilities
    `mysqld-max', An Extended `mysqld' Server
    `mysqld_safe', The Wrapper Around `mysqld'
    `mysql.server', A Server Startup Script for Run Directories
    `mysqld_multi', A Program for Managing Multiple MySQL Servers
  Configuring MySQL
    `mysqld' Command-line Options
    The Server SQL Mode
  General Security Issues
    General Security Guidelines
    Making MySQL Secure Against Attackers
    Startup Options for `mysqld' Concerning Security
    Security Issues with `LOAD DATA LOCAL'
  The MySQL Access Privilege System
    What the Privilege System Does
    How the Privilege System Works
    Privileges Provided by MySQL
    Connecting to the MySQL Server
    Access Control, Stage 1: Connection Verification
    Access Control, Stage 2: Request Verification
    Password Hashing in MySQL 4.1
    Causes of `Access denied' Errors
  MySQL User Account Management
    MySQL Usernames and Passwords
    When Privilege Changes Take Effect
    Setting Up the Initial MySQL Privileges
    Adding New Users to MySQL
    Deleting Users from MySQL
    Limiting user resources
    Setting Up Passwords
    Keeping Your Password Secure
    Using Secure Connections
      Basics
      Requirements
      Setting Up SSL Certificates for MySQL
      SSL `GRANT' Options
      SSL Command-line Options
      Connecting to MySQL Remotely from Windows with SSH
  Disaster Prevention and Recovery
    Database Backups
    Using `myisamchk' for Table Maintenance and Crash Recovery
      `myisamchk' Invocation Syntax
      General Options for `myisamchk'
      Check Options for `myisamchk'
      Repair Options for myisamchk
      Other Options for `myisamchk'
      `myisamchk' Memory Usage
      Using `myisamchk' for Crash Recovery
      How to Check Tables for Errors
      How to Repair Tables
      Table Optimization
    Setting Up a Table Maintenance Regimen
    Getting Information About a Table
  MySQL Localization and International Usage
    The Character Set Used for Data and Sorting
      German character set
    Non-English Error Messages
    Adding a New Character Set
    The Character Definition Arrays
    String Collating Support
    Multi-byte Character Support
    Problems With Character Sets
  The MySQL Log Files
    The Error Log
    The General Query Log
    The Update Log
    The Binary Log
    The Slow Query Log
    Log File Maintenance
  Running Multiple MySQL Servers on the Same Machine
    Running Multiple Servers on Windows
      Starting Multiple Windows Servers at the Command Line
      Starting Multiple Windows Servers as Services
    Running Multiple Servers on Unix
    Using Client Programs in a Multiple-Server Environment

Replication in MySQL
  Introduction to Replication
  Replication Implementation Overview
  Replication Implementation Details
  How to Set Up Replication
  Upgrading a Replication Setup - Mixing Different MySQL Versions
  Replication Features and Known Problems
  Replication Startup Options
  Replication FAQ
  Troubleshooting Replication
  Reporting Replication Bugs

MySQL Optimization
  Optimization Overview
    MySQL Design Limitations/Tradeoffs
    Portability
    What We Have Used MySQL For
    The MySQL Benchmark Suite
    Using Your Own Benchmarks
  Optimizing `SELECT' Statements and Other Queries
    `EXPLAIN' Syntax (Get Information About a `SELECT')
    Estimating Query Performance
    Speed of `SELECT' Queries
    How MySQL Optimizes `WHERE' Clauses
    How MySQL Optimizes `OR' Clauses
    How MySQL Optimizes `IS NULL'
    How MySQL Optimizes `DISTINCT'
    How MySQL Optimizes `LEFT JOIN' and `RIGHT JOIN'
    How MySQL Optimizes `ORDER BY'
    How MySQL Optimizes `LIMIT'
    Speed of `INSERT' Queries
    Speed of `UPDATE' Queries
    Speed of `DELETE' Queries
    Other Optimization Tips
  Locking Issues
    How MySQL Locks Tables
    Table Locking Issues
  Optimizing Database Structure
    Design Choices
    Get Your Data as Small as Possible
    How MySQL Uses Indexes
    Column Indexes
    Multiple-Column Indexes
    The MyISAM Key Cache
      Shared Key Cache Access
      Multiple Key Caches
      Midpoint Insertion Strategy
      Index Preloading
      Key Cache Block Size
      Restructuring a Key Cache
    How MySQL Counts Open Tables
    How MySQL Opens and Closes Tables
    Drawbacks to Creating Large Numbers of Tables in the Same Database
  Optimizing the MySQL Server
    System/Compile Time and Startup Parameter Tuning
    Tuning Server Parameters
    How Compiling and Linking Affects the Speed of MySQL
    How MySQL Uses Memory
    How MySQL uses DNS
    `SET' Syntax
  Disk Issues
    Using Symbolic Links
      Using Symbolic Links for Databases on Unix
      Using Symbolic Links for Tables on Unix
      Using Symbolic Links for Databases on Windows

MySQL Client and Utility Programs
  Overview of the Client-Side Scripts and Utilities
  `mysql', The Command-line Tool
    How to Run SQL Commands from a Text File
  `mysqlcc', The MySQL Control Center
  `mysqladmin', Administering a MySQL Server
  `mysqlbinlog', Executing the queries from a binary log
  Using `mysqlcheck' for Table Maintenance and Crash Recovery
  `mysqldump', Dumping Table Structure and Data
  `mysqlhotcopy', Copying MySQL Databases and Tables
  `mysqlimport', Importing Data from Text Files
  `mysqlshow', Showing Databases, Tables, and Columns
  `myisampack', The MySQL Compressed Read-only Table Generator
  `mysql_config', Get compile options for compiling clients
  `perror', Explaining Error Codes

MySQL Language Reference

Language Structure
  Literal Values
    Strings
    Numbers
    Hexadecimal Values
    Boolean Values
    `NULL' Values
  Database, Table, Index, Column, and Alias Names
    Identifier Qualifiers
    Identifier Case Sensitivity
  User Variables
  System Variables
    Dynamic System Variables
    Structured System Variables
  Comment Syntax
  Treatment of Reserved Words in MySQL

Column Types
  Numeric Types
  Date and Time Types
    Y2K Issues and Date Types
    The `DATETIME', `DATE', and `TIMESTAMP' Types
    The `TIME' Type
    The `YEAR' Type
  String Types
    The `CHAR' and `VARCHAR' Types
    The `BLOB' and `TEXT' Types
    The `ENUM' Type
    The `SET' Type
  Choosing the Right Type for a Column
  Using Column Types from Other Database Engines
  Column Type Storage Requirements

Functions and Operators
  Non-Type-Specific Operators and Functions
    Parentheses
    Comparison Operators
    Logical Operators
    Control Flow Functions
  String Functions
    String Comparison Functions
    Case-Sensitivity
  Numeric Functions
    Arithmetic Operations
    Mathematical Functions
  Date and Time Functions
  Cast Functions
  Other Functions
    Bit Functions
    Encryption Functions
    Information Functions
    Miscellaneous Functions
  Functions and Modifiers for Use with `GROUP BY' Clauses
    `GROUP BY' Functions
    `GROUP BY' Modifiers
    `GROUP BY' with Hidden Fields

SQL Statement Syntax
  Data Manipulation Statements
    `DELETE' Syntax
    `DO' Syntax
    `HANDLER' Syntax
    `INSERT' Syntax
      `INSERT ... SELECT' Syntax
      `INSERT DELAYED' Syntax
    `LOAD DATA INFILE' Syntax
    `REPLACE' Syntax
    `SELECT' Syntax
      `JOIN' Syntax
      `UNION' Syntax
    Subquery Syntax
      The Subquery as Scalar Operand
      Comparisons Using Subqueries
      Subqueries with `ANY', `IN', and `SOME'
      Subqueries with `ALL'
      Correlated Subqueries
      `EXISTS' and `NOT EXISTS'
      Row Subqueries
      Subqueries in the `FROM' clause
      Subquery Errors
      Optimizing Subqueries
      Rewriting Subqueries for Earlier MySQL Versions
    `TRUNCATE' Syntax
    `UPDATE' Syntax
  Data Definition Statements
    `ALTER DATABASE' Syntax
    `ALTER TABLE' Syntax
    `CREATE DATABASE' Syntax
    `CREATE INDEX' Syntax
    `CREATE TABLE' Syntax
      Silent Column Specification Changes
    `DROP DATABASE' Syntax
    `DROP INDEX' Syntax
    `DROP TABLE' Syntax
    `RENAME TABLE' Syntax
  Basic MySQL User Utility Statements
    `DESCRIBE' Syntax (Get Information About Columns)
    `USE' Syntax
  MySQL Transactional and Locking Statements
    `START TRANSACTION', `COMMIT', and `ROLLBACK' Syntax
    Statements That Cannot Be Rolled Back
    Statements That Cause an Implicit Commit
    `SAVEPOINT' and `ROLLBACK TO SAVEPOINT' Syntax
    `LOCK TABLES' and `UNLOCK TABLES' Syntax
    `SET TRANSACTION' Syntax
  Database Administration Statements
    Account Management Statements
      `GRANT' and `REVOKE' Syntax
    Table Maintenance Statements
      `ANALYZE TABLE' Syntax
      `BACKUP TABLE' Syntax
      `CHECK TABLE' Syntax
      `CHECKSUM TABLE' Syntax
      `OPTIMIZE TABLE' Syntax
      `REPAIR TABLE' Syntax
      `RESTORE TABLE' Syntax
    `SHOW' Syntax
      Retrieving Information about Database, Tables, Columns, and Indexes
      `SHOW TABLE STATUS'
      `SHOW STATUS'
      `SHOW VARIABLES'
      `SHOW [BDB] LOGS'
      `SHOW PROCESSLIST'
      `SHOW GRANTS'
      `SHOW CREATE TABLE'
      `SHOW WARNINGS | ERRORS'
      `SHOW TABLE TYPES'
      `SHOW PRIVILEGES'
    Other Administrative Statements
      `CACHE INDEX' Syntax
      `FLUSH' Syntax
      `KILL' Syntax
      `LOAD INDEX INTO CACHE' Syntax
      `PURGE MASTER LOGS' Syntax
      `RESET' Syntax
  Replication Statements
    SQL Statements for Controlling Master Servers
      `PURGE MASTER LOGS'
      `RESET MASTER'
      `SET SQL_LOG_BIN'
      `SHOW BINLOG EVENTS'
      `SHOW MASTER STATUS'
      `SHOW MASTER LOGS'
      `SHOW SLAVE HOSTS'
    SQL Statements for Controlling Slave Servers
      `CHANGE MASTER TO'
      `LOAD DATA FROM MASTER'
      `LOAD TABLE tbl_name FROM MASTER'
      `MASTER_POS_WAIT()'
      `RESET SLAVE'
      `SET GLOBAL SQL_SLAVE_SKIP_COUNTER'
      `SHOW SLAVE STATUS'
      `START SLAVE'
      `STOP SLAVE'
  MySQL Full-text Search
    Full-text Restrictions
    Fine-tuning MySQL Full-text Search
    Full-text Search TODO
  MySQL Query Cache
    How the Query Cache Operates
    Query Cache Configuration
    Query Cache Options in `SELECT'
    Query Cache Status and Maintenance

MySQL Table Types
  `MyISAM' Tables
    Space Needed for Keys
    `MyISAM' Table Formats
      Static (Fixed-length) Table Characteristics
      Dynamic Table Characteristics
      Compressed Table Characteristics
    `MyISAM' Table Problems
      Corrupted `MyISAM' Tables
      Clients is using or hasn't closed the table properly
  `MERGE' Tables
    `MERGE' Table Problems
  `HEAP' Tables
  `InnoDB' Tables
    InnoDB Tables Overview
    InnoDB in MySQL Version 3.23
    InnoDB Startup Options
    Creating InnoDB Tablespace
      If Something Goes Wrong in Database Creation
    Creating InnoDB Tables
      Converting MyISAM Tables to InnoDB
      `FOREIGN KEY' Constraints
      Multiple tablespaces - putting each table into its own .ibd file
    Adding and Removing InnoDB Data and Log Files
    Backing up and Recovering an InnoDB Database
      Forcing recovery
      Checkpoints
    Moving an InnoDB Database to Another Machine
    InnoDB Transaction Model and Locking
      InnoDB and `SET ... TRANSACTION ISOLATION LEVEL ...'
      Consistent Non-Locking Read
      Locking Reads `SELECT ... FOR UPDATE' and `SELECT ... LOCK IN SHARE MODE'
      Next-key Locking: Avoiding the Phantom Problem
      Locks Set by Different SQL Statements in `InnoDB'
      Deadlock Detection and Rollback
      An Example of How the Consistent Read Works in `InnoDB'
      How to Cope With Deadlocks
    Performance Tuning Tips
      `SHOW INNODB STATUS' and the `InnoDB' Monitors
    Implementation of Multi-versioning
    Table and Index Structures
      Physical Structure of an Index
      Insert Buffering
      Adaptive Hash Indexes
      Physical Record Structure
      How an `AUTO_INCREMENT' Column Works in InnoDB
    File Space Management and Disk I/O
      Disk I/O
      File Space Management
      Defragmenting a Table
    Error Handling
    Restrictions on InnoDB Tables
    InnoDB Change History
      MySQL/InnoDB-5.0.0, December 24, 2003
      MySQL/InnoDB-4.0.17, December 17, 2003
      MySQL/InnoDB-4.1.1, December 4, 2003
      MySQL/InnoDB-4.0.16, October 22, 2003
      MySQL/InnoDB-3.23.58, September 15, 2003
      MySQL/InnoDB-4.0.15, September 10, 2003
      MySQL/InnoDB-4.0.14, July 22, 2003
      MySQL/InnoDB-3.23.57, June 20, 2003
      MySQL/InnoDB-4.0.13, May 20, 2003
      MySQL/InnoDB-4.1.0, April 3, 2003
      MySQL/InnoDB-3.23.56, March 17, 2003
      MySQL/InnoDB-4.0.12, March 18, 2003
      MySQL/InnoDB-4.0.11, February 25, 2003
      MySQL/InnoDB-4.0.10, February 4, 2003
      MySQL/InnoDB-3.23.55, January 24, 2003
      MySQL/InnoDB-4.0.9, January 14, 2003
      MySQL/InnoDB-4.0.8, January 7, 2003
      MySQL/InnoDB-4.0.7, December 26, 2002
      MySQL/InnoDB-4.0.6, December 19, 2002
      MySQL/InnoDB-3.23.54, December 12, 2002
      MySQL/InnoDB-4.0.5, November 18, 2002
      MySQL/InnoDB-3.23.53, October 9, 2002
      MySQL/InnoDB-4.0.4, October 2, 2002
      MySQL/InnoDB-4.0.3, August 28, 2002
      MySQL/InnoDB-3.23.52, August 16, 2002
      MySQL/InnoDB-4.0.2, July 10, 2002
      MySQL/InnoDB-3.23.51, June 12, 2002
      MySQL/InnoDB-3.23.50, April 23, 2002
      MySQL/InnoDB-3.23.49, February 17, 2002
      MySQL/InnoDB-3.23.48, February 9, 2002
      MySQL/InnoDB-3.23.47, December 28, 2001
      MySQL/InnoDB-4.0.1, December 23, 2001
      MySQL/InnoDB-3.23.46, November 30, 2001
      MySQL/InnoDB-3.23.45, November 23, 2001
      MySQL/InnoDB-3.23.44, November 2, 2001
      MySQL/InnoDB-3.23.43, October 4, 2001
      MySQL/InnoDB-3.23.42, September 9, 2001
      MySQL/InnoDB-3.23.41, August 13, 2001
      MySQL/InnoDB-3.23.40, July 16, 2001
      MySQL/InnoDB-3.23.39, June 13, 2001
      MySQL/InnoDB-3.23.38, May 12, 2001
    `InnoDB' Contact Information
  `BDB' or `BerkeleyDB' Tables
    Overview of `BDB' Tables
    Installing `BDB'
    `BDB' Startup Options
    Characteristics of `BDB' Tables
    Things We Need to Fix for `BDB' in the Near Future
    Operating Systems Supported by `BDB'
    Restrictions on `BDB' Tables
    Errors That May Occur When Using `BDB' Tables
  `ISAM' Tables

Introduction to MaxDB
  History of MaxDB
  Licensing and Support
  Basic Concepts of MaxDB
  Feature Differences between MaxDB and MySQL
  Interoperability Features between MaxDB and MySQL
  MaxDB-related Links
  Reserved Words in MaxDB
  Functions
  Column Types

National Character Sets and Unicode
  Character Sets and Collations in General
  Character Sets and Collations in MySQL
  Determining the Default Character Set and Collation
    Server Character Set and Collation
    Database Character Set and Collation
    Table Character Set and Collation
    Column Character Set and Collation
    Examples of Character Set and Collation Assignment
    Connection Character Sets and Collations
    Character String Literal Character Set and Collation
    `COLLATE' Clause in Various Parts of an SQL Query
    `COLLATE' Clause Precedence
    `BINARY' Operator
    Some Special Cases Where the Collation Determination is Tricky
    Collations Must Be for the Right Character Set
    An example of the Effect of Collation
  Operations Affected by Character Set Support
    Result Strings
    `CONVERT()'
    `CAST()'
    `SHOW CHARACTER SET'
    `SHOW COLLATION'
    `SHOW CREATE DATABASE'
    `SHOW FULL COLUMNS'
  Unicode Support
  UTF8 for Metadata
  Compatibility with Other DBMSs
  New Character Set Configuration File format
  National Character Set
  Upgrading from MySQL 4.0
    4.0 Character Sets and Corresponding 4.1 Character Set/Collation Pairs
  The Character Sets and Collations that MySQL Supports
    The Unicode Character Sets
    Platform Specific Character Sets
    Character Sets for South Europe and Middle East
    The Asian Character Sets
    The Baltic Character Sets
    The Cyrillic Character Sets
    The Central European Character Sets
    The West European Character Sets

Spatial Extensions in MySQL
  Introduction
  The OpenGIS Geometry Model
    The Geometry Class Hierarchy
    Class `Geometry'
    Class `Point'
    Class `Curve'
    Class `LineString'
    Class `Surface'
    Class `Polygon'
    Class `GeometryCollection'
    Class `MultiPoint'
    Class `MultiCurve'
    Class `MultiLineString'
    Class `MultiSurface'
    Class `MultiPolygon'
  Supported Spatial Data Formats
    Well-Known Text (WKT) Format
    Well-Known Binary (WKB) Format
  Creating a Spatially Enabled MySQL Database
    MySQL Spatial Datatypes
    Creating Spatial Values
      Creating Geometry Values Using WKT Functions
      Creating Geometry Values Using WKB Functions
      Creating Geometry Values Using MySQL-Specific Functions
    Creating Spatial Columns
    Populating Spatial Columns
    Fetching Spatial Data
      Fetching Spatial Data in Internal Format
      Fetching Spatial Data in WKT Format
      Fetching Spatial Data in WKB Format
  Analyzing Spatial Information
    Geometry Format Conversion Functions
    `Geometry' Functions
      General Geometry Functions
      `Point' Functions
      `LineString' Functions
      `MultiLineString' Functions
      `Polygon' Functions
      `MultiPolygon' Functions
      `GeometryCollection' Functions
    Functions That Create New Geometries from Existing Ones
      Geometry Functions That Produce New Geometries
      Spatial Operators
    Functions for Testing Spatial Relations Between Geometric Objects
    Relations on Geometry Minimal Bounding Rectangles (MBRs)
    Functions That Test Spatial Relationships Between Geometries
  Optimizing Spatial Analysis
    Creating Spatial Indexes
    Using a Spatial Index
  MySQL Conformance and Compatibility
    GIS Features That Are Not Yet Implemented

Stored Procedures and Functions
  Stored Procedure Syntax
    Maintaining Stored Procedures
      `CREATE PROCEDURE' and `CREATE FUNCTION'
      `ALTER PROCEDURE' and `ALTER FUNCTION'
      `DROP PROCEDURE' and `DROP FUNCTION'
      `SHOW CREATE PROCEDURE' and `SHOW CREATE FUNCTION'
    `SHOW PROCEDURE STATUS' and `SHOW FUNCTION STATUS'
    `CALL'
    `BEGIN ... END' Compound Statement
    `DECLARE' Statement
    Variables in Stored Procedures
      `DECLARE' Local Variables
      Variable `SET' Statement
      `SELECT ... INTO' Statement
    Conditions and Handlers
      `DECLARE' Conditions
      `DECLARE' Handlers
    Cursors
      Declaring Cursors
      Cursor `OPEN' Statement
      Cursor `FETCH' Statement
      Cursor `CLOSE' Statement
    Flow Control Constructs
      `IF' Statement
      `CASE' Statement
      `LOOP' Statement
      `LEAVE' Statement
      `ITERATE' Statement
      `REPEAT' Statement
      `WHILE' Statement

MySQL APIs
  MySQL C API
    C API Datatypes
    C API Function Overview
    C API Function Descriptions
      `mysql_affected_rows()'
      `mysql_change_user()'
      `mysql_character_set_name()'
      `mysql_close()'
      `mysql_connect()'
      `mysql_create_db()'
      `mysql_data_seek()'
      `mysql_debug()'
      `mysql_drop_db()'
      `mysql_dump_debug_info()'
      `mysql_eof()'
      `mysql_errno()'
      `mysql_error()'
      `mysql_escape_string()'
      `mysql_fetch_field()'
      `mysql_fetch_fields()'
      `mysql_fetch_field_direct()'
      `mysql_fetch_lengths()'
      `mysql_fetch_row()'
      `mysql_field_count()'
      `mysql_field_seek()'
      `mysql_field_tell()'
      `mysql_free_result()'
      `mysql_get_client_info()'
      `mysql_get_client_version()'
      `mysql_get_host_info()'
      `mysql_get_proto_info()'
      `mysql_get_server_info()'
      `mysql_get_server_version()'
      `mysql_info()'
      `mysql_init()'
      `mysql_insert_id()'
      `mysql_kill()'
      `mysql_list_dbs()'
      `mysql_list_fields()'
      `mysql_list_processes()'
      `mysql_list_tables()'
      `mysql_num_fields()'
      `mysql_num_rows()'
      `mysql_options()'
      `mysql_ping()'
      `mysql_query()'
      `mysql_real_connect()'
      `mysql_real_escape_string()'
      `mysql_real_query()'
      `mysql_reload()'
      `mysql_row_seek()'
      `mysql_row_tell()'
      `mysql_select_db()'
      `mysql_set_server_option()'
      `mysql_shutdown()'
      `mysql_sqlstate()'
      `mysql_ssl_set()'
      `mysql_stat()'
      `mysql_store_result()'
      `mysql_thread_id()'
      `mysql_use_result()'
      `mysql_warning_count()'
      `mysql_commit()'
      `mysql_rollback()'
      `mysql_autocommit()'
      `mysql_more_results()'
      `mysql_next_result()'
    C API Prepared Statements
    C API Prepared Statement Datatypes
    C API Prepared Statement Function Overview
    C API Prepared Statement Function Descriptions
      `mysql_bind_param()'
      `mysql_bind_result()'
      `mysql_execute()'
      `mysql_fetch()'
      `mysql_fetch_column()'
      `mysql_get_metadata()'
      `mysql_param_count()'
      `mysql_param_result()'
      `mysql_prepare()'
      `mysql_send_long_data()'
      `mysql_stmt_affected_rows()'
      `mysql_stmt_close()'
      `mysql_stmt_data_seek()'
      `mysql_stmt_errno()'
      `mysql_stmt_error()'
      `mysql_stmt_free_result()'
      `mysql_stmt_num_rows()'
      `mysql_stmt_reset()'
      `mysql_stmt_row_seek()'
      `mysql_stmt_row_tell()'
      `mysql_stmt_sqlstate()'
      `mysql_stmt_store_result()'
    C API Handling of Multiple Query Execution
    C API Handling of Date and Time Values
    C API Threaded Function Descriptions
      `my_init()'
      `mysql_thread_init()'
      `mysql_thread_end()'
      `mysql_thread_safe()'
    C API Embedded Server Function Descriptions
      `mysql_server_init()'
      `mysql_server_end()'
    Common questions and problems when using the C API
      Why `mysql_store_result()' Sometimes Returns `NULL' After `mysql_query()' Returns Success
      What Results You Can Get from a Query
      How to Get the Unique ID for the Last Inserted Row
      Problems Linking with the C API
    Building Client Programs
    How to Make a Threaded Client
    libmysqld, the Embedded MySQL Server Library
      Overview of the Embedded MySQL Server Library
      Compiling Programs with `libmysqld'
      Restrictions when using the Embedded MySQL Server
      Using Option Files with the Embedded Server
      Things left to do in Embedded Server (TODO)
      A Simple Embedded Server Example
      Licensing the Embedded Server
  MySQL ODBC Support
    How to Install MyODBC
    How to Fill in the Various Fields in the ODBC Administrator Program
    Connect parameters for MyODBC
    How to Report Problems with MyODBC
    Programs Known to Work with MyODBC
    How to Get the Value of an `AUTO_INCREMENT' Column in ODBC
    Reporting Problems with MyODBC
  MySQL Java Connectivity (JDBC)
  MySQL PHP API
    Common Problems with MySQL and PHP
  MySQL Perl API
  MySQL C++ API
    Borland C++
  MySQL Python API
  MySQL Tcl API
  MySQL Eiffel Wrapper

Error Handling in MySQL
  Error Returns

Extending MySQL
  MySQL Internals
    MySQL Threads
    MySQL Test Suite
      Running the MySQL Test Suite
      Extending the MySQL Test Suite
      Reporting Bugs in the MySQL Test Suite
  Adding New Functions to MySQL
    `CREATE FUNCTION/DROP FUNCTION' Syntax
    Adding a New User-defined Function
      UDF Calling Sequences for simple functions
      UDF Calling Sequences for aggregate functions
      Argument Processing
      Return Values and Error Handling
      Compiling and Installing User-defined Functions
    Adding a New Native Function
  Adding New Procedures to MySQL
    Procedure Analyse
    Writing a Procedure

Problems and Common Errors
  How to Determine What Is Causing Problems
  Common Errors When Using MySQL
    `Access denied' Error
    `MySQL server has gone away' Error
    `Can't connect to [local] MySQL server' Error
    `Client does not support authentication protocol' error
    `Host '...' is blocked' Error
    `Too many connections' Error
    `Some non-transactional changed tables couldn't be rolled back' Error
    `Out of memory' Error
    `Packet too large' Error
    Communication Errors / Aborted Connection
    `The table is full' Error
    `Can't create/write to file' Error
    `Commands out of sync' Error in Client
    `Ignoring user' Error
    `Table 'xxx' doesn't exist' Error
    `Can't initialize character set xxx' error
    File Not Found
  Installation Related Issues
    Problems When Linking with the MySQL Client Library
    How to Run MySQL As a Normal User
    Problems with File Permissions
  Administration Related Issues
    What To Do If MySQL Keeps Crashing
    How to Reset a Forgotten Root Password
    How MySQL Handles a Full Disk
    Where MySQL Stores Temporary Files
    How to Protect or Change the MySQL Socket File `/tmp/mysql.sock'
    Time Zone Problems
  Query Related Issues
    Case-Sensitivity in Searches
    Problems Using `DATE' Columns
    Problems with `NULL' Values
    Problems with `alias'
    Deleting Rows from Related Tables
    Solving Problems with No Matching Rows
    Problems with Floating-Point Comparison
  Optimizer Related Issues
    How to avoid table scan,,,
  Table Definition Related Issues
    Problems with `ALTER TABLE'.
    How To Change the Order of Columns in a Table
    TEMPORARY TABLE problems

Credits
  Developers at MySQL AB
  Contributors to MySQL
  Documenters and translators
  Libraries used by and included with MySQL
  Packages that support MySQL
  Tools that were used to create MySQL
  Supporters of MySQL

MySQL Change History
  Changes in release 5.0.x (Development)
    Changes in release 5.0.1 (not released yet)
    Changes in release 5.0.0 (22 Dec 2003: Alpha)
  Changes in release 4.1.x (Alpha)
    Changes in release 4.1.2 (not released yet)
    Changes in release 4.1.1 (01 Dec 2003)
    Changes in release 4.1.0 (03 Apr 2003: Alpha)
  Changes in release 4.0.x (Production)
    Changes in release 4.0.19 (not released yet)
    Changes in release 4.0.18 (to be released soon)
    Changes in release 4.0.17 (14 Dec 2003)
    Changes in release 4.0.16 (17 Oct 2003)
    Changes in release 4.0.15 (03 Sep 2003)
    Changes in release 4.0.14 (18 Jul 2003)
    Changes in release 4.0.13 (16 May 2003)
    Changes in release 4.0.12 (15 Mar 2003: Production)
    Changes in release 4.0.11 (20 Feb 2003)
    Changes in release 4.0.10 (29 Jan 2003)
    Changes in release 4.0.9 (09 Jan 2003)
    Changes in release 4.0.8 (07 Jan 2003)
    Changes in release 4.0.7 (20 Dec 2002)
    Changes in release 4.0.6 (14 Dec 2002: Gamma)
    Changes in release 4.0.5 (13 Nov 2002)
    Changes in release 4.0.4 (29 Sep 2002)
    Changes in release 4.0.3 (26 Aug 2002: Beta)
    Changes in release 4.0.2 (01 Jul 2002)
    Changes in release 4.0.1 (23 Dec 2001)
    Changes in release 4.0.0 (Oct 2001: Alpha)
  Changes in release 3.23.x (Recent; still supported)
    Changes in release 3.23.59 (not released yet)
    Changes in release 3.23.58 (11 Sep 2003)
    Changes in release 3.23.57 (06 Jun 2003)
    Changes in release 3.23.56 (13 Mar 2003)
    Changes in release 3.23.55 (23 Jan 2003)
    Changes in release 3.23.54 (05 Dec 2002)
    Changes in release 3.23.53 (09 Oct 2002)
    Changes in release 3.23.52 (14 Aug 2002)
    Changes in release 3.23.51 (31 May 2002)
    Changes in release 3.23.50 (21 Apr 2002)
    Changes in release 3.23.49
    Changes in release 3.23.48 (07 Feb 2002)
    Changes in release 3.23.47 (27 Dec 2001)
    Changes in release 3.23.46 (29 Nov 2001)
    Changes in release 3.23.45 (22 Nov 2001)
    Changes in release 3.23.44 (31 Oct 2001)
    Changes in release 3.23.43 (04 Oct 2001)
    Changes in release 3.23.42 (08 Sep 2001)
    Changes in release 3.23.41 (11 Aug 2001)
    Changes in release 3.23.40
    Changes in release 3.23.39 (12 Jun 2001)
    Changes in release 3.23.38 (09 May 2001)
    Changes in release 3.23.37 (17 Apr 2001)
    Changes in release 3.23.36 (27 Mar 2001)
    Changes in release 3.23.35 (15 Mar 2001)
    Changes in release 3.23.34a
    Changes in release 3.23.34 (10 Mar 2001)
    Changes in release 3.23.33 (09 Feb 2001)
    Changes in release 3.23.32 (22 Jan 2001: Production)
    Changes in release 3.23.31 (17 Jan 2001)
    Changes in release 3.23.30 (04 Jan 2001)
    Changes in release 3.23.29 (16 Dec 2000)
    Changes in release 3.23.28 (22 Nov 2000: Gamma)
    Changes in release 3.23.27 (24 Oct 2000)
    Changes in release 3.23.26 (18 Oct 2000)
    Changes in release 3.23.25 (29 Sep 2000)
    Changes in release 3.23.24 (08 Sep 2000)
    Changes in release 3.23.23 (01 Sep 2000)
    Changes in release 3.23.22 (31 Jul 2000)
    Changes in release 3.23.21
    Changes in release 3.23.20
    Changes in release 3.23.19
    Changes in release 3.23.18
    Changes in release 3.23.17
    Changes in release 3.23.16
    Changes in release 3.23.15 (May 2000: Beta)
    Changes in release 3.23.14
    Changes in release 3.23.13
    Changes in release 3.23.12 (07 Mar 2000)
    Changes in release 3.23.11
    Changes in release 3.23.10
    Changes in release 3.23.9
    Changes in release 3.23.8 (02 Jan 2000)
    Changes in release 3.23.7 (10 Dec 1999)
    Changes in release 3.23.6
    Changes in release 3.23.5 (20 Oct 1999)
    Changes in release 3.23.4 (28 Sep 1999)
    Changes in release 3.23.3
    Changes in release 3.23.2 (09 Aug 1999)
    Changes in release 3.23.1
    Changes in release 3.23.0 (05 Aug 1999: Alpha)
  Changes in release 3.22.x (Old; discontinued)
    Changes in release 3.22.35
    Changes in release 3.22.34
    Changes in release 3.22.33
    Changes in release 3.22.32 (14 Feb 2000)
    Changes in release 3.22.31
    Changes in release 3.22.30
    Changes in release 3.22.29 (02 Jan 2000)
    Changes in release 3.22.28 (20 Oct 1999)
    Changes in release 3.22.27
    Changes in release 3.22.26 (16 Sep 1999)
    Changes in release 3.22.25
    Changes in release 3.22.24 (05 Jul 1999)
    Changes in release 3.22.23 (08 Jun 1999)
    Changes in release 3.22.22 (30 Apr 1999)
    Changes in release 3.22.21
    Changes in release 3.22.20 (18 Mar 1999)
    Changes in release 3.22.19 (Mar 1999: Production)
    Changes in release 3.22.18
    Changes in release 3.22.17
    Changes in release 3.22.16 (Feb 1999: Gamma)
    Changes in release 3.22.15
    Changes in release 3.22.14
    Changes in release 3.22.13
    Changes in release 3.22.12
    Changes in release 3.22.11
    Changes in release 3.22.10
    Changes in release 3.22.9
    Changes in release 3.22.8
    Changes in release 3.22.7 (Sep 1998: Beta)
    Changes in release 3.22.6
    Changes in release 3.22.5
    Changes in release 3.22.4
    Changes in release 3.22.3
    Changes in release 3.22.2
    Changes in release 3.22.1 (Jun 1998: Alpha)
    Changes in release 3.22.0
  Changes in release 3.21.x
    Changes in release 3.21.33
    Changes in release 3.21.32
    Changes in release 3.21.31
    Changes in release 3.21.30
    Changes in release 3.21.29
    Changes in release 3.21.28
    Changes in release 3.21.27
    Changes in release 3.21.26
    Changes in release 3.21.25
    Changes in release 3.21.24
    Changes in release 3.21.23
    Changes in release 3.21.22
    Changes in release 3.21.21a
    Changes in release 3.21.21
    Changes in release 3.21.20
    Changes in release 3.21.19
    Changes in release 3.21.18
    Changes in release 3.21.17
    Changes in release 3.21.16
    Changes in release 3.21.15
    Changes in release 3.21.14b
    Changes in release 3.21.14a
    Changes in release 3.21.13
    Changes in release 3.21.12
    Changes in release 3.21.11
    Changes in release 3.21.10
    Changes in release 3.21.9
    Changes in release 3.21.8
    Changes in release 3.21.7
    Changes in release 3.21.6
    Changes in release 3.21.5
    Changes in release 3.21.4
    Changes in release 3.21.3
    Changes in release 3.21.2
    Changes in release 3.21.0
  Changes in release 3.20.x
    Changes in release 3.20.18
    Changes in release 3.20.17
    Changes in release 3.20.16
    Changes in release 3.20.15
    Changes in release 3.20.14
    Changes in release 3.20.13
    Changes in release 3.20.11
    Changes in release 3.20.10
    Changes in release 3.20.9
    Changes in release 3.20.8
    Changes in release 3.20.7
    Changes in release 3.20.6
    Changes in release 3.20.3
    Changes in release 3.20.0
  Changes in release 3.19.x
    Changes in release 3.19.5
    Changes in release 3.19.4
    Changes in release 3.19.3

Porting to Other Systems
  Debugging a MySQL server
    Compiling MYSQL for Debugging
    Creating Trace Files
    Debugging mysqld under gdb
    Using a Stack Trace
    Using Log Files to Find Cause of Errors in mysqld
    Making a Test Case If You Experience Table Corruption
  Debugging a MySQL client
  The DBUG Package
  Locking methods
  Comments about RTS threads
  Differences between different thread packages

Environment Variables

MySQL Regular Expressions

GNU General Public License

SQL command, type and function index

Concept Index


This is the Reference Manual for the `MySQL Database System'.  This
version refers to the 4.0.18 version of `MySQL Server' but it is also
applicable for any older version (such as 3.23 and 4.0-production) as
changes are always indicated. There are also references for version 5.0
(development).

General Information
*******************

The `MySQL' (R) software delivers a very fast, multi-threaded,
multi-user, and robust `SQL' (`Structured Query Language') database
server.  `MySQL Server' is intended for mission-critical, heavy-load
production systems as well as for embedding into mass-deployed software.
`MySQL' is a trademark of `MySQL AB'.

The `MySQL' software is `Dual Licensed'. Users can choose to use the
`MySQL' software as an `Open Source'/`Free Software' product under the
terms of the `GNU General Public License'
(`http://www.fsf.org/licenses/') or can purchase a standard commercial
license from `MySQL AB'.  *Note Licensing and Support::.

The `MySQL' web site (`http://www.mysql.com/') provides the latest
information about the `MySQL' software.

The following list describes some sections of particular interest in
this manual:

   * For information about the company behind the `MySQL Database
     Server', see *Note What is MySQL AB::.

   * For a discussion about the capabilities of the `MySQL Database
     Server', see *Note Features::.

   * For installation instructions, see *Note Installing::.

   * For tips on porting the `MySQL Database Software' to new
     architectures or operating systems, see *Note Porting::.

   * For information about upgrading from a Version 4.0 release, see
     *Note Upgrading-from-4.0::.

   * For information about upgrading from a Version 3.23 release, see
     *Note Upgrading-from-3.23::.

   * For information about upgrading from a Version 3.22 release, see
     *Note Upgrading-from-3.22::.

   * For a tutorial introduction to the `MySQL Database Server', see
     *Note Tutorial::.

   * For examples of `SQL' and benchmarking information, see the
     benchmarking directory (`sql-bench' in the distribution).

   * For a history of new features and bug fixes, see *Note News::.

   * For a list of currently known bugs and misfeatures, see *Note
     Bugs::.

   * For future plans, see *Note TODO::.

   * For a list of all the contributors to this project, see *Note
     Credits::.

*Important*:

Reports of errors (often called bugs), as well as questions and
comments, should be sent to the general MySQL mailing list.  *Note
Mailing-list::.  *Note Bug reports::.

The `mysqlbug' script should be used to generate bug reports on Unix.
(Windows distributions contain a file `mysqlbug.txt' in the base
directory that can be used as a template for a bug report.)

For source distributions, the `mysqlbug' script can be found in the
`scripts' directory. For binary distributions, `mysqlbug' can be found
in the `bin' directory (`/usr/bin' for the `MySQL-server' RPM package).

If you have found a sensitive security bug in `MySQL Server', please let
us know immediately by sending an email message to <[e-mail]>.

About This Manual
=================

This is the `MySQL' reference manual; it documents `MySQL' up to
Version 4.0.18. Functional changes are always indicated with reference
to the version, so this manual is also suitable if you are using an
older version of the `MySQL' software (such as 3.23 or 4.0-production).
There are also references for version 5.0 (development).

Being a reference manual, it does not provide general instruction on
`SQL' or relational database concepts. It also will not teach you how to
use your operating system or command line interpreter.

As the `MySQL Database Software' is under constant development, the
manual is also updated frequently.  The most recent version of this
manual is available at `http://www.mysql.com/documentation/' in many
different formats, including HTML, PDF, and Windows HLP versions.

The primary document is the Texinfo file.  The HTML version is produced
automatically using a modified version of `texi2html'.  The plain text
and Info versions are produced with `makeinfo'.  The PostScript version
is produced using `texi2dvi' and `dvips'.  The PDF version is produced
with `pdftex'.

The index can assist you in finding information in the manual. For
online use, you can try the searchable version of the manual available
at `http://www.mysql.com/doc/'.

If you have any suggestions concerning additions or corrections to this
manual, please send them to the documentation team at <[e-mail]>.

This manual was initially written by David Axmark and Michael (Monty)
Widenius. It is now maintained by the MySQL Documentation Team,
consisting of Arjen Lentz, Paul DuBois and Stefan Hinz.  For the many
other contributors, see *Note Credits::.

The copyright (2004) to this manual is owned by the Swedish company
`MySQL AB'. *Note Copyright::.

Conventions Used in This Manual
-------------------------------

This manual uses certain typographical conventions:

`constant'
     Constant-width font is used for command names and options; SQL
     statements; database, table, and column names; C and Perl code;
     and environment variables.  Example: "To see how `mysqladmin'
     works, invoke it with the `--help' option."

`filename'
     Constant-width font with surrounding quotes is used for filenames
     and pathnames.  Example: "The distribution is installed under the
     `/usr/local/' directory."

`c'
     Constant-width font with surrounding quotes is also used to
     indicate character sequences.  Example: "To specify a wildcard,
     use the `%' character."

_italic_
     Italic font is used for emphasis, _like this_.

*boldface*
     Boldface font is used in table headings and to convey *especially
     strong emphasis*.

When commands are shown that are meant to be executed by a particular
program, the program is indicated by a prompt shown before the command.
For example, `shell>' indicates a command that you execute from your
login shell, and `mysql>' indicates a statement that you execute from
the `mysql' client program:

     shell> type a shell command here
     mysql> type a mysql statement here

The "shell" is your command interpreter. On Unix, this is typically a
program such as `sh' or `csh'. On Windows, the equivalent is
`command.com' or `cmd.exe', typically run in a Windows console.

Note that to enter a command or statement from an example, you do not
type the prompt shown in the example.

Commands to set shell variables are shown using Bourne shell syntax.
If you are using `csh' or `tcsh', you will need to issue commands
somewhat differently.  For example, the sequence to set an environment
variable and run a command looks like this in Bourne shell syntax:

     shell> VARNAME=value some_command

For `csh' or `tcsh', you would execute the sequence like this:

     shell> setenv VARNAME value
     shell> some_command

Database, table, and column names must often be substituted into
commands.  To indicate that such substitution is necessary, this manual
uses `db_name', `tbl_name', and `col_name'.  For example, you might see
a statement like this:

     mysql> SELECT col_name FROM db_name.tbl_name;

This means that if you were to enter a similar statement, you would
supply your own database, table, and column names, perhaps like this:

     mysql> SELECT author_name FROM biblio_db.author_list;

SQL keywords are not case sensitive and may be written in uppercase or
lowercase.  This manual uses uppercase.

In syntax descriptions, square brackets (`[' and `]') are used to
indicate optional words or clauses.  For example, in the following
statement, `IF EXISTS' is optional:

     DROP TABLE [IF EXISTS] tbl_name

When a syntax element consists of a number of alternatives, the
alternatives are separated by vertical bars (`|').  When one member
from a set of choices *may* be chosen, the alternatives are listed
within square brackets (`[' and `]'):

     TRIM([[BOTH | LEADING | TRAILING] [remstr] FROM] str)

When one member from a set of choices *must* be chosen, the
alternatives are listed within braces (`{' and `}'):

     {DESCRIBE | DESC} tbl_name {col_name | wild}

An ellipsis (`...') indicates the omission of a section of a statement,
typically to provide a shorter version of more complex syntax. For
example, `INSERT ... SELECT' is shorthand for the form of `INSERT'
statement that is followed by a `SELECT' statement.

An ellipsis can also indicate that the preceding syntax element of a
statement may be repeated. In the following example, multiple
`reset_option' values may be given, with each of those after the first
preceded by commas:

     RESET reset_option [,reset_option] ...

Overview of the MySQL Database Management System
================================================

`MySQL', the most popular `Open Source' SQL database management system,
is developed, distributed, and supported by `MySQL AB'.  `MySQL AB' is a
commercial company, founded by the MySQL developers, that builds its
business by providing services around the `MySQL' database management
system.  *Note What is MySQL AB::.

The `MySQL' web site (`http://www.mysql.com/') provides the latest
information about `MySQL' software and `MySQL AB'.

`MySQL' is a database management system.
     A database is a structured collection of data.  It may be anything
     from a simple shopping list to a picture gallery or the vast
     amounts of information in a corporate network.  To add, access,
     and process data stored in a computer database, you need a
     database management system such as `MySQL' Server.  Since
     computers are very good at handling large amounts of data,
     database management systems play a central role in computing, as
     stand-alone utilities or as parts of other applications.

MySQL is a relational database management system.
     A relational database stores data in separate tables rather than
     putting all the data in one big storeroom.  This adds speed and
     flexibility.  The `SQL' part of "`MySQL'" stands for "`Structured
     Query Language'". SQL is the most common standardized language
     used to access databases and is defined by the ANSI/ISO SQL
     Standard.(The SQL standard has been evolving since 1986 and
     several versions exist. In this manual, "`SQL-92'" refers to the
     standard released in 1992, "`SQL-99'" refers to the standard
     released in 1999, and "`SQL:2003'" refers to the next version of
     the standard.  We use the term "`the SQL standard'" to mean the
     current version of the SQL Standard at any time.)

MySQL software is `Open Source'.
     `Open Source' means that it is possible for anyone to use and
     modify the software.  Anybody can download the `MySQL' software
     from the Internet and use it without paying anything.  If you
     wish, you may study the source code and change it to suit your
     needs.  The `MySQL' software uses the `GPL' (`GNU General Public
     License'), `http://www.fsf.org/licenses/', to define what you may
     and may not do with the software in different situations.  If you
     feel uncomfortable with the `GPL' or need to embed `MySQL' code
     into a commercial application, you can buy a commercially licensed
     version from us.  *Note MySQL licenses::.

Why use the MySQL Database Server?
     The `MySQL Database Server' is very fast, reliable, and easy to
     use.  If that is what you are looking for, you should give it a
     try.  `MySQL Server' also has a practical set of features
     developed in close cooperation with our users.  You can find a
     performance comparison of `MySQL Server' with other database
     managers on our benchmark page.  *Note MySQL Benchmarks::.

     `MySQL Server' was originally developed to handle large databases
     much faster than existing solutions and has been successfully used
     in highly demanding production environments for several years.
     Though under constant development, `MySQL Server' today offers a
     rich and useful set of functions.  Its connectivity, speed, and
     security make `MySQL Server' highly suited for accessing databases
     on the Internet.

The technical features of MySQL Server
     The `MySQL Database Software' is a client/server system that
     consists of a multi-threaded `SQL' server that supports different
     backends, several different client programs and libraries,
     administrative tools, and a wide range of application programming
     interfaces (APIs).

     We also provide `MySQL Server' as a multi-threaded library which
     you can link into your application to get a smaller, faster,
     easier-to-manage product.

There is a large amount of contributed MySQL software available.
     It is very likely that you will find that your favorite
     application or language already supports the `MySQL Database
     Server'.

The official way to pronounce `MySQL' is "My Ess Que Ell" (not "my
sequel"), but we don't mind if you pronounce it as "my sequel" or in
some other localized way.

History of MySQL
----------------

We started out with the intention of using `mSQL' to connect to our
tables using our own fast low-level (ISAM) routines. However, after some
testing, we came to the conclusion that `mSQL' was not fast enough or
flexible enough for our needs.  This resulted in a new SQL interface to
our database but with almost the same API interface as `mSQL'.  This
API was designed to allow third-party code that was written for use
with `mSQL' to be ported easily for use with `MySQL'.

The derivation of the name `MySQL' is not clear.  Our base directory
and a large number of our libraries and tools have had the prefix "my"
for well over 10 years.  However, co-founder Monty Widenius's daughter
is also named My.  Which of the two gave its name to `MySQL' is still a
mystery, even for us.

The name of the MySQL Dolphin (our logo) is `Sakila'. `Sakila' was
chosen by the founders of MySQL AB from a huge list of names suggested
by users in our "Name the Dolphin" contest. The winning name was
submitted by Ambrose Twebaze, an open source software developer from
Swaziland, Africa.  According to Ambrose, the name Sakila has its roots
in SiSwati, the local language of Swaziland. Sakila is also the name of
a town in Arusha, Tanzania, near Ambrose's country of origin, Uganda.

The Main Features of MySQL
--------------------------

The following list describes some of the important characteristics of
the `MySQL Database Software'. *Note MySQL 4.0 Nutshell::.

Internals and Portability
        * Written in C and C++.

        * Tested with a broad range of different compilers.

        * Works on many different platforms.  *Note Which OS::.

        * Uses GNU Automake, Autoconf, and Libtool for portability.

        * APIs for C, C++, Eiffel, Java, Perl, PHP, Python, Ruby, and
          Tcl are available.  *Note Clients::.

        * Fully multi-threaded using kernel threads.  This means it can
          easily use multiple CPUs if they are available.

        * Provides transactional and non-transactional storage engines.

        * Uses very fast B-tree disk tables (`MyISAM') with index
          compression.

        * Relatively easy to add another storage engine. This is useful
          if you want to add an SQL interface to an in-house database.

        * A very fast thread-based memory allocation system.

        * Very fast joins using an optimized one-sweep multi-join.

        * In-memory hash tables which are used as temporary tables.

        * SQL functions are implemented using a highly optimized class
          library and should be as fast as possible.  Usually there is
          no memory allocation at all after query initialization.

        * The `MySQL' code is tested with Purify (a commercial memory
          leakage detector) as well as with Valgrind, a `GPL' tool
          (`http://developer.kde.org/~sewardj/').

        * The server is available as a separate program for use in a
          client/server networked environment.  It is also available as
          a library that can be embedded (linked) into standalone
          applications. Such applications can be used in isolation or
          in environments where no network is available.

Column Types
        * Many column types: signed/unsigned integers 1, 2, 3, 4, and 8
          bytes long, `FLOAT', `DOUBLE', `CHAR', `VARCHAR', `TEXT',
          `BLOB', `DATE', `TIME', `DATETIME', `TIMESTAMP', `YEAR',
          `SET', `ENUM', and OpenGIS geometry types.  *Note Column
          types::.

        * Fixed-length and variable-length records.

Commands and Functions
        * Full operator and function support in the `SELECT' and `WHERE'
          clauses of queries.  For example:

               mysql> SELECT CONCAT(first_name, ' ', last_name)
                   -> FROM tbl_name
                   -> WHERE income/dependents > 10000 AND age > 30;

        * Full support for SQL `GROUP BY' and `ORDER BY' clauses.
          Support for group functions (`COUNT()', `COUNT(DISTINCT ...)',
          `AVG()', `STD()', `SUM()', `MAX()', `MIN()', and
          `GROUP_CONCAT()').

        * Support for `LEFT OUTER JOIN' and `RIGHT OUTER JOIN' with
          both standard SQL and ODBC syntax.

        * Support for aliases on tables and columns as required by
          SQL-92.

        * `DELETE', `INSERT', `REPLACE', and `UPDATE' return the number
          of rows that were changed (affected).  It is possible to
          return the number of rows matched instead by setting a flag
          when connecting to the server.

        * The `MySQL'-specific `SHOW' command can be used to retrieve
          information about databases, tables, and indexes.  The
          `EXPLAIN' command can be used to determine how the optimizer
          resolves a query.

        * Function names do not clash with table or column names.  For
          example, `ABS' is a valid column name.  The only restriction
          is that for a function call, no spaces are allowed between
          the function name and the `(' that follows it.  *Note
          Reserved words::.

        * You can mix tables from different databases in the same query
          (as of Version 3.22).

Security
        * A privilege and password system that is very flexible and
          secure, and allows host-based verification.  Passwords are
          secure because all password traffic is encrypted when you
          connect to a server.

Scalability and Limits
        * Handles large databases.  We use `MySQL Server' with
          databases that contain 50 million records. We also know of
          users that use `MySQL Server' with 60,000 tables and about
          5,000,000,000 rows.

        * Up to 32 indexes per table are allowed.  Each index may
          consist of 1 to 16 columns or parts of columns.  The maximum
          index width is 500 bytes (this may be changed when compiling
          `MySQL Server').  An index may use a prefix of a `CHAR' or
          `VARCHAR' column.

Connectivity
        * Clients may connect to the `MySQL' server using TCP/IP sockets
          on any platform.  On Windows systems in the NT family (NT,
          2000, or XP), clients may connect using named pipes. On Unix
          systems, clients may connect using Unix domain socket files.

        * The Connector/ODBC interface provides `MySQL' support for
          client programs that use ODBC (Open-DataBase-Connectivity)
          connections.  For example, you can use MS Access to connect
          to your `MySQL' server.  Clients may be run on Windows or
          Unix.  Connector/ODBC source is available.  All ODBC 2.5
          functions are supported, as are many others.  *Note ODBC::.

        * The Connector/JDBC interface provides `MySQL' support for
          Java client programs that use JDBC connections.  Clients may
          be run on Windows or Unix.  Connector/JDBC source is
          available.  *Note Java::.

Localization
        * The server can provide error messages to clients in many
          languages.  *Note Languages::.

        * Full support for several different character sets, including
          ISO-8859-1 (Latin1), german, big5, ujis, and more.  For
          example, the Scandinavian characters `a^', `a"' and `o"' are
          allowed in table and column names.  Unicode support is
          available as of `MySQL' 4.1.

        * All data is saved in the chosen character set.  All
          comparisons for normal string columns are case-insensitive.

        * Sorting is done according to the chosen character set (the
          Swedish way by default).  It is possible to change this when
          the `MySQL' server is started.  To see an example of very
          advanced sorting, look at the Czech sorting code.  `MySQL
          Server' supports many different character sets that can be
          specified at compile and runtime.

Clients and Tools
        * The MySQL server has built-in support for SQL statements to
          check, optimize, and repair tables.  These statements are
          available from the command line through the `mysqlcheck'
          client. MySQL also includes `myisamchk', a very fast
          command-line utility for performing these operations on
          `MyISAM' tables.  *Note MySQL Database Administration::.

        * All `MySQL' programs can be invoked with the `--help' or `-?'
          options to obtain online assistance.

MySQL Stability
---------------

This section addresses the questions "_How stable is MySQL Server?_"
and "_Can I depend on MySQL Server in this project?_" We will try to
clarify these issues and answer some important questions that concern
many potential users. The information in this section is based on data
gathered from the mailing list, which is very active in identifying
problems as well as reporting types of use.

The original code stems back to the early 1980s. It provides a stable
code base, and the ISAM table format used by the original storage engine
remains backward-compatible.  At TcX, the predecessor of `MySQL AB',
`MySQL' code has worked in projects since mid-1996, without any
problems.  When the `MySQL Database Software' initially was released to
a wider public, our new users quickly found some pieces of "untested
code". Each new release since then has had fewer portability problems
(even though each new release has also had many new features).

Each release of the `MySQL Server' has been usable. Problems have
occurred only when users try code from the "gray zones."  Naturally,
new users don't know what the gray zones are; this section therefore
attempts to document those areas that are currently known.  The
descriptions mostly deal with Version 3.23 and 4.0 of `MySQL Server'.
All known and reported bugs are fixed in the latest version, with the
exception of those listed in the bugs section, which are
design-related.  *Note Bugs::.

The `MySQL Server' design is multi-layered with independent modules.
Some of the newer modules are listed here with an indication of how
well-tested each of them is:

*Replication -- Gamma*
     Large groups of servers using replication are in production use,
     with good results. Work on enhanced replication features is
     continuing in `MySQL' 5.x.

*`InnoDB' tables -- Stable (in 3.23 from 3.23.49)*
     The `InnoDB' transactional storage engine has been declared stable
     in the `MySQL' 3.23 tree, starting from version 3.23.49.  `InnoDB'
     is being used in large, heavy-load production systems.

*`BDB' tables -- Gamma*
     The `Berkeley DB' code is very stable, but we are still improving
     the `BDB' transactional storage engine interface in `MySQL
     Server', so it will take some time before this is as well tested
     as the other table types.

*Full-text searches -- Beta*
     Full-text searching works but is not yet widely used.  Important
     enhancements have been implemented in `MySQL' 4.0.

*`Connector/ODBC 3.51' (uses ODBC SDK 3.51) -- Stable*
     In wide production use. Some issues brought up appear to be
     application-related and independent of the ODBC driver or
     underlying database server.

*Automatic recovery of `MyISAM' tables -- Gamma*
     This status applies only to the new code in the `MyISAM' storage
     engine that checks if the table was closed properly on open and
     executes an automatic check/repair of the table if it wasn't.

*Bulk-insert -- Alpha*
     New feature in `MyISAM' tables in `MySQL' 4.0 for faster insert of
     many rows.

*Locking -- Gamma*
     This is very system-dependent.  On some systems there are big
     problems using standard operating system locking (`fcntl()').  In
     these cases, you should run `mysqld' with the
     `--skip-external-locking' flag.  Problems are known to occur on
     some Linux systems, and on SunOS when using NFS-mounted
     filesystems.

Paying customers receive high-quality support directly from MySQL AB.
MySQL AB also provides the MySQL mailing list as a community resource
where anyone may ask questions.

Bugs are usually fixed right away with a patch. For serious bugs, there
is almost always a new release.

How Big MySQL Tables Can Be
---------------------------

`MySQL' Version 3.22 had a 4 GB (4 gigabyte) limit on table size. With
the `MyISAM' storage engine in `MySQL' Version 3.23, the maximum table
size was increased to 8 million terabytes (2 ^ 63 bytes). With this
larger allowed table size, the maximum effective table size for `MySQL'
databases now normally is determined by operating system constraints on
file sizes, not by MySQL internal limits.

The `InnoDB' storage engine maintains `InnoDB' tables within a
tablespace that can be created from several files. This allows a table
to exceed the maximum individual file size. The tablespace can include
raw disk partitions, which allows extremely large tables. The maximum
tablespace size is 64 TB.

The following table lists some examples of operating system file-size
limits:

*Operating System*     *File-Size Limit*
Linux-Intel 32-bit     2 GB, much more when using LFS
Linux-Alpha            8 TB (?)
Solaris 2.5.1          2 GB (4GB possible with patch)
Solaris 2.6            4 GB (can be changed with flag)
Solaris 2.7 Intel      4 GB
Solaris 2.7            512 GB
UltraSPARC

On Linux 2.2, you can get `MyISAM' tables larger than 2 GB in size by
using the LFS patch for the ext2 filesystem. On Linux 2.4, patches also
exist for ReiserFS to get support for big files. Most current Linux
distributions are based on kernel 2.4 and already include all the
required Large File Support (LFS) patches. However, the maximum
available file size still depends on several factors, one of them being
the file system used to store MySQL tables.

For a very detailed overview about LFS in Linux, have a look at Andreas
Jaeger's "Large File Support in Linux" page at
<http://www.suse.de/~aj/linux_lfs.html>.

By default, `MySQL' creates `MyISAM' tables with an internal structure
that allows a maximum size of about 4 GB.  You can check the maximum
table size for a table with the `SHOW TABLE STATUS' command or with the
`myisamchk -dv table_name'.  *Note `SHOW': SHOW.

If you need a `MyISQM' table that will be larger than 4 GB in size (and
your operating system supports large files), the `CREATE TABLE'
statement allows `AVG_ROW_LENGTH' and `MAX_ROWS' options.  *Note
`CREATE TABLE': CREATE TABLE.  You can also change these options with
`ALTER TABLE' after the table has been created, to increase the table's
maximum allowable size.  *Note `ALTER TABLE': ALTER TABLE.

Other ways to work around file-size limits for `MyISAM' tables are as
follows:

   * If your large table is read-only, you can use `myisampack' to
     compress it.  `myisampack' usually compresses a table by at least
     50%, so you can have, in effect, much bigger tables.  `myisampack'
     also can merge multiple tables into a single table.  *Note
     `myisampack': myisampack.

   * Another way to get around the operating system file limit for
     `MyISAM' datafiles is by using the `RAID' options.  *Note `CREATE
     TABLE': CREATE TABLE.

   * `MySQL' includes a `MERGE' library that allows you to handle a
     collection of `MyISAM' tables that have identical structure as a
     single `MERGE' table.  *Note `MERGE' tables: MERGE.


Year 2000 Compliance
--------------------

The `MySQL Server' itself has no problems with Year 2000 (Y2K)
compliance:

   * `MySQL Server' uses Unix time functions that handle dates into the
     year `2037' for `TIMESTAMP' values. For `DATE' and `DATETIME'
     values, dates through the year `9999' are accepted.

   * All `MySQL' date functions are implemented in one source file,
     `sql/time.cc', and are coded very carefully to be year 2000-safe.

   * In `MySQL' Version 3.22 and later, the `YEAR' column type can
     store years `0' and `1901' to `2155' in one byte and display them
     using two or four digits.  All 2-digit years are considered to be
     in the range `1970' to `2069', which means that if you store `01'
     in a `YEAR' column, `MySQL Server' treats it as `2001'.

The following simple demonstration illustrates that `MySQL Server'
doesn't have any problems with dates until after the year 2030:

     mysql> DROP TABLE IF EXISTS y2k;
     Query OK, 0 rows affected (0.01 sec)

     mysql> CREATE TABLE y2k (date DATE,
         ->                   date_time DATETIME,
         ->                   time_stamp TIMESTAMP);
     Query OK, 0 rows affected (0.00 sec)

     mysql> INSERT INTO y2k VALUES
         -> ('1998-12-31','1998-12-31 23:59:59',19981231235959),
         -> ('1999-01-01','1999-01-01 00:00:00',19990101000000),
         -> ('1999-09-09','1999-09-09 23:59:59',19990909235959),
         -> ('2000-01-01','2000-01-01 00:00:00',20000101000000),
         -> ('2000-02-28','2000-02-28 00:00:00',20000228000000),
         -> ('2000-02-29','2000-02-29 00:00:00',20000229000000),
         -> ('2000-03-01','2000-03-01 00:00:00',20000301000000),
         -> ('2000-12-31','2000-12-31 23:59:59',20001231235959),
         -> ('2001-01-01','2001-01-01 00:00:00',20010101000000),
         -> ('2004-12-31','2004-12-31 23:59:59',20041231235959),
         -> ('2005-01-01','2005-01-01 00:00:00',20050101000000),
         -> ('2030-01-01','2030-01-01 00:00:00',20300101000000),
         -> ('2050-01-01','2050-01-01 00:00:00',20500101000000);
     Query OK, 13 rows affected (0.01 sec)
     Records: 13  Duplicates: 0  Warnings: 0

     mysql> SELECT * FROM y2k;
     +------------+---------------------+----------------+
     | date       | date_time           | time_stamp     |
     +------------+---------------------+----------------+
     | 1998-12-31 | 1998-12-31 23:59:59 | 19981231235959 |
     | 1999-01-01 | 1999-01-01 00:00:00 | 19990101000000 |
     | 1999-09-09 | 1999-09-09 23:59:59 | 19990909235959 |
     | 2000-01-01 | 2000-01-01 00:00:00 | 20000101000000 |
     | 2000-02-28 | 2000-02-28 00:00:00 | 20000228000000 |
     | 2000-02-29 | 2000-02-29 00:00:00 | 20000229000000 |
     | 2000-03-01 | 2000-03-01 00:00:00 | 20000301000000 |
     | 2000-12-31 | 2000-12-31 23:59:59 | 20001231235959 |
     | 2001-01-01 | 2001-01-01 00:00:00 | 20010101000000 |
     | 2004-12-31 | 2004-12-31 23:59:59 | 20041231235959 |
     | 2005-01-01 | 2005-01-01 00:00:00 | 20050101000000 |
     | 2030-01-01 | 2030-01-01 00:00:00 | 20300101000000 |
     | 2050-01-01 | 2050-01-01 00:00:00 | 00000000000000 |
     +------------+---------------------+----------------+
     13 rows in set (0.00 sec)

The final `TIMESTAMP' column value is zero because the final year
(`2050') exceeds the `TIMESTAMP' maximum.  The `TIMESTAMP' datatype,
which is used to store the current time, supports values that range
from `19700101000000' to `20300101000000' on 32-bit machines (signed
value).  On 64-bit machines, `TIMESTAMP' handles values up to `2106'
(unsigned value).

The example also shows that the `DATE' and `DATETIME' datatypes have no
problems with the dates used. They handle dates through the year `9999'.

Although `MySQL Server' itself is Y2K-safe, you may run into problems
if you use it with applications that are not Y2K-safe.  For example,
many old applications store or manipulate years using 2-digit values
(which are ambiguous) rather than 4-digit values.  This problem may be
compounded by applications that use values such as `00' or `99' as
"missing" value indicators.  Unfortunately, these problems may be
difficult to fix because different applications may be written by
different programmers, each of whom may use a different set of
conventions and date-handling functions.

Thus, even though `MySQL Server' has no Y2K problems, it is the
application's responsibility to provide unambiguous input.  See *Note
Y2K issues:: for `MySQL Server''s rules for dealing with ambiguous date
input data that contains 2-digit year values.

Overview of MySQL AB
====================

`MySQL AB' is the company of the `MySQL' founders and main developers.
`MySQL AB' was originally established in Sweden by David Axmark, Allan
Larsson, and Michael "Monty" Widenius.

The developers of the `MySQL' server are all employed by the company.
We are a virtual organization with people in a dozen countries around
the world. We communicate extensively over the Internet every day with
one another and with our users, supporters, and partners.

We are dedicated to developing the `MySQL' database software and
promoting it to new users. `MySQL AB' owns the copyright to the `MySQL'
source code, the `MySQL' logo and trademark, and this manual. *Note
What-is::.

The `MySQL' core values show our dedication to `MySQL' and `Open
Source'.

We want the `MySQL Database Software' to be:
   * The best and the most widely used database in the world

   * Available to, and affordable by all

   * Easy to use

   * Continuously improving while remaining fast and safe

   * Fun to use and improve

   * Free from bugs

`MySQL AB' and the people at `MySQL AB':
   * Promote `Open Source' philosophy and support the `Open Source'
     community

   * Aim to be good citizens

   * Prefer partners that share our values and mind-set

   * Answer email and provide support

   * Are a virtual company, networking with others

   * Work against software patents

The `MySQL' web site (`http://www.mysql.com/') provides the latest
information about `MySQL' and `MySQL AB'.

By the way, the "AB" part of the company name is the acronym for the
Swedish "aktiebolag", or "stock company."  It translates to "MySQL,
Inc." In fact, MySQL Inc. and MySQL GmbH are examples of MySQL AB
subsidiaries. They are located in the US and Germany, respectively.

The Business Model and Services of MySQL AB
-------------------------------------------

One of the most common questions we encounter is: "_How can you make a
living from something you give away for free?_" This is how:

   * `MySQL AB' makes money on support, services, commercial licenses,
     and royalties.

   * We use these revenues to fund product development and to expand
     the `MySQL' business.

The company has been profitable since its inception. In October 2001,
we accepted venture financing from leading Scandinavian investors and a
handful of business angels. This investment is used to solidify our
business model and build a basis for sustainable growth.

Support
.......

`MySQL AB' is run and owned by the founders and main developers of the
`MySQL' database. The developers are committed to providing support to
customers and other users in order to stay in touch with their needs
and problems. All our support is provided by qualified developers.
Really tricky questions are answered by Michael `Monty' Widenius,
principal author of the `MySQL Server'.  *Note Support::.

For more information and ordering support at various levels, see
`http://www.mysql.com/support/' or contact our sales staff at
<[e-mail]>.

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: <[e-mail]>.

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 <[e-mail]>.

Commercial Licenses
...................

The `MySQL' database is released under the `GNU General Public License'
(`GPL').  This means that the `MySQL' software can be used free of
charge under the `GPL'. If you do not want to be bound by the `GPL'
terms (such as the requirement that your application must also be
`GPL'), you may purchase a commercial license for the same product from
`MySQL AB'; see `http://www.mysql.com/products/pricing.html'.  Since
`MySQL AB' owns the copyright to the `MySQL' source code, we are able
to employ `Dual Licensing', which means that the same product is
available under `GPL' and under a commercial license. This does not in
any way affect the `Open Source' commitment of `MySQL AB'. For details
about when a commercial license is required, please see *Note MySQL
licenses::.

We also sell commercial licenses of third-party `Open Source GPL'
software that adds value to `MySQL Server'. A good example is the
`InnoDB' transactional storage engine that offers `ACID' support,
row-level locking, crash recovery, multi-versioning, foreign key
support, and more. *Note InnoDB::.

Partnering
..........

`MySQL AB' has a worldwide partner program that covers training
courses, consulting and support, publications, plus reselling and
distributing `MySQL' and related products. `MySQL AB Partners' get
visibility on the `http://www.mysql.com/' web site and the right to use
special versions of the `MySQL' trademarks to identify their products
and promote their business.

If you are interested in becoming a `MySQL AB Partner', please email
<[e-mail]>.

The word `MySQL' and the `MySQL' dolphin logo are trademarks of `MySQL
AB'. *Note MySQL AB Logos and Trademarks::.  These trademarks represent
a significant value that the `MySQL' founders have built over the years.

The `MySQL' web site (`http://www.mysql.com/') is popular among
developers and users. In December 2003, we served 16 million page views.
Our visitors represent a group that makes purchase decisions and
recommendations for both software and hardware. Twelve percent of our
visitors authorize purchase decisions, and only nine percent are not
involved in purchase decisions at all. More than 65% have made one or
more online business purchases within the last half-year, and 70% plan
to make one in the next few months.

Contact Information
-------------------

The `MySQL' web site (`http://www.mysql.com/') provides the latest
information about `MySQL' and `MySQL AB'.

For press services and inquiries not covered in our News releases
(`http://www.mysql.com/news/'), please send email to <[e-mail]>.

If you have a valid support contract with `MySQL AB', you will get
timely, precise answers to your technical questions about the `MySQL'
software. For more information, see *Note Support::.  On our web site,
see `http://www.mysql.com/support/', or send an email message to
<[e-mail]>.

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 <[e-mail]>.  *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 <[e-mail]>.  *Note Business
Services Consulting::.

Commercial licenses may be purchased online at
`https://order.mysql.com/'. There you will also find information on how
to fax your purchase order to `MySQL AB'. More information about
licensing can be found at `http://www.mysql.com/products/pricing.html'.
If you have questions regarding licensing or you want a quote for a
high-volume license deal, please fill in the contact form on our web
site (`http://www.mysql.com/') or send email to <[e-mail]>
(for licensing questions) or to <[e-mail]> (for sales inquiries).
*Note MySQL licenses::.

If you represent a business that is interested in partnering with
`MySQL AB', please send email to <[e-mail]>.  *Note Business
Services Partnering::.

For more information on the `MySQL' trademark policy, refer to
`http://www.mysql.com/company/trademark.html' or send email to
<[e-mail]>.  *Note MySQL AB Logos and Trademarks::.

If you are interested in any of the `MySQL AB' jobs listed in our jobs
section (`http://www.mysql.com/company/jobs/'), please send email to
<[e-mail]>.  Please do not send your CV as an attachment, but
rather as plain text at the end of your email message.

For general discussion among our many users, please direct your
attention to the appropriate mailing list.  *Note Questions::.

Reports of errors (often called bugs), as well as questions and
comments, should be sent to the general MySQL mailing list.  *Note
Mailing-list::.  If you have found a sensitive security bug in `MySQL
Server', please let us know immediately by sending an email message to
<[e-mail]>.  *Note Bug reports::.

If you have benchmark results that we can publish, please contact us
via email at <[e-mail]>.

If you have suggestions concerning additions or corrections to this
manual, please send them to the manual team via email at
<[e-mail]>.

For questions or comments about the workings or content of the `MySQL'
web site (`http://www.mysql.com/'), please send email to
<[e-mail]>.

`MySQL AB' has a privacy policy, which can be read at
`http://www.mysql.com/company/privacy.html'.  For any queries regarding
this policy, please send email to <[e-mail]>.

For all other inquires, please send an email to <[e-mail]>.

MySQL Support and Licensing
===========================

This section describes `MySQL' support and licensing arrangements.

Support Offered by MySQL AB
---------------------------

Technical support from `MySQL AB' means individualized answers to your
unique problems direct from the software engineers who code the `MySQL'
database engine.

We try to take a broad and inclusive view of technical support. Almost
any problem involving `MySQL' software is important to us if it's
important to you.  Typically customers seek help on how to get
different commands and utilities to work, remove performance
bottlenecks, restore crashed systems, understand the impact of
operating system or networking issues on `MySQL', set up best practices
for backup and recovery, utilize APIs, and so on.  Our support covers
only the `MySQL' server and our own utilities, not third-party products
that access the `MySQL' server, though we try to help with these where
we can.

Detailed information about our various support options is given at
`http://www.mysql.com/support/', where support contracts can also be
ordered online. If you have restricted access to the Internet, please
contact our sales staff via email at <[e-mail]>.

Technical support is like life insurance. You can live happily without
it for years. However, when your hour arrives, it becomes critically
important, but it's too late to buy it.  If you use `MySQL Server' for
important applications and encounter sudden difficulties, it may be too
time consuming to figure out all the answers yourself. You may need
immediate access to the most experienced `MySQL' troubleshooters
available, those employed by `MySQL AB'.

Copyrights and Licenses Used by MySQL
-------------------------------------

`MySQL AB' owns the copyright to the `MySQL' source code, the `MySQL'
logos and trademarks and this manual.  *Note What is MySQL AB::.
Several different licenses are relevant to the `MySQL' distribution:

  1. All the `MySQL'-specific source in the server, the `mysqlclient'
     library and the client, as well as the `GNU' `readline' library is
     covered by the `GNU General Public License'.  *Note GPL license::.
     The text of this license can be found as the file `COPYING' in the
     distribution.

  2. The `GNU' `getopt' library is covered by the `GNU Lesser General
     Public License'.  See <http://www.fsf.org/licenses/>.

  3. Some parts of the source (the `regexp' library) are covered by a
     Berkeley-style copyright.

  4. Older versions of `MySQL' (3.22 and earlier) are subject to a
     stricter license (`http://www.mysql.com/products/mypl.html').  See
     the documentation of the specific version for information.

  5. The `MySQL' reference manual is currently *not* distributed under
     a `GPL'-style license. Use of the manual is subject to the
     following terms:
        * Conversion to other formats is allowed, but the actual content
          may not be altered or edited in any way.

        * You may create a printed copy for your own personal use.

        * For all other uses, such as selling printed copies or using
          (parts of) the manual in another publication, prior written
          agreement from `MySQL AB' is required.
     Please send an email message to <[e-mail]> 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 <[e-mail]>.

Using the MySQL Software for Free Under GPL
...........................................

You can use the `MySQL' software for free under the `GPL' if you adhere
to the conditions of the `GPL'.  For additional details, including
answers to common questions about the `GPL', see the generic FAQ from
the Free Software Foundation at
`http://www.fsf.org/licenses/gpl-faq.html'.  Common uses of the `GPL'
include:

   * When you distribute both your own application and the `MySQL'
     source code under the `GPL' with your product.

   * When you distribute the `MySQL' source code bundled with other
     programs that are not linked to or dependent on the `MySQL' system
     for their functionality even if you sell the distribution
     commercially.  This is called mere aggregation in the `GPL'
     license.

   * When you are not distributing *any* part of the `MySQL' system,
     you can use it for free.

   * When you are an Internet Service Provider (ISP), offering web
     hosting with `MySQL' servers for your customers.  We encourage
     people to use ISPs that have MySQL support, as this will give them
     the confidence that their ISP will, in fact, have the resources to
     solve any problems they may experience with the `MySQL'
     installation. Even if an ISP does not have a commercial license
     for `MySQL Server', their customers should at least be given read
     access to the source of the `MySQL' installation so that the
     customers can verify that it is correctly patched.

   * When you use the `MySQL' database software in conjunction with a
     web server, you do not need a commercial license (so long as it is
     not a product you distribute). This is true even if you run a
     commercial web server that uses `MySQL Server', because you are not
     distributing any part of the `MySQL' system. However, in this case
     we would like you to purchase `MySQL' support because the `MySQL'
     software is helping your enterprise.

If your use of `MySQL' database software does not require a commercial
license, we encourage you to purchase support from `MySQL AB' anyway.
This way you contribute toward `MySQL' development and also gain
immediate advantages for yourself. *Note Support::.

If you use the `MySQL' database software in a commercial context such
that you profit by its use, we ask that you further the development of
the `MySQL' software by purchasing some level of support.  We feel that
if the `MySQL' database helps your business, it is reasonable to ask
that you help `MySQL AB'.  (Otherwise, if you ask us support questions,
you are not only using for free something into which we've put a lot a
work, you're asking us to provide free support, too.)

MySQL AB Logos and Trademarks
-----------------------------

Many users of the `MySQL' database want to display the `MySQL AB'
dolphin logo on their web sites, books, or boxed products. We welcome
and encourage this, although it should be noted that the word `MySQL'
and the `MySQL' dolphin logo are trademarks of `MySQL AB' and may only
be used as stated in our trademark policy at
`http://www.mysql.com/company/trademark.html'.

The Original MySQL Logo
.......................

The `MySQL' dolphin logo was designed by the Finnish advertising agency
Priority in 2001.  The dolphin was chosen as a suitable symbol for the
`MySQL' database management system, which is like a smart, fast, and
lean animal, effortlessly navigating oceans of data. We also happen to
like dolphins.

The original `MySQL' logo may only be used by representatives of `MySQL
AB' and by those having a written agreement allowing them to do so.

MySQL Logos that may be Used Without Written Permission
.......................................................

We have designed a set of special _Conditional Use_ logos that may be
downloaded from our web site at `http://www.mysql.com/press/logos.html'
and used on third-party web sites without written permission from
`MySQL AB'.  The use of these logos is not entirely unrestricted but,
as the name implies, subject to our trademark policy that is also
available on our web site. You should read through the trademark policy
if you plan to use them. The requirements are basically as follows:

   * Use the logo you need as displayed on the `http://www.mysql.com/'
     site. You may scale it to fit your needs, but may not change
     colors or design, or alter the graphics in any way.

   * Make it evident that you, and not `MySQL AB', are the creator and
     owner of the site that displays the `MySQL' trademark.

   * Don't use the trademark in a way that is detrimental to `MySQL AB'
     or to the value of `MySQL AB' trademarks. We reserve the right to
     revoke the right to use the `MySQL AB' trademark.

   * If you use the trademark on a web site, make it clickable, leading
     directly to `http://www.mysql.com/'.

   * If you use the `MySQL' database under `GPL' in an application,
     your application must be `Open Source' and must be able to connect
     to a `MySQL' server.

Contact us via email at <[e-mail]> to inquire about special
arrangements to fit your needs.

When You Need Written Permission to Use MySQL Logos
...................................................

You need written permission from `MySQL AB' before using `MySQL' logos
in the following cases:

   * When displaying any `MySQL AB' logo anywhere except on your web
     site.

   * When displaying any `MySQL AB' logo except the _Conditional Use_
     logos mentioned previously on web sites or elsewhere.

Due to legal and commercial reasons we monitor the use of MySQL
trademarks on products, books, and other items. We usually require a
fee for displaying `MySQL AB' logos on commercial products, since we
think it is reasonable that some of the revenue is returned to fund
further development of the `MySQL' database.

MySQL AB Partnership Logos
..........................

`MySQL' partnership logos may be used only by companies and persons
having a written partnership agreement with `MySQL AB'. Partnerships
include certification as a `MySQL' trainer or consultant.  For more
information, please see *Note Partnering: Business Services Partnering.

Using the Word `MySQL' in Printed Text or Presentations
.......................................................

`MySQL AB' welcomes references to the `MySQL' database, but it should
be noted that the word `MySQL' is a trademark of `MySQL AB'.  Because
of this, you must append the trademark symbol (`TM') to the first or
most prominent use of the word `MySQL' in a text and, where
appropriate, state that `MySQL' is a trademark of `MySQL AB'. For more
information, please refer to our trademark policy at
`http://www.mysql.com/company/trademark.html'.

Using the Word `MySQL' in Company and Product Names
...................................................

Use of the word `MySQL' in product or company names or in Internet
domain names is not allowed without written permission from `MySQL AB'.

MySQL Development Roadmap
=========================

This section provides a snapshot of the MySQL development roadmap,
including major features implemented or planned for MySQL 4.0, 4.1,
5.0, and 5.1.  The following sections provide information for each
release series.

The production release series is MySQL 4.0, which was declared stable
for production use as of Version 4.0.12, released in March 2003. This
means that future 4.0 development will be limited only to making bug
fixes. For the older MySQL 3.23 series, only critical bug fixes will be
made.

Active MySQL development currently is taking place in the MySQL 4.1 and
5.0 release series. This means that new features are being added to
MySQL 4.1 and MySQL 5.0. Both 4.1 and 5.0 are available now in alpha
status.

Before upgrading from one release series to the next, please see the
notes at *Note Upgrade::.

Plans for some of the most requested features are summarized in the
following table.

*Feature*              *MySQL version*
Unions                 4.0
Subqueries             4.1
R-trees                4.1 (for `MyISAM' tables)
Stored procedures      5.0
Views                  5.0 or 5.1
Cursors                5.0
Foreign keys           5.1 (already implemented in 3.23 for
                       `InnoDB')
Triggers               5.1
Full outer join        5.1
Constraints            5.1

MySQL 4.0 in a Nutshell
-----------------------

Long awaited by our users, MySQL Server 4.0 is now available in
production status.

MySQL 4.0 is available for download from `http://www.mysql.com/' and
from our mirrors. MySQL 4.0 has been tested by a large number of users
and is in production use at many large sites.

The major new features of MySQL Server 4.0 are geared toward our
existing business and community users, enhancing the MySQL database
software as the solution for mission-critical, heavy-load database
systems.  Other new features target the users of embedded databases.

Features Available in MySQL 4.0
...............................

Speed enhancements
        * MySQL 4.0 has a query cache that can give a huge speed boost
          to applications with repetitive queries. *Note Query Cache::.

        * Version 4.0 further increases the speed of MySQL Server in a
          number of areas, such as bulk `INSERT' statements, searching
          on packed indexes, full-text searching (using `FULLTEXT'
          indexes), and `COUNT(DISTINCT)'.

Embedded MySQL Server introduced
        * The new Embedded Server library can easily be used to create
          standalone and embedded applications.  The embedded server
          provides an alternative to using MySQL in a client/server
          environment.  *Note Nutshell Embedded MySQL::.

InnoDB storage engine as standard
        * The `InnoDB' storage engine is now offered as a standard
          feature of the `MySQL' server. This means full support for
          ACID transactions, foreign keys with cascading `UPDATE' and
          `DELETE', and row-level locking are now standard features.
          *Note `InnoDB': InnoDB.

New functionality
        * The enhanced `FULLTEXT' search properties of MySQL Server 4.0
          enables `FULLTEXT' indexing of large text masses with both
          binary and natural-language searching logic. You can
          customize minimal word length and define your own stop word
          lists in any human language, enabling a new set of
          applications to be built with MySQL Server.  *Note Fulltext
          Search::.

Standards compliance, portability, and migration
        * Many users will also be happy to learn that MySQL Server now
          supports the `UNION' statement, a long-awaited standard SQL
          feature.

        * MySQL now runs natively on the Novell NetWare 6.0 platform.
          *Note NetWare installation::.

        * Features to simplify migration from other database systems to
          MySQL Server include `TRUNCATE TABLE' (as in Oracle).

Internationalization
        * Our German, Austrian, and Swiss users will note that `MySQL'
          now supports a new character set, `latin1_de', which ensures
          that the _German sorting order_ sorts words with umlauts in
          the same order as do German telephone books.

Usability enhancements
     In the process of implementing features for new users, we have not
     forgotten requests from our loyal community of existing users.

        * Most `mysqld' parameters (startup options) can now be set
          without taking down the server. This is a convenient feature
          for database administrators (DBAs).  *Note `SET OPTION': SET
          OPTION.

        * Multiple-table `DELETE' and `UPDATE' statements have been
          added..

        * On Windows, symbolic link handling at the database level is
          enabled by default.  On Unix, the `MyISAM' storage engine now
          supports symbolic linking at the table level (and not just
          the database level as before).

        * `SQL_CALC_FOUND_ROWS' and `FOUND_ROWS()' are new functions
          that make it possible to find out the number of rows a
          `SELECT' query that includes a `LIMIT' clause would have
          returned without that clause.

The news section of this manual includes a more in-depth list of
features.  *Note News-4.0.x::.

The Embedded MySQL Server
.........................

The `libmysqld' embedded server library makes MySQL Server suitable for
a vastly expanded realm of applications. By using this library,
developers can embed MySQL Server into various applications and
electronics devices, where the end user has no knowledge of there
actually being an underlying database. Embedded MySQL Server is ideal
for use behind the scenes in Internet appliances, public kiosks, turnkey
hardware/software combination units, high performance Internet servers,
self-contained databases distributed on CD-ROM, and so on.

Many users of `libmysqld' will benefit from the MySQL _Dual Licensing_.
For those not wishing to be bound by the `GPL', the software is also
made available under a commercial license.  The embedded MySQL library
uses the same interface as the normal client library, so it is
convenient and easy to use.  *Note `libmysqld': libmysqld.

MySQL 4.1 in a Nutshell
-----------------------

MySQL Server 4.0 laid the foundation for new features implemented in
MySQL 4.1, such as subqueries and Unicode support, and for the work on
stored procedures being done in version 5.0.  These features come at
the top of the wish list of many of our customers.

With these additions, critics of the MySQL Database Server have to be
more imaginative than ever in pointing out deficiencies in the MySQL
database management system. Already well-known for its stability,
speed, and ease of use, MySQL Server will be able to fulfill the
requirement checklists of very demanding buyers.

Features Available in MySQL 4.1
...............................

The features listed in this section are implemented in MySQL 4.1. A few
other features are still planned for MySQL 4.1. *Note TODO MySQL 4.1::.

Most new features being coded are or will be available in MySQL 5.0.
*Note TODO MySQL 5.0::.

Support for subqueries and derived tables
        * A subquery is a `SELECT' statement nested within another
          statement.  A derived table (an unnamed view) is a subquery
          in the `FROM' clause of another statement.  *Note
          Subqueries::.

Speed enhancements
        * Faster binary client/server protocol with support for
          prepared statements and parameter binding.  *Note C API
          Prepared statements::.

        * `BTREE' indexing is now supported for `HEAP' tables,
          significantly improving response time for non-exact searches.

New functionality
        * `CREATE TABLE table_name2 LIKE table_name1' allows you to
          create, with a single statement, a new table with a structure
          exactly like that of an existing table.

        * The MyISAM storage engine now supports OpenGIS spatial types
          for storing geographical data.  *Note Spatial extensions in
          MySQL::.

        * Replication can be done over SSL connections.

Standards compliance, portability, and migration
        * The new client/server protocol adds the ability to pass
          multiple warnings to the client, rather than only a single
          result. This makes operations such as bulk data loading much
          easier to track.

        * `SHOW WARNINGS' shows warnings for the last command.  *Note
          `SHOW WARNINGS': SHOW WARNINGS.

Internationalization
        * To support applications that require the use of local
          languages, the MySQL software now offers extensive Unicode
          support through the `utf8' and `ucs2' character sets.

        * Character sets can now be defined per column, table, and
          database.  This allows for a high degree of flexibility in
          application design, particularly for multi-language web sites.

        * For documentation for this improved character set support,
          see *Note Charset::.

Usability enhancements
        * In response to popular demand, we have added a server-based
          `HELP' command that can be used to get help information for
          SQL statements.  The advantage of having this information on
          the server side is that the information is always applicable
          to the particular server version that you actually are using.
          Because this information is available by issuing a SQL
          statement, any client can be written to access it.  For
          example, the `help' command of the `mysql' command-line client
          has been modified to have this capability.

        * In the new client/server protocol, multiple statements can be
          issued with a single call.  *Note C API multiple queries::.

        * The new client/server protocol also supports returning
          multiple result sets.  This might occur as a result of
          sending multiple statements, for example.

        * A new `INSERT ... ON DUPLICATE KEY UPDATE ...' syntax has been
          implemented. This allows you to `UPDATE' an existing row if
          the `INSERT' would have caused a duplicate in a `PRIMARY' or
          `UNIQUE' key (index).  *Note `INSERT': INSERT.

        * A new aggregate function, `GROUP_CONCAT()' adds the extremely
          useful capability of concatenating column values from grouped
          rows into a single result string.  *Note Group by functions
          and modifiers::.

The news section of this manual includes a more in-depth list of
features.  *Note News-4.1.x::.

Stepwise Rollout
................

New features are being added to MySQL 4.1. The alpha version is already
available for download. *Note Nutshell Ready for Immediate Use::.

The set of features that are being added to version 4.1 is mostly
fixed. Additional development is already ongoing for version 5.0.
MySQL 4.1 will go through the steps of _Alpha_ (during which time new
features might still be added/changed), _Beta_ (when we have feature
freeze and only bug corrections will be done), and _Gamma_ (indicating
that a production release is just weeks ahead).  At the end of this
process, MySQL 4.1 will become the new production release.

Ready for Immediate Development Use
...................................

MySQL 4.1 is currently in the alpha stage, and binaries are available
for download at `http://www.mysql.com/downloads/mysql-4.1.html'.  All
binary releases pass our extensive test suite without any errors on the
platforms on which we test.  *Note News-4.1.x::.

For those wishing to use the most recent development source for MySQL
4.1, we make our 4.1 BitKeeper repository publicly available.  *Note
Installing source tree::.

MySQL 5.0, The Next Development Release
---------------------------------------

New development for MySQL is focused on the 5.0 release, featuring
Stored Procedures and other new features.  *Note TODO MySQL 5.0::.

For those wishing to take a look at the bleeding edge of MySQL
development, we make our BitKeeper repository for MySQL version 5.0
publicly available.  *Note Installing source tree::.  As of December
2003, binary builds of version 5.0 are also available.

MySQL and the Future (The TODO)
===============================

This section summarizes the features that we plan to implement in
`MySQL Server'. The items are ordered by release series. Within a list,
items are shown in approximately the order they will be done.

*Note:* If you are an enterprise level user with an urgent need for a
particular feature, please contact <[e-mail]> to discuss
sponsoring options. Targeted financing by sponsor companies allows us
to allocate additional resources for specific purposes.  One example of
a feature sponsored in the past is replication.

New Features Planned for 4.1
----------------------------

The features below are not yet implemented in MySQL 4.1, but are planned
for implementation before MySQL 4.1 moves into its beta phase.  For a
list what is already done in MySQL 4.1, see *Note Nutshell 4.1
features::.

   * Stable OpenSSL support (MySQL 4.0 supports rudimentary, not 100%
     tested, support for OpenSSL).

   * More testing of prepared statements.

   * More testing of multiple character sets for one table.

New Features Planned for 5.0
----------------------------

The following features are planned for inclusion into MySQL 5.0.  Some
of the features such as stored procedures are complete and are included
in MySQL 5.0 alpha, which is available now.  Others such as cursors are
only partially available. Expect these and other features to mature and
be fully supported in upcoming releases.

Note that because we have many developers that are working on different
projects, there will also be many additional features. There is also a
small chance that some of these features will be added to MySQL 4.1.
For a list what is already done in MySQL 4.1, see *Note Nutshell 4.1
features::.

For those wishing to take a look at the bleeding edge of MySQL
development, we make our BitKeeper repository for MySQL version 5.0
publicly available.  *Note Installing source tree::.  As of December
2003, binary builds of version 5.0 are also available.

Stored Procedures
        * Stored procedures are currently implemented, based on the
          SQL:2003 standard.  *Note Stored Procedures::.

          We will also implement a framework to hook in external
          languages, and (where possible) compatibility with, for
          example, PL/SQL and T-SQL.

New functionality
        * Elementary cursor support.  *Note Cursors::.

        * The ability to specify explicitly for `MyISAM' tables that an
          index should be created as an `RTREE' index.  (In MySQL 4.1,
          `RTREE' indexes are used internally for geometrical data that
          use GIS datatypes, but cannot be created on request.)

        * Dynamic length rows for `HEAP' tables.

Standards compliance, portability and migration
        * Add true `VARCHAR' support (column lengths longer than 255,
          and no stripping of trailing whitespace).  (There is already
          support for this in the `MyISAM' storage engine, but it is
          not yet available at the user level.)

Speed enhancements
        * `SHOW COLUMNS FROM table_name' (used by `mysql' client to
          allow expansions of column names) should not open the table,
          only the definition file. This will require less memory and
          be much faster.

        * Allow `DELETE' on `MyISAM' tables to use the record cache.
          To do this, we need to update the threads record cache when
          we update the `.MYD' file.

        * Better support for `MEMORY' (`HEAP') tables:
             * Dynamic length rows.

             * Faster row handling (less copying).

Usability enhancements
        * Resolving the issue of `RENAME TABLE' on a table used in an
          active `MERGE' table possibly corrupting the table.

The news section of this manual includes a more in-depth list of
features.  *Note News-5.0.x::.

New Features Planned for 5.1
----------------------------

New functionality
        * `FOREIGN KEY' support for all table types, not just `InnoDB'.

        * Column-level constraints.

        * Fail-safe replication.

        * Online backup with very low performance penalty.  The online
          backup will make it easy to add a new replication slave
          without taking down the master.

Speed enhancements
        * New text based table definition file format (`.frm' files)
          and a table cache for table definitions.  This will enable us
          to do faster queries of table structures and do more
          efficient foreign key support.

        * Optimize the `BIT' type to take 1 bit. (`BIT' now takes 1
          byte; it is treated as a synonym for `TINYINT'.)

Usability enhancements
        * Add options to the client/server protocol to get progress
          notes for long running commands.

        * Implement `RENAME DATABASE'. To make this safe for all
          storage engines, it should work as follows:
             * Create the new database.

             * For every table do a rename of the table to another
               database, as we do with the `RENAME' command.

             * Drop the old database.

        * New internal file interface change.  This will make all file
          handling much more general and make it easier to add
          extensions like RAID.

New Features Planned for the Near Future
----------------------------------------

New functionality
        * Oracle-like `CONNECT BY PRIOR ...' to search tree-like
          (hierarchical) structures.

        * Add all missing SQL-92 and ODBC 3.0 types.

        * Add `SUM(DISTINCT)'.

        * `INSERT SQL_CONCURRENT' and `mysqld --concurrent-insert' to do
          a concurrent insert at the end of a table if the table is
          read-locked.

        * Allow variables to be updated in `UPDATE' statements. For
          example: `UPDATE TABLE foo SET @a=a+b,a=@a, b=@a+c'.

        * Change when user variables are updated so that one can use
          them with `GROUP BY', as in the following example: `SELECT
          id, @a:=COUNT(*), SUM(sum_col)/@a FROM table_name GROUP BY
          id'.

        * Add an `IMAGE' option to `LOAD DATA INFILE' to not update
          `TIMESTAMP' and `AUTO_INCREMENT' fields.

        * Add `LOAD DATA INFILE ... UPDATE' syntax that works like this:
             * For tables with primary keys, if an input record
               contains a primary key value, existing rows matching
               that primary key value are updated from the remainder of
               the input columns. However, columns corresponding to
               columns that are *missing* from the input record are not
               touched.

             * For tables with primary keys, if an input record does
               not contain the primary key value or is missing some
               part of the key, the record is treated as `LOAD DATA
               INFILE ... REPLACE INTO'.

        * Make `LOAD DATA INFILE' understand syntax like:
               LOAD DATA INFILE 'file_name.txt' INTO TABLE tbl_name
                    TEXT_FIELDS (text_field1, text_field2, text_field3)
                    SET table_field1=CONCAT(text_field1, text_field2),
                        table_field3=23
                    IGNORE text_field3
          This can be used to skip over extra columns in the text file,
          or update columns based on expressions of the read data.

        * New functions for working with `SET' type columns:
             * `ADD_TO_SET(value,set)'

             * `REMOVE_FROM_SET(value,set)'

        * If you abort `mysql' in the middle of a query, you should open
          another connection and kill the old running query.
          Alternatively, an attempt should be made to detect this in
          the server.

        * Add a storage engine interface for table information so that
          you can use it as a system table. This would be a bit slow if
          you requested information about all tables, but very
          flexible.  `SHOW INFO FROM tbl_name' for basic table
          information should be implemented.

        * Allow `SELECT a FROM table_name1 LEFT JOIN table_name2 USING
          (a)'; in this case `a' is assumed to come from the
          `table_name1' table.

        * `DELETE' and `REPLACE' options to the `UPDATE' statement
          (this will delete rows when one gets a duplicate key error
          while updating).

        * Change the format of `DATETIME' to store fractions of seconds.

        * Make it possible to use the new GNU `regexp' library instead
          of the current one (the new library should be much faster
          than the current one).

Standards compliance, portability and migration
        * Don't add automatic `DEFAULT' values to columns.  Produce an
          error for any `INSERT' statement that is missing a value for
          a column that has no `DEFAULT'.

        * Add `ANY()', `EVERY()', and `SOME()' group functions. In
          standard SQL, these work only on boolean columns, but we can
          extend these to work on any columns or expressions by
          treating 0 values as FALSE and non-zero values as TRUE.

        * Fix the type of `MAX(column)' to be the same as the column
          type:
               mysql> CREATE TABLE t1 (a DATE);
               mysql> INSERT INTO t1 VALUES (NOW());
               mysql> CREATE TABLE t2 SELECT MAX(a) FROM t1;
               mysql> SHOW COLUMNS FROM t2;

Speed enhancements
        * Don't allow more than a defined number of threads to run
          `MyISAM' recovery at the same time.

        * Change `INSERT ... SELECT' to optionally use concurrent
          inserts.

        * Add an option to periodically flush key pages for tables with
          delayed keys if they haven't been used in a while.

        * Allow join on key parts (optimization issue).

        * Add a log file analyzer that can parse out information about
          which tables are hit most often, how often multiple-table
          joins are executed, etc.  This should help users identify
          areas of table design that could be optimized to execute much
          more efficient queries.

Internationalization

Usability enhancements
        * Return the original column types when doing `SELECT
          MIN(column) ... GROUP BY'.

        * Make it possible to specify `long_query_time' with a
          granularity in microseconds.

        * Link the `myisampack' code into the server so that it can
          perform `PACK' or `COMPRESS' operations.

        * Add a temporary key buffer cache during
          `INSERT/DELETE/UPDATE' so that we can gracefully recover if
          the index file gets full.

        * If you perform an `ALTER TABLE' on a table that is symlinked
          to another disk, create temporary tables on that disk.

        * Implement a `DATE/DATETIME' type that handles time zone
          information properly, to make dealing with dates in different
          time zones easier.

        * Fix `configure' so that one can compile all libraries (like
          `MyISAM') without threads.

        * Allow SQL variables as `LIMIT' arguments, for example, `LIMIT
          @a,@b'.

        * Automatic output from `mysql' to a web browser.

        * `LOCK DATABASES' (with various options).

        * Many more variables for `SHOW STATUS'.  Records reads and
          updates.  Selects on a single table and selects with joins.
          Mean number of tables in select. Number of `ORDER BY' and
          `GROUP BY' queries.

        * `mysqladmin copy database new-database'; this requires a
          `COPY' operation to be added to `mysqld'.

        * Processlist output should indicate the number of
          queries/threads.

        * `SHOW HOSTS' for printing information about the hostname
          cache.

        * Change table names from empty strings to `NULL' for
          calculated columns.

        * Don't use `Item_copy_string' on numerical values to avoid
          number->string->number conversion in case of: `SELECT
          COUNT(*)*(id+0) FROM table_name GROUP BY id'

        * Change so that `ALTER TABLE' doesn't abort clients that
          execute `INSERT DELAYED'.

        * Fix so that when columns are referenced in an `UPDATE' clause,
          they contain the old values from before the update started.

New operating systems
        * Port the MySQL clients to LynxOS.

New Features Planned for the Mid-Term Future
--------------------------------------------

   * Implement function:
     `get_changed_tables(timeout,table1,table2,...)'.

   * Change reading through tables to use memmap when possible. Now only
     compressed tables use memmap.

   * Make the automatic timestamp code nicer.  Add timestamps to the
     update log with `SET TIMESTAMP=#;'.

   * Use read/write mutex in some places to get more speed.

   * Simple views (implemented in stepwise fashion up to full
     functionality).  *Note ANSI diff Views::.

   * Automatically close some tables if a table, temporary table, or
     temporary file gets error 23 (too many open files).

   * Better constant propagation. When an occurrence of `col_name=n' is
     found in an expression, for some constant `n', replace other
     occurrences of `col_name' within the expression with `n'.
     Currently, this is done only for some simple cases.

   * Change all const expressions with calculated expressions if
     possible.

   * Optimize key = expression comparisons. At the moment only key =
     field or key = constant comparisons are optimized.

   * Join some of the copy functions for nicer code.

   * Change `sql_yacc.yy' to an inline parser to reduce its size and get
     better error messages.

   * Change the parser to use only one rule per different number of
     arguments in function.

   * Use of full calculation names in the order part (for ACCESS97).

   * `MINUS', `INTERSECT', and `FULL OUTER JOIN'.  (Currently `UNION'
     [in 4.0] and `LEFT|RIGHT OUTER JOIN' are supported.)

   * Allow `SQL_OPTION MAX_SELECT_TIME=#', for placing a time limit on
     a query.

   * Allow updates to be logged to a database.

   * Enhance `LIMIT' to allow retrieval of data from the end of a
     result set.

   * Alarm around client connect/read/write functions.

   * Please note the changes to `mysqld_safe': according to FSSTND
     (which Debian tries to follow) PID files should go into
     `/var/run/<progname>.pid' and log files into `/var/log'. It would
     be nice if you could put the "DATADIR" in the first declaration of
     "pidfile" and "log", so the placement of these files can be
     changed with a single statement.

   * Allow a client to request logging.

   * Allow the `LOAD DATA INFILE' statement to read files that have
     been compressed with `gzip'.

   * Fix sorting and grouping of `BLOB' columns (partly solved now).

   * Change to use semaphores when counting threads.  One should first
     implement a semaphore library for MIT-pthreads.

   * Add full support for `JOIN' with parentheses.

   * As an alternative to the one-thread-per-connection model, manage a
     pool of threads to handle queries.

   * Allow `GET_LOCK()' to obtain more than one lock.  When doing this,
     one must also handle the possible deadlocks this change will
     introduce.

New Features We Don't Plan to Implement
---------------------------------------

We aim toward full compliance with SQL-92/SQL-99, so there are no
features we plan not to implement.

MySQL Information Sources
=========================

MySQL Mailing Lists
-------------------

This section introduces you to the MySQL mailing lists and provides
some guidelines as to how the lists should be used. When you subscribe
to a mailing list, you will receive all postings to the list as email
messages. You can also to send your own questions and answers to the
list.

The MySQL Mailing Lists
.......................

To subscribe to or unsubscribe from any of the mailing lists described
in this section, visit `http://lists.mysql.com/'.  Please *do not* send
messages about subscribing or unsubscribing to any of the mailing
lists, because such messages are distributed automatically to thousands
of other users.

Your local site may have many subscribers to a MySQL mailing list.  If
so, the site may have a local mailing list, so that messages sent from
`lists.mysql.com' to your site are propagated to the local list.  In
such cases, please contact your system administrator to be added to or
dropped from the local MySQL list.

If you wish to have traffic for a mailing list go to a separate mailbox
in your mail program, set up a filter based on the message headers.
You can use either the `List-ID:' or `Delivered-To:' headers to identify
list messages.

The MySQL mailing lists are as follows:

``announce''
     This list is for announcements of new versions of MySQL and related
     programs.  This is a low-volume list to which all MySQL users
     should subscribe.

``mysql''
     This is the main list for general MySQL discussion.  Please note
     that some topics are better discussed on the more-specialized
     lists.  If you post to the wrong list, you may not get an answer.

``mysql-digest''
     This is the `mysql' list in digest form.  Subscribing to this list
     means you will get all list messages, sent as one large mail
     message once a day.

``bugs''
     This list will be of interest to you if you want to stay informed
     about issues reported since the last release of `MySQL' or if you
     want to be actively involved in the process of bug hunting and
     fixing.  *Note Bug reports::.

``bugs-digest''
     This is the `bugs' list in digest form.

``internals''
     This list is for people who work on the MySQL code.  This is also
     the forum for discussions on MySQL development and post patches.

``internals-digest''
     This is the `internals' list in digest form.

``mysqldoc''
     This list is for people who work on the MySQL documentation:
     people from MySQL AB, translators, and other community members.

``mysqldoc-digest''
     This is the `mysqldoc' list in digest form.

``benchmarks''
     This list is for anyone interested in performance issues.
     Discussions concentrate on database performance (not limited to
     MySQL) but also include broader categories such as performance of
     the kernel, file system, disk system, and so on.

``benchmarks-digest''
     This is the `benchmarks' list in digest form.

``packagers''
     This list is for discussions on packaging and distributing MySQL.
     This is the forum used by distribution maintainers to exchange
     ideas on packaging MySQL and on ensuring that MySQL looks and
     feels as similar as possible on all supported platforms and
     operating systems.

``packagers-digest''
     This is the `packagers' list in digest form.

``java''
     This list is for discussions about the MySQL server and Java.It is
     mostly used to discuss JDBC drivers, including MySQL Connector/J.

``java-digest''
     This is the `java' list in digest form.

``win32''
     This list is for all topics concerning the MySQL software on
     Microsoft operating systems, such as Windows 9x/Me/NT/2000/XP.

``win32-digest''
     This is the `win32' list in digest form.

``myodbc''
     This list is for all topics concerning connecting to the MySQL
     server with ODBC.

``myodbc-digest''
     This is the `myodbc' list in digest form.

``mysqlcc''
     This list is for all topics concerning the `MySQL Control Center'
     graphical client.

``mysqlcc-digest''
     This is the `mysqlcc' list in digest form.

``plusplus''
     This list is for all topics concerning programming with the C++
     API to MySQL.

``plusplus-digest''
     This is the `plusplus' list in digest form.

``msql-mysql-modules''
     This list is for all topics concerning the Perl support for MySQL
     with `msql-mysql-modules', which is now named `DBD::mysql'.

``msql-mysql-modules-digest''
     This is the `msql-mysql-modules' list in digest form.

If you're unable to get an answer to your questions from a `MySQL'
mailing list, one option is to purchase support from MySQL AB. This
will put you in direct contact with MySQL developers. *Note Support::.

The following table shows some MySQL mailing lists in languages other
than English.  These lists are not operated by MySQL AB.

`<[e-mail]>'
     A French mailing list.

`<[e-mail]>'
     A Korean mailing list.  Email `subscribe mysql [e-mail]'
     to this list.

`<[e-mail]>'
     A German mailing list.  Email `subscribe mysql-de
     [e-mail]' to this list.  You can find information about
     this mailing list at `http://www.4t2.com/mysql/'.

`<[e-mail]>'
     A Portuguese mailing list.  Email `subscribe mysql-br
     [e-mail]' to this list.

`<[e-mail]>'
     A Spanish mailing list.  Email `subscribe mysql
     [e-mail]' to this list.

Asking Questions or Reporting Bugs
..................................

Before posting a bug report or question, please do the following:

   * Start by searching the MySQL online manual at
     `http://www.mysql.com/doc/'.  We try to keep the manual up to date
     by updating it frequently with solutions to newly found problems.
     The change history appendix
     (`http://www.mysql.com/doc/en/News.html') can be particularly
     useful since it is quite possible that a newer version already
     contains a solution to your problem.

   * Search in the bugs database at `http://bugs.mysql.com/' to see
     whether the bug has already been reported and fixed.

   * Search the MySQL mailing list archives at
     `http://lists.mysql.com/'.

   * You can also use `http://www.mysql.com/search/' to search all the
     web pages (including the manual) that are located at the MySQL AB
     web site.

If you can't find an answer in the manual or the archives, check with
your local MySQL expert.  If you still can't find an answer to your
question, please follow the guidelines on sending mail to a MySQL
mailing list, outlined in the next section, before contacting us.

How to Report Bugs or Problems
..............................

The normal place to report bugs is `http://bugs.mysql.com/', which is
the address for our bugs database.  This database is public, and can be
browsed and searched by anyone.  If you log into the system, you will
also be able to enter new reports.

Writing a good bug report takes patience, but doing it right the first
time saves time both for us and for yourself.  A good bug report,
containing a full test case for the bug, makes it very likely that we
will fix the bug in the next release.  This section will help you write
your report correctly so that you don't waste your time doing things
that may not help us much or at all.

We encourage everyone to use the `mysqlbug' script to generate a bug
report (or a report about any problem).  `mysqlbug' can be found in the
`scripts' directory (source distribution) and in the `bin' directory
under your MySQL installation directory (binary distribution).  If you
are unable to use `mysqlbug' (for instance, if you are running on
Windows), it is still vital that you include all the necessary
information noted in this section (most importantly a description of
the operating system and the MySQL version).

The `mysqlbug' script helps you generate a report by determining much
of the following information automatically, but if something important
is missing, please include it with your message.  Please read this
section carefully and make sure that all the information described here
is included in your report.

Preferably, you should test the problem using the latest production or
development version of MySQL Server before posting.  Anyone should be
able to repeat the bug by just using '`mysql test < script'' on the
included test case or by running the shell or Perl script that is
included in the bug report.

All bugs posted in the bugs database at `http://bugs.mysql.com/' will
be corrected or documented in the next MySQL release. If only minor
code changes are needed to correct a problem, we will also post a patch
that fixes the problem.

If you have found a sensitive security bug in MySQL, please send an
email to <[e-mail]>.

If you have a repeatable bug report, please report it to the bugs
database at `http://bugs.mysql.com/'.  Note that even in this case it's
good to run the `mysqlbug' script first to find information about your
system.  Any bug that we are able to repeat has a high chance of being
fixed in the next MySQL release.

To report other problems, you can use one of the MySQL mailing lists.

Remember that it is possible for us to respond to a message containing
too much information, but not to one containing too little.  People
often omit facts because they think they know the cause of a problem
and assume that some details don't matter.  A good principle is: If you
are in doubt about stating something, state it.  It is faster and less
troublesome to write a couple more lines in your report than to wait
longer for the answer if we must ask you to provide information that
was missing from the initial report.

The most common errors made in bug reports are (a) not including the
version number of the MySQL distribution used and (b) not fully
describing the platform on which the MySQL server is installed
(including the platform type and version number).  This is highly
relevant information, and in 99 cases out of 100 the bug report is
useless without it.  Very often we get questions like, "Why doesn't
this work for me?" Then we find that the feature requested wasn't
implemented in that MySQL version, or that a bug described in a report
has already been fixed in newer MySQL versions.  Sometimes the error is
platform-dependent; in such cases, it is next to impossible for us to
fix anything without knowing the operating system and the version
number of the platform.

If you compiled MySQL from source, remember also to provide information
about your compiler, if it is related to the problem.  Often people
find bugs in compilers and think the problem is MySQL-related.  Most
compilers are under development all the time and become better version
by version.  To determine whether your problem depends on your
compiler, we need to know what compiler you use.  Note that every
compiling problem should be regarded as a bug and reported accordingly.

It is most helpful when a good description of the problem is included
in the bug report.  That is, give a good example of everything you did
that led to the problem and describe, in exact detail, the problem
itself.  The best reports are those that include a full example showing
how to reproduce the bug or problem.  *Note Reproduceable test case::.

If a program produces an error message, it is very important to include
the message in your report.  If we try to search for something from the
archives using programs, it is better that the error message reported
exactly matches the one that the program produces.  (Even the case
should be observed.)  You should never try to remember what the error
message was; instead, copy and paste the entire message into your
report.

If you have a problem with Connector/ODBC (MyODBC), please try to
generate a MyODBC trace file and send it with your report.  *Note
MyODBC bug report::.

Please remember that many of the people who will read your report will
do so using an 80-column display.  When generating reports or examples
using the `mysql' command-line tool, you should therefore use the
`--vertical' option (or the `\G' statement terminator) for output that
would exceed the available width for such a display (for example, with
the `EXPLAIN SELECT' statement; see the example later in this section).

Please include the following information in your report:

   * The version number of the MySQL distribution you are using (for
     example, MySQL Version 4.0.12). You can find out which version you
     are running by executing `mysqladmin version'.  `mysqladmin' can be
     found in the `bin' directory under your MySQL installation
     directory.

   * The manufacturer and model of the machine on which you experience
     the problem.

   * The operating system name and version.  If you work with Windows,
     you can usually get the name and version number by double-clicking
     your "My Computer" icon and pulling down the "Help/About Windows"
     menu.  For most Unix-like operating systems, you can get this
     information by executing the command `uname -a'.

   * Sometimes the amount of memory (real and virtual) is relevant. If
     in doubt, include these values.

   * If you are using a source distribution of the MySQL software, the
     name and version number of the compiler used is needed.  If you
     have a binary distribution, the distribution name is needed.

   * If the problem occurs during compilation, include the exact error
     messages and also a few lines of context around the offending code
     in the file where the error occurrs.

   * If `mysqld' died, you should also report the query that crashed
     `mysqld'.  You can usually find this out by running `mysqld' with
     logging enabled.  *Note Using log files::.

   * If a database table is related to the problem, include the output
     from `mysqldump --no-data db_name tbl_name1 tbl_name2 ...'.  This
     is very easy to do and is a powerful way to get information about
     any table in a database.  The information will help us create a
     situation matching the one you have.

   * For speed-related bugs or problems with `SELECT' statements, you
     should always include the output of `EXPLAIN SELECT ...', and at
     least the number of rows that the `SELECT' statement produces.  You
     should also include the output from `SHOW CREATE TABLE tbl_name'
     for each involved table. The more information you give about your
     situation, the more likely it is that someone can help you.

     The following is an example of a very good bug report. It should
     be posted with the `mysqlbug' script.  The example uses the `mysql'
     command-line tool. Note the use of the `\G' statement terminator
     for statements whose output width would otherwise exceed that of
     an 80-column display device.

          mysql> SHOW VARIABLES;
          mysql> SHOW COLUMNS FROM ...\G
                 <output from SHOW COLUMNS>
          mysql> EXPLAIN SELECT ...\G
                 <output from EXPLAIN>
          mysql> FLUSH STATUS;
          mysql> SELECT ...;
                 <A short version of the output from SELECT,
                 including the time taken to run the query>
          mysql> SHOW STATUS;
                 <output from SHOW STATUS>

   * If a bug or problem occurs while running `mysqld', try to provide
     an input script that will reproduce the anomaly.  This script
     should include any necessary source files.  The more closely the
     script can reproduce your situation, the better.  If you can make
     a reproducible test case, you should post it on
     `http://bugs.mysql.com/' for high-priority treatment.

     If you can't provide a script, you should at least include the
     output from `mysqladmin variables extended-status processlist' in
     your mail to provide some information on how your system is
     performing.

   * If you can't produce a test case with only a few rows, or if the
     test table is too big to be mailed to the mailing list (more than
     10 rows), you should dump your tables using `mysqldump' and create
     a `README' file that describes your problem.

     Create a compressed archive of your files using `tar' and `gzip'
     or `zip', and use `ftp' to transfer the archive to
     `ftp://support.mysql.com/pub/mysql/secret/'.  Then enter the
     problem into our bugs database at `http://bugs.mysql.com/'.

   * If you think that the MySQL server produces a strange result from
     a query, include not only the result, but also your opinion of
     what the result should be, and an account describing the basis for
     your opinion.

   * When giving an example of the problem, it's better to use the
     variable names, table names, etc., that exist in your actual
     situation than to come up with new names.  The problem could be
     related to the name of a variable or table.  These cases are rare,
     perhaps, but it is better to be safe than sorry.  After all, it
     should be easier for you to provide an example that uses your
     actual situation, and it is by all means better for us.  In case
     you have data you don't want to show to others, you can use `ftp'
     to transfer it to `ftp://support.mysql.com/pub/mysql/secret/'.  If
     the data is really top secret and you don't want to show it even
     to us, then go ahead and provide an example using other names, but
     please regard this as the last choice.

   * Include all the options given to the relevant programs, if
     possible.  For example, indicate the options that you use when you
     start the `mysqld' server as well as the options that you use to
     run any MySQL client programs.  The options to programs like
     `mysqld' and `mysql', and to the `configure' script, are often
     keys to answers and are very relevant.  It is never a bad idea to
     include them.  If you use any modules, such as Perl or PHP, please
     include the version numbers of those as well.

   * If your question is related to the privilege system, please
     include the output of `mysqlaccess', the output of `mysqladmin
     reload', and all the error messages you get when trying to
     connect.  When you test your privileges, you should first run
     `mysqlaccess'.  After this, execute `mysqladmin reload version'
     and try to connect with the program that gives you trouble.
     `mysqlaccess' can be found in the `bin' directory under your MySQL
     installation directory.

   * If you have a patch for a bug, do include it.  But don't assume
     the patch is all we need, or that we will use it, if you don't
     provide some necessary information such as test cases showing the
     bug that your patch fixes.  We might find problems with your patch
     or we might not understand it at all; if so, we can't use it.

     If we can't verify exactly what the purpose of the patch is, we
     won't use it.  Test cases will help us here.  Show that the patch
     will handle all the situations that may occur.  If we find a
     borderline case (even a rare one) where the patch won't work, it
     may be useless.

   * Guesses about what the bug is, why it occurs, or what it depends on
     are usually wrong.  Even the MySQL team can't guess such things
     without first using a debugger to determine the real cause of a
     bug.

   * Indicate in your bug report that you have checked the reference
     manual and mail archive so that others know you have tried to
     solve the problem yourself.

   * If you get a `parse error', please check your syntax closely.  If
     you can't find something wrong with it, it's extremely likely that
     your current version of MySQL Server doesn't support the syntax
     you are using.  If you are using the current version and the
     manual at `http://www.mysql.com/doc/' doesn't cover the syntax you
     are using, MySQL Server doesn't support your query.  In this case,
     your only options are to implement the syntax yourself or email
     <[e-mail]> and ask for an offer to implement it.

     If the manual covers the syntax you are using, but you have an
     older version of MySQL Server, you should check the MySQL change
     history to see when the syntax was implemented.  In this case, you
     have the option of upgrading to a newer version of MySQL Server.
     *Note News::.

   * If your problem is that your data appears corrupt or you get errors
     when you access a particular table, you should first check and
     then try to repair your tables with `CHECK TABLE' and `REPAIR
     TABLE' or with `myisamchk'.  *Note MySQL Database Administration::.

     If you are running Windows, please check that
     `lower_case_table_names is 1 or 2' with `SHOW VARIABLES LIKE
     'lower_case_table_names''.

   * If you often get corrupted tables, you should try to find out when
     and why this happens.  In this case, the error log in the MySQL
     data directory may contain some information about what happened.
     (This is the file with the `.err' suffix in the name.)  *Note
     Error log::.  Please include any relevant information from this
     file in your bug report.  Normally `mysqld' should *never* crash a
     table if nothing killed it in the middle of an update.  If you can
     find the cause of `mysqld' dying, it's much easier for us to
     provide you with a fix for the problem.  *Note What is crashing::.

   * If possible, download and install the most recent version of MySQL
     Server and check whether it solves your problem.  All versions of
     the MySQL software are thoroughly tested and should work without
     problems.  We believe in making everything as backward-compatible
     as possible, and you should be able to switch MySQL versions
     without difficulty.  *Note Which version::.

If you are a support customer, please cross-post the bug report to
<[e-mail]> for higher-priority treatment, as well as to
the appropriate mailing list to see whether someone else has
experienced (and perhaps solved) the problem.

For information on reporting bugs in `MyODBC', see *Note ODBC
Problems::.

For solutions to some common problems, see *Note Problems::.

When answers are sent to you individually and not to the mailing list,
it is considered good etiquette to summarize the answers and send the
summary to the mailing list so that others may have the benefit of
responses you received that helped you solve your problem.

Guidelines for Answering Questions on the Mailing List
......................................................

If you consider your answer to have broad interest, you may want to
post it to the mailing list instead of replying directly to the
individual who asked.  Try to make your answer general enough that
people other than the original poster may benefit from it.  When you
post to the list, please make sure that your answer is not a
duplication of a previous answer.

Try to summarize the essential part of the question in your reply;
don't feel obliged to quote the entire original message.

Please don't post mail messages from your browser with HTML mode turned
on.  Many users don't read mail with a browser.

MySQL Community Support on IRC (Internet Relay Chat)
----------------------------------------------------

In addition to the various MySQL mailing lists, you can find experienced
community people on `IRC' (`Internet Relay Chat').  These are the best
networks/channels currently known to us:

   * *freenode* (see `http://www.freenode.net/' for servers)
        * `#mysql' Primarily MySQL questions but other database and SQL
          questions welcome.

        * `#mysqlphp' Questions about MySQL+PHP, a popular combination.

        * `#mysqlperl' Questions about MySQL+Perl, another popular
          combination.

   * *EFnet* (see `http://www.efnet.org/' for servers)
        * `#mysql' MySQL questions.

If you are looking for IRC client software to connect to an IRC network,
take a look at `X-Chat' (`http://www.xchat.org/').  X-Chat (GPL
licensed) is available for Unix as well as for Windows platforms.

MySQL Standards Compliance
==========================

This section describes how MySQL relates to the ANSI/ISO SQL standards.
MySQL Server has many extensions to the SQL standard, and here you will
find out what they are and how to use them.  You will also find
information about functionality missing from MySQL Server, and how to
work around some differences.

Our goal is to not restrict MySQL Server usability for any usage
without a very good reason for doing so.  Even if we don't have the
resources to perform  development for every possible use, we are always
willing to help and offer suggestions to people who are trying to use
MySQL Server in new territories.

One of our main goals with the product is to continue to work toward
compliance with the SQL-99 standard, but without sacrificing speed or
reliability.  We are not afraid to add extensions to SQL or support for
non-SQL features if this greatly increases the usability of MySQL
Server for a large segment of our user base.  (The new `HANDLER'
interface in MySQL Server 4.0 is an example of this strategy. *Note
`HANDLER': HANDLER.)

We will continue to support transactional and non-transactional
databases to satisfy both mission-critical 24/7 usage and heavy
web/logging usage.

MySQL Server was designed from the start to work with medium size
databases (10-100 million rows, or about 100 MB per table) on small
computer systems.  We will continue to extend MySQL Server to work even
better with terabyte-size databases, as well as to make it possible to
compile a reduced MySQL version that is more suitable for hand-held
devices and embedded usage.  The compact design of the MySQL server
makes development in both of these directions possible without any
conflicts in the source tree.

We are currently not targeting realtime support, though you can already
do a lot of things with our replication capabilities.

Database cluster support is planned to begin sometime in 2004 through
implementation of a new storage engine.

We are looking at providing XML support in the database server.

What Standards MySQL Follows
----------------------------

Entry-level SQL-92. ODBC levels 0-3.51.

We are aiming toward supporting the full SQL-99 standard, but without
making concessions to speed and quality of the code.

Selecting SQL Modes
-------------------

The MySQL server can operate in different SQL modes, and can apply these
modes differentially for different clients. This allows applications to
tailor server operation to their own requirements.

Modes define what SQL syntax MySQL should support and what kind of
validation checks it should perform on the data.  This makes it easier
to use MySQL in a lot of different environments and to use MySQL
together with other database servers.

You can set the default SQL mode by starting `mysqld' with the
`--sql-mode="modes"' option. Beginning with MySQL 4.1, you can also
change the mode after startup time by setting the `sql_mode' variable
with a `SET [SESSION|GLOBAL] sql_mode='modes'' statement.

For more information on setting the server mode, see *Note Server SQL
mode::.

Running MySQL in ANSI Mode
--------------------------

You can tell `mysqld' to use the ANSI mode with the `--ansi' startup
option. *Note Server options::.

Running the server in ANSI mode is the same as starting it with these
options:

     --sql-mode=REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_BY
     --transaction-isolation=SERIALIZABLE

In MySQL 4.1, you can achieve the same effect with these two statements:

     SET GLOBAL TRANSACTION ISOLATION LEVEL SERIALIZABLE;
     SET GLOBAL sql_mode =
       "REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_BY";

*Note SQL mode::.

In MySQL 4.1.1, the `sql_mode' options shown can be also be set with:

     SET GLOBAL sql_mode="ansi";

In this case, the value of the `sql_mode' variable will be set to all
options that are relevant for ANSI mode. You can check the result by
doing:

     mysql> SET GLOBAL sql_mode="ansi";
     mysql> SELECT @@GLOBAL.sql_mode;
             -> "REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_BY,ANSI"

MySQL Extensions to the SQL-92 Standard
---------------------------------------

MySQL Server includes some extensions that you probably will not find in
other SQL databases.  Be warned that if you use them, your code will
not be portable to other SQL servers.  In some cases, you can write
code that includes MySQL extensions, but is still portable, by using
comments of the form `/*! ... */'.  In this case, MySQL Server will
parse and execute the code within the comment as it would any other
MySQL statement, but other SQL servers will ignore the extensions.  For
example:

     SELECT /*! STRAIGHT_JOIN */ col_name FROM table1,table2 WHERE ...

If you add a version number after the `'!'' character, the syntax within
the comment will be executed only if the MySQL version is equal to or
newer than the specified version number:

     CREATE /*!32302 TEMPORARY */ TABLE t (a INT);

This means that if you have Version 3.23.02 or newer, MySQL Server will
use the `TEMPORARY' keyword.

The following descriptions list MySQL extensions, organized by category.

Organization of data on disk
     MySQL Server maps each database to a directory under the MySQL
     data directory, and tables within a database to filenames in the
     database directory.  This has a few implications:

        * Database names and table names are case sensitive in MySQL
          Server on operating systems that have case sensitive
          filenames (like most Unix systems). *Note Name case
          sensitivity::.

        * Database, table, index, column, or alias names may begin with
          a digit (but may not consist solely of digits).

        * You can use standard system commands to back up, rename,
          move, delete, and copy tables that are managed by the
          `MyISAM' or `ISAM' storage engines.  For example, to rename a
          `MyISQM' table, rename the `.MYD', `.MYI', and `.frm' files
          to which the table corresponds.

General language syntax
        * Strings may be enclosed by either `"' or `'', not just by `''.

        * Use of `\' as an escape character in strings.

        * In SQL statements, you can access tables from different
          databases with the `db_name.tbl_name' syntax.  Some SQL
          servers provide the same functionality but call this `User
          space'.  MySQL Server doesn't support tablespaces such as
          used in statements like this: `CREATE TABLE
          ralph.my_table...IN my_tablespace'.


SQL statement syntax
        * The `ANALYZE TABLE', `CHECK TABLE', `OPTIMIZE TABLE', and
          `REPAIR TABLE' statements.

        * The `CREATE DATABASE' and `DROP DATABASE' statements.  *Note
          `CREATE DATABASE': CREATE DATABASE.

        * The `DO' statement.

        * `EXPLAIN SELECT' to get a description of how tables are
          joined.

        * The `FLUSH' and `RESET' statements.

        * The `SET' statement. *Note `SET': SET OPTION.

        * The `SHOW' statement.  *Note `SHOW': SHOW.

        * Use of `LOAD DATA INFILE'. In many cases, this syntax is
          compatible with Oracle's `LOAD DATA INFILE'. *Note `LOAD
          DATA': LOAD DATA.

        * Use of `RENAME TABLE'. *Note `RENAME TABLE': RENAME TABLE.

        * Use of `REPLACE' instead of `DELETE' + `INSERT'.  *Note
          `REPLACE': REPLACE.

        * Use of `CHANGE col_name', `DROP col_name', or `DROP INDEX',
          `IGNORE' or `RENAME' in an `ALTER TABLE' statement.  Use of
          multiple `ADD', `ALTER', `DROP', or `CHANGE' clauses in an
          `ALTER TABLE' statement.  *Note `ALTER TABLE': ALTER TABLE.

        * Use of index names, indexes on a prefix of a field, and use of
          `INDEX' or `KEY' in a `CREATE TABLE' statement. *Note `CREATE
          TABLE': CREATE TABLE.

        * Use of `TEMPORARY' or `IF NOT EXISTS' with `CREATE TABLE'.

        * Use of `IF EXISTS' with `DROP TABLE'.

        * You can drop multiple tables with a single `DROP TABLE'
          statement.

        * The `ORDER BY' and `LIMIT' clauses of the `UPDATE' and
          `DELETE' statements.

        * `INSERT INTO ... SET col_name = ...' syntax.

        * The `DELAYED' clause of the `INSERT' and `REPLACE' statements.

        * The `LOW_PRIORITY' clause of the `INSERT', `REPLACE',
          `DELETE', and `UPDATE' statements.

        * Use of `INTO OUTFILE' and `STRAIGHT_JOIN' in a `SELECT'
          statement. *Note `SELECT': SELECT.

        * The `SQL_SMALL_RESULT' option in a `SELECT' statement.

        * You don't need to name all selected columns in the `GROUP BY'
          part.  This gives better performance for some very specific,
          but quite normal queries.  *Note Group by functions and
          modifiers::.

        * You can specify `ASC' and `DESC' with `GROUP BY'.

        * The ability to set variables in a statement with the `:='
          assignment operator:
               mysql> SELECT @a:=SUM(total),@b=COUNT(*),@a/@b AS avg
                   -> FROM test_table;
               mysql> SELECT @t1:=(@t2:=1)+@t3:=4,@t1,@t2,@t3;


Column types
        * The column types `MEDIUMINT', `SET', `ENUM', and the
          different `BLOB' and `TEXT' types.

        * The column attributes `AUTO_INCREMENT', `BINARY', `NULL',
          `UNSIGNED', and `ZEROFILL'.

Functions and operators
        * To make it easier for users who come from other SQL
          environments, MySQL Server supports aliases for many
          functions. For example, all string functions support both
          standard SQL syntax and ODBC syntax.

        * MySQL Server understands the `||' and `&&' operators to mean
          logical OR and AND, as in the C programming language.  In
          MySQL Server, `||' and `OR' are synonyms, as are `&&' and
          `AND'.  Because of this nice syntax, MySQL Server doesn't
          support the standard SQL-99 `||' operator for string
          concatenation; use `CONCAT()' instead. Because `CONCAT()'
          takes any number of arguments, it's easy to convert use of
          the `||' operator to MySQL Server.

        * Use of `COUNT(DISTINCT list)' where `list' has more than one
          element.

        * All string comparisons are case-insensitive by default, with
          sort ordering determined by the current character set
          (ISO-8859-1 Latin1 by default).  If you don't like this, you
          should declare your columns with the `BINARY' attribute or
          use the `BINARY' cast, which causes comparisons to be done
          according to the ASCII order used on the MySQL server host.

        * The `%' operator is a synonym for `MOD()'.  That is, `N % M'
          is equivalent to `MOD(N,M)'.  `%' is supported for C
          programmers and for compatibility with PostgreSQL.

        * The `=', `<>', `<=' ,`<', `>=',`>', `<<', `>>', `<=>', `AND',
          `OR', or `LIKE' operators may be used in column comparisons
          to the left of the `FROM' in `SELECT' statements.  For
          example:

               mysql> SELECT col1=1 AND col2=2 FROM tbl_name;

        * The `LAST_INSERT_ID()' function.  *Note Information
          functions::.

        * `LIKE' is allowed on numeric columns.

        * The `REGEXP' and `NOT REGEXP' extended regular expression
          operators.

        * `CONCAT()' or `CHAR()' with one argument or more than two
          arguments.  (In MySQL Server, these functions can take any
          number of arguments.)

        * The `BIT_COUNT()', `CASE', `ELT()', `FROM_DAYS()',
          `FORMAT()', `IF()', `PASSWORD()', `ENCRYPT()', `MD5()',
          `ENCODE()', `DECODE()', `PERIOD_ADD()', `PERIOD_DIFF()',
          `TO_DAYS()', or `WEEKDAY()' functions.

        * Use of `TRIM()' to trim substrings.  SQL-99 supports removal
          of single characters only.

        * The `GROUP BY' functions `STD()', `BIT_OR()', `BIT_AND()',
          `BIT_XOR()', and `GROUP_CONCAT()'.  *Note Group by functions
          and modifiers::.

For a prioritized list indicating when new extensions will be added to
MySQL Server, you should consult the online MySQL TODO list at
`http://www.mysql.com/doc/en/TODO.html'.  That is the latest version of
the TODO list in this manual. *Note TODO::.

MySQL Differences Compared to SQL-92
------------------------------------

We try to make MySQL Server follow the ANSI SQL standard
(SQL-92/SQL-99) and the ODBC SQL standard, but MySQL Server performs
operations differently in some cases:

   * For `VARCHAR' columns, trailing spaces are removed when the value
     is stored. *Note Bugs::.

   * In some cases, `CHAR' columns are silently converted to `VARCHAR'
     columns when you define a table or alter its structure.  *Note
     Silent column changes::.

   * Privileges for a table are not automatically revoked when you
     delete a table. You must explicitly issue a `REVOKE' statement to
     revoke privileges for a table. *Note `GRANT': GRANT.

Subqueries
..........

MySQL Version 4.1 supports subqueries and derived tables.  A subquery
is a `SELECT' statement nested within another statement.  A derived
table (an unnamed view) is a subquery in the `FROM' clause of another
statement.  *Note Subqueries::.

For MySQL versions older than 4.1, most subqueries can be rewritten
using joins or other methods.  See *Note Rewriting subqueries:: for
examples that show how to do this.

`SELECT INTO TABLE'
...................

MySQL Server doesn't support the Sybase SQL extension: `SELECT ... INTO
TABLE ...'.  Instead, MySQL Server supports the SQL-99 syntax `INSERT
INTO ... SELECT ...', which is basically the same thing. *Note `INSERT
SELECT': INSERT SELECT.

     INSERT INTO tblTemp2 (fldID)
            SELECT tblTemp1.fldOrder_ID
            FROM tblTemp1 WHERE tblTemp1.fldOrder_ID > 100;

Alternatively, you can use `SELECT INTO OUTFILE ...' or `CREATE TABLE
... SELECT'.

From version 5.0, MySQL supports `SELECT ... INTO' with user variables.
The same syntax may also be used inside stored procedures using cursors
and local variables.  *Note SELECT INTO Statement::.

Transactions and Atomic Operations
..................................

MySQL Server (version 3.23-max and all versions 4.0 and above) supports
transactions with the `InnoDB' and `BDB' transactional storage engines.
`InnoDB' provides _full_ `ACID' compliance.  *Note Table types::.

The other non-transactional storage engines in MySQL Server (such as
`MyISAM') follow a different paradigm for data integrity called
"`Atomic Operations'." In transactional terms, `MyISAM' tables
effectively always operate in `AUTOCOMMIT=1' mode.  Atomic operations
often offer comparable integrity with higher performance.

With MySQL Server supporting both paradigms, you can decide whether your
applications are best served by the speed of atomic operations or the
use of transactional features. This choice can be made on a per-table
basis.

As noted, the trade off for transactional vs. non-transactional table
types lies mostly in performance. Transactional tables have
significantly higher memory and diskspace requirements, and more CPU
overhead.  On the other hand, transactional table types such as
`InnoDB' also offer many significant features. MySQL Server's modular
design allows the concurrent use of different storage engines to suit
different requirements and deliver optimum performance in all
situations.

But how does one use the features of MySQL Server to maintain rigorous
integrity even with the non-transactional `MyISAM' tables, and how do
these features compare with the transactional table types?

  1. If your applications are written in a way that is dependent on
     being able to call `ROLLBACK' rather than `COMMIT' in critical
     situations, transactions are more convenient. Transactions also
     ensure that unfinished updates or corrupting activities are not
     committed to the database; the server is given the opportunity to
     do an automatic rollback and your database is saved.

     If you use non-transactional tables, MySQL Server in almost all
     cases allows you to resolve potential problems by including simple
     checks before updates and by running simple scripts that check the
     databases for inconsistencies and automatically repair or warn if
     such an inconsistency occurs. Note that just by using the MySQL
     log or even adding one extra log, one can normally fix tables
     perfectly with no data integrity loss.

  2. More often than not, critical transactional updates can be
     rewritten to be atomic. Generally speaking, all integrity problems
     that transactions solve can be done with `LOCK TABLES' or atomic
     updates, ensuring that you never will get an automatic abort from
     the server, which is a common problem with transactional database
     systems.

  3. Even a transactional system can lose data if the server goes down.
     The difference between different systems lies in just how small the
     time-lap is where they could lose data. No system is 100% secure,
     only "secure enough." Even Oracle, reputed to be the safest of
     transactional database systems, is reported to sometimes lose data
     in such situations.

     To be safe with MySQL Server, whether using transactional tables
     or not, you only need to have backups and have binary logging
     turned on. With this you can recover from any situation that you
     could with any other transactional database system.  It is always
     good to have backups, independent of which database system you use.

The transactional paradigm has its benefits and its drawbacks. Many
users and application developers depend on the ease with which they can
code around problems where an abort appears to be, or is necessary.
However, even if you are new to the atomic operations paradigm, or more
familiar with transactions, do consider the speed benefit that
non-transactional tables can offer on the order of three to five times
the speed of the fastest and most optimally tuned transactional tables.

In situations where integrity is of highest importance, MySQL Server
offers transaction-level reliability and integrity even for
non-transactional tables.  If you lock tables with `LOCK TABLES', all
updates will stall until any integrity checks are made. If you obtain a
`READ LOCAL' lock (as opposed to a write lock) for a table that allows
concurrent inserts at the end of the table, reads are allowed, as are
inserts by other clients.  The new inserted records will not be seen by
the client that has the read lock until it releases the lock.  With
`INSERT DELAYED' you can queue inserts into a local queue, until the
locks are released, without having the client wait for the insert to
complete. *Note INSERT DELAYED::.

"Atomic," in the sense that we mean it, is nothing magical. It only
means that you can be sure that while each specific update is running,
no other user can interfere with it, and there will never be an
automatic rollback (which can happen with transactional tables if you
are not very careful).  MySQL Server also guarantees that there will
not be any dirty reads.

Following are some techniques for working with non-transactional tables:

   * Loops that need transactions normally can be coded with the help of
     `LOCK TABLES', and you don't need cursors to update records on the
     fly.

   * To avoid using `ROLLBACK', you can use the following strategy:

       1. Use `LOCK TABLES ...' to lock all the tables you want to
          access.

       2. Test the conditions that must be true before performing the
          update.

       3. Update if everything is okay.

       4. Use `UNLOCK TABLES' to release your locks.

     This is usually a much faster method than using transactions with
     possible rollbacks, although not always. The only situation this
     solution doesn't handle is when someone kills the threads in the
     middle of an update. In this case, all locks will be released but
     some of the updates may not have been executed.

   * You can also use functions to update records in a single operation.
     You can get a very efficient application by using the following
     techniques:

        * Modify fields relative to their current value.

        * Update only those fields that actually have changed.

     For example, when we are doing updates to some customer
     information, we update only the customer data that has changed and
     test only that none of the changed data, or data that depends on
     the changed data, has changed compared to the original row. The
     test for changed data is done with the `WHERE' clause in the
     `UPDATE' statement. If the record wasn't updated, we give the
     client a message: "Some of the data you have changed has been
     changed by another user." Then we show the old row versus the new
     row in a window, so the user can decide which version of the
     customer record he should use.

     This gives us something that is similar to column locking but is
     actually even better because we only update some of the columns,
     using values that are relative to their current values.  This
     means that typical `UPDATE' statements look something like these:

          UPDATE tablename SET pay_back=pay_back+125;

          UPDATE customer
            SET
              customer_date='current_date',
              address='new address',
              phone='new phone',
              money_he_owes_us=money_he_owes_us-125
            WHERE
              customer_id=id AND address='old address' AND phone='old phone';

     As you can see, this is very efficient and works even if another
     client has changed the values in the `pay_back' or
     `money_he_owes_us' columns.

   * In many cases, users have wanted `LOCK TABLES' and/or `ROLLBACK'
     for the purpose of managing unique identifiers.  This can be
     handled much more efficiently without locking or rolling back by
     using an `AUTO_INCREMENT' column and either the SQL function
     `LAST_INSERT_ID()' or the C API function `mysql_insert_id()'.
     *Note Information functions::.  *Note `mysql_insert_id()':
     mysql_insert_id.

     You can generally code around the need for row-level locking. Some
     situations really do need it, and `InnoDB' tables support
     row-level locking. With `MyISAM' tables, you can use a flag column
     in the table and do something like the following:

          UPDATE tbl_name SET row_flag=1 WHERE id=ID;

     MySQL returns 1 for the number of affected rows if the row was
     found and `row_flag' wasn't already 1 in the original row.

     You can think of it as though MySQL Server changed the preceding
     query to:

          UPDATE tbl_name SET row_flag=1 WHERE id=ID AND row_flag <> 1;

Stored Procedures and Triggers
..............................

Stored procedures are implemented in MySQL version 5.0.  *Note Stored
Procedures::.

Triggers are scheduled for implementation in MySQL version 5.1. A
trigger is effectively a type of stored procedure, one that is invoked
when a particular event occurs.  For example, you could set up a stored
procedure that is triggered each time a record is deleted from a
transactional table and that stored procedure automatically deletes the
corresponding customer from a customer table when all their
transactions are deleted.

Foreign Keys
............

In MySQL Server 3.23.44 and up, the `InnoDB' storage engine supports
checking of foreign key constraints, including `CASCADE', `ON DELETE',
and `ON UPDATE'. *Note InnoDB foreign key constraints::.

For storage engines other than `InnoDB', MySQL Server parses the
`FOREIGN KEY' syntax in `CREATE TABLE' statements, but does not use or
store it. In the future, the implementation will be extended to store
this information in the table specification file so that it may be
retrieved by `mysqldump' and ODBC.  At a later stage, foreign key
constraints will be implemented for `MyISAM' tables as well.

Foreign key enforcement offers several benefits to database developers:

   * Assuming proper design of the relationships, foreign key
     constraints make it more difficult for a programmer to introduce
     an inconsistency into the database.

   * Centralized checking of constraints by the database server makes it
     unnecessary to perform these checks on the application side. This
     eliminates the possibility that different applications may not all
     check the constraints in the same way.

   * Using cascading updates and deletes can simplify the application
     code.

   * Properly designed foreign key rules aid in documenting
     relationships between tables.

Do keep in mind that these benefits come at the cost of additional
overhead for the database server to perform the necessary checks.
Additional checking by the server affects performance, which for some
applications may be sufficiently undesirable as to be avoided if
possible.  (Some major commercial applications have coded the
foreign-key logic at the application level for this reason.)

MySQL gives database developers the choice of which approach to use. If
you don't need foreign keys and want to avoid the overhead associated
with enforcing referential integrity, you can choose another table type
instead, such as `MyISAM'. (For example, the `MyISAM' storage engine
offers very fast performance for applications that perform only
`INSERT' and `SELECT' operations, because the inserts can be performed
concurrently with retrievals.  *Note Table locking::.)

If you choose not to take advantage of referential integrity checks,
keep the following considerations in mind:

   * In the absence of server-side foreign key relationship checking,
     the application itself must handle relationship issues.  For
     example, it must take care to insert rows into tables in the proper
     order, and to avoid creating orphaned child records. It must also
     be able to recover from errors that occur in the middle of
     multiple-record insert operations.

   * If `ON DELETE' is the only referential integrity capability an
     application needs, note that as of MySQL Server 4.0, you can use
     multiple-table `DELETE' statements to delete rows from many tables
     with a single statement. *Note `DELETE': DELETE.

   * A workaround for the lack of `ON DELETE' is to add the appropriate
     `DELETE' statement to your application when you delete records
     from a table that has a foreign key. In practice, this is often as
     quick as using foreign keys, and is more portable.


Be aware that the use of foreign keys can in some instances lead to
problems:

   * Foreign key support addresses many referential integrity issues,
     but it is still necessary to design key relationships carefully to
     avoid circular rules or incorrect combinations of cascading
     deletes.

   * It is not uncommon for a DBA to create a topology of relationships
     that makes it difficult to restore individual tables from a backup.
     (MySQL alleviates this difficulty by allowing you to temporarily
     disable foreign key checks when reloading a table that depends on
     other tables.  *Note InnoDB foreign key constraints::.  As of
     MySQL 4.1.1, `mysqldump' generates dump files that take advantage
     of this capability automatically when reloaded.)

Note that foreign keys in SQL are used to check and enforce referential
integrity, not to join tables.  If you want to get results from multiple
tables from a `SELECT' statement, you do this by performing a join
between them:

     SELECT * FROM table1,table2 WHERE table1.id = table2.id;

*Note `JOIN': JOIN. *Note example-Foreign keys::.

The `FOREIGN KEY' syntax without `ON DELETE ...' is often used by ODBC
applications to produce automatic `WHERE' clauses.

Views
.....

Views are currently being implemented, and will appear in the 5.0 or 5.1
version of MySQL Server.  Unnamed views (_derived tables_, a subquery
in the `FROM' clause of a `SELECT') are already implemented in version
4.1.

Historically, MySQL Server has been most used in applications and on web
systems where the application writer has full control over database
usage. Usage has shifted over time, and so we find that an increasing
number of users now regard views as an important feature.

Views are useful for allowing users to access a set of relations
(tables) as if it were a single table, and limiting their access to
just that.  Views can also be used to restrict access to rows (a subset
of a particular table).  One does not require views to restrict access
to columns, as MySQL Server has a sophisticated privilege system.
*Note Privilege system::.

Many DBMS don't allow updates to a view. Instead, you have to perform
the updates on the individual tables.  In designing an implementation
of views, our goal, as much as is possible within the confines of SQL,
is full compliance with "*Codd's Rule #6*" for relational database
systems: All views that are theoretically updatable, should in practice
also be updatable.

`--' as the Start of a Comment
..............................

Some other SQL databases use `--' to start comments.  MySQL Server uses
`#' as the start comment character. You can also use the C comment
style `/* this is a comment */' with MySQL Server.  *Note Comments::.

MySQL Server Version 3.23.3 and above support the `--' comment style,
provided the comment is followed by a space (or by a control character
such as a newline). The requirement for a space is to prevent problems
with automatically generated SQL queries that have used something like
the following code, where we automatically insert the value of the
payment for `!payment!':

     UPDATE tbl_name SET credit=credit-!payment!

Think about what happens if the value of `payment' is a negative value
such as `-1':

     UPDATE tbl_name SET credit=credit--1

`credit--1' is a legal expression in SQL, but if `--' is interpreted as
the start of a comment, part of the expression is discarded. The result
is a statement that has a completely different meaning than intended:

     UPDATE tbl_name SET credit=credit

The statement produces no change in value at all!  This illustrates that
allowing comments to start with `--' can have serious consequences.

Using our implementation of this method of commenting in MySQL Server
Version 3.23.3 and up, `credit--1' is actually safe.

Another safe feature is that the `mysql' command-line client removes
all lines that start with `--'.

The following information is relevant only if you are running a MySQL
version earlier than 3.23.3:

If you have an SQL program in a text file that contains `--' comments,
you should use the `replace' utility as follows to convert the comments
to use `#' characters:

     shell> replace " --" " #" < text-file-with-funny-comments.sql \
              | mysql database

instead of the usual:

     shell> mysql database < text-file-with-funny-comments.sql

You can also edit the command file "in place" to change the `--'
comments to `#' comments:

     shell> replace " --" " #" -- text-file-with-funny-comments.sql

Change them back with this command:

     shell> replace " #" " --" -- text-file-with-funny-comments.sql

How MySQL Deals with Constraints
--------------------------------

MySQL allows you to work with both transactional tables that allow
rollback and non-transactional tables that do not, so constraint
handling is a bit different in MySQL than in other databases.

We have to handle the case when you have updated a lot of rows in a
non-transactional table that cannot roll back when an error occurs.

The basic philosophy is to try to give an error for anything that we can
detect at compile time but try to recover from any errors we get at
runtime.  We do this in most cases, but not yet for all. *Note TODO
future::.

The options MySQL has when an error occurs are to stop the statement in
the middle or to recover as well as possible from the problem and
continue.

The following sections describe what happens for the different types of
constraints.

Constraint PRIMARY KEY / UNIQUE
...............................

Normally you will get an error when you try to `INSERT' or `UPDATE' a
row that causes a primary key, unique key or foreign key violation.  If
you are using a transactional storage engine such as `InnoDB', MySQL
will automatically roll back the transaction.  If you are using a
non-transactional storage engine, MySQL will stop at the incorrect row
and leave any remaining rows unprocessed.

To make life easier, MySQL supports an `IGNORE' keyword for most
commands that can cause a key violation (such as `INSERT IGNORE' and
`UPDATE IGNORE'). In this case, MySQL will ignore any key violation and
continue with processing the next row.  You can get information about
what MySQL did with the `mysql_info()' API function.  *Note
`mysql_info()': mysql_info.  In MySQL 4.1 and up, you also can use the
`SHOW WARNINGS' statement.  *Note SHOW WARNINGS::.

Note that for the moment only `InnoDB' tables support foreign keys.
*Note InnoDB foreign key constraints::.  Foreign key support in
`MyISAM' tables is scheduled for implementation in MySQL 5.1.

Constraint `NOT NULL' and `DEFAULT' values
..........................................

To be able to support easy handling of non-transactional tables all
columns in MySQL have default values.

If you insert an "incorrect" value in a column, such as a `NULL' in a
`NOT NULL' column or a too-large numerical value in a numerical column,
MySQL sets the column to the "best possible value" instead of producing
an error.  For numerical values, this is either 0, the smallest
possible value or the largest possible value. For strings, this is
either the empty string or the longest possible string that can be in
the column.

This means that if you try to store `NULL' into a column that doesn't
take `NULL' values, MySQL Server instead stores 0 or `''' (the empty
string). This last behavior can, for single row inserts, be changed
with the `-DDONT_USE_DEFAULT_FIELDS' compile option.) *Note `configure'
options: configure options.  This causes `INSERT' statements to
generate an error unless you explicitly specify values for all columns
that require a non-`NULL' value.

The reason for the preceding rules is that we can't check these
conditions until the query has begun executing.  We can't just roll
back if we encounter a problem after updating a few rows, because the
table type may not support rollback.  The option of terminating the
statement is not that good; in this case, the update would be "half
done," which is probably the worst possible scenario.  In this case
it's better to "do the best you can" and then continue as if nothing
happened.

This means that you should generally not use MySQL to check column
content.  Instead, the application should ensure that is passes only
legal values to MySQL.

In MySQL 5.0, we plan to improve this by providing warnings when
automatic column conversions occur, plus an option to let you roll back
statements that attempt to perform a disallowed column value
assignment, as long as the statement uses only transactional tables.

Constraint `ENUM' and `SET'
...........................

In MySQL 4.x, `ENUM' is not a real constraint, but is a more efficient
way to define columns that can only contain a given set of values.
This is because of the same reasons `NOT NULL' is not honored.  *Note
constraint NOT NULL::.

If you insert an incorrect value into an `ENUM' column, it will be set
to the reserved enumeration value `0', which will be displayed as an
empty string in string context. *Note ENUM::.

If you insert an incorrect value into a `SET' column, the incorrect
value is ignored. For example, if the column can contain the values
`'a'', `'b'', and `'c'', an attempt to assign `'a,x,b,y'' results in a
value of `'a,b''.  *Note SET::.

Known Errors and Design Deficiencies in MySQL
---------------------------------------------

Errors in 3.23 Fixed in a Later MySQL Version
.............................................

The following known errors or bugs are not fixed in MySQL 3.23 because
fixing them would involve changing a lot of code that could introduce
other even worse bugs. The bugs are also classified as "not fatal" or
"bearable."

   * You can get a deadlock if you use `LOCK TABLE' to lock multiple
     tables and then in the same connection use `DROP TABLE' to drop
     one of them while another thread is trying to lock it.  (To break
     the deadlock, you can use `KILL' to terminate any of the threads
     involved.) This issue is resolved in MySQL 4.0.12.

   * `SELECT MAX(key_column) FROM t1,t2,t3...' where one of the tables
     are empty doesn't return `NULL' but instead returns the maximum
     value for the column.  This issue is resolved in MySQL 4.0.11.

   * `DELETE FROM heap_table' without a `WHERE' clause doesn't work on
     a locked `HEAP' table.

Errors in 4.0 Fixed in a Later MySQL Version
............................................

The following known errors or bugs are not fixed in MySQL 4.0 because
fixing them would involve changing a lot of code that could introduce
other even worse bugs. The bugs are also classified as "not fatal" or
"bearable."

   * In a `UNION', the first `SELECT' determines the type, `max_length'
     and `NULL' properties for the resulting columns.  This issue is
     resolved in MySQL 4.1.1; the property values are based on the rows
     from all `UNION' parts.

Open Bugs / Design Deficiencies in MySQL
........................................

The following problems are known and fixing them is a high priority:

   * Dropping a `FOREIGN KEY' constraint doesn't work in replication as
     the constraint may have another name.

   * You cannot mix `UNION ALL' and `UNION DISTINCT' in the same query.
     If you use `ALL' for one `UNION', it is used for all of them.

   * If one user has a long running transaction and another user drops a
     table that is updated in the transaction, there is small chance
     that the binary log may contain the `DROP TABLE' command before
     the table is used in the transaction itself.  We plan to fix this
     in 5.0 by having the `DROP TABLE' wait until the table is not used
     in any transaction.

   * When inserting a big integer value (between 2^63 and 2^64-1) into a
     decimal/string column, it is inserted as a negative value because
     the number is evaluated in a signed integer context. It is planned
     to be fixed in 4.1.

   * `FLUSH TABLES WITH READ LOCK' does not block `CREATE TABLE' or
     `COMMIT', which make cause a problem with the binary log position
     when doing a full backup of tables and the binary log.

   * `ANALYZE TABLE' on a `BDB' table may in some cases make the table
     unusable until one has restarted `mysqld'.  If this happens, you
     will see errors of the following form in the MySQL error file:

          001207 22:07:56  bdb:  log_flush: LSN past current end-of-log

   * MySQL accepts parentheses in the `FROM' part of a `SELECT'
     statement, but silently ignores them.  The reason for not giving
     an error is that many clients that automatically generate queries
     add parentheses in the `FROM' part even where they are not needed.

   * Concatenating many `RIGHT JOINS' or combining `LEFT' and `RIGHT'
     join in the same query may not give a correct answer as MySQL only
     generates `NULL' rows for the table preceding a `LEFT' or before a
     `RIGHT' join.  This will be fixed in 5.0 at the same time we add
     support for parentheses in the `FROM' part.

   * Don't execute `ALTER TABLE' on a `BDB' table on which you are
     running multiple-statement transactions until all those
     transactions complete.  (The transaction will probably be ignored.)

   * `ANALYZE TABLE', `OPTIMIZE TABLE', and `REPAIR TABLE' may cause
     problems on tables for which you are using `INSERT DELAYED'.

   * Doing a `LOCK TABLE ...' and `FLUSH TABLES ...' doesn't guarantee
     that there isn't a half-finished transaction in progress on the
     table.

   * `BDB' tables are a bit slow to open. If you have many `BDB' tables
     in a database, it will take a long time to use the `mysql' client
     on the database if you are not using the `-A' option or if you are
     using `rehash'. This is especially notable when you have a large
     table cache.

   * Replication uses query-level logging: The master writes the
     executed queries to the binary log. This is a very fast, compact,
     and efficient logging method that works perfectly in most cases.
     Though we have never heard of it actually occurring, it is
     theoretically possible for the data on the master and slave to
     become different if a query is designed in such a way that the
     data modification is non-deterministic, that is, left to the will
     of the query optimizer. (That generally is not a good practice
     anyway, even outside of replication!)  For example:

        - `CREATE ... SELECT' or `INSERT ... SELECT'  statements that
          insert zero or `NULL' values into an `AUTO_INCREMENT' column.

        - `DELETE' if you are deleting rows from a table which has
          foreign keys with `ON DELETE CASCADE' properties.

        - `REPLACE ... SELECT', `INSERT IGNORE ... SELECT' if you have
          duplicate key values in the inserted data.
     *IF and only if all these queries have NO `ORDER BY' clause
     guaranteeing a deterministic order*.

     Indeed, for example for `INSERT ... SELECT' with no `ORDER BY',
     the `SELECT' may return rows in a different order (which will
     result in a row having different ranks, hence getting a different
     number in the `auto_increment' column), depending on the choices
     made by the optimizers on the master and slave. A query will be
     optimized differently on the master and slave only if:

        - The files used by the two queries are not exactly the same;
          for example `OPTIMIZE TABLE' was run on the master tables and
          not on the slave tables (to fix this, since MySQL 4.1.1,
          `OPTIMIZE', `ANALYZE' and `REPAIR' are written to the binary
          log).

        - The table is stored in a different storage engine on the
          master than on the slave. (It is possible to use different
          storage engines on the master and slave. For example, you can
          use `InnoDB' on the master, but `MyISAM' on the slave if the
          slave has less available disk space.)

        - MySQL buffer sizes (`key_buffer_size', etc.) are different on
          the master and slave.

        - The master and slave run different MySQL versions, and the
          optimizer code is different between these versions.

     This problem may also affect database restoration using
     `mysqlbinlog|mysql'.

     The easiest way to avoid this problem in all cases is add an
     `ORDER BY' clause to such non-deterministic queries to ensure that
     the rows are always stored or modified in the same order.  In
     future MySQL versions, we will automatically add an `ORDER BY'
     clause when needed.


The following problems are known and will be fixed in due time:

   * Log files are based on hostnames (if you don't specify a file name
     with the startup option). For now you have to use options like
     `--log-bin=old_host_name-bin' if you change your host name to
     something else. Another option is to just rename the old files to
     reflect your hostname change. *Note Server options::.

   * `mysqlbinlog' will not delete temporary files left after a `LOAD
     DATA INFILE' command. *Note `mysqlbinlog': mysqlbinlog.

   * `RENAME' doesn't work with `TEMPORARY' tables or tables used in a
     `MERGE' table.

   * When using the `RPAD()' function in a query that has to be
     resolved by using a temporary table, all resulting strings will
     have rightmost spaces removed. This is an example of such a query:

          SELECT RPAD(t1.column1, 50, ' ') AS f2, RPAD(t2.column2, 50, ' ') AS f1
          FROM table1 as t1 LEFT JOIN table2 AS t2 ON t1.record=t2.joinID
          ORDER BY t2.record;

     The final result of this bug is that you will not be able to get
     spaces on the right side of the resulting values. The problem also
     occurs for any other string function that adds spaces to the right.

     The reason for this is due to the fact that `HEAP' tables, which
     are used first for temporary tables, are not capable of handling
     `VARCHAR' columns.

     This behavior exists in all versions of MySQL.  It will be fixed
     in one of the 4.1 series releases.

   * Due to the way table definition files are stored, you cannot use
     character 255 (`CHAR(255)') in table names, column names, or
     enumerations.  This is scheduled to be fixed in version 5.1 when
     we have new table definition format files.

   * When using `SET CHARACTER SET', you can't use translated
     characters in database, table, and column names.

   * You can't use `_' or `%' with `ESCAPE' in `LIKE ... ESCAPE'.

   * If you have a `DECIMAL' column with a  number stored in different
     formats (+01.00, 1.00, 01.00), `GROUP BY' may regard each value as
     a different value.

   * `DELETE FROM merge_table' used without a `WHERE' clause will clear
     only the mapping for the table, not delete everything in the
     mapped tables.

   * You cannot build the server in another directory when using
     MIT-pthreads. Because this requires changes to MIT-pthreads, we
     are not likely to fix this. *Note MIT-pthreads::.

   * `BLOB' values can't "reliably" be used in `GROUP BY' or `ORDER BY'
     or `DISTINCT'. Only the first `max_sort_length' bytes are used
     when comparing `BLOB' values in these cases.  The default value of
     `max_sort_length' value is 1024. It can be changed at server
     startup time.  A workaround for most cases is to use a substring.
     For example: `SELECT DISTINCT LEFT(blob,2048) FROM tbl_name'.

   * Numeric calculations are done with `BIGINT' or `DOUBLE' (both are
     normally 64 bits long). It depends on the function which precision
     one gets. The general rule is that bit functions are done with
     `BIGINT' precision, `IF', and `ELT()' with `BIGINT' or `DOUBLE'
     precision and the rest with `DOUBLE' precision.  You should try to
     avoid using unsigned long long values if they resolve to be bigger
     than 63 bits (9223372036854775807) for anything other than bit
     fields.  MySQL Server 4.0 has better `BIGINT' handling than 3.23.

   * All string columns, except `BLOB' and `TEXT' columns, automatically
     have all trailing spaces removed when retrieved. For `CHAR' types
     this is okay. The bug is that in MySQL Server, `VARCHAR' columns
     are treated the same way.

   * You can only have up to 255 `ENUM' and `SET' columns in one table.

   * In `MIN()', `MAX()', and other aggregate functions, MySQL
     currently compares `ENUM' and `SET' columns by their string value
     rather than by the string's relative position in the set.

   * `mysqld_safe' redirects all messages from `mysqld' to the `mysqld'
     log.  One problem with this is that if you execute `mysqladmin
     refresh' to close and reopen the log, `stdout' and `stderr' are
     still redirected to the old log.  If you use `--log' extensively,
     you should edit `mysqld_safe' to log to `'hostname'.err' instead
     of `'hostname'.log' so you can easily reclaim the space for the
     old log by deleting the old one and executing `mysqladmin refresh'.

   * In the `UPDATE' statement, columns are updated from left to right.
     If you refer to an updated column, you will get the updated value
     instead of the original value. For example:

          mysql> UPDATE tbl_name SET KEY=KEY+1,KEY=KEY+1;

     This will increment `KEY' by `2', not `1'.

   * You can refer to multiple temporary tables in the same query, but
     you cannot refer to any given temporary table more than once.  For
     example, the following doesn't work:

          mysql> SELECT * FROM temporary_table, temporary_table AS t2;

   * The optimizer may handle `DISTINCT' differently if you are using
     'hidden' columns in a join or not.  In a join, hidden columns are
     counted as part of the result (even if they are not shown) while in
     normal queries hidden columns don't participate in the `DISTINCT'
     comparison.  We will probably change this in the future to never
     compare the hidden columns when executing `DISTINCT'.

     An example of this is:

          SELECT DISTINCT mp3id FROM band_downloads
                 WHERE userid = 9 ORDER BY id DESC;

     and

          SELECT DISTINCT band_downloads.mp3id
                 FROM band_downloads,band_mp3
                 WHERE band_downloads.userid = 9
                 AND band_mp3.id = band_downloads.mp3id
                 ORDER BY band_downloads.id DESC;

     In the second case you may in MySQL Server 3.23.x get two
     identical rows in the result set (because the values in the hidden
     `id' column may differ).

     Note that this happens only for queries where you don't have the
     `ORDER BY' columns in the result, something that you are not
     allowed to do in SQL-92.

   * Because MySQL Server allows you to work with table types that don't
     support transactions, and thus can't roll back data, some things
     behave a little differently in MySQL Server than in other SQL
     servers.  This is just to ensure that MySQL Server never needs to
     do a rollback for an SQL statement.  This may be a little awkward
     at times as column values must be checked in the application, but
     this will actually give you a nice speed increase as it allows
     MySQL Server to do some optimizations that otherwise would be very
     hard to do.

     If you set a column to an incorrect value, MySQL Server will,
     instead of doing a rollback, store the `best possible value' in
     the column:

        - If you try to store a value outside the range in a numerical
          column, MySQL Server instead stores the smallest or largest
          possible value in the column.

        - If you try to store a string that doesn't start with a number
          into a numerical column, MySQL Server stores 0.

        - If you try to store `NULL' into a column that doesn't allow
          `NULL' values, MySQL Server stores 0 or `''' (the empty
          string) in it instead. (This behavior can, however, be
          changed with the `-DDONT_USE_DEFAULT_FIELDS' compile option.)

        - MySQL allows you to store some wrong date values into `DATE'
          and `DATETIME' columns (like `'2000-02-31'' or
          `'2000-02-00'').  The idea is that it's not the job of the
          SQL server to validate dates. If MySQL can store a date value
          and retrieve exactly the same value, MySQL stores it as
          given.  If the date is totally wrong (outside the server's
          ability to store it), the special date value `'0000-00-00''
          is stored in the column instead.

        - If you set an `ENUM' column to an unsupported value, it is
          set to the error value `empty string', with numeric value 0.

        - If you set a `SET' column to an unsupported value, the value
          is ignored.


   * If you execute a `PROCEDURE' on a query that returns an empty set,
     in some cases the `PROCEDURE' will not transform the columns.

   * Creation of a table of type `MERGE' doesn't check if the underlying
     tables are of compatible types.

   * MySQL Server can't yet handle `NaN', `-Inf', and `Inf' values in
     `DOUBLE' columns. Using these will cause problems when trying to
     export and import data. We should as an intermediate solution
     change `NaN' to `NULL' (if possible) and `-Inf' and `Inf' to the
     minimum respective maximum possible `double' value.

   * If you use `ALTER TABLE' to first add a `UNIQUE' index to a table
     used in a `MERGE' table and then use `ALTER TABLE' to add a normal
     index on the `MERGE' table, the key order will be different for
     the tables if there was an old key that was not unique in the
     table. This is because `ALTER TABLE' puts `UNIQUE' indexes before
     normal indexes to be able to detect duplicate keys as early as
     possible.

The following are known bugs in earlier versions of MySQL:

   * You can get a hung thread if you do a `DROP TABLE' on a table that
     is one among many tables that is locked with `LOCK TABLES'.

   * In the following case you can get a core dump:

        - Delayed insert handler has pending inserts to a table.

        - `LOCK table' with `WRITE'.

        - `FLUSH TABLES'.

   * Before MySQL Server Version 3.23.2 an `UPDATE' that updated a key
     with a `WHERE' on the same key may have failed because the key was
     used to search for records and the same row may have been found
     multiple times:

          UPDATE tbl_name SET KEY=KEY+1 WHERE KEY > 100;

     A workaround is to use:

          mysql> UPDATE tbl_name SET KEY=KEY+1 WHERE KEY+0 > 100;

     This will work because MySQL Server will not use an index on
     expressions in the `WHERE' clause.

   * Before MySQL Server Version 3.23, all numeric types were treated as
     fixed-point fields. That means you had to specify how many decimals
     a floating-point field should have. All results were returned with
     the correct number of decimals.

For platform-specific bugs, see the sections about compiling and
porting.  *Note Installing source::.  *Note Porting::.

Installing MySQL
****************

This chapter describes how to obtain and install MySQL:

  1. *Determine whether your platform is supported.*  Please note that
     not all supported systems are equally good for running MySQL on
     them.  On some it is much more robust and efficient than others.
     See *Note Which OS:: for details.

  2. *Choose a distribution to install.*  Several versions of MySQL are
     available, and most are available in serveral distribution
     formats.  You can choose from pre-packaged distributions
     containing binary (precompiled) programs or source code.  When in
     doubt, use a binary distribution.  We also provide public access
     to our current source tree, for those who want to see our most
     recent developments and help us test new code.  To determine which
     version and type of distribution you should use, see *Note Which
     version::.

  3. *Download the distribution that you want to install.* For a list
     of sites from which you can obtain MySQL, see *Note Getting MySQL:
     Getting MySQL.  You can verify the integrity of the distribution
     using the instructions in *Note Verifying Package Integrity::.

  4. *Install the distribution.*  For binary distributions, use the
     instructions in in *Note Installing binary::.  For source
     distributions, use the instructions in *Note Installing source::.
     Additional installation procedures include the following:

        * For post-installation procedures, see *Note
          Post-installation::.  These procedures apply whether you
          install MySQL using a binary or source distribution.

        * If you plan to upgrade an existing version of MySQL to a
          newer version rather than installing MySQL for the first
          time, see *Note Upgrade:: for information about upgrade
          procedures and about issues that you should consider before
          upgrading.

        * If you want to run the MySQL benchmark scripts, Perl support
          for MySQL must be available.  *Note Perl support::.



The last part of the chapter provides information on system-specific
problems you may run into.

General Installation Issues
===========================

Before installing MySQL, you should do the following:

  1. Determine whether or not MySQL runs on your platform.

  2. Choose a distribution to install.

  3. Download the distribution and verify its integrity.


This section contains the information necessary to carry out these
steps.  After doing so, you can use the instructions in later sections
of the chapter to install the distribution that you choose.

Operating Systems Supported by MySQL
------------------------------------

This section lists the operating systems on which you can expect to be
able to run MySQL.

We use GNU Autoconf, so it is possible to port MySQL to all modern
systems that have a C++ compiler and a working implementation of POSIX
threads.  (Thread suport is needed for the server. To compile only the
client code, the only requirement is a C++ compiler.) We use and
develop the software ourselves primarily on Linux (SuSE and Red Hat),
FreeBSD, and Sun Solaris (Versions 8 and 9).

MySQL has been reported to compile successfully on the following
combinations of operating system and thread package.  Note that for many
operating systems, native thread support works only in the latest
versions.

   * AIX 4.x, 5.x with native threads.  *Note IBM-AIX::.

   * Amiga.

   * BSDI 2.x with the MIT-pthreads package.  *Note BSDI::.

   * BSDI 3.0, 3.1 and 4.x with native threads.  *Note BSDI::.

   * DEC Unix 4.x with native threads.  *Note Alpha-DEC-UNIX::.

   * FreeBSD 2.x with the MIT-pthreads package.  *Note FreeBSD::.

   * FreeBSD 3.x and 4.x with native threads.  *Note FreeBSD::.

   * FreeBSD 4.x with Linuxthreads.  *Note FreeBSD::.

   * HP-UX 10.20 with the DCE threads or the MIT-pthreads package.
     *Note HP-UX 10.20::.

   * HP-UX 11.x with the native threads.  *Note HP-UX 11.x::.

   * Linux 2.0+ with LinuxThreads 0.7.1+ or `glibc' 2.0.7+.  *Note
     Linux::.

   * Mac OS X.  *Note Mac OS X::.

   * NetBSD 1.3/1.4 Intel and NetBSD 1.3 Alpha (Requires GNU make).
     *Note NetBSD::.

   * Novell NetWare 6.0.  *Note NetWare installation::.

   * OpenBSD > 2.5 with native threads. OpenBSD < 2.5 with the
     MIT-pthreads package.  *Note OpenBSD::.

   * OS/2 Warp 3, FixPack 29 and OS/2 Warp 4, FixPack 4.  *Note OS/2::.

   * SCO OpenServer with a recent port of the FSU Pthreads package.
     *Note SCO::.

   * SCO UnixWare 7.1.x.  *Note SCO UnixWare::.

   * SGI Irix 6.x with native threads.  *Note SGI-Irix::.

   * Solaris 2.5 and above with native threads on SPARC and x86.  *Note
     Solaris::.

   * SunOS 4.x with the MIT-pthreads package.  *Note Solaris::.

   * Tru64 Unix

   * Windows 9x, Me, NT, 2000, and XP.  *Note Windows installation::.

Not all platforms are equally well-suited for running MySQL. How well a
certain platform is suited for a high-load mission-critical MySQL
server is determined by the following factors:

   * General stability of the thread library. A platform may have an
     excellent reputation otherwise, but MySQL will be only as stable
     as the thread library if that library is unstable in the code that
     is called by MySQL, even if everything else is perfect.

   * The ability of the kernel and/or thread library to take advantage
     of symmetric multi-processor (SMP) systems. In other words, when a
     process creates a thread, it should be possible for that thread to
     run on a different CPU than the original process.

   * The ability of the kernel and/or the thread library to run many
     threads which acquire and release a mutex over a short critical
     region frequently without excessive context switches. In other
     words, if the implementation of `pthread_mutex_lock()' is too
     anxious to yield CPU time, this will hurt MySQL tremendously. If
     this issue is not taken care of, adding extra CPUs will actually
     make MySQL slower.

   * General filesystem stability and performance.

   * If your tables are big, the ability of the filesystem to deal with
     large files at all and to deal with them efficiently.

   * Our level of expertise here at MySQL AB with the platform. If we
     know a platform well, we enable platform-specific optimizations
     and fixes at compile time. We can also provide advice on
     configuring your system optimally for MySQL.

   * The amount of testing we have done internally for similar
     configurations.

   * The number of users that have successfully run MySQL on that
     platform in similar configurations. If this number is high, the
     chances of encountering platform-specific surprises are much
     smaller.

Based on the preceding criteria, the best platforms for running MySQL
at this point are x86 with SuSE Linux 8.2, 2.4 kernel, and ReiserFS (or
any similar Linux distribution) and SPARC with Solaris (2.7-9). FreeBSD
comes third, but we really hope it will join the top club once the
thread library is improved. We also hope that at some point we will be
able to include into the top category all other platforms on which
MySQL currently compiles and runs okay, but not quite with the same
level of stability and performance.  This will require some effort on
our part in cooperation with the developers of the operating system and
library components that MySQL depends on. If you are interested in
improving one of those components, are in a position to influence its
development, and need more detailed instructions on what MySQL needs to
run better, send an email message to the MySQL internals mailing list.
*Note Mailing-list::.

Please note that the purpose of the preceding comparison is not to say
that one operating system is better or worse than another in general.
We are talking only about choosing an OS for the specific purpose of
running MySQL.  With this in mind, the result of this comparison would
be different if we considered more factors. And in some cases, the
reason one OS is better than the other could simply be that we have put
forth more effort into testing on and optimizing for that particular
platform.  We are just stating our observations to help you decide
which platform to use MySQL in your setup.

Choosing Which MySQL Distribution to Install
--------------------------------------------

When preparing to install MySQL, you should decide which version to
use.  MySQL development occurs in several release series, and you can
pick the one that best fits your needs.  After deciding which version
to install, you can choose a distribution format.  Releases are
available in binary or source format.

Choosing Which Version of MySQL to Install
..........................................

The first decision to make is whether you want to use a production
(stable) release or a development release.  In the MySQL development
process, multiple release series co-exist, each at a different stage of
maturity:

   * MySQL 5.0 is the newest development release series and is under
     very active development for new features. Until recently it was
     available only in preview form from the BitKeeper source
     repository. An early alpha release has now been issued to allow
     more widespread testing.

   * MySQL 4.1 is a development release series to which major new
     features have been added. It is still at alpha status. Sources and
     binaries are available for use and testing on development systems.

   * MySQL 4.0 is the current stable/production-quality release series.
     New releases are issued for bugfixes. No new features are added
     that could diminish the code stability.

   * MySQL 3.23 is the old stable/production-quality release series.
     This series is retired, so new releases are issued only to fix
     critical bugs.


We don't believe in a complete freeze, as this also leaves out bug
fixes and things that "must be done."  "Somewhat frozen" means that we
may add small things that "almost surely will not affect anything
that's already working." Naturally, relevant bugfixes from an earlier
series propagate to later series.

   * Normally, if you are beginning to use MySQL for the first time or
     trying to port it to some system for which there is no binary
     distribution, we recommend going with the production release
     series. Currently this is MySQL 4.0.  Note that all MySQL
     releases, even those from development series, are checked with the
     MySQL benchmarks and an extensive test suite before being issued.

   * If you are running an old system and want to upgrade, but don't
     want to take chances with a non-seamless upgrade, you should
     upgrade to the latest version in the same release series you are
     using (where only the last part of the version number is newer
     than yours).  We have tried to fix only fatal bugs and make small,
     relatively safe changes to that version.

   * If you want to use new features not present in the production
     release series, you can use a version from a development series.
     Note that development releases are not as stable as production
     releases.

   * If you want to use the very latest sources containing all current
     patches and bugfixes, you can use one of our BitKeeper
     repositories.  These are not "releases" as such, but are available
     as previews of the code on which future releases will be based.

The MySQL naming scheme uses release names that consist of three
numbers and a suffix, for example, `mysql-4.1.0-alpha'.  The numbers
within the release name are is interpreted like this:

   * The first number (`4') is the major version and also describes the
     file format.  All Version 4 releases have the same file format.

   * The second number (`1') is the release level.  Taken together, the
     major version and release level constitute the release series
     number.

   * The third number (`0') is the version number within the release
     series.  This is incremented for each new release.  Usually you
     want the latest version for the series you have chosen.


For each minor update, the last number in the version string is
incremented.  When there are major new features or minor
incompatibilities with previous versions, the second number in the
version string is incremented.  When the file format changes, the first
number is increased.

Release names also include a suffix to indicates the stability level of
the release.  Releases within a series progress through a set of
suffixes to indicate how the stability level improves.  The possible
suffixes are:

   * `alpha' indicates that the release contains some large section of
     new code that hasn't been 100% tested.  Known bugs (usually there
     are none) should be documented in the News section.  *Note News::.
     There are also new commands and extensions in most alpha
     releases.  Active development that may involve major code changes
     can occur in an alpha release, but everything will be tested
     before issuing a release.  For this reason, there should be no
     known bugs in any MySQL release.

   * `beta' means that all new code has been tested.  No major new
     features that could cause corruption in old code are added.  There
     should be no known bugs.  A version changes from alpha to beta
     when there haven't been any reported fatal bugs within an alpha
     version for at least a month and we have no plans to add any
     features that could make any old command unreliable.

   * `gamma' is a beta that has been around a while and seems to work
     fine.  Only minor fixes are added.  This is what many other
     companies call a release.

   * If there is no suffix, it means that the version has been run for a
     while at many different sites with no reports of bugs other than
     platform-specific bugs.  Only critical bug fixes are applied to the
     release. This is what we call a production (stable) release.

MySQL uses a naming scheme that is slightly different from most other
products.  In general, it's relatively safe to use any version that has
been out for a couple of weeks without being replaced with a new
version within the release series.

All releases of MySQL are run through our standard tests and benchmarks
to ensure that they are relatively safe to use.  Because the standard
tests are extended over time to check for all previously found bugs,
the test suite keeps getting better.

Note that all releases have been tested at least with:

An internal test suite
     The `mysql-test' directory contains an extensive set of test cases.
     We run these tests for virtually every server binary.  See *Note
     MySQL test suite:: for more information about this test suite.

The MySQL benchmark suite
     This suite runs a range of common queries.  It is also a test to
     see whether the latest batch of optimizations actually made the
     code faster.  *Note MySQL Benchmarks::.

The `crash-me' test
     This test tries to determine what features the database supports
     and what its capabilities and limitations are.  *Note MySQL
     Benchmarks::.

Another test is that we use the newest MySQL version in our internal
production environment, on at least one machine.  We have more than 100
gigabytes of data to work with.

Choosing a Distribution Format
..............................

After choosing which version of MySQL to install, you should decide
whether to use a binary distribution or a source distribution.  In most
cases you should probably use a binary distribution, if one exists for
your platform. Binary distributions are available in native format for
many platforms, such as RPM files for Linux or DMG package installers
for Mac OS X. Distributions also are available as Zip archives or
compressed `tar' files.

Reasons to choose a binary distribution include the following:

   * Binary distributions generally are easier to install than source
     distributions.

   * To satisfy different user requirements, we provide two different
     binary versions: one compiled with the non-transactional storage
     engines (a small, fast binary), and one configured with the most
     important extended options like transaction-safe tables.  Both
     versions are compiled from the same source distribution.  All
     native MySQL clients can connect to both MySQL versions.

     The extended MySQL binary distribution is marked with the `-max'
     suffix and is configured with the same options as `mysqld-max'.
     *Note `mysqld-max': mysqld-max.

     If you want to use the `MySQL-Max' RPM, you must first install the
     standard `MySQL-server' RPM.


Circumstances under which you probably will be better off with a source
installation include the following:

   * You want to install MySQL at some explicit location.  The standard
     binary distributions are "ready to run" at any place, but you may
     want to have even more flexibility to place MySQL components where
     you want.

   * You want to configure `mysqld' with some extra features that are
     not in the standard binary distributions.  Here is a list of the
     most common extra options that you may want to use:

        * `--with-innodb' (default for MySQL 4.0 and onwards)

        * `--with-berkeley-db' (not available on all platforms)

        * `--with-raid'

        * `--with-libwrap'

        * `--with-named-z-libs' (This is done for some of the binaries)

        * `--with-debug[=full]'

   * You want to configure `mysqld' without some features that are
     included in the standard binary distributions. For example,
     distributions normally are compiled with support for all character
     sets. If you want a smaller MySQL server, you can recompile it
     with support for only the character sets you need.

   * You have a special compiler (like `pgcc') or want to use compiler
     options that are better optimized for your processor.  Binary
     distributions are compiled with options that should work on a
     variety of processors from the same processor family.

   * You want to use the latest sources from one of the BitKeeper
     repositories to have access to all current bugfixes. For example,
     if you have found a bug and reported it to the MySQL development
     team, the bugfix will be committed to the source repository and you
     can access it there.  The bugfix will not appear in a release until
     a release actually is issued.

   * You want to read (or modify) the C and C++ code that makes up
     MySQL. For this purpose, you should get a source distribution,
     because the source code is always the ultimate manual.  Source
     distributions also contain more tests and examples than binary
     distributions.


How and When Updates Are Released
.................................

MySQL is evolving quite rapidly here at MySQL AB and we want to share
new developments with other MySQL users.  We try to make a release when
we have very useful features that others seem to have a need for.

We also try to help out users who request features that are easy to
implement.  We take note of what our licensed users want to have, and
we especially take note of what our extended email supported customers
want and try to help them out.

No one has to download a new release.  The News section will tell you if
the new release has something you really want.  *Note News::.

We use the following policy when updating MySQL:

   * Releases are issued within each release series. For each release,
     the last number in the version is one more than the previous
     release within the same series.

   * Production (stable) releases are meant to appear about 1-2 times a
     year, but if small bugs are found, a release with only bug fixes
     will be issued.

   * Working releases/bug fixes to old releases are meant to appear
     about every 4-8 weeks.

   * Binary distributions for some platforms are made by us for major
     releases.  Other people may make binary distributions for other
     systems, but probably less frequently.

   * We usually make fixes available as soon as we have identified and
     corrected small or non-critical but annoying bugs. The fixes are
     available immediately from our public BitKeeper repositories, and
     will be included in the next release.

   * If by any chance a fatal bug is found in a release, we will make a
     new release as soon as possible.  We would like other companies to
     do this, too.

Release Philosophy--No Known Bugs in Releases
.............................................

We put a lot of time and effort into making our releases bug free.  To
our knowledge, we have not released a single MySQL version with any
_known_ "fatal" repeatable bugs.  (A fatal bug is something that
crashes MySQL under normal usage, produces incorrect answers for normal
queries, or has a security problem.)

We have documented all open problems, bugs, and issues that are
dependent on design decisions.  *Note Bugs::.

Our aim is to fix everything that is fixable without risk of making a
stable MySQL version less stable. In certain cases, this means we can
fix an issue in the development versions, but not in the stable
(production) version. Naturally, we document such issues so that users
are aware.

Here is a description of how our build process works:
   * We monitor bugs from our customer support list, the bugs database
     at `http://bugs.mysql.com/', and the MySQL external mailing lists.

   * All reported bugs for live versions are entered into the bugs
     database.

   * When we fix a bug, we always try to make a test case for it and
     include it into our test system to ensure that the bug will never
     recur without being detected. (About 90% of all fixed bugs have a
     test case.)

   * We also create test cases for all new features we add to MySQL.

   * Before we start to build a new MySQL release, we ensure that all
     reported repeatable bugs for the MySQL version (3.23.x, 4.0.x, etc)
     are fixed.  If something is impossible to fix (due to some internal
     design decision in MySQL) we document this in the manual.  *Note
     Bugs::.

   * We do a build on all platforms for which we support binaries (15+
     platforms) and run our test suite and benchmark suite on all of
     them.

   * We will not publish a binary for a platform for which the test or
     benchmark suite fails.  If it's a general error in the source, we
     fix this and do the build plus tests on all systems again, from
     scratch.

   * The build and test process takes 2-3 days).  If we receive a
     report regarding a fatal bug during this process (for example, one
     that causes a core dump), we fix the problem and restart the build
     process.

   * After publishing the binaries on `http://www.mysql.com/', we send
     out an announcement message to the `mysql' and `announce' mailing
     lists.  *Note Mailing-list::.  The announcement message contains a
     list of all changes to the release and any known problems with the
     release.  (The "known problems" section in the release notes has
     only been needed in a handful of releases.)

   * To quickly give our users access to the latest MySQL features, we
     do a new MySQL release every 4-8 weeks.  Source code snapshots are
     built daily and are available at
     `http://downloads.mysql.com/snapshots.php'.

   * If we, after the release is done, get any bug reports that there
     was (after all) anything critically wrong with the build on a
     specific platform, we will fix this at once and build a new `'a''
     release for that platform. Thanks to our large user base, problems
     are found quickly.

   * Our track record for making good releases is quite good.  In the
     last 150 releases, we had to do a new build for less than 10
     releases (in 3 of these cases, the bug was a faulty `glibc'
     library on one of our build machines that took us a long time to
     track down).

MySQL Binaries Compiled by MySQL AB
...................................

As a service, we at MySQL AB provide a set of binary distributions of
MySQL that are compiled at our site or at sites where customers kindly
have given us access to their machines.

In addition to the binaries provided in platform-specific package
formats (see *Note Quick Standard Installation::), we do offer binary
distributions for a number of platforms in the form of of compressed
tar files (`.tar.gz').

These distributions are generated using the script
`Build-tools/Do-compile' which compiles the source code and creates the
binary `tar.gz' archive using `scripts/make_binary_distribution' These
binaries are configured and built with the following compilers and
options.

Binaries built on MySQL AB development systems:

Linux 2.4.xx x86 with `gcc' 2.95.3:
     `CFLAGS="-O2 -mcpu=pentiumpro" CXX=gcc CXXFLAGS="-O2
     -mcpu=pentiumpro -felide-constructors" ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --enable-assembler --disable-shared
     --with-client-ldflags=-all-static
     --with-mysqld-ldflags=-all-static'

Linux 2.4.xx Intel Itanium 2 with `ecc' (Intel C++ Itanium Compiler 7.0):
     `CC=ecc CFLAGS="-O2 -tpp2 -ip -nolib_inline" CXX=ecc CXXFLAGS="-O2
     -tpp2 -ip -nolib_inline" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile'

Linux 2.4.xx Intel Itanium with `ecc' (Intel C++ Itanium Compiler 7.0):
     `CC=ecc CFLAGS=-tpp1 CXX=ecc CXXFLAGS=-tpp1 ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile'

Linux 2.4.xx alpha with `ccc' (Compaq C V6.2-505 / Compaq C++ V6.3-006):
     `CC=ccc CFLAGS="-fast -arch generic" CXX=cxx CXXFLAGS="-fast -arch
     generic -noexceptions -nortti" ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --with-mysqld-ldflags=-non_shared
     --with-client-ldflags=-non_shared --disable-shared'

Linux 2.4.xx s390 with `gcc' 2.95.3:
     `CFLAGS="-O2" CXX=gcc CXXFLAGS="-O2 -felide-constructors"
     ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --disable-shared
     --with-client-ldflags=-all-static
     --with-mysqld-ldflags=-all-static'

Linux 2.4.xx x86_64 (AMD64) with `gcc' 3.2.1:
     `CXX=gcc ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile  --disable-shared'

Sun Solaris 8 x86 with `gcc' 3.2.3:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --disable-shared --with-innodb'

Sun Solaris 8 SPARC with `gcc' 3.2:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --enable-assembler --with-named-z-libs=no
     --with-named-curses-libs=-lcurses --disable-shared'

Sun Solaris 8 SPARC 64-bit with `gcc' 3.2:
     `CC=gcc CFLAGS="-O3 -m64 -fno-omit-frame-pointer" CXX=gcc
     CXXFLAGS="-O3 -m64 -fno-omit-frame-pointer -felide-constructors
     -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --enable-assembler --with-named-z-libs=no
     --with-named-curses-libs=-lcurses --disable-shared'

Sun Solaris 9 SPARC with `gcc' 2.95.3:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --enable-assembler
     --with-named-curses-libs=-lcurses --disable-shared'

Sun Solaris 9 SPARC with `cc-5.0' (Sun Forte 5.0):
     `CC=cc-5.0 CXX=CC ASFLAGS="-xarch=v9" CFLAGS="-Xa -xstrconst -mt
     -D_FORTEC_ -xarch=v9" CXXFLAGS="-noex -mt -D_FORTEC_ -xarch=v9"
     ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --enable-assembler --with-named-z-libs=no
     --enable-thread-safe-client --disable-shared'

IBM AIX 4.3.2 ppc with `gcc' 3.2.3:
     `CFLAGS="-O2 -mcpu=powerpc -Wa,-many " CXX=gcc CXXFLAGS="-O2
     -mcpu=powerpc -Wa,-many  -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --with-named-z-libs=no --disable-shared'

IBM AIX 4.3.3 ppc with `xlC_r' (IBM Visual Age C/C++ 6.0):
     `CC=xlc_r CFLAGS="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192"
     CXX=xlC_r CXXFLAGS ="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192"
     ./configure --prefix=/usr/local/mysql
     --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --with-named-z-libs=no --disable-shared --with-innodb'

IBM AIX 5.1.0 ppc with `gcc' 3.3:
     `CFLAGS="-O2 -mcpu=powerpc -Wa,-many" CXX=gcc CXXFLAGS="-O2
     -mcpu=powerpc -Wa,-many  -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --with-server-suffix="-pro"
     --enable-thread-safe-client --enable-local-infile
     --with-named-z-libs=no --disable-shared'

HP-UX 10.20 pa-risc1.1 with `gcc' 3.1:
     `CFLAGS="-DHPUX -I/opt/dce/include -O3 -fPIC" CXX=gcc
     CXXFLAGS="-DHPUX -I/opt/dce /include -felide-constructors
     -fno-exceptions -fno-rtti -O3 -fPIC" ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile  --with-pthread
     --with-named-thread-libs=-ldce --with-lib-ccflags=-fPIC
     --disable-shared'

HP-UX 11.11 pa-risc2.0 64bit with `aCC' (HP ANSI C++ B3910B A.03.33):
     `CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile --disable-shared'

HP-UX 11.11 pa-risc2.0 32bit with `aCC' (HP ANSI C++ B3910B A.03.33):
     `CC=cc CXX=aCC CFLAGS="+DAportable" CXXFLAGS="+DAportable"
     ./configure --prefix=/usr/local/mysql
     --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --disable-shared --with-innodb'

Apple Mac OS X 10.2 powerpc with `gcc' 3.1:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile  --disable-shared'

FreeBSD 4.7 i386 with `gcc' 2.95.4:
     `CFLAGS=-DHAVE_BROKEN_REALPATH ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --enable-assembler --with-named-z-libs=not-used --disable-shared'

QNX Neutrino 6.2.1 i386 with `gcc' 2.95.3qnx-nto 20010315:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile  --disable-shared'

The following binaries are built on third-party systems kindly provided
to MySQL AB by other users. Please note that these are only provided as
a courtesy. Since MySQL AB does not have full control over these
systems, we can provide only limited support for the binaries built on
these systems.

SCO Unix 3.2v5.0.6 i386 with `gcc' 2.95.3:
     `CFLAGS="-O3 -mpentium" LDFLAGS=-static CXX=gcc CXXFLAGS="-O3
     -mpentium -felide-constructors" ./configure
     --prefix=/usr/local/mysql --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile
     --with-named-z-libs=no --enable-thread-safe-client
     --disable-shared'

SCO OpenUnix 8.0.0 i386 with `CC' 3.2:
     `CC=cc CFLAGS="-O" CXX=CC ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --with-named-z-libs=no
     --enable-thread-safe-client --disable-shared'

Compaq Tru64 OSF/1 V5.1 732 alpha with `cc/cxx' (Compaq C V6.3-029i / DIGITAL C++ V6.1-027):
     `CC="cc -pthread" CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline
     speed -speculate all" CXX="cxx -pthread" CXXFLAGS="-O4 -ansi_alias
     -fast -inline speed -speculate all -noexceptions -nortti"
     ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --with-prefix=/usr/local/mysql
     --with-named-thread-libs="-lpthread -lmach -lexc -lc"
     --disable-shared --with-mysqld-ldflags=-all-static'

SGI Irix 6.5 IP32 with `gcc' 3.0.1:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile  --disable-shared'

FreeBSD/sparc64 5.0 with `gcc' 3.2.1:
     `CFLAGS=-DHAVE_BROKEN_REALPATH ./configure
     --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data
     --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex
     --enable-thread-safe-client --enable-local-infile --disable-shared
     --with-innodb'

The following compile options have been used for binary packages MySQL
AB used to provide in the past. These binaries are no longer being
updated, but the compile options are listed here for reference purposes.

Linux 2.2.xx SPARC with `egcs' 1.1.2:
     `CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3
     -fno-omit-frame-pointer -felide-constructors -fno-exceptions
     -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex --enable-thread-safe-client
     --enable-local-infile --enable-assembler --disable-shared'

Linux 2.2.x with x686 with `gcc' 2.95.2:
     `CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro
     -felide-constructors -fno-exceptions -fno-rtti" ./configure
     --prefix=/usr/local/mysql --enable-assembler
     --with-mysqld-ldflags=-all-static --disable-shared
     --with-extra-charsets=complex'

SunOS 4.1.4 2 sun4c with `gcc' 2.7.2.1:
     `CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors" ./configure
     --prefix=/usr/local/mysql --disable-shared
     --with-extra-charsets=complex --enable-assembler'

SunOS 5.5.1 (and above) sun4u with `egcs' 1.0.3a or 2.90.27 or `gcc' 2.95.2 and newer:
     `CC=gcc CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors
     -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql
     --with-low-memory --with-extra-charsets=complex --enable-assembler'

SunOS 5.6 i86pc with `gcc' 2.8.1:
     `CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql
     --with-low-memory --with-extra-charsets=complex'

BSDI BSD/OS 3.1 i386 with `gcc' 2.7.2.1:
     `CC=gcc CXX=gcc CXXFLAGS=-O ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex'

BSDI BSD/OS 2.1 i386 with `gcc' 2.7.2:
     `CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex'

AIX 2 4 with `gcc' 2.7.2.2:
     `CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql
     --with-extra-charsets=complex'

Anyone who has more optimal options for any of the preceding
configurations listed can always mail them to the MySQL internals
mailing list.  *Note Mailing-list::.

RPM distributions prior to MySQL Version 3.22 are user-contributed.
Beginning with Version 3.22, the RPM distributions are generated by us
at MySQL AB.

If you want to compile a debug version of MySQL, you should add
`--with-debug' or `--with-debug=full' to the preceding configure lines
and remove any `-fomit-frame-pointer' options.

For the Windows distribution, please see *Note Windows installation::.

How to Get MySQL
----------------

Check the MySQL homepage (`http://www.mysql.com/') for information
about the current version and for downloading instructions.

Our main mirror is located at `http://mirrors.sunsite.dk/mysql/'.

For a complete up-to-date list of MySQL web/download mirrors, see
`http://www.mysql.com/downloads/mirrors.html'.  There you will also
find information about becoming a MySQL mirror site and how to report a
bad or out-of-date mirror.

Verifying Package Integrity Using MD5 Checksums or `GnuPG'
----------------------------------------------------------

After you have downloaded the MySQL package that suits your needs and
before you attempt to install it, you should make sure it is intact and
has not been tampered with.

MySQL AB offers three means of integrity checking:

   * MD5 checksums

   * Cryptographic signatures using `GnuPG', the GNU Privacy Guard

   * For RPM packages, the built-in RPM integrity verification mechanism


The following sections describe how to use these methods.

Verifying the `MD5 Checksum'
----------------------------

After you have downloaded the package, you should make sure that the MD5
checksum matches the one provided on the MySQL download pages. Each
package has an individual checksum that you can verify with the
following command, where `package_name' is the name of the package you
downloaded:

     shell> md5sum package_name

Note, that not all operating systems support the `md5sum' command--on
some it is simply called `md5', others do not ship it at all. On Linux,
it is part of the `GNU Text Utilities' package, which is available for
a wide range of platforms. You can download the source code from
`http://www.gnu.org/software/textutils/' as well. If you have `OpenSSL'
installed, you can also use the command `openssl md5 package_name'
instead. A DOS/Windows implementation of the `md5' command is available
from `http://www.fourmilab.ch/md5/'.

Example:
     shell> md5sum mysql-standard-4.0.17-pc-linux-i686.tar.gz
     60f5fe969d61c8f82e4f7f62657e1f06
                     mysql-standard-4.0.17-pc-linux-i686.tar.gz

You should verify that the resulting checksum (the string of hexadecimal
digits) matches the one displayed on the download page immediately
below the respective package.

Signature Checking Using `GnuPG'
--------------------------------

Another method of verifying the integrity and authenticity of a package
is to use cryptographic signatures. This is more reliable than using MD5
checksums, but requires more work.

Beginning with MySQL 4.0.10 (February 2003), MySQL AB started signing
downloadable packages with `GnuPG' (`GNU Privacy Guard').  `GnuPG' is
an Open Source alternative to the very well-known `Pretty Good Privacy'
(`PGP') by Phil Zimmermann.  See `http://www.gnupg.org/' for more
information about `GnuPG' and how to obtain and install it on your
system. Most Linux distributions already ship with `GnuPG' installed by
default.  For more information about `OpenPGP', see
`http://www.openpgp.org/'.

To verify the signature for a specific package, you first need to
obtain a copy of MySQL AB's public GPG build key <[e-mail]>. 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) <[e-mail]>
     Fingerprint: A4A9 4068 76FC BD3C 4567  70C8 8C71 8D3B 5072 E1F5

     Public Key (ASCII-armored):

     -----BEGIN PGP PUBLIC KEY BLOCK-----
     Version: GnuPG v1.0.6 (GNU/Linux)
     Comment: For info see http://www.gnupg.org

     mQGiBD4+owwRBAC14GIfUfCyEDSIePvEW3SAFUdJBtoQHH/nJKZyQT7h9bPlUWC3
     RODjQReyCITRrdwyrKUGku2FmeVGwn2u2WmDMNABLnpprWPkBdCk96+OmSLN9brZ
     fw2vOUgCmYv2hW0hyDHuvYlQA/BThQoADgj8AW6/0Lo7V1W9/8VuHP0gQwCgvzV3
     BqOxRznNCRCRxAuAuVztHRcEAJooQK1+iSiunZMYD1WufeXfshc57S/+yeJkegNW
     hxwR9pRWVArNYJdDRT+rf2RUe3vpquKNQU/hnEIUHJRQqYHo8gTxvxXNQc7fJYLV
     K2HtkrPbP72vwsEKMYhhr0eKCbtLGfls9krjJ6sBgACyP/Vb7hiPwxh6rDZ7ITnE
     kYpXBACmWpP8NJTkamEnPCia2ZoOHODANwpUkP43I7jsDmgtobZX9qnrAXw+uNDI
     QJEXM6FSbi0LLtZciNlYsafwAPEOMDKpMqAK6IyisNtPvaLd8lH0bPAnWqcyefep
     rv0sxxqUEMcM3o7wwgfN83POkDasDbs3pjwPhxvhz6//62zQJ7Q7TXlTUUwgUGFj
     a2FnZSBzaWduaW5nIGtleSAod3d3Lm15c3FsLmNvbSkgPGJ1aWxkQG15c3FsLmNv
     bT6IXQQTEQIAHQUCPj6jDAUJCWYBgAULBwoDBAMVAwIDFgIBAheAAAoJEIxxjTtQ
     cuH1cY4AnilUwTXn8MatQOiG0a/bPxrvK/gCAJ4oinSNZRYTnblChwFaazt7PF3q
     zIhMBBMRAgAMBQI+PqPRBYMJZgC7AAoJEElQ4SqycpHyJOEAn1mxHijft00bKXvu
     cSo/pECUmppiAJ41M9MRVj5VcdH/KN/KjRtW6tHFPYhMBBMRAgAMBQI+QoIDBYMJ
     YiKJAAoJELb1zU3GuiQ/lpEAoIhpp6BozKI8p6eaabzF5MlJH58pAKCu/ROofK8J
     Eg2aLos+5zEYrB/LsrkCDQQ+PqMdEAgA7+GJfxbMdY4wslPnjH9rF4N2qfWsEN/l
     xaZoJYc3a6M02WCnHl6ahT2/tBK2w1QI4YFteR47gCvtgb6O1JHffOo2HfLmRDRi
     Rjd1DTCHqeyX7CHhcghj/dNRlW2Z0l5QFEcmV9U0Vhp3aFfWC4Ujfs3LU+hkAWzE
     7zaD5cH9J7yv/6xuZVw411x0h4UqsTcWMu0iM1BzELqX1DY7LwoPEb/O9Rkbf4fm
     Le11EzIaCa4PqARXQZc4dhSinMt6K3X4BrRsKTfozBu74F47D8Ilbf5vSYHbuE5p
     /1oIDznkg/p8kW+3FxuWrycciqFTcNz215yyX39LXFnlLzKUb/F5GwADBQf+Lwqq
     a8CGrRfsOAJxim63CHfty5mUc5rUSnTslGYEIOCR1BeQauyPZbPDsDD9MZ1ZaSaf
     anFvwFG6Llx9xkU7tzq+vKLoWkm4u5xf3vn55VjnSd1aQ9eQnUcXiL4cnBGoTbOW
     I39EcyzgslzBdC++MPjcQTcA7p6JUVsP6oAB3FQWg54tuUo0Ec8bsM8b3Ev42Lmu
     QT5NdKHGwHsXTPtl0klk4bQk4OajHsiy1BMahpT27jWjJlMiJc+IWJ0mghkKHt92
     6s/ymfdf5HkdQ1cyvsz5tryVI3Fx78XeSYfQvuuwqp2H139pXGEkg0n6KdUOetdZ
     Whe70YGNPw1yjWJT1IhMBBgRAgAMBQI+PqMdBQkJZgGAAAoJEIxxjTtQcuH17p4A
     n3r1QpVC9yhnW2cSAjq+kr72GX0eAJ4295kl6NxYEuFApmr1+0uUq/SlsQ==
     =YJkx
     -----END PGP PUBLIC KEY BLOCK-----

You can import this key into your public GPG keyring by using `gpg
--import'. See the GPG documentation for more info on how to work with
public keys.

After you have downloaded and imported the public build key, download
your desired MySQL package and the corresponding signature, which also
is available from the download page.  The signature file has the same
name as the distribution file with an `.asc' extension. For example:

Distribution file      `mysql-standard-4.0.17-pc-linux-i686.tar.gz'
Signature file         `mysql-standard-4.0.17-pc-linux-i686.tar.gz.asc'

Make sure that both files are stored in the same directory and then run
the following command to verify the signature for the distribution file:

     shell> gpg --verify package_name.asc

Example:

     shell> gpg --verify mysql-standard-4.0.17-pc-linux-i686.tar.gz.asc
     gpg: Warning: using insecure memory!
     gpg: Signature made Mon 03 Feb 2003 08:50:39 PM MET using DSA key ID 5072E1F5
     gpg: Good signature from
          "MySQL Package signing key (www.mysql.com) <[e-mail]>"

The "Good signature" message indicates that everything is all right.

Signature Checking Using `RPM'
------------------------------

For RPM packages, there is no separate signature. RPM packages actually
have a built-in GPG signature and MD5 checksum. You can verify a
package by running the following command:

     shell> rpm --checksig package_name.rpm

Example:

     shell> rpm --checksig MySQL-server-4.0.10-0.i386.rpm
     MySQL-server-4.0.10-0.i386.rpm: md5 gpg OK

*Note:* If you are using RPM 4.1 and it complains about `(GPG) NOT OK
(MISSING KEYS: GPG#5072e1f5)' (even though you have imported it into
your GPG public keyring), you need to import the key into the RPM
keyring first. RPM 4.1 no longer uses your GPG keyring (and GPG
itself), but rather maintains its own keyring (because it's a
system-wide application and the GPG public keyring is a user-specific
file). To import the MySQL public key into the RPM keyring, use `rpm
--import'. For example, if you have the public key stored in a file
named `mysql_pubkey.asc', import it using this command:

     shell> rpm --import mysql_pubkey.asc

If you notice that the MD5 checksum or GPG signatures do not match,
first try to download the respective package one more time, perhaps
from another mirror site. If you repeatedly cannot successfully verify
the integrity of the package, please notify us about such incidents
including the full package name and the download site you have been
using at <[e-mail]> or <[e-mail]>.  Do not report
downloading problems using the bug-reporting system.

Installation Layouts
--------------------

This section describes the default layout of the directories created by
installing binary and source distributions.

On Windows, the default installation directory is `C:\mysql', which has
the following subdirectories:

*Directory*               *Contents of directory*
`bin'                     Client programs and the
                          `mysqld' server
`data'                    Log files, databases
`Docs'                    Documentation
`examples'                Example programs and scripts
`include'                 Include (header) files
`lib'                     Libraries
`scripts'                 Utility scripts
`share'                   Error message files

Installations created from Linux RPM distributions result in files under
the following system directories:

*Directory*               *Contents of directory*
`/usr/bin'                Client programs
`/usr/sbin'               `mysqld' server
`/var/lib/mysql'          Log files, databases
`/usr/share/doc/packages' Documentation
`include'                 Include (header) files
`lib'                     Libraries
`scripts'                 `mysql_install_db'
`/usr/share/mysql'        Error message and character set
                          files
`sql-bench'               Benchmarks

On Unix, a `tar' file binary distribution is installed by unpacking it
at the installation location you choose (typically `/usr/local/mysql')
and creates the following directories in that location:

*Directory*               *Contents of directory*
`bin'                     Client programs and the
                          `mysqld' server
`data'                    Log files, databases
`docs'                    Documentation, ChangeLog
`include'                 Include (header) files
`lib'                     Libraries
`scripts'                 `mysql_install_db'
`share/mysql'             Error message files
`sql-bench'               Benchmarks

A source distribution is installed after you configure and compile it.
By default, the installation step installs files under `/usr/local', in
the following subdirectories:

*Directory*               *Contents of directory*
`bin'                     Client programs and scripts
`include/mysql'           Include (header) files
`info'                    Documentation in Info format
`lib/mysql'               Libraries
`libexec'                 The `mysqld' server
`share/mysql'             Error message files
`sql-bench'               Benchmarks and `crash-me' test
`var'                     Databases and log files

Within an installation directory, the layout of a source installation
differs from that of a binary installation in the following ways:

   * The `mysqld' server is installed in the `libexec' directory rather
     than in the `bin' directory.

   * The data directory is `var' rather than `data'.

   * `mysql_install_db' is installed in the `bin' directory rather than
     in the `scripts' directory.

   * The header file and library directories are `include/mysql' and
     `lib/mysql' rather than `include' and `lib'.

You can create your own binary installation from a compiled source
distribution by executing the `scripts/make_binary_distribution' script
from the top directory of the source distribution.

Standard MySQL Installation Using a Binary Distribution
=======================================================

This section covers the installation of MySQL on platforms where we
offer packages using the native packaging format of the respective
platform. (This is also known as performing a "binary install.")
However, binary distributions of MySQL are available for many other
platforms as well. See *Note Installing binary:: for generic
installation instructions for these packages that apply to all
platforms.

See *Note General Installation Issues:: for more information on what
other binary distributions are available and how to obtain them.

Installing MySQL on Windows
---------------------------

The installation process for MySQL on Windows has the following steps:

  1. Install the distribution.

  2. Set up an option file if necessary.

  3. Select the server you want to use.

  4. Start the server.

  5. Assign passwords to the initial MySQL accounts.


MySQL for Windows is available in two distribution formats:

   * The binary distribution contains a setup program that installs
     everything you need so that you can start the server immediately.

   * The source distribution contains all the code and support files
     for building the executables using the VC++ 6.0 compiler.


Generally speaking, you should use the binary distribution. It's
simpler, and you need no additional tools to get MySQL up and running.

This section describes how to install MySQL on Windows using a binary
distribution.  To install using a source distribution, see *Note
Windows source build::.

Windows System Requirements
...........................

To run MySQL on Windows, you need the following:

   * A 32-bit Windows operating system such as 9x, Me, NT, 2000, or XP.
     The NT family (Windows NT, 2000, and XP) permits you to run the
     MySQL server as a service. *Note NT start::.

   * TCP/IP protocol support.

   * A copy of the MySQL binary distribution for Windows, which can be
     downloaded from `http://www.mysql.com/downloads/'.

     Note: The distribution files are supplied with a zipped format and
     we recommend the use of an adequate FTP client with resume feature
     to avoid corruption of files during the download process.

   * A `ZIP' program to unpack the distribution file.

   * Enough space on the hard drive to unpack, install, and create the
     databases in accordance with your requirements.

   * If you plan to connect to the MySQL server via ODBC, you also need
     the `MyODBC' driver. *Note ODBC::.

   * If you need tables with a size larger than 4 GB, install MySQL on
     an NTFS or newer filesystem. Don't forget to use `MAX_ROWS' and
     `AVG_ROW_LENGTH' when you create tables.  *Note `CREATE TABLE':
     CREATE TABLE.


Installing a Windows Binary Distribution
........................................

To install MySQL on Windows using a binary distribution, follow this
procedure:

  1. If you are working on a Windows NT, 2000, or XP machine, make sure
     you have logged in as a user with administrator privileges.

  2. If you are doing an upgrade of an earlier MySQL installation, it
     is necessary to stop the current server.  On Windows NT, 2000, or
     XP machines, if you are running the server as a Windows service,
     stop it as follows from the command prompt:

          C:\> NET STOP MySQL

     If you plan to use a different server after the upgrade (for
     example, if you want to run `mysqld-max' rather than `mysqld'),
     remove the existing service:

          C:\mysql\bin> mysqld --remove

     You can reinstall the service to use the proper server after
     upgrading.

     If you are not running the MySQL server as a service, stop it like
     this:

          C:\mysql\bin> mysqladmin -u root shutdown

  3. Exit the `WinMySQLAdmin' program if it is running.

  4. Unzip the distribution file to a temporary directory.

  5. Run the `setup.exe' program to begin the installation process.  If
     you want to install MySQL into a location other than the default
     directory (`C:\mysql'), use the `Browse' button to specify your
     preferred directory. If you do not install MySQL into the default
     location, you will need to specify the location whenever you start
     the server. The easiest way to do this is to use an option file,
     as described in *Note Windows prepare environment::.

  6. Finish the install process.


*Important note:* Early alpha Windows distributions for MySQL 4.1 do
not contain any installer program.  A 4.1 distribution is a ZIP file
that you just unzip in the location where you want to install MySQL.
For example, to install `mysql-4.1.1-alpha-win.zip' as `C:\mysql', unzip
the distribution file on the `C:' drive, then rename the resulting
`mysql-4.1.1-alpha' directory to `mysql'.

If you are upgrading to MySQL 4.1 from an earlier version, you will
want to preserve your existing `data' directory that contains the grant
tables in the `mysql' database and your own databases.  Before
installing 4.1, stop the server if it is running, and save your `data'
directory to another location. Then either rename the existing
`C:\mysql' directory or remove it.  Install 4.1 as described in the
preceding paragraph, and then replace its `data' directory with your
old `data' directory.  Start the new server and update the grant
tables.  This will avoid loss of your current databases.  *Note
Upgrading-grant-tables::.

Preparing the Windows MySQL Environment
.......................................

If you need to specify startup options when you run the server, you can
indicate them on the command line or place them in an option file. For
options that will be used every time the server starts, you will find
it most convenient to use an option file to specify your MySQL
configuration. This is true particularly under the following
circumstances:

   * The installation or data directory locations are different from
     the default locations (`C:\mysql' and `C:\mysql\data').

   * You need to tune the server settings.  For example, to use the
     `InnoDB' transactional tables in MySQL version 3.23, you must
     manually create two new directories to hold the `InnoDB' data and
     log files--such as, `C:\ibdata' and `C:\iblogs'.  You will also
     need to add some extra lines to the option file, as described in
     *Note `InnoDB' start: InnoDB start.  (As of MySQL 4.0, InnoDB
     creates its datafiles and log files in the data directory by
     default. This means you need not configure InnoDB explicitly.  You
     may still do so if you wish, and an option file will be useful in
     this case, too.)


On Windows, the MySQL installer places the data directory directly under
the directory where you install MySQL.  If you would like to use a data
directory in a different location, you should copy the entire contents
of the `data' directory to the new location. For example, by default,
the installer places MySQL in `C:\mysql' and the data directory in
`C:\mysql\data'. If you want to use a data directory of `E:\mydata',
you must do two things:

   * Move the data directory from `C:\mysql\data' to `E:\mydata'.

   * Use a `--datadir' option to specify the new data directory location
     each time you start the server.


When the MySQL server starts on Windows, it looks for options in two
files:  The `my.ini' file in the Windows directory, and the `C:\my.cnf'
file.  The Windows directory typically is named something like
`C:\WINDOWS' or `C:\WinNT'.  You can determine its exact location from
the value of the `WINDIR' environment variable using the following
command:

     C:\> echo %WINDIR%

MySQL looks for options first in the `my.ini' file, then in the
`my.cnf' file.  However, to avoid confusion, it's best if you use only
one file.  If your PC uses a boot loader where the `C:' drive isn't the
boot drive, your only option is to use the `my.ini' file.  Whichever
one you use, it must be a plain text file.

An option file can be created and modified with any text editor, such
as the `Notepad' program.  For example, if MySQL is installed at
`D:\mysql' and the data directory is located as `D:\mydata\data', you
can create the option file and set up a `[mysqld]' section to specify
values for the `basedir' and `datadir' parameters:

     [mysqld]
     # set basedir to your installation path
     basedir=D:/mysql
     # set datadir to the location of your data directory
     datadir=D:/mydata/data

Note that Windows pathnames are specified in option files using forward
slashes rather than backslashes.  If you do use backslashes, you must
double them.

Another way to manage an option file is to use the the `WinMySQLAdmin'
tool. You can find `WinMySQLAdmin' in the `bin' directory of your MySQL
installation, as well as a help file containing instructions for using
it. `WinMySQLAdmin' has the capability of editing your option file, but
note these points:

   * `WinMySQLAdmin' uses only the `my.ini' file.

   * If `WinMySQLAdmin' finds a `C:\my.cnf' file, it will in fact rename
     it to `C:\my_cnf.bak' to disable it.


Now you are ready to test starting the server.

Selecting a Windows Server
..........................

Starting with MySQL 3.23.38, the Windows distribution includes both the
normal and the MySQL-Max server binaries.  Here is a list of the
different MySQL servers from which you can choose:

*Binary*       *Description*
`mysqld'       Compiled with full debugging and automatic memory
               allocation checking, symbolic links, and `InnoDB' and
               `BDB' tables.
`mysqld-opt'   Optimized binary.  From version 4.0 on, `InnoDB' is
               enabled.  Before 4.0, this server includes no
               transactional table support.
`mysqld-nt'    Optimized binary for NT/2000/XP with support for named
               pipes.
`mysqld-max'   Optimized binary with support for symbolic links, and
               `InnoDB' and `BDB' tables.
`mysqld-max-nt'Like `mysqld-max', but compiled with support for named
               pipes.

All of the preceding binaries are optimized for modern Intel processors
but should work on any Intel i386-class or higher processor.

MySQL supports TCP/IP on all Windows platforms. The `mysqld-nt' and
`mysql-max-nt' servers support named pipes on NT, 2000, and XP.
However, the default is to use TCP/IP regardless of the platform.
(Named pipes are slower than TCP/IP in many Windows configurations.)

Named pipe use is subject to these conditions:

   * Starting from MySQL 3.23.50, named pipes are enabled only if you
     start the server with the `--enable-named-pipe' option.  It is now
     necessary to use this option explicitly because some users have
     experienced problems shutting down the MySQL server when named
     pipes are used.

   * Named pipe connections are allowed only by the `mysqld-nt' or
     `mysqld-max-nt' servers, and only if the server is run on a
     version of Windows that supports named pipes (NT, 2000, XP).

   * These servers can be run on Windows 98 or Me, but only if TCP/IP
     is installed; named pipe connections cannot be used.

   * On Windows 95, these servers cannot be used.


Starting the Server for the First Time
......................................

On Windows 95, 98, or Me, MySQL clients always connect to the server
using TCP/IP.  (This will allow any machine on your network to connect
to your MySQL server.)  Because of this, you must make sure that TCP/IP
support is installed on your machine before starting MySQL.  You can
find TCP/IP on your Windows CD-ROM.

Note that if you are using an old Windows 95 release (for example,
OSR2), it's likely that you have an old Winsock package; MySQL requires
Winsock 2! You can get the newest Winsock from
`http://www.microsoft.com/'.  Windows 98 has the new Winsock 2 library,
so it is unnecessary to update the library.

On NT-based systems such as Windows NT, 2000, or XP, clients have two
options. They can use TCP/IP, or they can use a named pipe if the server
supports named pipe connections.

For information about which server binary to run, see *Note Windows
prepare environment::.

This section gives a general overview of starting the MySQL server.
The following sections provide more specific information for particular
versions of Windows.

The examples in these sections assume that MySQL is installed under the
default location of `C:\mysql'. Adjust the pathnames shown in the
examples if you have MySQL installed in a different location.

Testing is best done from a command prompt in a console window (a "DOS
window"). This way you can have the server display status messages in
the window where they are easy to see.  If something is wrong with your
configuration, these messages will make it easier for you to identify
and fix any problems.

Make sure you are in the directory where the server is located, then
enter this command:

     C:\mysql\bin> mysqld --console

For servers that include `InnoDB' support, you should see the following
messages as the server starts:

     InnoDB: The first specified datafile c:\ibdata\ibdata1 did not exist:
     InnoDB: a new database to be created!
     InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200
     InnoDB: Database physically writes the file full: wait...
     InnoDB: Log file c:\iblogs\ib_logfile0 did not exist: new to be created
     InnoDB: Setting log file c:\iblogs\ib_logfile0 size to 31457280
     InnoDB: Log file c:\iblogs\ib_logfile1 did not exist: new to be created
     InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280
     InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be created
     InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280
     InnoDB: Doublewrite buffer not found: creating new
     InnoDB: Doublewrite buffer created
     InnoDB: creating foreign key constraint system tables
     InnoDB: foreign key constraint system tables created
     011024 10:58:25  InnoDB: Started

When the server finishes its startup sequence, you should see something
like this, which indicates that the server is ready to service client
connections:

     mysqld: ready for connections
     Version: '4.0.14-log'  socket: ''  port: 3306

The server will continue to write to the console any further diagnostic
output it produces.  You can open a new console window in which to run
client programs.

If you omit the `--console' option, the server writes diagnostic output
to the error log in the data directory. The error log is the file with
the `.err' extension.

The accounts that are listed in the MySQL grant tables initially have no
passwords.  After starting the server, you should set up passwords for
them using the instructions in *Note Post-installation::.

Starting MySQL from the Windows Command Line
............................................

The MySQL server can be started manually from the command line.  This
can be done on any version of Windows.

To start the `mysqld' server from the command line, you should start a
console window (a "DOS" window) and enter this command:

     shell> C:\mysql\bin\mysqld

On non-NT versions of Windows, this will start `mysqld' in the
background. That is, after the server starts, you should see another
command prompt. If you start the server this way on Windows NT, 2000,
or XP, the server will run in the foreground and no command prompt will
appear until the server exits.  Because of this, you should open
another console window to run client programs while the server is
running.

You can stop the MySQL server by executing this command:

     shell> C:\mysql\bin\mysqladmin -u root shutdown

This invokes the MySQL administrative utility `mysqladmin' to connect
to the server and tell it to shut down. The command connects as `root',
which is the default administrative account in the MySQL grant system.
Please note that users in the MySQL grant system are wholly independent
from any login users under Windows.

If `mysqld' doesn't start, check the error log to see whether the
server wrote any messages there to indicate the cause of the problem.
The error log is located in the `C:\mysql\data' directory. It is the
file with a suffix of `.err'. You can also try to start the server as
`mysqld --console'; in this case, you may get some useful information
on the screen that may help solve the problem.

The last option is to start `mysqld' with `--standalone --debug'.  In
this case `mysqld' will write a log file `C:\mysqld.trace' that should
contain the reason why `mysqld' doesn't start. *Note Making trace
files::.

Use `mysqld --help' to display all the options that `mysqld'
understands!

Starting MySQL as a Windows Service
...................................

On the NT family (Windows NT, 2000, or XP), the recommended way to run
MySQL is to install it as a Windows service. Then Windows starts and
stops the MySQL server automatically when Windows starts and stops. A
server installed as a service can also be controlled from the command
line using `NET' commands, or with the graphical `Services' utility.

The `Services' utility (the Windows `Service Control Manager') can be
found in the Windows `Control Panel' (under `Administrative Tools' on
Windows 2000). It is advisable to close the `Services' utility while
performing server installation or removal operations from this command
line.  This prevents some odd errors.

To get MySQL to work with TCP/IP on Windows NT 4, you must install
service pack 3 (or newer)!

Before installing MySQL as a Windows service, you should first stop the
current server if it is running by using the following command:

     shell> C:\mysql\bin\mysqladmin -u root shutdown

This invokes the MySQL administrative utility `mysqladmin' to connect
to the server and tell it to shut down. The command connects as `root',
which is the default administrative account in the MySQL grant system.
Please note that users in the MySQL grant system are wholly independent
from any login users under Windows.

Now install the server as a service:

     shell> mysqld --install

If you have problems installing `mysqld' as a service using just the
server name, try installing it using its full pathname:

     shell> C:\mysql\bin\mysqld --install

As of MySQL 4.0.2, you can specify a specific service name after the
`--install' option.  As of MySQL 4.0.3, you can in addition specify a
`--defaults-file' option after the service name to indicate where the
server should obtain options when it starts. The rules that determine
the service name and option files the server uses are as follows:

   * If you specify no service name, the server uses the default
     service name of `MySQL' and the server reads options from the
     `[mysqld]' group in the standard option files.

   * If you specify a service name after the `--install' option, the
     server ignores the `[mysqld]' option group and instead reads
     options from the group that has the same name as the service. The
     server reads options from the standard option files.

   * If you specify a `--defaults-file' option after the service name,
     the server ignores the standard option files and reads options
     only from the `[mysqld]' group of the named file.


*Note:* Prior to MySQL 4.0.17, a server installed as a Windows service
has problems starting if its pathname or the service name contains
spaces. For this reason, avoid installing MySQL in a directory such as
`C:\Program Files' or using a service name containing spaces.

In the usual case that you install the server with `--install' but no
service name, the server is installed with a service name of `MySQL'.

As a more complex example, consider the following command (which should
be entered on a single line):

     shell> C:\mysql\bin\mysqld --install mysql
                --defaults-file=C:\my-opts.cnf

Here, a service name is given after the `--install' option. If no
`--defaults-file' option had been given, this command would have the
effect of causing the server to read the `[mysql]' group from the
standard option files. (This would be a bad idea, because that option
group is for use by the `mysql' client program.) However, because the
`--defaults-file' option is present, the server reads options only from
the named file, and only from the `[mysqld]' option group.

You can also specify options as "`Start parameters'" in the Windows
`Services' utility before you start the MySQL service.

Once a MySQL server is installed as a service, Windows will start the
service automatically whenever Windows starts.  The service also can be
started immediately from the `Services' utility, or by using the
command `NET START MySQL'.  The `NET' command is not case sensitive.

Please note that when run as a service, `mysqld' has no access to a
console window, so no messages can be seen there.  If `mysqld' doesn't
start, check the error log to see whether the server wrote any messages
there to indicate the cause of the problem.  The error log is located
in the `C:\mysql\data' directory. It is the file with a suffix of
`.err'.

When `mysqld' is running as a service, it can be stopped by using the
`Services' utility, the command `NET STOP MySQL', or the command
`mysqladmin shutdown'. If the service is running when Windows shuts
down, Windows will stop the server automatically.

From MySQL version 3.23.44, you have the choice of installing the
server as a `Manual' service if you don't wish the service to be
started automatically during the boot process. To do this, use the
`--install-manual' option rather than the `--install' option:

     shell> C:\mysql\bin\mysqld --install-manual

To remove a server that is installed as a service, first stop it if it
is running. Then use the `--remove' option to remove it:

     shell> mysqld --remove

For MySQL versions older than 3.23.49, one problem with automatic MySQL
service shutdown is that Windows waited only for a few seconds for the
shutdown to complete, then killed the database server process if the
time limit was exceeded. This had the potential to cause problems.
(For example, the `InnoDB' storage engine had to perform crash recovery
at the next startup.) Starting from MySQL version 3.23.49, Windows
waits longer for the MySQL server shutdown to complete. If you notice
this still is not enough for your installation, it is safest not to run
the MySQL server as a service. Instead, start it from the command-line
prompt, and stop it with `mysqladmin shutdown'.

This change to tell Windows to wait longer when stopping the MySQL
server works for Windows 2000 and XP. It does not work for Windows NT,
where Windows waits only 20 seconds for a service to shut down, and
after that kills the service process. You can increase this default by
opening the Registry Editor `\winnt\system32\regedt32.exe' and editing
the value of `WaitToKillServiceTimeout' at
`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control' in the Registry
tree. Specify the new larger value in milliseconds.  For example, the
value 120000 tells Windows NT to wait up to 120 seconds.

If you don't want to start `mysqld' as a service, you can start it from
the command line the same way as for versions of Windows that are not
based on NT.  For instructions, see *Note Win95 start::.

Running MySQL Client Programs on Windows
........................................

You can test whether the MySQL server is working by executing any of the
following commands:

     C:\> C:\mysql\bin\mysqlshow
     C:\> C:\mysql\bin\mysqlshow -u root mysql
     C:\> C:\mysql\bin\mysqladmin version status proc
     C:\> C:\mysql\bin\mysql test

If `mysqld' is slow to respond to TCP/IP connections from client
programs on Windows 9x/Me, there is probably a problem with your DNS.
In this case, start `mysqld' with the `--skip-name-resolve' option and
use only `localhost' and IP numbers in the `Host' column of the MySQL
grant tables.

You can force a MySQL client to use a named pipe connection rather than
TCP/IP  by specifying the `--pipe' option or by specifying `.' (period)
as the host name.  Use the `--socket' option to specify the name of the
pipe.  In MySQL 4.1, you should use the `--protocol=PIPE' option.

There are two versions of the MySQL command-line tool:
*Binary*       *Description*
`mysql'        Compiled on native Windows, offering limited text editing
               capabilities.
`mysqlc'       Compiled with the Cygnus GNU compiler and libraries,
               which offers `readline' editing.

If you want to use `mysqlc', you must have a copy of the
`cygwinb19.dll' library installed somewhere that `mysqlc' can find it.
Current distributions of MySQL include this library in the same
directory as `mysqlc' (the `bin' directory under the base directory of
your MySQL installation). If your distribution does not have the
`cygwinb19.dll' library in the `bin' directory, look for it in the
`lib' directory and copy it to your Windows system directory
(`\Windows\system' or similar place).

MySQL on Windows Compared to MySQL on Unix
..........................................

MySQL for Windows has by now proven itself to be very stable. The
Windows version of MySQL has the same features as the corresponding
Unix version, with the following exceptions:

*Windows 95 and threads*
     Windows 95 leaks about 200 bytes of main memory for each thread
     creation.  Each connection in MySQL creates a new thread, so you
     shouldn't run `mysqld' for an extended time on Windows 95 if your
     server handles many connections!  Other versions of Windows don't
     suffer from this bug.

*Concurrent reads*
     MySQL depends on the `pread()' and `pwrite()' calls to be able to
     mix `INSERT' and `SELECT'.  Currently we use mutexes to emulate
     `pread()'/`pwrite()'.  We will, in the long run, replace the file
     level interface with a virtual interface so that we can use the
     `readfile()'/`writefile()' interface on NT/2000/XP to get more
     speed.  The current implementation limits the number of open files
     MySQL can use to 1024, which means that you will not be able to
     run as many concurrent threads on NT/2000/XP as on Unix.

*Blocking read*
     MySQL uses a blocking read for each connection, which has the
     following implications:

        * A connection will not be disconnected automatically after 8
          hours, as happens with the Unix version of MySQL.

        * If a connection hangs, it's impossible to break it without
          killing MySQL.

        * `mysqladmin kill' will not work on a sleeping connection.

        * `mysqladmin shutdown' can't abort as long as there are
          sleeping connections.

     We plan to fix this problem when our Windows developers have
     figured out a nice workaround.

*`DROP DATABASE'*
     You can't drop a database that is in use by some thread.

*Killing MySQL from the task manager*
     You can't kill MySQL from the task manager or with the shutdown
     utility in Windows 95.  You must take it down with `mysqladmin
     shutdown'.

*Case-insensitive names*
     Filenames are not case sensitive on Windows, so MySQL database and
     table names are also not case sensitive on Windows.  The only
     restriction is that database and table names must be specified
     using the same case throughout a given statement.  *Note Name case
     sensitivity::.

*The `\' pathname separator character*
     Pathname components in Windows 95 are separated by the `\'
     character, which is also the escape character in MySQL.  If you
     are using `LOAD DATA INFILE' or `SELECT ... INTO OUTFILE', use
     Unix style filenames with `/' characters:

          mysql> LOAD DATA INFILE "C:/tmp/skr.txt" INTO TABLE skr;
          mysql> SELECT * INTO OUTFILE 'C:/tmp/skr.txt' FROM skr;

     Alternatively, you must double the `\' character:

          mysql> LOAD DATA INFILE "C:\\tmp\\skr.txt" INTO TABLE skr;
          mysql> SELECT * INTO OUTFILE 'C:\\tmp\\skr.txt' FROM skr;

*Problems with pipes.*
     Pipes doesn't work reliably in the Windows command-line prompt.
     If the pipe includes the character `^Z' / `CHAR(24)', Windows will
     think it has encountered end-of-file and abort the program.

     This is mainly a problem when you try to apply a binary log as
     follows:

          mysqlbinlog binary-log-name | mysql --user=root

     If you get a problem applying the log and suspect it's because of
     an `^Z' / `CHAR(24)' character you can use the following
     workaround:

          mysqlbinlog binary-log-file --result-file=/tmp/bin.sql
          mysql --user=root --execute "source /tmp/bin.sql"

     The latter command also can be used to reliably read in any SQL
     file that may contain binary data.

*`Can't open named pipe' error*
     If you use a MySQL Version 3.22 server on NT with the newest MySQL
     client programs, you will get the following error:

          error 2017: can't open named pipe to host: . pipe...

     This is because the release version of MySQL uses named pipes on NT
     by default.  You can avoid this error by using the
     `--host=localhost' option to the new MySQL clients or create an
     option file `C:\my.cnf' that contains the following information:

          [client]
          host = localhost

     Starting from 3.23.50, named pipes are enabled only if `mysqld-nt'
     or `mysqld-max-nt' is started with `--enable-named-pipe'.

*`Access denied for user' error*
     If you attempt to run a MySQL client program to connect to a server
     running on the same machine, but get the error `Access denied for
     user: 'some-user@unknown' to database 'mysql'', this means that
     MySQL can't resolve your hostname properly.

     To fix this, you should create a file `\windows\hosts' with the
     following information:

          127.0.0.1       localhost

*`ALTER TABLE'*
     While you are executing an `ALTER TABLE' statement, the table is
     locked from being used by other threads.  This has to do with the
     fact that on Windows, you can't delete a file that is in use by
     another threads.  In the future, we may find some way to work
     around this problem.

*`DROP TABLE'*
     `DROP TABLE' on a table that is in use by a `MERGE' table will not
     work on Windows because the `MERGE' handler does the table mapping
     hidden from the upper layer of MySQL.  Because Windows doesn't
     allow you to drop files that are open, you first must flush all
     `MERGE' tables (with `FLUSH TABLES') or drop the `MERGE' table
     before dropping the table.  We will fix this at the same time we
     introduce views.

*`DATA DIRECTORY' and `INDEX DIRECTORY'*
     The `DATA DIRECTORY' and `INDEX DIRECTORY' options for `CREATE
     TABLE' are ignored on Windows, because Windows doesn't support
     symbolic links.  These options also are ignored on systems that
     have a non-functional `realpath()' call.

Here are some open issues for anyone who might want to help us improve
MySQL on Windows:

   * Add some nice start and shutdown icons to the MySQL installation.

   * It would be really nice to be able to kill `mysqld' from the task
     manager.  For the moment, you must use `mysqladmin shutdown'.

   * Port `readline' to Windows for use in the `mysql' command-line
     tool.

   * GUI versions of the standard MySQL clients (`mysql', `mysqlshow',
     `mysqladmin', and `mysqldump') would be nice.

   * It would be nice if the socket read and write functions in `net.c'
     were interruptible. This would make it possible to kill open
     threads with `mysqladmin kill' on Windows.

   * Add macros to use the faster thread-safe increment/decrement
     methods provided by Windows.

Installing MySQL on Linux
-------------------------

The recommended way to install MySQL on Linux is by using the RPM
packages. The MySQL RPMs are currently built on a SuSE Linux 7.3 system
but should work on most versions of Linux that support `rpm' and use
`glibc'.

If you have problems with an RPM file (for example, if you receive the
error "`Sorry, the host 'xxxx' could not be looked up'"), see *Note
Binary notes-Linux::.

In most cases, you only need to install the `MySQL-server' and
`MySQL-client' packages to get a functional MySQL installation. The
other packages are not required for a standard installation.  If you
want to run a MySQL-Max server that has additional capabilities, you
should install the `MySQL-Max' RPM. However, you should do so only _
after_ installing the `MySQL-server' RPM.  *Note `mysqld-max':
mysqld-max.

If you get a dependency failure when trying to install the MySQL 4.0
packages (for example, "`error: removing these packages would break
dependencies: libmysqlclient.so.10 is needed by ...'"), you should also
install the package `MySQL-shared-compat', which includes both the
shared libraries for backward compatibility (`libmysqlclient.so.12' for
MySQL 4.0 and `libmysqlclient.so.10' for MySQL 3.23).

Many Linux distributions still ship with MySQL 3.23 and they usually
link applications dynamically to save disk space. If these shared
libraries are in a separate package (for example, `MySQL-shared'), it is
sufficient to simply leave this package installed and just upgrade the
MySQL server and client packages (which are statically linked and do
not depend on the shared libraries). For distributions that include the
shared libraries in the same package as the MySQL server (for example,
Red Hat Linux), you could either install our 3.23 `MySQL-shared' RPM,
or use the `MySQL-shared-compat' package instead.

The following RPM packages are available:

   * `MySQL-server-VERSION.i386.rpm'

     The MySQL server.  You will need this unless you only want to
     connect to a MySQL server running on another machine. Please note:
     Server RPM files were called `MySQL-VERSION.i386.rpm' before MySQL
     4.0.10. That is, they did not have `-server' in the name.

   * `MySQL-Max-VERSION.i386.rpm'

     The MySQL-Max server. This server has additional capabilities that
     the one provided in the `MySQL-server' RPM does not.  You must
     install the `MySQL-server' RPM first, because the `MySQL-Max' RPM
     depends on it.

   * `MySQL-client-VERSION.i386.rpm'

     The standard MySQL client programs. You probably always want to
     install this package.

   * `MySQL-bench-VERSION.i386.rpm'

     Tests and benchmarks. Requires Perl and the `DBD::mysql' module.

   * `MySQL-devel-VERSION.i386.rpm'

     The libraries and include files that are needed if you want to
     compile other MySQL clients, such as the Perl modules.

   * `MySQL-shared-VERSION.i386.rpm'

     This package contains the shared libraries (`libmysqlclient.so*')
     that certain languages and applications need to dynamically load
     and use MySQL.

   * `MySQL-shared-compat-VERSION.i386.rpm'

     This package includes the shared libraries for both MySQL 3.23 and
     MySQL 4.0. Install this package instead of `MySQL-shared', if you
     have applications installed that are dynamically linked against
     MySQL 3.23 but you want to upgrade to MySQL 4.0 without breaking
     the library dependencies. This package is available since MySQL
     4.0.13.

   * `MySQL-embedded-VERSION.i386.rpm'

     The embedded MySQL server library (from MySQL 4.0).

   * `MySQL-VERSION.src.rpm'

     This contains the source code for all of the previous packages. It
     can also be used to rebuild the RPMs on other architectures (for
     example, Alpha or SPARC).

To see all files in an RPM package (for example, a `MySQL-server' RPM),
run:

     shell> rpm -qpl MySQL-server-VERSION.i386.rpm

To perform a standard minimal installation, run:

     shell> rpm -i MySQL-server-VERSION.i386.rpm
     shell> rpm -i MySQL-client-VERSION.i386.rpm

To install just the client package, run:

     shell> rpm -i MySQL-client-VERSION.i386.rpm

RPM provides a feature to verify the integrity and authenticity of
packages before installing them. If you would like to learn more about
this feature please see *Note Verifying Package Integrity::.

The server RPM places data under the `/var/lib/mysql' directory. The
RPM also creates the appropriate entries in `/etc/init.d/' to start the
server automatically at boot time. (This means that if you have
performed a previous installation and have made changes to its startup
script, you may want to make a copy of the script so you don't lose it
when you install a newer RPM.) See *Note Automatic start:: for more
information on how MySQL can be started automatically on system startup.

If you want to install the MySQL RPM on older Linux distributions that
do not support initialization scripts in `/etc/init.d' (directly or via
a symlink), you should create a symbolic link that points to the
location where your initialization scripts actually are installed. For
example, if that location is `/etc/rc.d/init.d', use these commands
before installing the RPM to create `/etc/init.d' as a symbolic link
that points there:

     shell> cd /etc; ln -s rc.d/init.d .

However, all current major Linux distributions should already support
the new directory layout that uses `/etc/init.d', because it is
required for LSB (Linux Standard Base) compliance.

If the RPM files that you install include `MySQL-server', the `mysqld'
server should be up and running after installation.  You should now be
able to start using MySQL.  *Note Post-installation::.

If something goes wrong, you can find more information in the binary
installation chapter. *Note Installing binary::.

Installing MySQL on Mac OS X
----------------------------

Beginning with MySQL 4.0.11, you can install MySQL on Mac OS X 10.2
("Jaguar") using a Mac OS X binary package in `PKG' format instead of
the binary tarball distribution. Please note that older versions of Mac
OS X (for example, 10.1.x) are not supported by this package.

The package is located inside a disk image (`.dmg') file, that you
first need to mount by double-clicking its icon in the Finder. It should
then mount the image and display its contents.

*NOTE*: Before proceeding with the installation, be sure to shut down
all running MySQL server instances by either using the MySQL Manager
Application (on Mac OS X Server) or via `mysqladmin shutdown' on the
command line.

To actually install the MySQL PKG file, double click on the package
icon. This launches the Mac OS X Package Installer, which will guide
you through the installation of MySQL.

Due to a bug in the Mac OS X package installer, you may sometimes see
the error message `You cannot install this software on this disk.
(null)' in the destination disk selection dialogue. If this error
occurs, simply click the `Go Back' button once to return to the
previous screen. Then click `Continue' to advance to the destination
disk selection again, and you should be able to choose the destination
disk correctly. We have reported this bug to Apple and they are
investigating this problem.

The Mac OS X PKG of MySQL will install itself into
`/usr/local/mysql-<version>' and will also install a symbolic link
`/usr/local/mysql', pointing to the new location. If a directory named
`/usr/local/mysql' already exists, it will be renamed to
`/usr/local/mysql.bak' first. Additionally, it will install the grant
tables in the `mysql' database by executing `mysql_install_db' after
the installation.

The installation layout is similar to the one of the binary
distribution; all MySQL binaries are located in the directory
`/usr/local/mysql/bin'.  The MySQL socket file is created as
`/tmp/mysql.sock' by default.  *Note Installation layouts::.

MySQL installation requires a Mac OS X user account named `mysql' (a
user account with this name should exist by default on Mac OS X 10.2
and up).

If you are running Mac OS X Server, you already have a version of MySQL
installed.  The versions of MySQL that ship with Mac OS X Server
versions are shown in the following table:

*Mac OS X Server       *MySQL Version*
Version*
10.2-10.2.2            3.23.51
10.2.3-10.2.6          3.23.53
10.3                   4.0.14
10.3.2                 4.0.16

This manual section covers the installation of the official MySQL Mac
OS X PKG only.  Make sure to read Apple's help about installing MySQL
(Run the "Help View" application, select "Mac OS X Server" help, and do
a search for "MySQL" and read the item entitled "Installing MySQL").

Especially note that for pre-installed versions of MySQL on Mac OS X
Server, you should start `mysqld' with `safe_mysqld' instead of
`mysqld_safe' if the MySQL is older than version 4.0.

If you previously used Marc Liyanage's MySQL packages for Mac OS X from
`http://www.entropy.ch', you can simply follow the update instructions
for packages using the binary installation layout as given on his pages.

If you are upgrading from Marc's 3.23.xx versions or from the Mac OS X
Server version of MySQL to the official MySQL PKG, you also need to
convert the existing MySQL privilege tables to the current format,
because some new security privileges have been added.  *Note
Upgrading-grant-tables::.

If you would like to automatically start up MySQL during system bootup,
you also need to install the MySQL Startup Item. Starting with MySQL
4.0.15, it is part of the Mac OS X installation disk images as a
separate installation package. Simply double-click the
`MySQLStartupItem.pkg' icon and follow the instructions to install it.

Note that the Startup Item need be installed only once! There is no
need to install it each time you upgrade the MySQL package later.

The Startup Item will be installed into `/Library/StartupItems/MySQL'.
It adds a variable `MYSQLCOM=-YES-' to the system configuration file
`/etc/hostconfig'. If you would like to disable the automatic startup
of MySQL, simply change this variable to `MYSQLCOM=-NO-'.

On Mac OS X Server, the default MySQL installation uses the variable
`MYSQL' in `/etc/hostconfig'.  The MySQL AB Startup Item installer
disables this variable by setting it to `MYSQL=-NO-'. This avoids boot
time conflicts with the `MYSQLCOM' variable used by the MySQL AB
Startup Item.  However, it does not shut down an already running MySQL
server.

After the installation, you can start up MySQL by running the following
commands in a terminal window. Please note that you must have
administrator privileges to perform this task.

If you have installed the Startup Item:

     shell> sudo /Library/StartupItems/MySQL/MySQL start
     (Enter your password, if necessary)
     (Press Control-D or enter "exit" to exit the shell)

If you don't use the Startup Item, enter the following command sequence:

     shell> cd /usr/local/mysql
     shell> sudo ./bin/mysqld_safe
     (Enter your password, if necessary)
     (Press Control-Z)
     shell> bg
     (Press Control-D or enter "exit" to exit the shell)

You should now be able to connect to the MySQL server, for example, by
running `/usr/local/mysql/bin/mysql'.

If you are installing MySQL for the first time, *please remember to set
a password for the MySQL `root' user!*

This is done with the following two commands:

     /usr/local/mysql/bin/mysqladmin -u root password <password>
     /usr/local/mysql/bin/mysqladmin -u root -h `hostname` password <password>

Please make sure that the `hostname' command in the second line is
enclosed by *backtick* characters (``'), so the shell can replace it
with the output of the command (which is the hostname of your system)!

You might want to also add aliases to your shell's resource file to
access `mysql' and `mysqladmin' from the command line. The syntax for
`tcsh' is:

     alias mysql /usr/local/mysql/bin/mysql
     alias mysqladmin /usr/local/mysql/bin/mysqladmin

For `bash', use:

     alias mysql=/usr/local/mysql/bin/mysql
     alias mysqladmin=/usr/local/mysql/bin/mysqladmin

Even better, add `/usr/local/mysql/bin' to your `PATH' environment
variable. For example, add the following line to your `$HOME/.tcshrc'
file if your shell is `tcsh':

     setenv PATH ${PATH}:/usr/local/mysql/bin

If no `.tcshrc' file exists in your home directory, create it with a
text editor.

If you are upgrading an existing installation, please note that
installing a new MySQL PKG does not remove the directory of an older
installation. Unfortunately, the Mac OS X Installer does not yet offer
the functionality required to properly upgrade previously installed
packages.

To use your existing databases with the new installation, you'll need
to copy the contents of the old data directory to the new data
directory. Make sure neither the old server nor the new one is running
when you do this.  After you have copied over the MySQL database files
from the previous installation and have successfully started the new
server, you should consider removing the old installation files to save
disk space.  Additionally, you should also remove older versions of the
Package Receipt directories located in
`/Library/Receipts/mysql-<version>.pkg'.

Installing MySQL on NetWare
---------------------------

Porting `MySQL' to `NetWare' was an effort spearheaded by `Novell'.
Novell customers will be pleased to note that NetWare 6.5 will ship
with bundled MySQL binaries, complete with an automatic commercial use
license for all servers running that version of NetWare.

As of version 4.0.11, the MySQL server is available for Novell NetWare
in binary package form.  MySQL for NetWare is compiled using a
combination of `Metrowerks CodeWarrior for NetWare' and special
cross-compilation versions of the GNU autotools.

In order to host MySQL, the NetWare server must meet these requirements:

   * NetWare version 6.5, or NetWare 6.0 with Support Pack 3 installed
     (You can obtain this at
     `http://support.novell.com/filefinder/13659/index.html').  The
     system must meet Novell's minimum requirements to run the
     respective version of NetWare.

   * MySQL data, as well as the binaries themselves, must be installed
     on an NSS volume; traditional volumes are not supported.

The binary package for NetWare can be obtained at
`http://www.mysql.com/downloads/'.

To install MySQL for NetWare, use the following procedure:

  1. If you are upgrading from a prior installation, stop the MySQL
     server.  This is done from the server console, using the following
     command:

          SERVER:  mysqladmin -u root shutdown

  2. Log on to the target server from a client machine with access to
     the location where you will install MySQL.

  3. Extract the binary package zip file onto the server. Be sure to
     allow the paths in the zip file to be used. It is safe to simply
     extract the file to `SYS:\'.

     If you are upgrading from a prior installation, you may need to
     copy the data directory (for example, `SYS:MYSQL\DATA') now, as
     well as `my.cnf' if you have customized it. You can then delete
     the old copy of MySQL.

  4. You may wish to rename the directory to something more consistent
     and easy to use. We recommend using `SYS:MYSQL'; examples in the
     manual will use this to refer to the installation directory in
     general.

  5. At the server console, add a search path for the directory
     containing the MySQL NLMs. For example:

          SERVER:  SEARCH ADD SYS:MYSQL\BIN

  6. Install the initial database, if needed, by executing
     `mysql_install_db' at the server console.

  7. Start the MySQL server using `mysqld_safe' at the server console.

  8. To finish the installation, you should also add the following
     commands to `autoexec.ncf'. For example, if your MySQL
     installation is in `SYS:MYSQL' and you want MySQL to start
     automatically, you could add these lines:

          #Starts the MySQL 4.0.x database server
          SEARCH ADD SYS:MYSQL\BIN
          MYSQLD_SAFE

     If you are running MySQL on NetWare 6.0, we strongly suggest that
     you use the `--skip-external-locking' option on the command line:

          #Starts the MySQL 4.0.x database server
          SEARCH ADD SYS:MYSQL\BIN
          MYSQLD_SAFE --skip-external-locking

     It will also be neccesary to use `CHECK TABLE' and `REPAIR TABLE'
     instead of `myisamchk', because `myisamchk' makes use of external
     locking.  External locking is known to have problems on NetWare
     6.0; the problem has been eliminated in NetWare 6.5.


If there was an existing installation of MySQL on the server, be sure
to check for existing MySQL startup commands in `autoexec.ncf', and
edit or delete them as necessary.

Installing MySQL on HP-UX
-------------------------

Binary distributions of MySQL for HP-UX are distributed as HP depot
files or as `tar' files.  To use the depot file you must be running at
least HP-UX 10.x to have access to HP's software depot tools.  To
install the HP-UX `tar.gz' distribution, you must have a copy of GNU
`tar'.

The HP version of MySQL was compiled on an HP 9000/8xx server under
HP-UX 10.20, and uses MIT-pthreads.  It is known to work well under
this configuration.  MySQL Version 3.22.26 and newer can also be built
with HP's native thread package.

Other configurations that may work:

   * HP 9000/7xx running HP-UX 10.20+

   * HP 9000/8xx running HP-UX 10.30

The following configurations almost definitely won't work:

   * HP 9000/7xx or 8xx running HP-UX 10.x where x < 2

   * HP 9000/7xx or 8xx running HP-UX 9.x

To install the distribution, use one of the commands here, where
`/path/to/depot' is the full pathname of the depot file:

   * To install everything, including the server, client and
     development tools:

          shell> /usr/sbin/swinstall -s /path/to/depot mysql.full

   * To install only the server:

          shell> /usr/sbin/swinstall -s /path/to/depot mysql.server

   * To install only the client package:

          shell> /usr/sbin/swinstall -s /path/to/depot mysql.client

   * To install only the development tools:

          shell> /usr/sbin/swinstall -s /path/to/depot mysql.developer

The depot places binaries and libraries in `/opt/mysql' and data in
`/var/opt/mysql'. The depot also creates the appropriate entries in
`/etc/init.d' and `/etc/rc2.d' to start the server automatically at
boot time.  Obviously, this entails being `root' to install.

Installing MySQL on Other Unix-like Systems
-------------------------------------------

This section covers the installation of MySQL binary distributions that
are provided for various platforms in the form of `tar' files (files
with a `.tar.gz' extension).  See *Note MySQL binaries:: for a detailed
list.

In addition to these generic packages, we also offer binaries in
platform-specific package formats for selected platforms.  See *Note
Quick Standard Installation:: for more information on how to install
these.

You need the following tools to install a MySQL `tar' file binary
distribution:

   * GNU `gunzip' to uncompress the distribution.

   * A reasonable `tar' to unpack the distribution. GNU `tar' is known
     to work. Some operating systems come with a pre-installed version
     of `tar' that is known to have problems.  For example, Sun `tar'
     and Mac OS X `tar' are known to have problems with long filenames.
     In such cases, you should install GNU `tar' first.  On Mac OS X,
     you can use the pre-installed `gnutar' program.

If you run into problems, *please always use `mysqlbug'* when posting
questions to a MySQL mailing list.  Even if the problem isn't a bug,
`mysqlbug' gathers system information that will help others solve your
problem.  By not using `mysqlbug', you lessen the likelihood of getting
a solution to your problem.  You will find `mysqlbug' in the `bin'
directory after you unpack the distribution.  *Note Bug reports::.

The basic commands you must execute to install and use a MySQL binary
distribution are:

     shell> groupadd mysql
     shell> useradd -g mysql mysql
     shell> cd /usr/local
     shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf -
     shell> ln -s full-path-to-mysql-VERSION-OS mysql
     shell> cd mysql
     shell> scripts/mysql_install_db
     shell> chown -R root  .
     shell> chown -R mysql data
     shell> chgrp -R mysql .
     shell> bin/mysqld_safe --user=mysql &

For versions of MySQL older than 4.0, substitute `bin/safe_mysqld' for
`bin/mysqld_safe' in the final command.

A more detailed description follows.

To install a binary distribution, follow these steps, then proceed to
*Note Post-installation::, for post-installation setup and testing:

  1. Add a user and group for `mysqld' to run as:

          shell> groupadd mysql
          shell> useradd -g mysql mysql

     These commands add the `mysql' group and the `mysql' user.  The
     syntax for `useradd' and `groupadd' may differ slightly on
     different versions of Unix.  They may also be called `adduser' and
     `addgroup'.  You may wish to call the user and group something
     else instead of `mysql'.

  2. Pick the directory under which you want to unpack the
     distribution, and move into it. In the following example, we
     unpack the distribution under `/usr/local' (The following
     instructions, therefore, assume you have permission to create
     files and directories in `/usr/local'.  If that directory is
     protected, you will need to perform the installation as `root'.)

  3. Obtain a distribution file from one of the sites listed in *Note
     Getting MySQL: Getting MySQL.

     MySQL `tar' file binary distributions have names like
     `mysql-VERSION-OS.tar.gz', where `VERSION' is a number (for
     example, `4.0.17'), and `OS' indicates the type of operating
     system for which the distribution is intended (for example,
     `pc-linux-gnu-i586').  For a given release, binary distributions
     for all platforms are built from the same MySQL source
     distribution.

  4. Change into the intended installation directory:

          shell> cd /usr/local

  5. Unpack the distribution, which will create the installation
     directory.  Then create a symbolic link to that directory:

          shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf -
          shell> ln -s full-path-to-mysql-VERSION-OS mysql

     The `tar' command creates a directory named `mysql-VERSION-OS'.
     The `ln' command makes a symbolic link to that directory.  This
     lets you refer more easily to the installation directory as
     `/usr/local/mysql'.

     With GNU `tar', no separate invocation of `gunzip' is necessary.
     You can replace the first line with the following alternative
     command to uncompress and extract the distribution:

          shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz

  6. Change into the installation directory:

          shell> cd mysql

     You will find several files and subdirectories in the `mysql'
     directory.  The most important for installation purposes are the
     `bin' and `scripts' subdirectories.

    `bin'
          This directory contains client programs and the server.  You
          should add the full pathname of this directory to your `PATH'
          environment variable so that your shell finds the MySQL
          programs properly. *Note Environment variables::.

    `scripts'
          This directory contains the `mysql_install_db' script used to
          initialize the `mysql' database containing the grant tables
          that store the server access permissions.

  7. If you haven't installed MySQL before, you must create the MySQL
     grant tables:

          shell> scripts/mysql_install_db

     Note that for MySQL versions older than Version 3.22.10,
     `mysql_install_db' left the server running after creating the grant
     tables.  This is no longer true; you will need to restart the
     server after performing the remaining steps in this procedure.

  8. Change ownership of program binaries to `root' and ownership of
     the data directory to the user that you will run `mysqld' as.
     Assuming that you are located in the installation directory
     (`/usr/local/mysql'), the commands look like this:

          shell> chown -R root  .
          shell> chown -R mysql data
          shell> chgrp -R mysql .

     The first command changes the `owner' attribute of the files to the
     `root' user. The second changes the `owner' attribute of the data
     directory to the `mysql' user. The third changes the `group'
     attribute to the `mysql' group.

  9. If you would like MySQL to start automatically when you boot your
     machine, you can copy `support-files/mysql.server' to the location
     where your system has its startup files.  More information can be
     found in the `support-files/mysql.server' script itself and in
     *Note Automatic start::.

 10. You can set up new accounts using the `bin/mysql_setpermission'
     script if you install the `DBI' and `DBD::mysql' Perl modules.
     For instructions, see *Note Perl support::.

 11. If you would like to use `mysqlaccess' and have the MySQL
     distribution in some non-standard place, you must change the
     location where `mysqlaccess' expects to find the `mysql' client.
     Edit the `bin/mysqlaccess' script at approximately line 18.
     Search for a line that looks like this:

          $MYSQL     = '/usr/local/bin/mysql';    # path to mysql executable

     Change the path to reflect the location where `mysql' actually is
     stored on your system.  If you do not do this, you will get a
     `Broken pipe' error when you run `mysqlaccess'.


After everything has been unpacked and installed, you should test your
distribution.

You can start the MySQL server with the following command:

     shell> bin/mysqld_safe --user=mysql &

For versions of MySQL older than 4.0, substitute `bin/safe_mysqld' for
`bin/mysqld_safe' in the command.

Now proceed to *Note `mysqld_safe': mysqld_safe, and *Note
Post-installation::.

MySQL Installation Using a Source Distribution
==============================================

Before you proceed with the source installation, check first to see
whether our binary is available for your platform and whether it will
work for you. We put a lot of effort into making sure that our binaries
are built with the best possible options.

You need the following tools to build and install MySQL from source:

   * GNU `gunzip' to uncompress the distribution.

   * A reasonable `tar' to unpack the distribution. GNU `tar' is known
     to work. Some `tar' implementations that come pre-installed with
     the operating system (for example, Sun `tar') is known to have
     problems with long file names). In that case, you should install
     GNU `tar' first.

   * A working ANSI C++ compiler.  `gcc' 2.95.2 or later, `egcs' 1.0.2
     or later or `egcs 2.91.66', SGI C++, and SunPro C++ are some of the
     compilers that are known to work.  `libg++' is not needed when
     using `gcc'.  `gcc' 2.7.x has a bug that makes it impossible to
     compile some perfectly legal C++ files, such as `sql/sql_base.cc'.
     If you only have `gcc' 2.7.x, you must upgrade your `gcc' to be
     able to compile MySQL. `gcc' 2.8.1 is also known to have problems
     on some platforms, so it should be avoided if a new compiler
     exists for the platform.

     `gcc' 2.95.2 or later is recommended when compiling MySQL Version
     3.23.x.

   * A good `make' program.  GNU `make' is always recommended and is
     sometimes required.  If you have problems, we recommend trying GNU
     `make' 3.75 or newer.

If you are using a recent version of `gcc', recent enough to understand
the `-fno-exceptions' option, it is *very important* that you use it.
Otherwise, you may compile a binary that crashes randomly. We also
recommend that you use `-felide-constructors' and `-fno-rtti' along
with `-fno-exceptions'. When in doubt, do the following:


     CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors \
            -fno-exceptions -fno-rtti" ./configure \
            --prefix=/usr/local/mysql --enable-assembler \
            --with-mysqld-ldflags=-all-static

On most systems this will give you a fast and stable binary.

If you run into problems, *please always use `mysqlbug'* when posting
questions to a MySQL mailing list.  Even if the problem isn't a bug,
`mysqlbug' gathers system information that will help others solve your
problem.  By not using `mysqlbug', you lessen the likelihood of getting
a solution to your problem.  You will find `mysqlbug' in the `scripts'
directory after you unpack the distribution.  *Note Bug reports::.

Quick Source Installation Overview
----------------------------------

The basic commands you must execute to install a MySQL source
distribution are:

     shell> groupadd mysql
     shell> useradd -g mysql mysql
     shell> gunzip < mysql-VERSION.tar.gz | tar -xvf -
     shell> cd mysql-VERSION
     shell> ./configure --prefix=/usr/local/mysql
     shell> make
     shell> make install
     shell> cp support-files/my-medium.cnf /etc/my.cnf
     shell> cd /usr/local/mysql
     shell> bin/mysql_install_db
     shell> chown -R root  .
     shell> chown -R mysql var
     shell> chgrp -R mysql .
     shell> bin/mysqld_safe --user=mysql &

For versions of MySQL older than 4.0, substitute `bin/safe_mysqld' for
`bin/mysqld_safe' in the final command.

If you start from a source RPM, do the following:

     shell> rpm --rebuild --clean MySQL-VERSION.src.rpm

This will make a binary RPM that you can install.

A more detailed description follows.

To install a source distribution, follow these steps, then proceed to
*Note Post-installation::, for post-installation initialization and
testing:

  1. Add a user and group for `mysqld' to run as:

          shell> groupadd mysql
          shell> useradd -g mysql mysql

     These commands add the `mysql' group and the `mysql' user.  The
     syntax for `useradd' and `groupadd' may differ slightly on
     different versions of Unix.  They may also be called `adduser' and
     `addgroup'.  You may wish to call the user and group something
     else instead of `mysql'.

  2. Pick the directory under which you want to unpack the
     distribution, and move into it.

  3. Obtain a distribution file from one of the sites listed in *Note
     Getting MySQL: Getting MySQL.  MySQL source distributions are
     provided as compressed `tar' archives and have names like
     `mysql-VERSION.tar.gz', where `VERSION' is a number like
     `4.0.18'.

  4. Unpack the distribution into the current directory:
          shell> gunzip < /path/to/mysql-VERSION.tar.gz | tar xvf -

     This command creates a directory named `mysql-VERSION'.

     With GNU `tar', no separate invocation of `gunzip' is necessary.
     You can use the following alternative command to uncompress and
     extract the distribution:

          shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz

  5. Change into the top-level directory of the unpacked distribution:

          shell> cd mysql-VERSION

     Note that currently you must configure and build MySQL from this
     top-level directory.  You cannot build it in a different directory.

  6. Configure the release and compile everything:

          shell> ./configure --prefix=/usr/local/mysql
          shell> make

     When you run `configure', you might want to specify some options.
     Run `./configure --help' for a list of options.  *Note `configure'
     options: configure options, discusses some of the more useful
     options.

     If `configure' fails and you are going to send mail to a MySQL
     mailing list to ask for assistance, please include any lines from
     `config.log' that you think can help solve the problem.  Also
     include the last couple of lines of output from `configure'.  Post
     the bug report using the `mysqlbug' script.  *Note Bug reports::.

     If the compile fails, see *Note Compilation problems::, for help
     with a number of common problems.

  7. Install the distribution:

          shell> make install

     If you want to set up an option file, use one of those present in
     the `support-files' directory as template. For example:

          shell> cp support-files/my-medium.cnf /etc/my.cnf

     You might need to run these commands as `root'.

     If you want to configure support for `InnoDB' tables, you should
     edit the `/etc/my.cnf' file, remove the `#' character before the
     option lines that start with `innodb_...', and modify the option
     values to be what you want.  *Note Option files::, and *Note
     InnoDB start::.

  8. Change location into the installation directory:

          shell> cd /usr/local/mysql

  9. If you haven't installed MySQL before, you must create the MySQL
     grant tables:

          shell> bin/mysql_install_db

     Note that for MySQL versions older than Version 3.22.10,
     `mysql_install_db' left the server running after creating the grant
     tables.  This is no longer true; you will need to restart the
     server after performing the remaining steps in this procedure.

 10. Change ownership of binaries to `root' and ownership of the data
     directory to the user that you will run `mysqld' as.  Assuming
     that you are located in the installation directory
     (`/usr/local/mysql'), the commands look like this:

          shell> chown -R root  .
          shell> chown -R mysql var
          shell> chgrp -R mysql .

     The first command changes the `owner' attribute of the files to the
     `root' user. The second changes the `owner' attribute of the data
     directory to the `mysql' user. The third changes the `group'
     attribute to the `mysql' group.

 11. If you would like MySQL to start automatically when you boot your
     machine, you can copy `support-files/mysql.server' to the location
     where your system has its startup files.  More information can be
     found in the `support-files/mysql.server' script itself and in
     *Note Automatic start::.

 12. You can set up new accounts using the `bin/mysql_setpermission'
     script if you install the `DBI' and `DBD::mysql' Perl modules.
     For instructions, see *Note Perl support::.


After everything has been installed, you should initialize and test your
distribution using this command:

     shell> /usr/local/mysql/bin/mysqld_safe --user=mysql &

For versions of MySQL older than 4.0, substitute `bin/safe_mysqld' for
`bin/mysqld_safe' in the command.

If that command fails immediately and prints `mysqld ended', you can
find some information in the file `mysql-data-directory/'hostname'.err'.
The likely reason is that you already have another `mysqld' server
running.  *Note Multiple servers::.

Now proceed to *Note Post-installation::.

Typical `configure' Options
---------------------------

The `configure' script gives you a great deal of control over how you
configure a MySQL source distribution.  Typically you do this using
options on the `configure' command-line.  You can also affect
`configure' using certain environment variables.  *Note Environment
variables::.  For a list of options supported by `configure', run this
command:

     shell> ./configure --help

Some of the more commonly used `configure' options are described here:

   * To compile just the MySQL client libraries and client programs and
     not the server, use the `--without-server' option:

          shell> ./configure --without-server

     If you don't have a C++ compiler, `mysql' will not compile (it is
     the one client program that requires C++).  In this case, you can
     remove the code in `configure' that tests for the C++ compiler and
     then run `./configure' with the `--without-server' option. The
     compile step will still try to build `mysql', but you can ignore
     any warnings about `mysql.cc'.  (If `make' stops, try `make -k' to
     tell it to continue with the rest of the build even if errors
     occur.)

   * If you want to get an embedded MySQL library (`libmysqld.a') you
     should use the `--with-embedded-server' option.

   * If you don't want your log files and database directories located
     under `/usr/local/var', use a `configure' command, something like
     one of these:

          shell> ./configure --prefix=/usr/local/mysql
          shell> ./configure --prefix=/usr/local \
                     --localstatedir=/usr/local/mysql/data

     The first command changes the installation prefix so that
     everything is installed under `/usr/local/mysql' rather than the
     default of `/usr/local'.  The second command preserves the default
     installation prefix, but overrides the default location for
     database directories (normally `/usr/local/var') and changes it to
     `/usr/local/mysql/data'.  After you have compiled MySQL, you can
     change these options with option files. *Note Option files::.

   * If you are using Unix and you want the MySQL socket located
     somewhere other than the default location (normally in the
     directory `/tmp' or `/var/run') use a `configure' command like
     this:

          shell> ./configure \
                     --with-unix-socket-path=/usr/local/mysql/tmp/mysql.sock

     Note that the given file must be an absolute pathname.  You can
     also later change the location of `mysql.sock' by using a MySQL
     option file. *Note Problems with `mysql.sock': Problems with
     mysql.sock.

   * If you want to compile statically linked programs (for example, to
     make a binary distribution, to get more speed, or to work around
     problems with some Red Hat Linux distributions), run `configure'
     like this:

          shell> ./configure --with-client-ldflags=-all-static \
                     --with-mysqld-ldflags=-all-static

   * If you are using `gcc' and don't have `libg++' or `libstdc++'
     installed, you can tell `configure' to use `gcc' as your C++
     compiler:

          shell> CC=gcc CXX=gcc ./configure

     When you use `gcc' as your C++ compiler, it will not attempt to
     link in `libg++' or `libstdc++'.  This may be a good idea to do
     even if you have the above libraries installed, as some versions
     of these libraries have caused strange problems for MySQL users in
     the past.

     The following list indicates some compilers and environment
     variable settings that are commonly used with each one.



    `gcc' 2.7.2:
          `CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors"'

    `egcs' 1.0.3a:
          `CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors \
          -fno-exceptions -fno-rtti"'

    `gcc' 2.95.2:
          `CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro
          \ -felide-constructors -fno-exceptions -fno-rtti"'

    `pgcc' 2.90.29 or newer:
          `CFLAGS="-O3 -mpentiumpro -mstack-align-double" CXX=gcc \
          CXXFLAGS="-O3 -mpentiumpro -mstack-align-double \
          -felide-constructors -fno-exceptions -fno-rtti"'

     In most cases you can get a reasonably optimal MySQL binary by
     using the options from the preceding list and adding the following
     options to the `configure' line:

          --prefix=/usr/local/mysql --enable-assembler \
          --with-mysqld-ldflags=-all-static

     The full `configure' line would, in other words, be something like
     the following for all recent `gcc' versions:

          CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
          -felide-constructors -fno-exceptions -fno-rtti" ./configure \
          --prefix=/usr/local/mysql --enable-assembler \
          --with-mysqld-ldflags=-all-static

     The binaries we provide on the MySQL web site at
     `http://www.mysql.com/' are all compiled with full optimization and
     should be perfect for most users.  *Note MySQL binaries::.  There
     are some configuration setings you can tweak to make an even
     faster binary, but this is only for advanced users.  *Note Compile
     and link options::.

     If the build fails and produces errors about your compiler or
     linker not being able to create the shared library
     `libmysqlclient.so.#' (`#' is a version number), you can work
     around this problem by giving the `--disable-shared' option to
     `configure'.  In this case, `configure' will not build a shared
     `libmysqlclient.so.#' library.

   * You can configure MySQL not to use `DEFAULT' column values for
     non-`NULL' columns (that is, columns that are not allowed to be
     `NULL'). *Note constraint NOT NULL::.

          shell> CXXFLAGS=-DDONT_USE_DEFAULT_FIELDS ./configure

     The effect of this flag is to cause any `INSERT' statement to fail
     unless it provides explicit values for all columns that require a
     non-`NULL' value.

   * By default, MySQL uses the ISO-8859-1 (Latin1) character set. To
     change the default set, use the `--with-charset' option:
          shell> ./configure --with-charset=CHARSET
     `CHARSET' may be one of `big5', `cp1251', `cp1257', `czech',
     `danish', `dec8', `dos', `euc_kr', `gb2312', `gbk', `german1',
     `hebrew', `hp8', `hungarian', `koi8_ru', `koi8_ukr', `latin1',
     `latin2', `sjis', `swe7', `tis620', `ujis', `usa7', or
     `win1251ukr'.  *Note Character sets::.

     If you want to convert characters between the server and the
     client, you should take a look at the `SET CHARACTER SET' command.
     *Note `SET': SET OPTION.

     *Warning:* If you change character sets after having created any
     tables, you will have to run `myisamchk -r -q
     --set-character-set=charset' on every table. Your indexes may be
     sorted incorrectly otherwise.  (This can happen if you install
     MySQL, create some tables, then reconfigure MySQL to use a
     different character set and reinstall it.)

     With the `configure' option `--with-extra-charsets=LIST', you can
     define which additional character sets should be compiled into the
     server.  `LIST' is either a list of character sets separated with
     spaces, `complex' to include all characters that can't be
     dynamically loaded, or `all' to include all character sets into
     the binaries.

   * To configure MySQL with debugging code, use the `--with-debug'
     option:
          shell> ./configure --with-debug
     This causes a safe memory allocator to be included that can find
     some errors and that provides output about what is happening.
     *Note Debugging server::.

   * If your client programs are using threads, you also must compile a
     thread-safe version of the MySQL client library with the
     `--enable-thread-safe-client' configure options. This will create a
     `libmysqlclient_r' library with which you should link your threaded
     applications.  *Note Threaded clients::.

   * Options that pertain to particular systems can be found in the
     system-specific section of this manual.  *Note Operating System
     Specific Notes::.

Installing from the Development Source Tree
-------------------------------------------

*Caution*: You should read this section only if you are interested in
helping us test our new code. If you just want to get MySQL up and
running on your system, you should use a standard release distribution
(either a binary or source distribution will do).

To obtain our most recent development source tree, use these
instructions:

  1. Download `BitKeeper' from
     `http://www.bitmover.com/cgi-bin/download.cgi'.  You will need
     `Bitkeeper' 3.0 or newer to access our repository.

  2. Follow the instructions to install it.

  3. After `BitKeeper' is installed, first go to the directory you want
     to work from, and then use one of the following commands to clone
     the MySQL version branch of your choice:

     To clone the old 3.23 branch, use this command:

          shell> bk clone bk://mysql.bkbits.net/mysql-3.23 mysql-3.23

     To clone the 4.0 stable (production) branch, use this command:

          shell> bk clone bk://mysql.bkbits.net/mysql-4.0 mysql-4.0

     To clone the 4.1 alpha branch, use this command:

          shell> bk clone bk://mysql.bkbits.net/mysql-4.1 mysql-4.1

     To clone the 5.0 development branch, use this command:

          shell> bk clone bk://mysql.bkbits.net/mysql-5.0 mysql-5.0

     In the preceding examples the source tree will be set up in the
     `mysql-3.23/', `mysql-4.0/', `mysql-4.1/', or `mysql-5.0/'
     subdirectory of your current directory.

     If you are behind a firewall and can only initiate HTTP
     connections, you can also use `BitKeeper' via HTTP.

     If you are required to use a proxy server, set the environment
     variable `http_proxy' to point to your proxy:

          shell> export http_proxy="http://your.proxy.server:8080/"

     Now, simply replace the `bk://' with `http://' when doing a clone.
     Example:

          shell> bk clone http://mysql.bkbits.net/mysql-4.1 mysql-4.1

     The initial download of the source tree may take a while,
     depending on the speed of your connection--please be patient.

  4. You will need GNU `make', `autoconf' 2.53 (or newer), `automake'
     1.5, `libtool' 1.4, and `m4' to run the next set of commands. Even
     though many operating systems already come with their own
     implementation of `make', chances are high that the compilation
     will fail with strange error messages. Therefore, it is highly
     recommended that you use GNU `make' (sometimes named `gmake')
     instead.

     Fortunately, a large number of operating systems already ship with
     the GNU toolchain preinstalled or supply installable packages of
     these. In any case, they can also be downloaded from the following
     locations:

        * <http://www.gnu.org/software/autoconf/>

        * <http://www.gnu.org/software/automake/>

        * <http://www.gnu.org/software/libtool/>

        * <http://www.gnu.org/software/make/>

     If you are trying to configure MySQL 4.1 or later, you will also
     need GNU `bison' 1.75 or later.  Older versions of `bison' may
     report this error:

          sql_yacc.yy:#####: fatal error: maximum table size (32767) exceeded

     Note: The maximum table size is not actually exceeded, the error
     is caused by bugs in older versions of `bison'.

     Versions of MySQL before version 4.1 may also compile with other
     `yacc' implementations (for example, BSD `yacc' 91.7.30). For later
     versions, GNU `bison' is required.

     The following example shows the typical commands required to
     configure a source tree. The first `cd' command changes location
     into the top-level directory of the tree; replace `mysql-4.0' with
     the appropriate directory name.

          shell> cd mysql-4.0
          shell> bk -r edit
          shell> aclocal; autoheader; autoconf; automake
          shell> (cd innobase; aclocal; autoheader; autoconf; automake)
          shell> (cd bdb/dist; sh s_all)
          shell> ./configure  # Add your favorite options here
          make

     The command lines that change directory into the `innobase' and
     `bdb/dist' directories are used to configure the `InnoDB' and
     Berkeley DB (`BDB') storage engines.  You can omit these command
     lines if you to not require `InnoDB' or `BDB' support.

     If you get some strange error during this stage, check that you
     really have `libtool' installed.

     A collection of our standard configuration scripts is located in
     the `BUILD/' subdirectory.  You may find it more convenient to use
     the `BUILD/compile-pentium-debug' script than the preceding set of
     shell commands.. To compile on a different architecture, modify
     the script by removing flags that are Pentium-specific.

  5. When the build is done, run `make install'.  Be careful with this
     on a production machine; the command may overwrite your live
     release installation.  If you have another installation of MySQL,
     we recommend that you run `./configure' with different values for
     the `--prefix', `--with-tcp-port', and `--unix-socket-path' options
     than those used for your production server.

  6. Play hard with your new installation and try to make the new
     features crash.  Start by running `make test'.  *Note MySQL test
     suite::.

  7. If you have gotten to the `make' stage and the distribution does
     not compile, please report it in our bugs database at
     `http://bugs.mysql.com/'.  If you have installed the latest
     versions of the required GNU tools, and they crash trying to
     process our configuration files, please report that also.
     However, if you execute `aclocal' and get a `command not found'
     error or a similar problem, do not report it.  Instead, make sure
     all the necessary tools are installed and that your `PATH'
     variable is set correctly so that your shell can find them.

  8. After the initial `bk clone' operation to obtain the source tree,
     you should run `bk pull' periodically to get updates.

  9. You can examine the change history for the tree with all the diffs
     by using `bk revtool'.  If you see some funny diffs or code that
     you have a question about, do not hesitate to send email to the
     MySQL internals mailing list.  *Note Mailing-list::.  Also, if you
     think you have a better idea on how to do something, send an email
     message to the same address with a patch.  `bk diffs' will produce
     a patch for you after you have made changes to the source. If you
     do not have the time to code your idea, just send a description.

 10. `BitKeeper' has a nice help utility that you can access via `bk
     helptool'.

 11. Please note that any commits (`bk ci' or `bk citool') will trigger
     the posting of a message with the changeset to our internals
     mailing list, as well as the usual openlogging.org submission with
     just the changeset comments.  Generally, you wouldn't need to use
     commit (since the public tree will not allow `bk push'), but
     rather use the `bk diffs' method described previously.


You can also browse changesets, comments, and source code online. For
example, to browse this information for MySQL 4.1, go to
`http://mysql.bkbits.net:8080/mysql-4.1'.

The manual is in a separate tree which can be cloned with:

     shell> bk clone bk://mysql.bkbits.net/mysqldoc mysqldoc

There are also public BitKeeper trees for MySQL Control Center and
Connector/ODBC. They can be cloned respectively as follows.

To clone MySQL Control center, use this command:

     shell> bk clone http://mysql.bkbits.net/mysqlcc mysqlcc

To clone Connector/ODBC, use this command:

     shell> bk clone http://mysql.bkbits.net/myodbc3 myodbc3

Dealing With Problems Compiling MySQL
-------------------------------------

All MySQL programs compile cleanly for us with no warnings on Solaris
or Linux using `gcc'.  On other systems, warnings may occur due to
differences in system include files.  See *Note MIT-pthreads:: for
warnings that may occur when using MIT-pthreads.  For other problems,
check the following list.

The solution to many problems involves reconfiguring.  If you do need to
reconfigure, take note of the following:

   * If `configure' is run after it already has been run, it may use
     information that was gathered during its previous invocation.  This
     information is stored in `config.cache'.  When `configure' starts
     up, it looks for that file and reads its contents if it exists, on
     the assumption that the information is still correct.  That
     assumption is invalid when you reconfigure.

   * Each time you run `configure', you must run `make' again to
     recompile.  However, you may want to remove old object files from
     previous builds first because they were compiled using different
     configuration options.

To prevent old configuration information or object files from being
used, run these commands before re-running `configure':

     shell> rm config.cache
     shell> make clean

Alternatively, you can run `make distclean'.

The following list describes some of the problems when compiling MySQL
that have been found to occur most often:

   * If you get errors when compiling `sql_yacc.cc', such as the ones
     shown here, you have probably run out of memory or swap space:

          Internal compiler error: program cc1plus got fatal signal 11
     or:
          Out of virtual memory
     or:
          Virtual memory exhausted

     The problem is that `gcc' requires huge amounts of memory to
     compile `sql_yacc.cc' with inline functions.  Try running
     `configure' with the `--with-low-memory' option:

          shell> ./configure --with-low-memory

     This option causes `-fno-inline' to be added to the compile line
     if you are using `gcc' and `-O0' if you are using something else.
     You should try the `--with-low-memory' option even if you have so
     much memory and swap space that you think you can't possibly have
     run out.  This problem has been observed to occur even on systems
     with generous hardware configurations, and the `--with-low-memory'
     option usually fixes it.

   * By default, `configure' picks `c++' as the compiler name and GNU
     `c++' links with `-lg++'.  If you are using `gcc', that behavior
     can cause problems during configuration such as this:

          configure: error: installation or configuration problem:
          C++ compiler cannot create executables.

     You might also observe problems during compilation related to
     `g++', `libg++', or `libstdc++'.

     One cause of these problems is that you may not have `g++', or you
     may have `g++' but not `libg++', or `libstdc++'.  Take a look at
     the `config.log' file.  It should contain the exact reason why
     your C++ compiler didn't work.  To work around these problems, you
     can use `gcc' as your C++ compiler.  Try setting the environment
     variable `CXX' to `"gcc -O3"'.  For example:

          shell> CXX="gcc -O3" ./configure

     This works because `gcc' compiles C++ sources as well as `g++'
     does, but does not link in `libg++' or `libstdc++' by default.

     Another way to fix these problems is to install `g++', `libg++',
     and `libstdc++'.  We would however like to recommend you to not
     use `libg++' or `libstdc++' with MySQL as this will only increase
     the binary size of mysqld without giving you any benefits.  Some
     versions of these libraries have also caused strange problems for
     MySQL users in the past.

     Using `gcc' as the C++ compiler is also required, if you want to
     compile MySQL with RAID functionality (see *Note CREATE TABLE::
     for more info on RAID table type) and you are using GNU `gcc'
     version 3 and above. If you get errors like the ones below during
     the linking stage when you configure MySQL to compile with the
     option `--with-raid', try to use `gcc' as your C++ compiler by
     defining the above mentioned environment variable `CXX':

          gcc -O3 -DDBUG_OFF -rdynamic -o isamchk isamchk.o sort.o  libnisam.a
          ../mysys/libmysys.a ../dbug/libdbug.a ../strings/libmystrings.a
           -lpthread -lz -lcrypt -lnsl -lm -lpthread
          ../mysys/libmysys.a(raid.o)(.text+0x79): In function
          `my_raid_create':: undefined reference to `operator new(unsigned)'
          ../mysys/libmysys.a(raid.o)(.text+0xdd): In function
          `my_raid_create':: undefined reference to `operator delete(void*)'
          ../mysys/libmysys.a(raid.o)(.text+0x129): In function
          `my_raid_open':: undefined reference to `operator new(unsigned)'
          ../mysys/libmysys.a(raid.o)(.text+0x189): In function
          `my_raid_open':: undefined reference to `operator delete(void*)'
          ../mysys/libmysys.a(raid.o)(.text+0x64b): In function
          `my_raid_close':: undefined reference to `operator delete(void*)'
          collect2: ld returned 1 exit status

   * If your compile fails with errors, such as any of the following,
     you must upgrade your version of `make' to GNU `make':

          making all in mit-pthreads
          make: Fatal error in reader: Makefile, line 18:
          Badly formed macro assignment
     or:
          make: file `Makefile' line 18: Must be a separator (:
     or:
          pthread.h: No such file or directory

     Solaris and FreeBSD are known to have troublesome `make' programs.

     GNU `make' Version 3.75 is known to work.

   * If you want to define flags to be used by your C or C++ compilers,
     do so by adding the flags to the `CFLAGS' and `CXXFLAGS'
     environment variables.  You can also specify the compiler names
     this way using `CC' and `CXX'.  For example:

          shell> CC=gcc
          shell> CFLAGS=-O3
          shell> CXX=gcc
          shell> CXXFLAGS=-O3
          shell> export CC CFLAGS CXX CXXFLAGS

     See *Note MySQL binaries::, for a list of flag definitions that
     have been found to be useful on various systems.

   * If you get an error message like this, you need to upgrade your
     `gcc' compiler:

          client/libmysql.c:273: parse error before `__attribute__'

     `gcc' 2.8.1 is known to work, but we recommend using `gcc' 2.95.2
     or `egcs' 1.0.3a instead.

   * If you get errors such as those shown here when compiling `mysqld',
     `configure' didn't correctly detect the type of the last argument
     to `accept()', `getsockname()', or `getpeername()':

          cxx: Error: mysqld.cc, line 645: In this statement, the referenced
               type of the pointer value ''length'' is ''unsigned long'',
               which is not compatible with ''int''.
          new_sock = accept(sock, (struct sockaddr *)&cAddr, &length);

     To fix this, edit the `config.h' file (which is generated by
     `configure').  Look for these lines:

          /* Define as the base type of the last arg to accept */
          #define SOCKET_SIZE_TYPE XXX

     Change `XXX' to `size_t' or `int', depending on your operating
     system.  (Note that you will have to do this each time you run
     `configure' because `configure' regenerates `config.h'.)

   * The `sql_yacc.cc' file is generated from `sql_yacc.yy'.  Normally
     the build process doesn't need to create `sql_yacc.cc', because
     MySQL comes with an already generated copy.  However, if you do
     need to re-create it, you might encounter this error:

          "sql_yacc.yy", line xxx fatal: default action causes potential...

     This is a sign that your version of `yacc' is deficient.  You
     probably need to install `bison' (the GNU version of `yacc') and
     use that instead.

   * On Debian Linux 3.0, you need to install `gawk' instead of the
     default `mawk', if you want to compile MySQL 4.1 or higher with
     Berkeley DB support.

   * If you need to debug `mysqld' or a MySQL client, run `configure'
     with the `--with-debug' option, then recompile and link your
     clients with the new client library.  *Note Debugging client::.

   * If you get a compilation error on Linux (e.g. SuSE Linux 8.1 or
     Red Hat Linux 7.3) similar to the following one:

          libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from
          incompatible pointer type
          libmysql.c:1329: too few arguments to function `gethostbyname_r'
          libmysql.c:1329: warning: assignment makes pointer from integer
          without a cast
          make[2]: *** [libmysql.lo] Error 1

     By default, the `configure' script attempts to determine the
     correct number of arguments by using `g++' the GNU C++ compiler.
     This test yields wrong results, if `g++' is not installed. There
     are two ways to work around this problem:

        * Make sure that the GNU C++ `g++' is installed. On some Linux
          distributions, the required package is called `gpp', on
          others it is named `gcc-c++'.

        * Use `gcc' as your C++ compiler by setting the `CXX'
          environment variable to `gcc':
               export CXX="gcc"

     Please note that you need to run `configure' again afterwards.


MIT-pthreads Notes
------------------

This section describes some of the issues involved in using
MIT-pthreads.

Note that on Linux you should *not* use MIT-pthreads but use the
installed LinuxThreads implementation instead.  *Note Linux::.

If your system does not provide native thread support, you will need to
build MySQL using the MIT-pthreads package.  This includes older
FreeBSD systems, SunOS 4.x, Solaris 2.4 and earlier, and some others.
*Note Which OS::.

Note that, beginning with MySQL 4.0.2, MIT-pthreads are no longer part
of the source distribution. If you require this package, you need to
download it separately from
<http://www.mysql.com/Downloads/Contrib/pthreads-1_60_beta6-mysql.tar.gz>

After downloading, extract this source archive into the top level of the
MySQL source directory. It will create a new subdirectory
`mit-pthreads'.

   * On most systems, you can force MIT-pthreads to be used by running
     `configure' with the `--with-mit-threads' option:

          shell> ./configure --with-mit-threads

     Building in a non-source directory is not supported when using
     MIT-pthreads because we want to minimise our changes to this code.

   * The checks that determine whether to use MIT-pthreads occur only
     during the part of the configuration process that deals with the
     server code.  If you have configured the distribution using
     `--without-server' to build only the client code, clients will not
     know whether MIT-pthreads is being used and will use Unix socket
     connections by default.  Because Unix socket files do not work
     under MIT-pthreads on some platforms, this means you will need to
     use `-h' or `--host' when you run client programs.

   * When MySQL is compiled using MIT-pthreads, system locking is
     disabled by default for performance reasons.  You can tell the
     server to use system locking with the `--external-locking' option.
     This is only needed if you want to be able to run two MySQL
     servers against the same datafiles (not recommended).

   * Sometimes the pthread `bind()' command fails to bind to a socket
     without any error message (at least on Solaris).  The result is
     that all connections to the server fail.  For example:

          shell> mysqladmin version
          mysqladmin: connect to server at '' failed;
          error: 'Can't connect to mysql server on localhost (146)'

     The solution to this is to kill the `mysqld' server and restart it.
     This has only happened to us when we have forced down the server
     and done a restart immediately.

   * With MIT-pthreads, the `sleep()' system call isn't interruptible
     with `SIGINT' (break).  This is only noticeable when you run
     `mysqladmin --sleep'.  You must wait for the `sleep()' call to
     terminate before the interrupt is served and the process stops.

   * When linking, you may receive warning messages like these (at
     least on Solaris); they can be ignored:

          ld: warning: symbol `_iob' has differing sizes:
              (file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
          file /usr/lib/libc.so value=0x140);
              /my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
          ld: warning: symbol `__iob' has differing sizes:
              (file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
          file /usr/lib/libc.so value=0x140);
              /my/local/pthreads/lib/libpthread.a(findfp.o) definition taken

   * Some other warnings also can be ignored:

          implicit declaration of function `int strtoll(...)'
          implicit declaration of function `int strtoul(...)'

   * We haven't gotten `readline' to work with MIT-pthreads.  (This
     isn't needed, but may be interesting for someone.)

Installing MySQL from Source on Windows
---------------------------------------

These instructions describe how to build MySQL binaries from source for
versions 4.1 and above on Windows. Instructions are provided for
building binaries from a standard source distribution or from the
BitKeeper tree that contains the latest development source.

*Note:* The instructions in this document are strictly for users who
want to test MySQL on Windows from the latest source distribution or
from the BitKeeper tree.  For production use, MySQL AB does not advise
using a MySQL server built by yourself from source.  Normally, it is
best to use precompiled binary distributions of MySQL that are built
specifically for optimal performance on Windows by MySQL AB.
Instructions for installing a binary distributions are available at
*Note Windows installation::.

To build MySQL on Windows from source, you need the following compiler
and resources available on your Windows system:

   * VC++ 6.0 compiler (updated with 4 or 5 SP and pre-processor
     package).  The pre-processor package is necessary for the macro
     assembler.  More details at:
     `http://msdn.microsoft.com/vstudio/downloads/updates/sp/vs6/sp5/faq.aspx'.

   * Approximately 45 MB disk space.

   * 64 MB RAM.


You'll also need a MySQL source distribution for Windows.  There are
two ways you can get a source distribution for MySQL version 4.1 and
above:

  1. Obtain a source distribution packaged by MySQL AB for the
     particular version of MySQL in which you are interested.
     Prepackaged source distributions are available for released
     versions of MySQL and can be obtained from
     `http://www.mysql.com/downloads/'.

  2. You can package a source distribution yourself from the latest
     BitKeeper developer source tree. If you plan to do this, you must
     create the package on a Unix system and then transfer it to your
     Windows system.  (The reason for this is that some of the
     configuration and build steps require tools that work only on
     Unix.)  The BitKeeper approach thus requires:

        * A system running Unix, or a Unix-like system such as Linux.

        * BitKeeper 3.0 installed on that system. You can obtain
          BitKeeper from `http://www.bitkeeper.com/'.



If you are using a Windows source distribution, you can go directly to
*Note Windows VC++ Build::. To build from the BitKeeper tree, proceed to
*Note Windows BitKeeper Build::.

If you find something not working as expected, or you have suggestions
about ways to improve the current build process on Windows, please send
a message to the `win32' mailing list.  *Note Mailing-list::.

Building MySQL Using VC++
.........................

*Note:* MySQL 4.1 and above VC++ workspace files are compatible with
Microsoft Visual Studio 6.0 and above(7.0/.NET) editions and tested by
MySQL AB staff before each release.

Follow this procedure to build MySQL:

  1. Create a work directory (for example, `workdir').

  2. Unpack the source distribution in the aforementioned directory
     using `WinZip' or other Windows tools that can read `.zip' files.

  3. Start the VC++ 6.0 compiler.

  4. In the `File' menu, select `Open Workspace'.

  5. Open the `mysql.dsw' workspace you find in the work directory.

  6. From the `Build' menu, select the `Set Active Configuration' menu.

  7. Click over the screen selecting `mysqld - Win32 Debug' and click
     OK.

  8. Press `F7' to begin the build of the debug server, libraries, and
     some client applications.

  9. Compile the release versions that you want, in the same way.

 10. Debug versions of the programs and libraries are placed in the
     `client_debug' and `lib_debug' directories.  Release versions of
     the programs and libraries are placed in the `client_release' and
     `lib_release' directories.  Note that if you want to build both
     debug and release versions, you can select the "build all" option
     from the `Build' menu.

 11. Test the server.  The server built using the preceding instructions
     will expect that the MySQL base directory and data directory are
     `C:\mysql' and `C:\mysql\data' by default. If you want to test
     your server using the source tree root directory and its data
     directory as the base directory and data directory, you will need
     to tell the server their pathnames. You can either do this on the
     command line with the `--basedir' and `--datadir' options, or
     place appropriate options in an option file (`C:\my.cnf' or the
     `my.ini' file in your Windows directory). If you have an existing
     data directory elsewhere that you want to use, you can specify its
     pathname instead.

 12. Start your server from the `client_release' or `client_debug'
     directory, depending on which server you want to use. The general
     server startup instructions are at *Note Windows installation::.
     You'll need to to adapt the instructions appropriately if you want
     to use a different base directory or data directory.

 13. When the server is running in standalone fashion or as a service
     based on your configuration, try to connect to it from the `mysql'
     interactive command line utility that exists in your
     `client_release' or `client_debug' directory.


When you are satisifed that the programs you have built are working
correctly, stop the server. Then install MySQL as follows:

  1. Create the directories where you want to install MySQL.  For
     example, to install into `C:\mysql', use these commands:

          C:
          mkdir \mysql
          mkdir \mysql\bin
          mkdir \mysql\data
          mkdir \mysql\share
          mkdir \mysql\scripts

     If you want to compile other clients and link them to MySQL, you
     should also create several additional directories:

          mkdir \mysql\include
          mkdir \mysql\lib
          mkdir \mysql\lib\debug
          mkdir \mysql\lib\opt

     If you want to benchmark MySQL, create this directory:

          mkdir \mysql\sql-bench

     Benchmarking requires Perl support.

  2. From the `workdir' directory, copy into the `C:\mysql' directory
     the following directories:

          copy client_release\*.exe C:\mysql\bin
          copy client_debug\mysqld.exe C:\mysql\bin\mysqld-debug.exe
          xcopy scripts\*.* C:\mysql\scripts /E
          xcopy share\*.* C:\mysql\share /E

     If you want to compile other clients and link them to MySQL, you
     should also copy several libraries and header files:

          copy lib_debug\mysqlclient.lib C:\mysql\lib\debug
          copy lib_debug\libmysql.* C:\mysql\lib\debug
          copy lib_debug\zlib.* C:\mysql\lib\debug
          copy lib_release\mysqlclient.lib C:\mysql\lib\opt
          copy lib_release\libmysql.* C:\mysql\lib\opt
          copy lib_release\zlib.* C:\mysql\lib\opt
          copy include\*.h C:\mysql\include
          copy libmysql\libmysql.def C:\mysql\include

     If you want to benchmark MySQL, you should also do this:

          xcopy sql-bench\*.* C:\mysql\bench /E


Set up and start the server in the same way as for the binary Windows
distribution.  *Note Windows installation::.

Creating a Windows Source Package from the Latest Development Source
....................................................................

To create a Windows source package from the current BitKeeper source
tree, use the following instructions. Please note that this procedure
must be performed on a system running a Unix or Unix-like operating
system.  (The procedure is known to work well on Linux, for example.)

  1. Clone the BitKeeper source tree for MySQL (version 4.1 or above,
     as desired).  For more information how to clone the source tree,
     see the instructions at *Note Installing source tree::.

  2. Configure and build the distribution so that you have a server
     binary to work with.  One way to do this is to run the following
     command in the top-level directory of your source tree:

          shell> ./BUILD/compile-pentium-max

  3. After making sure that the build process completed successfully,
     run the following utility script from top-level directory of your
     source tree:

          shell> ./scripts/make_win_src_distribution

     This script creates a Windows source package, to be used on your
     Windows system.  You can supply different options to the script
     based on your needs. It accepts the following options:

          --debug   Print information about script operations, do not create package
          --tmp     Specify the temporary location
          --suffix  Suffix name for the package
          --dirname Directory name to copy files (intermediate)
          --silent  Do not print verbose list of files processed
          --tar     Create tar.gz package instead of .zip package
          --help    Show this help message

     By default, `make_win_src_distribution' creates a zipped archive
     with the name `mysql-VERSION-win-src.zip', where `VERSION'
     represents the version of your MySQL source tree.

  4. Copy or upload to your Windows machine the Windows source package
     that you have just created. To compile it, use the instructions in
     *Note Windows VC++ Build::.


Compiling MySQL Clients on Windows
----------------------------------

In your source files, you should include `my_global.h' before `mysql.h':

     #include <my_global.h>
     #include <mysql.h>

`my_global.h' includes any other files needed for Windows compatibility
(such as `windows.h') if you compile your program on Windows.

You can either link your code with the dynamic `libmysql.lib' library,
which is just a wrapper to load in `libmysql.dll' on demand, or link
with the static `mysqlclient.lib' library.

Note that because the MySQL client libraries are compiled as threaded
libraries, you should also compile your code to be multi-threaded!

Post-installation Setup and Testing
===================================

There are some issues you should address after installing MySQL.  For
example, on Unix, you should create the MySQL grant tables.  On all
platforms, an important security concern is that the initial accounts
in the grant tables have no passwords.  You should assign passwords to
prevent unauthorized access to the MySQL server.

The following sections describe post-installation procedures for Windows
systems and for Unix systems.

Windows Post-installation Procedures
------------------------------------

On Windows, the grant tables do not have to be created. MySQL Windows
distributions include the grant tables already set up in the `mysql'
database under the `data' directory.  However, you should assign
passwords to the accounts.

The default privileges on Windows give all local users full privileges
to all databases without specifying a password.  To make MySQL more
secure, you should set a password for all users and remove the row in
the `mysql.user' table that has `Host='localhost'' and `User='''.

You should also add a password for the `root' user. The following
example starts by removing the anonymous user that has all privileges,
then sets a `root' user password:

     C:\> C:\mysql\bin\mysql mysql
     mysql> DELETE FROM user WHERE Host='localhost' AND User='';
     mysql> FLUSH PRIVILEGES;
     mysql> QUIT
     C:\> C:\mysql\bin\mysqladmin -u root password your_password

After you've set the password, if you want to shut down the `mysqld'
server, you can do so using this command:

     C:\> mysqladmin --user=root --password=your_password shutdown

If you are using a server from a _very_ old version of MySQL, the
`mysqladmin' command to set the password will fail with an error:
`parse error near 'SET password''.  The solution to this problem is to
upgrade to a newer version of MySQL.

With the current MySQL versions you can easily add new users and change
privileges with `GRANT' and `REVOKE' commands.  *Note `GRANT': GRANT.

Unix Post-installation Procedures
---------------------------------

After you install MySQL on Unix, you need to initialize the grant
tables, start the server, and make sure that the server works okay.
You may also wish to arrange for the server to be started and stopped
automatically when your system starts and stops.

Normally you install the grant tables and start the server like this
for installation from a source distribution:

     shell> cd mysql_installation_directory
     shell> bin/mysql_install_db
     shell> bin/mysqld_safe --user=mysql &

For a binary distribution (not RPM or PKG packages), do this:

     shell> cd mysql_installation_directory
     shell> scripts/mysql_install_db
     shell> bin/mysqld_safe --user=mysql &

The `mysql_install_db' script creates the `mysql' database that holds
all database privileges, and the `test' database that you can use to
test MySQL. The script also creates privilege table entries for `root'
accounts and anonymous-user accounts.  The entries are created without
passwords.  The `mysqld_safe' script starts the `mysqld' server.  (For
versions of MySQL older than 4.0, use `safe_mysqld' rather than
`mysqld_safe'.)

`mysql_install_db' will not overwrite any old privilege tables, so it
should be safe to run in any circumstances.  If you don't want to have
the `test' database you can remove it with `mysqladmin -u root drop
test' after starting the server.

Testing is most easily done from the top-level directory of the MySQL
distribution.  For a binary distribution, this is your installation
directory (typically something like `/usr/local/mysql').  For a source
distribution, this is the main directory of your MySQL source tree.

In the commands shown in this section and in the following subsections,
`BINDIR' is the path to the location in which programs like
`mysqladmin' and `mysqld_safe' are installed.  For a binary
distribution, this is the `bin' directory within the distribution.  For
a source distribution, `BINDIR' is probably `/usr/local/bin', unless
you specified an installation directory other than `/usr/local' when
you ran `configure'.  `EXECDIR' is the location in which the `mysqld'
server is installed.  For a binary distribution, this is the same as
`BINDIR'.  For a source distribution, `EXECDIR' is probably
`/usr/local/libexec'.

Testing is described in detail:

  1. If necessary, start the `mysqld' server and set up the initial
     MySQL grant tables containing the privileges that determine how
     users are allowed to connect to the server.  This is normally done
     with the `mysql_install_db' script:

          shell> scripts/mysql_install_db

     Typically, `mysql_install_db' needs to be run only the first time
     you install MySQL.  Therefore, if you are upgrading an existing
     installation, you can skip this step.  (However,
     `mysql_install_db' is quite safe to use and will not update any
     tables that already exist, so if you are unsure of what to do, you
     can always run `mysql_install_db'.)

     `mysql_install_db' creates six tables (`user', `db', `host',
     `tables_priv', `columns_priv', and `func') in the `mysql'
     database.  A description of the initial privileges is given in
     *Note Default privileges::.  Briefly, these privileges allow the
     MySQL `root' user to do anything, and allow anybody to create or
     use databases with a name of `test' or starting with `test_'.

     If you don't set up the grant tables, the following error will
     appear in the log file when you start the server:

          mysqld: Can't find file: 'host.frm'

     This may also happen with a binary MySQL distribution if you don't
     start MySQL by executing exactly `./bin/mysqld_safe'.  *Note
     `mysqld_safe': mysqld_safe.

     You might need to run `mysql_install_db' as `root'.  However, if
     you prefer, you can run the MySQL server as an unprivileged
     (non-`root') user, provided that the user can read and write files
     in the database directory.  Instructions for running MySQL as an
     unprivileged user are given in *Note Changing MySQL user: Changing
     MySQL user.

     If you have problems with `mysql_install_db', see *Note
     `mysql_install_db': mysql_install_db.

     There are some alternatives to running the `mysql_install_db'
     script as it is provided in the MySQL distribution:

        * You may want to edit `mysql_install_db' before running it, to
          change the initial privileges that are installed into the
          grant tables.  This is useful if you want to install MySQL on
          a lot of machines with the same privileges.  In this case you
          probably should need only to add a few extra `INSERT'
          statements to the `mysql.user' and `mysql.db' tables.

        * If you want to change the contents of the grant tables after
          installing them, you can run `mysql_install_db', then use
          `mysql -u root mysql' to connect to the grant tables as the
          MySQL `root' user and issue SQL statements to modify the
          grant tables directly.

        * It is possible to re-create the grant tables completely after
          they have already been created.  You might want to do this if
          you've already installed the tables but then want to
          re-create them after editing `mysql_install_db'.

     For more information about these alternatives, see *Note Default
     privileges::.

  2. Start the MySQL server like this:

          shell> cd mysql_installation_directory
          shell> bin/mysqld_safe &

     For versions of MySQL older than 4.0, substitute `bin/safe_mysqld'
     for `bin/mysqld_safe' in the final command.

     If you have problems starting the server, see *Note Starting
     server::.

  3. Use `mysqladmin' to verify that the server is running.  The
     following commands provide a simple test to check that the server
     is up and responding to connections:

          shell> BINDIR/mysqladmin version
          shell> BINDIR/mysqladmin variables

     The output from `mysqladmin version' varies slightly depending on
     your platform and version of MySQL, but should be similar to that
     shown here:

          shell> BINDIR/mysqladmin version
          mysqladmin  Ver 8.40 Distrib 4.0.18, for linux on i586
          Copyright (C) 2000 MySQL AB & MySQL Finland AB & TCX DataKonsult AB
          This software comes with ABSOLUTELY NO WARRANTY. This is free software,
          and you are welcome to modify and redistribute it under the GPL license


          Server version          4.0.18-log
          Protocol version        10
          Connection              Localhost via Unix socket
          TCP port                3306
          UNIX socket             /tmp/mysql.sock
          Uptime:                 16 sec

          Threads: 1  Questions: 9  Slow queries: 0
          Opens: 7  Flush tables: 2  Open tables: 0
          Queries per second avg: 0.000
          Memory in use: 132K  Max memory used: 16773K

     To see what else you can do with `mysqladmin', invoke it with the
     `--help' option.

  4. Verify that you can shut down the server:

          shell> BINDIR/mysqladmin -u root shutdown

  5. Verify that you can restart the server.  Do this using
     `mysqld_safe' or by invoking `mysqld' directly.  For example:

          shell> BINDIR/mysqld_safe --log &

     If `mysqld_safe' fails, try running it from the MySQL installation
     directory (if you are not already there).  If that doesn't work,
     see *Note Starting server::.

  6. Run some simple tests to verify that the server is working.  The
     output should be similar to what is shown here:

          shell> BINDIR/mysqlshow
          +-----------+
          | Databases |
          +-----------+
          | mysql     |
          +-----------+

          shell> BINDIR/mysqlshow mysql
          Database: mysql
          +--------------+
          |    Tables    |
          +--------------+
          | columns_priv |
          | db           |
          | func         |
          | host         |
          | tables_priv  |
          | user         |
          +--------------+

          shell> BINDIR/mysql -e "SELECT host,db,user FROM db" mysql
          +------+--------+------+
          | host | db     | user |
          +------+--------+------+
          | %    | test   |      |
          | %    | test_% |      |
          +------+--------+------+

     There is also a benchmark suite in the `sql-bench' directory
     (under the MySQL installation directory) that you can use to
     compare how MySQL performs on different platforms. The benchmark
     suite is written in Perl. It uses the Perl DBI module to provide a
     database-independent interface to the various databases. The
     following additional Perl modules are required to run the
     benchmark suite:

          DBI
          DBD::mysql
          Data::Dumper
          Data::ShowTable

     These modules can be obtained from CPAN `http://www.cpan.org/'.
     *Note Perl installation::.

     The `sql-bench/Results' directory contains the results from many
     runs against different databases and platforms.  To run all tests,
     execute these commands:

          shell> cd sql-bench
          shell> run-all-tests

     If you don't have the `sql-bench' directory, you probably
     installed MySQL using RPM files other than the source RPM.  (The
     source RPM includes the `sql-bench' benchmark directory.)  In this
     case, you must first install the benchmark suite before you can
     use it.  Beginning with MySQL Version 3.22, there are separate
     benchmark RPM files named `mysql-bench-VERSION-i386.rpm' that
     contain benchmark code and data.

     If you have a source distribution, there are also tests in its
     `tests' subdirectory that you can run. For example, to run
     `auto_increment.tst', do this:

          shell> BINDIR/mysql -vvf test < ./tests/auto_increment.tst

     The expected result of the test can be found in the
     `./tests/auto_increment.res' file.

Problems Running `mysql_install_db'
...................................

The purpose of the `mysql_install_db' script is to generate new MySQL
privilege tables.  It will not overwrite existing MySQL privilege
tables, and it will not affect any other data.

If you want to re-create your privilege tables, you should take down
the `mysqld' server, if it's running, and then do something like:

     mv mysql-data-directory/mysql mysql-data-directory/mysql-old
     mysql_install_db

This section lists problems you might encounter when you run
`mysql_install_db':

*`mysql_install_db' doesn't install the grant tables*
     You may find that `mysql_install_db' fails to install the grant
     tables and terminates after displaying the following messages:

          Starting mysqld daemon with databases from XXXXXX
          mysqld ended

     In this case, you should examine the log file very carefully.  The
     log should be located in the directory `XXXXXX' named by the error
     message, and should indicate why `mysqld' didn't start.  If you
     don't understand what happened, include the log when you post a
     bug report.  *Note Bug reports::.

*There is already a `mysqld' process running*
     In this case, you probably don't have to run `mysql_install_db' at
     all.  You have to run `mysql_install_db' only once, when you
     install MySQL the first time.

*Installing a second `mysqld' server doesn't work when one server is running*
     This can happen when you already have an existing MySQL
     installation, but want to put a new installation in a different
     location (for example, for testing, or perhaps you simply want to
     run two installations at the same time).  Generally the problem
     that occurs when you try to run the second server is that it tries
     to use the same socket and port as the old one.  In this case you
     will get the error message: `Can't start server: Bind on TCP/IP
     port: Address already in use' or `Can't start server: Bind on unix
     socket...'. *Note Multiple servers::.

*You don't have write access to `/tmp'*
     If you don't have write access to create a socket file at the
     default place (in `/tmp') or permission to create temporary files
     in `/tmp,' you will get an error when running `mysql_install_db'
     or when starting or using `mysqld'.

     You can specify a different socket and temporary directory as
     follows:

          shell> TMPDIR=/some_tmp_dir/
          shell> MYSQL_UNIX_PORT=/some_tmp_dir/mysqld.sock
          shell> export TMPDIR MYSQL_UNIX_PORT

     See *Note Problems with `mysql.sock': Problems with mysql.sock.

     `some_tmp_dir' should be the path to some directory for which you
     have write permission. *Note Environment variables::.

     After this, you should be able to run `mysql_install_db' and start
     the server with these commands:

          shell> scripts/mysql_install_db
          shell> BINDIR/mysqld_safe &

*`mysqld' crashes immediately*
     If you are running Red Hat Version 5.0 with a version of `glibc'
     older than 2.0.7-5, you should make sure you have installed all
     `glibc' patches.  There is a lot of information about this in the
     MySQL mail archives.  Links to the mail archives are available
     online at `http://lists.mysql.com/'.  Also, see *Note Linux::.

     You can also start `mysqld' manually using the
     `--skip-grant-tables' option and add the privilege information
     yourself using `mysql':

          shell> BINDIR/mysqld_safe --skip-grant-tables &
          shell> BINDIR/mysql -u root mysql

     From `mysql', manually execute the SQL commands in
     `mysql_install_db'.  Make sure you run `mysqladmin
     flush-privileges' or `mysqladmin reload' afterward to tell the
     server to reload the grant tables.

Starting and Stopping MySQL Automatically
.........................................

Generally, you start the `mysqld' server in one of these ways:

   * By invoking `mysqld' directly. This works on any platform.

   * By running the MySQL server as a Windows service.  This can be
     done on Windows NT, 2000, and XP.  For instructions, see *Note NT
     start::.

   * By invoking `mysql.server'.  This script is used primarily at
     system startup and shutdown on systems that use System V-style run
     directories. It is described more fully later in this section.

   * By invoking `mysqld_safe', which tries to determine the proper
     options for `mysqld' and then runs it with those options.  This
     script is used on systems based on BSD Unix. It also is invoked by
     `mysql.server'.  *Note `mysqld_safe': mysqld_safe.

The `mysql.server' and `mysqld_safe' scripts can be used to start the
server automatically at system startup time. `mysql.server' can also be
used to stop the server.

The `mysql.server' script can be used to start or stop the server by
invoking it with `start' or `stop' arguments:

     shell> mysql.server start
     shell> mysql.server stop

`mysql.server' can be found in the `share/mysql' directory under the
MySQL installation directory or in the `support-files' directory of the
MySQL source tree.

Note that if you use the Linux RPM package
(`MySQL-server-VERSION.rpm'), the `mysql.server' script has already
been installed as `/etc/init.d/mysql'. You don't have to install it
manually. See *Note Linux-RPM:: for more information on the Linux RPM
packages.

On Mac OS X, you can install a separate MySQL Startup Item package to
enable the automatic startup of MySQL on system bootup.  See *Note Mac
OS X installation:: for details.

Before `mysql.server' starts the server, it changes the directory to
the MySQL installation directory, then invokes `mysqld_safe'.  You
might need to edit `mysql.server' if you have a binary distribution
that you've installed in a non-standard location.  Modify it to `cd'
into the proper directory before it runs `mysqld_safe'. If you want the
server to run as some specific user, add an appropriate `user' line to
the `/etc/my.cnf' file, as shown later in this section.

`mysql.server stop' brings down the server by sending a signal to it.
You can also stop the server manually by executing `mysqladmin
shutdown'.

You need to add these start and stop commands to the appropriate places
in your `/etc/rc*' files when you want to start up MySQL automatically
on your server.

On most current Linux distributions, it is sufficient to copy the file
`mysql.server' into the `/etc/init.d' directory (or `/etc/rc.d/init.d'
on older Red Hat systems). Afterwards, run the following command to
enable the startup of MySQL on system bootup:

     shell> chkconfig --add mysql.server

On FreeBSD startup scripts generally should go in
`/usr/local/etc/rc.d/'. The `rc(8)' manual page also states that
scripts in this directory are only executed, if their basename matches
the shell globbing pattern `*.sh'. Any other files or directories
present within the directory are silently ignored. In other words, on
FreeBSD you should install the file `mysql.server' as
`/usr/local/etc/rc.d/mysql.server.sh' to enable automatic startup.

As an alternative to the above, some operating systems also use
`/etc/rc.local' or `/etc/init.d/boot.local' to start additional
services on bootup. To start up MySQL using this method, you could
append something like the following to it:

     /bin/sh -c 'cd /usr/local/mysql; ./bin/mysqld_safe --user=mysql &'

You can also add options for `mysql.server' in a global `/etc/my.cnf'
file.  A typical `/etc/my.cnf' file might look like this:

     [mysqld]
     datadir=/usr/local/mysql/var
     socket=/var/tmp/mysql.sock
     port=3306
     user=mysql

     [mysql.server]
     basedir=/usr/local/mysql

The `mysql.server' script understands the following options: `datadir',
`basedir', and `pid-file'.

The following table shows which option groups each startup script reads
from option files:

*Script*    *Option groups*
`mysqld'    `[mysqld]', `[server]' and `[mysqld-major-version]'
`mysql.server'`[mysql.server]', `[mysqld]', and `[server]'
`mysqld_safe'`[mysqld]', `[server]', and `[mysqld_safe]'

For backward compatibility, `mysql.server' also reads the
`[mysql_server]' group and `mysqld_safe' also reads the `[safe_mysqld]'
group. However, you should update your option files to use the
`[mysql.server]' and `[mysqld_safe]' groups instead.

*Note Option files::.

Starting and Troubleshooting the MySQL Server
.............................................

If you are going to use storage engines that support transactional
tables (`InnoDB', `BDB'), you should first create a `my.cnf' file and
set startup options for the engines you plan to use. *Note Table
types::.

When the `mysqld' server starts, it changes location to the data
directory.  This is where it expects to write log files and the pid
(process ID) file, and where it expects to find databases.

The data directory location is hardwired in when the distribution is
compiled.  However, if `mysqld' expects to find the data directory
somewhere other than where it really is on your system, it will not work
properly.  If you have problems with incorrect paths, you can find out
what options `mysqld' allows and what the default path settings are by
invoking `mysqld' with the `--help' option.  You can override the
defaults by specifying the correct pathnames as command-line arguments
to `mysqld'.  (These options can be used with `mysqld_safe' as well.)

Normally you should need to tell `mysqld' only the base directory under
which MySQL is installed.  You can do this with the `--basedir' option.
You can also use `--help' to check the effect of changing path options
(note that `--help' *must* be the final option of the `mysqld'
command).  For example:

     shell> EXECDIR/mysqld --basedir=/usr/local --help

Once you determine the path settings you want, start the server without
the `--help' option.

Whichever method you use to start the server, if it fails to start up
correctly, check the log file to see if you can find out why.  Log files
are located in the data directory (typically `/usr/local/mysql/data'
for a binary distribution, `/usr/local/var' for a source distribution,
and `\mysql\data\mysql.err' on Windows).  Look in the data directory for
files with names of the form `host_name.err' and `host_name.log' where
`host_name' is the name of your server host.  Then check the last few
lines of these files:

     shell> tail host_name.err
     shell> tail host_name.log

Look for something like the following in the log file:
     000729 14:50:10  bdb:  Recovery function for LSN 1 27595 failed
     000729 14:50:10  bdb:  warning: ./test/t1.db: No such file or directory
     000729 14:50:10  Can't init databases

This means that you didn't start `mysqld' with `--bdb-no-recover' and
Berkeley DB found something wrong with its log files when it tried to
recover your databases.  To be able to continue, you should move away
the old Berkeley DB log file from the database directory to some other
place, where you can later examine it.  The log files are named
`log.0000000001', where the number will increase over time.

If you are running `mysqld' with `BDB' table support and `mysqld' core
dumps at start this could be because of some problems with the `BDB'
recovery log.  In this case you can try starting `mysqld' with
`--bdb-no-recover'.  If this helps, then you should remove all `log.*'
files from the data directory and try starting `mysqld' again.

If you get the following error, it means that some other program (or
another `mysqld' server) is already using the TCP/IP port or socket
`mysqld' is trying to use:

     Can't start server: Bind on TCP/IP port: Address already in use
or:
     Can't start server: Bind on unix socket...

Use `ps' to make sure that you don't have another `mysqld' server
running.  If you can't find another server running, you can try to
execute the command `telnet your-host-name tcp-ip-port-number' and press
Enter a couple of times.  If you don't get an error message like
`telnet: Unable to connect to remote host: Connection refused',
something is using the TCP/IP port `mysqld' is trying to use.  See
*Note mysql_install_db:: and *Note Multiple servers::.

If `mysqld' is currently running, you can find out what path settings
it is using by executing this command:

     shell> mysqladmin variables

or:

     shell> mysqladmin -h 'your-host-name' variables

If you get `Errcode 13', which means `Permission denied', when starting
`mysqld' this means that you didn't have the right to read/create files
in the MySQL database or log directory. In this case you should either
start `mysqld' as the `root' user or change the permissions for the
involved files and directories so that you have the right to use them.

If `mysqld_safe' starts the server but you can't connect to it, you
should make sure you have an entry in `/etc/hosts' that looks like this:

     127.0.0.1       localhost

This problem occurs only on systems that don't have a working thread
library and for which MySQL must be configured to use MIT-pthreads.

If you can't get `mysqld' to start you can try to make a trace file to
find the problem. *Note Making trace files::.

If you are using `InnoDB' tables, refer to the `InnoDB'-specific startup
options.  *Note InnoDB start::.

If you are using `BDB' (Berkeley DB) tables, you should familiarise
yourself with the different `BDB'-specific startup options.  *Note BDB
start::.

Upgrading/Downgrading MySQL
===========================

As a general rule, we recommend that when upgrading from one release
series to another, you should go to the next series rather than
skipping a series. For example, if you currently are running MySQL 3.23
and wish to upgrade to a newer series, upgrade to MySQL 4.0 rather than
to 4.1 or 5.0.

Before you do an upgrade, you should back up your old databases.

You can always move the MySQL format files and datafiles between
different versions on the same architecture as long as you have the
same base version of MySQL. The current base version is 4. If you
change the character set when running MySQL, you must run `myisamchk -r
-q --set-character-set=charset' on all tables.  Otherwise, your indexes
may not be ordered correctly, because changing the character set may
also change the sort order.

If you are cautious about using new versions, you can always rename
your old `mysqld' to something like `mysqld-old-version-number'.  If
your new `mysqld' then does something unexpected, you can simply shut
it down and restart with your old `mysqld'.

If, after an upgrade, you experience problems with recompiled client
programs, such as `Commands out of sync' or unexpected core dumps, you
probably have used an old header or library file when compiling your
programs.  In this case you should check the date for your `mysql.h'
file and `libmysqlclient.a' library to verify that they are from the new
MySQL distribution.  If not, please recompile your programs.

If problems occur, such as that the new `mysqld' server doesn't want to
start or that you can't connect without a password, check that you don't
have some old `my.cnf' file from your old installation.  You can check
this with: `program-name --print-defaults'.  If this outputs anything
other than the program name, you have an active `my.cnf' file that
affects server operation.

It is a good idea to rebuild and reinstall the Perl `DBD::mysql' module
whenever you install a new release of MySQL. The same applies to other
MySQL interfaces as well, such as the Python `MySQLdb' module.

Upgrading from Version 4.1 to 5.0
---------------------------------

In general, you should do the following when upgrading to MySQL 5.0
from an earlier version:

   * Read the 5.0 news items to see what significant new features you
     can use in 5.0.  *Note News-5.0.x::.

   * If you are running MySQL Server on Windows, please also see *Note
     Windows upgrading::.

   * If you are using replication, please also see *Note Replication
     Upgrade:: for information on upgrading your replication setup.

   * MySQL 5.0 adds support for stored procedures. This support
     requires the `proc' table in the `mysql' database.  To create this
     file you should run the `mysql_fix_privilege_tables' script.  This
     is described in *Note Upgrading-grant-tables::.


Upgrading from Version 4.0 to 4.1
---------------------------------

Several visible behaviors have changed between MySQL 4.0 and MySQL 4.1
to fix some critical bugs and make MySQL more compatible with the ANSI
SQL standard. These changes may affect your applications.

Some of the 4.1 behaviors can be tested in 4.0 before performing a full
upgrade to 4.1. We have added to later MySQL 4.0 releases (from 4.0.12
on) a `--new' startup option for `mysqld'.

This option gives you the 4.1 behavior for the most critical changes.
You can also enable these behaviors for a given client connection with
the `SET @@new=1' command, or turn them off if they are on with `SET
@@new=0'.

If you believe that some of the 4.1 changes will affect you, we
recommend that before upgrading to 4.1, you download the latest MySQL
4.0 version and run it with the `--new' option by adding the following
to your config file:

     [mysqld-4.0]
     new

That way you can test the new behaviors in 4.0 to make sure that your
applications work with them. This will help you have a smooth painless
transition when you perform a full upgrade to 4.1 later.  Doing it the
above way will ensure that you don't accidently later run the 4.1
version with the `--new' option.

The following list describes changes that may affect applications and
that you should watch out for when upgrading to version 4.1:

   * `TIMESTAMP' is now returned as a string in `'YYYY-MM-DD HH:MM:SS''
     format.  (The `--new' option can be used from 4.0.12 on to make a
     4.0 server behave as 4.1 in this respect.)  If you want to have
     the value returned as a number (like Version 4.0 does) you should
     add +0 to `TIMESTAMP' columns when you retrieve them:

          mysql> SELECT ts_col + 0 FROM tbl_name;

     Display widths for `TIMESTAMP' columns are no longer supported.
     For example, if you declare a column as `TIMESTAMP(10)', the `(10)'
     is ignored.

     These changes were necessary for SQL standards compliance. In a
     future version, a further change will be made (backward compatible
     with this change), allowing the timestamp length to indicate the
     desired number of digits for fractions of a second.

   * Binary values such as `0xFFDF' now are assumed to be strings
     instead of numbers.  This fixes some problems with character sets
     where it's convenient to input a string as a binary value.  With
     this change, you should use `CAST()' if you want to compare binary
     values numerically as integers:

          mysql> SELECT CAST(0xFEFF AS UNSIGNED INTEGER) < CAST(0xFF AS UNSIGNED INTEGER);
                  -> 0

     If you don't use `CAST()', a lexical string comparison will be
     done:

          mysql> SELECT 0xFEFF < 0xFF;
                  -> 1

     Using binary items in a numeric context or comparing them using the
     `=' operator should work as before.  (The `--new' option can be
     used from 4.0.13 on to make a 4.0 server behave as 4.1 in this
     respect.)

   * For functions that produce a `DATE', `DATETIME', or `TIME' value,
     the result returned to the client now is fixed up to have a
     temporal type. For example, in MySQL 4.1, you get this result:

          mysql> SELECT CAST("2001-1-1" as DATETIME);
              -> '2001-01-01 00:00:00'

     In MySQL 4.0, the result is different:

          mysql> SELECT CAST("2001-1-1" as DATETIME);
              -> '2001-01-01'

   * `DEFAULT' values no longer can be specified for `AUTO_INCREMENT'
     columns. (In 4.0, a `DEFAULT' value is silently ignored; in 4.1,
     an error occurs).

   * `LIMIT' no longer accept negative arguments.  Use
     18446744073709551615 instead of -1.

   * `SERIALIZE' is no longer a valid mode value for the `sql_mode'
     variable.  You should use `SET TRANSACTION ISOLATION LEVEL
     SERIALIZABLE' instead. `SERIALIZE' is no longer valid for the
     `--sql-mode' option for `mysqld', either. Use
     `--transaction-isolation=SERIALIZABLE' instead.

   * All tables and string columns now have a character set.  *Note
     Charset::.  Character set information is displayed by `SHOW CREATE
     TABLE' and `mysqldump'.  (MySQL versions 4.0.6 and above can read
     the new dump files; older versions cannot.)

   * The table definition format used in `.frm' files has changed
     slightly in 4.1.  MySQL 4.0 versions from 4.0.11 on can read the
     new `.frm' format directly, but older versions cannot.  If you
     need to move tables from 4.1 to a version earlier than 4.0.11, you
     should use `mysqldump'.  *Note `mysqldump': mysqldump.

   * If you are running multiple servers on the same Windows machine,
     you should use a different `--shared_memory_base_name' option on
     all machines.

   * The interface to aggregated UDF functions has changed a bit. You
     must now declare a `xxx_clear()' function for each aggregate
     function `XXX()'.


In general, upgrading to 4.1 from an earlier MySQL version involves the
following steps:

   * Check the changes listed earlier in this section to see whether
     there are any that may affect your applications.

   * Read the 4.1 news items to see what significant new features you
     can use in 4.1.  *Note News-4.1.x::.

   * If you are running MySQL Server on Windows, please also see *Note
     Windows upgrading::.

     *Important note:* Early alpha Windows distributions for MySQL 4.1
     do not contain any installer program.  See *Note Windows binary
     installation:: for instructions on how to install such a
     distribution.

   * If you are using replication, please also see *Note Replication
     Upgrade:: for information on upgrading your replication setup.

   * After upgrading, update the grant tables to generate the new
     longer `Password' column that is needed for secure handling of
     passwords.  The procedure uses `mysql_fix_privilege_tables' and is
     described in *Note Upgrading-grant-tables::.


The password hashing mechanism has changed in 4.1 to provide better
security, but this may cause compatibility problems if you still have
clients that use the client library from 4.0 or earlier.  (It is very
likely that you will have 4.0 clients in situations where clients
connect from remote hosts that have not yet upgraded to 4.1).  The
following list indicates some possible upgrade strategies.  They
represent various tradeoffs between the goal of compatibility with old
clients and the goal of security.

   * Don't upgrade to 4.1. No behavior will change, but you cannot use
     any of the new features provided by the 4.1 client/server protocol,
     either.  (MySQL 4.1 has an extended client/server protocol that
     offers such features as prepared statements and multiple result
     sets.)  *Note C API Prepared statements::.

   * Upgrade to 4.1 and run the `mysql_fix_privilege_tables' script to
     widen the `Password' column in the `user' table so that it can
     hold long password hashes.  But run the server with the
     `--old-passwords' option to provide backward compatibility that
     allows pre-4.1 clients to continue to connect to their short-hash
     accounts.  Eventually, when all your clients are upgraded to 4.1,
     you can stop using the `--old-passwords' server option. You can
     also change the passwords for your MySQL accounts to use the new
     more secure format.

   * Upgrade to 4.1 and run the `mysql_fix_privilege_tables' script to
     widen the `Password' column in the `user' table.  If you know that
     all clients also have been upgraded to 4.1, don't run the server
     with the `--old-passwords' option.  Instead, change the passwords
     on all existing accounts so that they have the new format.  A
     pure-4.1 installation is the most secure.


Further background on password hashing with respect to client
authentication and password-changing operations may be found in *Note
Password hashing::.

Upgrading from Version 3.23 to 4.0
----------------------------------

In general, you should do the following when upgrading to MySQL 4.0
from an earlier version:

   * After upgrading, update the grant tables to add new privileges and
     features.  The procedure uses the `mysql_fix_privilege_tables'
     script and is described in *Note Upgrading-grant-tables::.

   * Edit any MySQL startup scripts or configure files to not use any
     of the deprecated options described later in this section.

   * Convert your old `ISAM' files to `MyISAM' files with the
     `mysql_convert_table_format database' script. (This is a Perl
     script; it requires that DBI be installed.) To convert the tables
     in a given database, use this command:

          shell> mysql_convert_table_format database db_name

     Note that this should only be used if all tables in the given
     database are `ISAM' or `MyISAM' tables. To avoid converting tables
     of other types to `MyISAM', you can explicitly list the names of
     your `ISAM' tables after the database name on the command line.
     You can also issue a `ALTER TABLE table_name TYPE=MyISAM'
     statement for each `ISAM' table to convert it to `MyISAM'.

     To find out the table type for a given table, use this statement:

          mysql> SHOW TABLE STATUS LIKE 'tbl_name';

   * Ensure that you don't have any MySQL clients that use shared
     libraries (like the Perl `DBD::mysql' module). If you do, you
     should recompile them, because the data structures used in
     `libmysqlclient.so' have changed.  The same applies to other MySQL
     interfaces as well, such as the Python `MySQLdb' module.

   * If you are running MySQL Server on Windows, please also see *Note
     Windows upgrading::.

   * If you are using replication, please also see *Note Replication
     Upgrade:: for information on upgrading your replication setup.


MySQL 4.0 will work even if you don't do the above, but you will not be
able to use the new security privileges that MySQL 4.0 and you may run
into problems when upgrading later to MySQL 4.1 or newer.  The `ISAM'
file format still works in MySQL 4.0 but it's deprecated and will be
disabled (not compiled in by default) in MySQL 4.1. `MyISAM' tables
should be used instead.

Old clients should work with a Version 4.0 server without any problems.

Even if you do the above, you can still downgrade to MySQL 3.23.52 or
newer if you run into problems with the MySQL 4.0 series.  In this
case, you must use `mysqldump' to dump any tables that use full-text
indexes and reload the dump file into the 3.23 server.  This is
necessary because 4.0 uses a new format for full-text indexing.

The following is a more complete list that tells what you must watch out
for when upgrading to version 4.0:

   * MySQL 4.0 has a lot of new privileges in the `mysql.user' table.
     *Note `GRANT': GRANT.

     To get these new privileges to work, you must update the grant
     tables.  The procedure is described in *Note
     Upgrading-grant-tables::.  Until you do this, all users have the
     `SHOW DATABASES', `CREATE TEMPORARY TABLES', and `LOCK TABLES'
     privileges. `SUPER' and `EXECUTE' privileges take their value from
     `PROCESS'.  `REPLICATION SLAVE' and `REPLICATION CLIENT' take their
     values from `FILE'.

     If you have any scripts that create new users, you may want to
     change them to use the new privileges.  If you are not using
     `GRANT' commands in the scripts, this is a good time to change
     your scripts to use `GRANT' instead of modifying the grant tables
     directly..

     From version 4.0.2 on, the option `--safe-show-database' is
     deprecated (and no longer does anything). *Note Privileges
     options::.

     If you get `Access denied' errors for new users in version 4.0.2
     and up, you should check if you need some of the new grants that
     you didn't need before.  In particular, you will need `REPLICATION
     SLAVE' (instead of `FILE') for new slaves.

   * `safe_mysqld' is renamed to `mysqld_safe'.  For backward
     compatibility, binary distributions will for some time include
     `safe_mysqld' as a symlink to `mysqld_safe'.

   * InnoDB support is now included by default in binary distributions.
     If you build MySQL from source, InnoDB is configured in by default.
     If you do not use InnoDB and want to save memory when running a
     server that has InnoDB support enabled, use the `--skip-innodb'
     server startup option. To compile MySQL without InnoDB support,
     run `configure' with the `--without-innodb' option.

   * The startup parameters `myisam_max_extra_sort_file_size' and
     `myisam_max_extra_sort_file_size' are now given in bytes (they
     were given in megabytes before 4.0.3).

   * External system locking of `MyISAM'/`ISAM' files is now turned off
     by default.  Your can turn this on by doing `--external-locking'.
     (However, this is never needed for most users.)

   * The following startup variables/options have been renamed:

     *Old Name*                         *New Name*
     `myisam_bulk_insert_tree_size'     `bulk_insert_buffer_size'
     `query_cache_startup_type'         `query_cache_type'
     `record_buffer'                    `read_buffer_size'
     `record_rnd_buffer'                `read_rnd_buffer_size'
     `sort_buffer'                      `sort_buffer_size'
     `warnings'                         `log-warnings'
     `--err-log'                        `--log-error' (for `mysqld_safe')

     The startup options `record_buffer', `sort_buffer' and `warnings'
     will still work in MySQL 4.0 but are deprecated.

   * The following SQL variables have changed name.

     *Old Name*                         *New Name*
     `SQL_BIG_TABLES'                   `BIG_TABLES'
     `SQL_LOW_PRIORITY_UPDATES'         `LOW_PRIORITY_UPDATES'
     `SQL_MAX_JOIN_SIZE'                `MAX_JOIN_SIZE'
     `SQL_QUERY_CACHE_TYPE'             `QUERY_CACHE_TYPE'
     The old names still work in MySQL 4.0 but are deprecated.

   * You have to use `SET GLOBAL SQL_SLAVE_SKIP_COUNTER=#' instead of
     `SET SQL_SLAVE_SKIP_COUNTER=#'.

   * The `mysqld' startup options `--skip-locking' and
     `--enable-locking' were renamed to `--skip-external-locking' and
     `--external-locking'.

   * `SHOW MASTER STATUS' now returns an empty set if binary logging is
     not enabled.

   * `SHOW SLAVE STATUS' now returns an empty set if slave is not
     initialized.

   * `mysqld' now has the option `--temp-pool' enabled by default as
     this gives better performance with some operating systems (most
     notably Linux).

   * `DOUBLE' and `FLOAT' columns now honor the `UNSIGNED' flag on
     storage (before, `UNSIGNED' was ignored for these columns).

   * `ORDER BY col_name DESC' sorts `NULL' values last, as of MySQL
     4.0.11. In 3.23 and in earlier 4.0 versions, this was not always
     consistent.

   * `SHOW INDEX' has two more columns (`Null' and `Index_type') than
     it had in 3.23.

   * `CHECK', `LOCALTIME' and `LOCALTIMESTAMP' are now reserved words.

   * The result of all bitwise operators (`|', `&', `<<', `>>', and
     `~')) is now unsigned.  This may cause problems if you are using
     them in a context where you want a signed result.  *Note Cast
     Functions::.

   * *Note:* when you use subtraction between integer values where one
     is of type `UNSIGNED', the result will be unsigned.  In other
     words, before upgrading to MySQL 4.0, you should check your
     application for cases where you are subtracting a value from an
     unsigned entity and want a negative answer or subtracting an
     unsigned value from an integer column. You can disable this
     behavior by using the `--sql-mode=NO_UNSIGNED_SUBTRACTION' option
     when starting `mysqld'.  *Note Cast Functions::.

   * To use `MATCH ... AGAINST (... IN BOOLEAN MODE)' with your tables,
     you need to rebuild them with `REPAIR TABLE table_name USE_FRM'.

   * `LOCATE()' and `INSTR()' are case-sensitive if one of the
     arguments is a binary string. Otherwise they are case-insensitive.

   * `STRCMP()' now uses the current character set when performing
     comparisons.  This makes the default comparison behavior case
     insensitive unless one or both of the operands are binary strings.

   * `HEX(string)' now returns the characters in `string' converted to
     hexadecimal.  If you want to convert a number to hexadecimal, you
     should ensure that you call `HEX()' with a numeric argument.

   * In 3.23, `INSERT INTO ... SELECT' always had `IGNORE' enabled.  In
     4.0.1, MySQL will stop (and possibly roll back) by default in case
     of an error unless you specify `IGNORE'.

   * The old C API functions `mysql_drop_db()', `mysql_create_db()', and
     `mysql_connect()' are no longer supported unless you compile MySQL
     with `CFLAGS=-DUSE_OLD_FUNCTIONS'.  However, it is preferable to
     change client programs to use the new 4.0 API instead.

   * In the `MYSQL_FIELD' structure, `length' and `max_length' have
     changed from `unsigned int' to `unsigned long'. This should not
     cause any problems, except that they may generate warning messages
     when used as arguments in the `printf()' class of functions.

   * You should use `TRUNCATE TABLE' when you want to delete all rows
     from a table and you don't need to obtain a count of the number of
     rows that were deleted.  (`DELETE FROM table_name' returns a row
     count in 4.0, and `TRUNCATE TABLE' is faster.)

   * You will get an error if you have an active `LOCK TABLES' or
     transaction when trying to execute `TRUNCATE TABLE' or `DROP
     DATABASE'.

   * You should use integers to store values in `BIGINT' columns
     (instead of using strings, as you did in MySQL 3.23).  Using
     strings will still work, but using integers is more efficient.

   * The format of `SHOW OPEN TABLES' has changed.

   * Multi-threaded clients should use `mysql_thread_init()' and
     `mysql_thread_end()'. *Note Threaded clients::.

   * If you want to recompile the Perl `DBD::mysql' module, use a recent
     version.  Version 2.9003 is recommended. Versions older than
     1.2218 should not be used because they use the deprecated
     `mysql_drop_db()' call.

   * `RAND(seed)' returns a different random number series in 4.0 than
     in 3.23; this was done to further differentiate `RAND(seed)' and
     `RAND(seed+1)'.

   * The default type returned by `IFNULL(A,B)' is now set to be the
     more 'general' of the types of `A' and `B'. (The
     general-to-specific order is string, `REAL' or `INTEGER').


Upgrading from Version 3.22 to 3.23
-----------------------------------

MySQL Version 3.23 supports tables of the new `MyISAM' type and the old
`ISAM' type.  You don't have to convert your old tables to use these
with Version 3.23.  By default, all new tables will be created with
type `MyISAM' (unless you start `mysqld' with the
`--default-table-type=isam' option). You can convert an `ISAM' table to
`MyISAM' format with `ALTER TABLE table_name TYPE=MyISAM' or the Perl
script `mysql_convert_table_format'.

Version 3.22 and 3.21 clients will work without any problems with a
Version 3.23 server.

The following list tells what you have to watch out for when upgrading
to Version 3.23:

   * All tables that use the `tis620' character set must be fixed with
     `myisamchk -r' or `REPAIR TABLE'.

   * If you do a `DROP DATABASE' on a symbolically linked database,
     both the link and the original database are deleted.  (This didn't
     happen in 3.22 because `configure' didn't detect the availability
     of the `readlink()' system call.)

   * `OPTIMIZE TABLE' now works only for `MyISAM' tables.  For other
     table types, you can use `ALTER TABLE' to optimize the table.
     During `OPTIMIZE TABLE', the table is now locked to prevent it
     from being used by other threads.

   * The MySQL client `mysql' is now by default started with the option
     `--no-named-commands (-g)'. This option can be disabled with
     `--enable-named-commands (-G)'. This may cause incompatibility
     problems in some cases--for example, in SQL scripts that use named
     commands without a semicolon.  Long format commands still work
     from the first line.

   * Date functions that work on parts of dates (like `MONTH()') will
     now return 0 for `0000-00-00' dates. (In MySQL 3.22, these
     functions returned `NULL'.)

   * If you are using the `german' character sort order for `ISAM'
     tables, you must repair them with `isamchk -r', because we have
     made some changes in the sort order.

   * The default return type of `IF()' now depends on both arguments
     and not only the first argument.

   * `AUTO_INCREMENT' columns should not be used to store negative
     numbers. The reason for this is that negative numbers caused
     problems when wrapping from -1 to 0.  You should not store 0 in
     `AUTO_INCREMENT' columns, either; `CHECK TABLE' will complain
     about 0 values because they may change if you dump and restore the
     table.  `AUTO_INCREMENT' for `MyISAM' tables is now handled at a
     lower level and is much faster than before. In addition, for
     `MyISAM' tables, old numbers are no longer reused, even if you
     delete rows from the table.

   * `CASE', `DELAYED', `ELSE', `END', `FULLTEXT', `INNER', `RIGHT',
     `THEN', and `WHEN' are now reserved words.

   * `FLOAT(X)' is now a true floating-point type and not a value with a
     fixed number of decimals.

   * When declaring columns using a `DECIMAL(length,dec)' type, the
     `length' argument no longer includes a place for the sign or the
     decimal point.

   * A `TIME' string must now be of one of the following formats:
     `[[[DAYS] [H]H:]MM:]SS[.fraction]' or
     `[[[[[H]H]H]H]MM]SS[.fraction]'.

   * `LIKE' now compares strings using the same character comparison
     rules as for the `=' operator.  If you require the old behavior,
     you can compile MySQL with the `CXXFLAGS=-DLIKE_CMP_TOUPPER' flag.

   * `REGEXP' is now case-insensitive if neither of the strings are
     binary strings.

   * When you check or repair `MyISAM' (`.MYI') tables, you should use
     the `CHECK TABLE' statement or the `myisamchk' command. For `ISAM'
     (`.ISM') tables, use the `isamchk' command.

   * If you want your `mysqldump' files to be compatible between MySQL
     Version 3.22 and Version 3.23, you should not use the `--opt' or
     `--all' option to `mysqldump'.

   * Check all your calls to `DATE_FORMAT()' to make sure there is a
     `%' before each format character.  (MySQL Version 3.22 and later
     already allowed this syntax.)

   * `mysql_fetch_fields_direct()' is now a function (it used to be a
     macro) and it returns a pointer to a `MYSQL_FIELD' instead of a
     `MYSQL_FIELD'.

   * `mysql_num_fields()' can no longer be used on a `MYSQL*' object
     (it's now a function that takes a `MYSQL_RES*' value as an
     argument). With a `MYSQL*' object, you should now use
     `mysql_field_count()' instead.

   * In MySQL Version 3.22, the output of `SELECT DISTINCT ...' was
     almost always sorted.  In Version 3.23, you must use `GROUP BY' or
     `ORDER BY' to obtain sorted output.

   * `SUM()' now returns `NULL' instead of 0 if there are no matching
     rows. This is required by SQL-99.

   * An `AND' or `OR' with `NULL' values will now return `NULL' instead
     of 0. This mostly affects queries that use `NOT' on an `AND/OR'
     expression as `NOT NULL' = `NULL'.

   * `LPAD()' and `RPAD()' now shorten the result string if it's longer
     than the length argument.

Upgrading from Version 3.21 to 3.22
-----------------------------------

Nothing that affects compatibility has changed between versions 3.21
and 3.22.  The only pitfall is that new tables that are created with
`DATE' type columns will use the new way to store the date. You can't
access these new columns from an old version of `mysqld'.

After installing MySQL Version 3.22, you should start the new server
and then run the `mysql_fix_privilege_tables' script. This will add the
new privileges that you need to use the `GRANT' command.  If you forget
this, you will get `Access denied' when you try to use `ALTER TABLE',
`CREATE INDEX', or `DROP INDEX'. The procedure for updating the grant
tables is described in *Note Upgrading-grant-tables::.

The C API interface to `mysql_real_connect()' has changed.  If you have
an old client program that calls this function, you must place a `0' for
the new `db' argument (or recode the client to send the `db' element
for faster connections).  You must also call `mysql_init()' before
calling `mysql_real_connect()'.  This change was done to allow the new
`mysql_options()' function to save options in the `MYSQL' handler
structure.

The `mysqld' variable `key_buffer' has been renamed to
`key_buffer_size', but you can still use the old name in your startup
files.

Upgrading from Version 3.20 to 3.21
-----------------------------------

If you are running a version older than Version 3.20.28 and want to
switch to Version 3.21, you need to do the following:

You can start the `mysqld' Version 3.21 server with the
`--old-protocol' option to use it with clients from a Version 3.20
distribution.  In this case, the new client function `mysql_errno()'
will not return any server error, only `CR_UNKNOWN_ERROR' (but it works
for client errors), and the server uses the old pre-3.21 `password()'
checking rather than the new method.

If you are *not* using the `--old-protocol' option to `mysqld', you
will need to make the following changes:

   * All client code must be recompiled. If you are using ODBC, you
     must get the new `MyODBC' 2.x driver.

   * The script `scripts/add_long_password' must be run to convert the
     `Password' field in the `mysql.user' table to `CHAR(16)'.

   * All passwords must be reassigned in the `mysql.user' table (to get
     62-bit rather than 31-bit passwords).

   * The table format hasn't changed, so you don't have to convert any
     tables.


MySQL Version 3.20.28 and above can handle the new `user' table format
without affecting clients. If you have a MySQL version earlier than
Version 3.20.28, passwords will no longer work with it if you convert
the `user' table. So to be safe, you should first upgrade to at least
Version 3.20.28 and then upgrade to Version 3.21.

The new client code works with a 3.20.x `mysqld' server, so if you
experience problems with 3.21.x, you can use the old 3.20.x server
without having to recompile the clients again.

If you are not using the `--old-protocol' option to `mysqld', old
clients will be unable to connect and will issue the following error
message:

     ERROR: Protocol mismatch. Server Version = 10 Client Version = 9

The Perl DBI interface also supports the old `mysqlperl' interface.
The only change you have to make if you use `mysqlperl' is to change
the arguments to the `connect()' function.  The new arguments are:
`host', `database', `user', and `password' (note that the `user' and
`password' arguments have changed places).

The following changes may affect queries in old applications:

   * `HAVING' must now be specified before any `ORDER BY' clause.

   * The parameters to `LOCATE()' have been swapped.

   * There are some new reserved words. The most notable are `DATE',
     `TIME', and `TIMESTAMP'.


Upgrading MySQL under Windows
-----------------------------

When upgrading MySQL under Windows, please follow these steps:

  1. Download the latest Windows distribution of MySQL.

  2. Choose a time of day with low usage, where a maintenance break is
     acceptable.

  3. Alert the users that still are active about the maintenance break.

  4. Stop the running MySQL Server (for example, with `NET STOP MySQL'
     or with the `Services' utility if you are running MySQL as a
     service, or with `mysqladmin shutdown' otherwise).

  5. Exit the `WinMySQLAdmin' program if it is running.

  6. Run the installation script of the Windows distribution, by
     clicking the "Install" button in WinZip and following the
     installation steps of the script.

     *Important note:* Early alpha Windows distributions for MySQL 4.1
     do not contain any installer program.  See *Note Windows binary
     installation:: for instructions on how to install such a
     distribution.

  7. You may either overwrite your old MySQL installation (usually
     located at `C:\mysql'), or install it into a different directory,
     such as `C:\mysql4'. Overwriting the old installation is
     recommended.

  8. Restart the server (for example, with `NET START MySQL' if you run
     MySQL as a service, or by invoking `mysqld' directly otherwise).

  9. Update the grant tables. The procedure is described in *Note
     Upgrading-grant-tables::.


Possible error situations:
     A system error has occurred.
     System error 1067 has occurred.
     The process terminated unexpectedly.

This error means that your `my.cnf' file (by default `C:\my.cnf')
contains an option that cannot be recognized by MySQL. You can verify
that this is the case by trying to restart MySQL with the `my.cnf' file
renamed, for example, to `my_cnf.old' to prevent the server from using
it.  Once you have verified it, you need to identify which option is
the culprit. Create a new `my.cnf' file and move parts of the old file
to it (restarting the server after you move each part) until you
determine which option causes server startup to fail.

Upgrading the Grant Tables
--------------------------

Some releases introduce changes to the structure of the grant tables
(the tables in the `mysql' database) to add new  privileges or
features. To make sure that your grant tables are current when you
update to a new version of MySQL, you should update your grant tables
as well.

On Unix or Unix-like systems, update the grant tables by running the
`mysql_fix_privilege_tables' script:

     shell> mysql_fix_privilege_tables

You must run this script while the server is running. It attempts to
connect to the server running on the local host as `root'.  If your
`root' account requires a password, indicate the password on the
command line.  For MySQL 4.1 and up, specify the password like this:

     shell> mysql_fix_privilege_tables --password=root_password

Prior to MySQL 4.1, specify the password like this:

     shell> mysql_fix_privilege_tables root_password

The `mysql_fix_privilege_tables' script performs any actions necessary
to convert your grant tables to the current format. You may see some
`Duplicate column name' warnings as it runs; they can be ignored.

After running the script, stop the server and restart it.

On Windows systems, there isn't an easy way to update the grant tables
until MySQL 4.0.15.  From version 4.0.15 on, MySQL distributions
include a `mysql_fix_privilege_tables.sql' SQL script that you can run
using the `mysql' client.  If your MySQL installation is located at
`C:\mysql', the commands look like this:

     C:\mysql\bin> mysql -u root -p mysql

     mysql> SOURCE C:\mysql\scripts\mysql_fix_privilege_tables.sql

If your installation is located in some other directory, adjust the
pathnames appropriately.

The `mysql' command will prompt you for the `root' password; enter it
when prompted.

As with the Unix procedure, you may see some `Duplicate column name'
warnings as `mysql' processes the statements in the
`mysql_fix_privilege_tables.sql' script; they can be ignored.

After running the script, stop the server and restart it.

Copying MySQL Databases to Another Machine
------------------------------------------

If you are using MySQL Version 3.23 or later, you can copy the `.frm',
`.MYI', and `.MYD' files for `MyISAM' tables between different
architectures that support the same floating-point format.  (MySQL
takes care of any byte-swapping issues.)  *Note `MyISAM' Tables: MyISAM.

The MySQL `ISAM' data and index files (`.ISD' and `*.ISM',
respectively) are architecture-dependent and in some cases operating
system-dependent.  If you want to move your applications to another
machine that has a different architecture or operating system than your
current machine, you should not try to move a database by simply copying
the files to the other machine. Use `mysqldump' instead.

By default, `mysqldump' will create a file containing SQL statements.
You can then transfer the file to the other machine and feed it as input
to the `mysql' client.

Try `mysqldump --help' to see what options are available.  If you are
moving the data to a newer version of MySQL, you should use `mysqldump
--opt' to take advantage of any optimizations that result in a dump
file that is smaller and can be processed faster.

The easiest (although not the fastest) way to move a database between
two machines is to run the following commands on the machine on which
the database is located:

     shell> mysqladmin -h 'other hostname' create db_name
     shell> mysqldump --opt db_name \
             | mysql -h 'other hostname' db_name

If you want to copy a database from a remote machine over a slow
network, you can use:

     shell> mysqladmin create db_name
     shell> mysqldump -h 'other hostname' --opt --compress db_name \
             | mysql db_name

You can also store the result in a file, then transfer the file to the
target machine and load the file into the database there.  For example,
you can dump a database to a file on the source machine like this:

     shell> mysqldump --quick db_name | gzip > db_name.contents.gz

(The file created in this example is compressed.) Transfer the file
containing the database contents to the target machine and run these
commands there:

     shell> mysqladmin create db_name
     shell> gunzip < db_name.contents.gz | mysql db_name

You can also use `mysqldump' and `mysqlimport' to transfer the database.
For big tables, this is much faster than simply using `mysqldump'.  In
the following commands, `DUMPDIR' represents the full pathname of the
directory you use to store the output from `mysqldump'.

First, create the directory for the output files and dump the database:

     shell> mkdir DUMPDIR
     shell> mysqldump --tab=DUMPDIR db_name

Then transfer the files in the `DUMPDIR' directory to some corresponding
directory on the target machine and load the files into MySQL there:

     shell> mysqladmin create db_name           # create database
     shell> cat DUMPDIR/*.sql | mysql db_name   # create tables in database
     shell> mysqlimport db_name DUMPDIR/*.txt   # load data into tables

Also, don't forget to copy the `mysql' database because that's where the
grant tables (`user', `db', `host') are stored.  You may have to run
commands as the MySQL `root' user on the new machine until you have the
`mysql' database in place.

After you import the `mysql' database on the new machine, execute
`mysqladmin flush-privileges' so that the server reloads the grant table
information.

Operating System Specific Notes
===============================

Linux Notes
-----------

This section discusses issues that have been found to occur on Linux.
The first few subsections describe general operating sytem-related
issues, problems that can occur when using binary or source
distributions, and post-installation issues. The remaining subsections
discuss problems that occur with Linux on specific platforms.

Note that most of these problems occur on older versions of Linux. If
you are running a recent version, you likely will see none of them.

Linux Operating System Notes
............................

MySQL needs at least Linux Version 2.0.

*Warning:* We have seen some strange problems with Linux 2.2.14 and
MySQL on SMP systems.  We also have reports from some MySQL users that
they have encountered serious stability problems using MySQL with
kernel 2.2.14.  If you are using this kernel, you should upgrade to
2.2.19 (or newer) or to a 2.4 kernel.  If you have a multiple-CPU box,
then you should seriously consider using 2.4 as this will give you a
significant speed boost.  Your system also will be more stable.

When using LinuxThreads you will see a minimum of three `mysqld'
processes running.  These are in fact threads.  There will be one
thread for the LinuxThreads manager, one thread to handle connections,
and one thread to handle alarms and signals.

Linux Binary Distribution Notes
...............................

The Linux-Intel binary and RPM releases of MySQL are configured for the
highest possible speed.  We are always trying to use the fastest stable
compiler available.

The binary release is linked with `-static', which means you do not
normally need to worry about which version of the system libraries you
have. You need not install LinuxThreads, either.  A program linked with
`-static' is slightly larger than a dynamically linked program, but
also slightly faster (3-5%).  However, one problem with a statically
linked program is that you can't use user-defined functions (UDFs).  If
you are going to write or use UDFs (this is something for C or C++
programmers only), you must compile MySQL yourself using dynamic
linking.

A known issue with binary distributions is that on older Linux systems
that use `libc' (such as Red Hat 4.x or Slackware), you will get some
non-fatal problems with hostname resolution. If your system uses `libc'
rather than `glibc2', you probably will encounter some difficulties
with hostname resolution and `getpwnam()'. This happens because `glibc'
unfortunately depends on some external libraries to implement hostname
resolution and `getpwent()', even when compiled with `-static').  These
problems manifest themselves in two ways:

   * You probably will see  the following error message when you run
     `mysql_install_db':

          Sorry, the host 'xxxx' could not be looked up

     You can deal with this by executing `mysql_install_db --force',
     which will not execute the `resolveip' test in `mysql_install_db'.
     The downside is that you can't use hostnames in the grant tables:
     Except for `localhost', you must use IP numbers instead.  If you
     are using an old version of MySQL that doesn't support `--force',
     you must manually remove the `resolveip' test in `mysql_install'
     using an editor.

   * You also may see the following error when you try to run `mysqld'
     with the `--user' option:

          getpwnam: No such file or directory

     To work around this, start `mysqld' with `su' rather than by
     specifying the `--user' option. This causes the system itself to
     change the user ID of the `mysqld' process so that `mysqld' need
     not do so.


Another solution, which solves both problems, is to not use a binary
distribution.  Get a MySQL source distribution (an RPM or the `tar.gz'
distribution) and install that instead.

On some Linux 2.2 versions, you may get the error `Resource temporarily
unavailable' when clients make a lot of new connections to a `mysqld'
server over TCP/IP.  The problem is that Linux has a delay between the
time that you close a TCP/IP socket and the time that the system
actually frees it.  There is only room for a finite number of TCP/IP
slots, so you will encounter the resource-unavailable error if clients
attempt too many new TCP/IP connections during a short time. For
example, you may see the error when you run the MySQL `test-connect'
benchmark over TCP/IP.

We have inquired about this problem a few times on different Linux
mailing lists but have never been able to find a suitable resolution.
The only known "fix" is for the clients to use persistent connections,
or, if you are running the database server and clients on the same
machine, to use Unix socket file connections rather than TCP/IP
connections.

Linux Source Distribution Notes
...............................

The following notes regarding `glibc' apply only to the situation when
you build MySQL yourself. If you are running Linux on an x86 machine,
in most cases it is much better for you to just use our binary. We link
our binaries against the best patched version of `glibc' we can come up
with and with the best compiler options, in an attempt to make it
suitable for a high-load server.  For a typical user, even for setups
with a lot of concurrent connections or tables exceeding the 2G limit,
our binary is the best choice in most cases.  After reading the
following text, if you are in doubt about what to do, try our binary
first to see whether it meets your needs.  If you discover that our
binary is not good enough, then you may want to try your own build.  In
that case, we would appreciate a note about it, so we can build a
better binary next time.

MySQL uses LinuxThreads on Linux.  If you are using an old Linux
version that doesn't have `glibc2', you must install LinuxThreads
before trying to compile MySQL.   You can get LinuxThreads at
`http://www.mysql.com/downloads/os-linux.html'.

Note that `glibc' versions before and including Version 2.1.1 have a
fatal bug in `pthread_mutex_timedwait()' handling, which is used when
you issue `INSERT DELAYED' statements.  We recommend that you not use
`INSERT DELAYED' before upgrading `glibc'.

Note that Linux kernel and the LinuxThread library can by default only
have 1024 threads.  If you plan to have more than 1000 concurrent
connections, you will need to make some changes to LinuxThreads:

   * Increase `PTHREAD_THREADS_MAX' in
     `sysdeps/unix/sysv/linux/bits/local_lim.h' to 4096 and decrease
     `STACK_SIZE' in `linuxthreads/internals.h' to 256 KB. The paths
     are relative to the root of `glibc'. (Note that MySQL will not be
     stable with around 600-1000 connections if `STACK_SIZE' is the
     default of 2 MB.)

   * Recompile LinuxThreads to produce a new `libpthread.a' library,
     and relink MySQL against it.


The page `http://www.volano.com/linuxnotes.html' contains additional
information about circumventing thread limits in LinuxThreads.

There is another issue that greatly hurts MySQL performance, especially
on SMP systems.  The mutex implementation in LinuxThreads in `glibc'
2.1 is very bad for programs with many threads that hold the mutex only
for a short time.  This produces a paradoxical result: If you link
MySQL against an unmodified LinuxThreads, removing processors from an
SMP actually improves MySQL performance in many cases.  We have made a
patch available for `glibc' 2.1.3 to correct this behavior
(`http://www.mysql.com/Downloads/Linux/linuxthreads-2.1-patch').

With `glibc' 2.2.2, MySQL version 3.23.36 will use the adaptive mutex,
which is much better than even the patched one in `glibc' 2.1.3. Be
warned, however, that under some conditions, the current mutex code in
`glibc' 2.2.2 overspins, which hurts MySQL performance. The likelihood
that this condition will occur can be reduced by renicing the `mysqld'
process to the highest priority. We have also been able to correct the
overspin behavior with a patch, available at
`http://www.mysql.com/Downloads/Linux/linuxthreads-2.2.2.patch'.  It
combines the correction of overspin, maximum number of threads, and
stack spacing all in one. You will need to apply it in the
`linuxthreads' directory with `patch -p0
</tmp/linuxthreads-2.2.2.patch'.  We hope it will be included in some
form in future releases of `glibc' 2.2. In any case, if you link
against `glibc' 2.2.2, you still need to correct `STACK_SIZE' and
`PTHREAD_THREADS_MAX'. We hope that the defaults will be corrected to
some more acceptable values for high-load MySQL setup in the future, so
that the commands needed to produce your own build can be reduced to
`./configure; make; make install'.

We recommend that you use the above patches to build a special static
version of `libpthread.a' and use it only for statically linking
against MySQL. We know that the patches are safe for MySQL and
significantly improve its performance, but we cannot say anything about
other applications. If you link other applications that require
LinuxThreads against the patched static version of the library, or
build a patched shared version and install it on your system, you are
doing it at your own risk.

If you experience any strange problems during the installation of
MySQL, or with some common utilities hanging, it is very likely that
they are either library or compiler related. If this is the case, using
our binary will resolve them.

If you link your own MySQL client programs, you may see the following
error at runtime:

     ld.so.1: fatal: libmysqlclient.so.#:
     open failed: No such file or directory

This problem can be avoided by one of the following methods:

   * Link clients with the `-Wl,r/full-path-to-libmysqlclient.so' flag
     rather than with `-Lpath').

   * Copy `libmysqclient.so' to `/usr/lib'.

   * Add the pathname of the directory where `libmysqlclient.so' is
     located to the `LD_RUN_PATH' environment variable before running
     your client.

If you are using the Fujitsu compiler (`fcc/FCC'), you will have some
problems compiling MySQL because the Linux header files are very `gcc'
oriented.  The following `configure' line should work with `fcc/FCC':

     CC=fcc CFLAGS="-O -K fast -K lib -K omitfp -Kpreex -D_GNU_SOURCE \
         -DCONST=const -DNO_STRTOLL_PROTO" \
     CXX=FCC CXXFLAGS="-O -K fast -K lib \
         -K omitfp -K preex --no_exceptions --no_rtti -D_GNU_SOURCE \
         -DCONST=const -Dalloca=__builtin_alloca -DNO_STRTOLL_PROTO \
         '-D_EXTERN_INLINE=static __inline'" \
     ./configure \
         --prefix=/usr/local/mysql --enable-assembler \
         --with-mysqld-ldflags=-all-static --disable-shared \
         --with-low-memory

Linux Post-installation Notes
.............................

`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.  You can install it as `/etc/init.d/mysql' for
automatic MySQL startup and shutdown.  *Note Automatic start::.

If MySQL can't open enough files or connections, it may be that you
haven't configured Linux to handle enough files.

In Linux 2.2 and onward, you can check the number of allocated file
handles as follows:

     shell> cat /proc/sys/fs/file-max
     shell> cat /proc/sys/fs/dquot-max
     shell> cat /proc/sys/fs/super-max

If you have more than 16 MB of memory, you should add something like the
following to your init scripts (for example, `/etc/init.d/boot.local'
on SuSE Linux):

     echo 65536 > /proc/sys/fs/file-max
     echo 8192 > /proc/sys/fs/dquot-max
     echo 1024 > /proc/sys/fs/super-max

You can also run the `echo' commands from the command line as `root',
but these settings will be lost the next time your computer reboots.

Alternatively, you can set these parameters on bootup by using the
`sysctl' tool, which is used by many Linux distributions (SuSE has
added it as well, beginning with SuSE Linux 8.0). Just put the following
values into a file named `/etc/sysctl.conf':

     # Increase some values for MySQL
     fs.file-max = 65536
     fs.dquot-max = 8192
     fs.super-max = 1024

You should also add the following to `/etc/my.cnf':

     [mysqld_safe]
     open-files-limit=8192

This should allow the server a limit of 8192 for the combined number of
connections and open files.

The `STACK_SIZE' constant in LinuxThreads controls the spacing of thread
stacks in the address space.  It needs to be large enough so that there
will be plenty of room for the stack of each individual thread, but
small enough to keep the stack of some threads from running into the
global `mysqld' data.  Unfortunately, as we have experimentally
discovered, the Linux implementation of `mmap()' will successfully
unmap an already mapped region if you ask it to map out an address
already in use, zeroing out the data on the entire page, instead of
returning an error.  So, the safety of `mysqld' or any other threaded
application depends on "gentlemanly" behavior of the code that creates
threads.  The user must take measures to make sure the number of
running threads at any time is sufficiently low for thread stacks to
stay away from the global heap.  With `mysqld', you should enforce this
behavior by setting a reasonable value for the `max_connections'
variable.

If you build MySQL yourself, you can patch LinuxThreads for better
stack use.  *Note Source notes-Linux::.  If you do not want to patch
LinuxThreads, you should set `max_connections' to a value no higher
than 500.  It should be even less if you have a large key buffer,  large
heap tables, or some other things that make `mysqld' allocate a lot of
memory, or if you are running a 2.2 kernel with a 2G patch. If you are
using our binary or RPM version 3.23.25 or later, you can safely set
`max_connections' at 1500, assuming no large key buffer or heap tables
with lots of data.  The more you reduce `STACK_SIZE' in LinuxThreads
the more threads you can safely create.  We recommend values between
128K and 256K.

If you use a lot of concurrent connections, you may suffer from a
"feature" in the 2.2 kernel that attempts to prevent fork bomb attacks
by penalizing a process for forking or cloning a child.  This causes
MySQL not to scale well as you increase the number of concurrent
clients.  On single-CPU systems, we have seen this manifested as very
slow thread creation: It may take a long time to connect to MySQL (as
long as 1 minute), and it may take just as long to shut it down.  On
multiple-CPU systems, we have observed a gradual drop in query speed as
the number of clients increases.  In the process of trying to find a
solution, we have received a kernel patch from one of our users who
claimed it made a lot of difference for his site.  The patch is
available at `http://www.mysql.com/Downloads/Patches/linux-fork.patch'.
We have now done rather extensive testing of this patch on both
development and production systems.  It has significantly improved
MySQL performance without causing any problems and we now recommend it
to our users who still run high-load servers on 2.2 kernels.

This issue has been fixed in the 2.4 kernel, so if you are not satisfied
with the current performance of your system, rather than patching your
2.2 kernel, it might be easier to upgrade to 2.4. On SMP systems,
upgrading also will give you a nice SMP boost in addition to fixing the
fairness bug.

We have tested MySQL on the 2.4 kernel on a 2-CPU machine and found
MySQL scales *much* better. There was virtually no slowdown on query
throughput all the way up to 1000 clients, and the MySQL scaling factor
(computed as the ratio of maximum throughput to the throughput for one
client) was 180%.  We have observed similar results on a 4-CPU system:
Virtually no slowdown as the number of clients was increased up to 1000,
and a 300% scaling factor. Based on these results, for a high-load SMP
server using a 2.2 kernel, we definitely recommend upgrading to the 2.4
kernel at this point.

We have discovered that it is essential to run `mysqld' process with
the highest possible priority on the 2.4 kernel to achieve maximum
performance.  This can be done by adding a `renice -20 $$' command to
`mysqld_safe'. In our testing on a 4-CPU machine, increasing the
priority gave 60% throughput increase with 400 clients.

We are currently also trying to collect more information on how well
MySQL performs on 2.4 kernel on 4-way and 8-way systems. If you have
access such a system and have done some benchmarks, please send an email
message to <[e-mail]> with the results. We will review them
for inclusion in the manual.

If you see a dead `mysqld' server process with `ps', this usually means
that you have found a bug in MySQL or you have a corrupted table. *Note
Crashing::.

To get a core dump on Linux if `mysqld' dies with a `SIGSEGV' signal,
you can start `mysqld' with the `--core-file' option.  Note that you
also probably need to raise the `core file size' by adding `ulimit -c
1000000' to `mysqld_safe' or starting `mysqld_safe' with
`--core-file-size=1000000'.  *Note `mysqld_safe': mysqld_safe.

Linux x86 Notes
...............

MySQL requires `libc' Version 5.4.12 or newer. It's known to work with
`libc' 5.4.46.  `glibc' Version 2.0.6 and later should also work. There
have been some problems with the `glibc' RPMs from Red Hat, so if you
have problems, check whether there are any updates.  The `glibc'
2.0.7-19 and 2.0.7-29 RPMs are known to work.

If you are using Red Hat 8.0 or a new `glibc' 2.2.x library, you may see
`mysqld' die in `gethostbyaddr()'. This happens because the new `glibc'
library requires a stack size greater than 128K for this call.  To fix
the problem, start `mysqld' with the `--thread-stack=192K' option.
(Use `-O thread_stack=192K' before MySQL 4.)  This stack size is now
the default on MySQL 4.0.10 and above, so you should not see the
problem.

If you are using `gcc' 3.0 and above to compile MySQL, you must install
the `libstdc++v3' library before compiling MySQL; if you don't do this,
you will get an error about a missing `__cxa_pure_virtual' symbol
during linking.

On some older Linux distributions, `configure' may produce an error
like this:

     Syntax error in sched.h. Change _P to __P in the
     /usr/include/sched.h file.
     See the Installation chapter in the Reference Manual.

Just do what the error message says. Add an extra underscore to the
`_P' macro name that has only one underscore, then try again.

You may get some warnings when compiling. Those shown here can be
ignored:

     mysqld.cc -o objs-thread/mysqld.o
     mysqld.cc: In function `void init_signals()':
     mysqld.cc:315: warning: assignment of negative value `-1' to
     `long unsigned int'
     mysqld.cc: In function `void * signal_hand(void *)':
     mysqld.cc:346: warning: assignment of negative value `-1' to
     `long unsigned int'

If `mysqld' always dumps core when it starts, the problem may be that
you have an old `/lib/libc.a'.  Try renaming it, then remove
`sql/mysqld' and do a new `make install' and try again.  This problem
has been reported on some Slackware installations.

If you get the following error when linking `mysqld', it means that
your `libg++.a' is not installed correctly:

     /usr/lib/libc.a(putc.o): In function `_IO_putc':
     putc.o(.text+0x0): multiple definition of `_IO_putc'

You can avoid using `libg++.a' by running `configure' like this:

     shell> CXX=gcc ./configure

Linux SPARC Notes
.................

In some implementations, `readdir_r()' is broken.  The symptom is that
the `SHOW DATABASES' statement always returns an empty set.  This can
be fixed by removing `HAVE_READDIR_R' from `config.h' after configuring
and before compiling.

Linux Alpha Notes
.................

MySQL Version 3.23.12 is the first MySQL version that is tested on
Linux-Alpha.  If you plan to use MySQL on Linux-Alpha, you should
ensure that you have this version or newer.

We have tested MySQL on Alpha with our benchmarks and test suite, and
it appears to work nicely.

We currently build the MySQL binary packages on SuSE Linux 7.0 for AXP,
kernel 2.4.4-SMP, Compaq C compiler (V6.2-505) and Compaq C++ compiler
(V6.3-006) on a Compaq DS20 machine with an Alpha EV6 processor.

You can find the above compilers at
`http://www.support.compaq.com/alpha-tools/'.  By using these compilers
rather than `gcc', we get about 9-14% better MySQL performance.

Note that until MySQL version 3.23.52 and 4.0.2, we optimized the
binary for the current CPU only (by using the `-fast' compile option).
This means that for older versions, you can use our Alpha binaries only
if you have an Alpha EV6 processor.

For all following releases, we added the `-arch generic' flag to our
compile options, which makes sure the binary runs on all Alpha
processors. We also compile statically to avoid library problems.  The
`configure' command looks like this:

     CC=ccc CFLAGS="-fast -arch generic" CXX=cxx \
     CXXFLAGS="-fast -arch generic -noexceptions -nortti" \
     ./configure --prefix=/usr/local/mysql --disable-shared \
         --with-extra-charsets=complex --enable-thread-safe-client \
         --with-mysqld-ldflags=-non_shared --with-client-ldflags=-non_shared

If you want to use `egcs', the following `configure' line worked for us:

     CFLAGS="-O3 -fomit-frame-pointer" CXX=gcc \
     CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \
         -fno-exceptions -fno-rtti" \
     ./configure --prefix=/usr/local/mysql --disable-shared

Some known problems when running MySQL on Linux-Alpha:

   * Debugging threaded applications like MySQL will not work with `gdb
     4.18'.  You should use `gdb' 5.1 instead!

   * If you try linking `mysqld' statically when using `gcc', the
     resulting image will dump core at startup time.  In other words,
     *don't* use `--with-mysqld-ldflags=-all-static' with `gcc'.

Linux PowerPC Notes
...................

MySQL should work on MkLinux with the newest `glibc' package (tested
with `glibc' 2.0.7).

Linux MIPS Notes
................

To get MySQL to work on Qube2 (Linux Mips), you need the newest `glibc'
libraries. `glibc-2.0.7-29C2' is known to work.  You must also use the
`egcs' C++ compiler (`egcs-1.0.2-9', `gcc 2.95.2' or newer).

Linux IA-64 Notes
.................

To get MySQL to compile on Linux IA-64, we use the following `configure'
command for building with `gcc' 2.96:

     CC=gcc \
     CFLAGS="-O3 -fno-omit-frame-pointer" \
     CXX=gcc \
     CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \
         -fno-exceptions -fno-rtti" \
     ./configure --prefix=/usr/local/mysql \
         "--with-comment=Official MySQL binary" \
         --with-extra-charsets=complex

On IA-64, the MySQL client binaries use shared libraries. This means
that if you install our binary distribution at a location other than
`/usr/local/mysql', you need to add the path of the directory where you
have `libmysqlclient.so' installed either to the `/etc/ld.so.conf' file
or to the value of your `LD_LIBRARY_PATH' environment variable.

*Note Link errors::.

Mac OS X Notes
--------------

On Mac OS X, `tar' cannot handle long filenames. If you need to unpack a
`.tar.gz' distribution, use `gnutar' instead.

Mac OS X 10.x (Darwin)
......................

MySQL should work without any problems on Mac OS X 10.x (Darwin).

Our binary for Mac OS X is compiled on Darwin 6.3 with the following
`configure' line:

     CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc \
     CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \
         -fno-exceptions -fno-rtti" \
     ./configure --prefix=/usr/local/mysql \
         --with-extra-charsets=complex --enable-thread-safe-client \
         --enable-local-infile --disable-shared

*Note Mac OS X installation::.

Mac OS X Server 1.2 (Rhapsody)
..............................

For current versions of Mac OS X Server, no operating system changes are
necessary before compiling MySQL.  Compiling for the Server platform is
the same as for the client version of Mac OS X. (However, note that
MySQL comes preinstalled on Mac OS X Server, so you need not build it
yourself.)

For older versions (Mac OS X Server 1.2, a.k.a. Rhapsody), you must
first install a pthread package before trying to configure MySQL.

*Note Mac OS X installation::.

Solaris Notes
-------------

On Solaris, you may run into trouble even before you get the MySQL
distribution unpacked!  Solaris `tar' can't handle long file names, so
you may see an error like this when you unpack MySQL:

     x mysql-3.22.12-beta/bench/Results/ATIS-mysql_odbc-NT_4.0-cmp-db2,\
     informix,ms-sql,mysql,oracle,solid,sybase, 0 bytes, 0 tape blocks
     tar: directory checksum error

In this case, you must use GNU `tar' (`gtar') to unpack the
distribution.  You can find a precompiled copy for Solaris at
`http://www.mysql.com/downloads/os-solaris.html'.

Sun native threads only work on Solaris 2.5 and higher.  For Version
2.4 and earlier, MySQL will automatically use MIT-pthreads.  *Note
MIT-pthreads::.

If you get the following error from `configure', it means that you have
something wrong with your compiler installation:

     checking for restartable system calls... configure: error can not
     run test programs while cross compiling

In this case you should upgrade your compiler to a newer version.  You
may also be able to solve this problem by inserting the following row
into the `config.cache' file:

     ac_cv_sys_restartable_syscalls=${ac_cv_sys_restartable_syscalls='no'}

If you are using Solaris on a SPARC, the recommended compiler is `gcc'
2.95.2 or 3.2. You can find this at `http://gcc.gnu.org/'.  Note that
`egcs' 1.1.1 and `gcc' 2.8.1 don't work reliably on SPARC!

The recommended `configure' line when using `gcc' 2.95.2 is:

     CC=gcc CFLAGS="-O3" \
     CXX=gcc CXXFLAGS="-O3 -felide-constructors -fno-exceptions -fno-rtti" \
     ./configure --prefix=/usr/local/mysql --with-low-memory \
     --enable-assembler

If you have an UltraSPARC system, you can get 4% better performance by
adding `-mcpu=v8 -Wa,-xarch=v8plusa' to the `CFLAGS' and `CXXFLAGS'
environment variables.

If you have Sun's Forte 5.0 (or newer) compiler, you can run
`configure' like this:

     CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt" \
     CXX=CC CXXFLAGS="-noex -mt" \
     ./configure --prefix=/usr/local/mysql --enable-assembler

To create a 64-bit binary with Sun's Forte compiler, use the following
configuration options:

     CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt -xarch=v9" \
     CXX=CC CXXFLAGS="-noex -mt -xarch=v9" ASFLAGS="-xarch=v9" \
     ./configure --prefix=/usr/local/mysql --enable-assembler

To create a 64bit Solaris binary using `gcc', add `-m64' to `CFLAGS'
and `CXXFLAGS'. Note that this works only with MySQL 4.0 and up - MySQL
3.23 does not include the required modifications to support this.

In the MySQL benchmarks, we got a 4% speedup on an UltraSPARC when using
Forte 5.0 in 32-bit mode compared to using `gcc' 3.2 with `-mcpu' flags.

If you create a 64-bit `mysqld' binary, it is 4% slower than the 32-bit
binary, but can handle more threads and memory.

If you get a problem with `fdatasync' or `sched_yield', you can fix
this by adding `LIBS=-lrt' to the configure line

For older compilers than WorkShop 5.3, you may have to edit the
`configure' script to change this line:

     #if !defined(__STDC__) || __STDC__ != 1

To this:

     #if !defined(__STDC__)

If you turn on `__STDC__' with the `-Xc' option, the Sun compiler can't
compile with the Solaris `pthread.h' header file.  This is a Sun bug
(broken compiler or broken include file).

If `mysqld' issues the following error message when you run it, you have
tried to compile MySQL with the Sun compiler without enabling the
multi-thread option (`-mt'):

     libc internal error: _rmutex_unlock: rmutex not held

Add `-mt' to `CFLAGS' and `CXXFLAGS' and recompile.

If you are using the SFW version of `gcc' (which comes with Solaris 8),
you must add `/opt/sfw/lib' to the environment variable
`LD_LIBRARY_PATH' before running `configure'.

If you are using the `gcc' available from `sunfreeware.com', you may
have many problems.  To avoid this, you should recompile `gcc' and GNU
`binutils' on the machine where you will be running them.

If you get the following error when compiling MySQL with `gcc', it
means that your `gcc' is not configured for your version of Solaris:

     shell> gcc -O3 -g -O2 -DDBUG_OFF  -o thr_alarm ...
     ./thr_alarm.c: In function `signal_hand':
     ./thr_alarm.c:556: too many arguments to function `sigwait'

The proper thing to do in this case is to get the newest version of
`gcc' and compile it with your current `gcc' compiler!  At least for
Solaris 2.5, almost all binary versions of `gcc' have old, unusable
include files that will break all programs that use threads, and
possibly other programs!

Solaris doesn't provide static versions of all system libraries
(`libpthreads' and `libdl'), so you can't compile MySQL with
`--static'.  If you try to do so, you will get one of the following
errors:

     ld: fatal: library -ldl: not found
     undefined reference to `dlopen'
     cannot find -lrt

If you link your own MySQL client programs, you may see the following
error at runtime:

     ld.so.1: fatal: libmysqlclient.so.#:
     open failed: No such file or directory

This problem can be avoided by one of the following methods:

   * Link clients with the `-Wl,r/full-path-to-libmysqlclient.so' flag
     rather than with `-Lpath').

   * Copy `libmysqclient.so' to `/usr/lib'.

   * Add the pathname of the directory where `libmysqlclient.so' is
     located to the `LD_RUN_PATH' environment variable before running
     your client.

If you have problems with `configure' trying to link with `-lz' when
you don't have `zlib' installed, you have two options:

   * If you want to be able to use the compressed communication
     protocol, you need to get and install `zlib' from `ftp.gnu.org'.

   * Run `configure' with the `--with-named-z-libs=no' option when
     building MySQL.

If you are using `gcc' and have problems with loading user-defined
functions (UDFs) into MySQL, try adding `-lgcc' to the link line for
the UDF.

If you would like MySQL to start automatically, you can copy
`support-files/mysql.server' to `/etc/init.d' and create a symbolic
link to it named `/etc/rc3.d/S99mysql.server'.

If too many processes try to connect very rapidly to `mysqld', you will
see this error in the MySQL log:

     Error in accept: Protocol error

You might try starting the server with the `--back_log=50' option as a
workaround for this.  (Use `-O back_log=50' before MySQL 4.)

Solaris doesn't support core files for `setuid()' applications, so you
can't get a core file from `mysqld' if you are using the `--user'
option.

Solaris 2.7/2.8 Notes
.....................

You can normally use a Solaris 2.6 binary on Solaris 2.7 and 2.8.  Most
of the Solaris 2.6 issues also apply for Solaris 2.7 and 2.8.

MySQL Version 3.23.4 and above should be able to detect new versions of
Solaris automatically and enable workarounds for the following problems!

Solaris 2.7 / 2.8 has some bugs in the include files.  You may see the
following error when you use `gcc':

     /usr/include/widec.h:42: warning: `getwc' redefined
     /usr/include/wchar.h:326: warning: this is the location of the previous
     definition

If this occurs, you can fix the problem by copying
`/usr/include/widec.h' to `.../lib/gcc-lib/os/gcc-version/include' and
changing line 41 from this:

     #if     !defined(lint) && !defined(__lint)

To this:

     #if     !defined(lint) && !defined(__lint) && !defined(getwc)

Alternatively, you can edit `/usr/include/widec.h' directly.  Either
way, after you make the fix, you should remove `config.cache' and run
`configure' again!

If you get the following errors when you run `make', it's because
`configure' didn't detect the `curses.h' file (probably because of the
error in `/usr/include/widec.h'):

     In file included from mysql.cc:50:
     /usr/include/term.h:1060: syntax error before `,'
     /usr/include/term.h:1081: syntax error before `;'

The solution to this is to do one of the following:

   * Configure with `CFLAGS=-DHAVE_CURSES_H CXXFLAGS=-DHAVE_CURSES_H
     ./configure'.

   * Edit `/usr/include/widec.h' as indicated above and re-run
     `configure'.

   * Remove the `#define HAVE_TERM' line from the `config.h' file and
     run `make' again.

If your linker can't find `-lz' when linking client programs, the
problem is probably that your `libz.so' file is installed in
`/usr/local/lib'.  You can fix this by one of the following methods:

   * Add `/usr/local/lib' to `LD_LIBRARY_PATH'.

   * Add a link to `libz.so' from `/lib'.

   * If you are using Solaris 8, you can install the optional `zlib'
     from your Solaris 8 CD distribution.

   * Run `configure' with the `--with-named-z-libs=no' option when
     building MySQL.

Solaris x86 Notes
.................

On Solaris 8 on x86, `mysqld' will dump core if you remove the debug
symbols using `strip'.

If you are using `gcc' or `egcs' on Solaris x86 and you experience
problems with core dumps under load, you should use the following
`configure' command:

     CC=gcc CFLAGS="-O3 -fomit-frame-pointer -DHAVE_CURSES_H" \
     CXX=gcc \
     CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \
         -fno-exceptions -fno-rtti -DHAVE_CURSES_H" \
     ./configure --prefix=/usr/local/mysql

This will avoid problems with the `libstdc++' library and with C++
exceptions.

If this doesn't help, you should compile a debug version and run it
with a trace file or under `gdb'.  *Note Using `gdb' on `mysqld': Using
gdb on mysqld.

BSD Notes
---------

This section provides information about using MySQL on BSD variants.

FreeBSD Notes
.............

FreeBSD 4.x or newer is recommended for running MySQL, because the
thread package is much more integrated.  To get a secure and stable
system, you should use only FreeBSD kernels that are marked `-RELEASE'.

The easiest (and preferred) way to install MySQL is to use the
`mysql-server' and `mysql-client' ports available at
`http://www.freebsd.org/'.  Using these ports gives you the following
benefits:

   * A working MySQL with all optimizations enabled that are known to
     work on your version of FreeBSD.

   * Automatic configuration and build.

   * Startup scripts installed in `/usr/local/etc/rc.d'.

   * The ability to use `pkg_info -L' to see which files are installed.

   * The ability to use `pkg_delete' to remove MySQL if you no longer
     want it on your machine.

It is recommended you use MIT-pthreads on FreeBSD 2.x, and native
threads on Versions 3 and up. It is possible to run with native threads
on some late 2.2.x versions but you may encounter problems shutting
down `mysqld'.

Unfortunately, certain function calls on FreeBSD are not yet fully
thread-safe.  Most notably, this includes the `gethostbyname()'
function, which is used by MySQL to convert hostnames into IP
addresses. Under certain circumstances, the `mysqld' process will
suddenly cause 100% CPU load and will be unresponsive. If you encounter
this problem, try to start up MySQL using the `--skip-name-resolve'
option.

Alternatively, you can link MySQL on FreeBSD 4.x against the
LinuxThreads library, which avoids a few of the problems that the
native FreeBSD thread implementation has. For a very good comparison of
LinuxThreads vs. native threads, see Jeremy Zawodny's article `FreeBSD
or Linux for your MySQL Server?' at
`http://jeremy.zawodny.com/blog/archives/000697.html'.

A known problem when using LinuxThreads on FreeBSD is that
`wait_timeout' is not working (probably a signal handling problem in
FreeBSD/LinuxThreads).  This is supposed to be fixed in FreeBSD 5.0.
The symptom is that persistent connections can hang for a very long
time without getting closed down.

The MySQL build process require GNU make (`gmake') to work.  If GNU
`make' is not available, you must install it first before compiling
MySQL.

The recommended way to compile and install MySQL on FreeBSD with `gcc'
(2.95.2 and up) is:

     shell> CC=gcc CFLAGS="-O2 -fno-strength-reduce" \
                CXX=gcc CXXFLAGS="-O2 -fno-rtti -fno-exceptions \
                -felide-constructors -fno-strength-reduce" \
                ./configure --prefix=/usr/local/mysql --enable-assembler
     shell> gmake
     shell> gmake install
     shell> cd /usr/local/mysql
     shell> bin/mysql_install_db
     shell> bin/mysqld_safe &

If you notice that `configure' will use MIT-pthreads, you should read
the MIT-pthreads notes.  *Note MIT-pthreads::.

If you get an error from `make install' that it can't find
`/usr/include/pthreads', `configure' didn't detect that you need
MIT-pthreads. To fix this problem, remove `config.cache', then re-run
`configure' with the `--with-mit-threads' option.

Be sure your name resolver setup is correct.  Otherwise, you may
experience resolver delays or failures when connecting to `mysqld'.
Also make sure that the `localhost' entry in the `/etc/hosts' file is
correct.  The file should start with a line similar to this:

     127.0.0.1       localhost localhost.your.domain

FreeBSD is known to have a very low default file handle limit.  *Note
Not enough file handles::.  Start the server by using the
`--open-files-limit' option for `mysqld_safe', or raise the limits for
the `mysqld' user in `/etc/login.conf' and rebuild it with `cap_mkdb
/etc/login.conf'.  Also be sure you set the appropriate class for this
user in the password file if you are not using the default (use `chpass
mysqld-user-name').  *Note `mysqld_safe': mysqld_safe.

If you have a lot of memory, you should consider rebuilding the kernel
to allow MySQL to use more than 512M of RAM.  Take a look at `option
MAXDSIZ' in the LINT config file for more information.

If you get problems with the current date in MySQL, setting the `TZ'
variable will probably help.  *Note Environment variables::.

NetBSD Notes
............

To compile on NetBSD you need GNU `make'. Otherwise, the build process
will fail when `make' tries to run `lint' on C++ files.

OpenBSD 2.5 Notes
.................

On OpenBSD Version 2.5, you can compile MySQL with native threads with
the following options:

     CFLAGS=-pthread CXXFLAGS=-pthread ./configure --with-mit-threads=no

OpenBSD 2.8 Notes
.................

Our users have reported that OpenBSD 2.8 has a threading bug which
causes problems with MySQL.  The OpenBSD Developers have fixed the
problem, but as of January 25th, 2001, it's only available in the
"-current" branch.  The symptoms of this threading bug are: slow
response, high load, high CPU usage, and crashes.

If you get an error like `Error in accept:: Bad file descriptor' or
error 9 when trying to open tables or directories, the problem is
probably that you haven't allocated enough file descriptors for MySQL.

In this case, try starting `mysqld_safe' as `root' with the following
options:

     shell> mysqld_safe --user=mysql --open-files-limit=2048 &

BSD/OS Version 2.x Notes
........................

If you get the following error when compiling MySQL, your `ulimit'
value for virtual memory is too low:

     item_func.h: In method `Item_func_ge::Item_func_ge(const Item_func_ge &)':
     item_func.h:28: virtual memory exhausted
     make[2]: *** [item_func.o] Error 1

Try using `ulimit -v 80000' and run `make' again.  If this doesn't work
and you are using `bash', try switching to `csh' or `sh'; some BSDI
users have reported problems with `bash' and `ulimit'.

If you are using `gcc', you may also use have to use the
`--with-low-memory' flag for `configure' to be able to compile
`sql_yacc.cc'.

If you get problems with the current date in MySQL, setting the `TZ'
variable will probably help.  *Note Environment variables::.

BSD/OS Version 3.x Notes
........................

Upgrade to BSD/OS Version 3.1.  If that is not possible, install
BSDIpatch M300-038.

Use the following command when configuring MySQL:

     shell> env CXX=shlicc++ CC=shlicc2 \
            ./configure \
                --prefix=/usr/local/mysql \
                --localstatedir=/var/mysql \
                --without-perl \
                --with-unix-socket-path=/var/mysql/mysql.sock

The following is also known to work:

     shell> env CC=gcc CXX=gcc CXXFLAGS=-O3 \
            ./configure \
                --prefix=/usr/local/mysql \
                --with-unix-socket-path=/var/mysql/mysql.sock

You can change the directory locations if you wish, or just use the
defaults by not specifying any locations.

If you have problems with performance under heavy load, try using the
`--skip-thread-priority' option to `mysqld'!  This will run all threads
with the same priority; on BSDI Version 3.1, this gives better
performance (at least until BSDI fixes their thread scheduler).

If you get the error `virtual memory exhausted' while compiling, you
should try using `ulimit -v 80000' and run `make' again.  If this
doesn't work and you are using `bash', try switching to `csh' or `sh';
some BSDI users have reported problems with `bash' and `ulimit'.

BSD/OS Version 4.x Notes
........................

BSDI Version 4.x has some thread-related bugs.  If you want to use
MySQL on this, you should install all thread-related patches.  At least
M400-023 should be installed.

On some BSDI Version 4.x systems, you may get problems with shared
libraries.  The symptom is that you can't execute any client programs,
for example, `mysqladmin'.  In this case you need to reconfigure not to
use shared libraries with the `--disable-shared' option to configure.

Some customers have had problems on BSDI 4.0.1 that the `mysqld' binary
after a while can't open tables.  This is because some library/system
related bug causes `mysqld' to change current directory without asking
for this!

The fix is to either upgrade MySQL to at least version 3.23.34 or, after
running `configure', remove the line `#define HAVE_REALPATH' from
`config.h' before running make.

Note that the above means that you can't symbolic link a database
directories to another database directory or symbolic link a table to
another database on BSDI!  (Making a symbolic link to another disk is
okay).

Other Unix Notes
----------------

HP-UX Version 10.20 Notes
.........................

There are a couple of small problems when compiling MySQL on HP-UX.  We
recommend that you use `gcc' instead of the HP-UX native compiler,
because `gcc' produces better code!

We recommend using `gcc' 2.95 on HP-UX.  Don't use high optimization
flags (like `-O6') as they may not be safe on HP-UX.

The following `configure' line should work with `gcc' 2.95:

     CFLAGS="-I/opt/dce/include -fpic" \
     CXXFLAGS="-I/opt/dce/include -felide-constructors -fno-exceptions \
     -fno-rtti" \
     CXX=gcc \
     ./configure --with-pthread \
         --with-named-thread-libs='-ldce' \
         --prefix=/usr/local/mysql --disable-shared

The following `configure' line should work with `gcc' 3.1:

     CFLAGS="-DHPUX -I/opt/dce/include -O3 -fPIC" CXX=gcc \
     CXXFLAGS="-DHPUX -I/opt/dce/include -felide-constructors \
         -fno-exceptions -fno-rtti -O3 -fPIC" \
     ./configure --prefix=/usr/local/mysql \
         --with-extra-charsets=complex --enable-thread-safe-client \
         --enable-local-infile  --with-pthread \
         --with-named-thread-libs=-ldce --with-lib-ccflags=-fPIC
         --disable-shared

HP-UX Version 11.x Notes
........................

For HP-UX Version 11.x, we recommend MySQL Version 3.23.15 or later.

Because of some critical bugs in the standard HP-UX libraries, you
should install the following patches before trying to run MySQL on
HP-UX 11.0:

     PHKL_22840 Streams cumulative
     PHNE_22397 ARPA cumulative

This will solve the problem of getting `EWOULDBLOCK' from `recv()' and
`EBADF' from `accept()' in threaded applications.

If you are using `gcc' 2.95.1 on an unpatched HP-UX 11.x system, you
will get the error:

     In file included from /usr/include/unistd.h:11,
                      from ../include/global.h:125,
                      from mysql_priv.h:15,
                      from item.cc:19:
     /usr/include/sys/unistd.h:184: declaration of C function ...
     /usr/include/sys/pthread.h:440: previous declaration ...
     In file included from item.h:306,
                      from mysql_priv.h:158,
                      from item.cc:19:

The problem is that HP-UX doesn't define `pthreads_atfork()'
consistently.  It has conflicting prototypes in
`/usr/include/sys/unistd.h':184 and `/usr/include/sys/pthread.h':440
(details below).

One solution is to copy `/usr/include/sys/unistd.h' into
`mysql/include' and edit `unistd.h' and change it to match the
definition in `pthread.h'.  Here's the diff:

     183,184c183,184
     <      extern int pthread_atfork(void (*prepare)(), void (*parent)(),
     <                                                void (*child)());
     ---
     >      extern int pthread_atfork(void (*prepare)(void), void (*parent)(void),
     >                                                void (*child)(void));

After this, the following `configure' line should work:

     CFLAGS="-fomit-frame-pointer -O3 -fpic" CXX=gcc \
     CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti -O3" \
     ./configure --prefix=/usr/local/mysql --disable-shared

If you are using MySQL 4.0.5 with the HP-UX compiler, you can use the
following command (which has been tested with `cc' B.11.11.04):

     CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure \
         --with-extra-character-set=complex

You can ignore any errors of the following type:

     aCC: warning 901: unknown option: `-3': use +help for online
     documentation

If you get the following error from `configure', check that you don't
have the path to the K&R compiler before the path to the HP-UX C and
C++ compiler:

     checking for cc option to accept ANSI C... no
     configure: error: MySQL requires a ANSI C compiler (and a C++ compiler).
     Try gcc. See the Installation chapter in the Reference Manual.

Another reason for not being able to compile is that you didn't define
the `+DD64' flags above.

Another possibility for HP-UX 11 is to use MySQL binaries for HP-UX
10.20.  We have received reports from some users that these binaries
work fine on HP-UX 11.00. If you encounter problems, be sure to check
your HP-UX patch level.

IBM-AIX notes
.............

Automatic detection of `xlC' is missing from Autoconf, so a number of
variables need to be set before running `configure'. The following
example uses the IBM compiler:

     export CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 "
     export CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192"
     export CFLAGS="-I /usr/local/include"
     export LDFLAGS="-L /usr/local/lib"
     export CPPFLAGS=$CFLAGS
     export CXXFLAGS=$CFLAGS

     ./configure --prefix=/usr/local \
                     --localstatedir=/var/mysql \
                     --sysconfdir=/etc/mysql \
                     --sbindir='/usr/local/bin' \
                     --libexecdir='/usr/local/bin' \
                     --enable-thread-safe-client \
                     --enable-large-files

Above are the options used to compile the MySQL distribution that can
be found at `http://www-frec.bull.com/'.

If you change the `-O3' to `-O2' in the preceding `configure' line, you
must also remove the `-qstrict' option (this is a limitation in the IBM
C compiler).

If you are using `gcc' or `egcs' to compile MySQL, you *must* use the
`-fno-exceptions' flag, because the exception handling in `gcc'/`egcs'
is not thread-safe!  (This is tested with `egcs' 1.1.)  There are also
some known problems with IBM's assembler that may cause it to generate
bad code when used with `gcc'.

We recommend the following `configure' line with `egcs' and `gcc 2.95'
on AIX:

     CC="gcc -pipe -mcpu=power -Wa,-many" \
     CXX="gcc -pipe -mcpu=power -Wa,-many" \
     CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti" \
     ./configure --prefix=/usr/local/mysql --with-low-memory

The `-Wa,-many' is necessary for the compile to be successful.  IBM is
aware of this problem but is in to hurry to fix it because of the
workaround available.  We don't know if the `-fno-exceptions' is
required with `gcc 2.95', but as MySQL doesn't use exceptions and the
above option generates faster code, we recommend that you should always
use this option with `egcs / gcc'.

If you get a problem with assembler code, try changing the `-mcpu=xxx'
option to match your CPU. Typically `power2', `power', or `powerpc' may
need to be used.  Alternatively, you might need to use `604' or `604e'.
We are not positive but suspect that `power' would likely be safe most
of the time, even on a power2 machine.

If you don't know what your CPU is, execute a `uname -m' command.  It
will produce a string that looks like `000514676700', with a format of
`xxyyyyyymmss' where `xx' and `ss' are always `00', `yyyyyy' is a
unique system ID and `mm' is the ID of the CPU Planar.  A chart of
these values can be found at
`http://publib.boulder.ibm.com/doc_link/en_US/a_doc_lib/cmds/aixcmds5/uname.htm'.
This will give you a machine type and a machine model you can use to
determine what type of CPU you have.

If you have problems with signals (MySQL dies unexpectedly under high
load) you may have found an OS bug with threads and signals.  In this
case you can tell MySQL not to use signals by configuring with:

     shell> CFLAGS=-DDONT_USE_THR_ALARM CXX=gcc \
            CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti \
            -DDONT_USE_THR_ALARM" \
            ./configure --prefix=/usr/local/mysql --with-debug \
                --with-low-memory

This doesn't affect the performance of MySQL, but has the side effect
that you can't kill clients that are "sleeping" on a connection with
`mysqladmin kill' or `mysqladmin shutdown'.  Instead, the client will
die when it issues its next command.

On some versions of AIX, linking with `libbind.a' makes `getservbyname'
core dump.  This is an AIX bug and should be reported to IBM.

For AIX 4.2.1 and `gcc', you have to make the following changes.

After configuring, edit `config.h' and `include/my_config.h' and change
the line that says this:

     #define HAVE_SNPRINTF 1

to this:

     #undef HAVE_SNPRINTF

And finally, in `mysqld.cc' you need to add a prototype for initgoups.

     #ifdef _AIX41
     extern "C" int initgroups(const char *,int);
     #endif

If you need to allocate a lot of memory to the `mysqld' process, it's
not enough to just use `ulimit -d unlimited'. You may also have to
modify `mysqld_safe' to add a line something like this:

     export LDR_CNTRL='MAXDATA=0x80000000'

You can find more about using a lot of memory at:
`http://publib16.boulder.ibm.com/pseries/en_US/aixprggd/genprogc/lrg_prg_support.htm'.

SunOS 4 Notes
.............

On SunOS 4, MIT-pthreads is needed to compile MySQL. This in turn means
you will need GNU `make'.

Some SunOS 4 systems have problems with dynamic libraries and `libtool'.
You can use the following `configure' line to avoid this problem:

     shell> ./configure --disable-shared --with-mysqld-ldflags=-all-static

When compiling `readline', you may get warnings about duplicate defines.
These may be ignored.

When compiling `mysqld', there will be some `implicit declaration of
function' warnings. These may be ignored.

Alpha-DEC-UNIX Notes (Tru64)
............................

If you are using `egcs' 1.1.2 on Digital Unix, you should upgrade to
`gcc' 2.95.2, because `egcs' on DEC has some serious bugs!

When compiling threaded programs under Digital Unix, the documentation
recommends using the `-pthread' option for `cc' and `cxx' and the
`-lmach -lexc' libraries (in addition to `-lpthread').  You should run
`configure' something like this:

     CC="cc -pthread" CXX="cxx -pthread -O" \
     ./configure --with-named-thread-libs="-lpthread -lmach -lexc -lc"

When compiling `mysqld', you may see a couple of warnings like this:

     mysqld.cc: In function void handle_connections()':
     mysqld.cc:626: passing long unsigned int *' as argument 3 of
     accept(int,sockadddr *, int *)'

You can safely ignore these warnings.  They occur because `configure'
can detect only errors, not warnings.

If you start the server directly from the command-line, you may have
problems with it dying when you log out.  (When you log out, your
outstanding processes receive a `SIGHUP' signal.)  If so, try starting
the server like this:

     shell> nohup mysqld [options] &

`nohup' causes the command following it to ignore any `SIGHUP' signal
sent from the terminal.  Alternatively, start the server by running
`mysqld_safe', which invokes `mysqld' using `nohup' for you.  *Note
`mysqld_safe': mysqld_safe.

If you get a problem when compiling `mysys/get_opt.c', just remove the
`#define _NO_PROTO' line from the start of that file!

If you are using Compaq's CC compiler, the following `configure' line
should work:

     CC="cc -pthread"
     CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all -arch host"
     CXX="cxx -pthread"
     CXXFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all \
         -arch host -noexceptions -nortti"
     export CC CFLAGS CXX CXXFLAGS
     ./configure \
         --prefix=/usr/local/mysql \
         --with-low-memory \
         --enable-large-files \
         --enable-shared=yes \
         --with-named-thread-libs="-lpthread -lmach -lexc -lc"
     gnumake

If you get a problem with `libtool', when compiling with shared
libraries as above, when linking `mysql', you should be able to get
around this by issuing:

     cd mysql
     /bin/sh ../libtool --mode=link cxx -pthread  -O3 -DDBUG_OFF \
         -O4 -ansi_alias -ansi_args -fast -inline speed \
         -speculate all \ -arch host  -DUNDEF_HAVE_GETHOSTBYNAME_R \
         -o mysql  mysql.o readline.o sql_string.o completion_hash.o \
         ../readline/libreadline.a -lcurses \
         ../libmysql/.libs/libmysqlclient.so  -lm
     cd ..
     gnumake
     gnumake install
     scripts/mysql_install_db

Alpha-DEC-OSF/1 Notes
.....................

If you have problems compiling and have DEC `CC' and `gcc' installed,
try running `configure' like this:

     CC=cc CFLAGS=-O CXX=gcc CXXFLAGS=-O3 \
     ./configure --prefix=/usr/local/mysql

If you get problems with the `c_asm.h' file, you can create and use a
'dummy' `c_asm.h' file with:

     touch include/c_asm.h
     CC=gcc CFLAGS=-I./include \
     CXX=gcc CXXFLAGS=-O3 \
     ./configure --prefix=/usr/local/mysql

Note that the following problems with the `ld' program can be fixed by
downloading the latest DEC (Compaq) patch kit from:
`http://ftp.support.compaq.com/public/unix/'.

On OSF/1 V4.0D and compiler "DEC C V5.6-071 on Digital Unix V4.0 (Rev.
878)" the compiler had some strange behavior (undefined `asm' symbols).
`/bin/ld' also appears to be broken (problems with `_exit undefined'
errors occurring while linking `mysqld').  On this system, we have
managed to compile MySQL with the following `configure' line, after
replacing `/bin/ld' with the version from OSF 4.0C:

     CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql

With the Digital compiler "C++ V6.1-029", the following should work:

     CC=cc -pthread
     CFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed -speculate all \
            -arch host
     CXX=cxx -pthread
     CXXFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed -speculate all \
               -arch host -noexceptions -nortti
     export CC CFLAGS CXX CXXFLAGS
     ./configure --prefix=/usr/mysql/mysql --with-mysqld-ldflags=-all-static \
                 --disable-shared --with-named-thread-libs="-lmach -lexc -lc"

In some versions of OSF/1, the `alloca()' function is broken. Fix this
by removing the line in `config.h' that defines `'HAVE_ALLOCA''.

The `alloca()' function also may have an incorrect prototype in
`/usr/include/alloca.h'.  This warning resulting from this can be
ignored.

`configure' will use the following thread libraries automatically:
`--with-named-thread-libs="-lpthread -lmach -lexc -lc"'.

When using `gcc', you can also try running `configure' like this:

     shell> CFLAGS=-D_PTHREAD_USE_D4 CXX=gcc CXXFLAGS=-O3 ./configure ...

If you have problems with signals (MySQL dies unexpectedly under high
load), you may have found an OS bug with threads and signals. In this
case you can tell MySQL not to use signals by configuring with:

     shell> CFLAGS=-DDONT_USE_THR_ALARM \
            CXXFLAGS=-DDONT_USE_THR_ALARM \
            ./configure ...

This doesn't affect the performance of MySQL, but has the side effect
that you can't kill clients that are "sleeping" on a connection with
`mysqladmin kill' or `mysqladmin shutdown'.  Instead, the client will
die when it issues its next command.

With `gcc' 2.95.2, you will probably run into the following compile
error:

     sql_acl.cc:1456: Internal compiler error in `scan_region', at except.c:2566
     Please submit a full bug report.

To fix this you should change to the `sql' directory and do a "cut and
paste" of the last `gcc' line, but change `-O3' to `-O0' (or add `-O0'
immediately after `gcc' if you don't have any `-O' option on your
compile line).  After this is done you can just change back to the
top-level directly and run `make' again.

SGI Irix Notes
..............

If you are using Irix Version 6.5.3 or newer `mysqld' will be able to
create threads only if you run it as a user with `CAP_SCHED_MGT'
privileges (like `root') or give the `mysqld' server this privilege
with the following shell command:

     shell> chcap "CAP_SCHED_MGT+epi" /opt/mysql/libexec/mysqld

You may have to undefine some symbols in `config.h' after running
`configure' and before compiling.

In some Irix implementations, the `alloca()' function is broken.  If the
`mysqld' server dies on some `SELECT' statements, remove the lines from
`config.h' that define `HAVE_ALLOC' and `HAVE_ALLOCA_H'.  If
`mysqladmin create' doesn't work, remove the line from `config.h' that
defines `HAVE_READDIR_R'.  You may have to remove the `HAVE_TERM_H'
line as well.

SGI recommends that you install all of the patches on this page as a
set:
`http://support.sgi.com/surfzone/patches/patchset/6.2_indigo.rps.html'

At the very minimum, you should install the latest kernel rollup, the
latest `rld' rollup, and the latest `libc' rollup.

You definitely need all the POSIX patches on this page, for pthreads
support:

`http://support.sgi.com/surfzone/patches/patchset/6.2_posix.rps.html'

If you get the something like the following error when compiling
`mysql.cc':

     "/usr/include/curses.h", line 82: error(1084): invalid combination of type

Type the following in the top-level directory of your MySQL source tree:

     shell> extra/replace bool curses_bool < /usr/include/curses.h \
                > include/curses.h
     shell> make

There have also been reports of scheduling problems.  If only one
thread is running, performance is slow.  Avoid this by starting another
client.  This may lead to a 2-to-10-fold increase in execution speed
thereafter for the other thread.  This is a poorly understood problem
with Irix threads; you may have to improvise to find solutions until
this can be fixed.

If you are compiling with `gcc', you can use the following `configure'
command:

     CC=gcc CXX=gcc CXXFLAGS=-O3 \
     ./configure --prefix=/usr/local/mysql --enable-thread-safe-client \
         --with-named-thread-libs=-lpthread

On Irix 6.5.11 with native Irix C and C++ compilers ver. 7.3.1.2, the
following is reported to work

     CC=cc CXX=CC CFLAGS='-O3 -n32 -TARG:platform=IP22 -I/usr/local/include \
     -L/usr/local/lib' CXXFLAGS='-O3 -n32 -TARG:platform=IP22 \
     -I/usr/local/include -L/usr/local/lib' \
     ./configure --prefix=/usr/local/mysql --with-innodb --with-berkeley-db \
         --with-libwrap=/usr/local \
         --with-named-curses-libs=/usr/local/lib/libncurses.a

SCO Notes
.........

The current port is tested only on "sco3.2v5.0.5", "sco3.2v5.0.6" and
"sco3.2v5.0.7" systems.  There has also been a lot of progress on a
port to "sco 3.2v4.2".

For the moment the recommended compiler on OpenServer is `gcc' 2.95.2.
With this you should be able to compile MySQL with just:

     CC=gcc CXX=gcc ./configure ... (options)

  1. For OpenServer 5.0.x you need to use gcc-2.95.2p1 or newer from the
     Skunkware.  `http://www.sco.com/skunkware/' and choose browser
     OpenServer packages or by ftp to ftp2.caldera.com in the
     `pub/skunkware/osr5/devtools/gcc' directory.

  2. You need the port of GCC 2.5.x for this product and the Development
     system.  They are required on this version of SCO Unix.  You cannot
     just use the GCC Dev system.

  3. You should get the FSU Pthreads package and install it first.
     This can be found at
     `http://moss.csc.ncsu.edu/~mueller/ftp/pub/PART/pthreads.tar.gz'.
     You can also get a precompiled package from
     `http://www.mysql.com/Downloads/SCO/FSU-threads-3.5c.tar.gz'.

  4. FSU Pthreads can be compiled with SCO Unix 4.2 with tcpip.  Or
     OpenServer 3.0 or Open Desktop 3.0 (OS 3.0 ODT 3.0), with the SCO
     Development System installed using a good port of GCC 2.5.x ODT or
     OS 3.0 you will need a good port of GCC 2.5.x There are a lot of
     problems without a good port.  The port for this product requires
     the SCO Unix Development system.  Without it, you are missing the
     libraries and the linker that is needed.

  5. To build FSU Pthreads on your system, do the following:

       1. Run `./configure' in the `threads/src' directory and select
          the SCO OpenServer option. This command copies
          `Makefile.SCO5' to `Makefile'.

       2. Run `make'.

       3. To install in the default `/usr/include' directory, login as
          root, then `cd' to the `thread/src' directory, and run `make
          install'.

  6. Remember to use GNU `make' when making MySQL.

  7. If you don't start `mysqld_safe' as `root', you probably will get
     only the default 110 open files per process.  `mysqld' will write
     a note about this in the log file.

  8. With SCO 3.2V5.0.5, you should use FSU Pthreads version 3.5c or
     newer.  You should also use `gcc' 2.95.2 or newer!

     The following `configure' command should work:

          shell> ./configure --prefix=/usr/local/mysql --disable-shared

  9. With SCO 3.2V4.2, you should use FSU Pthreads version 3.5c or
     newer.  The following `configure' command should work:

          shell> CFLAGS="-D_XOPEN_XPG4" CXX=gcc CXXFLAGS="-D_XOPEN_XPG4" \
                 ./configure \
                     --prefix=/usr/local/mysql \
                     --with-named-thread-libs="-lgthreads -lsocket -lgen -lgthreads" \
                     --with-named-curses-libs="-lcurses"

     You may get some problems with some include files. In this case,
     you can find new SCO-specific include files at
     `http://www.mysql.com/Downloads/SCO/SCO-3.2v4.2-includes.tar.gz'.
     You should unpack this file in the `include' directory of your
     MySQL source tree.

SCO development notes:

   * MySQL should automatically detect FSU Pthreads and link `mysqld'
     with `-lgthreads -lsocket -lgthreads'.

   * The SCO development libraries are re-entrant in FSU Pthreads.  SCO
     claims that its libraries' functions are re-entrant, so they must
     be re-entrant with FSU Pthreads.  FSU Pthreads on OpenServer tries
     to use the SCO scheme to make re-entrant libraries.

   * FSU Pthreads (at least the version at `http://www.mysql.com/')
     comes linked with GNU `malloc'.  If you encounter problems with
     memory usage, make sure that `gmalloc.o' is included in
     `libgthreads.a' and `libgthreads.so'.

   * In FSU Pthreads, the following system calls are pthreads-aware:
     `read()', `write()', `getmsg()', `connect()', `accept()',
     `select()', and `wait()'.

   * The CSSA-2001-SCO.35.2 (the patch is listed in custom as
     erg711905-dscr_remap security patch (version 2.0.0) breaks FSU
     threads and makes `mysqld' unstable.  You have to remove this one
     if you want to run `mysqld' on an OpenServer 5.0.6 machine.

   * SCO provides Operating Systems Patches at
     `ftp://ftp.sco.com/pub/openserver5' for OpenServer 5.0.x

   * SCO provides security fixes and `libsocket.so.2' at
     `ftp://ftp.sco.com/pub/security/OpenServer' and
     `ftp://ftp.sco.com/pub/security/sse' for OpenServer 5.0.x

   * pre-OSR506 security fixes. Also, the `telnetd' fix at
     `ftp://stage.caldera.com/pub/security/openserver/' or
     `ftp://stage.caldera.com/pub/security/openserver/CSSA-2001-SCO.10/'
     as both `libsocket.so.2' and `libresolv.so.1' with instructions for
     installing on pre-OSR506 systems.

     It's probably a good idea to install the above patches before
     trying to compile/use MySQL.

SCO UnixWare Version 7.1.x Notes
................................

On UnixWare 7.1.0, you must use a version of MySQL at least as recent as
3.22.13 to get fixes for some portability and OS problems.

We have been able to compile MySQL with the following `configure'
command on UnixWare Version 7.1.x:

     CC=cc CXX=CC ./configure --prefix=/usr/local/mysql

If you want to use `gcc', you must use `gcc' 2.95.2 or newer.

     CC=gcc CXX=g++ ./configure --prefix=/usr/local/mysql

  1. SCO provides Operating Systems Patches at
     `ftp://ftp.sco.com/pub/unixware7' for UnixWare 7.1.1 and 7.1.3 and
     at `ftp://ftp.sco.com/pub/openunix8' for OpenUNIX 8.0.0.

  2. SCO provides information about Security Fixes at
     `ftp://ftp.sco.com/pub/security/OpenUNIX' for OpenUNIX and at
     `ftp://ftp.sco.com/pub/security/UnixWare' for UnixWare.

OS/2 Notes
----------

MySQL uses quite a few open files. Because of this, you should add
something like the following to your `CONFIG.SYS' file:

     SET EMXOPT=-c -n -h1024

If you don't do this, you will probably run into the following error:

     File 'xxxx' not found (Errcode: 24)

When using MySQL with OS/2 Warp 3, FixPack 29 or above is required.
With OS/2 Warp 4, FixPack 4 or above is required. This is a requirement
of the Pthreads library.  MySQL must be installed on a partition with a
type that supports long filenames, such as HPFS, FAT32, etc.

The `INSTALL.CMD' script must be run from OS/2's own `CMD.EXE' and may
not work with replacement shells such as `4OS2.EXE'.

The `scripts/mysql-install-db' script has been renamed.  It is now
called `install.cmd' and is a REXX script, which will set up the default
MySQL security settings and create the WorkPlace Shell icons for MySQL.

Dynamic module support is compiled in but not fully tested. Dynamic
modules should be compiled using the Pthreads run-time library.

     gcc -Zdll -Zmt -Zcrtdll=pthrdrtl -I../include -I../regex -I.. \
         -o example udf_example.cc -L../lib -lmysqlclient udf_example.def
     mv example.dll example.udf

*Note:* Due to limitations in OS/2, UDF module name stems must not
exceed 8 characters. Modules are stored in the `/mysql2/udf' directory;
the `safe-mysqld.cmd' script will put this directory in the
`BEGINLIBPATH' environment variable. When using UDF modules, specified
extensions are ignored--it is assumed to be `.udf'.  For example, in
Unix, the shared module might be named `example.so' and you would load
a function from it like this:

     mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME "example.so";

In OS/2, the module would be named `example.udf', but you would not
specify the module extension:

     mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME "example";

BeOS Notes
----------

We have in the past talked with some BeOS developers that have said that
MySQL is 80% ported to BeOS, but we haven't heard from them in a while.

Perl Installation Notes
=======================

Perl support for MySQL is provided by means of the `DBI'/`DBD' client
interface. The interface requires Perl Version 5.6.0 or later.  It
*will not work* if you have an older version of Perl.

If you want to use transactions with Perl DBI, you need to have
`DBD::mysql' version 1.2216 or newer. Version 2.9003 or newer is
recommended.

As of Version 3.22.8, Perl support is no longer included with MySQL
distributions. You can obtain the necessary modules from
`http://search.cpan.org' for Unix, or using the ActiveState `ppm'
program on Windows. The following sections describe how to do this.

Perl support for MySQL must be installed if you want to run the MySQL
benchmark scripts.  *Note MySQL Benchmarks::.

Installing Perl on Unix
-----------------------

MySQL Perl support requires that you've installed MySQL client
programming support (libraries and header files).  Most installation
methods install the necesssary files. However, if you installed MySQL
from RPM files on Linux, be sure that you've installed the developer
RPM.  The client programs are in the client RPM, but client programming
support is in the developer RPM.

If you want to install Perl support, the files you will need can be
obtained from the CPAN (Comprehensive Perl Archive Network) at
`http://search.cpan.org'.

The easiest way to install Perl modules on Unix is to use the `CPAN'
module. For example:

     shell> perl -MCPAN -e shell
     cpan> install DBI
     cpan> install DBD::mysql

The `DBD::mysql' installation runs a number of tests.  These tests
require being able to connect to the local MySQL server as the
anonymous user with no password. If you have removed anonymous accounts
or assigned them passwords, the tests fail. You can use `force install
DBD::mysql' to ignore the failed tests.

`DBI' requires the `Data::Dumper' module. It may already be installed;
if not, you should install it before installing `DBI'.

It is also possible to download the module distributions in the form of
compressed `tar' archives and build the modules manually. For example,
to unpack and build a DBI distribution, use a procedure such as this:

  1. Unpack the distribution into the current directory:
          shell> gunzip < DBI-VERSION.tar.gz | tar xvf -
     This command creates a directory named `DBI-VERSION'.

  2. Change into the top-level directory of the unpacked distribution:
          shell> cd DBI-VERSION

  3. Build the distribution and compile everything:
          shell> perl Makefile.PL
          shell> make
          shell> make test
          shell> make install

The `make test' command is important because it verifies that the
module is working.  Note that when you run that command during the
`DBD::mysql' installation to exercise the interface code, the MySQL
server must be running or the test will fail.

It is a good idea to rebuild and reinstall the `DBD::mysql'
distribution whenever you install a new release of MySQL, particularly
if you notice symptoms such as that all your `DBI' scripts fail after
you upgrade MySQL.

If you don't have access rights to install Perl modules in the system
directory or if you want to install local Perl modules, the following
reference may be useful:

     `http://servers.digitaldaze.com/extensions/perl/modules.html#modules'

Look under the heading `Installing New Modules that Require Locally
Installed Modules'.

Installing ActiveState Perl on Windows
--------------------------------------

On Windows, you should do the following to install the MySQL `DBD'
module with ActiveState Perl:

   * Get ActiveState Perl from
     `http://www.activestate.com/Products/ActivePerl/' and install it.

   * Open a console window (a "DOS window").

   * If required, set the `HTTP_proxy' variable. For example, you might
     try:

          set HTTP_proxy=my.proxy.com:3128

   * Start the PPM program:

          C:\> c:\perl\bin\ppm.pl

   * If you have not already done so, install `DBI':

          ppm> install DBI

   * If this succeeds, run the following command:

          install \
          ftp://ftp.de.uu.net/pub/CPAN/authors/id/JWIED/DBD-mysql-1.2212.x86.ppd

The above should work at least with ActiveState Perl Version 5.6.

If you can't get the above to work, you should instead install the
`MyODBC' driver and connect to the MySQL server through ODBC:

     use DBI;
     $dbh= DBI->connect("DBI:ODBC:$dsn",$user,$password) ||
       die "Got error $DBI::errstr when connecting to $dsn\n";

Problems Using the Perl `DBI'/`DBD' Interface
---------------------------------------------

If Perl reports that it can't find the `../mysql/mysql.so' module, then
the problem is probably that Perl can't locate the shared library
`libmysqlclient.so'.

You should be able to fix this by one of the following methods:

   * Compile the `DBD::mysql' distribution with `perl Makefile.PL
     -static -config' rather than `perl Makefile.PL'.

   * Copy `libmysqlclient.so' to the directory where your other shared
     libraries are located (probably `/usr/lib' or `/lib').

   * Modify the `-L' options used to compile `DBD::mysql' to reflect
     the actual location of `libmysqlclient.so'.

   * On Linux you can add the pathname of the directory where
     `libmysqlclient.so' is located to the `/etc/ld.so.conf' file.

   * Add the pathname of the directory where `libmysqlclient.so' is
     located to the `LD_RUN_PATH' environment variable. Some systems use
     `LD_LIBRARY_PATH' instead.

Note that you may also need to modify the `-L' options if there are
other libraries that the linker fails to find. For example, if the
linker cannot find `libc' because it is in `/lib' and the link command
specifies `-L/usr/lib', change the `-L' option to `-L/lib' or add
`-L/lib' to the existing link command.

If you get the following errors from `DBD::mysql', you are probably
using `gcc' (or using an old binary compiled with `gcc'):

     /usr/bin/perl: can't resolve symbol '__moddi3'
     /usr/bin/perl: can't resolve symbol '__divdi3'

Add `-L/usr/lib/gcc-lib/... -lgcc' to the link command when the
`mysql.so' library gets built (check the output from `make' for
`mysql.so' when you compile the Perl client).  The `-L' option should
specify the pathname of the directory where `libgcc.a' is located on
your system.

Another cause of this problem may be that Perl and MySQL aren't both
compiled with `gcc'.  In this case, you can solve the mismatch by
compiling both with `gcc'.

You may see the following error from `DBD::mysql' when you run the
tests:

     t/00base............install_driver(mysql) failed:
     Can't load '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
     ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol:
     uncompress at /usr/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 169.

This means that you need to include the `-lz' compression library on the
link line. That can be done by changing the following line in the file
`lib/DBD/mysql/Install.pm':

     $sysliblist .= " -lm";

Change that line to:

     $sysliblist .= " -lm -lz";

After this, you *must* run `make realclean' and then proceed with the
installation from the beginning.

If you want to install DBI on SCO, you have to edit the `Makefile' in
DBI-xxx and each subdirectory.

Note that the following assumes `gcc' 2.95.2 or newer:

     OLD:                                  NEW:
     CC = cc                               CC = gcc
     CCCDLFLAGS = -KPIC -W1,-Bexport       CCCDLFLAGS = -fpic
     CCDLFLAGS = -wl,-Bexport              CCDLFLAGS =

     LD = ld                               LD = gcc -G -fpic
     LDDLFLAGS = -G -L/usr/local/lib       LDDLFLAGS = -L/usr/local/lib
     LDFLAGS = -belf -L/usr/local/lib      LDFLAGS = -L/usr/local/lib

     LD = ld                               LD = gcc -G -fpic
     OPTIMISE = -Od                        OPTIMISE = -O1

     OLD:
     CCCFLAGS = -belf -dy -w0 -U M_XENIX -DPERL_SCO5 -I/usr/local/include

     NEW:
     CCFLAGS = -U M_XENIX -DPERL_SCO5 -I/usr/local/include

This is because the Perl dynaloader will not load the `DBI' modules if
they were compiled with `icc' or `cc'.

If you want to use the Perl module on a system that doesn't support
dynamic linking (like SCO) you can generate a static version of Perl
that includes `DBI' and `DBD::mysql'.  The way this works is that you
generate a version of Perl with the `DBI' code linked in and install it
on top of your current Perl.  Then you use that to build a version of
Perl that additionally has the `DBD' code linked in, and install that.

On SCO, you must have the following environment variables set:

     shell> LD_LIBRARY_PATH=/lib:/usr/lib:/usr/local/lib:/usr/progressive/lib
     or:
     shell> LD_LIBRARY_PATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
     /usr/progressive/lib:/usr/skunk/lib
     shell> LIBPATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
     /usr/progressive/lib:/usr/skunk/lib
     shell> MANPATH=scohelp:/usr/man:/usr/local1/man:/usr/local/man:\
     /usr/skunk/man:

First, create a Perl that includes a statically linked `DBI' module by
running these commands in the directory where your `DBI' distribution is
located:

     shell> perl Makefile.PL -static -config
     shell> make
     shell> make install
     shell> make perl

Then you must install the new Perl. The output of `make perl' will
indicate the exact `make' command you will need to execute to perform
the installation.  On SCO, this is `make -f Makefile.aperl inst_perl
MAP_TARGET=perl'.

Next, use the just-created Perl to create another Perl that also
includes a statically linked `DBD::mysql' by running these commands in
the directory where your `DBD::mysql' distribution is located:

     shell> perl Makefile.PL -static -config
     shell> make
     shell> make install
     shell> make perl

Finally, you should install this new Perl.  Again, the output of `make
perl' indicates the command to use.

MySQL Tutorial
**************

This chapter provides a tutorial introduction to MySQL by showing how
to use the `mysql' client program to create and use a simple database.
`mysql' (sometimes referred to as the "terminal monitor" or just
"monitor") is an interactive program that allows you to connect to a
MySQL server, run queries, and view the results.  `mysql' may also be
used in batch mode: you place your queries in a file beforehand, then
tell `mysql' to execute the contents of the file.  Both ways of using
`mysql' are covered here.

To see a list of options provided by `mysql', invoke it with the
`--help' option:

     shell> mysql --help

This chapter assumes that `mysql' is installed on your machine and that
a MySQL server is available to which you can connect.  If this is not
true, contact your MySQL administrator.  (If *you* are the
administrator, you will need to consult other sections of this manual.)

This chapter describes the entire process of setting up and using a
database.  If you are interested only in accessing an already-existing
database, you may want to skip over the sections that describe how to
create the database and the tables it contains.

Because this chapter is tutorial in nature, many details are necessarily
omitted.  Consult the relevant sections of the manual for more
information on the topics covered here.

Connecting to and Disconnecting from the Server
===============================================

To connect to the server, you'll usually need to provide a MySQL
username when you invoke `mysql' and, most likely, a password.  If the
server runs on a machine other than the one where you log in, you'll
also need to specify a hostname.  Contact your administrator to find
out what connection parameters you should use to connect (that is, what
host, username, and password to use).  Once you know the proper
parameters, you should be able to connect like this:

     shell> mysql -h host -u user -p
     Enter password: ********

`host' and `user' represent the hostname where your MySQL server is
running and the username of your MySQL account.  Substitute appropriate
values for your setup.  The `********' represents your password; enter
it when `mysql' displays the `Enter password:' prompt.

If that works, you should see some introductory information followed by
a `mysql>' prompt:

     shell> mysql -h host -u user -p
     Enter password: ********
     Welcome to the MySQL monitor.  Commands end with ; or \g.
     Your MySQL connection id is 25338 to server version: 4.0.14-log

     Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

     mysql>

The prompt tells you that `mysql' is ready for you to enter commands.

Some MySQL installations allow users to connect as the anonymous
(unnamed) user to the server running on the local host.  If this is the
case on your machine, you should be able to connect to that server by
invoking `mysql' without any options:

     shell> mysql

After you have connected successfully, you can disconnect any time by
typing `QUIT' (or `\q') at the `mysql>' prompt:

     mysql> QUIT
     Bye

On Unix, you can also disconnect by pressing Control-D.

Most examples in the following sections assume you are connected to the
server.  They indicate this by the `mysql>' prompt.

Entering Queries
================

Make sure you are connected to the server, as discussed in the previous
section.  Doing so will not in itself select any database to work with,
but that's okay.  At this point, it's more important to find out a
little about how to issue queries than to jump right in creating
tables, loading data into them, and retrieving data from them.  This
section describes the basic principles of entering commands, using
several queries you can try out to familiarise yourself with how
`mysql' works.

Here's a simple command that asks the server to tell you its version
number and the current date.  Type it in as shown here following the
`mysql>' prompt and press Enter:

     mysql> SELECT VERSION(), CURRENT_DATE;
     +--------------+--------------+
     | VERSION()    | CURRENT_DATE |
     +--------------+--------------+
     | 3.22.20a-log | 1999-03-19   |
     +--------------+--------------+
     1 row in set (0.01 sec)
     mysql>

This query illustrates several things about `mysql':

   * A command normally consists of an SQL statement followed by a
     semicolon.  (There are some exceptions where a semicolon may be
     omitted.  `QUIT', mentioned earlier, is one of them.  We'll get to
     others later.)

   * When you issue a command, `mysql' sends it to the server for
     execution and displays the results, then prints another `mysql>'
     prompt to indicate that it is ready for another command.

   * `mysql' displays query output in tabular form (rows and columns).
     The first row contains labels for the columns.  The rows following
     are the query results.  Normally, column labels are the names of
     the columns you fetch from database tables.  If you're retrieving
     the value of an expression rather than a table column (as in the
     example just shown), `mysql' labels the column using the
     expression itself.

   * `mysql' shows how many rows were returned and how long the query
     took to execute, which gives you a rough idea of server
     performance.  These values are imprecise because they represent
     wall clock time (not CPU or machine time), and because they are
     affected by factors such as server load and network latency.  (For
     brevity, the "rows in set" line is not shown in the remaining
     examples in this chapter.)

Keywords may be entered in any lettercase.  The following queries are
equivalent:

     mysql> SELECT VERSION(), CURRENT_DATE;
     mysql> select version(), current_date;
     mysql> SeLeCt vErSiOn(), current_DATE;

Here's another query.  It demonstrates that you can use `mysql' as a
simple calculator:

     mysql> SELECT SIN(PI()/4), (4+1)*5;
     +-------------+---------+
     | SIN(PI()/4) | (4+1)*5 |
     +-------------+---------+
     |    0.707107 |      25 |
     +-------------+---------+

The queries shown thus far have been relatively short, single-line
statements.  You can even enter multiple statements on a single line.
Just end each one with a semicolon:

     mysql> SELECT VERSION(); SELECT NOW();
     +--------------+
     | VERSION()    |
     +--------------+
     | 3.22.20a-log |
     +--------------+

     +---------------------+
     | NOW()               |
     +---------------------+
     | 1999-03-19 00:15:33 |
     +---------------------+

A command need not be given all on a single line, so lengthy commands
that require several lines are not a problem.  `mysql' determines where
your statement ends by looking for the terminating semicolon, not by
looking for the end of the input line.  (In other words, `mysql'
accepts free-format input:  it collects input lines but does not
execute them until it sees the semicolon.)

Here's a simple multiple-line statement:

     mysql> SELECT
         -> USER()
         -> ,
         -> CURRENT_DATE;
     +--------------------+--------------+
     | USER()             | CURRENT_DATE |
     +--------------------+--------------+
     | joesmith@localhost | 1999-03-18   |
     +--------------------+--------------+

In this example, notice how the prompt changes from `mysql>' to `->'
after you enter the first line of a multiple-line query.  This is how
`mysql' indicates that it hasn't seen a complete statement and is
waiting for the rest.  The prompt is your friend, because it provides
valuable feedback.  If you use that feedback, you will always be aware
of what `mysql' is waiting for.

If you decide you don't want to execute a command that you are in the
process of entering, cancel it by typing `\c':

     mysql> SELECT
         -> USER()
         -> \c
     mysql>

Here, too, notice the prompt.  It switches back to `mysql>' after you
type `\c', providing feedback to indicate that `mysql' is ready for a
new command.

The following table shows each of the prompts you may see and
summarizes what they mean about the state that `mysql' is in:

*Prompt**Meaning*
`mysql>'Ready for new command.
`       Waiting for next line of multiple-line command.
->'
`       Waiting for next line, collecting a string that begins
'>'     with a single quote (`'').
`       Waiting for next line, collecting a string that begins
">'     with a double quote (`"').
`       Waiting for next line, collecting an identifier that
`>'     begins with a backtick (``').

Multiple-line statements commonly occur by accident when you intend to
issue a command on a single line, but forget the terminating semicolon.
In this case, `mysql' waits for more input:

     mysql> SELECT USER()
         ->

If this happens to you (you think you've entered a statement but the
only response is a `->' prompt), most likely `mysql' is waiting for the
semicolon.  If you don't notice what the prompt is telling you, you
might sit there for a while before realising what you need to do.
Enter a semicolon to complete the statement, and `mysql' will execute
it:

     mysql> SELECT USER()
         -> ;
     +--------------------+
     | USER()             |
     +--------------------+
     | joesmith@localhost |
     +--------------------+

The `'>' and `">' prompts occur during string collection.  In MySQL,
you can write strings surrounded by either `'' or `"' characters (for
example, `'hello'' or `"goodbye"'), and `mysql' lets you enter strings
that span multiple lines.  When you see a `'>' or `">' prompt, it means
that you've entered a line containing a string that begins with a `''
or `"' quote character, but have not yet entered the matching quote
that terminates the string.  That's fine if you really are entering a
multiple-line string, but how likely is that?  Not very.  More often,
the `'>' and `">' prompts indicate that you've inadvertantly left out a
quote character.  For example:

     mysql> SELECT * FROM my_table WHERE name = "Smith AND age < 30;
         ">

If you enter this `SELECT' statement, then press Enter and wait for the
result, nothing will happen.  Instead of wondering why this query takes
so long, notice the clue provided by the `">' prompt.  It tells you
that `mysql' expects to see the rest of an unterminated string.  (Do
you see the error in the statement?  The string `"Smith' is missing the
second quote.)

At this point, what do you do?  The simplest thing is to cancel the
command.  However, you cannot just type `\c' in this case, because
`mysql' interprets it as part of the string that it is collecting!
Instead, enter the closing quote character (so `mysql' knows you've
finished the string), then type `\c':

     mysql> SELECT * FROM my_table WHERE name = "Smith AND age < 30;
         "> "\c
     mysql>

The prompt changes back to `mysql>', indicating that `mysql' is ready
for a new command.

The ``>' prompt is similar to th `'>' and `">' prompts, but indicates
that you have begun but not completed a backtick-quoted identifier.

It's important to know what the `'>', `">', and ``>' prompts signify,
because if you mistakenly enter an unterminated string, any further
lines you type will appear to be ignored by `mysql'--including a line
containing `QUIT'!  This can be quite confusing, especially if you
don't know that you need to supply the terminating quote before you can
cancel the current command.

Creating and Using a Database
=============================

Now that you know how to enter commands, it's time to access a database.

Suppose you have several pets in your home (your menagerie) and you'd
like to keep track of various types of information about them.  You can
do so by creating tables to hold your data and loading them with the
desired information.  Then you can answer different sorts of questions
about your animals by retrieving data from the tables.  This section
shows you how to:

   * Create a database

   * Create a table

   * Load data into the table

   * Retrieve data from the table in various ways

   * Use multiple tables

The menagerie database will be simple (deliberately), but it is not
difficult to think of real-world situations in which a similar type of
database might be used.  For example, a database like this could be
used by a farmer to keep track of livestock, or by a veterinarian to
keep track of patient records.  A menagerie distribution containing
some of the queries and sample data used in the following sections can
be obtained from the MySQL web site.  It's available in either
compressed `tar' format
(`http://www.mysql.com/Downloads/Contrib/Examples/menagerie.tar.gz') or
Zip format
(`http://www.mysql.com/Downloads/Contrib/Examples/menagerie.zip').

Use the `SHOW' statement to find out what databases currently exist on
the server:

     mysql> SHOW DATABASES;
     +----------+
     | Database |
     +----------+
     | mysql    |
     | test     |
     | tmp      |
     +----------+

The list of databases is probably different on your machine, but the
`mysql' and `test' databases are likely to be among them.  The `mysql'
database is required because it describes user access privileges.  The
`test' database is often provided as a workspace for users to try
things out.

Note that you may not see all databases if you don't have the `SHOW
DATABASES' privilege. *Note `GRANT': GRANT.

If the `test' database exists, try to access it:

     mysql> USE test
     Database changed

Note that `USE', like `QUIT', does not require a semicolon.  (You can
terminate such statements with a semicolon if you like; it does no
harm.)  The `USE' statement is special in another way, too:  it must be
given on a single line.

You can use the `test' database (if you have access to it) for the
examples that follow, but anything you create in that database can be
removed by anyone else with access to it.  For this reason, you should
probably ask your MySQL administrator for permission to use a database
of your own.  Suppose you want to call yours `menagerie'.  The
administrator needs to execute a command like this:

     mysql> GRANT ALL ON menagerie.* TO 'your_mysql_name'@'your_client_host';

where `your_mysql_name' is the MySQL username assigned to you and
`your_client_host' is the host from which you connect to the server.

Creating and Selecting a Database
---------------------------------

If the administrator creates your database for you when setting up your
permissions, you can begin using it.  Otherwise, you need to create it
yourself:

     mysql> CREATE DATABASE menagerie;

Under Unix, database names are case-sensitive (unlike SQL keywords), so
you must always refer to your database as `menagerie', not as
`Menagerie', `MENAGERIE', or some other variant.  This is also true for
table names.  (Under Windows, this restriction does not apply, although
you must refer to databases and tables using the same lettercase
throughout a given query.)

Creating a database does not select it for use; you must do that
explicitly.  To make `menagerie' the current database, use this command:

     mysql> USE menagerie
     Database changed

Your database needs to be created only once, but you must select it for
use each time you begin a `mysql' session.  You can do this by issuing a
`USE' statement as shown in the example.  Alternatively, you can select
the database on the command-line when you invoke `mysql'.  Just specify
its name after any connection parameters that you might need to
provide.  For example:

     shell> mysql -h host -u user -p menagerie
     Enter password: ********

Note that `menagerie' is not your password on the command just shown.
If you want to supply your password on the command-line after the `-p'
option, you must do so with no intervening space (for example, as
`-pmypassword', not as `-p mypassword').  However, putting your
password on the command-line is not recommended, because doing so
exposes it to snooping by other users logged in on your machine.

Creating a Table
----------------

Creating the database is the easy part, but at this point it's empty, as
`SHOW TABLES' will tell you:

     mysql> SHOW TABLES;
     Empty set (0.00 sec)

The harder part is deciding what the structure of your database should
be: what tables you will need and what columns will be in each of them.

You'll want a table that contains a record for each of your pets.  This
can be called the `pet' table, and it should contain, as a bare minimum,
each animal's name.  Because the name by itself is not very
interesting, the table should contain other information.  For example,
if more than one person in your family keeps pets, you might want to
list each animal's owner.  You might also want to record some basic
descriptive information such as species and sex.

How about age?  That might be of interest, but it's not a good thing to
store in a database.  Age changes as time passes, which means you'd
have to update your records often.  Instead, it's better to store a
fixed value such as date of birth.  Then, whenever you need age, you
can calculate it as the difference between the current date and the
birth date.  MySQL provides functions for doing date arithmetic, so
this is not difficult.  Storing birth date rather than age has other
advantages, too:

   * You can use the database for tasks such as generating reminders
     for upcoming pet birthdays.  (If you think this type of query is
     somewhat silly, note that it is the same question you might ask in
     the context of a business database to identify clients to whom
     you'll soon need to send out birthday greetings, for that
     computer-assisted personal touch.)

   * You can calculate age in relation to dates other than the current
     date.  For example, if you store death date in the database, you
     can easily calculate how old a pet was when it died.

You can probably think of other types of information that would be
useful in the `pet' table, but the ones identified so far are
sufficient for now: name, owner, species, sex, birth, and death.

Use a `CREATE TABLE' statement to specify the layout of your table:

     mysql> CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20),
         -> species VARCHAR(20), sex CHAR(1), birth DATE, death DATE);

`VARCHAR' is a good choice for the `name', `owner', and `species'
columns because the column values will vary in length.  The lengths of
those columns need not all be the same, and need not be `20'.  You can
pick any length from `1' to `255', whatever seems most reasonable to
you.  (If you make a poor choice and it turns out later that you need a
longer field, MySQL provides an `ALTER TABLE' statement.)

Several types of values can be chosen to represent sex in animal
records, such as `"m"' and `"f"', or perhaps `"male"' and `"female"'.
It's simplest to use the single characters `"m"' and `"f"'.

The use of the `DATE' datatype for the `birth' and `death' columns is a
fairly obvious choice.

Now that you have created a table, `SHOW TABLES' should produce some
output:

     mysql> SHOW TABLES;
     +---------------------+
     | Tables in menagerie |
     +---------------------+
     | pet                 |
     +---------------------+

To verify that your table was created the way you expected, use a
`DESCRIBE' statement:

     mysql> DESCRIBE pet;
     +---------+-------------+------+-----+---------+-------+
     | Field   | Type        | Null | Key | Default | Extra |
     +---------+-------------+------+-----+---------+-------+
     | name    | varchar(20) | YES  |     | NULL    |       |
     | owner   | varchar(20) | YES  |     | NULL    |       |
     | species | varchar(20) | YES  |     | NULL    |       |
     | sex     | char(1)     | YES  |     | NULL    |       |
     | birth   | date        | YES  |     | NULL    |       |
     | death   | date        | YES  |     | NULL    |       |
     +---------+-------------+------+-----+---------+-------+

You can use `DESCRIBE' any time, for example, if you forget the names of
the columns in your table or what types they have.

Loading Data into a Table
-------------------------

After creating your table, you need to populate it.  The `LOAD DATA' and
`INSERT' statements are useful for this.

Suppose your pet records can be described as shown here.  (Observe that
MySQL expects dates in `'YYYY-MM-DD'' format; this may be different
from what you are used to.)

*name*  *owner* *species**sex**birth*        *death*
Fluffy  Harold  cat     f    1993-02-04
Claws   Gwen    cat     m    1994-03-17
Buffy   Harold  dog     f    1989-05-13
Fang    Benny   dog     m    1990-08-27
Bowser  Diane   dog     m    1979-08-31     1995-07-29
Chirpy  Gwen    bird    f    1998-09-11
WhistlerGwen    bird         1997-12-09
Slim    Benny   snake   m    1996-04-29

Because you are beginning with an empty table, an easy way to populate
it is to create a text file containing a row for each of your animals,
then load the contents of the file into the table with a single
statement.

You could create a text file `pet.txt' containing one record per line,
with values separated by tabs, and given in the order in which the
columns were listed in the `CREATE TABLE' statement.  For missing
values (such as unknown sexes or death dates for animals that are still
living), you can use `NULL' values.  To represent these in your text
file, use `\N' (backslash, capital-N).  For example, the record for
Whistler the bird would look like this (where the whitespace between
values is a single tab character):

*name*  *owner* *species**sex**birth*        *death*
`Whistler'`Gwen'  `bird'  `\N' `1997-12-09'   `\N'

To load the text file `pet.txt' into the `pet' table, use this command:

     mysql> LOAD DATA LOCAL INFILE "pet.txt" INTO TABLE pet;

Note that if you created the file on Windows with an editor that uses
`\r\n' as a line terminator, you should use:

     mysql> LOAD DATA LOCAL INFILE "pet.txt" INTO TABLE pet
         -> LINES TERMINATED BY '\r\n';

You can specify the column value separator and end of line marker
explicitly in the `LOAD DATA' statement if you wish, but the defaults
are tab and linefeed.  These are sufficient for the statement to read
the file `pet.txt' properly.

If the statement fails, it is likely that your MySQL installation does
not have local file capability enabled by default.  See *Note `LOAD
DATA LOCAL': LOAD DATA LOCAL for information on how to change this.

When you want to add new records one at a time, the `INSERT' statement
is useful.  In its simplest form, you supply values for each column, in
the order in which the columns were listed in the `CREATE TABLE'
statement.  Suppose Diane gets a new hamster named Puffball.  You could
add a new record using an `INSERT' statement like this:

     mysql> INSERT INTO pet
         -> VALUES ('Puffball','Diane','hamster','f','1999-03-30',NULL);

Note that string and date values are specified as quoted strings here.
Also, with `INSERT', you can insert `NULL' directly to represent a
missing value.  You do not use `\N' like you do with `LOAD DATA'.

From this example, you should be able to see that there would be a 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)<RIGHT(birth,5))
         -> AS age
         -> FROM pet;
     +----------+------------+------------+------+
     | name     | birth      | CURDATE()  | age  |
     +----------+------------+------------+------+
     | Fluffy   | 1993-02-04 | 2003-08-19 |   10 |
     | Claws    | 1994-03-17 | 2003-08-19 |    9 |
     | Buffy    | 1989-05-13 | 2003-08-19 |   14 |
     | Fang     | 1990-08-27 | 2003-08-19 |   12 |
     | Bowser   | 1989-08-31 | 2003-08-19 |   13 |
     | Chirpy   | 1998-09-11 | 2003-08-19 |    4 |
     | Whistler | 1997-12-09 | 2003-08-19 |    5 |
     | Slim     | 1996-04-29 | 2003-08-19 |    7 |
     | Puffball | 1999-03-30 | 2003-08-19 |    4 |
     +----------+------------+------------+------+

Here, `YEAR()' pulls out the year part of a date and `RIGHT()' pulls
off the rightmost five characters that represent the `MM-DD' (calendar
year) part of the date.  The part of the expression that compares the
`MM-DD' values evaluates to 1 or 0, which adjusts the year difference
down a year if `CURDATE()' occurs earlier in the year than `birth'.
The full expression is somewhat ungainly, so an alias (`age') is used
to make the output column label more meaningful.

The query works, but the result could be scanned more easily if the rows
were presented in some order.  This can be done by adding an `ORDER BY
name' clause to sort the output by name:

     mysql> SELECT name, birth, CURDATE(),
         -> (YEAR(CURDATE())-YEAR(birth))
         -> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
         -> AS age
         -> FROM pet ORDER BY name;
     +----------+------------+------------+------+
     | name     | birth      | CURDATE()  | age  |
     +----------+------------+------------+------+
     | Bowser   | 1989-08-31 | 2003-08-19 |   13 |
     | Buffy    | 1989-05-13 | 2003-08-19 |   14 |
     | Chirpy   | 1998-09-11 | 2003-08-19 |    4 |
     | Claws    | 1994-03-17 | 2003-08-19 |    9 |
     | Fang     | 1990-08-27 | 2003-08-19 |   12 |
     | Fluffy   | 1993-02-04 | 2003-08-19 |   10 |
     | Puffball | 1999-03-30 | 2003-08-19 |    4 |
     | Slim     | 1996-04-29 | 2003-08-19 |    7 |
     | Whistler | 1997-12-09 | 2003-08-19 |    5 |
     +----------+------------+------------+------+

To sort the output by `age' rather than `name', just use a different
`ORDER BY' clause:

     mysql> SELECT name, birth, CURDATE(),
         -> (YEAR(CURDATE())-YEAR(birth))
         -> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
         -> AS age
         -> FROM pet ORDER BY age;
     +----------+------------+------------+------+
     | name     | birth      | CURDATE()  | age  |
     +----------+------------+------------+------+
     | Chirpy   | 1998-09-11 | 2003-08-19 |    4 |
     | Puffball | 1999-03-30 | 2003-08-19 |    4 |
     | Whistler | 1997-12-09 | 2003-08-19 |    5 |
     | Slim     | 1996-04-29 | 2003-08-19 |    7 |
     | Claws    | 1994-03-17 | 2003-08-19 |    9 |
     | Fluffy   | 1993-02-04 | 2003-08-19 |   10 |
     | Fang     | 1990-08-27 | 2003-08-19 |   12 |
     | Bowser   | 1989-08-31 | 2003-08-19 |   13 |
     | Buffy    | 1989-05-13 | 2003-08-19 |   14 |
     +----------+------------+------------+------+

A similar query can be used to determine age at death for animals that
have died.  You determine which animals these are by checking whether
the `death' value is `NULL'.  Then, for those with non-`NULL' values,
compute the difference between the `death' and `birth' values:

     mysql> SELECT name, birth, death,
         -> (YEAR(death)-YEAR(birth)) - (RIGHT(death,5)<RIGHT(birth,5))
         -> AS age
         -> FROM pet WHERE death IS NOT NULL ORDER BY age;
     +--------+------------+------------+------+
     | name   | birth      | death      | age  |
     +--------+------------+------------+------+
     | Bowser | 1989-08-31 | 1995-07-29 |    5 |
     +--------+------------+------------+------+

The query uses `death IS NOT NULL' rather than `death <> NULL' because
`NULL' is a special value that cannot be compared using the usual
comparison operators.  This is discussed later.  *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.  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%";
     +--------+--------+---------+------+------------+------------+
     | name   | owner  | species | sex  | birth      | death      |
     +--------+--------+---------+------+------------+------------+
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL       |
     | Bowser | Diane  | dog     | m    | 1989-08-31 | 1995-07-29 |
     +--------+--------+---------+------+------------+------------+

To find names ending with `fy':

     mysql> SELECT * FROM pet WHERE name LIKE "%fy";
     +--------+--------+---------+------+------------+-------+
     | name   | owner  | species | sex  | birth      | death |
     +--------+--------+---------+------+------------+-------+
     | Fluffy | Harold | cat     | f    | 1993-02-04 | NULL  |
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL  |
     +--------+--------+---------+------+------------+-------+

To find names containing a `w':

     mysql> SELECT * FROM pet WHERE name LIKE "%w%";
     +----------+-------+---------+------+------------+------------+
     | name     | owner | species | sex  | birth      | death      |
     +----------+-------+---------+------+------------+------------+
     | Claws    | Gwen  | cat     | m    | 1994-03-17 | NULL       |
     | Bowser   | Diane | dog     | m    | 1989-08-31 | 1995-07-29 |
     | Whistler | Gwen  | bird    | NULL | 1997-12-09 | NULL       |
     +----------+-------+---------+------+------------+------------+

To find names containing exactly five characters, use fives instances of
the `_' pattern character:

     mysql> SELECT * FROM pet WHERE name LIKE "_____";
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Claws | Gwen   | cat     | m    | 1994-03-17 | NULL  |
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

The other type of pattern matching provided by MySQL uses extended
regular expressions.  When you test for a match for this type of
pattern, use the `REGEXP' and `NOT REGEXP' operators (or `RLIKE' and
`NOT RLIKE', which are synonyms).

Some characteristics of extended regular expressions are:

   * `.' matches any single character.

   * A character class `[...]' matches any character within the
     brackets.  For example, `[abc]' matches `a', `b', or `c'.  To name
     a range of characters, use a dash.  `[a-z]' matches any letter,
     whereas `[0-9]' matches any digit.

   * `*' matches zero or more instances of the thing preceding it.  For
     example, `x*' matches any number of `x' characters, `[0-9]*'
     matches any number of digits, and `.*' matches any number of
     anything.

   * A `REGEXP' pattern match succeed if the pattern matches anywhere
     in the value being tested.  (This differs from a `LIKE' pattern
     match, which succeeds only if the pattern matches the entire
     value.)

   * To anchor a pattern so that it must match the beginning or end of
     the value being tested, use `^' at the beginning or `$' at the end
     of the pattern.

To demonstrate how extended regular expressions work, the `LIKE' queries
shown previously are rewritten here to use `REGEXP'.

To find names beginning with `b', use `^' to match the beginning of the
name:

     mysql> SELECT * FROM pet WHERE name REGEXP "^b";
     +--------+--------+---------+------+------------+------------+
     | name   | owner  | species | sex  | birth      | death      |
     +--------+--------+---------+------+------------+------------+
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL       |
     | Bowser | Diane  | dog     | m    | 1989-08-31 | 1995-07-29 |
     +--------+--------+---------+------+------------+------------+

Prior to MySQL Version 3.23.4, `REGEXP' is case-sensitive, and the
previous query will return no rows. In this case, to match either
lowercase or uppercase `b', use this query instead:

     mysql> SELECT * FROM pet WHERE name REGEXP "^[bB]";

From MySQL 3.23.4 on, if you really want to force a `REGEXP' comparison
to be case-sensitive, use the `BINARY' keyword to make one of the
strings a binary string. This query will match only lowercase `b' at
the beginning of a name:

     mysql> SELECT * FROM pet WHERE name REGEXP BINARY "^b";

To find names ending with `fy', use `$' to match the end of the name:

     mysql> SELECT * FROM pet WHERE name REGEXP "fy$";
     +--------+--------+---------+------+------------+-------+
     | name   | owner  | species | sex  | birth      | death |
     +--------+--------+---------+------+------------+-------+
     | Fluffy | Harold | cat     | f    | 1993-02-04 | NULL  |
     | Buffy  | Harold | dog     | f    | 1989-05-13 | NULL  |
     +--------+--------+---------+------+------------+-------+

To find names containing a `w', use this query:

     mysql> SELECT * FROM pet WHERE name REGEXP "w";
     +----------+-------+---------+------+------------+------------+
     | name     | owner | species | sex  | birth      | death      |
     +----------+-------+---------+------+------------+------------+
     | Claws    | Gwen  | cat     | m    | 1994-03-17 | NULL       |
     | Bowser   | Diane | dog     | m    | 1989-08-31 | 1995-07-29 |
     | Whistler | Gwen  | bird    | NULL | 1997-12-09 | NULL       |
     +----------+-------+---------+------+------------+------------+

Because a regular expression pattern matches if it occurs anywhere in
the value, it is not necessary in the previous query to put a wildcard
on either side of the pattern to get it to match the entire value like
it would be if you used an SQL pattern.

To find names containing exactly five characters, use `^' and `$' to
match the beginning and end of the name, and five instances of `.' in
between:

     mysql> SELECT * FROM pet WHERE name REGEXP "^.....$";
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Claws | Gwen   | cat     | m    | 1994-03-17 | NULL  |
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

You could also write the previous query using the `{n}'
"repeat-`n'-times" operator:

     mysql> SELECT * FROM pet WHERE name REGEXP "^.{5}$";
     +-------+--------+---------+------+------------+-------+
     | name  | owner  | species | sex  | birth      | death |
     +-------+--------+---------+------+------------+-------+
     | Claws | Gwen   | cat     | m    | 1994-03-17 | NULL  |
     | Buffy | Harold | dog     | f    | 1989-05-13 | NULL  |
     +-------+--------+---------+------+------------+-------+

Counting Rows
.............

Databases are often used to answer the question, "How often does a
certain type of data occur in a table?"  For example, you might want to
know how many pets you have, or how many pets each owner has, or you
might want to perform various kinds of census operations on your
animals.

Counting the total number of animals you have is the same question as
"How many rows are in the `pet' table?" because there is one record per
pet.  `COUNT(*)' counts the number of rows, so the query to count your
animals looks like this:

     mysql> SELECT COUNT(*) FROM pet;
     +----------+
     | COUNT(*) |
     +----------+
     |        9 |
     +----------+

Earlier, you retrieved the names of the people who owned pets.  You can
use `COUNT()' if you want to find out how many pets each owner has:

     mysql> SELECT owner, COUNT(*) FROM pet GROUP BY owner;
     +--------+----------+
     | owner  | COUNT(*) |
     +--------+----------+
     | Benny  |        2 |
     | Diane  |        2 |
     | Gwen   |        3 |
     | Harold |        2 |
     +--------+----------+

Note the use of `GROUP BY' to group together all records for each
`owner'.  Without it, all you get is an error message:

     mysql> SELECT owner, COUNT(*) FROM pet;
     ERROR 1140: Mixing of GROUP columns (MIN(),MAX(),COUNT()...)
     with no GROUP columns is illegal if there is no GROUP BY clause

`COUNT()' and `GROUP BY' are useful for characterising your data in
various ways.  The following examples show different ways to perform
animal census operations.

Number of animals per species:

     mysql> SELECT species, COUNT(*) FROM pet GROUP BY species;
     +---------+----------+
     | species | COUNT(*) |
     +---------+----------+
     | bird    |        2 |
     | cat     |        2 |
     | dog     |        3 |
     | hamster |        1 |
     | snake   |        1 |
     +---------+----------+

Number of animals per sex:

     mysql> SELECT sex, COUNT(*) FROM pet GROUP BY sex;
     +------+----------+
     | sex  | COUNT(*) |
     +------+----------+
     | NULL |        1 |
     | f    |        4 |
     | m    |        4 |
     +------+----------+

(In this output, `NULL' indicates that the sex is unknown.)

Number of animals per combination of species and sex:

     mysql> SELECT species, sex, COUNT(*) FROM pet GROUP BY species, sex;
     +---------+------+----------+
     | species | sex  | COUNT(*) |
     +---------+------+----------+
     | bird    | NULL |        1 |
     | bird    | f    |        1 |
     | cat     | f    |        1 |
     | cat     | m    |        1 |
     | dog     | f    |        1 |
     | dog     | m    |        2 |
     | hamster | f    |        1 |
     | snake   | m    |        1 |
     +---------+------+----------+

You need not retrieve an entire table when you use `COUNT()'.  For
example, the previous query, when performed just on dogs and cats,
looks like this:

     mysql> SELECT species, sex, COUNT(*) FROM pet
         -> WHERE species = "dog" OR species = "cat"
         -> GROUP BY species, sex;
     +---------+------+----------+
     | species | sex  | COUNT(*) |
     +---------+------+----------+
     | cat     | f    |        1 |
     | cat     | m    |        1 |
     | dog     | f    |        1 |
     | dog     | m    |        2 |
     +---------+------+----------+

Or, if you wanted the number of animals per sex only for known-sex
animals:

     mysql> SELECT species, sex, COUNT(*) FROM pet
         -> WHERE sex IS NOT NULL
         -> GROUP BY species, sex;
     +---------+------+----------+
     | species | sex  | COUNT(*) |
     +---------+------+----------+
     | bird    | f    |        1 |
     | cat     | f    |        1 |
     | cat     | m    |        1 |
     | dog     | f    |        1 |
     | dog     | m    |        2 |
     | hamster | f    |        1 |
     | snake   | m    |        1 |
     +---------+------+----------+

Using More Than one Table
.........................

The `pet' table keeps track of which pets you have.  If you want to
record other information about them, such as events in their lives like
visits to the vet or when litters are born, you need another table.
What should this table look like? It needs:

   * To contain the pet name so you know which animal each event
     pertains to.

   * A date so you know when the event occurred.

   * A field to describe the event.

   * An event type field, if you want to be able to categorise events.

Given these considerations, the `CREATE TABLE' statement for the
`event' table might look like this:

     mysql> CREATE TABLE event (name VARCHAR(20), date DATE,
         -> type VARCHAR(15), remark VARCHAR(255));

As with the `pet' table, it's easiest to load the initial records by
creating a tab-delimited text file containing the information:

*name*      *date*      *type*      *remark*
Fluffy      1995-05-15  litter      4 kittens, 3 female, 1
                                    male
Buffy       1993-06-23  litter      5 puppies, 2 female, 3
                                    male
Buffy       1994-06-19  litter      3 puppies, 3 female
Chirpy      1999-03-21  vet         needed beak straightened
Slim        1997-08-03  vet         broken rib
Bowser      1991-10-12  kennel
Fang        1991-10-12  kennel
Fang        1998-08-28  birthday    Gave him a new chew toy
Claws       1998-03-17  birthday    Gave him a new flea
                                    collar
Whistler    1998-12-09  birthday    First birthday

Load the records like this:

     mysql> LOAD DATA LOCAL INFILE "event.txt" INTO TABLE event;

Based on what you've learned from the queries you've run on the `pet'
table, you should be able to perform retrievals on the records in the
`event' table; the principles are the same.  But when is the `event'
table by itself insufficient to answer questions you might ask?

Suppose you want to find out the ages at which each pet had its
litters. We saw earlier how to calculate ages from two dates.  The
litter date of the mother is in the `event' table, but to calculate her
age on that date you need her birth date, which is stored in the `pet'
table.  This means the query requires both tables:

     mysql> SELECT pet.name,
         -> (YEAR(date)-YEAR(birth)) - (RIGHT(date,5)<RIGHT(birth,5)) AS age,
         -> remark
         -> FROM pet, event
         -> WHERE pet.name = event.name AND type = "litter";
     +--------+------+-----------------------------+
     | name   | age  | remark                      |
     +--------+------+-----------------------------+
     | Fluffy |    2 | 4 kittens, 3 female, 1 male |
     | Buffy  |    4 | 5 puppies, 2 female, 3 male |
     | Buffy  |    5 | 3 puppies, 3 female         |
     +--------+------+-----------------------------+

There are several things to note about this query:

   * The `FROM' clause lists two tables because the query needs to pull
     information from both of them.

   * When combining (joining) information from multiple tables, you
     need to specify how records in one table can be matched to records
     in the other.  This is easy because they both have a `name'
     column.  The query uses `WHERE' clause to match up records in the
     two tables based on the `name' values.

   * Because the `name' column occurs in both tables, you must be
     specific about which table you mean when referring to the column.
     This is done by prepending the table name to the column name.

You need not have two different tables to perform a join.  Sometimes it
is useful to join a table to itself, if you want to compare records in
a table to other records in that same table.  For example, to find
breeding pairs among your pets, you can join the `pet' table with
itself to produce candidate pairs of males and females of like species:

     mysql> SELECT p1.name, p1.sex, p2.name, p2.sex, p1.species
         -> FROM pet AS p1, pet AS p2
         -> WHERE p1.species = p2.species AND p1.sex = "f" AND p2.sex = "m";
     +--------+------+--------+------+---------+
     | name   | sex  | name   | sex  | species |
     +--------+------+--------+------+---------+
     | Fluffy | f    | Claws  | m    | cat     |
     | Buffy  | f    | Fang   | m    | dog     |
     | Buffy  | f    | Bowser | m    | dog     |
     +--------+------+--------+------+---------+

In this query, we specify aliases for the table name in order to refer
to the columns and keep straight which instance of the table each
column reference is associated with.

Getting Information About Databases and Tables
==============================================

What if you forget the name of a database or table, or what the
structure of a given table is (for example, what its columns are
called)?  MySQL addresses this problem through several statements that
provide information about the databases and tables it supports.

You have already seen `SHOW DATABASES', which lists the databases
managed by the server.  To find out which database is currently
selected, use the `DATABASE()' function:

     mysql> SELECT DATABASE();
     +------------+
     | DATABASE() |
     +------------+
     | menagerie  |
     +------------+

If you haven't selected any database yet, the result is `NULL' (or the
empty string before MySQL 4.1.1).

To find out what tables the current database contains (for example, when
you're not sure about the name of a table), use this command:

     mysql> SHOW TABLES;
     +---------------------+
     | Tables in menagerie |
     +---------------------+
     | event               |
     | pet                 |
     +---------------------+

If you want to find out about the structure of a table, the `DESCRIBE'
command is useful; it displays information about each of a table's
columns:

     mysql> DESCRIBE pet;
     +---------+-------------+------+-----+---------+-------+
     | Field   | Type        | Null | Key | Default | Extra |
     +---------+-------------+------+-----+---------+-------+
     | name    | varchar(20) | YES  |     | NULL    |       |
     | owner   | varchar(20) | YES  |     | NULL    |       |
     | species | varchar(20) | YES  |     | NULL    |       |
     | sex     | char(1)     | YES  |     | NULL    |       |
     | birth   | date        | YES  |     | NULL    |       |
     | death   | date        | YES  |     | NULL    |       |
     +---------+-------------+------+-----+---------+-------+

`Field' indicates the column name, `Type' is the datatype for the
column, `NULL' indicates whether the column can contain `NULL' values,
`Key' indicates whether the column is indexed, and `Default' specifies
the column's default value.

If you have indexes on a table, `SHOW INDEX FROM tbl_name' produces
information about them.

Using `mysql' in Batch Mode
===========================

In the previous sections, you used `mysql' interactively to enter
queries and view the results.  You can also run `mysql' in batch mode.
To do this, put the commands you want to run in a file, then tell
`mysql' to read its input from the file:

     shell> mysql < batch-file

If you are running `mysql' under Windows and have some special
characters in the file that cause problems, you can do this:

     dos> mysql -e "source batch-file"

If you need to specify connection parameters on the command line, the
command might look like this:

     shell> mysql -h host -u user -p < batch-file
     Enter password: ********

When you use `mysql' this way, you are creating a script file, then
executing the script.

If you want the script to continue even if some of the statements in it
produce errors, you should use the `--force' command-line option.

Why use a script?  Here are a few reasons:

   * If you run a query repeatedly (say, every day or every week),
     making it a script allows you to avoid retyping it each time you
     execute it.

   * You can generate new queries from existing ones that are similar
     by copying and editing script files.

   * Batch mode can also be useful while you're developing a query,
     particularly for multiple-line commands or multiple-statement
     sequences of commands.  If you make a mistake, you don't have to
     retype everything.  Just edit your script to correct the error,
     then tell `mysql' to execute it again.

   * If you have a query that produces a lot of output, you can run the
     output through a pager rather than watching it scroll off the top
     of your screen:

          shell> mysql < batch-file | more

   * You can catch the output in a file for further processing:

          shell> mysql < batch-file > mysql.out

   * You can distribute your script to other people so they can run the
     commands, too.

   * Some situations do not allow for interactive use, for example,
     when you run a query from a `cron' job.  In this case, you must
     use batch mode.

The default output format is different (more concise) when you run
`mysql' in batch mode than when you use it interactively.  For example,
the output of `SELECT DISTINCT species FROM pet' looks like this when
`mysql' is run interactively:

     +---------+
     | species |
     +---------+
     | bird    |
     | cat     |
     | dog     |
     | hamster |
     | snake   |
     +---------+

In batch mode, the output looks like this instead:

     species
     bird
     cat
     dog
     hamster
     snake

If you want to get the interactive output format in batch mode, use
`mysql -t'.  To echo to the output the commands that are executed, use
`mysql -vvv'.

You can also use scripts from the `mysql' prompt by using the `source'
command:

     mysql> source filename;

Examples of Common Queries
==========================

Here are examples of how to solve some common problems with MySQL.

Some of the examples use the table `shop' to hold the price of each
article (item number) for certain traders (dealers).  Supposing that
each trader has a single fixed price per article, then (`article',
`dealer') is a primary key for the records.

Start the command-line tool `mysql' and select a database:

     shell> mysql your-database-name

(In most MySQL installations, you can use the database name `test').

You can create and populate the example table with these statements:

     mysql> CREATE TABLE shop (
         -> article INT(4) UNSIGNED ZEROFILL DEFAULT '0000' NOT NULL,
         -> dealer  CHAR(20)                 DEFAULT ''     NOT NULL,
         -> price   DOUBLE(16,2)             DEFAULT '0.00' NOT NULL,
         -> PRIMARY KEY(article, dealer));
     mysql> INSERT INTO shop VALUES
         -> (1,'A',3.45),(1,'B',3.99),(2,'A',10.99),(3,'B',1.45),(3,'C',1.69),
         -> (3,'D',1.25),(4,'D',19.95);

After issuing the statements, the table should have the following
contents:

     mysql> SELECT * FROM shop;
     +---------+--------+-------+
     | article | dealer | price |
     +---------+--------+-------+
     |    0001 | A      |  3.45 |
     |    0001 | B      |  3.99 |
     |    0002 | A      | 10.99 |
     |    0003 | B      |  1.45 |
     |    0003 | C      |  1.69 |
     |    0003 | D      |  1.25 |
     |    0004 | D      | 19.95 |
     +---------+--------+-------+

The Maximum Value for a Column
------------------------------

"What's the highest item number?"

     SELECT MAX(article) AS article FROM shop;

     +---------+
     | article |
     +---------+
     |       4 |
     +---------+

The Row Holding the Maximum of a Certain Column
-----------------------------------------------

"Find number, dealer, and price of the most expensive article."

In SQL-99 (and MySQL Version 4.1) this is easily done with a subquery:

     SELECT article, dealer, price
     FROM   shop
     WHERE  price=(SELECT MAX(price) FROM shop);

In MySQL versions prior to 4.1, just do it in two steps:

  1. Get the maximum price value from the table with a `SELECT'
     statement.
          mysql> SELECT MAX(price) FROM shop;
          +------------+
          | MAX(price) |
          +------------+
          |      19.95 |
          +------------+

  2. Using the value 19.95 shown by the previous query to be the maximum
     article price, write a query to locate and display the
     corresponding record:
          mysql> SELECT article, dealer, price
              -> FROM   shop
              -> WHERE  price=19.95;
          +---------+--------+-------+
          | article | dealer | price |
          +---------+--------+-------+
          |    0004 | D      | 19.95 |
          +---------+--------+-------+

Another solution is to sort all rows descending by price and only get
the first row using the MySQL-specific `LIMIT' clause:

     SELECT article, dealer, price
     FROM   shop
     ORDER BY price DESC
     LIMIT 1;

*NOTE*:  If there were several most expensive articles, each with a
price of 19.95, the `LIMIT' solution would show only one of them!

Maximum of Column per Group
---------------------------

"What's the highest price per article?"

     SELECT article, MAX(price) AS price
     FROM   shop
     GROUP BY article

     +---------+-------+
     | article | price |
     +---------+-------+
     |    0001 |  3.99 |
     |    0002 | 10.99 |
     |    0003 |  1.69 |
     |    0004 | 19.95 |
     +---------+-------+

The Rows Holding the Group-wise Maximum of a Certain Field
----------------------------------------------------------

"For each article, find the dealer or dealers with the most expensive
price."

In SQL-99 (and MySQL Version 4.1 or greater), the problem can be solved
with a subquery like this:

     SELECT article, dealer, price
     FROM   shop s1
     WHERE  price=(SELECT MAX(s2.price)
                   FROM shop s2
                   WHERE s1.article = s2.article);

In MySQL versions prior to 4.1, it's best do it in several steps:

  1. Get the list of (article,maxprice) pairs.

  2. For each article, get the corresponding rows that have the stored
     maximum price.

This can easily be done with a temporary table and a join:

     CREATE TEMPORARY TABLE tmp (
             article INT(4) UNSIGNED ZEROFILL DEFAULT '0000' NOT NULL,
             price   DOUBLE(16,2)             DEFAULT '0.00' NOT NULL);

     LOCK TABLES shop READ;

     INSERT INTO tmp SELECT article, MAX(price) FROM shop GROUP BY article;

     SELECT shop.article, dealer, shop.price FROM shop, tmp
     WHERE shop.article=tmp.article AND shop.price=tmp.price;

     UNLOCK TABLES;

     DROP TABLE tmp;

If you don't use a `TEMPORARY' table, you must also lock the `tmp'
table.

"Can it be done with a single query?"

Yes, but only by using a quite inefficient trick called the "MAX-CONCAT
trick":

     SELECT article,
            SUBSTRING( MAX( CONCAT(LPAD(price,6,'0'),dealer) ), 7) AS dealer,
       0.00+LEFT(      MAX( CONCAT(LPAD(price,6,'0'),dealer) ), 6) AS price
     FROM   shop
     GROUP BY article;

     +---------+--------+-------+
     | article | dealer | price |
     +---------+--------+-------+
     |    0001 | B      |  3.99 |
     |    0002 | A      | 10.99 |
     |    0003 | C      |  1.69 |
     |    0004 | D      | 19.95 |
     +---------+--------+-------+

The last example can be made a bit more efficient by doing the
splitting of the concatenated column in the client.

Using User Variables
--------------------

You can use MySQL user variables to remember results without having to
store them in temporary variables in the client.  *Note Variables::.

For example, to find the articles with the highest and lowest price you
can do this:

     mysql> SELECT @min_price:=MIN(price),@max_price:=MAX(price) FROM shop;
     mysql> SELECT * FROM shop WHERE price=@min_price OR price=@max_price;
     +---------+--------+-------+
     | article | dealer | price |
     +---------+--------+-------+
     |    0003 | D      |  1.25 |
     |    0004 | D      | 19.95 |
     +---------+--------+-------+

Using Foreign Keys
------------------

In MySQL 3.23.44 and up, `InnoDB' tables support checking of foreign
key constraints. *Note `InnoDB': InnoDB.  See also *Note ANSI diff
Foreign Keys::.

You don't actually need foreign keys to join two tables.  For table
types other than `InnoDB'), the only things MySQL currently doesn't do
are 1) `CHECK' to make sure that the keys you use really exist in the
table or tables you're referencing and 2) automatically delete rows
from a table with a foreign key definition. Using your keys to join
tables will work just fine:

     CREATE TABLE person (
         id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
         name CHAR(60) NOT NULL,
         PRIMARY KEY (id)
     );

     CREATE TABLE shirt (
         id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
         style ENUM('t-shirt', 'polo', 'dress') NOT NULL,
         color ENUM('red', 'blue', 'orange', 'white', 'black') NOT NULL,
         owner SMALLINT UNSIGNED NOT NULL REFERENCES person(id),
         PRIMARY KEY (id)
     );


     INSERT INTO person VALUES (NULL, 'Antonio Paz');

     INSERT INTO shirt VALUES
     (NULL, 'polo', 'blue', LAST_INSERT_ID()),
     (NULL, 'dress', 'white', LAST_INSERT_ID()),
     (NULL, 't-shirt', 'blue', LAST_INSERT_ID());


     INSERT INTO person VALUES (NULL, 'Lilliana Angelovska');

     INSERT INTO shirt VALUES
     (NULL, 'dress', 'orange', LAST_INSERT_ID()),
     (NULL, 'polo', 'red', LAST_INSERT_ID()),
     (NULL, 'dress', 'blue', LAST_INSERT_ID()),
     (NULL, 't-shirt', 'white', LAST_INSERT_ID());


     SELECT * FROM person;
     +----+---------------------+
     | id | name                |
     +----+---------------------+
     |  1 | Antonio Paz         |
     |  2 | Lilliana Angelovska |
     +----+---------------------+

     SELECT * FROM shirt;
     +----+---------+--------+-------+
     | id | style   | color  | owner |
     +----+---------+--------+-------+
     |  1 | polo    | blue   |     1 |
     |  2 | dress   | white  |     1 |
     |  3 | t-shirt | blue   |     1 |
     |  4 | dress   | orange |     2 |
     |  5 | polo    | red    |     2 |
     |  6 | dress   | blue   |     2 |
     |  7 | t-shirt | white  |     2 |
     +----+---------+--------+-------+


     SELECT s.* FROM person p, shirt s
      WHERE p.name LIKE 'Lilliana%'
        AND s.owner = p.id
        AND s.color <> 'white';

     +----+-------+--------+-------+
     | id | style | color  | owner |
     +----+-------+--------+-------+
     |  4 | dress | orange |     2 |
     |  5 | polo  | red    |     2 |
     |  6 | dress | blue   |     2 |
     +----+-------+--------+-------+

Searching on Two Keys
---------------------

MySQL doesn't yet optimize when you search on two different keys
combined with `OR' (searching on one key with different `OR' parts is
optimized quite well):

     SELECT field1_index, field2_index FROM test_table
     WHERE field1_index = '1' OR  field2_index = '1'

The reason is that we haven't yet had time to come up with an efficient
way to handle this in the general case. (The `AND' handling is, in
comparison, now completely general and works very well.)

In MySQL 4.0 and up, you can solve this problem efficiently by using a
`UNION' that combines the output of two separate `SELECT' statements.
*Note UNION::.  Each `SELECT' searches only one key and can be
optimized:

     SELECT field1_index, field2_index FROM test_table WHERE field1_index = '1'
     UNION
     SELECT field1_index, field2_index FROM test_table WHERE field2_index = '1';

Prior to MySQL 4.0, you can achieve the same effect by using a
`TEMPORARY' table and separate `SELECT' statements.  This type of
optimization is also very good if you are using very complicated
queries where the SQL server does the optimizations in the wrong order.

     CREATE TEMPORARY TABLE tmp
     SELECT field1_index, field2_index FROM test_table WHERE field1_index = '1';
     INSERT INTO tmp
     SELECT field1_index, field2_index FROM test_table WHERE field2_index = '1';
     SELECT * from tmp;
     DROP TABLE tmp;

The above way to solve this query is in effect a `UNION' of two queries.

Calculating Visits Per Day
--------------------------

The following example shows how you can use the bit group functions to
calculate the number of days per month a user has visited a web page.

     CREATE TABLE t1 (year YEAR(4), month INT(2) UNSIGNED ZEROFILL,
                  day INT(2) UNSIGNED ZEROFILL);
     INSERT INTO t1 VALUES(2000,1,1),(2000,1,20),(2000,1,30),(2000,2,2),
                 (2000,2,23),(2000,2,23);

The example table contains year-month-day values representing visits by
users to the page. To determine how many different days in each month
these visits occur, use this query:

     SELECT year,month,BIT_COUNT(BIT_OR(1<<day)) AS days FROM t1
            GROUP BY year,month;

Which returns:

     +------+-------+------+
     | year | month | days |
     +------+-------+------+
     | 2000 |    01 |    3 |
     | 2000 |    02 |    2 |
     +------+-------+------+

The query calculates how many different days appear in the table for
each year/month combination, with automatic removal of duplicate
entries.

Using `AUTO_INCREMENT'
----------------------

The `AUTO_INCREMENT' attribute can be used to generate a unique
identity for new rows:

     CREATE TABLE animals (
                  id MEDIUMINT NOT NULL AUTO_INCREMENT,
                  name CHAR(30) NOT NULL,
                  PRIMARY KEY (id)
                  );
     INSERT INTO animals (name) VALUES ("dog"),("cat"),("penguin"),
                                       ("lax"),("whale"),("ostrich");
     SELECT * FROM animals;

Which returns:

     +----+---------+
     | id | name    |
     +----+---------+
     |  1 | dog     |
     |  2 | cat     |
     |  3 | penguin |
     |  4 | lax     |
     |  5 | whale   |
     |  6 | ostrich |
     +----+---------+

You can retrieve the most recent `AUTO_INCREMENT' value with the
`LAST_INSERT_ID()' SQL function or the `mysql_insert_id()' C API
function.  Note: For a multiple-row insert,
`LAST_INSERT_ID()'/`mysql_insert_id()' will actually return the
`AUTO_INCREMENT' key from the *first* of the inserted rows.  This
allows multiple-row inserts to be reproduced correctly on other servers
in a replication setup.

For `MyISAM' and `BDB' tables you can specify `AUTO_INCREMENT' on a
secondary column in a multiple-column index.  In this case, the
generated value for the `AUTO_INCREMENT' column is calculated as
`MAX(auto_increment_column)+1) WHERE prefix=given-prefix'.  This is
useful when you want to put data into ordered groups.

     CREATE TABLE animals (
                  grp ENUM('fish','mammal','bird') NOT NULL,
                  id MEDIUMINT NOT NULL AUTO_INCREMENT,
                  name CHAR(30) NOT NULL,
                  PRIMARY KEY (grp,id)
                  );
     INSERT INTO animals (grp,name) VALUES("mammal","dog"),("mammal","cat"),
                       ("bird","penguin"),("fish","lax"),("mammal","whale"),
                       ("bird","ostrich");
     SELECT * FROM animals ORDER BY grp,id;

Which returns:

     +--------+----+---------+
     | grp    | id | name    |
     +--------+----+---------+
     | fish   |  1 | lax     |
     | mammal |  1 | dog     |
     | mammal |  2 | cat     |
     | mammal |  3 | whale   |
     | bird   |  1 | penguin |
     | bird   |  2 | ostrich |
     +--------+----+---------+

Note that in this case (when the `AUTO_INCREMENT' column is part of a
multiple-column index), `AUTO_INCREMENT' values will be reused if you
delete the row with the biggest `AUTO_INCREMENT' value in any group.
This happens even for `MyISAM' tables, for which `AUTO_INCREMENT'
values normally are not reused.)

Queries from the Twin Project
=============================

At Analytikerna and Lentus, we have been doing the systems and field
work for a big research project. This project is a collaboration
between the Institute of Environmental Medicine at Karolinska
Institutet Stockholm and the Section on Clinical Research in Aging and
Psychology at the University of Southern California.

The project involves a screening part where all twins in Sweden older
than 65 years are interviewed by telephone. Twins who meet certain
criteria are passed on to the next stage. In this latter stage, twins
who want to participate are visited by a doctor/nurse team. Some of the
examinations include physical and neuropsychological examination,
laboratory testing, neuroimaging, psychological status assessment, and
family history collection. In addition, data are collected on medical
and environmental risk factors.

More information about Twin studies can be found at:
`http://www.mep.ki.se/twinreg/index_en.html'

The latter part of the project is administered with a web interface
written using Perl and MySQL.

Each night all data from the interviews is moved into a MySQL database.

Find All Non-distributed Twins
------------------------------

The following query is used to determine who goes into the second part
of the project:

     SELECT
             CONCAT(p1.id, p1.tvab) + 0 AS tvid,
             CONCAT(p1.christian_name, " ", p1.surname) AS Name,
             p1.postal_code AS Code,
             p1.city AS City,
             pg.abrev AS Area,
             IF(td.participation = "Aborted", "A", " ") AS A,
             p1.dead AS dead1,
             l.event AS event1,
             td.suspect AS tsuspect1,
             id.suspect AS isuspect1,
             td.severe AS tsevere1,
             id.severe AS isevere1,
             p2.dead AS dead2,
             l2.event AS event2,
             h2.nurse AS nurse2,
             h2.doctor AS doctor2,
             td2.suspect AS tsuspect2,
             id2.suspect AS isuspect2,
             td2.severe AS tsevere2,
             id2.severe AS isevere2,
             l.finish_date
     FROM
             twin_project AS tp
             /* For Twin 1 */
             LEFT JOIN twin_data AS td ON tp.id = td.id
                       AND tp.tvab = td.tvab
             LEFT JOIN informant_data AS id ON tp.id = id.id
                       AND tp.tvab = id.tvab
             LEFT JOIN harmony AS h ON tp.id = h.id
                       AND tp.tvab = h.tvab
             LEFT JOIN lentus AS l ON tp.id = l.id
                       AND tp.tvab = l.tvab
             /* For Twin 2 */
             LEFT JOIN twin_data AS td2 ON p2.id = td2.id
                       AND p2.tvab = td2.tvab
             LEFT JOIN informant_data AS id2 ON p2.id = id2.id
                       AND p2.tvab = id2.tvab
             LEFT JOIN harmony AS h2 ON p2.id = h2.id
                       AND p2.tvab = h2.tvab
             LEFT JOIN lentus AS l2 ON p2.id = l2.id
                       AND p2.tvab = l2.tvab,
             person_data AS p1,
             person_data AS p2,
             postal_groups AS pg
     WHERE
             /* p1 gets main twin and p2 gets his/her twin. */
             /* ptvab is a field inverted from tvab */
             p1.id = tp.id AND p1.tvab = tp.tvab AND
             p2.id = p1.id AND p2.ptvab = p1.tvab AND
             /* Just the sceening survey */
             tp.survey_no = 5 AND
             /* Skip if partner died before 65 but allow emigration (dead=9) */
             (p2.dead = 0 OR p2.dead = 9 OR
              (p2.dead = 1 AND
               (p2.death_date = 0 OR
                (((TO_DAYS(p2.death_date) - TO_DAYS(p2.birthday)) / 365)
                 >= 65))))
             AND
             (
             /* Twin is suspect */
             (td.future_contact = 'Yes' AND td.suspect = 2) OR
             /* Twin is suspect - Informant is Blessed */
             (td.future_contact = 'Yes' AND td.suspect = 1
                                        AND id.suspect = 1) OR
             /* No twin - Informant is Blessed */
             (ISNULL(td.suspect) AND id.suspect = 1
                                 AND id.future_contact = 'Yes') OR
             /* Twin broken off - Informant is Blessed */
             (td.participation = 'Aborted'
              AND id.suspect = 1 AND id.future_contact = 'Yes') OR
             /* Twin broken off - No inform - Have partner */
             (td.participation = 'Aborted' AND ISNULL(id.suspect)
                                           AND p2.dead = 0))
             AND
             l.event = 'Finished'
             /* Get at area code */
             AND SUBSTRING(p1.postal_code, 1, 2) = pg.code
             /* Not already distributed */
             AND (h.nurse IS NULL OR h.nurse=00 OR h.doctor=00)
             /* Has not refused or been aborted */
             AND NOT (h.status = 'Refused' OR h.status = 'Aborted'
             OR h.status = 'Died' OR h.status = 'Other')
     ORDER BY
             tvid;

Some explanations:
`CONCAT(p1.id, p1.tvab) + 0 AS tvid'
     We want to sort on the concatenated `id' and `tvab' in numerical
     order. Adding `0' to the result causes MySQL to treat the result
     as a number.

column `id'
     This identifies a pair of twins. It is a key in all tables.

column `tvab'
     This identifies a twin in a pair. It has a value of `1' or `2'.

column `ptvab'
     This is an inverse of `tvab'. When `tvab' is `1' this is `2', and
     vice versa. It exists to save typing and to make it easier for
     MySQL to optimize the query.

This query demonstrates, among other things, how to do lookups on a
table from the same table with a join (`p1' and `p2'). In the example,
this is used to check whether a twin's partner died before the age of
65. If so, the row is not returned.

All of the above exist in all tables with twin-related information. We
have a key on both `id,tvab' (all tables), and `id,ptvab'
(`person_data') to make queries faster.

On our production machine (A 200MHz UltraSPARC), this query returns
about 150-200 rows and takes less than one second.

The current number of records in the tables used above:
*Table*            *Rows*
`person_data'      71074
`lentus'           5291
`twin_project'     5286
`twin_data'        2012
`informant_data'   663
`harmony'          381
`postal_groups'    100

Show a Table of Twin Pair Status
--------------------------------

Each interview ends with a status code called `event'. The query shown
here is used to display a table over all twin pairs combined by event.
This indicates in how many pairs both twins are finished, in how many
pairs one twin is finished and the other refused, and so on.

     SELECT
             t1.event,
             t2.event,
             COUNT(*)
     FROM
             lentus AS t1,
             lentus AS t2,
             twin_project AS tp
     WHERE
             /* We are looking at one pair at a time */
             t1.id = tp.id
             AND t1.tvab=tp.tvab
             AND t1.id = t2.id
             /* Just the sceening survey */
             AND tp.survey_no = 5
             /* This makes each pair only appear once */
             AND t1.tvab='1' AND t2.tvab='2'
     GROUP BY
             t1.event, t2.event;

Using MySQL with Apache
=======================

There are programs that let you authenticate your users from a MySQL
database and also let you write your log files into a MySQL table.

You can change the Apache logging format to be easily readable by MySQL
by putting the following into the Apache configuration file:

     LogFormat \
             "\"%h\",%{%Y%m%d%H%M%S}t,%>s,\"%b\",\"%{Content-Type}o\",  \
             \"%U\",\"%{Referer}i\",\"%{User-Agent}i\""

To load a log file in that format into MySQL, you can use a statement
something like this:

     LOAD DATA INFILE '/local/access_log' INTO TABLE table_name
     FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"' ESCAPED BY '\\'

The named table should be created to have columns that correspond to
those that the `LogFormat' line writes to the log file.

Using MySQL Programs
********************

This chapter provides a brief overview of the programs provided by
MySQL AB and discusses how to specify options when you run these
programs.  Most programs have options that are specific to their own
operation, but the syntax for specifying options is similar for all of
them. Later chapters provide more detailed descriptions of individual
programs, including which options they recognize.

Overview of MySQL Programs
==========================

MySQL AB provides several types of programs:

The MYSQL server and server startup scripts:
        * `mysqld' is the MySQL server

        * `mysqld_safe', `mysql.server', and `mysqld_multi' are server
          startup scripts

        * `mysql_install_db' initializes the data directory and the
          initial databases

Client programs that access the server:
        * `mysql' is a command-line client for executing SQL statements
          interactively or in batch mode

        * `mysqlcc' (MySQL Control Center) is an interactive graphical
          tool for executing SQL statements and administration

        * `mysqladmin' is an administrative client

        * `mysqlcheck' performs table maintenance operations

        * `mysqldump' and `mysqlhotcopy' make database backups

        * `mysqlimport' imports data files

        * `mysqlshow' displays information about databases and tables

Utility programs that operate independently of the server:
        * `myisamchk' performs table maintenance operations

        * `myisampack' produces compressed, read-only tables

        * `mysqlbinlog' is a tool for processing binary log files

        * `mysql_config' shows command-line options for compiling MySQL
          programs

        * `perror' displays error code meanings

More information on running the server may be found in *Note Database
Administration::.  Client and utility programs are described in more
detail in *Note Client-Side Scripts::.

Most MySQL distribution formats include all of these programs, except
for those programs that are platform-specific. (For example, the server
startup scripts are not used on Windows.) The exception is that RPM
distributions are more specialized. There is one RPM for the server,
another for the client programs, and so forth. If you appear to be
missing one or more programs, see *Note Installing:: for information on
distributions and what they contain.  It may be that you need to
install something else.

Invoking MySQL Programs
=======================

To invoke a MySQL program at the command line (that is, from your shell
or command prompt), enter the program name followed by any options or
other arguments needed to instruct the program what you want it to do.
The following commands show some sample program invocations. "`shell>'"
represents your command prompt; it is not part of what you type.

     shell> mysql test
     shell> mysqldump --quote-names personnel
     shell> mysqladmin extended-status variables
     shell> mysqlshow --help

Arguments that begin with a dash are option arguments. They typically
specify the type of connection a program should make to the server or
affect its operational mode. Options have a syntax that is described in
*Note Program Options::.

Non-option arguments (arguments with no leading dash) provide additional
information to the program. For example, the `mysql' program interprets
the first non-option argument as a database name, so the command `mysql
test' indicates that you want to use the `test' database.

Later sections that describe individual programs indicate which options
a program understands and describe the meaning of any additional
non-option arguments.

Some options are common to a number of programs. The most common of
these are the `--host', `--user', and `--password' options that specify
connection parameters. They indicate the host where the MySQL server is
running, and the username and password of your MySQL account. All MySQL
client programs understand these options; they allow you to specify
which server to connect to and the account to use on that server.

Note that you may find it necessary to invoke MySQL programs using the
pathname to the `bin' directory in which they are installed. This is
likely to be the case if you get a "program not found" error whenever
you attempt to run a MySQL program from any directory other than the
`bin' directory.  To make it more convenient to use MySQL, you can add
the pathname of the `bin' directory to your `PATH' environment variable
setting. Then to run a program you need only type its name, not its
entire pathname.

Consult the documentation for your command interpreter for instructions
on setting your `PATH'; the syntax for setting environment variables is
interpreter-specific.

Specifying Program Options
==========================

You can provide options for MySQL programs in several ways:

   * On the command line following the program name. This is most
     common for options that apply to a specific invocation of the
     program.

   * In an option file that the program reads when it starts. This is
     common for options that you want the program to use each time it
     runs.

   * In environment variables. These are useful for options that you
     want to apply each time the program runs, though in practice
     option files are used more commonly for this purpose.  (*Note
     Multiple Unix servers:: discusses one situation in which
     environment variables can be very helpful. It describes a handy
     technique that uses such variables to specify the TCP/IP port and
     Unix socket file for both the server and client programs.)


MySQL programs determine which options are given by examining
environment variables first, then option files, then the command line.
If an option is specified multiple times, the last occurrence takes
precedence.  This means that environment variables have the lowest
precedence and command-line options the highest.

You can take advantage of the way that MySQL programs process options by
specifying the default value for a program's options in an option file.
Then you need not type them each time you run the program, but can
override the defaults if necessary by using command-line options.

Using Options on the Command Line
---------------------------------

Program options specified on the command line follow these rules:

   * Options are given after the command name.

   * An option argument begins with one dash or two dashes, depending
     on whether it has a short name or a long name. Many options have
     both forms.  For example, `-?' and `--help' are the short and long
     forms of the option that instructs a MySQL program to display a
     help message.

   * Option names are case sensitive.  `-v' and `-V' are both legal and
     have different meanings. (They are the corresponding short forms
     of the `--verbose' and `--version' options.)

   * Some options take a value following the option name.  For example,
     `-h localhost' or `--host=localhost' indicate the MySQL server
     host to a client program.  The option value tells the program the
     name of the host where the MySQL server is running.

   * For a long option that takes a value, separate the option name and
     the value by an `=' sign.  For a short option that takes a value,
     the option value can immediately follow the option letter, or
     there can be a space between.  (`-hlocalhost' and `-h localhost'
     are equivalent.)  An exception to this rule is the option for
     specifying your MySQL password.  This option can be given in long
     form as `--password=pass_val' or as `--password'. In the latter
     case (with no password value given), the program will prompt you
     for the password.  The password option also may be given in short
     form as `-ppass_val' or as `-p'. However, for the short form, if
     the password value is given, it must follow the option letter
     _with no intervening space_. The reason for this is that if a
     space follows the option letter, the program has no way to tell
     whether a following argument is supposed to be the password value
     or some other kind of argument.  Consequently, the following two
     commands have two completely different meanings:

          shell> mysql -ptest
          shell> mysql -p test

     The first command instructs `mysql' to use a password value of
     `test', but specifies no default database.  The second instructs
     `mysql' to prompt for the password value and to use `test' as the
     default database.


MySQL 4.0 introduced some additional flexibility in the way you specify
options. These changes were made in MySQL 4.0.2. Some of them relate to
the way you specify options that have "enabled" and "disabled" states,
and to the use of options that may be present in one version of MySQL
but not another.  Those capabilities are discussed here.  Another
change pertains to the way you use options to set program variables.
*Note Program variables:: discusses that topic further.

Some options control behavior that can be turned on or off. For example,
the `mysql' client supports a `--column-names' option that determines
whether or not to display a row of column names at the beginning of
query results. By default, this option is enabled. However, you may
want to disable it in some instances, such as when sending the output
of `mysql' into another program that expects to see only data and not
an initial header line.

To disable column names, you can specify the option using any of these
forms:

     --disable-column-names
     --skip-column-names
     --column-names=0

The `--disable' and `--skip' prefixes and the `=0' suffix all have the
same effect of turning the option off.

The "enabled" form of the option may be specified as:

     --column-names
     --enable-column-names
     --column-names=1

Another change to option processing introduced in MySQL 4.0 is that you
can use the `--loose' prefix for command-line options. If an option is
prefixed by `--loose', the program will not exit with an error if it
does not recognize the option, but instead will issue only a warning:

     shell> mysql --loose-no-such-option
     mysql: WARNING: unknown option '--no-such-option'

The `--loose' prefix can be useful when you run programs from multiple
installations of MySQL on the same machine, at least if all the
versions are as recent as 4.0.2.  This prefix is particularly useful
when you list options in an option file.  An option that may not be
recognized by all versions of a program can be given using the `--loose'
prefix (or `loose' in an option file). Versions of the program that do
not recognize the option will issue a warning and ignore it. Note that
this strategy works only if all versions involved are 4.0.2 or later,
because earlier versions know nothing of the `--loose' convention.

Using Option Files
------------------

MySQL programs can read startup options from option files (also
sometimes called configuration files).  Option files provide a
convenient way to specify commonly used options so they need not be
entered on the command line each time you run a program.  Option file
capability is available from MySQL 3.22 on.

The following programs support option files:  `mysql', `mysqladmin',
`mysqld', `mysqld_safe', `mysql.server', `mysqldump', `mysqlimport',
`mysqlshow', `mysqlcheck', `mysqlhotcopy', `myisamchk', and
`myisampack'.

On Windows, MySQL programs read startup options from the following
files:

*Filename*             *Purpose*
`windows-dir\my.ini'   Global options
`C:\my.cnf'            Global options

`windows-dir' represents the location of your Windows directory.  This
is commonly `C:\Windows' or `C:\WinNT'. Check the value of the `WINDIR'
environment vairable to see where this directory is located on your
system.

On Unix, MySQL programs read startup options from the following files:

*Filename*             *Purpose*
`/etc/my.cnf'          Global options
`DATADIR/my.cnf'       Server-specific options
`defaults-extra-file'  The file specified with
                       `--defaults-extra-file=path', if any
`~/.my.cnf'            User-specific options

`DATADIR' represents the location of the MySQL data directory. Typically
this is `/usr/local/mysql/data' for a binary installation or
`/usr/local/var' for a source installation.  Note that this is the data
directory location that was specified at configuration time, not the
one specified with `--datadir' when `mysqld' starts!  Use of
`--datadir' at runtime has no effect on where the server looks for
option files, because it looks for them before processing any
command-line arguments.

MySQL looks for option files in the order listed above and reads any
that exist.  If multiple option files exist, an option specified in a
file read later takes precedence over the same option specified in a
file read earlier.

Any long option that may be given on the command-line when running a
MySQL program can be given in an option file as well.  To get the list
of available options for a program, run it with the `--help' option.

The syntax for specifying options in an option file is similar to
command-line syntax, except that you omit the leading two dashes. For
example, `--quick' or `--host=localhost' on the command line are
specified as `quick' or `host=localhost' in an option file.  To specify
an option of the form `--loose-opt_name' in an option file, write it as
`loose-opt_name'.

Empty lines in option files are ignored. Non-empty lines can take any
of the following forms:

`#comment'
`;comment'
     Comment lines start with `#' or `;'. As of MySQL 4.0.14, a
     `#'-comment can start in the middle of a line as well.

`[group]'
     `group' is the name of the program or group for which you want to
     set options.  After a group line, any `option' or `set-variable'
     lines apply to the named group until the end of the option file or
     another group line is given.

`opt_name'
     This is equivalent to `--opt_name' on the command-line.

`opt_name=value'
     This is equivalent to `--opt_name=value' on the command-line.  In
     an option file, you can have spaces around the `=' character,
     something that is not true on the command line.  As of MySQL
     4.0.16, you can quote the value with double quotes or single
     quotes.  This is useful if the value contains a comment character
     or whitespace.

`set-variable = var_name=value'
     Set the program variable `var_name' to the given value.  This is
     equivalent to `--set-variable=var_name=value' on the command-line.
     Spaces are allowed around the first `=' character but not around
     the second.  This syntax is deprecated as of MySQL 4.0.  See *Note
     Program variables:: for more information on setting program
     variables.

Note that for options and values, all leading and trailing blanks are
automatically deleted.  You may use the escape sequences `\b', `\t',
`\n', `\r', `\\', and `\s' in option values to represent the backspace,
tab, newline, carriage return, and space characters.

On Windows, if an option value represents a pathname, you should
specify the value using `/' rather than `\' as the pathname separator.
If you use `\', you must double it as `\\', because `\' is the escape
character in MySQL.

If an option group name is the same as a program name, options in the
group apply specifically to that program.

The `[client]' option group is read by all client programs (but not by
`mysqld'). This allows you to specify options that apply to every
client. For example, `[client]' is the perfect group to use to specify
the password that you use to connect to the server.  (But make sure the
option file is readable and writable only by yourself, so that other
people cannot find out your password.) Be sure not to put an option in
the `[client]' group unless it is recognized by _all_ client programs.

As of MySQL 4.0.14, if you want to create options that should only be
read by one specific `mysqld' server release series, you can do this
with `[mysqld-4.0]', `[mysqld-4.1]', and so forth:

     [mysqld-4.0]
     new

The above `new' option will be used only with MySQL server versions
4.0.x.

Here is a typical global option file:

     [client]
     port=3306
     socket=/tmp/mysql.sock

     [mysqld]
     port=3306
     socket=/tmp/mysql.sock
     key_buffer_size=16M
     max_allowed_packet=1M

     [mysqldump]
     quick

Here is a typical user option file:

     [client]
     # The following password will be sent to all standard MySQL clients
     password="my_password"

     [mysql]
     no-auto-rehash
     set-variable = connect_timeout=2

     [mysqlhotcopy]
     interactive-timeout

If you have a source distribution, you will find sample option files
named `my-xxxx.cnf' in the `support-files' directory.  If you have a
binary distribution, look in the `support-files' directory under your
MySQL installation directory (typically `C:\mysql' on Windows or
`/usr/local/mysql' on Unix).  Currently there are sample option files
for small, medium, large, and very large systems. To experiment with
one of these files, copy it to `C:\my.cnf' on Windows or to `.my.cnf'
in your home directory on Unix.

All MySQL programs that support option files support the following
command-line options:

`--no-defaults'
     Don't read any option files.

`--print-defaults'
     Print the program name and all options that it will get from
     option files.

`--defaults-file=path_name'
     Use only the given option file. `path_name' is the full pathname
     to the file.

`--defaults-extra-file=path_name'
     Read this option file after the global option file but before the
     user option file. `path_name' is the full pathname to the file.

Note that to work properly, each of these options must immediately
follow the command name on the command line, with the exception that
`--print-defaults' may be used immediately after `--defaults-file' or
`--defaults-extra-file'.

In shell scripts, you can use the `my_print_defaults' program to parse
the option files. The following example shows the output that
`my_print_defaults' might produce when asked to show the options found
in the `[client]' and `[mysql]' groups:


     shell> my_print_defaults client mysql
     --port=3306
     --socket=/tmp/mysql.sock
     --no-auto-rehash

Note for developers:  Option file handling is implemented in the C
client library simply by processing all matching options (that is,
options in the appropriate group) before any command-line arguments.
This works nicely for programs that use the last instance of an option
that is specified multiple times. If you have a C or C++ program that
handles multiply specified options this way but doesn't read option
files, you need add only two lines to give it that capability.  Check
the source code of any of the standard MySQL clients to see how to do
this.

Several other language interfaces to MySQL are based on the C client
library, and some of them provide a way to access option file contents.
These include Perl and Python. See the documentation for your preferred
interface for details.

Using Environment Variables to Specify Options
----------------------------------------------

To specify an option using an environment variable, set the variable
using the syntax appropriate for your comment processor. For example,
on Windows or NetWare, you can set the `USER' variable to specify your
MySQL account name.  To do so, use this syntax:

     SET USER=your_name

The syntax on Unix depends on your shell. Suppose you want to specify
the TCP/IP port number using the `MYSQL_TCP_PORT' variable. The syntax
for Bourne shell and variants (`sh', `bash', `zsh', etc.) is:

     MYSQL_TCP_PORT=3306

For `csh' and `tcsh', use this syntax:

     setenv MYSQL_TCP_PORT 3306

The commands to set environment variables can be executed at your
command prompt to take effect immediately. These settings persist until
you log out.  To have the settings take effect each time you log in,
place the appropriate command or commands in a startup file that your
command interpreter reads each time it starts. Typical startup files are
`AUTOEXEC.BAT' for Windows, `.bash_profile' for `bash', or `.tcshrc'
for `tcsh'. Consult the documentation for your command interpreter for
specific details.

*Note Environment variables:: lists all environment variables that
affect MySQL program operation.

Using Options to Set Program Variables
--------------------------------------

Many MySQL programs have internal variables that can be set at runtime.
As of MySQL 4.0.2, program variables are set the same way as any other
long option that takes a value.  For example, `mysql' has a
`max_allowed_packet' variable that controls the maximum size of its
communication buffer.  To set the `max_allowed_packet' variable for
`mysql' to a value of 64 MB, use either of the following commands:

     shell> mysql --max_allowed_packet=6710740
     shell> mysql --max_allowed_packet=64M

The first command specifies the value in bytes. The second specifies
the value in megabytes. Variable values can have a suffix of `K', `M',
or `G' (either uppercase or lowercase) to indicate units of kilobytes,
megabytes, or gigabytes.

In an option file, the variable setting is given without the leading
dashes:

     [mysql]
     max_allowed_packet=6710740

Or:

     [mysql]
     max_allowed_packet=64M

If you like, underscores in a variable name can be specified as dashes.

Prior to MySQL 4.0.2, program variable names are not recognized as
option names.  Instead, use the `--set-variable' option to assign a
value to a variable:

     shell> mysql --set-variable=max_allowed_packet=6710740
     shell> mysql --set-variable=max_allowed_packet=64M

In an option file, omit the leading dashes:

     [mysql]
     set-variable = max_allowed_packet=6710740

Or:

     [mysql]
     set-variable = max_allowed_packet=64M

With `--set-variable', underscores in variable names may not be given as
dashes for versions of MySQL older than 4.0.2.

The `--set-variable' option is still recognized in MySQL 4.0.2 and up,
but is deprecated.

Database Administration
***********************

This chapter covers topics that deal with administering a MySQL
installation, such as configuring the server, managing user accounts,
and performing backups.

The MySQL Server and Server Startup Scripts
===========================================

The MySQL server, `mysqld', is the main program that does most of the
work in a MySQL installation. The server is accompanied by several
related scripts that perform setup operations when you install MySQL or
that are helper programs to assist you in starting and stopping the
server.

Overview of the Server-Side Scripts and Utilities
-------------------------------------------------

All MySQL programs take many different options. However, every MySQL
program provides a `--help' option that you can use to get a
description of the program's options. For example, try `mysqld --help'.

You can override default options for all standard programs by specifying
options on the command line or in an option file.  *Note Program
Options::.

The following list briefly describes the server-related MySQL programs:

`mysqld'
     The SQL daemon (that is, the MySQL server). To use client
     programs, this program must be running, because clients gain
     access to databases by connecting the the server.

`mysqld-max'
     A version of the server that includes additional features.

`mysqld_safe'
     A server startup script.  `mysqld_safe' attempts to start
     `mysqld-max' if it exists, and `mysqld' otherwise.

`mysql.server'
     A server startup script.  This script is used on systems that use
     run directories containing scripts that start system services for
     particular run levels. It invokes `mysqld_safe' to start the MySQL
     server.

`mysqld_multi'
     A server startup script that can start or stop multiple servers
     installed on the system.

`mysql_install_db'
     This script creates the MySQL grant tables with default
     privileges. It is usually executed only once, when first
     installing MySQL on a system.

`mysql_fix_privilege_tables'
     This script is used after an upgrade install operation, to update
     the grant tables with any changes that were made in newer versions
     of MySQL.

There are several other programs that also are run on the server host:

`myisamchk'
     A utility to describe, check, optimize, and repair MySQL tables.
     `myisamchk' is described in *Note Table maintenance::.

`make_binary_distribution'
     This program makes a binary release of a compiled MySQL. This
     could be sent by FTP to `/pub/mysql/Incoming' on
     `support.mysql.com' for the convenience of other MySQL users.

`mysqlbug'
     The MySQL bug reporting script.  It can be be used to send a bug
     report to the MySQL list. (You can also visit
     <http://bugs.mysql.com/> to file a bug report online.)

`mysqld-max', An Extended `mysqld' Server
-----------------------------------------

A MySQL-Max server is a version of the `mysqld' MySQL server that is
configured to include additional features.

You can find the MySQL-Max binaries at
`http://www.mysql.com/downloads/mysql-max-4.0.html'.

The MySQL binary distributions Windows include both the standard server
(named `mysqld.exe') and the MySQL-Max server (named `mysqld-max.exe').
`http://www.mysql.com/downloads/mysql-4.0.html'.  *Note Windows
installation::.

If you install MySQL on Linux using RPM distributions, install the
`MySQL-server' RPM first, and then the `MySQL-Max' RPM.  The latter
presupposes that you have already installed the regular server RPM.
This process installs a standard server named `mysqld' and a MySQL-Max
server named `mysqld-max'.

All other MySQL-Max distributions contain a single server that is named
`mysqld' but that has the additional features.

MySQL-Max servers are built by using the following `configure' options:

*Option*                  *Comment*
`--with-server-suffix=-max'Add a `-max' suffix to the `mysqld' version
                          string
`--with-innodb'           Support for `InnoDB' tables (MySQL 3.23 only)
`--with-bdb'              Support for Berkeley DB (`BDB') tables
`CFLAGS=-DUSE_SYMDIR'     Symbolic link support for Windows

MySQL-Max binary distributions are a convenience for those who wish to
install precompiled programs. If you build MySQL using a source
distribution, you can build your own Max-like server by enabling the
same features at configuration time that the MySQL-Max binary
distributions are built with.

MySQL-Max servers always include the `InnoDB' storage engine.  The
`--with-innodb' option for enabling `InnoDB' support is needed only in
MySQL 3.23. (In MySQL 4 and up, `InnoDB' is included by default.  so
you do not need a MySQL-Max server to obtain `InnoDB' support.)

MySQL-Max servers include the BerkeleyDB (`BDB') storage engine
whenever possible, but not all platforms support `BDB'.  The following
table shows which platforms allow MySQL-Max binaries to include `BDB':

*System*               `BDB'
Windows/NT             Y
AIX 4.3                N
HP-UX 11.0             N
Linux-Alpha            N
Linux-Intel            Y
Linux-IA-64            N
Solaris-Intel          N
Solaris-SPARC          Y
SCO OSR5               Y
UnixWare               Y
Mac OS X               N

As of Version 3.23, all MySQL servers support `MyISAM' tables, because
`MyISAM' is the default storage engine. To find out which storage
engines your server supports, issue the following statement:

     mysql> SHOW VARIABLES LIKE "have_%";
     +------------------+----------+
     | Variable_name    | Value    |
     +------------------+----------+
     | have_bdb         | NO       |
     | have_crypt       | YES      |
     | have_innodb      | YES      |
     | have_isam        | NO       |
     | have_raid        | NO       |
     | have_symlink     | DISABLED |
     | have_openssl     | NO       |
     | have_query_cache | YES      |
     +------------------+----------+

The values in the second column indicate the server's level of support
for each feature:

*Value*     *Meaning*
`YES'       The feature is supported and is active.
`NO'        The feature is not supported.
`DISABLED'  The feature is supported but has been disabled.

A value of `NO' means that the server was compiled without support for
the feature, so it cannot be activated at runtime.

A value of `DISABLED' occurs either because the server was started with
an option that disables the feature, or because not all options
required to enable it were given. In the latter case, the
`hostname.err' file should contain a reason indicating why the option
is disabled.

One situation in which you might see `DISABLED' occurs with MySQL 3.23
when the `InnoDB' storage engine is compiled in. In MySQL 3.23, you
must supply at least the `innodb_data_file_path' option at runtime to
set up the `InnoDB' tablespace. Without the options, `InnoDB' disables
itself.  *Note InnoDB in MySQL 3.23::.  (You can specify configuration
options for the `BDB' storage engine, too, but `BDB' will not disable
itself without them.  *Note BDB start::.)

You may also see `DISABLED' for the `InnoDB', `BDB', or `ISAM' storage
engines if the server was compiled to support them, but was started
with the `--skip-innodb', `--skip-bdb', or `--skip-isam' options at
runtime.

`mysqld_safe', The Wrapper Around `mysqld'
------------------------------------------

`mysqld_safe' is the recommended way to start a `mysqld' server on
Unix.  `mysqld_safe' adds some safety features such as restarting the
server when an error occurs and logging run-time information to a log
file.

*Note:* Before MySQL 4.0, `mysqld_safe' is named `safe_mysqld'.  To
preserve backward compatibility, MySQL binary distributions for some
time will include `safe_mysqld' as a symbolic link to `mysqld_safe'.

If you don't use `--mysqld=#' or `--mysqld-version=#' `mysqld_safe'
will use an executable named `mysqld-max' if it exists. If not,
`mysqld_safe' will start `mysqld'.

On Linux, the `MySQL-Max' RPM uses this `mysqld_safe' feature. (It just
installs the `mysqld-max' executable, so `mysqld_safe' automatically
uses this executable when `mysqld_safe' is restarted.)

The preference of `mysqld_safe' for `mysqld-max' over `mysqld' makes it
very easy to test a new `mysqld' binary in an existing installation.
Just run `configure' with the options you want and then install the new
`mysqld' binary as `mysqld-max' in the same directory where your
existing `mysqld' binary is located.

On the other hand, this behavior means that if you install a MySQL-Max
distribution that includes a server named `mysqld-max', then upgrade
later to a non-Max version of MySQL, `mysqld_safe' will still attempt
to run the old `mysqld-max' server.  If you perform such an upgrade,
manually remove the old `mysqld-max' server to ensure that
`mysqld_safe' runs the new `mysqld' server.

Normally, you should never edit the `mysqld_safe' script.  Instead, put
the options to `mysqld_safe' in the `[mysqld_safe]' section in a
`my.cnf' option file.  *Note Option files::.  `mysqld_safe' reads all
options from the `[mysqld]', `[server]' and `[mysqld_safe]' sections
from the option files.  (For backward compatibility, it also reads the
`[safe_mysqld]' sections, though you should rename such sections to
`[mysqld_safe]' once you begin using MySQL 4.0 or later.)

Note that all options specified to `mysqld_safe' on the command-line
are passed to `mysqld'.  If you wants to use any options for
`mysqld_safe' that `mysqld' doesn't support, you must specify them in
the option file.

Many of the options to `mysqld_safe' are the same as the options to
`mysqld'. *Note Server options::.

`mysqld_safe' supports the following options:

`--basedir=path'
     The path to the installation directory.

`--core-file-size=#'
     The size of the core file `mysqld' should be able to create. Passed
     to `ulimit -c'.

`--datadir=path'
     The path to the data directory.

`--defaults-extra-file=path'
     The name of an option file to be read in addition to the usual
     option files.

`--defaults-file=path'
     The name of an option file to be read instead of the usual option
     files.

`--err-log=path'
     Old form of the `--log-error' option, to be used before MySQL 4.0.

`--log-error=path'
     Write the error log to the above file. *Note Error log::.

`--ledir=path'
     The path to the directory containing the `mysqld' program.  Use
     this option to explicitly indicate the location of the server.

`--log=path'

`--mysqld=prog_name'
     The name of the server program (in the `ledir' directory) that you
     want to start.

`--mysqld-version=suffix'
     Similar to `--mysqld=' but here you only give the suffix for the
     server program name. The base name is assumed to be `mysqld'.  For
     example, if you use `--mysqld-version=max', `mysqld_safe' will
     start the `mysqld-max' program in the `ledir' directory.  If the
     argument to `--mysqld-version' is empty, `mysqld' in the `ledir'
     directory is used.

`--nice=#'
     Use the `nice' program to set the server's scheduling priority to
     the given value.  This option was added in MySQL 4.0.14.

`--no-defaults'
     Do not read any option files.

`--open-files-limit=#'
     The number of files `mysqld' should be able to open. Passed to
     `ulimit -n'. Note that you need to start `mysqld_safe' as `root'
     for this to work properly!

`--pid-file=path'
     The path to the process ID file.

`--port=#'
     The TCP/IP port number.

`--socket=path'
     The Unix socket file path.

`--timezone=#'
     Set the time zone (the `TZ') variable to the value of this
     parameter.

`--user=#'
The `mysqld_safe' script is written so that it normally is able to start
a server that was installed from either a source or a binary
distribution of MySQL, even those these normally install the server in
slightly different locations.  *Note Installation layouts::.
`mysqld_safe' expects one of the following conditions to be true:

   * The server and databases can be found relative to the directory
     from which `mysqld_safe' is invoked.  `mysqld_safe' looks under
     its working directory for `bin' and `data' directories (for binary
     distributions) or for `libexec' and `var' directories (for source
     distributions).  This condition should be met if you execute
     `mysqld_safe' from your MySQL installation directory (for example,
     `/usr/local/mysql' for a binary distribution).

   * If the server and databases cannot be found relative to the working
     directory, `mysqld_safe' attempts to locate them by absolute
     pathnames.  Typical locations are `/usr/local/libexec' and
     `/usr/local/var'.  The actual locations are determined from the
     values configured into the distribution at the time it was built.
     They should be correct if MySQL is installed in the location
     specified at configuration time.

Because `mysqld_safe' will try to find the server and databases relative
to its own working directory, you can install a binary distribution of
MySQL anywhere, as long as you start `mysqld_safe' from the MySQL
installation directory:

     shell> cd mysql_installation_directory
     shell> bin/mysqld_safe &

If `mysqld_safe' fails, even when invoked from the MySQL installation
directory, you can specify the `--ledir' and `--datadir' options to
indicate the directories in which the server and databases are located
on your system.

In rare cases, it may be necessary to edit `mysqld_safe' to get it to
start the server properly. If you do this, note that if you upgrade
MySQL in the future, your modified version of `mysqld_safe' will be
overwritten, so you should make a copy of your edited version that you
can reinstall.

`mysql.server', A Server Startup Script for Run Directories
-----------------------------------------------------------

MySQL distributions on Unix include a script named `mysql.server'.  It
can be used on systems such as Linux and Solaris that use System V-style
run directories to start and stop system services.

On Linux systems, the server RPM distribution installs `mysql.server'
in `/etc/init.d' automatically under the name `mysql'.

If you install MySQL on Linux using another distribution format, or on
a System V-style system, you can install the script manually by copying
it to the `/etc/init.d' directory with the name `mysql'.  Make sure the
script is executable. (Use `chmod +x mysql'.)

The commands needed to activate the script depend on your operating
system.  On Linux, you can use `chkconfig':

     shell> chkconfig --add mysql

For other systems, consult your operating system documentation to see
how to install startup scripts.

`mysqld_multi', A Program for Managing Multiple MySQL Servers
-------------------------------------------------------------

`mysqld_multi' is meant for managing several `mysqld' processes that
listen for connections on different Unix socket files and TCP/IP ports.
It can start or stop servers, or report their current status.

The program searches for groups named `[mysqld#]' in `my.cnf' (or in
the file named by the `--config-file=...' option on the command line).
`#' can be any positive integer.  This number is referred to in the
following discussion as the option group number, or GNR.  Group numbers
distinquish option groups from one another and are used as arguments to
`mysqld_multi' to specify which servers you want to start, stop, or
obtain the status of.  Options listed in these groups are the same as
you would use in the usual `[mysqld]' group used for starting `mysqld'.
(See, for example, *Note Automatic start::.) However, when using
multiple servers it is necessary that each one use its own value for
options such as the Unix socket file and TCP/IP port number. For more
information on which options should be specified in a multiple-server
environment, see *Note Multiple servers::.

To invoke `mysqld_multi', use the following syntax:

     shell> mysqld_multi [OPTIONS] {start|stop|report} [GNR[,GNR]...]

`start', `stop', and `report' indicate the operation you want to
perform. You can perform the operation on a single server or multiple
servers, depending on the GNR list that follows the option name.  If
there is no list, `mysqld_multi' performs the operation for all servers
in the option file.

Each GNR value represents an option group number or range of group
numbers.  The value should be the number at the end of the group name
in the option file.  For example, the GNR for a group named `[mysqld17]'
is `17'.  To specify a range of numbers, separate the first and last
numbers by a dash.  The GNR value 10-13 represents groups `[mysqld10]'
through `[mysqld13]'.  Multiple groups or group ranges can be specified
on the command line, separated by commas.  There must be no whitespace
characters (spaces or tabs) in the GNR list. (Anything after a
whitespace character is ignored.)

This command starts a single server using option group `[mysqld17]':

     shell> mysqld_multi start 17

This command stops serveral servers, using option groups `[mysql8]' and
`[mysqld10]' through `[mysqld13]':

     shell> mysqld_multi start 8,10-13

For an example of how you might set up an option file, use this command:

     shell> mysqld_multi --example

`mysqld_multi' supports the following options:

`--config-file=...'
     Specify the name of an alternative option file. This affects where
     `mysqld_multi' looks for `[mysqld#]' option groups.  It does not
     affect where `mysqld_multi' reads its own options, which are always
     taken from the `[mysqld_multi]' group in the usual `my.cnf' file.
     Without this option, all options are read from the usual `my.cnf'
     file.

`--example'
     Display an example option file.

`--help'
     Print this help message and exit.

`--log=...'
     Specify the name of the log file. If the file exists, log output
     is appended to it.

`--mysqladmin=...'
     The `mysqladmin' binary to be used to stop servers.

`--mysqld=...'
     The `mysqld' binary to be used. Note that you can specify
     `mysqld_safe' as the value for this option also. The options are
     passed to `mysqld'. Just make sure you have the directory where
     `mysqld' is located in your `PATH' environment variable setting or
     fix `mysqld_safe'.

`--no-log'
     Print log information to stdout rather than to the log file. By
     default, output goes to the log file.

`--password=...'
     The password of the MySQL account to use when invoking
     `mysqladmin'.

`--tcp-ip'
     Connect to each MySQL server via the TCP/IP port instead of the
     Unix socket file.  (If a socket file is missing, the server may
     still be running, but accessible only via the TCP/IP port.)  By
     default, connections are made using the Unix socket file.  This
     option affects `stop' and `report' operations.

`--user=...'
     The username of the MySQL account to use when invoking
     `mysqladmin'.

`--version'
     Print the version number and exit.

Some notes about `mysqld_multi':

   * Make sure that the MySQL user who is stopping the `mysqld'
     services (using the `mysqladmin' program) has the same password
     and username for all the data directories accessed (to the `mysql'
     database). And make sure that the user has the `SHUTDOWN'
     privilege! If you have many data directories and many different
     `mysql' databases with different passwords for the MySQL `root'
     user, you may want to create a common `multi_admin' user for each
     using the same password (see below). Example how to do it:
          shell> mysql -u root -S /tmp/mysql.sock -proot_password -e
          "GRANT SHUTDOWN ON *.* TO multi_admin@localhost IDENTIFIED BY 'multipass'"
     *Note Privileges::.  You will have to do the above for each
     `mysqld' running in each data directory, that you have (just
     change the socket, `-S=...').

   * `pid-file' is very important, if you are using `mysqld_safe' to
     start `mysqld' (for example, `--mysqld=mysqld_safe') Every
     `mysqld' should have its own `pid-file'. The advantage using
     `mysqld_safe' instead of `mysqld' directly here is, that
     `mysqld_safe' "guards" every `mysqld' process and will restart it,
     if a `mysqld' process terminates due to a signal sent using `kill
     -9', or for other reasons such as a segmentation fault. Please
     note that the `mysqld_safe' script may require that you start it
     from a certain place. This means that you may have to `cd' to a
     certain directory, before you start the `mysqld_multi'. If you
     have problems starting, please see the `mysqld_safe' script. Check
     especially the lines:

          --------------------------------------------------------------------------
          MY_PWD=`pwd`
          # Check if we are starting this relative (for the binary release)
          if test -d $MY_PWD/data/mysql -a -f ./share/mysql/english/errmsg.sys -a \
           -x ./bin/mysqld
          --------------------------------------------------------------------------

     *Note `mysqld_safe': mysqld_safe.  The above test should be
     successful, or you may encounter problems.

   * Beware of the dangers of using multiple `mysqld' servers with the
     same data directory.  Use separate data directories, unless you
     *know* what you are doing!  *Note Multiple servers::.

   * The Unix socket file and the TCP/IP port must be different for
     every `mysqld'.

   * You may want to use option `--user' for `mysqld', but in order to
     do this you need to run the `mysqld_multi' script as the Unix
     `root' user. Having the option in the config file doesn't matter;
     you will just get a warning, if you are not the superuser and the
     `mysqlds' are started under *your* Unix account. *Important*: Make
     sure that the `pid-file' and the data directory are
     read+write(+execute for the latter one) accessible for *that* Unix
     user, who the specific `mysqld' process is started as. *Do not*
     use the Unix root account for this, unless you *know* what you are
     doing!

   * *Most important*: Before using `mysqld_multi' be sure that you
     understand the meanings of the options that are passed to the
     `mysqld' servers and *why* you would want to have separate
     `mysqld' processes. Starting multiple servers with the same data
     directory *will not* give you extra performance in a threaded
     system!  *Note Multiple servers::.

The following example shows how you might set up an option file for use
with `mysqld_multi'.  The first and fifth `[mysqld#]' group were
intentionally left out from the example.  You may have "gaps" in the
option file. This gives you more flexibility.  The order in which the
`mysqld' programs are started or stopped depends on the order in which
they appear in the option file.

     # This file should probably be in your home dir (~/.my.cnf)
     # or /etc/my.cnf
     # Version 2.1 by Jani Tolonen

     [mysqld_multi]
     mysqld     = /usr/local/bin/mysqld_safe
     mysqladmin = /usr/local/bin/mysqladmin
     user       = multi_admin
     password   = multipass

     [mysqld2]
     socket     = /tmp/mysql.sock2
     port       = 3307
     pid-file   = /usr/local/mysql/var2/hostname.pid2
     datadir    = /usr/local/mysql/var2
     language   = /usr/local/share/mysql/english
     user       = john

     [mysqld3]
     socket     = /tmp/mysql.sock3
     port       = 3308
     pid-file   = /usr/local/mysql/var3/hostname.pid3
     datadir    = /usr/local/mysql/var3
     language   = /usr/local/share/mysql/swedish
     user       = monty

     [mysqld4]
     socket     = /tmp/mysql.sock4
     port       = 3309
     pid-file   = /usr/local/mysql/var4/hostname.pid4
     datadir    = /usr/local/mysql/var4
     language   = /usr/local/share/mysql/estonia
     user       = tonu

     [mysqld6]
     socket     = /tmp/mysql.sock6
     port       = 3311
     pid-file   = /usr/local/mysql/var6/hostname.pid6
     datadir    = /usr/local/mysql/var6
     language   = /usr/local/share/mysql/japanese
     user       = jani

*Note Option files::.

Configuring MySQL
=================

This section discusses MySQL server configuration topics:

   * Startup options that the server supports.

   * How to set the server SQL mode.

`mysqld' Command-line Options
-----------------------------

When you start the `mysqld' server, you specify program options using
any of the methods described in *Note Program Options::. The most
common methods are to provide options in an option file or on the
command line. However, in most cases it is desirable to make sure the
server uses the same options each time it runs. The best way to ensure
this is to specify server options in an option file.  *Note Option
files::.

`mysqld' reads options from the `[mysqld]' and `[server]' groups.
`mysqld_safe' reads options from the `[mysqld]', `[server]',
`[mysqld_safe]' and `[safe_mysqld]' groups.  `mysql.server' reads
options from the `[mysqld]' and `[mysql.server]' groups.  An embedded
MySQL server usually reads options from the `[server]', `[embedded]'
and `[xxxxx_SERVER]' groups, where `xxxxx' is the name of the
application into which the server is embedded.

`mysqld' accepts many command-line options.  For a list, execute
`mysqld --help'. Before MySQL 4.1.1, `--help' prints the full help
message. As of 4.1.1, it prints a brief message; to see the full list,
use `mysqld --help --verbose'.

The following list shows some of the most common server options.
Options used for replication are listed in a separate section, see
*Note Replication Options::.

`--ansi'
     Use SQL-99 syntax instead of MySQL syntax.  *Note ANSI mode::.
     For more precise control over the server SQL mode, use the
     `--sql-mode' option instead.

`--basedir=path, -b path'
     The path to the installation directory. All paths are usually
     resolved relative to this.

`--big-tables'
     Allow large result sets by saving all temporary sets on file.
     This option prevents most "table full" errors, but also slows down
     queries for which in-memory tables would suffice.  Since Version
     3.23.2, MySQL is able to handle large result sets automatically by
     using memory for small temporary tables and switching to disk
     tables where necessary.

`--bind-address=IP'
     The IP address to bind to.

`--console'
     Write the error log messages to stderr/stdout even if `--log-error'
     is specified.  On Windows, `mysqld' will not close the console
     screen if this option is used.

`--character-sets-dir=path'
     The directory where character sets are installed.  *Note Character
     sets::.

`--chroot=path'
     Put the `mysqld' server in a closed environment during startup by
     using the `chroot()' system call. This is a recommended security
     measure as of MySQL 4.0. (MySQL 3.23 is not able to provide a
     `chroot()' jail that is 100% closed.)  Note that use of this
     option somewhat limits `LOAD DATA INFILE' and `SELECT ... INTO
     OUTFILE'.

`--core-file'
     Write a core file if `mysqld' dies.  For some systems, you must
     also specify the `--core-file-size' option to `mysqld_safe'.
     *Note `mysqld_safe': mysqld_safe.  Note that on some systems, such
     as Solaris, you will not get a core file if you are also using the
     `--user' option.

`--datadir=path, -h path'
     The path to the data directory.

`--debug[=...]'
     If MySQL is configured with `--with-debug', you can use this
     option to get a trace file of what `mysqld' is doing.  *Note
     Making trace files::.

`--default-character-set=charset'
     Set the default character set.  *Note Character sets::.

`--default-table-type=type'
     Set the default table type for tables.  *Note Table types::.

`--delay-key-write[= OFF | ON | ALL]'
     How the `DELAYED KEYS' option should be used.  Delayed key writing
     causes key buffers not to be flushed between writes for `MyISAM'
     tables.  `OFF' disables delayed key writes.  `ON' enables delayed
     key writes for those tables that were created with the `DELAYED
     KEYS' option.  `ALL' delays key writes for all `MyISAM' tables.
     Available as of MySQL 4.0.3.  *Note Server parameters::.

`--delay-key-write-for-all-tables'
     Old form of `--delay-key-write=ALL' for use prior to MySQL 4.0.3.
     As of 4.0.3, use `--delay-key-write' instead.

`--des-key-file=filename'
     Read the default keys used by `DES_ENCRYPT()' and `DES_DECRYPT()'
     from this file.

`--enable-external-locking'
     Enable system locking.  Note that if you use this option on a
     system on which `lockd' does not fully work (as on Linux), you
     will easily get `mysqld' to deadlock.  This option used to be
     named `--enable-locking'.

`--enable-named-pipe'
     Enable support for named pipes.  This option applies only on
     Windows NT, 2000, and XP systems, and may be used only with the
     `mysqld-nt' and `mysqld-max-nt' servers that support named pipe
     connections.

`--exit-info, -T'
     This is a bit mask of different flags you can use for debugging the
     `mysqld' server. Do not use this option unless you know exactly
     what it does!

`--flush'
     Flush all changes to disk after each SQL statement.  Normally MySQL
     only does a write of all changes to disk after each SQL statement
     and lets the operating system handle the syncing to disk.  *Note
     Crashing::.

`--help, -?'
     Display a short help message and exit.  Prior to MySQL 4.1.1,
     `--help' displays the full help message.  As of 4.1.1, it displays
     an abbreviated message only.  Use both the `--verbose' and
     `--help' options to see the full message.

`--init-file=file'
     Read SQL statements from this file at startup.

`--language=lang_name, -L lang_name'
     Client error messages in given language.  `lang_name' may be given
     as the language name or as the full pathname to the directory
     where the language files are installed.  *Note Languages::.

`--log[=file], -l [file]'
     Log connections and queries to this file. *Note Query log::. If
     you don't specify a file name, MySQL will use `hostname.log' as
     filename.

`--log-bin=[file]'
     Log all queries that change data to this file. Used for backup and
     replication.  *Note Binary log::.  If you don't specify a file
     name, MySQL will use `hostname-bin' as filename.

`--log-bin-index[=file]'
     The index file for binary log file names. *Note Binary log::.  If
     you don't specify file name, MySQL will use `hostname-bin.index' as
     filename.

`--log-error[=file]'
     Log errors and startup messages to this file. *Note Error log::.
     If you don't specify file name, MySQL will use `hostname.err' as
     filename.

`--log-isam[=file]'
     Log all `ISAM'/`MyISAM' changes to this file (used only when
     debugging `ISAM'/`MyISAM').

`--log-long-format'
     Log some extra information to the log files (update log, binary
     update log, and slow queries log, whatever log has been
     activated). For example, username and timestamp are logged for
     queries. If you are using `--log-slow-queries' and
     `--log-long-format', then queries that are not using indexes also
     are logged to the slow query log.  Note that `--log-long-format'
     is deprecated as of MySQL version 4.1, when `--log-short-format'
     was introduced (the long log format is the default setting since
     version 4.1). Also note that starting with MySQL 4.1 the
     `--log-queries-not-using-indexes' option is available for the
     purpose of logging queries that do not use indexes to the slow
     queries log.

`--log-queries-not-using-indexes'
     If you are using this option with `--log-slow-queries', then also
     queries that are not using indexes are logged to the slow query
     log. This option is available as of MySQL 4.1. *Note Slow query
     log::.

`--log-short-format'
     Log less information to the log files (update log, binary update
     log, and slow queries log, whatever log has been activated). For
     example, username and timestamp are not logged for queries. This
     options was introduced in MySQL 4.1.

`--log-slow-queries[=file]'
     Log all queries that have taken more than `long_query_time' seconds
     to execute to file. Note that the default for the amount of
     information logged has changed in MySQL 4.1. See the
     `--log-long-format' and `--log-long-format' options for details.
     *Note Slow query log::.

`--log-update[=file]'
     Log updates to `file.#' where `#' is a unique number if not given.
     *Note Update log::. The update log is deprecated and is removed in
     MySQL 5.0.0; you should use the binary log instead (`--log-bin').
     *Note Binary log::. Starting from version 5.0.0, using
     `--log-update' will just turn on the binlog instead (*note
     News-5.0.0::).

`--log-warnings, -W'
     Print out warnings like `Aborted connection...' to the `.err'
     file. Enabling this option is recommended, for example, if you use
     replication (you will get more information about what is happening,
     such as messages about network failures and reconnections). *Note
     Communication errors::.

     This option used to be called `--warnings'.

`--low-priority-updates'
     Table-modifying operations (`INSERT'/`DELETE'/`UPDATE') will have
     lower priority than selects.  It can also be done via `{INSERT |
     REPLACE | UPDATE | DELETE} LOW_PRIORITY ...' to lower the priority
     of only one query, or by `SET LOW_PRIORITY_UPDATES=1' to change
     the priority in one thread.  *Note Table locking::.

`--memlock'
     Lock the `mysqld' process in memory.  This works on systems such as
     Solaris that support the `mlockall()' system call.  This may help
     if you have a problem where the operating system is causing
     `mysqld' to swap on disk.  Note that use of this option requires
     that you run the server as `root', which is normally not a good
     idea for security reasons.

`--myisam-recover [=option[,option...]]]'
     Set the `MyISAM' storage engine recovery mode.  The option value
     is any combination of the values of `DEFAULT', `BACKUP', `FORCE'
     or `QUICK'.  If you specify multiple values, seprate them by
     commas.  You can also use a value of `""' to disable this option.
     If this option is used, `mysqld' will on open check if the table
     is marked as crashed or if the table wasn't closed properly.  (The
     last option works only if you are running with
     `--skip-external-locking'.)  If this is the case `mysqld' will run
     check on the table. If the table was corrupted, `mysqld' will
     attempt to repair it.

     The following options affects how the repair works.

     *Option*   *Description*
     `DEFAULT'  The same as not giving any option to
                         `--myisam-recover'.
     `BACKUP'   If the data table was changed during recover,
                save a                     backup of the
                `table_name.MYD' datafile as
                 `table_name-datetime.BAK'.
     `FORCE'    Run recover even if we will lose more than one
                row                     from the `.MYD' file.
     `QUICK'    Don't check the rows in the table if there
                aren't any                     delete blocks.

     Before a table is automatically repaired, MySQL will add a note
     about this in the error log.  If you want to be able to recover
     from most problems without user intervention, you should use the
     options `BACKUP,FORCE'.  This will force a repair of a table even
     if some rows would be deleted, but it will keep the old datafile
     as a backup so that you can later examine what happened.

`--new'
     From version 4.0.12, the `--new' option can be used to make the
     server behave as 4.1 in certain respects, easing a 4.0 to 4.1
     upgrade:
        * `TIMESTAMP' is returned as a string with the format
          `'YYYY-MM-DD HH:MM:SS''.  *Note Column types::.

     This option can be used to help you see how your applications will
     behave in MySQL 4.1, without actually upgrading to 4.1.

`--pid-file=path'
     The path to pid file used by `mysqld_safe'.

`--port=num, -P num'
     The port number to listen for TCP/IP connections.

`--old-protocol, -o'
     Use the 3.20 protocol for compatibility with some very old clients.
     *Note Upgrading-from-3.20::.

`--one-thread'
     Only use one thread (for debugging under Linux).  This option is
     available only if the server is built with debugging enabled.
     *Note Debugging server::.

`--open-files-limit='
     To change the number of file descriptors available to `mysqld'.
     If this is not set or set to 0, then `mysqld' will use this value
     to reserve file descriptors to use with `setrlimit()'.  If this
     value is 0 then `mysqld' will reserve `max_connections*5' or
     `max_connections + table_cache*2' (whichever is larger) number of
     files.  You should try increasing this if `mysqld' gives you the
     error 'Too many open files'.

`--set-variable=name=value, -O value'
     Assign a value to a system variable.  Use `--help' to list the
     variables.  You can find a full description for all variables in
     the `SHOW VARIABLES' section in this manual.  *Note `SHOW
     VARIABLES': SHOW VARIABLES.  The section on tuning server
     parameters includes information on how to optimize them.  *Note
     Server parameters::.

     Please note that `--set-variable=name=value' and `-O name=value'
     syntax is deprecated as of MySQL 4.0.2.  In 4.0.2, you can set
     variables directly using `--variable-name=value' syntax, and
     `--set-variable' is no longer needed.

     If you want to restrict the maximum value a startup option can be
     set to with `SET', you can define this by using the
     `--maximum-variable-name' command line option.  *Note `SET
     OPTION': SET OPTION.

     Note that when setting a variable to a value, MySQL may
     automatically correct it to stay within a given range, or adjust
     the value to the closest allowable value if only certain values
     are allowed.

`--safe-mode'
     Skip some optimize stages.

`--safe-show-database'
     With this option, the `SHOW DATABASES' statement returns only those
     databases for which the user has some kind of privilege.  From
     version 4.0.2 this option is deprecated and doesn't do anything
     (the option is enabled by default) as we now have the `SHOW
     DATABASES' privilege. *Note `GRANT': GRANT.

`--safe-user-create'
     If this is enabled, a user can't create new users with the `GRANT'
     statement, if the user doesn't have `INSERT' privilege to the
     `mysql.user' table or any column in this table.

`--skip-bdb'
     Disable the `BDB' storage engine. This saves memory and may speed
     up some operations.  Do not use this operation if you require
     `BDB' tables.

`--skip-concurrent-insert'
     Turn off the ability to select and insert at the same time on
     `MyISAM' tables. (This is only to be used if you think you have
     found a bug in this feature.)

`--skip-delay-key-write'
     Ignore the `DELAY_KEY_WRITE' option for all tables.  As of MySQL
     4.0.3, you should use `--delay-key-write=OFF' instead.  *Note
     Server parameters::.

`--skip-external-locking'
     Don't use system locking.  To use `isamchk' or `myisamchk' you must
     shut down the server.  *Note Stability::.  Note that in MySQL
     Version 3.23, you can use `CHECK TABLE' and `REPAIR TABLE' to
     check and repair`MyISAM' tables.  This option used to be named
     `--skip-locking'.

`--skip-grant-tables'
     This option causes the server not to use the privilege system at
     all.  This gives everyone *full access* to all databases!  (You
     can tell a running server to start using the grant tables again by
     executing a `mysqladmin flush-privileges' or `mysqladmin reload'
     command, or by issuing a `FLUSH PRIVILEGES' statement.)

`--skip-host-cache'
     Do not use the internal hostname cache for faster name-IP
     resolution. Instead, query the DNS server every time a client
     connects.  *Note DNS::.

`--skip-innodb'
     Disable the `InnoDB' storage engine.  This saves memory and disk
     space and may speed up some operations.  Do not use this operation
     if you require `InnoDB' tables.

`--skip-isam'
     Disable the `ISAM' storage engine.  As of MySQL 4.1, `ISAM' is
     disabled by default, so this option applies only if the server was
     configured with support for `ISAM'.  This option was added in
     MySQL 4.1.1.

`--skip-name-resolve'
     Do not resolve hostnames when checking client connections. Use
     only IP numbers. If you use this option, all `Host' column values
     in the grant tables must be IP numbers or `localhost'.  *Note
     DNS::.

`--skip-networking'
     Don't listen for TCP/IP connections at all.  All interaction with
     `mysqld' must be made via named pipes (on Windows) or Unix socket
     files (on Unix).  This option is highly recommended for systems
     where only local clients are allowed.  *Note DNS::.

`--skip-new'
     Don't use new, possibly wrong routines.

`--skip-symlink'
     This is the old form of `--skip-symbolic-links', for use before
     MySQL 4.0.13.

`--symbolic-links, --skip-symbolic-links'
     Enable or disable symbolic link support. This option has different
     effects on Windows and Unix:

        * On Windows, enabling symbolic links allows you to establish a
          symbolic link to a database directory by creating a
          `directory.sym' file that contains the path to the real
          directory.  *Note Windows symbolic links::.

        * On Unix, enabling symbolic links means that you can link a
          `MyISAM' index file or datafile to another directory with the
          `INDEX DIRECTORY' or `DATA DIRECTORY' options of the `CREATE
          TABLE' statement.  If you delete or rename the table, the
          files that its symbolic links point to also are deleted or
          renamed. *Note `CREATE TABLE': CREATE TABLE.

     This option was added in MySQL 4.0.13.

`--skip-safemalloc'
     If MySQL is configured with `--with-debug=full', all MySQL programs
     checks for memory overruns during each memory allocation and memory
     freeing operation.  This checking is very slow, so for the server
     you can avoid it when you don't need it by using the
     `--skip-safemalloc' option.

`--skip-show-database'
     Don't allow the `SHOW DATABASES' statement, unless the user has the
     `SHOW DATABASES' privilege.

`--skip-stack-trace'
     Don't write stack traces.  This option is useful when you are
     running `mysqld' under a debugger. On some systems, you also must
     use this option to get a core file. *Note Debugging server::.

`--skip-thread-priority'
     Disable using thread priorities for faster response time.

`--socket=path'
     On Unix, this option specifies the Unix socket file to use for
     local connections. The default value is `/tmp/mysql.sock'.  On
     Windows, the option specifies the pipe name to use for local
     connections that use a named pipe. The default value is `MySQL'.

`--sql-mode=value[,value[,value...]]'
     Set the SQL mode for MySQL. *Note SQL mode::. This option was
     added in 3.23.41.

`--temp-pool'
     This option causes most temporary files created by the server to
     use a small set of names, rather than a unique name for each new
     file. This works around a problem in the Linux kernel dealing with
     creating many new files with different names. With the old
     behavior, Linux seems to "leak" memory, as it's being allocated to
     the directory entry cache rather than to the disk cache.

`--transaction-isolation=level'
     Sets the default transaction isolation level, which may be
     `READ-UNCOMMITTED', `READ-COMMITTED', `REPEATABLE-READ', or
     `SERIALIZABLE'.  *Note `SET TRANSACTION': SET TRANSACTION.

`--tmpdir=path, -t path'
     The path of the directory to use for creating temporary files. It
     may be useful if your default `/tmp' directory resides on a
     partition that is too small to hold temporary tables.  Starting
     from MySQL 4.1, this option accepts several paths that are used in
     round-robin fashion. Paths should be separated by colon characters
     (`:') on Unix and semicolon characters (`;') on Windows.  It is
     possible to set `tmpdir' to point to a memory-based filesystem,
     except if the MySQL server is a slave replication server. If it is
     a slave, some of its temporary files are needed to survive a
     machine's reboot.  (For example, to replicate temporary tables or
     `LOAD DATA INFILE' statements).  In this case, a memory-based
     `tmpdir' that is cleared when the machine reboots is not suitable;
     a disk-based `tmpdir' is necessary.

`--user={user_name | user_id}, -u {user_name | user_id}'
     Run the `mysqld' server as the user having the name `user_name' or
     the numeric user ID `user_id'.  ("User" in this context refers to
     a system login account, not a MySQL user listed in the grant
     tables.)

     This option is *mandatory* when starting `mysqld' as `root'.  The
     server will change its user ID during its startup sequence,
     causing it to run as that particular user rather than as `root'.
     *Note Security guidelines::.

     Starting from MySQL 3.23.56 and 4.0.12: To avoid a possible
     security hole where a user adds a `--user=root' option to some
     `my.cnf' file (thus causing the server to run as `root'), `mysqld'
     uses only the first `--user' option specified and produces a
     warning if there are multiple `--user' options. Options in
     `/etc/my.cnf' and `datadir/my.cnf' are processed before
     command-line options, so it is recommended that you put a `--user'
     option in `/etc/my.cnf' and specify a value other than `root'. The
     option in `/etc/my.cnf' will be found before any other `--user'
     options, which ensures that the server runs as a user other than
     `root', and that a warning results if any other `--user' option is
     found.

`--version, -V'
     Display version information and exit.

You can change the values of most system variables for a running server
with the `SET' statement. *Note `SET OPTION': SET OPTION.

The Server SQL Mode
-------------------

The MySQL server can operate in different SQL modes, and (as of MySQL
4.1) can apply these modes differentially for different clients. This
allows applications to tailor server operation to their own
requirements.

Modes define what SQL syntax MySQL should support and what kind of data
validation checks it should perform.  This makes it easier to use MySQL
in different environments and to use MySQL together with other database
servers.

You can set the default SQL mode by starting `mysqld' with the
`--sql-mode="modes"' option. Beginning with MySQL 4.1, you can also
change the mode after startup time by setting the `sql_mode' variable
with a `SET [SESSION|GLOBAL] sql_mode='modes'' statement.  Setting the
`GLOBAL' variable affects the operation of all clients that connect
from that time on. Setting the `SESSION' variable affects only the
current client.  `modes' is a list of different modes separated by
comma (`,') characters.  You can retrieve the current mode by issuing a
`SELECT @@sql_mode' statement. The default value is empty (no modes
set).

The value also can be empty (`--sql-mode=""') if you want to reset it.

The following table lists the supported modes. The *Version* column
indicates when each mode value was implemented.

*Value*        *Version**Meaning*
`ANSI_QUOTES'  4.0.0   Treat `"' 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. With
                       `ANSI_QUOTES' enabled, you cannot use double
                       quotes to quote a literal string, because it will
                       be intepreted as an identifier.
`IGNORE_SPACE' 4.0.0   Allow spaces between a function name and the `('
                       character.  This forces all function names to be
                       treated as reserved words. As a result, if you
                       want to access any database, table, or column
                       name that is a reserved word, you must quote it.
                       For example, because there is a `USER()'
                       function, the name of the `user' table in the
                       `mysql' database and the `User' column in that
                       table become reserved, so you must quote them:
                            SELECT "User" FROM mysql."user";
`NO_AUTO_VALUE_ON_ZERO'4.1.1    `NO_AUTO_VALUE_ON_ZERO' affects handling of
                       `AUTO_INCREMENT' columns. Normally, you generate
                       the next sequence number for the column by
                       inserting either `NULL' or `0' into it.
                       `NO_AUTO_VALUE_ON_ZERO' suppresses this behavior
                       for `0' so that only `NULL' generates the next
                       sequence number. This mode can be useful if `0'
                       has been stored in a table's `AUTO_INCREMENT'
                       column. (This is not a recommended practice, by
                       the way.)  For example, if you dump the table
                       with `mysqldump' and then reload it, normally
                       MySQL will generate new sequence numbers when it
                       encounters the `0' values, resulting in a table
                       with different contents than the one that was
                       dumped. Enabling `NO_AUTO_VALUE_ON_ZERO' before
                       reloading the dump file solves this problem. (As
                       of MySQL 4.1.1, `mysqldump' automatically
                       includes statements in the dump output to enable
                       `NO_AUTO_VALUE_ON_ZERO'.)
`NO_DIR_IN_CREATE'4.0.15  When creating a table, ignore all `INDEX
                       DIRECTORY' and `DATA DIRECTORY' directives. This
                       option is useful on slave replication servers.
`NO_FIELD_OPTIONS'4.1.1   Don't print MySQL field-specific options in the
                       output of `SHOW CREATE TABLE'. This mode is used
                       by `mysqldump' in portability mode.
`NO_KEY_OPTIONS'4.1.1   Don't print MySQL index-specific options in the
                       output of `SHOW CREATE TABLE'. This mode is used
                       by `mysqldump' in portability mode.
`NO_TABLE_OPTIONS'4.1.1   Don't print MySQL table-specific options (such as
                       `ENGINE') in the output of `SHOW CREATE TABLE'.
                       This mode is used by `mysqldump' in portability
                       mode.
`NO_UNSIGNED_SUBTRACTION'4.0.2   In subtraction operations, don't mark the result
                       as `UNSIGNED' if one of the operands is unsigned.
                       Note that this makes `UNSIGNED BIGINT' not 100%
                       usable in all contexts. *Note Cast Functions::.
`ONLY_FULL_GROUP_BY'4.0.0   Don't allow queries which in the `GROUP BY' part
                       refers to a not selected column.
`PIPES_AS_CONCAT'4.0.0   Treat `||' as a string concatenation operator
                       (same as `CONCAT()') rather than as a synonym for
                       `OR'.
`REAL_AS_FLOAT'4.0.0   Treat `REAL' as a synonym for `FLOAT' rather than
                       as a synonym for `DOUBLE'.

The following special modes are provided as shorthand for combinations
of mode values from the preceding table:

*Value*        `Version'*Meaning*
`ANSI'         4.1.1   `REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ONLY_FULL_GROUP_BY'.
                       *Note ANSI mode::.
`DB2'          4.1.1   `PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,NO_KEY_OPTIONS,NO_TABLE_OPTIONS,NO_FIELD_OPTIONS'
`DB2'          4.1.1   `PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,NO_KEY_OPTIONS,NO_TABLE_OPTIONS,NO_FIELD_OPTIONS'
`MAXDB'        4.1.1   `PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,NO_KEY_OPTIONS,NO_TABLE_OPTIONS,NO_FIELD_OPTIONS'
`MSSQL'        4.1.1   `PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,NO_KEY_OPTIONS,NO_TABLE_OPTIONS,NO_FIELD_OPTIONS'
`MYSQL323'     4.1.1   `NO_FIELD_OPTIONS'
`MYSQL40'      4.1.1   `NO_FIELD_OPTIONS'
`ORACLE'       4.1.1   `PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,NO_KEY_OPTIONS,NO_TABLE_OPTIONS,NO_FIELD_OPTIONS'
`POSTGRESQL'   4.1.1   `PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,NO_KEY_OPTIONS,NO_TABLE_OPTIONS,NO_FIELD_OPTIONS'

General Security Issues
=======================

This section describes some general security issues to be aware of and
what you can do to make your MySQL installation more secure against
attack or misuse. For information specifically about the access control
system that MySQL uses for setting up user accounts and checking
database access, see *Note Privilege system::.

General Security Guidelines
---------------------------

Anyone using MySQL on a computer connected to the Internet should read
this section to avoid the most common security mistakes.

In discussing security, we emphasize the necessity of fully protecting
the entire server host (not just the MySQL server) against all types of
applicable attacks: eavesdropping, altering, playback, and denial of
service. We do not cover all aspects of availability and fault tolerance
here.

MySQL uses security based on Access Control Lists (ACLs) for all
connections, queries, and other operations that users may attempt to
perform. There is also some support for SSL-encrypted connections
between MySQL clients and servers. Many of the concepts discussed here
are not specific to MySQL at all; the same general ideas apply to
almost all applications.

When running MySQL, follow these guidelines whenever possible:

   * *Do not ever give anyone (except MySQL `root' accounts) access to
     the `user' table in the `mysql' database!*  This is critical.
     *The encrypted password is the real password in MySQL.* Anyone who
     knows the password which is listed in the `user' table and has
     access to the host listed for the account *can easily log in as
     that user*.

   * Learn the MySQL access privilege system. The `GRANT' and `REVOKE'
     statements are used for controlling access to MySQL. Do not grant
     any more privileges than necessary. Never grant privileges to all
     hosts.

     Checklist:
        - Try `mysql -u root'. If you are able to connect successfully
          to the server without being asked for a password, you have
          problems. Anyone can connect to your MySQL server as the MySQL
          `root' user with full privileges!  Review the MySQL
          installation instructions, paying particular attention to the
          item about setting a `root' password.

        - Use the `SHOW GRANTS' statement and check to see who has
          access to what.  Then use the `REVOKE' statement to remove
          those privileges that are not necessary.

   * Do not store any plain-text passwords in your database. If your
     computer becomes compromised, the intruder can take the full list
     of passwords and use them. Instead, use `MD5()', `SHA1()' or some
     other one-way hashing function.

   * Do not choose passwords from dictionaries. There are special
     programs to break them. Even passwords like "xfish98" are very
     bad.  Much better is "duag98" which contains the same word "fish"
     but typed one key to the left on a standard QWERTY keyboard.
     Another method is to use "Mhall" which is taken from the first
     characters of each word in the sentence "Mary had a little lamb."
     This is easy to remember and type, but difficult to guess for
     someone who does not know it.

   * Invest in a firewall. This protects you from at least 50% of all
     types of exploits in any software. Put MySQL behind the firewall
     or in a demilitarized zone (DMZ).

     Checklist:
        - Try to scan your ports from the Internet using a tool such as
          `nmap'. MySQL uses port 3306 by default. This port should not
          be accessible from untrusted hosts. Another simple way to
          check whether or not your MySQL port is open is to try the
          following command from some remote machine, where
          `server_host' is the host where your MySQL server runs:

               shell> telnet server_host 3306

          If you get a connection and some garbage characters, the port
          is open, and should be closed on your firewall or router,
          unless you really have a good reason to keep it open. If
          `telnet' just hangs or the connection is refused, everything
          is OK; the port is blocked.

   * Do not trust any data entered by users of your applications. They
     can try to trick your code by entering special or escaped
     character sequences in web forms, URLs, or whatever application
     you have built. Be sure that your application remains secure if a
     user enters something like "`; DROP DATABASE mysql;'". This is an
     extreme example, but large security leaks and data loss may occur
     as a result of hackers using similar techniques, if you do not
     prepare for them.

     A common mistake is to protect only string data values.  Remember
     to check numeric data as well.  If an application generates a
     query such as `SELECT * FROM table WHERE ID=234' when a user
     enters the value `234', the user can enter the value `234 OR 1=1'
     to cause the application to generate the query `SELECT * FROM
     table WHERE ID=234 OR 1=1'.  As a result, the server retrieves
     every record in the table.  This exposes every record and causes
     excessive server load.  The simplest way to protect from this type
     of attack is to use apostrophes around the numeric constants:
     `SELECT * FROM table WHERE ID='234''. If the user enters extra
     information, it all becomes part of the string. In numeric context,
     MySQL automatically converts this string to a number and strips
     any trailing non-numeric characters from it.

     Sometimes people think that if a database contains only publicly
     available data, it need not be protected. This is incorrect.  Even
     if it is allowable to display any record in the database, you
     should still protect against denial of service attacks (for
     example, those that are based on the technique in the preceding
     paragraph that causes the server to waste resources). Otherwise,
     your server becomes unresponsive to legitimate users.

     Checklist:
        - Try to enter `'' and `"' in all your web forms. If you get
          any kind of MySQL error, investigate the problem right away.

        - Try to modify any dynamic URLs by adding `%22' (`"'), `%23'
          (`#'), and `%27' (`'') in the URL.

        - Try to modify datatypes in dynamic URLs from numeric ones to
          character ones containing characters from previous examples.
          Your application should be safe against this and similar
          attacks.

        - Try to enter characters, spaces, and special symbols rather
          than numbers in numeric fields. Your application should
          remove them before passing them to MySQL or else generate an
          error. Passing unchecked values to MySQL is very dangerous!

        - Check data sizes before passing them to MySQL.

        - Consider having your application connect to the database
          using a different username than the one you use for
          administrative purposes. Do not give your applications any
          access privileges they do not need.

   * Many application programming interfaces provide the means of
     escaping special characters in data values. Properly used, this
     prevents application users from entering values that cause the
     application to generate statements that have a different effect
     than you intend:
        - Users of PHP: Use the `mysql_escape_string()' function, which
          is based on the function of the same name in the MySQL C API.
          Prior to PHP 4.0.3, use  `addslashes()' instead.

        - Users of MySQL C API: Use the `mysql_real_escape_string()'
          API call.

        - Users of MySQL++: Use the `escape' and `quote' modifiers for
          query streams.

        - Users of Perl DBI: Use the `quote()' method or use
          placeholders.

        - Users of Java JDBC: Use a `PreparedStatement' object and
          placeholders.

     Other programming interfaces may have similar capabilities.

   * Do not transmit plain (unencrypted) data over the Internet. This
     information is accessible to everyone who has the time and ability
     to intercept it and use it for their own purposes. Instead, use an
     encrypted protocol such as SSL or SSH. MySQL supports internal SSL
     connections as of Version 4.0.0.  SSH port-forwarding can be used
     to create an encrypted (and compressed) tunnel for the
     communication.

   * Learn to use the `tcpdump' and `strings' utilities. For most cases,
     you can check whether MySQL data streams are unencrypted by
     issuing a command like the following:

          shell> tcpdump -l -i eth0 -w - src or dst port 3306 | strings

     (This works under Linux and should work with small modifications
     under other systems.)  Warning: If you do not see plaintext data,
     this doesn't always mean that the information actually is
     encrypted. If you need high security, you should consult with a
     security expert.

Making MySQL Secure Against Attackers
-------------------------------------

When you connect to a MySQL server, you should use a password.  The
password is not transmitted in clear text over the connection. Password
handling during the client connection sequence was upgraded in MySQL
4.1.1 to be very secure.  If you are using an older version of MySQL,
or are still using pre-4.1.1-style passwords, the encryption algorithm
is less strong and with some effort a clever attacker that can sniff
the traffic between the client and the server can crack the password.
(See *Note Password hashing:: for a discussion of the different
password handling methods.)  If the connection between the client and
the server goes through an untrusted network, you should use an SSH
tunnel to encrypt the communication.

All other information is transferred as text that can be read by anyone
who is able to watch the connection.  If you are concerned about this,
you can use the compressed protocol (in MySQL Version 3.22 and above)
to make traffic much more difficult to decipher.  To make the
connection even more secure, you should use SSH to get an encrypted
TCP/IP connection between a MySQL server and a MySQL client.  You can
find an `Open Source' SSH client at `http://www.openssh.org/', and a
commercial SSH client at `http://www.ssh.com/'.

If you are using MySQL 4.0 or newer, you can also use internal OpenSSL
support.  *Note Secure connections::.

To make a MySQL system secure, you should strongly consider the
following suggestions:

   * Use passwords for all MySQL users. A client program does not
     necessarily know the identify of the person running it. It is
     common for client/server applications that the user may specify
     any username to the client program.  For example, anyone can use
     the `mysql' program to connect as any other person simply by
     invoking it as `mysql -u other_user db_name' if `other_user' has
     no password. If all users have a password, connecting using
     another user's account becomes much more difficult.

     To change the password for a user, use the `SET PASSWORD'
     statement.  It is also possible to update the `user' table in the
     `mysql' database directly.  For example, to change the password of
     all MySQL accounts that have a username of `root', do this:

          shell> mysql -u root mysql
          mysql> UPDATE user SET Password=PASSWORD('new_password')
              -> WHERE user='root';
          mysql> FLUSH PRIVILEGES;

   * Don't run the MySQL server as the Unix `root' user.  This is very
     dangerous, because any user with the `FILE' privilege will be able
     to create files as `root' (for example, `~root/.bashrc'). To
     prevent this, `mysqld' refuses to run as `root' unless that is
     specified explicitly using a `--user=root' option.

     `mysqld' can be run as an ordinary unprivileged user instead.  You
     can also create a separate Unix account named `mysql' to make
     everything even more secure (use the account only for
     administering MySQL).  To start `mysqld' as another Unix user, add
     a `user' option that specifies the username to the `[mysqld]'
     group of the `/etc/my.cnf' option file or the `my.cnf' option file
     in the server's data directory. For example:

          [mysqld]
          user=mysql

     This causes the server to start as the designated user whether you
     start it manually or by using `mysqld_safe' or `mysql.server'.
     For more details, see *Note Changing MySQL user::.

     Note that running `mysql' as a Unix user other than `root' does not
     mean that you need to change the `root' username in the `user'
     table. Usernames for MySQL accounts have nothing to do with
     usernames for Unix accounts.

   * Don't allow the use of symlinks to tables. (This can be disabled
     with the `--skip-symlink' option.) This is especially important if
     you run `mysqld' as `root', because anyone that has write access
     to the server's data directory could then delete any file in the
     system!  *Note Symbolic links to tables::.

   * Make sure that the only Unix user with read or write privileges in
     the database directories is the user that `mysqld' runs as.

   * Don't grant the `PROCESS' privilege to non-administrative users.
     The output of `mysqladmin processlist' shows the text of the
     currently executing queries, so any user who is allowed to execute
     that command might be able to see if another user issues an
     `UPDATE user SET password=PASSWORD('not_secure')' query.

     `mysqld' reserves an extra connection for users who have the
     `PROCESS' privilege, so that a MySQL `root' user can log in and
     check server activity even if all normal connections are in use.

   * Don't grant the `SUPER' privilege to non-administrative users.  It
     can be used to terminate client connections, change server
     operation by changing the value of system variables, and control
     replication servers.

   * Don't grant the `FILE' privilege to non-administrative users.  Any
     user that has this privilege can write a file anywhere in the
     filesystem with the privileges of the `mysqld' daemon!  To make
     this a bit safer, files generated with `SELECT ... INTO OUTFILE'
     will not overwrite existing files and are writable by everyone.

     The `FILE' privilege may also be used to read any file that is
     world-readable or accessible to the Unix user that the server runs
     as.  With this privilege, you can read any file into a database
     table.  This could be abused, for example, by using `LOAD DATA' to
     load `/etc/passwd' into a table, which then can be displayed with
     `SELECT'.

   * If you don't trust your DNS, you should use IP numbers rather than
     hostnames in the grant tables. In any case, you should be very
     careful about creating grant table entries using hostname values
     that contain wildcards!

   * If you want to restrict the number of connections allowed to a
     single account, you can do so by setting the
     `max_user_connections' variable in `mysqld'.  The `GRANT'
     statement also supports resource control options for limiting the
     extent of server use allowed to an account.

Startup Options for `mysqld' Concerning Security
------------------------------------------------

The following `mysqld' options affect security:

`--local-infile[={0|1}]'
     If you start the server with `--local-infile=0', clients cannot use
     `LOCAL' in `LOAD DATA' statements.  *Note `LOAD DATA LOCAL': LOAD
     DATA LOCAL.

`--safe-show-database'
     With this option, the `SHOW DATABASES' statement displays the names
     of only those databases for which the user has some kind of
     privilege.  As of version 4.0.2, this option is deprecated and
     doesn't do anything (it is enabled by default), because there is
     now a `SHOW DATABASES' privilege that can be used to control
     access to database names on a per-account basis. *Note `GRANT':
     GRANT.

`--safe-user-create'
     If this is enabled, a user cannot create new users with the `GRANT'
     statement unless the user has the `INSERT' privilege for the
     `mysql.user' table.  If you want a user to have the ability to
     create new users with those privileges that the user has right to
     grant, you should grant the user the following privilege:

          mysql> GRANT INSERT(user) ON mysql.user TO 'user'@'hostname';

     This will ensure that the user can't change any privilege columns
     directly, but has to use the `GRANT' statement to give privileges
     to other users.

`--skip-grant-tables'
     This option causes the server not to use the privilege system at
     all. This gives everyone *full access* to all databases!  (You can
     tell a running server to start using the grant tables again by
     executing a `mysqladmin flush-privileges' or `mysqladmin reload'
     command, or by issuing a `FLUSH PRIVILEGES' statement.)

`--skip-name-resolve'
     Hostnames are not resolved.  All `Host' column values in the grant
     tables must be IP numbers or `localhost'.

`--skip-networking'
     Don't allow TCP/IP connections over the network.  All connections
     to `mysqld' must be made via Unix socket files.  This option is
     unsuitable when using a MySQL version prior to 3.23.27 with the
     MIT-pthreads package, because Unix socket files were not supported
     by MIT-pthreads at that time.

`--skip-show-database'
     Don't allow the `SHOW DATABASES' statement, unless the user has the
     `SHOW DATABASES' privilege. As of version 4.0.2, you should no
     longer need this option. Access now can be granted to specific
     accounts with the `SHOW DATABASES' privilege.

Security Issues with `LOAD DATA LOCAL'
--------------------------------------

The `LOAD DATA' statement can load a file that is located on the server
host, or, when the `LOCAL' keyword is specified, a file that is located
on the client host.

There are two possible problems with supporting the `LOCAL' version of
`LOAD DATA' statements:

   * The reading of the file is initiated from the server, so one could
     theoretically create a patched MySQL server that could tell the
     client program to read any file on the client machine that the
     current user has read access to, when the client issues a query
     against the table.

   * In a web environment where the clients are connecting from a web
     server, a user could use `LOAD DATA LOCAL' to read any files that
     the web server process has read access to (assuming a user could
     run any command against the SQL server). In this environment, the
     client with respect to the MySQL server actually is the web
     server, not the program being run by the user connecting to the
     web server.


To deal with these potential security issues, we changed how `LOAD DATA
LOCAL' is handled as of MySQL 3.23.49 and MySQL 4.0.2 (4.0.13 on
Windows):

   * By default, all MySQL clients and libraries in binary
     distributions are compiled with the `--enable-local-infile'
     option, to be compatible with MySQL 3.23.48 and before.

   * If you build MySQL from source but don't use the
     `--enable-local-infile' option to `configure', `LOAD DATA LOCAL'
     cannot be used by any client unless it is written explicitly to
     invoke `mysql_options(... MYSQL_OPT_LOCAL_INFILE, 0)'.  *Note
     `mysql_options()': mysql_options.

   * You can disable all `LOAD DATA LOCAL' commands from the server side
     by starting `mysqld' with `--local-infile=0'.

   * For the `mysql' command-line client, `LOAD DATA LOCAL' can be
     enabled by specifying the `--local-infile[=1]' option, or disabled
     with the `--local-infile=0' option.  Similarly, for `mysqlimport',
     the `--local' or `-L' option enable local datafile loading. In any
     case, successful use of a local loading operation requires that the
     server is enabled to allow it.

   * If `LOAD DATA LOCAL INFILE' is disabled, either in the server or
     the client, a client that attempts to issue such a statement
     receives the following error message:

          ERROR 1148: The used command is not allowed with this MySQL version


The MySQL Access Privilege System
=================================

MySQL has an advanced but non-standard security/privilege system.  This
section describes how it works.

What the Privilege System Does
------------------------------

The primary function of the MySQL privilege system is to authenticate a
user connecting from a given host, and to associate that user with
privileges on a database such as `SELECT', `INSERT', `UPDATE' and
`DELETE'.

Additional functionality includes the ability to have an anonymous user
and to grant privileges for MySQL-specific functions such as `LOAD DATA
INFILE' and administrative operations.

How the Privilege System Works
------------------------------

The MySQL privilege system ensures that all users may perform only the
operations allowed to them.  As a user, when you connect to a MySQL
server, your identity is determined by *the host from which you
connect* and *the username you specify*.  The system grants privileges
according to your identity and *what you want to do*.

MySQL considers both your hostname and username in identifying you
because there is little reason to assume that a given username belongs
to the same person everywhere on the Internet.  For example, the user
`joe' who connects from `office.com' need not be the same person as the
user `joe' who connects from `elsewhere.com'.  MySQL handles this by
allowing you to distinguish users on different hosts that happen to
have the same name:  you can grant `joe' one set of privileges for
connections from `office.com', and a different set of privileges for
connections from `elsewhere.com'.

MySQL access control involves two stages:

   * Stage 1: The server checks whether you are even allowed to connect.

   * Stage 2: Assuming you can connect, the server checks each request
     you issue to see whether you have sufficient privileges to perform
     it.  For example, if you try to select rows from a table in a
     database or drop a table from the database, the server makes sure
     you have the `SELECT' privilege for the table or the `DROP'
     privilege for the database.

Note that if your privileges are changed (either by yourself or someone
else) while you are connected, those changes will not necessarily take
effect with your next query or queries. See *Note Privilege changes::
for details.

The server uses the `user', `db', and `host' tables in the `mysql'
database at both stages of access control.  The columns in these grant
tables are shown here:

*Table name*   *user*         *db*           *host*
*Scope         `Host'         `Host'         `Host'
columns*
               `User'         `Db'           `Db'
               `Password'     `User'
*Privilege     `Select_priv'  `Select_priv'  `Select_priv'
columns*
               `Insert_priv'  `Insert_priv'  `Insert_priv'
               `Update_priv'  `Update_priv'  `Update_priv'
               `Delete_priv'  `Delete_priv'  `Delete_priv'
               `Index_priv'   `Index_priv'   `Index_priv'
               `Alter_priv'   `Alter_priv'   `Alter_priv'
               `Create_priv'  `Create_priv'  `Create_priv'
               `Drop_priv'    `Drop_priv'    `Drop_priv'
               `Grant_priv'   `Grant_priv'   `Grant_priv'
               `References_priv'`References_priv'`References_priv'
               `Reload_priv'
               `Shutdown_priv'
               `Process_priv'
               `File_priv'
               `Show_db_priv'
               `Super_priv'
               `Create_tmp_table_priv'`Create_tmp_table_priv'`Create_tmp_table_priv'
               `Lock_tables_priv'`Lock_tables_priv'`Lock_tables_priv'
               `Execute_priv'
               `Repl_slave_priv'
               `Repl_client_priv'
               `ssl_type'
               `ssl_cypher'
               `x509_issuer'
               `x509_cubject'
               `max_questions'
               `max_updates'
               `max_connections'

During the second stage of access control (request verification), the
server may, if the request involves tables, additionally consult the
`tables_priv' and `columns_priv' tables that provide finer control at
the table and column levels.  The columns in these tables are shown
here:

*Table name*   *tables_priv*  *columns_priv*
*Scope         `Host'         `Host'
columns*
               `Db'           `Db'
               `User'         `User'
               `Table_name'   `Table_name'
                              `Column_name'
*Privilege     `Table_priv'   `Column_priv'
columns*
               `Column_priv'
*Other         `Timestamp'    `Timestamp'
columns*
               `Grantor'

Each grant table contains scope columns and privilege columns.

Scope columns determine the scope of each entry (row) in the tables,
that is, the context in which the entry applies.  For example, a `user'
table entry with `Host' and `User' values of `'thomas.loc.gov'' and
`'bob'' would be used for authenticating connections made to the server
from the host `thomas.loc.gov' by a client that specifies a username of
`bob'.  Similarly, a `db' table entry with `Host', `User', and `Db'
column values of `'thomas.loc.gov'', `'bob'' and `'reports'' would be
used when `bob' connects from the host `thomas.loc.gov' to access the
`reports' database.  The `tables_priv' and `columns_priv' tables
contain scope columns indicating tables or table/column combinations to
which each entry applies.

For access-checking purposes, comparisons of `Host' values are
case-insensitive.  `User', `Password', `Db', and `Table_name' values
are case-sensitive.  `Column_name' values are case-insensitive in MySQL
Version 3.22.12 or later.

Privilege columns indicate the privileges granted by a table entry,
that is, what operations can be performed.  The server combines the
information in the various grant tables to form a complete description
of a user's privileges.  The rules used to do this are described in
*Note Request access::.

Scope columns contain strings. They are declared as shown here; the
default value for each is the empty string:

*Column name*  *Type*
`Host'         `CHAR(60)'
`User'         `CHAR(16)'
`Password'     `CHAR(16)'
`Db'           `CHAR(64)'
`Table_name'   `CHAR(60)'
`Column_name'  `CHAR(60)'

Before MySQL 3.23, the `Db' column was `CHAR(32)' in some tables and
`CHAR(60)' in others.

In the `user', `db' and `host' tables, each privilege is listed in a
separate column. Each privilege column is declared as `ENUM('N','Y')'
and can have a value of `'N'' or `'Y''; the default value is `'N''.

In the `tables_priv' and `columns_priv' tables, the privilege columns
are declared as `SET' columns. Values in these columns can contain any
combination of the privileges controlled by the table:

*Table      *Column     *Possible set elements*
name*       name*
`tables_priv'`Table_priv'`'Select', 'Insert', 'Update',
                        'Delete', 'Create', 'Drop', 'Grant',
                        'References', 'Index', 'Alter''
`tables_priv'`Column_priv'`'Select', 'Insert', 'Update',
                        'References''
`columns_priv'`Column_priv'`'Select', 'Insert', 'Update',
                        'References''

Briefly, the server uses the grant tables like this:

   * The `user' table scope columns determine whether to allow or reject
     incoming connections.  For allowed connections, any privileges
     granted in the `user' table indicate the user's global (superuser)
     privileges.  These privileges apply to *all* databases on the
     server.

   * The `db' and `host' tables are used together:

        - The `db' table scope columns determine which users can access
          which databases from which hosts.  The privilege columns
          determine which operations are allowed.

        - The `host' table is used as an extension of the `db' table
          when you want a given `db' table entry to apply to several
          hosts.  For example, if you want a user to be able to use a
          database from several hosts in your network, leave the `Host'
          value empty in the user's `db' table entry, then populate the
          `host' table with an entry for each of those hosts.  This
          mechanism is described more detail in *Note Request access::.
          Note that the `host' table is not affected by the `GRANT' and
          `REVOKE' statements. Most MySQL installations need not use
          this table at all.

   * The `tables_priv' and `columns_priv' tables are similar to the
     `db' table, but are more fine-grained: they apply at the table and
     column levels rather than at the database level.

Administrative privileges (such as `RELOAD' or `SHUTDOWN') are
specified only in the `user' table.  This is because administrative
operations are operations on the server itself and are not
database-specific, so there is no reason to list these privileges in the
other grant tables.  In fact, to determine whether you can perform an
administrative operation, the server need consult only the `user' table.

The `FILE' privilege also is specified only in the `user' table.  It is
not an administrative privilege as such, but your ability to read or
write files on the server host is independent of the database you are
accessing.

The `mysqld' server reads the contents of the grant tables once, when it
starts.  Changes to the grant tables take effect as indicated in *Note
Privilege changes::.

When you modify the contents of the grant tables, it is a good idea to
make sure that your changes set up privileges the way you want.  For
help in diagnosing problems, see *Note Access denied::.  For advice on
general security issues, see *Note Security::.

A useful diagnostic tool is the `mysqlaccess' script, which Yves
Carlier has provided for the MySQL distribution.  Invoke `mysqlaccess'
with the `--help' option to find out how it works.  Note that
`mysqlaccess' checks access using only the `user', `db' and `host'
tables.  It does not check table or column privileges in the
`tables_priv' or `columns_priv' tables.

Privileges Provided by MySQL
----------------------------

Information about user privileges is stored in the `user', `db',
`host', `tables_priv', and `columns_priv' tables in the `mysql'
database (that is, in the database named `mysql').  The MySQL server
reads the contents of these tables when it starts and under the
circumstances indicated in *Note Privilege changes::.

The names used in this manual to refer to the privileges provided by
MySQL version 4.0.2 are shown here, along with the table column name
associated with each privilege in the grant tables and the context in
which the privilege applies. Further information about the meaning of
each privilege may be found at *Note `GRANT': GRANT.

*Privilege* *Column*       *Context*
`ALTER'     `Alter_priv'   tables
`DELETE'    `Delete_priv'  tables
`INDEX'     `Index_priv'   tables
`INSERT'    `Insert_priv'  tables
`SELECT'    `Select_priv'  tables
`UPDATE'    `Update_priv'  tables
`CREATE'    `Create_priv'  databases, tables, or
                           indexes
`DROP'      `Drop_priv'    databases or tables
`GRANT'     `Grant_priv'   databases or tables
`REFERENCES'`References_priv'databases or tables
`CREATE     `Create_tmp_table_priv'server administration
TEMPORARY
TABLES'
`EXECUTE'   `Execute_priv' server administration
`FILE'      `File_priv'    file access on server
`LOCK       `Lock_tables_priv'server administration
TABLES'
`PROCESS'   `Process_priv' server administration
`RELOAD'    `Reload_priv'  server administration
`REPLICATION`Repl_client_priv'server administration
CLIENT'
`REPLICATION`Repl_slave_priv'server administration
SLAVE'
`SHOW       `Show_db_priv' server administration
DATABASES'
`SHUTDOWN'  `Shutdown_priv'server administration
`SUPER'     `Super_priv'   server administration

The `SELECT', `INSERT', `UPDATE', and `DELETE' privileges allow you to
perform operations on rows in existing tables in a database.

`SELECT' statements require the `SELECT' privilege only if they
actually retrieve rows from a table.  Some `SELECT' statements do not
access tables, so they can be executed even without permission for any
of the databases on the server.  For example, you can use the `mysql'
client as a simple calculator:

     mysql> SELECT 1+1;
     mysql> SELECT PI()*2;

The `INDEX' privilege allows you to create or drop (remove) indexes.

The `ALTER' privilege allows you to use `ALTER TABLE'.

The `CREATE' and `DROP' privileges allow you to create new databases
and tables, or to drop (remove) existing databases and tables.

Note that if you grant the `DROP' privilege for the `mysql' database to
a user, that user can drop the database in which the MySQL access
privileges are stored!

The `GRANT' privilege allows you to give to other users those
privileges you yourself possess.

The `FILE' privilege gives you permission to read and write files on
the server using the `LOAD DATA INFILE' and `SELECT ... INTO OUTFILE'
statements.  Any user to whom this privilege is granted can read any
world-readable file accessable by the MySQL server and create a new
world-readable file in any directory where the MySQL server can write.
The user can also read any file in the current database directory.
However, the user cannot change any existing file.

The remaining privileges are used for administrative operations. Many of
them can be performed by using using the `mysqladmin' program or by
issuing SQL statements.  The following table shows which `mysqladmin'
commands each administrative privilege allows you to execute:

*Privilege* *Commands permitted to privilege holders*
`RELOAD'    `refresh', `reload', `flush-hosts', `flush-logs',
            `flush-privileges', `flush-status', `flush-threads',
            and `flush-tables'
`SHUTDOWN'  `shutdown'
`PROCESS'   `processlist'
`SUPER'     `kill'

The `reload' command tells the server to re-read the grant tables.  The
`refresh' command flushes all tables and opens and closes the log
files.  `flush-privileges' is a synonym for `reload'.  The other
`flush-*' commands perform functions similar to `refresh' but are more
limited in scope, and may be preferable in some instances.  For example,
if you want to flush just the log files, `flush-logs' is a better choice
than `refresh'.

The `shutdown' command shuts down the server. This command can be issued
only from `mysqladmin'. There is no corresponding SQL statement.

The `processlist' command displays information about the threads
executing within the server (that is, about the statements that other
clients are executing).  The `kill' command kills server threads.  You
can always display or kill your own threads, but you need the `PROCESS'
privilege to display threads initiated by other users and and the
`SUPER' privilege to kill them.  *Note `KILL': KILL.

It is a good idea in general to grant privileges only to those users
who need them, but you should exercise particular caution in granting
administrative privileges:

   * The `GRANT' privilege allows users to give their privileges to
     other users.  Two users with different privileges and with the
     `GRANT' privilege are able to combine privileges.

   * The `ALTER' privilege may be used to subvert the privilege system
     by renaming tables.

   * The `FILE' privilege can be abused to read into a database table
     any world-readable file on the server host or any file in the
     server's data directory. The contents of that table can then be
     accessed using `SELECT'.

   * The `SHUTDOWN' privilege can be abused to deny service to other
     users entirely by terminating the server.

   * The `PROCESS' privilege can be used to view the plain text of
     currently executing queries, including queries that set or change
     passwords.

   * The `SUPER' privilege can be used to terminate other clients or
     change how the server operates.

   * Privileges granted for the `mysql' database itself can be used to
     change passwords and other access privilege information.
     (Passwords are stored encrypted, so a malicious user cannot simply
     read them to know the plain text password.)  If they can access
     the `mysql.user' password column, they can use it to log into the
     MySQL server for the given user.  (With sufficient privileges, the
     same user can replace a password with a different one.)

There are some things that you cannot do with the MySQL privilege
system:

   * You cannot explicitly specify that a given user should be denied
     access.  That is, you cannot explicitly match a user and then
     refuse the connection.

   * You cannot specify that a user has privileges to create or drop
     tables in a database but not to create or drop the database itself.

Connecting to the MySQL Server
------------------------------

MySQL client programs generally require that you specify connection
parameters when you want to access a MySQL server: the host you want to
connect to, your username, and your password.  For example, the `mysql'
client can be started like this, where optional arguments are indicated
by `[' and `]':

     shell> mysql [-h host_name] [-u user_name] [-pyour_pass]

Alternate forms of the `-h', `-u', and `-p' options are
`--host=host_name', `--user=user_name', and `--password=your_pass'.
Note that there is _no space_ between `-p' or `--password=' and the
password following it.

*Note:* Specifying a password on the command line is not secure!  Any
user on your system may then find out your password by typing a command
like: `ps auxww'.  *Note Option files::.

`mysql' uses default values for connection parameters that are not given
on the command line:

   * The default hostname is `localhost'.

   * The default username is your Unix login name.

   * No password is supplied if `-p' is missing.

Thus, for a Unix user `joe', the following commands are equivalent:

     shell> mysql -h localhost -u joe
     shell> mysql -h localhost
     shell> mysql -u joe
     shell> mysql

Other MySQL clients behave similarly.

On Unix systems, you can specify different default values to be used
when you make a connection, so that you need not enter them on the
command-line each time you invoke a client program.  This can be done
in a couple of ways:

   * You can specify connection parameters in the `[client]' section of
     the `.my.cnf' option file in your home directory.  The relevant
     section of the file might look like this:

          [client]
          host=host_name
          user=user_name
          password=your_pass

     *Note Option files::.

   * You can specify connection parameters using environment variables.
     The host can be specified for `mysql' using `MYSQL_HOST'.  The
     MySQL username can be specified using `USER' (this is for Windows
     and NetWare only).  The password can be specified using `MYSQL_PWD'
     (but this is insecure; see the next section).  *Note Environment
     variables::.

Access Control, Stage 1: Connection Verification
------------------------------------------------

When you attempt to connect to a MySQL server, the server accepts or
rejects the connection based on your identity and whether you can
verify your identity by supplying the correct password.  If not, the
server denies access to you completely.  Otherwise, the server accepts
the connection, then enters Stage 2 and waits for requests.

Your identity is based on two pieces of information:

   * The host from which you connect

   * Your MySQL username

Identity checking is performed using the three `user' table scope
columns (`Host', `User', and `Password').  The server accepts the
connection only if a `user' table entry matches your hostname and user
name, and you supply the correct password.

Values in the `user' table scope columns may be specified as follows:

   * A `Host' value may be a hostname or an IP number, or `'localhost''
     to indicate the local host.

   * You can use the wildcard characters `%' and `_' in the `Host'
     column.

   * A `Host' value of `'%'' matches any hostname.

   * A blank `Host' value means that the privilege should be anded with
     the entry in the `host' table that matches the given hostname.
     You can find more information about this in the next chapter.

   * As of MySQL Version 3.23, for `Host' values specified as IP
     numbers, you can specify a netmask indicating how many address
     bits to use for the network number. For example:

          mysql> GRANT ALL PRIVILEGES ON db.*
              -> TO david@'192.58.197.0/255.255.255.0';

     This will allow everyone to connect from an IP where the following
     is true:

          user_ip & netmask = host_ip.

     In the above example all IP:s in the interval 192.58.197.0 -
     192.58.197.255 can connect to the MySQL server.

   * Wildcard characters are not allowed in the `User' column, but you
     can specify a blank value, which matches any name.  If the `user'
     table entry that matches an incoming connection has a blank
     username, the user is considered to be the anonymous user (the
     user with no name), rather than the name that the client actually
     specified.  This means that a blank username is used for all
     further access checking for the duration of the connection (that
     is, during Stage 2).

   * The `Password' column can be blank.  This does not mean that any
     password matches, it means the user must connect without
     specifying a password.

Non-blank `Password' values represent encrypted passwords.  MySQL does
not store passwords in plaintext form for anyone to see.  Rather, the
password supplied by a user who is attempting to connect is encrypted
(using the `PASSWORD()' function). The encrypted password is then used
when the client/server is checking if the password is correct. (This is
done without the encrypted password ever traveling over the
connection.)  Note that from MySQL's point of view the encrypted
password is the REAL password, so you should not give anyone access to
it!  In particular, don't give normal users read access to the tables
in the `mysql' database!  From version 4.1, MySQL employs a different
password and login mechanism that is secure even if TCP/IP packets are
sniffed and/or the mysql database is captured.

The examples here show how various combinations of `Host' and `User'
values in `user' table entries apply to incoming connections:

`Host' *value*            `User'      *Connections matched by entry*
                          *value*
`'thomas.loc.gov''        `'fred''    `fred', connecting from
                                      `thomas.loc.gov'
`'thomas.loc.gov''        `'''        Any user, connecting from
                                      `thomas.loc.gov'
`'%''                     `'fred''    `fred', connecting from any host
`'%''                     `'''        Any user, connecting from any host
`'%.loc.gov''             `'fred''    `fred', connecting from any host in
                                      the `loc.gov' domain
`'x.y.%''                 `'fred''    `fred', connecting from `x.y.net',
                                      `x.y.com',`x.y.edu', etc. (this is
                                      probably not useful)
`'144.155.166.177''       `'fred''    `fred', connecting from the host
                                      with IP address `144.155.166.177'
`'144.155.166.%''         `'fred''    `fred', connecting from any host in
                                      the `144.155.166' class C subnet
`'144.155.166.0/255.255.255.0''`'fred''    Same as previous example

Because you can use IP wildcard values in the `Host' column (for
example, `'144.155.166.%'' to match every host on a subnet), there is
the possibility that someone might try to exploit this capability by
naming a host `144.155.166.somewhere.com'.  To foil such attempts, MySQL
disallows matching on hostnames that start with digits and a dot. Thus,
if you have a host named something like `1.2.foo.com', its name will
never match the `Host' column of the grant tables.  Only an IP number
can match an IP wildcard value.

An incoming connection may be matched by more than one entry in the
`user' table.  For example, a connection from `thomas.loc.gov' by
`fred' would be matched by several of the entries shown in the preceding
table.  How does the server choose which entry to use if more than one
matches?  The server resolves this question by sorting the `user' table
after reading it at startup time, then looking through the entries in
sorted order when a user attempts to connect.  The first matching entry
is the one that is used.

`user' table sorting works as follows.  Suppose the `user' table looks
like this:

     +-----------+----------+-
     | Host      | User     | ...
     +-----------+----------+-
     | %         | root     | ...
     | %         | jeffrey  | ...
     | localhost | root     | ...
     | localhost |          | ...
     +-----------+----------+-

When the server reads in the table, it orders the entries with the
most-specific `Host' values first (`'%'' in the `Host' column means
"any host" and is least specific).  Entries with the same `Host' value
are ordered with the most-specific `User' values first (a blank `User'
value means "any user" and is least specific).  The resulting sorted
`user' table looks like this:

     +-----------+----------+-
     | Host      | User     | ...
     +-----------+----------+-
     | localhost | root     | ...
     | localhost |          | ...
     | %         | jeffrey  | ...
     | %         | root     | ...
     +-----------+----------+-

When a connection is attempted, the server looks through the sorted
entries and uses the first match found.  For a connection from
`localhost' by `jeffrey', the entries with `'localhost'' in the `Host'
column match first.  Of those, the entry with the blank username
matches both the connecting hostname and username.  (The
`'%'/'jeffrey'' entry would have matched, too, but it is not the first
match in the table.)

Here is another example.  Suppose the `user' table looks like this:

     +----------------+----------+-
     | Host           | User     | ...
     +----------------+----------+-
     | %              | jeffrey  | ...
     | thomas.loc.gov |          | ...
     +----------------+----------+-

The sorted table looks like this:

     +----------------+----------+-
     | Host           | User     | ...
     +----------------+----------+-
     | thomas.loc.gov |          | ...
     | %              | jeffrey  | ...
     +----------------+----------+-

A connection from `thomas.loc.gov' by `jeffrey' is matched by the first
entry, whereas a connection from `whitehouse.gov' by `jeffrey' is
matched by the second.

A common misconception is to think that for a given username, all
entries that explicitly name that user will be used first when the
server attempts to find a match for the connection.  This is simply not
true.  The previous example illustrates this, where a connection from
`thomas.loc.gov' by `jeffrey' is first matched not by the entry
containing `'jeffrey'' as the `User' column value, but by the entry
with no username!

If you have problems connecting to the server, print out the `user'
table and sort it by hand to see where the first match is being made.
If connection was successful, but your privileges are not what you
expected you may use `CURRENT_USER()' function (new in version 4.0.6)
to see what user/host combination your connection actually matched.
*Note `CURRENT_USER()': Miscellaneous functions.

Access Control, Stage 2: Request Verification
---------------------------------------------

Once you establish a connection, the server enters Stage 2.  For each
request that comes in on the connection, the server checks whether you
have sufficient privileges to perform it, based on the type of
operation you wish to perform.  This is where the privilege columns in
the grant tables come into play.  These privileges can come from any of
the `user', `db', `host', `tables_priv', or `columns_priv' tables.  The
grant tables are manipulated with `GRANT' and `REVOKE' commands.  *Note
`GRANT': GRANT.  (You may find it helpful to refer to *Note
Privileges::, which lists the columns present in each of the grant
tables.)

The `user' table grants privileges that are assigned to you on a global
basis and that apply no matter what the current database is.  For
example, if the `user' table grants you the `DELETE' privilege, you can
delete rows from any database on the server host!  In other words,
`user' table privileges are superuser privileges.  It is wise to grant
privileges in the `user' table only to superusers such as server or
database administrators.  For other users, you should leave the
privileges in the `user' table set to `'N'' and grant privileges on a
database-specific basis only, using the `db' and `host' tables.

The `db' and `host' tables grant database-specific privileges.  Values
in the scope columns may be specified as follows:

   * The wildcard characters `%' and `_' can be used in the `Host' and
     `Db' columns of either table. If you wish to use for instance a
     `_' character as part of a database name, specify it as `\_' in
     the `GRANT' command.

   * A `'%'' `Host' value in the `db' table means "any host." A blank
     `Host' value in the `db' table means "consult the `host' table for
     further information."

   * A `'%'' or blank `Host' value in the `host' table means "any host."

   * A `'%'' or blank `Db' value in either table means "any database."

   * A blank `User' value in either table matches the anonymous user.

The `db' and `host' tables are read in and sorted when the server
starts (at the same time that it reads the `user' table).  The `db'
table is sorted on the `Host', `Db', and `User' scope columns, and the
`host' table is sorted on the `Host' and `Db' scope columns.  As with
the `user' table, sorting puts the most-specific values first and
least-specific values last, and when the server looks for matching
entries, it uses the first match that it finds.

The `tables_priv' and `columns_priv' tables grant table- and
column-specific privileges.  Values in the scope columns may be
specified as follows:

   * The wildcard characters `%' and `_' can be used in the `Host'
     column of either table.

   * A `'%'' or blank `Host' value in either table means "any host."

   * The `Db', `Table_name' and `Column_name' columns cannot contain
     wildcards or be blank in either table.

The `tables_priv' and `columns_priv' tables are sorted on the `Host',
`Db', and `User' columns.  This is similar to `db' table sorting,
although the sorting is simpler because only the `Host' column may
contain wildcards.

The request verification process is described here.  (If you are
familiar with the access-checking source code, you will notice that the
description here differs slightly from the algorithm used in the code.
The description is equivalent to what the code actually does; it
differs only to make the explanation simpler.)

For administrative requests (`SHUTDOWN', `RELOAD', etc.), the server
checks only the `user' table entry, because that is the only table that
specifies administrative privileges.  Access is granted if the entry
allows the requested operation and denied otherwise.  For example, if
you want to execute `mysqladmin shutdown' but your `user' table entry
doesn't grant the `SHUTDOWN' privilege to you, access is denied without
even checking the `db' or `host' tables.  (They contain no
`Shutdown_priv' column, so there is no need to do so.)

For database-related requests (`INSERT', `UPDATE', etc.), the server
first checks the user's global (superuser) privileges by looking in the
`user' table entry.  If the entry allows the requested operation,
access is granted.  If the global privileges in the `user' table are
insufficient, the server determines the user's database-specific
privileges by checking the `db' and `host' tables:

  1. The server looks in the `db' table for a match on the `Host',
     `Db', and `User' columns.  The `Host' and `User' columns are
     matched to the connecting user's hostname and MySQL username.  The
     `Db' column is matched to the database the user wants to access.
     If there is no entry for the `Host' and `User', access is denied.

  2. If there is a matching `db' table entry and its `Host' column is
     not blank, that entry defines the user's database-specific
     privileges.

  3. If the matching `db' table entry's `Host' column is blank, it
     signifies that the `host' table enumerates which hosts should be
     allowed access to the database.  In this case, a further lookup is
     done in the `host' table to find a match on the `Host' and `Db'
     columns.  If no `host' table entry matches, access is denied.  If
     there is a match, the user's database-specific privileges are
     computed as the intersection (*not* the union!) of the privileges
     in the `db' and `host' table entries, that is, the privileges that
     are `'Y'' in both entries.  (This way you can grant general
     privileges in the `db' table entry and then selectively restrict
     them on a host-by-host basis using the `host' table entries.)

After determining the database-specific privileges granted by the `db'
and `host' table entries, the server adds them to the global privileges
granted by the `user' table.  If the result allows the requested
operation, access is granted.  Otherwise, the server checks the user's
table and column privileges in the `tables_priv' and `columns_priv'
tables and adds those to the user's privileges.  Access is allowed or
denied based on the result.

Expressed in boolean terms, the preceding description of how a user's
privileges are calculated may be summarized like this:

     global privileges
     OR (database privileges AND host privileges)
     OR table privileges
     OR column privileges

It may not be apparent why, if the global `user' entry privileges are
initially found to be insufficient for the requested operation, the
server adds those privileges to the database-, table-, and
column-specific privileges later. The reason is that a request might
require more than one type of privilege.  For example, if you execute
an `INSERT ...  SELECT' statement, you need both `INSERT' and `SELECT'
privileges.  Your privileges might be such that the `user' table entry
grants one privilege and the `db' table entry grants the other.  In
this case, you have the necessary privileges to perform the request,
but the server cannot tell that from either table by itself; the
privileges granted by the entries in both tables must be combined.

The `host' table can be used to maintain a list of secure servers.

At TcX, the `host' table contains a list of all machines on the local
network. These are granted all privileges.

You can also use the `host' table to indicate hosts that are *not*
secure.  Suppose you have a machine `public.your.domain' that is located
in a public area that you do not consider secure.  You can allow access
to all hosts on your network except that machine by using `host' table
entries like this:

     +--------------------+----+-
     | Host               | Db | ...
     +--------------------+----+-
     | public.your.domain | %  | ... (all privileges set to 'N')
     | %.your.domain      | %  | ... (all privileges set to 'Y')
     +--------------------+----+-

Naturally, you should always test your entries in the grant tables (for
example, using `mysqlaccess') to make sure your access privileges are
actually set up the way you think they are.

Password Hashing in MySQL 4.1
-----------------------------

MySQL user accounts are listed in the `user' table of the `mysql'
database. Each MySQL account is assigned a password, although what is
stored in the `Password' column of the `user' table is not the
plaintext version of the password, but a hash value computed from it.
Password hash values are computed by the `PASSWORD()' function.

MySQL uses passwords in two phases of client/server communication:

   * First, when a client attempts to connect to the server, there is an
     initial authentication step in which the client must present a
     password that matches the hash value stored in the user table for
     the account that the client wants to use.

   * Second, after the client connects, it may set or change the
     password hashes for accounts listed in the user table (if it has
     sufficient privileges). The client may do this by using the
     PASSWORD() function to generate a password hash, or by using the
     GRANT or SET PASSWORD statements.


In other words, the server _uses_ hash values during authentication when
a client first attempts to connect. The server _generates_ hash values
if a connected client invokes the `PASSWORD()' function or uses a
`GRANT' or `SET PASSWORD' statement to set or change a password.

The password hashing mechanism was updated in MySQL 4.1 to provide
better security and to reduce the risk of passwords being stolen.
However, this new mechanism is understood only by the 4.1 server and
4.1 clients, which can result in some compatibility problems.  A 4.1
client can connect to a pre-4.1 server, because the client understands
both the old and new password hashing mechanisms. However, a pre-4.1
client that attempts to connect to a 4.1 server may run into
difficulties.  For example, a 4.0 `mysql' client that attempts to
connect to a 4.1 server may fail with the following error message:

     shell> mysql
     Client does not support authentication protocol requested
     by server; consider upgrading MySQL client

The following discussion describes the differences between the old and
new password mechanisms, and what you should do if you upgrade your
server to 4.1 but need to maintain backward compatibility with pre-4.1
clients.

*Note:* This discussion contrasts 4.1 behavior with pre-4.1 behavior,
but the 4.1 behavior described here actually begins with 4.1.1. MySQL
4.1.0 is an "odd" release because it has a slightly different mechanism
than that implemented in 4.1.1 and up.  Differences between 4.1.0 and
more recent versions are described later.

Prior to MySQL 4.1, password hashes computed by the `PASSWORD()'
function are 16 bytes long.  Such hashes look like this:

     mysql> SELECT PASSWORD('mypass');
     +--------------------+
     | PASSWORD('mypass') |
     +--------------------+
     | 6f8c114b58f2ce9e   |
     +--------------------+

The `Password' column of the `user' table (in which these hashes are
stored) also is 16 bytes long before MySQL 4.1.

As of MySQL 4.1, the `PASSWORD()' function has been modified to produce
a longer 41-byte hash value:

     mysql> SELECT PASSWORD('mypass');
     +-----------------------------------------------+
     | PASSWORD('mypass')                            |
     +-----------------------------------------------+
     | *43c8aa34cdc98eddd3de1fe9a9c2c2a9f92bb2098d75 |
     +-----------------------------------------------+

Accordingly, the `Password' column in the `user' table also must be 41
bytes long to store these values:

   * If you perform a new installation of MySQL 4.1, the `Password'
     column will be made 41 bytes long automatically.

   * If you upgrade an older installation to 4.1, you should run the
     `mysql_fix_privilege_tables' script to update the length of the
     `Password' column from 16 to 41 bytes. (The script does not change
     existing password values, which remain 16 bytes long.)


A widened `Password' column can store password hashes in both the old
and new formats. The format of any given password hash value can be
determined two ways:

   * The obvious difference is the length (16 bytes versus 41 bytes)

   * A second difference is that password hashes in the new format
     always begin with a `*' character, whereas passwords in the old
     format never do


The longer password hash format has better cryptographic properties, and
client authentication based on long hashes is more secure than that
based on the older short hashes.

The differences between short and long password hashes are relevant
both for how the server uses passwords during authentication and for
how it generates password hashes for connected clients that perform
password-changing operations.

The way in which the server uses password hashes during authentication
is affected by the width of the Password column:

   * If the column is narrow, only short-hash authentication is used.

   * If the column is wide, it can hold either short or long hashes, and
     the server can use either format:

        * Pre-4.1 clients can connect, though because they know only
          about the old hashing mechanism, they can authenticate only
          for accounts that have short hashes.

        * 4.1 clients can authenticate for accounts that have short or
          long hashes.



For short-hash accounts, the authentication process is actually a bit
more secure for 4.1 clients than for older clients.  In terms of
security, the gradient from least to most secure is:

   * Pre-4.1 client authenticating for account with short password hash

   * 4.1 client authenticating for account with short password hash

   * 4.1 client authenticating for account with long password hash


The way in which the server generates password hashes for connected
clients is affected by the width of the `Password' column and by the
`--old-passwords' option.  A 4.1 server generates long hashes only if
certain conditions are met: The `Password' column must be wide enough
to hold long values and the `--old-passwords' option must not be given.
These conditions apply as follows:

   * The `Password' column must be wide enough to hold long hashes (41
     bytes).  If the column has not been updated and still has the
     pre-4.1 width (16 bytes), the server notices that long hashes
     cannot fit into it and generates only short hashes when a client
     performs password-changing operations using `PASSWORD()', `GRANT',
     or `SET PASSWORD'.  (This behavior occurs if you have upgraded to
     4.1 but have not run the `mysql_fix_privilege_tables' script to
     widen the `Password' column.)

   * If the `Password' column is wide, it can store either short or long
     password hashes. In this case, `PASSWORD()', `GRANT', and `SET
     PASSWORD' will generate long hashes unless the server was started
     with the `--old-passwords' option. This option forces the server
     to generate short passsword hashes instead.


The purpose of the `--old-passwords' option is to allow you to maintain
backward compatibility with pre-4.1 clients under circumstances where
the server would otherwise generate long password hashes. It doesn't
affect authentication (4.1 clients can still use accounts that have
long password hashes), but it does prevent creation of a long password
hash in the `user' table as the result of a password-changing
operation. Were that to occur, the account no longer could be used by
pre-4.1 clients. Without the `--old-passwords' option, the following
scenario is possible:

   * An old client connects to an account that has a short password
     hash.

   * The client changes the account's password. Without
     `--old-passwords', this results in the account having a long
     password hash.

   * The next time the old client attempts to connect to the account, it
     cannot, because the account now requires the new hashing mechanism
     during authentication. (Once an account has a long password hash in
     the user table, only 4.1 clients can authenticate for it, because
     pre-4.1 clients do not understand long hashes.)


This scenario illustrates that it is dangerous to run a 4.1 server
without using the `--old-passwords' option if you must support older
pre-4.1 clients. By running the server with `--old-passwords',
password-changing operations will not generate long password hashes and
thus do not cause accounts to become inaccessible to older clients.
(Those clients cannot inadvertently lock themselves out by changing
their password and ending up with a long password hash.)

The downside of the `--old-passwords' option is that any passwords you
create or change will use short hashes, even for 4.1 clients. Thus, you
lose the additional security provided by long password hashes. If you
want to create an account that has a long hash (for example, for use by
4.1 clients), you must do so while running the server without
`--old-passwords'.

The following scenarios are possible for running a 4.1 server:

Scenario 1) Narrow `Password' column in user table

   * Only short hashes can be stored in the `Password' column.

   * The server uses only short hashes during client authentication.

   * For connected clients, password hash-generating operations
     involving `PASSWORD()', `GRANT', or `SET PASSWORD' use short hashes
     exclusively.  Any change to an account's password results in that
     account having a short password hash.

   * The `--old-passwords' option can be used but is superfluous because
     with a narrow `Password' column, the server will be generating
     short password hashes anyway.


Scenario 2) Long `Password' column; server not started with
`--old-passwords' option

   * Short or long hashes can be stored in the `Password' column.

   * 4.1 clients can authenticate for accounts that have short or long
     hashes.

   * Pre-4.1 clients can authenticate only for accounts that have short
     hashes.

   * For connected clients, password hash-generating operations
     involving `PASSWORD()', `GRANT', or `SET PASSWORD' use long hashes
     exclusively.  Any change to an account's password results in that
     account having a long password hash.

   * `OLD_PASSWORD()' may be used to explicitly generate a short hash.
     For example, to assign an account a short password, use `UPDATE'
     as follows:

          mysql> UPDATE user SET Password = OLD_PASSWORD('mypass')
              -> WHERE Host = 'some_host' AND User = 'some_user';
          mysql> FLUSH PRIVILEGES;


As indicated earlier, a danger in this scenario is that it is possible
for accounts that have a short password hash to become inaccessible to
pre-4.1 clients. Any change to such an account's password made via
`GRANT', `SET PASSWORD', or `PASSWORD()' results in the account being
given a long password hash, and from that point on, no pre-4.1 client
can authenticate to that account until the client upgrades to 4.1.

Scenario 3) Long `Password' column; server started with
`--old-passwords' option

   * Short or long hashes can be stored in the `Password' column.

   * 4.1 clients can authenticate for accounts that have short or long
     hashes (but note that it is possible to create long hashes only
     when the server is started without `--old-passwords').

   * Pre-4.1 clients can authenticate only for accounts that have short
     hashes.

   * For connected clients, password hash-generating operations
     involving `PASSWORD()', `GRANT', or `SET PASSWORD' use short hashes
     exclusively.  Any change to an account's password results in that
     account having a short password hash.


In this scenario, you cannot create accounts that have long password
hashes, because `--old-passwords' prevents generation of long hashes.
Also, if you create an account with a long hash before using the
`--old-passwords' option, changing the account's password while
`--old-passwords' is in effect results in the account being given a
short password, causing it to lose the security benefits of a longer
hash.

The disadvantages for these scenarios may be summarized as follows:

Scenario 1) You cannot take advantage of longer hashes that provide more
secure authentication.

Scenario 2) Accounts with short hashes become inaccessible to pre-4.1
clients if you change their passwords without explicitly using
`OLD_PASSWORD()'.

Scenario 3) `--old-passwords' prevents accounts with short hashes from
becoming inaccessible, but password-changing operations cause accounts
with long hashes to revert to short hashes, and you cannot change them
back to long hashes while `--old-passwords' is in effect.

Implications of Password Hashing Changes for Application Programs
-----------------------------------------------------------------

An upgrade to MySQL 4.1 can cause a compatibility issue for
applications that use `PASSWORD()' to generate passwords for their own
purposes. (Applications really should not do this, because `PASSWORD()'
should be used only to manage passwords for MySQL accounts. But some
applications use `PASSWORD()' for their own purposes anyway.)  If you
upgrade to 4.1 and run the server under conditions where it generates
long password hashes, an application that uses `PASSWORD()' for its own
passwords will break.  The recommended course of action is to modify
the application to use another function such as `SHA1()' or `MD5()' to
produce hashed values.  If that is not possible, you can use the
`OLD_PASSWORD()' function, which is provided to generate short hashes
in the old format. (But note that `OLD_PASSWORD()' may one day no
longer be supported.)

If the server is running under circumstances where it generates short
hashes, `OLD_PASSWORD()' is available but is equivalent to `PASSWORD()'.

Password hashing in MySQL 4.1.0 differs from hashing in 4.1.1 and up.
The 4.1.0 differences are:

   * Password hashes are 45 bytes long rather than 41 bytes.

   * The `PASSWORD()' function is non-repeatable.  That is, with a given
     argument `X', successive calls to `PASSWORD(X)' generate different
     results.


Causes of `Access denied' Errors
--------------------------------

If you encounter `Access denied' errors when you try to connect to the
MySQL server, the following list indicates some courses of action you
can take to correct the problem:

   * After installing MySQL, did you run the `mysql_install_db' script
     to set up the initial grant table contents?  If not, do so.  *Note
     Default privileges::.  Test the initial privileges by executing
     this command:

          shell> mysql -u root test

     The server should let you connect without error.  You should also
     make sure you have a file `user.MYD' in the MySQL database
     directory.  Ordinarily, this is `PATH/var/mysql/user.MYD', where
     `PATH' is the pathname to the MySQL installation root.

   * After a fresh installation, you should connect to the server and
     set up your users and their access permissions:

          shell> mysql -u root mysql

     The server should let you connect because the MySQL `root' user
     has no password initially.  That is also a security risk, so
     setting the `root' password is something you should do while
     you're setting up your other MySQL users.

     If you try to connect as `root' and get this error:

          Access denied for user: '@unknown' to database mysql

     this means that you don't have an entry in the `user' table with a
     `User' column value of `'root'' and that `mysqld' cannot resolve
     the hostname for your client.  In this case, you must restart the
     server with the `--skip-grant-tables' option and edit your
     `/etc/hosts' or `\windows\hosts' file to add an entry for your
     host.

   * If you get an error like the following:

          shell> mysqladmin -u root -pxxxx ver
          Access denied for user: 'root@localhost' (Using password: YES)

     It means that you are using an incorrect password. *Note
     Passwords::.

     If you have forgot the root password, you can restart `mysqld' with
     `--skip-grant-tables' to change the password.  *Note Resetting
     permissions::.

     If you get the above error even if you haven't specified a
     password, this means that you have an incorrect password in some
     `my.ini' file. *Note Option files::.  You can avoid using option
     files with the `--no-defaults' option, as follows:

          shell> mysqladmin --no-defaults -u root ver

   * If you updated an existing MySQL installation from a version
     earlier than Version 3.22.11 to Version 3.22.11 or later, did you
     run the `mysql_fix_privilege_tables' script?  If not, do so.  The
     structure of the grant tables changed with MySQL Version 3.22.11
     when the `GRANT' statement became functional.  *Note
     Upgrading-grant-tables::.

   * If your privileges seem to have changed in the middle of a
     session, it may be that a superuser has changed them.  Reloading
     the grant tables affects new client connections, but it also
     affects existing connections as indicated in *Note Privilege
     changes::.

   * If you can't get your password to work, remember that you must use
     the `PASSWORD()' function if you set the password with the
     `INSERT', `UPDATE', or `SET PASSWORD' statements.  The
     `PASSWORD()' function is unnecessary if you specify the password
     using the `GRANT ... IDENTIFIED BY' statement or the `mysqladmin
     password' command.  *Note Passwords::.

   * `localhost' is a synonym for your local hostname, and is also the
     default host to which clients try to connect if you specify no host
     explicitly.  However, connections to `localhost' do not work if
     you are using a MySQL version prior to 3.23.27 that uses
     MIT-pthreads (`localhost' connections are made using Unix socket
     files, which were not supported by MIT-pthreads at that time).  To
     avoid this problem on such systems, you should use the `--host'
     option to name the server host explicitly.  This will make a
     TCP/IP connection to the `mysqld' server.  In this case, you must
     have your real hostname in `user' table entries on the server
     host.  (This is true even if you are running a client program on
     the same host as the server.)

   * If you get an `Access denied' error when trying to connect to the
     database with `mysql -u user_name db_name', you may have a problem
     with the `user' table. Check this by executing `mysql -u root
     mysql' and issuing this SQL statement:

          mysql> SELECT * FROM user;

     The result should include an entry with the `Host' and `User'
     columns matching your computer's hostname and your MySQL username.

   * The `Access denied' error message will tell you who you are trying
     to log in as, the host from which you are trying to connect, and
     whether or not you were using a password. Normally, you should
     have one entry in the `user' table that exactly matches the
     hostname and username that were given in the error message. For
     example if you get an error message that contains `Using password:
     NO', this means that you tried to log in without an password.

   * If you get the following error when you try to connect from a
     different host than the one on which the MySQL server is running,
     then there is no row in the `user' table that matches that host:

          Host ... is not allowed to connect to this MySQL server

     You can fix this by using the command-line tool `mysql' (on the
     server host!) to add a row to the `user', `db', or `host' table
     for the user/hostname combination from which you are trying to
     connect and then execute `mysqladmin flush-privileges'.  If you are
     not running MySQL Version 3.22 and you don't know the IP number or
     hostname of the machine from which you are connecting, you should
     put an entry with `'%'' as the `Host' column value in the `user'
     table and restart `mysqld' with the `--log' option on the server
     machine.  After trying to connect from the client machine, the
     information in the MySQL log will indicate how you really did
     connect.  (Then replace the `'%'' in the `user' table entry with
     the actual hostname that shows up in the log.  Otherwise, you'll
     have a system that is insecure.)

     Another reason for this error on Linux is that you are using a
     binary MySQL version that is compiled with a different glibc
     version than the one you are using.  In this case you should
     either upgrade your OS/glibc or download the source MySQL version
     and compile this yourself.  A source RPM is normally trivial to
     compile and install, so this isn't a big problem.

   * If you get an error message where the hostname is not shown or
     where the hostname is an IP, even if you try to connect with a
     hostname:

          shell> mysqladmin -u root -pxxxx -h some-hostname ver
          Access denied for user: 'root@' (Using password: YES)

     This means that MySQL got some error when trying to resolve the IP
     to a hostname.  In this case you can execute `mysqladmin
     flush-hosts' to reset the internal DNS cache. *Note DNS::.

     Some permanent solutions are:

        - Try to find out what is wrong with your DNS server and fix
          this.

        - Specify IPs instead of hostnames in the MySQL privilege
          tables.

        - Start `mysqld' with `--skip-name-resolve'.

        - Start `mysqld' with `--skip-host-cache'.

        - Connect to `localhost' if you are running the server and the
          client on the same machine.

        - Put the client machine names in `/etc/hosts'.

   * If `mysql -u root test' works but `mysql -h your_hostname -u root
     test' results in `Access denied', then you may not have the
     correct name for your host in the `user' table.  A common problem
     here is that the `Host' value in the user table entry specifies an
     unqualified hostname, but your system's name resolution routines
     return a fully qualified domain name (or vice-versa).  For
     example, if you have an entry with host `'tcx'' in the `user'
     table, but your DNS tells MySQL that your hostname is
     `'tcx.subnet.se'', the entry will not work. Try adding an entry to
     the `user' table that contains the IP number of your host as the
     `Host' column value.  (Alternatively, you could add an entry to the
     `user' table with a `Host' value that contains a wildcard--for
     example, `'tcx.%''.  However, use of hostnames ending with `%' is
     *insecure* and is *not* recommended!)

   * If `mysql -u user_name test' works but `mysql -u user_name
     other_db_name' doesn't work, you don't have an entry for
     `other_db_name' listed in the `db' table.

   * If `mysql -u user_name db_name' works when executed on the server
     machine, but `mysql -h host_name -u user_name db_name' doesn't
     work when executed on another client machine, you don't have the
     client machine listed in the `user' table or the `db' table.

   * If you can't figure out why you get `Access denied', remove from
     the `user' table all entries that have `Host' values containing
     wildcards (entries that contain `%' or `_').  A very common error
     is to insert a new entry with `Host'=`'%'' and `User'=`'some
     user'', thinking that this will allow you to specify `localhost'
     to connect from the same machine.  The reason that this doesn't
     work is that the default privileges include an entry with
     `Host'=`'localhost'' and `User'=`'''.  Because that entry has a
     `Host' value `'localhost'' that is more specific than `'%'', it is
     used in preference to the new entry when connecting from
     `localhost'!  The correct procedure is to insert a second entry
     with `Host'=`'localhost'' and `User'=`'some_user'', or to remove
     the entry with `Host'=`'localhost'' and `User'=`'''.

   * If you get the following error, you may have a problem with the
     `db' or `host' table:

          Access to database denied

     If the entry selected from the `db' table has an empty value in the
     `Host' column, make sure there are one or more corresponding
     entries in the `host' table specifying which hosts the `db' table
     entry applies to.

     If you get the error when using the SQL commands `SELECT ...  INTO
     OUTFILE' or `LOAD DATA INFILE', your entry in the `user' table
     probably doesn't have the `FILE' privilege enabled.

   * Remember that client programs will use connection parameters
     specified in configuration files or environment variables.  *Note
     Environment variables::.  If a client seems to be sending the
     wrong default connection parameters when you don't specify them on
     the command-line, check your environment and the `.my.cnf' file in
     your home directory.  You might also check the system-wide MySQL
     configuration files, though it is far less likely that client
     connection parameters will be specified there. If you get `Access
     denied' when you run a client without any options, make sure you
     haven't specified an old password in any of your option files!
     *Note Option files::.

   * If you make changes to the grant tables directly (using an
     `INSERT' or `UPDATE' statement) and your changes seem to be
     ignored, remember that you must issue a `FLUSH PRIVILEGES'
     statement or execute a `mysqladmin flush-privileges' command to
     cause the server to re-read the privilege tables. Otherwise, your
     changes have no effect until the next time the server is
     restarted.  Remember that after you set the `root' password with
     an `UPDATE' command, you won't need to specify it until after you
     flush the privileges, because the server won't know you've changed
     the password yet!

   * If you have access problems with a Perl, PHP, Python, or ODBC
     program, try to connect to the server with `mysql -u user_name
     db_name' or `mysql -u user_name -pyour_pass db_name'.  If you are
     able to connect using the `mysql' client, there is a problem with
     your program and not with the access privileges.  (Note that there
     is no space between `-p' and the password; you can also use the
     `--password=your_pass' syntax to specify the password. If you use
     the `-p' option alone, MySQL will prompt you for the password.)

   * For testing, start the `mysqld' daemon with the
     `--skip-grant-tables' option.  Then you can change the MySQL grant
     tables and use the `mysqlaccess' script to check whether your
     modifications have the desired effect.  When you are satisfied
     with your changes, execute `mysqladmin flush-privileges' to tell
     the `mysqld' server to start using the new grant tables.  *Note:*
     Reloading the grant tables overrides the `--skip-grant-tables'
     option.  This allows you to tell the server to begin using the
     grant tables again without bringing it down and restarting it.

   * If everything else fails, start the `mysqld' daemon with a
     debugging option (for example, `--debug=d,general,query'). This
     will print host and user information about attempted connections,
     as well as information about each command issued. *Note Making
     trace files::.

   * If you have any other problems with the MySQL grant tables and
     feel you must post the problem to the mailing list, always provide
     a dump of the MySQL grant tables. You can dump the tables with the
     `mysqldump mysql' command. As always, post your problem using the
     `mysqlbug' script.  *Note Bug reports::.  In some cases you may
     need to restart `mysqld' with `--skip-grant-tables' to run
     `mysqldump'.

MySQL User Account Management
=============================

MySQL Usernames and Passwords
-----------------------------

There are several distinctions between the way usernames and passwords
are used by MySQL and the way they are used by Unix or Windows:

   * Usernames, as used by MySQL for authentication purposes, have
     nothing to do with Unix usernames (login names) or Windows
     usernames.  Most MySQL clients by default try to log in using the
     current Unix user name as the MySQL username, but that is for
     convenience only.  Client programs allow a different name to be
     specified with the `-u' or `--user' options. This means that you
     can't make a database secure in any way unless all MySQL usernames
     have passwords.  Anyone may attempt to connect to the server using
     any name, and they will succeed if they specify any name that
     doesn't have a password.

   * MySQL usernames can be up to 16 characters long; Unix usernames
     typically are limited to 8 characters.

   * MySQL passwords have nothing to do with Unix passwords.  There is
     no necessary connection between the password you use to log in to
     a Unix machine and the password you use to access a database on
     that machine.

   * MySQL encrypts passwords using a different algorithm than the one
     used during the Unix login process.  See the descriptions of the
     `PASSWORD()' and `ENCRYPT()' functions in *Note Encryption
     functions::.  Note that even if the password is stored
     'scrambled', and knowing your 'scrambled' password is enough to be
     able to connect to the MySQL server!  From version 4.1, MySQL
     employs a different password and login mechanism that is secure
     even if TCP/IP packets are sniffed and/or the mysql database is
     captured.

MySQL users and their privileges are normally created with the `GRANT'
command. *Note GRANT::.

When you login to a MySQL server with a command-line client you should
specify the password with `--password=your-password'.  *Note
Connecting::.

     mysql --user=monty --password=guess database_name

If you want the client to prompt for a password, you should use
`--password' without any argument

     mysql --user=monty --password database_name

or the short form:

     mysql -u monty -p database_name

Note that in the last example the password is *not* 'database_name'.

If you want to use the `-p' option to supply a password you should do so
like this:

     mysql -u monty -pguess database_name

On some systems, the library call that MySQL uses to prompt for a
password will automatically cut the password to 8 characters. Internally
MySQL doesn't have any limit for the length of the password.

When Privilege Changes Take Effect
----------------------------------

When `mysqld' starts, all grant table contents are read into memory and
become effective at that point.

Modifications to the grant tables that you perform using `GRANT',
`REVOKE', or `SET PASSWORD' are noticed by the server immediately.

If you modify the grant tables manually (using `INSERT', `UPDATE',
etc.), you should execute a `FLUSH PRIVILEGES' statement or run
`mysqladmin flush-privileges' or `mysqladmin reload' to tell the server
to reload the grant tables. Otherwise, your changes will have _no
effect_ until you restart the server. If you change the grant tables
manually but forget to reload the privileges, you will be wondering why
your changes don't seem to make any difference!

When the server notices that the grant tables have been changed,
existing client connections are affected as follows:

   * Table and column privilege changes take effect with the client's
     next request.

   * Database privilege changes take effect at the next `USE db_name'
     command.

   * Global privilege changes and password changes take effect the next
     time the client connects.

Setting Up the Initial MySQL Privileges
---------------------------------------

After installing MySQL, you set up the initial access privileges by
running `scripts/mysql_install_db'.  *Note Quick install::.  The
`mysql_install_db' script starts the `mysqld' server, then initializes
the grant tables to contain the following set of privileges:

   * The MySQL `root' user is created as a superuser who can do
     anything.  Connections must be made from the local host.

     *Note:* The initial `root' password is empty, so anyone can
     connect as `root' _without a password_ and be granted all
     privileges.

   * An anonymous user is created that can do anything with databases
     that have a name of `'test'' or starting with `'test_''.
     Connections must be made from the local host.  This means any
     local user can connect without a password and be treated as the
     anonymous user.

   * Other privileges are denied.  For example, normal users can't use
     `mysqladmin shutdown' or `mysqladmin processlist'.

*Note:* The default privileges are different for Windows.  *Note
Windows running::.

Because your installation is initially wide open, one of the first
things you should do is specify a password for the MySQL `root' user.
You can do this as follows (note that you specify the password using
the `PASSWORD()' function):

     shell> mysql -u root mysql
     mysql> SET PASSWORD FOR root@localhost=PASSWORD('new_password');

Replace `'new_password'' with the password that you want to use.

If you know what you are doing, you can also directly manipulate the
privilege tables:

     shell> mysql -u root mysql
     mysql> UPDATE user SET Password=PASSWORD('new_password')
         ->     WHERE user='root';
     mysql> FLUSH PRIVILEGES;

Another way to set the password is by using the `mysqladmin' command:

     shell> mysqladmin -u root password new_password

Only users with write/update access to the `mysql' database can change
the password for other users.  All normal users (not anonymous ones)
can only change their own password with either of the above commands or
with `SET PASSWORD=PASSWORD('new_password')'.

Note that if you update the password in the `user' table directly using
`UPDATE', you must tell the server to re-read the grant tables (with
`FLUSH PRIVILEGES'), because the change will go unnoticed otherwise.

Once the `root' password has been set, thereafter you must supply that
password when you connect to the server as `root'.

You may wish to leave the `root' password blank so that you don't need
to specify it while you perform additional setup or testing. However,
be sure to set it before using your installation for any real
production work.

See the `scripts/mysql_install_db' script to see how it sets up the
default privileges.  You can use this as a basis to see how to add
other users.

If you want the initial privileges to be different from those just
described above, you can modify `mysql_install_db' before you run it.

To re-create the grant tables completely, remove all the `.frm',
`.MYI', and `.MYD' files in the directory containing the `mysql'
database.  (This is the directory named `mysql' under the database
directory, which is listed when you run `mysqld --help'.) Then run the
`mysql_install_db' script, possibly after editing it first to have the
privileges you want.

*Note:* For MySQL versions older than Version 3.22.10, you should not
delete the `.frm' files.  If you accidentally do this, you should copy
them back from your MySQL distribution before running
`mysql_install_db'.

Adding New Users to MySQL
-------------------------

You can add users two different ways: by using `GRANT' statements or by
manipulating the MySQL grant tables directly.  The preferred method is
to use `GRANT' statements, because they are more concise and less
error-prone. *Note GRANT::.

There are also several contributed programs (such as `phpMyAdmin') that
can be used to create and administer users.

The following examples show how to use the `mysql' client to set up new
users.  These examples assume that privileges are set up according to
the defaults described in the previous section.  This means that to
make changes, you must be on the same machine where `mysqld' is
running, you must connect as the MySQL `root' user, and the `root' user
must have the `INSERT' privilege for the `mysql' database and the
`RELOAD' administrative privilege.  Also, if you have changed the
`root' user password, you must specify it for the `mysql' commands here.

First, use the `mysql' program to connect to the server as the MySQL
`root' user:

     shell> mysql --user=root mysql

Then you can add new users by issuing `GRANT' statements:

     mysql> GRANT ALL PRIVILEGES ON *.* TO monty@localhost
         ->     IDENTIFIED BY 'some_pass' WITH GRANT OPTION;
     mysql> GRANT ALL PRIVILEGES ON *.* TO monty@'%'
         ->     IDENTIFIED BY 'some_pass' WITH GRANT OPTION;
     mysql> GRANT RELOAD,PROCESS ON *.* TO admin@localhost;
     mysql> GRANT USAGE ON *.* TO dummy@localhost;

These `GRANT' statements set up three new users:

`monty'
     A full superuser who can connect to the server from anywhere, but
     who must use a password `'some_pass'' to do so.  Note that we must
     issue `GRANT' statements for both `monty@localhost' and
     `monty@"%"'.  If we don't add the entry with `localhost', the
     anonymous user entry for `localhost' that is created by
     `mysql_install_db' takes precedence when we connect from the local
     host, because it has a more specific `Host' column value and thus
     comes earlier in the `user' table sort order.

`admin'
     A user who can connect from `localhost' without a password and who
     is granted the `RELOAD' and `PROCESS' administrative privileges.
     This allows the user to execute the `mysqladmin reload',
     `mysqladmin refresh', and `mysqladmin flush-*' commands, as well as
     `mysqladmin processlist' .  No database-level privileges are
     granted.  (They can be granted later by issuing additional `GRANT'
     statements.)

`dummy'
     A user who can connect without a password, but only from the local
     host.  No privileges are granted--the `USAGE' privilege type
     allows you to create a user with no privileges. It has the effect
     of setting all the global privileges to `'N''.  It is assumed that
     you will grant specific privileges to the account later.

You can also add the same user access information directly by issuing
`INSERT' statements and then telling the server to reload the grant
tables:

     shell> mysql --user=root mysql
     mysql> INSERT INTO user VALUES('localhost','monty',PASSWORD('some_pass'),
         ->          'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
     mysql> INSERT INTO user VALUES('%','monty',PASSWORD('some_pass'),
         ->          'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
     mysql> INSERT INTO user SET Host='localhost',User='admin',
         ->           Reload_priv='Y', Process_priv='Y';
     mysql> INSERT INTO user (Host,User,Password)
         ->                  VALUES('localhost','dummy','');
     mysql> FLUSH PRIVILEGES;

Depending on your MySQL version, you may have to use a different number
of `'Y'' values above. (Versions prior to Version 3.22.11 have fewer
privilege columns, and versions from 4.0.2 on have more.)  For the
`admin' user, the more readable extended `INSERT' syntax using `SET'
that is available starting with Version 3.22.11 is used.

Note that to set up a superuser, you need only create a `user' table
entry with the privilege columns set to `'Y''.  No `db' or `host' table
entries are necessary.

In the last `INSERT' statement (for the `dummy' user), only the `Host',
`User', and `Password' columns in the `user' table record are assigned
values. None of the privilege columns are set explicitly, so MySQL
assigns them all the default value of `'N''.  This is the same thing
that `GRANT USAGE' does.

The following example adds a user `custom' who can access the
`bankaccount' database only from the local host, the `expenses'
database only from the host `whitehouse.gov', and the `customer'
database only from the host `server.domain'.  He wants to use the
password `obscure' from all three hosts.

To set up this user's privileges using `GRANT' statements, run these
commands:

     shell> mysql --user=root mysql
     mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
         ->     ON bankaccount.*
         ->     TO custom@localhost
         ->     IDENTIFIED BY 'obscure';
     mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
         ->     ON expenses.*
         ->     TO custom@'whitehouse.gov'
         ->     IDENTIFIED BY 'obscure';
     mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
         ->     ON customer.*
         ->     TO custom@'server.domain'
         ->     IDENTIFIED BY 'obscure';

To set up the user's privileges by modifying the grant tables directly,
run these commands (note the `FLUSH PRIVILEGES' at the end):

     shell> mysql --user=root mysql
     mysql> INSERT INTO user (Host,User,Password)
         -> VALUES('localhost','custom',PASSWORD('obscure'));
     mysql> INSERT INTO user (Host,User,Password)
         -> VALUES('whitehouse.gov','custom',PASSWORD('obscure'));
     mysql> INSERT INTO user (Host,User,Password)
         -> VALUES('server.domain','custom',PASSWORD('obscure'));
     mysql> INSERT INTO db
         -> (Host,Db,User,Select_priv,Insert_priv,Update_priv,Delete_priv,
         ->  Create_priv,Drop_priv)
         -> VALUES
         -> ('localhost','bankaccount','custom','Y','Y','Y','Y','Y','Y');
     mysql> INSERT INTO db
         -> (Host,Db,User,Select_priv,Insert_priv,Update_priv,Delete_priv,
         ->  Create_priv,Drop_priv)
         -> VALUES
         -> ('whitehouse.gov','expenses','custom','Y','Y','Y','Y','Y','Y');
     mysql> INSERT INTO db
         -> (Host,Db,User,Select_priv,Insert_priv,Update_priv,Delete_priv,
         ->  Create_priv,Drop_priv)
         -> VALUES('server.domain','customer','custom','Y','Y','Y','Y','Y','Y');
     mysql> FLUSH PRIVILEGES;

As in the preceding example that used `INSERT' statements, you may need
to use a different number of `'Y'' values, depending on your version of
MySQL.

The first three `INSERT' statements add `user' table entries that allow
user `custom' to connect from the various hosts with the given
password, but grant no permissions (all privileges are set to the
default value of `'N'').  The next three `INSERT' statements add `db'
table entries that grant privileges to `custom' for the `bankaccount',
`expenses', and `customer' databases, but only when accessed from the
proper hosts.  As usual, after you modify the grant tables directly ,
you must tell the server to reload them (with `FLUSH PRIVILEGES') so
that the privilege changes take effect.

If you want to give a specific user access from any machine in a given
domain (for example, `mydomain.com'), you can issue a `GRANT' statement
like the following:

     mysql> GRANT ...
         ->     ON *.*
         ->     TO myusername@'%.mydomain.com'
         ->     IDENTIFIED BY 'mypassword';

To do the same thing by modifying the grant tables directly, do this:

     mysql> INSERT INTO user VALUES ('%.mydomain.com', 'myusername',
         ->             PASSWORD('mypassword'),...);
     mysql> FLUSH PRIVILEGES;

Deleting Users from MySQL
-------------------------

     DROP USER user_name

This command was added to MySQL 4.1.1.

It deletes a user that doesn't have any privileges.

To delete a user from MySQL, you should use the following procedure,
performing the steps in the order shown:

  1. Check which privileges the user has with `SHOW PRIVILEGES'.  *Note
     SHOW PRIVILEGES::.

  2. Delete all privileges from the user with `REVOKE'. *Note GRANT::.

  3. Delete the user with `DROP USER'.

If you are using and older MySQL version you should first revoke the
privileges and then delete the user with:

     DELETE FROM mysql.user WHERE user='username' and host='hostname';
     FLUSH PRIVILEGES;

Limiting user resources
-----------------------

Starting from MySQL 4.0.2 one can limit certain resources per user.

So far, the only available method of limiting usage of MySQL server
resources has been setting the `max_user_connections' startup variable
to a non-zero value. But this method is strictly global and does not
allow for management of individual users, which could be of particular
interest to Internet Service Providers.

Therefore, management of three resources is introduced on the
individual user level:

   * Number of all queries per hour: All commands that could be run by
     a user.

   * Number of all updates per hour: Any command that changes any table
     or database.

   * Number of connections made per hour: New connections opened per
     hour.

A user in the aforementioned context is a single entry in the `user'
table, which is uniquely identified by its `user' and `host' columns.

All users are by default not limited in using the above resources,
unless the limits are granted to them. These limits can be granted
*only* via global `GRANT (*.*)', using this syntax:

     GRANT ... WITH MAX_QUERIES_PER_HOUR N1
                    MAX_UPDATES_PER_HOUR N2
                    MAX_CONNECTIONS_PER_HOUR N3;

One can specify any combination of the above resources.  `N1', `N2',
and `N3' are integers and represent counts per hour.

If a user reaches the limit on number of connections within one hour, no
further connections will be accepted until that hour is up. Similarly,
if the user reaches the limit on number of queries or updates, further
queries or updates will be rejected until the hour is up. In all cases,
an appropriate error message shall be issued.

Current usage values for a particular user can be flushed (set to zero)
by issuing a `GRANT' statement with any of the above clauses, including
a `GRANT' statement with the current values.

Also, current values for all users will be flushed if privileges are
reloaded (in the server or using `mysqladmin reload') or if the `FLUSH
USER_RESOURCES' command is issued.

The feature is enabled as soon as a single user is granted with any of
the limiting `GRANT' clauses.

As a prerequisite for enabling this feature, the `user' table in the
`mysql' database must contain the additional columns, as defined in the
table creation scripts `mysql_install_db' and `mysql_install_db.sh' in
`scripts' subdirectory.

Setting Up Passwords
--------------------

In most cases you should use `GRANT' to set up your users/passwords, so
the following only applies for advanced users. *Note `GRANT': GRANT.

The examples in the preceding sections illustrate an important
principle: when you store a non-empty password using `INSERT' or
`UPDATE' statements, you must use the `PASSWORD()' function to encrypt
it.  This is because the `user' table stores passwords in encrypted
form, not as plaintext.  If you forget that fact, you are likely to
attempt to set passwords like this:

     shell> mysql -u root mysql
     mysql> INSERT INTO user (Host,User,Password)
         -> VALUES('%','jeffrey','biscuit');
     mysql> FLUSH PRIVILEGES;

The result is that the plaintext value `'biscuit'' is stored as the
password in the `user' table.  When the user `jeffrey' attempts to
connect to the server using this password, the `mysql' client encrypts
it with `PASSWORD()', generates an authentication vector based on
*encrypted* password and a random number, obtained from server, and
sends the result to the server.  The server uses the `password' value
in the `user' table (that is *not encrypted* value `'biscuit'') to
perform the same calculations, and compares results.  The comparison
fails and the server rejects the connection:

     shell> mysql -u jeffrey -pbiscuit test
     Access denied

Passwords must be encrypted when they are inserted in the `user' table,
so the `INSERT' statement should have been specified like this instead:

     mysql> INSERT INTO user (Host,User,Password)
         -> VALUES('%','jeffrey',PASSWORD('biscuit'));

You must also use the `PASSWORD()' function when you use `SET PASSWORD'
statements:

     mysql> SET PASSWORD FOR jeffrey@"%" = PASSWORD('biscuit');

If you set passwords using the `GRANT ... IDENTIFIED BY' statement or
the `mysqladmin password' command, the `PASSWORD()' function is
unnecessary.  They both take care of encrypting the password for you,
so you would specify a password of `'biscuit'' like this:

     mysql> GRANT USAGE ON *.* TO jeffrey@"%" IDENTIFIED BY 'biscuit';

or:

     shell> mysqladmin -u jeffrey password biscuit

*Note:* `PASSWORD()' is different from Unix password encryption.  *Note
User names::.

Keeping Your Password Secure
----------------------------

It is inadvisable to specify your password in a way that exposes it to
discovery by other users.  The methods you can use to specify your
password when you run client programs are listed here, along with an
assessment of the risks of each method:

   * Never give a normal user access to the `mysql.user' table. Knowing
     the encrypted password for a user makes it possible to log in as
     this user.  The passwords are only scrambled so that one shouldn't
     be able to see the real password you used (if you happen to use a
     similar password with your other applications).

   * Use a `-pyour_pass' or `--password=your_pass' option on the command
     line.  This is convenient but insecure, because your password
     becomes visible to system status programs (such as `ps') that may
     be invoked by other users to display command-lines.  (MySQL
     clients typically overwrite the command-line argument with zeroes
     during their initialization sequence, but there is still a brief
     interval during which the value is visible.)

   * Use a `-p' or `--password' option (with no `your_pass' value
     specified).  In this case, the client program solicits the
     password from the terminal:

          shell> mysql -u user_name -p
          Enter password: ********

     The `*' characters represent your password.

     It is more secure to enter your password this way than to specify
     it on the command-line because it is not visible to other users.
     However, this method of entering a password is suitable only for
     programs that you run interactively.  If you want to invoke a
     client from a script that runs non-interactively, there is no
     opportunity to enter the password from the terminal. On some
     systems, you may even find that the first line of your script is
     read and interpreted (incorrectly) as your password!

   * Store your password in a configuration file.  For example, you can
     list your password in the `[client]' section of the `.my.cnf' file
     in your home directory:

          [client]
          password=your_pass

     If you store your password in `.my.cnf', the file should not be
     group or world-readable or -writable.  Make sure the file's access
     mode is `400' or `600'.

     *Note Option files::.

   * You can store your password in the `MYSQL_PWD' environment
     variable, but this method must be considered extremely insecure
     and should not be used.  Some versions of `ps' include an option
     to display the environment of running processes; your password
     will be in plain sight for all to see if you set `MYSQL_PWD'.
     Even on systems without such a version of `ps', it is unwise to
     assume there is no other method to observe process environments.
     *Note Environment variables::.

All in all, the safest methods are to have the client program prompt
for the password or to specify the password in a properly protected
`.my.cnf' file.

Using Secure Connections
------------------------

This section describes how to set up secure connections between MySQL
clients and the server using the Secure Sockets Layer (SSL) protocol.
It also decribes a way to set up SSH on Windows.

Basics
......

Beginning with version 4.0.0, MySQL has support for SSL encrypted
connections. To understand how MySQL uses SSL, it's necessary to
explain some basic SSL and X509 concepts. People who are already
familiar with them can skip this part.

By default, MySQL uses unencrypted connections between the client and
the server. This means that someone could watch all your traffic and
look at the data being sent or received.  They could even change the
data while it is in transit between client and server. Sometimes you
need to move information over public networks in a secure fashion; in
such cases, using an unencrypted connection is unacceptable.

SSL is a protocol that uses different encryption algorithms to ensure
that data received over a public network can be trusted. It has
mechanisms to detect any change, loss or replay of data. SSL also
incorporates algorithms to recognize and provide identity verification
using the X509 standard.

Encryption is the way to make any kind of data unreadable. In fact,
today's practice requires many additional security elements from
encryption algorithms.  They should resist many kind of known attacks
like just messing with the order of encrypted messages or replaying data
twice.

X509 is a standard that makes it possible to identify someone on the
Internet.  It is most commonly used in e-commerce applications. In basic
terms, there should be some company (called a "Certificate Authority")
that assigns electronic certificates to anyone who needs them.
Certificates rely on asymmetric encryption algorithms that have two
encryption keys (a public key and a secret key). A certificate owner
can prove his identity by showing his certificate to other party. A
certificate consists of its owner's public key. Any data encrypted with
this public key can be decrypted only using the corresponding secret
key, which is held by the owner of the certificate.

MySQL doesn't use encrypted connections by default, because doing so
would make the client/server protocol much slower. Any kind of
additional functionality requires the computer to do additional work and
encrypting data is a CPU-intensive operation that requires time and can
delay MySQL main tasks. By default MySQL is tuned to be fast as
possible.

If you need more information about SSL, X509, or encryption, you should
use your favorite Internet search engine and search for keywords in
which you are interested.

Requirements
............

To get secure connections to work with MySQL you must do the following:

  1. Install the OpenSSL library. We have tested MySQL with OpenSSL
     0.9.6.  `http://www.openssl.org/'.

  2. Configure MySQL with `--with-vio --with-openssl'.

  3. If you are using an old MySQL installation, you have to update your
     `mysql.user' table with some new SSL-related columns.  This is
     necessary if your grant tables date from a version prior to MySQL
     4.0.0.  The procedure is described in *Note
     Upgrading-grant-tables::.

  4. You can check if a running `mysqld' server supports OpenSSL by
     examining if `SHOW VARIABLES LIKE 'have_openssl'' returns `YES'.

Setting Up SSL Certificates for MySQL
.....................................

Here is an example for setting up SSL certificates for MySQL:

     DIR=`pwd`/openssl
     PRIV=$DIR/private

     mkdir $DIR $PRIV $DIR/newcerts
     cp /usr/share/ssl/openssl.cnf $DIR
     replace ./demoCA $DIR -- $DIR/openssl.cnf

     # Create necessary files: $database, $serial and $new_certs_dir
     # directory (optional)

     touch $DIR/index.txt
     echo "01" > $DIR/serial

     #
     # Generation of Certificate Authority(CA)
     #

     openssl req -new -x509 -keyout $PRIV/cakey.pem -out $DIR/cacert.pem \
         -config $DIR/openssl.cnf

     # Sample output:
     # Using configuration from /home/monty/openssl/openssl.cnf
     # Generating a 1024 bit RSA private key
     # ................++++++
     # .........++++++
     # writing new private key to '/home/monty/openssl/private/cakey.pem'
     # Enter PEM pass phrase:
     # Verifying password - Enter PEM pass phrase:
     # -----
     # You are about to be asked to enter information that will be incorporated
     # into your certificate request.
     # What you are about to enter is what is called a Distinguished Name or a DN.
     # There are quite a few fields but you can leave some blank
     # For some fields there will be a default value,
     # If you enter '.', the field will be left blank.
     # -----
     # Country Name (2 letter code) [AU]:FI
     # State or Province Name (full name) [Some-State]:.
     # Locality Name (eg, city) []:
     # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
     # Organizational Unit Name (eg, section) []:
     # Common Name (eg, YOUR name) []:MySQL admin
     # Email Address []:

     #
     # Create server request and key
     #
     openssl req -new -keyout $DIR/server-key.pem -out \
         $DIR/server-req.pem -days 3600 -config $DIR/openssl.cnf

     # Sample output:
     # Using configuration from /home/monty/openssl/openssl.cnf
     # Generating a 1024 bit RSA private key
     # ..++++++
     # ..........++++++
     # writing new private key to '/home/monty/openssl/server-key.pem'
     # Enter PEM pass phrase:
     # Verifying password - Enter PEM pass phrase:
     # -----
     # You are about to be asked to enter information that will be incorporated
     # into your certificate request.
     # What you are about to enter is what is called a Distinguished Name or a DN.
     # There are quite a few fields but you can leave some blank
     # For some fields there will be a default value,
     # If you enter '.', the field will be left blank.
     # -----
     # Country Name (2 letter code) [AU]:FI
     # State or Province Name (full name) [Some-State]:.
     # Locality Name (eg, city) []:
     # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
     # Organizational Unit Name (eg, section) []:
     # Common Name (eg, YOUR name) []:MySQL server
     # Email Address []:
     #
     # Please enter the following 'extra' attributes
     # to be sent with your certificate request
     # A challenge password []:
     # An optional company name []:

     #
     # Remove the passphrase from the key (optional)
     #

     openssl rsa -in $DIR/server-key.pem -out $DIR/server-key.pem

     #
     # Sign server cert
     #
     openssl ca  -policy policy_anything -out $DIR/server-cert.pem \
         -config $DIR/openssl.cnf -infiles $DIR/server-req.pem

     # Sample output:
     # Using configuration from /home/monty/openssl/openssl.cnf
     # Enter PEM pass phrase:
     # Check that the request matches the signature
     # Signature ok
     # The Subjects Distinguished Name is as follows
     # countryName           :PRINTABLE:'FI'
     # organizationName      :PRINTABLE:'MySQL AB'
     # commonName            :PRINTABLE:'MySQL admin'
     # Certificate is to be certified until Sep 13 14:22:46 2003 GMT (365 days)
     # Sign the certificate? [y/n]:y
     #
     #
     # 1 out of 1 certificate requests certified, commit? [y/n]y
     # Write out database with 1 new entries
     # Data Base Updated

     #
     # Create client request and key
     #
     openssl req -new -keyout $DIR/client-key.pem -out \
         $DIR/client-req.pem -days 3600 -config $DIR/openssl.cnf

     # Sample output:
     # Using configuration from /home/monty/openssl/openssl.cnf
     # Generating a 1024 bit RSA private key
     # .....................................++++++
     # .............................................++++++
     # writing new private key to '/home/monty/openssl/client-key.pem'
     # Enter PEM pass phrase:
     # Verifying password - Enter PEM pass phrase:
     # -----
     # You are about to be asked to enter information that will be incorporated
     # into your certificate request.
     # What you are about to enter is what is called a Distinguished Name or a DN.
     # There are quite a few fields but you can leave some blank
     # For some fields there will be a default value,
     # If you enter '.', the field will be left blank.
     # -----
     # Country Name (2 letter code) [AU]:FI
     # State or Province Name (full name) [Some-State]:.
     # Locality Name (eg, city) []:
     # Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
     # Organizational Unit Name (eg, section) []:
     # Common Name (eg, YOUR name) []:MySQL user
     # Email Address []:
     #
     # Please enter the following 'extra' attributes
     # to be sent with your certificate request
     # A challenge password []:
     # An optional company name []:

     #
     # Remove a passphrase from the key (optional)
     #
     openssl rsa -in $DIR/client-key.pem -out $DIR/client-key.pem

     #
     # Sign client cert
     #

     openssl ca  -policy policy_anything -out $DIR/client-cert.pem \
         -config $DIR/openssl.cnf -infiles $DIR/client-req.pem

     # Sample output:
     # Using configuration from /home/monty/openssl/openssl.cnf
     # Enter PEM pass phrase:
     # Check that the request matches the signature
     # Signature ok
     # The Subjects Distinguished Name is as follows
     # countryName           :PRINTABLE:'FI'
     # organizationName      :PRINTABLE:'MySQL AB'
     # commonName            :PRINTABLE:'MySQL user'
     # Certificate is to be certified until Sep 13 16:45:17 2003 GMT (365 days)
     # Sign the certificate? [y/n]:y
     #
     #
     # 1 out of 1 certificate requests certified, commit? [y/n]y
     # Write out database with 1 new entries
     # Data Base Updated

     #
     # Create a my.cnf file that you can use to test the certificates
     #

     cnf=""
     cnf="$cnf [client]"
     cnf="$cnf ssl-ca=$DIR/cacert.pem"
     cnf="$cnf ssl-cert=$DIR/client-cert.pem"
     cnf="$cnf ssl-key=$DIR/client-key.pem"
     cnf="$cnf [mysqld]"
     cnf="$cnf ssl-ca=$DIR/cacert.pem"
     cnf="$cnf ssl-cert=$DIR/server-cert.pem"
     cnf="$cnf ssl-key=$DIR/server-key.pem"
     echo $cnf | replace " " '
     ' > $DIR/my.cnf

     #
     # To test MySQL

     mysqld --defaults-file=$DIR/my.cnf &

     mysql --defaults-file=$DIR/my.cnf

You can also test your setup by modifying the above `my.cnf' file to
refer to the demo certificates in the mysql-source-dist/SSL direcory.

SSL `GRANT' Options
...................

MySQL can check X509 certificate attributes in addition to the normal
username/password scheme. All the usual options are still required
(username, password, IP address mask, database/table name).

There are different possibilities to limit connections:

   * Without any SSL or X509 options, all kind of encrypted/unencrypted
     connections are allowed if the username and password are valid.

   * `REQUIRE SSL' option limits the server to allow only SSL encrypted
     connections. Note that this option can be omitted if there are any
     ACL records which allow non-SSL connections.

          mysql> GRANT ALL PRIVILEGES ON test.* TO root@localhost
              -> IDENTIFIED BY 'goodsecret' REQUIRE SSL;

   * `REQUIRE X509' means that the client should have a valid
     certificate but we do not care about the exact certificate, issuer
     or subject.  The only restriction is that it should be possible to
     verify its signature with one of the CA certificates.

          mysql> GRANT ALL PRIVILEGES ON test.* TO root@localhost
              -> IDENTIFIED BY 'goodsecret' REQUIRE X509;

   * `REQUIRE ISSUER 'issuer'' places a restriction on connection
     attempts: The client must present a valid X509 certificate issued
     by CA `'issuer''.  Using X509 certificates always implies
     encryption, so the `SSL' option is unneccessary.

          mysql> GRANT ALL PRIVILEGES ON test.* TO root@localhost
              -> IDENTIFIED BY 'goodsecret'
              -> REQUIRE ISSUER 'C=FI, ST=Some-State, L=Helsinki,
              '> O=MySQL Finland AB, CN=Tonu Samuel/Email=[e-mail]';

   * `REQUIRE SUBJECT 'subject'' requires clients to have valid X509
     certificate with subject `'subject'' on it. If the client presents
     a certificate that is valid but has a different `'subject'', the
     connection is disallowed.

          mysql> GRANT ALL PRIVILEGES ON test.* TO root@localhost
              -> IDENTIFIED BY 'goodsecret'
              -> REQUIRE SUBJECT 'C=EE, ST=Some-State, L=Tallinn,
              '> O=MySQL demo client certificate,
              '> CN=Tonu Samuel/Email=[e-mail]';

   * `REQUIRE CIPHER 'cipher'' is needed to assure enough strong ciphers
     and keylengths will be used. SSL itself can be weak if old
     algorithms with short encryption keys are used. Using this option,
     we can ask for some exact cipher method to allow a connection.

          mysql> GRANT ALL PRIVILEGES ON test.* TO root@localhost
              -> IDENTIFIED BY 'goodsecret'
              -> REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';

     The `SUBJECT', `ISSUER', and `CIPHER' options can be combined in
     the `REQUIRE' clause like this:

          mysql> GRANT ALL PRIVILEGES ON test.* TO root@localhost
              -> IDENTIFIED BY 'goodsecret'
              -> REQUIRE SUBJECT 'C=EE, ST=Some-State, L=Tallinn,
              '> O=MySQL demo client certificate,
              '> CN=Tonu Samuel/Email=[e-mail]'
              -> AND ISSUER 'C=FI, ST=Some-State, L=Helsinki,
              '> O=MySQL Finland AB, CN=Tonu Samuel/Email=[e-mail]'
              -> AND CIPHER 'EDH-RSA-DES-CBC3-SHA';

     Starting from MySQL 4.0.4 the `AND' keyword is optional between
     `REQUIRE' options.

     The order of the options does not matter, but no option can be
     specified twice.

SSL Command-line Options
........................

The following table lists options that are used for specifying the use
of SSL, certificate files, and key files.  These options are available
beginning with MySQL 4.0. They may be given on the command line or in
option files.

`--ssl'
     For the server, specifies that the server allows SSL connections.
     For a client program, allows the client to connect to the server
     using SSL.  This option itself is not sufficient to cause an SSL
     connection to be used.  You must also specify the `--ssl-ca',
     `--ssl-cert', and `--ssl-key' options.

     Note that this option doesn't *require* an SSL connection.  For
     example, if the server or client are compiled without SSL support,
     a normal unencrypted connection will be used.

     The secure way to ensure that a SSL connection will be used is to
     create an account on the server that includes a `REQUIRE SSL'
     clause in the `GRANT' statement.  Then use this account to connect
     to the server, with both a server and client that have SSL support
     enabled.

     You can use this option to indicate that the connection should not
     use SSL.  Do this by specifying the option as `--skip-ssl' or
     `--ssl=0'.

`--ssl-ca=file_name'
     The path to a file with a list of trusted SSL CAs.

`--ssl-capath=directory_name'
     The path to a directory that contains trusted SSL CA certificates
     in pem format.

`--ssl-cert=file_name'
     The name of the SSL certificate file to use used for establishing
     a secure connection.

`--ssl-cipher=cipher_list'
     A list of allowable ciphers to use for SSL encryption.
     `cipher_list' has the same format as the `openssl ciphers' command.

     Example: `--ssl-cipher=ALL:-AES:-EXP'

`--ssl-key=file_name'
     The name of the SSL key file to use used for establishing a secure
     connection.

Connecting to MySQL Remotely from Windows with SSH
..................................................

Here is a note about how to connect to get a secure connection to remote
MySQL server with SSH (by David Carlson <[e-mail]>):

  1. Install an SSH client on your Windows machine.  As a user, the
     best non-free one I've found is from `SecureCRT' from
     `http://www.vandyke.com/'.  Another option is `f-secure' from
     `http://www.f-secure.com/'. You can also find some free ones on
     `Google' at
     `http://directory.google.com/Top/Computers/Security/Products_and_Tools/Cryptography/SSH/Clients/Windows/'.

  2. Start your Windows SSH client.  Set `Host_Name =
     yourmysqlserver_URL_or_IP'.  Set `userid=your_userid' to log in to
     your server. This `userid' value may not be the same as the
     username of your MySQL account.

  3. Set up port forwarding. Either do a remote forward (Set
     `local_port: 3306', `remote_host: yourmysqlservername_or_ip',
     `remote_port: 3306' ) or a local forward (Set `port: 3306',
     `host: localhost', `remote port: 3306').

  4. Save everything, otherwise you'll have to redo it the next time.

  5. Log in to your server with the SSH session you just created.

  6. On your Windows machine, start some ODBC application (such as
     Access).

  7. Create a new file in Windows and link to MySQL using the ODBC
     driver the same way you normally do, except type in `localhost'
     for the MySQL host server--not `yourmysqlservername'.

You should now have an ODBC connection to MySQL, encrypted using SSH.

Disaster Prevention and Recovery
================================

This section discusses how to make database backups and how to perform
table maintenance.  The syntax of the SQL statements described here is
given in *Note Database Administration::.

Database Backups
----------------

Because MySQL tables are stored as files, it is easy to do a backup. To
get a consistent backup, do a `LOCK TABLES' on the relevant tables
followed by `FLUSH TABLES' for the tables.  *Note `LOCK TABLES': LOCK
TABLES.  *Note `FLUSH': FLUSH.  You only need a read lock; this allows
other threads to continue to query the tables while you are making a
copy of the files in the database directory.  The `FLUSH TABLE' is
needed to ensure that the all active index pages is written to disk
before you start the backup.

Starting from 3.23.56 and 4.0.12 `BACKUP TABLE' will not allow you to
overwrite existing files as this would be a security risk.

If you want to make an SQL level backup of a table, you can use `SELECT
INTO OUTFILE' or `BACKUP TABLE'. *Note SELECT::.  *Note BACKUP TABLE::.

Another way to back up a database is to use the `mysqldump' program or
the `mysqlhotcopy script'. *Note `mysqldump': mysqldump.  *Note
`mysqlhotcopy': mysqlhotcopy.

  1. Do a full backup of your database:

          shell> mysqldump --tab=/path/to/some/dir --opt db_name

     or:

          shell> mysqlhotcopy db_name /path/to/some/dir

     You can also simply copy all table files (`*.frm', `*.MYD', and
     `*.MYI' files) as long as the server isn't updating anything.  The
     script `mysqlhotcopy' does use this method.  (But note that these
     methods will not work if your database contains `InnoDB' tables.
     `InnoDB' does not store table contents in database directories,
     and `mysqlhotcopy' works only for `MyISAM' and `ISAM' tables.)

  2. Stop `mysqld' if it's running, then start it with the
     `--log-bin[=file_name]' option.  *Note Binary log::. The binary
     log files provide you with the information you need to replicate
     changes to the database that are made subsequent to the point at
     which you executed `mysqldump'.

If your MySQL server is a slave, whatever backup method you choose,
when you backup your slave's data, you should also backup the
`master.info' and `relay-log.info' files which are always needed to
resume replication after you restore the slave's data. If your slave is
subject to replicating `LOAD DATA INFILE' commands, you should also
backup the `SQL_LOAD-*' files which may exist in the directory
specified by the `--slave-load-tmpdir' option. (This location defaults
to the value of the `tmpdir' variable if not specified.) The slave will
need these files to resume replication of any interrupted `LOAD DATA
INFILE' operations.

If you have to restore something, try to recover your tables using
`REPAIR TABLE' or `myisamchk -r' first.  That should work in 99.9% of
all cases.  If `myisamchk' fails, try the following procedure (this
will work only if you have started MySQL with `--log-bin', see *Note
Binary log::):

  1. Restore the original `mysqldump' backup, or binary backup.

  2. Execute the following command to re-run the updates in the binary
     log:

          shell> mysqlbinlog hostname-bin.[0-9]* | mysql

     In your case you may want to re-run only certain binlogs, from
     certain positions (usually you want to re-run all binlogs from the
     date of the restored backup, possibly excepted some wrong queries).
     See *Note mysqlbinlog:: for more information on the `mysqlbinlog'
     utility and how to use it.

     If you are using the update log (which is removed in MySQL 5.0.0)
     you can execute the content of the update log like this:

          shell> ls -1 -t -r hostname.[0-9]* | xargs cat | mysql

`ls' is used to get all the update log files in the right order.

You can also do selective backups with `SELECT * INTO OUTFILE
'file_name' FROM tbl_name' and restore with `LOAD DATA INFILE
'file_name' REPLACE ...' To avoid duplicate records, you need a
`PRIMARY KEY' or a `UNIQUE' key in the table. The `REPLACE' keyword
causes old records to be replaced with new ones when a new record
duplicates an old record on a unique key value.

If you get performance problems in making backups on your system, you
can solve this by setting up replication and do the backups on the slave
instead of on the master. *Note Replication Intro::.

If you are using a Veritas filesystem, you can do:

  1. From a client (or Perl), execute: `FLUSH TABLES WITH READ LOCK'.

  2. From another shell, execute: `mount vxfs snapshot'.

  3. From the first client, execute: `UNLOCK TABLES'.

  4. Copy files from snapshot.

  5. Unmount snapshot.

Using `myisamchk' for Table Maintenance and Crash Recovery
----------------------------------------------------------

Starting with MySQL Version 3.23.13, you can check MyISAM tables with
the `CHECK TABLE' command. *Note CHECK TABLE::.  You can repair tables
with the `REPAIR TABLE' command. *Note REPAIR TABLE::.

To check/repair MyISAM tables (`.MYI' and `.MYD') you should use the
`myisamchk' utility. To check/repair ISAM tables (`.ISM' and `.ISD')
you should use the `isamchk' utility. *Note Table types::.

In the following text we will talk about `myisamchk', but everything
also applies to the old `isamchk'.

You can use the `myisamchk' utility to get information about your
database tables, check and repair them, or optimize them.  The following
sections describe how to invoke `myisamchk' (including a description of
its options), how to set up a table maintenance schedule, and how to
use `myisamchk' to perform its various functions.

You can, in most cases, also use the command `OPTIMIZE TABLES' to
optimize and repair tables, but this is not as fast or reliable (in case
of real fatal errors) as `myisamchk'.  On the other hand, `OPTIMIZE
TABLE' is easier to use and you don't have to worry about flushing
tables.  *Note `OPTIMIZE TABLE': OPTIMIZE TABLE.

Even though the repair in `myisamchk' is quite secure, it's always a
good idea to make a backup _before_ doing a repair (or anything that
could make a lot of changes to a table)

`myisamchk' Invocation Syntax
.............................

`myisamchk' is invoked like this:

     shell> myisamchk [options] tbl_name

The `options' specify what you want `myisamchk' to do.  They are
described here.  (You can also get a list of options by invoking
`myisamchk --help'.)  With no options, `myisamchk' simply checks your
table.  To get more information or to tell `myisamchk' to take
corrective action, specify options as described here and in the
following sections.

`tbl_name' is the database table you want to check/repair.  If you run
`myisamchk' somewhere other than in the database directory, you must
specify the path to the file, because `myisamchk' has no idea where your
database is located.  Actually, `myisamchk' doesn't care whether the
files you are working on are located in a database directory; you can
copy the files that correspond to a database table into another
location and perform recovery operations on them there.

You can name several tables on the `myisamchk' command-line if you
wish.  You can also specify a name as an index file name (with the
`.MYI' suffix), which allows you to specify all tables in a directory
by using the pattern `*.MYI'.  For example, if you are in a database
directory, you can check all the tables in the directory like this:

     shell> myisamchk *.MYI

If you are not in the database directory, you can check all the tables
there by specifying the path to the directory:

     shell> myisamchk /path/to/database_dir/*.MYI

You can even check all tables in all databases by specifying a wildcard
with the path to the MySQL data directory:

     shell> myisamchk /path/to/datadir/*/*.MYI

The recommended way to quickly check all tables is:

     myisamchk --silent --fast /path/to/datadir/*/*.MYI
     isamchk --silent /path/to/datadir/*/*.ISM

If you want to check all tables and repair all tables that are
corrupted, you can use the following line:

     myisamchk --silent --force --fast --update-state -O key_buffer=64M \
               -O sort_buffer=64M -O read_buffer=1M -O write_buffer=1M \
               /path/to/datadir/*/*.MYI
     isamchk --silent --force -O key_buffer=64M -O sort_buffer=64M \
             -O read_buffer=1M -O write_buffer=1M /path/to/datadir/*/*.ISM

The above assumes that you have more than 64 M free.

Note that if you get an error like:

     myisamchk: warning: 1 clients is using or hasn't closed the table properly

This means that you are trying to check a table that has been updated by
another program (like the `mysqld' server) that hasn't yet closed the
file or that has died without closing the file properly.

If `mysqld' is running, you must force a sync/close of all tables with
`FLUSH TABLES' and ensure that no one is using the tables while you are
running `myisamchk'.  In MySQL Version 3.23 the easiest way to avoid
this problem is to use `CHECK TABLE' instead of `myisamchk' to check
tables.

General Options for `myisamchk'
...............................

`myisamchk' supports the following options.

`-# or --debug=debug_options'
     Output debug log. The `debug_options' string often is
     `'d:t:o,filename''.

`-? or --help'
     Display a help message and exit.

`-O name=value, --set-variable=name=value'
     Set the value of a variable.  Please note that
     `--set-variable=name=value' and `-O name=value' syntax is
     deprecated as of MySQL 4.0.  Use `--name=value' instead.  The
     possible variables and their default values for myisamchk can be
     examined with `myisamchk --help':
     *Variable*    *Value*
     key_buffer_size523264
     read_buffer_size262136
     write_buffer_size262136
     sort_buffer_size2097144
     sort_key_blocks16
     decode_bits   9

     `sort_buffer_size' is used when the keys are repaired by sorting
     keys, which is the normal case when you use `--recover'.

     `key_buffer_size' is used when you are checking the table with
     `--extended-check' or when the keys are repaired by inserting key
     row by row in to the table (like when doing normal inserts).
     Repairing through the key buffer is used in the following cases:

        * If you use `--safe-recover'.

        * If the temporary files needed to sort the keys would be more
          than twice as big as when creating the key file directly.
          This is often the case when you have big `CHAR', `VARCHAR' or
          `TEXT' keys as the sort needs to store the whole keys during
          sorting. If you have lots of temporary space and you can
          force `myisamchk' to repair by sorting you can use the
          `--sort-recover' option.

     Reparing through the key buffer takes much less disk space than
     using sorting, but is also much slower.

     If you want a faster repair, set the above variables to about 1/4
     of your available memory.  You can set both variables to big
     values, as only one of the above buffers will be used at a time.

`-s or --silent'
     Silent mode.  Write output only when errors occur. You can use `-s'
     twice (`-ss') to make `myisamchk' very silent.

`-v or --verbose'
     Verbose mode.  Print more information. This can be used with `-d'
     and `-e'. Use `-v' multiple times (`-vv', `-vvv') for more
     verbosity!

`-V or --version'
     Print the `myisamchk' version and exit.

`-w or, --wait'
     Instead of giving an error if the table is locked, wait until the
     table is unlocked before continuing.  Note that if you are running
     `mysqld' on the table with `--skip-external-locking', the table
     can only be locked by another `myisamchk' command.

Check Options for `myisamchk'
.............................

`-c or --check'
     Check table for errors. This is the default operation if you are
     not giving `myisamchk' any options that override this.

`-e or --extend-check'
     Check the table very thoroughly (which is quite slow if you have
     many indexes).  This option should only be used in extreme cases.
     Normally, `myisamchk' or `myisamchk --medium-check' should, in most
     cases, be able to find out if there are any errors in the table.

     If you are using `--extended-check' and have much memory, you
     should increase the value of `key_buffer_size' a lot!

`-F or --fast'
     Check only tables that haven't been closed properly.

`-C or --check-only-changed'
     Check only tables that have changed since the last check.

`-f or --force'
     Restart `myisamchk' with `-r' (repair) on the table, if
     `myisamchk' finds any errors in the table.

`-i or --information'
     Print informational statistics about the table that is checked.

`-m or --medium-check'
     Faster than extended-check, but only finds 99.99% of all errors.
     Should, however, be good enough for most cases.

`-U or --update-state'
     Store in the `.MYI' file when the table was checked and if the
     table crashed.  This should be used to get full benefit of the
     `--check-only-changed' option, but you shouldn't use this option
     if the `mysqld' server is using the table and you are running
     `mysqld' with `--skip-external-locking'.

`-T or --read-only'
     Don't mark table as checked. This is useful if you use `myisamchk'
     to check a table that is in use by some other application that
     doesn't use locking (like `mysqld --skip-external-locking').

Repair Options for myisamchk
............................

The following options are used if you start `myisamchk' with `-r' or
`-o':

`-B or --backup'
     Make a backup of the `.MYD' file as `filename-time.BAK'

`--correct-checksum'
     Correct checksum information for table.

`-D # or --data-file-length=#'
     Max length of datafile (when re-creating datafile when it's
     'full').

`-e or --extend-check'
     Try to recover every possible row from the datafile.  Normally
     this will also find a lot of garbage rows. Don't use this option
     if you are not totally desperate.

`-f or --force'
     Overwrite old temporary files (`table_name.TMD') instead of
     aborting.

`-k # or --keys-used=#'
     If you are using `ISAM', tells the `ISAM' storage engine to update
     only the first `#' indexes.  If you are using `MyISAM', tells
     which keys to use, where each binary bit stands for one key (first
     key is bit 0).  This can be used to get faster inserts!
     Deactivated indexes can be reactivated by using `myisamchk -r'.

`-l or --no-symlinks'
     Do not follow symbolic links. Normally `myisamchk' repairs the
     table a symlink points at.  This option doesn't exist in MySQL 4.0,
     as MySQL 4.0 will not remove symlinks during repair.

`-p or --parallel-recover'
     Uses the same technique as `-r' and `-n', but creates all the keys
     in parallel, in different threads.  This option was added in MySQL
     4.0.2.  *This is alpha code. Use at your own risk!*

`-r or --recover'
     Can fix almost anything except unique keys that aren't unique
     (which is an extremely unlikely error with `ISAM'/`MyISAM' tables).
     If you want to recover a table, this is the option to try first.
     Only if `myisamchk' reports that the table can't be recovered by
     `-r', you should then try `-o'.  (Note that in the unlikely case
     that `-r' fails, the datafile is still intact.)  If you have lots
     of memory, you should increase the size of `sort_buffer_size'!

`-o or --safe-recover'
     Uses an old recovery method (reads through all rows in order and
     updates all index trees based on the found rows); this is an order
     of magnitude slower than `-r', but can handle a couple of very
     unlikely cases that `-r' cannot handle.  This recovery method also
     uses much less disk space than `-r'. Normally one should always
     first repair with `-r', and only if this fails use `-o'.

     If you have lots of memory, you should increase the size of
     `key_buffer_size'!

`-n or --sort-recover'
     Force `myisamchk' to use sorting to resolve the keys even if the
     temporary files should be very big.

`--character-sets-dir=...'
     Directory where character sets are stored.

`--set-character-set=name'
     Change the character set used by the index

`-t or --tmpdir=path'
     Path for storing temporary files. If this is not set, `myisamchk'
     will use the environment variable `TMPDIR' for this.  Starting
     from MySQL 4.1, `tmpdir' can be set to a list of paths separated
     by colon `:' (semicolon `;' on Windows). They will be used in
     round-robin fashion.

`-q or --quick'
     Faster repair by not modifying the datafile. One can give a second
     `-q' to force `myisamchk' to modify the original datafile in case
     of duplicate keys

`-u or --unpack'
     Unpack file packed with myisampack.

Other Options for `myisamchk'
.............................

Other actions that `myisamchk' can do, besides repair and check tables:

`-a or --analyze'
     Analyze the distribution of keys. This improves join performance by
     enabling the join optimizer to better choose in which order it
     should join the tables and which keys it should use: `myisamchk
     --describe --verbose table_name'' or using `SHOW KEYS' in MySQL.

`-d or --description'
     Prints some information about table.

`-A or --set-auto-increment[=value]'
     Force `AUTO_INCREMENT' to start at this or higher value. If no
     value is given, then sets the next `AUTO_INCREMENT' value to the
     highest used value for the auto key + 1.

`-S or --sort-index'
     Sort the index tree blocks in high-low order.  This will optimize
     seeks and will make table scanning by key faster.

`-R or --sort-records=#'
     Sorts records according to an index.  This makes your data much
     more localized and may speed up ranged `SELECT' and `ORDER BY'
     operations on this index. (It may be very slow to do a sort the
     first time!)  To find out a table's index numbers, use `SHOW
     INDEX', which shows a table's indexes in the same order that
     `myisamchk' sees them.  Indexes are numbered beginning with 1.

`myisamchk' Memory Usage
........................

Memory allocation is important when you run `myisamchk'.  `myisamchk'
uses no more memory than you specify with the `-O' options.  If you are
going to use `myisamchk' on very large files, you should first decide
how much memory you want it to use.  The default is to use only about
3M to perform repairs.  By using larger values, you can get `myisamchk'
to operate faster.  For example, if you have more than 32M RAM, you
could use options such as these (in addition to any other options you
might specify):

     shell> myisamchk -O sort=16M -O key=16M -O read=1M -O write=1M ...

Using `-O sort=16M' should probably be enough for most cases.

Be aware that `myisamchk' uses temporary files in `TMPDIR'. If `TMPDIR'
points to a memory filesystem, you may easily get out of memory errors.
If this happens, set `TMPDIR' to point at some directory with more
space and restart `myisamchk'.

When repairing, `myisamchk' will also need a lot of disk space:

   * Double the size of the record file (the original one and a copy).
     This space is not needed if one does a repair with `--quick', as
     in this case only the index file will be re-created.  This space
     is needed on the same disk as the original record file!

   * Space for the new index file that replaces the old one. The old
     index file is truncated at start, so one usually ignore this space.
     This space is needed on the same disk as the original index file!

   * When using `--recover' or `--sort-recover' (but not when using
     `--safe-recover'), you will need space for a sort buffer for:
     `(largest_key + row_pointer_length)*number_of_rows * 2'.  You can
     check the length of the keys and the row_pointer_length with
     `myisamchk -dv table'.  This space is allocated on the temporary
     disk (specified by `TMPDIR' or `--tmpdir=#').

If you have a problem with disk space during repair, you can try to use
`--safe-recover' instead of `--recover'.

Using `myisamchk' for Crash Recovery
....................................

If you run `mysqld' with `--skip-external-locking' (which is the
default on some systems, like Linux), you can't reliably use `myisamchk'
to check a table when `mysqld' is using the same table.  If you can be
sure that no one is accessing the tables through `mysqld' while you run
`myisamchk', you only have to do `mysqladmin flush-tables' before you
start checking the tables.  If you can't guarantee the above, then you
must take down `mysqld' while you check the tables.  If you run
`myisamchk' while `mysqld' is updating the tables, you may get a
warning that a table is corrupt even if it isn't.

If you are not using `--skip-external-locking', you can use `myisamchk'
to check tables at any time.  While you do this, all clients that try
to update the table will wait until `myisamchk' is ready before
continuing.

If you use `myisamchk' to repair or optimize tables, you *must* always
ensure that the `mysqld' server is not using the table (this also
applies if you are using `--skip-external-locking').  If you don't take
down `mysqld' you should at least do a `mysqladmin flush-tables' before
you run `myisamchk'.  Your tables *may be corrupted* if the server and
`myisamchk' access the tables simultaneously.

This section describes how to check for and deal with data corruption
in MySQL databases.  If your tables get corrupted frequently you should
try to find the reason for this! *Note Crashing::.

The `MyISAM' table section contains reason for why a table could be
corrupted. *Note MyISAM table problems::.

When performing crash recovery, it is important to understand that each
table `tbl_name' in a database corresponds to three files in the
database directory:

*File*         *Purpose*
`tbl_name.frm' Table definition
               (form) file
`tbl_name.MYD' Datafile
`tbl_name.MYI' Index file

Each of these three file types is subject to corruption in various
ways, but problems occur most often in datafiles and index files.

`myisamchk' works by creating a copy of the `.MYD' (data) file row by
row. It ends the repair stage by removing the old `.MYD' file and
renaming the new file to the original file name.  If you use `--quick',
`myisamchk' does not create a temporary `.MYD' file, but instead
assumes that the `.MYD' file is correct and only generates a new index
file without touching the `.MYD' file. This is safe, because
`myisamchk' automatically detects if the `.MYD' file is corrupt and
aborts the repair in this case.  You can also give two `--quick'
options to `myisamchk'.  In this case, `myisamchk' does not abort on
some errors (like duplicate key) but instead tries to resolve them by
modifying the `.MYD' file. Normally the use of two `--quick' options is
useful only if you have too little free disk space to perform a normal
repair.  In this case you should at least make a backup before running
`myisamchk'.

How to Check Tables for Errors
..............................

To check a MyISAM table, use the following commands:

`myisamchk tbl_name'
     This finds 99.99% of all errors. What it can't find is corruption
     that involves *only* the datafile (which is very unusual). If you
     want to check a table, you should normally run `myisamchk' without
     options or with either the `-s' or `--silent' option.

`myisamchk -m tbl_name'
     This finds 99.999% of all errors. It checks first all index
     entries for errors and then it reads through all rows. It
     calculates a checksum for all keys in the rows and verifies that
     they checksum matches the checksum for the keys in the index tree.

`myisamchk -e tbl_name'
     This does a complete and thorough check of all data (`-e' means
     "extended check"). It does a check-read of every key for each row
     to verify that they indeed point to the correct row.  This may
     take a long time on a big table with many keys.  `myisamchk' will
     normally stop after the first error it finds. If you want to
     obtain more information, you can add the `--verbose' (`-v')
     option.  This causes `myisamchk' to keep going, up through a
     maximum of 20 errors.  In normal usage, a simple `myisamchk' (with
     no arguments other than the table name) is sufficient.

`myisamchk -e -i tbl_name'
     Like the previous command, but the `-i' option tells `myisamchk' to
     print some informational statistics, too.

How to Repair Tables
....................

In the following section we only talk about using `myisamchk' on
`MyISAM' tables (extensions `.MYI' and `.MYD').  If you are using
`ISAM' tables (extensions `.ISM' and `.ISD'), you should use `isamchk'
instead.

Starting with MySQL Version 3.23.14, you can repair MyISAM tables with
the `REPAIR TABLE' command. *Note REPAIR TABLE::.

The symptoms of a corrupted table include queries that abort
unexpectedly and observable errors such as these:

   * `tbl_name.frm' is locked against change

   * Can't find file `tbl_name.MYI' (Errcode: ###)

   * Unexpected end of file

   * Record file is crashed

   * Got error ### from table handler

     To get more information about the error you can run `perror ###'.
     Here is the most common errors that indicates a problem with the
     table:

          shell> perror 126 127 132 134 135 136 141 144 145
          126 = Index file is crashed / Wrong file format
          127 = Record-file is crashed
          132 = Old database file
          134 = Record was already deleted (or record file crashed)
          135 = No more room in record file
          136 = No more room in index file
          141 = Duplicate unique key or constraint on write or update
          144 = Table is crashed and last repair failed
          145 = Table was marked as crashed and should be repaired

     Note that error 135 (no more room in record file), is not an error
     that can be fixed by a simple repair. In this case you have to do:

          ALTER TABLE table MAX_ROWS=xxx AVG_ROW_LENGTH=yyy;

     You can also use this technique for error 136 (no more room in
     index file).


In the other cases, you must repair your tables. `myisamchk' can
usually detect and fix most problems that occur.

The repair process involves up to four stages, described here. Before
you begin, you should `cd' to the database directory and check the
permissions of the table files. Make sure they are readable by the Unix
user that `mysqld' runs as (and to you, because you need to access the
files you are checking).  If it turns out you need to modify files,
they must also be writable by you.

If you are using MySQL Version 3.23.16 and above, you can (and should)
use the `CHECK' and `REPAIR' commands to check and repair `MyISAM'
tables.  *Note CHECK TABLE::.  *Note REPAIR TABLE::.

The manual section about table maintenance includes the options to
`isamchk'/`myisamchk'.  *Note Table maintenance::.

The following section is for the cases where the above command fails or
if you want to use the extended features that `isamchk'/`myisamchk'
provides.

If you are going to repair a table from the command-line, you must first
take down the `mysqld' server. Note that when you do `mysqladmin
shutdown' on a remote server, the `mysqld' server will still be alive
for a while after `mysqladmin' returns, until all queries are stopped
and all keys have been flushed to disk.

*Stage 1: Checking your tables*

Run `myisamchk *.MYI' or `myisamchk -e *.MYI' if you have more time.
Use the `-s' (silent) option to suppress unnecessary information.

If the `mysqld' server is done you should use the -update option to tell
`myisamchk' to mark the table as 'checked'.

You have to repair only those tables for which `myisamchk' announces an
error.  For such tables, proceed to Stage 2.

If you get weird errors when checking (such as `out of memory' errors),
or if `myisamchk' crashes, go to Stage 3.

*Stage 2: Easy safe repair*

Note: If you want repairing to go much faster, you should add: `-O
sort_buffer=# -O key_buffer=#' (where # is about 1/4 of the available
memory) to all `isamchk/myisamchk' commands.

First, try `myisamchk -r -q tbl_name' (`-r -q' means "quick recovery
mode"). This will attempt to repair the index file without touching the
datafile.  If the datafile contains everything that it should and the
delete links point at the correct locations within the datafile, this
should work, and the table is fixed. Start repairing the next table.
Otherwise, use the following procedure:

  1. Make a backup of the datafile before continuing.

  2. Use `myisamchk -r tbl_name' (`-r' means "recovery mode"). This will
     remove incorrect records and deleted records from the datafile and
     reconstruct the index file.

  3. If the preceding step fails, use `myisamchk --safe-recover
     tbl_name'.  Safe recovery mode uses an old recovery method that
     handles a few cases that regular recovery mode doesn't (but is
     slower).

If you get weird errors when repairing (such as `out of memory'
errors), or if `myisamchk' crashes, go to Stage 3.

*Stage 3: Difficult repair*

You should only reach this stage if the first 16K block in the index
file is destroyed or contains incorrect information, or if the index
file is missing.  In this case, it's necessary to create a new index
file. Do so as follows:

  1. Move the datafile to some safe place.

  2. Use the table description file to create new (empty) data and
     index files:

          shell> mysql db_name
          mysql> SET AUTOCOMMIT=1;
          mysql> TRUNCATE TABLE table_name;
          mysql> quit

     If your SQL version doesn't have `TRUNCATE TABLE', use `DELETE FROM
     table_name' instead.

  3. Copy the old datafile back onto the newly created datafile.
     (Don't just move the old file back onto the new file; you want to
     retain a copy in case something goes wrong.)

Go back to Stage 2.  `myisamchk -r -q' should work now.  (This shouldn't
be an endless loop.)

As of `MySQL' 4.0.2 you can also use `REPAIR ... USE_FRM' which
performs the whole procedure automatically.

*Stage 4: Very difficult repair*

You should reach this stage only if the description file has also
crashed. That should never happen, because the description file isn't
changed after the table is created:

  1. Restore the description file from a backup and go back to Stage 3.
     You can also restore the index file and go back to Stage 2.  In
     the latter case, you should start with `myisamchk -r'.

  2. If you don't have a backup but know exactly how the table was
     created, create a copy of the table in another database.  Remove
     the new datafile, then move the description and index files from
     the other database to your crashed database.  This gives you new
     description and index files, but leaves the datafile alone.  Go
     back to Stage 2 and attempt to reconstruct the index file.

Table Optimization
..................

To coalesce fragmented records and eliminate wasted space resulting from
deleting or updating records, run `myisamchk' in recovery mode:

     shell> myisamchk -r tbl_name

You can optimize a table in the same way using the SQL `OPTIMIZE TABLE'
statement.  `OPTIMIZE TABLE' does a repair of the table and a key
analysis, and also sorts the index tree to give faster key lookups.
There is also no possibility of unwanted interaction between a utility
and the server, because the server does all the work when you use
`OPTIMIZE TABLE'. *Note OPTIMIZE TABLE::.

`myisamchk' also has a number of other options you can use to improve
the performance of a table:

   * `-S', `--sort-index'

   * `-R index_num', `--sort-records=index_num'

   * `-a', `--analyze'

For a full description of the option. *Note myisamchk syntax::.

Setting Up a Table Maintenance Regimen
--------------------------------------

Starting with MySQL Version 3.23.13, you can check MyISAM tables with
the `CHECK TABLE' command. *Note CHECK TABLE::.  You can repair tables
with the `REPAIR TABLE' command. *Note REPAIR TABLE::.

It is a good idea to perform table checks on a regular basis rather than
waiting for problems to occur.  For maintenance purposes, you can use
`myisamchk -s' to check tables.  The `-s' option (short for `--silent')
causes `myisamchk' to run in silent mode, printing messages only when
errors occur.

It's also a good idea to check tables when the server starts.  For
example, whenever the machine has done a reboot in the middle of an
update, you usually need to check all the tables that could have been
affected. (This is an "expected crashed table".) You could add a test to
`mysqld_safe' that runs `myisamchk' to check all tables that have been
modified during the last 24 hours if there is an old `.pid' (process
ID) file left after a reboot.  (The `.pid' file is created by `mysqld'
when it starts and removed when it terminates normally.  The presence
of a `.pid' file at system startup time indicates that `mysqld'
terminated abnormally.)

An even better test would be to check any table whose last-modified time
is more recent than that of the `.pid' file.

You should also check your tables regularly during normal system
operation.  At MySQL AB, we run a `cron' job to check all our important
tables once a week, using a line like this in a `crontab' file:

     35 0 * * 0 /path/to/myisamchk --fast --silent /path/to/datadir/*/*.MYI

This prints out information about crashed tables so we can examine and
repair them when needed.

As we haven't had any unexpectedly crashed tables (tables that become
corrupted for reasons other than hardware trouble) for a couple of
years now (this is really true), once a week is more than enough for us.

We recommend that to start with, you execute `myisamchk -s' each night
on all tables that have been updated during the last 24 hours, until
you come to trust MySQL as much as we do.

Normally you don't need to maintain MySQL tables that much.  If you are
changing tables with dynamic size rows (tables with `VARCHAR', `BLOB'
or `TEXT' columns) or have tables with many deleted rows you may want
to from time to time (once a month?) defragment/reclaim space from the
tables.

You can do this by using `OPTIMIZE TABLE' on the tables in question or
if you can take down the `mysqld' server for a while do:

     isamchk -r --silent --sort-index -O sort_buffer_size=16M */*.ISM
     myisamchk -r --silent --sort-index  -O sort_buffer_size=16M */*.MYI

Getting Information About a Table
---------------------------------

To get a description of a table or statistics about it, use the
commands shown here. We explain some of the information in more detail
later:

   * myisamchk -d tbl_name Runs `myisamchk' in "describe mode" to
     produce a description of your table. If you start the MySQL server
     using the `--skip-external-locking' option, `myisamchk' may report
     an error for a table that is updated while it runs.  However,
     because `myisamchk' doesn't change the table in describe mode,
     there isn't any risk of destroying data.

   * myisamchk -d -v tbl_name To produce more information about what
     `myisamchk' is doing, add `-v' to tell it to run in verbose mode.

   * myisamchk -eis tbl_name Shows only the most important information
     from a table. It is slow because it must read the whole table.

   * myisamchk -eiv tbl_name This is like `-eis', but tells you what is
     being done.

Example of `myisamchk -d' output:
     MyISAM file:     company.MYI
     Record format:   Fixed length
     Data records:    1403698  Deleted blocks:         0
     Recordlength:    226

     table description:
     Key Start Len Index   Type
     1   2     8   unique  double
     2   15    10  multip. text packed stripped
     3   219   8   multip. double
     4   63    10  multip. text packed stripped
     5   167   2   multip. unsigned short
     6   177   4   multip. unsigned long
     7   155   4   multip. text
     8   138   4   multip. unsigned long
     9   177   4   multip. unsigned long
         193   1           text

Example of `myisamchk -d -v' output:
     MyISAM file:         company
     Record format:       Fixed length
     File-version:        1
     Creation time:       1999-10-30 12:12:51
     Recover time:        1999-10-31 19:13:01
     Status:              checked
     Data records:           1403698  Deleted blocks:              0
     Datafile parts:         1403698  Deleted data:                0
     Datafilepointer (bytes):      3  Keyfile pointer (bytes):     3
     Max datafile length: 3791650815  Max keyfile length: 4294967294
     Recordlength:               226

     table description:
     Key Start Len Index   Type                  Rec/key     Root Blocksize
     1   2     8   unique  double                      1 15845376      1024
     2   15    10  multip. text packed stripped        2 25062400      1024
     3   219   8   multip. double                     73 40907776      1024
     4   63    10  multip. text packed stripped        5 48097280      1024
     5   167   2   multip. unsigned short           4840 55200768      1024
     6   177   4   multip. unsigned long            1346 65145856      1024
     7   155   4   multip. text                     4995 75090944      1024
     8   138   4   multip. unsigned long              87 85036032      1024
     9   177   4   multip. unsigned long             178 96481280      1024
         193   1           text

Example of `myisamchk -eis' output:
     Checking MyISAM file: company
     Key:  1:  Keyblocks used:  97%  Packed:    0%  Max levels:  4
     Key:  2:  Keyblocks used:  98%  Packed:   50%  Max levels:  4
     Key:  3:  Keyblocks used:  97%  Packed:    0%  Max levels:  4
     Key:  4:  Keyblocks used:  99%  Packed:   60%  Max levels:  3
     Key:  5:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     Key:  6:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     Key:  7:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     Key:  8:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     Key:  9:  Keyblocks used:  98%  Packed:    0%  Max levels:  4
     Total:    Keyblocks used:  98%  Packed:   17%

     Records:          1403698    M.recordlength:     226
     Packed:             0%
     Recordspace used:     100%   Empty space:          0%
     Blocks/Record:   1.00
     Record blocks:    1403698    Delete blocks:        0
     Recorddata:     317235748    Deleted data:         0
     Lost space:             0    Linkdata:             0

     User time 1626.51, System time 232.36
     Maximum resident set size 0, Integral resident set size 0
     Non physical pagefaults 0, Physical pagefaults 627, Swaps 0
     Blocks in 0 out 0, Messages in 0 out 0, Signals 0
     Voluntary context switches 639, Involuntary context switches 28966

Example of `myisamchk -eiv' output:
     Checking MyISAM file: company
     Data records: 1403698   Deleted blocks:       0
     - check file-size
     - check delete-chain
     block_size 1024:
     index  1:
     index  2:
     index  3:
     index  4:
     index  5:
     index  6:
     index  7:
     index  8:
     index  9:
     No recordlinks
     - check index reference
     - check data record references index: 1
     Key:  1:  Keyblocks used:  97%  Packed:    0%  Max levels:  4
     - check data record references index: 2
     Key:  2:  Keyblocks used:  98%  Packed:   50%  Max levels:  4
     - check data record references index: 3
     Key:  3:  Keyblocks used:  97%  Packed:    0%  Max levels:  4
     - check data record references index: 4
     Key:  4:  Keyblocks used:  99%  Packed:   60%  Max levels:  3
     - check data record references index: 5
     Key:  5:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     - check data record references index: 6
     Key:  6:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     - check data record references index: 7
     Key:  7:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     - check data record references index: 8
     Key:  8:  Keyblocks used:  99%  Packed:    0%  Max levels:  3
     - check data record references index: 9
     Key:  9:  Keyblocks used:  98%  Packed:    0%  Max levels:  4
     Total:    Keyblocks used:   9%  Packed:   17%

     - check records and index references
     [LOTS OF ROW NUMBERS DELETED]

     Records:          1403698    M.recordlength:     226   Packed:             0%
     Recordspace used:     100%   Empty space:          0%  Blocks/Record:   1.00
     Record blocks:    1403698    Delete blocks:        0
     Recorddata:     317235748    Deleted data:         0
     Lost space:             0    Linkdata:             0

     User time 1639.63, System time 251.61
     Maximum resident set size 0, Integral resident set size 0
     Non physical pagefaults 0, Physical pagefaults 10580, Swaps 0
     Blocks in 4 out 0, Messages in 0 out 0, Signals 0
     Voluntary context switches 10604, Involuntary context switches 122798

Here are the sizes of the data and index files for the table used in the
preceding examples:

     -rw-rw-r--   1 monty    tcx     317235748 Jan 12 17:30 company.MYD
     -rw-rw-r--   1 davida   tcx      96482304 Jan 12 18:35 company.MYM

Explanations for the types of information `myisamchk' produces are
given here.  The "keyfile" is the index file.  "Record" and "row" are
synonymous:

   * ISAM file Name of the ISAM (index) file.

   * Isam-version Version of ISAM format. Currently always 2.

   * Creation time When the datafile was created.

   * Recover time When the index/datafile was last reconstructed.

   * Data records How many records are in the table.

   * Deleted blocks How many deleted blocks still have reserved space.
     You can optimize your table to minimise this space.  *Note
     Optimisation::.

   * Data file: Parts For dynamic record format, this indicates how
     many data blocks there are. For an optimized table without
     fragmented records, this is the same as `Data records'.

   * Deleted data How many bytes of non-reclaimed deleted data there
     are.  You can optimize your table to minimise this space.  *Note
     Optimisation::.

   * Data file pointer The size of the datafile pointer, in bytes. It
     is usually 2, 3, 4, or 5 bytes. Most tables manage with 2 bytes,
     but this cannot be controlled from MySQL yet. For fixed tables,
     this is a record address. For dynamic tables, this is a byte
     address.

   * Keyfile pointer The size of the index file pointer, in bytes. It
     is usually 1, 2, or 3 bytes. Most tables manage with 2 bytes, but
     this is calculated automatically by MySQL. It is always a block
     address.

   * Max datafile length How long the table's datafile (`.MYD' file)
     can become, in bytes.

   * Max keyfile length How long the table's key file (`.MYI' file) can
     become, in bytes.

   * Recordlength How much space each record takes, in bytes.

   * Record format The format used to store table rows.  The preceding
     examples use `Fixed length'.  Other possible values are
     `Compressed' and `Packed'.

   * table description A list of all keys in the table. For each key,
     some low-level information is presented:

        - Key This key's number.

        - Start Where in the record this index part starts.

        - Len How long this index part is. For packed numbers, this
          should always be the full length of the column. For strings,
          it may be shorter than the full length of the indexed column,
          because you can index a prefix of a string column.

        - Index `unique' or `multip.' (multiple). Indicates whether one
          value can exist multiple times in this index.

        - Type What data-type this index part has. This is an ISAM
          data-type with the options `packed', `stripped' or `empty'.

        - Root Address of the root index block.

        - Blocksize The size of each index block. By default this is
          1024, but the value may be changed at compile time.

        - Rec/key This is a statistical value used by the optimizer. It
          tells how many records there are per value for this key. A
          unique key always has a value of 1. This may be updated after
          a table is loaded (or greatly changed) with `myisamchk -a'.
          If this is not updated at all, a default value of 30 is given.

   * In the first example above, the 9th key is a multi-part key with
     two parts.

   * Keyblocks used What percentage of the keyblocks are used. Because
     the table used in the examples had just been reorganized with
     `myisamchk', the values are very high (very near the theoretical
     maximum).

   * Packed MySQL tries to pack keys with a common suffix. This can
     only be used for `CHAR'/`VARCHAR'/`DECIMAL' keys. For long strings
     like names, this can significantly reduce the space used. In the
     third example above, the 4th key is 10 characters long and a 60%
     reduction in space is achieved.

   * Max levels How deep the B-tree for this key is. Large tables with
     long keys get high values.

   * Records How many rows are in the table.

   * M.recordlength The average record length. For tables with
     fixed-length records, this is the exact record length.

   * Packed MySQL strips spaces from the end of strings. The `Packed'
     value indicates the percentage of savings achieved by doing this.

   * Recordspace used What percentage of the datafile is used.

   * Empty space What percentage of the datafile is unused.

   * Blocks/Record Average number of blocks per record (that is, how
     many links a fragmented record is composed of). This is always 1.0
     for fixed-format tables. This value should stay as close to 1.0 as
     possible. If it gets too big, you can reorganize the table with
     `myisamchk'.  *Note Optimisation::.

   * Recordblocks How many blocks (links) are used. For fixed format,
     this is the same as the number of records.

   * Deleteblocks How many blocks (links) are deleted.

   * Recorddata How many bytes in the datafile are used.

   * Deleted data How many bytes in the datafile are deleted (unused).

   * Lost space If a record is updated to a shorter length, some space
     is lost. This is the sum of all such losses, in bytes.

   * Linkdata When the dynamic table format is used, record fragments
     are linked with pointers (4 to 7 bytes each). `Linkdata' is the
     sum of the amount of storage used by all such pointers.

If a table has been compressed with `myisampack', `myisamchk -d' prints
additional information about each table column.  See *Note
`myisampack': myisampack, for an example of this information and a
description of what it means.

MySQL Localization and International Usage
==========================================

The Character Set Used for Data and Sorting
-------------------------------------------

By default, MySQL uses the ISO-8859-1 (Latin1) character set with
sorting according to Swedish/Finnish rules. These defaults are suitable
for the USA and most of western Europe.

All standard MySQL binaries are compiled with
`--with-extra-charsets=complex'.  This will add code to all standard
programs to be able to handle `latin1' and all multi-byte character
sets within the binary. Other character sets will be loaded from a
character-set definition file when needed.

The character set determines what characters are allowed in names and
how strings are sorted by the `ORDER BY' and `GROUP BY' clauses of the
`SELECT' statement.

You can change the character set with the `--default-character-set'
option when you start the server.  The character sets available depend
on the `--with-charset=charset' and `--with-extra-charsets=
list-of-charset | complex | all | none' options to `configure', and the
character set configuration files listed in `SHAREDIR/charsets/Index'.
*Note configure options::.

If you change the character set when running MySQL (which may also
change the sort order), you must run `myisamchk -r -q
--set-character-set=charset' on all tables. Otherwise, your indexes may
not be ordered correctly.

When a client connects to a MySQL server, the server sends the default
character set in use to the client.  The client will switch to use this
character set for this connection.

One should use `mysql_real_escape_string()' when escaping strings for
an SQL query.  `mysql_real_escape_string()' is identical to the old
`mysql_escape_string()' function, except that it takes the `MYSQL'
connection handle as the first parameter.

If the client is compiled with different paths than where the server is
installed and the user who configured MySQL didn't include all
character sets in the MySQL binary, one must specify for the client
where it can find the additional character sets it will need if the
server runs with a different character set than the client.

One can specify this by putting in a MySQL option file:

     [client]
     character-sets-dir=/usr/local/mysql/share/mysql/charsets

where the path points to the directory in which the dynamic MySQL
character sets are stored.

One can force the client to use specific character set by specifying:

     [client]
     default-character-set=character-set-name

but normally this is never needed.

German character set
....................

To get German sorting order, you should start `mysqld' with
`--default-character-set=latin1_de'.  This will give you the following
characteristics.

When sorting and comparing strings, the following mapping is done on the
strings before doing the comparison:

     a"  ->  ae
     o"  ->  oe
     u"  ->  ue
     ss  ->  ss

All accented characters, are converted to their un-accented uppercase
counterpart.  All letters are converted to uppercase.

When comparing strings with `LIKE' the one -> two character mapping is
not done. All letters are converted to uppercase. Accent are removed
from all letters except: `U"', `u"', `O"', `o"', `A"' and `a"'.

Non-English Error Messages
--------------------------

`mysqld' can issue error messages in the following languages: Czech,
Danish, Dutch, English (the default), Estonian, French, German, Greek,
Hungarian, Italian, Japanese, Korean, Norwegian, Norwegian-ny, Polish,
Portuguese, Romanian, Russian, Slovak, Spanish, and Swedish.

To start `mysqld' with a particular language, use either the
`--language=lang' or `-L lang' options. For example:

     shell> mysqld --language=swedish

or:

     shell> mysqld --language=/usr/local/share/swedish

Note that all language names are specified in lowercase.

The language files are located (by default) in
`MYSQL_BASE_DIR/share/LANGUAGE/'.

To update the error message file, you should edit the `errmsg.txt' file
and execute the following command to generate the `errmsg.sys' file:

     shell> comp_err errmsg.txt errmsg.sys

If you upgrade to a newer version of MySQL, remember to repeat your
changes with the new `errmsg.txt' file.

Adding a New Character Set
--------------------------

To add another character set to MySQL, use the following procedure.

Decide if the set is simple or complex.  If the character set does not
need to use special string collating routines for sorting and does not
need multi-byte character support, it is simple.  If it needs either of
those features, it is complex.

For example, `latin1' and `danish' are simple charactersets while
`big5' or `czech' are complex character sets.

In the following section, we have assumed that you name your character
set `MYSET'.

For a simple character set do the following:

  1. Add MYSET to the end of the `sql/share/charsets/Index' file Assign
     a unique number to it.

  2. Create the file `sql/share/charsets/MYSET.conf'.  (You can use
     `sql/share/charsets/latin1.conf' as a base for this.)

     The syntax for the file is very simple:

        * Comments start with a '#' character and proceed to the end of
          the line.

        * Words are separated by arbitrary amounts of whitespace.

        * When defining the character set, every word must be a number
          in hexadecimal format

        * The `ctype' array takes up the first 257 words. The
          `to_lower[]', `to_upper[]' and `sort_order[]' arrays take up
          256 words each after that.

     *Note Character arrays::.

  3. Add the character set name to the `CHARSETS_AVAILABLE' and
     `COMPILED_CHARSETS' lists in `configure.in'.

  4. Reconfigure, recompile, and test.


For a complex character set do the following:

  1. Create the file `strings/ctype-MYSET.c' in the MySQL source
     distribution.

  2. Add MYSET to the end of the `sql/share/charsets/Index' file.
     Assign a unique number to it.

  3. Look at one of the existing `ctype-*.c' files to see what needs to
     be defined, for example `strings/ctype-big5.c'. Note that the
     arrays in your file must have names like `ctype_MYSET',
     `to_lower_MYSET', and so on.  This corresponds to the arrays in
     the simple character set. *Note Character arrays::.

  4. Near the top of the file, place a special comment like this:

          /*
           * This comment is parsed by configure to create ctype.c,
           * so don't change it unless you know what you are doing.
           *
           * .configure. number_MYSET=MYNUMBER
           * .configure. strxfrm_multiply_MYSET=N
           * .configure. mbmaxlen_MYSET=N
           */

     The `configure' program uses this comment to include the character
     set into the MySQL library automatically.

     The strxfrm_multiply and mbmaxlen lines will be explained in the
     following sections.  Only include these if you need the string
     collating functions or the multi-byte character set functions,
     respectively.

  5. You should then create some of the following functions:

        * `my_strncoll_MYSET()'

        * `my_strcoll_MYSET()'

        * `my_strxfrm_MYSET()'

        * `my_like_range_MYSET()'

     *Note String collating::.

  6. Add the character set name to the `CHARSETS_AVAILABLE' and
     `COMPILED_CHARSETS' lists in `configure.in'.

  7. Reconfigure, recompile, and test.

The file `sql/share/charsets/README' includes some more instructions.

If you want to have the character set included in the MySQL
distribution, mail a patch to the MySQL internals mailing list.  *Note
Mailing-list::.

The Character Definition Arrays
-------------------------------

`to_lower[]' and `to_upper[]' are simple arrays that hold the lowercase
and uppercase characters corresponding to each member of the character
set.  For example:

     to_lower['A'] should contain 'a'
     to_upper['a'] should contain 'A'

`sort_order[]' is a map indicating how characters should be ordered for
comparison and sorting purposes. Quite often (but not for all character
sets) this is the same as `to_upper[]' (which means sorting will be
case-insensitive). MySQL will sort characters based on the value of
`sort_order[character]'.  For more complicated sorting rules, see the
discussion of string collating below. *Note String collating::.

`ctype[]' is an array of bit values, with one element for one character.
(Note that `to_lower[]', `to_upper[]', and `sort_order[]' are indexed
by character value, but `ctype[]' is indexed by character value + 1.
This is an old legacy to be able to handle `EOF'.)

You can find the following bitmask definitions in `m_ctype.h':

     #define _U      01      /* Uppercase */
     #define _L      02      /* Lowercase */
     #define _N      04      /* Numeral (digit) */
     #define _S      010     /* Spacing character */
     #define _P      020     /* Punctuation */
     #define _C      040     /* Control character */
     #define _B      0100    /* Blank */
     #define _X      0200    /* heXadecimal digit */

The `ctype[]' entry for each character should be the union of the
applicable bitmask values that describe the character.  For example,
`'A'' is an uppercase character (`_U') as well as a hexadecimal digit
(`_X'), so `ctype['A'+1]' should contain the value:

     _U + _X = 01 + 0200 = 0201

String Collating Support
------------------------

If the sorting rules for your language are too complex to be handled
with the simple `sort_order[]' table, you need to use the string
collating functions.

Right now the best documentation on this is the character sets that are
already implemented.  Look at the `big5', `czech', `gbk', `sjis', and
`tis160' character sets for examples.

You must specify the `strxfrm_multiply_MYSET=N' value in the special
comment at the top of the file.  `N' should be set to the maximum ratio
the strings may grow during `my_strxfrm_MYSET' (it must be a positive
integer).

Multi-byte Character Support
----------------------------

If your want to add support for a new character set that includes
multi-byte characters, you need to use the multi-byte character
functions.

Right now the best documentation on this is the character sets that are
already implemented.  Look at the `euc_kr', `gb2312', `gbk', `sjis',
and `ujis' character sets for examples. These are implemented in the
`ctype-'charset'.c' files in the `strings' directory.

You must specify the `mbmaxlen_MYSET=N' value in the special comment at
the top of the source file.  `N' should be set to the size in bytes of
the largest character in the set.

Problems With Character Sets
----------------------------

If you try to use a character set that is not compiled into your binary,
you can run into a couple of different problems:

   * Your program has a wrong path to where the character sets are
     stored.  (Default `/usr/local/mysql/share/mysql/charsets').  This
     can be fixed by using the `--character-sets-dir' option to the
     program in question.

   * The character set is a multi-byte character set that can't be
     loaded dynamically.  In this case you have to recompile the
     program with the support for the character set.

   * The character set is a dynamic character set, but you don't have a
     configure file for it.  In this case you should install the
     configure file for the character set from a new MySQL distribution.

   * Your `Index' file doesn't contain the name for the character set.

          ERROR 1105: File '/usr/local/share/mysql/charsets/?.conf' not found
          (Errcode: 2)

     In this case you should either get a new `Index' file or add by
     hand the name of any missing character sets.

For `MyISAM' tables, you can check the character set name and number
for a table with `myisamchk -dvv table_name'.

The MySQL Log Files
===================

MySQL has several different log files that can help you find out what's
going on inside `mysqld':

*Log file*     *Description*
The error log  Problems encountering starting, running or stopping
               `mysqld'.
The isam log   Logs all changes to the ISAM tables. Used only for
               debugging the isam code.
The query log  Established connections and executed queries.
The update     Deprecated: Stores all statements that changes data
log
The binary     Stores all statements that changes something. Used also
log            for replication
The slow log   Stores all queries that took more than `long_query_time'
               seconds to execute or didn't use indexes.

All logs can be found in the `mysqld' data directory.  You can force
`mysqld' to reopen the log files (or in some cases switch to a new log)
by executing `FLUSH LOGS'. *Note FLUSH::.

The Error Log
-------------

The error log file contains information indicating when `mysqld' was
started and stopped and also any critical errors found when running.

If `mysqld' dies unexpectedly and `mysqld_safe' needs to restart
`mysqld', `mysqld_safe' will write a `restarted mysqld' row in this
file.  This log also holds a warning if `mysqld' notices a table that
needs to be automatically checked or repaired.

On some operating systems, the error log will contain a stack trace for
where `mysqld' died. This can be used to find out where `mysqld' died.
*Note Using stack trace::.

Beginning with MySQL 4.0.10 you can specify where `mysqld' stores the
error log file with the option `--log-error[=filename]'. If no file
name is given `mysqld' will use `mysql-data-dir/'hostname'.err' on Unix
and `\mysql\data\mysql.err' on Windows.  If you execute `flush logs'
the old file will be prefixed with `--old' and `mysqld' will create a
new empty log file.

In older MySQL versions the error log handling was done by
`mysqld_safe' which redirected the error file to `'hostname'.err'.  One
could change this file name with the option `--err-log=filename'.

If you don't specify `--log-error' or if you use the `--console' option
the errors will be written to stderr (the terminal).

On Windows, the output is always written to the `.err' file if
`--console' is not given.

The General Query Log
---------------------

If you want to know what happens within `mysqld', you should start it
with `--log[=file]'.  This will log all connections and queries to the
log file (by default named `'hostname'.log').  This log can be very
useful when you suspect an error in a client and want to know exactly
what `mysqld' thought the client sent to it.

Older versions of the `mysql.server' script (from MySQL 3.23.4 to
3.23.8) pass `safe_mysqld' a `--log' option (enable general query log).
If you need better performance when you start using MySQL in a
production environment, you can remove the `--log' option from
`mysql.server' or change it to `--log-bin'. *Note Binary log::.

The entries in this log are written as `mysqld' receives the questions.
This may be different from the order in which the statements are
executed.  This is in contrast to the update log and the binary log
which are written after the query is executed, but before any locks are
released.

The Update Log
--------------

*Note:* The update log has been deprecated and replaced by the binary
log. *Note Binary log::.  The binary log can do anything the old update
log could do, and more. *The update log is removed starting from MySQL
5.0.0*.

When started with the `--log-update[=file_name]' option, `mysqld'
writes a log file containing all SQL commands that update data. If no
filename is given, it defaults to the name of the host machine. If a
filename is given, but it doesn't contain a path, the file is written
in the data directory. If `file_name' doesn't have an extension,
`mysqld' will create log file names like so: `file_name.###', where
`###' is a number that is incremented each time you execute `mysqladmin
refresh', execute `mysqladmin flush-logs', execute the `FLUSH LOGS'
statement, or restart the server.

*Note:* For the above scheme to work, you must not create your own
files with the same filename as the update log + some extensions that
may be regarded as a number, in the directory used by the update log!

If you use the `--log' or `-l' options, `mysqld' writes a general log
with a filename of `hostname.log', and restarts and refreshes do not
cause a new log file to be generated (although it is closed and
reopened). In this case you can copy it (on Unix) by doing:

     mv hostname.log hostname-old.log
     mysqladmin flush-logs
     cp hostname-old.log to-backup-directory
     rm hostname-old.log

Update logging is smart because it logs only statements that really
update data. So an `UPDATE' or a `DELETE' with a `WHERE' that finds no
rows is not written to the log. It even skips `UPDATE' statements that
set a column to the value it already has.

The update logging is done immediately after a query completes but
before any locks are released or any commit is done. This ensures that
the log will be logged in the execution order.

If you want to update a database from update log files, you could do the
following (assuming your update logs have names of the form
`file_name.###'):

     shell> ls -1 -t -r file_name.[0-9]* | xargs cat | mysql

`ls' is used to get all the log files in the right order.

This can be useful if you have to revert to backup files after a crash
and you want to redo the updates that occurred between the time of the
backup and the crash.

The Binary Log
--------------

The binary log has replaced the old update log. The update log is
removed starting from MySQL 5.0. The binary log contains all
information that is available in the update log in a more efficient
format and in a manner that is transactionally safe.

The binary log, like the old update log, only logs statements that
really update data. So an `UPDATE' or a `DELETE' with a `WHERE' that
finds no rows is not written to the log. It even skips `UPDATE'
statements that set a column to the value it already has.

The primary purpose of the binary log is to be able to update the
database during a restore operation as fully as possible, as the binary
log would contain all updates done after a backup was made.

The binary log is also used when you are replicating a slave from a
master.  *Note Replication::.

The binary log also contains information about how long each query took
that updated the database.  It doesn't contain queries that don't modify
any data.  If you want to log all queries (for example to find a problem
query) you should use the general query log. *Note Query log::.

When started with the `--log-bin[=file_name]' option, `mysqld' writes a
log file containing all SQL commands that update data. If no file name
is given, it defaults to the name of the host machine followed by
`-bin'. If file name is given, but it doesn't contain a path, the file
is written in the data directory.

If you supply an extension to `--log-bin=filename.extension', the
extension will be silenty removed.

To the binary log filename `mysqld' will append an extension that is a
number that is incremented each time you execute `mysqladmin refresh',
execute `mysqladmin flush-logs', execute the `FLUSH LOGS' statement or
restart the server. A new binary log will also automatically be created
when the current one's size reaches `max_binlog_size'. Note if you are
using transactions: a transaction is written in one chunk to the binary
log, hence it is never split between several binary logs. Therefore, if
you have big transactions, you may see binlogs bigger than
`max_binlog_size'.

You can delete all binary log files with the `RESET MASTER' command
(*note `RESET': RESET.), or only some of them with `PURGE MASTER LOGS'
(*note Replication Master SQL::).

You can use the following options to `mysqld' to affect what is logged
to the binary log (please make sure to read the notes which follow this
table):

*Option*                    *Description*
`binlog-do-db=database_name' Tells the master that it should log updates
                            to the binary log if the current database
                            (that is, the one selected by `USE')
                            database is 'database_name'. All others
                            databases which are not explicitly mentioned
                            are ignored.  Note that if you use this you
                            should ensure that you only do updates in
                            the current database.  (Example:
                            `binlog-do-db=some_database')

                            Example of what does not work as you could
                            expect it: if the server is started with
                            `binlog-do-db=sales', and you do `USE
                            prices; UPDATE sales.january SET
                            amount=amount+1000;', this query will not be
                            written into the binary log.
`binlog-ignore-db=database_name' Tells the master that updates where the
                            current database (that is, the one selected
                            by `USE') is 'database_name' should not be
                            stored in the binary log.  Note that if you
                            use this you should ensure that you only do
                            updates in the current database.  (Example:
                            `binlog-ignore-db=some_database')

                            Example of what does not work as you could
                            expect it: if the server is started with
                            `binlog-ignore-db=sales', and you do `USE
                            prices; UPDATE sales.january SET
                            amount=amount+1000;', this query will be
                            written into the binary log.

The rules are evaluated in the following order, to decide if the query
should be written to the binary log or not:
  1. Are there `binlog-do-db' or `binlog-ignore-db' rules?
        * No: write the query to the binlog and exit.

        * Yes: go to step below.

  2. So there are some rules (`binlog-do-db' or `binlog-ignore-db' or
     both). Is there a current database (has any database been selected
     by `USE'?)?
        * No: do *NOT* write the query, and exit.

        * Yes: go to step below.

  3. There is a current database. Are there some `binlog-do-db' rules?
        * Yes: Does the current database match any of the `binlog-do-db'
          rules?
             * Yes: write the query and exit.

             * No: do *NOT* write the query, and exit.

        * No: go to step below.

  4. There are some `binlog-ignore-db' rules.  Does the current
     database match any of the `binlog-ignore-db' rules?
        * Yes: do not write the query, and exit.

        * No: write the query and exit.

So for example, a slave running with only `binlog-do-db=sales' will not
write to the binlog any query whose current database is different from
`sales' (in other words, `binlog-do-db' can sometimes mean "ignore
other databases").

To be able to know which different binary log files have been used,
`mysqld' will also create a binary log index file that contains the
name of all used binary log files. By default this has the same name as
the binary log file, with the extension `'.index''.  You can change the
name of the binary log index file with the `--log-bin-index=[filename]'
option.  You should not manually edit this file while `mysqld' is
running; doing this would confuse `mysqld'.

If you are using replication, you should not delete old binary log
files until you are sure that no slave will ever need to use them.  One
way to do this is to do `mysqladmin flush-logs' once a day and then
remove any logs that are more than 3 days old. You can remove them
manually, or preferably using `PURGE MASTER LOGS' (*note Replication
Master SQL::) which will also safely update the binary log index file
for you  (and which can take a date argument since MySQL 4.1)

A connection with the `SUPER' privilege can disable the binary logging
of its queries using `SET SQL_LOG_BIN=0'. *Note Replication Master
SQL::.

You can examine the binary log file with the `mysqlbinlog' utility.
For example, you can update a MySQL server from the binary log as
follows:

     shell> mysqlbinlog log-file | mysql -h server_name

See *Note mysqlbinlog:: for more information on the `mysqlbinlog'
utility and how to use it.

If you are using `BEGIN [WORK]' or `SET AUTOCOMMIT=0', you must use the
MySQL binary log for backups instead of the old update log, which will
is removed in MySQL 5.0.0.

The binary logging is done immediately after a query completes but
before any locks are released or any commit is done. This ensures that
the log will be logged in the execution order.

Updates to non-transactional tables are stored in the binary log
immediately after execution.  For transactional tables such as `BDB' or
`InnoDB' tables, all updates (`UPDATE', `DELETE' or `INSERT') that
change tables are cached until a `COMMIT' command is sent to the
server. At this point `mysqld' writes the whole transaction to the
binary log before the `COMMIT' is executed.  Every thread will, on
start, allocate a buffer of `binlog_cache_size' to buffer queries.  If
a query is bigger than this, the thread will open a temporary file to
store the transaction.  The temporary file will be deleted when the
thread ends.

The `max_binlog_cache_size' (default 4G) can be used to restrict the
total size used to cache a multi-query transaction.  If a transaction is
bigger than this it will fail and roll back.

If you are using the update or binary log, concurrent inserts will be
converted to normal inserts when using `CREATE ... SELECT' or `INSERT
... SELECT'.  This is to ensure that you can re-create an exact copy of
your tables by applying the log on a backup.

The binary log format is different in versions 3.23, 4.0, and 5.0.0.
Those format changes were required to enhance replication.  MySQL 4.1
has the same binary log format as 4.0.

The Slow Query Log
------------------

When started with the `--log-slow-queries[=file_name]' option, `mysqld'
writes a log file containing all SQL commands that took more than
`long_query_time' seconds to execute. The time to get the initial table
locks are not counted as execution time.

The slow query log is logged after the query is executed and after all
locks has been released. This may be different from the order in which
the statements are executed.

If no file name is given, it defaults to the name of the host machine
suffixed with `-slow.log'. If a filename is given, but doesn't contain
a path, the file is written in the data directory.

The slow query log can be used to find queries that take a long time to
execute and are thus candidates for optimization. With a large log, that
can become a difficult task. You can pipe the slow query log through the
`mysqldumpslow' command to get a summary of the queries which appear in
the log.

You are using `--log-long-format' then also queries that are not using
indexes are printed. *Note Server options::.

Log File Maintenance
--------------------

The MySQL Server can create a number of different log files, which make
it easy to see what is going on. *Note Log Files::. However, you must
clean up these files regularly, to ensure that the logs don't take up
too much disk space.

When using MySQL with log files, you will want to remove/backup old log
files from time to time and tell MySQL to start logging to new files.
*Note Backup::.

On a Linux (`Red Hat') installation, you can use the `mysql-log-rotate'
script for this. If you installed MySQL from an RPM distribution, the
script should have been installed automatically.  Note that you should
be careful with this script if you are using the binary log for
replication!

On other systems you must install a short script yourself that you
start from `cron' to handle log files.

You can force MySQL to start using new log files by using `mysqladmin
flush-logs' or by using the SQL command `FLUSH LOGS'.  If you are using
MySQL Version 3.21, you must use `mysqladmin refresh'.

The above command does the following:

   * If standard logging (`--log') or slow query logging
     (`--log-slow-queries') is used, closes and reopens the log file
     (`mysql.log' and ``hostname`-slow.log' as default).

   * If update logging (`--log-update') is used, closes the update log
     and opens a new log file with a higher sequence number.

If you are using only an update log, you only have to flush the logs
and then move away the old update log files to a backup.  If you are
using the normal logging, you can do something like:

     shell> cd mysql-data-directory
     shell> mv mysql.log mysql.old
     shell> mysqladmin flush-logs

and then take a backup and remove `mysql.old'.

Running Multiple MySQL Servers on the Same Machine
==================================================

In some cases you might want to run multiple `mysqld' servers on the
same machine.  You might want to test a new MySQL release while leaving
your existing production setup undisturbed.  Or you may want to give
different users access to different `mysqld' servers that they manage
themselves.  (For example, you might be an Internet service provider
that wants to provide independent MySQL installations for different
customers.)

To run multiple servers on a single machine, each server must have
unique values for several operating parameters. These can be set on the
command line or in option files.  *Note Program Options::.

At least the following options must be different for each server:

   * `--port=port_num'

   * `--socket=path'

   * `--shared-memory-base-name=name' (Windows only; new in MySQL 4.1)

   * `--pid-file=path' (Unix only)

`--port' controls the port number for TCP/IP connections.  `--socket'
controls the socket file path on Unix and the name of the named pipe on
Windows. (It's necessary to specify distinct pipe names on Windows only
for those servers that support named pipe connections.)
`--shared-memory-base-name' designates the shared memory name used by a
Windows server to allow clients to connect via shared memory.
`--pid-file' indicates the name of the file in which a Unix server
writes its process ID.

If you use the following options, they must be different for each
server:

   * `--log=path'

   * `--log-bin=path'

   * `--log-update=path'

   * `--log-error=path'

   * `--log-isam=path'

   * `--bdb-logdir=path'

If you want more performance, you can also specify the following options
differently for each server, to spread load between several physical
disks:

   * `--tmpdir=path'

   * `--bdb-tmpdir=path'

Having different temporary directories like above is also recommended
because it will be easier for you in case you want to know to which
MySQL server a certain temporary file belongs.

Generally, each server should also use a different data directory,
which is specified using the `--datadir=path' option.

*Warning:* Normally you should never have two servers that update data
in the same databases!  This may lead to unpleasant surprises if your
operating system doesn't support fault-free system locking!  If
(despite this warning) you run multiple servers using the same data
directory and they have logging enabled, you must use the appropriate
options to specify log file names that are unique to each server.
Otherwise, the servers will try to log to the same files.

This warning against sharing a data directory among servers also applies
in an NFS environment.  Allowing multiple MySQL servers to access a
common data directory over NFS is a *bad idea*!

   * The primary problem is that NFS will become the speed bottleneck.
     It is not meant for such use.

   * Another risk with NFS is that you will have to come up with a way
     to make sure that two or more servers do not interfere with each
     other.  Usually NFS file locking is handled by the `lockd' daemon,
     but at the moment there is no platform that will perform locking
     100% reliably in every situation.


Make it easy for yourself: Forget about sharing a data directory among
servers over NFS. A better solution is to have one computer that
contains several CPUs and use an operating system that handles threads
efficiently.

If you have multiple MySQL installations in different locations,
normally you can specify the base installation directory for each
server with the `--basedir=path' option to cause each server to use a
different data directory, log files, and PID file. (The defaults for
all these values are determined relative to the base directory.) In
that case, the only other options you need to specify are the
`--socket' and `--port' options.  For example, suppose you install
different versions of MySQL using `.tar' file binary distributions.
These will install in different locations, so you can start the server
for each installation using the command `./bin/mysqld_safe' under its
corresponding base directory.  `mysqld_safe' will determine the proper
`--basedir' option to pass to `mysqld', and you need specify only the
`--socket' and `--port' options to `mysqld_safe'.

As discussed in the following sections, it is possible to start
additional servers by setting environment variables or by specifying
appropriate command-line options.  However, if you need to run multiple
servers on a more permanent basis, it will be more convenient to use
option files to specify for each server those option values that must
be unique to it.

Running Multiple Servers on Windows
-----------------------------------

You can run multiple servers on Windows by starting them manually from
the command line, each with appropriate operating parameters. On
Windows NT-based systems, you also have the option of installing
several servers as Windows services and running them that way. General
instructions for running MySQL servers from the command line or as
services are given in *Note Windows installation::. This section
describes how to make sure you start each server with different values
for those startup options that must be unique per server, such as the
data directory.  (These options are described in *Note Multiple
servers::.)

Starting Multiple Windows Servers at the Command Line
.....................................................

To start multiple servers manually from the command line, you can
specify the appropriate options on the command line or in an option
file. It's more convenient to place the options in an option file, but
it's necessary to make sure that each server gets its own set of
options. To do this, create an option file for each server and tell the
server the filename with a `--defaults-file' option when you run it.

Suppose you want to run `mysqld' on port 3307 with a data directory of
`C:\mydata1', and `mysqld-max' on port 3308 with a data directory of
`C:\mydata2'. To accomplish this, create two option files. For example,
create one file named `C:\my-opts1.cnf' that looks like this:

     [mysqld]
     datadir = C:/mydata1
     port = 3307

Create a second file named `C:\my-opts2.cnf' that looks like this:

     [mysqld]
     datadir = C:/mydata2
     port = 3308

Then start each server with its own option file:

     shell> mysqld --defaults-file=C:\my-opts1.cnf
     shell> mysqld-max --defaults-file=C:\my-opts2.cnf

(On NT, the servers will start in the foreground, so you'll need to
issue those two commands in separate console windows.)

To shut down the servers, you must connect to the appropriate port
number:

     shell> mysqladmin --port=3307 shutdown
     shell> mysqladmin --port=3308 shutdown

Servers configured as just described will allow clients to connect over
TCP/IP.  If you also want to allow named pipe connections, use the
`mysqld-nt' or `mysqld-max-nt' servers and specify options that enable
the named pipe and specify its name. (Each server that supports named
pipe connections must use a unique pipe name.)  For example, the
`C:\my-opts1.cnf' file might be written like this:

     [mysqld]
     datadir = C:/mydata1
     port = 3307
     enable-named-pipe
     socket = mypipe1

Then start the server this way:

     shell> mysqld-nt --defaults-file=C:\my-opts1.cnf

`C:\my-opts2.cnf' would be modified similarly for use by the second
server.

Starting Multiple Windows Servers as Services
.............................................

On NT-based systems, a MySQL server can be run as a Windows service. The
procedures for installing, controlling, and removing a single MySQL
service are described in *Note NT start::.

As of MySQL 4.0.2, you can install multiple servers as services.  In
this case, you must make sure that each server uses a different service
name in addition to all the other parameters that must be unique per
server.

For the following instructions, assume that you want to run the
`mysqld-nt' server from two different versions of MySQL that are
installed at `C:\mysql-4.0.8' and `C:\mysql-4.0.17', respectively.
(This might be the case if you're running 4.0.8 as your production
server, but want to test 4.0.17 before upgrading to it.)

The following principles are relevant when installing a MySQL service
with the `--install' option:

   * If you specify no service name, the server uses the default
     service name of `MySQL' and the server reads options from the
     `[mysqld]' group in the standard option files.

   * If you specify a service name after the `--install' option, the
     server ignores the `[mysqld]' option group and instead reads
     options from the group that has the same name as the service. The
     server reads options from the standard option files.

   * If you specify a `--defaults-file' option after the service name,
     the server ignores the standard option files and reads options
     only from the `[mysqld]' group of the named file.


These principles also apply if you install a server using the
`--install-manual' option.

Based on the preceding information, you have several ways to set up
multiple services.  The following instructions describe some examples.
Before trying any of them, be sure you shut down and remove any
existing MySQL services first.

   * Specify the options for all services in one of the standard option
     files.  To do this, use a different service name for each server.
     Suppose you want to run the 4.0.8 `mysqld-nt' using the service
     name of `mysqld1' and the 4.0.17 `mysqld-nt' using the service
     name `mysqld2'.  In this case, you can use the `[mysqld1]' group
     for 4.0.8 and the `[mysqld2]' group for 4.0.17.  For example, you
     can set up `C:\my.cnf' like this:

          # options for mysqld1 service
          [mysqld1]
          basedir = C:/mysql-4.0.8
          port = 3307
          enable-named-pipe
          socket = mypipe1

          # options for mysqld2 service
          [mysqld2]
          basedir = C:/mysql-4.0.17
          port = 3308
          enable-named-pipe
          socket = mypipe2

     Install the services as follows, using the full server pathnames
     to ensure that Windows registers the correct executable program
     for each service:

          shell> C:\mysql-4.0.8\bin\mysqld-nt --install mysqld1
          shell> C:\mysql-4.0.17\bin\mysqld-nt --install mysqld2

     To start the services, use the services manager, or use `NET START'
     with the appropriate service names:

          shell> NET START mysqld1
          shell> NET START mysqld2

     To stop the services, use the services manager, or use `NET STOP'
     with the appropriate service names:

          shell> NET STOP mysqld1
          shell> NET STOP mysqld2

     Note: Before MySQL 4.0.17, only a server installed using the
     default service name (`MySQL') or one installed explicitly with a
     service name of `mysqld' will read the `[mysqld]' group in the
     standard option files. As of 4.0.17, all servers read the
     `[mysqld' group if they read the standard option files, even if
     they are installed using another service name. This allows you to
     use the `[mysqld]' group for options that should be used by all
     MySQL services, and an option group named after each service for
     use by the server installed with that service name.

   * Specify options for each server in separate files and use
     `--defaults-file' when you install the services to tell each server
     what file to use.  In this case, each file should list options
     using a `[mysqld]' group.

     With this approach, to specify options for the 4.0.8 `mysqld-nt',
     create a file `C:\my-opts1.cnf' that looks like this:

          [mysqld]
          basedir = C:/mysql-4.0.8
          port = 3307
          enable-named-pipe
          socket = mypipe1

     For the 4.0.17 `mysqld-nt', create a file `C:\my-opts2.cnf' that
     looks like this:

          [mysqld]
          basedir = C:/mysql-4.0.17
          port = 3308
          enable-named-pipe
          socket = mypipe2

     Install the services as follows (enter each command on a single
     line):

          shell> C:\mysql-4.0.8\bin\mysqld-nt --install mysqld1
                     --defaults-file=C:\my-opts1.cnf
          shell> C:\mysql-4.0.17\bin\mysqld-nt --install mysqld2
                     --defaults-file=C:\my-opts2.cnf

     To use a `--defaults-file' option when you install a MySQL server
     as a service, you must precede the option with the service name.

     After installing the services, start and stop them the same way as
     in the preceding example.


To remove multiple services, use `mysqld --remove' for each one,
specifying a service name following the `--remove' option if the
service to remove has a name different than the default.

Running Multiple Servers on Unix
--------------------------------

The easiest way is to run multiple servers on Unix is to compile them
with different TCP/IP ports and socket files so that each one is
listening on different network interfaces. Also, by compiling in
different base directories for each installation, that automatically
results in different compiled-in data directory, log file, and PID file
locations for each of your servers.

Assume an existing server is configured for the default port number and
socket file.  To configure a new server to have different operating
parameters, use a `configure' command something like this:

     shell> ./configure --with-tcp-port=port_number \
                  --with-unix-socket-path=file_name \
                  --prefix=/usr/local/mysql-4.0.17

Here `port_number' and `file_name' should be different from the default
port number and socket file pathname, and the `--prefix' value should
specify an installation directory different than the one under which
the existing MySQL installation is located.

If you have a MySQL server listening on a given port number, you can
use the following command to find out what operating parameters it is
using for several important configurable variables, including the base
directory and socket name:

     shell> mysqladmin --host=host_name --port=port_number variables

With the information displayed by that command, you can tell what option
values *not* to use when configuring an additional server.

Note that if you specify "`localhost'" as a hostname, `mysqladmin' will
default to using a Unix socket connection rather than TCP/IP.  In MySQL
4.1, you can explicitly specify the connection protocol to use by using
the `--protocol={TCP | SOCKET | PIPE | MEMORY}' option.

You don't have to compile a new MySQL server just to start with a
different socket file and TCP/IP port number.  It is also possible to
specify those values at runtime. One way to do so is by using
command-line options:

     shell> /path/to/mysqld_safe --socket=file_name --port=port_number

To use another database directory for the second server, pass a
`--datadir=path' option to `mysqld_safe'.

Another way to achieve a similar effect is to use environment variables
to set the socket name and port number:

     shell> MYSQL_UNIX_PORT=/tmp/mysqld-new.sock
     shell> MYSQL_TCP_PORT=3307
     shell> export MYSQL_UNIX_PORT MYSQL_TCP_PORT
     shell> scripts/mysql_install_db
     shell> bin/mysqld_safe &

This is a quick way of starting a second server to use for testing.
The nice thing about this method is that the environment variable
settings will apply to any client programs that you invoke from the
above shell. Thus, connections for those clients automatically will be
directed to the second server!

*Note Environment variables:: includes a list of other environment
variables you can use to affect `mysqld'.

For automatic server execution, your startup script that is executed at
boot time should execute the following command once for each server
with an appropriate option file path for each command:

     mysqld_safe --defaults-file=path-to-option-file

Each option file should contain option values specific to a given
server.

On Unix, the `mysqld_multi' script is another way to start multiple
servers.  *Note `mysqld_multi': mysqld_multi.

Using Client Programs in a Multiple-Server Environment
------------------------------------------------------

When you want to connect with a client program to a MySQL server that is
listening to different network interfaces than those compiled into your
client, you can use one of the following methods:

   * Start the client with `--host=host_name --port=port_number' to
     connect via TCP/IP to a remote host, or with `--host=localhost
     --socket=file_name' to connect to a local host via a Unix socket
     or a Windows named pipe.

   * As of MySQL 4.1, start the client with `--protocol=tcp' to connect
     via TCP/IP, `--protocol=socket' to connect via a Unix socket,
     `--protocol=pipe' to connect via a named pipe, or
     `--protocol=memory' to connect via shared memory.  For TCP/IP
     connections, you may also need to specify `--host' and `--port'
     options.  For the other types of connections, you may need to
     specify a `--socket' option to specify a socket or named pipe
     name, or a `--shared-memory-base-name' option to specify the
     shared memory name.

   * On Unix, set the `MYSQL_UNIX_PORT' and `MYSQL_TCP_PORT'
     environment variables to point to the Unix socket and TCP/IP port
     before you start your clients.  If you normally use a specific
     socket or port, you can place commands to set these environment
     variables in your `.login' file so that they apply each time you
     log in.  *Note Environment variables::.

   * Specify the default socket and TCP/IP port in the `[client]' group
     of an option file. For example, you can use `C:\my.cnf' on
     Windows, or the `.my.cnf' file in your home directory on Unix.
     *Note Option files::.

   * In a C program, you can specify the port or socket arguments in the
     `mysql_real_connect()' call.  You can also have the program read
     option files by calling `mysql_options()'.  *Note C API
     functions::.

   * If you are using the Perl `DBD::mysql' module, you can read the
     options from the MySQL option files. For example:

          $dsn = "DBI:mysql:test;mysql_read_default_group=client;"
                  . "mysql_read_default_file=/usr/local/mysql/data/my.cnf";
          $dbh = DBI->connect($dsn, $user, $password);

     *Note Perl::.


Replication in MySQL
********************

Replication capabilities allowing the databases on one MySQL server to
be duplicated on another were introduced in MySQL version 3.23.15.
This section describes the various replication features in MySQL.  It
serves as a reference to the options available with replication.  You
will be introduced to replication and learn how to implement it.
Toward that end, there are some frequently asked questions, descriptions
of problems, and how to solve them.

For a description of the syntax of replication SQL statements, see
*Note Replication SQL::.

We suggest that you visit our website at `http://www.mysql.com/' often
and read updates to this section. Replication is constantly being
improved, and we update the manual frequently with the most current
information.

Introduction to Replication
===========================

Starting in Version 3.23.15, MySQL supports one-way replication
internally. One server acts as the master, while one or more other
servers act as slaves.  The master server keeps a binary log of updates
(*note Binary log::).  It also maintains an index file of the binary
logs to keep track of log rotation.  Each slave, upon connecting,
informs the master where it left off since the last successfully
propagated update, catches up any updates that have occurred since
then, and then blocks and waits for the master to notify it of new
updates.

A slave can also serve as a master if you set up chained replication
servers.

Note that when you are using replication, all updates to the tables
that are replicated should be performed on the master server.
Otherwise, you must always be careful to avoid conflicts between
updates that users make to tables on the master and updates that they
make to tables on the slave.

One-way replication has benefits for robustness, speed, and system
administration:

   * Robustness is increased with a master/slave setup.  In the event
     of problems with the master, you can switch to the slave as a
     backup.

   * The extra speed is achieved by splitting the load for processing
     client queries between the master and slave servers, resulting in
     better client response time.  `SELECT' queries may be sent to the
     slave to reduce query processing load of the master. Queries that
     modify data should still be sent to the master so that the master
     and slave to not get out of sync.  This load-balancing strategy is
     effective if non-updating queries dominate, but that is the normal
     case.

   * Another benefit of using replication is that one can get
     non-disturbing backups of the system by doing a backup on a slave
     instead of doing it on the master. *Note Backup::.


Replication Implementation Overview
===================================

MySQL replication is based on the master server keeping track of all
changes to your database (updates, deletes, etc) in the binary log
(*note Binary log::).  Each slave server receives from the master the
saved queries that the master has recorded in its binary log, so that
the slave can execute the same queries on its copy of the data.

It is *very important* to realize that the binary log is simply a
record starting from a fixed point in time (the moment you enable binary
logging). Any slaves that you set up will need copies of the databases
on your master as they existed at the moment you enabled binary logging
on the master. If you start your slaves with data that is not the same
as what was on the master *when the binary log was started*, your
slaves may fail.

Starting from 4.0.0, you can use `LOAD DATA FROM MASTER' to set up a
slave. Be aware that `LOAD DATA FROM MASTER' currently works only if
all the tables on the master are `MyISAM' type. Also, this statement
acquires a global read lock, so no writes are possible while the tables
are being transferred from the master. When we implement lock-free hot
table backup (in MySQL 5.0), this global read lock will no longer be
necessary.

Due to these limitations, we recommend that at this point  you use
`LOAD DATA FROM MASTER' only if the dataset on the master is relatively
small, or if a prolonged read lock on the master is acceptable. While
the actual speed of `LOAD DATA FROM MASTER' may vary from system to
system, a good rule of thumb for how long it is going to take is 1
second per 1 MB of the datafile. You will get close to the estimate if
both master and slave are equivalent to 700 MHz Pentium and are
connected through a 100 MBit/s network.  Note that this is only a rough
estimate.

Once a slave is properly configured and running, it will simply connect
to the master and wait for updates to process. If the master goes away
or the slave loses connectivity with your master, it will keep trying to
connect periodically until it is able to reconnect and resume listening
for updates. The retry interval is controlled by the
`--master-connect-retry' option. The default is 60 seconds.

Each slave keeps track of where it left off. The master server has no
knowledge of how many slaves there are or which ones are up-to-date at
any given time.

Replication Implementation Details
==================================

Three threads are involved in replication: one on the master and two on
the slave.  When `START SLAVE' is issued, the I/O thread is created on
the slave. It connects to the master and asks it to send the queries
recorded in its binlogs. Then one thread is created on the master to
send these binlogs.  This thread is identified by `Binlog Dump' in
`SHOW PROCESSLIST' output on the master.  The I/O thread reads what the
master `Binlog Dump' thread sends and simply copies it to some local
files in the slave's data directory called relay logs.  The last
thread, the SQL thread, is created on the slave; it reads the relay
logs and executes the queries it contains.

Note that the master has one thread for each currently connected slave
server.

With `SHOW PROCESSLIST' you can know what is happening on the master
and on the slave as regards replication.

The following example illustrates how the three threads show up in
`SHOW PROCESSLIST'.  The output format is that used by `SHOW
PROCESSLIST' as of MySQL version 4.0.15, when the content of the
`State' column was changed to be more meaningful compared to earlier
versions.

On the master server, the output looks like this:

     mysql> SHOW PROCESSLIST\G
     *************************** 1. row ***************************
          Id: 2
        User: root
        Host: localhost:32931
          db: NULL
     Command: Binlog Dump
        Time: 94
       State: Has sent all binlog to slave; waiting for binlog to be updated
        Info: NULL

On the slave server, the output looks like this:

     mysql> SHOW PROCESSLIST\G
     *************************** 1. row ***************************
          Id: 10
        User: system user
        Host:
          db: NULL
     Command: Connect
        Time: 11
       State: Waiting for master to send event
        Info: NULL
     *************************** 2. row ***************************
          Id: 11
        User: system user
        Host:
          db: NULL
     Command: Connect
        Time: 11
       State: Has read all relay log; waiting for the slave I/O thread to update it
        Info: NULL

Here thread 2 is on the master. Thread 10 is the I/O thread on the
slave.  Thread 11 is the SQL thread on the slave; note that the value
in the `Time' column can tell how late the slave is compared to the
master (*note Replication FAQ::).

The following list shows the most common states you will see in the
`State' column for the master's `Binlog Dump' thread. If you don't see
this thread on a master server, replication is not running.

`Sending binlog event to slave'
     Binlogs consist of events, where an event is usually a query plus
     some other information. The thread has read an event from the
     binlog and is sending it to the slave.

`Finished reading one binlog; switching to next binlog'
     The thread has finished reading a binlog file and is opening the
     next one to send to the slave.

`Has sent all binlog to slave; waiting for binlog to be updated'
     The thread has read all binary log files and is idle. It is
     waiting for new events to appear in the binary log as a result of
     new update queries being executed on the master.

`Waiting to finalize termination'
     A very brief state that happens as the thread is stopping.

Here are the most common states you will see in the `State' column for
the I/O thread of a slave server. Beginning with MySQL 4.1.1, this
state also appears in the `Slave_IO_State' column of `SHOW SLAVE
STATUS' output. This means that you can get a good view of what is
happening by using only `SHOW SLAVE STATUS'.

`Connecting to master'
     The thread is attempting to connect to the master.

`Checking master version'
     A very brief state that happens just after the connection to the
     master is established.

`Registering slave on master'
     A very brief state that happens just after the connection to the
     master is established.

`Requesting binlog dump'
     A very brief state that happens just after the connection to the
     master is established.  The thread sends to the master a request
     for the contents of its binlogs, starting from the requested
     binlog filename and position.

`Waiting to reconnect after a failed binlog dump request'
     If the binlog dump request failed (due to disconnection), the
     thread goes into this state while it sleeps. The thread sleeps for
     `master-connect-retry' seconds before retrying.

`Reconnecting after a failed binlog dump request'
     Then the thread tries to reconnect to the master.

`Waiting for master to send event'
     The thread has connected and is waiting for binlog events to
     arrive. This can last for a long time if the master is idle. If the
     wait lasts for `slave_read_timeout' seconds, a timeout will occur.
     At that point, the thread will consider the connection to be
     broken and make an attempt to reconnect.

`Queueing master event to the relay log'
     The thread has read an event and is copying it to the relay log so
     the SQL thread can process it.

`Waiting to reconnect after a failed master event read'
     An error occurred while reading (due to disconnection). The thread
     is sleeping for `master-connect-retry' seconds before attempting
     to reconnect.

`Reconnecting after a failed master event read'
     Then the thread tries to reconnect. When connection is established
     again, the state will become `Waiting for master to send event'.

`Waiting for the slave SQL thread to free enough relay log space'
     You are using a non-zero `relay_log_space_limit' value, and the
     relay logs have grown so much that their combined size exceeds
     this value.  The I/O thread is waiting until the SQL thread frees
     enough space by processing relay log contents so that it can
     delete some relay log files.

`Waiting for slave mutex on exit'
     A very brief state that happens as the thread is stopping.

Here are the most common states you will see in the `State' column for
the SQL thread of a slave server:

`Reading event from the relay log'
     The thread has read an event from the relay log so that it can
     process it.

`Has read all relay log; waiting for the slave I/O thread to update it'
     The thread has processed all events in the relay log files and is
     waiting for the I/O thread to write new events to the relay log.

`Waiting for slave mutex on exit'
     A very brief state that happens as the thread is stopping.

The `State' column for the I/O thread may also show a query string.
This indicates that the thread has read an event from the relay log,
extracted the query from it and is executing the query.

Before MySQL 4.0.2, the slave I/O and SQL threads were combined as a
single thread, and no relay log files were used.  The advantage of
using two threads is that it separates query reading and query
execution into two independent tasks, so the task of reading queries is
not slowed down if query execution is slow.  For example, if the slave
server has not been running for a while, its I/O thread can quickly
fetch all the binlog contents from the master when the slave starts,
even if the SQL thread lags far behind and may take hours to catch up.
If the slave stops before the SQL thread has executed all the fetched
queries, the I/O thread has at least fetched everything so that a safe
copy of the queries is locally stored in the slave's relay logs for
execution when next the slave starts. This allows the binlogs to be
purged on the master, because it no longer need wait for the slave to
fetch their contents.

By default, relay logs are named using filenames of the form
`host_name-relay-bin.nnn', where `host_name' is the name of the slave
server host, and `nnn' is a sequence number.  Successive relay log
files are created using successive sequence numbers, beginning with
`001'.  The slave keeps track of relay logs currently in use in an
index file.  The default relay log index filename is
`host_name-relay-bin.index'.  By default these files are created in the
slave's data directory.  The default filenames may be overridden with
the `--relay-log' and `--relay-log-index' server options.

Relay logs have the same format as binary logs, so they can be read
with `mysqlbinlog'.  A relay log is automatically deleted by the SQL
thread as soon as it no longer needs it (that is, as soon as it has
executed all its events). There is no command to delete relay logs,
because the SQL thread takes care of doing so. However, from MySQL
4.0.14, `FLUSH LOGS' rotates relay logs, which will influence when the
SQL thread deletes them.

A new relay log is created under the following conditions:

   * The first time the I/O thread starts after the slave server starts.
     (In MySQL 5.0, a new relay log will be created each time the I/O
     thread starts, not just the first time.)

   * A `FLUSH LOGS' statement is issued (4.0.14 and up only).

   * The size of the current relay log file becomes too big. The
     meaning of "too big" is determined as follows:
        - `max_relay_log_size', if `max_relay_log_size' > 0

        - `max_binlog_size', if `max_relay_log_size' = 0 or MySQL is
          older than 4.0.14


A slave replication server creates additional two small files in the
data directory.  These files are named `master.info' and
`relay-log.info' by default.  They contain information like that shown
in the output of the `SHOW SLAVE STATUS' statement (*note Replication
Slave SQL:: for a description of this command).  As disk files they
survive slave's shutdown. The next time the slave starts up, it can
read these files to know how far it has proceeded in reading binlogs
from the master and in processing its own relay logs.

The `master.info' file is updated by the I/O thread.  The
correspondance between the lines in the file and the columns displayed
by `SHOW SLAVE STATUS' is as follows:

*Line**Description*
1    `Master_Log_File'
2    `Read_Master_Log_Pos'
3    `Master_Host'
4    `Master_User'
5    Password (not shown by `SHOW SLAVE STATUS')
6    `Master_Port'
7    `Connect_Retry'

The `relay-log.info' file is updated by the SQL thread.  The
correspondance between the lines in the file and the columns displayed
by `SHOW SLAVE STATUS' is as follows:

*Line**Description*
1    `Relay_Log_File'
2    `Relay_Log_Pos'
3    `Relay_Master_Log_File'
4    `Exec_Master_Log_Pos'

When you back up your slave's data, you should back up these 2 small
files as well, along with the relay log files. because they are needed
to resume replication after you restore the slave's data.  If you lose
the relay logs but still have the `relay-log.info' file, you can check
it to determine how far the SQL thread has executed in the master
binlogs. Then you can use `CHANGE MASTER TO' with the
`MASTER_RELAY_LOG' and `MASTER_RELAY_POS' options to tell the slave to
re-read the binlogs from that point.  This requires that the binlogs
still exist on the master server.

If your slave is subject to replicating `LOAD DATA INFILE' statements,
you should also backup the `SQL_LOAD-*' files that may exist in the
directory that the slave uses for this purpose.  The slave needs these
files to resume replication of any interrupted `LOAD DATA INFILE'
statements.  The directory location is specified using the
`--slave-load-tmpdir' option.  Its default value if not specified is
the value of the `tmpdir' variable.

How to Set Up Replication
=========================

Here is a quick description of how to set up complete replication on
your current MySQL server. It assumes you want to replicate all your
databases and have not configured replication before. You will need to
shut down your master server briefly to complete the steps outlined
here.

The procedure is written in terms of setting up a single slave, but you
can use it to set up multiple slaves.

While this method is the most straightforward way to set up a slave, it
is not the only one. For example, if you already have a snapshot of the
master's data, and the master already has its server ID set and binary
logging enabled, you can set up a slave without shutting down the
master or even blocking updates to it.  For more details, please see
*Note Replication FAQ::.

If you want to administer a MySQL replication setup, we suggest that you
read this entire chapter through and try all commands mentioned in
*Note Replication Master SQL:: ans *Note Replication Slave SQL::.  You
should also familiarise yourself with replication startup options in
`my.cnf' in *Note Replication Options::.

Note that this procedure and some of the replication SQL statements in
later sections refer to the `SUPER' privilege. Prior to MySQL 4.0.2,
use the `PROCESS' privilege instead.

  1. Make sure you have a recent version of MySQL installed on the
     master and and slaves, and that these versions are compatible
     according to the table shown in *Note Replication Upgrade::.

     Please do not report bugs until you have verified that the problem
     is present in the latest release.

  2. Set up an account on the master server that the slave server can
     use to connnect. This account must be given the `REPLICATION
     SLAVE' privilege.  (If MySQL versions older than 4.0.2, give the
     account the `FILE' privilege instead.)  If the account is only for
     replication (which is recommended), you don't need to grant any
     additional privileges.

     The hostname in the account name should be such that each of the
     slave servers can use the account to connect to the master.  For
     example, to create a user named `repl' which can access your
     master from any host, you might use this command:

          mysql> GRANT REPLICATION SLAVE ON *.* TO repl@'%' IDENTIFIED BY '<password>';

     For MySQL versions older than 4.0.2, use this command instead:

          mysql> GRANT FILE ON *.* TO repl@'%' IDENTIFIED BY '<password>';

     If you plan to use the `LOAD TABLE FROM MASTER' or `LOAD DATA FROM
     MASTER' statements from the slave host, you will need to grant this
     account additional privileges:

        * Grant to the account the `SUPER' and `RELOAD' global
          privileges.

        * Grant the `SELECT' privilege for all tables that you want to
          load. Any master tables from which the account cannot
          `SELECT' will be ignored by `LOAD DATA FROM MASTER'.

  3. If you are using MyISAM tables, flush all the tables and block
     write queries by executing `FLUSH TABLES WITH READ LOCK' command.

          mysql> FLUSH TABLES WITH READ LOCK;

     and then take a snapshot of the data on your master server.

     The easiest way to create a snapshot is to simply use an archiving
     program (`tar' on Unix, `PowerArchiver', `WinRAR', `WinZip' or any
     similar software on Windows) to produce an archive of the
     databases in your master's data directory.  For example, to use
     `tar' to create an archive that includes all databases, change
     location into the master server's data directory, then execute
     this command:

          shell> tar -cvf /tmp/mysql-snapshot.tar .

     If you want the archive to include only a database called
     `this_db', use this command instead:

          shell> tar -cvf /tmp/mysql-snapshot.tar ./this_db

     Then copy the archive file to the `/tmp' directory on the slave
     server host. On that machine, change location into the slave's
     data directory, and unpack the archive file using this command:

          shell> tar -xvf /tmp/mysql-snapshot.tar

     You may not want to replicate the `mysql' database. If not, you can
     exclude it from the archive. You also need not include any log
     files in the archive, or the `master.info' or `relay-log.info'
     files.

     While the read lock placed by `FLUSH TABLES WITH READ LOCK' is in
     effect, read the value of the current binary log name and offset
     on the master:

          mysql > SHOW MASTER STATUS;
          +---------------+----------+--------------+------------------+
          | File          | Position | Binlog_Do_DB | Binlog_Ignore_DB |
          +---------------+----------+--------------+------------------+
          | mysql-bin.003 | 73       | test,bar     | foo,manual,mysql |
          +---------------+----------+--------------+------------------+
          1 row in set (0.06 sec)

     The `File' column shows the name of the log,  while `Position'
     shows the offset. In the above example, the binary log value is
     `mysql-bin.003' and the offset is 73. Record the values. You will
     need to use them later when you are setting up the slave.

     Once you have taken the snapshot and recorded the log name and
     offset, you can re-enable write activity on the master:

          mysql> UNLOCK TABLES;

     If you are using InnoDB tables, ideally you should use the InnoDB
     Hot Backup tool that is available to those who purchase MySQL
     commercial licenses, support, or the backup tool itself. It takes
     a consistent snapshot without acquiring any locks on the master
     server, and records the log name and offset corresponding to the
     snapshot to be later used on the slave. More information about the
     tool is available at `http://www.innodb.com/order.php'.

     Without the Hot Backup tool, the quickest way to take a snapshot
     of  InnoDB tables is to shut down the master server and copy the
     InnoDB datafiles and logs, and the table definition files
     (`.frm'). To record the current log file name and offset, you
     should do the following before you shut down the server:

          mysql> FLUSH TABLES WITH READ LOCK;
          mysql> SHOW MASTER STATUS;

     And then record the log name and the offset from the output of
     `SHOW MASTER STATUS' as was shown earlier. Once you have recorded
     the log name and the offset, shut down the server without
     unlocking the tables to make sure it goes down with the snapshot
     corresponding to the current log file and offset:

          shell> mysqladmin -uroot shutdown

     An alternative for both MyISAM and InnoDB tables is to take an SQL
     dump of the master instead of a binary copy like above; for this
     you can use `mysqldump --master-data' on your master and later run
     this SQL dump into your slave. However, this is slower than doing
     a binary copy.

     If the master has been previously running without `--log-bin'
     enabled, the log name and position values displayed by `SHOW MASTER
     STATUS' or `mysqldump' will be empty. In that case, record empty
     string (") for the log name, and 4 for the offset.

  4. Make sure the `[mysqld]' section of the `my.cnf' file on the
     master host includes a `log-bin' option. The section should also
     have a `server-id=master_id' option, where `master_id' must be an
     integer value from 1 to 2^32 - 1. For example:

          [mysqld]
          log-bin
          server-id=1

     If those options are not present, add them and restart the server.

  5. Stop the server that is to be used as a slave server and add the
     following to its `my.cnf' file:

          [mysqld]
          server-id=slave_id

     The `slave_id' value, like the `master_id' value, must be an
     integer value from 1 to 2^32 - 1. In addition, it is very
     important that the ID of the slave be different than the ID of the
     master. For example:

          [mysqld]
          server-id=2

     If you are setting up multiple slaves, each one must have a
     `server-id' value that differs from that of the master and from
     each of the other slaves.  Think of `server-id' values as
     something similar to IP addresses: These IDs uniquely identify
     each server instance in the community of replication partners.

     If you don't specify a `server-id' value, it will be set to 1 if
     you have not defined `master-host', else it will be set to 2. Note
     that in the case of `server-id' omission, a master will refuse
     connections from all slaves, and a slave will refuse to connect to
     a master. Thus, omitting `server-id' is only good for backup with a
     binary log.

  6. If you made a binary backup of the master server's data, copy it
     to the slave server's data directory before starting the slave.
     Make sure that the privileges on the files and directories are
     correct. The user which MySQL runs as needs to be able to read
     from and write to them, just as on the master.

     If you made a backup using `mysqldump', start the slave first (see
     next step).

  7. Start the slave server. If it has been replicating previously,
     start the slave server with the `--skip-slave-start' option.  You
     also may want to start the slave server with the `--log-warnings'
     option. That way, you will get more messages about problems (for
     example, network or connection problems).

  8. If you made a backup of the master server's data using
     `mysqldump', load the dump file into the slave server:

          shell> mysql -u root -p < dump_file.sql

  9. Execute the following command on the slave, replacing the values
     within `<>' with the actual values relevant to your system:

          mysql> CHANGE MASTER TO
              ->     MASTER_HOST='<master hostname>',
              ->     MASTER_USER='<replication username>',
              ->     MASTER_PASSWORD='<replication password>',
              ->     MASTER_LOG_FILE='<recorded log file name>',
              ->     MASTER_LOG_POS=<recorded log offset>;

     The following table lists the maximum string length for these
     variables:

     `MASTER_HOST'               60
     `MASTER_USER'               16
     `MASTER_PASSWORD'           32
     `MASTER_LOG_FILE'           255

 10. Start the slave threads:

          mysql> START SLAVE;


After you have performed this procedure, the slave should connect to
the master and catch up on any updates that have occurred since the
snapshot was taken.

If you have forgotten to set `server-id' for the master, slaves will
not be able to connect to it.

If you have forgotten to set `server-id' for the slave, you will get
the following error in its error log:

     Warning: one should set server_id to a non-0 value if master_host is set.
     The server will not act as a slave.

You will also find error messages in the slave's error log if it is not
able to replicate for any other reason.

Once a slave is replicating, you will find in its data directory one
file called `master.info' and another called `relay-log.info'.  The
slave uses these two files to keep track of how much of the master's
binary log it has processed. *Do not* remove or edit these files,
unless you really know what you are doing and understand the
implications. Even in that case, it is preferred that you use `CHANGE
MASTER TO' command.

*NOTE*: The content of `master.info' overrides some options specified
on the command-line or in `my.cnf' See *Note Replication Options:: for
more details.

Once you have a snapshot, you can use it to set up other slaves by
following the slave portion of the procedure just described. You do not
need to take another snapshot of the master.

Upgrading a Replication Setup - Mixing Different MySQL Versions
===============================================================

Any MySQL 4.1.x version is identical to MySQL 4.0.3 (and newer 4.0) as
far as replication is concerned (same binary log format).  So
replication between 4.0.3 (and newer 4.0) and any 4.1.x (whatever of
the two is the master or slave) is working seamlessly.

Binary log format was changed between MySQL 3.23 and MySQL 4.0, and
between MySQL 4.0 (or 4.1, as it's the same binary log format) and
MySQL 5.0. This has consequences on how to upgrade a replication setup,
which is explained below.

The following table indicates master/slave replication compatibility
between different versions of MySQL.

                    *Master*    *Master*    *Master*
                    *3.23.33    *4.0.3 and  *5.0.0*
                    and up*     up or any
                                4.1.x*
*Slave* *3.23.33    yes         no          no
        and up*
*Slave* *4.0.3 and  yes         yes         no
        up*
*Slave* *5.0.0*     yes         yes         yes

Versions 4.0.0, 4.0.1 and 4.0.2 were very early development versions
which should not be used anymore (their compatibility is still
documented in the manual included in these versions' distributions).

As a general rule, it's always recommended to use recent MySQL versions,
because replication capabilities are continually being improved.  We
recommend using same version for both the master and the slave.

*Upgrading from 3.23 to 4.0 (4.0.3 or newer) or any 4.1.x*
     When you upgrade a master from MySQL 3.23 to MySQL 4.0 (or 4.1),
     you should first ensure that all the slaves of this master are
     already 4.0 or 4.1 (if that's not the case, you should first
     upgrade your slaves as explained a few lines below).  Once the
     master is upgraded, you should not restart replication using old
     3.23 binary logs, because this will unfortunately confuse the 4.0
     or 4.1 slave. The upgrade can safely be done this way, assuming
     you have a 3.23 master to upgrade and you have 4.0 or 4.1 slaves:

       1. Block all updates on the master (`FLUSH TABLES WITH READ
          LOCK').

       2. Wait until all the slaves have caught up all changes from the
          master (use `SHOW MASTER STATUS' on the master, and `SELECT
          MASTER_POS_WAIT()' on the slaves). Then run `STOP SLAVE' on
          the slaves.

       3. Shut down MySQL on the master and upgrade the master to MySQL
          4.0 or 4.1.

       4. Restart MySQL on the master. Record the name `<name>' of the
          master's newly created binary log. You can obtain the name of
          the file by issuing `SHOW MASTER STATUS' on the master. Then
          issue these commands on each slave:
               mysql> CHANGE MASTER TO MASTER_LOG_FILE='<name>', MASTER_LOG_POS=4;
               mysql> START SLAVE;


     If you also must upgrade your slaves from 3.23 to 4.0 or 4.1, you
     should first upgrade your slaves: shut down each one, upgrade it,
     and restart it. Then upgrade the master as just described.

*Upgrading from 3.23 or 4.0 (4.0.3 or newer) or any 4.1.x to 5.0.0*
     First, note that MySQL 5.0.0 is alpha; even if it is supposed to
     work better than older versions (easier upgrade, replication of
     some important session variables like `sql_mode'; see *Note
     News-5.0.0::), it has not been tested a lot yet so, as with any
     alpha release, we recommend you do not use in critical production
     environment yet.

     When you upgrade a master from MySQL 3.23 or 4.0 or 4.1 to 5.0.0,
     you should first ensure that all the slaves of this master are
     already 5.0.0 (if that's not the case, you should first upgrade
     your slaves as explained a few lines below).  Then just shut down
     your master, upgrade it to 5.0.0 and restart it.  The 5.0.0 master
     will be able to read the old binary logs (of before the master
     upgrade) and to send them to the 5.0.0 slaves which will recognize
     this old format and handle it. Binary logs created after the
     master upgrade will be in 5.0.0 format and be recognized by 5.0.0
     slaves too.  To upgrade the slaves, just shut them down, upgrade
     them to 5.0.0, and restart them (and restart replication). The
     5.0.0 slaves will be able to read the old relay logs (of before
     the slave upgrade) and execute the statements they contain. Relay
     logs created after the slave upgrade will be in 5.0.0 format.  In
     other words, there are no measures to take when upgrading to 5.0.0,
     except that slaves must be 5.0.0 to be able to upgrade the master
     to 5.0.0. Note that downgrading from 5.0.0 to older versions does
     not work as automatically; you will have to remove any 5.0.0
     binary logs or relay logs before proceeding.

Replication Features and Known Problems
=======================================

Here is an explanation of what is supported and what is not:

   * Replication will be done correctly with `AUTO_INCREMENT',
     `LAST_INSERT_ID()', and `TIMESTAMP' values.

   * The `USER()' and `LOAD_FILE()' functions are replicated without
     changes and will thus not work reliably on the slave. This is also
     true for `CONNECTION_ID()' in slave versions older than 4.1.1.
     The *new* `PASSWORD()' function in MySQL 4.1, is well replicated
     since 4.1.1 masters; your slaves must be 4.1.0 or above to
     replicate it. If you have older slaves and need to replicate
     `PASSWORD()' from your 4.1.x master, you must start your master
     with option `--old-password'.

   * The `SQL_MODE', `UNIQUE_CHECKS', `SQL_AUTO_IS_NULL' variables are
     replicated only starting from 5.0.0.  `SQL_SELECT_LIMIT' and
     `TABLE_TYPE' variables are not replicated yet.
     `FOREIGN_KEY_CHECKS' is replicated since version 4.0.14.

   * You must use the same character set (`--default-character-set') on
     the master and the slave. Otherwise, you may get duplicate key
     errors on the slave, because a key that is regarded as unique in
     the master character set may not be unique in the slave character
     set. Character sets will be replicated in 5.0.x.

   * If you are using transactional tables on the master and
     non-transactional tables (for the same tables) on the slave, you
     will get problems if the slave is stopped in the middle of a
     `BEGIN/COMMIT' block, as the slave will later start at the
     beginning of the `BEGIN' block.  This issue is on our TODO and
     will be fixed in the near future.

   * Update queries that use user variables are badly replicated in
     3.23 and 4.0. This is fixed in 4.1. Note that user variable names
     are case insensitive starting from version 5.0, so you should take
     this into account when setting up replication between 5.0 and a
     previous version.

   * The slave can connect to the master using SSL, if the master and
     slave are both 4.1.1 or newer.

   * If a `DATA DIRECTORY' or `INDEX DIRECTORY' clause was used in a
     `CREATE TABLE' on master, then these clauses will be used too on
     slave. Starting from MySQL 4.0.15 there is a `SQL_MODE' mode called
     `NO_DIR_IN_CREATE'; if the slave server is run in this mode, it
     will simply cut off the clauses before replicating the `CREATE
     TABLE' (so the MyISAM data and index files will be created in the
     slave's `datadir' directory).

   * 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 a detailed explanation, see
     *Note Open bugs::.

   * Before MySQL 4.1.1, `FLUSH', `ANALYZE', `OPTIMIZE', `REPAIR'
     commands are not stored in the binary log and thus are not
     replicated to the slaves. This is not normally a problem as these
     commands don't change anything. However, it does mean that if you
     update the MySQL privilege tables directly without using the
     `GRANT' statement and you replicate the `mysql' privilege
     database, you must do a `FLUSH PRIVILEGES' on your slaves to put
     the new privileges into effect. Also if you use `FLUSH TABLES'
     when renaming a `MyISAM' table involved in a `MERGE' table, you
     will have to issue `FLUSH TABLES' manually on the slave.  Since
     MySQL 4.1.1, these commands are written to the binary log (except
     `FLUSH LOGS', `FLUSH MASTER', `FLUSH SLAVE', `FLUSH TABLES WITH
     READ LOCK') unless you specify `NO_WRITE_TO_BINLOG' (or its alias
     `LOCAL').  For a syntax example, see *Note `FLUSH': FLUSH.

   * MySQL only supports one master and many slaves. Later we will add
     a voting algorithm to automatically change master if something goes
     wrong with the current master. We will also introduce "agent"
     processes to help do load balancing by sending `SELECT' queries to
     different slaves.

   * Starting from MySQL 4.0.18, the master notifies the slave of a
     `HEAP' table having been emptied by master's shutdown/restart by
     writing a `DELETE FROM' to its binary log the first time it uses
     the table since startup. See *Note HEAP:: for more details.

   * Temporary tables are replicated with the exception of the case
     that you shut down slave server (not just slave thread) and you
     have some replicated temporary tables that are used in update
     statements that have not yet been executed on the slave.  (If you
     shut down the slave, the temporary tables needed by those updates
     no longer are available when the slave starts again.)  To avoid
     this problem, do not shut down the slave while it has temporary
     tables open. Instead, use this procedure:

       1. Issue a `STOP SLAVE' statement.

       2. Use `SHOW STATUS' to check the value of the
          `Slave_open_temp_tables' variable.

       3. If the value is 0, issue a `mysqladmin shutdown' command to
          shut down the slave.

       4. If the value is not 0, restart the slave threads with `START
          SLAVE'.

       5. Repeat the procedure later to see if you have better luck
          next time.


     We have plans to fix this problem in the near future.

   * It is safe to connect servers in a circular master/slave
     relationship with `log-slave-updates' enabled.  Note, however,
     that many queries will not work correctly in this kind of setup
     unless your client code is written to take care of the potential
     problems that can happen from updates that occur in different
     sequence on different servers.

     This means that you can do a setup like the following:

          A -> B -> C -> A

     Server IDs are encoded in the binary log events.  A will know when
     an event it reads had originally been created by A, so A will not
     execute it and there will be no infinite loop.  But this circular
     setup will work only if you only if you perform no conflicting
     updates between the tables.  In other words, if you insert data in
     A and C, you should never insert a row in A that may have a
     conflicting key with a row insert in C.  You should also not update
     the same rows on two servers if the order in which the updates are
     applied matters.

   * If a query on the slave gets an error, the slave SQL thread will
     terminate, and a message will appear in the slave error log. You
     should then connect to the slave manually, fix the cause of the
     error (for example, non-existent table), and then run `START
     SLAVE'.

   * If the connection to the master is lost, the slave will try to
     reconnect immediately. If that fails, the slave will retry every
     `master-connect-retry' seconds (default 60). Because of this, it
     is safe to shut down the master, and then restart it after a
     while. The slave will also be able to deal with network
     connectivity outages. However, the slave will notice the network
     outage only after receiving no data from the master for
     `slave_net_timeout' seconds. So if your outages are short, you may
     want to decrease `slave_net_timeout'.  *Note `SHOW VARIABLES':
     SHOW VARIABLES.

   * Shutting down the slave (cleanly) is also safe, as it keeps track
     of where it left off.  Unclean shutdowns might produce problems,
     especially if disk cache was not synced before the system died.
     Your system fault tolerance will be greatly increased if you have
     a good UPS.

   * Due to the non-transactional nature of MyISAM tables, it is
     possible to have a query that will only partially update a table
     and return an error code. This can happen, for example, on a
     multi-row insert that has one row violating a key constraint, or
     if a long update query is killed after updating some of the rows.
     If that happens on the master, the slave thread will exit and wait
     for the DBA to decide what to do about it unless the error code is
     legitimate and the query execution results in the same error code.
     If this error code validation behavior is not desirable, some (or
     all) errors can be masked out (ignored) with the
     `--slave-skip-errors' option.  This option is available starting
     with MySQL Version 3.23.47.

   * If you update transactional tables from non-transactional tables
     inside a `BEGIN/COMMIT' segment, updates to the binary log may be
     out of sync if some thread changes the non-transactional table
     before the transaction commits.  This is because the transaction
     is written to the binary log only when it's commited.

   * Before version 4.0.15, any update to a non-transactional table is
     written to the binary log at once when the update is made while
     transactional updates are written on `COMMIT' or not written at
     all if you use `ROLLBACK'; you have to take this into account when
     updating both transactional tables and non-transactional tables in
     the same transaction if you are using binary logging for backups or
     replication. In version 4.0.15, we changed the logging behavior
     for transactions that mix updates to transactional and
     non-transactional tables, which solves the problems (order of
     queries is good in binlog, and all needed queries are written to
     the binlog even in case of `ROLLBACK'). The problem which remains
     is when a second connection updates the non-transactional table
     while the first connection's transaction is not finished yet
     (wrong order can still occur, because the second connection's
     update will be written immediately after it is done).

The following table lists problems in MySQL 3.23 that are fixed in
MySQL 4.0:

   * `LOAD DATA INFILE' is handled properly, as long as the data file
     still resides on the master server at the time of update
     propagation.

   * `LOAD LOCAL DATA INFILE' will be skipped.

   * In 3.23 `RAND()' in updates does not replicate properly.  Use
     `RAND(some_non_rand_expr)' if you are replicating updates with
     `RAND()'. You can, for example, use `UNIX_TIMESTAMP()' for the
     argument to `RAND()'. This is fixed in 4.0.

Replication Startup Options
===========================

On both the master and the slave you need to use the `server-id' option
to establish a unique replication ID for each server. You should pick a
unique integer in the range from 1 to 2^32 - 1 for each master and
slave.  Example: `server-id=3'

The options that you can use on the master server for controlling binary
logging are all described in *Note Binary log::.

The following table describes the options you can use on slave servers.
You can specify them on the command line or in an option file.

*NOTE*: Replication handles the following options in a special way:

   * `--master-host'

   * `--master-user'

   * `--master-password'

   * `--master-port'

   * `--master-connect-retry'

If no `master.info' file exists when the slave server starts, it uses
values for those options that are specified in option files or on the
command line.  This will occur when you start the server as a
replication slave for the very first time, or you have run `RESET
SLAVE' and shut down and restarted the slave server.

However, if the `master.info' file exists when the slave server starts,
it uses the values in the file and *IGNORES* any values specified for
those options in option files or on the command line.

Suppose you specify this option in your `my.cnf' file:

     [mysqld]
     master-host=this_host

The first time you start the server as a replication slave, it will
read and use that option from the `my.cnf' file.  The server will then
record that value in the `master.info' file.  The next time you start
the server, it will read the master host value from the `master.info'
file only.  If you modify the `my.cnf' file to specify a different
master host, it will have no effect.  You must use `CHANGE MASTER TO'
instead.

As of MySQL 4.1.1, the following options also are handled specially:

   * `--master-ssl'

   * `--master-ssl-ca'

   * `--master-ssl-capath'

   * `--master-ssl-cert'

   * `--master-ssl-cipher'

   * `--master-ssl-key'

The `master.info' file includes the values corresponding to those
options. In addition, the 4.1.1 file format includes as its first line
the number of lines in the file. If you upgrade an older server to
4.1.1, the `master.info' will be upgraded to the new format
automatically when the new server starts. (If you downgrade a 4.1.1 or
newer server to a version older than 4.1.1, you should manually remove
the first line before starting the older server for the first time.)

Because the server gives an existing `master.info' file precedence over
the startup options just described, you might prefer not to use startup
options for these values at all, and instead specify them by using the
`CHANGE MASTER TO' statement.  See *Note `CHANGE MASTER TO': CHANGE
MASTER TO.

This example shows a more extensive use of startup options to configure
a slave server:

     [mysqld]
     server-id=2
     master-host=db-master.mycompany.com
     master-port=3306
     master-user=pertinax
     master-password=freitag
     master-connect-retry=60
     report-host=db-slave.mycompany.com

The following list describes startup options for controlling
replication:

`--log-slave-updates'
     Tells the slave to log the updates performed by its SQL thread to
     the slave's own binary log. Off by default.  For this option to
     have any effect, the slave must be started with binary logging
     enabled (`--log-bin' option).  `--log-slave-updates' is used when
     you want to chain replication servers.  For example, you might
     want a setup like this:

          A -> B -> C

     That is, A serves as the master for the slave B, and B serves as
     the master for the slave C. For this to work, where B is both a
     master and a slave, you must start B with the
     `--log-slave-updates' option.  A and B must both be started with
     binary logging enabled.

`--log-warnings'
     Makes the slave print more messages about what it is doing. For
     example, it will warn you that it succeeded in reconnecting after a
     network/connection failure, and warn you about how each slave
     thread started.

     This option is not limited to replication use only. It produces
     warnings across a spectrum of server activities.

`--master-host=host'
     Specify the hostname or IP address of the master replication
     server.  If this option is not given, the slave thread will not be
     started.  The value in `master.info' takes precedence if it can be
     read.  Probably a better name for this options would have been
     something like `--bootstrap-master-host', but it is too late to
     change now.

`--master-user=username'
     The username of the account that the slave thread uses for
     authentication when connecting to the master. The account must
     have the `REPLICATION SLAVE' privilege (prior to MySQL 4.0.2, it
     must have the `FILE' privilege instead). If the master user is not
     set, user `test' is assumed. The value in `master.info' takes
     precedence if it can be read.

`--master-password=password'
     The password of the account that the slave thread uses for
     authentication when connecting to the master.  If not set, an
     empty password is assumed. The value in `master.info' takes
     precedence if it can be read.

`--master-port=port_number'
     The port the master is listening on. If not set, the compiled
     setting of `MYSQL_PORT' is assumed. If you have not tinkered with
     `configure' options, this should be 3306. The value in
     `master.info' takes precedence if it can be read.

`--master-connect-retry=seconds'
     The number of seconds the slave thread sleeps before retrying to
     connect to the master in case the master goes down or the
     connection is lost.  Default is 60. The value in `master.info'
     takes precedence if it can be read.

`--master-info-file=filename'
     Specifies the name to use for the file in which the slave records
     information about the master.  The default name is `mysql.info' in
     the data directory.

`--master-ssl'
`--master-ssl-ca=file_name'
`--master-ssl-capath=directory_name'
`--master-ssl-cert=file_name'
`--master-ssl-cipher=cipher_list'
`--master-ssl-key=file_name'
     These options are used for setting up a secure replication
     connection to the master server using SSL.  Their meanings are the
     same as the corresponding `--ssl', `--ssl-ca', `--ssl-capath',
     `--ssl-cert', `--ssl-cipher', `--ssl-key' options described in
     *Note SSL options::.

     These options are operational as of MySQL 4.1.1.

`--max-relay-log-size=#'
     To rotate the relay log automatically.  *Note `SHOW VARIABLES':
     SHOW VARIABLES.

`--relay-log=filename'
     To specify the location and name that should be used for relay
     logs.  You can use this to have hostname-independant relay log
     names, or if your relay logs tend to be big (and you don't want to
     decrease `max_relay_log_size') and you need to put them on some
     area different from the data directory, or if you want to increase
     speed by balancing load between disks.

`--relay-log-index=filename'
     To specify the location and name that should be used for the relay
     logs index file.

`--relay-log-info-file=filename'
     To give `relay-log.info' another name and/or to put it in another
     directory than the data directory.

`--relay-log-purge=0|1'
     Disables/enables automatic purging of relay logs as soon as they
     are not needed any more. This is a global variable that can be
     dynamically changed with `SET GLOBAL RELAY_LOG_PURGE=0|1'. The
     default value is 1.

     This option is available as of MySQL 4.1.1.

`--relay-log-space-limit=#'
     To put an upper limit on the total size of all relay logs on the
     slave (a value of 0 means "unlimited"). This is useful if you have
     a small hard disk on your slave machine. When the limit is
     reached, the I/O thread pauses (does not read the master's binlog)
     until the SQL thread has caught up and deleted some now unused
     relay logs. Note that this limit is not absolute: there are cases
     where the SQL thread needs more events to be able to delete; in
     that case the I/O thread will overgo the limit until deletion
     becomes possible. Not doing so would cause a deadlock (which
     happens before MySQL 4.0.13).  Users should not set
     `--relay-log-space-limit' to less than twice the value of
     `--max-relay-log-size' (or `--max-binlog-size' if
     `--max-relay-log-size' is 0) because in that case there are
     chances that when the I/O thread waits for free space because
     `--relay-log-space-limit' is exceeded, the SQL thread has no relay
     log to purge and so cannot satisfy the I/O thread, forcing the I/O
     thread to temporarily ignore `--relay-log-space-limit'.

`--replicate-do-table=db_name.table_name'
     Tells the slave thread to restrict replication to the specified
     table.  To specify more than one table, use the directive multiple
     times, once for each table.  This will work for cross-database
     updates, in contrast to `--replicate-do-db'.  Please read the
     notes that follow this option list.

`--replicate-ignore-table=db_name.table_name'
     Tells the slave thread to not replicate any command that updates
     the specified table (even if any other tables may be update by the
     same command). To specify more than one table to ignore, use the
     directive multiple times, once for each table. This will work for
     cross-database updates, in contrast to `--replicate-ignore-db'.
     Please read the notes that follow this option list.

`--replicate-wild-do-table=db_name.table_name'
     Tells the slave thread to restrict replication to queries where
     any of the updated tables match the specified wildcard pattern.
     To specify more than one table, use the directive multiple times,
     once for each table.  This will work for cross-database updates.
     Please read the notes that follow this option list.

     Example: `--replicate-wild-do-table=foo%.bar%' will replicate only
     updates that uses a table in any databases that start with `foo'
     and whose table names start with `bar'.

     Note that if you do `--replicate-wild-do-table=foo%.%' then the
     rule will be propagated to `CREATE DATABASE' and `DROP DATABASE',
     that is, these two statements will be replicated if the database
     name matches the database pattern (`foo%' here) (this magic is
     triggered by `%' being the table pattern).

     Escaping wildcard characters `_' and `%': if you want to
     replicate, for example, all tables of the `my_own%db' database
     (this is the exact name of the database), but not replicate tables
     from the `my1ownAABCdb' database, you should escape the `_' and
     `%': you should use something like this:
     `replicate-wild-do-table=my\_own\%db'. And if you are specifying
     this option from the command-line, depending on your system you
     may need to escape the `\' (for example, with a `bash' shell, you
     would need to type `--replicate-wild-do-table=my\\_own\\%db').

`--replicate-wild-ignore-table=db_name.table_name'
     Tells the slave thread to not replicate a query where any table
     matches the given wildcard pattern. To specify more than one table
     to ignore, use the directive multiple times, once for each table.
     This will work for cross-database updates.  Please read the notes
     that follow this option list.

     Example: `--replicate-wild-ignore-table=foo%.bar%' will not do
     updates to tables in databases that start with `foo' and whose
     table names start with `bar'.

     Note that if you do `--replicate-wild-ignore-table=foo%.%' then the
     rule will be propagated to `CREATE DATABASE' and `DROP DATABASE',
     that is, these two statements will not be replicated if the
     database name matches the database pattern (`foo%' here) (this
     magic is triggered by `%' being the table pattern).

     Escaping wildcard characters `_' and `%': see notes in the
     description of `replicate-wild-do-table' just above.

`--replicate-do-db=database_name'
     Tells the slave to restrict replication to commands where the
     current database (that is, the one selected by `USE') is
     `database_name'.  To specify more than one database, use the
     directive multiple times, once for each database. Note that this
     will not replicate cross-database queries such as `UPDATE
     some_db.some_table SET foo='bar'' while having selected a
     different or no database. If you need cross database updates to
     work, make sure you have 3.23.28 or later, and use
     `--replicate-wild-do-table=db_name.%'.  Please read the notes that
     follow this option list.

     Example of what does not work as you could expect it: if the slave
     is started with `--replicate-do-db=sales', and you do `USE prices;
     UPDATE sales.january SET amount=amount+1000;', this query will not
     be replicated.

     If you need cross database updates to work, use
     `--replicate-wild-do-table=db_name.%' instead.

     The main reason for this "just-check-the-current-database"
     behavior is that it's hard from the command alone to know if a
     query should be replicated or not; for example if you are using
     multiple-table-delete or multiple-table-update commands that go
     across multiple databases.  It's also very fast to just check the
     current database.

`--replicate-ignore-db=database_name'
     Tells the slave to not replicate any command where the current
     database (that is, the one selected by `USE') is `database_name'.
     To specify more than one database to ignore, use the directive
     multiple times, once for each database.  You should not use this
     directive if you are using cross table updates and you don't want
     these update to be replicated.  Please read the notes that follow
     this option list.

     Example of what does not work as you could expect it: if the slave
     is started with `--replicate-ignore-db=sales', and you do `USE
     prices; UPDATE sales.january SET amount=amount+1000;', this query
     will be replicated.

     If you need cross database updates to work, use
     `--replicate-wild-ignore-table=db_name.%' instead.

`--replicate-rewrite-db=from_name->to_name'
     Tells the slave to translate the current database (that is, the
     one selected by `USE') to `to_name' if it was `from_name' on the
     master.  Only statements involving tables may be affected (`CREATE
     DATABASE', `DROP DATABASE' won't), and only if `from_name' was the
     current database on the master.  This will not work for
     cross-database updates.  Note that the translation is done before
     `--replicate-*' rules are tested.

     Example: `replicate-rewrite-db=master_db_name->slave_db_name'

`--report-host=host'
     The hostname or IP number of the slave to be reported to the
     master during slave registration. Will appear in the output of
     `SHOW SLAVE HOSTS'. Leave unset if you do not want the slave to
     register itself with the master. Note that it is not sufficient
     for the master to simply read the IP number of the slave from the
     TCP/IP socket once the slave connects. Due to `NAT' and other
     routing issues, that IP may not be valid for connecting to the
     slave from the master or other hosts.

     This option is available as of MySQL 4.0.0.

`--report-port=port_number'
     Port for connecting to slave reported to the master during slave
     registration.  Set it only if the slave is listening on a
     non-default port or if you have a special tunnel from the master or
     other clients to the slave. If not sure, leave this option unset.

     This option is available as of MySQL 4.0.0.

`--skip-slave-start'
     Tells the slave server not to start the slave threads on server
     startup. The user can start them later with `START SLAVE'.

`--slave_compressed_protocol=#'
     If 1, then use compression on the slave/client protocol if both
     slave and master support this.

`--slave-load-tmpdir=filename'
     This option is by default equal to the value of the `tmpdir'
     variable.  When the slave SQL thread replicates a `LOAD DATA
     INFILE' command, it extracts the to-be-loaded file from the relay
     log into temporary files, then loads these into the table. If the
     file loaded on the master was huge, the temporary files on the
     slave will be huge, too; therefore you may wish/have to tell the
     slave to put the temporary files on some large disk different from
     `tmpdir', using this option. In that case, you may also use the
     `--relay-log' option, as relay logs will be huge, too.
     `--slave-load-tmpdir' should point to a disk-based filesystem; not
     a memory-based one. Because the slave needs the temporary files
     used to replicate `LOAD DATA INFILE') to survive a machine's
     reboot.

`--slave-net-timeout=#'
     Number of seconds to wait for more data from the master before
     aborting the read, considering the connection broken and retrying
     to connect. The first retry occurs immediately after timeout. The
     interval between retries is controlled by the
     `--master-connect-retry' option.

`--slave-skip-errors= [err_code1,err_code2,... | all]'
     Tells the slave SQL thread to continue replication when a query
     returns an error from the provided list. Normally, replication
     will discontinue when an error is encountered, giving the user a
     chance to resolve the inconsistency in the data manually. Do not
     use this option unless you fully understand why you are getting
     the errors.  If there are no bugs in your replication setup and
     client programs, and no bugs in MySQL itself, you should never get
     an abort with error. Indiscriminate use of this option will result
     in slaves being hopelessly out of sync with the master and you
     having no idea how the problem happened.

     For error codes, you should use the numbers provided by the error
     message in your slave error log and in the output of `SHOW SLAVE
     STATUS'. A full list of error messages can be found in the source
     distribution in `Docs/mysqld_error.txt'.  The server error codes
     also are listed at *Note Error-returns::.

     You can (but should not) also use a very non-recommended value of
     `all' which will ignore all error messages and keep barging along
     regardless.  Needless to say, if you use it, we make no promises
     regarding your data integrity. Please do not complain if your data
     on the slave is not anywhere close to what it is on the master in
     this case -- you have been warned.

     Examples:

          --slave-skip-errors=1062,1053
          --slave-skip-errors=all

Some of these options, like all `--replicate-*' options, can only be
set at the slave server's startup, not on-the-fly. We plan to fix this.

Here is the order of evaluation of the `r--eplicate-*' rules, to decide
if the query is going to be executed by the slave or ignored by it:
  1. Are there some `--replicate-do-db' or `--replicate-ignore-db'
     rules?
        * Yes: test them like for `--binlog-do-db' and
          `--binlog-ignore-db' (*note Binary log::). What is the result
          of the test?
             - ignore the query: ignore it and exit.

             - execute the query: don't execute it immediately, defer
               the decision, go to step below.

        * No: go to step below.

  2. Are there some `--replicate-*-table' rules?
        * No: execute the query and exit.

        * Yes: go to step below. Only tables which are to be updated
          will be compared to rules (`INSERT INTO sales SELECT * from
          prices': only `sales' will be compared to rules). If several
          tables are to be updated (multiple-table statement), the
          first matching table (matching "do" or "ignore") wins (that
          is, the first table is compared to rules, then if no decision
          could be taken the second table is compared to rules, etc).

  3. Are there some `--replicate-do-table' rules?
        * Yes: does the table match any of them?
             - Yes: execute the query and exit.

             - No: go to step below.

        * No: go to step below.

  4. Are there some `--replicate-ignore-table' rules?
        * Yes: does the table match any of them?
             - Yes: ignore the query and exit.

             - No: go to step below.

        * No: go to step below.

  5. Are there some `--replicate-wild-do-table' rules?
        * Yes: does the table match any of them?
             - Yes: execute the query and exit.

             - No: go to step below.

        * No: go to step below.

  6. Are there some `--replicate-wild-ignore-table' rules?
        * Yes: does the table match any of them?
             - Yes: ignore the query and exit.

             - No: go to step below.

        * No: go to step below.

  7. No `--replicate-*-table' rule was matched.  Is there another table
     to test against these rules?
        * Yes: loop.

        * No: we have tested all tables to be updated, could not match
          any rule.  Are there `--replicate-do-table' or
          `--replicate-wild-do-table' rules ?
             - Yes: ignore the query and exit.

             - No: execute the query and exit.

Replication FAQ
===============

*Q*: How do I configure a slave if the master is already running and I
do not want to stop it?

*A*: There are several options. If you have taken a backup of the
master at some point and recorded the binlog name and offset ( from the
output of `SHOW MASTER STATUS' ) corresponding to the snapshot, do the
following:

  1. Make sure the slave is assigned a unique server ID.

  2. Execute the following statement on the slave, filling in
     appropriate values for each parameter:

          mysql> CHANGE MASTER TO
              ->     MASTER_HOST='master_host-name',
              ->     MASTER_USER='master_user_name',
              ->     MASTER_PASSWORD='master_pass',
              ->     MASTER_LOG_FILE='recorded_log_name',
              ->     MASTER_LOG_POS=recorded_log_pos;

  3. Execute `START SLAVE' on the slave.

If you do not have a backup of the master already, here is a quick way
to do it consistently:

  1. `FLUSH TABLES WITH READ LOCK'

  2. `gtar zcf /tmp/backup.tar.gz /var/lib/mysql' (or a variation of
     this)

  3. `SHOW MASTER STATUS' - make sure to record the output - you will
     need it later

  4. `UNLOCK TABLES'

An alternative is taking an SQL dump of the master instead of a binary
copy like above; for this you can use `mysqldump --master-data' on your
master and later run this SQL dump into your slave. However, this is
slower than makeing a binary copy.

No matter which of the two methods you use, afterwards follow the
instructions for the case when you have a snapshot and have recorded
the log name and offset. You can use the same snapshot to set up
several slaves. As long as the binary logs of the master are left
intact, you can wait as long as several days or in some cases maybe a
month to set up a slave once you have the snapshot of the master. In
theory the waiting gap can be infinite. The two practical limitations
is the diskspace of the master getting filled with old logs, and the
amount of time it will take the slave to catch up.

You can also use `LOAD DATA FROM MASTER'.  This is a convenient command
that takes a snapshot, restores it to the slave, and adjusts the log
name and offset on the slave all at once. In the future, `LOAD DATA
FROM MASTER' will be the recommended way to set up a slave.  Be warned,
howerver, that the read lock may be held for a long time if you use
this command. It is not yet implemented as efficiently as we would like
to have it. If you have large tables, the preferred method at this time
is still with a local `tar' snapshot after executing `FLUSH TABLES WITH
READ LOCK'.

*Q*: Does the slave need to be connected to the master all the time?

*A*: No, it does not. The slave can go down or stay disconnected for
hours or even days, then reconnect and catch up on the updates.  For
example, you can set up a master/slave relationship over a dial-up link
where the link is up only sporadically and for short periods of time.
The implication of this is that at any given time the slave is not
guaranteed to be in sync with the master unless you take some special
measures. In the future, we will have the option to block the master
until at least one slave is in sync.

*Q*: How do I know how late a slave is compared to the master? In other
words, how do I know the date of the last query replicated by the slave?

*A*: If the slave is 4.1.1 or newer, read the `Seconds_Behind_Master'
column in `SHOW SLAVE STATUS'. For older versions, the following
applies.  This is possible only if the slave SQL thread exists (that
is, if it shows up in `SHOW PROCESSLIST', *note Replication
Implementation Details::) (in MySQL 3.23: if the slave thread exists,
that is, shows up in `SHOW PROCESSLIST'), and if it has executed at
least one event from the master. Indeed, when the slave SQL thread
executes an event read from the master, this thread modifies its own
time to the event's timestamp (this is why `TIMESTAMP' is well
replicated). So in the `Time' column in the output of `SHOW
PROCESSLIST', the number of seconds displayed for the slave SQL thread
is the number of seconds between the timestamp of the last replicated
event and the real time of the slave machine. You can use this to
determine the date of the last replicated event. Note that if your
slave has been disconnected from the master for one hour, then
reconnects, you may immediately see `Time' values like 3600 for the
slave SQL thread in `SHOW PROCESSLIST'... This would be because the
slave is executing queries that are one hour old.

*Q*: How do I force the master to block updates until the slave catches
up?

*A*: Use the following procedure:

  1. On the master, execute these commands:

          mysql> FLUSH TABLES WITH READ LOCK;
          mysql> SHOW MASTER STATUS;

     Record the log name and the offset from the output of the `SHOW'
     statement.

  2. On the slave, issue this command, where the replication
     coordinates that are the arguments to the `MASTER_POS_WAIT()'
     function are the values recorded in the previous step:

          mysql> SELECT MASTER_POS_WAIT('log_name', log_offset);

     The `SELECT' statement will block until the slave reaches the
     specified log file and offset. At that point, the slave will be in
     sync with the master and the statement will return.

  3. On the master, issue the following statement to allow the master
     to begin processing updates again:

          mysql> UNLOCK TABLES;


*Q*: What issues should I be aware of when setting up two-way
replication?

*A*: MySQL replication currently does not support any locking protocol
between master and slave to guarantee the atomicity of a distributed
(cross-server) update. In other words, it is possible for client A to
make an update to  co-master 1, and in the meantime, before it
propagates to co-master 2, client B could make an update to co-master 2
that will make the update of client A work differently than it did on
co-master 1. Thus, when the update of client A will make it to
co-master 2, it will produce  tables that are different than what you
have on co-master 1, even after all the updates from co-master 2 have
also propagated. So you should not co-chain two servers in a two-way
replication relationship, unless you are sure that your updates can
safely happen in any order, or unless you take care of mis-ordered
updates somehow in the client code.

You must also realize that two-way replication actually does not improve
performance very much (if at all), as far as updates are concerned. Both
servers need to do the same amount of updates each, as you would have
one server do. The only difference is that there will be a little less
lock contention, because the updates originating on another server will
be serialized in one slave thread. Even so, this benefit might be
offset by network delays.

*Q*: How can I use replication to improve performance of my system?

*A*: You should set up one server as the master and direct all writes
to it. Then configure as many slaves as you have the money and
rackspace for, and distribute the reads among the master and the slaves.
You can also start the slaves with `--skip-bdb',
`--low-priority-updates' and `--delay-key-write=ALL' to get speed
improvements for the slave.  In this case the slave will use
non-transactional `MyISAM' tables instead of `BDB' tables to get more
speed.

*Q*: What should I do to prepare client code in my own applications to
use performance-enhancing replication?

*A*: If the part of your code that is responsible for database access
has been properly abstracted/modularised, converting it to run with a
replicated setup should be very smooth and easy. Just change the
implementation of your database access to send all writes the the
master, and to send reads to either the master or a slave.  If your
code does not have this level of abstraction, setting up a replicated
system will give you the opportunity and motivation to it clean up.
You should start by creating a wrapper library or module with the
following functions:

   * `safe_writer_connect()'

   * `safe_reader_connect()'

   * `safe_reader_query()'

   * `safe_writer_query()'

`safe_' in each function name means that the function will take care of
handling all the error conditions.  You can use different names for the
functions. The important thing is to have a unified interface for
connecting for reads, connecting for writes, doing a read, and doing a
write.

You should then convert your client code to use the wrapper library.
This may be a painful and scary process at first, but it will pay off in
the long run. All applications that use the approach just described
will be able to take advantage of a master/slave configuration, even
one involving multiple slaves.  The code will be a lot easier to
maintain, and adding troubleshooting options will be trivial. You will
just need to modify one or two functions, for example, to log how long
each query took, or which query, among your many thousands, gave you an
error.

If you have written a lot of code already, you may want to automate the
conversion task by using the `replace' utility that comes with the
standard distribution of MySQL, or just write your own Perl script.
Hopefully, your code follows some recognizable pattern. If not, then
you are probably better off rewriting it anyway, or at least going
through and manually beating it into a pattern.

*Q*: When and how much can MySQL replication improve the performance of
my system?

*A*: MySQL replication is most beneficial for a system with frequent
reads and infrequent writes. In theory, by using a
single-master/multiple-slave setup, you can scale the system by adding
more slaves until you either run out of network bandwidth, or your
update load grows to the point that the master cannot handle it.

In order to determine how many slaves you can get before the added
benefits begin to level out, and how much you can improve performance
of your site, you need to know your query patterns, and empirically
(by benchmarking) determine the relationship between the throughput on
reads (reads per second, or `max_reads') and on writes (`max_writes')
on a typical master and a typical slave. The example here will show you
a rather simplified calculation of what you can get with replication
for a hypothetical system.

Let's say that system load consists of 10% writes and 90% reads, and we
have determined `max_reads' to be 1200 - 2 * `max_writes'.  In other
words, the system can do 1200 reads per second with no writes, the
average write is twice as slow as average read, and the relationship is
linear. Let us suppose that the master and each slave have the same
capacity, and that we have 1 master and N slaves. Then we have for each
server (master or slave):

`reads = 1200 - 2 * writes' (from benchmarks)

`reads = 9* writes / (N + 1) ' (reads split, but writes go to all
servers)

`9*writes/(N+1) + 2 * writes = 1200'

`writes = 1200/(2 + 9/(N+1)'

This analysis yields the following conclusions:

   * If N = 0 (which means we have no replication), our system can
     handle 1200/11, about 109 writes per second (which means we will
     have 9 times as many reads due to the nature of our application).

   * If N = 1, we can get up to 184 writes per second.

   * If N = 8, we get up to 400.

   * If N = 17, 480 writes.

   * Eventually, as N approaches infinity (and our budget negative
     infinity), we can get very close to 600 writes per second,
     increasing system throughput about 5.5 times. However, with only 8
     servers, we increased it almost 4 times already.


Note that these computations assume infinite network bandwidth and
neglect several other factors that could turn out to be significant on
your system. In many cases, you may not be able to perform a computation
similar to the one above that will accurately predict what will happen
on your system if you add N replication slaves. However, answering the
following questions should help you decide whether and how much
replication will improve the performance of your system:

   * What is the read/write ratio on your system?

   * How much more write load can one server handle if you reduce the
     reads?

   * How many slaves do you have bandwidth available for on your
     network?

*Q*: How can I use replication to provide redundancy/high availability?

*A*: With the currently available features, you would have to set up a
master and a slave (or several slaves), and write a script that will
monitor the master to see whether it is up, and instruct your
applications and the slaves of the master change in case of failure.
Some suggestions:

   * To tell a slave to change the master, use the `CHANGE MASTER TO'
     command.

   * A good way to keep your applications informed as to the location
     of the master is by having a dynamic DNS entry for the master.
     With `bind' you can use `nsupdate' to dynamically update your DNS.

   * You should run your slaves with the `--log-bin' option and without
     `--log-slave-updates'. This way the slave will be ready to become a
     master as soon as you issue `STOP SLAVE'; `RESET MASTER', and
     `CHANGE MASTER TO' on the other slaves.  For example, consider you
     have the following setup ("M" means the master, "S" the slaves,
     "WC" the clients that issue database writes and reads; clients
     that issue only database reads are not represented, because they
     need not switch):

                 WC
                  \
                   v
           WC----> M
                 / | \
                /  |  \
               v   v   v
              S1   S2  S3

     S1 (like S2 and S3) is a slave running with `--log-bin' and
     without `--log-slave-updates'. As the only writes executed on S1
     are those replicated from M, the binary log on S1 is *empty*
     (remember, S1 runs without `--log-slave-updates').  Then, for some
     reason, M becomes unavailable, and you want S1 to become the new
     master (that is, direct all WC to S1, and make S2 and S3 replicate
     S1).

     Make sure that all slaves have processed any queries in their
     relay log.  On each slave, issue `STOP SLAVE IO_THREAD', then
     check the output of `SHOW PROCESSLIST' until you see `Has read all
     relay log'.  When this is true for all slaves, they can be
     reconfigured to the new setup.  Issue `STOP SLAVE' on all slaves,
     `RESET MASTER' on the slave being promoted to master, and `CHANGE
     MASTER' on the other slaves.

     No WC accesses M. Instruct all WC to direct their queries to S1.
     From now on, all queries sent by WC to S1 are written to the
     binary log of S1. The binary log of S1 contains exactly every
     writing query sent to S1 since M died.  On S2 (and S3) do `STOP
     SLAVE', `CHANGE MASTER TO MASTER_HOST='S1'' (where `'S1'' is
     replaced by the real hostname of S1). To `CHANGE MASTER', add all
     information about how to connect to S1 from S2 or S3 (user,
     password, port). In `CHANGE MASTER', no need to specify the name
     of S1's binary log or binary log position to read from: we know it
     is the first binary log, from position 4, and these are the
     defaults of `CHANGE MASTER'. Finally do `START SLAVE' on S2 and
     S3, and now you have this:

                 WC
                /
                |
           WC   |  M(unavailable)
            \   |
             \  |
              v v
               S1<--S2  S3
                ^       |
                +-------+

     When M is up again, you just have to issue on it the same `CHANGE
     MASTER' as the one issued on S2 and S3, so that M becomes a slave
     of S1 and picks all the WC writes it has missed while it was down.
     Now to make M a master again (because it is the most powerful
     machine, for example), follow the preceding procedure as if S1 was
     unavailable and M was to be the new master; then during the
     procedure don't forget to run `RESET MASTER' on M before making
     S1, S2, S3 slaves of M, or they may pick old WC writes from before
     M's unavailibility.


We are currently working on integrating an automatic master election
system into MySQL, but until it is ready, you will have to create your
own monitoring tools.

Troubleshooting Replication
===========================

If you have followed the instructions, and your replication setup is not
working, first check the following:

   * *Check the error log for messages*. Many users have lost time by
     not doing this early enough.

   * Is the master logging to the binary log? Check with `SHOW MASTER
     STATUS'.  If it is, `Position' will be non-zero. If not, verify
     that you have given the master `log-bin' option and have set
     `server-id'.

   * Is the slave running? Do `SHOW SLAVE STATUS' and check that the
     `Slave_IO_Running' and `Slave_SQL_Running' values are both `Yes'.
     If not, verify slave options

   * If the slave is running, did it establish a connection with the
     master? Do `SHOW PROCESSLIST', find the I/O and SQL threads (*note
     Replication Implementation Details:: to see how they display), and
     check their `State' column. If it says `Connecting to master',
     verify the privileges for the replication user on the master,
     master hostname, your DNS setup, whether the master is actually
     running, whether it is reachable from the slave.

   * If the slave was running before but now has stopped, the reason
     usually is that some query that succeeded on the master failed on
     the slave. This should never happen if you have taken a proper
     snapshot of the master, and never modify the data on the slave
     outside of the slave thread. If it does, it is a bug; read below
     on how to report it.

   * If a query on that succeeded on the master refuses to run on the
     slave, and it does not feasible to do a full database resync (that
     is, to delete the slave's database and copy a new snapshot from
     the master), try the following:
        - First see if the slave's table was different from the
          master's. Understand how it happened (it may be a bug: read
          the Changelogs in the online MySQL manual as
          `http://www.mysql.com/documentation' to check if this is a
          known bug and if it is fixed yet).  Then make the slave's
          table identical to the master's and run `START SLAVE'.

        - If the above does not work or does not apply, try to
          understand if it would be safe to make the update manually
          (if needed) and then ignore the next query from the master.

        - If you have decided you can skip the next query, issue the
          following statements:

               mysql> SET GLOBAL SQL_SLAVE_SKIP_COUNTER = n;
               mysql> START SLAVE;

          The value of `n' should be 1 if the query does not use
          `AUTO_INCREMENT' or `LAST_INSERT_ID()'. Otherwise, the value
          should be 2.  The reason for using a value of 2 for queries
          that use `AUTO_INCREMENT' or `LAST_INSERT_ID()' is that they
          take two events in the binary log of the master.

        - Make sure you are not running into an old bug by upgrading to
          the most recent version.

        - If you are sure the slave started out perfectly in sync with
          the master, and no one has updated  the tables involved
          outside of slave thread, report the bug.

Reporting Replication Bugs
==========================

When you have determined that there is no user error involved, and
replication still either does not work at all or is unstable, it is
time to send us a bug report. We need to get as much information as
possible from you to be able to track down the bug. Please do spend
some time and effort preparing a good bug report.

If you have a repeatable way to demonstrate the bug, please enter it
into our bugs database at `http://bugs.mysql.com/'. If you have a
phantom problem (one that you cannot duplicate "at will"), use the
following procedure:

  1. Verify that no user error is involved. For example, if you update
     the slave outside of the slave thread, the data will go out of
     sync, and you can have unique key violations on updates. In this
     case, the slave thread will stop and wait for you to clean up the
     tables manually to bring them in sync.  This is not a replication
     problem; it is a problem of outside interference that causes
     replication to fail.

  2. Run the slave with the `--log-slave-updates' and `--log-bin'
     options.  They will cause the slave to log the updates that it
     receives in its own binlogs.

  3. Save all evidence before resetting the replication state. If we
     have no information or only sketchy information, it will take us
     longer to track down the problem. The evidence you should collect
     is:
        * All binary logs from the master

        * All binary logs from the slave

        * The output of `SHOW MASTER STATUS' from the master at the time
          you have discovered the problem

        * The output of `SHOW SLAVE STATUS' from the master at the time
          you have discovered the problem

        * Error logs from the master and on the slave

  4. Use `mysqlbinlog' to examine the binary logs. The following should
     be helpful to find the trouble query, for example:
          mysqlbinlog -j pos_from_slave_status /path/to/log_from_slave_status | head

Once you have collected the evidence for the phantom problem, try hard
to isolate it into a separate test case first. Then enter the problem
into our bugs database at `http://bugs.mysql.com/' with as much
information as possible.

MySQL Optimization
******************

Optimization is a complicated task because it ultimately requires
understanding of the whole system. While it may be possible to perform
some local optimizations with small knowledge of your system or
application, the more optimal you want your system to become the more
you will have to know about it.

This chapter tries to explain and give some examples of different ways
to optimize MySQL.  Remember, however, that there are always some
(increasingly harder) additional ways to make the system even faster.

Optimization Overview
=====================

The most important factor in making a system fast is the basic design.
You also need to know what kinds of things your system will be doing,
and what your bottlenecks are.

The most common bottlenecks are:
   * Disk seeks.  It takes time for the disk to find a piece of data.
     With modern disks in 1999, the mean time for this is usually lower
     than 10ms, so we can in theory do about 100 seeks a second. This
     time improves slowly with new disks and is very hard to optimize
     for a single table. The way to optimize this is to spread the data
     on more than one disk.

   * Disk reading/writing.  When the disk is at the correct position we
     need to read the data. With modern disks in 1999, one disk
     delivers something like 10-20 MB. This is easier to optimize than
     seeks because you can read in parallel from multiple disks.

   * CPU cycles.  When we have the data in main memory (or if it
     already were there) we need to process it to get to our result.
     Having small tables compared to the memory is the most common
     limiting factor. But then, with small tables speed is usually not
     the problem.

   * Memory bandwidth.  When the CPU needs more data than can fit in
     the CPU cache the main memory bandwidth becomes a bottleneck. This
     is an uncommon bottleneck for most systems, but one should be
     aware of it.

MySQL Design Limitations/Tradeoffs
----------------------------------

When using the MyISAM storage engine, MySQL uses extremely fast table
locking (multiple readers / single writers). The biggest problem with
this table type occurs when you have a mix of a steady stream of
updates and slow selects on the same table.  If this is a problem with
some tables, you can use another table type for these. *Note Table
types::.

MySQL can work with both transactional and non-transactional tables.
To be able to work smoothly with non-transactional tables (which can't
roll back if something goes wrong), MySQL has the following rules:

   * All columns 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.

   * All calculated expressions returns a value that can be used
     instead of signaling an error condition. For example 1/0 returns
     `NULL'

For more information about this, see *Note Constraints::.

The above means that one should not use MySQL to check fields content,
but one should do this in the application.

Portability
-----------

Because all SQL servers implement different parts of SQL, it takes work
to write portable SQL applications. For very simple selects/inserts it
is very easy, but the more you need the harder it gets. If you want an
application that is fast with many databases it becomes even harder!

To make a complex application portable you need to choose a number of
SQL servers that it should work with.

You can use the MySQL `crash-me' program/web-page
`http://www.mysql.com/information/crash-me.php' to find functions,
types, and limits you can use with a selection of database servers.
Crash-me now tests far from everything possible, but it is still
comprehensive with about 450 things tested.

For example, you shouldn't have column names longer than 18 characters
if you want to be able to use Informix or DB2.

Both the MySQL benchmarks and `crash-me' programs are very
database-independent.  By taking a look at how we have handled this, you
can get a feeling for what you have to do to write your application
database-independent.  The benchmarks themselves can be found in the
`sql-bench' directory in the MySQL source distribution. They are
written in Perl with DBI database interface (which solves the access
part of the problem).

See `http://www.mysql.com/information/benchmarks.html' for the results
from this benchmark.

As you can see in these results, all databases have some weak points.
That is, they have different design compromises that lead to different
behavior.

If you strive for database independence, you need to get a good feeling
for each SQL server's bottlenecks. MySQL is very fast in retrieving and
updating records, but will have a problem in mixing slow
readers/writers on the same table. Oracle, on the other hand, has a big
problem when you try to access rows that you have recently updated
(until they are flushed to disk). Transaction databases in general are
not very good at generating summary tables from log tables, as in this
case row locking is almost useless.

To get your application _really_ database-independent, you need to
define an easy extendable interface through which you manipulate your
data. As C++ is available on most systems, it makes sense to use a C++
classes interface to the databases.

If you use some specific feature for some database (like the `REPLACE'
command in MySQL), you should code a method for the other SQL servers
to implement the same feature (but slower).  With MySQL you can use the
`/*!  */' syntax to add MySQL-specific keywords to a query.  The code
inside `/**/' will be treated as a comment (ignored) by most other SQL
servers.

If high performance is more important than exactness, as in some web
applications, it is possibile to create an application layer that
caches all results to give you even higher performance. By letting old
results 'expire' after a while, you can keep the cache reasonably
fresh.  This provides a method to handle high load spikes, in which case
you can dynamically increase the cache and set the expire timeout higher
until things get back to normal.

In this case the table creation information should contain information
of the initial size of the cache and how often the table should normally
be refreshed.

What We Have Used MySQL For
---------------------------

During MySQL initial development, the features of MySQL were made to
fit our largest customer. They handle data warehousing for a couple of
the biggest retailers in Sweden.

From all stores, we get weekly summaries of all bonus card transactions,
and we are expected to provide useful information for the store owners
to help them find how their advertisement campaigns are affecting their
customers.

The data is quite huge (about 7 million summary transactions per month),
and we have data for 4-10 years that we need to present to the users.
We got weekly requests from the customers that they want to get
'instant' access to new reports from this data.

We solved this by storing all information per month in compressed
'transaction' tables. We have a set of simple macros (script) that
generates summary tables grouped by different criteria (product group,
customer id, store ...) from the transactional tables.  The reports are
web pages that are dynamically generated by a small Perl script that
parses a web page, executes the SQL statements in it, and inserts the
results. We would have used PHP or mod_perl instead but they were not
available at that time.

For graphical data we wrote a simple tool in `C' that can produce GIFs
based on the result of an SQL query (with some processing of the
result). This is also dynamically executed from the Perl script that
parses the HTML files.

In most cases a new report can simply be done by copying an existing
script and modifying the SQL query in it.  In some cases, we will need
to add more fields to an existing summary table or generate a new one,
but this is also quite simple, as we keep all transactions tables on
disk.  (Currently we have at least 50G of transactions tables and 200G
of other customer data.)

We also let our customers access the summary tables directly with ODBC
so that the advanced users can themselves experiment with the data.

We haven't had any problems handling this with quite modest Sun Ultra
SPARCstation (2x200 Mhz). We recently upgraded one of our servers to a 2
CPU 400 Mhz UltraSPARC, and we are now planning to start handling
transactions on the product level, which would mean a ten-fold increase
of data. We think we can keep up with this by just adding more disk to
our systems.

We are also experimenting with Intel-Linux to be able to get more CPU
power cheaper. Now that we have the binary portable database format (new
in Version 3.23), we will start to use this for some parts of the
application.

Our initial feelings are that Linux will perform much better on
low-to-medium load and Solaris will perform better when you start to
get a high load because of extreme disk IO, but we don't yet have
anything conclusive about this. After some discussion with a Linux
kernel developer, this might be a side effect of Linux allocating so
many resources to the batch job that the interactive performance gets
very low. This makes the machine feel very slow and unresponsive while
big batches are going. Hopefully this will be better handled in future
Linux Kernels.

The MySQL Benchmark Suite
-------------------------

This section should contain a technical description of the MySQL
benchmark suite (and `crash-me'), but that description is not written
yet. Currently, you can get a good idea of the benchmark by looking at
the code and results in the `sql-bench' directory in any MySQL source
distribution.

This benchmark suite is meant to be a benchmark that will tell any user
what operations a given SQL implementation performs well or poorly.

Note that this benchmark is single-threaded, so it measures the minimum
time for the operations performed. We plan to add a lot of
multi-threaded tests to the benchmark suite in the future.

The following tables show some comparative benchmark results for several
database servers when accessed through ODBC on a Windows NT 4.0 machine.

*Reading 2000000 rows by  *Seconds**Seconds*
index*
mysql                     367     249
mysql_odbc                464
db2_odbc                  1206
informix_odbc             121126
ms-sql_odbc               1634
oracle_odbc               20800
solid_odbc                877
sybase_odbc               17614

*Inserting 350768 rows*   *Seconds**Seconds*
mysql                     381     206
mysql_odbc                619
db2_odbc                  3460
informix_odbc             2692
ms-sql_odbc               4012
oracle_odbc               11291
solid_odbc                1801
sybase_odbc               4802

For the preceding tests, MySQL was run with an index cache size of 8M.

We have gathered some more benchmark results at
`http://www.mysql.com/information/benchmarks.html'.

Note that Oracle is not included because they asked to be removed. All
Oracle benchmarks have to be passed by Oracle! We believe that makes
Oracle benchmarks *very* biased because the above benchmarks are
supposed to show what a standard installation can do for a single
client.

To use the benchmark suite, the following requirements must be
satisified:

   * The benchmark suite is provided with MySQL source distributions,
     so you must have a source distribution.  You can either download a
     released distribution from `http://www.mysql.com/downloads/', or
     use the current development source tree (*note Installing source
     tree::).

   * The benchmark scripts are written in Perl and use the Perl DBI
     module to access database servers, so DBI must be installed.  You
     will also need the server-specific DBD drivers for each of the
     servers you want to test.  For example, to test MySQL, PostgreSQL,
     and DB2, the DBD::mysql, DBD::Pg, and DBD::DB2 modules must be
     installed.


The benchmark suite is located in the `sql-bench' directory of MySQL
source distributions.  To run the benchmark tests, change location into
that directory and execute the `run-all-tests' script:

     shell> cd sql-bench
     shell> perl run-all-tests --server=server_name

`server_name' is one of supported servers. You can get a list of all
options and supported servers by invoking `run-all-tests --help'.

`crash-me' tries to determine what features a database supports and
what its capabilities and limitations are by actually running queries.
For example, it determines:

   * What column types are supported

   * How many indexes are supported

   * What functions are supported

   * How big a query can be

   * How big a `VARCHAR' column can be

We can find the result from `crash-me' on a lot of different databases
at `http://www.mysql.com/information/crash-me.php'.

Using Your Own Benchmarks
-------------------------

You should definitely benchmark your application and database to find
out where the bottlenecks are.  By fixing it (or by replacing the
bottleneck with a "dummy module") you can then easily identify the next
bottleneck (and so on).  Even if the overall performance for your
application currently is acceptable, you should at least make a plan
for each bottleneck, and decide how to solve it if someday you really
need the extra performance.

For an example of portable benchmark programs, look at the MySQL
benchmark suite. *Note MySQL Benchmarks: MySQL Benchmarks. You can take
any program from this suite and modify it for your needs. By doing
this, you can try different solutions to your problem and test which is
really fastest for you.

Another free benchmark suite is the `Open Source Database Benchmark',
available at `http://osdb.sourceforge.net/'.

It is very common for a problem to occur only when the system is very
heavily loaded. We have had many customers who contact us when they
have a (tested) system in production and have encountered load
problems. In most cases, performance problems turn out to be due to
issues of basic database design (table scans are *not good* at high
load) or problems with the operating system or libraries. Most of the
time, these problems would be a *lot* easier to fix if the systems were
not already in production.

To avoid problems like this, you should put some effort into
benchmarking your whole application under the worst possible load!  You
can use Super Smack for this. It is available at
`http://www.mysql.com/Downloads/super-smack/super-smack-1.0.tar.gz'.
As the name suggests, it can bring your system to its knees if you ask
it, so make sure to use it only on your development systems.

Optimizing `SELECT' Statements and Other Queries
================================================

First, one thing that affects all queries: The more complex permission
system setup you have, the more overhead you get.

If you do not have any `GRANT' statements done, MySQL will optimize the
permission checking somewhat. So if you have a very high volume it may
be worth the time to avoid grants. Otherwise, more permission check
results in a larger overhead.

If your problem is with some explicit MySQL function, you can always
time this in the MySQL client:

     mysql> SELECT BENCHMARK(1000000,1+1);
     +------------------------+
     | BENCHMARK(1000000,1+1) |
     +------------------------+
     |                      0 |
     +------------------------+
     1 row in set (0.32 sec)

The above shows that MySQL can execute 1,000,000 `+' expressions in
0.32 seconds on a `PentiumII 400MHz'.

All MySQL functions should be very optimized, but there may be some
exceptions, and the `BENCHMARK(loop_count,expression)' is a great tool
to find out if this is a problem with your query.

`EXPLAIN' Syntax (Get Information About a `SELECT')
---------------------------------------------------

         EXPLAIN tbl_name
     or  EXPLAIN SELECT select_options

`EXPLAIN tbl_name' is a synonym for `DESCRIBE tbl_name' or `SHOW
COLUMNS FROM tbl_name'.

When you precede a `SELECT' statement with the keyword `EXPLAIN', MySQL
explains how it would process the `SELECT', providing information about
how tables are joined and in which order.

With the help of `EXPLAIN', you can see when you must add indexes to
tables to get a faster `SELECT' that uses indexes to find the records.

You should frequently run `ANALYZE TABLE' to update table statistics
such as cardinality of keys which can affect the choices the optimizer
makes. *Note ANALYZE TABLE::.

You can also see if the optimizer joins the tables in an optimal order.
To force the optimizer to use a specific join order for a `SELECT'
statement, add a `STRAIGHT_JOIN' clause.

For non-simple joins, `EXPLAIN' returns a row of information for each
table used in the `SELECT' statement. The tables are listed in the order
they would be read.  MySQL resolves all joins using a single-sweep
multi-join method. This means that MySQL reads a row from the first
table, then finds a matching row in the second table, then in the third
table and so on. When all tables are processed, it outputs the selected
columns and backtracks through the table list until a table is found
for which there are more matching rows. The next row is read from this
table and the process continues with the next table.

In MySQL version 4.1 the `EXPLAIN' output was changed to work better
with constructs like `UNION' statements, subqueries and derived tables.
Most notable is the addition of two new columns: `id' and `select_type'.

Output from `EXPLAIN' consists of the following columns:

`id'
     `SELECT' identifier, the sequential number of this `SELECT' within
     the query.

`select_type'
     Type of `SELECT' clause, which can be any of the following:

    `SIMPLE'
          Simple `SELECT' (not using `UNION' or subqueries).

    `PRIMARY'
          Outermost `SELECT'.

    `UNION'
          Second and further `SELECT' statements in a `UNION'.

    `DEPENDENT UNION'
          Second and further `SELECT' statements in a `UNION',
          dependent on outer subquery.

    `SUBQUERY'
          First `SELECT' in subquery.

    `DEPENDENT SUBQUERY'
          First `SELECT', dependent on outer subquery.

    `DERIVED'
          Derived table `SELECT' (subquery in `FROM' clause).

`table'
     The table to which the row of output refers.

`type'
     The join type. The different join types are listed here, ordered
     from best to worst type:

    `system'
          The table has only one row (= system table). This is a
          special case of the `const' join type.

    `const'
          The table has at most one matching row, which will be read at
          the start of the query. Because there is only one row, values
          from the column in this row can be regarded as constants by
          the rest of the optimizer. `const' tables are very fast as
          they are read only once!

          `const' is used when you compare all parts of a
          `PRIMARY'/`UNIQUE' key with constants:

               SELECT * FROM const_table WHERE primary_key=1;

               SELECT * FROM const_table
               WHERE primary_key_part1=1 AND primary_key_part2=2;

    `eq_ref'
          One row will be read from this table for each combination of
          rows from the previous tables.  This is the best possible
          join type, other than the `const' types.  It is used when all
          parts of an index are used by the join and the index is
          `UNIQUE' or a `PRIMARY KEY'.

          `eq_ref' can be used for indexed columns that is compared
          with the `=' operator.  The compared item may be a constant
          or an expression that uses columns from tables that are read
          before this table.

          In the following examples, `ref_table' will be able to use
          `eq_ref'

               SELECT * FROM ref_table,other_table
               WHERE ref_table.key_column=other_table.column;

               SELECT * FROM ref_table,other_table
               WHERE ref_table.key_column_part1=other_table.column
               AND ref_table.key_column_part2=1;

    `ref'
          All rows with matching index values will be read from this
          table for each combination of rows from the previous tables.
          `ref' is used if the join uses only a leftmost prefix of the
          key, or if the key is not `UNIQUE' or a `PRIMARY KEY' (in
          other words, if the join cannot select a single row based on
          the key value).  If the key that is used matches only a few
          rows, this join type is good.

          `ref' can be used for indexed columns that is compared with
          the `=' operator.

          In the following examples, `ref_table' will be able to use
          `ref'.

               SELECT * FROM ref_table WHERE key_column=expr;

               SELECT * FROM ref_table,other_table
               WHERE ref_table.key_column=other_table.column;

               SELECT * FROM ref_table,other_table
               WHERE ref_table.key_column_part1=other_table.column
               AND ref_table.key_column_part2=1;

    `ref_or_null'
          Like `ref', but with the addition that we will do an extra
          search for rows with `NULL'.  *Note `IS NULL' optimisation:
          IS NULL optimisation.

               SELECT * FROM ref_table WHERE key_column=expr OR key_column IS NULL;

          This join type optimization is new for MySQL 4.1.1 and is
          mostly used when resolving subqueries.

    `unique_subquery'
          This type replaces `ref' for some `IN' subqueries of the
          following form:
               value IN (SELECT primary_key FROM single_table WHERE some_exp)
          `unique_subquery' is just an index lookup function that
          replaces the subquery completely for better efficiency.

    `index_subquery'
          Like `unique_subquery', this type replaces `IN' subqueries,
          but it works for non-unique indexes:
               value IN (SELECT key_field FROM single_table WHERE some_exp)

    `range'
          Only rows that are in a given range will be retrieved, using
          an index to select the rows.  The `key' column indicates
          which index is used.  The `key_len' contains the longest key
          part that was used.  The `ref' column will be `NULL' for this
          type.

          `range' can be used for when an key column is compared to a
          constant with `=', `<>', `>', `>=', `<', `<=', `IS NULL',
          `<=>', `BETWEEN' and `IN'.

               SELECT * FROM range_table WHERE key_column = 10;

               SELECT * FROM range_table WHERE key_column BETWEEN 10 and 20;

               SELECT * FROM range_table WHERE key_column IN (10,20,30);

               SELECT * FROM range_table WHERE key_part1= 10 and key_part2 IN (10,20,30);

    `index'
          This is the same as `ALL', except that only the index tree is
          scanned.  This is usually faster than `ALL', as the index
          file is usually smaller than the datafile.

          This can be used when the query only uses columns that are
          part of one index.

    `ALL'
          A full table scan will be done for each combination of rows
          from the previous tables.  This is normally not good if the
          table is the first table not marked `const', and usually
          *very* bad in all other cases. You normally can avoid `ALL'
          by adding more indexes, so that the row can be retrieved
          based on constant values or column values from earlier tables.

`possible_keys'
     The `possible_keys' column indicates which indexes MySQL could use
     to find the rows in this table. Note that this column is totally
     independent of the order of the tables. That means that some of
     the keys in `possible_keys' may not be usable in practice with the
     generated table order.

     If this column is `NULL', there are no relevant indexes. In this
     case, you may be able to improve the performance of your query by
     examining the `WHERE' clause to see whether it refers to some
     column or columns that would be suitable for indexing.  If so,
     create an appropriate index and check the query with `EXPLAIN'
     again.  *Note `ALTER TABLE': ALTER TABLE.

     To see what indexes a table has, use `SHOW INDEX FROM tbl_name'.

`key'
     The `key' column indicates the key (index) that MySQL actually
     decided to use. The key is `NULL' if no index was chosen. To force
     MySQL to use an key listed in the `possible_keys' column, use `USE
     KEY/IGNORE KEY' in your query.  *Note `SELECT': SELECT.

     Also, running `myisamchk --analyze' (*note `myismchk' syntax:
     myisamchk syntax.) or `ANALYZE TABLE' (*note `ANALYZE TABLE':
     ANALYZE TABLE.) on the table will help the optimizer choose better
     indexes.

`key_len'
     The `key_len' column indicates the length of the key that MySQL
     decided to use.  The length is `NULL' if the `key' is `NULL'. Note
     that this tells us how many parts of a multi-part key MySQL will
     actually use.

`ref'
     The `ref' column shows which columns or constants are used with the
     `key' to select rows from the table.

`rows'
     The `rows' column indicates the number of rows MySQL believes it
     must examine to execute the query.

`Extra'
     This column contains additional information of how MySQL will
     resolve the query. Here is an explanation of the different text
     strings that can be found in this column:

    `Distinct'
          MySQL will not continue searching for more rows for the
          current row combination after it has found the first matching
          row.

    `Not exists'
          MySQL was able to do a `LEFT JOIN' optimization on the query
          and will not examine more rows in this table for the previous
          row combination after it finds one row that matches the `LEFT
          JOIN' criteria.

          Here is an example for this:

               SELECT * FROM t1 LEFT JOIN t2 ON t1.id=t2.id
               WHERE t2.id IS NULL;

          Assume that `t2.id' is defined with `NOT NULL'.  In this case
          MySQL will scan `t1' and look up the rows in `t2' through
          `t1.id'. If MySQL finds a matching row in `t2', it knows that
          `t2.id' can never be `NULL', and will not scan through the
          rest of the rows in `t2' that has the same `id'.  In other
          words, for each row in `t1', MySQL only needs to do a single
          lookup in `t2', independent of how many matching rows there
          are in `t2'.

    ``range checked for each record (index map: #)''
          MySQL didn't find a real good index to use. It will, instead,
          for each row combination in the preceding tables, do a check
          on which index to use (if any), and use this index to
          retrieve the rows from the table.  This isn't very fast but
          is faster than having to do a join without an index.

    `Using filesort'
          MySQL will need to do an extra pass to find out how to
          retrieve the rows in sorted order.  The sort is done by going
          through all rows according to the `join type' and storing the
          sort key + pointer to the row for all rows that match the
          `WHERE'. Then the keys are sorted. Finally the rows are
          retrieved in sorted order.

    `Using index'
          The column information is retrieved from the table using only
          information in the index tree without having to do an
          additional seek to read the actual row.  This can be done
          when all the used columns for the table are part of the same
          index.

    `Using temporary'
          To resolve the query MySQL will need to create a temporary
          table to hold the result.  This typically happens if you do an
          `ORDER BY' on a different column set than you did a `GROUP
          BY' on.

    `Using where'
          A `WHERE' clause will be used to restrict which rows will be
          matched against the next table or sent to the client.  If you
          don't have this information and the table is of type `ALL' or
          `index', you may have something wrong in your query (if you
          don't intend to fetch/examine all rows from the table).

     If you want to get your queries as fast as possible, you should
     look out for `Using filesort' and `Using temporary'.

You can get a good indication of how good a join is by multiplying all
values in the `rows' column of the `EXPLAIN' output. This should tell
you roughly how many rows MySQL must examine to execute the query. This
number is also used when you restrict queries with the `max_join_size'
variable.  *Note Server parameters::.

The following example shows how a `JOIN' can be optimized progressively
using the information provided by `EXPLAIN'.

Suppose you have the `SELECT' statement shown here, that you examine
using `EXPLAIN':

     EXPLAIN SELECT tt.TicketNumber, tt.TimeIn,
                 tt.ProjectReference, tt.EstimatedShipDate,
                 tt.ActualShipDate, tt.ClientID,
                 tt.ServiceCodes, tt.RepetitiveID,
                 tt.CurrentProcess, tt.CurrentDPPerson,
                 tt.RecordVolume, tt.DPPrinted, et.COUNTRY,
                 et_1.COUNTRY, do.CUSTNAME
             FROM tt, et, et AS et_1, do
             WHERE tt.SubmitTime IS NULL
                 AND tt.ActualPC = et.EMPLOYID
                 AND tt.AssignedPC = et_1.EMPLOYID
                 AND tt.ClientID = do.CUSTNMBR;

For this example, assume that:

   * The columns being compared have been declared as follows:

     *Table* *Column*   *Column
                        type*
     `tt'    `ActualPC' `CHAR(10)'
     `tt'    `AssignedPC'`CHAR(10)'
     `tt'    `ClientID' `CHAR(10)'
     `et'    `EMPLOYID' `CHAR(15)'
     `do'    `CUSTNMBR' `CHAR(15)'

   * The tables have the indexes shown here:

     *Table* *Index*
     `tt'    `ActualPC'
     `tt'    `AssignedPC'
     `tt'    `ClientID'
     `et'    `EMPLOYID' (primary
             key)
     `do'    `CUSTNMBR' (primary
             key)

   * The `tt.ActualPC' values aren't evenly distributed.

Initially, before any optimizations have been performed, the `EXPLAIN'
statement produces the following information:

     table type possible_keys                key  key_len ref  rows  Extra
     et    ALL  PRIMARY                      NULL NULL    NULL 74
     do    ALL  PRIMARY                      NULL NULL    NULL 2135
     et_1  ALL  PRIMARY                      NULL NULL    NULL 74
     tt    ALL  AssignedPC,ClientID,ActualPC NULL NULL    NULL 3872
           range checked for each record (key map: 35)

Because `type' is `ALL' for each table, this output indicates that
MySQL is generating a Cartesian product of all the tables!  This will
take quite a long time, as the product of the number of rows in each
table must be examined!  For the case at hand, this is `74 * 2135 * 74
* 3872 = 45,268,558,720' rows.  If the tables were bigger, you can only
imagine how long it would take.

One problem here is that MySQL can't (yet) use indexes on columns
efficiently if they are declared differently.  In this context,
`VARCHAR' and `CHAR' are the same unless they are declared as different
lengths. Because `tt.ActualPC' is declared as `CHAR(10)' and
`et.EMPLOYID' is declared as `CHAR(15)', there is a length mismatch.

To fix this disparity between column lengths, use `ALTER TABLE' to
lengthen `ActualPC' from 10 characters to 15 characters:

     mysql> ALTER TABLE tt MODIFY ActualPC VARCHAR(15);

Now `tt.ActualPC' and `et.EMPLOYID' are both `VARCHAR(15)'.  Executing
the `EXPLAIN' statement again produces this result:

     table type   possible_keys   key     key_len ref         rows    Extra
     tt    ALL    AssignedPC,ClientID,ActualPC NULL NULL NULL 3872    Using where
     do    ALL    PRIMARY         NULL    NULL    NULL        2135
           range checked for each record (key map: 1)
     et_1  ALL    PRIMARY         NULL    NULL    NULL        74
           range checked for each record (key map: 1)
     et    eq_ref PRIMARY         PRIMARY 15      tt.ActualPC 1

This is not perfect, but is much better (the product of the `rows'
values is now less by a factor of 74). This version is executed in a
couple of seconds.

A second alteration can be made to eliminate the column length
mismatches for the `tt.AssignedPC = et_1.EMPLOYID' and `tt.ClientID =
do.CUSTNMBR' comparisons:

     mysql> ALTER TABLE tt MODIFY AssignedPC VARCHAR(15),
         ->                MODIFY ClientID   VARCHAR(15);

Now `EXPLAIN' produces the output shown here:

     table type   possible_keys   key      key_len ref           rows Extra
     et    ALL    PRIMARY         NULL     NULL    NULL          74
     tt    ref    AssignedPC,     ActualPC 15      et.EMPLOYID   52   Using where
                  ClientID,
                  ActualPC
     et_1  eq_ref PRIMARY         PRIMARY  15      tt.AssignedPC 1
     do    eq_ref PRIMARY         PRIMARY  15      tt.ClientID   1

This is almost as good as it can get.

The remaining problem is that, by default, MySQL assumes that values in
the `tt.ActualPC' column are evenly distributed, and that isn't the
case for the `tt' table.  Fortunately, it is easy to tell MySQL about
this:

     shell> myisamchk --analyze PATH_TO_MYSQL_DATABASE/tt
     shell> mysqladmin refresh

Now the join is perfect, and `EXPLAIN' produces this result:

     table type   possible_keys key     key_len ref           rows Extra
     tt    ALL    AssignedPC    NULL    NULL    NULL          3872 Using where
                  ClientID,
                  ActualPC
     et    eq_ref PRIMARY       PRIMARY 15      tt.ActualPC   1
     et_1  eq_ref PRIMARY       PRIMARY 15      tt.AssignedPC 1
     do    eq_ref PRIMARY       PRIMARY 15      tt.ClientID   1

Note that the `rows' column in the output from `EXPLAIN' is an educated
guess from the MySQL join optimizer. To optimize a query, you should
check if the numbers are even close to the truth.  If not, you may get
better performance by using `STRAIGHT_JOIN' in your `SELECT' statement
and trying to list the tables in a different order in the `FROM' clause.

Estimating Query Performance
----------------------------

In most cases you can estimate the performance by counting disk seeks.
For small tables, you can usually find the row in 1 disk seek (as the
index is probably cached).  For bigger tables, you can estimate that
(using B++ tree indexes) you will need: `log(row_count) /
log(index_block_length / 3 * 2 / (index_length + data_pointer_length)) +
1' seeks to find a row.

In MySQL an index block is usually 1024 bytes and the data pointer is
usually 4 bytes. A 500,000 row table with an index length of 3 (medium
integer) gives you: `log(500,000)/log(1024/3*2/(3+4)) + 1' = 4 seeks.

As the above index would require about 500,000 * 7 * 3/2 = 5.2M,
(assuming that the index buffers are filled to 2/3, which is typical)
you will probably have much of the index in memory and you will probably
only need 1-2 calls to read data from the OS to find the row.

For writes, however, you will need 4 seek requests (as above) to find
where to place the new index and normally 2 seeks to update the index
and write the row.

Note that the above doesn't mean that your application will slowly
degenerate by log N!  As long as everything is cached by the OS or SQL
server, things will go only marginally slower while the table gets
bigger. After the data gets too big to be cached, things will start to
go much slower until your applications is only bound by disk-seeks
(which increase by log N). To avoid this, increase the index cache as
the data grows. *Note Server parameters::.

Speed of `SELECT' Queries
-------------------------

In general, when you want to make a slow `SELECT ... WHERE' faster, the
first thing to check is whether you can add an index. *Note MySQL
indexes: MySQL indexes. All references between different tables should
usually be done with indexes. You can use the `EXPLAIN' command to
determine which indexes are used for a `SELECT'.  *Note `EXPLAIN':
EXPLAIN.

Some general tips:

   * To help MySQL optimize queries better, run `myisamchk --analyze'
     on a table after it has been loaded with relevant data. This
     updates a value for each index part that indicates the average
     number of rows that have the same value.  (For unique indexes,
     this is always 1.)  MySQL will use this to decide which index to
     choose when you connect two tables with 'a non-constant
     expression'.  You can check the result from the `analyze' run by
     doing `SHOW INDEX FROM table_name' and examining the `Cardinality'
     column.

   * To sort an index and data according to an index, use `myisamchk
     --sort-index --sort-records=1' (if you want to sort on index 1).
     If you have a unique index from which you want to read all records
     in order according to that index, this is a good way to make that
     faster.  Note, however, that this sorting isn't written optimally
     and will take a long time for a large table!

How MySQL Optimizes `WHERE' Clauses
-----------------------------------

The `WHERE' optimizations are put in the `SELECT' part here because
they are mostly used with `SELECT', but the same optimizations apply for
`WHERE' in `DELETE' and `UPDATE' statements.

Also note that this section is incomplete. MySQL does many
optimizations, and we have not had time to document them all.

Some of the optimizations performed by MySQL are listed here:

   * Removal of unnecessary parentheses:
             ((a AND b) AND c OR (((a AND b) AND (c AND d))))
          -> (a AND b AND c) OR (a AND b AND c AND d)

   * Constant folding:
             (a<b AND b=c) AND a=5
          -> b>5 AND b=c AND a=5

   * Constant condition removal (needed because of constant folding):
             (B>=5 AND B=5) OR (B=6 AND 5=5) OR (B=7 AND 5=6)
          -> B=5 OR B=6

   * Constant expressions used by indexes are evaluated only once.

   * `COUNT(*)' on a single table without a `WHERE' is retrieved
     directly from the table information for `MyISAM' and `HEAP' tables.
     This is also done for any `NOT NULL' expression when used with
     only one table.

   * Early detection of invalid constant expressions. MySQL quickly
     detects that some `SELECT' statements are impossible and returns
     no rows.

   * `HAVING' is merged with `WHERE' if you don't use `GROUP BY' or
     group functions (`COUNT()', `MIN()'...).

   * For each sub-join, a simpler `WHERE' is constructed to get a fast
     `WHERE' evaluation for each sub-join and also to skip records as
     soon as possible.

   * All constant tables are read first, before any other tables in the
     query.  A constant table is:
        - An empty table or a table with 1 row.

        - A table that is used with a `WHERE' clause on a `UNIQUE'
          index, or a `PRIMARY KEY', where all index parts are used
          with constant expressions and the index parts are defined as
          `NOT NULL'.
     All the following tables are used as constant tables:
          mysql> SELECT * FROM t WHERE primary_key=1;
          mysql> SELECT * FROM t1,t2
              ->          WHERE t1.primary_key=1 AND t2.primary_key=t1.id;

   * The best join combination to join the tables is found by trying all
     possibilities. If all columns in `ORDER BY' and in `GROUP BY' come
     from the same table, then this table is preferred first when
     joining.

   * If there is an `ORDER BY' clause and a different `GROUP BY'
     clause, or if the `ORDER BY' or `GROUP BY' contains columns from
     tables other than the first table in the join queue, a temporary
     table is created.

   * If you use `SQL_SMALL_RESULT', MySQL will use an in-memory
     temporary table.

   * Each table index is queried, and the best index that spans fewer
     than 30% of the rows is used. If no such index can be found, a
     quick table scan is used.

   * In some cases, MySQL can read rows from the index without even
     consulting the datafile.  If all columns used from the index are
     numeric, only the index tree is used to resolve the query.

   * Before each record is output, those that do not match the `HAVING'
     clause are skipped.

Some examples of queries that are very fast:

     mysql> SELECT COUNT(*) FROM tbl_name;
     mysql> SELECT MIN(key_part1),MAX(key_part1) FROM tbl_name;
     mysql> SELECT MAX(key_part2) FROM tbl_name
         ->        WHERE key_part_1=constant;
     mysql> SELECT ... FROM tbl_name
         ->        ORDER BY key_part1,key_part2,... LIMIT 10;
     mysql> SELECT ... FROM tbl_name
         ->        ORDER BY key_part1 DESC,key_part2 DESC,... LIMIT 10;

The following queries are resolved using only the index tree (assuming
the indexed columns are numeric):

     mysql> SELECT key_part1,key_part2 FROM tbl_name WHERE key_part1=val;
     mysql> SELECT COUNT(*) FROM tbl_name
         ->        WHERE key_part1=val1 AND key_part2=val2;
     mysql> SELECT key_part2 FROM tbl_name GROUP BY key_part1;

The following queries use indexing to retrieve the rows in sorted order
without a separate sorting pass:

     mysql> SELECT ... FROM tbl_name
         ->            ORDER BY key_part1,key_part2,... ;
     mysql> SELECT ... FROM tbl_name
         ->            ORDER BY key_part1 DESC,key_part2 DESC,... ;

How MySQL Optimizes `OR' Clauses
--------------------------------

The `Merge Index' method is used to retrieve rows with several `ref',
`ref_or_null' or `range' scans and merge the results into one.  This
method is employed when the table condition is a disjunction of
conditions for which `ref', `ref_or_null', or `range' could be used
with different keys.  The `key' column contains a list of used indexes.
`key_len' contains a list of the longest key parts of the used indexes.

Example:

     SELECT * FROM table WHERE key1column = 10 OR key2column = 20;

     SELECT * FROM table WHERE
       (key1column = 10 OR key2column = 20) AND nonkeycolumn=30;

     SELECT * FROM t1,t2 WHERE
       (t1.key1 IN (1,2) OR t1.key2 LIKE 'value%') AND t2.key1=t1.somefield

     SELECT * FROM t1,t2 WHERE
       t1.key1=1 AND (t2.key1=t1.somefield OR t2.key2=t1.somefield2)

This "join" type optimization is new in MySQL 5.0.0, and represents a
significant change in behaviour with regard to indexes since the _old_
rule was that the server is only ever able to use at most one index for
each referenced table.

How MySQL Optimizes `IS NULL'
-----------------------------

MySQL can do the same optimization on `column IS NULL' as it can do
with `column = constant_value'.  For example, MySQL can use indexes and
ranges to search for `NULL' with `IS NULL'.

     SELECT * FROM table_name WHERE key_col IS NULL;

     SELECT * FROM table_name WHERE key_col <=> NULL;

     SELECT * FROM table_name WHERE key_col=# OR key_col=# OR key_col IS NULL

If you use `column_name IS NULL' on a `NOT NULL' in a `WHERE' clause on
table that is not used `OUTER JOIN' that expression will be optimized
away.

MySQL 4.1.1 can additionally optimize the combination `column = expr
AND column IS NULL', an form that is common in resolved sub queries.
`EXPLAIN' will show `ref_or_null' when this optimization is used.

This optimization can handle one `IS NULL' for any key part.

Some examples of queries that are optimized (assuming key on t2 (a,b)):

     SELECT * FROM t1 WHERE t1.a=expr OR t1.a IS NULL;

     SELECT * FROM t1,t2 WHERE t1.a=t2.a OR t2.a IS NULL;

     SELECT * FROM t1,t2 WHERE (t1.a=t2.a OR t2.a IS NULL) AND t2.b=t1.b;

     SELECT * FROM t1,t2 WHERE t1.a=t2.a AND (t2.b=t1.b OR t2.b IS NULL);

     SELECT * FROM t1,t2 WHERE (t1.a=t2.a AND t2.a IS NULL AND ...) OR (t1.a=t2.a AND t2.a IS NULL AND ...);

`ref_or_null' works by first doing a read on the reference key and
after that a separate search after rows with NULL key.

Note that the optimization can only handle one `IS NULL' level.

     SELECT * FROM t1,t2 where (t1.a=t2.a AND t2.a IS NULL) OR (t1.b=t2.b AND t2.b IS NULL);

Int the above case MySQL will only use key lookups on the part
`(t1.a=t2.a AND t2.a IS NULL)' and not be able to use the key part on
`b'.

How MySQL Optimizes `DISTINCT'
------------------------------

`DISTINCT' combined with `ORDER BY' will in many cases need a temporary
table.

Note that as `DISTINCT' may use `GROUP BY', you should be aware of how
MySQL works with in fields in `ORDER BY' or `HAVING' that are not part
of the selected fields. *Note GROUP-BY-hidden-fields::.

When combining `LIMIT row_count' with `DISTINCT', MySQL will stop as
soon as it finds `row_count' unique rows.

If you don't use columns from all used tables, MySQL will stop the
scanning of the not used tables as soon as it has found the first match.

     SELECT DISTINCT t1.a FROM t1,t2 where t1.a=t2.a;

In this case, assuming `t1' is used before `t2' (check with `EXPLAIN'),
then MySQL will stop reading from `t2' (for that particular row in
`t1') when the first row in `t2' is found.

How MySQL Optimizes `LEFT JOIN' and `RIGHT JOIN'
------------------------------------------------

`A LEFT JOIN B join_condition' in MySQL is implemented as follows:

   * The table `B' is set to be dependent on table `A' and all tables
     that `A' is dependent on.

   * The table `A' is set to be dependent on all tables (except `B')
     that are used in the `LEFT JOIN' condition.

   * The `LEFT JOIN' condition is used to decide how we should retrieve
     rows from table B. (In other words, any condition in the `WHERE'
     clause is not used).

   * All standard join optimizations are done, with the exception that
     a table is always read after all tables it is dependent on.  If
     there is a circular dependence then MySQL will issue an error.

   * All standard `WHERE' optimizations are done.

   * If there is a row in `A' that matches the `WHERE' clause, but there
     wasn't any row in `B' that matched the `ON' condition, then an
     extra `B' row is generated with all columns set to `NULL'.

   * If you use `LEFT JOIN' to find rows that don't exist in some table
     and you have the following test: `column_name IS NULL' in the
     `WHERE' part, where column_name is a column that is declared as
     `NOT NULL', then MySQL will stop searching after more rows (for a
     particular key combination) after it has found one row that
     matches the `LEFT JOIN' condition.

`RIGHT JOIN' is implemented analogously to `LEFT JOIN'.

The table read order forced by `LEFT JOIN' and `STRAIGHT JOIN' will
help the join optimizer (which calculates in which order tables should
be joined) to do its work much more quickly, as there are fewer table
permutations to check.

Note that the above means that if you do a query of type:

     SELECT * FROM a,b LEFT JOIN c ON (c.key=a.key) LEFT JOIN d (d.key=a.key)
              WHERE b.key=d.key

MySQL will do a full scan on `b' as the `LEFT JOIN' will force it to be
read before `d'.

The fix in this case is to change the query to:

     SELECT * FROM b,a LEFT JOIN c ON (c.key=a.key) LEFT JOIN d (d.key=a.key)
              WHERE b.key=d.key

Starting from 4.0.14, MySQL does the following `LEFT JOIN' optimization:

If the `WHERE' condition is always be false for the generated `NULL'
row, the `LEFT JOIN' is changed to a normal join.

For example, in the following query the `WHERE' clause would be false
if t2.column would be `NULL' so it's safe to convert to a normal join.

     SELECT * FROM t1 LEFT t2 ON (column) WHERE t2.column2 =5;
     ->
     SELECT * FROM t1,t2 WHERE t2.column2=5 AND t1.column=t2.column;

This can be made faster as MySQL can now use table `t2' before table
`t1' if this would result in a better query plan.  To force a specific
table order, use `STRAIGHT JOIN'.

How MySQL Optimizes `ORDER BY'
------------------------------

In some cases MySQL can uses index to satisfy an `ORDER BY' or `GROUP
BY' request without doing any extra sorting.

The index can also be used even if the `ORDER BY' doesn't match the
index exactly, as long as all the unused index parts and all the extra
are `ORDER BY' columns are constants in the `WHERE' clause. The
following queries will use the index to resolve the `ORDER BY' / `GROUP
BY' part:

     SELECT * FROM t1 ORDER BY key_part1,key_part2,...
     SELECT * FROM t1 WHERE key_part1=constant ORDER BY key_part2
     SELECT * FROM t1 WHERE key_part1=constant GROUP BY key_part2
     SELECT * FROM t1 ORDER BY key_part1 DESC,key_part2 DESC
     SELECT * FROM t1 WHERE key_part1=1 ORDER BY key_part1 DESC,key_part2 DESC

Some cases where MySQL can *not* use indexes to resolve the `ORDER BY':
(Note that MySQL will still use indexes to find the rows that matches
the `WHERE' clause):

   * You are doing an `ORDER BY' on different keys:

     `SELECT * FROM t1 ORDER BY key1,key2'

   * You are doing an `ORDER BY' using non-consecutive key parts.

     `SELECT * FROM t1 WHERE key2=constant ORDER BY key_part2'

   * You are mixing `ASC' and `DESC'.

     `SELECT * FROM t1 ORDER BY key_part1 DESC,key_part2 ASC'

   * The key used to fetch the rows are not the same one that is used to
     do the `ORDER BY':

     `SELECT * FROM t1 WHERE key2=constant ORDER BY key1'

   * You are joining many tables and the columns you are doing an `ORDER
     BY' on are not all from the first not-`const' table that is used to
     retrieve rows (This is the first table in the `EXPLAIN' output
     which doesn't use a `const' row fetch method).

   * You have different `ORDER BY' and `GROUP BY' expressions.

   * The used table index is an index type that doesn't store rows in
     order.  (Like the `HASH' index in `HEAP' tables).

In the cases where MySQL have to sort the result, it uses the following
algorithm:

   * Read all rows according to key or by table scanning.  Rows that
     don't match the `WHERE' clause are skipped.

   * Store the sort-key in a buffer (of size `sort_buffer').

   * When the buffer gets full, run a qsort on it and store the result
     in a temporary file.  Save a pointer to the sorted block.  (In the
     case where all rows fits into the sort buffer, no temporary file
     is created)

   * Repeat the above until all rows have been read.

   * Do a multi-merge of up to `MERGEBUFF' (7) regions to one block in
     another temporary file.  Repeat until all blocks from the first
     file are in the second file.

   * Repeat the following until there is less than `MERGEBUFF2' (15)
     blocks left.

   * On the last multi-merge, only the pointer to the row (last part of
     the sort-key) is written to a result file.

   * Now the code in `sql/records.cc' will be used to read through them
     in sorted order by using the row pointers in the result file.  To
     optimize this, we read in a big block of row pointers, sort these
     and then we read the rows in the sorted order into a row buffer
     (`read_rnd_buffer_size') .

You can with `EXPLAIN SELECT ... ORDER BY' check if MySQL can use
indexes to resolve the query.  If you get `Using filesort' in the
`extra' column, then MySQL can't use indexes to resolve the `ORDER BY'.
*Note `EXPLAIN': EXPLAIN.

If you want to have a higher `ORDER BY' speed, you should first see if
you can get MySQL to use indexes instead of having to do an extra
sorting phase. If this is not possible, then you can do:

   * Increase the size of the `sort_buffer_size' variable.

   * Increase the size of the `read_rnd_buffer_size' variable.

   * Change `tmpdir' to point to a dedicated disk with lots of empty
     space.  If you use MySQL 4.1 or later you can spread load between
     several physical disks by setting `tmpdir' to a list of paths
     separated by colon `:' (semicolon `;' on Windows). They will be
     used in round-robin fashion.  *Note:* These paths should end up on
     different *physical* disks, not different partitions of the same
     disk.

By default, MySQL sorts all `GROUP BY x,y[,...]' queries as if you
specified `ORDER BY x,y[,...]' in the query as well. If you include the
`ORDER BY' clause explicitly,  MySQL optimizes it away without any speed
penalty, though the sorting still occurs.  If a query includes `GROUP
BY' but you want to avoid the overhead of sorting the result, you can
supress sorting by specifying `ORDER BY NULL':

     INSERT INTO foo SELECT a,COUNT(*) FROM bar GROUP BY a ORDER BY NULL;

How MySQL Optimizes `LIMIT'
---------------------------

In some cases MySQL will handle the query differently when you are
using `LIMIT row_count' and not using `HAVING':

   * If you are selecting only a few rows with `LIMIT', MySQL will use
     indexes in some cases when it normally would prefer to do a full
     table scan.

   * If you use `LIMIT row_count' with `ORDER BY', MySQL will end the
     sorting as soon as it has found the first `row_count' lines
     instead of sorting the whole table.

   * When combining `LIMIT row_count' with `DISTINCT', MySQL will stop
     as soon as it finds `row_count' unique rows.

   * In some cases a `GROUP BY' can be resolved by reading the key in
     order (or do a sort on the key) and then calculate summaries until
     the key value changes.  In this case `LIMIT row_count' will not
     calculate any unnecessary `GROUP BY' values.

   * As soon as MySQL has sent the first `#' rows to the client, it
     will abort the query (if you are not using `SQL_CALC_FOUND_ROWS').

   * `LIMIT 0' will always quickly return an empty set.  This is useful
     to check the query and to get the column types of the result
     columns.

   * When the server uses temporary tables to resolve the query, the
     `LIMIT row_count' is used to calculate how much space is required.

Speed of `INSERT' Queries
-------------------------

The time to insert a record consists approximately of:

   * Connect:                 (3)

   * Sending query to server: (2)

   * Parsing query:           (2)

   * Inserting record:        (1 x size of record)

   * Inserting indexes:       (1 x number of indexes)

   * Close:                   (1)

where the numbers are somewhat proportional to the overall time. This
does not take into consideration the initial overhead to open tables
(which is done once for each concurrently running query).

The size of the table slows down the insertion of indexes by log N
(B-trees).

Some ways to speed up inserts:

   * If you are inserting many rows from the same client at the same
     time, use multiple value lists `INSERT' statements. This is much
     faster (many times in some cases) than using separate `INSERT'
     statements.  If you are adding data to non-empty table, you may
     tune up the `bulk_insert_buffer_size' variable to make it even
     faster.  *Note `bulk_insert_buffer_size': SHOW VARIABLES.

   * If you are inserting a lot of rows from different clients, you can
     get higher speed by using the `INSERT DELAYED' statement. *Note
     `INSERT': INSERT.

   * Note that with `MyISAM' tables you can insert rows at the same time
     `SELECT' statements are running if there are no deleted rows in
     the tables.

   * When loading a table from a text file, use `LOAD DATA INFILE'. This
     is usually 20 times faster than using a lot of `INSERT' statements.
     *Note `LOAD DATA': LOAD DATA.

   * It is possible with some extra work to make `LOAD DATA INFILE' run
     even faster when the table has many indexes. Use the following
     procedure:

       1. Optionally create the table with `CREATE TABLE'. For example,
          using `mysql' or Perl-DBI.

       2. Execute a `FLUSH TABLES' statement or the shell command
          `mysqladmin flush-tables'.

       3. Use `myisamchk --keys-used=0 -rq /path/to/db/tbl_name'. This
          will remove all usage of all indexes from the table.

       4. Insert data into the table with `LOAD DATA INFILE'. This will
          not update any indexes and will therefore be very fast.

       5. If you are going to only read the table in the future, run
          `myisampack' on it to make it smaller. *Note Compressed
          format::.

       6. Re-create the indexes with `myisamchk -r -q
          /path/to/db/tbl_name'. This will create the index tree in
          memory before writing it to disk, which is much faster
          because it avoids lots of disk seeks. The resulting index
          tree is also perfectly balanced.

       7. Execute a `FLUSH TABLES' statement or the shell command
          `mysqladmin flush-tables'.

     Note that `LOAD DATA INFILE' also does the above optimization if
     you insert into an empty table; the main difference with the above
     procedure is that you can let `myisamchk' allocate much more
     temporary memory for the index creation that you may want MySQL to
     allocate for every index recreation.

     Since MySQL 4.0 you can also use `ALTER TABLE tbl_name DISABLE
     KEYS' instead of `myisamchk --keys-used=0 -rq
     /path/to/db/tbl_name' and `ALTER TABLE tbl_name ENABLE KEYS'
     instead of `myisamchk -r -q /path/to/db/tbl_name'. This way you
     can also skip `FLUSH TABLES' steps.

   * You can speed up insertions that are done using multiple
     statements by locking your tables:

          mysql> LOCK TABLES a WRITE;
          mysql> INSERT INTO a VALUES (1,23),(2,34),(4,33);
          mysql> INSERT INTO a VALUES (8,26),(6,29);
          mysql> UNLOCK TABLES;

     The main speed difference is that the index buffer is flushed to
     disk only once, after all `INSERT' statements have completed.
     Normally there would be as many index buffer flushes as there are
     different `INSERT' statements. Locking is not needed if you can
     insert all rows with a single statement.

     For transactional tables, you should use `BEGIN/COMMIT' instead of
     `LOCK TABLES' to get a speedup.

     Locking will also lower the total time of multi-connection tests,
     but the maximum wait time for some threads will go up (because
     they wait for locks).  For example:

          thread 1 does 1000 inserts
          thread 2, 3, and 4 does 1 insert
          thread 5 does 1000 inserts

     If you don't use locking, 2, 3, and 4 will finish before 1 and 5.
     If you use locking, 2, 3, and 4 probably will not finish before 1
     or 5, but the total time should be about 40% faster.

     As `INSERT', `UPDATE', and `DELETE' operations are very fast in
     MySQL, you will obtain better overall performance by adding locks
     around everything that does more than about 5 inserts or updates
     in a row.  If you do very many inserts in a row, you could do a
     `LOCK TABLES' followed by an `UNLOCK TABLES' once in a while
     (about each 1000 rows) to allow other threads access to the table.
     This would still result in a nice performance gain.

     `LOAD DATA INFILE' is much faster for loading data.

To get some more speed for both `LOAD DATA INFILE' and `INSERT',
enlarge the key buffer. *Note Server parameters::.

Speed of `UPDATE' Queries
-------------------------

Update queries are optimized as a `SELECT' query with the additional
overhead of a write. The speed of the write is dependent on the size of
the data that is being updated and the number of indexes that are
updated.  Indexes that are not changed will not be updated.

Also, another way to get fast updates is to delay updates and then do
many updates in a row later. Doing many updates in a row is much quicker
than doing one at a time if you lock the table.

Note that, with dynamic record format, updating a record to a longer
total length may split the record.  So if you do this often, it is very
important to `OPTIMIZE TABLE' sometimes.  *Note `OPTIMIZE TABLE':
OPTIMIZE TABLE.

Speed of `DELETE' Queries
-------------------------

If you want to delete all rows in the table, you should use `TRUNCATE
TABLE table_name'. *Note `TRUNCATE': TRUNCATE.

The time to delete a record is exactly proportional to the number of
indexes. To delete records more quickly, you can increase the size of
the index cache. *Note Server parameters::.

Other Optimization Tips
-----------------------

Unsorted tips for faster systems:

   * Use persistent connections to the database to avoid the connection
     overhead. If you can't use persistent connections and you are
     doing a lot of new connections to the database, you may want to
     change the value of the `thread_cache_size' variable. *Note Server
     parameters::.

   * Always check that all your queries really use the indexes you have
     created in the tables. In MySQL you can do this with the `EXPLAIN'
     command. *Note Explain: (manual)EXPLAIN.

   * Try to avoid complex `SELECT' queries on `MyISAM' tables that are
     updated a lot. This is to avoid problems with table locking.

   * With `MyISAM' tables that have no deleted rows, you can insert rows
     at the same time another query is reading from it.  If this is
     important for you, you should consider methods where you don't
     have to delete rows or run `OPTIMIZE TABLE' after you have deleted
     a lot of rows.

   * Use `ALTER TABLE ... ORDER BY expr1,expr2...' if you mostly
     retrieve rows in `expr1,expr2...' order.  By using this option
     after big changes to the table, you may be able to get higher
     performance.

   * In some cases it may make sense to introduce a column that is
     'hashed' based on information from other columns. If this column
     is short and reasonably unique it may be much faster than a big
     index on many columns. In MySQL it's very easy to use this extra
     column: `SELECT * FROM table_name WHERE hash=MD5(CONCAT(col1,col2))
     AND col_1='constant' AND col_2='constant''

   * For tables that change a lot you should try to avoid all `VARCHAR'
     or `BLOB' columns. You will get dynamic row length as soon as you
     are using a single `VARCHAR' or `BLOB' column. *Note Table types::.

   * It's not normally useful to split a table into different tables
     just because the rows gets 'big'. To access a row, the biggest
     performance hit is the disk seek to find the first byte of the
     row. After finding the data most new disks can read the whole row
     fast enough for most applications. The only cases where it really
     matters to split up a table is if it's a dynamic row size table
     (see above) that you can change to a fixed row size, or if you
     very often need to scan the table and don't need most of the
     columns. *Note Table types::.

   * If you very often need to calculate things based on information
     from a lot of rows (like counts of things), it's probably much
     better to introduce a new table and update the counter in real
     time. An update of type `UPDATE table SET count=count+1 WHERE
     index_column=constant' is very fast!

     This is really important when you use MySQL table types like
     MyISAM and ISAM that only have table locking (multiple readers /
     single writers). This will also give better performance with most
     databases, as the row locking manager in this case will have less
     to do.

   * If you need to collect statistics from big log tables, use summary
     tables instead of scanning the whole table. Maintaining the
     summaries should be much faster than trying to do statistics
     'live'. It's much faster to regenerate new summary tables from the
     logs when things change (depending on business decisions) than to
     have to change the running application!

   * If possible, one should classify reports as 'live' or
     'statistical', where data needed for statistical reports are only
     generated based on summary tables that are generated from the
     actual data.

   * Take advantage of the fact that columns have default values. Insert
     values explicitly only when the value to be inserted differs from
     the default. This reduces the parsing that MySQL need to do and
     improves the insert speed.

   * In some cases it's convenient to pack and store data into a blob.
     In this case you have to add some extra code in your application
     to pack/unpack things in the blob, but this may save a lot of
     accesses at some stage.  This is practical when you have data that
     doesn't conform to a static table structure.

   * Normally you should try to keep all data non-redundant (what is
     called 3rd normal form in database theory), but you should not be
     afraid of duplicating things or creating summary tables if you
     need these to gain more speed.

   * Stored procedures or UDF (user-defined functions) may be a good
     way to get more performance.  In this case you should, however,
     always have a way to do this some other (slower) way if you use
     some database that doesn't support this.

   * You can always gain something by caching queries/answers in your
     application and trying to do many inserts/updates at the same
     time.  If your database supports lock tables (like MySQL and
     Oracle), this should help to ensure that the index cache is only
     flushed once after all updates.

   * Use `INSERT /*! DELAYED */' when you do not need to know when your
     data is written. This speeds things up because many records can be
     written with a single disk write.

   * Use `INSERT /*! LOW_PRIORITY */' when you want your selects to be
     more important.

   * Use `SELECT /*! HIGH_PRIORITY */' to get selects that jump the
     queue. That is, the select is done even if there is somebody
     waiting to do a write.

   * Use the multi-line `INSERT' statement to store many rows with one
     SQL command (many SQL servers supports this).

   * Use `LOAD DATA INFILE' to load bigger amounts of data. This is
     faster than normal inserts and will be even faster when `myisamchk'
     is integrated in `mysqld'.

   * Use `AUTO_INCREMENT' columns to make unique values.

   * Use `OPTIMIZE TABLE' once in a while to avoid fragmentation when
     using a dynamic table format. *Note `OPTIMIZE TABLE': OPTIMIZE
     TABLE.

   * Use `HEAP' tables to get more speed when possible. *Note Table
     types::.

   * When using a normal web server setup, images should be stored as
     files. That is, store only a file reference in the database.  The
     main reason for this is that a normal web server is much better at
     caching files than database contents. So it it's much easier to
     get a fast system if you are using files.

   * Use in memory tables for non-critical data that are accessed often
     (like information about the last shown banner for users that don't
     have cookies).

   * Columns with identical information in different tables should be
     declared identical and have identical names. Before Version 3.23
     you got slow joins otherwise.

     Try to keep the names simple (use `name' instead of
     `customer_name' in the customer table). To make your names portable
     to other SQL servers you should keep them shorter than 18
     characters.

   * If you need really high speed, you should take a look at the
     low-level interfaces for data storage that the different SQL
     servers support!  For example, by accessing the MySQL `MyISAM'
     directly, you could get a speed increase of 2-5 times compared to
     using the SQL interface.  To be able to do this the data must be
     on the same server as the application, and usually it should only
     be accessed by one process (because external file locking is
     really slow).  One could eliminate the above problems by
     introducing low-level `MyISAM' commands in the MySQL server (this
     could be one easy way to get more performance if needed).  By
     carefully designing the database interface, it should be quite
     easy to support this types of optimization.

   * In many cases it's faster to access data from a database (using a
     live connection) than accessing a text file, just because the
     database is likely to be more compact than the text file (if you
     are using numerical data), and this will involve fewer disk
     accesses.  You will also save code because you don't have to parse
     your text files to find line and column boundaries.

   * You can also use replication to speed things up. *Note
     Replication::.

   * Declaring a table with `DELAY_KEY_WRITE=1' will make the updating
     of indexes faster, as these are not logged to disk until the file
     is closed.  The downside is that you should run `myisamchk' on
     these tables before you start `mysqld' to ensure that they are
     okay if something killed `mysqld' in the middle.  As the key
     information can always be generated from the data, you should not
     lose anything by using `DELAY_KEY_WRITE'.

Locking Issues
==============

How MySQL Locks Tables
----------------------

You can find a discussion about different locking methods in the
appendix.  *Note Locking methods::.

All locking in MySQL is deadlock-free, except for `InnoDB' and `BDB'
type tables.  This is managed by always requesting all needed locks at
once at the beginning of a query and always locking the tables in the
same order.

`InnoDB' type tables automatically acquire their row locks and `BDB'
type tables their page locks during the processing of SQL statements,
not at the start of the transaction.

The locking method MySQL uses for `WRITE' locks works as follows:

   * If there are no locks on the table, put a write lock on it.

   * Otherwise, put the lock request in the write lock queue.

The locking method MySQL uses for `READ' locks works as follows:

   * If there are no write locks on the table, put a read lock on it.

   * Otherwise, put the lock request in the read lock queue.

When a lock is released, the lock is made available to the threads in
the write lock queue, then to the threads in the read lock queue.

This means that if you have many updates on a table, `SELECT'
statements will wait until there are no more updates.

To work around this for the case where you want to do many `INSERT' and
`SELECT' operations on a table, you can insert rows in a temporary
table and update the real table with the records from the temporary
table once in a while.

This can be done with the following code:
     mysql> LOCK TABLES real_table WRITE, insert_table WRITE;
     mysql> INSERT INTO real_table SELECT * FROM insert_table;
     mysql> TRUNCATE TABLE insert_table;
     mysql> UNLOCK TABLES;

You can use the `LOW_PRIORITY' options with `INSERT', `UPDATE' or
`DELETE' or `HIGH_PRIORITY' with `SELECT' if you want to prioritize
retrieval in some specific cases.  You can also start `mysqld' with
`--low-priority-updates' to get the same behavior.

Using `SQL_BUFFER_RESULT' can also help making table locks shorter.
*Note `SELECT': SELECT.

You could also change the locking code in `mysys/thr_lock.c' to use a
single queue.  In this case, write locks and read locks would have the
same priority, which might help some applications.

Table Locking Issues
--------------------

The table locking code in MySQL is deadlock free.

MySQL uses table locking (instead of row locking or column locking) on
all table types, except `InnoDB' and `BDB' tables, to achieve a very
high lock speed.  For large tables, table locking is much better than
row locking for most applications, but there are some pitfalls.

For `InnoDB' and `BDB' tables, MySQL only uses table locking if you
explicitly lock the table with `LOCK TABLES'.  For these table types we
recommend you to not use `LOCK TABLES' at all, because `InnoDB' uses
automatic row level locking and `BDB' uses page level locking to ensure
transaction isolation.

As of MySQL Version 3.23.7 (3.23.25 for Windows), you can insert rows
into `MyISAM' tables at the same time other threads are reading from the
table.  Note that currently this works only if there are no holes
resulting from deleted rows in the table at the time the insert is
made. When all holes has been filled with new data, concurrent inserts
will automatically be enabled again.

Table locking enables many threads to read from a table at the same
time, but if a thread wants to write to a table, it must first get
exclusive access.  During the update, all other threads that want to
access this particular table will wait until the update is ready.

As updates on tables normally are considered to be more important than
`SELECT', all statements that update a table have higher priority than
statements that retrieve information from a table. This should ensure
that updates are not 'starved' because one issues a lot of heavy
queries against a specific table. (You can change this by using
`LOW_PRIORITY' with the statement that does the update or
`HIGH_PRIORITY' with the `SELECT' statement.)

Starting from MySQL Version 3.23.7 one can use the
`max_write_lock_count' variable to force MySQL to temporary give all
`SELECT' statements, that wait for a table, a higher priority after a
specific number of inserts on a table.

Table locking is, however, not very good under the following scenario:

   * A client issues a `SELECT' that takes a long time to run.

   * Another client then issues an `UPDATE' on a used table. This client
     will wait until the `SELECT' is finished.

   * Another client issues another `SELECT' statement on the same
     table. As `UPDATE' has higher priority than `SELECT', this `SELECT'
     will wait for the `UPDATE' to finish.  It will also wait for the
     first `SELECT' to finish!

   * A thread is waiting for something like `full disk', in which case
     all threads that wants to access the problem table will also be
     put in a waiting state until more disk space is made available.

Some possible solutions to this problem are:

   * Try to get the `SELECT' statements to run faster. You may have to
     create some summary tables to do this.

   * Start `mysqld' with `--low-priority-updates'.  This will give all
     statements that update (modify) a table lower priority than a
     `SELECT' statement. In this case the last `SELECT' statement in
     the previous scenario would execute before the `INSERT' statement.

   * You can give a specific `INSERT', `UPDATE', or `DELETE' statement
     lower priority with the `LOW_PRIORITY' attribute.

   * Start `mysqld' with a low value for `max_write_lock_count' to give
     `READ' locks after a certain number of `WRITE' locks.

   * You can specify that all updates from a specific thread should be
     done with low priority by using the SQL command: `SET
     LOW_PRIORITY_UPDATES=1'.  *Note `SET': SET OPTION.

   * You can specify that a specific `SELECT' is very important with the
     `HIGH_PRIORITY' attribute. *Note `SELECT': SELECT.

   * If you have problems with `INSERT' combined with `SELECT', switch
     to use the new `MyISAM' tables as these support concurrent
     `SELECT' and `INSERT' statements.

   * If you mainly mix `INSERT' and `SELECT' statements, the `DELAYED'
     attribute to `INSERT' will probably solve your problems.  *Note
     `INSERT': INSERT.

   * If you have problems with `SELECT' and `DELETE', the `LIMIT'
     option to `DELETE' may help. *Note `DELETE': DELETE.

Optimizing Database Structure
=============================

Design Choices
--------------

MySQL keeps row data and index data in separate files. Many (almost
all) other databases mix row and index data in the same file. We
believe that the MySQL choice is better for a very wide range of modern
systems.

Another way to store the row data is to keep the information for each
column in a separate area (examples are SDBM and Focus). This will
cause a performance hit for every query that accesses more than one
column. Because this degenerates so quickly when more than one column
is accessed, we believe that this model is not good for general purpose
databases.

The more common case is that the index and data are stored together (as
in Oracle/Sybase et al). In this case you will find the row information
at the leaf page of the index. The good thing with this layout is that
it, in many cases, depending on how well the index is cached, saves a
disk read.  The bad things with this layout are:

   * Table scanning is much slower because you have to read through the
     indexes to get at the data.

   * You can't use only the index table to retrieve data for a query.

   * You lose a lot of space, as you must duplicate indexes from the
     nodes (as you can't store the row in the nodes).

   * Deletes will degenerate the table over time (as indexes in nodes
     are usually not updated on delete).

   * It's harder to cache only the index data.

Get Your Data as Small as Possible
----------------------------------

One of the most basic optimization is to get your data (and indexes) to
take as little space on the disk (and in memory) as possible. This can
give huge improvements because disk reads are faster and normally less
main memory will be used. Indexing also takes less resources if done on
smaller columns.

MySQL supports a lot of different table types and row formats.
Choosing the right table format may give you a big performance gain.
*Note Table types::.

You can get better performance on a table and minimise storage space
using the techniques listed here:

   * Use the most efficient (smallest) types possible. MySQL has many
     specialized types that save disk space and memory.

   * Use the smaller integer types if po