Chapter 5. Database Administration <?php include("header_c.php");?><link rel="start" href="index.html" title="MySQL 3.23, 4.0, 4.1 Reference Manual"><link rel="up" href="index.html" title="MySQL 3.23, 4.0, 4.1 Reference Manual"><link rel="prev" href="using-mysql-programs.html" title="Chapter 4. Using MySQL Programs"><link rel="next" href="replication.html" title="Chapter 6. Replication in MySQL"></head><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. Database Administration</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using-mysql-programs.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="replication.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="database-administration"></a>Chapter 5. Database Administration</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="database-administration.html#server-side-scripts">5.1. The MySQL Server and Server Startup Scripts</a></span></dt><dd><dl><dt><span class="section"><a href="database-administration.html#server-side-overview">5.1.1. Overview of the Server-Side Scripts and Utilities</a></span></dt><dt><span class="section"><a href="database-administration.html#mysqld-max">5.1.2. The <span><strong class="command">mysqld-max</strong></span> Extended MySQL Server</a></span></dt><dt><span class="section"><a href="database-administration.html#mysqld-safe">5.1.3. mysqld_safe — MySQL Server Startup Script</a></span></dt><dt><span class="section"><a href="database-administration.html#mysql-server">5.1.4. mysql.server — MySQL Server Startup Script</a></span></dt><dt><span class="section"><a href="database-administration.html#mysqld-multi">5.1.5. mysqld_multi — Program for Managing Multiple MySQL Servers</a></span></dt></dl></dd><dt><span class="section"><a href="database-administration.html#mysqld">5.2. mysqld — The MySQL Server</a></span></dt><dd><dl><dt><span class="section"><a href="database-administration.html#server-options">5.2.1. <span><strong class="command">mysqld</strong></span> Command-Line Options</a></span></dt><dt><span class="section"><a href="database-administration.html#server-sql-mode">5.2.2. The Server SQL Mode</a></span></dt><dt><span class="section"><a href="database-administration.html#server-system-variables">5.2.3. Server System Variables</a></span></dt><dt><span class="section"><a href="database-administration.html#server-status-variables">5.2.4. Server Status Variables</a></span></dt></dl></dd><dt><span class="section"><a href="database-administration.html#mysql-fix-privilege-tables">5.3. mysql_fix_privilege_tables — Upgrade MySQL System Tables</a></span></dt><dt><span class="section"><a href="database-administration.html#server-shutdown">5.4. The MySQL Server Shutdown Process</a></span></dt><dt><span class="section"><a href="database-administration.html#security">5.5. General Security Issues</a></span></dt><dd><dl><dt><span class="section"><a href="database-administration.html#security-guidelines">5.5.1. General Security Guidelines</a></span></dt><dt><span class="section"><a href="database-administration.html#security-against-attack">5.5.2. Making MySQL Secure Against Attackers</a></span></dt><dt><span class="section"><a href="database-administration.html#privileges-options">5.5.3. Startup Options for <span><strong class="command">mysqld</strong></span> Concerning Security</a></span></dt><dt><span class="section"><a href="database-administration.html#load-data-local">5.5.4. Security Issues with <code class="literal">LOAD DATA LOCAL</code></a></span></dt></dl></dd><dt><span class="section"><a href="database-administration.html#privilege-system">5.6. The MySQL Access Privilege System</a></span></dt><dd><dl><dt><span class="section"><a href="database-administration.html#what-privileges">5.6.1. What the Privilege System Does</a></span></dt><dt><span class="section"><a href="database-administration.html#privileges">5.6.2. How the Privilege System Works</a></span></dt><dt><span class="section"><a href="database-administration.html#privileges-provided">5.6.3. Privileges Provided by MySQL</a></span></dt><dt><span class="section"><a href="database-administration.html#connecting">5.6.4. Connecting to the MySQL Server</a></span></dt><dt><span class="section"><a href="database-administration.html#connection-access">5.6.5. Access Control, Stage 1: Connection Verification</a></span></dt><dt><span class="section"><a href="database-administration.html#request-access">5.6.6. Access Control, Stage 2: Request Verification</a></span></dt><dt><span class="section"><a href="database-administration.html#privilege-changes">5.6.7. When Privilege Changes Take Effect</a></span></dt><dt><span class="section"><a href="database-administration.html#access-denied">5.6.8. Causes of <code class="literal">Access denied</code> Errors</a></span></dt><dt><span class="section"><a href="database-administration.html#password-hashing">5.6.9. Password Hashing in MySQL 4.1</a></span></dt></dl></dd><dt><span class="section"><a href="database-administration.html#user-account-management">5.7. MySQL User Account Management</a></span></dt><dd><dl><dt><span class="section"><a href="database-administration.html#user-names">5.7.1. MySQL Usernames and Passwords</a></span></dt><dt><span class="section"><a href="database-administration.html#adding-users">5.7.2. Adding New User Accounts to MySQL</a></span></dt><dt><span class="section"><a href="database-administration.html#removing-users">5.7.3. Removing User Accounts from MySQL</a></span></dt><dt><span class="section"><a href="database-administration.html#user-resources">5.7.4. Limiting Account Resources</a></span></dt><dt><span class="section"><a href="database-administration.html#passwords">5.7.5. Assigning Account Passwords</a></span></dt><dt><span class="section"><a href="database-administration.html#password-security">5.7.6. Keeping Your Password Secure</a></span></dt><dt><span class="section"><a href="database-administration.html#secure-connections">5.7.7. Using Secure Connections</a></span></dt></dl></dd><dt><span class="section"><a href="database-administration.html#disaster-prevention">5.8. Backup and Recovery</a></span></dt><dd><dl><dt><span class="section"><a href="database-administration.html#backup">5.8.1. Database Backups</a></span></dt><dt><span class="section"><a href="database-administration.html#backup-strategy-example">5.8.2. Example Backup and Recovery Strategy</a></span></dt><dt><span class="section"><a href="database-administration.html#point-in-time-recovery">5.8.3. Point-in-Time Recovery</a></span></dt><dt><span class="section"><a href="database-administration.html#table-maintenance">5.8.4. Table Maintenance and Crash Recovery</a></span></dt><dt><span class="section"><a href="database-administration.html#myisamchk">5.8.5. myisamchk — <code class="literal">MyISAM</code> Table-Maintenance Utility</a></span></dt><dt><span class="section"><a href="database-administration.html#maintenance-schedule">5.8.6. Setting Up a Table Maintenance Schedule</a></span></dt><dt><span class="section"><a href="database-administration.html#table-info">5.8.7. Getting Information About a Table</a></span></dt></dl></dd><dt><span class="section"><a href="database-administration.html#localisation">5.9. MySQL Localization and International Usage</a></span></dt><dd><dl><dt><span class="section"><a href="database-administration.html#character-sets">5.9.1. The Character Set Used for Data and Sorting</a></span></dt><dt><span class="section"><a href="database-administration.html#languages">5.9.2. Setting the Error Message Language</a></span></dt><dt><span class="section"><a href="database-administration.html#adding-character-set">5.9.3. Adding a New Character Set</a></span></dt><dt><span class="section"><a href="database-administration.html#character-arrays">5.9.4. The Character Definition Arrays</a></span></dt><dt><span class="section"><a href="database-administration.html#string-collating">5.9.5. String Collating Support</a></span></dt><dt><span class="section"><a href="database-administration.html#multi-byte-characters">5.9.6. Multi-Byte Character Support</a></span></dt><dt><span class="section"><a href="database-administration.html#problems-with-character-sets">5.9.7. Problems With Character Sets</a></span></dt><dt><span class="section"><a href="database-administration.html#time-zone-support">5.9.8. MySQL Server Time Zone Support</a></span></dt></dl></dd><dt><span class="section"><a href="database-administration.html#log-files">5.10. The MySQL Log Files</a></span></dt><dd><dl><dt><span class="section"><a href="database-administration.html#error-log">5.10.1. The Error Log</a></span></dt><dt><span class="section"><a href="database-administration.html#query-log">5.10.2. The General Query Log</a></span></dt><dt><span class="section"><a href="database-administration.html#update-log">5.10.3. The Update Log</a></span></dt><dt><span class="section"><a href="database-administration.html#binary-log">5.10.4. The Binary Log</a></span></dt><dt><span class="section"><a href="database-administration.html#slow-query-log">5.10.5. The Slow Query Log</a></span></dt><dt><span class="section"><a href="database-administration.html#log-file-maintenance">5.10.6. Log File Maintenance</a></span></dt></dl></dd><dt><span class="section"><a href="database-administration.html#multiple-servers">5.11. Running Multiple MySQL Servers on the Same Machine</a></span></dt><dd><dl><dt><span class="section"><a href="database-administration.html#multiple-windows-servers">5.11.1. Running Multiple Servers on Windows</a></span></dt><dt><span class="section"><a href="database-administration.html#multiple-unix-servers">5.11.2. Running Multiple Servers on Unix</a></span></dt><dt><span class="section"><a href="database-administration.html#multiple-server-clients">5.11.3. Using Client Programs in a Multiple-Server Environment</a></span></dt></dl></dd><dt><span class="section"><a href="database-administration.html#query-cache">5.12. The MySQL Query Cache</a></span></dt><dd><dl><dt><span class="section"><a href="database-administration.html#query-cache-how">5.12.1. How the Query Cache Operates</a></span></dt><dt><span class="section"><a href="database-administration.html#query-cache-in-select">5.12.2. Query Cache <code class="literal">SELECT</code> Options</a></span></dt><dt><span class="section"><a href="database-administration.html#query-cache-configuration">5.12.3. Query Cache Configuration</a></span></dt><dt><span class="section"><a href="database-administration.html#query-cache-status-and-maintenance">5.12.4. Query Cache Status and Maintenance</a></span></dt></dl></dd></dl></div><p> This chapter covers topics that deal with administering a MySQL installation, such as configuring the server, managing user accounts, and performing backups. </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="server-side-scripts"></a>5.1. The MySQL Server and Server Startup Scripts</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="database-administration.html#server-side-overview">5.1.1. Overview of the Server-Side Scripts and Utilities</a></span></dt><dt><span class="section"><a href="database-administration.html#mysqld-max">5.1.2. The <span><strong class="command">mysqld-max</strong></span> Extended MySQL Server</a></span></dt><dt><span class="section"><a href="database-administration.html#mysqld-safe">5.1.3. mysqld_safe — MySQL Server Startup Script</a></span></dt><dt><span class="section"><a href="database-administration.html#mysql-server">5.1.4. mysql.server — MySQL Server Startup Script</a></span></dt><dt><span class="section"><a href="database-administration.html#mysqld-multi">5.1.5. mysqld_multi — Program for Managing Multiple MySQL Servers</a></span></dt></dl></div><p> The MySQL server, <span><strong class="command">mysqld</strong></span>, 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. </p><p> This section provides an overview of the server and related programs, and information about server startup scripts. Information about configuring the server itself is given in <a href="database-administration.html#mysqld" title="5.2. mysqld — The MySQL Server">Section 5.2, “mysqld — The MySQL Server”</a>. </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="server-side-overview"></a>5.1.1. Overview of the Server-Side Scripts and Utilities</h3></div></div></div><a class="indexterm" name="id2767611"></a><p> All MySQL programs take many different options. However, every MySQL program provides a <code class="option">--help</code> option that you can use to get a description of the program's options. For example, try <span><strong class="command">mysqld --help</strong></span>. </p><p> You can override default options for all standard programs by specifying options on the command line or in an option file. <a href="using-mysql-programs.html#program-options" title="4.3. Specifying Program Options">Section 4.3, “Specifying Program Options”</a>. </p><p> The following list briefly describes the MySQL server and server-related programs: </p><div class="itemizedlist"><ul type="disc"><li><p> <a class="indexterm" name="id2767658"></a> <code class="literal">mysqld</code> </p><p> The SQL daemon (that is, the MySQL server). To use client programs, this program must be running, because clients gain access to databases by connecting to the server. See <a href="database-administration.html#mysqld" title="5.2. mysqld — The MySQL Server">Section 5.2, “mysqld — The MySQL Server”</a>. </p></li><li><p> <a class="indexterm" name="id2767687"></a> <code class="literal">mysqld-max</code> </p><p> A version of the server that includes additional features. See <a href="database-administration.html#mysqld-max" title="5.1.2. The mysqld-max Extended MySQL Server">Section 5.1.2, “The <span><strong class="command">mysqld-max</strong></span> Extended MySQL Server”</a>. </p></li><li><p> <a class="indexterm" name="id2767714"></a> <code class="literal">mysqld_safe</code> </p><p> A server startup script. <span><strong class="command">mysqld_safe</strong></span> attempts to start <span><strong class="command">mysqld-max</strong></span> if it exists, and <span><strong class="command">mysqld</strong></span> otherwise. See <a href="database-administration.html#mysqld-safe" title="5.1.3. mysqld_safe — MySQL Server Startup Script">Section 5.1.3, “mysqld_safe — MySQL Server Startup Script”</a>. </p></li><li><p> <a class="indexterm" name="id2767753"></a> <code class="literal">mysql.server</code> </p><p> 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 <span><strong class="command">mysqld_safe</strong></span> to start the MySQL server. See <a href="database-administration.html#mysql-server" title="5.1.4. mysql.server — MySQL Server Startup Script">Section 5.1.4, “mysql.server — MySQL Server Startup Script”</a>. </p></li><li><p> <a class="indexterm" name="id2767787"></a> <code class="literal">mysqld_multi</code> </p><p> A server startup script that can start or stop multiple servers installed on the system. See <a href="database-administration.html#mysqld-multi" title="5.1.5. mysqld_multi — Program for Managing Multiple MySQL Servers">Section 5.1.5, “mysqld_multi — Program for Managing Multiple MySQL Servers”</a>. </p></li><li><p> <a class="indexterm" name="id2767816"></a> <code class="literal">mysql_install_db</code> </p><p> This script creates the MySQL grant tables with default privileges. It is usually executed only once, when first installing MySQL on a system. See <a href="installing.html#unix-post-installation" title="2.9.2. Unix Post-Installation Procedures">Section 2.9.2, “Unix Post-Installation Procedures”</a>. </p></li><li><p> <a class="indexterm" name="id2767845"></a> <code class="literal">mysql_fix_privilege_tables</code> </p><p> This script is used after an upgrade install operation, to update the grant tables with any changes that have been made in newer versions of MySQL. See <a href="installing.html#upgrading-grant-tables" title="2.10.3. Upgrading the Grant Tables">Section 2.10.3, “Upgrading the Grant Tables”</a>. </p></li></ul></div><p> There are several other programs that also are run on the server host: </p><div class="itemizedlist"><ul type="disc"><li><p> <a class="indexterm" name="id2767890"></a> <code class="literal">myisamchk</code> </p><p> A utility to describe, check, optimize, and repair <code class="literal">MyISAM</code> tables. <span><strong class="command">myisamchk</strong></span> is described in <a href="database-administration.html#myisamchk" title="5.8.5. myisamchk — MyISAM Table-Maintenance Utility">Section 5.8.5, “myisamchk — <code class="literal">MyISAM</code> Table-Maintenance Utility”</a>. </p></li><li><p> <a class="indexterm" name="id2767925"></a> <code class="literal">make_binary_distribution</code> </p><p> This program makes a binary release of a compiled MySQL. This could be sent by FTP to <code class="filename">/pub/mysql/upload/</code> on <code class="literal">ftp.mysql.com</code> for the convenience of other MySQL users. </p></li><li><p> <a class="indexterm" name="id2767957"></a> <code class="literal">mysqlbug</code> </p><p> The MySQL bug reporting script. It can be used to send a bug report to the MySQL mailing list. (You can also visit <a href="http://bugs.mysql.com/" target="_top">http://bugs.mysql.com/</a> to file a bug report online. See <a href="introduction.html#bug-reports" title="1.7.1.3. How to Report Bugs or Problems">Section 1.7.1.3, “How to Report Bugs or Problems”</a>.) </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mysqld-max"></a>5.1.2. The <span><strong class="command">mysqld-max</strong></span> Extended MySQL Server</h3></div></div></div><a class="indexterm" name="id2768008"></a><p> A MySQL-Max server is a version of the <span><strong class="command">mysqld</strong></span> MySQL server that has been built to include additional features. </p><p> The distribution to use depends on your platform: </p><div class="itemizedlist"><ul type="disc"><li><p> For Windows, MySQL binary distributions include both the standard server (<code class="literal">mysqld.exe</code>) and the MySQL-Max server (<span><strong class="command">mysqld-max.exe</strong></span>), so you need not get a special distribution. Just use a regular Windows distribution, available at <a href="http://dev.mysql.com/downloads/" target="_top">http://dev.mysql.com/downloads/</a>. See <a href="installing.html#windows-installation" title="2.3. Installing MySQL on Windows">Section 2.3, “Installing MySQL on Windows”</a>. </p></li><li><p> For Linux, if you install MySQL using RPM distributions, use the regular <code class="literal">MySQL-server</code> RPM first to install a standard server named <span><strong class="command">mysqld</strong></span>. Then use the <code class="literal">MySQL-Max</code> RPM to install a server named <span><strong class="command">mysqld-max</strong></span>. The <code class="literal">MySQL-Max</code> RPM presupposes that you have installed the regular server RPM. See <a href="installing.html#linux-rpm" title="2.4. Installing MySQL on Linux">Section 2.4, “Installing MySQL on Linux”</a> for more information on the Linux RPM packages. </p></li><li><p> All other MySQL-Max distributions contain a single server that is named <span><strong class="command">mysqld</strong></span> but that has the additional features included. </p></li></ul></div><p> You can find the MySQL-Max binaries on the MySQL AB Web site at <a href="http://dev.mysql.com/downloads/mysql-4.0.html" target="_top">http://dev.mysql.com/downloads/mysql-4.0.html</a>. </p><p> MySQL AB builds the MySQL-Max servers by using the following <span><strong class="command">configure</strong></span> options: </p><div class="itemizedlist"><ul type="disc"><li><p> <code class="option">--with-server-suffix=-max</code> </p><p> This option adds a <code class="literal">-max</code> suffix to the <span><strong class="command">mysqld</strong></span> version string. </p></li><li><p> <code class="option">--with-innodb</code> </p><p> This option enables support for the <code class="literal">InnoDB</code> storage engine. MySQL-Max servers always include <code class="literal">InnoDB</code> support, but this option actually is needed only for MySQL 3.23. From MySQL 4.0 onwards, <code class="literal">InnoDB</code> is included by default in all binary distributions, so you do not need a MySQL-Max server merely to obtain <code class="literal">InnoDB</code> support. </p></li><li><p> <code class="option">--with-bdb</code> </p><p> This option enables support for the Berkeley DB (<code class="literal">BDB</code>) storage engine. </p></li><li><p> <code class="option">--with-blackhole-storage-engine</code> </p><p> This option enables support for the <code class="literal">BLACKHOLE</code> storage engine in MySQL 4.1.11 and newer. </p></li><li><p> <code class="literal">USE_SYMDIR</code> </p><p> This define is enabled to turn on database symbolic link support for Windows. (This applies only before MySQL 4.0. As of MySQL 4.0, symbolic link support is available for all Windows servers, so a Max server is not needed to take advantage of this feature.) </p></li><li><p> <code class="option">--with-ndbcluster</code> </p><p> This option enables support for the NDB Cluster storage engine in MySQL 4.1.2 and newer. <span class="emphasis"><em>Currently, MySQL Cluster is supported on Linux, Solaris, and Mac OS X only</em></span>. </p></li></ul></div><p> 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. </p><p> MySQL-Max servers include the BerkeleyDB (<code class="literal">BDB</code>) storage engine whenever possible, but not all platforms support <code class="literal">BDB</code>. </p><p> MySQL-Max servers versions 4.1.2 and above for Solaris, Mac OS X, and Linux (on most platforms) include support for the <code class="literal">NDB Cluster</code> storage engine. Note that the server must be started with the <code class="option">ndbcluster</code> option in order to run the server as part of a MySQL Cluster. (For details, see <a href="ndbcluster.html#mysql-cluster-configuration" title="16.4. MySQL Cluster Configuration">Section 16.4, “MySQL Cluster Configuration”</a>.) </p><p> The following table shows on which platforms allow MySQL-Max binaries include support for <code class="literal">BDB</code> and/or <code class="literal">NDB Cluster</code>: </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><tbody><tr><td><span class="bold"><strong>System</strong></span></td><td><span class="bold"><strong>BDB Support</strong></span></td><td><span class="bold"><strong>NDB Support</strong></span></td></tr><tr><td>AIX 4.3</td><td>N</td><td>N</td></tr><tr><td>HP-UX 11.0</td><td>N</td><td>N</td></tr><tr><td>Linux-Alpha</td><td>N</td><td>Y</td></tr><tr><td>Linux-IA-64</td><td>N</td><td>N</td></tr><tr><td>Linux-Intel</td><td>Y</td><td>Y</td></tr><tr><td>Mac OS X</td><td>N</td><td>N</td></tr><tr><td>NetWare</td><td>N</td><td>N</td></tr><tr><td>SCO OSR5</td><td>Y</td><td>N</td></tr><tr><td>Solaris-SPARC</td><td>Y</td><td>Y</td></tr><tr><td>Solaris-Intel</td><td>N</td><td>Y</td></tr><tr><td>UnixWare</td><td>Y</td><td>N</td></tr><tr><td>Windows NT/2000/XP</td><td>Y</td><td>N</td></tr></tbody></table></div><p> To find out which storage engines your server supports, issue the following statement: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SHOW ENGINES;</code></strong> +------------+---------+------------------------------------------------------------+ | Engine | Support | Comment | +------------+---------+------------------------------------------------------------+ | MyISAM | DEFAULT | Default engine as of MySQL 3.23 with great performance | | HEAP | YES | Alias for MEMORY | | MEMORY | YES | Hash based, stored in memory, useful for temporary tables | | MERGE | YES | Collection of identical MyISAM tables | | MRG_MYISAM | YES | Alias for MERGE | | ISAM | NO | Obsolete storage engine, now replaced by MyISAM | | MRG_ISAM | NO | Obsolete storage engine, now replaced by MERGE | | InnoDB | YES | Supports transactions, row-level locking, and foreign keys | | INNOBASE | YES | Alias for INNODB | | BDB | YES | Supports transactions and page-level locking | | BERKELEYDB | YES | Alias for BDB | | NDBCLUSTER | NO | Clustered, fault-tolerant, memory-based tables | | NDB | NO | Alias for NDBCLUSTER | | EXAMPLE | NO | Example storage engine | | ARCHIVE | NO | Archive storage engine | | CSV | NO | CSV storage engine | | BLACKHOLE | NO | Storage engine designed to act as null storage | +------------+---------+------------------------------------------------------------+ 17 rows in set (0.02 sec) </pre><p> (See also <a href="sql-syntax.html#show-engines" title="13.5.4.8. SHOW ENGINES Syntax">Section 13.5.4.8, “<code class="literal">SHOW ENGINES</code> Syntax”</a>.) </p><p> Before MySQL 4.1.2, <code class="literal">SHOW ENGINES</code> is unavailable. Use the following statement instead and check the value of the variable for the storage engine in which you are interested: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SHOW VARIABLES LIKE 'have%';</code></strong> +-----------------------+-------+ | Variable_name | Value | +-----------------------+-------+ | have_archive | NO | | have_bdb | YES | | have_blackhole_engine | NO | | have_compress | YES | | have_crypt | NO | | have_csv | NO | | have_example_engine | NO | | have_geometry | YES | | have_innodb | YES | | have_isam | NO | | have_ndbcluster | NO | | have_openssl | NO | | have_query_cache | YES | | have_raid | NO | | have_rtree_keys | YES | | have_symlink | YES | +-----------------------+-------+ 16 rows in set (0.00 sec) </pre><p> The precise output from these <code class="literal">SHOW</code> commands will vary according to the MySQL version used (and the features which are enabled). The values in the second column indicate the server's level of support for each feature, as shown here: </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td><span class="bold"><strong>Value</strong></span></td><td><span class="bold"><strong>Meaning</strong></span></td></tr><tr><td><code class="literal">YES</code></td><td>The feature is supported and is active.</td></tr><tr><td><code class="literal">NO</code></td><td>The feature is not supported.</td></tr><tr><td><code class="literal">DISABLED</code></td><td>The feature is supported but has been disabled.</td></tr></tbody></table></div><p> A value of <code class="literal">NO</code> means that the server was compiled without support for the feature, so it cannot be activated at runtime. </p><p> A value of <code class="literal">DISABLED</code> 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 <code class="literal"><em class="replaceable"><code>host_name</code></em>.err</code> error log file should contain a reason indicating why the option is disabled. </p><p> One situation in which you might see <code class="literal">DISABLED</code> occurs with MySQL 3.23 when the <code class="literal">InnoDB</code> storage engine is compiled in. In MySQL 3.23, you must supply at least the <code class="literal">innodb_data_file_path</code> option at runtime to set up the <code class="literal">InnoDB</code> tablespace. Without this option, <code class="literal">InnoDB</code> disables itself. See <a href="innodb.html#innodb-in-mysql-3-23" title="15.3. InnoDB in MySQL 3.23">Section 15.3, “<code class="literal">InnoDB</code> in MySQL 3.23”</a>. You can specify configuration options for the <code class="literal">BDB</code> storage engine, too, but <code class="literal">BDB</code> does not disable itself if you do not provide them. See <a href="storage-engines.html#bdb-start" title="14.4.3. BDB Startup Options">Section 14.4.3, “<code class="literal">BDB</code> Startup Options”</a>. </p><p> You might also see <code class="literal">DISABLED</code> for the <code class="literal">InnoDB</code>, <code class="literal">BDB</code>, or <code class="literal">ISAM</code> storage engines if the server was compiled to support them, but was started with the <code class="option">--skip-innodb</code>, <code class="option">--skip-bdb</code>, or <code class="option">--skip-isam</code> options at runtime. This is also the case where the server supports <code class="literal">NDB Cluster</code>, but was not started with the <code class="option">ndbcluster</code> option. </p><p> As of version 3.23, all MySQL servers support <code class="literal">MyISAM</code> tables, because <code class="literal">MyISAM</code> is the default storage engine. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mysqld-safe"></a>5.1.3. mysqld_safe — MySQL Server Startup Script</h3></div></div></div><p> <span><strong class="command">mysqld_safe</strong></span> is the recommended way to start a <span><strong class="command">mysqld</strong></span> server on Unix and NetWare. <span><strong class="command">mysqld_safe</strong></span> adds some safety features such as restarting the server when an error occurs and logging runtime information to an error log file. NetWare-specific behaviors are listed later in this section. </p><p> <span class="bold"><strong>Note</strong></span>: Before MySQL 4.0, <span><strong class="command">mysqld_safe</strong></span> is named <span><strong class="command">safe_mysqld</strong></span>. To preserve backward compatibility, MySQL binary distributions for some time will include <span><strong class="command">safe_mysqld</strong></span> as a symbolic link to <span><strong class="command">mysqld_safe</strong></span>. </p><p> By default, <span><strong class="command">mysqld_safe</strong></span> tries to start an executable named <span><strong class="command">mysqld-max</strong></span> if it exists, or <span><strong class="command">mysqld</strong></span> otherwise. Be aware of the implications of this behavior: </p><div class="itemizedlist"><ul type="disc"><li><p> On Linux, the <code class="literal">MySQL-Max</code> RPM relies on this <span><strong class="command">mysqld_safe</strong></span> behavior. The RPM installs an executable named <span><strong class="command">mysqld-max</strong></span>, which causes <span><strong class="command">mysqld_safe</strong></span> to automatically use that executable from that point on. </p></li><li><p> If you install a MySQL-Max distribution that includes a server named <span><strong class="command">mysqld-max</strong></span>, then upgrade later to a non-Max version of MySQL, <span><strong class="command">mysqld_safe</strong></span> still attempts to run the old <span><strong class="command">mysqld-max</strong></span> server. If you perform such an upgrade, you should manually remove the old <span><strong class="command">mysqld-max</strong></span> server to ensure that <span><strong class="command">mysqld_safe</strong></span> runs the new <span><strong class="command">mysqld</strong></span> server. </p></li></ul></div><p> To override the default behavior and specify explicitly which server you want to run, specify a <code class="option">--mysqld</code> or <code class="option">--mysqld-version</code> option to <span><strong class="command">mysqld_safe</strong></span>. </p><p> Many of the options to <span><strong class="command">mysqld_safe</strong></span> are the same as the options to <span><strong class="command">mysqld</strong></span>. See <a href="database-administration.html#server-options" title="5.2.1. mysqld Command-Line Options">Section 5.2.1, “<span><strong class="command">mysqld</strong></span> Command-Line Options”</a>. </p><p> All options specified to <span><strong class="command">mysqld_safe</strong></span> on the command line are passed to <span><strong class="command">mysqld</strong></span>. If you want to use any options that are specific to <span><strong class="command">mysqld_safe</strong></span> and that <span><strong class="command">mysqld</strong></span> does not support, do not specify them on the command line. Instead, list them in the <code class="literal">[mysqld_safe]</code> group of an option file. See <a href="using-mysql-programs.html#option-files" title="4.3.2. Using Option Files">Section 4.3.2, “Using Option Files”</a>. </p><p> <span><strong class="command">mysqld_safe</strong></span> reads all options from the <code class="literal">[mysqld]</code>, <code class="literal">[server]</code>, and <code class="literal">[mysqld_safe]</code> sections in option files. For backward compatibility, it also reads <code class="literal">[safe_mysqld]</code> sections, although you should rename such sections to <code class="literal">[mysqld_safe]</code> when you begin using MySQL 4.0 or later. </p><p> <span><strong class="command">mysqld_safe</strong></span> supports the following options: </p><div class="itemizedlist"><ul type="disc"><li><p> <code class="option">--autoclose</code> </p><p> (NetWare only) On NetWare, <span><strong class="command">mysqld_safe</strong></span> provides a screen presence. When you unload (shut down) the <span><strong class="command">mysqld_safe</strong></span> NLM, the screen does not by default go away. Instead, it prompts for user input: </p><pre class="programlisting">*<NLM has terminated; Press any key to close the screen>* </pre><p> If you want NetWare to close the screen automatically instead, use the <code class="option">--autoclose</code> option to <span><strong class="command">mysqld_safe</strong></span>. </p></li><li><p> <code class="option">--basedir=<em class="replaceable"><code>path</code></em></code> </p><p> The path to the MySQL installation directory. </p></li><li><p> <code class="option">--character-set-client-handshake</code> </p><p> Don't ignore character set information sent by the client. To ignore client information and use the default server character set, use <code class="option">--skip-character-set-client-handshake</code>; this makes MySQL 4.1 and higher behave like MySQL 4.0. </p></li><li><p> <code class="option">--core-file-size=<em class="replaceable"><code>size</code></em></code> </p><p> The size of the core file <span><strong class="command">mysqld</strong></span> should be able to create. The option value is passed to <span><strong class="command">ulimit -c</strong></span>. </p></li><li><p> <code class="option">--datadir=<em class="replaceable"><code>path</code></em></code> </p><p> The path to the data directory. </p></li><li><p> <code class="option">--defaults-extra-file=<em class="replaceable"><code>path</code></em></code> </p><p> The name of an option file to be read in addition to the usual option files. If given, this option must be first. </p></li><li><p> <code class="option">--defaults-file=<em class="replaceable"><code>path</code></em></code> </p><p> The name of an option file to be read instead of the usual option files. If given, this option must be first. </p></li><li><p> <code class="option">--err-log=<em class="replaceable"><code>path</code></em></code> </p><p> The old form of the <code class="option">--log-error</code> option, to be used before MySQL 4.0. </p></li><li><p> <code class="option">--ledir=<em class="replaceable"><code>path</code></em></code> </p><p> The path to the directory containing the <span><strong class="command">mysqld</strong></span> program. Use this option to explicitly indicate the location of the server. </p></li><li><p> <code class="option">--log-error=<em class="replaceable"><code>path</code></em></code> </p><p> Write the error log to the given file. See <a href="database-administration.html#error-log" title="5.10.1. The Error Log">Section 5.10.1, “The Error Log”</a>. </p></li><li><p> <code class="option">--mysqld=<em class="replaceable"><code>prog_name</code></em></code> </p><p> The name of the server program (in the <code class="literal">ledir</code> directory) that you want to start. This option is needed if you use the MySQL binary distribution but have the data directory outside of the binary distribution. </p></li><li><p> <code class="option">--mysqld-version=<em class="replaceable"><code>suffix</code></em></code> </p><p> This option is similar to the <code class="option">--mysqld</code> option, but you specify only the suffix for the server program name. The basename is assumed to be <span><strong class="command">mysqld</strong></span>. For example, if you use <code class="option">--mysqld-version=max</code>, <span><strong class="command">mysqld_safe</strong></span> starts the <span><strong class="command">mysqld-max</strong></span> program in the <code class="literal">ledir</code> directory. If the argument to <code class="option">--mysqld-version</code> is empty, <span><strong class="command">mysqld_safe</strong></span> uses <span><strong class="command">mysqld</strong></span> in the <code class="literal">ledir</code> directory. </p></li><li><p> <code class="option">--nice=<em class="replaceable"><code>priority</code></em></code> </p><p> Use the <code class="literal">nice</code> program to set the server's scheduling priority to the given value. This option was added in MySQL 4.0.14. </p></li><li><p> <code class="option">--no-defaults</code> </p><p> Do not read any option files. If given, this option must be first. </p></li><li><p> <code class="option">--open-files-limit=<em class="replaceable"><code>count</code></em></code> </p><p> The number of files <span><strong class="command">mysqld</strong></span> should be able to open. The option value is passed to <span><strong class="command">ulimit -n</strong></span>. Note that you need to start <span><strong class="command">mysqld_safe</strong></span> as <code class="literal">root</code> for this to work properly. </p></li><li><p> <code class="option">--pid-file=<em class="replaceable"><code>path</code></em></code> </p><p> The path to the process ID file. </p></li><li><p> <code class="option">--port=<em class="replaceable"><code>port_num</code></em></code> </p><p> The port number to use when listening for TCP/IP connections. The port number must be <code class="literal">1024</code> or higher unless MySQL is run as the <code class="literal">root</code> system user. </p></li><li><p> <code class="option">--socket=<em class="replaceable"><code>path</code></em></code> </p><p> The Unix socket file to use for local connections. </p></li><li><p> <code class="option">--timezone=<em class="replaceable"><code>zone</code></em></code> </p><p> Set the <code class="literal">TZ</code> time zone environment variable to the given option value. Consult your operating system documentation for legal time zone specification formats. </p></li><li><p> <code class="option">--user={<em class="replaceable"><code>user_name</code></em> | <em class="replaceable"><code>user_id</code></em>}</code> </p><p> Run the <span><strong class="command">mysqld</strong></span> server as the user having the name <em class="replaceable"><code>user_name</code></em> or the numeric user ID <em class="replaceable"><code>user_id</code></em>. (“<span class="quote">User</span>” in this context refers to a system login account, not a MySQL user listed in the grant tables.) </p></li></ul></div><p> When executing <span><strong class="command">mysqld_safe</strong></span>, the <code class="option">--defaults-file</code> or <code class="option">--defaults-extra-option</code> must be given first, or the option file will not be used. For example, this command will not use the named option file: </p><pre class="programlisting">mysqld_safe --port=<em class="replaceable"><code>port_num</code></em> --defaults-file=<em class="replaceable"><code>file_name</code></em> </pre><p> Instead, use the following command: </p><pre class="programlisting">mysqld_safe --defaults-file=<em class="replaceable"><code>file_name</code></em> --port=<em class="replaceable"><code>port_num</code></em> </pre><p> The <span><strong class="command">mysqld_safe</strong></span> script is written so that it normally can start a server that was installed from either a source or a binary distribution of MySQL, even though these types of distributions typically install the server in slightly different locations. (See <a href="installing.html#installation-layouts" title="2.1.5. Installation Layouts">Section 2.1.5, “Installation Layouts”</a>.) <span><strong class="command">mysqld_safe</strong></span> expects one of the following conditions to be true: </p><div class="itemizedlist"><ul type="disc"><li><p> The server and databases can be found relative to the directory from which <span><strong class="command">mysqld_safe</strong></span> is invoked. For binary distributions, <span><strong class="command">mysqld_safe</strong></span> looks under its working directory for <code class="filename">bin</code> and <code class="filename">data</code> directories. For source distributions, it looks for <code class="filename">libexec</code> and <code class="filename">var</code> directories. This condition should be met if you execute <span><strong class="command">mysqld_safe</strong></span> from your MySQL installation directory (for example, <code class="filename">/usr/local/mysql</code> for a binary distribution). </p></li><li><p> If the server and databases cannot be found relative to the working directory, <span><strong class="command">mysqld_safe</strong></span> attempts to locate them by absolute pathnames. Typical locations are <code class="filename">/usr/local/libexec</code> and <code class="filename">/usr/local/var</code>. 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. </p></li></ul></div><p> Because <span><strong class="command">mysqld_safe</strong></span> tries to find the server and databases relative to its own working directory, you can install a binary distribution of MySQL anywhere, as long as you run <span><strong class="command">mysqld_safe</strong></span> from the MySQL installation directory: </p><pre class="programlisting">shell> <strong class="userinput"><code>cd mysql_installation_directory</code></strong> shell> <strong class="userinput"><code>bin/mysqld_safe &</code></strong> </pre><p> If <span><strong class="command">mysqld_safe</strong></span> fails, even when invoked from the MySQL installation directory, you can specify the <code class="option">--ledir</code> and <code class="option">--datadir</code> options to indicate the directories in which the server and databases are located on your system. </p><p> Normally, you should not edit the <span><strong class="command">mysqld_safe</strong></span> script. Instead, configure <span><strong class="command">mysqld_safe</strong></span> by using command-line options or options in the <code class="literal">[mysqld_safe]</code> section of a <code class="filename">my.cnf</code> option file. In rare cases, it might be necessary to edit <span><strong class="command">mysqld_safe</strong></span> to get it to start the server properly. However, if you do this, your modified version of <span><strong class="command">mysqld_safe</strong></span> might be overwritten if you upgrade MySQL in the future, so you should make a copy of your edited version that you can reinstall. </p><p> On NetWare, <span><strong class="command">mysqld_safe</strong></span> is a NetWare Loadable Module (NLM) that is ported from the original Unix shell script. It does the following: </p><div class="orderedlist"><ol type="1"><li><p> Runs a number of system and option checks. </p></li><li><p> Runs a check on <code class="literal">MyISAM</code> and <code class="literal">ISAM</code> tables. </p></li><li><p> Provides a screen presence for the MySQL server. </p></li><li><p> Starts <span><strong class="command">mysqld</strong></span>, monitors it, and restarts it if it terminates in error. </p></li><li><p> Sends error messages from <span><strong class="command">mysqld</strong></span> to the <code class="filename"><em class="replaceable"><code>host_name</code></em>.err</code> file in the data directory. </p></li><li><p> Sends <span><strong class="command">mysqld_safe</strong></span> screen output to the <code class="filename"><em class="replaceable"><code>host_name</code></em>.safe</code> file in the data directory. </p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mysql-server"></a>5.1.4. mysql.server — MySQL Server Startup Script</h3></div></div></div><p> MySQL distributions on Unix include a script named <span><strong class="command">mysql.server</strong></span>. It can be used on systems such as Linux and Solaris that use System V-style run directories to start and stop system services. It is also used by the Mac OS X Startup Item for MySQL. </p><p> <span><strong class="command">mysql.server</strong></span> can be found in the <code class="filename">support-files</code> directory under your MySQL installation directory or in a MySQL source tree. </p><p> If you use the Linux server RPM package (<code class="literal">MySQL-server-<em class="replaceable"><code>VERSION</code></em>.rpm</code>), the <span><strong class="command">mysql.server</strong></span> script will be installed in the <code class="filename">/etc/init.d</code> directory with the name <code class="filename">mysql</code>. You need not install it manually. See <a href="installing.html#linux-rpm" title="2.4. Installing MySQL on Linux">Section 2.4, “Installing MySQL on Linux”</a> for more information on the Linux RPM packages. </p><p> Some vendors provide RPM packages that install a startup script under a different name such as <span><strong class="command">mysqld</strong></span>. </p><p> If you install MySQL from a source distribution or using a binary distribution format that does not install <span><strong class="command">mysql.server</strong></span> automatically, you can install it manually. Instructions are provided in <a href="installing.html#automatic-start" title="2.9.2.2. Starting and Stopping MySQL Automatically">Section 2.9.2.2, “Starting and Stopping MySQL Automatically”</a>. </p><p> <span><strong class="command">mysql.server</strong></span> reads options from the <code class="literal">[mysql.server]</code> and <code class="literal">[mysqld]</code> sections of option files. (For backward compatibility, it also reads <code class="literal">[mysql_server]</code> sections, although you should rename such sections to <code class="literal">[mysql.server]</code> when you begin using MySQL 4.0 or later.) </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="mysqld-multi"></a>5.1.5. mysqld_multi — Program for Managing Multiple MySQL Servers</h3></div></div></div><p> <span><strong class="command">mysqld_multi</strong></span> is meant for managing several <span><strong class="command">mysqld</strong></span> 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. </p><p> The program searches for groups named <code class="literal">[mysqld<em class="replaceable"><code>N</code></em>]</code> in <code class="filename">my.cnf</code> (or in the file named by the <code class="option">--config-file</code> option). <em class="replaceable"><code>N</code></em> can be any positive integer. This number is referred to in the following discussion as the option group number, or <em class="replaceable"><code>GNR</code></em>. Group numbers distinguish option groups from one another and are used as arguments to <span><strong class="command">mysqld_multi</strong></span> to specify which servers you want to start, stop, or obtain a status report for. Options listed in these groups are the same that you would use in the <code class="literal">[mysqld]</code> group used for starting <span><strong class="command">mysqld</strong></span>. (See, for example, <a href="installing.html#automatic-start" title="2.9.2.2. Starting and Stopping MySQL Automatically">Section 2.9.2.2, “Starting and Stopping MySQL Automatically”</a>.) However, when using multiple servers it is necessary that each one use its own value for options such as the Unix socket file and TCP/IP port number. For more information on which options must be unique per server in a multiple-server environment, see <a href="database-administration.html#multiple-servers" title="5.11. Running Multiple MySQL Servers on the Same Machine">Section 5.11, “Running Multiple MySQL Servers on the Same Machine”</a>. </p><p> To invoke <span><strong class="command">mysqld_multi</strong></span>, use the following syntax: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysqld_multi [<em class="replaceable"><code>options</code></em>] {start|stop|report} [<em class="replaceable"><code>GNR</code></em>[,<em class="replaceable"><code>GNR</code></em>] ...]</code></strong> </pre><p> <code class="literal">start</code>, <code class="literal">stop</code>, and <code class="literal">report</code> indicate which operation you want to perform. You can perform the designated operation on a single server or multiple servers, depending on the <em class="replaceable"><code>GNR</code></em> list that follows the option name. If there is no list, <span><strong class="command">mysqld_multi</strong></span> performs the operation for all servers in the option file. </p><p> Each <em class="replaceable"><code>GNR</code></em> 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 <em class="replaceable"><code>GNR</code></em> for a group named <code class="literal">[mysqld17]</code> is <code class="literal">17</code>. To specify a range of numbers, separate the first and last numbers by a dash. The <em class="replaceable"><code>GNR</code></em> value <code class="literal">10-13</code> represents groups <code class="literal">[mysqld10]</code> through <code class="literal">[mysqld13]</code>. 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 <em class="replaceable"><code>GNR</code></em> list; anything after a whitespace character is ignored. </p><p> This command starts a single server using option group <code class="literal">[mysqld17]</code>: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysqld_multi start 17</code></strong> </pre><p> This command stops several servers, using option groups <code class="literal">[mysql8]</code> and <code class="literal">[mysqld10]</code> through <code class="literal">[mysqld13]</code>: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysqld_multi stop 8,10-13</code></strong> </pre><p> For an example of how you might set up an option file, use this command: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysqld_multi --example</code></strong> </pre><p> <span><strong class="command">mysqld_multi</strong></span> supports the following options: </p><div class="itemizedlist"><ul type="disc"><li><p> <a class="indexterm" name="id2770283"></a> <code class="option">--config-file=<em class="replaceable"><code>name</code></em></code> </p><p> Specify the name of an alternative option file. This affects where <span><strong class="command">mysqld_multi</strong></span> looks for <code class="literal">[mysqld<em class="replaceable"><code>N</code></em>]</code> option groups. Without this option, all options are read from the usual <code class="filename">my.cnf</code> file. The option does not affect where <span><strong class="command">mysqld_multi</strong></span> reads its own options, which are always taken from the <code class="literal">[mysqld_multi]</code> group in the usual <code class="filename">my.cnf</code> file. </p></li><li><p> <a class="indexterm" name="id2770345"></a> <code class="option">--example</code> </p><p> Display a sample option file. </p></li><li><p> <a class="indexterm" name="id2770373"></a> <code class="option">--help</code> </p><p> Display a help message and exit. </p></li><li><p> <a class="indexterm" name="id2770401"></a> <code class="option">--log=<em class="replaceable"><code>name</code></em></code> </p><p> Specify the name of the log file. If the file exists, log output is appended to it. </p></li><li><p> <a class="indexterm" name="id2770432"></a> <code class="option">--mysqladmin=<em class="replaceable"><code>prog_name</code></em></code> </p><p> The <span><strong class="command">mysqladmin</strong></span> binary to be used to stop servers. </p></li><li><p> <a class="indexterm" name="id2770467"></a> <code class="option">--mysqld=<em class="replaceable"><code>prog_name</code></em></code> </p><p> The <span><strong class="command">mysqld</strong></span> binary to be used. Note that you can specify <span><strong class="command">mysqld_safe</strong></span> as the value for this option also. The options are passed to <span><strong class="command">mysqld</strong></span>. Just make sure that you have the directory where <span><strong class="command">mysqld</strong></span> is located in your <code class="literal">PATH</code> environment variable setting or fix <span><strong class="command">mysqld_safe</strong></span>. </p></li><li><p> <a class="indexterm" name="id2770524"></a> <code class="option">--no-log</code> </p><p> Print log information to stdout rather than to the log file. By default, output goes to the log file. </p></li><li><p> <a class="indexterm" name="id2770553"></a> <code class="option">--password=<em class="replaceable"><code>password</code></em></code> </p><p> The password of the MySQL account to use when invoking <span><strong class="command">mysqladmin</strong></span>. Note that the password value is not optional for this option, unlike for other MySQL programs. </p></li><li><p> <a class="indexterm" name="id2770590"></a> <code class="option">--silent</code> </p><p> Disable warnings. This option was added in MySQL 4.1.6. </p></li><li><p> <a class="indexterm" name="id2770618"></a> <code class="option">--tcp-ip</code> </p><p> Connect to each MySQL server via the TCP/IP port instead of the Unix socket file. (If a socket file is missing, the server might still be running, but accessible only via the TCP/IP port.) By default, connections are made using the Unix socket file. This option affects <code class="literal">stop</code> and <code class="literal">report</code> operations. </p></li><li><p> <a class="indexterm" name="id2770659"></a> <code class="option">--user=<em class="replaceable"><code>user_name</code></em></code> </p><p> The username of the MySQL account to use when invoking <span><strong class="command">mysqladmin</strong></span>. </p></li><li><p> <a class="indexterm" name="id2770694"></a> <code class="option">--verbose</code> </p><p> Be more verbose. This option was added in MySQL 4.1.6. </p></li><li><p> <a class="indexterm" name="id2770722"></a> <code class="option">--version</code> </p><p> Display version information and exit. </p></li></ul></div><p> Some notes about <span><strong class="command">mysqld_multi</strong></span>: </p><div class="itemizedlist"><ul type="disc"><li><p> Make sure that the MySQL account used for stopping the <span><strong class="command">mysqld</strong></span> servers (with the <span><strong class="command">mysqladmin</strong></span> program) has the same username and password for each server. Also, make sure that the account has the <code class="literal">SHUTDOWN</code> privilege. If the servers that you want to manage have many different usernames or passwords for the administrative accounts, you might want to create an account on each server that has the same username and password. For example, you might set up a common <code class="literal">multi_admin</code> account by executing the following commands for each server: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql -u root -S /tmp/mysql.sock -p<em class="replaceable"><code>root_password</code></em></code></strong> mysql> <strong class="userinput"><code>GRANT SHUTDOWN ON *.*</code></strong> -> <strong class="userinput"><code>TO 'multi_admin'@'localhost' IDENTIFIED BY 'multipass';</code></strong> </pre><p> See <a href="database-administration.html#privileges" title="5.6.2. How the Privilege System Works">Section 5.6.2, “How the Privilege System Works”</a>. You have to do this for each <span><strong class="command">mysqld</strong></span> server. Change the connection parameters appropriately when connecting to each one. Note that the host part of the account name must allow you to connect as <code class="literal">multi_admin</code> from the host where you want to run <span><strong class="command">mysqld_multi</strong></span>. </p></li><li><p> The <code class="option">--pid-file</code> option is very important if you are using <span><strong class="command">mysqld_safe</strong></span> to start <span><strong class="command">mysqld</strong></span> (for example, <code class="option">--mysqld=mysqld_safe</code>) Every <span><strong class="command">mysqld</strong></span> should have its own process ID file. The advantage of using <span><strong class="command">mysqld_safe</strong></span> instead of <span><strong class="command">mysqld</strong></span> is that <span><strong class="command">mysqld_safe</strong></span> “<span class="quote">guards</span>” its <span><strong class="command">mysqld</strong></span> process and restarts it if the process terminates due to a signal sent using <code class="literal">kill -9</code> or for other reasons, such as a segmentation fault. Please note that the <span><strong class="command">mysqld_safe</strong></span> script might require that you start it from a certain place. This means that you might have to change location to a certain directory before running <span><strong class="command">mysqld_multi</strong></span>. If you have problems starting, please see the <span><strong class="command">mysqld_safe</strong></span> script. Check especially the lines: </p><pre class="programlisting">---------------------------------------------------------------- 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 ---------------------------------------------------------------- </pre><p> See <a href="database-administration.html#mysqld-safe" title="5.1.3. mysqld_safe — MySQL Server Startup Script">Section 5.1.3, “mysqld_safe — MySQL Server Startup Script”</a>. The test performed by these lines should be successful, or you might encounter problems. </p></li><li><p> The Unix socket file and the TCP/IP port number must be different for every <span><strong class="command">mysqld</strong></span>. </p></li><li><p> You might want to use the <code class="option">--user</code> option for <span><strong class="command">mysqld</strong></span>, but in order to do this you need to run the <span><strong class="command">mysqld_multi</strong></span> script as the Unix <code class="literal">root</code> user. Having the option in the option file does not matter; you merely get a warning if you are not the superuser and the <span><strong class="command">mysqld</strong></span> processes are started under your own Unix account. </p></li><li><p> <span class="bold"><strong>Important</strong></span>: Make sure that the data directory is fully accessible to the Unix account that the specific <span><strong class="command">mysqld</strong></span> process is started as. Do <span class="emphasis"><em>not</em></span> use the Unix root account for this, unless you know <span class="emphasis"><em>exactly</em></span> what you are doing. </p></li><li><p> <span class="bold"><strong>Most important</strong></span>: Before using <span><strong class="command">mysqld_multi</strong></span> be sure that you understand the meanings of the options that are passed to the <span><strong class="command">mysqld</strong></span> servers and <span class="emphasis"><em>why</em></span> you would want to have separate <span><strong class="command">mysqld</strong></span> processes. Beware of the dangers of using multiple <span><strong class="command">mysqld</strong></span> servers with the same data directory. Use separate data directories, unless you know <span class="emphasis"><em>exactly</em></span> what you are doing. Starting multiple servers with the same data directory does <span class="emphasis"><em>not</em></span> give you extra performance in a threaded system. See <a href="database-administration.html#multiple-servers" title="5.11. Running Multiple MySQL Servers on the Same Machine">Section 5.11, “Running Multiple MySQL Servers on the Same Machine”</a>. </p></li></ul></div><p> The following example shows how you might set up an option file for use with <span><strong class="command">mysqld_multi</strong></span>. The first and fifth <code class="literal">[mysqld<em class="replaceable"><code>N</code></em>]</code> group were intentionally left out from the example to illustrate that you can have “<span class="quote">gaps</span>” in the option file. This gives you more flexibility. The order in which the <span><strong class="command">mysqld</strong></span> programs are started or stopped depends on the order in which they appear in the option file. </p><pre class="programlisting"># 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 </pre><p> See <a href="using-mysql-programs.html#option-files" title="4.3.2. Using Option Files">Section 4.3.2, “Using Option Files”</a>. </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mysqld"></a>5.2. mysqld — The MySQL Server</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="database-administration.html#server-options">5.2.1. <span><strong class="command">mysqld</strong></span> Command-Line Options</a></span></dt><dt><span class="section"><a href="database-administration.html#server-sql-mode">5.2.2. The Server SQL Mode</a></span></dt><dt><span class="section"><a href="database-administration.html#server-system-variables">5.2.3. Server System Variables</a></span></dt><dt><span class="section"><a href="database-administration.html#server-status-variables">5.2.4. Server Status Variables</a></span></dt></dl></div><p> <span><strong class="command">mysqld</strong></span> is the MySQL server. The following discussion covers these MySQL server configuration topics: </p><div class="itemizedlist"><ul type="disc"><li><p> Startup options that the server supports </p></li><li><p> How to set the server SQL mode </p></li><li><p> Server system variables </p></li><li><p> Server status variables </p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="server-options"></a>5.2.1. <span><strong class="command">mysqld</strong></span> Command-Line Options</h3></div></div></div><a class="indexterm" name="id2771172"></a><a class="indexterm" name="id2771181"></a><a class="indexterm" name="id2771191"></a><p> When you start the <span><strong class="command">mysqld</strong></span> server, you can specify program options using any of the methods described in <a href="using-mysql-programs.html#program-options" title="4.3. Specifying Program Options">Section 4.3, “Specifying Program Options”</a>. The most common methods are to provide options in an option file or on the command line. However, in most cases it is desirable to make sure that the server uses the same options each time it runs. The best way to ensure this is to list them in an option file. See <a href="using-mysql-programs.html#option-files" title="4.3.2. Using Option Files">Section 4.3.2, “Using Option Files”</a>. </p><p> <span><strong class="command">mysqld</strong></span> reads options from the <code class="literal">[mysqld]</code> and <code class="literal">[server]</code> groups. <span><strong class="command">mysqld_safe</strong></span> reads options from the <code class="literal">[mysqld]</code>, <code class="literal">[server]</code>, <code class="literal">[mysqld_safe]</code>, and <code class="literal">[safe_mysqld]</code> groups. <span><strong class="command">mysql.server</strong></span> reads options from the <code class="literal">[mysqld]</code> and <code class="literal">[mysql.server]</code> groups. An embedded MySQL server usually reads options from the <code class="literal">[server]</code>, <code class="literal">[embedded]</code>, and <code class="literal">[<em class="replaceable"><code>xxxxx</code></em>_SERVER]</code> groups, where <em class="replaceable"><code>xxxxx</code></em> is the name of the application into which the server is embedded. </p><p> <span><strong class="command">mysqld</strong></span> accepts many command-line options. For a list, execute <span><strong class="command">mysqld --help</strong></span>. Before MySQL 4.1.1, <code class="option">--help</code> prints the full help message. As of 4.1.1, it prints a brief message; to see the full list, use <span><strong class="command">mysqld --verbose --help</strong></span>. </p><p> The following list shows some of the most common server options. Additional options are described elsewhere: </p><div class="itemizedlist"><ul type="disc"><li><p> Options that affect security: See <a href="database-administration.html#privileges-options" title="5.5.3. Startup Options for mysqld Concerning Security">Section 5.5.3, “Startup Options for <span><strong class="command">mysqld</strong></span> Concerning Security”</a>. </p></li><li><p> SSL-related options: See <a href="database-administration.html#ssl-options" title="5.7.7.5. SSL Command-Line Options">Section 5.7.7.5, “SSL Command-Line Options”</a>. </p></li><li><p> Binary log control options: See <a href="database-administration.html#binary-log" title="5.10.4. The Binary Log">Section 5.10.4, “The Binary Log”</a>. </p></li><li><p> Replication-related options: See <a href="replication.html#replication-options" title="6.8. Replication Startup Options">Section 6.8, “Replication Startup Options”</a>. </p></li><li><p> Options specific to particular storage engines: See <a href="storage-engines.html#myisam-start" title="14.1.1. MyISAM Startup Options">Section 14.1.1, “<code class="literal">MyISAM</code> Startup Options”</a>, <a href="storage-engines.html#bdb-start" title="14.4.3. BDB Startup Options">Section 14.4.3, “<code class="literal">BDB</code> Startup Options”</a>, <a href="innodb.html#innodb-start" title="15.5. InnoDB Startup Options">Section 15.5, “<code class="literal">InnoDB</code> Startup Options”</a>. </p></li></ul></div><p> You can also set the value of a server system variable by using the variable name as an option, as described later in this section. </p><div class="itemizedlist"><ul type="disc"><li><p> <code class="option">--help</code>, <code class="option">-?</code> </p><p> Display a short help message and exit. Before MySQL 4.1.1, <code class="option">--help</code> displays the full help message. As of 4.1.1, it displays an abbreviated message only. Use both the <code class="option">--verbose</code> and <code class="option">--help</code> options to see the full message. </p></li><li><p> <code class="option">--allow-suspicious-udfs</code> </p><p> This option controls whether user-defined functions that have only an <code class="literal">xxx</code> symbol for the main function can be loaded. By default, the option is off and only UDFs that have at least one auxiliary symbol can be loaded. This prevents attempts at loading functions from shared object files other than those containing legitimate UDFs. This option was added in MySQL 4.0.24, and 4.1.10a. See <a href="extending-mysql.html#udf-security" title="20.2.4.6. User-Defined Function Security Precautions">Section 20.2.4.6, “User-Defined Function Security Precautions”</a>. </p></li><li><p> <code class="option">--ansi</code> </p><p> Use standard SQL syntax instead of MySQL syntax. See <a href="introduction.html#ansi-mode" title="1.8.3. Running MySQL in ANSI Mode">Section 1.8.3, “Running MySQL in ANSI Mode”</a>. For more precise control over the server SQL mode, use the <code class="option">--sql-mode</code> option instead. </p></li><li><p> <code class="option">--basedir=<em class="replaceable"><code>path</code></em>, -b <em class="replaceable"><code>path</code></em></code> </p><p> The path to the MySQL installation directory. All paths are usually resolved relative to this. </p></li><li><p> <code class="option">--big-tables</code> </p><p> Allow large result sets by saving all temporary sets in files. This option prevents most “<span class="quote">table full</span>” errors, but also slows down queries for which in-memory tables would suffice. Since MySQL 3.23.2, the server is able to handle large result sets automatically by using memory for small temporary tables and switching to disk tables where necessary. </p></li><li><p> <code class="option">--bind-address=<em class="replaceable"><code>IP</code></em></code> </p><p> The IP address to bind to. </p></li><li><p> <code class="option">--bootstrap</code> </p><p> This option is used by the <span><strong class="command">mysql_install_db</strong></span> script to create the MySQL privilege tables without having to start a full MySQL server. </p></li><li><p> <code class="option">--console</code> </p><p> Write the error log messages to stderr/stdout even if <code class="option">--log-error</code> is specified. On Windows, <span><strong class="command">mysqld</strong></span> does not close the console screen if this option is used. </p></li><li><p> <code class="option">--character-sets-dir=<em class="replaceable"><code>path</code></em></code> </p><p> The directory where character sets are installed. See <a href="database-administration.html#character-sets" title="5.9.1. The Character Set Used for Data and Sorting">Section 5.9.1, “The Character Set Used for Data and Sorting”</a>. </p></li><li><p> <code class="option">--chroot=<em class="replaceable"><code>path</code></em></code> </p><p> Put the <span><strong class="command">mysqld</strong></span> server in a closed environment during startup by using the <code class="literal">chroot()</code> system call. This is a recommended security measure as of MySQL 4.0. (MySQL 3.23 is not able to provide a <code class="literal">chroot()</code> jail that is 100% closed.) Note that use of this option somewhat limits <code class="literal">LOAD DATA INFILE</code> and <code class="literal">SELECT ... INTO OUTFILE</code>. </p></li><li><p> <code class="option">--character-set-server=<em class="replaceable"><code>charset</code></em></code> </p><p> Use <em class="replaceable"><code>charset</code></em> as the default server character set. This option is available as of MySQL 4.1.3. See <a href="database-administration.html#character-sets" title="5.9.1. The Character Set Used for Data and Sorting">Section 5.9.1, “The Character Set Used for Data and Sorting”</a>. </p></li><li><p> <code class="option">--core-file</code> </p><p> Write a core file if <span><strong class="command">mysqld</strong></span> dies. For some systems, you must also specify the <code class="option">--core-file-size</code> option to <span><strong class="command">mysqld_safe</strong></span>. See <a href="database-administration.html#mysqld-safe" title="5.1.3. mysqld_safe — MySQL Server Startup Script">Section 5.1.3, “mysqld_safe — MySQL Server Startup Script”</a>. Note that on some systems, such as Solaris, you do not get a core file if you are also using the <code class="option">--user</code> option. </p></li><li><p> <code class="option">--collation-server=<em class="replaceable"><code>collation</code></em></code> </p><p> Use <em class="replaceable"><code>collation</code></em> as the default server collation. This option is available as of MySQL 4.1.3. See <a href="database-administration.html#character-sets" title="5.9.1. The Character Set Used for Data and Sorting">Section 5.9.1, “The Character Set Used for Data and Sorting”</a>. </p></li><li><p> <code class="option">--datadir=<em class="replaceable"><code>path</code></em>, -h <em class="replaceable"><code>path</code></em></code> </p><p> The path to the data directory. </p></li><li><p> <code class="option">--debug[=<em class="replaceable"><code>debug_options</code></em>]</code>, <code class="option">-# [<em class="replaceable"><code>debug_options</code></em>]</code> </p><p> If MySQL is configured with <code class="option">--with-debug</code>, you can use this option to get a trace file of what <span><strong class="command">mysqld</strong></span> is doing. The <em class="replaceable"><code>debug_options</code></em> string often is <code class="literal">'d:t:o,<em class="replaceable"><code>file_name</code></em>'</code>. See <a href="porting.html#making-trace-files" title="E.1.2. Creating Trace Files">Section E.1.2, “Creating Trace Files”</a>. </p></li><li><p> <code class="option">--default-character-set=<em class="replaceable"><code>charset</code></em></code> </p><p> Use <em class="replaceable"><code>charset</code></em> as the default character set. This option is deprecated in favor of <code class="option">--character-set-server</code> as of MySQL 4.1.3. See <a href="database-administration.html#character-sets" title="5.9.1. The Character Set Used for Data and Sorting">Section 5.9.1, “The Character Set Used for Data and Sorting”</a>. </p></li><li><p> <code class="option">--default-collation=<em class="replaceable"><code>collation</code></em></code> </p><p> Use <em class="replaceable"><code>collation</code></em> as the default collation. This option is deprecated in favor of <code class="option">--collation-server</code> as of MySQL 4.1.3. See <a href="database-administration.html#character-sets" title="5.9.1. The Character Set Used for Data and Sorting">Section 5.9.1, “The Character Set Used for Data and Sorting”</a>. </p></li><li><p> <code class="option">--default-storage-engine=<em class="replaceable"><code>type</code></em></code> </p><p> This option is a synonym for <code class="option">--default-table-type</code>. It is available as of MySQL 4.1.2. </p></li><li><p> <code class="option">--default-table-type=<em class="replaceable"><code>type</code></em></code> </p><p> Set the default table type for tables. See <a href="storage-engines.html" title="Chapter 14. Storage Engines and Table Types">Chapter 14, <i>Storage Engines and Table Types</i></a>. </p></li><li><p> <code class="option">--default-time-zone=<em class="replaceable"><code>type</code></em></code> </p><p> Set the default server time zone. This option sets the global <code class="literal">time_zone</code> system variable. If this option is not given, the default time zone is the same as the system time zone (given by the value of the <code class="literal">system_time_zone</code> system variable. This option is available as of MySQL 4.1.3. </p></li><li><p> <code class="option">--delay-key-write[= OFF | ON | ALL]</code> </p><p> How the <code class="literal">DELAYED KEYS</code> option should be used. Delayed key writing causes key buffers not to be flushed between writes for <code class="literal">MyISAM</code> tables. <code class="literal">OFF</code> disables delayed key writes. <code class="literal">ON</code> enables delayed key writes for those tables that were created with the <code class="literal">DELAYED KEYS</code> option. <code class="literal">ALL</code> delays key writes for all <code class="literal">MyISAM</code> tables. Available as of MySQL 4.0.3. See <a href="optimization.html#server-parameters" title="7.5.2. Tuning Server Parameters">Section 7.5.2, “Tuning Server Parameters”</a>. See <a href="storage-engines.html#myisam-start" title="14.1.1. MyISAM Startup Options">Section 14.1.1, “<code class="literal">MyISAM</code> Startup Options”</a>. </p><p> <span class="bold"><strong>Note</strong></span>: If you set this variable to <code class="literal">ALL</code>, you should not use <code class="literal">MyISAM</code> tables from within another program (such as from another MySQL server or with <span><strong class="command">myisamchk</strong></span>) when the table is in use. Doing so leads to index corruption. </p></li><li><p> <code class="option">--delay-key-write-for-all-tables</code> </p><p> Old form of <code class="option">--delay-key-write=ALL</code> for use prior to MySQL 4.0.3. As of 4.0.3, use <code class="option">--delay-key-write</code> instead. </p></li><li><p> <code class="option">--des-key-file=<em class="replaceable"><code>file_name</code></em></code> </p><p> Read the default keys used by <code class="literal">DES_ENCRYPT()</code> and <code class="literal">DES_DECRYPT()</code> from this file. </p></li><li><p> <code class="option">--enable-named-pipe</code> </p><p> Enable support for named pipes. This option applies only on Windows NT, 2000, XP, and 2003 systems, and can be used only with the <span><strong class="command">mysqld-nt</strong></span> and <span><strong class="command">mysqld-max-nt</strong></span> servers that support named pipe connections. </p></li><li><p> <code class="option">--exit-info[=<em class="replaceable"><code>flags</code></em>]</code>, <code class="option">-T [<em class="replaceable"><code>flags</code></em>]</code> </p><p> This is a bit mask of different flags you can use for debugging the <span><strong class="command">mysqld</strong></span> server. Do <span class="emphasis"><em>not</em></span> use this option unless you know <span class="emphasis"><em>exactly</em></span> what it does. </p></li><li><p> <code class="option">--external-locking</code> </p><p> Enable system locking. Note that if you use this option on a system on which <code class="literal">lockd</code> does not fully work (as on Linux), it is easy for <span><strong class="command">mysqld</strong></span> to deadlock. This option previously was named <code class="option">--enable-locking</code>. </p><p> <span class="bold"><strong>Note</strong></span>: If you use this option to enable updates to <code class="literal">MyISAM</code> tables from many MySQL processes, you have to ensure that these conditions are satisfied: </p><div class="itemizedlist"><ul type="circle"><li><p> You should not use the query cache for queries that use tables that are updated by another process. </p></li><li><p> You should not use <code class="option">--delay-key-write=ALL</code> or <code class="literal">DELAY_KEY_WRITE=1</code> on any shared tables. </p></li></ul></div><p> The easiest way to ensure this is to always use <code class="option">--external-locking</code> together with <code class="option">--delay-key-write=OFF --query-cache-size=0</code>. </p><p> (This is not done by default because in many setups it is useful to have a mixture of the above options.) </p></li><li><p> <code class="option">--flush</code> </p><p> Flush all changes to disk after each SQL statement. Normally MySQL does a write of all changes to disk only after each SQL statement and lets the operating system handle the synching to disk. See <a href="problems.html#crashing" title="A.4.2. What to Do If MySQL Keeps Crashing">Section A.4.2, “What to Do If MySQL Keeps Crashing”</a>. </p></li><li><p> <code class="option">--init-file=<em class="replaceable"><code>file</code></em></code> </p><p> Read SQL statements from this file at startup. Each statement must be on a single line and should not include comments. </p></li><li><p> <code class="option">--innodb-safe-binlog</code> </p><p> Adds consistency guarantees between the content of <code class="literal">InnoDB</code> tables and the binary log. See <a href="database-administration.html#binary-log" title="5.10.4. The Binary Log">Section 5.10.4, “The Binary Log”</a>. </p></li><li><p> <code class="option">--language=<em class="replaceable"><code>lang_name</code></em>, -L <em class="replaceable"><code>lang_name</code></em></code> </p><p> Client error messages in given language. <em class="replaceable"><code>lang_name</code></em> can be given as the language name or as the full pathname to the directory where the language files are installed. See <a href="database-administration.html#languages" title="5.9.2. Setting the Error Message Language">Section 5.9.2, “Setting the Error Message Language”</a>. </p></li><li><p> <code class="option">--log[=<em class="replaceable"><code>file</code></em>]</code>, <code class="option">-l [<em class="replaceable"><code>file</code></em>]</code> </p><p> Log connections and queries to this file. See <a href="database-administration.html#query-log" title="5.10.2. The General Query Log">Section 5.10.2, “The General Query Log”</a>. If you do not specify a filename, MySQL uses <code class="filename"><em class="replaceable"><code>host_name</code></em>.log</code> as the filename. </p></li><li><p> <code class="option">--log-bin=[<em class="replaceable"><code>file</code></em>]</code> </p><p> The binary log file. Log all queries that change data to this file. Used for backup and replication. See <a href="database-administration.html#binary-log" title="5.10.4. The Binary Log">Section 5.10.4, “The Binary Log”</a>. It is recommended to specify a filename (see <a href="problems.html#open-bugs" title="A.8.4. Open Issues in MySQL">Section A.8.4, “Open Issues in MySQL”</a> for the reason) otherwise MySQL uses <code class="filename"><em class="replaceable"><code>host_name</code></em>-bin</code> as the log file basename. </p></li><li><p> <code class="option">--log-bin-index[=<em class="replaceable"><code>file</code></em>]</code> </p><p> The index file for binary log filenames. See <a href="database-administration.html#binary-log" title="5.10.4. The Binary Log">Section 5.10.4, “The Binary Log”</a>. If you do not specify a filename, and if you didn't specify one in <code class="option">--log-bin</code>, MySQL uses <code class="filename"><em class="replaceable"><code>host_name</code></em>-bin.index</code> as the filename. </p></li><li><p> <code class="option">--log-error[=<em class="replaceable"><code>file</code></em>]</code> </p><p> Log errors and startup messages to this file. See <a href="database-administration.html#error-log" title="5.10.1. The Error Log">Section 5.10.1, “The Error Log”</a>. If you do not specify a filename, MySQL uses <code class="filename"><em class="replaceable"><code>host_name</code></em>.err</code> as the filename. If the filename has no extension, an extension of <code class="filename">.err</code> is added to the name. </p></li><li><p> <code class="option">--log-isam[=<em class="replaceable"><code>file</code></em>]</code> </p><p> Log all <code class="literal">ISAM</code>/<code class="literal">MyISAM</code> changes to this file (used only when debugging <code class="literal">ISAM</code>/<code class="literal">MyISAM</code>). </p></li><li><p> <code class="option">--log-long-format</code> </p><p> Log some extra information to the log files (update log, binary update log, and slow queries log, whatever log has been activated). For example, username and timestamp are logged for queries. Before MySQL 4.1, if you are using <code class="option">--log-slow-queries</code> and <code class="option">--log-long-format</code>, queries that are not using indexes also are logged to the slow query log. <code class="option">--log-long-format</code> is deprecated as of MySQL version 4.1, when <code class="option">--log-short-format</code> was introduced. (Long log format is the default setting since version 4.1.) Also note that starting with MySQL 4.1, the <code class="option">--log-queries-not-using-indexes</code> option is available for the purpose of logging queries that do not use indexes to the slow query log. </p></li><li><p> <code class="option">--log-queries-not-using-indexes</code> </p><p> If you are using this option with <code class="option">--log-slow-queries</code>, then queries that are not using indexes also are logged to the slow query log. This option is available as of MySQL 4.1. See <a href="database-administration.html#slow-query-log" title="5.10.5. The Slow Query Log">Section 5.10.5, “The Slow Query Log”</a>. </p></li><li><p> <code class="option">--log-short-format</code> </p><p> Log less information to the log files (update log, binary update log, and slow queries log, whatever log has been activated). For example, username and timestamp are not logged for queries. This option was introduced in MySQL 4.1. </p></li><li><p> <code class="option">--log-slow-admin-statements</code> </p><p> Log slow administrative statements such as <code class="literal">OPTIMIZE TABLE</code>, <code class="literal">ANALYZE TABLE</code>, and <code class="literal">ALTER TABLE</code> to the slow query log. </p><p> This option was added in MySQL 4.1.13. (It is unnecessary in MySQL 4.0 because slow administrative statements are logged by default.) </p></li><li><p> <code class="option">--log-slow-queries[=<em class="replaceable"><code>file</code></em>]</code> </p><p> Log all queries that have taken more than <code class="literal">long_query_time</code> seconds to execute to this file. See <a href="database-administration.html#slow-query-log" title="5.10.5. The Slow Query Log">Section 5.10.5, “The Slow Query Log”</a>. Note that the default for the amount of information logged has changed in MySQL 4.1. See the <code class="option">--log-long-format</code> and <code class="option">--log-short-format</code> options for details. </p></li><li><p> <code class="option">--log-update[=<em class="replaceable"><code>file</code></em>]</code> </p><p> Log updates to <em class="replaceable"><code>fileN</code></em> where <em class="replaceable"><code>N</code></em> is a unique number if not given. See <a href="database-administration.html#update-log" title="5.10.3. The Update Log">Section 5.10.3, “The Update Log”</a>. The update log is now deprecated; you should use the binary log instead (<code class="option">--log-bin</code>). See <a href="database-administration.html#binary-log" title="5.10.4. The Binary Log">Section 5.10.4, “The Binary Log”</a>. </p></li><li><p> <code class="option">--log-warnings</code>, <code class="option">-W</code> </p><p> Print out warnings such as <code class="literal">Aborted connection...</code> to the error log. Enabling this option is recommended, for example, if you use replication (you get more information about what is happening, such as messages about network failures and reconnections). This option is enabled by default as of MySQL 4.0.19 and 4.1.2; to disable it, use <code class="option">--skip-log-warnings</code>. As of MySQL 4.0.21 and 4.1.3, aborted connections are not logged to the error log unless the value is greater than 1. See <a href="problems.html#communication-errors" title="A.2.10. Communication Errors and Aborted Connections">Section A.2.10, “Communication Errors and Aborted Connections”</a>. </p><p> This option was named <code class="option">--warnings</code> before MySQL 4.0. </p></li><li><p> <code class="option">--low-priority-updates</code> </p><p> Table-modifying operations (<code class="literal">INSERT</code>, <code class="literal">REPLACE</code>, <code class="literal">DELETE</code>, <code class="literal">UPDATE</code>) have lower priority than selects. This can also be done via <code class="literal">{INSERT | REPLACE | DELETE | UPDATE} LOW_PRIORITY ...</code> to lower the priority of only one query, or by <code class="literal">SET LOW_PRIORITY_UPDATES=1</code> to change the priority in one thread. See <a href="optimization.html#table-locking" title="7.3.2. Table Locking Issues">Section 7.3.2, “Table Locking Issues”</a>. </p></li><li><p> <code class="option">--memlock</code> </p><p> Lock the <span><strong class="command">mysqld</strong></span> process in memory. This works on systems such as Solaris that support the <code class="literal">mlockall()</code> system call. This might help if you have a problem where the operating system is causing <span><strong class="command">mysqld</strong></span> to swap on disk. Note that use of this option requires that you run the server as <code class="literal">root</code>, which is normally not a good idea for security reasons. </p></li><li><p> <code class="option">--myisam-recover [=<em class="replaceable"><code>option</code></em>[,<em class="replaceable"><code>option</code></em>...]]]</code> </p><p> Set the <code class="literal">MyISAM</code> storage engine recovery mode. The option value is any combination of the values of <code class="literal">DEFAULT</code>, <code class="literal">BACKUP</code>, <code class="literal">FORCE</code>, or <code class="literal">QUICK</code>. If you specify multiple values, separate them by commas. You can also use a value of <code class="literal">""</code> to disable this option. If this option is used, <span><strong class="command">mysqld</strong></span>, when it opens a <code class="literal">MyISAM</code> table, checks whether the table is marked as crashed or wasn't closed properly. (The last option works only if you are running with <code class="option">--skip-external-locking</code>.) If this is the case, <span><strong class="command">mysqld</strong></span> runs a check on the table. If the table was corrupted, <span><strong class="command">mysqld</strong></span> attempts to repair it. </p><p> The following options affect how the repair works: </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td><span class="bold"><strong>Option</strong></span></td><td><span class="bold"><strong>Description</strong></span></td></tr><tr><td><code class="literal">DEFAULT</code></td><td>The same as not giving any option to <code class="option">--myisam-recover</code>.</td></tr><tr><td><code class="literal">BACKUP</code></td><td>If the data file was changed during recovery, save a backup of the <code class="filename"><em class="replaceable"><code>tbl_name</code></em>.MYD</code> file as <code class="filename"><em class="replaceable"><code>tbl_name-datetime</code></em>.BAK</code>.</td></tr><tr><td><code class="literal">FORCE</code></td><td>Run recovery even if we would lose more than one row from the <code class="filename">.MYD</code> file.</td></tr><tr><td><code class="literal">QUICK</code></td><td>do not check the rows in the table if there are not any delete blocks.</td></tr></tbody></table></div><p> Before a table is automatically repaired, MySQL adds a note about this in the error log. If you want to be able to recover from most problems without user intervention, you should use the options <code class="literal">BACKUP,FORCE</code>. This forces a repair of a table even if some rows would be deleted, but it keeps the old data file as a backup so that you can later examine what happened. </p><p> This option is available as of MySQL 3.23.25. </p></li><li><p> <code class="option">--ndb-connectstring=<em class="replaceable"><code>connect_string</code></em></code> </p><p> When using the <code class="literal">NDB</code> storage engine, it is possible to point out the management server that distributes the cluster configuration by setting the connect string option. See <a href="ndbcluster.html#mysql-cluster-connectstring" title="16.4.4.2. The MySQL Cluster connectstring">Section 16.4.4.2, “The MySQL Cluster <code class="literal">connectstring</code>”</a> for syntax. </p></li><li><p> <code class="option">--ndbcluster</code> </p><p> If the binary includes support for the <code class="literal">NDB Cluster</code> storage engine (from version 4.1.3, the MySQL-Max binaries are built with <code class="literal">NDB Cluster</code> enabled) the default disabling of support for the <code class="literal">NDB Cluster</code> storage engine can be overruled by using this option. Using the <code class="literal">NDB Cluster</code> storage engine is necessary for using MySQL Cluster. See <a href="ndbcluster.html" title="Chapter 16. MySQL Cluster">Chapter 16, <i>MySQL Cluster</i></a>. </p></li><li><p> <code class="option">--new</code> </p><p> The <code class="option">--new</code> option can be used to make the server behave as 4.1 in certain respects, easing a 4.0 to 4.1 upgrade: </p><div class="itemizedlist"><ul type="circle"><li><p> Hexadecimal strings such as <code class="literal">0xFF</code> are treated as strings by default rather than as numbers. (Works in 4.0.12 and up.) </p></li><li><p> <code class="literal">TIMESTAMP</code> is returned as a string with the format <code class="literal">'YYYY-MM-DD HH:MM:SS'</code>. (Works in 4.0.13 and up.) See <a href="data-types.html" title="Chapter 11. Data Types">Chapter 11, <i>Data Types</i></a>. </p></li></ul></div><p> This option can be used to help you see how your applications behave in MySQL 4.1, without actually upgrading to 4.1. </p></li><li><p> <code class="option">--old-passwords</code> </p><p> Force the server to generate short (pre-4.1) password hashes for new passwords. This is useful for compatibility when the server must support older client programs. See <a href="database-administration.html#password-hashing" title="5.6.9. Password Hashing in MySQL 4.1">Section 5.6.9, “Password Hashing in MySQL 4.1”</a>. </p></li><li><p> <code class="option">--old-protocol</code>, <code class="option">-o</code> </p><p> Use the 3.20 protocol for compatibility with some very old clients. </p></li><li><p> <code class="option">--one-thread</code> </p><p> Only use one thread (for debugging under Linux). This option is available only if the server is built with debugging enabled. See <a href="porting.html#debugging-server" title="E.1. Debugging a MySQL Server">Section E.1, “Debugging a MySQL Server”</a>. </p></li><li><p> <code class="option">--open-files-limit=<em class="replaceable"><code>count</code></em></code> </p><p> To change the number of file descriptors available to <span><strong class="command">mysqld</strong></span>. If this is not set or set to 0, then <span><strong class="command">mysqld</strong></span> uses this value to reserve file descriptors to use with <code class="literal">setrlimit()</code>. If this value is 0 then <span><strong class="command">mysqld</strong></span> reserves <code class="literal">max_connections*5</code> or <code class="literal">max_connections + table_cache*2</code> (whichever is larger) number of files. You should try increasing this if <span><strong class="command">mysqld</strong></span> gives you the error "Too many open files." </p></li><li><p> <code class="option">--pid-file=<em class="replaceable"><code>path</code></em></code> </p><p> The path to the process ID file used by <span><strong class="command">mysqld_safe</strong></span>. </p></li><li><p> <code class="option">--port=<em class="replaceable"><code>port_num</code></em>, -P <em class="replaceable"><code>port_num</code></em></code> </p><p> The port number to use when listening for TCP/IP connections. </p></li><li><p> <code class="option">--safe-mode</code> </p><p> Skip some optimization stages. </p></li><li><p> <code class="option">--safe-show-database</code> </p><p> With this option, the <code class="literal">SHOW DATABASES</code> statement displays only the names of those databases for which the user has some kind of privilege. As of MySQL 4.0.2, this option is deprecated and does not do anything (it is enabled by default), because there is a <code class="literal">SHOW DATABASES</code> privilege that can be used to control access to database names on a per-account basis. See <a href="database-administration.html#privileges-provided" title="5.6.3. Privileges Provided by MySQL">Section 5.6.3, “Privileges Provided by MySQL”</a>. </p></li><li><p> <code class="option">--safe-user-create</code> </p><p> If this is enabled, a user cannot create new users with the <code class="literal">GRANT</code> statement, if the user does not have the <code class="literal">INSERT</code> privilege for the <code class="literal">mysql.user</code> table or any column in the table. </p></li><li><p> <code class="option">--secure-auth</code> </p><p> Disallow authentication for accounts that have old (pre-4.1) passwords. This option is available as of MySQL 4.1.1. </p></li><li><p> <code class="option">--shared-memory</code> </p><p> Enable shared-memory connections by local clients. This option is available only on Windows. It was added in MySQL 4.1.0. </p></li><li><p> <code class="option">--shared-memory-base-name=<em class="replaceable"><code>name</code></em></code> </p><p> The name to use for shared-memory connections. This option is available only on Windows. It was added in MySQL 4.1.0. </p></li><li><p> <code class="option">--skip-bdb</code> </p><p> Disable the <code class="literal">BDB</code> storage engine. This saves memory and might speed up some operations. Do not use this option if you require <code class="literal">BDB</code> tables. </p></li><li><p> <code class="option">--skip-concurrent-insert</code> </p><p> Turn off the ability to select and insert at the same time on <code class="literal">MyISAM</code> tables. (This is to be used only if you think you have found a bug in this feature.) </p></li><li><p> <code class="option">--skip-delay-key-write</code> </p><p> Ignore the <code class="literal">DELAY_KEY_WRITE</code> option for all tables. As of MySQL 4.0.3, you should use <code class="option">--delay-key-write=OFF</code> instead. See <a href="optimization.html#server-parameters" title="7.5.2. Tuning Server Parameters">Section 7.5.2, “Tuning Server Parameters”</a>. </p></li><li><p> <code class="option">--skip-external-locking</code> </p><p> do not use system locking. To use <span><strong class="command">isamchk</strong></span> or <span><strong class="command">myisamchk</strong></span>, you must shut down the server. See <a href="introduction.html#stability" title="1.4.3. MySQL Stability">Section 1.4.3, “MySQL Stability”</a>. In MySQL 3.23, you can use <code class="literal">CHECK TABLE</code> and <code class="literal">REPAIR TABLE</code> to check and repair <code class="literal">MyISAM</code> tables. This option previously was named <code class="option">--skip-locking</code>. </p></li><li><p> <code class="option">--skip-grant-tables</code> </p><p> This option causes the server not to use the privilege system at all. This gives anyone with access to the server <span class="emphasis"><em>unrestricted access</em></span> to <span class="emphasis"><em>all databases</em></span>. You can cause a running server to start using the grant tables again by executing <span><strong class="command">mysqladmin flush-privileges</strong></span> or <span><strong class="command">mysqladmin reload</strong></span> command from a system shell, or by issuing a MySQL <code class="literal">FLUSH PRIVILEGES</code> statement. This option also suppresses loading of user-defined functions (UDFs). </p></li><li><p> <code class="option">--skip-host-cache</code> </p><p> Do not use the internal hostname cache for faster name-to-IP resolution. Instead, query the DNS server every time a client connects. See <a href="optimization.html#dns" title="7.5.5. How MySQL Uses DNS">Section 7.5.5, “How MySQL Uses DNS”</a>. </p></li><li><p> <code class="option">--skip-innodb</code> </p><p> Disable the <code class="literal">InnoDB</code> storage engine. This saves memory and disk space and might speed up some operations. Do not use this option if you require <code class="literal">InnoDB</code> tables. </p></li><li><p> <code class="option">--skip-isam</code> </p><p> Disable the <code class="literal">ISAM</code> storage engine. As of MySQL 4.1, <code class="literal">ISAM</code> is disabled by default, so this option applies only if the server was configured with support for <code class="literal">ISAM</code>. This option was added in MySQL 4.1.1. </p></li><li><p> <code class="option">--skip-name-resolve</code> </p><p> Do not resolve hostnames when checking client connections. Use only IP numbers. If you use this option, all <code class="literal">Host</code> column values in the grant tables must be IP numbers or <code class="literal">localhost</code>. See <a href="optimization.html#dns" title="7.5.5. How MySQL Uses DNS">Section 7.5.5, “How MySQL Uses DNS”</a>. </p></li><li><p> <code class="option">--skip-ndbcluster</code> </p><p> Disable the <code class="literal">NDB Cluster</code> storage engine. This is the default for binaries that were built with <code class="literal">NDB Cluster</code> storage engine support, this means that the system allocates memory and other resources for this storage engine only if it is explicitly enabled. </p></li><li><p> <code class="option">--skip-networking</code> </p><p> Do not listen for TCP/IP connections at all. All interaction with <span><strong class="command">mysqld</strong></span> must be made via named pipes or shared memory (on Windows) or Unix socket files (on Unix). This option is highly recommended for systems where only local clients are allowed. See <a href="optimization.html#dns" title="7.5.5. How MySQL Uses DNS">Section 7.5.5, “How MySQL Uses DNS”</a>. </p></li><li><p> <code class="option">--skip-new</code> </p><p> do not use new, possibly wrong routines. </p></li><li><p> <code class="option">--skip-symlink</code> </p><p> This is the old form of <code class="option">--skip-symbolic-links</code>, for use before MySQL 4.0.13. </p></li><li><p> <code class="option">--standalone</code> </p><p> Windows-NT based systems only, instructs MySQL server to not run as a service. </p></li><li><p> <code class="option">--symbolic-links</code>, <code class="option">--skip-symbolic-links</code> </p><p> Enable or disable symbolic link support. This option has different effects on Windows and Unix: </p><div class="itemizedlist"><ul type="circle"><li><p> On Windows, enabling symbolic links allows you to establish a symbolic link to a database directory by creating a <code class="filename">directory.sym</code> file that contains the path to the real directory. See <a href="optimization.html#windows-symbolic-links" title="7.6.1.3. Using Symbolic Links for Databases on Windows">Section 7.6.1.3, “Using Symbolic Links for Databases on Windows”</a>. </p></li><li><p> On Unix, enabling symbolic links means that you can link a <code class="literal">MyISAM</code> index file or data file to another directory with the <code class="literal">INDEX DIRECTORY</code> or <code class="literal">DATA DIRECTORY</code> options of the <code class="literal">CREATE TABLE</code> statement. If you delete or rename the table, the files that its symbolic links point to also are deleted or renamed. See <a href="sql-syntax.html#create-table" title="13.1.5. CREATE TABLE Syntax">Section 13.1.5, “<code class="literal">CREATE TABLE</code> Syntax”</a>. </p></li></ul></div><p> This option was added in MySQL 4.0.13. </p></li><li><p> <code class="option">--skip-safemalloc</code> </p><p> If MySQL is configured with <code class="option">--with-debug=full</code>, all MySQL programs check for memory overruns during each memory allocation and memory freeing operation. This checking is very slow, so for the server you can avoid it when you do not need it by using the <code class="option">--skip-safemalloc</code> option. </p></li><li><p> <code class="option">--skip-show-database</code> </p><p> With this option, the <code class="literal">SHOW DATABASES</code> statement is allowed only to users who have the <code class="literal">SHOW DATABASES</code> privilege, and the statement displays all database names. Without this option, <code class="literal">SHOW DATABASES</code> is allowed to all users, but displays each database name only if the user has the <code class="literal">SHOW DATABASES</code> privilege or some privilege for the database. Note that any global privilege is a privilege for the database. </p></li><li><p> <code class="option">--skip-stack-trace</code> </p><p> do not write stack traces. This option is useful when you are running <span><strong class="command">mysqld</strong></span> under a debugger. On some systems, you also must use this option to get a core file. See <a href="porting.html#debugging-server" title="E.1. Debugging a MySQL Server">Section E.1, “Debugging a MySQL Server”</a>. </p></li><li><p> <code class="option">--skip-thread-priority</code> </p><p> Disable using thread priorities for faster response time. </p></li><li><p> <code class="option">--socket=<em class="replaceable"><code>path</code></em></code> </p><p> On Unix, this option specifies the Unix socket file to use for local connections. The default value is <code class="filename">/tmp/mysql.sock</code>. On Windows, the option specifies the pipe name to use for local connections that use a named pipe. The default value is <code class="literal">MySQL</code>. </p></li><li><p> <code class="option">--sql-mode=<em class="replaceable"><code>value</code></em>[,<em class="replaceable"><code>value</code></em>[,<em class="replaceable"><code>value</code></em>...]]</code> </p><p> Set the SQL mode for MySQL. See <a href="database-administration.html#server-sql-mode" title="5.2.2. The Server SQL Mode">Section 5.2.2, “The Server SQL Mode”</a>. This option was added in 3.23.41. </p></li><li><p> <code class="option">--temp-pool</code> </p><p> 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 “<span class="quote">leak</span>” memory, because it is being allocated to the directory entry cache rather than to the disk cache. </p></li><li><p> <code class="option">--transaction-isolation=<em class="replaceable"><code>level</code></em></code> </p><p> Sets the default transaction isolation level, which can be <code class="literal">READ-UNCOMMITTED</code>, <code class="literal">READ-COMMITTED</code>, <code class="literal">REPEATABLE-READ</code>, or <code class="literal">SERIALIZABLE</code>. See <a href="sql-syntax.html#set-transaction" title="13.4.6. SET TRANSACTION Syntax">Section 13.4.6, “<code class="literal">SET TRANSACTION</code> Syntax”</a>. </p></li><li><p> <code class="option">--tmpdir=<em class="replaceable"><code>path</code></em>, -t <em class="replaceable"><code>path</code></em></code> </p><p> The path of the directory to use for creating temporary files. It might be useful if your default <code class="literal">/tmp</code> directory resides on a partition that is too small to hold temporary tables. Starting from MySQL 4.1.0, this option accepts several paths that are used in round-robin fashion. Paths should be separated by colon characters (‘<code class="literal">:</code>’) on Unix and semicolon characters (‘<code class="literal">;</code>’) on Windows, NetWare, and OS/2. If the MySQL server is acting as a replication slave, you should not set <code class="option">--tmpdir</code> to point to a directory on a memory-based filesystem or to a directory that is cleared when the server host restarts. For more information about the storage location of temporary files, see <a href="problems.html#temporary-files" title="A.4.4. Where MySQL Stores Temporary Files">Section A.4.4, “Where MySQL Stores Temporary Files”</a>. A replication slave needs some of its temporary files to survive a machine restart so that it can replicate temporary tables or <code class="literal">LOAD DATA INFILE</code> operations. If files in the temporary file directory are lost when the server restarts, replication fails. </p></li><li><p> <code class="option">--user={<em class="replaceable"><code>user_name</code></em> | <em class="replaceable"><code>user_id</code></em>}, -u {<em class="replaceable"><code>user_name</code></em> | <em class="replaceable"><code>user_id</code></em>}</code> </p><p> Run the <span><strong class="command">mysqld</strong></span> server as the user having the name <em class="replaceable"><code>user_name</code></em> or the numeric user ID <em class="replaceable"><code>user_id</code></em>. (“<span class="quote">User</span>” in this context refers to a system login account, not a MySQL user listed in the grant tables.) </p><p> This option is <span class="emphasis"><em>mandatory</em></span> when starting <span><strong class="command">mysqld</strong></span> as <code class="literal">root</code>. The server changes its user ID during its startup sequence, causing it to run as that particular user rather than as <code class="literal">root</code>. See <a href="database-administration.html#security-guidelines" title="5.5.1. General Security Guidelines">Section 5.5.1, “General Security Guidelines”</a>. </p><p> Starting from MySQL 3.23.56 and 4.0.12: To avoid a possible security hole where a user adds a <code class="option">--user=root</code> option to a <code class="filename">my.cnf</code> file (thus causing the server to run as <code class="literal">root</code>), <span><strong class="command">mysqld</strong></span> uses only the first <code class="option">--user</code> option specified and produces a warning if there are multiple <code class="option">--user</code> options. Options in <code class="filename">/etc/my.cnf</code> and <code class="filename">$MYSQL_HOME/my.cnf</code> are processed before command-line options, so it is recommended that you put a <code class="option">--user</code> option in <code class="filename">/etc/my.cnf</code> and specify a value other than <code class="literal">root</code>. The option in <code class="filename">/etc/my.cnf</code> is found before any other <code class="option">--user</code> options, which ensures that the server runs as a user other than <code class="literal">root</code>, and that a warning results if any other <code class="option">--user</code> option is found. </p></li><li><p> <code class="option">--version</code>, <code class="option">-V</code> </p><p> Display version information and exit. </p></li></ul></div><p> As of MySQL 4.0, you can assign a value to a server system variable by using an option of the form <code class="option">--<em class="replaceable"><code>var_name</code></em>=<em class="replaceable"><code>value</code></em></code>. For example, <code class="option">--key_buffer_size=32M</code> sets the <code class="literal">key_buffer_size</code> variable to a value of 32MB. </p><p> Note that when setting a variable to a value, MySQL might automatically correct it to stay within a given range, or adjust the value to the closest allowable value if only certain values are allowed. </p><p> It is also possible to set variables by using <code class="option">--set-variable=<em class="replaceable"><code>var_name</code></em>=<em class="replaceable"><code>value</code></em></code> or <code class="option">--<em class="replaceable"><code>var_name</code></em>=<em class="replaceable"><code>value</code></em></code> syntax. However, this syntax is deprecated as of MySQL 4.0. </p><p> You can find a full description for all variables in <a href="database-administration.html#server-system-variables" title="5.2.3. Server System Variables">Section 5.2.3, “Server System Variables”</a>. The section on tuning server parameters includes information on how to optimize them. See <a href="optimization.html#server-parameters" title="7.5.2. Tuning Server Parameters">Section 7.5.2, “Tuning Server Parameters”</a>. </p><p> You can change the values of most system variables for a running server with the <code class="literal">SET</code> statement. See <a href="sql-syntax.html#set-option" title="13.5.3. SET Syntax">Section 13.5.3, “<code class="literal">SET</code> Syntax”</a>. </p><p> If you want to restrict the maximum value that a startup option can be set to with <code class="literal">SET</code>, you can define this by using the <code class="option">--maximum-<em class="replaceable"><code>var_name</code></em></code> command-line option. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="server-sql-mode"></a>5.2.2. The Server SQL Mode</h3></div></div></div><p> The MySQL server can operate in different SQL modes, and (as of MySQL 4.1) can apply these modes differentially for different clients. This allows an application to tailor server operation to its own requirements. </p><p> 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. </p><p> You can set the default SQL mode by starting <span><strong class="command">mysqld</strong></span> with the <code class="option">--sql-mode="<em class="replaceable"><code>modes</code></em>"</code> option. The value also can be empty (<code class="option">--sql-mode=""</code>) if you want to reset it. </p><p> Beginning with MySQL 4.1, you can also change the SQL mode after startup time by setting the <code class="literal">sql_mode</code> variable with a <code class="literal">SET [SESSION|GLOBAL] sql_mode='<em class="replaceable"><code>modes</code></em>'</code> statement. Setting the <code class="literal">GLOBAL</code> variable requires the <code class="literal">SUPER</code> privilege and affects the operation of all clients that connect from that time on. Setting the <code class="literal">SESSION</code> variable affects only the current client. Any client can change its session <code class="literal">sql_mode</code> value. </p><p> <em class="replaceable"><code>modes</code></em> is a list of different modes separated by comma (‘<code class="literal">,</code>’) characters. You can retrieve the current mode by issuing a <code class="literal">SELECT @@sql_mode</code> statement. The default value is empty (no modes set). </p><a class="indexterm" name="id2774581"></a><p> The most important <code class="literal">sql_mode</code> value is <code class="literal">ANSI</code>, which changes syntax and behavior to be more conformant to standard SQL. This mode is available beginning in MySQL 4.1.1 </p><p> The following list describes all the supported modes: </p><div class="itemizedlist"><ul type="disc"><li><p> <a class="indexterm" name="id2774612"></a> <code class="literal">ANSI_QUOTES</code> </p><p> Treat ‘<code class="literal">"</code>’ as an identifier quote character (like the ‘<code class="literal">`</code>’ quote character) and not as a string quote character. You can still use ‘<code class="literal">`</code>’ to quote identifiers in ANSI mode. With <code class="literal">ANSI_QUOTES</code> enabled, you cannot use double quotes to quote a literal string, because it is interpreted as an identifier. (New in MySQL 4.0.0) </p></li><li><p> <a class="indexterm" name="id2774654"></a> <code class="literal">IGNORE_SPACE</code> </p><p> Allow spaces between a function name and the ‘<code class="literal">(</code>’ 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 <code class="literal">USER()</code> function, the name of the <code class="literal">user</code> table in the <code class="literal">mysql</code> database and the <code class="literal">User</code> column in that table become reserved, so you must quote them: </p><pre class="programlisting">SELECT "User" FROM mysql."user"; </pre><p> (New in MySQL 4.0.0) </p></li><li><p> <a class="indexterm" name="id2774710"></a> <code class="literal">NO_AUTO_VALUE_ON_ZERO</code> </p><p> <code class="literal">NO_AUTO_VALUE_ON_ZERO</code> affects handling of <code class="literal">AUTO_INCREMENT</code> columns. Normally, you generate the next sequence number for the column by inserting either <code class="literal">NULL</code> or <code class="literal">0</code> into it. <code class="literal">NO_AUTO_VALUE_ON_ZERO</code> suppresses this behavior for <code class="literal">0</code> so that only <code class="literal">NULL</code> generates the next sequence number. (New in MySQL 4.1.1) </p><p> This mode can be useful if <code class="literal">0</code> has been stored in a table's <code class="literal">AUTO_INCREMENT</code> column. (This is not a recommended practice, by the way.) For example, if you dump the table with <span><strong class="command">mysqldump</strong></span> and then reload it, MySQL normally generates new sequence numbers when it encounters the <code class="literal">0</code> values, resulting in a table with different contents than the one that was dumped. Enabling <code class="literal">NO_AUTO_VALUE_ON_ZERO</code> before reloading the dump file solves this problem. As of MySQL 4.1.1, <span><strong class="command">mysqldump</strong></span> automatically includes a statement in the dump output to enable <code class="literal">NO_AUTO_VALUE_ON_ZERO</code>. </p></li><li><p> <a class="indexterm" name="id2774802"></a> <code class="literal">NO_DIR_IN_CREATE</code> </p><p> When creating a table, ignore all <code class="literal">INDEX DIRECTORY</code> and <code class="literal">DATA DIRECTORY</code> directives. This option is useful on slave replication servers. (New in MySQL 4.0.15) </p></li><li><p> <a class="indexterm" name="id2774833"></a> <code class="literal">NO_FIELD_OPTIONS</code> </p><p> do not print MySQL-specific column options in the output of <code class="literal">SHOW CREATE TABLE</code>. This mode is used by <span><strong class="command">mysqldump</strong></span> in portability mode. (New in MySQL 4.1.1) </p></li><li><p> <a class="indexterm" name="id2774864"></a> <code class="literal">NO_KEY_OPTIONS</code> </p><p> do not print MySQL-specific index options in the output of <code class="literal">SHOW CREATE TABLE</code>. This mode is used by <span><strong class="command">mysqldump</strong></span> in portability mode. (New in MySQL 4.1.1) </p></li><li><p> <a class="indexterm" name="id2774895"></a> <code class="literal">NO_TABLE_OPTIONS</code> </p><p> do not print MySQL-specific table options (such as <code class="literal">ENGINE</code>) in the output of <code class="literal">SHOW CREATE TABLE</code>. This mode is used by <span><strong class="command">mysqldump</strong></span> in portability mode. (New in MySQL 4.1.1) </p></li><li><p> <a class="indexterm" name="id2774930"></a> <code class="literal">NO_UNSIGNED_SUBTRACTION</code> </p><p> In subtraction operations, do not mark the result as <code class="literal">UNSIGNED</code> if one of the operands is unsigned. Note that this makes <code class="literal">UNSIGNED BIGINT</code> not 100% usable in all contexts. See <a href="functions.html#cast-functions" title="12.8. Cast Functions and Operators">Section 12.8, “Cast Functions and Operators”</a>. (New in MySQL 4.0.2) </p></li><li><p> <a class="indexterm" name="id2774967"></a> <code class="literal">ONLY_FULL_GROUP_BY</code> </p><p> Do not allow queries that in the <code class="literal">GROUP BY</code> part refer to a not selected column. (New in MySQL 4.0.0) </p></li><li><p> <a class="indexterm" name="id2774993"></a> <code class="literal">PIPES_AS_CONCAT</code> </p><p> Treat <code class="literal">||</code> as a string concatenation operator (same as <code class="literal">CONCAT()</code>) rather than as a synonym for <code class="literal">OR</code>. (New in MySQL 4.0.0) </p></li><li><p> <a class="indexterm" name="id2775027"></a> <code class="literal">REAL_AS_FLOAT</code> </p><p> Treat <code class="literal">REAL</code> as a synonym for <code class="literal">FLOAT</code> rather than as a synonym for <code class="literal">DOUBLE</code>. (New in MySQL 4.0.0) </p></li></ul></div><p> The following special modes are provided as shorthand for combinations of mode values from the preceding list. All are available as of MySQL 4.1.1. </p><p> The descriptions include all mode values that are available in the most recent version of MySQL. For older versions, a combination mode does not include individual mode values that are not available except in newer versions. </p><div class="itemizedlist"><ul type="disc"><li><p> <a class="indexterm" name="id2775078"></a> <code class="literal">ANSI</code> </p><p> Equivalent to <code class="literal">REAL_AS_FLOAT</code>, <code class="literal">PIPES_AS_CONCAT</code>, <code class="literal">ANSI_QUOTES</code>, <code class="literal">IGNORE_SPACE</code>. Before MySQL 4.1.11, <code class="literal">ANSI</code> also includes <code class="literal">ONLY_FULL_GROUP_BY</code>. See <a href="introduction.html#ansi-mode" title="1.8.3. Running MySQL in ANSI Mode">Section 1.8.3, “Running MySQL in ANSI Mode”</a>. </p></li><li><p> <a class="indexterm" name="id2775128"></a> <code class="literal">DB2</code> </p><p> Equivalent to <code class="literal">PIPES_AS_CONCAT</code>, <code class="literal">ANSI_QUOTES</code>, <code class="literal">IGNORE_SPACE</code>, <code class="literal">NO_KEY_OPTIONS</code>, <code class="literal">NO_TABLE_OPTIONS</code>, <code class="literal">NO_FIELD_OPTIONS</code>. </p></li><li><p> <a class="indexterm" name="id2775172"></a> <code class="literal">MAXDB</code> </p><p> Equivalent to <code class="literal">PIPES_AS_CONCAT</code>, <code class="literal">ANSI_QUOTES</code>, <code class="literal">IGNORE_SPACE</code>, <code class="literal">NO_KEY_OPTIONS</code>, <code class="literal">NO_TABLE_OPTIONS</code>, <code class="literal">NO_FIELD_OPTIONS</code>. </p></li><li><p> <a class="indexterm" name="id2775216"></a> <code class="literal">MSSQL</code> </p><p> Equivalent to <code class="literal">PIPES_AS_CONCAT</code>, <code class="literal">ANSI_QUOTES</code>, <code class="literal">IGNORE_SPACE</code>, <code class="literal">NO_KEY_OPTIONS</code>, <code class="literal">NO_TABLE_OPTIONS</code>, <code class="literal">NO_FIELD_OPTIONS</code>. </p></li><li><p> <a class="indexterm" name="id2775260"></a> <code class="literal">MYSQL323</code> </p><p> Equivalent to <code class="literal">NO_FIELD_OPTIONS</code>. </p></li><li><p> <a class="indexterm" name="id2775285"></a> <code class="literal">MYSQL40</code> </p><p> Equivalent to <code class="literal">NO_FIELD_OPTIONS</code>. </p></li><li><p> <a class="indexterm" name="id2775310"></a> <code class="literal">ORACLE</code> </p><p> Equivalent to <code class="literal">PIPES_AS_CONCAT</code>, <code class="literal">ANSI_QUOTES</code>, <code class="literal">IGNORE_SPACE</code>, <code class="literal">NO_KEY_OPTIONS</code>, <code class="literal">NO_TABLE_OPTIONS</code>, <code class="literal">NO_FIELD_OPTIONS</code>. </p></li><li><p> <a class="indexterm" name="id2775354"></a> <code class="literal">POSTGRESQL</code> </p><p> Equivalent to <code class="literal">PIPES_AS_CONCAT</code>, <code class="literal">ANSI_QUOTES</code>, <code class="literal">IGNORE_SPACE</code>, <code class="literal">NO_KEY_OPTIONS</code>, <code class="literal">NO_TABLE_OPTIONS</code>, <code class="literal">NO_FIELD_OPTIONS</code>. </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="server-system-variables"></a>5.2.3. Server System Variables</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="database-administration.html#dynamic-system-variables">5.2.3.1. Dynamic System Variables</a></span></dt></dl></div><a class="indexterm" name="id2775410"></a><a class="indexterm" name="id2775417"></a><a class="indexterm" name="id2775424"></a><a class="indexterm" name="id2775434"></a><p> The server maintains many system variables that indicate how it is configured. All of them have default values. They can be set at server startup using options on the command line or in option files. Most of them can be set at runtime using the <code class="literal">SET</code> statement. </p><p> Beginning with MySQL 4.0.3, the <span><strong class="command">mysqld</strong></span> server maintains two kinds of variables. Global variables affect the overall operation of the server. Session variables affect its operation for individual client connections. </p><p> When the server starts, it initializes all global variables to their default values. These defaults can be changed by options specified in option files or on the command line. After the server starts, those global variables that are dynamic can be changed by connecting to the server and issuing a <code class="literal">SET GLOBAL <em class="replaceable"><code>var_name</code></em></code> statement. To change a global variable, you must have the <code class="literal">SUPER</code> privilege. </p><p> The server also maintains a set of session variables for each client that connects. The client's session variables are initialized at connect time using the current values of the corresponding global variables. For those session variables that are dynamic, the client can change them by issuing a <code class="literal">SET SESSION <em class="replaceable"><code>var_name</code></em></code> statement. Setting a session variable requires no special privilege, but a client can change only its own session variables, not those of any other client. </p><p> A change to a global variable is visible to any client that accesses that global variable. However, it affects the corresponding session variable that is initialized from the global variable only for clients that connect after the change. It does not affect the session variable for any client that is currently connected (not even that of the client that issues the <code class="literal">SET GLOBAL</code> statement). </p><p> When setting a variable using a startup option, variable values can be given with a suffix of <code class="literal">K</code>, <code class="literal">M</code>, or <code class="literal">G</code> to indicate kilobytes, megabytes, or gigabytes, respectively. For example, the following command starts the server with a key buffer size of 16 megabytes: </p><pre class="programlisting">mysqld --key_buffer_size=16M </pre><p> Before MySQL 4.0, use this syntax instead: </p><pre class="programlisting">mysqld --set-variable=key_buffer_size=16M </pre><p> The lettercase of suffix letters does not matter; <code class="literal">16M</code> and <code class="literal">16m</code> are equivalent. </p><p> At runtime, use the <code class="literal">SET</code> statement to set system variables. In this context, suffix letters cannot be used, but the value can take the form of an expression: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SET sort_buffer_size = 10 * 1024 * 1024;</code></strong> </pre><p> To specify explicitly whether to set the global or session variable, use the <code class="literal">GLOBAL</code> or <code class="literal">SESSION</code> options: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SET GLOBAL sort_buffer_size = 10 * 1024 * 1024;</code></strong> mysql> <strong class="userinput"><code>SET SESSION sort_buffer_size = 10 * 1024 * 1024;</code></strong> </pre><p> Without either option, the statement sets the session variable. </p><p> The variables that can be set at runtime are listed in <a href="database-administration.html#dynamic-system-variables" title="5.2.3.1. Dynamic System Variables">Section 5.2.3.1, “Dynamic System Variables”</a>. </p><p> If you want to restrict the maximum value to which a system variable can be set with the <code class="literal">SET</code> statement, you can specify this maximum by using an option of the form <code class="option">--maximum-<em class="replaceable"><code>var_name</code></em></code> at server startup. For example, to prevent the value of <code class="literal">query_cache_size</code> from being increased to more than 32MB at runtime, use the option <code class="option">--maximum-query_cache_size=32M</code>. This feature is available as of MySQL 4.0.2. </p><p> You can view system variables and their values by using the <code class="literal">SHOW VARIABLES</code> statement. See <a href="language-structure.html#system-variables" title="9.4. System Variables">Section 9.4, “System Variables”</a> for more information. </p><pre class="programlisting">mysql> <strong class="userinput"><code>SHOW VARIABLES;</code></strong> +---------------------------------+---------------------------------------------------------+ | Variable_name | Value | +---------------------------------+---------------------------------------------------------+ | back_log | 50 | | basedir | /usr/local/mysql | | bdb_cache_size | 8388600 | | bdb_home | /usr/local/mysql | | bdb_log_buffer_size | 32768 | | bdb_logdir | | | bdb_max_lock | 10000 | | bdb_shared_data | OFF | | bdb_tmpdir | /tmp/ | | binlog_cache_size | 32768 | | bulk_insert_buffer_size | 8388608 | | character_set_client | latin1 | | character_set_connection | latin1 | | character_set_database | latin1 | | character_set_results | latin1 | | character_set_server | latin1 | | character_set_system | utf8 | | character_sets_dir | /usr/local/mysql/share/charsets/ | | collation_connection | latin1_swedish_ci | | collation_database | latin1_swedish_ci | | collation_server | latin1_swedish_ci | | concurrent_insert | ON | | connect_timeout | 5 | | datadir | /usr/local/mysql/data/ | | date_format | %Y-%m-%d | | datetime_format | %Y-%m-%d %H:%i:%s | | default_week_format | 0 | | delay_key_write | ON | | delayed_insert_limit | 100 | | delayed_insert_timeout | 300 | | delayed_queue_size | 1000 | | expire_logs_days | 0 | | flush | OFF | | flush_time | 1800 | | ft_boolean_syntax | + -><()~*:""&| | | ft_max_word_len | 84 | | ft_min_word_len | 4 | | ft_query_expansion_limit | 20 | | ft_stopword_file | (built-in) | | group_concat_max_len | 1024 | | have_archive | NO | | have_bdb | YES | | have_blackhole_engine | NO | | have_compress | YES | | have_crypt | NO | | have_csv | NO | | have_example_engine | NO | | have_geometry | YES | | have_innodb | YES | | have_isam | NO | | have_ndbcluster | NO | | have_openssl | NO | | have_query_cache | YES | | have_raid | NO | | have_rtree_keys | YES | | have_symlink | YES | | init_connect | | | init_file | | | init_slave | | | innodb_additional_mem_pool_size | 1048576 | | innodb_autoextend_increment | 8 | | innodb_buffer_pool_awe_mem_mb | 0 | | innodb_buffer_pool_size | 8388608 | | innodb_data_file_path | ibdata1:10M:autoextend | | innodb_data_home_dir | | | innodb_fast_shutdown | ON | | innodb_file_io_threads | 4 | | innodb_file_per_table | OFF | | innodb_flush_log_at_trx_commit | 1 | | innodb_flush_method | | | innodb_force_recovery | 0 | | innodb_lock_wait_timeout | 50 | | innodb_locks_unsafe_for_binlog | OFF | | innodb_log_arch_dir | | | innodb_log_archive | OFF | | innodb_log_buffer_size | 1048576 | | innodb_log_file_size | 5242880 | | innodb_log_files_in_group | 2 | | innodb_log_group_home_dir | ./ | | innodb_max_dirty_pages_pct | 90 | | innodb_max_purge_lag | 0 | | innodb_mirrored_log_groups | 1 | | innodb_open_files | 300 | | innodb_table_locks | ON | | innodb_thread_concurrency | 8 | | interactive_timeout | 28800 | | join_buffer_size | 131072 | | key_buffer_size | 16777216 | | key_cache_age_threshold | 300 | | key_cache_block_size | 1024 | | key_cache_division_limit | 100 | | language | /usr/local/mysql/share/english/ | | large_files_support | ON | | license | GPL | | local_infile | ON | | log | ON | | log_bin | ON | | log_error | ./megalon.err | | log_slave_updates | OFF | | log_slow_queries | OFF | | log_update | OFF | | log_warnings | 1 | | long_query_time | 10 | | low_priority_updates | OFF | | lower_case_file_system | OFF | | lower_case_table_names | 1 | | max_allowed_packet | 1048576 | | max_binlog_cache_size | 4294967295 | | max_binlog_size | 1073741824 | | max_connect_errors | 10 | | max_connections | 100 | | max_delayed_threads | 20 | | max_error_count | 64 | | max_heap_table_size | 16777216 | | max_insert_delayed_threads | 20 | | max_join_size | 4294967295 | | max_length_for_sort_data | 1024 | | max_relay_log_size | 0 | | max_seeks_for_key | 4294967295 | | max_sort_length | 1024 | | max_tmp_tables | 32 | | max_user_connections | 0 | | max_write_lock_count | 4294967295 | | myisam_data_pointer_size | 4 | | myisam_max_extra_sort_file_size | 2147483648 | | myisam_max_sort_file_size | 2147483647 | | myisam_recover_options | OFF | | myisam_repair_threads | 1 | | myisam_sort_buffer_size | 8388608 | | named_pipe | OFF | | net_buffer_length | 16384 | | net_read_timeout | 30 | | net_retry_count | 10 | | net_write_timeout | 60 | | new | OFF | | old_passwords | OFF | | open_files_limit | 510 | | pid_file | /usr/local/mysql/megalon.pid | | port | 3306 | | preload_buffer_size | 32768 | | protocol_version | 10 | | query_alloc_block_size | 8192 | | query_cache_limit | 1048576 | | query_cache_min_res_unit | 4096 | | query_cache_size | 0 | | query_cache_type | ON | | query_cache_wlock_invalidate | OFF | | query_prealloc_size | 8192 | | range_alloc_block_size | 2048 | | read_buffer_size | 131072 | | read_only | OFF | | read_rnd_buffer_size | 262144 | | relay_log_purge | ON | | relay_log_space_limit | 0 | | rpl_recovery_rank | 0 | | secure_auth | OFF | | shared_memory | OFF | | shared_memory_base_name | MYSQL | | server_id | 1 | | skip_external_locking | ON | | skip_networking | OFF | | skip_show_database | OFF | | slave_net_timeout | 3600 | | slave_transaction_retries | 0 | | slow_launch_time | 2 | | sort_buffer_size | 2097144 | | sql_mode | | | storage_engine | MyISAM | | sql_notes | ON | | sql_warnings | ON | | sync_binlog | 0 | | sync_replication | 0 | | sync_replication_slave_id | 0 | | sync_replication_timeout | 0 | | sync_frm | ON | | system_time_zone | E. Australia Standard Time | | table_cache | 64 | | table_type | MyISAM | | thread_cache_size | 0 | | thread_stack | 196608 | | time_format | %H:%i:%s | | time_zone | SYSTEM | | tmp_table_size | 33554432 | | tmpdir | | | transaction_alloc_block_size | 8192 | | transaction_prealloc_size | 4096 | | tx_isolation | REPEATABLE-READ | | version | 4.1.13-max-log | | version_bdb | Sleepycat Software: Berkeley DB 4.1.24: (July 28, 2005) | | version_comment | MySQL Community Edition - Max (GPL) | | version_compile_machine | i686 | | version_compile_os | pc-linux-gnu | | wait_timeout | 28800 | +---------------------------------+---------------------------------------------------------+ 193 rows in set (0.00 sec) </pre><a class="indexterm" name="id2776048"></a><p> Most system variables are described here. Variables with no version indicated have been present since at least MySQL 3.22. <code class="literal">InnoDB</code> system variables are listed at <a href="innodb.html#innodb-start" title="15.5. InnoDB Startup Options">Section 15.5, “<code class="literal">InnoDB</code> Startup Options”</a>. </p><p> Values for buffer sizes, lengths, and stack sizes are given in bytes unless otherwise specified. </p><p> Information on tuning these variables can be found in <a href="optimization.html#server-parameters" title="7.5.2. Tuning Server Parameters">Section 7.5.2, “Tuning Server Parameters”</a>. </p><div class="itemizedlist"><ul type="disc"><li><p> <code class="literal">ansi_mode</code> </p><p> This is <code class="literal">ON</code> if <span><strong class="command">mysqld</strong></span> was started with <code class="option">--ansi</code>. See <a href="introduction.html#ansi-mode" title="1.8.3. Running MySQL in ANSI Mode">Section 1.8.3, “Running MySQL in ANSI Mode”</a>. This variable was added in MySQL 3.23.6 and removed in 3.23.41. See the description for <code class="literal">sql_mode</code>. </p></li><li><p> <code class="literal">back_log</code> </p><p> The number of outstanding connection requests MySQL can have. This comes into play when the main MySQL thread gets very many connection requests in a very short time. It then takes some time (although very little) for the main thread to check the connection and start a new thread. The <code class="literal">back_log</code> value indicates how many requests can be stacked during this short time before MySQL momentarily stops answering new requests. You need to increase this only if you expect a large number of connections in a short period of time. </p><p> In other words, this value is the size of the listen queue for incoming TCP/IP connections. Your operating system has its own limit on the size of this queue. The manual page for the Unix <code class="literal">listen()</code> system call should have more details. Check your OS documentation for the maximum value for this variable. Attempting to set <code class="literal">back_log</code> higher than your operating system limit is ineffective. </p></li><li><p> <code class="literal">basedir</code> </p><p> The MySQL installation base directory. This variable can be set with the <code class="option">--basedir</code> option. </p></li><li><p> <code class="literal">bdb_cache_size</code> </p><p> The size of the buffer that is allocated for caching indexes and rows for <code class="literal">BDB</code> tables. If you do not use <code class="literal">BDB</code> tables, you should start <span><strong class="command">mysqld</strong></span> with <code class="option">--skip-bdb</code> to not waste memory for this cache. This variable was added in MySQL 3.23.14. </p></li><li><p> <code class="literal">bdb_home</code> </p><p> The base directory for <code class="literal">BDB</code> tables. This should be assigned the same value as the <code class="literal">datadir</code> variable. This variable was added in MySQL 3.23.14. </p></li><li><p> <code class="literal">bdb_log_buffer_size</code> </p><p> The size of the buffer that is allocated for caching indexes and rows for <code class="literal">BDB</code> tables. If you do not use <code class="literal">BDB</code> tables, you should set this to 0 or start <span><strong class="command">mysqld</strong></span> with <code class="option">--skip-bdb</code> in order not to waste memory for this cache. This variable was added in MySQL 3.23.31. </p></li><li><p> <code class="literal">bdb_logdir</code> </p><p> The directory where the <code class="literal">BDB</code> storage engine writes its log files. This variable can be set with the <code class="option">--bdb-logdir</code> option. This variable was added in MySQL 3.23.14. </p></li><li><p> <code class="literal">bdb_max_lock</code> </p><p> The maximum number of locks you can have active on a <code class="literal">BDB</code> table (10,000 by default). You should increase this if errors such as the following occur when you perform long transactions or when <span><strong class="command">mysqld</strong></span> has to examine many rows to calculate a query: </p><pre class="programlisting">bdb: Lock table is out of available locks Got error 12 from ... </pre><p> This variable was added in MySQL 3.23.29. </p></li><li><p> <code class="literal">bdb_shared_data</code> </p><p> This is <code class="literal">ON</code> if you are using <code class="option">--bdb-shared-data</code>. This variable was added in MySQL 3.23.29. </p></li><li><p> <code class="literal">bdb_tmpdir</code> </p><p> The value of the <code class="option">--bdb-tmpdir</code> option. This variable was added in MySQL 3.23.14. </p></li><li><p> <code class="literal">bdb_version</code> </p><p> See the description for <code class="literal">version_bdb</code>. </p></li><li><p> <code class="literal">binlog_cache_size</code> </p><p> The size of the cache to hold the SQL statements for the binary log during a transaction. A binary log cache is allocated for each client if the server supports any transactional storage engines and, starting from MySQL 4.1.2, if the server has binary log enabled (<code class="option">--log-bin</code> option). If you often use large, multiple-statement transactions, you can increase this to get more performance. The <code class="literal">Binlog_cache_use</code> and <code class="literal">Binlog_cache_disk_use</code> status variables can be useful for tuning the size of this variable. This variable was added in MySQL 3.23.29. See <a href="database-administration.html#binary-log" title="5.10.4. The Binary Log">Section 5.10.4, “The Binary Log”</a>. </p></li><li><p> <code class="literal">bulk_insert_buffer_size</code> </p><p> <code class="literal">MyISAM</code> uses a special tree-like cache to make bulk inserts faster for <code class="literal">INSERT ... SELECT</code>, <code class="literal">INSERT ... VALUES (...), (...), ...</code>, and <code class="literal">LOAD DATA INFILE</code>. This variable limits the size of the cache tree in bytes per thread. Setting it to 0 disables this optimization. <span class="bold"><strong>Note</strong></span>: This cache is used only when adding data to a non-empty table. The default value is 8MB. This variable was added in MySQL 4.0.3. This variable previously was named <code class="literal">myisam_bulk_insert_tree_size</code>. </p></li><li><p> <code class="literal">character_set</code> </p><p> The default character set. This variable was added in MySQL 3.23.3, then removed in MySQL 4.1.1 and replaced by the various <code class="literal">character_set_<em class="replaceable"><code>xxx</code></em></code> variables. </p></li><li><p> <code class="literal">character_set_client</code> </p><p> The character set for statements that arrive from the client. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">character_set_connection</code> </p><p> The character set used for literals that do not have a character set introducer and for number-to-string conversion. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">character_set_database</code> </p><p> The character set used by the default database. The server sets this variable whenever the default database changes. If there is no default database, the variable has the same value as <code class="literal">character_set_server</code>. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">character_set_results</code> </p><p> The character set used for returning query results to the client. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">character_set_server</code> </p><p> The server default character set. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">character_set_system</code> </p><p> The character set used by the server for storing identifiers. The value is always <code class="literal">utf8</code>. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">character_sets</code> </p><p> The supported character sets. This variable was added in MySQL 3.23.15 and removed in MySQL 4.1.1. (Use <code class="literal">SHOW CHARACTER SET</code> for a list of character sets.) </p></li><li><p> <code class="literal">character_sets_dir</code> </p><p> The directory where character sets are installed. This variable was added in MySQL 4.1.2. </p></li><li><p> <code class="literal">collation_connection</code> </p><p> The collation of the connection character set. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">collation_database</code> </p><p> The collation used by the default database. The server sets this variable whenever the default database changes. If there is no default database, the variable has the same value as <code class="literal">collation_server</code>. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">collation_server</code> </p><p> The server default collation. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">concurrent_insert</code> </p><p> If <code class="literal">ON</code> (the default), MySQL allows <code class="literal">INSERT</code> and <code class="literal">SELECT</code> statements to run concurrently for <code class="literal">MyISAM</code> tables that have no free blocks in the middle. You can turn this option off by starting <span><strong class="command">mysqld</strong></span> with <code class="option">--safe</code> or <code class="option">--skip-new</code>. This variable was added in MySQL 3.23.7. </p></li><li><p> <a class="indexterm" name="id2776752"></a> <code class="literal">connect_timeout</code> </p><p> The number of seconds the <span><strong class="command">mysqld</strong></span> server waits for a connect packet before responding with <code class="literal">Bad handshake</code>. </p></li><li><p> <code class="literal">convert_character_set</code> </p><p> The current character set mapping that was set by <code class="literal">SET CHARACTER SET</code>. This variable was removed in MySQL 4.1. </p></li><li><p> <code class="literal">datadir</code> </p><p> The MySQL data directory. This variable can be set with the <code class="option">--datadir</code> option. </p></li><li><p> <code class="literal">date_format</code> </p><p> This variable is not implemented. </p></li><li><p> <code class="literal">datetime_format</code> </p><p> This variable is not implemented. </p></li><li><p> <code class="literal">default_week_format</code> </p><p> The default mode value to use for the <code class="literal">WEEK()</code> function. This variable is available as of MySQL 4.0.14. </p></li><li><p> <code class="literal">delay_key_write</code> </p><p> This option applies only to <code class="literal">MyISAM</code> tables. It can have one of the following values to affect handling of the <code class="literal">DELAY_KEY_WRITE</code> table option that can be used in <code class="literal">CREATE TABLE</code> statements. </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td><span class="bold"><strong>Option</strong></span></td><td><span class="bold"><strong>Description</strong></span></td></tr><tr><td><code class="literal">OFF</code></td><td><code class="literal">DELAY_KEY_WRITE</code> is ignored.</td></tr><tr><td><code class="literal">ON</code></td><td>MySQL honors the <code class="literal">DELAY_KEY_WRITE</code> option for <code class="literal">CREATE TABLE</code>. This is the default value.</td></tr><tr><td><code class="literal">ALL</code></td><td>All new opened tables are treated as if they were created with the <code class="literal">DELAY_KEY_WRITE</code> option enabled.</td></tr></tbody></table></div><p> If <code class="literal">DELAY_KEY_WRITE</code> is enabled, this means that the key buffer for tables with this option are not flushed on every index update, but only when a table is closed. This speeds up writes on keys a lot, but if you use this feature, you should add automatic checking of all <code class="literal">MyISAM</code> tables by starting the server with the <code class="option">--myisam-recover</code> option (for example, <code class="option">--myisam-recover=BACKUP,FORCE</code>). See <a href="database-administration.html#server-options" title="5.2.1. mysqld Command-Line Options">Section 5.2.1, “<span><strong class="command">mysqld</strong></span> Command-Line Options”</a> and <a href="storage-engines.html#myisam-start" title="14.1.1. MyISAM Startup Options">Section 14.1.1, “<code class="literal">MyISAM</code> Startup Options”</a>. </p><p> Note that <code class="option">--external-locking</code> does not offer any protection against index corruption for tables that use delayed key writes. </p><p> This variable was added in MySQL 3.23.8. </p></li><li><p> <code class="literal">delayed_insert_limit</code> </p><p> After inserting <code class="literal">delayed_insert_limit</code> delayed rows, the <code class="literal">INSERT DELAYED</code> handler thread checks whether there are any <code class="literal">SELECT</code> statements pending. If so, it allows them to execute before continuing to insert delayed rows. </p></li><li><p> <code class="literal">delayed_insert_timeout</code> </p><p> How long an <code class="literal">INSERT DELAYED</code> handler thread should wait for <code class="literal">INSERT</code> statements before terminating. </p></li><li><p> <code class="literal">delayed_queue_size</code> </p><p> This is a per-table limit on the number of rows to queue when handling <code class="literal">INSERT DELAYED</code> statements. If the queue becomes full, any client that issues an <code class="literal">INSERT DELAYED</code> statement waits until there is room in the queue again. </p></li><li><p> <code class="literal">expire_logs_days</code> </p><p> The number of days for automatic binary log removal. The default is 0, which means “<span class="quote">no automatic removal</span>”. Possible removals happen at startup and at binary log rotation. This variable was added in MySQL 4.1.0. </p></li><li><p> <code class="literal">flush</code> </p><p> This is <code class="literal">ON</code> if you have started <span><strong class="command">mysqld</strong></span> with the <code class="option">--flush</code> option. This variable was added in MySQL 3.22.9. </p></li><li><p> <code class="literal">flush_time</code> </p><p> If this is set to a non-zero value, all tables are closed every <code class="literal">flush_time</code> seconds to free up resources and sync unflushed data to disk. We recommend this option only on Windows 9x or Me, or on systems with minimal resources available. This variable was added in MySQL 3.22.18. </p></li><li><p> <code class="literal">ft_boolean_syntax</code> </p><p> The list of operators supported by boolean full-text searches performed using <code class="literal">IN BOOLEAN MODE</code>. See <a href="functions.html#fulltext-boolean" title="12.7.1. Boolean Full-Text Searches">Section 12.7.1, “Boolean Full-Text Searches”</a>. This variable was added as a read-only variable in MySQL 4.0.1. It can be modified as of MySQL 4.1.2. </p><p> The default variable value is <code class="literal">'+ -><()~*:""&|'</code>. The rules for changing the value are as follows: </p><div class="itemizedlist"><ul type="circle"><li><p> Operator function is determined by position within the string. </p></li><li><p> The replacement value must be 14 characters. </p></li><li><p> Each character must be an ASCII non-alphanumeric character. </p></li><li><p> Either the first or second character must be a space. </p></li><li><p> No duplicates are allowed except the phrase quoting operators in positions 11 and 12. These two characters are not required to be the same, but they are the only two that may be. </p></li><li><p> Positions 10, 13, and 14 (which by default are set to ‘<code class="literal">:</code>’, ‘<code class="literal">&</code>’, and ‘<code class="literal">|</code>’) are reserved for future extensions. </p></li></ul></div></li><li><p> <code class="literal">ft_max_word_len</code> </p><p> The maximum length of the word to be included in a <code class="literal">FULLTEXT</code> index. This variable was added in MySQL 4.0.0. </p><p> <span class="bold"><strong>Note</strong></span>: <code class="literal">FULLTEXT</code> indexes must be rebuilt after changing this variable. Use <code class="literal">REPAIR TABLE <em class="replaceable"><code>tbl_name</code></em> QUICK</code>. </p></li><li><p> <code class="literal">ft_min_word_len</code> </p><p> The minimum length of the word to be included in a <code class="literal">FULLTEXT</code> index. This variable was added in MySQL 4.0.0. </p><p> <span class="bold"><strong>Note</strong></span>: <code class="literal">FULLTEXT</code> indexes must be rebuilt after changing this variable. Use <code class="literal">REPAIR TABLE <em class="replaceable"><code>tbl_name</code></em> QUICK</code>. </p></li><li><p> <code class="literal">ft_query_expansion_limit</code> </p><p> The number of top matches to use for full-text searches performed using <code class="literal">WITH QUERY EXPANSION</code>. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">ft_stopword_file</code> </p><p> The file from which to read the list of stopwords for full-text searches. All the words from the file are used; comments are <span class="emphasis"><em>not</em></span> honored. By default, a built-in list of stopwords is used (as defined in the <code class="filename">myisam/ft_static.c</code> file). Setting this variable to the empty string (<code class="literal">''</code>) disables stopword filtering. This variable was added in MySQL 4.0.10. </p><p> <span class="bold"><strong>Note</strong></span>: <code class="literal">FULLTEXT</code> indexes must be rebuilt after changing this variable or the contents of the stopword file. Use <code class="literal">REPAIR TABLE <em class="replaceable"><code>tbl_name</code></em> QUICK</code>. </p></li><li><p> <code class="literal">group_concat_max_len</code> </p><p> The maximum allowed result length for the <code class="literal">GROUP_CONCAT()</code> function. This variable was added in MySQL 4.1.0. </p></li><li><p> <code class="literal">have_archive</code> </p><p> <code class="literal">YES</code> if <span><strong class="command">mysqld</strong></span> supports <code class="literal">ARCHIVE</code> tables, <code class="literal">NO</code> if not. This variable was added in MySQL 4.1.3. </p></li><li><p> <code class="literal">have_bdb</code> </p><p> <code class="literal">YES</code> if <span><strong class="command">mysqld</strong></span> supports <code class="literal">BDB</code> tables. <code class="literal">DISABLED</code> if <code class="option">--skip-bdb</code> is used. This variable was added in MySQL 3.23.30. </p></li><li><p> <code class="literal">have_blackhole_engine</code> </p><p> <code class="literal">YES</code> if <span><strong class="command">mysqld</strong></span> supports <code class="literal">BLACKHOLE</code> tables, <code class="literal">NO</code> if not. This variable was added in MySQL 4.1.11. </p></li><li><p> <code class="literal">have_compress</code> </p><p> Whether the <code class="literal">zlib</code> compression library is available to the server. If not, the <code class="literal">COMPRESS()</code> and <code class="literal">UNCOMPRESS()</code> functions cannot be used. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">have_crypt</code> </p><p> Whether the <code class="literal">crypt()</code> system call is available to the server. If not, the <code class="literal">ENCRYPT()</code> function cannot be used. This variable was added in MySQL 4.0.10. </p></li><li><p> <code class="literal">have_csv</code> </p><p> <code class="literal">YES</code> if <span><strong class="command">mysqld</strong></span> supports <code class="literal">ARCHIVE</code> tables, <code class="literal">NO</code> if not. This variable was added in MySQL 4.1.4. </p></li><li><p> <code class="literal">have_example_engine</code> </p><p> <code class="literal">YES</code> if <span><strong class="command">mysqld</strong></span> supports <code class="literal">EXAMPLE</code> tables, <code class="literal">NO</code> if not. This variable was added in MySQL 4.1.4. </p></li><li><p> <code class="literal">have_geometry</code> </p><p> Whether the server supports spatial data types. This variable was added in MySQL 4.1.3. </p></li><li><p> <code class="literal">have_innodb</code> </p><p> <code class="literal">YES</code> if <span><strong class="command">mysqld</strong></span> supports <code class="literal">InnoDB</code> tables. <code class="literal">DISABLED</code> if <code class="option">--skip-innodb</code> is used. This variable was added in MySQL 3.23.37. </p></li><li><p> <code class="literal">have_isam</code> </p><p> <code class="literal">YES</code> if <span><strong class="command">mysqld</strong></span> supports <code class="literal">ISAM</code> tables. <code class="literal">DISABLED</code> if <code class="option">--skip-isam</code> is used. This variable was added in MySQL 3.23.30. </p></li><li><p> <code class="literal">have_ndbcluster</code> </p><p> <code class="literal">YES</code> if <span><strong class="command">mysqld</strong></span> supports <code class="literal">NDB Cluster</code> tables. <code class="literal">DISABLED</code> if <code class="option">--skip-ndbcluster</code> is used. This variable was added in MySQL 4.1.2. </p></li><li><p> <code class="literal">have_openssl</code> </p><p> <code class="literal">YES</code> if <span><strong class="command">mysqld</strong></span> supports SSL (encryption) of the client/server protocol. This variable was added in MySQL 3.23.43. </p></li><li><p> <code class="literal">have_query_cache</code> </p><p> <code class="literal">YES</code> if <span><strong class="command">mysqld</strong></span> supports the query cache. This variable was added in MySQL 4.0.2. </p></li><li><p> <code class="literal">have_raid</code> </p><p> <code class="literal">YES</code> if <span><strong class="command">mysqld</strong></span> supports the <code class="literal">RAID</code> option. This variable was added in MySQL 3.23.30. </p></li><li><p> <code class="literal">have_rtree_keys</code> </p><p> Whether <code class="literal">RTREE</code> indexes are available. (These are used for spatial indexes in <code class="literal">MyISAM</code> tables.) This variable was added in MySQL 4.1.3. </p></li><li><p> <code class="literal">have_symlink</code> </p><p> Whether symbolic link support is enabled. This is required on Unix for support of the <code class="literal">DATA DIRECTORY</code> and <code class="literal">INDEX DIRECTORY</code> table options. </p><p> This variable was added in MySQL 4.0.0. </p></li><li><p> <code class="literal">init_connect</code> </p><p> A string to be executed by the server for each client that connects. The string consists of one or more SQL statements. To specify multiple statements, separate them by semicolon characters. For example, each client begins by default with autocommit mode enabled. There is no global server variable to specify that autocommit should be disabled by default, but <code class="literal">init_connect</code> can be used to achieve the same effect: </p><pre class="programlisting">SET GLOBAL init_connect='SET AUTOCOMMIT=0'; </pre><p> This variable can also be set on the command line or in an option file. To set the variable as just shown using an option file, include these lines: </p><pre class="programlisting">[mysqld] init_connect='SET AUTOCOMMIT=0' </pre><p> Note that the content of <code class="literal">init_connect</code> is not executed for users having the <code class="literal">SUPER</code> privilege; this is in case that content has been wrongly set (contains a wrong query, for example with a syntax error), thus making all connections fail. Not executing it for <code class="literal">SUPER</code> users enables those to open a connection and fix <code class="literal">init_connect</code>. This variable was added in MySQL 4.1.2. </p></li><li><p> <code class="literal">init_file</code> </p><p> The name of the file specified with the <code class="option">--init-file</code> option when you start the server. This is a file containing SQL statements that you want the server to execute when it starts. Each statement must be on a single line and should not include comments. This variable was added in MySQL 3.23.2. </p></li><li><p> <code class="literal">init_slave</code> </p><p> This variable is similar to <code class="literal">init_connect</code>, but is a string to be executed by a slave server each time the SQL thread starts. The format of the string is the same as for the <code class="literal">init_connect</code> variable. This variable was added in MySQL 4.1.2. </p></li><li><p> <code class="literal">innodb_<em class="replaceable"><code>xxx</code></em></code> </p><p> The <code class="literal">InnoDB</code> system variables are listed at <a href="innodb.html#innodb-start" title="15.5. InnoDB Startup Options">Section 15.5, “<code class="literal">InnoDB</code> Startup Options”</a>. </p></li><li><p> <code class="literal">interactive_timeout</code> </p><p> The number of seconds the server waits for activity on an interactive connection before closing it. An interactive client is defined as a client that uses the <code class="literal">CLIENT_INTERACTIVE</code> option to <code class="literal">mysql_real_connect()</code>. See also <code class="literal">wait_timeout</code>. </p></li><li><p> <code class="literal">join_buffer_size</code> </p><p> The size of the buffer that is used for full joins (joins that do not use indexes). Normally the best way to get fast joins is to add indexes. Increase the value of <code class="literal">join_buffer_size</code> to get a faster full join when adding indexes is not possible. One join buffer is allocated for each full join between two tables. For a complex join between several tables for which indexes are not used, multiple join buffers might be necessary. </p></li><li><p> <a class="indexterm" name="id2778117"></a> <code class="literal">key_buffer_size</code> </p><p> Index blocks for <code class="literal">MyISAM</code> and <code class="literal">ISAM</code> tables are buffered and are shared by all threads. <code class="literal">key_buffer_size</code> is the size of the buffer used for index blocks. The key buffer is also known as the key cache. </p><p> The maximum allowable setting for <code class="literal">key_buffer_size</code> is 4GB. The effective maximum size might be less, depending on your available physical RAM and per-process RAM limits imposed by your operating system or hardware platform. </p><p> Increase the value to get better index handling (for all reads and multiple writes) to as much as you can afford. Using a value that is 25% of total memory on a machine that mainly runs MySQL is quite common. However, if you make the value too large (for example, more than 50% of your total memory) your system might start to page and become extremely slow. MySQL relies on the operating system to perform filesystem caching for data reads, so you must leave some room for the filesystem cache. </p><p> For even more speed when writing many rows at the same time, use <code class="literal">LOCK TABLES</code>. See <a href="sql-syntax.html#lock-tables" title="13.4.5. LOCK TABLES and UNLOCK TABLES Syntax">Section 13.4.5, “<code class="literal">LOCK TABLES</code> and <code class="literal">UNLOCK TABLES</code> Syntax”</a>. </p><p> You can check the performance of the key buffer by issuing a <code class="literal">SHOW STATUS</code> statement and examining the <code class="literal">Key_read_requests</code>, <code class="literal">Key_reads</code>, <code class="literal">Key_write_requests</code>, and <code class="literal">Key_writes</code> status variables. See <a href="sql-syntax.html#show" title="13.5.4. SHOW Syntax">Section 13.5.4, “<code class="literal">SHOW</code> Syntax”</a>. </p><p> The <code class="literal">Key_reads/Key_read_requests</code> ratio should normally be less than 0.01. The <code class="literal">Key_writes/Key_write_requests</code> ratio is usually near 1 if you are using mostly updates and deletes, but might be much smaller if you tend to do updates that affect many rows at the same time or if you are using the <code class="literal">DELAY_KEY_WRITE</code> table option. </p><p> The fraction of the key buffer in use can be determined using <code class="literal">key_buffer_size</code> in conjunction with the <code class="literal">Key_blocks_unused</code> status variable and the buffer block size. From MySQL 4.1.1 on, the buffer block size is available from the <code class="literal">key_cache_block_size</code> server variable. The fraction of the buffer in use is: </p><pre class="programlisting">1 - ((Key_blocks_unused * key_cache_block_size) / key_buffer_size) </pre><p> This value is an approximation because some space in the key buffer may be allocated internally for administrative structures. </p><p> Before MySQL 4.1.1, key cache blocks are 1024 bytes, and before MySQL 4.1.2, <code class="literal">Key_blocks_unused</code> is unavailable. The <code class="literal">Key_blocks_used</code> variable can be used as follows to determine the fraction of the key buffer in use: </p><pre class="programlisting">(Key_blocks_used * 1024) / key_buffer_size </pre><p> However, <code class="literal">Key_blocks_used</code> indicates the maximum number of blocks that have ever been in use at once, so this formula does not necessary represent the current fraction of the buffer that is in use. </p><p> As of MySQL 4.1, it is possible to create multiple <code class="literal">MyISAM</code> key caches. The size limit of 4GB applies to each cache individually, not as a group. See <a href="optimization.html#myisam-key-cache" title="7.4.6. The MyISAM Key Cache">Section 7.4.6, “The <code class="literal">MyISAM</code> Key Cache”</a>. </p></li><li><p> <code class="literal">key_cache_age_threshold</code> </p><p> This value controls the demotion of buffers from the hot sub-chain of a key cache to the warm sub-chain. Lower values cause demotion to happen more quickly. The minimum value is 100. The default value is 300. This variable was added in MySQL 4.1.1. See <a href="optimization.html#myisam-key-cache" title="7.4.6. The MyISAM Key Cache">Section 7.4.6, “The <code class="literal">MyISAM</code> Key Cache”</a>. </p></li><li><p> <code class="literal">key_cache_block_size</code> </p><p> The size in bytes of blocks in the key cache. The default value is 1024. This variable was added in MySQL 4.1.1. See <a href="optimization.html#myisam-key-cache" title="7.4.6. The MyISAM Key Cache">Section 7.4.6, “The <code class="literal">MyISAM</code> Key Cache”</a>. </p></li><li><p> <code class="literal">key_cache_division_limit</code> </p><p> The division point between the hot and warm sub-chains of the key cache buffer chain. The value is the percentage of the buffer chain to use for the warm sub-chain. Allowable values range from 1 to 100. The default value is 100. This variable was added in MySQL 4.1.1. See <a href="optimization.html#myisam-key-cache" title="7.4.6. The MyISAM Key Cache">Section 7.4.6, “The <code class="literal">MyISAM</code> Key Cache”</a>. </p></li><li><p> <code class="literal">language</code> </p><p> The language used for error messages. </p></li><li><p> <code class="literal">large_file_support</code> </p><p> Whether <span><strong class="command">mysqld</strong></span> was compiled with options for large file support. This variable was added in MySQL 3.23.28. </p></li><li><p> <code class="literal">large_pages</code> </p><p> Indicates whether large page support is enabled. This variable was added in MySQL 5.0.3. </p></li><li><p> <code class="literal">license</code> </p><p> The type of license the server has. This variable was added in MySQL 4.0.19. </p></li><li><p> <code class="literal">local_infile</code> </p><p> Whether <code class="literal">LOCAL</code> is supported for <code class="literal">LOAD DATA INFILE</code> statements. This variable was added in MySQL 4.0.3. </p></li><li><p> <code class="literal">locked_in_memory</code> </p><p> Whether <span><strong class="command">mysqld</strong></span> was locked in memory with <code class="option">--memlock</code>. This variable was added in MySQL 3.23.25. </p></li><li><p> <code class="literal">log</code> </p><p> Whether logging of all queries to the general query log is enabled. See <a href="database-administration.html#query-log" title="5.10.2. The General Query Log">Section 5.10.2, “The General Query Log”</a>. </p></li><li><p> <code class="literal">log_bin</code> </p><p> Whether the binary log is enabled. This variable was added in MySQL 3.23.14. See <a href="database-administration.html#binary-log" title="5.10.4. The Binary Log">Section 5.10.4, “The Binary Log”</a>. </p></li><li><p> <code class="literal">log_error</code> </p><p> The location of the error log. This variable was added in MySQL 4.0.10. </p></li><li><p> <code class="literal">log_slave_updates</code> </p><p> Whether updates received by a slave server from a master server should be logged to the slave's own binary log. Binary logging must be enabled on the slave for this to have any effect. This variable was added in MySQL 3.23.17. See <a href="replication.html#replication-options" title="6.8. Replication Startup Options">Section 6.8, “Replication Startup Options”</a>. </p></li><li><p> <code class="literal">log_slow_queries</code> </p><p> Whether slow queries should be logged. “<span class="quote">Slow</span>” is determined by the value of the <code class="literal">long_query_time</code> variable. This variable was added in MySQL 4.0.2. See <a href="database-administration.html#slow-query-log" title="5.10.5. The Slow Query Log">Section 5.10.5, “The Slow Query Log”</a>. </p></li><li><p> <code class="literal">log_update</code> </p><p> Whether the update log is enabled. This variable was added in MySQL 3.22.18. Note that the binary log is preferable to the update log, which is unavailable as of MySQL 5.0. See <a href="database-administration.html#update-log" title="5.10.3. The Update Log">Section 5.10.3, “The Update Log”</a>. </p></li><li><p> <code class="literal">log_warnings</code> </p><p> Whether to produce additional warning messages. This variable was added in MySQL 4.0.3. It is enabled by default as of MySQL 4.0.19 and 4.1.2. As of MySQL 4.0.21 and 4.1.3, aborted connections are not logged to the error log unless the value is greater than 1. </p></li><li><p> <code class="literal">long_query_time</code> </p><p> If a query takes longer than this many seconds, the <code class="literal">Slow_queries</code> status variable is incremented. If you are using the <code class="option">--log-slow-queries</code> option, the query is logged to the slow query log file. This value is measured in real time, not CPU time, so a query that is under the threshold on a lightly loaded system might be above the threshold on a heavily loaded one. The minimum value is 1. See <a href="database-administration.html#slow-query-log" title="5.10.5. The Slow Query Log">Section 5.10.5, “The Slow Query Log”</a>. </p></li><li><p> <code class="literal">low_priority_updates</code> </p><p> If set to <code class="literal">1</code>, all <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, <code class="literal">DELETE</code>, and <code class="literal">LOCK TABLE WRITE</code> statements wait until there is no pending <code class="literal">SELECT</code> or <code class="literal">LOCK TABLE READ</code> on the affected table. This variable previously was named <code class="literal">sql_low_priority_updates</code>. It was added in MySQL 3.22.5. </p></li><li><p> <code class="literal">lower_case_file_system</code> </p><p> This variable indicates whether the filesystem where the data directory is located has case insensitive filenames. <code class="literal">ON</code> means filenames are case insensitive, <code class="literal">OFF</code> means they are case sensitive. This variable was added in MySQL 4.0.19. </p></li><li><p> <code class="literal">lower_case_table_names</code> </p><p> If set to <code class="literal">1</code>, table names are stored in lowercase on disk and table name comparisons are not case sensitive. This variable was added in MySQL 3.23.6. If set to <code class="literal">2</code> (new in 4.0.18), table names are stored as given but compared in lowercase. From MySQL 4.0.2, this option also applies to database names. From 4.1.1, it also applies to table aliases. See <a href="language-structure.html#name-case-sensitivity" title="9.2.2. Identifier Case Sensitivity">Section 9.2.2, “Identifier Case Sensitivity”</a>. </p><p> <span class="bold"><strong>Note</strong></span>: If you are using <code class="literal">InnoDB</code> tables, you should set this variable to <code class="literal">1</code> on all platforms to force names to be converted to lowercase. </p><p> You should <span class="emphasis"><em>not</em></span> set this variable to <code class="literal">0</code> if you are running MySQL on a system that does not have case-sensitive filenames (such as Windows or Mac OS X). <span class="emphasis"><em>New in 4.0.18</em></span>: If this variable is not set at startup and the filesystem on which the data directory is located does not have case-sensitive filenames, MySQL automatically sets <code class="literal">lower_case_table_names</code> to <code class="literal">2</code>. </p></li><li><p> <code class="literal">max_allowed_packet</code> </p><p> The maximum size of one packet or any generated/intermediate string. </p><p> The packet message buffer is initialized to <code class="literal">net_buffer_length</code> bytes, but can grow up to <code class="literal">max_allowed_packet</code> bytes when needed. This value by default is small, to catch big (possibly wrong) packets. </p><p> You must increase this value if you are using large <code class="literal">BLOB</code> columns or long strings. It should be as big as the biggest <code class="literal">BLOB</code> you want to use. The protocol limit for <code class="literal">max_allowed_packet</code> is 16MB before MySQL 4.0 and 1GB thereafter. </p></li><li><p> <code class="literal">max_binlog_cache_size</code> </p><p> If a multiple-statement transaction requires more than this amount of memory, you get the error <code class="literal">Multi-statement transaction required more than 'max_binlog_cache_size' bytes of storage</code>. This variable was added in MySQL 3.23.29. </p></li><li><p> <code class="literal">max_binlog_size</code> </p><p> If a write to the binary log exceeds the given value, rotate the binary logs. You cannot set this variable to more than 1GB or to less than 4096 bytes. (The minimum before MYSQL 4.0.14 is 1024 bytes.) The default value is 1GB. This variable was added in MySQL 3.23.33. </p><p> Note if you are using transactions: A transaction is written in one chunk to the binary log, hence it is never split between several binary logs. Therefore, if you have big transactions, you might see binary logs bigger than <code class="literal">max_binlog_size</code>. </p><p> If <code class="literal">max_relay_log_size</code> is 0, the value of <code class="literal">max_binlog_size</code> applies to relay logs as well. <code class="literal">max_relay_log_size</code> was added in MySQL 4.0.14. </p></li><li><p> <code class="literal">max_connect_errors</code> </p><p> If there are more than this number of interrupted connections from a host, that host is blocked from further connections. You can unblock blocked hosts with the <code class="literal">FLUSH HOSTS</code> statement. </p></li><li><p> <code class="literal">max_connections</code> </p><p> The number of simultaneous client connections allowed. Increasing this value increases the number of file descriptors that <span><strong class="command">mysqld</strong></span> requires. See <a href="optimization.html#table-cache" title="7.4.9. How MySQL Opens and Closes Tables">Section 7.4.9, “How MySQL Opens and Closes Tables”</a> for comments on file descriptor limits. Also see <a href="problems.html#too-many-connections" title="A.2.6. Too many connections">Section A.2.6, “<code class="literal">Too many connections</code>”</a>. </p></li><li><p> <code class="literal">max_delayed_threads</code> </p><p> Do not start more than this number of threads to handle <code class="literal">INSERT DELAYED</code> statements. If you try to insert data into a new table after all <code class="literal">INSERT DELAYED</code> threads are in use, the row is inserted as if the <code class="literal">DELAYED</code> attribute wasn't specified. If you set this to <code class="literal">0</code>, MySQL never creates a thread to handle <code class="literal">DELAYED</code> rows; in effect, doing so disables <code class="literal">DELAYED</code> entirely. This variable was added in MySQL 3.23.0. </p></li><li><p> <code class="literal">max_error_count</code> </p><p> The maximum number of error, warning, and note messages to be stored for display by <code class="literal">SHOW ERRORS</code> or <code class="literal">SHOW WARNINGS</code>. This variable was added in MySQL 4.1.0. </p></li><li><p> <code class="literal">max_heap_table_size</code> </p><p> This variable sets the maximum size to which <code class="literal">MEMORY</code> (<code class="literal">HEAP</code>) tables are allowed to grow. The value of the variable is used to calculate <code class="literal">MEMORY</code> table <code class="literal">MAX_ROWS</code> values. Setting this variable has no effect on any existing <code class="literal">MEMORY</code> table, unless the table is re-created with a statement such as <code class="literal">CREATE TABLE</code> or <code class="literal">TRUNCATE TABLE</code>, or altered with <code class="literal">ALTER TABLE</code>. This variable was added in MySQL 3.23.0. </p></li><li><p> <code class="literal">max_insert_delayed_threads</code> </p><p> This variable is a synonym for <code class="literal">max_delayed_threads</code>. It was added in MySQL 4.0.19. </p></li><li><p> <code class="literal">max_join_size</code> </p><p> do not allow <code class="literal">SELECT</code> statements that probably need to examine more than <code class="literal">max_join_size</code> rows (for single-table statements) or row combinations (for multiple-table statements) or that are likely to do more than <code class="literal">max_join_size</code> disk seeks. By setting this value, you can catch <code class="literal">SELECT</code> statements where keys are not used properly and that would probably take a long time. Set it if your users tend to perform joins that lack a <code class="literal">WHERE</code> clause, that take a long time, or that return millions of rows. </p><p> Setting this variable to a value other than <code class="literal">DEFAULT</code> resets the <code class="literal">SQL_BIG_SELECTS</code> value to <code class="literal">0</code>. If you set the <code class="literal">SQL_BIG_SELECTS</code> value again, the <code class="literal">max_join_size</code> variable is ignored. </p><p> If a query result is in the query cache, no result size check is performed, because the result has previously been computed and it does not burden the server to send it to the client. </p><p> This variable previously was named <code class="literal">sql_max_join_size</code>. </p></li><li><p> <code class="literal">max_length_for_sort_data</code> </p><p> The cutoff on the size of index values that determines which <code class="literal">filesort</code> algorithm to use. See <a href="optimization.html#order-by-optimization" title="7.2.9. How MySQL Optimizes ORDER BY">Section 7.2.9, “How MySQL Optimizes <code class="literal">ORDER BY</code>”</a>. This variable was added in MySQL 4.1.1 </p></li><li><p> <code class="literal">max_relay_log_size</code> </p><p> If a write by a replication slave to its relay log exceeds the given value, rotate the relay log. This variable enables you to put different size constraints on relay logs and binary logs. However, setting the variable to 0 makes MySQL use <code class="literal">max_binlog_size</code> for both binary logs and relay logs. You must set <code class="literal">max_relay_log_size</code> to between 4096 bytes and 1GB (inclusive), or to <code class="literal">0</code>. The default value is <code class="literal">0</code>. This variable was added in MySQL 4.0.14. See <a href="replication.html#replication-implementation-details" title="6.3. Replication Implementation Details">Section 6.3, “Replication Implementation Details”</a>. </p></li><li><p> <code class="literal">max_seeks_for_key</code> </p><p> Limit the assumed maximum number of seeks when looking up rows based on a key. The MySQL optimizer assumes that no more than this number of key seeks are required when searching for matching rows in a table by scanning a key, regardless of the actual cardinality of the key (see <a href="sql-syntax.html#show-index" title="13.5.4.11. SHOW INDEX Syntax">Section 13.5.4.11, “<code class="literal">SHOW INDEX</code> Syntax”</a>). By setting this to a low value (say, <code class="literal">100</code>), you can force MySQL to prefer keys instead of table scans. </p><p> This variable was added in MySQL 4.0.14. </p></li><li><p> <code class="literal">max_sort_length</code> </p><p> The number of bytes to use when sorting <code class="literal">BLOB</code> or <code class="literal">TEXT</code> values. Only the first <code class="literal">max_sort_length</code> bytes of each value are used; the rest are ignored. </p></li><li><p> <code class="literal">max_tmp_tables</code> </p><p> The maximum number of temporary tables a client can keep open at the same time. (This option does not yet do anything.) </p></li><li><p> <code class="literal">max_user_connections</code> </p><p> The maximum number of simultaneous connections allowed to any given MySQL account. A value of <code class="literal">0</code> means “<span class="quote">no limit</span>”. This variable was added in MySQL 3.23.34. </p><p> This variable has only a global form. </p></li><li><p> <code class="literal">max_write_lock_count</code> </p><p> After this many write locks, allow some read locks to run in between. This variable was added in MySQL 3.23.7. </p></li><li><p> <code class="literal">myisam_data_pointer_size</code> </p><p> The default pointer size in bytes, to be used by <code class="literal">CREATE TABLE</code> for <code class="literal">MyISAM</code> tables when no <code class="literal">MAX_ROWS</code> option is specified. This variable cannot be less than 2 or larger than 7. The default value is <code class="literal">4</code>. This variable was added in MySQL 4.1.2. See <a href="problems.html#full-table" title="A.2.11. The table is full">Section A.2.11, “<code class="literal">The table is full</code>”</a>. </p></li><li><p> <code class="literal">myisam_max_extra_sort_file_size</code> </p><p> If the temporary file used for fast <code class="literal">MyISAM</code> index creation would be larger than using the key cache by the amount specified here, prefer the key cache method. This is mainly used to force long character keys in large tables to use the slower key cache method to create the index. This variable was added in MySQL 3.23.37. <span class="bold"><strong>Note</strong></span>: The value is given in megabytes before 4.0.3 and in bytes thereafter. </p></li><li><p> <code class="literal">myisam_max_sort_file_size</code> </p><p> The maximum size of the temporary file MySQL is allowed to use while re-creating a <code class="literal">MyISAM</code> index (during <code class="literal">REPAIR TABLE</code>, <code class="literal">ALTER TABLE</code>, or <code class="literal">LOAD DATA INFILE</code>). If the file size would be bigger than this value, the index is created using the key cache instead, which is slower. This variable was added in MySQL 3.23.37. <span class="bold"><strong>Note</strong></span>: The value is given in megabytes before 4.0.3 and in bytes thereafter. </p></li><li><p> <code class="literal">myisam_recover_options</code> </p><p> The value of the <code class="option">--myisam-recover</code> option. This variable was added in MySQL 3.23.36. </p></li><li><p> <code class="literal">myisam_repair_threads</code> </p><p> If this value is greater than 1, <code class="literal">MyISAM</code> table indexes are created in parallel (each index in its own thread) during the <code class="literal">Repair by sorting</code> process. The default value is 1. <span class="bold"><strong>Note</strong></span>: Multi-threaded repair is still <span class="emphasis"><em>alpha</em></span> quality code. This variable was added in MySQL 4.0.13. </p></li><li><p> <code class="literal">myisam_sort_buffer_size</code> </p><p> The buffer that is allocated when sorting <code class="literal">MyISAM</code> indexes during a <code class="literal">REPAIR TABLE</code> or when creating indexes with <code class="literal">CREATE INDEX</code> or <code class="literal">ALTER TABLE</code>. This variable was added in MySQL 3.23.16. </p></li><li><p> <code class="literal">myisam_stats_method</code> </p><p> How the server treats <code class="literal">NULL</code> values when collecting statistics about the distribution of index values for <code class="literal">MyISAM</code> tables. This variable has two possible values, <code class="literal">nulls_equal</code> and <code class="literal">nulls_unequal</code>. For <code class="literal">nulls_equal</code>, all <code class="literal">NULL</code> index values are considered equal and form a single value group that has a size equal to the number of <code class="literal">NULL</code> values. For <code class="literal">nulls_unequal</code>, <code class="literal">NULL</code> values are considered unequal, and each <code class="literal">NULL</code> forms a distinct value group of size 1. </p><p> The method that is used for generating table statistics influences how the optimizer chooses indexes for query execution, as described in <a href="optimization.html#myisam-index-statistics" title="7.4.7. MyISAM Index Statistics Collection">Section 7.4.7, “<code class="literal">MyISAM</code> Index Statistics Collection”</a>. </p><p> This variable was added in MySQL 4.1.15/5.0.14. For older versions, the statistics collection method is equivalent to <code class="literal">nulls_equal</code>. </p></li><li><p> <code class="literal">named_pipe</code> </p><p> On Windows, indicates whether the server supports connections over named pipes. This variable was added in MySQL 3.23.50. </p></li><li><p> <code class="literal">net_buffer_length</code> </p><p> The communication buffer is reset to this size between queries. This should not normally be changed, but if you have very little memory, you can set it to the expected length of SQL statements sent by clients. If statements exceed this length, the buffer is automatically enlarged, up to <code class="literal">max_allowed_packet</code> bytes. </p></li><li><p> <code class="literal">net_read_timeout</code> </p><p> The number of seconds to wait for more data from a connection before aborting the read. When the server is reading from the client, <code class="literal">net_read_timeout</code> is the timeout value controlling when to abort. When the server is writing to the client, <code class="literal">net_write_timeout</code> is the timeout value controlling when to abort. See also <code class="literal">slave_net_timeout</code>. This variable was added in MySQL 3.23.20. </p></li><li><p> <code class="literal">net_retry_count</code> </p><p> If a read on a communication port is interrupted, retry this many times before giving up. This value should be set quite high on FreeBSD because internal interrupts are sent to all threads. This variable was added in MySQL 3.23.7. </p></li><li><p> <code class="literal">net_write_timeout</code> </p><p> The number of seconds to wait for a block to be written to a connection before aborting the write. See also <code class="literal">net_read_timeout</code>. This variable was added in MySQL 3.23.20. </p></li><li><p> <code class="literal">new</code> </p><p> This variable is used in MySQL 4.0 to turn on some 4.1 behaviors. This variable was added in MySQL 4.0.12. </p></li><li><p> <code class="literal">old_passwords</code> </p><p> Whether the server should use pre-4.1-style passwords for MySQL user accounts. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">one_shot</code> </p><p> This is not a variable, but it can be used when setting some variables. It's described in <a href="sql-syntax.html#set-option" title="13.5.3. SET Syntax">Section 13.5.3, “<code class="literal">SET</code> Syntax”</a>. </p></li><li><p> <code class="literal">one_shot</code> </p><p> This is not a variable, but it can be used when setting some variables. It's described in <a href="sql-syntax.html#set-option" title="13.5.3. SET Syntax">Section 13.5.3, “<code class="literal">SET</code> Syntax”</a>. </p></li><li><p> <code class="literal">open_files_limit</code> </p><p> The number of files that the operating system allows <span><strong class="command">mysqld</strong></span> to open. This is the real value allowed by the system and might be different from the value you gave <span><strong class="command">mysqld</strong></span> as a startup option. The value is 0 on systems where MySQL cannot change the number of open files. This variable was added in MySQL 3.23.20. </p></li><li><p> <code class="literal">pid_file</code> </p><p> The pathname of the process ID (PID) file. This variable can be set with the <code class="option">--pid-file</code> option. This variable was added in MySQL 3.23.23. </p></li><li><p> <code class="literal">port</code> </p><p> The port on which the server listens for TCP/IP connections. This variable can be set with the <code class="option">--port</code> option. </p></li><li><p> <code class="literal">preload_buffer_size</code> </p><p> The size of the buffer that is allocated when preloading indexes. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">protocol_version</code> </p><p> The version of the client/server protocol used by the MySQL server. This variable was added in MySQL 3.23.18. </p></li><li><p> <code class="literal">query_alloc_block_size</code> </p><p> The allocation size of memory blocks that are allocated for objects created during query parsing and execution. If you have problems with memory fragmentation, it might help to increase this a bit. This variable was added in MySQL 4.0.16. </p></li><li><p> <code class="literal">query_cache_limit</code> </p><p> Do not cache results that are bigger than this. The default value is 1MB. This variable was added in MySQL 4.0.1. </p></li><li><p> <code class="literal">query_cache_min_res_unit</code> </p><p> The minimum size for blocks allocated by the query cache. The default value is 4KB. Tuning information for this variable is given in <a href="database-administration.html#query-cache-configuration" title="5.12.3. Query Cache Configuration">Section 5.12.3, “Query Cache Configuration”</a>. This variable is present from MySQL 4.1. </p></li><li><p> <code class="literal">query_cache_size</code> </p><p> The amount of memory allocated for caching query results. The default value is <code class="literal">0</code>, which disables the query cache. Note that this amount of memory is allocated even if <code class="literal">query_cache_type</code> is set to <code class="literal">0</code>. This variable was added in MySQL 4.0.1. </p></li><li><p> <code class="literal">query_cache_type</code> </p><p> Set query cache type. Setting the <code class="literal">GLOBAL</code> value sets the type for all clients that connect thereafter. Individual clients can set the <code class="literal">SESSION</code> value to affect their own use of the query cache. </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td><span class="bold"><strong>Option</strong></span></td><td><span class="bold"><strong>Description</strong></span></td></tr><tr><td><code class="literal">0</code> or <code class="literal">OFF</code></td><td>do not cache or retrieve results. Note that this does not deallocate the query cache buffer. To do that, you should set <code class="literal">query_cache_size</code> to <code class="literal">0</code>.</td></tr><tr><td><code class="literal">1</code> or <code class="literal">ON</code></td><td>Cache all query results except for those that begin with <code class="literal">SELECT SQL_NO_CACHE</code>.</td></tr><tr><td><code class="literal">2</code> or <code class="literal">DEMAND</code></td><td>Cache results only for queries that begin with <code class="literal">SELECT SQL_CACHE</code>.</td></tr></tbody></table></div><p> This variable was added in MySQL 4.0.3. </p></li><li><p> <code class="literal">query_cache_wlock_invalidate</code> </p><p> Normally, when one client acquires a <code class="literal">WRITE</code> lock on a <code class="literal">MyISAM</code> table, other clients are not blocked from issuing queries for the table if the query results are present in the query cache. Setting this variable to 1 causes acquisition of a <code class="literal">WRITE</code> lock for a table to invalidate any queries in the query cache that refer to the table. This forces other clients that attempt to access the table to wait while the lock is in effect. This variable was added in MySQL 4.0.19. </p></li><li><p> <code class="literal">query_prealloc_size</code> </p><p> The size of the persistent buffer used for query parsing and execution. This buffer is not freed between queries. If you are running complex queries, a larger <code class="literal">query_prealloc_size</code> value might be helpful in improving performance, because it can reduce the need for the server to perform memory allocation during query execution operations. </p><p> This variable was added in MySQL 4.0.16. </p></li><li><p> <code class="literal">range_alloc_block_size</code> </p><p> The size of blocks that are allocated when doing range optimization. This variable was added in MySQL 4.0.16. </p></li><li><p> <code class="literal">read_buffer_size</code> </p><p> Each thread that does a sequential scan allocates a buffer of this size for each table it scans. If you do many sequential scans, you might want to increase this value. This variable was added in MySQL 4.0.3. Previously, it was named <code class="literal">record_buffer</code>. </p></li><li><p> <code class="literal">read_only</code> </p><p> When the variable is set to <code class="literal">ON</code> for a replication slave server, it causes the slave to allow no updates except from slave threads or from users with the <code class="literal">SUPER</code> privilege. This can be useful to ensure that a slave server accepts no updates from clients. This variable was added in MySQL 4.0.14. </p></li><li><p> <code class="literal">relay_log_purge</code> </p><p> Disables or enables automatic purging of relay logs as soon as they are not needed any more. The default value is <code class="literal">1</code> (enabled). This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">read_rnd_buffer_size</code> </p><p> When reading rows in sorted order after a sort, the rows are read through this buffer to avoid disk seeks. Setting the variable to a large value can improve <code class="literal">ORDER BY</code> performance considerably. However, this is a buffer allocated for each client, so you should not set the global variable to a large value. Instead, change the session variable only from within those clients that need to run large queries. This variable was added in MySQL 4.0.3. Previously, it was named <code class="literal">record_rnd_buffer</code>. </p></li><li><p> <code class="literal">safe_show_database</code> </p><p> Do not show databases for which the user has no database or table privileges. This can improve security if you are concerned about people being able to see what databases other users have. See also <code class="literal">skip_show_database</code>. </p><p> This variable was removed in MySQL 4.0.5. Beginning with this version, you should instead use the <code class="literal">SHOW DATABASES</code> privilege to control access by MySQL accounts to databases. </p></li><li><p> <code class="literal">secure_auth</code> </p><p> If the MySQL server has been started with the <code class="option">--secure-auth</code> option, it blocks connections from all accounts that have passwords stored in the old (pre-4.1) format. In that case, the value of this variable is <code class="literal">ON</code>, otherwise it is <code class="literal">OFF</code>. </p><p> You should enable this option if you want to prevent all usage of passwords in the old format (and hence insecure communication over the network). This variable was added in MySQL 4.1.1. </p><p> Server startup fails with an error if this option is enabled and the privilege tables are in pre-4.1 format. </p><p> When used as a client-side option, the client refuses to connect to a server if the server requires a password in old format for the client account. </p></li><li><p> <code class="literal">server_id</code> </p><p> The value of the <code class="option">--server-id</code> option. It is used for master and slave replication servers. This variable was added in MySQL 3.23.26. </p></li><li><p> <code class="literal">shared_memory</code> </p><p> Whether or not the server allows shared-memory connections. Currently, only Windows servers support this. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">shared_memory_base_name</code> </p><p> Indicates whether or not the server allows shared-memory connections, and sets the identifier for the shared memory. This is useful when running multiple MYSQL instances on a single physical machine. Currently, only Windows servers support this. This variable was added in MySQL 4.1.0. </p></li><li><p> <code class="literal">skip_external_locking</code> </p><p> This is <code class="literal">OFF</code> if <span><strong class="command">mysqld</strong></span> uses external locking. This variable was added in MySQL 4.0.3. Previously, it was named <code class="literal">skip_locking</code>. </p></li><li><p> <code class="literal">skip_networking</code> </p><p> This is <code class="literal">ON</code> if the server allows only local (non-TCP/IP) connections. On Unix, local connections use a Unix socket file. On Windows, local connections use a named pipe or shared memory. On NetWare, only TCP/IP connections are supported, so do not set this variable to <code class="literal">ON</code>. This variable was added in MySQL 3.22.23. </p></li><li><p> <code class="literal">skip_show_database</code> </p><p> This prevents people from using the <code class="literal">SHOW DATABASES</code> statement if they do not have the <code class="literal">SHOW DATABASES</code> privilege. This can improve security if you are concerned about people being able to see what databases other users have. See also <code class="literal">safe_show_database</code>. This variable was added in MySQL 3.23.4. As of MySQL 4.0.2, its effect also depends on the <code class="literal">SHOW DATABASES</code> privilege: If the variable value is <code class="literal">ON</code>, the <code class="literal">SHOW DATABASES</code> statement is allowed only to users who have the <code class="literal">SHOW DATABASES</code> privilege, and the statement displays all database names. If the value is <code class="literal">OFF</code>, <code class="literal">SHOW DATABASES</code> is allowed to all users, but displays each database name only if the user has the <code class="literal">SHOW DATABASES</code> privilege or some privilege for the database. Note that any global privilege is a privilege for the database. </p></li><li><p> <code class="literal">slave_compressed_protocol</code> </p><p> Whether to use compression of the master/slave protocol if both the slave and the master support it. This variable was added in MySQL 4.0.3. </p></li><li><p> <code class="literal">slave_load_tmpdir</code> </p><p> The name of the directory where the slave creates temporary files for replicating <code class="literal">LOAD DATA INFILE</code> statement. This variable was added in MySQL 4.0.0. </p></li><li><p> <code class="literal">slave_net_timeout</code> </p><p> The number of seconds to wait for more data from a master/slave connection before aborting the read. This variable was added in MySQL 3.23.40. </p></li><li><p> <code class="literal">slave_skip_errors</code> </p><p> The replication errors that the slave should skip (ignore). This variable was added in MySQL 3.23.47. </p></li><li><p> <code class="literal">slave_transaction_retries</code> </p><p> If a replication slave SQL thread fails to execute a transaction because of an <code class="literal">InnoDB</code> deadlock or <code class="literal">InnoDB</code>'s <code class="literal">innodb_lock_wait_timeout</code> or <code class="literal">NDB Cluster</code>'s <code class="literal">TransactionDeadlockDetectionTimeout</code> or <code class="literal">TransactionInactiveTimeout</code> was exceeded, it automatically retries <code class="literal">slave_transaction_retries</code> times before stopping with an error. The default in MySQL 4.1 is <code class="literal">0</code>. You must explicitly set the value to greater than 0 to enable the “<span class="quote">retry</span>” behavior, which is probably a good idea. </p></li><li><p> <code class="literal">slow_launch_time</code> </p><p> If creating a thread takes longer than this many seconds, the server increments the <code class="literal">Slow_launch_threads</code> status variable. This variable was added in MySQL 3.23.15. </p></li><li><p> <code class="literal">socket</code> </p><p> On Unix, this is the Unix socket file used for local client connections. On Windows, this is the name of the named pipe used for local client connections. </p></li><li><p> <code class="literal">sort_buffer_size</code> </p><p> Each thread that needs to do a sort allocates a buffer of this size. Increase this value for faster <code class="literal">ORDER BY</code> or <code class="literal">GROUP BY</code> operations. See <a href="problems.html#temporary-files" title="A.4.4. Where MySQL Stores Temporary Files">Section A.4.4, “Where MySQL Stores Temporary Files”</a>. </p></li><li><p> <code class="literal">sql_mode</code> </p><p> The current server SQL mode. This variable was added in MySQL 3.23.41. It can be set dynamically as of MySQL 4.1.1. See <a href="database-administration.html#server-sql-mode" title="5.2.2. The Server SQL Mode">Section 5.2.2, “The Server SQL Mode”</a>. </p></li><li><p> <code class="literal">sql_slave_skip_counter</code> </p><p> The number of events from the master that a slave server should skip. It was added in MySQL 3.23.33. </p></li><li><p> <code class="literal">storage_engine</code> </p><p> This variable is a synonym for <code class="literal">table_type</code>. It was added in MySQL 4.1.2. </p></li><li><p> <code class="literal">sync_binlog</code> </p><p> If positive, the MySQL server synchronizes its binary log to disk (<code class="literal">fdatasync()</code>) after every <code class="literal">sync_binlog</code>'th write to this binary log. Note that there is one write to the binary log per statement if in autocommit mode, and otherwise one write per transaction. The default value is 0 which does no sync'ing to disk. A value of 1 is the safest choice, because in case of crash you lose at most one statement/transaction from the binary log; but it is also the slowest choice (unless the disk has a battery-backed cache, which makes sync'ing very fast). This variable was added in MySQL 4.1.3. </p></li><li><p> <code class="literal">sync_frm</code> </p><p> This was added as a command-line option in MySQL 4.0.18, and is also a settable global variable since MySQL 4.1.3. If set to <code class="literal">1</code>, when a non-temporary table is created it synchronizes its <code class="filename">.frm</code> file to disk (<code class="literal">fdatasync()</code>); this is slower but safer in case of a crash. The default is <code class="literal">1</code>. </p></li><li><p> <code class="literal">system_time_zone</code> </p><p> The server system time zone. When the server begins executing, it inherits a time zone setting from the machine defaults, possibly modified by the environment of the account used for running the server or the startup script. The value is used to set <code class="literal">system_time_zone</code>. Typically the time zone is specified by the <code class="literal">TZ</code> environment variable. It also can be specified using the <code class="option">--timezone</code> option of the <span><strong class="command">mysqld_safe</strong></span> script. This variable was added in MySQL 4.1.3. </p></li><li><p> <code class="literal">table_cache</code> </p><p> The number of open tables for all threads. Increasing this value increases the number of file descriptors that <span><strong class="command">mysqld</strong></span> requires. You can check whether you need to increase the table cache by checking the <code class="literal">Opened_tables</code> status variable. See <a href="database-administration.html#server-status-variables" title="5.2.4. Server Status Variables">Section 5.2.4, “Server Status Variables”</a>. If the value of <code class="literal">Opened_tables</code> is large and you do not do <code class="literal">FLUSH TABLES</code> often (which just forces all tables to be closed and reopened), then you should increase the value of the <code class="literal">table_cache</code> variable. </p><p> For more information about the table cache, see <a href="optimization.html#table-cache" title="7.4.9. How MySQL Opens and Closes Tables">Section 7.4.9, “How MySQL Opens and Closes Tables”</a>. </p></li><li><p> <code class="literal">table_type</code> </p><p> The default table type (storage engine). To set the table type at server startup, use the <code class="option">--default-table-type</code> option. This variable was added in MySQL 3.23.0. See <a href="database-administration.html#server-options" title="5.2.1. mysqld Command-Line Options">Section 5.2.1, “<span><strong class="command">mysqld</strong></span> Command-Line Options”</a>. </p></li><li><p> <code class="literal">thread_cache_size</code> </p><p> How many threads the server should cache for reuse. When a client disconnects, the client's threads are put in the cache if there are fewer than <code class="literal">thread_cache_size</code> threads there. Requests for threads are satisfied by reusing threads taken from the cache if possible, and only when the cache is empty is a new thread created. This variable can be increased to improve performance if you have a lot of new connections. (Normally this does not give a notable performance improvement if you have a good thread implementation.) By examining the difference between the <code class="literal">Connections</code> and <code class="literal">Threads_created</code> status variables (see <a href="database-administration.html#server-status-variables" title="5.2.4. Server Status Variables">Section 5.2.4, “Server Status Variables”</a> for details) you can see how efficient the thread cache is. This variable was added in MySQL 3.23.16. </p></li><li><p> <code class="literal">thread_concurrency</code> </p><p> On Solaris, <span><strong class="command">mysqld</strong></span> calls <code class="literal">thr_setconcurrency()</code> with this value. This function allows applications to give the threads system a hint about the desired number of threads that should be run at the same time. This variable was added in MySQL 3.23.7. </p></li><li><p> <code class="literal">thread_stack</code> </p><p> The stack size for each thread. Many of the limits detected by the <code class="literal">crash-me</code> test are dependent on this value. The default is large enough for normal operation. See <a href="optimization.html#mysql-benchmarks" title="7.1.4. The MySQL Benchmark Suite">Section 7.1.4, “The MySQL Benchmark Suite”</a>. </p></li><li><p> <code class="literal">time_format</code> </p><p> This variable is not implemented. </p></li><li><p> <code class="literal">time_zone</code> </p><p> The current time zone. The initial value of this is <code class="literal">'SYSTEM'</code> (use the value of <code class="literal">system_time_zone</code>), but can be specified explicitly at server startup time with the <code class="option">--default-time-zone</code> option. This variable was added in MySQL 4.1.3. </p></li><li><p> <code class="literal">timezone</code> </p><p> The time zone for the server. This is set from the <code class="literal">TZ</code> environment variable when <span><strong class="command">mysqld</strong></span> is started. The time zone also can be set by giving a <code class="option">--timezone</code> argument to <span><strong class="command">mysqld_safe</strong></span>. This variable was added in MySQL 3.23.15. As of MySQL 4.1.3, it is obsolete and has been replaced by the <code class="literal">system_time_zone</code> variable. See <a href="problems.html#timezone-problems" title="A.4.6. Time Zone Problems">Section A.4.6, “Time Zone Problems”</a>. </p></li><li><p> <code class="literal">tmp_table_size</code> </p><p> If an in-memory temporary table exceeds this size, MySQL automatically converts it to an on-disk <code class="literal">MyISAM</code> table. Increase the value of <code class="literal">tmp_table_size</code> if you do many advanced <code class="literal">GROUP BY</code> queries and you have lots of memory. </p></li><li><p> <code class="literal">tmpdir</code> </p><p> The directory used for temporary files and temporary tables. Starting from MySQL 4.1, this variable can be set to a list of several paths that are used in round-robin fashion. Paths should be separated by colon characters (‘<code class="literal">:</code>’) on Unix and semicolon characters (‘<code class="literal">;</code>’) on Windows, NetWare, and OS/2. </p><p> This feature can be used to spread the load between several physical disks. If the MySQL server is acting as a replication slave, you should not set <code class="literal">tmpdir</code> to point to a directory on a memory-based filesystem or to a directory that is cleared when the server host restarts. A replication slave needs some of its temporary files to survive a machine restart so that it can replicate temporary tables or <code class="literal">LOAD DATA INFILE</code> operations. If files in the temporary file directory are lost when the server restarts, replication fails. However, if you're using MySQL 4.0.0 or later, you may set the slave's temporary directory using the <code class="literal">slave_load_tmpdir</code> variable. In that case, the slave won't use the general <code class="literal">tmpdir</code> any more, which means you can set <code class="literal">tmpdir</code> to a non-permanent location then. </p><p> This variable was added in MySQL 3.22.4. </p></li><li><p> <code class="literal">transaction_alloc_block_size</code> </p><p> The allocation size of memory blocks that are allocated for storing queries that are part of a transaction to be stored in the binary log when doing a commit. This variable was added in MySQL 4.0.16. </p></li><li><p> <code class="literal">transaction_prealloc_size</code> </p><p> The size of the persistent buffer for <code class="literal">transaction_alloc_blocks</code> that is not freed between queries. By making this big enough to fit all queries in a common transaction, you can avoid a lot of <code class="literal">malloc()</code> calls. This variable was added in MySQL 4.0.16. </p></li><li><p> <code class="literal">tx_isolation</code> </p><p> The default transaction isolation level. This variable was added in MySQL 4.0.3. </p></li><li><p> <code class="literal">version</code> </p><p> The version number for the server. </p></li><li><p> <code class="literal">version_bdb</code> </p><p> The <code class="literal">BDB</code> storage engine version. This variable was added in MySQL 3.23.31 with the name <code class="literal">bdb_version</code> and renamed to <code class="literal">version_bdb</code> in MySQL 4.1.1. </p></li><li><p> <code class="literal">version_comment</code> </p><p> The <span><strong class="command">configure</strong></span> script has a <code class="option">--with-comment</code> option that allows a comment to be specified when building MySQL. This variable contains the value of that comment. This variable was added in MySQL 4.0.17. </p></li><li><p> <code class="literal">version_compile_machine</code> </p><p> The type of machine MySQL was built on. This variable was added in MySQL 4.1.1. </p></li><li><p> <code class="literal">version_compile_os</code> </p><p> The type of operating system MySQL was built on. This variable was added in MySQL 4.0.19. </p></li><li><p> <code class="literal">wait_timeout</code> </p><p> The number of seconds the server waits for activity on a non-interactive connection before closing it. </p><p> On thread startup, the session <code class="literal">wait_timeout</code> value is initialized from the global <code class="literal">wait_timeout</code> value or from the global <code class="literal">interactive_timeout</code> value, depending on the type of client (as defined by the <code class="literal">CLIENT_INTERACTIVE</code> connect option to <code class="literal">mysql_real_connect()</code>). See also <code class="literal">interactive_timeout</code>. </p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="dynamic-system-variables"></a>5.2.3.1. Dynamic System Variables</h4></div></div></div><p> Beginning with MySQL 4.0.3, many server system variables are dynamic and can be set at runtime using <code class="literal">SET GLOBAL</code> or <code class="literal">SET SESSION</code>. You can also select their values using <code class="literal">SELECT</code>. See <a href="language-structure.html#system-variables" title="9.4. System Variables">Section 9.4, “System Variables”</a>. </p><p> The following table shows the full list of all dynamic system variables. The last column indicates for each variable whether <code class="literal">GLOBAL</code> or <code class="literal">SESSION</code> (or both) apply. </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><tbody><tr><td><span class="bold"><strong>Variable Name</strong></span></td><td><span class="bold"><strong>Value Type</strong></span></td><td><span class="bold"><strong>Type</strong></span></td></tr><tr><td><code class="literal">autocommit</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">big_tables</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">binlog_cache_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">bulk_insert_buffer_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">character_set_client</code></td><td>string</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">character_set_connection</code></td><td>string</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code> </td></tr><tr><td><code class="literal">character_set_results</code></td><td>string</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">character_set_server</code></td><td>string</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">collation_connection</code></td><td>string</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code> </td></tr><tr><td><code class="literal">collation_server</code></td><td>string</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">concurrent_insert</code></td><td>boolean</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">connect_timeout</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">convert_character_set</code></td><td>string</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">default_week_format</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">delay_key_write</code></td><td><code class="literal">OFF</code> | <code class="literal">ON</code> | <code class="literal">ALL</code></td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">delayed_insert_limit</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">delayed_insert_timeout</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">delayed_queue_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">error_count</code></td><td>numeric</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">expire_logs_days</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">flush</code></td><td>boolean</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">flush_time</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">foreign_key_checks</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">ft_boolean_syntax</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">group_concat_max_len</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">identity</code></td><td>numeric</td><td><code class="literal">SESSION</code> </td></tr><tr><td><code class="literal">innodb_autoextend_increment</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">innodb_concurrency_tickets</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">innodb_max_dirty_pages_pct</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">innodb_max_purge_lag</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">innodb_sync_spin_loops</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">innodb_table_locks</code></td><td>boolean</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">innodb_thread_concurrency</code></td><td>numeric <code class="literal">GLOBAL</code></td><td class="auto-generated"> </td></tr><tr><td><code class="literal">innodb_thread_sleep_delay</code></td><td>numeric <code class="literal">GLOBAL</code></td><td class="auto-generated"> </td></tr><tr><td><code class="literal">insert_id</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">interactive_timeout</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">join_buffer_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">key_buffer_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td> <code class="literal">last_insert_id</code></td><td>numeric</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">local_infile</code></td><td>boolean</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">log_warnings</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">long_query_time</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">low_priority_updates</code></td><td>boolean</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">max_allowed_packet</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">max_binlog_cache_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">max_binlog_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">max_connect_errors</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">max_connections</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">max_delayed_threads</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">max_error_count</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">max_heap_table_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">max_insert_delayed_threads</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">max_join_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">max_relay_log_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">max_seeks_for_key</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">max_sort_length</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">max_tmp_tables</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">max_user_connections</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">max_write_lock_count</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">myisam_stats_method</code></td><td>enum</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">multi_read_range</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">myisam_data_pointer_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">myisam_max_sort_file_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">myisam_repair_threads</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">myisam_sort_buffer_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">net_buffer_length</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">net_read_timeout</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">net_retry_count</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">net_write_timeout</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">old_passwords</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">optimizer_prune_level</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">optimizer_search_depth</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">preload_buffer_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">query_alloc_block_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">query_cache_limit</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">query_cache_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">query_cache_type</code></td><td>enumeration</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">query_cache_wlock_invalidate</code></td><td>boolean</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">query_prealloc_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">range_alloc_block_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">read_buffer_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">read_only</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">read_rnd_buffer_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">rpl_recovery_rank</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">safe_show_database</code></td><td>boolean</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">secure_auth</code></td><td>boolean</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">server_id</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">slave_compressed_protocol</code></td><td>boolean</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">slave_net_timeout</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">slave_transaction_retries</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">slow_launch_time</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">sort_buffer_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_auto_is_null</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_big_selects</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_big_tables</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_buffer_result</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_log_bin</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_log_off</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_log_update</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_low_priority_updates</code></td><td>boolean</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_max_join_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_mode</code></td><td>enumeration</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_notes</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_quote_show_create</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_safe_updates</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_select_limit</code></td><td>numeric</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_slave_skip_counter</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">updatable_views_with_limit</code></td><td>enumeration</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sql_warnings</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">sync_binlog</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">sync_frm</code></td><td>boolean</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">storage_engine</code></td><td>enumeration</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">table_cache</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">table_type</code></td><td>enumeration</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">thread_cache_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code></td></tr><tr><td><code class="literal">time_zone</code></td><td>string</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">timestamp</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">tmp_table_size</code></td><td>enumeration</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">transaction_alloc_block_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">transaction_prealloc_size</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">tx_isolation</code></td><td>enumeration</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">unique_checks</code></td><td>boolean</td><td><code class="literal">SESSION</code></td></tr><tr><td><code class="literal">wait_timeout</code></td><td>numeric</td><td><code class="literal">GLOBAL</code> | <code class="literal">SESSION</code></td></tr><tr><td><code class="literal">warning_count</code></td><td>numeric</td><td><code class="literal">SESSION</code></td></tr></tbody></table></div><p> Variables that are marked as “<span class="quote">string</span>” take a string value. Variables that are marked as “<span class="quote">numeric</span>” take a numeric value. Variables that are marked as “<span class="quote">boolean</span>” can be set to <code class="literal">0</code>, <code class="literal">1</code>, <code class="literal">ON</code> or <code class="literal">OFF</code>. Variables that are marked as “<span class="quote">enumeration</span>” normally should be set to one of the available values for the variable, but can also be set to the number that corresponds to the desired enumeration value. For enumeration-valued system variables, the first enumeration value corresponds to 0. This differs from <code class="literal">ENUM</code> columns, for which the first enumeration value corresponds to 1. </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="server-status-variables"></a>5.2.4. Server Status Variables</h3></div></div></div><a class="indexterm" name="id2783916"></a><a class="indexterm" name="id2783923"></a><p> The server maintains many status variables that provide information about its operations. You can view these variables and their values by using the <code class="literal">SHOW STATUS</code> statement: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SHOW STATUS;</code></strong> +--------------------------+------------+ | Variable_name | Value | +--------------------------+------------+ | Aborted_clients | 0 | | Aborted_connects | 0 | | Bytes_received | 155372598 | | Bytes_sent | 1176560426 | | Connections | 30023 | … </pre><p> Many status variables are reset to 0 by the <code class="literal">FLUSH STATUS</code> statement. </p><p> The status variables have the following meanings. The <code class="literal">Com_<em class="replaceable"><code>xxx</code></em></code> statement counter variables were added beginning with MySQL 3.23.47. The <code class="literal">Qcache_<em class="replaceable"><code>xxx</code></em></code> query cache variables were added beginning with MySQL 4.0.1. Otherwise, variables with no version indicated have been present since at least MySQL 3.22. </p><div class="itemizedlist"><ul type="disc"><li><p> <code class="literal">Aborted_clients</code> </p><p> The number of connections that were aborted because the client died without closing the connection properly. See <a href="problems.html#communication-errors" title="A.2.10. Communication Errors and Aborted Connections">Section A.2.10, “Communication Errors and Aborted Connections”</a>. </p></li><li><p> <code class="literal">Aborted_connects</code> </p><p> The number of tries to connect to the MySQL server that failed. See <a href="problems.html#communication-errors" title="A.2.10. Communication Errors and Aborted Connections">Section A.2.10, “Communication Errors and Aborted Connections”</a>. </p></li><li><p> <code class="literal">Binlog_cache_disk_use</code> </p><p> The number of transactions that used the temporary binary log cache but that exceeded the value of <code class="literal">binlog_cache_size</code> and used a temporary file to store statements from the transaction. This variable was added in MySQL 4.1.2. </p></li><li><p> <code class="literal">Binlog_cache_use</code> </p><p> The number of transactions that used the temporary binary log cache. This variable was added in MySQL 4.1.2. </p></li><li><p> <code class="literal">Bytes_received</code> </p><p> The number of bytes received from all clients. This variable was added in MySQL 3.23.7. </p></li><li><p> <code class="literal">Bytes_sent</code> </p><p> The number of bytes sent to all clients. This variable was added in MySQL 3.23.7. </p></li><li><p> <code class="literal">Com_<em class="replaceable"><code>xxx</code></em></code> </p><p> The <code class="literal">Com_<em class="replaceable"><code>xxx</code></em></code> statement counter variables were added beginning with MySQL 3.23.47. They indicate the number of times each <em class="replaceable"><code>xxx</code></em> statement has been executed. There is one status variable for each type of statement. For example, <code class="literal">Com_delete</code> and <code class="literal">Com_insert</code> count <code class="literal">DELETE</code> and <code class="literal">INSERT</code> statements. </p><p> New <code class="literal">Com_stmt_<em class="replaceable"><code>xxx</code></em></code> status variables have been added in MySQL 4.1.13. </p><div class="itemizedlist"><ul type="circle"><li><p> <code class="literal">Com_stmt_prepare</code> </p></li><li><p> <code class="literal">Com_stmt_execute</code> </p></li><li><p> <code class="literal">Com_stmt_send_long_data</code> </p></li><li><p> <code class="literal">Com_stmt_reset</code> </p></li><li><p> <code class="literal">Com_stmt_close</code> </p></li></ul></div><p> Those variables stand for prepared statements commands. Their names refer to the <code class="literal">COM_<em class="replaceable"><code>xxx</code></em></code> command set used in the network layer; in other words: Their values are being increased whenever prepared statements API calls such as <span><strong class="command">mysql_stmt_prepare()</strong></span>, <span><strong class="command">mysql_stmt_execute()</strong></span>, and so forth are executed. However, <code class="literal">Com_stmt_prepare</code>, <code class="literal">Com_stmt_execute</code> and <code class="literal">Com_stmt_close</code> are also increased when one issues the following SQL statements: <code class="literal">PREPARE</code>, <code class="literal">EXECUTE</code>, or <code class="literal">DEALLOCATE PREPARE</code> respectively. Additionally, the values of the older (available since MySQL 4.1.3) statement counter variables <code class="literal">Com_prepare_sql</code>, <code class="literal">Com_execute_sql</code>, and <code class="literal">Com_dealloc_sql</code> are increased for the <code class="literal">PREPARE</code>, <code class="literal">EXECUTE</code>, and <code class="literal">DEALLOCATE PREPARE</code> statements. </p><p> All of the <code class="literal">Com_stmt_<em class="replaceable"><code>xxx</code></em></code> variables are increased even if their argument (a prepared statement) is unknown or an error occurred during execution; in other words: Their values correspond to the number of requests issued, not to the number of requests successfully completed. </p></li><li><p> <code class="literal">Connections</code> </p><p> The number of connection attempts (successful or not) to the MySQL server. </p></li><li><p> <code class="literal">Created_tmp_disk_tables</code> </p><p> The number of temporary tables on disk created automatically by the server while executing statements. This variable was added in MySQL 3.23.24. </p></li><li><p> <code class="literal">Created_tmp_files</code> </p><p> How many temporary files <span><strong class="command">mysqld</strong></span> has created. This variable was added in MySQL 3.23.28. </p></li><li><p> <code class="literal">Created_tmp_tables</code> </p><p> The number of in-memory temporary tables created automatically by the server while executing statements. If <code class="literal">Created_tmp_disk_tables</code> is big, you may want to increase the <code class="literal">tmp_table_size</code> value to cause temporary tables to be memory-based instead of disk-based. </p></li><li><p> <code class="literal">Delayed_errors</code> </p><p> The number of rows written with <code class="literal">INSERT DELAYED</code> for which some error occurred (probably <code class="literal">duplicate key</code>). </p></li><li><p> <code class="literal">Delayed_insert_threads</code> </p><p> The number of <code class="literal">INSERT DELAYED</code> handler threads in use. </p></li><li><p> <code class="literal">Delayed_writes</code> </p><p> The number of <code class="literal">INSERT DELAYED</code> rows written. </p></li><li><p> <code class="literal">Flush_commands</code> </p><p> The number of executed <code class="literal">FLUSH</code> statements. </p></li><li><p> <code class="literal">Handler_commit</code> </p><p> The number of internal <code class="literal">COMMIT</code> statements. This variable was added in MySQL 4.0.2. </p></li><li><p> <code class="literal">Handler_discover</code> </p><p> The MySQL server can ask the <code class="literal">NDB Cluster</code> storage engine if it knows about a table with a given name. This is called discovery. <code class="literal">Handler_discover</code> indicates the number of times that tables have been discovered. This variable was added in MySQL 4.1.2. </p></li><li><p> <code class="literal">Handler_delete</code> </p><p> The number of times a row was deleted from a table. </p></li><li><p> <code class="literal">Handler_read_first</code> </p><p> The number of times the first entry was read from an index. If this is high, it suggests that the server is doing a lot of full index scans; for example, <code class="literal">SELECT col1 FROM foo</code>, assuming that <code class="literal">col1</code> is indexed. </p></li><li><p> <code class="literal">Handler_read_key</code> </p><p> The number of requests to read a row based on a key. If this is high, it is a good indication that your queries and tables are properly indexed. </p></li><li><p> <code class="literal">Handler_read_next</code> </p><p> The number of requests to read the next row in key order. This is incremented if you are querying an index column with a range constraint or if you are doing an index scan. </p></li><li><p> <code class="literal">Handler_read_prev</code> </p><p> The number of requests to read the previous row in key order. This read method is mainly used to optimize <code class="literal">ORDER BY ... DESC</code>. This variable was added in MySQL 3.23.6. </p></li><li><p> <code class="literal">Handler_read_rnd</code> </p><p> The number of requests to read a row based on a fixed position. This is high if you are doing a lot of queries that require sorting of the result. You probably have a lot of queries that require MySQL to scan whole tables or you have joins that do not use keys properly. </p></li><li><p> <code class="literal">Handler_read_rnd_next</code> </p><p> The number of requests to read the next row in the data file. This is high if you are doing a lot of table scans. Generally this suggests that your tables are not properly indexed or that your queries are not written to take advantage of the indexes you have. </p></li><li><p> <code class="literal">Handler_rollback</code> </p><p> The number of internal <code class="literal">ROLLBACK</code> statements. This variable was added in MySQL 4.0.2. </p></li><li><p> <code class="literal">Handler_update</code> </p><p> The number of requests to update a row in a table. </p></li><li><p> <code class="literal">Handler_write</code> </p><p> The number of requests to insert a row in a table. </p></li><li><p> <code class="literal">Key_blocks_not_flushed</code> </p><p> The number of key blocks in the key cache that have changed but haven't yet been flushed to disk. This variable was added in MySQL 4.1.1. It used to be known as <code class="literal">Not_flushed_key_blocks</code>. </p></li><li><p> <code class="literal">Key_blocks_unused</code> </p><p> The number of unused blocks in the key cache. You can use this value to determine how much of the key cache is in use; see the discussion of <code class="literal">key_buffer_size</code> in <a href="database-administration.html#server-system-variables" title="5.2.3. Server System Variables">Section 5.2.3, “Server System Variables”</a>. This variable was added in MySQL 4.1.2. <a href="database-administration.html#server-system-variables" title="5.2.3. Server System Variables">Section 5.2.3, “Server System Variables”</a>. </p></li><li><p> <code class="literal">Key_blocks_used</code> </p><p> The number of used blocks in the key cache. This value is a high-water mark that indicates the maximum number of blocks that have ever been in use at one time. </p></li><li><p> <code class="literal">Key_read_requests</code> </p><p> The number of requests to read a key block from the cache. </p></li><li><p> <code class="literal">Key_reads</code> </p><p> The number of physical reads of a key block from disk. If <code class="literal">Key_reads</code> is big, then your <code class="literal">key_buffer_size</code> value is probably too small. The cache miss rate can be calculated as <code class="literal">Key_reads</code>/<code class="literal">Key_read_requests</code>. </p></li><li><p> <code class="literal">Key_write_requests</code> </p><p> The number of requests to write a key block to the cache. </p></li><li><p> <code class="literal">Key_writes</code> </p><p> The number of physical writes of a key block to disk. </p></li><li><p> <code class="literal">Max_used_connections</code> </p><p> The maximum number of connections that have been in use simultaneously since the server started. </p></li><li><p> <code class="literal">Not_flushed_delayed_rows</code> </p><p> The number of rows waiting to be written in <code class="literal">INSERT DELAY</code> queues. </p></li><li><p> <code class="literal">Not_flushed_key_blocks</code> </p><p> The old name for <code class="literal">Key_blocks_not_flushed</code> before MySQL 4.1.1. </p></li><li><p> <code class="literal">Open_files</code> </p><p> The number of files that are open. </p></li><li><p> <code class="literal">Open_streams</code> </p><p> The number of streams that are open (used mainly for logging). </p></li><li><p> <code class="literal">Open_tables</code> </p><p> The number of tables that are open. </p></li><li><p> <code class="literal">Opened_tables</code> </p><p> The number of tables that have been opened. If <code class="literal">Opened_tables</code> is big, your <code class="literal">table_cache</code> value is probably too small. </p></li><li><p> <code class="literal">Qcache_free_blocks</code> </p><p> The number of free memory blocks in query cache. </p></li><li><p> <code class="literal">Qcache_free_memory</code> </p><p> The amount of free memory for query cache. </p></li><li><p> <code class="literal">Qcache_hits</code> </p><p> The number of cache hits. </p></li><li><p> <code class="literal">Qcache_inserts</code> </p><p> The number of queries added to the cache. </p></li><li><p> <code class="literal">Qcache_lowmem_prunes</code> </p><p> The number of queries that were deleted from the cache because of low memory. </p></li><li><p> <code class="literal">Qcache_not_cached</code> </p><p> The number of non-cached queries (not cachable, or not cached due to the <code class="literal">query_cache_type</code> setting). </p></li><li><p> <code class="literal">Qcache_queries_in_cache</code> </p><p> The number of queries registered in the cache. </p></li><li><p> <code class="literal">Qcache_total_blocks</code> </p><p> The total number of blocks in the query cache. </p></li><li><p> <code class="literal">Questions</code> </p><p> The number of queries that have been sent to the server. </p></li><li><p> <code class="literal">Rpl_status</code> </p><p> The status of failsafe replication (not yet implemented). </p></li><li><p> <code class="literal">Select_full_join</code> </p><p> The number of joins that do not use indexes. If this value is not 0, you should carefully check the indexes of your tables. This variable was added in MySQL 3.23.25. </p></li><li><p> <code class="literal">Select_full_range_join</code> </p><p> The number of joins that used a range search on a reference table. This variable was added in MySQL 3.23.25. </p></li><li><p> <code class="literal">Select_range</code> </p><p> The number of joins that used ranges on the first table. (it is normally not critical even if this is big.) This variable was added in MySQL 3.23.25. </p></li><li><p> <code class="literal">Select_range_check</code> </p><p> The number of joins without keys that check for key usage after each row. (If this is not equal to <code class="literal">0</code>, you should very carefully check the indexes of your tables.) This variable was added in MySQL 3.23.25. </p></li><li><p> <code class="literal">Select_scan</code> </p><p> The number of joins that did a full scan of the first table. This variable was added in MySQL 3.23.25. </p></li><li><p> <code class="literal">Slave_open_temp_tables</code> </p><p> The number of temporary tables currently open by the slave SQL thread. This variable was added in MySQL 3.23.29. </p></li><li><p> <code class="literal">Slave_running</code> </p><p> This is <code class="literal">ON</code> if this server is a slave that is connected to a master. This variable was added in MySQL 3.23.16. </p></li><li><p> <code class="literal">Slave_retried_transactions</code> </p><p> Total (since startup) number of times the replication slave SQL thread has retried transactions. This variable was added in MySQL 4.1.11. </p></li><li><p> <code class="literal">Slow_launch_threads</code> </p><p> The number of threads that have taken more than <code class="literal">slow_launch_time</code> seconds to create. This variable was added in MySQL 3.23.15. </p></li><li><p> <code class="literal">Slow_queries</code> </p><p> The number of queries that have taken more than <code class="literal">long_query_time</code> seconds. See <a href="database-administration.html#slow-query-log" title="5.10.5. The Slow Query Log">Section 5.10.5, “The Slow Query Log”</a>. </p></li><li><p> <code class="literal">Sort_merge_passes</code> </p><p> The number of merge passes the sort algorithm has had to do. If this value is large, you should consider increasing the value of the <code class="literal">sort_buffer_size</code> system variable. This variable was added in MySQL 3.23.28. </p></li><li><p> <code class="literal">Sort_range</code> </p><p> The number of sorts that were done with ranges. This variable was added in MySQL 3.23.25. </p></li><li><p> <code class="literal">Sort_rows</code> </p><p> The number of sorted rows. This variable was added in MySQL 3.23.25. </p></li><li><p> <code class="literal">Sort_scan</code> </p><p> The number of sorts that were done by scanning the table. This variable was added in MySQL 3.23.25. </p></li><li><p> <code class="literal">Ssl_<em class="replaceable"><code>xxx</code></em></code> </p><p> Variables used for SSL connections. These variables were added in MySQL 4.0.0. </p></li><li><p> <code class="literal">Table_locks_immediate</code> </p><p> The number of times that a table lock was acquired immediately. This variable was added in MySQL 3.23.33. </p></li><li><p> <code class="literal">Table_locks_waited</code> </p><p> The number of times that a table lock could not be acquired immediately and a wait was needed. If this is high, and you have performance problems, you should first optimize your queries, and then either split your table or tables or use replication. This variable was added in MySQL 3.23.33. </p></li><li><p> <code class="literal">Threads_cached</code> </p><p> The number of threads in the thread cache. This variable was added in MySQL 3.23.17. </p></li><li><p> <code class="literal">Threads_connected</code> </p><p> The number of currently open connections. </p></li><li><p> <code class="literal">Threads_created</code> </p><p> The number of threads created to handle connections. If <code class="literal">Threads_created</code> is big, you may want to increase the <code class="literal">thread_cache_size</code> value. The cache hit rate can be calculated as <code class="literal">Threads_created</code> divided by <code class="literal">Connections</code>. This variable was added in MySQL 3.23.31. </p></li><li><p> <code class="literal">Threads_running</code> </p><p> The number of threads that are not sleeping. </p></li><li><p> <code class="literal">Uptime</code> </p><p> The number of seconds the server has been up. </p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mysql-fix-privilege-tables"></a>5.3. mysql_fix_privilege_tables — Upgrade MySQL System Tables</h2></div></div></div><p> Some releases of MySQL introduce changes to the structure of the system tables in the <code class="literal">mysql</code> database to add new privileges or features. When you update to a new version of MySQL, you should update your system tables as well to make sure that their structure is up to date. First make a backup of your <code class="literal">mysql</code> database, and then use the following procedure. </p><p> On Unix or Unix-like systems, update the system tables by running the <span><strong class="command">mysql_fix_privilege_tables</strong></span> script: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql_fix_privilege_tables</code></strong> </pre><p> You must run this script while the server is running. It attempts to connect to the server running on the local host as <code class="literal">root</code>. If your <code class="literal">root</code> account requires a password, indicate the password on the command line. For MySQL 4.1 and up, specify the password like this: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql_fix_privilege_tables --password=<em class="replaceable"><code>root_password</code></em></code></strong> </pre><p> Prior to MySQL 4.1, specify the password like this: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql_fix_privilege_tables <em class="replaceable"><code>root_password</code></em></code></strong> </pre><p> The <span><strong class="command">mysql_fix_privilege_tables</strong></span> script performs any actions necessary to convert your system tables to the current format. You might see some <code class="literal">Duplicate column name</code> warnings as it runs; you can ignore them. </p><p> After running the script, stop the server and restart it. </p><p> On Windows systems, there isn't an easy way to update the system tables until MySQL 4.0.15. From version 4.0.15 on, MySQL distributions include a <code class="filename">mysql_fix_privilege_tables.sql</code> SQL script that you can run using the <span><strong class="command">mysql</strong></span> client. For example, if your MySQL installation is located at <code class="filename">C:\Program Files\MySQL\MySQL Server 4.1</code>, the commands look like this: </p><pre class="programlisting">C:\> <strong class="userinput"><code>C:\Program Files\MySQL\MySQL Server 4.1\bin\mysql -u root -p mysql</code></strong> mysql> <strong class="userinput"><code>SOURCE C:/Program Files/MySQL/MySQL Server 4.1/scripts/mysql_fix_privilege_tables.sql</code></strong> </pre><p> If your installation is located in some other directory, adjust the pathnames appropriately. </p><p> The <span><strong class="command">mysql</strong></span> command will prompt you for the <code class="literal">root</code> password; enter it when prompted. </p><p> As with the Unix procedure, you might see some <code class="literal">Duplicate column name</code> warnings as <span><strong class="command">mysql</strong></span> processes the statements in the <code class="filename">mysql_fix_privilege_tables.sql</code> script; you can ignore them. </p><p> After running the script, stop the server and restart it. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="server-shutdown"></a>5.4. The MySQL Server Shutdown Process</h2></div></div></div><p> The server shutdown process can be summarized like this: </p><div class="orderedlist"><ol type="1"><li><p> The shutdown process is initiated. </p></li><li><p> The server creates a shutdown thread if necessary. </p></li><li><p> The server stops accepting new connections. </p></li><li><p> The server terminates current activity. </p></li><li><p> Storage engines are shut down or closed. </p></li><li><p> The server exits. </p></li></ol></div><p> A more detailed description of the process follows: </p><div class="orderedlist"><ol type="1"><li><p> The shutdown process is initiated. </p><p> Server shutdown can be initiated several ways. For example, a user with the <code class="literal">SHUTDOWN</code> privilege can execute a <span><strong class="command">mysqladmin shutdown</strong></span> command. <span><strong class="command">mysqladmin</strong></span> can be used on any platform supported by MySQL. Other operating system-specific shutdown initiation methods are possible as well: The server shuts down on Unix when it receives a <code class="literal">SIGTERM</code> signal. A server running as a service on Windows shuts down when the services manager tells it to. (On Windows, a user with Administrator rights can also shut down the server using <code class="literal">NET STOP <em class="replaceable"><code>service_name</code></em></code>, where <em class="replaceable"><code>service_name</code></em> is the name of the MySQL service. By default, this is <code class="literal">MySQL</code>.) </p></li><li><p> The server creates a shutdown thread if necessary. </p><p> Depending on how shutdown was initiated, the server might create a thread to handle the shutdown process. If shutdown was requested by a client, a shutdown thread is created. If shutdown is the result of receiving a <code class="literal">SIGTERM</code> signal, the signal thread might handle shutdown itself, or it might create a separate thread to do so. If the server tries to create a shutdown thread and cannot (for example, if memory is exhausted), it issues a diagnostic message that appears in the error log: </p><pre class="programlisting">Error: cannot create thread to kill server </pre></li><li><p> The server stops accepting new connections. </p><p> To prevent new activity from being initiated during shutdown, the server stops accepting new client connections. It does this by closing the network connections to which it normally listens for connections: the TCP/IP port, the Unix socket file, the Windows named pipe, and shared memory on Windows. </p></li><li><p> The server terminates current activity. </p><p> For each thread that is associated with a client connection, the connection to the client is broken and the thread is marked as killed. Threads die when they notice that they are so marked. Threads for idle connections die quickly. Threads that currently are processing queries check their state periodically and take longer to die. For additional information about thread termination, see <a href="sql-syntax.html#kill" title="13.5.5.3. KILL Syntax">Section 13.5.5.3, “<code class="literal">KILL</code> Syntax”</a>, in particular for the instructions about killed <code class="literal">REPAIR TABLE</code> or <code class="literal">OPTIMIZE TABLE</code> operations on <code class="literal">MyISAM</code> tables. </p><p> For threads that have an open transaction, the transaction is rolled back. Note that if a thread is updating a non-transactional table, an operation such as a multiple-row <code class="literal">UPDATE</code> or <code class="literal">INSERT</code> may leave the table partially updated, because the operation can terminate before completion. </p><p> If the server is a master replication server, threads associated with currently connected slaves are treated like other client threads. That is, each one is marked as killed and exits when it next checks its state. </p><p> If the server is a slave replication server, the I/O and SQL threads, if active, are stopped before client threads are marked as killed. The SQL thread is allowed to finish its current statement (to avoid causing replication problems) then stops. If the SQL thread was in the middle of a transaction at this point, the transaction is rolled back. </p></li><li><p> Storage engines are shut down or closed. </p><p> At this stage, the table cache is flushed and all open tables are closed. </p><p> Each storage engine performs any actions necessary for tables that it manages. For example, MyISAM flushes any pending index writes for a table. InnoDB flushes its buffer pool to disk, writes the current LSN to the tablespace, and terminates its own internal threads. </p></li><li><p> The server exits. </p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security"></a>5.5. General Security Issues</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="database-administration.html#security-guidelines">5.5.1. General Security Guidelines</a></span></dt><dt><span class="section"><a href="database-administration.html#security-against-attack">5.5.2. Making MySQL Secure Against Attackers</a></span></dt><dt><span class="section"><a href="database-administration.html#privileges-options">5.5.3. Startup Options for <span><strong class="command">mysqld</strong></span> Concerning Security</a></span></dt><dt><span class="section"><a href="database-administration.html#load-data-local">5.5.4. Security Issues with <code class="literal">LOAD DATA LOCAL</code></a></span></dt></dl></div><a class="indexterm" name="id2785963"></a><p> 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 <a href="database-administration.html#privilege-system" title="5.6. The MySQL Access Privilege System">Section 5.6, “The MySQL Access Privilege System”</a>. </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-guidelines"></a>5.5.1. General Security Guidelines</h3></div></div></div><p> Anyone using MySQL on a computer connected to the Internet should read this section to avoid the most common security mistakes. </p><p> 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. </p><p> MySQL uses security based on Access Control Lists (ACLs) for all connections, queries, and other operations that users can attempt to perform. There is also some support for SSL-encrypted connections between MySQL clients and servers. Many of the concepts discussed here are not specific to MySQL at all; the same general ideas apply to almost all applications. </p><p> When running MySQL, follow these guidelines whenever possible: </p><div class="itemizedlist"><ul type="disc"><li><p> <span class="bold"><strong>Do not ever give anyone (except MySQL <code class="literal">root</code> accounts) access to the <code class="literal">user</code> table in the <code class="literal">mysql</code> database!</strong></span> This is critical. <span class="bold"><strong>The encrypted password is the real password in MySQL.</strong></span> Anyone who knows the password that is listed in the <code class="literal">mysql.user</code> table and who has access to the host listed for the account <span class="emphasis"><em>can easily log in as that user</em></span>. </p></li><li><p> Learn the MySQL access privilege system. The <code class="literal">GRANT</code> and <code class="literal">REVOKE</code> statements are used for controlling access to MySQL. Do not grant any more privileges than necessary. Never grant privileges to all hosts. </p><p> Checklist: </p><div class="itemizedlist"><ul type="circle"><li><p> Try <code class="literal">mysql -u root</code>. If you are able to connect successfully to the server without being asked for a password, then <span class="emphasis"><em>anyone</em></span> can connect to your MySQL server as the MySQL <code class="literal">root</code> user with full privileges. Review the MySQL installation instructions, paying particular attention to the information about setting a <code class="literal">root</code> password. See <a href="installing.html#default-privileges" title="2.9.3. Securing the Initial MySQL Accounts">Section 2.9.3, “Securing the Initial MySQL Accounts”</a>. </p></li><li><p> Use the <code class="literal">SHOW GRANTS</code> statement to see who has access to what. Then use the <code class="literal">REVOKE</code> statement to remove those privileges that are not necessary. </p></li></ul></div></li><li><p> 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 <code class="literal">MD5()</code>, <code class="literal">SHA1()</code>, or some other one-way hashing function. </p></li><li><p> Do not choose passwords from dictionaries. There are special programs to break them. Even passwords like “<span class="quote">xfish98</span>” are very bad. Much better is “<span class="quote">duag98</span>” which contains the same word “<span class="quote">fish</span>” but typed one key to the left on a standard QWERTY keyboard. Another method is to use the first characters of each word in a sentence. For example, “<span class="quote">Mhall</span>” is taken from “<span class="quote">Mary had a little lamb.</span>” This is easy to remember and type, but difficult to guess for someone who does not know it. </p></li><li><p> 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). </p><p> Checklist: </p><div class="itemizedlist"><ul type="circle"><li><p> Try to scan your ports from the Internet using a tool such as <code class="literal">nmap</code>. 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 <code class="literal">server_host</code> is the host on which your MySQL server runs: </p><pre class="programlisting">shell> <strong class="userinput"><code>telnet server_host 3306</code></strong> </pre><p> 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 <span><strong class="command">telnet</strong></span> hangs or the connection is refused, this is good; this means that the port is blocked. </p></li></ul></div></li><li><p> 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 “<span class="quote"><code class="literal">; DROP DATABASE mysql;</code></span>”. This is an extreme example, but large security leaks and data loss might occur as a result of hackers using similar techniques, if you do not prepare for them. </p><p> 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 <code class="literal">SELECT * FROM table WHERE ID=234</code> when a user enters the value <code class="literal">234</code>, the user can enter the value <code class="literal">234 OR 1=1</code> to cause the application to generate the query <code class="literal">SELECT * FROM table WHERE ID=234 OR 1=1</code>. 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 single quotes around the numeric constants: <code class="literal">SELECT * FROM table WHERE ID='234'</code>. If the user enters extra information, it all becomes part of the string. In a numeric context, MySQL automatically converts this string to a number and strips any trailing non-numeric characters from it. </p><p> 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. </p><p> Checklist: </p><div class="itemizedlist"><ul type="circle"><li><p> Try to enter ‘<code class="literal">'</code>’ and ‘<code class="literal">"</code>’ in all your Web forms. If you get any kind of MySQL error, investigate the problem right away. </p></li><li><p> Try to modify any dynamic URLs by adding <code class="literal">%22</code> (‘<code class="literal">"</code>’), <code class="literal">%23</code> (‘<code class="literal">#</code>’), and <code class="literal">%27</code> (‘<code class="literal">'</code>’) in the URL. </p></li><li><p> Try to modify data types in dynamic URLs from numeric ones to character ones containing characters from previous examples. Your application should be safe against this and similar attacks. </p></li><li><p> 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! </p></li><li><p> Check data sizes before passing them to MySQL. </p></li><li><p> 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. </p></li></ul></div></li><li><p> Many application programming interfaces provide a means of escaping special characters in data values. Properly used, this prevents application users from entering values that cause the application to generate statements that have a different effect than you intend: </p><div class="itemizedlist"><ul type="circle"><li><p> MySQL C API: Use the <code class="literal">mysql_real_escape_string()</code> API call. </p></li><li><p> MySQL++: Use the <code class="literal">escape</code> and <code class="literal">quote</code> modifiers for query streams. </p></li><li><p> PHP: Use the <code class="literal">mysql_escape_string()</code> function, which is based on the function of the same name in the MySQL C API. Prior to PHP 4.0.3, use <code class="literal">addslashes()</code> instead. </p></li><li><p> Perl DBI: Use the <code class="literal">quote()</code> method or use placeholders. </p></li><li><p> Java JDBC: Use a <code class="literal">PreparedStatement</code> object and placeholders. </p></li></ul></div><p> Other programming interfaces might have similar capabilities. </p></li><li><p> 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. </p></li><li><p> Learn to use the <code class="literal">tcpdump</code> and <code class="literal">strings</code> utilities. For most cases, you can check whether MySQL data streams are unencrypted by issuing a command like the following: </p><pre class="programlisting">shell> <strong class="userinput"><code>tcpdump -l -i eth0 -w - src or dst port 3306 | strings</code></strong> </pre><p> (This works under Linux and should work with small modifications under other systems.) <span class="bold"><strong>Warning</strong></span>: If you do not see plaintext data, this does not always mean that the information actually is encrypted. If you need high security, you should consult with a security expert. </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="security-against-attack"></a>5.5.2. Making MySQL Secure Against Attackers</h3></div></div></div><a class="indexterm" name="id2786580"></a><a class="indexterm" name="id2786590"></a><p> When you connect to a MySQL server, you should use a password. The password is not transmitted in clear text over the connection. Password handling during the client connection sequence was upgraded in MySQL 4.1.1 to be very secure. If you are using an older version of MySQL, or are still using pre-4.1.1-style passwords, the encryption algorithm is less strong and with some effort a clever attacker who can sniff the traffic between the client and the server can crack the password. (See <a href="database-administration.html#password-hashing" title="5.6.9. Password Hashing in MySQL 4.1">Section 5.6.9, “Password Hashing in MySQL 4.1”</a> 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. </p><p> All other information is transferred as text that can be read by anyone who is able to watch the connection. If you are concerned about this, you can use the compressed protocol (in MySQL 3.22 and above) to make traffic much more difficult to decipher. To make the connection even more secure, you should use SSH to obtain an encrypted TCP/IP connection between a MySQL server and a MySQL client. You can find an Open Source SSH client at <a href="http://www.openssh.org/" target="_top">http://www.openssh.org/</a>, and a commercial SSH client at <a href="http://www.ssh.com/" target="_top">http://www.ssh.com/</a>. </p><p> If you are using MySQL 4.0 or newer, you can also use internal OpenSSL support. See <a href="database-administration.html#secure-connections" title="5.7.7. Using Secure Connections">Section 5.7.7, “Using Secure Connections”</a>. </p><p> To make a MySQL system secure, you should strongly consider the following suggestions: </p><div class="itemizedlist"><ul type="disc"><li><p> Use passwords for all MySQL users. A client program does not necessarily know the identity of the person running it. It is common for client/server applications that the user can specify any username to the client program. For example, anyone can use the <span><strong class="command">mysql</strong></span> program to connect as any other person simply by invoking it as <code class="literal">mysql -u <em class="replaceable"><code>other_user</code></em> <em class="replaceable"><code>db_name</code></em></code> if <em class="replaceable"><code>other_user</code></em> has no password. If all users have a password, connecting using another user's account becomes much more difficult. </p><p> To change the password for a user, use the <code class="literal">SET PASSWORD</code> statement. It is also possible to update the <code class="literal">user</code> table in the <code class="literal">mysql</code> database directly. For example, to change the password of all MySQL accounts that have a username of <code class="literal">root</code>, do this: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql -u root</code></strong> mysql> <strong class="userinput"><code>UPDATE mysql.user SET Password=PASSWORD('<em class="replaceable"><code>newpwd</code></em>')</code></strong> -> <strong class="userinput"><code>WHERE User='root';</code></strong> mysql> <strong class="userinput"><code>FLUSH PRIVILEGES;</code></strong> </pre></li><li><p> <span class="emphasis"><em>Do not run the MySQL server as the Unix <code class="literal">root</code> user</em></span>. This is very dangerous, because any user with the <code class="literal">FILE</code> privilege is able to create files as <code class="literal">root</code> (for example, <code class="literal">~root/.bashrc</code>). To prevent this, <span><strong class="command">mysqld</strong></span> refuses to run as <code class="literal">root</code> unless specified explicitly using the option <code class="option">--user=root</code>. </p><p> <span><strong class="command">mysqld</strong></span> can (and should) be run as an ordinary, unprivileged user instead. You can also create a separate Unix account named <code class="literal">mysql</code> to make everything even more secure. Use the account only for administering MySQL. To start <span><strong class="command">mysqld</strong></span> as another Unix user, add a <code class="literal">user</code> option that specifies the username to the <code class="literal">[mysqld]</code> group of the <code class="filename">/etc/my.cnf</code> option file or the <code class="filename">my.cnf</code> option file in the server's data directory. For example: </p><pre class="programlisting">[mysqld] user=mysql </pre><p> This causes the server to start as the designated user whether you start it manually or by using <span><strong class="command">mysqld_safe</strong></span> or <span><strong class="command">mysql.server</strong></span>. For more details, see <a href="problems.html#changing-mysql-user" title="A.3.2. How to Run MySQL as a Normal User">Section A.3.2, “How to Run MySQL as a Normal User”</a>. </p><p> Running <span><strong class="command">mysqld</strong></span> as a Unix user other than <code class="literal">root</code> does not mean that you need to change the <code class="literal">root</code> username in the <code class="literal">user</code> table. <span class="emphasis"><em>Usernames for MySQL accounts have nothing to do with usernames for Unix accounts</em></span>. </p></li><li><p> Do not allow the use of symlinks to tables. (This can be disabled with the <code class="option">--skip-symbolic-links</code> option.) This is especially important if you run <span><strong class="command">mysqld</strong></span> as <code class="literal">root</code>, because anyone having write access to the server's data directory then could delete any file in the system! See <a href="optimization.html#symbolic-links-to-tables" title="7.6.1.2. Using Symbolic Links for Tables on Unix">Section 7.6.1.2, “Using Symbolic Links for Tables on Unix”</a>. </p></li><li><p> Make sure that the only Unix user with read or write privileges in the database directories is the user that <span><strong class="command">mysqld</strong></span> runs as. </p></li><li><p> Do not grant the <code class="literal">PROCESS</code> or <code class="literal">SUPER</code> privilege to non-administrative users. The output of <span><strong class="command">mysqladmin processlist</strong></span> 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 a query such as <code class="literal">UPDATE user SET password=PASSWORD('<em class="replaceable"><code>plaintext-password</code></em>');</code>. </p><p> <span><strong class="command">mysqld</strong></span> reserves an extra connection for users who have the <code class="literal">SUPER</code> privilege (<code class="literal">PROCESS</code> before MySQL 4.0.2), so that a MySQL <code class="literal">root</code> user can log in and check server activity even if all normal connections are in use. </p><p> The <code class="literal">SUPER</code> privilege can be used to terminate client connections, change server operation by changing the value of system variables, and control replication servers. </p></li><li><p> Do not grant the <code class="literal">FILE</code> privilege to non-administrative users. Any user that has this privilege can write a file anywhere in the filesystem with the privileges of the <span><strong class="command">mysqld</strong></span> daemon. To make this a bit safer, files generated with <code class="literal">SELECT ... INTO OUTFILE</code> do not overwrite existing files and are writable by everyone. </p><a class="indexterm" name="id2786993"></a><p> The <code class="literal">FILE</code> 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 <code class="literal">LOAD DATA</code> to load <code class="filename">/etc/passwd</code> into a table, which then can be displayed with <code class="literal">SELECT</code>. </p></li><li><p> If you do not 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. </p></li><li><p> If you want to restrict the number of connections allowed to a single account, you can do so by setting the <code class="literal">max_user_connections</code> variable in <span><strong class="command">mysqld</strong></span>. The <code class="literal">GRANT</code> statement also supports resource control options for limiting the extent of server use allowed to an account. </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="privileges-options"></a>5.5.3. Startup Options for <span><strong class="command">mysqld</strong></span> Concerning Security</h3></div></div></div><p> The following <span><strong class="command">mysqld</strong></span> options affect security: </p><div class="itemizedlist"><ul type="disc"><li><p> <code class="option">--allow-suspicious-udfs</code> </p><p> This option controls whether user-defined functions that have only an <code class="literal">xxx</code> symbol for the main function can be loaded. By default, the option is turned off and only UDFs that have at least one auxiliary symbol can be loaded. This prevents attempts at loading functions from shared object files other than those containing legitimate UDFs. This option was added in MySQL 4.0.24 and 4.1.10a. See <a href="extending-mysql.html#udf-security" title="20.2.4.6. User-Defined Function Security Precautions">Section 20.2.4.6, “User-Defined Function Security Precautions”</a>. </p></li><li><p> <code class="option">--local-infile[={0|1}]</code> </p><p> If you start the server with <code class="option">--local-infile=0</code>, clients cannot use <code class="literal">LOCAL</code> in <code class="literal">LOAD DATA</code> statements. See <a href="database-administration.html#load-data-local" title="5.5.4. Security Issues with LOAD DATA LOCAL">Section 5.5.4, “Security Issues with <code class="literal">LOAD DATA LOCAL</code>”</a>. </p></li><li><p> <code class="option">--old-passwords</code> </p><p> Force the server to generate short (pre-4.1) password hashes for new passwords. This is useful for compatibility when the server must support older client programs. See <a href="database-administration.html#password-hashing" title="5.6.9. Password Hashing in MySQL 4.1">Section 5.6.9, “Password Hashing in MySQL 4.1”</a>. </p></li><li><p> <code class="option">--safe-show-database</code> </p><p> With this option, the <code class="literal">SHOW DATABASES</code> statement displays the names of only those databases for which the user has some kind of privilege. As of MySQL 4.0.2, this option is deprecated and does not do anything (it is enabled by default), because there is a <code class="literal">SHOW DATABASES</code> privilege that can be used to control access to database names on a per-account basis. See <a href="sql-syntax.html#grant" title="13.5.1.2. GRANT and REVOKE Syntax">Section 13.5.1.2, “<code class="literal">GRANT</code> and <code class="literal">REVOKE</code> Syntax”</a>. </p></li><li><p> <code class="option">--safe-user-create</code> </p><p> If this is enabled, a user cannot create new users with the <code class="literal">GRANT</code> statement unless the user has the <code class="literal">INSERT</code> privilege for the <code class="literal">mysql.user</code> 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: </p><pre class="programlisting">mysql> <strong class="userinput"><code>GRANT INSERT(user) ON mysql.user TO '<em class="replaceable"><code>user_name</code></em>'@'<em class="replaceable"><code>host_name</code></em>';</code></strong> </pre><p> This ensures that the user cannot change any privilege columns directly, but has to use the <code class="literal">GRANT</code> statement to give privileges to other users. </p></li><li><p> <code class="option">--secure-auth</code> </p><p> Disallow authentication for accounts that have old (pre-4.1) passwords. This option is available as of MySQL 4.1.1. </p></li><li><p> <code class="option">--skip-grant-tables</code> </p><p> This option causes the server not to use the privilege system at all. This gives anyone with access to the server <span class="emphasis"><em>unrestricted access</em></span> to <span class="emphasis"><em>all databases</em></span>. You can cause a running server to start using the grant tables again by executing <span><strong class="command">mysqladmin flush-privileges</strong></span> or <span><strong class="command">mysqladmin reload</strong></span> command from a system shell, or by issuing a MySQL <code class="literal">FLUSH PRIVILEGES</code> statement. This option also suppresses loading of user-defined functions (UDFs). </p></li><li><p> <code class="option">--skip-name-resolve</code> </p><p> Hostnames are not resolved. All <code class="literal">Host</code> column values in the grant tables must be IP numbers or <code class="literal">localhost</code>. </p></li><li><p> <code class="option">--skip-networking</code> </p><p> Do not allow TCP/IP connections over the network. All connections to <span><strong class="command">mysqld</strong></span> 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. </p></li><li><p> <code class="option">--skip-show-database</code> </p><p> With this option, the <code class="literal">SHOW DATABASES</code> statement is allowed only to users who have the <code class="literal">SHOW DATABASES</code> privilege, and the statement displays all database names. Without this option, <code class="literal">SHOW DATABASES</code> is allowed to all users, but displays each database name only if the user has the <code class="literal">SHOW DATABASES</code> privilege or some privilege for the database. Note that any global privilege is a privilege for the database. </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="load-data-local"></a>5.5.4. Security Issues with <code class="literal">LOAD DATA LOCAL</code></h3></div></div></div><p> The <code class="literal">LOAD DATA</code> statement can load a file that is located on the server host, or it can load a file that is located on the client host when the <code class="literal">LOCAL</code> keyword is specified. </p><p> There are two potential security issues with supporting the <code class="literal">LOCAL</code> version of <code class="literal">LOAD DATA</code> statements: </p><div class="itemizedlist"><ul type="disc"><li><p> The transfer of the file from the client host to the server host is initiated by the MySQL server. In theory, a patched server could be built that would tell the client program to transfer a file of the server's choosing rather than the file named by the client in the <code class="literal">LOAD DATA</code> statement. Such a server could access any file on the client host to which the client user has read access. </p></li><li><p> In a Web environment where the clients are connecting from a Web server, a user could use <code class="literal">LOAD DATA LOCAL</code> to read any files that the Web server process has read access to (assuming that a user could run any command against the SQL server). In this environment, the client with respect to the MySQL server actually is the Web server, not the program being run by the user connecting to the Web server. </p></li></ul></div><p> To deal with these problems, we changed how <code class="literal">LOAD DATA LOCAL</code> is handled as of MySQL 3.23.49 and MySQL 4.0.2 (4.0.13 on Windows): </p><div class="itemizedlist"><ul type="disc"><li><p> By default, all MySQL clients and libraries in binary distributions are compiled with the <code class="option">--enable-local-infile</code> option, to be compatible with MySQL 3.23.48 and before. </p></li><li><p> If you build MySQL from source but do not use the <code class="option">--enable-local-infile</code> option to <span><strong class="command">configure</strong></span>, <code class="literal">LOAD DATA LOCAL</code> cannot be used by any client unless it is written explicitly to invoke <code class="literal">mysql_options(... MYSQL_OPT_LOCAL_INFILE, 0)</code>. See <a href="apis.html#mysql-options" title="18.2.3.47. mysql_options()">Section 18.2.3.47, “<code class="literal">mysql_options()</code>”</a>. </p></li><li><p> You can disable all <code class="literal">LOAD DATA LOCAL</code> commands from the server side by starting <span><strong class="command">mysqld</strong></span> with the <code class="option">--local-infile=0</code> option. </p></li><li><p> For the <span><strong class="command">mysql</strong></span> command-line client, <code class="literal">LOAD DATA LOCAL</code> can be enabled by specifying the <code class="option">--local-infile[=1]</code> option, or disabled with the <code class="option">--local-infile=0</code> option. Similarly, for <span><strong class="command">mysqlimport</strong></span>, the <code class="option">--local</code> or <code class="option">-L</code> option enables local data file loading. In any case, successful use of a local loading operation requires that the server is enabled to allow it. </p></li><li><p> If you use <code class="literal">LOAD DATA LOCAL</code> in Perl scripts or other programs that read the <code class="literal">[client]</code> group from option files, you can add the <code class="literal">local-infile=1</code> option to that group. However, to keep this from causing problems for programs that do not understand <code class="literal">local-infile</code>, specify it using the <code class="literal">loose-</code> prefix: </p><pre class="programlisting">[client] loose-local-infile=1 </pre><p> The <code class="literal">loose-</code> prefix can be used as of MySQL 4.0.2. </p></li><li><p> If <code class="literal">LOAD DATA LOCAL INFILE</code> is disabled, either in the server or the client, a client that attempts to issue such a statement receives the following error message: </p><pre class="programlisting">ERROR 1148: The used command is not allowed with this MySQL version </pre></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="privilege-system"></a>5.6. The MySQL Access Privilege System</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="database-administration.html#what-privileges">5.6.1. What the Privilege System Does</a></span></dt><dt><span class="section"><a href="database-administration.html#privileges">5.6.2. How the Privilege System Works</a></span></dt><dt><span class="section"><a href="database-administration.html#privileges-provided">5.6.3. Privileges Provided by MySQL</a></span></dt><dt><span class="section"><a href="database-administration.html#connecting">5.6.4. Connecting to the MySQL Server</a></span></dt><dt><span class="section"><a href="database-administration.html#connection-access">5.6.5. Access Control, Stage 1: Connection Verification</a></span></dt><dt><span class="section"><a href="database-administration.html#request-access">5.6.6. Access Control, Stage 2: Request Verification</a></span></dt><dt><span class="section"><a href="database-administration.html#privilege-changes">5.6.7. When Privilege Changes Take Effect</a></span></dt><dt><span class="section"><a href="database-administration.html#access-denied">5.6.8. Causes of <code class="literal">Access denied</code> Errors</a></span></dt><dt><span class="section"><a href="database-administration.html#password-hashing">5.6.9. Password Hashing in MySQL 4.1</a></span></dt></dl></div><a class="indexterm" name="id2787675"></a><a class="indexterm" name="id2787682"></a><a class="indexterm" name="id2787692"></a><a class="indexterm" name="id2787699"></a><p> MySQL has an advanced but non-standard security and privilege system. This section describes how it works. </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="what-privileges"></a>5.6.1. What the Privilege System Does</h3></div></div></div><a class="indexterm" name="id2787720"></a><a class="indexterm" name="id2787730"></a><a class="indexterm" name="id2787736"></a><p> 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 <code class="literal">SELECT</code>, <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, and <code class="literal">DELETE</code>. </p><p> Additional functionality includes the ability to have anonymous users and to grant privileges for MySQL-specific functions such as <code class="literal">LOAD DATA INFILE</code> and administrative operations. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="privileges"></a>5.6.2. How the Privilege System Works</h3></div></div></div><a class="indexterm" name="id2787788"></a><p> 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 <span class="emphasis"><em>the host from which you connect</em></span> and <span class="emphasis"><em>the username you specify</em></span>. When you issue requests after connecting, the system grants privileges according to your identity and <span class="emphasis"><em>what you want to do</em></span>. </p><p> 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 <code class="literal">joe</code> who connects from <code class="literal">office.com</code> need not be the same person as the user <code class="literal">joe</code> who connects from <code class="literal">elsewhere.com</code>. MySQL handles this by allowing you to distinguish users on different hosts that happen to have the same name: You can grant one set of privileges for connections by <code class="literal">joe</code> from <code class="literal">office.com</code>, and a different set of privileges for connections by <code class="literal">joe</code> from <code class="literal">elsewhere.com</code>. </p><p> MySQL access control involves two stages: </p><div class="itemizedlist"><ul type="disc"><li><p> <span class="bold"><strong>Stage 1</strong></span>: The server checks whether it should allow you to connect. </p></li><li><p> <span class="bold"><strong>Stage 2</strong></span>: Assuming that you can connect, the server checks each statement you issue to see whether you have sufficient privileges to perform it. For example, if you try to select rows from a table in a database or drop a table from the database, the server verifies that you have the <code class="literal">SELECT</code> privilege for the table or the <code class="literal">DROP</code> privilege for the database. </p></li></ul></div><p> If your privileges are changed (either by yourself or someone else) while you are connected, those changes do not necessarily take effect immediately for the next statement you issue. See <a href="database-administration.html#privilege-changes" title="5.6.7. When Privilege Changes Take Effect">Section 5.6.7, “When Privilege Changes Take Effect”</a> for details. </p><p> The server stores privilege information in the grant tables of the <code class="literal">mysql</code> database (that is, in the database named <code class="literal">mysql</code>). The MySQL server reads the contents of these tables into memory when it starts and re-reads them under the circumstances indicated in <a href="database-administration.html#privilege-changes" title="5.6.7. When Privilege Changes Take Effect">Section 5.6.7, “When Privilege Changes Take Effect”</a>. Access-control decisions are based on the in-memory copies of the grant tables. </p><p> Normally, you manipulate the contents of the grant tables indirectly by using the <code class="literal">GRANT</code> and <code class="literal">REVOKE</code> statements to set up accounts and control the privileges available to each one. See <a href="sql-syntax.html#grant" title="13.5.1.2. GRANT and REVOKE Syntax">Section 13.5.1.2, “<code class="literal">GRANT</code> and <code class="literal">REVOKE</code> Syntax”</a>. The discussion here describes the underlying structure of the grant tables and how the server uses their contents when interacting with clients. </p><p> The server uses the <code class="literal">user</code>, <code class="literal">db</code>, and <code class="literal">host</code> tables in the <code class="literal">mysql</code> database at both stages of access control. The columns in these grant tables are shown here: </p><div class="informaltable"><table border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="bold"><strong>Table Name</strong></span></td><td><span class="bold"><strong>user</strong></span></td><td><span class="bold"><strong>db</strong></span></td><td><span class="bold"><strong>host</strong></span></td></tr><tr><td><span class="bold"><strong>Scope columns</strong></span></td><td><code class="literal">Host</code></td><td><code class="literal">Host</code></td><td><code class="literal">Host</code></td></tr><tr><td> </td><td><code class="literal">User</code></td><td><code class="literal">Db</code></td><td><code class="literal">Db</code></td></tr><tr><td> </td><td><code class="literal">Password</code></td><td><code class="literal">User</code></td><td> </td></tr><tr><td><span class="bold"><strong>Privilege columns</strong></span></td><td><code class="literal">Select_priv</code></td><td><code class="literal">Select_priv</code></td><td><code class="literal">Select_priv</code></td></tr><tr><td> </td><td><code class="literal">Insert_priv</code></td><td><code class="literal">Insert_priv</code></td><td><code class="literal">Insert_priv</code></td></tr><tr><td> </td><td><code class="literal">Update_priv</code></td><td><code class="literal">Update_priv</code></td><td><code class="literal">Update_priv</code></td></tr><tr><td> </td><td><code class="literal">Delete_priv</code></td><td><code class="literal">Delete_priv</code></td><td><code class="literal">Delete_priv</code></td></tr><tr><td> </td><td><code class="literal">Index_priv</code></td><td><code class="literal">Index_priv</code></td><td><code class="literal">Index_priv</code></td></tr><tr><td> </td><td><code class="literal">Alter_priv</code></td><td><code class="literal">Alter_priv</code></td><td><code class="literal">Alter_priv</code></td></tr><tr><td> </td><td><code class="literal">Create_priv</code></td><td><code class="literal">Create_priv</code></td><td><code class="literal">Create_priv</code></td></tr><tr><td> </td><td><code class="literal">Drop_priv</code></td><td><code class="literal">Drop_priv</code></td><td><code class="literal">Drop_priv</code></td></tr><tr><td> </td><td><code class="literal">Grant_priv</code></td><td><code class="literal">Grant_priv</code></td><td><code class="literal">Grant_priv</code></td></tr><tr><td> </td><td><code class="literal">References_priv</code></td><td><code class="literal">References_priv</code></td><td><code class="literal">References_priv</code></td></tr><tr><td> </td><td><code class="literal">Reload_priv</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">Shutdown_priv</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">Process_priv</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">File_priv</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">Show_db_priv</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">Super_priv</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">Create_tmp_table_priv</code></td><td><code class="literal">Create_tmp_table_priv</code></td><td><code class="literal">Create_tmp_table_priv</code></td></tr><tr><td> </td><td><code class="literal">Lock_tables_priv</code></td><td><code class="literal">Lock_tables_priv</code></td><td><code class="literal">Lock_tables_priv</code></td></tr><tr><td> </td><td><code class="literal">Execute_priv</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">Repl_slave_priv</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">Repl_client_priv</code></td><td> </td><td> </td></tr><tr><td><span class="bold"><strong>Security columns</strong></span></td><td><code class="literal">ssl_type</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">ssl_cipher</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">x509_issuer</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">x509_subject</code></td><td> </td><td> </td></tr><tr><td><span class="bold"><strong>Resource control columns</strong></span></td><td><code class="literal">max_questions</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">max_updates</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">max_connections</code></td><td> </td><td> </td></tr><tr><td> </td><td><code class="literal">max_user_connections</code></td><td> </td><td> </td></tr></tbody></table></div><p> The <code class="literal">ssl_type</code>, <code class="literal">ssl_cipher</code>, <code class="literal">x509_issuer</code>, and <code class="literal">x509_subject</code> columns were added in MySQL 4.0.0. </p><p> The <code class="literal">Create_tmp_table_priv</code>, <code class="literal">Execute_priv</code>, <code class="literal">Lock_tables_priv</code>, <code class="literal">Repl_client_priv</code>, <code class="literal">Repl_slave_priv</code>, <code class="literal">Show_db_priv</code>, <code class="literal">Super_priv</code>, <code class="literal">max_questions</code>, <code class="literal">max_updates</code>, and <code class="literal">max_connections</code> columns were added in MySQL 4.0.2. <code class="literal">Execute_priv</code> is not operational through MySQL 4.1. </p><p> During the second stage of access control, the server performs request verification to make sure that each client has sufficient privileges for each request that it issues. In addition to the <code class="literal">user</code>, <code class="literal">db</code>, and <code class="literal">host</code> grant tables, the server may also consult the <code class="literal">tables_priv</code> and <code class="literal">columns_priv</code> tables for requests that involve tables. The <code class="literal">tables_priv</code> and <code class="literal">columns_priv</code> tables provide finer privilege control at the table and column levels. They have the following columns: </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><tbody><tr><td><span class="bold"><strong>Table Name</strong></span></td><td><span class="bold"><strong>tables_priv</strong></span></td><td><span class="bold"><strong>columns_priv</strong></span></td></tr><tr><td><span class="bold"><strong>Scope columns</strong></span></td><td><code class="literal">Host</code></td><td><code class="literal">Host</code></td></tr><tr><td> </td><td><code class="literal">Db</code></td><td><code class="literal">Db</code></td></tr><tr><td> </td><td><code class="literal">User</code></td><td><code class="literal">User</code></td></tr><tr><td> </td><td><code class="literal">Table_name</code></td><td><code class="literal">Table_name</code></td></tr><tr><td> </td><td> </td><td><code class="literal">Column_name</code></td></tr><tr><td><span class="bold"><strong>Privilege columns</strong></span></td><td><code class="literal">Table_priv</code></td><td><code class="literal">Column_priv</code></td></tr><tr><td> </td><td><code class="literal">Column_priv</code></td><td> </td></tr><tr><td><span class="bold"><strong>Other columns</strong></span></td><td><code class="literal">Timestamp</code></td><td><code class="literal">Timestamp</code></td></tr><tr><td> </td><td><code class="literal">Grantor</code></td><td> </td></tr></tbody></table></div><p> The <code class="literal">Timestamp</code> and <code class="literal">Grantor</code> columns currently are unused and are discussed no further here. </p><p> Each grant table contains scope columns and privilege columns: </p><div class="itemizedlist"><ul type="disc"><li><p> Scope columns determine the scope of each entry (row) in the tables; that is, the context in which the row applies. For example, a <code class="literal">user</code> table row with <code class="literal">Host</code> and <code class="literal">User</code> values of <code class="literal">'thomas.loc.gov'</code> and <code class="literal">'bob'</code> would be used for authenticating connections made to the server from the host <code class="literal">thomas.loc.gov</code> by a client that specifies a username of <code class="literal">bob</code>. Similarly, a <code class="literal">db</code> table row with <code class="literal">Host</code>, <code class="literal">User</code>, and <code class="literal">Db</code> column values of <code class="literal">'thomas.loc.gov'</code>, <code class="literal">'bob'</code> and <code class="literal">'reports'</code> would be used when <code class="literal">bob</code> connects from the host <code class="literal">thomas.loc.gov</code> to access the <code class="literal">reports</code> database. The <code class="literal">tables_priv</code> and <code class="literal">columns_priv</code> tables contain scope columns indicating tables or table/column combinations to which each row applies. The <code class="literal">procs_priv</code> scope columns indicate the store routine to which each row applies. </p></li><li><p> Privilege columns indicate which privileges are granted by a table row; that is, what operations can be performed. The server combines the information in the various grant tables to form a complete description of a user's privileges. The rules used to do this are described in <a href="database-administration.html#request-access" title="5.6.6. Access Control, Stage 2: Request Verification">Section 5.6.6, “Access Control, Stage 2: Request Verification”</a>. </p></li></ul></div><p> Scope columns contain strings. They are declared as shown here; the default value for each is the empty string: </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td><span class="bold"><strong>Column Name</strong></span></td><td><span class="bold"><strong>Type</strong></span></td></tr><tr><td><code class="literal">Host</code></td><td><code class="literal">CHAR(60)</code></td></tr><tr><td><code class="literal">User</code></td><td><code class="literal">CHAR(16)</code></td></tr><tr><td><code class="literal">Password</code></td><td><code class="literal">CHAR(16)</code></td></tr><tr><td><code class="literal">Db</code></td><td><code class="literal">CHAR(64)</code></td></tr><tr><td><code class="literal">Table_name</code></td><td><code class="literal">CHAR(64)</code></td></tr><tr><td><code class="literal">Column_name</code></td><td><code class="literal">CHAR(64)</code></td></tr><tr><td><code class="literal">Routine_name</code></td><td><code class="literal">CHAR(64)</code></td></tr></tbody></table></div><p> Before MySQL 3.23, the <code class="literal">Db</code> column is <code class="literal">CHAR(32)</code> in some tables and <code class="literal">CHAR(60)</code> in others. </p><a class="indexterm" name="id2789148"></a><p> For access-checking purposes, comparisons of <code class="literal">Host</code> values are case-insensitive. <code class="literal">User</code>, <code class="literal">Password</code>, <code class="literal">Db</code>, and <code class="literal">Table_name</code> values are case sensitive. <code class="literal">Column_name</code> values are case insensitive in MySQL 3.22.12 or later. </p><p> In the <code class="literal">user</code>, <code class="literal">db</code>, and <code class="literal">host</code> tables, each privilege is listed in a separate column that is declared as <code class="literal">ENUM('N','Y') DEFAULT 'N'</code>. In other words, each privilege can be disabled or enabled, with the default being disabled. </p><p> In the <code class="literal">tables_priv</code>, <code class="literal">columns_priv</code>, and <code class="literal">procs_priv</code> tables, the privilege columns are declared as <code class="literal">SET</code> columns. Values in these columns can contain any combination of the privileges controlled by the table: </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><tbody><tr><td><span class="bold"><strong>Table Name</strong></span></td><td><span class="bold"><strong>Column Name</strong></span></td><td><span class="bold"><strong>Possible Set Elements</strong></span></td></tr><tr><td><code class="literal">tables_priv</code></td><td><code class="literal">Table_priv</code></td><td><code class="literal">'Select', 'Insert', 'Update', 'Delete', 'Create', 'Drop', 'Grant', 'References', 'Index', 'Alter'</code></td></tr><tr><td><code class="literal">tables_priv</code></td><td><code class="literal">Column_priv</code></td><td><code class="literal">'Select', 'Insert', 'Update', 'References'</code></td></tr><tr><td><code class="literal">columns_priv</code></td><td><code class="literal">Column_priv</code></td><td><code class="literal">'Select', 'Insert', 'Update', 'References'</code></td></tr></tbody></table></div><p> Briefly, the server uses the grant tables as follows: </p><div class="itemizedlist"><ul type="disc"><li><p> The <code class="literal">user</code> table scope columns determine whether to reject or allow incoming connections. For allowed connections, any privileges granted in the <code class="literal">user</code> table indicate the user's global (superuser) privileges. These privileges apply to <span class="emphasis"><em>all</em></span> databases on the server. </p></li><li><p> The <code class="literal">db</code> table scope columns determine which users can access which databases from which hosts. The privilege columns determine which operations are allowed. A privilege granted at the database level applies to the database and to all its tables. </p></li><li><p> The <code class="literal">host</code> table is used in conjunction with the <code class="literal">db</code> table when you want a given <code class="literal">db</code> table row to apply to several hosts. For example, if you want a user to be able to use a database from several hosts in your network, leave the <code class="literal">Host</code> value empty in the user's <code class="literal">db</code> table row, then populate the <code class="literal">host</code> table with a row for each of those hosts. This mechanism is described more detail in <a href="database-administration.html#request-access" title="5.6.6. Access Control, Stage 2: Request Verification">Section 5.6.6, “Access Control, Stage 2: Request Verification”</a>. </p><p> <span class="bold"><strong>Note</strong></span>: The <code class="literal">host</code> table is not affected by the <code class="literal">GRANT</code> and <code class="literal">REVOKE</code> statements. Most MySQL installations need not use this table at all. </p></li><li><p> The <code class="literal">tables_priv</code> and <code class="literal">columns_priv</code> tables are similar to the <code class="literal">db</code> table, but are more fine-grained: They apply at the table and column levels rather than at the database level. A privilege granted at the table level applies to the table and to all its columns. A privilege granted at the column level applies only to a specific column. </p></li></ul></div><p> Administrative privileges (such as <code class="literal">RELOAD</code> or <code class="literal">SHUTDOWN</code>) are specified only in the <code class="literal">user</code> 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 <code class="literal">user</code> table. </p><p> The <code class="literal">FILE</code> privilege also is specified only in the <code class="literal">user</code> 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. </p><p> The <span><strong class="command">mysqld</strong></span> server reads the contents of the grant tables into memory when it starts. You can tell it to re-read the tables by issuing a <code class="literal">FLUSH PRIVILEGES</code> statement or executing a <span><strong class="command">mysqladmin flush-privileges</strong></span> or <span><strong class="command">mysqladmin reload</strong></span> command. Changes to the grant tables take effect as indicated in <a href="database-administration.html#privilege-changes" title="5.6.7. When Privilege Changes Take Effect">Section 5.6.7, “When Privilege Changes Take Effect”</a>. </p><p> When you modify the contents of the grant tables, it is a good idea to make sure that your changes set up privileges the way you want. To check the privileges for a given account, use the <code class="literal">SHOW GRANTS</code> statement. For example, to determine the privileges that are granted to an account with <code class="literal">Host</code> and <code class="literal">User</code> values of <code class="literal">pc84.example.com</code> and <code class="literal">bob</code>, issue this statement: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SHOW GRANTS FOR 'bob'@'pc84.example.com';</code></strong> </pre><p> A useful diagnostic tool is the <span><strong class="command">mysqlaccess</strong></span> script, which Yves Carlier has provided for the MySQL distribution. Invoke <span><strong class="command">mysqlaccess</strong></span> with the <code class="option">--help</code> option to find out how it works. Note that <span><strong class="command">mysqlaccess</strong></span> checks access using only the <code class="literal">user</code>, <code class="literal">db</code>, and <code class="literal">host</code> tables. It does not check table, column, or routine privileges specified in the <code class="literal">tables_priv</code>, <code class="literal">columns_priv</code>, or <code class="literal">procs_priv</code> tables. </p><p> For additional help in diagnosing privilege-related problems, see <a href="database-administration.html#access-denied" title="5.6.8. Causes of Access denied Errors">Section 5.6.8, “Causes of <code class="literal">Access denied</code> Errors”</a>. For general advice on security issues, see <a href="database-administration.html#security" title="5.5. General Security Issues">Section 5.5, “General Security Issues”</a>. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="privileges-provided"></a>5.6.3. Privileges Provided by MySQL</h3></div></div></div><a class="indexterm" name="id2789642"></a><p> Information about account privileges is stored in the <code class="literal">user</code>, <code class="literal">db</code>, <code class="literal">host</code>, <code class="literal">tables_priv</code>, and <code class="literal">columns_priv</code> tables in the <code class="literal">mysql</code> database. The MySQL server reads the contents of these tables into memory when it starts and re-reads them under the circumstances indicated in <a href="database-administration.html#privilege-changes" title="5.6.7. When Privilege Changes Take Effect">Section 5.6.7, “When Privilege Changes Take Effect”</a>. Access-control decisions are based on the in-memory copies of the grant tables. </p><p> The names used in the <code class="literal">GRANT</code> and <code class="literal">REVOKE</code> statements to refer to privileges are shown in the following table, along with the column name associated with each privilege in the grant tables and the context in which the privilege applies. Further information about the meaning of each privilege may be found at <a href="sql-syntax.html#grant" title="13.5.1.2. GRANT and REVOKE Syntax">Section 13.5.1.2, “<code class="literal">GRANT</code> and <code class="literal">REVOKE</code> Syntax”</a>. </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><tbody><tr><td><span class="bold"><strong>Privilege</strong></span></td><td><span class="bold"><strong>Column</strong></span></td><td><span class="bold"><strong>Context</strong></span></td></tr><tr><td><code class="literal">CREATE</code></td><td><code class="literal">Create_priv</code></td><td>databases, tables, or indexes</td></tr><tr><td><code class="literal">DROP</code></td><td><code class="literal">Drop_priv</code></td><td>databases or tables</td></tr><tr><td><code class="literal">GRANT OPTION</code></td><td><code class="literal">Grant_priv</code></td><td>databases, tables, or stored routines</td></tr><tr><td><code class="literal">REFERENCES</code></td><td><code class="literal">References_priv</code></td><td>databases or tables</td></tr><tr><td><code class="literal">ALTER</code></td><td><code class="literal">Alter_priv</code></td><td>tables</td></tr><tr><td><code class="literal">DELETE</code></td><td><code class="literal">Delete_priv</code></td><td>tables</td></tr><tr><td><code class="literal">INDEX</code></td><td><code class="literal">Index_priv</code></td><td>tables</td></tr><tr><td><code class="literal">INSERT</code></td><td><code class="literal">Insert_priv</code></td><td>tables</td></tr><tr><td><code class="literal">SELECT</code></td><td><code class="literal">Select_priv</code></td><td>tables</td></tr><tr><td><code class="literal">UPDATE</code></td><td><code class="literal">Update_priv</code></td><td>tables</td></tr><tr><td><code class="literal">FILE</code></td><td><code class="literal">File_priv</code></td><td>file access on server host</td></tr><tr><td><code class="literal">CREATE TEMPORARY TABLES</code></td><td><code class="literal">Create_tmp_table_priv</code></td><td>server administration</td></tr><tr><td><code class="literal">LOCK TABLES</code></td><td><code class="literal">Lock_tables_priv</code></td><td>server administration</td></tr><tr><td><code class="literal">CREATE USER</code></td><td><code class="literal">Create_user_priv</code></td><td>server administration</td></tr><tr><td><code class="literal">PROCESS</code></td><td><code class="literal">Process_priv</code></td><td>server administration</td></tr><tr><td><code class="literal">RELOAD</code></td><td><code class="literal">Reload_priv</code></td><td>server administration</td></tr><tr><td><code class="literal">REPLICATION CLIENT</code></td><td><code class="literal">Repl_client_priv</code></td><td>server administration</td></tr><tr><td><code class="literal">REPLICATION SLAVE</code></td><td><code class="literal">Repl_slave_priv</code></td><td>server administration</td></tr><tr><td><code class="literal">SHOW DATABASES</code></td><td><code class="literal">Show_db_priv</code></td><td>server administration</td></tr><tr><td><code class="literal">SHUTDOWN</code></td><td><code class="literal">Shutdown_priv</code></td><td>server administration</td></tr><tr><td><code class="literal">SUPER</code></td><td><code class="literal">Super_priv</code></td><td>server administration</td></tr></tbody></table></div><p> The <code class="literal">CREATE TEMPORARY TABLES</code>, <code class="literal">EXECUTE</code>, <code class="literal">LOCK TABLES</code>, <code class="literal">REPLICATION CLIENT</code>, <code class="literal">REPLICATION SLAVE</code>, <code class="literal">SHOW DATABASES</code>, and <code class="literal">SUPER</code> privileges were added in MySQL 4.0.2. (<code class="literal">EXECUTE</code> is not used in any MySQL version through the 4.1 release series.) To use these privileges when upgrading from an earlier version of MySQL that does not have them, you must upgrade your grant tables. See <a href="installing.html#upgrading-grant-tables" title="2.10.3. Upgrading the Grant Tables">Section 2.10.3, “Upgrading the Grant Tables”</a>. </p><p> The <code class="literal">CREATE</code> and <code class="literal">DROP</code> privileges allow you to create new databases and tables, or to drop (remove) existing databases and tables. If you grant the <code class="literal">DROP</code> privilege for the <code class="literal">mysql</code> database to a user, that user can drop the database in which the MySQL access privileges are stored! </p><p> The <code class="literal">SELECT</code>, <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, and <code class="literal">DELETE</code> privileges allow you to perform operations on rows in existing tables in a database. </p><p> <code class="literal">SELECT</code> statements require the <code class="literal">SELECT</code> privilege only if they actually retrieve rows from a table. Some <code class="literal">SELECT</code> statements do not access tables and can be executed without permission for any database. For example, you can use the <span><strong class="command">mysql</strong></span> client as a simple calculator to evaluate expressions that make no reference to tables: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SELECT 1+1;</code></strong> mysql> <strong class="userinput"><code>SELECT PI()*2;</code></strong> </pre><p> The <code class="literal">INDEX</code> privilege allows you to create or drop (remove) indexes. <code class="literal">INDEX</code> applies to existing tables. If you have the <code class="literal">CREATE</code> privilege for a table, you can include index definitions in the <code class="literal">CREATE TABLE</code> statement. </p><p> The <code class="literal">ALTER</code> privilege allows you to use <code class="literal">ALTER TABLE</code> to change the structure of or rename tables. </p><p> The <code class="literal">GRANT</code> privilege allows you to give to other users those privileges that you yourself possess. It can be used for databases, tables, and stored routines. </p><p> The <code class="literal">FILE</code> privilege gives you permission to read and write files on the server host using the <code class="literal">LOAD DATA INFILE</code> and <code class="literal">SELECT ... INTO OUTFILE</code> statements. A user who has the <code class="literal">FILE</code> privilege can read any file on the server host that is either world-readable or readable by the MySQL server. (This implies the user can read any file in any database directory, because the server can access any of those files.) The <code class="literal">FILE</code> privilege also allows the user to create new files in any directory where the MySQL server has write access. Existing files cannot be overwritten. </p><p> The remaining privileges are used for administrative operations. Many of them can be performed by using the <span><strong class="command">mysqladmin</strong></span> program or by issuing SQL statements. The following table shows which <span><strong class="command">mysqladmin</strong></span> commands each administrative privilege allows you to execute: </p><div class="informaltable"><table border="1"><colgroup><col><col></colgroup><tbody><tr><td><span class="bold"><strong>Privilege</strong></span></td><td><span class="bold"><strong>Commands Permitted to Privilege Holders</strong></span></td></tr><tr><td><code class="literal">RELOAD</code></td><td><code class="literal">flush-hosts</code>, <code class="literal">flush-logs</code>, <code class="literal">flush-privileges</code>, <code class="literal">flush-status</code>, <code class="literal">flush-tables</code>, <code class="literal">flush-threads</code>, <code class="literal">refresh</code>, <code class="literal">reload</code></td></tr><tr><td><code class="literal">SHUTDOWN</code></td><td><code class="literal">shutdown</code></td></tr><tr><td><code class="literal">PROCESS</code></td><td><code class="literal">processlist</code></td></tr><tr><td><code class="literal">SUPER</code></td><td><code class="literal">kill</code></td></tr></tbody></table></div><p> The <code class="literal">reload</code> command tells the server to re-read the grant tables into memory. <code class="literal">flush-privileges</code> is a synonym for <code class="literal">reload</code>. The <code class="literal">refresh</code> command closes and reopens the log files and flushes all tables. The other <code class="literal">flush-<em class="replaceable"><code>xxx</code></em></code> commands perform functions similar to <code class="literal">refresh</code>, but are more specific and may be preferable in some instances. For example, if you want to flush just the log files, <code class="literal">flush-logs</code> is a better choice than <code class="literal">refresh</code>. </p><p> The <code class="literal">shutdown</code> command shuts down the server. This command can be issued only from <span><strong class="command">mysqladmin</strong></span>. There is no corresponding SQL statement. </p><p> The <code class="literal">processlist</code> command displays information about the threads executing within the server (that is, about the statements being executed by clients associated with other accounts). The <code class="literal">kill</code> command terminates server threads. You can always display or kill your own threads, but you need the <code class="literal">PROCESS</code> privilege to display threads initiated by other users and the <code class="literal">SUPER</code> privilege to kill them. See <a href="sql-syntax.html#kill" title="13.5.5.3. KILL Syntax">Section 13.5.5.3, “<code class="literal">KILL</code> Syntax”</a>. Prior to MySQL 4.0.2 when <code class="literal">SUPER</code> was introduced, the <code class="literal">PROCESS</code> privilege controls the ability to both see and terminate threads for other clients. </p><p> The <code class="literal">CREATE TEMPORARY TABLES</code> privilege allows the use of the keyword <code class="literal">TEMPORARY</code> in <code class="literal">CREATE TABLE</code> statements. </p><p> The <code class="literal">LOCK TABLES</code> privilege allows the use of explicit <code class="literal">LOCK TABLES</code> statements to lock tables for which you have the <code class="literal">SELECT</code> privilege. This includes the use of write locks, which prevents anyone else from reading the locked table. </p><p> The <code class="literal">REPLICATION CLIENT</code> privilege allows the use of <code class="literal">SHOW MASTER STATUS</code> and <code class="literal">SHOW SLAVE STATUS</code>. </p><p> The <code class="literal">REPLICATION SLAVE</code> privilege should be granted to accounts that are used by slave servers to connect to the current server as their master. Without this privilege, the slave cannot request updates that have been made to databases on the master server. </p><p> The <code class="literal">SHOW DATABASES</code> privilege allows the account to see database names by issuing the <code class="literal">SHOW DATABASE</code> statement. Accounts that do not have this privilege see only databases for which they have some privileges, and cannot use the statement at all if the server was started with the <code class="option">--skip-show-database</code> option. Note that any global privilege is a privilege for the database. </p><p> It is a good idea in general to grant to an account only those privileges that it needs. You should exercise particular caution in granting the <code class="literal">FILE</code> and administrative privileges: </p><div class="itemizedlist"><ul type="disc"><li><p> The <code class="literal">FILE</code> privilege can be abused to read into a database table any files that the MySQL server can read on the server host. This includes all world-readable files and files in the server's data directory. The table can then be accessed using <code class="literal">SELECT</code> to transfer its contents to the client host. </p></li><li><p> The <code class="literal">GRANT</code> privilege allows users to give their privileges to other users. Two users with different privileges and with the <code class="literal">GRANT</code> privilege are able to combine privileges. </p></li><li><p> The <code class="literal">ALTER</code> privilege may be used to subvert the privilege system by renaming tables. </p></li><li><p> The <code class="literal">SHUTDOWN</code> privilege can be abused to deny service to other users entirely by terminating the server. </p></li><li><p> The <code class="literal">PROCESS</code> privilege can be used to view the plain text of currently executing queries, including queries that set or change passwords. </p></li><li><p> The <code class="literal">SUPER</code> privilege can be used to terminate other clients or change how the server operates. </p></li><li><p> Privileges granted for the <code class="literal">mysql</code> database itself can be used to change passwords and other access privilege information. Passwords are stored encrypted, so a malicious user cannot simply read them to know the plain text password. However, a user with write access to the <code class="literal">user</code> table <code class="literal">Password</code> column can change an account's password, and then connect to the MySQL server using that account. </p></li></ul></div><p> There are some things that you cannot do with the MySQL privilege system: </p><div class="itemizedlist"><ul type="disc"><li><p> 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. </p></li><li><p> 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. </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="connecting"></a>5.6.4. Connecting to the MySQL Server</h3></div></div></div><a class="indexterm" name="id2790772"></a><a class="indexterm" name="id2790782"></a><a class="indexterm" name="id2790789"></a><a class="indexterm" name="id2790799"></a><p> MySQL client programs generally expect you to specify these connection parameters when you want to access a MySQL server: </p><div class="itemizedlist"><ul type="disc"><li><p> The name of the host where the MySQL server is running </p></li><li><p> Your username </p></li><li><p> Your password </p></li></ul></div><p> For example, the <span><strong class="command">mysql</strong></span> client can be started as follows from a command-line prompt (indicated here by <code class="literal">shell></code>): </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql -h <em class="replaceable"><code>host_name</code></em> -u <em class="replaceable"><code>user_name</code></em> -p<em class="replaceable"><code>your_pass</code></em></code></strong> </pre><p> Alternate forms of the <code class="option">-h</code>, <code class="option">-u</code>, and <code class="option">-p</code> options are <code class="option">--host=<em class="replaceable"><code>host_name</code></em></code>, <code class="option">--user=<em class="replaceable"><code>user_name</code></em></code>, and <code class="option">--password=<em class="replaceable"><code>your_pass</code></em></code>. Note that there is <span class="emphasis"><em>no space</em></span> between <code class="option">-p</code> or <code class="option">--password=</code> and the password following it. </p><p> If you use a <code class="option">-p</code> or <code class="option">--password</code> option but do not specify the password value, the client program prompts you to enter the password. The password is not displayed as you enter it. This is more secure than giving the password on the command line. Any user on your system may be able to see a password specified on the command line by executing a command such as <span><strong class="command">ps auxww</strong></span>. See <a href="database-administration.html#password-security" title="5.7.6. Keeping Your Password Secure">Section 5.7.6, “Keeping Your Password Secure”</a>. </p><p> MySQL client programs use default values for any connection parameter option that you do not specify: </p><div class="itemizedlist"><ul type="disc"><li><p> The default hostname is <code class="literal">localhost</code>. </p></li><li><p> The default username is <code class="literal">ODBC</code> on Windows and your Unix login name on Unix. </p></li><li><p> No password is supplied if <code class="option">-p</code> is missing. </p></li></ul></div><p> Thus, for a Unix user with a login name of <code class="literal">joe</code>, all of the following commands are equivalent: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql -h localhost -u joe</code></strong> shell> <strong class="userinput"><code>mysql -h localhost</code></strong> shell> <strong class="userinput"><code>mysql -u joe</code></strong> shell> <strong class="userinput"><code>mysql</code></strong> </pre><p> Other MySQL clients behave similarly. </p><p> 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: </p><div class="itemizedlist"><ul type="disc"><li><p> <a class="indexterm" name="id2791029"></a> You can specify connection parameters in the <code class="literal">[client]</code> section of an option file. The relevant section of the file might look like this: </p><pre class="programlisting">[client] host=<em class="replaceable"><code>host_name</code></em> user=<em class="replaceable"><code>user_name</code></em> password=<em class="replaceable"><code>your_pass</code></em> </pre><p> Option files are discussed further in <a href="using-mysql-programs.html#option-files" title="4.3.2. Using Option Files">Section 4.3.2, “Using Option Files”</a>. </p><a class="indexterm" name="id2791070"></a><a class="indexterm" name="id2791082"></a><a class="indexterm" name="id2791095"></a><a class="indexterm" name="id2791107"></a><a class="indexterm" name="id2791121"></a><a class="indexterm" name="id2791132"></a></li><li><p> You can specify some connection parameters using environment variables. The host can be specified for <span><strong class="command">mysql</strong></span> using <code class="literal">MYSQL_HOST</code>. The MySQL username can be specified using <code class="literal">USER</code> (this is for Windows and NetWare only). The password can be specified using <code class="literal">MYSQL_PWD</code>, although this is insecure; see <a href="database-administration.html#password-security" title="5.7.6. Keeping Your Password Secure">Section 5.7.6, “Keeping Your Password Secure”</a>. For a list of variables, see <a href="environment-variables.html" title="Appendix F. Environment Variables">Appendix F, <i>Environment Variables</i></a>. </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="connection-access"></a>5.6.5. Access Control, Stage 1: Connection Verification</h3></div></div></div><a class="indexterm" name="id2791195"></a><a class="indexterm" name="id2791202"></a><a class="indexterm" name="id2791209"></a><a class="indexterm" name="id2791219"></a><p> 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. </p><p> Your identity is based on two pieces of information: </p><div class="itemizedlist"><ul type="disc"><li><p> The client host from which you connect </p></li><li><p> Your MySQL username </p></li></ul></div><p> Identity checking is performed using the three <code class="literal">user</code> table scope columns (<code class="literal">Host</code>, <code class="literal">User</code>, and <code class="literal">Password</code>). The server accepts the connection only if the <code class="literal">Host</code> and <code class="literal">User</code> columns in some <code class="literal">user</code> table record match the client hostname and username, and the client supplies the password specified in that record. </p><p> <code class="literal">Host</code> values in the <code class="literal">user</code> table may be specified as follows: </p><div class="itemizedlist"><ul type="disc"><li><p> A <code class="literal">Host</code> value may be a hostname or an IP number, or <code class="literal">'localhost'</code> to indicate the local host. </p><a class="indexterm" name="id2791324"></a></li><li><p> You can use the wildcard characters ‘<code class="literal">%</code>’ and ‘<code class="literal">_</code>’ in <code class="literal">Host</code> column values. These have the same meaning as for pattern-matching operations performed with the <code class="literal">LIKE</code> operator. For example, a <code class="literal">Host</code> value of <code class="literal">'%'</code> matches any hostname, whereas a value of <code class="literal">'%.mysql.com'</code> matches any host in the <code class="literal">mysql.com</code> domain. </p></li><li><p> <a class="indexterm" name="id2791386"></a> As of MySQL 3.23, for <code class="literal">Host</code> values specified as IP numbers, you can specify a netmask indicating how many address bits to use for the network number. For example: </p><pre class="programlisting">mysql> <strong class="userinput"><code>GRANT ALL PRIVILEGES ON db.*</code></strong> -> <strong class="userinput"><code>TO david@'192.58.197.0/255.255.255.0';</code></strong> </pre><p> This allows <code class="literal">david</code> to connect from any client host having an IP number <code class="literal">client_ip</code> for which the following condition is true: </p><pre class="programlisting">client_ip & netmask = host_ip </pre><p> That is, for the <code class="literal">GRANT</code> statement just shown: </p><pre class="programlisting">client_ip & 255.255.255.0 = 192.58.197.0 </pre><p> IP numbers that satisfy this condition and can connect to the MySQL server are those that lie in the range from <code class="literal">192.58.197.0</code> to <code class="literal">192.58.197.255</code>. </p></li><li><p> Note: The netmask can only be used to tell the server to use 8, 16, 24, or 32 bits of the address, for example: </p><pre class="programlisting">192.0.0.0/255.0.0.0 (anything on the 192 class A network) 192.168.0.0/255.255.0.0 (anything on the 192.168 class B network) 192.168.1.0/255.255.255.0 (anything on the 192.168.1 class C network) 192.168.1.1 (only this specific IP) </pre><p> The following netmask (28 bits) will not work: </p><pre class="programlisting">192.168.0.1/255.255.255.240 </pre></li><li><p> A blank <code class="literal">Host</code> value in a <code class="literal">db</code> table record means that its privileges should be combined with those in the row in the <code class="literal">host</code> table that matches the client hostname. The privileges are combined using an AND (intersection) operation, not OR (union). You can find more information about the <code class="literal">host</code> table in <a href="database-administration.html#request-access" title="5.6.6. Access Control, Stage 2: Request Verification">Section 5.6.6, “Access Control, Stage 2: Request Verification”</a>. </p><p> A blank <code class="literal">Host</code> value in the other grant tables is the same as <code class="literal">'%'</code>. </p></li></ul></div><p> Because you can use IP wildcard values in the <code class="literal">Host</code> column (for example, <code class="literal">'144.155.166.%'</code> to match every host on a subnet), someone could try to exploit this capability by naming a host <code class="literal">144.155.166.somewhere.com</code>. 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 <code class="literal">1.2.foo.com</code>, its name never matches the <code class="literal">Host</code> column of the grant tables. An IP wildcard value can match only IP numbers, not hostnames. </p><a class="indexterm" name="id2791566"></a><p> In the <code class="literal">User</code> column, wildcard characters are not allowed, but you can specify a blank value, which matches any name. If the <code class="literal">user</code> table row that matches an incoming connection has a blank username, the user is considered to be an anonymous user with no name, not a user with the name that the client actually specified. This means that a blank username is used for all further access checking for the duration of the connection (that is, during Stage 2). </p><p> The <code class="literal">Password</code> column can be blank. This is not a wildcard and does not mean that any password matches. It means that the user must connect without specifying a password. </p><a class="indexterm" name="id2791602"></a><p> Non-blank <code class="literal">Password</code> values in the <code class="literal">user</code> table represent encrypted passwords. MySQL does not store passwords in plaintext form for anyone to see. Rather, the password supplied by a user who is attempting to connect is encrypted (using the <code class="literal">PASSWORD()</code> function). The encrypted password then is used during the connection process when checking whether the password is correct. (This is done without the encrypted password ever traveling over the connection.) From MySQL's point of view, the encrypted password is the <span class="emphasis"><em>real</em></span> password, so you should never give anyone access to it. In particular, <span class="emphasis"><em>do not give non-administrative users read access to tables in the <code class="literal">mysql</code> database</em></span>. </p><p> From version 4.1 on, MySQL employs a stronger authentication method that has better password protection during the connection process than in earlier versions. It is secure even if TCP/IP packets are sniffed or the <code class="literal">mysql</code> database is captured. Password encryption is discussed further in <a href="database-administration.html#password-hashing" title="5.6.9. Password Hashing in MySQL 4.1">Section 5.6.9, “Password Hashing in MySQL 4.1”</a>. </p><p> The following examples show how various combinations of <code class="literal">Host</code> and <code class="literal">User</code> values in the <code class="literal">user</code> table apply to incoming connections: </p><div class="informaltable"><table border="1"><colgroup><col><col><col></colgroup><tbody><tr><td><code class="literal">Host</code> <span class="bold"><strong>Value</strong></span></td><td><code class="literal">User</code> <span class="bold"><strong>Value</strong></span></td><td><span class="bold"><strong>Connections Matched by Entry</strong></span></td></tr><tr><td><code class="literal">'thomas.loc.gov'</code></td><td><code class="literal">'fred'</code></td><td><code class="literal">fred</code>, connecting from <code class="literal">thomas.loc.gov</code></td></tr><tr><td><code class="literal">'thomas.loc.gov'</code></td><td><code class="literal">''</code></td><td>Any user, connecting from <code class="literal">thomas.loc.gov</code></td></tr><tr><td><code class="literal">'%'</code></td><td><code class="literal">'fred'</code></td><td><code class="literal">fred</code>, connecting from any host</td></tr><tr><td><code class="literal">'%'</code></td><td><code class="literal">''</code></td><td>Any user, connecting from any host</td></tr><tr><td><code class="literal">'%.loc.gov'</code></td><td><code class="literal">'fred'</code></td><td><code class="literal">fred</code>, connecting from any host in the <code class="literal">loc.gov</code> domain</td></tr><tr><td><code class="literal">'x.y.%'</code></td><td><code class="literal">'fred'</code></td><td><code class="literal">fred</code>, connecting from <code class="literal">x.y.net</code>, <code class="literal">x.y.com</code>, <code class="literal">x.y.edu</code>, and so on. (this is probably not useful)</td></tr><tr><td><code class="literal">'144.155.166.177'</code></td><td><code class="literal">'fred'</code></td><td><code class="literal">fred</code>, connecting from the host with IP address <code class="literal">144.155.166.177</code></td></tr><tr><td><code class="literal">'144.155.166.%'</code></td><td><code class="literal">'fred'</code></td><td><code class="literal">fred</code>, connecting from any host in the <code class="literal">144.155.166</code> class C subnet</td></tr><tr><td><code class="literal">'144.155.166.0/255.255.255.0'</code></td><td><code class="literal">'fred'</code></td><td>Same as previous example</td></tr></tbody></table></div><p> It is possible for the client hostname and username of an incoming connection to match more than one row in the <code class="literal">user</code> table. The preceding set of examples demonstrates this: Several of the entries shown match a connection from <code class="literal">thomas.loc.gov</code> by <code class="literal">fred</code>. </p><p> When multiple matches are possible, the server must determine which of them to use. It resolves this issue as follows: </p><div class="itemizedlist"><ul type="disc"><li><p> Whenever the server reads the <code class="literal">user</code> table into memory, it sorts the entries. </p></li><li><p> When a client attempts to connect, the server looks through the entries in sorted order. </p></li><li><p> The server uses the first row that matches the client hostname and username. </p></li></ul></div><p> To see how this works, suppose that the <code class="literal">user</code> table looks like this: </p><pre class="programlisting">+-----------+----------+- | Host | User | ... +-----------+----------+- | % | root | ... | % | jeffrey | ... | localhost | root | ... | localhost | | ... +-----------+----------+- </pre><p> When the server reads in the table, it orders the entries with the most-specific <code class="literal">Host</code> values first. Literal hostnames and IP numbers are the most specific. The pattern <code class="literal">'%'</code> means “<span class="quote">any host</span>” and is least specific. Entries with the same <code class="literal">Host</code> value are ordered with the most-specific <code class="literal">User</code> values first (a blank <code class="literal">User</code> value means “<span class="quote">any user</span>” and is least specific). For the <code class="literal">user</code> table just shown, the result after sorting looks like this: </p><pre class="programlisting">+-----------+----------+- | Host | User | ... +-----------+----------+- | localhost | root | ... | localhost | | ... | % | jeffrey | ... | % | root | ... +-----------+----------+- </pre><a class="indexterm" name="id2792043"></a><a class="indexterm" name="id2792053"></a><a class="indexterm" name="id2792064"></a><p> When a client attempts to connect, the server looks through the sorted entries and uses the first match found. For a connection from <code class="literal">localhost</code> by <code class="literal">jeffrey</code>, two of the entries in the table match: the one with <code class="literal">Host</code> and <code class="literal">User</code> values of <code class="literal">'localhost'</code> and <code class="literal">''</code>, and the one with values of <code class="literal">'%'</code> and <code class="literal">'jeffrey'</code>. The <code class="literal">'localhost'</code> row appears first in sorted order, so that is the one the server uses. </p><p> Here is another example. Suppose that the <code class="literal">user</code> table looks like this: </p><pre class="programlisting">+----------------+----------+- | Host | User | ... +----------------+----------+- | % | jeffrey | ... | thomas.loc.gov | | ... +----------------+----------+- </pre><p> The sorted table looks like this: </p><pre class="programlisting">+----------------+----------+- | Host | User | ... +----------------+----------+- | thomas.loc.gov | | ... | % | jeffrey | ... +----------------+----------+- </pre><p> A connection by <code class="literal">jeffrey</code> from <code class="literal">thomas.loc.gov</code> is matched by the first row, whereas a connection by <code class="literal">jeffrey</code> from <code class="literal">whitehouse.gov</code> is matched by the second. </p><p> It is a common misconception to think that, for a given username, all entries that explicitly name that user are used first when the server attempts to find a match for the connection. This is simply not true. The previous example illustrates this, where a connection from <code class="literal">thomas.loc.gov</code> by <code class="literal">jeffrey</code> is first matched not by the row containing <code class="literal">'jeffrey'</code> as the <code class="literal">User</code> column value, but by the row with no username. As a result, <code class="literal">jeffrey</code> is authenticated as an anonymous user, even though he specified a username when connecting. </p><p> If you are able to connect to the server, but your privileges are not what you expect, you probably are being authenticated as some other account. To find out what account the server used to authenticate you, use the <code class="literal">CURRENT_USER()</code> function. It returns a value in <code class="literal"><em class="replaceable"><code>user_name</code></em>@<em class="replaceable"><code>host_name</code></em></code> format that indicates the <code class="literal">User</code> and <code class="literal">Host</code> values from the matching <code class="literal">user</code> table record. Suppose that <code class="literal">jeffrey</code> connects and issues the following query: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SELECT CURRENT_USER();</code></strong> +----------------+ | CURRENT_USER() | +----------------+ | @localhost | +----------------+ </pre><p> The result shown here indicates that the matching <code class="literal">user</code> table row had a blank <code class="literal">User</code> column value. In other words, the server is treating <code class="literal">jeffrey</code> as an anonymous user. </p><p> The <code class="literal">CURRENT_USER()</code> function is available as of MySQL 4.0.6. See <a href="functions.html#information-functions" title="12.9.3. Information Functions">Section 12.9.3, “Information Functions”</a>. Another way to diagnose authentication problems is to print out the <code class="literal">user</code> table and sort it by hand to see where the first match is being made. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="request-access"></a>5.6.6. Access Control, Stage 2: Request Verification</h3></div></div></div><p> Once you establish a connection, the server enters Stage 2 of access control. For each request that comes in on the connection, the server determines what operation you want to perform, then checks whether you have sufficient privileges to do so. This is where the privilege columns in the grant tables come into play. These privileges can come from any of the <code class="literal">user</code>, <code class="literal">db</code>, <code class="literal">host</code>, <code class="literal">tables_priv</code>, or <code class="literal">columns_priv</code> tables. (You may find it helpful to refer to <a href="database-administration.html#privileges" title="5.6.2. How the Privilege System Works">Section 5.6.2, “How the Privilege System Works”</a>, which lists the columns present in each of the grant tables.) </p><p> The <code class="literal">user</code> 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 <code class="literal">user</code> table grants you the <code class="literal">DELETE</code> privilege, you can delete rows from any table in any database on the server host! In other words, <code class="literal">user</code> table privileges are superuser privileges. It is wise to grant privileges in the <code class="literal">user</code> table only to superusers such as database administrators. For other users, you should leave the privileges in the <code class="literal">user</code> table set to <code class="literal">'N'</code> and grant privileges at more specific levels only. You can grant privileges for particular databases, tables, or columns. </p><a class="indexterm" name="id2792364"></a><a class="indexterm" name="id2792371"></a><a class="indexterm" name="id2792385"></a><p> The <code class="literal">db</code> and <code class="literal">host</code> tables grant database-specific privileges. Values in the scope columns of these tables can take the following forms: </p><div class="itemizedlist"><ul type="disc"><li><p> The wildcard characters ‘<code class="literal">%</code>’ and ‘<code class="literal">_</code>’ can be used in the <code class="literal">Host</code> and <code class="literal">Db</code> columns of either table. These have the same meaning as for pattern-matching operations performed with the <code class="literal">LIKE</code> operator. If you want to use either character literally when granting privileges, you must escape it with a backslash. For example, to include ‘<code class="literal">_</code>’ character as part of a database name, specify it as ‘<code class="literal">\_</code>’ in the <code class="literal">GRANT</code> statement. </p></li><li><p> A <code class="literal">'%'</code> <code class="literal">Host</code> value in the <code class="literal">db</code> table means “<span class="quote">any host.</span>” A blank <code class="literal">Host</code> value in the <code class="literal">db</code> table means “<span class="quote">consult the <code class="literal">host</code> table for further information</span>” (a process that is described later in this section). </p></li><li><p> A <code class="literal">'%'</code> or blank <code class="literal">Host</code> value in the <code class="literal">host</code> table means “<span class="quote">any host.</span>” </p></li><li><p> A <code class="literal">'%'</code> or blank <code class="literal">Db</code> value in either table means “<span class="quote">any database.</span>” </p></li><li><p> A blank <code class="literal">User</code> value in either table matches the anonymous user. </p></li></ul></div><a class="indexterm" name="id2792552"></a><a class="indexterm" name="id2792562"></a><a class="indexterm" name="id2792572"></a><a class="indexterm" name="id2792585"></a><p> The server reads in and sorts the <code class="literal">db</code> and <code class="literal">host</code> tables at the same time that it reads the <code class="literal">user</code> table. The server sorts the <code class="literal">db</code> table based on the <code class="literal">Host</code>, <code class="literal">Db</code>, and <code class="literal">User</code> scope columns, and sorts the <code class="literal">host</code> table based on the <code class="literal">Host</code> and <code class="literal">Db</code> scope columns. As with the <code class="literal">user</code> 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. </p><a class="indexterm" name="id2792647"></a><a class="indexterm" name="id2792661"></a><p> The <code class="literal">tables_priv</code> and <code class="literal">columns_priv</code> tables grant table-specific and column-specific privileges. Values in the scope columns of these tables can take the following form: </p><div class="itemizedlist"><ul type="disc"><li><p> The wildcard characters ‘<code class="literal">%</code>’ and ‘<code class="literal">_</code>’ can be used in the <code class="literal">Host</code> column of either table. These have the same meaning as for pattern-matching operations performed with the <code class="literal">LIKE</code> operator. </p></li><li><p> A <code class="literal">'%'</code> or blank <code class="literal">Host</code> value in either table means “<span class="quote">any host.</span>” </p></li><li><p> The <code class="literal">Db</code>, <code class="literal">Table_name</code>, and <code class="literal">Column_name</code> columns cannot contain wildcards or be blank in either table. </p></li></ul></div><p> The server sorts the <code class="literal">tables_priv</code> and <code class="literal">columns_priv</code> tables based on the <code class="literal">Host</code>, <code class="literal">Db</code>, and <code class="literal">User</code> columns. This is similar to <code class="literal">db</code> table sorting, but simpler because only the <code class="literal">Host</code> column can contain wildcards. </p><p> The request verification process is described here. (If you are familiar with the access-checking source code, you may notice that the description here differs slightly from the algorithm used in the code. The description is equivalent to what the code actually does; it differs only to make the explanation simpler.) </p><p> For requests that require administrative privileges such as <code class="literal">SHUTDOWN</code> or <code class="literal">RELOAD</code>, the server checks only the <code class="literal">user</code> table row because that is the only table that specifies administrative privileges. Access is granted if the row allows the requested operation and denied otherwise. For example, if you want to execute <span><strong class="command">mysqladmin shutdown</strong></span> but your <code class="literal">user</code> table row does not grant the <code class="literal">SHUTDOWN</code> privilege to you, the server denies access without even checking the <code class="literal">db</code> or <code class="literal">host</code> tables. (They contain no <code class="literal">Shutdown_priv</code> column, so there is no need to do so.) </p><p> For database-related requests (<code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, and so on), the server first checks the user's global (superuser) privileges by looking in the <code class="literal">user</code> table row. If the row allows the requested operation, access is granted. If the global privileges in the <code class="literal">user</code> table are insufficient, the server determines the user's database-specific privileges by checking the <code class="literal">db</code> and <code class="literal">host</code> tables: </p><div class="orderedlist"><ol type="1"><li><p> The server looks in the <code class="literal">db</code> table for a match on the <code class="literal">Host</code>, <code class="literal">Db</code>, and <code class="literal">User</code> columns. The <code class="literal">Host</code> and <code class="literal">User</code> columns are matched to the connecting user's hostname and MySQL username. The <code class="literal">Db</code> column is matched to the database that the user wants to access. If there is no row for the <code class="literal">Host</code> and <code class="literal">User</code>, access is denied. </p></li><li><p> If there is a matching <code class="literal">db</code> table row and its <code class="literal">Host</code> column is not blank, that row defines the user's database-specific privileges. </p></li><li><p> If the matching <code class="literal">db</code> table row's <code class="literal">Host</code> column is blank, it signifies that the <code class="literal">host</code> table enumerates which hosts should be allowed access to the database. In this case, a further lookup is done in the <code class="literal">host</code> table to find a match on the <code class="literal">Host</code> and <code class="literal">Db</code> columns. If no <code class="literal">host</code> table row matches, access is denied. If there is a match, the user's database-specific privileges are computed as the intersection (<span class="emphasis"><em>not</em></span> the union!) of the privileges in the <code class="literal">db</code> and <code class="literal">host</code> table entries; that is, the privileges that are <code class="literal">'Y'</code> in both entries. (This way you can grant general privileges in the <code class="literal">db</code> table row and then selectively restrict them on a host-by-host basis using the <code class="literal">host</code> table entries.) </p></li></ol></div><p> After determining the database-specific privileges granted by the <code class="literal">db</code> and <code class="literal">host</code> table entries, the server adds them to the global privileges granted by the <code class="literal">user</code> table. If the result allows the requested operation, access is granted. Otherwise, the server successively checks the user's table and column privileges in the <code class="literal">tables_priv</code> and <code class="literal">columns_priv</code> tables, adds those to the user's privileges, and allows or denies access based on the result. </p><p> Expressed in boolean terms, the preceding description of how a user's privileges are calculated may be summarized like this: </p><pre class="programlisting">global privileges OR (database privileges AND host privileges) OR table privileges OR column privileges </pre><p> It may not be apparent why, if the global <code class="literal">user</code> row privileges are initially found to be insufficient for the requested operation, the server adds those privileges to the database, table, and column privileges later. The reason is that a request might require more than one type of privilege. For example, if you execute an <code class="literal">INSERT INTO ... SELECT</code> statement, you need both the <code class="literal">INSERT</code> and the <code class="literal">SELECT</code> privileges. Your privileges might be such that the <code class="literal">user</code> table row grants one privilege and the <code class="literal">db</code> table row grants the other. In this case, you have the necessary privileges to perform the request, but the server cannot tell that from either table by itself; the privileges granted by the entries in both tables must be combined. </p><a class="indexterm" name="id2793082"></a><a class="indexterm" name="id2793091"></a><p> The <code class="literal">host</code> table is not affected by the <code class="literal">GRANT</code> or <code class="literal">REVOKE</code> statements, so it is unused in most MySQL installations. If you modify it directly, you can use it for some specialized purposes, such as to maintain a list of secure servers. For example, at TcX, the <code class="literal">host</code> table contains a list of all machines on the local network. These are granted all privileges. </p><p> You can also use the <code class="literal">host</code> table to indicate hosts that are <span class="emphasis"><em>not</em></span> secure. Suppose that you have a machine <code class="literal">public.your.domain</code> 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 <code class="literal">host</code> table entries like this: </p><pre class="programlisting">+--------------------+----+- | Host | Db | ... +--------------------+----+- | public.your.domain | % | ... (all privileges set to 'N') | %.your.domain | % | ... (all privileges set to 'Y') +--------------------+----+- </pre><a class="indexterm" name="id2793157"></a><a class="indexterm" name="id2793168"></a><a class="indexterm" name="id2793174"></a><a class="indexterm" name="id2793185"></a><p> Naturally, you should always test your entries in the grant tables (for example, by using <code class="literal">SHOW GRANTS</code> or <span><strong class="command">mysqlaccess</strong></span>) to make sure that your access privileges are actually set up the way you think they are. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="privilege-changes"></a>5.6.7. When Privilege Changes Take Effect</h3></div></div></div><p> When <span><strong class="command">mysqld</strong></span> starts, all grant table contents are read into memory and become effective for access control at that point. </p><p> When the server reloads the grant tables, privileges for existing client connections are affected as follows: </p><div class="itemizedlist"><ul type="disc"><li><p> Table and column privilege changes take effect with the client's next request. </p></li><li><p> Database privilege changes take effect at the next <code class="literal">USE <em class="replaceable"><code>db_name</code></em></code> statement. </p></li><li><p> Changes to global privileges and passwords take effect the next time the client connects. </p></li></ul></div><p> If you modify the grant tables using <code class="literal">GRANT</code>, <code class="literal">REVOKE</code>, or <code class="literal">SET PASSWORD</code>, the server notices these changes and reloads the grant tables into memory again immediately. </p><p> If you modify the grant tables directly using statements such as <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, or <code class="literal">DELETE</code>, your changes have no effect on privilege checking until you either restart the server or tell it to reload the tables. To reload the grant tables manually, issue a <code class="literal">FLUSH PRIVILEGES</code> statement or execute a <span><strong class="command">mysqladmin flush-privileges</strong></span> or <span><strong class="command">mysqladmin reload</strong></span> command. </p><p> If you change the grant tables directly but forget to reload them, your changes have <span class="emphasis"><em>no effect</em></span> until you restart the server. This may leave you wondering why your changes do not seem to make any difference! </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="access-denied"></a>5.6.8. Causes of <code class="literal">Access denied</code> Errors</h3></div></div></div><p> If you encounter problems when you try to connect to the MySQL server, the following items describe some courses of action you can take to correct the problem. </p><div class="itemizedlist"><ul type="disc"><li><p> Make sure that the server is running. If it is not running, you cannot connect to it. For example, if you attempt to connect to the server and see a message such as one of those following, one cause might be that the server is not running: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql</code></strong> ERROR 2003: cannot connect to MySQL server on '<em class="replaceable"><code>host_name</code></em>' (111) shell> <strong class="userinput"><code>mysql</code></strong> ERROR 2002: cannot connect to local MySQL server through socket '/tmp/mysql.sock' (111) </pre><p> It might also be that the server is running, but you are trying to connect using a TCP/IP port, named pipe, or Unix socket file different from those on which the server is listening. To correct this when you invoke a client program, specify a <code class="option">--port</code> option to indicate the proper port, or a <code class="option">--socket</code> option to indicate the proper named pipe or Unix socket file. To find out where the socket file is, you can do: </p><pre class="programlisting">shell> <strong class="userinput"><code>netstat -ln | grep mysql</code></strong> </pre></li><li><p> The grant tables must be properly set up so that the server can use them for access control. For some distribution types (such as binary distributions on Windows, or RPM distributions on Linux), the installation process initializes the <code class="literal">mysql</code> database containing the grant tables. For distributions that do not do this, you should initialize the grant tables manually by running the <span><strong class="command">mysql_install_db</strong></span> script. For details, see <a href="installing.html#unix-post-installation" title="2.9.2. Unix Post-Installation Procedures">Section 2.9.2, “Unix Post-Installation Procedures”</a>. </p><p> One way to determine whether you need to initialize the grant tables is to look for a <code class="filename">mysql</code> directory under the data directory. (The data directory normally is named <code class="filename">data</code> or <code class="filename">var</code> and is located under your MySQL installation directory.) Make sure that you have a file named <code class="filename">user.MYD</code> in the <code class="filename">mysql</code> database directory. If you do not, execute the <span><strong class="command">mysql_install_db</strong></span> script. After running this script and starting the server, test the initial privileges by executing this command: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql -u root test</code></strong> </pre><p> The server should let you connect without error. </p></li><li><p> After a fresh installation, you should connect to the server and set up your users and their access permissions: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql -u root mysql</code></strong> </pre><p> The server should let you connect because the MySQL <code class="literal">root</code> user has no password initially. That is also a security risk, so setting the password for the <code class="literal">root</code> accounts is something you should do while you are setting up your other MySQL users. For instructions on setting the initial passwords, see <a href="installing.html#default-privileges" title="2.9.3. Securing the Initial MySQL Accounts">Section 2.9.3, “Securing the Initial MySQL Accounts”</a>. </p></li><li><p> <a class="indexterm" name="id2793526"></a> If you have updated an existing MySQL installation to a newer version, did you run the <span><strong class="command">mysql_fix_privilege_tables</strong></span> script? If not, do so. The structure of the grant tables changes occasionally when new capabilities are added, so after an upgrade you should always make sure that your tables have the current structure. For instructions, see <a href="installing.html#upgrading-grant-tables" title="2.10.3. Upgrading the Grant Tables">Section 2.10.3, “Upgrading the Grant Tables”</a>. </p></li><li><p> If a client program receives the following error message when it tries to connect, it means that the server expects passwords in a newer format than the client is capable of generating: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql</code></strong> Client does not support authentication protocol requested by server; consider upgrading MySQL client </pre><p> For information on how to deal with this, see <a href="database-administration.html#password-hashing" title="5.6.9. Password Hashing in MySQL 4.1">Section 5.6.9, “Password Hashing in MySQL 4.1”</a> and <a href="problems.html#old-client" title="A.2.3. Client does not support authentication protocol">Section A.2.3, “<code class="literal">Client does not support authentication protocol</code>”</a>. </p></li><li><p> If you try to connect as <code class="literal">root</code> and get the following error, it means that you do not have an row in the <code class="literal">user</code> table with a <code class="literal">User</code> column value of <code class="literal">'root'</code> and that <span><strong class="command">mysqld</strong></span> cannot resolve the hostname for your client: </p><pre class="programlisting">Access denied for user ''@'unknown' to database mysql </pre><p> In this case, you must restart the server with the <code class="option">--skip-grant-tables</code> option and edit your <code class="filename">/etc/hosts</code> or <code class="filename">\<em class="replaceable"><code>%WINDIR%</code></em>\SYSTEM32\hosts</code> file to add an entry for your host. </p></li><li><p> <a class="indexterm" name="id2793644"></a> <a class="indexterm" name="id2793651"></a> <a class="indexterm" name="id2793658"></a> <a class="indexterm" name="id2793665"></a> Remember that client programs use connection parameters specified in option files or environment variables. If a client program seems to be sending incorrect default connection parameters when you do not specify them on the command line, check your environment and any applicable option files. For example, if you get <code class="literal">Access denied</code> when you run a client without any options, make sure that you haven't specified an old password in any of your option files. </p><p> You can suppress the use of option files by a client program by invoking it with the <code class="option">--no-defaults</code> option. For example: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysqladmin --no-defaults -u root version</code></strong> </pre><p> The option files that clients use are listed in <a href="using-mysql-programs.html#option-files" title="4.3.2. Using Option Files">Section 4.3.2, “Using Option Files”</a>. Environment variables are listed in <a href="environment-variables.html" title="Appendix F. Environment Variables">Appendix F, <i>Environment Variables</i></a>. </p></li><li><p> If you get the following error, it means that you are using an incorrect <code class="literal">root</code> password: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysqladmin -u root -p<em class="replaceable"><code>xxxx</code></em> ver</code></strong> Access denied for user 'root'@'localhost' (using password: YES) </pre><p> If the preceding error occurs even when you haven't specified a password, it means that you have an incorrect password listed in some option file. Try the <code class="option">--no-defaults</code> option as described in the previous item. </p><p> For information on changing passwords, see <a href="database-administration.html#passwords" title="5.7.5. Assigning Account Passwords">Section 5.7.5, “Assigning Account Passwords”</a>. </p><p> If you have lost or forgotten the <code class="literal">root</code> password, you can restart <span><strong class="command">mysqld</strong></span> with <code class="option">--skip-grant-tables</code> to change the password. See <a href="problems.html#resetting-permissions" title="A.4.1. How to Reset the Root Password">Section A.4.1, “How to Reset the Root Password”</a>. </p></li><li><p> If you change a password by using <code class="literal">SET PASSWORD</code>, <code class="literal">INSERT</code>, or <code class="literal">UPDATE</code>, you must encrypt the password using the <code class="literal">PASSWORD()</code> function. If you do not use <code class="literal">PASSWORD()</code> for these statements, the password does not work. For example, the following statement sets a password, but fails to encrypt it, so the user is not able to connect afterward: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SET PASSWORD FOR 'abe'@'<em class="replaceable"><code>host_name</code></em>' = 'eagle';</code></strong> </pre><p> Instead, set the password like this: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SET PASSWORD FOR 'abe'@'<em class="replaceable"><code>host_name</code></em>' = PASSWORD('eagle');</code></strong> </pre><p> The <code class="literal">PASSWORD()</code> function is unnecessary when you specify a password using the <code class="literal">GRANT</code> statement or the <span><strong class="command">mysqladmin password</strong></span> command, both of which automatically use <code class="literal">PASSWORD()</code> to encrypt the password. See <a href="database-administration.html#passwords" title="5.7.5. Assigning Account Passwords">Section 5.7.5, “Assigning Account Passwords”</a>. </p></li><li><p> <code class="literal">localhost</code> 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 <code class="literal">localhost</code> on Unix systems do not work if you are using a MySQL version older than 3.23.27 that uses MIT-pthreads: <code class="literal">localhost</code> connections are made using Unix socket files, which were not supported by MIT-pthreads at that time. </p><p> To avoid this problem on such systems, you can use a <code class="option">--host=127.0.0.1</code> option to name the server host explicitly. This will make a TCP/IP connection to the local <span><strong class="command">mysqld</strong></span> server. You can also use TCP/IP by specifying a <code class="option">--host</code> option that uses the actual hostname of the local host. In this case, the hostname must be specified in a <code class="literal">user</code> table row on the server host, even though you are running the client program on the same host as the server. </p></li><li><p> If you get an <code class="literal">Access denied</code> error when trying to connect to the database with <code class="literal">mysql -u user_name</code>, you may have a problem with the <code class="literal">user</code> table. Check this by executing <code class="literal">mysql -u root mysql</code> and issuing this SQL statement: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SELECT * FROM user;</code></strong> </pre><p> The result should include an row with the <code class="literal">Host</code> and <code class="literal">User</code> columns matching your computer's hostname and your MySQL username. </p></li><li><p> The <code class="literal">Access denied</code> error message tells you who you are trying to log in as, the client host from which you are trying to connect, and whether or not you were using a password. Normally, you should have one row in the <code class="literal">user</code> 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 <code class="literal">using password: NO</code>, it means that you tried to log in without a password. </p></li><li><p> If the following error occurs when you try to connect from a host other than the one on which the MySQL server is running, it means that there is no row in the <code class="literal">user</code> table with a <code class="literal">Host</code> value that matches the client host: </p><pre class="programlisting">Host ... is not allowed to connect to this MySQL server </pre><p> You can fix this by setting up an account for the combination of client hostname and username that you are using when trying to connect. </p><p> If you do not know the IP number or hostname of the machine from which you are connecting, you should put a row with <code class="literal">'%'</code> as the <code class="literal">Host</code> column value in the <code class="literal">user</code> table. After trying to connect from the client machine, use a <code class="literal">SELECT USER()</code> query to see how you really did connect. (Then change the <code class="literal">'%'</code> in the <code class="literal">user</code> table row to the actual hostname that shows up in the log. Otherwise, your system is left insecure because it allows connections from any host for the given username.) </p><p> (Note that if you are running a version of MySQL older than 3.23.11, the output from <code class="literal">USER()</code> does not include the hostname. In this case, you must restart the server with the <code class="option">--log</code> option, then obtain the hostname from the log.) </p><p> On Linux, another reason that this error might occur is that you are using a binary MySQL version that is compiled with a different version of the <code class="literal">glibc</code> library than the one you are using. In this case, you should either upgrade your operating system or <code class="literal">glibc</code>, or download a source distribution of MySQL version and compile it yourself. A source RPM is normally trivial to compile and install, so this is not a big problem. </p></li><li><p> If you specify a hostname when trying to connect, but get an error message where the hostname is not shown or is an IP number, it means that the MySQL server got an error when trying to resolve the IP number of the client host to a name: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysqladmin -u root -p<em class="replaceable"><code>xxxx</code></em> -h <em class="replaceable"><code>some-hostname</code></em> ver</code></strong> Access denied for user 'root'@'' (using password: YES) </pre><p> This indicates a DNS problem. To fix it, execute <span><strong class="command">mysqladmin flush-hosts</strong></span> to reset the internal DNS hostname cache. See <a href="optimization.html#dns" title="7.5.5. How MySQL Uses DNS">Section 7.5.5, “How MySQL Uses DNS”</a>. </p><p> Some permanent solutions are: </p><div class="itemizedlist"><ul type="circle"><li><p> Find out what is wrong with your DNS server and fix it. </p></li><li><p> Specify IP numbers rather than hostnames in the MySQL grant tables. </p></li><li><p> Put an entry for the client machine name in <code class="literal">/etc/hosts</code>. </p></li><li><p> Start <span><strong class="command">mysqld</strong></span> with the <code class="option">--skip-name-resolve</code> option. </p></li><li><p> Start <span><strong class="command">mysqld</strong></span> with the <code class="option">--skip-host-cache</code> option. </p></li><li><p> On Unix, if you are running the server and the client on the same machine, connect to <code class="literal">localhost</code>. Unix connections to <code class="literal">localhost</code> use a Unix socket file rather than TCP/IP. </p></li><li><p> On Windows, if you are running the server and the client on the same machine and the server supports named pipe connections, connect to the hostname <code class="literal">.</code> (period). Connections to <code class="literal">.</code> use a named pipe rather than TCP/IP. </p></li></ul></div></li><li><p> If <code class="literal">mysql -u root test</code> works but <code class="literal">mysql -h <em class="replaceable"><code>your_hostname</code></em> -u root test</code> results in <code class="literal">Access denied</code> (where <em class="replaceable"><code>your_hostname</code></em> is the actual hostname of the local host), you may not have the correct name for your host in the <code class="literal">user</code> table. A common problem here is that the <code class="literal">Host</code> value in the <code class="literal">user</code> table row specifies an unqualified hostname, but your system's name resolution routines return a fully qualified domain name (or vice versa). For example, if you have an entry with host <code class="literal">'tcx'</code> in the <code class="literal">user</code> table, but your DNS tells MySQL that your hostname is <code class="literal">'tcx.subnet.se'</code>, the entry does not work. Try adding an entry to the <code class="literal">user</code> table that contains the IP number of your host as the <code class="literal">Host</code> column value. (Alternatively, you could add an entry to the <code class="literal">user</code> table with a <code class="literal">Host</code> value that contains a wildcard; for example, <code class="literal">'tcx.%'</code>. However, use of hostnames ending with ‘<code class="literal">%</code>’ is insecure and is <span class="emphasis"><em>not</em></span> recommended.) </p></li><li><p> If <code class="literal">mysql -u <em class="replaceable"><code>user_name</code></em> test</code> works but <code class="literal">mysql -u <em class="replaceable"><code>user_name</code></em> <em class="replaceable"><code>other_db_name</code></em></code> does not, you have not granted database access for <em class="replaceable"><code>other_db_name</code></em> to the given user. </p></li><li><p> If <code class="literal">mysql -u <em class="replaceable"><code>user_name</code></em></code> works when executed on the server host, but <code class="literal">mysql -h <em class="replaceable"><code>host_name</code></em> -u <em class="replaceable"><code>user_name</code></em></code> does not work when executed on a remote client host, you have not enabled access to the server for the given username from the remote host. </p></li><li><p> If you cannot figure out why you get <code class="literal">Access denied</code>, remove from the <code class="literal">user</code> table all entries that have <code class="literal">Host</code> values containing wildcards (entries that contain ‘<code class="literal">%</code>’ or ‘<code class="literal">_</code>’). A very common error is to insert a new entry with <code class="literal">Host</code>=<code class="literal">'%'</code> and <code class="literal">User</code>=<code class="literal">'<em class="replaceable"><code>some_user</code></em>'</code>, thinking that this allows you to specify <code class="literal">localhost</code> to connect from the same machine. The reason that this does not work is that the default privileges include an entry with <code class="literal">Host</code>=<code class="literal">'localhost'</code> and <code class="literal">User</code>=<code class="literal">''</code>. Because that entry has a <code class="literal">Host</code> value <code class="literal">'localhost'</code> that is more specific than <code class="literal">'%'</code>, it is used in preference to the new entry when connecting from <code class="literal">localhost</code>! The correct procedure is to insert a second entry with <code class="literal">Host</code>=<code class="literal">'localhost'</code> and <code class="literal">User</code>=<code class="literal">'<em class="replaceable"><code>some_user</code></em>'</code>, or to delete the entry with <code class="literal">Host</code>=<code class="literal">'localhost'</code> and <code class="literal">User</code>=<code class="literal">''</code>. After deleting the entry, remember to issue a <code class="literal">FLUSH PRIVILEGES</code> statement to reload the grant tables. </p></li><li><p> If you get the following error, you may have a problem with the <code class="literal">db</code> or <code class="literal">host</code> table: </p><pre class="programlisting">Access to database denied </pre><p> If the entry selected from the <code class="literal">db</code> table has an empty value in the <code class="literal">Host</code> column, make sure that there are one or more corresponding entries in the <code class="literal">host</code> table specifying which hosts the <code class="literal">db</code> table entry applies to. </p></li><li><p> If you are able to connect to the MySQL server, but get an <code class="literal">Access denied</code> message whenever you issue a <code class="literal">SELECT ... INTO OUTFILE</code> or <code class="literal">LOAD DATA INFILE</code> statement, your entry in the <code class="literal">user</code> table does not have the <code class="literal">FILE</code> privilege enabled. </p></li><li><p> If you change the grant tables directly (for example, by using <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, or <code class="literal">DELETE</code> statements) and your changes seem to be ignored, remember that you must execute a <code class="literal">FLUSH PRIVILEGES</code> statement or a <span><strong class="command">mysqladmin flush-privileges</strong></span> command to cause the server to re-read the privilege tables. Otherwise, your changes have no effect until the next time the server is restarted. Remember that after you change the <code class="literal">root</code> password with an <code class="literal">UPDATE</code> command, you will not need to specify the new password until after you flush the privileges, because the server will not know you've changed the password yet! </p></li><li><p> If your privileges seem to have changed in the middle of a session, it may be that a MySQL administrator has changed them. Reloading the grant tables affects new client connections, but it also affects existing connections as indicated in <a href="database-administration.html#privilege-changes" title="5.6.7. When Privilege Changes Take Effect">Section 5.6.7, “When Privilege Changes Take Effect”</a>. </p></li><li><p> If you have access problems with a Perl, PHP, Python, or ODBC program, try to connect to the server with <code class="literal">mysql -u <em class="replaceable"><code>user_name</code></em> <em class="replaceable"><code>db_name</code></em></code> or <code class="literal">mysql -u <em class="replaceable"><code>user_name</code></em> -p<em class="replaceable"><code>your_pass</code></em> <em class="replaceable"><code>db_name</code></em></code>. If you are able to connect using the <span><strong class="command">mysql</strong></span> client, the problem lies with your program, not with the access privileges. (There is no space between <code class="option">-p</code> and the password; you can also use the <code class="option">--password=<em class="replaceable"><code>your_pass</code></em></code> syntax to specify the password. If you use the <code class="option">-p</code> option alone, MySQL prompts you for the password.) </p></li><li><p> For testing, start the <span><strong class="command">mysqld</strong></span> server with the <code class="option">--skip-grant-tables</code> option. Then you can change the MySQL grant tables and use the <span><strong class="command">mysqlaccess</strong></span> script to check whether your modifications have the desired effect. When you are satisfied with your changes, execute <span><strong class="command">mysqladmin flush-privileges</strong></span> to tell the <span><strong class="command">mysqld</strong></span> server to start using the new grant tables. (Reloading the grant tables overrides the <code class="option">--skip-grant-tables</code> option. This allows you to tell the server to begin using the grant tables again without stopping and restarting it.) </p></li><li><p> If everything else fails, start the <span><strong class="command">mysqld</strong></span> server with a debugging option (for example, <code class="option">--debug=d,general,query</code>). This prints host and user information about attempted connections, as well as information about each command issued. See <a href="porting.html#making-trace-files" title="E.1.2. Creating Trace Files">Section E.1.2, “Creating Trace Files”</a>. </p></li><li><p> 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 <span><strong class="command">mysqldump mysql</strong></span> command. As always, post your problem using the <span><strong class="command">mysqlbug</strong></span> script. See <a href="introduction.html#bug-reports" title="1.7.1.3. How to Report Bugs or Problems">Section 1.7.1.3, “How to Report Bugs or Problems”</a>. In some cases, you may need to restart <span><strong class="command">mysqld</strong></span> with <code class="option">--skip-grant-tables</code> to run <span><strong class="command">mysqldump</strong></span>. </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="password-hashing"></a>5.6.9. Password Hashing in MySQL 4.1</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="database-administration.html#application-password-use">5.6.9.1. Implications of Password Hashing Changes for Application Programs</a></span></dt><dt><span class="section"><a href="database-administration.html#password-hashing-4-1-0">5.6.9.2. Password Hashing in MySQL 4.1.0</a></span></dt></dl></div><p> MySQL user accounts are listed in the <code class="literal">user</code> table of the <code class="literal">mysql</code> database. Each MySQL account is assigned a password, although what is stored in the <code class="literal">Password</code> column of the <code class="literal">user</code> table is not the plaintext version of the password, but a hash value computed from it. Password hash values are computed by the <code class="literal">PASSWORD()</code> function. </p><p> MySQL uses passwords in two phases of client/server communication: </p><div class="itemizedlist"><ul type="disc"><li><p> When a client attempts to connect to the server, there is an initial authentication step in which the client must present a password that has a hash value matching the hash value stored in the <code class="literal">user</code> table for the account that the client wants to use. </p></li><li><p> After the client connects, it can (if it has sufficient privileges) set or change the password hashes for accounts listed in the <code class="literal">user</code> table. The client can do this by using the <code class="literal">PASSWORD()</code> function to generate a password hash, or by using the <code class="literal">GRANT</code> or <code class="literal">SET PASSWORD</code> statements. </p></li></ul></div><p> In other words, the server <span class="emphasis"><em>uses</em></span> hash values during authentication when a client first attempts to connect. The server <span class="emphasis"><em>generates</em></span> hash values if a connected client invokes the <code class="literal">PASSWORD()</code> function or uses a <code class="literal">GRANT</code> or <code class="literal">SET PASSWORD</code> statement to set or change a password. </p><p> The password hashing mechanism was updated in MySQL 4.1 to provide better security and to reduce the risk of passwords being intercepted. However, this new mechanism is understood only by the 4.1 server and 4.1 clients, which can result in some compatibility problems. A 4.1 client can connect to a pre-4.1 server, because the client understands both the old and new password hashing mechanisms. However, a pre-4.1 client that attempts to connect to a 4.1 server may run into difficulties. For example, a 4.0 <span><strong class="command">mysql</strong></span> client that attempts to connect to a 4.1 server may fail with the following error message: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql -h localhost -u root</code></strong> Client does not support authentication protocol requested by server; consider upgrading MySQL client </pre><p> Another common example of this occurs when trying to use the older PHP <span class="bold"><strong>mysql</strong></span> extension after upgrading to MySQL 4.1 or newer. (See <a href="apis.html#php-problems" title="18.3.1. Common Problems with MySQL and PHP">Section 18.3.1, “Common Problems with MySQL and PHP”</a>.) </p><p> The following discussion describes the differences between the old and new password mechanisms, and what you should do if you upgrade your server to 4.1 but need to maintain backward compatibility with pre-4.1 clients. Additional information can be found in <a href="problems.html#old-client" title="A.2.3. Client does not support authentication protocol">Section A.2.3, “<code class="literal">Client does not support authentication protocol</code>”</a>. This information is of particular importance to PHP programmers migrating MySQL databases from version 4.0 or lower to version 4.1 or higher. </p><p> <span class="bold"><strong>Note</strong></span>: 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 “<span class="quote">odd</span>” release because it has a slightly different mechanism than that implemented in 4.1.1 and up. Differences between 4.1.0 and more recent versions are described further in <a href="database-administration.html#password-hashing-4-1-0" title="5.6.9.2. Password Hashing in MySQL 4.1.0">Section 5.6.9.2, “Password Hashing in MySQL 4.1.0”</a>. </p><p> Prior to MySQL 4.1, password hashes computed by the <code class="literal">PASSWORD()</code> function are 16 bytes long. Such hashes look like this: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SELECT PASSWORD('mypass');</code></strong> +--------------------+ | PASSWORD('mypass') | +--------------------+ | 6f8c114b58f2ce9e | +--------------------+ </pre><p> The <code class="literal">Password</code> column of the <code class="literal">user</code> table (in which these hashes are stored) also is 16 bytes long before MySQL 4.1. </p><p> As of MySQL 4.1, the <code class="literal">PASSWORD()</code> function has been modified to produce a longer 41-byte hash value: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SELECT PASSWORD('mypass');</code></strong> +-------------------------------------------+ | PASSWORD('mypass') | +-------------------------------------------+ | *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 | +-------------------------------------------+ </pre><p> Accordingly, the <code class="literal">Password</code> column in the <code class="literal">user</code> table also must be 41 bytes long to store these values: </p><div class="itemizedlist"><ul type="disc"><li><p> If you perform a new installation of MySQL 4.1, the <code class="literal">Password</code> column is made 41 bytes long automatically. </p></li><li><p> If you upgrade an older installation to 4.1, you should run the <span><strong class="command">mysql_fix_privilege_tables</strong></span> script to increase the length of the <code class="literal">Password</code> column from 16 to 41 bytes. (The script does not change existing password values, which remain 16 bytes long.) </p></li></ul></div><p> A widened <code class="literal">Password</code> 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: </p><div class="itemizedlist"><ul type="disc"><li><p> The obvious difference is the length (16 bytes versus 41 bytes). </p></li><li><p> A second difference is that password hashes in the new format always begin with a ‘<code class="literal">*</code>’ character, whereas passwords in the old format never do. </p></li></ul></div><p> 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. </p><p> 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. </p><p> The way in which the server uses password hashes during authentication is affected by the width of the <code class="literal">Password</code> column: </p><div class="itemizedlist"><ul type="disc"><li><p> If the column is short, only short-hash authentication is used. </p></li><li><p> If the column is long, it can hold either short or long hashes, and the server can use either format: </p><div class="itemizedlist"><ul type="circle"><li><p> Pre-4.1 clients can connect, although because they know only about the old hashing mechanism, they can authenticate only for accounts that have short hashes. </p></li><li><p> 4.1 clients can authenticate for accounts that have short or long hashes. </p></li></ul></div></li></ul></div><p> 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: </p><div class="itemizedlist"><ul type="disc"><li><p> Pre-4.1 client authenticating for account with short password hash </p></li><li><p> 4.1 client authenticating for account with short password hash </p></li><li><p> 4.1 client authenticating for account with long password hash </p></li></ul></div><p> The way in which the server generates password hashes for connected clients is affected by the width of the <code class="literal">Password</code> column and by the <code class="option">--old-passwords</code> option. A 4.1 server generates long hashes only if certain conditions are met: The <code class="literal">Password</code> column must be wide enough to hold long values and the <code class="option">--old-passwords</code> option must not be given. These conditions apply as follows: </p><div class="itemizedlist"><ul type="disc"><li><p> The <code class="literal">Password</code> column must be wide enough to hold long hashes (41 bytes). If the column has not been updated and still has the pre-4.1 width of 16 bytes, the server notices that long hashes cannot fit into it and generates only short hashes when a client performs password-changing operations using <code class="literal">PASSWORD()</code>, <code class="literal">GRANT</code>, or <code class="literal">SET PASSWORD</code>. This is the behavior that occurs if you have upgraded to 4.1 but have not yet run the <span><strong class="command">mysql_fix_privilege_tables</strong></span> script to widen the <code class="literal">Password</code> column. </p></li><li><p> If the <code class="literal">Password</code> column is wide, it can store either short or long password hashes. In this case, <code class="literal">PASSWORD()</code>, <code class="literal">GRANT</code>, and <code class="literal">SET PASSWORD</code> generate long hashes unless the server was started with the <code class="option">--old-passwords</code> option. That option forces the server to generate short password hashes instead. </p></li></ul></div><p> The purpose of the <code class="option">--old-passwords</code> option is to allow you to maintain backward compatibility with pre-4.1 clients under circumstances where the server would otherwise generate long password hashes. The option does not 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 <code class="literal">user</code> 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 <code class="option">--old-passwords</code> option, the following undesirable scenario is possible: </p><div class="itemizedlist"><ul type="disc"><li><p> An old client connects to an account that has a short password hash. </p></li><li><p> The client changes its own password. Without <code class="option">--old-passwords</code>, this results in the account having a long password hash. </p></li><li><p> The next time the old client attempts to connect to the account, it cannot, because the account has a long password hash that requires the new hashing mechanism during authentication. (Once an account has a long password hash in the user table, only 4.1 clients can authenticate for it, because pre-4.1 clients do not understand long hashes.) </p></li></ul></div><p> This scenario illustrates that, if you must support older pre-4.1 clients, it is dangerous to run a 4.1 server without using the <code class="option">--old-passwords</code> option. By running the server with <code class="option">--old-passwords</code>, password-changing operations do not generate long password hashes and thus do not cause accounts to become inaccessible to older clients. (Those clients cannot inadvertently lock themselves out by changing their password and ending up with a long password hash.) </p><p> The downside of the <code class="option">--old-passwords</code> option is that any passwords you create or change use short hashes, even for 4.1 clients. Thus, you lose the additional security provided by long password hashes. If you want to create an account that has a long hash (for example, for use by 4.1 clients), you must do so while running the server without <code class="option">--old-passwords</code>. </p><p> The following scenarios are possible for running a 4.1 server: </p><p> <span class="bold"><strong>Scenario 1:</strong></span> Short <code class="literal">Password</code> column in user table: </p><div class="itemizedlist"><ul type="disc"><li><p> Only short hashes can be stored in the <code class="literal">Password</code> column. </p></li><li><p> The server uses only short hashes during client authentication. </p></li><li><p> For connected clients, password hash-generating operations involving <code class="literal">PASSWORD()</code>, <code class="literal">GRANT</code>, or <code class="literal">SET PASSWORD</code> use short hashes exclusively. Any change to an account's password results in that account having a short password hash. </p></li><li><p> The <code class="option">--old-passwords</code> option can be used but is superfluous because with a short <code class="literal">Password</code> column, the server generates only short password hashes anyway. </p></li></ul></div><p> <span class="bold"><strong>Scenario 2:</strong></span> Long <code class="literal">Password</code> column; server not started with <code class="option">--old-passwords</code> option: </p><div class="itemizedlist"><ul type="disc"><li><p> Short or long hashes can be stored in the <code class="literal">Password</code> column. </p></li><li><p> 4.1 clients can authenticate for accounts that have short or long hashes. </p></li><li><p> Pre-4.1 clients can authenticate only for accounts that have short hashes. </p></li><li><p> For connected clients, password hash-generating operations involving <code class="literal">PASSWORD()</code>, <code class="literal">GRANT</code>, or <code class="literal">SET PASSWORD</code> use long hashes exclusively. A change to an account's password results in that account having a long password hash. </p></li></ul></div><p> As indicated earlier, a danger in this scenario is that it is possible for accounts that have a short password hash to become inaccessible to pre-4.1 clients. A change to such an account's password made via <code class="literal">GRANT</code>, <code class="literal">PASSWORD()</code>, or <code class="literal">SET PASSWORD</code> results in the account being given a long password hash. From that point on, no pre-4.1 client can authenticate to that account until the client upgrades to 4.1. </p><p> To deal with this problem, you can change a password in a special way. For example, normally you use <code class="literal">SET PASSWORD</code> as follows to change an account password: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SET PASSWORD FOR '<em class="replaceable"><code>some_user</code></em>'@'<em class="replaceable"><code>some_host</code></em>' = PASSWORD('mypass');</code></strong> </pre><p> To change the password but create a short hash, use the <code class="literal">OLD_PASSWORD()</code> function instead: </p><pre class="programlisting">mysql> <strong class="userinput"><code>SET PASSWORD FOR '<em class="replaceable"><code>some_user</code></em>'@'<em class="replaceable"><code>some_host</code></em>' = OLD_PASSWORD('mypass');</code></strong> </pre><p> <code class="literal">OLD_PASSWORD()</code> is useful for situations in which you explicitly want to generate a short hash. </p><p> <span class="bold"><strong>Scenario 3:</strong></span> Long <code class="literal">Password</code> column; server started with <code class="option">--old-passwords</code> option: </p><div class="itemizedlist"><ul type="disc"><li><p> Short or long hashes can be stored in the <code class="literal">Password</code> column. </p></li><li><p> 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 <code class="option">--old-passwords</code>). </p></li><li><p> Pre-4.1 clients can authenticate only for accounts that have short hashes. </p></li><li><p> For connected clients, password hash-generating operations involving <code class="literal">PASSWORD()</code>, <code class="literal">GRANT</code>, or <code class="literal">SET PASSWORD</code> use short hashes exclusively. Any change to an account's password results in that account having a short password hash. </p></li></ul></div><p> In this scenario, you cannot create accounts that have long password hashes, because the <code class="option">--old-passwords</code> option prevents generation of long hashes. Also, if you create an account with a long hash before using the <code class="option">--old-passwords</code> option, changing the account's password while <code class="option">--old-passwords</code> is in effect results in the account being given a short password, causing it to lose the security benefits of a longer hash. </p><p> The disadvantages for these scenarios may be summarized as follows: </p><p> In scenario 1, you cannot take advantage of longer hashes that provide more secure authentication. </p><p> In scenario 2, accounts with short hashes become inaccessible to pre-4.1 clients if you change their passwords without explicitly using <code class="literal">OLD_PASSWORD()</code>. </p><p> In scenario 3, <code class="option">--old-passwords</code> 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 <code class="option">--old-passwords</code> is in effect. </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="application-password-use"></a>5.6.9.1. Implications of Password Hashing Changes for Application Programs</h4></div></div></div><p> An upgrade to MySQL 4.1 can cause a compatibility issue for applications that use <code class="literal">PASSWORD()</code> to generate passwords for their own purposes. Applications really should not do this, because <code class="literal">PASSWORD()</code> should be used only to manage passwords for MySQL accounts. But some applications use <code class="literal">PASSWORD()</code> for their own purposes anyway. </p><p> If you upgrade to 4.1 and run the server under conditions where it generates long password hashes, an application that uses <code class="literal">PASSWORD()</code> for its own passwords breaks. The recommended course of action is to modify the application to use another function, such as <code class="literal">SHA1()</code> or <code class="literal">MD5()</code>, to produce hashed values. If that is not possible, you can use the <code class="literal">OLD_PASSWORD()</code> function, which is provided to generate short hashes in the old format. But note that <code class="literal">OLD_PASSWORD()</code> may one day no longer be supported. </p><p> If the server is running under circumstances where it generates short hashes, <code class="literal">OLD_PASSWORD()</code> is available but is equivalent to <code class="literal">PASSWORD()</code>. </p><p> PHP programmers migrating their MySQL databases from version 4.0 or lower to version 4.1 or higher should see <a href="problems.html#old-client" title="A.2.3. Client does not support authentication protocol">Section A.2.3, “<code class="literal">Client does not support authentication protocol</code>”</a>. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="password-hashing-4-1-0"></a>5.6.9.2. Password Hashing in MySQL 4.1.0</h4></div></div></div><p> Password hashing in MySQL 4.1.0 differs from hashing in 4.1.1 and up. The 4.1.0 differences are: </p><div class="itemizedlist"><ul type="disc"><li><p> Password hashes are 45 bytes long rather than 41 bytes. </p></li><li><p> The <code class="literal">PASSWORD()</code> function is non-repeatable. That is, with a given argument <em class="replaceable"><code>X</code></em>, successive calls to <code class="literal">PASSWORD(<em class="replaceable"><code>X</code></em>)</code> generate different results. </p></li></ul></div><p> These differences make authentication in 4.1.0 incompatible with that of releases that follow it. If you have upgraded to MySQL 4.1.0, it is recommended that you upgrade to a newer version as soon as possible. After you do, reassign any long passwords in the <code class="literal">user</code> table so that they are compatible with the 41-byte format. </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="user-account-management"></a>5.7. MySQL User Account Management</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="database-administration.html#user-names">5.7.1. MySQL Usernames and Passwords</a></span></dt><dt><span class="section"><a href="database-administration.html#adding-users">5.7.2. Adding New User Accounts to MySQL</a></span></dt><dt><span class="section"><a href="database-administration.html#removing-users">5.7.3. Removing User Accounts from MySQL</a></span></dt><dt><span class="section"><a href="database-administration.html#user-resources">5.7.4. Limiting Account Resources</a></span></dt><dt><span class="section"><a href="database-administration.html#passwords">5.7.5. Assigning Account Passwords</a></span></dt><dt><span class="section"><a href="database-administration.html#password-security">5.7.6. Keeping Your Password Secure</a></span></dt><dt><span class="section"><a href="database-administration.html#secure-connections">5.7.7. Using Secure Connections</a></span></dt></dl></div><p> This section describes how to set up accounts for clients of your MySQL server. It discusses the following topics: </p><div class="itemizedlist"><ul type="disc"><li><p> The meaning of account names and passwords as used in MySQL and how that compares to names and passwords used by your operating system </p></li><li><p> How to set up new accounts and remove existing accounts </p></li><li><p> How to change passwords </p></li><li><p> Guidelines for using passwords securely </p></li><li><p> How to use secure connections with SSL </p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="user-names"></a>5.7.1. MySQL Usernames and Passwords</h3></div></div></div><a class="indexterm" name="id2796022"></a><a class="indexterm" name="id2796032"></a><p> A MySQL account is defined in terms of a username and the client host or hosts from which the user can connect to the server. The account also has a password. There are several distinctions between the way usernames and passwords are used by MySQL and the way they are used by your operating system: </p><div class="itemizedlist"><ul type="disc"><li><p> Usernames, as used by MySQL for authentication purposes, have nothing to do with usernames (login names) as used by Windows or Unix. On Unix, most MySQL clients by default try to log in using the current Unix username as the MySQL username, but that is for convenience only. The default can be overridden easily, because client programs allow any username to be specified with a <code class="option">-u</code> or <code class="option">--user</code> option. Because this means that anyone can attempt to connect to the server using any username, you cannot make a database secure in any way unless all MySQL accounts have passwords. Anyone who specifies a username for an account that has no password is able to connect successfully to the server. </p></li><li><p> MySQL usernames can be up to 16 characters long. Operating system usernames might have a different maximum length. For example, Unix usernames typically are limited to eight characters. </p></li><li><p> MySQL usernames can be up to 16 characters long. <span class="emphasis"><em>Changing the maximum length is not supported</em></span>. If you try to change it, for example by changing the length of the <code class="literal">User</code> column in the <code class="literal">mysql</code> database tables, this will result in unpredictable behavior. (Altering privilege tables is not supported in any case.) Operating system usernames might have a different maximum length. For example, Unix usernames typically are limited to eight characters. </p></li><li><p> MySQL passwords have nothing to do with passwords for logging in to your operating system. There is no necessary connection between the password you use to log in to a Windows or Unix machine and the password you use to access the MySQL server on that machine. </p></li><li><p> MySQL encrypts passwords using its own algorithm. This encryption is different from that used during the Unix login process. MySQL password encryption is the same as that implemented by the <code class="literal">PASSWORD()</code> SQL function. Unix password encryption is the same as that implemented by the <code class="literal">ENCRYPT()</code> SQL function. See the descriptions of the <code class="literal">PASSWORD()</code> and <code class="literal">ENCRYPT()</code> functions in <a href="functions.html#encryption-functions" title="12.9.2. Encryption Functions">Section 12.9.2, “Encryption Functions”</a>. From version 4.1 on, MySQL employs a stronger authentication method that has better password protection during the connection process than in earlier versions. It is secure even if TCP/IP packets are sniffed or the <code class="literal">mysql</code> database is captured. (In earlier versions, even though passwords are stored in encrypted form in the <code class="literal">user</code> table, knowledge of the encrypted password value could be used to connect to the MySQL server.) </p></li></ul></div><p> When you install MySQL, the grant tables are populated with an initial set of accounts. These accounts have names and access privileges that are described in <a href="installing.html#default-privileges" title="2.9.3. Securing the Initial MySQL Accounts">Section 2.9.3, “Securing the Initial MySQL Accounts”</a>, which also discusses how to assign passwords to them. Thereafter, you normally set up, modify, and remove MySQL accounts using the <code class="literal">GRANT</code> and <code class="literal">REVOKE</code> statements. See <a href="sql-syntax.html#grant" title="13.5.1.2. GRANT and REVOKE Syntax">Section 13.5.1.2, “<code class="literal">GRANT</code> and <code class="literal">REVOKE</code> Syntax”</a>. </p><p> When you connect to a MySQL server with a command-line client, you should specify the username and password for the account that you want to use: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql --user=monty --password=<em class="replaceable"><code>guess</code></em> <em class="replaceable"><code>db_name</code></em></code></strong> </pre><p> If you prefer short options, the command looks like this: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql -u monty -p<em class="replaceable"><code>guess</code></em> <em class="replaceable"><code>db_name</code></em></code></strong> </pre><p> There must be <span class="emphasis"><em>no space</em></span> between the <code class="option">-p</code> option and the following password value. See <a href="database-administration.html#connecting" title="5.6.4. Connecting to the MySQL Server">Section 5.6.4, “Connecting to the MySQL Server”</a>. </p><p> The preceding commands include the password value on the command line, which can be a security risk. See <a href="database-administration.html#password-security" title="5.7.6. Keeping Your Password Secure">Section 5.7.6, “Keeping Your Password Secure”</a>. To avoid this, specify the <code class="option">--password</code> or <code class="option">-p</code> option without any following password value: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql --user=monty --password <em class="replaceable"><code>db_name</code></em></code></strong> shell> <strong class="userinput"><code>mysql -u monty -p <em class="replaceable"><code>db_name</code></em></code></strong> </pre><p> Then the client program prints a prompt and waits for you to enter the password. (In these examples, <em class="replaceable"><code>db_name</code></em> is <span class="emphasis"><em>not</em></span> interpreted as a password, because it is separated from the preceding password option by a space.) </p><p> On some systems, the library call that MySQL uses to prompt for a password automatically limits the password to eight characters. That is a problem with the system library, not with MySQL. Internally, MySQL does not have any limit for the length of the password. To work around the problem, change your MySQL password to a value that is eight or fewer characters long, or put your password in an option file. </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="adding-users"></a>5.7.2. Adding New User Accounts to MySQL</h3></div></div></div><a class="indexterm" name="id2796331"></a><a class="indexterm" name="id2796340"></a><a class="indexterm" name="id2796352"></a><a class="indexterm" name="id2796362"></a><a class="indexterm" name="id2796372"></a><a class="indexterm" name="id2796383"></a><a class="indexterm" name="id2796393"></a><p> You can create MySQL accounts in two ways: </p><div class="itemizedlist"><ul type="disc"><li><p> By using <code class="literal">GRANT</code> statements </p></li><li><p> By manipulating the MySQL grant tables directly </p></li></ul></div><p> The preferred method is to use <code class="literal">GRANT</code> statements, because they are more concise and less error-prone. <code class="literal">GRANT</code> is available as of MySQL 3.22.11; its syntax is described in <a href="sql-syntax.html#grant" title="13.5.1.2. GRANT and REVOKE Syntax">Section 13.5.1.2, “<code class="literal">GRANT</code> and <code class="literal">REVOKE</code> Syntax”</a>. </p><p> Another option for creating accounts is to use one of several available third-party programs that offer capabilities for MySQL account administration. <code class="literal">phpMyAdmin</code> is one such program. </p><p> The following examples show how to use the <span><strong class="command">mysql</strong></span> client program to set up new users. These examples assume that privileges are set up according to the defaults described in <a href="installing.html#default-privileges" title="2.9.3. Securing the Initial MySQL Accounts">Section 2.9.3, “Securing the Initial MySQL Accounts”</a>. This means that to make changes, you must connect to the MySQL server as the MySQL <code class="literal">root</code> user, and the <code class="literal">root</code> account must have the <code class="literal">INSERT</code> privilege for the <code class="literal">mysql</code> database and the <code class="literal">RELOAD</code> administrative privilege. </p><p> First, use the <span><strong class="command">mysql</strong></span> program to connect to the server as the MySQL <code class="literal">root</code> user: </p><pre class="programlisting">shell> <strong class="userinput"><code>mysql --user=root mysql</code></strong> </pre><p> If you have assigned a password to the <code class="literal">root</code> account, you also need to supply a <code class="option">--password</code> or <code class="option">-p</code> option for this <span><strong class="command">mysql</strong></span> command and also for those later in this section. </p><p> After connecting to the server as <code class="literal">root</code>, you can add new accounts. The following statements use <code class="literal">GRANT</code> to set up four new accounts: </p><pre class