<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Chapter 13. Storage Engines</title><link rel="stylesheet" href="mysql-html.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.69.1"><link rel="start" href="index.html" title="MySQL 5.0 Reference Manual"><link rel="up" href="index.html" title="MySQL 5.0 Reference Manual"><link rel="prev" href="sql-syntax.html" title="Chapter 12. SQL Statement Syntax"><link rel="next" href="ha-overview.html" title="Chapter 14. High Availability, Scalability, and DRBD"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 13. Storage Engines</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="sql-syntax.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ha-overview.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="storage-engines"></a>Chapter 13. Storage Engines</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="storage-engines.html#myisam-storage-engine">13.1. The <code class="literal">MyISAM</code> Storage Engine</a></span></dt><dd><dl><dt><span class="section"><a href="storage-engines.html#myisam-start">13.1.1. <code class="literal">MyISAM</code> Startup Options</a></span></dt><dt><span class="section"><a href="storage-engines.html#key-space">13.1.2. Space Needed for Keys</a></span></dt><dt><span class="section"><a href="storage-engines.html#myisam-table-formats">13.1.3. <code class="literal">MyISAM</code> Table Storage Formats</a></span></dt><dt><span class="section"><a href="storage-engines.html#myisam-table-problems">13.1.4. <code class="literal">MyISAM</code> Table Problems</a></span></dt></dl></dd><dt><span class="section"><a href="storage-engines.html#innodb">13.2. The <code class="literal">InnoDB</code> Storage Engine</a></span></dt><dd><dl><dt><span class="section"><a href="storage-engines.html#innodb-overview">13.2.1. <code class="literal">InnoDB</code> Overview</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-contact-information">13.2.2. <code class="literal">InnoDB</code> Contact Information</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-configuration">13.2.3. <code class="literal">InnoDB</code> Configuration</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-parameters">13.2.4. <code class="literal">InnoDB</code> Startup Options and System Variables</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-init">13.2.5. Creating the <code class="literal">InnoDB</code> Tablespace</a></span></dt><dt><span class="section"><a href="storage-engines.html#using-innodb-tables">13.2.6. Creating and Using <code class="literal">InnoDB</code> Tables</a></span></dt><dt><span class="section"><a href="storage-engines.html#adding-and-removing">13.2.7. Adding and Removing <code class="literal">InnoDB</code> Data and Log Files</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-backup">13.2.8. Backing Up and Recovering an <code class="literal">InnoDB</code> Database</a></span></dt><dt><span class="section"><a href="storage-engines.html#moving">13.2.9. Moving an <code class="literal">InnoDB</code> Database to Another Machine</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-transaction-model">13.2.10. <code class="literal">InnoDB</code> Transaction Model and Locking</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-tuning">13.2.11. <code class="literal">InnoDB</code> Performance Tuning Tips</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-multi-versioning">13.2.12. Implementation of Multi-Versioning</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-table-and-index">13.2.13. <code class="literal">InnoDB</code> Table and Index Structures</a></span></dt><dt><span class="section"><a href="storage-engines.html#file-space-management">13.2.14. <code class="literal">InnoDB</code> File Space Management and Disk I/O</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-error-handling">13.2.15. <code class="literal">InnoDB</code> Error Handling</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-restrictions">13.2.16. Restrictions on <code class="literal">InnoDB</code> Tables</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-troubleshooting">13.2.17. <code class="literal">InnoDB</code> Troubleshooting</a></span></dt></dl></dd><dt><span class="section"><a href="storage-engines.html#merge-storage-engine">13.3. The <code class="literal">MERGE</code> Storage Engine</a></span></dt><dd><dl><dt><span class="section"><a href="storage-engines.html#merge-table-problems">13.3.1. <code class="literal">MERGE</code> Table Problems</a></span></dt></dl></dd><dt><span class="section"><a href="storage-engines.html#memory-storage-engine">13.4. The <code class="literal">MEMORY</code> (<code class="literal">HEAP</code>) Storage Engine</a></span></dt><dt><span class="section"><a href="storage-engines.html#bdb-storage-engine">13.5. The <code class="literal">BDB</code> (<code class="literal">BerkeleyDB</code>) Storage
Engine</a></span></dt><dd><dl><dt><span class="section"><a href="storage-engines.html#bdb-portability">13.5.1. Operating Systems Supported by <code class="literal">BDB</code></a></span></dt><dt><span class="section"><a href="storage-engines.html#bdb-install">13.5.2. Installing <code class="literal">BDB</code></a></span></dt><dt><span class="section"><a href="storage-engines.html#bdb-start">13.5.3. <code class="literal">BDB</code> Startup Options</a></span></dt><dt><span class="section"><a href="storage-engines.html#bdb-characteristics">13.5.4. Characteristics of <code class="literal">BDB</code> Tables</a></span></dt><dt><span class="section"><a href="storage-engines.html#bdb-restrictions">13.5.5. Restrictions on <code class="literal">BDB</code> Tables</a></span></dt><dt><span class="section"><a href="storage-engines.html#bdb-errors">13.5.6. Errors That May Occur When Using <code class="literal">BDB</code> Tables</a></span></dt></dl></dd><dt><span class="section"><a href="storage-engines.html#example-storage-engine">13.6. The <code class="literal">EXAMPLE</code> Storage Engine</a></span></dt><dt><span class="section"><a href="storage-engines.html#federated-storage-engine">13.7. The <code class="literal">FEDERATED</code> Storage Engine</a></span></dt><dd><dl><dt><span class="section"><a href="storage-engines.html#federated-description">13.7.1. Description of the <code class="literal">FEDERATED</code> Storage Engine</a></span></dt><dt><span class="section"><a href="storage-engines.html#federated-use">13.7.2. How to Use <code class="literal">FEDERATED</code> Tables</a></span></dt><dt><span class="section"><a href="storage-engines.html#federated-limitations">13.7.3. Limitations of the <code class="literal">FEDERATED</code> Storage Engine</a></span></dt></dl></dd><dt><span class="section"><a href="storage-engines.html#archive-storage-engine">13.8. The <code class="literal">ARCHIVE</code> Storage Engine</a></span></dt><dt><span class="section"><a href="storage-engines.html#csv-storage-engine">13.9. The <code class="literal">CSV</code> Storage Engine</a></span></dt><dt><span class="section"><a href="storage-engines.html#blackhole-storage-engine">13.10. The <code class="literal">BLACKHOLE</code> Storage Engine</a></span></dt></dl></div><a class="indexterm" name="id2892587"></a><a class="indexterm" name="id2892600"></a><a class="indexterm" name="id2892612"></a><a class="indexterm" name="id2892625"></a><a class="indexterm" name="id2892634"></a><a class="indexterm" name="id2892643"></a><a class="indexterm" name="id2892652"></a><a class="indexterm" name="id2892661"></a><a class="indexterm" name="id2892670"></a><a class="indexterm" name="id2892680"></a><a class="indexterm" name="id2892689"></a><a class="indexterm" name="id2892698"></a><a class="indexterm" name="id2892707"></a><a class="indexterm" name="id2892716"></a><a class="indexterm" name="id2892726"></a><a class="indexterm" name="id2892735"></a><p>
MySQL supports several storage engines that act as handlers for
different table types. MySQL storage engines include both those that
handle transaction-safe tables and those that handle
non-transaction-safe tables:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">MyISAM</code> manages non-transactional tables. It
provides high-speed storage and retrieval, as well as fulltext
searching capabilities. <code class="literal">MyISAM</code> is supported
in all MySQL configurations, and is the default storage engine
unless you have configured MySQL to use a different one by
default.
</p></li><li><p>
The <code class="literal">MEMORY</code> storage engine provides in-memory
tables. The <code class="literal">MERGE</code> storage engine allows a
collection of identical <code class="literal">MyISAM</code> tables to be
handled as a single table. Like <code class="literal">MyISAM</code>, the
<code class="literal">MEMORY</code> and <code class="literal">MERGE</code> storage
engines handle non-transactional tables, and both are also
included in MySQL by default.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The <code class="literal">MEMORY</code> storage engine formerly was
known as the <code class="literal">HEAP</code> engine.
</p></div></li><li><p>
The <code class="literal">InnoDB</code> and <code class="literal">BDB</code> storage
engines provide transaction-safe tables.
<code class="literal">InnoDB</code> is included by default in all MySQL
5.0 binary distributions. In source distributions,
you can enable or disable either engine by configuring MySQL as
you like.
</p></li><li><p>
The <code class="literal">EXAMPLE</code> storage engine is a
“<span class="quote">stub</span>” engine that does nothing. You can create
tables with this engine, but no data can be stored in them or
retrieved from them. The purpose of this engine is to serve as
an example in the MySQL source code that illustrates how to
begin writing new storage engines. As such, it is primarily of
interest to developers.
</p></li><li><p>
<code class="literal">NDB Cluster</code> is the storage engine used by
MySQL Cluster to implement tables that are partitioned over many
computers. It is available in MySQL 5.0 binary
distributions. This storage engine is currently supported on a
number of Unix platforms. We intend to add support for this
engine on other platforms, including Windows, in future MySQL
releases.
</p><p>
MySQL Cluster is covered in a separate chapter of this Manual.
See <a href="mysql-cluster.html" title="Chapter 16. MySQL Cluster">Chapter 16, <i>MySQL Cluster</i></a>, for more information.
</p></li><li><p>
The <code class="literal">ARCHIVE</code> storage engine is used for
storing large amounts of data without indexes with a very small
footprint.
</p></li><li><p>
The <code class="literal">CSV</code> storage engine stores data in text
files using comma-separated values format.
</p></li><li><p>
The <code class="literal">BLACKHOLE</code> storage engine accepts but does
not store data and retrievals always return an empty set.
</p></li><li><p>
The <code class="literal">FEDERATED</code> storage engine was added in
MySQL 5.0.3. This engine stores data in a remote database.
Currently, it works with MySQL only, using the MySQL C Client
API. In future releases, we intend to enable it to connect to
other data sources using other drivers or client connection
methods.
</p></li></ul></div><p>
This chapter describes each of the MySQL storage engines except for
<code class="literal">NDB Cluster</code>, which is covered in
<a href="mysql-cluster.html" title="Chapter 16. MySQL Cluster">Chapter 16, <i>MySQL Cluster</i></a>.
</p><p>
For answers to some commonly asked questions about MySQL storage
engines, see <a href="faqs.html#faqs-storage-engines" title="A.2. MySQL 5.0 FAQ — Storage Engines">Section A.2, “MySQL 5.0 FAQ — Storage Engines”</a>.
</p><p>
When you create a new table, you can specify which storage engine to
use by adding an <code class="literal">ENGINE</code> or
<code class="literal">TYPE</code> table option to the <code class="literal">CREATE
TABLE</code> statement:
</p><pre class="programlisting">CREATE TABLE t (i INT) ENGINE = INNODB;
CREATE TABLE t (i INT) TYPE = MEMORY;
</pre><p>
The older term <code class="literal">TYPE</code> is supported as a synonym for
<code class="literal">ENGINE</code> for backward compatibility, but
<code class="literal">ENGINE</code> is the preferred term and
<code class="literal">TYPE</code> is deprecated.
</p><p>
If you omit the <code class="literal">ENGINE</code> or <code class="literal">TYPE</code>
option, the default storage engine is used. Normally, this is
<code class="literal">MyISAM</code>, but you can change it by using the
<code class="option">--default-storage-engine</code> or
<code class="option">--default-table-type</code> server startup option, or by
setting the <code class="literal">default-storage-engine</code> or
<code class="literal">default-table-type</code> option in the
<code class="filename">my.cnf</code> configuration file.
</p><p>
You can set the default storage engine to be used during the current
session by setting the <code class="literal">storage_engine</code> or
<code class="literal">table_type</code> variable:
</p><pre class="programlisting">SET storage_engine=MYISAM;
SET table_type=BDB;
</pre><p>
When MySQL is installed on Windows using the MySQL Configuration
Wizard, the <code class="literal">InnoDB</code> storage engine can be selected
as the default instead of <code class="literal">MyISAM</code>. See
<a href="installing.html#mysql-config-wizard-database-usage" title="2.4.8.4.5. The Database Usage Dialog">Section 2.4.8.4.5, “The Database Usage Dialog”</a>.
</p><p>
To convert a table from one storage engine to another, use an
<code class="literal">ALTER TABLE</code> statement that indicates the new
engine:
</p><pre class="programlisting">ALTER TABLE t ENGINE = MYISAM;
ALTER TABLE t TYPE = BDB;
</pre><p>
See <a href="sql-syntax.html#create-table" title="12.1.5. CREATE TABLE Syntax">Section 12.1.5, “<code class="literal">CREATE TABLE</code> Syntax”</a>, and
<a href="sql-syntax.html#alter-table" title="12.1.2. ALTER TABLE Syntax">Section 12.1.2, “<code class="literal">ALTER TABLE</code> Syntax”</a>.
</p><p>
If you try to use a storage engine that is not compiled in or that
is compiled in but deactivated, MySQL instead creates a table using
the default storage engine, usually <code class="literal">MyISAM</code>. This
behavior is convenient when you want to copy tables between MySQL
servers that support different storage engines. (For example, in a
replication setup, perhaps your master server supports transactional
storage engines for increased safety, but the slave servers use only
non-transactional storage engines for greater speed.)
</p><p>
This automatic substitution of the default storage engine for
unavailable engines can be confusing for new MySQL users. A warning
is generated whenever a storage engine is automatically changed.
</p><p>
For new tables, MySQL always creates an <code class="filename">.frm</code>
file to hold the table and column definitions. The table's index and
data may be stored in one or more other files, depending on the
storage engine. The server creates the <code class="filename">.frm</code>
file above the storage engine level. Individual storage engines
create any additional files required for the tables that they
manage.
</p><p>
A database may contain tables of different types. That is, tables
need not all be created with the same storage engine.
</p><p>
Transaction-safe tables (TSTs) have several advantages over
non-transaction-safe tables (NTSTs):
</p><div class="itemizedlist"><ul type="disc"><li><p>
They are safer. Even if MySQL crashes or you get hardware
problems, you can get your data back, either by automatic
recovery or from a backup plus the transaction log.
</p></li><li><p>
You can combine many statements and accept them all at the same
time with the <code class="literal">COMMIT</code> statement (if autocommit
is disabled).
</p></li><li><p>
You can execute <code class="literal">ROLLBACK</code> to ignore your
changes (if autocommit is disabled).
</p></li><li><p>
If an update fails, all of your changes are reverted. (With
non-transaction-safe tables, all changes that have taken place
are permanent.)
</p></li><li><p>
Transaction-safe storage engines can provide better concurrency
for tables that get many updates concurrently with reads.
</p></li></ul></div><p>
You can combine transaction-safe and non-transaction-safe tables in
the same statements to get the best of both worlds. However,
although MySQL supports several transaction-safe storage engines,
for best results, you should not mix different storage engines
within a transaction with autocommit disabled. For example, if you
do this, changes to non-transaction-safe tables still are committed
immediately and cannot be rolled back. For information about this
and other problems that can occur in transactions that use mixed
storage engines, see <a href="sql-syntax.html#commit" title="12.4.1. START TRANSACTION, COMMIT, and
ROLLBACK Syntax">Section 12.4.1, “<code class="literal">START TRANSACTION</code>, <code class="literal">COMMIT</code>, and
<code class="literal">ROLLBACK</code> Syntax”</a>.
</p><p>
Non-transaction-safe tables have several advantages of their own,
all of which occur because there is no transaction overhead:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Much faster
</p></li><li><p>
Lower disk space requirements
</p></li><li><p>
Less memory required to perform updates
</p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="myisam-storage-engine"></a>13.1. The <code class="literal">MyISAM</code> Storage Engine</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#myisam-start">13.1.1. <code class="literal">MyISAM</code> Startup Options</a></span></dt><dt><span class="section"><a href="storage-engines.html#key-space">13.1.2. Space Needed for Keys</a></span></dt><dt><span class="section"><a href="storage-engines.html#myisam-table-formats">13.1.3. <code class="literal">MyISAM</code> Table Storage Formats</a></span></dt><dt><span class="section"><a href="storage-engines.html#myisam-table-problems">13.1.4. <code class="literal">MyISAM</code> Table Problems</a></span></dt></dl></div><a class="indexterm" name="id2893410"></a><a class="indexterm" name="id2893420"></a><p>
<code class="literal">MyISAM</code> is the default storage engine. It is based
on the older <code class="literal">ISAM</code> code but has many useful
extensions. (Note that MySQL 5.0 does
<span class="emphasis"><em>not</em></span> support <code class="literal">ISAM</code>.)
</p><p>
Each <code class="literal">MyISAM</code> table is stored on disk in three
files. The files have names that begin with the table name and have
an extension to indicate the file type. An <code class="filename">.frm</code>
file stores the table format. The data file has an
<code class="filename">.MYD</code> (<code class="literal">MYData</code>) extension. The
index file has an <code class="filename">.MYI</code>
(<code class="literal">MYIndex</code>) extension.
</p><p>
To specify explicitly that you want a <code class="literal">MyISAM</code>
table, indicate that with an <code class="literal">ENGINE</code> table option:
</p><pre class="programlisting">CREATE TABLE t (i INT) ENGINE = MYISAM;
</pre><p>
The older term <code class="literal">TYPE</code> is supported as a synonym for
<code class="literal">ENGINE</code> for backward compatibility, but
<code class="literal">ENGINE</code> is the preferred term and
<code class="literal">TYPE</code> is deprecated.
</p><p>
Normally, it is unnecesary to use <code class="literal">ENGINE</code> to
specify the <code class="literal">MyISAM</code> storage engine.
<code class="literal">MyISAM</code> is the default engine unless the default
has been changed. To ensure that <code class="literal">MyISAM</code> is used
in situations where the default might have been changed, include the
<code class="literal">ENGINE</code> option explicitly.
</p><p>
You can check or repair <code class="literal">MyISAM</code> tables with the
<span><strong class="command">mysqlcheck</strong></span> client or <span><strong class="command">myisamchk</strong></span>
utility. You can also compress <code class="literal">MyISAM</code> tables with
<span><strong class="command">myisampack</strong></span> to take up much less space. See
<a href="client-utility-programs.html#mysqlcheck" title="7.11. mysqlcheck — A Table Maintenance and Repair Program">Section 7.11, “<span><strong class="command">mysqlcheck</strong></span> — A Table Maintenance and Repair Program”</a>, <a href="server-administration.html#crash-recovery" title="5.9.4.1. Using myisamchk for Crash Recovery">Section 5.9.4.1, “Using <span><strong class="command">myisamchk</strong></span> for Crash Recovery”</a>, and
<a href="client-utility-programs.html#myisampack" title="7.6. myisampack — Generate Compressed, Read-Only MyISAM Tables">Section 7.6, “<span><strong class="command">myisampack</strong></span> — Generate Compressed, Read-Only MyISAM Tables”</a>.
</p><p>
<code class="literal">MyISAM</code> tables have the following characteristics:
</p><div class="itemizedlist"><ul type="disc"><li><p>
All data values are stored with the low byte first. This makes
the data machine and operating system independent. The only
requirements for binary portability are that the machine uses
two's-complement signed integers and IEEE floating-point format.
These requirements are widely used among mainstream machines.
Binary compatibility might not be applicable to embedded
systems, which sometimes have peculiar processors.
</p><p>
There is no significant speed penalty for storing data low byte
first; the bytes in a table row normally are unaligned and it
takes little more processing to read an unaligned byte in order
than in reverse order. Also, the code in the server that fetches
column values is not time critical compared to other code.
</p></li><li><p>
All numeric key values are stored with the high byte first to
allow better index compression.
</p></li><li><p>
Large files (up to 63-bit file length) are supported on
filesystems and operating systems that support large files.
</p></li><li><p>
There is a limit of 2<sup>32</sup> (~4.295E+09)
rows in a <code class="literal">MyISAM</code> table. If you build MySQL
with the <code class="option">--with-big-tables</code> option, the row
limitation is increased to
(2<sup>32</sup>)<sup>2</sup>
(1.844E+19) rows. See <a href="installing.html#configure-options" title="2.4.15.2. Typical configure Options">Section 2.4.15.2, “Typical <span><strong class="command">configure</strong></span> Options”</a>.
Binary distributions for Unix and Linux are built with this
option.
</p></li><li><p>
The maximum number of indexes per <code class="literal">MyISAM</code>
table is 64. This can be changed by recompiling. Beginning with
MySQL 5.0.18, you can configure the build by invoking
<span><strong class="command">configure</strong></span> with the
<code class="option">--with-max-indexes=<em class="replaceable"><code>N</code></em></code>
option, where <em class="replaceable"><code>N</code></em> is the maximum number
of indexes to permit per <code class="literal">MyISAM</code> table.
<em class="replaceable"><code>N</code></em> must be less than or equal to 128.
Before MySQL 5.0.18, you must change the source.
</p><p>
The maximum number of columns per index is 16.
</p></li><li><p>
The maximum key length is 1000 bytes. This can also be changed
by changing the source and recompiling. For the case of a key
longer than 250 bytes, a larger key block size than the default
of 1024 bytes is used.
</p></li><li><p>
When rows are inserted in sorted order (as when you are using an
<code class="literal">AUTO_INCREMENT</code> column), the index tree is
split so that the high node only contains one key. This improves
space utilization in the index tree.
</p></li><li><p>
Internal handling of one <code class="literal">AUTO_INCREMENT</code>
column per table is supported. <code class="literal">MyISAM</code>
automatically updates this column for <code class="literal">INSERT</code>
and <code class="literal">UPDATE</code> operations. This makes
<code class="literal">AUTO_INCREMENT</code> columns faster (at least 10%).
Values at the top of the sequence are not reused after being
deleted. (When an <code class="literal">AUTO_INCREMENT</code> column is
defined as the last column of a multiple-column index, reuse of
values deleted from the top of a sequence does occur.) The
<code class="literal">AUTO_INCREMENT</code> value can be reset with
<code class="literal">ALTER TABLE</code> or <span><strong class="command">myisamchk</strong></span>.
</p></li><li><p>
Dynamic-sized rows are much less fragmented when mixing deletes
with updates and inserts. This is done by automatically
combining adjacent deleted blocks and by extending blocks if the
next block is deleted.
</p></li><li><p>
<code class="literal">MyISAM</code> supports concurrent inserts: If a
table has no free blocks in the middle of the data file, you can
<code class="literal">INSERT</code> new rows into it at the same time that
other threads are reading from the table. A free block can occur
as a result of deleting rows or an update of a dynamic length
row with more data than its current contents. When all free
blocks are used up (filled in), future inserts become concurrent
again. See <a href="optimization.html#concurrent-inserts" title="6.3.3. Concurrent Inserts">Section 6.3.3, “Concurrent Inserts”</a>.
</p></li><li><p>
You can put the data file and index file on different
directories to get more speed with the <code class="literal">DATA
DIRECTORY</code> and <code class="literal">INDEX DIRECTORY</code> table
options to <code class="literal">CREATE TABLE</code>. See
<a href="sql-syntax.html#create-table" title="12.1.5. CREATE TABLE Syntax">Section 12.1.5, “<code class="literal">CREATE TABLE</code> Syntax”</a>.
</p></li><li><p>
<code class="literal">BLOB</code> and <code class="literal">TEXT</code> columns can
be indexed.
</p></li><li><p>
<code class="literal">NULL</code> values are allowed in indexed columns.
This takes 0–1 bytes per key.
</p></li><li><p>
Each character column can have a different character set. See
<a href="internationalization-localization.html#charset" title="9.1. Character Set Support">Section 9.1, “Character Set Support”</a>.
</p></li><li><p>
There is a flag in the <code class="literal">MyISAM</code> index file that
indicates whether the table was closed correctly. If
<span><strong class="command">mysqld</strong></span> is started with the
<code class="option">--myisam-recover</code> option,
<code class="literal">MyISAM</code> tables are automatically checked when
opened, and are repaired if the table wasn't closed properly.
</p></li><li><p>
<span><strong class="command">myisamchk</strong></span> marks tables as checked if you run
it with the <code class="option">--update-state</code> option.
<span><strong class="command">myisamchk --fast</strong></span> checks only those tables
that don't have this mark.
</p></li><li><p>
<span><strong class="command">myisamchk --analyze</strong></span> stores statistics for
portions of keys, as well as for entire keys.
</p></li><li><p>
<span><strong class="command">myisampack</strong></span> can pack <code class="literal">BLOB</code>
and <code class="literal">VARCHAR</code> columns.
</p></li></ul></div><p>
<code class="literal">MyISAM</code> also supports the following features:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Support for a true <code class="literal">VARCHAR</code> type; a
<code class="literal">VARCHAR</code> column starts with a length stored in
one or two bytes.
</p></li><li><p>
Tables with <code class="literal">VARCHAR</code> columns may have fixed or
dynamic row length.
</p></li><li><p>
The sum of the lengths of the <code class="literal">VARCHAR</code> and
<code class="literal">CHAR</code> columns in a table may be up to 64KB.
</p></li><li><p>
Arbitrary length <code class="literal">UNIQUE</code> constraints.
</p></li></ul></div><p>
<span class="bold"><strong>Additional resources</strong></span>
</p><div class="itemizedlist"><ul type="disc"><li><p>
A forum dedicated to the <code class="literal">MyISAM</code> storage
engine is available at <a href="http://forums.mysql.com/list.php?21" target="_top">http://forums.mysql.com/list.php?21</a>.
</p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="myisam-start"></a>13.1.1. <code class="literal">MyISAM</code> Startup Options</h3></div></div></div><p>
The following options to <span><strong class="command">mysqld</strong></span> can be used to
change the behavior of <code class="literal">MyISAM</code> tables. For
additional information, see <a href="server-administration.html#server-options" title="5.2.2. Command Options">Section 5.2.2, “Command Options”</a>.
</p><div class="informaltable"><table border="1"><colgroup><col><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th><span class="bold"><strong>Name</strong></span></th><th align="center"><span class="bold"><strong>Cmd-line</strong></span></th><th align="center"><span class="bold"><strong>Option file</strong></span></th><th align="center"><span class="bold"><strong>System Var</strong></span></th><th align="center"><span class="bold"><strong>Status Var</strong></span></th><th align="center"><span class="bold"><strong>Var Scope</strong></span></th><th align="center"><span class="bold"><strong>Dynamic</strong></span></th></tr></thead><tbody><tr><td><a href="server-administration.html#option_mysqld_bulk_insert_buffer_size">bulk_insert_buffer_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">both</td><td align="center">yes</td></tr><tr><td>concurrent_insert</td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_delay-key-write">delay-key-write</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td> - <span class="emphasis"><em>Variable</em></span>: delay_key_write</td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_have_rtree_keys">have_rtree_keys</a></td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_key_buffer_size">key_buffer_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_log-isam">log-isam</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_myisam-recover">myisam-recover</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">both</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_myisam_block_size">myisam_block_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">both</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_myisam_data_pointer_size">myisam_data_pointer_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_myisam_max_extra_sort_file_size">myisam_max_extra_sort_file_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_myisam_max_sort_file_size">myisam_max_sort_file_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td>myisam_recover_options</td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_myisam_repair_threads">myisam_repair_threads</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">both</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_myisam_sort_buffer_size">myisam_sort_buffer_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">both</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_myisam_stats_method">myisam_stats_method</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">both</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_skip-concurrent-insert">skip-concurrent-insert</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td> - <span class="emphasis"><em>Variable</em></span>: skip-concurrent_insert</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td><a href="server-administration.html#option_mysqld_tmp_table_size">tmp_table_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">both</td><td align="center">yes</td></tr></tbody></table></div><div class="itemizedlist"><ul type="disc"><li><p>
<a class="indexterm" name="id2894860"></a>
<a class="indexterm" name="id2894872"></a>
<code class="option">--myisam-recover=<em class="replaceable"><code>mode</code></em></code>
</p><p>
Set the mode for automatic recovery of crashed
<code class="literal">MyISAM</code> tables.
</p></li><li><p>
<a class="indexterm" name="id2894908"></a>
<a class="indexterm" name="id2894921"></a>
<code class="option">--delay-key-write=ALL</code>
</p><p>
Don't flush key buffers between writes for any
<code class="literal">MyISAM</code> table.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
If you do this, you should not access
<code class="literal">MyISAM</code> tables from another program (such
as from another MySQL server or with
<span><strong class="command">myisamchk</strong></span>) when the tables are in use.
Doing so risks index corruption. Using
<code class="option">--external-locking</code> does not eliminate this
risk.
</p></div></li></ul></div><p>
The following system variables affect the behavior of
<code class="literal">MyISAM</code> tables. For additional information, see
<a href="server-administration.html#server-system-variables" title="5.2.3. System Variables">Section 5.2.3, “System Variables”</a>.
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">bulk_insert_buffer_size</code>
</p><p>
The size of the tree cache used in bulk insert optimization.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
This is a limit <span class="emphasis"><em>per thread</em></span>!
</p></div></li><li><p>
<code class="literal">myisam_max_extra_sort_file_size</code>
</p><p>
Used to help MySQL to decide when to use the slow but safe key
cache index creation method.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
This parameter was given in bytes before MySQL 5.0.6, when
it was removed.
</p></div></li><li><p>
<code class="literal">myisam_max_sort_file_size</code>
</p><p>
The maximum size of the temporary file that 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 larger than this value, the index is
created using the key cache instead, which is slower. The
value is given in bytes.
</p></li><li><p>
<code class="literal">myisam_sort_buffer_size</code>
</p><p>
Set the size of the buffer used when recovering tables.
</p></li></ul></div><p>
Automatic recovery is activated if you start
<span><strong class="command">mysqld</strong></span> with the
<code class="option">--myisam-recover</code> option. In this case, when the
server opens a <code class="literal">MyISAM</code> table, it checks whether
the table is marked as crashed or whether the open count variable
for the table is not 0 and you are running the server with
external locking disabled. If either of these conditions is true,
the following happens:
</p><p class="mnmas"><b>MySQL Enterprise</b>
Subscribers to MySQL Enterprise Monitor receive notification if
the <code class="option">--myisam-recover</code> option has not been set.
For more information see
<a href="http://www.mysql.com/products/enterprise/advisors.html" target="_top">http://www.mysql.com/products/enterprise/advisors.html</a>.
</p><div class="itemizedlist"><ul type="disc"><li><p>
The server checks the table for errors.
</p></li><li><p>
If the server finds an error, it tries to do a fast table
repair (with sorting and without re-creating the data file).
</p></li><li><p>
If the repair fails because of an error in the data file (for
example, a duplicate-key error), the server tries again, this
time re-creating the data file.
</p></li><li><p>
If the repair still fails, the server tries once more with the
old repair option method (write row by row without sorting).
This method should be able to repair any type of error and has
low disk space requirements.
</p></li></ul></div><p>
If the recovery wouldn't be able to recover all rows from
previously completed statements and you didn't specify
<code class="literal">FORCE</code> in the value of the
<code class="option">--myisam-recover</code> option, automatic repair aborts
with an error message in the error log:
</p><pre class="programlisting">Error: Couldn't repair table: test.g00pages
</pre><p>
If you specify <code class="literal">FORCE</code>, a warning like this is
written instead:
</p><pre class="programlisting">Warning: Found 344 of 354 rows when repairing ./test/g00pages
</pre><p>
Note that if the automatic recovery value includes
<code class="literal">BACKUP</code>, the recovery process creates files with
names of the form
<code class="filename"><em class="replaceable"><code>tbl_name-datetime</code></em>.BAK</code>.
You should have a <span><strong class="command">cron</strong></span> script that
automatically moves these files from the database directories to
backup media.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="key-space"></a>13.1.2. Space Needed for Keys</h3></div></div></div><a class="indexterm" name="id2895282"></a><p>
<code class="literal">MyISAM</code> tables use B-tree indexes. You can
roughly calculate the size for the index file as
<code class="literal">(key_length+4)/0.67</code>, summed over all keys. This
is for the worst case when all keys are inserted in sorted order
and the table doesn't have any compressed keys.
</p><p>
String indexes are space compressed. If the first index part is a
string, it is also prefix compressed. Space compression makes the
index file smaller than the worst-case figure if a string column
has a lot of trailing space or is a <code class="literal">VARCHAR</code>
column that is not always used to the full length. Prefix
compression is used on keys that start with a string. Prefix
compression helps if there are many strings with an identical
prefix.
</p><p>
In <code class="literal">MyISAM</code> tables, you can also prefix compress
numbers by specifying the <code class="literal">PACK_KEYS=1</code> table
option when you create the table. Numbers are stored with the high
byte first, so this helps when you have many integer keys that
have an identical prefix.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="myisam-table-formats"></a>13.1.3. <code class="literal">MyISAM</code> Table Storage Formats</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#static-format">13.1.3.1. Static (Fixed-Length) Table Characteristics</a></span></dt><dt><span class="section"><a href="storage-engines.html#dynamic-format">13.1.3.2. Dynamic Table Characteristics</a></span></dt><dt><span class="section"><a href="storage-engines.html#compressed-format">13.1.3.3. Compressed Table Characteristics</a></span></dt></dl></div><p>
<code class="literal">MyISAM</code> supports three different storage
formats. Two of them, fixed and dynamic format, are chosen
automatically depending on the type of columns you are using. The
third, compressed format, can be created only with the
<span><strong class="command">myisampack</strong></span> utility (see
<a href="client-utility-programs.html#myisampack" title="7.6. myisampack — Generate Compressed, Read-Only MyISAM Tables">Section 7.6, “<span><strong class="command">myisampack</strong></span> — Generate Compressed, Read-Only MyISAM Tables”</a>).
</p><p>
When you use <code class="literal">CREATE TABLE</code> or <code class="literal">ALTER
TABLE</code> for a table that has no <code class="literal">BLOB</code> or
<code class="literal">TEXT</code> columns, you can force the table format to
<code class="literal">FIXED</code> or <code class="literal">DYNAMIC</code> with the
<code class="literal">ROW_FORMAT</code> table option.
</p><p>
See <a href="sql-syntax.html#create-table" title="12.1.5. CREATE TABLE Syntax">Section 12.1.5, “<code class="literal">CREATE TABLE</code> Syntax”</a>, for information about
<code class="literal">ROW_FORMAT</code>.
</p><p>
You can decompress (unpack) compressed <code class="literal">MyISAM</code>
tables using <span><strong class="command">myisamchk
<code class="option">--unpack</code></strong></span>; see
<a href="client-utility-programs.html#myisamchk" title="7.4. myisamchk — MyISAM Table-Maintenance Utility">Section 7.4, “<span><strong class="command">myisamchk</strong></span> — MyISAM Table-Maintenance Utility”</a>, for more information.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="static-format"></a>13.1.3.1. Static (Fixed-Length) Table Characteristics</h4></div></div></div><p>
Static format is the default for <code class="literal">MyISAM</code>
tables. It is used when the table contains no variable-length
columns (<code class="literal">VARCHAR</code>,
<code class="literal">VARBINARY</code>, <code class="literal">BLOB</code>, or
<code class="literal">TEXT</code>). Each row is stored using a fixed
number of bytes.
</p><p>
Of the three <code class="literal">MyISAM</code> storage formats, static
format is the simplest and most secure (least subject to
corruption). It is also the fastest of the on-disk formats due
to the ease with which rows in the data file can be found on
disk: To look up a row based on a row number in the index,
multiply the row number by the row length to calculate the row
position. Also, when scanning a table, it is very easy to read a
constant number of rows with each disk read operation.
</p><p>
The security is evidenced if your computer crashes while the
MySQL server is writing to a fixed-format
<code class="literal">MyISAM</code> file. In this case,
<span><strong class="command">myisamchk</strong></span> can easily determine where each row
starts and ends, so it can usually reclaim all rows except the
partially written one. Note that <code class="literal">MyISAM</code> table
indexes can always be reconstructed based on the data rows.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Fixed-length row format is only available for tables without
<code class="literal">BLOB</code> or <code class="literal">TEXT</code> columns.
Creating a table with these columns with an explicit
<code class="literal">ROW_FORMAT</code> clause will not raise an error
or warning; the format specification will be ignored.
</p></div><p>
Static-format tables have these characteristics:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">CHAR</code> and <code class="literal">VARCHAR</code>
columns are space-padded to the specified column width,
although the column type is not altered. This is also true
for <code class="literal">NUMERIC</code> and
<code class="literal">DECIMAL</code> columns created before MySQL
5.0.3. <code class="literal">BINARY</code> and
<code class="literal">VARBINARY</code> columns are space-padded to the
column width before MySQL 5.0.15. As of 5.0.15,
<code class="literal">BINARY</code> and <code class="literal">VARBINARY</code>
columns are padded with <code class="literal">0x00</code> bytes.
</p></li><li><p>
Very quick.
</p></li><li><p>
Easy to cache.
</p></li><li><p>
Easy to reconstruct after a crash, because rows are located
in fixed positions.
</p></li><li><p>
Reorganization is unnecessary unless you delete a huge
number of rows and want to return free disk space to the
operating system. To do this, use <code class="literal">OPTIMIZE
TABLE</code> or <span><strong class="command">myisamchk -r</strong></span>.
</p></li><li><p>
Usually require more disk space than dynamic-format tables.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="dynamic-format"></a>13.1.3.2. Dynamic Table Characteristics</h4></div></div></div><a class="indexterm" name="id2895737"></a><a class="indexterm" name="id2895747"></a><p>
Dynamic storage format is used if a <code class="literal">MyISAM</code>
table contains any variable-length columns
(<code class="literal">VARCHAR</code>, <code class="literal">VARBINARY</code>,
<code class="literal">BLOB</code>, or <code class="literal">TEXT</code>), or if the
table was created with the <code class="literal">ROW_FORMAT=DYNAMIC</code>
table option.
</p><p>
Dynamic format is a little more complex than static format
because each row has a header that indicates how long it is. A
row can become fragmented (stored in non-contiguous pieces) when
it is made longer as a result of an update.
</p><a class="indexterm" name="id2895809"></a><p>
You can use <code class="literal">OPTIMIZE TABLE</code> or
<span><strong class="command">myisamchk -r</strong></span> to defragment a table. If you
have fixed-length columns that you access or change frequently
in a table that also contains some variable-length columns, it
might be a good idea to move the variable-length columns to
other tables just to avoid fragmentation.
</p><p>
Dynamic-format tables have these characteristics:
</p><div class="itemizedlist"><ul type="disc"><li><p>
All string columns are dynamic except those with a length
less than four.
</p></li><li><p>
Each row is preceded by a bitmap that indicates which
columns contain the empty string (for string columns) or
zero (for numeric columns). Note that this does not include
columns that contain <code class="literal">NULL</code> values. If a
string column has a length of zero after trailing space
removal, or a numeric column has a value of zero, it is
marked in the bitmap and not saved to disk. Non-empty
strings are saved as a length byte plus the string contents.
</p></li><li><p>
Much less disk space usually is required than for
fixed-length tables.
</p></li><li><p>
Each row uses only as much space as is required. However, if
a row becomes larger, it is split into as many pieces as are
required, resulting in row fragmentation. For example, if
you update a row with information that extends the row
length, the row becomes fragmented. In this case, you may
have to run <code class="literal">OPTIMIZE TABLE</code> or
<span><strong class="command">myisamchk -r</strong></span> from time to time to improve
performance. Use <span><strong class="command">myisamchk -ei</strong></span> to obtain
table statistics.
</p></li><li><p>
More difficult than static-format tables to reconstruct
after a crash, because rows may be fragmented into many
pieces and links (fragments) may be missing.
</p></li><li><p>
The expected row length for dynamic-sized rows is calculated
using the following expression:
</p><pre class="programlisting">3
+ (<em class="replaceable"><code>number of columns</code></em> + 7) / 8
+ (<em class="replaceable"><code>number of char columns</code></em>)
+ (<em class="replaceable"><code>packed size of numeric columns</code></em>)
+ (<em class="replaceable"><code>length of strings</code></em>)
+ (<em class="replaceable"><code>number of NULL columns</code></em> + 7) / 8
</pre><p>
There is a penalty of 6 bytes for each link. A dynamic row
is linked whenever an update causes an enlargement of the
row. Each new link is at least 20 bytes, so the next
enlargement probably goes in the same link. If not, another
link is created. You can find the number of links using
<span><strong class="command">myisamchk -ed</strong></span>. All links may be removed
with <code class="literal">OPTIMIZE TABLE</code> or <span><strong class="command">myisamchk
-r</strong></span>.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="compressed-format"></a>13.1.3.3. Compressed Table Characteristics</h4></div></div></div><a class="indexterm" name="id2896003"></a><a class="indexterm" name="id2896016"></a><a class="indexterm" name="id2896025"></a><a class="indexterm" name="id2896037"></a><p>
Compressed storage format is a read-only format that is
generated with the <span><strong class="command">myisampack</strong></span> tool.
Compressed tables can be uncompressed with
<span><strong class="command">myisamchk</strong></span>.
</p><p>
Compressed tables have the following characteristics:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Compressed tables take very little disk space. This
minimizes disk usage, which is helpful when using slow disks
(such as CD-ROMs).
</p></li><li><p>
Each row is compressed separately, so there is very little
access overhead. The header for a row takes up one to three
bytes depending on the biggest row in the table. Each column
is compressed differently. There is usually a different
Huffman tree for each column. Some of the compression types
are:
</p><div class="itemizedlist"><ul type="circle"><li><p>
Suffix space compression.
</p></li><li><p>
Prefix space compression.
</p></li><li><p>
Numbers with a value of zero are stored using one bit.
</p></li><li><p>
If values in an integer column have a small range, the
column is stored using the smallest possible type. For
example, a <code class="literal">BIGINT</code> column (eight
bytes) can be stored as a <code class="literal">TINYINT</code>
column (one byte) if all its values are in the range
from <code class="literal">-128</code> to <code class="literal">127</code>.
</p></li><li><p>
If a column has only a small set of possible values, the
data type is converted to <code class="literal">ENUM</code>.
</p></li><li><p>
A column may use any combination of the preceding
compression types.
</p></li></ul></div></li><li><p>
Can be used for fixed-length or dynamic-length rows.
</p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
While a compressed table is read only, and you cannot
therefore update or add rows in the table, DDL (Data
Definition Language) operations are still valid. For example,
you may still use <code class="literal">DROP</code> to drop the table,
and <code class="literal">TRUNCATE</code> to empty the table.
</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="myisam-table-problems"></a>13.1.4. <code class="literal">MyISAM</code> Table Problems</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#corrupted-myisam-tables">13.1.4.1. Corrupted <code class="literal">MyISAM</code> Tables</a></span></dt><dt><span class="section"><a href="storage-engines.html#myisam-table-close">13.1.4.2. Problems from Tables Not Being Closed Properly</a></span></dt></dl></div><p>
The file format that MySQL uses to store data has been extensively
tested, but there are always circumstances that may cause database
tables to become corrupted. The following discussion describes how
this can happen and how to handle it.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="corrupted-myisam-tables"></a>13.1.4.1. Corrupted <code class="literal">MyISAM</code> Tables</h4></div></div></div><p>
Even though the <code class="literal">MyISAM</code> table format is very
reliable (all changes to a table made by an SQL statement are
written before the statement returns), you can still get
corrupted tables if any of the following events occur:
</p><div class="itemizedlist"><ul type="disc"><li><p>
The <span><strong class="command">mysqld</strong></span> process is killed in the
middle of a write.
</p></li><li><p>
An unexpected computer shutdown occurs (for example, the
computer is turned off).
</p></li><li><p>
Hardware failures.
</p></li><li><p>
You are using an external program (such as
<span><strong class="command">myisamchk</strong></span>) to modify a table that is
being modified by the server at the same time.
</p></li><li><p>
A software bug in the MySQL or <code class="literal">MyISAM</code>
code.
</p></li></ul></div><p>
Typical symptoms of a corrupt table are:
</p><div class="itemizedlist"><ul type="disc"><li><p>
You get the following error while selecting data from the
table:
</p><pre class="programlisting">Incorrect key file for table: '...'. Try to repair it
</pre></li><li><p>
Queries don't find rows in the table or return incomplete
results.
</p></li></ul></div><p>
You can check the health of a <code class="literal">MyISAM</code> table
using the <code class="literal">CHECK TABLE</code> statement, and repair a
corrupted <code class="literal">MyISAM</code> table with <code class="literal">REPAIR
TABLE</code>. When <span><strong class="command">mysqld</strong></span> is not running,
you can also check or repair a table with the
<span><strong class="command">myisamchk</strong></span> command. See
<a href="sql-syntax.html#check-table" title="12.5.2.3. CHECK TABLE Syntax">Section 12.5.2.3, “<code class="literal">CHECK TABLE</code> Syntax”</a>, <a href="sql-syntax.html#repair-table" title="12.5.2.6. REPAIR TABLE Syntax">Section 12.5.2.6, “<code class="literal">REPAIR TABLE</code> Syntax”</a>,
and <a href="client-utility-programs.html#myisamchk" title="7.4. myisamchk — MyISAM Table-Maintenance Utility">Section 7.4, “<span><strong class="command">myisamchk</strong></span> — MyISAM Table-Maintenance Utility”</a>.
</p><p>
If your tables become corrupted frequently, you should try to
determine why this is happening. The most important thing to
know is whether the table became corrupted as a result of a
server crash. You can verify this easily by looking for a recent
<code class="literal">restarted mysqld</code> message in the error log. If
there is such a message, it is likely that table corruption is a
result of the server dying. Otherwise, corruption may have
occurred during normal operation. This is a bug. You should try
to create a reproducible test case that demonstrates the
problem. See <a href="error-handling.html#crashing" title="B.1.4.2. What to Do If MySQL Keeps Crashing">Section B.1.4.2, “What to Do If MySQL Keeps Crashing”</a>, and
<a href="http://forge.mysql.com/wiki/MySQL_Internals_Porting" target="_top">MySQL
Internals: Porting</a>.
</p><p class="mnmas"><b>MySQL Enterprise</b>
Find out about problems before they occur. Subscribe to the
MySQL Enterprise Monitor for expert advice about the state of
your servers. For more information see
<a href="http://www.mysql.com/products/enterprise/advisors.html" target="_top">http://www.mysql.com/products/enterprise/advisors.html</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="myisam-table-close"></a>13.1.4.2. Problems from Tables Not Being Closed Properly</h4></div></div></div><p>
Each <code class="literal">MyISAM</code> index file
(<code class="filename">.MYI</code> file) has a counter in the header
that can be used to check whether a table has been closed
properly. If you get the following warning from <code class="literal">CHECK
TABLE</code> or <span><strong class="command">myisamchk</strong></span>, it means that
this counter has gone out of sync:
</p><pre class="programlisting">clients are using or haven't closed the table properly
</pre><p>
This warning doesn't necessarily mean that the table is
corrupted, but you should at least check the table.
</p><p>
The counter works as follows:
</p><div class="itemizedlist"><ul type="disc"><li><p>
The first time a table is updated in MySQL, a counter in the
header of the index files is incremented.
</p></li><li><p>
The counter is not changed during further updates.
</p></li><li><p>
When the last instance of a table is closed (because a
<code class="literal">FLUSH TABLES</code> operation was performed or
because there is no room in the table cache), the counter is
decremented if the table has been updated at any point.
</p></li><li><p>
When you repair the table or check the table and it is found
to be okay, the counter is reset to zero.
</p></li><li><p>
To avoid problems with interaction with other processes that
might check the table, the counter is not decremented on
close if it was zero.
</p></li></ul></div><p>
In other words, the counter can become incorrect only under
these conditions:
</p><div class="itemizedlist"><ul type="disc"><li><p>
A <code class="literal">MyISAM</code> table is copied without first
issuing <code class="literal">LOCK TABLES</code> and <code class="literal">FLUSH
TABLES</code>.
</p></li><li><p>
MySQL has crashed between an update and the final close.
(Note that the table may still be okay, because MySQL always
issues writes for everything between each statement.)
</p></li><li><p>
A table was modified by <span><strong class="command">myisamchk
--recover</strong></span> or <span><strong class="command">myisamchk
--update-state</strong></span> at the same time that it was in use
by <span><strong class="command">mysqld</strong></span>.
</p></li><li><p>
Multiple <span><strong class="command">mysqld</strong></span> servers are using the
table and one server performed a <code class="literal">REPAIR
TABLE</code> or <code class="literal">CHECK TABLE</code> on the
table while it was in use by another server. In this setup,
it is safe to use <code class="literal">CHECK TABLE</code>, although
you might get the warning from other servers. However,
<code class="literal">REPAIR TABLE</code> should be avoided because
when one server replaces the data file with a new one, this
is not known to the other servers.
</p><p>
In general, it is a bad idea to share a data directory among
multiple servers. See <a href="server-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>,
for additional discussion.
</p></li></ul></div></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="innodb"></a>13.2. The <code class="literal">InnoDB</code> Storage Engine</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#innodb-overview">13.2.1. <code class="literal">InnoDB</code> Overview</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-contact-information">13.2.2. <code class="literal">InnoDB</code> Contact Information</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-configuration">13.2.3. <code class="literal">InnoDB</code> Configuration</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-parameters">13.2.4. <code class="literal">InnoDB</code> Startup Options and System Variables</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-init">13.2.5. Creating the <code class="literal">InnoDB</code> Tablespace</a></span></dt><dt><span class="section"><a href="storage-engines.html#using-innodb-tables">13.2.6. Creating and Using <code class="literal">InnoDB</code> Tables</a></span></dt><dt><span class="section"><a href="storage-engines.html#adding-and-removing">13.2.7. Adding and Removing <code class="literal">InnoDB</code> Data and Log Files</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-backup">13.2.8. Backing Up and Recovering an <code class="literal">InnoDB</code> Database</a></span></dt><dt><span class="section"><a href="storage-engines.html#moving">13.2.9. Moving an <code class="literal">InnoDB</code> Database to Another Machine</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-transaction-model">13.2.10. <code class="literal">InnoDB</code> Transaction Model and Locking</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-tuning">13.2.11. <code class="literal">InnoDB</code> Performance Tuning Tips</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-multi-versioning">13.2.12. Implementation of Multi-Versioning</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-table-and-index">13.2.13. <code class="literal">InnoDB</code> Table and Index Structures</a></span></dt><dt><span class="section"><a href="storage-engines.html#file-space-management">13.2.14. <code class="literal">InnoDB</code> File Space Management and Disk I/O</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-error-handling">13.2.15. <code class="literal">InnoDB</code> Error Handling</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-restrictions">13.2.16. Restrictions on <code class="literal">InnoDB</code> Tables</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-troubleshooting">13.2.17. <code class="literal">InnoDB</code> Troubleshooting</a></span></dt></dl></div><a class="indexterm" name="id2896732"></a><a class="indexterm" name="id2896741"></a><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-overview"></a>13.2.1. <code class="literal">InnoDB</code> Overview</h3></div></div></div><a class="indexterm" name="id2896774"></a><a class="indexterm" name="id2896783"></a><a class="indexterm" name="id2896796"></a><a class="indexterm" name="id2896805"></a><p>
<code class="literal">InnoDB</code> provides MySQL with a transaction-safe
(<code class="literal">ACID</code> compliant) storage engine that has
commit, rollback, and crash recovery capabilities.
<code class="literal">InnoDB</code> does locking on the row level and also
provides an Oracle-style consistent non-locking read in
<code class="literal">SELECT</code> statements. These features increase
multi-user concurrency and performance. There is no need for lock
escalation in <code class="literal">InnoDB</code> because row-level locks
fit in very little space. <code class="literal">InnoDB</code> also supports
<code class="literal">FOREIGN KEY</code> constraints. You can freely mix
<code class="literal">InnoDB</code> tables with tables from other MySQL
storage engines, even within the same statement.
</p><p>
<code class="literal">InnoDB</code> has been designed for maximum
performance when processing large data volumes. Its CPU efficiency
is probably not matched by any other disk-based relational
database engine.
</p><p>
Fully integrated with MySQL Server, the <code class="literal">InnoDB</code>
storage engine maintains its own buffer pool for caching data and
indexes in main memory. <code class="literal">InnoDB</code> stores its
tables and indexes in a tablespace, which may consist of several
files (or raw disk partitions). This is different from, for
example, <code class="literal">MyISAM</code> tables where each table is
stored using separate files. <code class="literal">InnoDB</code> tables can
be of any size even on operating systems where file size is
limited to 2GB.
</p><p>
<code class="literal">InnoDB</code> is included in binary distributions by
default. The Windows Essentials installer makes
<code class="literal">InnoDB</code> the MySQL default storage engine on
Windows.
</p><p>
<code class="literal">InnoDB</code> is used in production at numerous large
database sites requiring high performance. The famous Internet
news site Slashdot.org runs on <code class="literal">InnoDB</code>. Mytrix,
Inc. stores over 1TB of data in <code class="literal">InnoDB</code>, and
another site handles an average load of 800 inserts/updates per
second in <code class="literal">InnoDB</code>.
</p><p>
<code class="literal">InnoDB</code> is published under the same GNU GPL
License Version 2 (of June 1991) as MySQL. For more information on
MySQL licensing, see
<a href="http://www.mysql.com/company/legal/licensing/" target="_top">http://www.mysql.com/company/legal/licensing/</a>.
</p><p>
<span class="bold"><strong>Additional resources</strong></span>
</p><div class="itemizedlist"><ul type="disc"><li><p>
A forum dedicated to the <code class="literal">InnoDB</code> storage
engine is available at
<a href="http://forums.mysql.com/list.php?22" target="_top">http://forums.mysql.com/list.php?22</a>.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-contact-information"></a>13.2.2. <code class="literal">InnoDB</code> Contact Information</h3></div></div></div><p>
Contact information for Innobase Oy, producer of the
<code class="literal">InnoDB</code> engine:
</p><pre class="programlisting">Web site: <a href="http://www.innodb.com/" target="_top">http://www.innodb.com/</a>
Email: <code class="email"><<a href="mailto:sales@innodb.com">sales@innodb.com</a>></code>
Phone: +358-9-6969 3250 (office)
+358-40-5617367 (mobile)
Innobase Oy Inc.
World Trade Center Helsinki
Aleksanterinkatu 17
P.O.Box 800
00101 Helsinki
Finland
</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-configuration"></a>13.2.3. <code class="literal">InnoDB</code> Configuration</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#multiple-tablespaces">13.2.3.1. Using Per-Table Tablespaces</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-raw-devices">13.2.3.2. Using Raw Devices for the Shared Tablespace</a></span></dt></dl></div><p>
The <code class="literal">InnoDB</code> storage engine is enabled by
default. If you don't want to use <code class="literal">InnoDB</code>
tables, you can add the <code class="literal">skip-innodb</code> option to
your MySQL option file.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
<code class="literal">InnoDB</code> provides MySQL with a transaction-safe
(<code class="literal">ACID</code> compliant) storage engine that has
commit, rollback, and crash recovery capabilities.
<span class="bold"><strong>However, it cannot do so</strong></span> if the
underlying operating system or hardware does not work as
advertised. Many operating systems or disk subsystems may delay
or reorder write operations to improve performance. On some
operating systems, the very system call that should wait until
all unwritten data for a file has been flushed —
<code class="literal">fsync()</code> — might actually return before
the data has been flushed to stable storage. Because of this, an
operating system crash or a power outage may destroy recently
committed data, or in the worst case, even corrupt the database
because of write operations having been reordered. If data
integrity is important to you, you should perform some
“<span class="quote">pull-the-plug</span>” tests before using anything in
production. On Mac OS X 10.3 and up, <code class="literal">InnoDB</code>
uses a special <code class="literal">fcntl()</code> file flush method.
Under Linux, it is advisable to <span class="bold"><strong>disable
the write-back cache</strong></span>.
</p></div><p>
On ATAPI hard disks, a command such <code class="literal">hdparm -W0
/dev/hda</code> may work to disable the write-back cache.
<span class="bold"><strong>Beware that some drives or disk controllers
may be unable to disable the write-back cache.</strong></span>
</p><p>
Two important disk-based resources managed by the
<code class="literal">InnoDB</code> storage engine are its tablespace data
files and its log files.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
If you specify no <code class="literal">InnoDB</code> configuration
options, MySQL creates an auto-extending 10MB data file named
<code class="filename">ibdata1</code> and two 5MB log files named
<code class="filename">ib_logfile0</code> and
<code class="filename">ib_logfile1</code> in the MySQL data directory. To
get good performance, you should explicitly provide
<code class="literal">InnoDB</code> parameters as discussed in the
following examples. Naturally, you should edit the settings to
suit your hardware and requirements.
</p></div><a class="indexterm" name="id2897250"></a><a class="indexterm" name="id2897263"></a><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
It is not a good idea to configure <code class="literal">InnoDB</code> to
use datafiles or logfiles on NFS volumes. Otherwise, the files
might be locked by other processes and become unavailable for
use by MySQL.
</p></div><p class="mnmas"><b>MySQL Enterprise</b>
For advice on settings suitable to your specific circumstances,
subscribe to the MySQL Enterprise Monitor. For more information
see <a href="http://www.mysql.com/products/enterprise/advisors.html" target="_top">http://www.mysql.com/products/enterprise/advisors.html</a>.
</p><p>
The examples shown here are representative. See
<a href="storage-engines.html#innodb-parameters" title="13.2.4. InnoDB Startup Options and System Variables">Section 13.2.4, “<code class="literal">InnoDB</code> Startup Options and System Variables”</a> for additional information
about <code class="literal">InnoDB</code>-related configuration parameters.
</p><p>
To set up the <code class="literal">InnoDB</code> tablespace files, use the
<code class="literal">innodb_data_file_path</code> option in the
<code class="literal">[mysqld]</code> section of the
<code class="filename">my.cnf</code> option file. On Windows, you can use
<code class="filename">my.ini</code> instead. The value of
<code class="literal">innodb_data_file_path</code> should be a list of one
or more data file specifications. If you name more than one data
file, separate them by semicolon
(“<span class="quote"><code class="literal">;</code></span>”) characters:
</p><pre class="programlisting">innodb_data_file_path=<em class="replaceable"><code>datafile_spec1</code></em>[;<em class="replaceable"><code>datafile_spec2</code></em>]...
</pre><p>
For example, a setting that explicitly creates a tablespace having
the same characteristics as the default is as follows:
</p><pre class="programlisting">[mysqld]
innodb_data_file_path=ibdata1:10M:autoextend
</pre><p>
This setting configures a single 10MB data file named
<code class="filename">ibdata1</code> that is auto-extending. No location
for the file is given, so by default, <code class="literal">InnoDB</code>
creates it in the MySQL data directory.
</p><p>
Sizes are specified using <code class="literal">M</code> or
<code class="literal">G</code> suffix letters to indicate units of MB or GB.
</p><p>
A tablespace containing a fixed-size 50MB data file named
<code class="filename">ibdata1</code> and a 50MB auto-extending file named
<code class="filename">ibdata2</code> in the data directory can be
configured like this:
</p><pre class="programlisting">[mysqld]
innodb_data_file_path=ibdata1:50M;ibdata2:50M:autoextend
</pre><p>
The full syntax for a data file specification includes the
filename, its size, and several optional attributes:
</p><pre class="programlisting"><em class="replaceable"><code>file_name</code></em>:<em class="replaceable"><code>file_size</code></em>[:autoextend[:max:<em class="replaceable"><code>max_file_size</code></em>]]
</pre><p>
The <code class="literal">autoextend</code> attribute and those following
can be used only for the last data file in the
<code class="literal">innodb_data_file_path</code> line.
</p><p>
If you specify the <code class="literal">autoextend</code> option for the
last data file, <code class="literal">InnoDB</code> extends the data file if
it runs out of free space in the tablespace. The increment is 8MB
at a time by default. It can be modified by changing the
<code class="literal">innodb_autoextend_increment</code> system variable.
</p><p>
If the disk becomes full, you might want to add another data file
on another disk. Instructions for reconfiguring an existing
tablespace are given in <a href="storage-engines.html#adding-and-removing" title="13.2.7. Adding and Removing InnoDB Data and Log Files">Section 13.2.7, “Adding and Removing <code class="literal">InnoDB</code> Data and Log Files”</a>.
</p><p>
<code class="literal">InnoDB</code> is not aware of the filesystem maximum
file size, so be cautious on filesystems where the maximum file
size is a small value such as 2GB. To specify a maximum size for
an auto-extending data file, use the <code class="literal">max</code>
attribute. The following configuration allows
<code class="filename">ibdata1</code> to grow up to a limit of 500MB:
</p><pre class="programlisting">[mysqld]
innodb_data_file_path=ibdata1:10M:autoextend:max:500M
</pre><p>
<code class="literal">InnoDB</code> creates tablespace files in the MySQL
data directory by default. To specify a location explicitly, use
the <code class="literal">innodb_data_home_dir</code> option. For example,
to use two files named <code class="filename">ibdata1</code> and
<code class="filename">ibdata2</code> but create them in the
<code class="filename">/ibdata</code> directory, configure
<code class="literal">InnoDB</code> like this:
</p><pre class="programlisting">[mysqld]
innodb_data_home_dir = /ibdata
innodb_data_file_path=ibdata1:50M;ibdata2:50M:autoextend
</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
<code class="literal">InnoDB</code> does not create directories, so make
sure that the <code class="filename">/ibdata</code> directory exists
before you start the server. This is also true of any log file
directories that you configure. Use the Unix or DOS
<code class="literal">mkdir</code> command to create any necessary
directories.
</p></div><p>
<code class="literal">InnoDB</code> forms the directory path for each data
file by textually concatenating the value of
<code class="literal">innodb_data_home_dir</code> to the data file name,
adding a pathname separator (slash or backslash) between values if
necessary. If the <code class="literal">innodb_data_home_dir</code> option
is not mentioned in <code class="filename">my.cnf</code> at all, the
default value is the “<span class="quote">dot</span>” directory
<code class="filename">./</code>, which means the MySQL data directory.
(The MySQL server changes its current working directory to its
data directory when it begins executing.)
</p><p>
If you specify <code class="literal">innodb_data_home_dir</code> as an empty
string, you can specify absolute paths for the data files listed
in the <code class="literal">innodb_data_file_path</code> value. The
following example is equivalent to the preceding one:
</p><pre class="programlisting">[mysqld]
innodb_data_home_dir =
innodb_data_file_path=/ibdata/ibdata1:50M;/ibdata/ibdata2:50M:autoextend
</pre><p>
<span class="bold"><strong>A simple <code class="filename">my.cnf</code>
example.</strong></span> Suppose that you have a computer with 128MB
RAM and one hard disk. The following example shows possible
configuration parameters in <code class="filename">my.cnf</code> or
<code class="filename">my.ini</code> for <code class="literal">InnoDB</code>,
including the <code class="literal">autoextend</code> attribute. The example
suits most users, both on Unix and Windows, who do not want to
distribute <code class="literal">InnoDB</code> data files and log files onto
several disks. It creates an auto-extending data file
<code class="filename">ibdata1</code> and two <code class="literal">InnoDB</code> log
files <code class="filename">ib_logfile0</code> and
<code class="filename">ib_logfile1</code> in the MySQL data directory.
</p><pre class="programlisting">[mysqld]
# You can write your other MySQL server options here
# ...
# Data files must be able to hold your data and indexes.
# Make sure that you have enough free disk space.
innodb_data_file_path = ibdata1:10M:autoextend
#
# Set buffer pool size to 50-80% of your computer's memory
innodb_buffer_pool_size=70M
innodb_additional_mem_pool_size=10M
#
# Set the log file size to about 25% of the buffer pool size
innodb_log_file_size=20M
innodb_log_buffer_size=8M
#
innodb_flush_log_at_trx_commit=1
</pre><p>
Make sure that the MySQL server has the proper access rights to
create files in the data directory. More generally, the server
must have access rights in any directory where it needs to create
data files or log files.
</p><p>
Note that data files must be less than 2GB in some filesystems.
The combined size of the log files must be less than 4GB. The
combined size of data files must be at least 10MB.
</p><p>
When you create an <code class="literal">InnoDB</code> tablespace for the
first time, it is best that you start the MySQL server from the
command prompt. <code class="literal">InnoDB</code> then prints the
information about the database creation to the screen, so you can
see what is happening. For example, on Windows, if
<span><strong class="command">mysqld</strong></span> is located in <code class="filename">C:\Program
Files\MySQL\MySQL Server 5.0\bin</code>, you can
start it like this:
</p><pre class="programlisting">C:\> <strong class="userinput"><code>"C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld" --console</code></strong>
</pre><p>
If you do not send server output to the screen, check the server's
error log to see what <code class="literal">InnoDB</code> prints during the
startup process.
</p><p>
See <a href="storage-engines.html#innodb-init" title="13.2.5. Creating the InnoDB Tablespace">Section 13.2.5, “Creating the <code class="literal">InnoDB</code> Tablespace”</a>, for an example of what the
information displayed by <code class="literal">InnoDB</code> should look
like.
</p><p>
You can place <code class="literal">InnoDB</code> options in the
<code class="literal">[mysqld]</code> group of any option file that your
server reads when it starts. The locations for option files are
described 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><p>
If you installed MySQL on Windows using the installation and
configuration wizards, the option file will be the
<code class="filename">my.ini</code> file located in your MySQL
installation directory. See
<a href="installing.html#mysql-config-wizard-starting-windows" title="2.4.8.4.1.1. The MySQL Server Configuration Wizard on Windows">Section 2.4.8.4.1.1, “The MySQL Server Configuration Wizard on Windows”</a>.
</p><p>
If your PC uses a boot loader where the <code class="filename">C:</code>
drive is not the boot drive, your only option is to use the
<code class="filename">my.ini</code> file in your Windows directory
(typically <code class="filename">C:\WINDOWS</code>). You can use the
<code class="literal">SET</code> command at the command prompt in a console
window to print the value of <code class="literal">WINDIR</code>:
</p><pre class="programlisting">C:\> <strong class="userinput"><code>SET WINDIR</code></strong>
windir=C:\WINDOWS
</pre><p>
If you want to make sure that <span><strong class="command">mysqld</strong></span> reads
options only from a specific file, you can use the
<code class="option">--defaults-file</code> option as the first option on the
command line when starting the server:
</p><pre class="programlisting">mysqld --defaults-file=<em class="replaceable"><code>your_path_to_my_cnf</code></em>
</pre><p>
<span class="bold"><strong>An advanced <code class="filename">my.cnf</code>
example.</strong></span> Suppose that you have a Linux computer with
2GB RAM and three 60GB hard disks at directory paths
<code class="filename">/</code>, <code class="filename">/dr2</code> and
<code class="filename">/dr3</code>. The following example shows possible
configuration parameters in <code class="filename">my.cnf</code> for
<code class="literal">InnoDB</code>.
</p><pre class="programlisting">[mysqld]
# You can write your other MySQL server options here
# ...
innodb_data_home_dir =
#
# Data files must be able to hold your data and indexes
innodb_data_file_path = /ibdata/ibdata1:2000M;/dr2/ibdata/ibdata2:2000M:autoextend
#
# Set buffer pool size to 50-80% of your computer's memory,
# but make sure on Linux x86 total memory usage is < 2GB
innodb_buffer_pool_size=1G
innodb_additional_mem_pool_size=20M
innodb_log_group_home_dir = /dr3/iblogs
#
innodb_log_files_in_group = 2
#
# Set the log file size to about 25% of the buffer pool size
innodb_log_file_size=250M
innodb_log_buffer_size=8M
#
innodb_flush_log_at_trx_commit=1
innodb_lock_wait_timeout=50
#
# Uncomment the next lines if you want to use them
#innodb_thread_concurrency=5
</pre><p>
In some cases, database performance improves if all the data is
not placed on the same physical disk. Putting log files on a
different disk from data is very often beneficial for performance.
The example illustrates how to do this. It places the two data
files on different disks and places the log files on the third
disk. <code class="literal">InnoDB</code> fills the tablespace beginning
with the first data file. You can also use raw disk partitions
(raw devices) as <code class="literal">InnoDB</code> data files, which may
speed up I/O. See <a href="storage-engines.html#innodb-raw-devices" title="13.2.3.2. Using Raw Devices for the Shared Tablespace">Section 13.2.3.2, “Using Raw Devices for the Shared Tablespace”</a>.
</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
On 32-bit GNU/Linux x86, you must be careful not to set memory
usage too high. <code class="literal">glibc</code> may allow the process
heap to grow over thread stacks, which crashes your server. It
is a risk if the value of the following expression is close to
or exceeds 2GB:
</p></div><pre class="programlisting">innodb_buffer_pool_size
+ key_buffer_size
+ max_connections*(sort_buffer_size+read_buffer_size+binlog_cache_size)
+ max_connections*2MB
</pre><p>
Each thread uses a stack (often 2MB, but only 256KB in MySQL AB
binaries) and in the worst case also uses
<code class="literal">sort_buffer_size + read_buffer_size</code> additional
memory.
</p><p>
By compiling MySQL yourself, you can use up to 64GB of physical
memory in 32-bit Windows. See the description for
<code class="literal">innodb_buffer_pool_awe_mem_mb</code> in
<a href="storage-engines.html#innodb-parameters" title="13.2.4. InnoDB Startup Options and System Variables">Section 13.2.4, “<code class="literal">InnoDB</code> Startup Options and System Variables”</a>.
</p><p>
<span class="bold"><strong>How to tune other <span><strong class="command">mysqld</strong></span>
server parameters?</strong></span> The following values are typical and
suit most users:
</p><pre class="programlisting">[mysqld]
skip-external-locking
max_connections=200
read_buffer_size=1M
sort_buffer_size=1M
#
# Set key_buffer to 5 - 50% of your RAM depending on how much
# you use MyISAM tables, but keep key_buffer_size + InnoDB
# buffer pool size < 80% of your RAM
key_buffer_size=<em class="replaceable"><code>value</code></em>
</pre><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="multiple-tablespaces"></a>13.2.3.1. Using Per-Table Tablespaces</h4></div></div></div><p>
You can store each <code class="literal">InnoDB</code> table and its
indexes in its own file. This feature is called “<span class="quote">multiple
tablespaces</span>” because in effect each table has its own
tablespace.
</p><p>
Using multiple tablespaces can be beneficial to users who want
to move specific tables to separate physical disks or who wish
to restore backups of single tables quickly without interrupting
the use of the remaining <code class="literal">InnoDB</code> tables.
</p><p>
You can enable multiple tablespaces by adding this line to the
<code class="literal">[mysqld]</code> section of
<code class="filename">my.cnf</code>:
</p><pre class="programlisting">[mysqld]
innodb_file_per_table
</pre><p>
After restarting the server, <code class="literal">InnoDB</code> stores
each newly created table into its own file
<code class="filename"><em class="replaceable"><code>tbl_name</code></em>.ibd</code> in
the database directory where the table belongs. This is similar
to what the <code class="literal">MyISAM</code> storage engine does, but
<code class="literal">MyISAM</code> divides the table into a data file
<code class="filename"><em class="replaceable"><code>tbl_name</code></em>.MYD</code> and
the index file
<code class="filename"><em class="replaceable"><code>tbl_name</code></em>.MYI</code>.
For <code class="literal">InnoDB</code>, the data and the indexes are
stored together in the <code class="filename">.ibd</code> file. The
<code class="filename"><em class="replaceable"><code>tbl_name</code></em>.frm</code>
file is still created as usual.
</p><p>
If you remove the <code class="literal">innodb_file_per_table</code> line
from <code class="filename">my.cnf</code> and restart the server,
<code class="literal">InnoDB</code> creates tables inside the shared
tablespace files again.
</p><p>
<code class="literal">innodb_file_per_table</code> affects only table
creation, not access to existing tables. If you start the server
with this option, new tables are created using
<code class="filename">.ibd</code> files, but you can still access tables
that exist in the shared tablespace. If you remove the option
and restart the server, new tables are created in the shared
tablespace, but you can still access any tables that were
created using multiple tablespaces.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
<code class="literal">InnoDB</code> always needs the shared tablespace
because it puts its internal data dictionary and undo logs
there. The <code class="filename">.ibd</code> files are not sufficient
for <code class="literal">InnoDB</code> to operate.
</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
You cannot freely move <code class="filename">.ibd</code> files between
database directories as you can with <code class="literal">MyISAM</code>
table files. This is because the table definition that is
stored in the <code class="literal">InnoDB</code> shared tablespace
includes the database name, and because
<code class="literal">InnoDB</code> must preserve the consistency of
transaction IDs and log sequence numbers.
</p></div><p>
To move an <code class="filename">.ibd</code> file and the associated
table from one database to another, use a <code class="literal">RENAME
TABLE</code> statement:
</p><pre class="programlisting">RENAME TABLE <em class="replaceable"><code>db1.tbl_name</code></em> TO <em class="replaceable"><code>db2.tbl_name</code></em>;
</pre><a class="indexterm" name="id2898495"></a><a class="indexterm" name="id2898504"></a><p>
If you have a “<span class="quote">clean</span>” backup of an
<code class="filename">.ibd</code> file, you can restore it to the MySQL
installation from which it originated as follows:
</p><div class="orderedlist"><ol type="1"><li><p>
Issue this <code class="literal">ALTER TABLE</code> statement:
</p><pre class="programlisting">ALTER TABLE <em class="replaceable"><code>tbl_name</code></em> DISCARD TABLESPACE;
</pre><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p>
This statement deletes the current
<code class="filename">.ibd</code> file.
</p></div></li><li><p>
Put the backup <code class="filename">.ibd</code> file back in the
proper database directory.
</p></li><li><p>
Issue this <code class="literal">ALTER TABLE</code> statement:
</p><pre class="programlisting">ALTER TABLE <em class="replaceable"><code>tbl_name</code></em> IMPORT TABLESPACE;
</pre></li></ol></div><p>
In this context, a “<span class="quote">clean</span>”
<code class="filename">.ibd</code> file backup means:
</p><div class="itemizedlist"><ul type="disc"><li><p>
There are no uncommitted modifications by transactions in
the <code class="filename">.ibd</code> file.
</p></li><li><p>
There are no unmerged insert buffer entries in the
<code class="filename">.ibd</code> file.
</p></li><li><p>
Purge has removed all delete-marked index records from the
<code class="filename">.ibd</code> file.
</p></li><li><p>
<span><strong class="command">mysqld</strong></span> has flushed all modified pages of
the <code class="filename">.ibd</code> file from the buffer pool to
the file.
</p></li></ul></div><p>
You can make a clean backup <code class="filename">.ibd</code> file using
the following method:
</p><div class="orderedlist"><ol type="1"><li><p>
Stop all activity from the <span><strong class="command">mysqld</strong></span> server
and commit all transactions.
</p></li><li><p>
Wait until <code class="literal">SHOW ENGINE INNODB STATUS</code>
shows that there are no active transactions in the database,
and the main thread status of <code class="literal">InnoDB</code> is
<code class="literal">Waiting for server activity</code>. Then you can
make a copy of the <code class="filename">.ibd</code> file.
</p></li></ol></div><p>
Another method for making a clean copy of an
<code class="filename">.ibd</code> file is to use the commercial
<span><strong class="command">InnoDB Hot Backup</strong></span> tool:
</p><div class="orderedlist"><ol type="1"><li><p>
Use <span><strong class="command">InnoDB Hot Backup</strong></span> to back up the
<code class="literal">InnoDB</code> installation.
</p></li><li><p>
Start a second <span><strong class="command">mysqld</strong></span> server on the
backup and let it clean up the <code class="filename">.ibd</code>
files in the backup.
</p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-raw-devices"></a>13.2.3.2. Using Raw Devices for the Shared Tablespace</h4></div></div></div><p>
You can use raw disk partitions as data files in the shared
tablespace. By using a raw disk, you can perform non-buffered
I/O on Windows and on some Unix systems without filesystem
overhead, which may improve performance.
</p><p>
When you create a new data file, you must put the keyword
<code class="literal">newraw</code> immediately after the data file size
in <code class="literal">innodb_data_file_path</code>. The partition must
be at least as large as the size that you specify. Note that 1MB
in <code class="literal">InnoDB</code> is 1024 × 1024 bytes, whereas
1MB in disk specifications usually means 1,000,000 bytes.
</p><pre class="programlisting">[mysqld]
innodb_data_home_dir=
innodb_data_file_path=/dev/hdd1:3Gnewraw;/dev/hdd2:2Gnewraw
</pre><p>
The next time you start the server, <code class="literal">InnoDB</code>
notices the <code class="literal">newraw</code> keyword and initializes
the new partition. However, do not create or change any
<code class="literal">InnoDB</code> tables yet. Otherwise, when you next
restart the server, <code class="literal">InnoDB</code> reinitializes the
partition and your changes are lost. (As a safety measure
<code class="literal">InnoDB</code> prevents users from modifying data
when any partition with <code class="literal">newraw</code> is specified.)
</p><p>
After <code class="literal">InnoDB</code> has initialized the new
partition, stop the server, change <code class="literal">newraw</code> in
the data file specification to <code class="literal">raw</code>:
</p><pre class="programlisting">[mysqld]
innodb_data_home_dir=
innodb_data_file_path=/dev/hdd1:5Graw;/dev/hdd2:2Graw
</pre><p>
Then restart the server and <code class="literal">InnoDB</code> allows
changes to be made.
</p><p>
On Windows, you can allocate a disk partition as a data file
like this:
</p><pre class="programlisting">[mysqld]
innodb_data_home_dir=
innodb_data_file_path=//./D::10Gnewraw
</pre><p>
The <code class="filename">//./</code> corresponds to the Windows syntax
of <code class="filename">\\.\</code> for accessing physical drives.
</p><p>
When you use raw disk partitions, be sure that they have
permissions that allow read and write access by the account used
for running the MySQL server.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-parameters"></a>13.2.4. <code class="literal">InnoDB</code> Startup Options and System Variables</h3></div></div></div><p>
This section describes the <code class="literal">InnoDB</code>-related
command options and system variables. System variables that are
true or false can be enabled at server startup by naming them, or
disabled by using a <code class="literal">skip-</code> prefix. For example,
to enable or disable <code class="literal">InnoDB</code> checksums, you can
use <code class="option">--innodb_checksums</code> or
<code class="option">--skip-innodb_checksums</code> on the command line, or
<code class="literal">innodb_checksums</code> or
<code class="literal">skip-innodb_checksums</code> in an option file. System
variables that take a numeric value can be specified as
<code class="option">--<em class="replaceable"><code>var_name</code></em>=<em class="replaceable"><code>value</code></em></code>
on the command line or as
<code class="literal"><em class="replaceable"><code>var_name</code></em>=<em class="replaceable"><code>value</code></em></code>
in option files. For more information on specifying options and
system variables, see <a href="using-mysql-programs.html#program-options" title="4.3. Specifying Program Options">Section 4.3, “Specifying Program Options”</a>. Many of
the system variables can be changed at runtime (see
<a href="server-administration.html#dynamic-system-variables" title="5.2.4.2. Dynamic System Variables">Section 5.2.4.2, “Dynamic System Variables”</a>).
</p><p class="mnmas"><b>MySQL Enterprise</b>
The MySQL Enterprise Monitor provides expert advice on InnoDB
start-up options and related system variables. For more
information see
<a href="http://www.mysql.com/products/enterprise/advisors.html" target="_top">http://www.mysql.com/products/enterprise/advisors.html</a>.
</p><div class="informaltable"><table border="1"><colgroup><col><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th><span class="bold"><strong>Name</strong></span></th><th align="center"><span class="bold"><strong>Cmd-line</strong></span></th><th align="center"><span class="bold"><strong>Option file</strong></span></th><th align="center"><span class="bold"><strong>System Var</strong></span></th><th align="center"><span class="bold"><strong>Status Var</strong></span></th><th align="center"><span class="bold"><strong>Var Scope</strong></span></th><th align="center"><span class="bold"><strong>Dynamic</strong></span></th></tr></thead><tbody><tr><td><a href="server-administration.html#option_mysqld_Com_option_mysqld">Com_show_innodb_status</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Com_option_mysqld">Com_show_ndb_status</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td>foreign_key_checks</td><td align="center">Y</td><td align="center"> </td><td align="center">Y</td><td align="center"> </td><td align="center">session</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_have_innodb">have_innodb</a></td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb">innodb</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td><a href="server-administration.html#option_mysqld_innodb-safe-binlog">innodb-safe-binlog</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_additional_mem_pool_size">innodb_additional_mem_pool_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_autoextend_increment">innodb_autoextend_increment</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_buffer_pool_awe_mem_mb">innodb_buffer_pool_awe_mem_mb</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_pages_data">Innodb_buffer_pool_pages_data</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_pages_dirty">Innodb_buffer_pool_pages_dirty</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_pages_flushed">Innodb_buffer_pool_pages_flushed</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_pages_free">Innodb_buffer_pool_pages_free</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_pages_latched">Innodb_buffer_pool_pages_latched</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_pages_misc">Innodb_buffer_pool_pages_misc</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_pages_total">Innodb_buffer_pool_pages_total</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_read_ahead_rnd">Innodb_buffer_pool_read_ahead_rnd</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_read_ahead_seq">Innodb_buffer_pool_read_ahead_seq</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_read_requests">Innodb_buffer_pool_read_requests</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_reads">Innodb_buffer_pool_reads</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_buffer_pool_size">innodb_buffer_pool_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_wait_free">Innodb_buffer_pool_wait_free</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_buffer_pool_write_requests">Innodb_buffer_pool_write_requests</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_checksums">innodb_checksums</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_commit_concurrency">innodb_commit_concurrency</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_concurrency_tickets">innodb_concurrency_tickets</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_data_file_path">innodb_data_file_path</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_data_fsyncs">Innodb_data_fsyncs</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_data_home_dir">innodb_data_home_dir</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_data_pending_fsyncs">Innodb_data_pending_fsyncs</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_data_pending_reads">Innodb_data_pending_reads</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_data_pending_writes">Innodb_data_pending_writes</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_data_read">Innodb_data_read</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_data_reads">Innodb_data_reads</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_data_writes">Innodb_data_writes</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_data_written">Innodb_data_written</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td>Innodb_dblwr_pages_written</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td>Innodb_dblwr_writes</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_doublewrite">innodb_doublewrite</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_fast_shutdown">innodb_fast_shutdown</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_file_io_threads">innodb_file_io_threads</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_file_per_table">innodb_file_per_table</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_flush_log_at_trx_commit">innodb_flush_log_at_trx_commit</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_flush_method">innodb_flush_method</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_force_recovery">innodb_force_recovery</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_lock_wait_timeout">innodb_lock_wait_timeout</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_locks_unsafe_for_binlog">innodb_locks_unsafe_for_binlog</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td>innodb_log_arch_dir</td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_log_archive">innodb_log_archive</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_log_buffer_size">innodb_log_buffer_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_log_file_size">innodb_log_file_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_log_files_in_group">innodb_log_files_in_group</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_log_group_home_dir">innodb_log_group_home_dir</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_log_waits">Innodb_log_waits</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_log_write_requests">Innodb_log_write_requests</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_log_writes">Innodb_log_writes</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_max_dirty_pages_pct">innodb_max_dirty_pages_pct</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_max_purge_lag">innodb_max_purge_lag</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_mirrored_log_groups">innodb_mirrored_log_groups</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_open_files">innodb_open_files</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_os_log_fsyncs">Innodb_os_log_fsyncs</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_os_log_pending_fsyncs">Innodb_os_log_pending_fsyncs</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_os_log_pending_writes">Innodb_os_log_pending_writes</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_os_log_written">Innodb_os_log_written</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_page_size">Innodb_page_size</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_pages_created">Innodb_pages_created</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_pages_read">Innodb_pages_read</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_pages_written">Innodb_pages_written</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_rollback_on_timeout">innodb_rollback_on_timeout</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_row_lock_current_waits">Innodb_row_lock_current_waits</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_row_lock_time">Innodb_row_lock_time</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_row_lock_time_avg">Innodb_row_lock_time_avg</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_row_lock_time_max">Innodb_row_lock_time_max</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_row_lock_waits">Innodb_row_lock_waits</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_rows_deleted">Innodb_rows_deleted</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_rows_inserted">Innodb_rows_inserted</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_rows_read">Innodb_rows_read</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_Innodb_rows_updated">Innodb_rows_updated</a></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center">both</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_status_file">innodb_status_file</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_support_xa">innodb_support_xa</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">both</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_sync_spin_loops">innodb_sync_spin_loops</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_table_locks">innodb_table_locks</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">both</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_thread_concurrency">innodb_thread_concurrency</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_thread_sleep_delay">innodb_thread_sleep_delay</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_skip-innodb">skip-innodb</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td><a href="storage-engines.html#option_mysqld_innodb_checksums">skip-innodb-checksums</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td><a href="server-administration.html#option_mysqld_sync_binlog">sync-binlog</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td><a href="server-administration.html#option_mysqld_timed_mutexes">timed_mutexes</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">yes</td></tr><tr><td>unique_checks</td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">session</td><td align="center">yes</td></tr></tbody></table></div><p>
<code class="literal">InnoDB</code> command options:
</p><div class="itemizedlist"><ul type="disc"><li><p><a name="option_mysqld_innodb"></a>
<a class="indexterm" name="id2901603"></a>
<a class="indexterm" name="id2901616"></a>
<code class="option">--innodb</code>
</p><p>
Enables the <code class="literal">InnoDB</code> storage engine, if the
server was compiled with <code class="literal">InnoDB</code> support.
Use <code class="option">--skip-innodb</code> to disable
<code class="literal">InnoDB</code>.
</p></li><li><p><a name="option_mysqld_innodb_status_file"></a>
<a class="indexterm" name="id2901668"></a>
<a class="indexterm" name="id2901680"></a>
<code class="option">--innodb_status_file</code>
</p><p>
Causes <code class="literal">InnoDB</code> to create a file named
<code class="filename"><em class="replaceable"><code><datadir></code></em>/innodb_status.<em class="replaceable"><code><pid></code></em></code>
in the MySQL data directory. <code class="literal">InnoDB</code>
periodically writes the output of <code class="literal">SHOW ENGINE INNODB
STATUS</code> to this file.
</p></li></ul></div><p>
<code class="literal">InnoDB</code> system variables:
</p><div class="itemizedlist"><ul type="disc"><li><p><a name="option_mysqld_innodb_additional_mem_pool_size"></a>
<code class="literal">innodb_additional_mem_pool_size</code>
</p><p>
The size in bytes of a memory pool <code class="literal">InnoDB</code>
uses to store data dictionary information and other internal
data structures. The more tables you have in your application,
the more memory you need to allocate here. If
<code class="literal">InnoDB</code> runs out of memory in this pool, it
starts to allocate memory from the operating system and writes
warning messages to the MySQL error log. The default value is
1MB.
</p></li><li><p><a name="option_mysqld_innodb_autoextend_increment"></a>
<code class="literal">innodb_autoextend_increment</code>
</p><p>
The increment size (in MB) for extending the size of an
auto-extending tablespace when it becomes full. The default
value is 8.
</p></li><li><p><a name="option_mysqld_innodb_buffer_pool_awe_mem_mb"></a>
<code class="literal">innodb_buffer_pool_awe_mem_mb</code>
</p><p>
The size of the buffer pool (in MB), if it is placed in the
AWE memory. This is relevant only in 32-bit Windows. If your
32-bit Windows operating system supports more than 4GB memory,
using so-called “<span class="quote">Address Windowing Extensions,</span>”
you can allocate the <code class="literal">InnoDB</code> buffer pool
into the AWE physical memory using this variable. The maximum
possible value for this variable is 63000. If it is greater
than 0, <code class="literal">innodb_buffer_pool_size</code> is the
window in the 32-bit address space of
<span><strong class="command">mysqld</strong></span> where <code class="literal">InnoDB</code> maps
that AWE memory. A good value for
<code class="literal">innodb_buffer_pool_size</code> is 500MB.
</p><p>
To take advantage of AWE memory, you will need to recompile
MySQL yourself. The current project settings needed for doing
this can be found in the
<code class="filename">innobase/os/os0proj.c</code> source file.
</p></li><li><p><a name="option_mysqld_innodb_buffer_pool_size"></a>
<code class="literal">innodb_buffer_pool_size</code>
</p><p>
The size in bytes of the memory buffer
<code class="literal">InnoDB</code> uses to cache data and indexes of
its tables. The larger you set this value, the less disk I/O
is needed to access data in tables. On a dedicated database
server, you may set this to up to 80% of the machine physical
memory size. However, do not set it too large because
competition for physical memory might cause paging in the
operating system.
</p></li><li><p><a name="option_mysqld_innodb_checksums"></a>
<code class="literal">innodb_checksums</code>
</p><p>
<code class="literal">InnoDB</code> can use checksum validation on all
pages read from the disk to ensure extra fault tolerance
against broken hardware or data files. This validation is
enabled by default. However, under some rare circumstances
(such as when running benchmarks) this extra safety feature is
unneeded and can be disabled with
<code class="option">--skip-innodb_checksums</code>. This variable was
added in MySQL 5.0.3.
</p></li><li><p><a name="option_mysqld_innodb_commit_concurrency"></a>
<code class="literal">innodb_commit_concurrency</code>
</p><p>
The number of threads that can commit at the same time.
Setting this parameter to 0 allows any number of transactions
to commit simultaneously. This variable was added in MySQL
5.0.12.
</p></li><li><p><a name="option_mysqld_innodb_concurrency_tickets"></a>
<code class="literal">innodb_concurrency_tickets</code>
</p><p>
The number of threads that can enter <code class="literal">InnoDB</code>
concurrently is determined by the
<code class="literal">innodb_thread_concurrency</code> variable. A
thread is placed in a queue when it tries to enter
<code class="literal">InnoDB</code> if the number of threads has already
reached the concurrency limit. When a thread is allowed to
enter <code class="literal">InnoDB</code>, it is given a number of
“<span class="quote">free tickets</span>” equal to the value of
<code class="literal">innodb_concurrency_tickets</code>, and the thread
can enter and leave <code class="literal">InnoDB</code> freely until it
has used up its tickets. After that point, the thread again
becomes subject to the concurrency check (and possible
queuing) the next time it tries to enter
<code class="literal">InnoDB</code>. This variable was added in MySQL
5.0.3.
</p></li><li><p><a name="option_mysqld_innodb_data_file_path"></a>
<code class="literal">innodb_data_file_path</code>
</p><p>
The paths to individual data files and their sizes. The full
directory path to each data file is formed by concatenating
<code class="literal">innodb_data_home_dir</code> to each path specified
here. The file sizes are specified in MB or GB (1024MB) by
appending <code class="literal">M</code> or <code class="literal">G</code> to the
size value. The sum of the sizes of the files must be at least
10MB. If you do not specify
<code class="literal">innodb_data_file_path</code>, the default behavior
is to create a single 10MB auto-extending data file named
<code class="filename">ibdata1</code>. The size limit of individual
files is determined by your operating system. You can set the
file size to more than 4GB on those operating systems that
support big files. You can also use raw disk partitions as
data files. See <a href="storage-engines.html#innodb-raw-devices" title="13.2.3.2. Using Raw Devices for the Shared Tablespace">Section 13.2.3.2, “Using Raw Devices for the Shared Tablespace”</a>.
</p></li><li><p><a name="option_mysqld_innodb_data_home_dir"></a>
<code class="literal">innodb_data_home_dir</code>
</p><p>
The common part of the directory path for all
<code class="literal">InnoDB</code> data files. If you do not set this
value, the default is the MySQL data directory. You can
specify the value as an empty string, in which case you can
use absolute file paths in
<code class="literal">innodb_data_file_path</code>.
</p></li><li><p><a name="option_mysqld_innodb_doublewrite"></a>
<code class="literal">innodb_doublewrite</code>
</p><p>
By default, <code class="literal">InnoDB</code> stores all data twice,
first to the doublewrite buffer, and then to the actual data
files. This variable is enabled by default. It can be turned
off with <code class="option">--skip-innodb_doublewrite</code> for
benchmarks or cases when top performance is needed rather than
concern for data integrity or possible failures. This variable
was added in MySQL 5.0.3.
</p></li><li><p><a name="option_mysqld_innodb_fast_shutdown"></a>
<code class="literal">innodb_fast_shutdown</code>
</p><p>
If you set this variable to 0, <code class="literal">InnoDB</code> does
a full purge and an insert buffer merge before a shutdown.
These operations can take minutes, or even hours in extreme
cases. If you set this variable to 1,
<code class="literal">InnoDB</code> skips these operations at shutdown.
The default value is 1. If you set it to 2,
<code class="literal">InnoDB</code> will just flush its logs and then
shut down cold, as if MySQL had crashed; no committed
transaction will be lost, but crash recovery will be done at
the next startup. The value of 2 can be used as of MySQL
5.0.5, except that it cannot be used on NetWare.
</p></li><li><p><a name="option_mysqld_innodb_file_io_threads"></a>
<code class="literal">innodb_file_io_threads</code>
</p><p>
The number of file I/O threads in <code class="literal">InnoDB</code>.
Normally, this should be left at the default value of 4, but
disk I/O on Windows may benefit from a larger number. On Unix,
increasing the number has no effect; <code class="literal">InnoDB</code>
always uses the default value.
</p></li><li><p><a name="option_mysqld_innodb_file_per_table"></a>
<code class="literal">innodb_file_per_table</code>
</p><p>
If this variable is enabled, <code class="literal">InnoDB</code> creates
each new table using its own <code class="filename">.ibd</code> file
for storing data and indexes, rather than in the shared
tablespace. The default is to create tables in the shared
tablespace. See <a href="storage-engines.html#multiple-tablespaces" title="13.2.3.1. Using Per-Table Tablespaces">Section 13.2.3.1, “Using Per-Table Tablespaces”</a>.
</p></li><li><p><a name="option_mysqld_innodb_flush_log_at_trx_commit"></a>
<code class="literal">innodb_flush_log_at_trx_commit</code>
</p><p>
When <code class="literal">innodb_flush_log_at_trx_commit</code> is set
to 0, the log buffer is written out to the log file once per
second and the flush to disk operation is performed on the log
file, but nothing is done at a transaction commit. When this
value is 1 (the default), the log buffer is written out to the
log file at each transaction commit and the flush to disk
operation is performed on the log file. When set to 2, the log
buffer is written out to the file at each commit, but the
flush to disk operation is not performed on it. However, the
flushing on the log file takes place once per second also when
the value is 2. Note that the once-per-second flushing is not
100% guaranteed to happen every second, due to process
scheduling issues.
</p><p>
The default value of this variable is 1, which is the value
that is required for ACID compliance. You can achieve better
performance by setting the value different from 1, but then
you can lose at most one second worth of transactions in a
crash. If you set the value to 0, then any
<span><strong class="command">mysqld</strong></span> process crash can erase the last
second of transactions. If you set the value to 2, then only
an operating system crash or a power outage can erase the last
second of transactions. However, <code class="literal">InnoDB</code>'s
crash recovery is not affected and thus crash recovery does
work regardless of the value. Note that many operating systems
and some disk hardware fool the flush-to-disk operation. They
may tell <span><strong class="command">mysqld</strong></span> that the flush has taken
place, even though it has not. Then the durability of
transactions is not guaranteed even with the setting 1, and in
the worst case a power outage can even corrupt the
<code class="literal">InnoDB</code> database. Using a battery-backed
disk cache in the SCSI disk controller or in the disk itself
speeds up file flushes, and makes the operation safer. You can
also try using the Unix command <span><strong class="command">hdparm</strong></span> to
disable the caching of disk writes in hardware caches, or use
some other command specific to the hardware vendor.
</p><p>
Note: For the greatest possible durability and consistency in
a replication setup using <code class="literal">InnoDB</code> with
transactions, you should use
<code class="literal">innodb_flush_log_at_trx_commit=1</code>,
<code class="literal">sync_binlog=1</code>, and, before MySQL 5.0.3,
<code class="literal">innodb_safe_binlog</code> in your master server
<code class="filename">my.cnf</code> file.
(<code class="literal">innodb_safe_binlog</code> is not needed from
5.0.3 on.)
</p></li><li><p><a name="option_mysqld_innodb_flush_method"></a>
<code class="literal">innodb_flush_method</code>
</p><p>
If set to <code class="literal">fdatasync</code> (the default),
<code class="literal">InnoDB</code> uses <code class="literal">fsync()</code> to
flush both the data and log files. If set to
<code class="literal">O_DSYNC</code>, <code class="literal">InnoDB</code> uses
<code class="literal">O_SYNC</code> to open and flush the log files, but
uses <code class="literal">fsync()</code> to flush the data files. If
<code class="literal">O_DIRECT</code> is specified (available on some
GNU/Linux versions, FreeBSD and Solaris),
<code class="literal">InnoDB</code> uses <code class="literal">O_DIRECT</code> (or
<code class="literal">directio()</code> on Solaris) to open the data
files, and uses <code class="literal">fsync()</code> to flush both the
data and log files. Note that <code class="literal">InnoDB</code> uses
<code class="literal">fsync()</code> instead of
<code class="literal">fdatasync()</code>, and it does not use
<code class="literal">O_DSYNC</code> by default because there have been
problems with it on many varieties of Unix. This variable is
relevant only for Unix. On Windows, the flush method is always
<code class="literal">async_unbuffered</code> and cannot be changed.
</p><p>
Different values of this variable can have a marked effect on
<code class="literal">InnoDB performance</code>. For example, on some
systems where <code class="literal">InnoDB</code> data and log files are
located on a SAN, it has been found that setting
<code class="literal">innodb_flush_method</code> to
<code class="literal">O_DIRECT</code> can degrade performance of simple
<code class="literal">SELECT</code> statements by a factor of three.
</p></li><li><p><a name="option_mysqld_innodb_force_recovery"></a>
<code class="literal">innodb_force_recovery</code>
</p><p>
The crash recovery mode.
</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
This variable should be set greater than 0 only in an
emergency situation when you want to dump your tables from a
corrupt database! Possible values are from 1 to 6. The
meanings of these values are described in
<a href="storage-engines.html#forcing-recovery" title="13.2.8.1. Forcing InnoDB Recovery">Section 13.2.8.1, “Forcing <code class="literal">InnoDB</code> Recovery”</a>. As a safety measure,
<code class="literal">InnoDB</code> prevents any changes to its data
when this variable is greater than 0.
</p></div></li><li><p><a name="option_mysqld_innodb_lock_wait_timeout"></a>
<code class="literal">innodb_lock_wait_timeout</code>
</p><p>
The timeout in seconds an <code class="literal">InnoDB</code>
transaction may wait for a lock before being rolled back.
<code class="literal">InnoDB</code> automatically detects transaction
deadlocks in its own lock table and rolls back the
transaction. <code class="literal">InnoDB</code> notices locks set using
the <code class="literal">LOCK TABLES</code> statement. The default is
50 seconds.
</p></li><li><p><a name="option_mysqld_innodb_locks_unsafe_for_binlog"></a>
<code class="literal">innodb_locks_unsafe_for_binlog</code>
</p><p>
<a class="indexterm" name="id2902720"></a>
<a class="indexterm" name="id2902729"></a>
This variable controls next-key locking in
<code class="literal">InnoDB</code> searches and index scans. By
default, this variable is 0 (disabled), which means that
next-key locking is enabled.
</p><p>
Normally, <code class="literal">InnoDB</code> uses an algorithm called
<em class="firstterm">next-key locking</em>.
<code class="literal">InnoDB</code> performs row-level locking in such a
way that when it searches or scans a table index, it sets
shared or exclusive locks on any index records it encounters.
Thus, the row-level locks are actually index record locks. The
locks that <code class="literal">InnoDB</code> sets on index records
also affect the “<span class="quote">gap</span>” preceding that index
record. If a user has a shared or exclusive lock on record
<span class="emphasis"><em>R</em></span> in an index, another user cannot insert
a new index record immediately before <span class="emphasis"><em>R</em></span>
in the order of the index. Enabling this variable causes
<code class="literal">InnoDB</code> not to use next-key locking in
searches or index scans. Next-key locking is still used to
ensure foreign key constraints and duplicate key checking.
Note that enabling this variable may cause phantom problems:
Suppose that you want to read and lock all children from the
<code class="literal">child</code> table with an identifier value larger
than 100, with the intention of updating some column in the
selected rows later:
</p><pre class="programlisting">SELECT * FROM child WHERE id > 100 FOR UPDATE;
</pre><p>
Suppose that there is an index on the <code class="literal">id</code>
column. The query scans that index starting from the first
record where <code class="literal">id</code> is greater than 100. If the
locks set on the index records do not lock out inserts made in
the gaps, another client can insert a new row into the table.
If you execute the same <code class="literal">SELECT</code> within the
same transaction, you see a new row in the result set returned
by the query. This also means that if new items are added to
the database, <code class="literal">InnoDB</code> does not guarantee
serializability. Therefore, if this variable is enabled
<code class="literal">InnoDB</code> guarantees at most isolation level
<code class="literal">READ COMMITTED</code>. (Conflict serializability
is still guaranteed.)
</p><p>
Starting from MySQL 5.0.2, this option is even more unsafe.
<code class="literal">InnoDB</code> in an <code class="literal">UPDATE</code> or a
<code class="literal">DELETE</code> only locks rows that it updates or
deletes. This greatly reduces the probability of deadlocks,
but they can happen. Note that enabling this variable still
does not allow operations such as <code class="literal">UPDATE</code> to
overtake other similar operations (such as another
<code class="literal">UPDATE</code>) even in the case when they affect
different rows. Consider the following example, beginning with
this table:
</p><pre class="programlisting">CREATE TABLE A(A INT NOT NULL, B INT) ENGINE = InnoDB;
INSERT INTO A VALUES (1,2),(2,3),(3,2),(4,3),(5,2);
COMMIT;
</pre><p>
Suppose that one client executes these statements:
</p><pre class="programlisting">SET AUTOCOMMIT = 0;
UPDATE A SET B = 5 WHERE B = 3;
</pre><p>
Then suppose that another client executes these statements
following those of the first client:
</p><pre class="programlisting">SET AUTOCOMMIT = 0;
UPDATE A SET B = 4 WHERE B = 2;
</pre><p>
In this case, the second <code class="literal">UPDATE</code> must wait
for a commit or rollback of the first
<code class="literal">UPDATE</code>. The first <code class="literal">UPDATE</code>
has an exclusive lock on row (2,3), and the second
<code class="literal">UPDATE</code> while scanning rows also tries to
acquire an exclusive lock for the same row, which it cannot
have. This is because <code class="literal">UPDATE</code> two first
acquires an exclusive lock on a row and then determines
whether the row belongs to the result set. If not, it releases
the unnecessary lock, when the
<code class="literal">innodb_locks_unsafe_for_binlog</code> variable is
enabled.
</p><p>
Therefore, <code class="literal">InnoDB</code> executes
<code class="literal">UPDATE</code> one as follows:
</p><pre class="programlisting">x-lock(1,2)
unlock(1,2)
x-lock(2,3)
update(2,3) to (2,5)
x-lock(3,2)
unlock(3,2)
x-lock(4,3)
update(4,3) to (4,5)
x-lock(5,2)
unlock(5,2)
</pre><p>
<code class="literal">InnoDB</code> executes <code class="literal">UPDATE</code>
two as follows:
</p><pre class="programlisting">x-lock(1,2)
update(1,2) to (1,4)
x-lock(2,3) - wait for query one to commit or rollback
</pre></li><li><p><a name="option_mysqld_innodb_log_archive"></a>
<code class="literal">innodb_log_archive</code>
</p><p>
Whether to log <code class="literal">InnoDB</code> archive files. This
variable is present for historical reasons, but is unused.
Recovery from a backup is done by MySQL using its own log
files, so there is no need to archive
<code class="literal">InnoDB</code> log files. The default for this
variable is 0.
</p></li><li><p><a name="option_mysqld_innodb_log_buffer_size"></a>
<code class="literal">innodb_log_buffer_size</code>
</p><p>
The size in bytes of the buffer that <code class="literal">InnoDB</code>
uses to write to the log files on disk. Sensible values range
from 1MB to 8MB. The default is 1MB. A large log buffer allows
large transactions to run without a need to write the log to
disk before the transactions commit. Thus, if you have big
transactions, making the log buffer larger saves disk I/O.
</p></li><li><p><a name="option_mysqld_innodb_log_file_size"></a>
<code class="literal">innodb_log_file_size</code>
</p><p>
The size in bytes of each log file in a log group. The
combined size of log files must be less than 4GB on 32-bit
computers. The default is 5MB. Sensible values range from 1MB
to 1/<em class="replaceable"><code>N</code></em>-th of the size of the buffer
pool, where <em class="replaceable"><code>N</code></em> is the number of log
files in the group. The larger the value, the less checkpoint
flush activity is needed in the buffer pool, saving disk I/O.
But larger log files also mean that recovery is slower in case
of a crash.
</p></li><li><p><a name="option_mysqld_innodb_log_files_in_group"></a>
<code class="literal">innodb_log_files_in_group</code>
</p><p>
The number of log files in the log group.
<code class="literal">InnoDB</code> writes to the files in a circular
fashion. The default (and recommended) is 2.
</p></li><li><p><a name="option_mysqld_innodb_log_group_home_dir"></a>
<code class="literal">innodb_log_group_home_dir</code>
</p><p>
The directory path to the <code class="literal">InnoDB</code> log files.
If you do not specify any <code class="literal">InnoDB</code> log
variables, the default is to create two 5MB files names
<code class="filename">ib_logfile0</code> and
<code class="filename">ib_logfile1</code> in the MySQL data directory.
</p></li><li><p><a name="option_mysqld_innodb_max_dirty_pages_pct"></a>
<code class="literal">innodb_max_dirty_pages_pct</code>
</p><p>
This is an integer in the range from 0 to 100. The default is
90. The main thread in <code class="literal">InnoDB</code> tries to
write pages from the buffer pool so that the percentage of
dirty (not yet written) pages will not exceed this value.
</p></li><li><p><a name="option_mysqld_innodb_max_purge_lag"></a>
<code class="literal">innodb_max_purge_lag</code>
</p><p>
This variable controls how to delay <code class="literal">INSERT</code>,
<code class="literal">UPDATE</code> and <code class="literal">DELETE</code>
operations when the purge operations are lagging (see
<a href="storage-engines.html#innodb-multi-versioning" title="13.2.12. Implementation of Multi-Versioning">Section 13.2.12, “Implementation of Multi-Versioning”</a>). The default value
of this variable is 0, meaning that there are no delays.
</p><p>
The <code class="literal">InnoDB</code> transaction system maintains a
list of transactions that have delete-marked index records by
<code class="literal">UPDATE</code> or <code class="literal">DELETE</code>
operations. Let the length of this list be
<em class="replaceable"><code>purge_lag</code></em>. When
<em class="replaceable"><code>purge_lag</code></em> exceeds
<code class="literal">innodb_max_purge_lag</code>, each
<code class="literal">INSERT</code>, <code class="literal">UPDATE</code> and
<code class="literal">DELETE</code> operation is delayed by
((<em class="replaceable"><code>purge_lag</code></em>/<code class="literal">innodb_max_purge_lag</code>)×10)–5
milliseconds. The delay is computed in the beginning of a
purge batch, every ten seconds. The operations are not delayed
if purge cannot run because of an old consistent read view
that could see the rows to be purged.
</p><p>
A typical setting for a problematic workload might be 1
million, assuming that our transactions are small, only 100
bytes in size, and we can allow 100MB of unpurged rows in our
tables.
</p></li><li><p><a name="option_mysqld_innodb_mirrored_log_groups"></a>
<code class="literal">innodb_mirrored_log_groups</code>
</p><p>
The number of identical copies of log groups to keep for the
database. Currently, this should be set to 1.
</p></li><li><p><a name="option_mysqld_innodb_open_files"></a>
<code class="literal">innodb_open_files</code>
</p><p>
This variable is relevant only if you use multiple tablespaces
in <code class="literal">InnoDB</code>. It specifies the maximum number
of <code class="filename">.ibd</code> files that
<code class="literal">InnoDB</code> can keep open at one time. The
minimum value is 10. The default is 300.
</p><p>
The file descriptors used for <code class="filename">.ibd</code> files
are for <code class="literal">InnoDB</code> only. They are independent
of those specified by the <code class="option">--open-files-limit</code>
server option, and do not affect the operation of the table
cache.
</p></li><li><p><a name="option_mysqld_innodb_rollback_on_timeout"></a>
<code class="literal">innodb_rollback_on_timeout</code>
</p><p>
In MySQL 5.0.13 and up, <code class="literal">InnoDB</code> rolls back
only the last statement on a transaction timeout. If this
option is given, a transaction timeout causes
<code class="literal">InnoDB</code> to abort and roll back the entire
transaction (the same behavior as before MySQL 5.0.13). This
variable was added in MySQL 5.0.32.
</p></li><li><p>
<code class="literal">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="server-administration.html#binary-log" title="5.10.3. The Binary Log">Section 5.10.3, “The Binary Log”</a>. This variable was removed in
MySQL 5.0.3, having been made obsolete by the introduction of
XA transaction support. You should set
<code class="literal">innodb_support_xa</code> to <code class="literal">ON</code>
or 1 to ensure consistency. See
<code class="literal"><a href="storage-engines.html#option_mysqld_innodb_support_xa">innodb_support_xa</a></code>.
</p></li><li><p><a name="option_mysqld_innodb_support_xa"></a>
<code class="literal">innodb_support_xa</code>
</p><p>
When set to <code class="literal">ON</code> or 1 (the default), this
variable enables <code class="literal">InnoDB</code> support for
two-phase commit in XA transactions. Enabling
<code class="literal">innodb_support_xa</code> causes an extra disk
flush for transaction preparation.
</p><p>
If you don't care about using XA, you can disable this
variable by setting it to <code class="literal">OFF</code> or 0 to
reduce the number of disk flushes and get better
<code class="literal">InnoDB</code> performance. If you are using
replication and/or the binary log then you should set this
variable to <code class="literal">ON</code> or 1 to ensure that the
binary log does not get out of sync compared to the table
data.
</p><p>
This variable was added in MySQL 5.0.3.
</p></li><li><p><a name="option_mysqld_innodb_sync_spin_loops"></a>
<code class="literal">innodb_sync_spin_loops</code>
</p><p>
The number of times a thread waits for an
<code class="literal">InnoDB</code> mutex to be freed before the thread
is suspended. This variable was added in MySQL 5.0.3.
</p></li><li><p><a name="option_mysqld_innodb_table_locks"></a>
<code class="literal">innodb_table_locks</code>
</p><p>
If <code class="literal">AUTOCOMMIT=0</code>, <code class="literal">InnoDB</code>
honors <code class="literal">LOCK TABLES</code>; MySQL does not return
from <code class="literal">LOCK TABLE .. WRITE</code> until all other
threads have released all their locks to the table. The
default value of <code class="literal">innodb_table_locks</code> is 1,
which means that <code class="literal">LOCK TABLES</code> causes InnoDB
to lock a table internally if <code class="literal">AUTOCOMMIT=0</code>.
</p></li><li><p><a name="option_mysqld_innodb_thread_concurrency"></a>
<code class="literal">innodb_thread_concurrency</code>
</p><p>
<code class="literal">InnoDB</code> tries to keep the number of
operating system threads concurrently inside
<code class="literal">InnoDB</code> less than or equal to the limit
given by this variable. Once the number of threads reaches
this limit, additional threads are placed into a wait state
within a FIFO queue for execution. Threads waiting for locks
are not counted in the number of concurrently executing
threads.
</p><p>
The correct value for this variable is dependent on
environment and workload. You will need to try a range of
different values to determine what value works for your
application.
</p><p>
The range of this variable is 0 to 1000. A value of 20 or
higher is interpreted as infinite concurrency before MySQL
5.0.19. From 5.0.19 on, you can disable thread concurrency
checking by setting the value to 0, which allows InnoDB to
create as many threads as it needs.
</p><p>
The default value has changed several times: 8 before MySQL
5.0.8, 20 (infinite) from 5.0.8 through 5.0.18, 0 (infinite)
from 5.0.19 to 5.0.20, and 8 (finite) from 5.0.21 on.
</p></li><li><p><a name="option_mysqld_innodb_thread_sleep_delay"></a>
<code class="literal">innodb_thread_sleep_delay</code>
</p><p>
How long <code class="literal">InnoDB</code> threads sleep before
joining the <code class="literal">InnoDB</code> queue, in microseconds.
The default value is 10,000. A value of 0 disables sleep. This
variable was added in MySQL 5.0.3.
</p></li><li><p>
<code class="literal">sync_binlog</code>
</p><p>
If the value of this variable is positive, the MySQL server
synchronizes its binary log to disk
(<code class="literal">fdatasync()</code>) after every
<code class="literal">sync_binlog</code> writes 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 synchronizing to disk. A
value of 1 is the safest choice, because in the event of a
crash you lose at most one statement/transaction from the
binary log; however, it is also the slowest choice (unless the
disk has a battery-backed cache, which makes synchronization
very fast).
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-init"></a>13.2.5. Creating the <code class="literal">InnoDB</code> Tablespace</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#error-creating-innodb">13.2.5.1. Dealing with <code class="literal">InnoDB</code> Initialization Problems</a></span></dt></dl></div><p>
Suppose that you have installed MySQL and have edited your option
file so that it contains the necessary <code class="literal">InnoDB</code>
configuration parameters. Before starting MySQL, you should verify
that the directories you have specified for
<code class="literal">InnoDB</code> data files and log files exist and that
the MySQL server has access rights to those directories.
<code class="literal">InnoDB</code> does not create directories, only files.
Check also that you have enough disk space for the data and log
files.
</p><p>
It is best to run the MySQL server <span><strong class="command">mysqld</strong></span> from
the command prompt when you first start the server with
<code class="literal">InnoDB</code> enabled, not from the
<span><strong class="command">mysqld_safe</strong></span> wrapper or as a Windows service.
When you run from a command prompt you see what
<span><strong class="command">mysqld</strong></span> prints and what is happening. On Unix,
just invoke <span><strong class="command">mysqld</strong></span>. On Windows, use the
<code class="option">--console</code> option.
</p><p>
When you start the MySQL server after initially configuring
<code class="literal">InnoDB</code> in your option file,
<code class="literal">InnoDB</code> creates your data files and log files,
and prints something like this:
</p><pre class="programlisting">InnoDB: The first specified datafile /home/heikki/data/ibdata1
did not exist:
InnoDB: a new database to be created!
InnoDB: Setting file /home/heikki/data/ibdata1 size to 134217728
InnoDB: Database physically writes the file full: wait...
InnoDB: datafile /home/heikki/data/ibdata2 did not exist:
new to be created
InnoDB: Setting file /home/heikki/data/ibdata2 size to 262144000
InnoDB: Database physically writes the file full: wait...
InnoDB: Log file /home/heikki/data/logs/ib_logfile0 did not exist:
new to be created
InnoDB: Setting log file /home/heikki/data/logs/ib_logfile0 size
to 5242880
InnoDB: Log file /home/heikki/data/logs/ib_logfile1 did not exist:
new to be created
InnoDB: Setting log file /home/heikki/data/logs/ib_logfile1 size
to 5242880
InnoDB: Doublewrite buffer not found: creating new
InnoDB: Doublewrite buffer created
InnoDB: Creating foreign key constraint system tables
InnoDB: Foreign key constraint system tables created
InnoDB: Started
mysqld: ready for connections
</pre><p>
At this point <code class="literal">InnoDB</code> has initialized its
tablespace and log files. You can connect to the MySQL server with
the usual MySQL client programs like <span><strong class="command">mysql</strong></span>.
When you shut down the MySQL server with <span><strong class="command">mysqladmin
shutdown</strong></span>, the output is like this:
</p><pre class="programlisting">010321 18:33:34 mysqld: Normal shutdown
010321 18:33:34 mysqld: Shutdown Complete
InnoDB: Starting shutdown...
InnoDB: Shutdown completed
</pre><p>
You can look at the data file and log directories and you see the
files created there. When MySQL is started again, the data files
and log files have been created already, so the output is much
briefer:
</p><pre class="programlisting">InnoDB: Started
mysqld: ready for connections
</pre><p>
If you add the <code class="literal">innodb_file_per_table</code> option to
<code class="filename">my.cnf</code>, <code class="literal">InnoDB</code> stores each
table in its own <code class="filename">.ibd</code> file in the same MySQL
database directory where the <code class="filename">.frm</code> file is
created. See <a href="storage-engines.html#multiple-tablespaces" title="13.2.3.1. Using Per-Table Tablespaces">Section 13.2.3.1, “Using Per-Table Tablespaces”</a>.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="error-creating-innodb"></a>13.2.5.1. Dealing with <code class="literal">InnoDB</code> Initialization Problems</h4></div></div></div><p>
If <code class="literal">InnoDB</code> prints an operating system error
during a file operation, usually the problem has one of the
following causes:
</p><div class="itemizedlist"><ul type="disc"><li><p>
You did not create the <code class="literal">InnoDB</code> data file
directory or the <code class="literal">InnoDB</code> log directory.
</p></li><li><p>
<span><strong class="command">mysqld</strong></span> does not have access rights to
create files in those directories.
</p></li><li><p>
<span><strong class="command">mysqld</strong></span> cannot read the proper
<code class="filename">my.cnf</code> or <code class="filename">my.ini</code>
option file, and consequently does not see the options that
you specified.
</p></li><li><p>
The disk is full or a disk quota is exceeded.
</p></li><li><p>
You have created a subdirectory whose name is equal to a
data file that you specified, so the name cannot be used as
a filename.
</p></li><li><p>
There is a syntax error in the
<code class="literal">innodb_data_home_dir</code> or
<code class="literal">innodb_data_file_path</code> value.
</p></li></ul></div><p>
If something goes wrong when <code class="literal">InnoDB</code> attempts
to initialize its tablespace or its log files, you should delete
all files created by <code class="literal">InnoDB</code>. This means all
<code class="filename">ibdata</code> files and all
<code class="filename">ib_logfile</code> files. In case you have already
created some <code class="literal">InnoDB</code> tables, delete the
corresponding <code class="filename">.frm</code> files for these tables
(and any <code class="filename">.ibd</code> files if you are using
multiple tablespaces) from the MySQL database directories as
well. Then you can try the <code class="literal">InnoDB</code> database
creation again. It is best to start the MySQL server from a
command prompt so that you see what is happening.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="using-innodb-tables"></a>13.2.6. Creating and Using <code class="literal">InnoDB</code> Tables</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#innodb-transactions-with-different-apis">13.2.6.1. How to Use Transactions in <code class="literal">InnoDB</code> with Different APIs</a></span></dt><dt><span class="section"><a href="storage-engines.html#converting-tables-to-innodb">13.2.6.2. Converting <code class="literal">MyISAM</code> Tables to <code class="literal">InnoDB</code></a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-auto-increment-handling">13.2.6.3. How <code class="literal">AUTO_INCREMENT</code> Handling Works in
<code class="literal">InnoDB</code></a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-foreign-key-constraints">13.2.6.4. <code class="literal">FOREIGN KEY</code> Constraints</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-and-mysql-replication">13.2.6.5. <code class="literal">InnoDB</code> and MySQL Replication</a></span></dt></dl></div><p>
To create an <code class="literal">InnoDB</code> table, specify an
<code class="literal">ENGINE = InnoDB</code> option in the <code class="literal">CREATE
TABLE</code> statement:
</p><pre class="programlisting">CREATE TABLE customers (a INT, b CHAR (20), INDEX (a)) ENGINE=InnoDB;
</pre><p>
The older term <code class="literal">TYPE</code> is supported as a synonym
for <code class="literal">ENGINE</code> for backward compatibility, but
<code class="literal">ENGINE</code> is the preferred term and
<code class="literal">TYPE</code> is deprecated.
</p><p>
The statement creates a table and an index on column
<code class="literal">a</code> in the <code class="literal">InnoDB</code> tablespace
that consists of the data files that you specified in
<code class="filename">my.cnf</code>. In addition, MySQL creates a file
<code class="filename">customers.frm</code> in the
<code class="filename">test</code> directory under the MySQL database
directory. Internally, <code class="literal">InnoDB</code> adds an entry for
the table to its own data dictionary. The entry includes the
database name. For example, if <code class="literal">test</code> is the
database in which the <code class="literal">customers</code> table is
created, the entry is for <code class="literal">'test/customers'</code>.
This means you can create a table of the same name
<code class="literal">customers</code> in some other database, and the table
names do not collide inside <code class="literal">InnoDB</code>.
</p><p>
You can query the amount of free space in the
<code class="literal">InnoDB</code> tablespace by issuing a <code class="literal">SHOW
TABLE STATUS</code> statement for any <code class="literal">InnoDB</code>
table. The amount of free space in the tablespace appears in the
<code class="literal">Comment</code> section in the output of <code class="literal">SHOW
TABLE STATUS</code>. For example:
</p><pre class="programlisting">SHOW TABLE STATUS FROM test LIKE 'customers'
</pre><p>
Note that the statistics <code class="literal">SHOW</code> displays for
<code class="literal">InnoDB</code> tables are only approximate. They are
used in SQL optimization. Table and index reserved sizes in bytes
are accurate, though.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-transactions-with-different-apis"></a>13.2.6.1. How to Use Transactions in <code class="literal">InnoDB</code> with Different APIs</h4></div></div></div><p>
By default, each client that connects to the MySQL server begins
with autocommit mode enabled, which automatically commits every
SQL statement as you execute it. To use multiple-statement
transactions, you can switch autocommit off with the SQL
statement <code class="literal">SET AUTOCOMMIT = 0</code> and use
<code class="literal">COMMIT</code> and <code class="literal">ROLLBACK</code> to
commit or roll back your transaction. If you want to leave
autocommit on, you can enclose your transactions within
<code class="literal">START TRANSACTION</code> and either
<code class="literal">COMMIT</code> or <code class="literal">ROLLBACK</code>. The
following example shows two transactions. The first is
committed; the second is rolled back.
</p><pre class="programlisting">shell> <strong class="userinput"><code>mysql test</code></strong>
mysql> <strong class="userinput"><code>CREATE TABLE CUSTOMER (A INT, B CHAR (20), INDEX (A))</code></strong>
-> <strong class="userinput"><code>ENGINE=InnoDB;</code></strong>
Query OK, 0 rows affected (0.00 sec)
mysql> <strong class="userinput"><code>START TRANSACTION;</code></strong>
Query OK, 0 rows affected (0.00 sec)
mysql> <strong class="userinput"><code>INSERT INTO CUSTOMER VALUES (10, 'Heikki');</code></strong>
Query OK, 1 row affected (0.00 sec)
mysql> <strong class="userinput"><code>COMMIT;</code></strong>
Query OK, 0 rows affected (0.00 sec)
mysql> <strong class="userinput"><code>SET AUTOCOMMIT=0;</code></strong>
Query OK, 0 rows affected (0.00 sec)
mysql> <strong class="userinput"><code>INSERT INTO CUSTOMER VALUES (15, 'John');</code></strong>
Query OK, 1 row affected (0.00 sec)
mysql> <strong class="userinput"><code>ROLLBACK;</code></strong>
Query OK, 0 rows affected (0.00 sec)
mysql> <strong class="userinput"><code>SELECT * FROM CUSTOMER;</code></strong>
+------+--------+
| A | B |
+------+--------+
| 10 | Heikki |
+------+--------+
1 row in set (0.00 sec)
mysql>
</pre><p>
In APIs such as PHP, Perl DBI, JDBC, ODBC, or the standard C
call interface of MySQL, you can send transaction control
statements such as <code class="literal">COMMIT</code> to the MySQL server
as strings just like any other SQL statements such as
<code class="literal">SELECT</code> or <code class="literal">INSERT</code>. Some
APIs also offer separate special transaction commit and rollback
functions or methods.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="converting-tables-to-innodb"></a>13.2.6.2. Converting <code class="literal">MyISAM</code> Tables to <code class="literal">InnoDB</code></h4></div></div></div><p>
Important: Do not convert MySQL system tables in the
<code class="literal">mysql</code> database (such as
<code class="literal">user</code> or <code class="literal">host</code>) to the
<code class="literal">InnoDB</code> type. This is an unsupported
operation. The system tables must always be of the
<code class="literal">MyISAM</code> type.
</p><p>
If you want all your (non-system) tables to be created as
<code class="literal">InnoDB</code> tables, you can simply add the line
<code class="literal">default-storage-engine=innodb</code> to the
<code class="literal">[mysqld]</code> section of your server option file.
</p><p>
<code class="literal">InnoDB</code> does not have a special optimization
for separate index creation the way the
<code class="literal">MyISAM</code> storage engine does. Therefore, it
does not pay to export and import the table and create indexes
afterward. The fastest way to alter a table to
<code class="literal">InnoDB</code> is to do the inserts directly to an
<code class="literal">InnoDB</code> table. That is, use <code class="literal">ALTER
TABLE ... ENGINE=INNODB</code>, or create an empty
<code class="literal">InnoDB</code> table with identical definitions and
insert the rows with <code class="literal">INSERT INTO ... SELECT * FROM
...</code>.
</p><p>
If you have <code class="literal">UNIQUE</code> constraints on secondary
keys, you can speed up a table import by turning off the
uniqueness checks temporarily during the import operation:
</p><pre class="programlisting">SET UNIQUE_CHECKS=0;
<em class="replaceable"><code>... import operation ...</code></em>
SET UNIQUE_CHECKS=1;
</pre><p>
For big tables, this saves a lot of disk I/O because
<code class="literal">InnoDB</code> can then use its insert buffer to
write secondary index records as a batch. Be certain that the
data contains no duplicate keys.
<code class="literal">UNIQUE_CHECKS</code> allows but does not require
storage engines to ignore duplicate keys.
</p><p>
To get better control over the insertion process, it might be
good to insert big tables in pieces:
</p><pre class="programlisting">INSERT INTO newtable SELECT * FROM oldtable
WHERE yourkey > something AND yourkey <= somethingelse;
</pre><p>
After all records have been inserted, you can rename the tables.
</p><p>
During the conversion of big tables, you should increase the
size of the <code class="literal">InnoDB</code> buffer pool to reduce disk
I/O. Do not use more than 80% of the physical memory, though.
You can also increase the sizes of the <code class="literal">InnoDB</code>
log files.
</p><p>
Make sure that you do not fill up the tablespace:
<code class="literal">InnoDB</code> tables require a lot more disk space
than <code class="literal">MyISAM</code> tables. If an <code class="literal">ALTER
TABLE</code> operation runs out of space, it starts a
rollback, and that can take hours if it is disk-bound. For
inserts, <code class="literal">InnoDB</code> uses the insert buffer to
merge secondary index records to indexes in batches. That saves
a lot of disk I/O. For rollback, no such mechanism is used, and
the rollback can take 30 times longer than the insertion.
</p><p>
In the case of a runaway rollback, if you do not have valuable
data in your database, it may be advisable to kill the database
process rather than wait for millions of disk I/O operations to
complete. For the complete procedure, see
<a href="storage-engines.html#forcing-recovery" title="13.2.8.1. Forcing InnoDB Recovery">Section 13.2.8.1, “Forcing <code class="literal">InnoDB</code> Recovery”</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-auto-increment-handling"></a>13.2.6.3. How <code class="literal">AUTO_INCREMENT</code> Handling Works in
<code class="literal">InnoDB</code></h4></div></div></div><p>
If you specify an <code class="literal">AUTO_INCREMENT</code> column for
an <code class="literal">InnoDB</code> table, the table handle in the
<code class="literal">InnoDB</code> data dictionary contains a special
counter called the auto-increment counter that is used in
assigning new values for the column. This counter is stored only
in main memory, not on disk.
</p><p>
<code class="literal">InnoDB</code> uses the following algorithm to
initialize the auto-increment counter for a table
<code class="literal">t</code> that contains an
<code class="literal">AUTO_INCREMENT</code> column named
<code class="literal">ai_col</code>: After a server startup, for the first
insert into a table <code class="literal">t</code>,
<code class="literal">InnoDB</code> executes the equivalent of this
statement:
</p><pre class="programlisting">SELECT MAX(ai_col) FROM t FOR UPDATE;
</pre><p>
<code class="literal">InnoDB</code> increments by one the value retrieved
by the statement and assigns it to the column and to the
auto-increment counter for the table. If the table is empty,
<code class="literal">InnoDB</code> uses the value <code class="literal">1</code>.
If a user invokes a <code class="literal">SHOW TABLE STATUS</code>
statement that displays output for the table
<code class="literal">t</code> and the auto-increment counter has not been
initialized, <code class="literal">InnoDB</code> initializes but does not
increment the value and stores it for use by later inserts. This
initialization uses a normal exclusive-locking read on the table
and the lock lasts to the end of the transaction.
</p><p>
<code class="literal">InnoDB</code> follows the same procedure for
initializing the auto-increment counter for a freshly created
table.
</p><p>
After the auto-increment counter has been initialized, if a user
does not explicitly specify a value for an
<code class="literal">AUTO_INCREMENT</code> column,
<code class="literal">InnoDB</code> increments the counter by one and
assigns the new value to the column. If the user inserts a row
that explicitly specifies the column value, and the value is
bigger than the current counter value, the counter is set to the
specified column value.
</p><p>
When accessing the auto-increment counter,
<code class="literal">InnoDB</code> uses a special table-level
<code class="literal">AUTO-INC</code> lock that it keeps to the end of the
current SQL statement, not to the end of the transaction. The
special lock release strategy was introduced to improve
concurrency for inserts into a table containing an
<code class="literal">AUTO_INCREMENT</code> column. Nevertheless, two
transactions cannot have the <code class="literal">AUTO-INC</code> lock on
the same table simultaneously, which can have a performance
impact if the <code class="literal">AUTO-INC</code> lock is held for a
long time. That might be the case for a statement such as
<code class="literal">INSERT INTO t1 ... SELECT ... FROM t2</code> that
inserts all rows from one table into another.
</p><p>
<code class="literal">InnoDB</code> uses the in-memory auto-increment
counter as long as the server runs. When the server is stopped
and restarted, <code class="literal">InnoDB</code> reinitializes the
counter for each table for the first <code class="literal">INSERT</code>
to the table, as described earlier.
</p><p>
You may see gaps in the sequence of values assigned to the
<code class="literal">AUTO_INCREMENT</code> column if you roll back
transactions that have generated numbers using the counter.
</p><p>
If a user specifies <code class="literal">NULL</code> or
<code class="literal">0</code> for the <code class="literal">AUTO_INCREMENT</code>
column in an <code class="literal">INSERT</code>,
<code class="literal">InnoDB</code> treats the row as if the value had not
been specified and generates a new value for it.
</p><p>
The behavior of the auto-increment mechanism is not defined if a
user assigns a negative value to the column or if the value
becomes bigger than the maximum integer that can be stored in
the specified integer type.
</p><p>
An <code class="literal">AUTO_INCREMENT</code> column must be the first
column listed if it is part of a multiple-column index in an
<code class="literal">InnoDB</code> table.
</p><p>
Beginning with MySQL 5.0.3, <code class="literal">InnoDB</code> supports
the <code class="literal">AUTO_INCREMENT =
<em class="replaceable"><code>N</code></em></code> table option in
<code class="literal">CREATE TABLE</code> and <code class="literal">ALTER
TABLE</code> statements, to set the initial counter value or
alter the current counter value. The effect of this option is
canceled by a server restart, for reasons discussed earlier in
this section.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-foreign-key-constraints"></a>13.2.6.4. <code class="literal">FOREIGN KEY</code> Constraints</h4></div></div></div><p>
<code class="literal">InnoDB</code> also supports foreign key constraints.
The syntax for a foreign key constraint definition in
<code class="literal">InnoDB</code> looks like this:
</p><pre class="programlisting">[CONSTRAINT <em class="replaceable"><code>symbol</code></em>] FOREIGN KEY [<em class="replaceable"><code>id</code></em>] (<em class="replaceable"><code>index_col_name</code></em>, ...)
REFERENCES <em class="replaceable"><code>tbl_name</code></em> (<em class="replaceable"><code>index_col_name</code></em>, ...)
[ON DELETE {RESTRICT | CASCADE | SET NULL | NO ACTION}]
[ON UPDATE {RESTRICT | CASCADE | SET NULL | NO ACTION}]
</pre><p>
Foreign keys definitions are subject to the following
conditions:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Both tables must be <code class="literal">InnoDB</code> tables and
they must not be <code class="literal">TEMPORARY</code> tables.
</p></li><li><p>
Corresponding columns in the foreign key and the referenced
key must have similar internal data types inside
<code class="literal">InnoDB</code> so that they can be compared
without a type conversion. <span class="emphasis"><em>The size and sign of
integer types must be the same</em></span>. The length of
string types need not be the same. For non-binary
(character) string columns, the character set and collation
must be the same.
</p></li><li><p>
In the referencing table, there must be an index where the
foreign key columns are listed as the
<span class="emphasis"><em>first</em></span> columns in the same order. Such
an index is created on the referencing table automatically
if it does not exist.
</p></li><li><p>
In the referenced table, there must be an index where the
referenced columns are listed as the
<span class="emphasis"><em>first</em></span> columns in the same order.
</p></li><li><p>
Index prefixes on foreign key columns are not supported. One
consequence of this is that <code class="literal">BLOB</code> and
<code class="literal">TEXT</code> columns cannot be included in a
foreign key, because indexes on those columns must always
include a prefix length.
</p></li><li><p>
If the <code class="literal">CONSTRAINT
<em class="replaceable"><code>symbol</code></em></code> clause is given,
the <em class="replaceable"><code>symbol</code></em> value must be unique
in the database. If the clause is not given,
<code class="literal">InnoDB</code> creates the name automatically.
</p></li></ul></div><p>
<code class="literal">InnoDB</code> rejects any <code class="literal">INSERT</code>
or <code class="literal">UPDATE</code> operation that attempts to create a
foreign key value in a child table if there is no a matching
candidate key value in the parent table. The action
<code class="literal">InnoDB</code> takes for any
<code class="literal">UPDATE</code> or <code class="literal">DELETE</code> operation
that attempts to update or delete a candidate key value in the
parent table that has some matching rows in the child table is
dependent on the <span class="emphasis"><em>referential action</em></span>
specified using <code class="literal">ON UPDATE</code> and <code class="literal">ON
DELETE</code> subclauses of the <code class="literal">FOREIGN
KEY</code> clause. When the user attempts to delete or update
a row from a parent table, and there are one or more matching
rows in the child table, <code class="literal">InnoDB</code> supports five
options regarding the action to be taken:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">CASCADE</code>: Delete or update the row from
the parent table and automatically delete or update the
matching rows in the child table. Both <code class="literal">ON DELETE
CASCADE</code> and <code class="literal">ON UPDATE CASCADE</code>
are supported. Between two tables, you should not define
several <code class="literal">ON UPDATE CASCADE</code> clauses that
act on the same column in the parent table or in the child
table.
</p></li><li><p>
<code class="literal">SET NULL</code>: Delete or update the row from
the parent table and set the foreign key column or columns
in the child table to <code class="literal">NULL</code>. This is valid
only if the foreign key columns do not have the <code class="literal">NOT
NULL</code> qualifier specified. Both <code class="literal">ON DELETE
SET NULL</code> and <code class="literal">ON UPDATE SET NULL</code>
clauses are supported.
</p><p>
If you specify a <code class="literal">SET NULL</code> action,
<span class="emphasis"><em>make sure that you have not declared the columns
in the child table as <code class="literal">NOT
NULL</code></em></span>.
</p></li><li><p>
<code class="literal">NO ACTION</code>: In standard SQL, <code class="literal">NO
ACTION</code> means <span class="emphasis"><em>no action</em></span> in the
sense that an attempt to delete or update a primary key
value is not allowed to proceed if there is a related
foreign key value in the referenced table.
<code class="literal">InnoDB</code> rejects the delete or update
operation for the parent table.
</p></li><li><p>
<code class="literal">RESTRICT</code>: Rejects the delete or update
operation for the parent table. <code class="literal">NO ACTION</code>
and <code class="literal">RESTRICT</code> are the same as omitting the
<code class="literal">ON DELETE</code> or <code class="literal">ON UPDATE</code>
clause. (Some database systems have deferred checks, and
<code class="literal">NO ACTION</code> is a deferred check. In MySQL,
foreign key constraints are checked immediately, so
<code class="literal">NO ACTION</code> and <code class="literal">RESTRICT</code>
are the same.)
</p></li><li><p>
<code class="literal">SET DEFAULT</code>: This action is recognized by
the parser, but <code class="literal">InnoDB</code> rejects table
definitions containing <code class="literal">ON DELETE SET
DEFAULT</code> or <code class="literal">ON UPDATE SET
DEFAULT</code> clauses.
</p></li></ul></div><p>
Note that <code class="literal">InnoDB</code> supports foreign key
references within a table. In these cases, “<span class="quote">child table
records</span>” really refers to dependent records within the
same table.
</p><p>
<code class="literal">InnoDB</code> requires indexes on foreign keys and
referenced keys so that foreign key checks can be fast and not
require a table scan. The index on the foreign key is created
automatically. This is in contrast to some older versions, in
which indexes had to be created explicitly or the creation of
foreign key constraints would fail.
</p><p>
If MySQL reports an error number 1005 from a <code class="literal">CREATE
TABLE</code> statement, and the error message refers to errno
150, table creation failed because a foreign key constraint was
not correctly formed. Similarly, if an <code class="literal">ALTER
TABLE</code> fails and it refers to errno 150, that means a
foreign key definition would be incorrectly formed for the
altered table. You can use <code class="literal">SHOW ENGINE INNODB
STATUS</code> to display a detailed explanation of the most
recent <code class="literal">InnoDB</code> foreign key error in the
server.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
<code class="literal">InnoDB</code> does not check foreign key
constraints on those foreign key or referenced key values that
contain a <code class="literal">NULL</code> column.
</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Currently, triggers are not activated by cascaded foreign key
actions.
</p></div><p>
<span class="bold"><strong>Deviation from SQL standards</strong></span>:
If there are several rows in the parent table that have the same
referenced key value, <code class="literal">InnoDB</code> acts in foreign
key checks as if the other parent rows with the same key value
do not exist. For example, if you have defined a
<code class="literal">RESTRICT</code> type constraint, and there is a
child row with several parent rows, <code class="literal">InnoDB</code>
does not allow the deletion of any of those parent rows.
</p><p>
<code class="literal">InnoDB</code> performs cascading operations through
a depth-first algorithm, based on records in the indexes
corresponding to the foreign key constraints.
</p><p>
<span class="bold"><strong>Deviation from SQL standards</strong></span>: A
<code class="literal">FOREIGN KEY</code> constraint that references a
non-<code class="literal">UNIQUE</code> key is not standard SQL. It is an
<code class="literal">InnoDB</code> extension to standard SQL.
</p><p>
<span class="bold"><strong>Deviation from SQL standards</strong></span>:
If <code class="literal">ON UPDATE CASCADE</code> or <code class="literal">ON UPDATE
SET NULL</code> recurses to update the <span class="emphasis"><em>same
table</em></span> it has previously updated during the cascade,
it acts like <code class="literal">RESTRICT</code>. This means that you
cannot use self-referential <code class="literal">ON UPDATE CASCADE</code>
or <code class="literal">ON UPDATE SET NULL</code> operations. This is to
prevent infinite loops resulting from cascaded updates. A
self-referential <code class="literal">ON DELETE SET NULL</code>, on the
other hand, is possible, as is a self-referential <code class="literal">ON
DELETE CASCADE</code>. Cascading operations may not be nested
more than 15 levels deep.
</p><p>
<span class="bold"><strong>Deviation from SQL standards</strong></span>:
Like MySQL in general, in an SQL statement that inserts,
deletes, or updates many rows, <code class="literal">InnoDB</code> checks
<code class="literal">UNIQUE</code> and <code class="literal">FOREIGN KEY</code>
constraints row-by-row. According to the SQL standard, the
default behavior should be deferred checking. That is,
constraints are only checked after the <span class="emphasis"><em>entire SQL
statement</em></span> has been processed. Until
<code class="literal">InnoDB</code> implements deferred constraint
checking, some things will be impossible, such as deleting a
record that refers to itself via a foreign key.
</p><p>
Here is a simple example that relates <code class="literal">parent</code>
and <code class="literal">child</code> tables through a single-column
foreign key:
</p><pre class="programlisting">CREATE TABLE parent (id INT NOT NULL,
PRIMARY KEY (id)
) ENGINE=INNODB;
CREATE TABLE child (id INT, parent_id INT,
INDEX par_ind (parent_id),
FOREIGN KEY (parent_id) REFERENCES parent(id)
ON DELETE CASCADE
) ENGINE=INNODB;
</pre><p>
A more complex example in which a
<code class="literal">product_order</code> table has foreign keys for two
other tables. One foreign key references a two-column index in
the <code class="literal">product</code> table. The other references a
single-column index in the <code class="literal">customer</code> table:
</p><pre class="programlisting">CREATE TABLE product (category INT NOT NULL, id INT NOT NULL,
price DECIMAL,
PRIMARY KEY(category, id)) ENGINE=INNODB;
CREATE TABLE customer (id INT NOT NULL,
PRIMARY KEY (id)) ENGINE=INNODB;
CREATE TABLE product_order (no INT NOT NULL AUTO_INCREMENT,
product_category INT NOT NULL,
product_id INT NOT NULL,
customer_id INT NOT NULL,
PRIMARY KEY(no),
INDEX (product_category, product_id),
FOREIGN KEY (product_category, product_id)
REFERENCES product(category, id)
ON UPDATE CASCADE ON DELETE RESTRICT,
INDEX (customer_id),
FOREIGN KEY (customer_id)
REFERENCES customer(id)) ENGINE=INNODB;
</pre><p>
<code class="literal">InnoDB</code> allows you to add a new foreign key
constraint to a table by using <code class="literal">ALTER TABLE</code>:
</p><pre class="programlisting">ALTER TABLE <em class="replaceable"><code>tbl_name</code></em>
ADD [CONSTRAINT <em class="replaceable"><code>symbol</code></em>] FOREIGN KEY [<em class="replaceable"><code>id</code></em>] (<em class="replaceable"><code>index_col_name</code></em>, ...)
REFERENCES <em class="replaceable"><code>tbl_name</code></em> (<em class="replaceable"><code>index_col_name</code></em>, ...)
[ON DELETE {RESTRICT | CASCADE | SET NULL | NO ACTION}]
[ON UPDATE {RESTRICT | CASCADE | SET NULL | NO ACTION}]
</pre><p>
<span class="bold"><strong>Remember to create the required indexes
first</strong></span>. You can also add a self-referential foreign
key constraint to a table using <code class="literal">ALTER TABLE</code>.
</p><a class="indexterm" name="id2906203"></a><a class="indexterm" name="id2906212"></a><a class="indexterm" name="id2906224"></a><p>
<code class="literal">InnoDB</code> also supports the use of
<code class="literal">ALTER TABLE</code> to drop foreign keys:
</p><pre class="programlisting">ALTER TABLE <em class="replaceable"><code>tbl_name</code></em> DROP FOREIGN KEY <em class="replaceable"><code>fk_symbol</code></em>;
</pre><p>
If the <code class="literal">FOREIGN KEY</code> clause included a
<code class="literal">CONSTRAINT</code> name when you created the foreign
key, you can refer to that name to drop the foreign key.
Otherwise, the <em class="replaceable"><code>fk_symbol</code></em> value is
internally generated by <code class="literal">InnoDB</code> when the
foreign key is created. To find out the symbol value when you
want to drop a foreign key, use the <code class="literal">SHOW CREATE
TABLE</code> statement. For example:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>SHOW CREATE TABLE ibtest11c\G</code></strong>
*************************** 1. row ***************************
Table: ibtest11c
Create Table: CREATE TABLE `ibtest11c` (
`A` int(11) NOT NULL auto_increment,
`D` int(11) NOT NULL default '0',
`B` varchar(200) NOT NULL default '',
`C` varchar(175) default NULL,
PRIMARY KEY (`A`,`D`,`B`),
KEY `B` (`B`,`C`),
KEY `C` (`C`),
CONSTRAINT `0_38775` FOREIGN KEY (`A`, `D`)
REFERENCES `ibtest11a` (`A`, `D`)
ON DELETE CASCADE ON UPDATE CASCADE,
CONSTRAINT `0_38776` FOREIGN KEY (`B`, `C`)
REFERENCES `ibtest11a` (`B`, `C`)
ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=INNODB CHARSET=latin1
1 row in set (0.01 sec)
mysql> <strong class="userinput"><code>ALTER TABLE ibtest11c DROP FOREIGN KEY `0_38775`;</code></strong>
</pre><p>
You cannot add a foreign key and drop a foreign key in separate
clauses of a single <code class="literal">ALTER TABLE</code> statement.
Separate statements are required.
</p><p>
If <code class="literal">ALTER TABLE</code> for an
<code class="literal">InnoDB</code> table results in changes to column
values (for example, because a column is truncated),
<code class="literal">InnoDB</code>'s <code class="literal">FOREIGN KEY</code>
constraint checks do not notice possible violations caused by
changing the values.
</p><p>
The <code class="literal">InnoDB</code> parser allows table and column
identifiers in a <code class="literal">FOREIGN KEY ... REFERENCES
...</code> clause to be quoted within backticks.
(Alternatively, double quotes can be used if the
<code class="literal">ANSI_QUOTES</code> SQL mode is enabled.) The
<code class="literal">InnoDB</code> parser also takes into account the
setting of the <code class="literal">lower_case_table_names</code> system
variable.
</p><p>
<code class="literal">InnoDB</code> returns a table's foreign key
definitions as part of the output of the <code class="literal">SHOW CREATE
TABLE</code> statement:
</p><pre class="programlisting">SHOW CREATE TABLE <em class="replaceable"><code>tbl_name</code></em>;
</pre><p>
<span><strong class="command">mysqldump</strong></span> also produces correct definitions
of tables to the dump file, and does not forget about the
foreign keys.
</p><p>
You can also display the foreign key constraints for a table
like this:
</p><pre class="programlisting">SHOW TABLE STATUS FROM <em class="replaceable"><code>db_name</code></em> LIKE '<em class="replaceable"><code>tbl_name</code></em>';
</pre><p>
The foreign key constraints are listed in the
<code class="literal">Comment</code> column of the output.
</p><p>
When performing foreign key checks, <code class="literal">InnoDB</code>
sets shared row-level locks on child or parent records it has to
look at. <code class="literal">InnoDB</code> checks foreign key
constraints immediately; the check is not deferred to
transaction commit.
</p><p>
To make it easier to reload dump files for tables that have
foreign key relationships, <span><strong class="command">mysqldump</strong></span>
automatically includes a statement in the dump output to set
<code class="literal">FOREIGN_KEY_CHECKS</code> to 0. This avoids problems
with tables having to be reloaded in a particular order when the
dump is reloaded. It is also possible to set this variable
manually:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>SET FOREIGN_KEY_CHECKS = 0;</code></strong>
mysql> <strong class="userinput"><code>SOURCE <em class="replaceable"><code>dump_file_name</code></em>;</code></strong>
mysql> <strong class="userinput"><code>SET FOREIGN_KEY_CHECKS = 1;</code></strong>
</pre><p>
This allows you to import the tables in any order if the dump
file contains tables that are not correctly ordered for foreign
keys. It also speeds up the import operation. Setting
<code class="literal">FOREIGN_KEY_CHECKS</code> to 0 can also be useful
for ignoring foreign key constraints during <code class="literal">LOAD
DATA</code> and <code class="literal">ALTER TABLE</code> operations.
However, even if <code class="literal">FOREIGN_KEY_CHECKS=0</code>, InnoDB
does not allow the creation of a foreign key constraint where a
column references a non-matching column type. Also, if an
<code class="literal">InnoDB</code> table has foreign key constraints,
<code class="literal">ALTER TABLE</code> cannot be used to change the
table to use another storage engine. To alter the storage
engine, you must drop any foreign key constraints first.
</p><p>
<code class="literal">InnoDB</code> does not allow you to drop a table
that is referenced by a <code class="literal">FOREIGN KEY</code>
constraint, unless you do <code class="literal">SET
FOREIGN_KEY_CHECKS=0</code>. When you drop a table, the
constraints that were defined in its create statement are also
dropped.
</p><p>
If you re-create a table that was dropped, it must have a
definition that conforms to the foreign key constraints
referencing it. It must have the right column names and types,
and it must have indexes on the referenced keys, as stated
earlier. If these are not satisfied, MySQL returns error number
1005 and refers to errno 150 in the error message.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-and-mysql-replication"></a>13.2.6.5. <code class="literal">InnoDB</code> and MySQL Replication</h4></div></div></div><p>
MySQL replication works for <code class="literal">InnoDB</code> tables as
it does for <code class="literal">MyISAM</code> tables. It is also
possible to use replication in a way where the storage engine on
the slave is not the same as the original storage engine on the
master. For example, you can replicate modifications to an
<code class="literal">InnoDB</code> table on the master to a
<code class="literal">MyISAM</code> table on the slave.
</p><p>
To set up a new slave for a master, you have to make a copy of
the <code class="literal">InnoDB</code> tablespace and the log files, as
well as the <code class="filename">.frm</code> files of the
<code class="literal">InnoDB</code> tables, and move the copies to the
slave. If the <code class="literal">innodb_file_per_table</code> variable
is enabled, you must also copy the <code class="filename">.ibd</code>
files as well. For the proper procedure to do this, see
<a href="storage-engines.html#innodb-backup" title="13.2.8. Backing Up and Recovering an InnoDB Database">Section 13.2.8, “Backing Up and Recovering an <code class="literal">InnoDB</code> Database”</a>.
</p><p>
If you can shut down the master or an existing slave, you can
take a cold backup of the <code class="literal">InnoDB</code> tablespace
and log files and use that to set up a slave. To make a new
slave without taking down any server you can also use the
non-free (commercial)
<a href="http://www.innodb.com/hot-backup" target="_top"><code class="literal">InnoDB
Hot Backup</code> tool</a>.
</p><p>
You cannot set up replication for <code class="literal">InnoDB</code>
using the <code class="literal">LOAD TABLE FROM MASTER</code> statement,
which works only for <code class="literal">MyISAM</code> tables. There are
two possible workarounds:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Dump the table on the master and import the dump file into
the slave.
</p></li><li><p>
Use <code class="literal">ALTER TABLE <em class="replaceable"><code>tbl_name</code></em>
ENGINE=MyISAM</code> on the master before setting up
replication with <code class="literal">LOAD TABLE
<em class="replaceable"><code>tbl_name</code></em> FROM MASTER</code>,
and then use <code class="literal">ALTER TABLE</code> to convert the
master table back to <code class="literal">InnoDB</code> afterward.
However, this should not be done for tables that have
foreign key definitions because the definitions will be
lost.
</p></li></ul></div><p>
Transactions that fail on the master do not affect replication
at all. MySQL replication is based on the binary log where MySQL
writes SQL statements that modify data. A transaction that fails
(for example, because of a foreign key violation, or because it
is rolled back) is not written to the binary log, so it is not
sent to slaves. See <a href="sql-syntax.html#commit" title="12.4.1. START TRANSACTION, COMMIT, and
ROLLBACK Syntax">Section 12.4.1, “<code class="literal">START TRANSACTION</code>, <code class="literal">COMMIT</code>, and
<code class="literal">ROLLBACK</code> Syntax”</a>.
</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>
Cascading actions for <code class="literal">InnoDB</code> tables on the
master are <span class="emphasis"><em>not</em></span> replicated to the slave.
For example, suppose you have two tables defined and populated
on both the master and the slave as shown here:
</p><pre class="programlisting">CREATE TABLE fc1 (
i INT PRIMARY KEY,
j INT
) ENGINE = InnoDB;
CREATE TABLE fc2 (
m INT PRIMARY KEY,
n INT,
FOREIGN KEY mi (m) REFERENCES fc1 (i)
ON DELETE CASCADE
) ENGINE = InnoDB;
INSERT INTO fc1 VALUES (1, 1), (2, 2);
INSERT INTO fc2 VALUES (1, 1), (2, 2), (3, 1);
</pre><p>
At this point, on both the master and the slave, table
<code class="literal">fc1</code> contains 2 rows, and table
<code class="literal">fc2</code> contains 3 rows. Now suppose that you
perform the following <code class="literal">DELETE</code> statement on
the master:
</p><pre class="programlisting">DELETE FROM fc1 WHERE i = 1;
</pre><p>
Due to the cascade, table <code class="literal">fc2</code> on the master
now contains only 1 row:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>SELECT * FROM fc2;</code></strong>
+---+---+
| m | n |
+---+---+
| 2 | 2 |
+---+---+
1 row in set (0.00 sec)
</pre><p>
However, the cascade does not propagate to the slave. The
slave's copy of <code class="literal">fc2</code> still contains all
of the rows that were originally inserted:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>SELECT * FROM fc2;</code></strong>
+---+---+
| m | n |
+---+---+
| 1 | 1 |
| 3 | 1 |
| 2 | 2 |
+---+---+
3 rows in set (0.00 sec)
</pre><p>
</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="adding-and-removing"></a>13.2.7. Adding and Removing <code class="literal">InnoDB</code> Data and Log Files</h3></div></div></div><p>
This section describes what you can do when your
<code class="literal">InnoDB</code> tablespace runs out of room or when you
want to change the size of the log files.
</p><p>
The easiest way to increase the size of the
<code class="literal">InnoDB</code> tablespace is to configure it from the
beginning to be auto-extending. Specify the
<code class="literal">autoextend</code> attribute for the last data file in
the tablespace definition. Then <code class="literal">InnoDB</code>
increases the size of that file automatically in 8MB increments
when it runs out of space. The increment size can be changed by
setting the value of the
<code class="literal">innodb_autoextend_increment</code> system variable,
which is measured in MB.
</p><p>
Alternatively, you can increase the size of your tablespace by
adding another data file. To do this, you have to shut down the
MySQL server, change the tablespace configuration to add a new
data file to the end of <code class="literal">innodb_data_file_path</code>,
and start the server again.
</p><p>
If your last data file was defined with the keyword
<code class="literal">autoextend</code>, the procedure for reconfiguring the
tablespace must take into account the size to which the last data
file has grown. Obtain the size of the data file, round it down to
the closest multiple of 1024 × 1024 bytes (= 1MB), and
specify the rounded size explicitly in
<code class="literal">innodb_data_file_path</code>. Then you can add another
data file. Remember that only the last data file in the
<code class="literal">innodb_data_file_path</code> can be specified as
auto-extending.
</p><p>
As an example, assume that the tablespace has just one
auto-extending data file <code class="filename">ibdata1</code>:
</p><pre class="programlisting">innodb_data_home_dir =
innodb_data_file_path = /ibdata/ibdata1:10M:autoextend
</pre><p>
Suppose that this data file, over time, has grown to 988MB. Here
is the configuration line after modifying the original data file
to not be auto-extending and adding another auto-extending data
file:
</p><pre class="programlisting">innodb_data_home_dir =
innodb_data_file_path = /ibdata/ibdata1:988M;/disk2/ibdata2:50M:autoextend
</pre><p>
When you add a new file to the tablespace configuration, make sure
that it does not exist. <code class="literal">InnoDB</code> will create and
initialize the file when you restart the server.
</p><p>
Currently, you cannot remove a data file from the tablespace. To
decrease the size of your tablespace, use this procedure:
</p><div class="orderedlist"><ol type="1"><li><p>
Use <span><strong class="command">mysqldump</strong></span> to dump all your
<code class="literal">InnoDB</code> tables.
</p></li><li><p>
Stop the server.
</p></li><li><p>
Remove all the existing tablespace files.
</p></li><li><p>
Configure a new tablespace.
</p></li><li><p>
Restart the server.
</p></li><li><p>
Import the dump files.
</p></li></ol></div><p>
If you want to change the number or the size of your
<code class="literal">InnoDB</code> log files, use the following
instructions. The procedure to use depends on the value of
<code class="literal">innodb_fast_shutdown</code>:
</p><div class="itemizedlist"><ul type="disc"><li><p>
If <code class="literal">innodb_fast_shutdown</code> is not set to 2:
You must stop the MySQL server and make sure that it shuts
down without errors (to ensure that there is no information
for outstanding transactions in the logs). Then copy the old
log files into a safe place just in case something went wrong
in the shutdown and you need them to recover the tablespace.
Delete the old log files from the log file directory, edit
<code class="filename">my.cnf</code> to change the log file
configuration, and start the MySQL server again.
<span><strong class="command">mysqld</strong></span> sees that no log files exist at
startup and tells you that it is creating new ones.
</p></li><li><p>
If <code class="literal">innodb_fast_shutdown</code> is set to 2: You
should shut down the server, set
<code class="literal">innodb_fast_shutdown</code> to 1, and restart the
server. The server should be allowed to recover. Then you
should shut down the server again and follow the procedure
described in the preceding item to change
<code class="literal">InnoDB</code> log file size. Set
<code class="literal">innodb_fast_shutdown</code> back to 2 and restart
the server.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-backup"></a>13.2.8. Backing Up and Recovering an <code class="literal">InnoDB</code> Database</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#forcing-recovery">13.2.8.1. Forcing <code class="literal">InnoDB</code> Recovery</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-checkpoints">13.2.8.2. Checkpoints</a></span></dt></dl></div><p>
The key to safe database management is making regular backups.
</p><p>
<span><strong class="command">InnoDB Hot Backup</strong></span> is an online backup tool you
can use to backup your <code class="literal">InnoDB</code> database while it
is running. <span><strong class="command">InnoDB Hot Backup</strong></span> does not require
you to shut down your database and it does not set any locks or
disturb your normal database processing. <span><strong class="command">InnoDB Hot
Backup</strong></span> is a non-free (commercial) add-on tool with an
annual license fee of €390 per computer on which the MySQL
server is run. See the
<a href="http://www.innodb.com/hot-backup" target="_top"><span><strong class="command">InnoDB Hot
Backup</strong></span> home page</a> for detailed information and
screenshots.
</p><p>
If you are able to shut down your MySQL server, you can make a
binary backup that consists of all files used by
<code class="literal">InnoDB</code> to manage its tables. Use the following
procedure:
</p><div class="orderedlist"><ol type="1"><li><p>
Shut down your MySQL server and make sure that it shuts down
without errors.
</p></li><li><p>
Copy all your data files (<code class="filename">ibdata</code> files
and <code class="filename">.ibd</code> files) into a safe place.
</p></li><li><p>
Copy all your <code class="filename">ib_logfile</code> files to a safe
place.
</p></li><li><p>
Copy your <code class="filename">my.cnf</code> configuration file or
files to a safe place.
</p></li><li><p>
Copy all the <code class="filename">.frm</code> files for your
<code class="literal">InnoDB</code> tables to a safe place.
</p></li></ol></div><p>
Replication works with <code class="literal">InnoDB</code> tables, so you
can use MySQL replication capabilities to keep a copy of your
database at database sites requiring high availability.
</p><p>
In addition to making binary backups as just described, you should
also regularly make dumps of your tables with
<span><strong class="command">mysqldump</strong></span>. The reason for this is that a binary
file might be corrupted without you noticing it. Dumped tables are
stored into text files that are human-readable, so spotting table
corruption becomes easier. Also, because the format is simpler,
the chance for serious data corruption is smaller.
<span><strong class="command">mysqldump</strong></span> also has a
<code class="option">--single-transaction</code> option that you can use to
make a consistent snapshot without locking out other clients.
</p><p>
To be able to recover your <code class="literal">InnoDB</code> database to
the present from the binary backup just described, you have to run
your MySQL server with binary logging turned on. Then you can
apply the binary log to the backup database to achieve
point-in-time recovery:
</p><pre class="programlisting">mysqlbinlog <em class="replaceable"><code>yourhostname</code></em>-bin.123 | mysql
</pre><p>
To recover from a crash of your MySQL server, the only requirement
is to restart it. <code class="literal">InnoDB</code> automatically checks
the logs and performs a roll-forward of the database to the
present. <code class="literal">InnoDB</code> automatically rolls back
uncommitted transactions that were present at the time of the
crash. During recovery, <span><strong class="command">mysqld</strong></span> displays output
something like this:
</p><pre class="programlisting">InnoDB: Database was not shut down normally.
InnoDB: Starting recovery from log files...
InnoDB: Starting log scan based on checkpoint at
InnoDB: log sequence number 0 13674004
InnoDB: Doing recovery: scanned up to log sequence number 0 13739520
InnoDB: Doing recovery: scanned up to log sequence number 0 13805056
InnoDB: Doing recovery: scanned up to log sequence number 0 13870592
InnoDB: Doing recovery: scanned up to log sequence number 0 13936128
...
InnoDB: Doing recovery: scanned up to log sequence number 0 20555264
InnoDB: Doing recovery: scanned up to log sequence number 0 20620800
InnoDB: Doing recovery: scanned up to log sequence number 0 20664692
InnoDB: 1 uncommitted transaction(s) which must be rolled back
InnoDB: Starting rollback of uncommitted transactions
InnoDB: Rolling back trx no 16745
InnoDB: Rolling back of trx no 16745 completed
InnoDB: Rollback of uncommitted transactions completed
InnoDB: Starting an apply batch of log records to the database...
InnoDB: Apply batch completed
InnoDB: Started
mysqld: ready for connections
</pre><p>
If your database gets corrupted or your disk fails, you have to do
the recovery from a backup. In the case of corruption, you should
first find a backup that is not corrupted. After restoring the
base backup, do the recovery from the binary log files using
<span><strong class="command">mysqlbinlog</strong></span> and <span><strong class="command">mysql</strong></span> to
restore the changes performed after the backup was made.
</p><p>
In some cases of database corruption it is enough just to dump,
drop, and re-create one or a few corrupt tables. You can use the
<code class="literal">CHECK TABLE</code> SQL statement to check whether a
table is corrupt, although <code class="literal">CHECK TABLE</code>
naturally cannot detect every possible kind of corruption. You can
use <code class="literal">innodb_tablespace_monitor</code> to check the
integrity of the file space management inside the tablespace
files.
</p><p>
In some cases, apparent database page corruption is actually due
to the operating system corrupting its own file cache, and the
data on disk may be okay. It is best first to try restarting your
computer. Doing so may eliminate errors that appeared to be
database page corruption.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="forcing-recovery"></a>13.2.8.1. Forcing <code class="literal">InnoDB</code> Recovery</h4></div></div></div><p>
If there is database page corruption, you may want to dump your
tables from the database with <code class="literal">SELECT INTO
OUTFILE</code>. Usually, most of the data obtained in this
way is intact. Even so, the corruption may cause <code class="literal">SELECT
* FROM <em class="replaceable"><code>tbl_name</code></em></code> statements
or <code class="literal">InnoDB</code> background operations to crash or
assert, or even to cause <code class="literal">InnoDB</code> roll-forward
recovery to crash. However, you can force the
<code class="literal">InnoDB</code> storage engine to start up while
preventing background operations from running, so that you are
able to dump your tables. For example, you can add the following
line to the <code class="literal">[mysqld]</code> section of your option
file before restarting the server:
</p><pre class="programlisting">[mysqld]
innodb_force_recovery = 4
</pre><p>
The allowable non-zero values for
<code class="literal">innodb_force_recovery</code> follow. A larger number
includes all precautions of smaller numbers. If you are able to
dump your tables with an option value of at most 4, then you are
relatively safe that only some data on corrupt individual pages
is lost. A value of 6 is more drastic because database pages are
left in an obsolete state, which in turn may introduce more
corruption into B-trees and other database structures.
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">1</code>
(<code class="literal">SRV_FORCE_IGNORE_CORRUPT</code>)
</p><p>
Let the server run even if it detects a corrupt page. Try to
make <code class="literal">SELECT * FROM
<em class="replaceable"><code>tbl_name</code></em></code> jump over
corrupt index records and pages, which helps in dumping
tables.
</p></li><li><p>
<code class="literal">2</code>
(<code class="literal">SRV_FORCE_NO_BACKGROUND</code>)
</p><p>
Prevent the main thread from running. If a crash would occur
during the purge operation, this recovery value prevents it.
</p></li><li><p>
<code class="literal">3</code>
(<code class="literal">SRV_FORCE_NO_TRX_UNDO</code>)
</p><p>
Do not run transaction rollbacks after recovery.
</p></li><li><p>
<code class="literal">4</code>
(<code class="literal">SRV_FORCE_NO_IBUF_MERGE</code>)
</p><p>
Prevent also insert buffer merge operations. If they would
cause a crash, do not do them. Do not calculate table
statistics.
</p></li><li><p>
<code class="literal">5</code>
(<code class="literal">SRV_FORCE_NO_UNDO_LOG_SCAN</code>)
</p><p>
Do not look at undo logs when starting the database:
<code class="literal">InnoDB</code> treats even incomplete
transactions as committed.
</p></li><li><p>
<code class="literal">6</code>
(<code class="literal">SRV_FORCE_NO_LOG_REDO</code>)
</p><p>
Do not do the log roll-forward in connection with recovery.
</p></li></ul></div><p>
You can <code class="literal">SELECT</code> from tables to dump them, or
<code class="literal">DROP</code> or <code class="literal">CREATE</code> tables even
if forced recovery is used. If you know that a given table is
causing a crash on rollback, you can drop it. You can also use
this to stop a runaway rollback caused by a failing mass import
or <code class="literal">ALTER TABLE</code>. You can kill the
<span><strong class="command">mysqld</strong></span> process and set
<code class="literal">innodb_force_recovery</code> to <code class="literal">3</code>
to bring the database up without the rollback, then
<code class="literal">DROP</code> the table that is causing the runaway
rollback.
</p><p>
<span class="emphasis"><em>The database must not otherwise be used with any
non-zero value of
<code class="literal">innodb_force_recovery</code></em></span>. As a safety
measure, <code class="literal">InnoDB</code> prevents users from
performing <code class="literal">INSERT</code>, <code class="literal">UPDATE</code>,
or <code class="literal">DELETE</code> operations when
<code class="literal">innodb_force_recovery</code> is greater than 0.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-checkpoints"></a>13.2.8.2. Checkpoints</h4></div></div></div><p>
<code class="literal">InnoDB</code> implements a checkpoint mechanism
known as “<span class="quote">fuzzy</span>” checkpointing.
<code class="literal">InnoDB</code> flushes modified database pages from
the buffer pool in small batches. There is no need to flush the
buffer pool in one single batch, which would in practice stop
processing of user SQL statements during the checkpointing
process.
</p><p>
During crash recovery, <code class="literal">InnoDB</code> looks for a
checkpoint label written to the log files. It knows that all
modifications to the database before the label are present in
the disk image of the database. Then <code class="literal">InnoDB</code>
scans the log files forward from the checkpoint, applying the
logged modifications to the database.
</p><p>
<code class="literal">InnoDB</code> writes to its log files on a rotating
basis. All committed modifications that make the database pages
in the buffer pool different from the images on disk must be
available in the log files in case <code class="literal">InnoDB</code> has
to do a recovery. This means that when <code class="literal">InnoDB</code>
starts to reuse a log file, it has to make sure that the
database page images on disk contain the modifications logged in
the log file that <code class="literal">InnoDB</code> is going to reuse.
In other words, <code class="literal">InnoDB</code> must create a
checkpoint and this often involves flushing of modified database
pages to disk.
</p><p>
The preceding description explains why making your log files
very large may save disk I/O in checkpointing. It often makes
sense to set the total size of the log files as big as the
buffer pool or even bigger. The drawback of using large log
files is that crash recovery can take longer because there is
more logged information to apply to the database.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="moving"></a>13.2.9. Moving an <code class="literal">InnoDB</code> Database to Another Machine</h3></div></div></div><p>
On Windows, <code class="literal">InnoDB</code> always stores database and
table names internally in lowercase. To move databases in a binary
format from Unix to Windows or from Windows to Unix, you should
have all table and database names in lowercase. A convenient way
to accomplish this is to add the following line to the
<code class="literal">[mysqld]</code> section of your
<code class="filename">my.cnf</code> or <code class="filename">my.ini</code> file
before creating any databases or tables:
</p><pre class="programlisting">[mysqld]
lower_case_table_names=1
</pre><p>
Like <code class="literal">MyISAM</code> data files,
<code class="literal">InnoDB</code> data and log files are binary-compatible
on all platforms having the same floating-point number format. You
can move an <code class="literal">InnoDB</code> database simply by copying
all the relevant files listed in <a href="storage-engines.html#innodb-backup" title="13.2.8. Backing Up and Recovering an InnoDB Database">Section 13.2.8, “Backing Up and Recovering an <code class="literal">InnoDB</code> Database”</a>.
If the floating-point formats differ but you have not used
<code class="literal">FLOAT</code> or <code class="literal">DOUBLE</code> data types
in your tables, then the procedure is the same: simply copy the
relevant files. If the formats differ and your tables contain
floating-point data, you must use <span><strong class="command">mysqldump</strong></span> to
dump your tables on one machine and then import the dump files on
the other machine.
</p><p>
One way to increase performance is to switch off autocommit mode
when importing data, assuming that the tablespace has enough space
for the big rollback segment that the import transactions
generate. Do the commit only after importing a whole table or a
segment of a table.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-transaction-model"></a>13.2.10. <code class="literal">InnoDB</code> Transaction Model and Locking</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#innodb-lock-modes">13.2.10.1. <code class="literal">InnoDB</code> Lock Modes</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-and-autocommit">13.2.10.2. <code class="literal">InnoDB</code> and <code class="literal">AUTOCOMMIT</code></a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-transaction-isolation">13.2.10.3. <code class="literal">InnoDB</code> and <code class="literal">TRANSACTION ISOLATION
LEVEL</code></a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-consistent-read">13.2.10.4. Consistent Non-Locking Read</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-locking-reads">13.2.10.5. <code class="literal">SELECT ... FOR UPDATE</code> and <code class="literal">SELECT ... LOCK IN
SHARE MODE</code> Locking Reads</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-next-key-locking">13.2.10.6. Next-Key Locking: Avoiding the Phantom Problem</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-consistent-read-example">13.2.10.7. An Example of Consistent Read in <code class="literal">InnoDB</code></a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-locks-set">13.2.10.8. Locks Set by Different SQL Statements in <code class="literal">InnoDB</code></a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-implicit-commit">13.2.10.9. Implicit Transaction Commit and Rollback</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-deadlock-detection">13.2.10.10. Deadlock Detection and Rollback</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-deadlocks">13.2.10.11. How to Cope with Deadlocks</a></span></dt></dl></div><p>
In the <code class="literal">InnoDB</code> transaction model, the goal is to
combine the best properties of a multi-versioning database with
traditional two-phase locking. <code class="literal">InnoDB</code> does
locking on the row level and runs queries as non-locking
consistent reads by default, in the style of Oracle. The lock
table in <code class="literal">InnoDB</code> is stored so space-efficiently
that lock escalation is not needed: Typically several users are
allowed to lock every row in the database, or any random subset of
the rows, without <code class="literal">InnoDB</code> running out of memory.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-lock-modes"></a>13.2.10.1. <code class="literal">InnoDB</code> Lock Modes</h4></div></div></div><p>
<code class="literal">InnoDB</code> implements standard row-level locking
where there are two types of locks:
</p><div class="itemizedlist"><ul type="disc"><li><p>
A shared (<em class="replaceable"><code>S</code></em>) lock allows a
transaction to read a row (tuple).
</p></li><li><p>
An exclusive (<em class="replaceable"><code>X</code></em>) lock allows a
transaction to update or delete a row.
</p></li></ul></div><p>
If transaction <code class="literal">T1</code> holds a shared
(<em class="replaceable"><code>S</code></em>) lock on tuple
<code class="literal">t</code>, then
</p><div class="itemizedlist"><ul type="disc"><li><p>
A request from some distinct transaction
<code class="literal">T2</code> for an <em class="replaceable"><code>S</code></em>
lock on <code class="literal">t</code> can be granted immediately. As
a result, both <code class="literal">T1</code> and
<code class="literal">T2</code> hold an <em class="replaceable"><code>S</code></em>
lock on <code class="literal">t</code>.
</p></li><li><p>
A request from some distinct transaction
<code class="literal">T2</code> for an <em class="replaceable"><code>X</code></em>
lock on <code class="literal">t</code> cannot be granted immediately.
</p></li></ul></div><p>
If a transaction <code class="literal">T1</code> holds an exclusive
(<em class="replaceable"><code>X</code></em>) lock on tuple
<code class="literal">t</code>, then a request from some distinct
transaction <code class="literal">T2</code> for a lock of either type on
<code class="literal">t</code> cannot be granted immediately. Instead,
transaction <code class="literal">T2</code> has to wait for transaction
<code class="literal">T1</code> to release its lock on tuple
<code class="literal">t</code>.
</p><p>
Additionally, <code class="literal">InnoDB</code> supports
<span class="emphasis"><em>multiple granularity locking</em></span> which allows
coexistence of record locks and locks on entire tables. To make
locking at multiple granularity levels practical, additional
types of locks called <span class="emphasis"><em>intention locks</em></span> are
used. Intention locks are table locks in
<code class="literal">InnoDB</code>. The idea behind intention locks is
for a transaction to indicate which type of lock (shared or
exclusive) it will require later for a row in that table. There
are two types of intention locks used in
<code class="literal">InnoDB</code> (assume that transaction
<code class="literal">T</code> has requested a lock of the indicated type
on table <code class="literal">R</code>):
</p><div class="itemizedlist"><ul type="disc"><li><p>
Intention shared (<em class="replaceable"><code>IS</code></em>):
Transaction <code class="literal">T</code> intends to set
<em class="replaceable"><code>S</code></em> locks on individual rows in
table <code class="literal">R</code>.
</p></li><li><p>
Intention exclusive (<em class="replaceable"><code>IX</code></em>):
Transaction <code class="literal">T</code> intends to set
<em class="replaceable"><code>X</code></em> locks on those rows.
</p></li></ul></div><p>
The intention locking protocol is as follows:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Before a given transaction can acquire an
<em class="replaceable"><code>S</code></em> lock on a given row, it must
first acquire an <em class="replaceable"><code>IS</code></em> or stronger
lock on the table containing that row.
</p></li><li><p>
Before a given transaction can acquire an
<em class="replaceable"><code>X</code></em> lock on a given row, it must
first acquire an <em class="replaceable"><code>IX</code></em> lock on the
table containing that row.
</p></li></ul></div><p>
These rules can be conveniently summarized by means of a
<span class="emphasis"><em>lock type compatibility matrix</em></span>:
</p><div class="informaltable"><table border="1"><colgroup><col><col><col><col><col></colgroup><tbody><tr><td> </td><td><em class="replaceable"><code>X</code></em></td><td><em class="replaceable"><code>IX</code></em></td><td><em class="replaceable"><code>S</code></em></td><td><em class="replaceable"><code>IS</code></em></td></tr><tr><td><em class="replaceable"><code>X</code></em></td><td>Conflict</td><td>Conflict</td><td>Conflict</td><td>Conflict</td></tr><tr><td><em class="replaceable"><code>IX</code></em></td><td>Conflict</td><td>Compatible</td><td>Conflict</td><td>Compatible</td></tr><tr><td><em class="replaceable"><code>S</code></em></td><td>Conflict</td><td>Conflict</td><td>Compatible</td><td>Compatible</td></tr><tr><td><em class="replaceable"><code>IS</code></em></td><td>Conflict</td><td>Compatible</td><td>Compatible</td><td>Compatible</td></tr></tbody></table></div><p>
A lock is granted to a requesting transaction if it is
compatible with existing locks. A lock is not granted to a
requesting transaction if it conflicts with existing locks. A
transaction waits until the conflicting existing lock is
released. If a lock request conflicts with an existing lock and
cannot be granted because it would cause deadlock, an error
occurs.
</p><p>
Thus, intention locks do not block anything except full table
requests (for example, <code class="literal">LOCK TABLES ...
WRITE</code>). The main purpose of
<em class="replaceable"><code>IX</code></em> and <em class="replaceable"><code>IS</code></em>
locks is to show that someone is locking a row, or going to lock
a row in the table.
</p><p>
The following example illustrates how an error can occur when a
lock request would cause a deadlock. The example involves two
clients, A and B.
</p><p>
First, client A creates a table containing one row, and then
begins a transaction. Within the transaction, A obtains an
<em class="replaceable"><code>S</code></em> lock on the row by selecting it in
share mode:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>CREATE TABLE t (i INT) ENGINE = InnoDB;</code></strong>
Query OK, 0 rows affected (1.07 sec)
mysql> <strong class="userinput"><code>INSERT INTO t (i) VALUES(1);</code></strong>
Query OK, 1 row affected (0.09 sec)
mysql> <strong class="userinput"><code>START TRANSACTION;</code></strong>
Query OK, 0 rows affected (0.00 sec)
mysql> <strong class="userinput"><code>SELECT * FROM t WHERE i = 1 LOCK IN SHARE MODE;</code></strong>
+------+
| i |
+------+
| 1 |
+------+
1 row in set (0.10 sec)
</pre><p>
Next, client B begins a transaction and attempts to delete the
row from the table:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>START TRANSACTION;</code></strong>
Query OK, 0 rows affected (0.00 sec)
mysql> <strong class="userinput"><code>DELETE FROM t WHERE i = 1;</code></strong>
</pre><p>
The delete operation requires an <em class="replaceable"><code>X</code></em>
lock. The lock cannot be granted because it is incompatible with
the <em class="replaceable"><code>S</code></em> lock that client A holds, so
the request goes on the queue of lock requests for the row and
client B blocks.
</p><p>
Finally, client A also attempts to delete the row from the
table:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>DELETE FROM t WHERE i = 1;</code></strong>
ERROR 1213 (40001): Deadlock found when trying to get lock;
try restarting transaction
</pre><p>
Deadlock occurs here because client A needs an
<em class="replaceable"><code>X</code></em> lock to delete the row. However,
that lock request cannot be granted because client B already has
a request for an <em class="replaceable"><code>X</code></em> lock and is
waiting for client A to release its <em class="replaceable"><code>S</code></em>
lock. Nor can the <em class="replaceable"><code>S</code></em> lock held by A be
upgraded to an <em class="replaceable"><code>X</code></em> lock because of the
prior request by B for an <em class="replaceable"><code>X</code></em> lock. As
a result, <code class="literal">InnoDB</code> generates an error for
client A and releases its locks. At that point, the lock request
for client B can be granted and B deletes the row from the
table.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-and-autocommit"></a>13.2.10.2. <code class="literal">InnoDB</code> and <code class="literal">AUTOCOMMIT</code></h4></div></div></div><p>
In <code class="literal">InnoDB</code>, all user activity occurs inside a
transaction. If the autocommit mode is enabled, each SQL
statement forms a single transaction on its own. By default,
MySQL starts new connections with autocommit enabled.
</p><p>
If the autocommit mode is switched off with <code class="literal">SET
AUTOCOMMIT = 0</code>, then we can consider that a user
always has a transaction open. An SQL <code class="literal">COMMIT</code>
or <code class="literal">ROLLBACK</code> statement ends the current
transaction and a new one starts. A <code class="literal">COMMIT</code>
means that the changes made in the current transaction are made
permanent and become visible to other users. A
<code class="literal">ROLLBACK</code> statement, on the other hand,
cancels all modifications made by the current transaction. Both
statements release all <code class="literal">InnoDB</code> locks that were
set during the current transaction.
</p><p>
If the connection has autocommit enabled, the user can still
perform a multiple-statement transaction by starting it with an
explicit <code class="literal">START TRANSACTION</code> or
<code class="literal">BEGIN</code> statement and ending it with
<code class="literal">COMMIT</code> or <code class="literal">ROLLBACK</code>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-transaction-isolation"></a>13.2.10.3. <code class="literal">InnoDB</code> and <code class="literal">TRANSACTION ISOLATION
LEVEL</code></h4></div></div></div><p>
In terms of the SQL:1992 transaction isolation levels, the
<code class="literal">InnoDB</code> default is <code class="literal">REPEATABLE
READ</code>. <code class="literal">InnoDB</code> offers all four
transaction isolation levels described by the SQL standard. You
can set the default isolation level for all connections by using
the <code class="option">--transaction-isolation</code> option on the
command line or in an option file. For example, you can set the
option in the <code class="literal">[mysqld]</code> section of an option
file like this:
</p><pre class="programlisting">[mysqld]
transaction-isolation = {READ-UNCOMMITTED | READ-COMMITTED
| REPEATABLE-READ | SERIALIZABLE}
</pre><p>
A user can change the isolation level for a single session or
for all new incoming connections with the <code class="literal">SET
TRANSACTION</code> statement. Its syntax is as follows:
</p><pre class="programlisting">SET [SESSION | GLOBAL] TRANSACTION ISOLATION LEVEL
{READ UNCOMMITTED | READ COMMITTED
| REPEATABLE READ | SERIALIZABLE}
</pre><p>
Note that there are hyphens in the level names for the
<code class="option">--transaction-isolation</code> option, but not for the
<code class="literal">SET TRANSACTION</code> statement.
</p><p>
The default behavior is to set the isolation level for the next
(not started) transaction. If you use the
<code class="literal">GLOBAL</code> keyword, the statement sets the
default transaction level globally for all new connections
created from that point on (but not for existing connections).
You need the <code class="literal">SUPER</code> privilege to do this.
Using the <code class="literal">SESSION</code> keyword sets the default
transaction level for all future transactions performed on the
current connection.
</p><p>
Any client is free to change the session isolation level (even
in the middle of a transaction), or the isolation level for the
next transaction.
</p><p>
You can determine the global and session transaction isolation
levels by checking the value of the
<code class="literal">tx_isolation</code> system variable with these
statements:
</p><pre class="programlisting">SELECT @@global.tx_isolation;
SELECT @@tx_isolation;
</pre><a class="indexterm" name="id2909174"></a><a class="indexterm" name="id2909183"></a><p>
In row-level locking, <code class="literal">InnoDB</code> uses next-key
locking. That means that besides index records,
<code class="literal">InnoDB</code> can also lock the “<span class="quote">gap</span>”
preceding an index record to block insertions by other users
immediately before the index record. A next-key lock refers to a
lock that locks an index record and the gap before it. A gap
lock refers to a lock that only locks a gap before some index
record. Next-key locking for searches or index scans can be
disabled by enabling the
<code class="literal">innodb_locks_unsafe_for_binlog</code> system
variable.
</p><p>
A detailed description of each isolation level in
<code class="literal">InnoDB</code> follows:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">READ UNCOMMITTED</code>
</p><p>
<code class="literal">SELECT</code> statements are performed in a
non-locking fashion, but a possible earlier version of a
record might be used. Thus, using this isolation level, such
reads are not consistent. This is also called a “<span class="quote">dirty
read.</span>” Otherwise, this isolation level works like
<code class="literal">READ COMMITTED</code>.
</p></li><li><p>
<code class="literal">READ COMMITTED</code>
</p><p>
A somewhat Oracle-like isolation level. All <code class="literal">SELECT
... FOR UPDATE</code> and <code class="literal">SELECT ... LOCK IN
SHARE MODE</code> statements lock only the index records,
not the gaps before them, and thus allow the free insertion
of new records next to locked records.
<code class="literal">UPDATE</code> and <code class="literal">DELETE</code>
statements using a unique index with a unique search
condition lock only the index record found, not the gap
before it. In range-type <code class="literal">UPDATE</code> and
<code class="literal">DELETE</code> statements,
<code class="literal">InnoDB</code> must set next-key or gap locks and
block insertions by other users to the gaps covered by the
range. This is necessary because “<span class="quote">phantom rows</span>”
must be blocked for MySQL replication and recovery to work.
</p><p>
Consistent reads behave as in Oracle: Each consistent read,
even within the same transaction, sets and reads its own
fresh snapshot. See
<a href="storage-engines.html#innodb-consistent-read" title="13.2.10.4. Consistent Non-Locking Read">Section 13.2.10.4, “Consistent Non-Locking Read”</a>.
</p></li><li><p>
<code class="literal">REPEATABLE READ</code>
</p><p>
This is the default isolation level of
<code class="literal">InnoDB</code>. <code class="literal">SELECT ... FOR
UPDATE</code>, <code class="literal">SELECT ... LOCK IN SHARE
MODE</code>, <code class="literal">UPDATE</code>, and
<code class="literal">DELETE</code> statements that use a unique index
with a unique search condition lock only the index record
found, not the gap before it. With other search conditions,
these operations employ next-key locking, locking the index
range scanned with next-key or gap locks, and block new
insertions by other users.
</p><p>
In consistent reads, there is an important difference from
the <code class="literal">READ COMMITTED</code> isolation level: All
consistent reads within the same transaction read the same
snapshot established by the first read. This convention
means that if you issue several plain
<code class="literal">SELECT</code> statements within the same
transaction, these <code class="literal">SELECT</code> statements are
consistent also with respect to each other. See
<a href="storage-engines.html#innodb-consistent-read" title="13.2.10.4. Consistent Non-Locking Read">Section 13.2.10.4, “Consistent Non-Locking Read”</a>.
</p></li><li><p>
<code class="literal">SERIALIZABLE</code>
</p><p>
This level is like <code class="literal">REPEATABLE READ</code>, but
<code class="literal">InnoDB</code> implicitly converts all plain
<code class="literal">SELECT</code> statements to <code class="literal">SELECT ...
LOCK IN SHARE MODE</code>.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-consistent-read"></a>13.2.10.4. Consistent Non-Locking Read</h4></div></div></div><p>
A consistent read means that <code class="literal">InnoDB</code> uses
multi-versioning to present to a query a snapshot of the
database at a point in time. The query sees the changes made by
those transactions that committed before that point of time, and
no changes made by later or uncommitted transactions. The
exception to this rule is that the query sees the changes made
by earlier statements within the same transaction. Note that the
exception to the rule causes the following anomaly: if you
update some rows in a table, a <code class="literal">SELECT</code> will
see the latest version of the updated rows, but it might also
see older versions of any rows. If other users simultaneously
update the same table, the anomaly means that you may see the
table in a state that never existed in the database.
</p><p>
If you are running with the default <code class="literal">REPEATABLE
READ</code> isolation level, all consistent reads within the
same transaction read the snapshot established by the first such
read in that transaction. You can get a fresher snapshot for
your queries by committing the current transaction and after
that issuing new queries.
</p><p>
Consistent read is the default mode in which
<code class="literal">InnoDB</code> processes <code class="literal">SELECT</code>
statements in <code class="literal">READ COMMITTED</code> and
<code class="literal">REPEATABLE READ</code> isolation levels. A
consistent read does not set any locks on the tables it
accesses, and therefore other users are free to modify those
tables at the same time a consistent read is being performed on
the table.
</p><p>
Note that consistent read does not work over <code class="literal">DROP
TABLE</code> and over <code class="literal">ALTER TABLE</code>.
Consistent read does not work over <code class="literal">DROP TABLE</code>
because MySQL can't use a table that has been dropped and
<code class="literal">InnoDB</code> destroys the table. Consistent read
does not work over <code class="literal">ALTER TABLE</code> because
<code class="literal">ALTER TABLE</code> works by making a temporary copy
of the original table and deleting the original table when the
temporary copy is built. When you reissue a consistent read
within a transaction, rows in the new table are not visible
because those rows did not exist when the transaction's snapshot
was taken.
</p><p>
<code class="literal">InnoDB</code> uses a consistent read for select in
clauses like <code class="literal">INSERT INTO ... SELECT</code> and
<code class="literal">UPDATE ... (SELECT)</code> that do not specify
<code class="literal">FOR UPDATE</code> or <code class="literal">IN SHARE
MODE</code> if the
<code class="literal">innodb_locks_unsafe_for_binlog</code> option is set
and the isolation level of the transaction is not set to
serializable. Thus no locks are set to rows read from selected
table. Otherwise, <code class="literal">InnoDB</code> uses stronger locks
and the <code class="literal">SELECT</code> part acts like <code class="literal">READ
COMMITTED</code>, where each consistent read, even within the
same transaction, sets and reads its own fresh snapshot.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-locking-reads"></a>13.2.10.5. <code class="literal">SELECT ... FOR UPDATE</code> and <code class="literal">SELECT ... LOCK IN
SHARE MODE</code> Locking Reads</h4></div></div></div><p>
In some circumstances, a consistent read is not convenient. For
example, you might want to add a new row into your table
<code class="literal">child</code>, and make sure that the child has a
parent in table <code class="literal">parent</code>. The following example
shows how to implement referential integrity in your application
code.
</p><p>
Suppose that you use a consistent read to read the table
<code class="literal">parent</code> and indeed see the parent of the child
in the table. Can you safely add the child row to table
<code class="literal">child</code>? No, because it may happen that
meanwhile some other user deletes the parent row from the table
<code class="literal">parent</code> without you being aware of it.
</p><p>
The solution is to perform the <code class="literal">SELECT</code> in a
locking mode using <code class="literal">LOCK IN SHARE MODE</code>:
</p><pre class="programlisting">SELECT * FROM parent WHERE NAME = 'Jones' LOCK IN SHARE MODE;
</pre><p>
Performing a read in share mode means that we read the latest
available data, and set a shared mode lock on the rows we read.
A shared mode lock prevents others from updating or deleting the
row we have read. Also, if the latest data belongs to a yet
uncommitted transaction of another client connection, we wait
until that transaction commits. After we see that the preceding
query returns the parent <code class="literal">'Jones'</code>, we can
safely add the child record to the <code class="literal">child</code>
table and commit our transaction.
</p><p>
Let us look at another example: We have an integer counter field
in a table <code class="literal">child_codes</code> that we use to assign
a unique identifier to each child added to table
<code class="literal">child</code>. Obviously, using a consistent read or
a shared mode read to read the present value of the counter is
not a good idea because two users of the database may then see
the same value for the counter, and a duplicate-key error occurs
if two users attempt to add children with the same identifier to
the table.
</p><p>
Here, <code class="literal">LOCK IN SHARE MODE</code> is not a good
solution because if two users read the counter at the same time,
at least one of them ends up in deadlock when attempting to
update the counter.
</p><p>
In this case, there are two good ways to implement the reading
and incrementing of the counter: (1) update the counter first by
incrementing it by 1 and only after that read it, or (2) read
the counter first with a lock mode <code class="literal">FOR
UPDATE</code>, and increment after that. The latter approach
can be implemented as follows:
</p><pre class="programlisting">SELECT counter_field FROM child_codes FOR UPDATE;
UPDATE child_codes SET counter_field = counter_field + 1;
</pre><p>
A <code class="literal">SELECT ... FOR UPDATE</code> reads the latest
available data, setting exclusive locks on each row it reads.
Thus, it sets the same locks a searched SQL
<code class="literal">UPDATE</code> would set on the rows.
</p><p>
The preceding description is merely an example of how
<code class="literal">SELECT ... FOR UPDATE</code> works. In MySQL, the
specific task of generating a unique identifier actually can be
accomplished using only a single access to the table:
</p><pre class="programlisting">UPDATE child_codes SET counter_field = LAST_INSERT_ID(counter_field + 1);
SELECT LAST_INSERT_ID();
</pre><p>
The <code class="literal">SELECT</code> statement merely retrieves the
identifier information (specific to the current connection). It
does not access any table.
</p><p>
Locks set by <code class="literal">IN SHARE MODE</code> and <code class="literal">FOR
UPDATE</code> reads are released when the transaction is
committed or rolled back.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Locking of rows for update using <code class="literal">SELECT FOR
UPDATE</code> only applies when
<code class="literal">AUTOCOMMIT</code> is switched off. If
<code class="literal">AUTOCOMMIT</code> is on, then the rows matching
the specification are not locked.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-next-key-locking"></a>13.2.10.6. Next-Key Locking: Avoiding the Phantom Problem</h4></div></div></div><a class="indexterm" name="id2909978"></a><a class="indexterm" name="id2909988"></a><p>
In row-level locking, <code class="literal">InnoDB</code> uses an
algorithm called <span class="emphasis"><em>next-key locking</em></span>.
<code class="literal">InnoDB</code> performs the row-level locking in such
a way that when it searches or scans an index of a table, it
sets shared or exclusive locks on the index records it
encounters. Thus, the row-level locks are actually index record
locks.
</p><p>
The next-key locks that <code class="literal">InnoDB</code> sets on index
records also affect the “<span class="quote">gap</span>” before that index
record. If a user has a shared or exclusive lock on record
<code class="literal">R</code> in an index, another user cannot insert a
new index record immediately before <code class="literal">R</code> in the
index order. (A gap lock refers to a lock that only locks a gap
before some index record.)
</p><p>
This next-key locking of gaps is done to prevent the so-called
“<span class="quote">phantom problem.</span>” Suppose that you want to read
and lock all children from the <code class="literal">child</code> table
having an identifier value greater than 100, with the intention
of updating some column in the selected rows later:
</p><pre class="programlisting">SELECT * FROM child WHERE id > 100 FOR UPDATE;
</pre><p>
Suppose that there is an index on the <code class="literal">id</code>
column. The query scans that index starting from the first
record where <code class="literal">id</code> is bigger than 100. If the
locks set on the index records would not lock out inserts made
in the gaps, a new row might meanwhile be inserted to the table.
If you execute the same <code class="literal">SELECT</code> within the
same transaction, you would see a new row in the result set
returned by the query. This is contrary to the isolation
principle of transactions: A transaction should be able to run
so that the data it has read does not change during the
transaction. If we regard a set of rows as a data item, the new
“<span class="quote">phantom</span>” child would violate this isolation
principle.
</p><p>
When <code class="literal">InnoDB</code> scans an index, it can also lock
the gap after the last record in the index. Just that happens in
the previous example: The locks set by <code class="literal">InnoDB</code>
prevent any insert to the table where <code class="literal">id</code>
would be bigger than 100.
</p><p>
You can use next-key locking to implement a uniqueness check in
your application: If you read your data in share mode and do not
see a duplicate for a row you are going to insert, then you can
safely insert your row and know that the next-key lock set on
the successor of your row during the read prevents anyone
meanwhile inserting a duplicate for your row. Thus, the next-key
locking allows you to “<span class="quote">lock</span>” the non-existence of
something in your table.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-consistent-read-example"></a>13.2.10.7. An Example of Consistent Read in <code class="literal">InnoDB</code></h4></div></div></div><p>
Suppose that you are running in the default <code class="literal">REPEATABLE
READ</code> isolation level. When you issue a consistent read
(that is, an ordinary <code class="literal">SELECT</code> statement),
<code class="literal">InnoDB</code> gives your transaction a timepoint
according to which your query sees the database. If another
transaction deletes a row and commits after your timepoint was
assigned, you do not see the row as having been deleted. Inserts
and updates are treated similarly.
</p><p>
You can advance your timepoint by committing your transaction
and then doing another <code class="literal">SELECT</code>.
</p><p>
This is called <em class="firstterm">multi-versioned concurrency
control</em>.
</p><pre class="programlisting"> User A User B
SET AUTOCOMMIT=0; SET AUTOCOMMIT=0;
time
| SELECT * FROM t;
| empty set
| INSERT INTO t VALUES (1, 2);
|
v SELECT * FROM t;
empty set
COMMIT;
SELECT * FROM t;
empty set
COMMIT;
SELECT * FROM t;
---------------------
| 1 | 2 |
---------------------
1 row in set
</pre><p>
In this example, user A sees the row inserted by B only when B
has committed the insert and A has committed as well, so that
the timepoint is advanced past the commit of B.
</p><p>
If you want to see the “<span class="quote">freshest</span>” state of the
database, you should use either the <code class="literal">READ
COMMITTED</code> isolation level or a locking read:
</p><pre class="programlisting">SELECT * FROM t LOCK IN SHARE MODE;
</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-locks-set"></a>13.2.10.8. Locks Set by Different SQL Statements in <code class="literal">InnoDB</code></h4></div></div></div><p>
A locking read, an <code class="literal">UPDATE</code>, or a
<code class="literal">DELETE</code> generally set record locks on every
index record that is scanned in the processing of the SQL
statement. It does not matter if there are
<code class="literal">WHERE</code> conditions in the statement that would
exclude the row. <code class="literal">InnoDB</code> does not remember the
exact <code class="literal">WHERE</code> condition, but only knows which
index ranges were scanned. The record locks are normally
next-key locks that also block inserts to the “<span class="quote">gap</span>”
immediately before the record.
</p><p>
If the locks to be set are exclusive, <code class="literal">InnoDB</code>
always retrieves also the clustered index record and sets a lock
on it.
</p><p>
If you do not have indexes suitable for your statement and MySQL
has to scan the whole table to process the statement, every row
of the table becomes locked, which in turn blocks all inserts by
other users to the table. It is important to create good indexes
so that your queries do not unnecessarily need to scan many
rows.
</p><p>
For <code class="literal">SELECT ... FOR UPDATE</code> or <code class="literal">SELECT
... IN SHARE MODE</code>, locks are acquired for scanned
rows, and expected to be released for rows that do not qualify
for inclusion in the result set (for example, if they do not
meet the criteria given in the <code class="literal">WHERE</code> clause).
However, in some cases, rows might not be unlocked immediately
because the relationship between a result row and its original
source is lost during query execution. For example, in a
<code class="literal">UNION</code>, scanned (and locked) rows from a table
might be inserted into a temporary table before evaluation
whether they qualify for the result set. In this circumstance,
the relationship of the rows in the temporary table to the rows
in the original table is lost and the latter rows are not
unlocked until the end of query execution.
</p><p>
<code class="literal">InnoDB</code> sets specific types of locks as
follows:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">SELECT ... FROM</code> is a consistent read,
reading a snapshot of the database and setting no locks
unless the transaction isolation level is set to
<code class="literal">SERIALIZABLE</code>. For
<code class="literal">SERIALIZABLE</code> level, this sets shared
next-key locks on the index records it encounters.
</p></li><li><p>
<code class="literal">SELECT ... FROM ... LOCK IN SHARE MODE</code>
sets shared next-key locks on all index records the read
encounters.
</p></li><li><p>
<code class="literal">SELECT ... FROM ... FOR UPDATE</code> sets
exclusive next-key locks on all index records the read
encounters.
</p></li><li><p>
<code class="literal">UPDATE ... WHERE ...</code> sets an exclusive
next-key lock on every record the search encounters.
</p></li><li><p>
<code class="literal">DELETE FROM ... WHERE ...</code> sets an
exclusive next-key lock on every record the search
encounters.
</p></li><li><p>
<code class="literal">INSERT INTO ... VALUES (...)</code> sets an
exclusive lock on the inserted row. Note that this lock is
not a next-key lock and does not prevent other users from
inserting to the gap before the inserted row. If a
duplicate-key error occurs, a shared lock on the duplicate
index record is set.
</p></li><li><p>
<code class="literal">REPLACE</code> is done like an
<code class="literal">INSERT</code> if there is no collision on a
unique key. Otherwise, an exclusive next-key lock is placed
on the row that has to be updated.
</p></li><li><p>
While initializing a previously specified
<code class="literal">AUTO_INCREMENT</code> column on a table,
<code class="literal">InnoDB</code> sets an exclusive lock on the end
of the index associated with the
<code class="literal">AUTO_INCREMENT</code> column. In accessing the
auto-increment counter, <code class="literal">InnoDB</code> uses a
specific table lock mode <code class="literal">AUTO-INC</code> where
the lock lasts only to the end of the current SQL statement,
not to the end of the entire transaction. Note that other
clients cannot insert into the table while the
<code class="literal">AUTO-INC</code> table lock is held; see
<a href="storage-engines.html#innodb-and-autocommit" title="13.2.10.2. InnoDB and AUTOCOMMIT">Section 13.2.10.2, “<code class="literal">InnoDB</code> and <code class="literal">AUTOCOMMIT</code>”</a>.
</p><p>
<code class="literal">InnoDB</code> fetches the value of a previously
initialized <code class="literal">AUTO_INCREMENT</code> column without
setting any locks.
</p></li><li><p>
<code class="literal">INSERT INTO T SELECT ... FROM S WHERE ...</code>
sets an exclusive (non-next-key) lock on each row inserted
into <code class="literal">T</code>. <code class="literal">InnoDB</code> sets
shared next-key locks on <code class="literal">S</code>, unless
<code class="literal">innodb_locks_unsafe_for_binlog</code> is
enabled, in which case it does the search on
<code class="literal">S</code> as a consistent read.
<code class="literal">InnoDB</code> has to set locks in the latter
case: In roll-forward recovery from a backup, every SQL
statement has to be executed in exactly the same way it was
done originally.
</p></li><li><p>
<code class="literal">CREATE TABLE ... SELECT ...</code> performs the
<code class="literal">SELECT</code> as a consistent read or with
shared locks, as in the previous item.
</p></li><li><p>
If a <code class="literal">FOREIGN KEY</code> constraint is defined on
a table, any insert, update, or delete that requires the
constraint condition to be checked sets shared record-level
locks on the records that it looks at to check the
constraint. <code class="literal">InnoDB</code> also sets these locks
in the case where the constraint fails.
</p></li><li><p>
<code class="literal">LOCK TABLES</code> sets table locks, but it is
the higher MySQL layer above the <code class="literal">InnoDB</code>
layer that sets these locks. <code class="literal">InnoDB</code> is
aware of table locks if
<code class="literal">innodb_table_locks=1</code> (the default) and
<code class="literal">AUTOCOMMIT=0</code>, and the MySQL layer above
<code class="literal">InnoDB</code> knows about row-level locks.
Otherwise, <code class="literal">InnoDB</code>'s automatic deadlock
detection cannot detect deadlocks where such table locks are
involved. Also, because the higher MySQL layer does not know
about row-level locks, it is possible to get a table lock on
a table where another user currently has row-level locks.
However, this does not endanger transaction integrity, as
discussed in <a href="storage-engines.html#innodb-deadlock-detection" title="13.2.10.10. Deadlock Detection and Rollback">Section 13.2.10.10, “Deadlock Detection and Rollback”</a>.
See also <a href="storage-engines.html#innodb-restrictions" title="13.2.16. Restrictions on InnoDB Tables">Section 13.2.16, “Restrictions on <code class="literal">InnoDB</code> Tables”</a>.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-implicit-commit"></a>13.2.10.9. Implicit Transaction Commit and Rollback</h4></div></div></div><p>
By default, MySQL begins each client connection with autocommit
mode enabled. When autocommit is enabled, MySQL does a commit
after each SQL statement if that statement did not return an
error. If an SQL statement returns an error, the commit or
rollback behavior depends on the error. See
<a href="storage-engines.html#innodb-error-handling" title="13.2.15. InnoDB Error Handling">Section 13.2.15, “<code class="literal">InnoDB</code> Error Handling”</a>.
</p><p>
If you have the autocommit mode off and close a connection
without explicitly committing the final transaction, MySQL rolls
back that transaction.
</p><p>
For details about which statements implicitly end a transaction,
as if you had done a <code class="literal">COMMIT</code> before executing
the statement, see <a href="sql-syntax.html#implicit-commit" title="12.4.3. Statements That Cause an Implicit Commit">Section 12.4.3, “Statements That Cause an Implicit Commit”</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-deadlock-detection"></a>13.2.10.10. Deadlock Detection and Rollback</h4></div></div></div><p>
<code class="literal">InnoDB</code> automatically detects a deadlock of
transactions and rolls back a transaction or transactions to
break the deadlock. <code class="literal">InnoDB</code> tries to pick
small transactions to roll back, where the size of a transaction
is determined by the number of rows inserted, updated, or
deleted.
</p><p>
<code class="literal">InnoDB</code> is aware of table locks if
<code class="literal">innodb_table_locks=1</code> (the default) and
<code class="literal">AUTOCOMMIT=0</code>, and the MySQL layer above it
knows about row-level locks. Otherwise,
<code class="literal">InnoDB</code> cannot detect deadlocks where a table
lock set by a MySQL <code class="literal">LOCK TABLES</code> statement or
a lock set by a storage engine other than
<code class="literal">InnoDB</code> is involved. You must resolve these
situations by setting the value of the
<code class="literal">innodb_lock_wait_timeout</code> system variable.
</p><p>
When <code class="literal">InnoDB</code> performs a complete rollback of a
transaction, all locks set by the transaction are released.
However, if just a single SQL statement is rolled back as a
result of an error, some of the locks set by the statement may
be preserved. This happens because <code class="literal">InnoDB</code>
stores row locks in a format such that it cannot know afterward
which lock was set by which statement.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-deadlocks"></a>13.2.10.11. How to Cope with Deadlocks</h4></div></div></div><p>
Deadlocks are a classic problem in transactional databases, but
they are not dangerous unless they are so frequent that you
cannot run certain transactions at all. Normally, you must write
your applications so that they are always prepared to re-issue a
transaction if it gets rolled back because of a deadlock.
</p><p>
<code class="literal">InnoDB</code> uses automatic row-level locking. You
can get deadlocks even in the case of transactions that just
insert or delete a single row. That is because these operations
are not really “<span class="quote">atomic</span>”; they automatically set
locks on the (possibly several) index records of the row
inserted or deleted.
</p><p>
You can cope with deadlocks and reduce the likelihood of their
occurrence with the following techniques:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Use <code class="literal">SHOW ENGINE INNODB STATUS</code> to
determine the cause of the latest deadlock. That can help
you to tune your application to avoid deadlocks.
</p></li><li><p>
Always be prepared to re-issue a transaction if it fails due
to deadlock. Deadlocks are not dangerous. Just try again.
</p></li><li><p>
Commit your transactions often. Small transactions are less
prone to collision.
</p></li><li><p>
If you are using locking reads (<code class="literal">SELECT ... FOR
UPDATE</code> or <code class="literal">... LOCK IN SHARE
MODE</code>), try using a lower isolation level such as
<code class="literal">READ COMMITTED</code>.
</p></li><li><p>
Access your tables and rows in a fixed order. Then
transactions form well-defined queues and do not deadlock.
</p></li><li><p>
Add well-chosen indexes to your tables. Then your queries
need to scan fewer index records and consequently set fewer
locks. Use <code class="literal">EXPLAIN SELECT</code> to determine
which indexes the MySQL server regards as the most
appropriate for your queries.
</p></li><li><p>
Use less locking. If you can afford to allow a
<code class="literal">SELECT</code> to return data from an old
snapshot, do not add the clause <code class="literal">FOR
UPDATE</code> or <code class="literal">LOCK IN SHARE MODE</code> to
it. Using the <code class="literal">READ COMMITTED</code> isolation
level is good here, because each consistent read within the
same transaction reads from its own fresh snapshot. You
should also set the value of
<code class="literal">innodb_support_xa</code> to 0 which will reduce
the number of disk flushes due to synchronizing on disk data
and the binary log.
</p></li><li><p>
If nothing else helps, serialize your transactions with
table-level locks. The correct way to use <code class="literal">LOCK
TABLES</code> with transactional tables, such as
<code class="literal">InnoDB</code> tables, is to set
<code class="literal">AUTOCOMMIT = 0</code> and not to call
<code class="literal">UNLOCK TABLES</code> until after you commit the
transaction explicitly. For example, if you need to write to
table <code class="literal">t1</code> and read from table
<code class="literal">t2</code>, you can do this:
</p><pre class="programlisting">SET AUTOCOMMIT=0;
LOCK TABLES t1 WRITE, t2 READ, ...;
<em class="replaceable"><code>... do something with tables t1 and t2 here ...</code></em>
COMMIT;
UNLOCK TABLES;
</pre><p>
Table-level locks make your transactions queue nicely, and
deadlocks are avoided.
</p></li><li><p>
Another way to serialize transactions is to create an
auxiliary “<span class="quote">semaphore</span>” table that contains just
a single row. Have each transaction update that row before
accessing other tables. In that way, all transactions happen
in a serial fashion. Note that the <code class="literal">InnoDB</code>
instant deadlock detection algorithm also works in this
case, because the serializing lock is a row-level lock. With
MySQL table-level locks, the timeout method must be used to
resolve deadlocks.
</p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-tuning"></a>13.2.11. <code class="literal">InnoDB</code> Performance Tuning Tips</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#innodb-monitor">13.2.11.1. <code class="literal">SHOW ENGINE INNODB STATUS</code> and the
<code class="literal">InnoDB</code> Monitors</a></span></dt></dl></div><a class="indexterm" name="id2911202"></a><div class="itemizedlist"><ul type="disc"><li><p>
In <code class="literal">InnoDB</code>, having a long <code class="literal">PRIMARY
KEY</code> wastes a lot of disk space because its value
must be stored with every secondary index record. (See
<a href="storage-engines.html#innodb-table-and-index" title="13.2.13. InnoDB Table and Index Structures">Section 13.2.13, “<code class="literal">InnoDB</code> Table and Index Structures”</a>.) Create an
<code class="literal">AUTO_INCREMENT</code> column as the primary key if
your primary key is long.
</p></li><li><p>
If the Unix <code class="filename">top</code> tool or the Windows Task
Manager shows that the CPU usage percentage with your workload
is less than 70%, your workload is probably disk-bound. Maybe
you are making too many transaction commits, or the buffer
pool is too small. Making the buffer pool bigger can help, but
do not set it equal to more than 80% of physical memory.
</p></li><li><p>
Wrap several modifications into one transaction.
<code class="literal">InnoDB</code> must flush the log to disk at each
transaction commit if that transaction made modifications to
the database. The rotation speed of a disk is typically at
most 167 revolutions/second, which constrains the number of
commits to the same 167<sup>th</sup> of a
second if the disk does not “<span class="quote">fool</span>” the operating
system.
</p></li><li><p>
If you can afford the loss of some of the latest committed
transactions if a crash occurs, you can set the
<code class="literal">innodb_flush_log_at_trx_commit</code> parameter to
0. <code class="literal">InnoDB</code> tries to flush the log once per
second anyway, although the flush is not guaranteed.
</p></li><li><p>
Make your log files big, even as big as the buffer pool. When
<code class="literal">InnoDB</code> has written the log files full, it
has to write the modified contents of the buffer pool to disk
in a checkpoint. Small log files cause many unnecessary disk
writes. The drawback of big log files is that the recovery
time is longer.
</p></li><li><p>
Make the log buffer quite large as well (on the order of 8MB).
</p></li><li><p>
Use the <code class="literal">VARCHAR</code> data type instead of
<code class="literal">CHAR</code> if you are storing variable-length
strings or if the column may contain many
<code class="literal">NULL</code> values. A
<code class="literal">CHAR(<em class="replaceable"><code>N</code></em>)</code> column
always takes <em class="replaceable"><code>N</code></em> characters to store
data, even if the string is shorter or its value is
<code class="literal">NULL</code>. Smaller tables fit better in the
buffer pool and reduce disk I/O.
</p><p>
When using <code class="literal">row_format=compact</code> (the default
<code class="literal">InnoDB</code> record format in MySQL
5.0) and variable-length character sets, such as
<code class="literal">utf8</code> or <code class="literal">sjis</code>,
<code class="literal">CHAR(<em class="replaceable"><code>N</code></em>)</code> will
occupy a variable amount of space, at least
<em class="replaceable"><code>N</code></em> bytes.
</p></li><li><p>
In some versions of GNU/Linux and Unix, flushing files to disk
with the Unix <code class="literal">fsync()</code> call (which
<code class="literal">InnoDB</code> uses by default) and other similar
methods is surprisingly slow. If you are dissatisfied with
database write performance, you might try setting the
<code class="literal">innodb_flush_method</code> parameter to
<code class="literal">O_DSYNC</code>. Although
<code class="literal">O_DSYNC</code> seems to be slower on most systems,
yours might not be one of them.
</p></li><li><p>
When using the <code class="literal">InnoDB</code> storage engine on
Solaris 10 for x86_64 architecture (AMD Opteron), it is
important to mount any filesystems used for storing
<code class="literal">InnoDB</code>-related files using the
<code class="literal">forcedirectio</code> option. (The default on
Solaris 10/x86_64 is <span class="emphasis"><em>not</em></span> to use this
option.) Failure to use <code class="literal">forcedirectio</code>
causes a serious degradation of <code class="literal">InnoDB</code>'s
speed and performance on this platform.
</p><p>
When using the <code class="literal">InnoDB</code> storage engine with a
large <code class="literal">innodb_buffer_pool_size</code> value on any
release of Solaris 2.6 and up and any platform
(sparc/x86/x64/amd64), a significant performance gain can be
achieved by placing <code class="literal">InnoDB</code> data files and
log files on raw devices or on a separate direct I/O UFS
filesystem (using mount option
<code class="literal">forcedirectio</code>; see
<code class="literal">mount_ufs(1M)</code>). Users of the Veritas
filesystem VxFS should use the mount option
<code class="literal">convosync=direct</code>.
</p><p>
Other MySQL data files, such as those for
<code class="literal">MyISAM</code> tables, should not be placed on a
direct I/O filesystem. Executables or libraries <span class="emphasis"><em>must
not</em></span> be placed on a direct I/O filesystem.
</p></li><li><p>
When importing data into <code class="literal">InnoDB</code>, make sure
that MySQL does not have autocommit mode enabled because that
requires a log flush to disk for every insert. To disable
autocommit during your import operation, surround it with
<code class="literal">SET AUTOCOMMIT</code> and
<code class="literal">COMMIT</code> statements:
</p><pre class="programlisting">SET AUTOCOMMIT=0;
<em class="replaceable"><code>... SQL import statements ...</code></em>
COMMIT;
</pre><p>
If you use the <span><strong class="command">mysqldump</strong></span> option
<code class="option">--opt</code>, you get dump files that are fast to
import into an <code class="literal">InnoDB</code> table, even without
wrapping them with the <code class="literal">SET AUTOCOMMIT</code> and
<code class="literal">COMMIT</code> statements.
</p></li><li><p>
Beware of big rollbacks of mass inserts:
<code class="literal">InnoDB</code> uses the insert buffer to save disk
I/O in inserts, but no such mechanism is used in a
corresponding rollback. A disk-bound rollback can take 30
times as long to perform as the corresponding insert. Killing
the database process does not help because the rollback starts
again on server startup. The only way to get rid of a runaway
rollback is to increase the buffer pool so that the rollback
becomes CPU-bound and runs fast, or to use a special
procedure. See <a href="storage-engines.html#forcing-recovery" title="13.2.8.1. Forcing InnoDB Recovery">Section 13.2.8.1, “Forcing <code class="literal">InnoDB</code> Recovery”</a>.
</p></li><li><p>
Beware also of other big disk-bound operations. Use
<code class="literal">DROP TABLE</code> and <code class="literal">CREATE
TABLE</code> to empty a table, not <code class="literal">DELETE FROM
<em class="replaceable"><code>tbl_name</code></em></code>.
</p></li><li><p>
Use the multiple-row <code class="literal">INSERT</code> syntax to
reduce communication overhead between the client and the
server if you need to insert many rows:
</p><pre class="programlisting">INSERT INTO yourtable VALUES (1,2), (5,5), ...;
</pre><p>
This tip is valid for inserts into any table, not just
<code class="literal">InnoDB</code> tables.
</p></li><li><p>
If you have <code class="literal">UNIQUE</code> constraints on secondary
keys, you can speed up table imports by temporarily turning
off the uniqueness checks during the import session:
</p><pre class="programlisting">SET UNIQUE_CHECKS=0;
<em class="replaceable"><code>... import operation ...</code></em>
SET UNIQUE_CHECKS=1;
</pre><p>
For big tables, this saves a lot of disk I/O because
<code class="literal">InnoDB</code> can use its insert buffer to write
secondary index records in a batch. Be certain that the data
contains no duplicate keys. <code class="literal">UNIQUE_CHECKS</code>
allows but does not require storage engines to ignore
duplicate keys.
</p></li><li><p>
If you have <code class="literal">FOREIGN KEY</code> constraints in your
tables, you can speed up table imports by turning the foreign
key checks off for the duration of the import session:
</p><pre class="programlisting">SET FOREIGN_KEY_CHECKS=0;
<em class="replaceable"><code>... import operation ...</code></em>
SET FOREIGN_KEY_CHECKS=1;
</pre><p>
For big tables, this can save a lot of disk I/O.
</p></li><li><p>
If you often have recurring queries for tables that are not
updated frequently, use the query cache:
</p><pre class="programlisting">[mysqld]
query_cache_type = ON
query_cache_size = 10M
</pre></li><li><p>
Unlike <code class="literal">MyISAM</code>, <code class="literal">InnoDB</code>
does not store an index cardinality value in its tables.
Instead, <code class="literal">InnoDB</code> computes a cardinality for
a table the first time it accesses it after startup. With a
large number of tables, this might take significant time. It
is the initial table open operation that is important, so to
“<span class="quote">warm up</span>” a table for later use, you might want
to use it immediately after start up by issuing a statement
such as <code class="literal">SELECT 1 FROM
<em class="replaceable"><code>tbl_name</code></em> LIMIT 1</code>.
</p></li></ul></div><p class="mnmas"><b>MySQL Enterprise</b>
For optimization recommendations geared to your specific
circumstances subscribe to the MySQL Enterprise Monitor. For
more information see
<a href="http://www.mysql.com/products/enterprise/advisors.html" target="_top">http://www.mysql.com/products/enterprise/advisors.html</a>.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-monitor"></a>13.2.11.1. <code class="literal">SHOW ENGINE INNODB STATUS</code> and the
<code class="literal">InnoDB</code> Monitors</h4></div></div></div><p>
<code class="literal">InnoDB</code> includes <code class="literal">InnoDB</code>
Monitors that print information about the
<code class="literal">InnoDB</code> internal state. You can use the
<code class="literal">SHOW ENGINE INNODB STATUS</code> SQL statement at
any time to fetch the output of the standard
<code class="literal">InnoDB</code> Monitor to your SQL client. This
information is useful in performance tuning. (If you are using
the <span><strong class="command">mysql</strong></span> interactive SQL client, the output
is more readable if you replace the usual semicolon statement
terminator with <code class="literal">\G</code>.) For a discussion of
<code class="literal">InnoDB</code> lock modes, see
<a href="storage-engines.html#innodb-lock-modes" title="13.2.10.1. InnoDB Lock Modes">Section 13.2.10.1, “<code class="literal">InnoDB</code> Lock Modes”</a>.
</p><pre class="programlisting">mysql> <strong class="userinput"><code>SHOW ENGINE INNODB STATUS\G</code></strong>
</pre><p>
Another way to use <code class="literal">InnoDB</code> Monitors is to let
them periodically write data to the standard output of the
<span><strong class="command">mysqld</strong></span> server. In this case, no output is
sent to clients. When switched on, <code class="literal">InnoDB</code>
Monitors print data about every 15 seconds. Server output
usually is directed to the <code class="filename">.err</code> log in the
MySQL data directory. This data is useful in performance tuning.
On Windows, you must start the server from a command prompt in a
console window with the <code class="option">--console</code> option if you
want to direct the output to the window rather than to the error
log.
</p><p>
Monitor output includes the following types of information:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Table and record locks held by each active transaction
</p></li><li><p>
Lock waits of a transactions
</p></li><li><p>
Semaphore waits of threads
</p></li><li><p>
Pending file I/O requests
</p></li><li><p>
Buffer pool statistics
</p></li><li><p>
Purge and insert buffer merge activity of the main
<code class="literal">InnoDB</code> thread
</p></li></ul></div><p>
To cause the standard <code class="literal">InnoDB</code> Monitor to write
to the standard output of <span><strong class="command">mysqld</strong></span>, use the
following SQL statement:
</p><pre class="programlisting">CREATE TABLE innodb_monitor (a INT) ENGINE=INNODB;
</pre><p>
The monitor can be stopped by issuing the following statement:
</p><pre class="programlisting">DROP TABLE innodb_monitor;
</pre><p>
The <code class="literal">CREATE TABLE</code> syntax is just a way to pass
a command to the <code class="literal">InnoDB</code> engine through
MySQL's SQL parser: The only things that matter are the table
name <code class="literal">innodb_monitor</code> and that it be an
<code class="literal">InnoDB</code> table. The structure of the table is
not relevant at all for the <code class="literal">InnoDB</code> Monitor.
If you shut down the server, the monitor does not restart
automatically when you restart the server. You must drop the
monitor table and issue a new <code class="literal">CREATE TABLE</code>
statement to start the monitor. (This syntax may change in a
future release.)
</p><p>
You can use <code class="literal">innodb_lock_monitor</code> in a similar
fashion. This is the same as <code class="literal">innodb_monitor</code>,
except that it also provides a great deal of lock information. A
separate <code class="literal">innodb_tablespace_monitor</code> prints a
list of created file segments existing in the tablespace and
validates the tablespace allocation data structures. In
addition, there is <code class="literal">innodb_table_monitor</code> with
which you can print the contents of the
<code class="literal">InnoDB</code> internal data dictionary.
</p><p>
A sample of <code class="literal">InnoDB</code> Monitor output:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>SHOW ENGINE INNODB STATUS\G</code></strong>
*************************** 1. row ***************************
Status:
=====================================
030709 13:00:59 INNODB MONITOR OUTPUT
=====================================
Per second averages calculated from the last 18 seconds
----------
SEMAPHORES
----------
OS WAIT ARRAY INFO: reservation count 413452, signal count 378357
--Thread 32782 has waited at btr0sea.c line 1477 for 0.00 seconds the
semaphore: X-lock on RW-latch at 41a28668 created in file btr0sea.c line 135
a writer (thread id 32782) has reserved it in mode wait exclusive
number of readers 1, waiters flag 1
Last time read locked in file btr0sea.c line 731
Last time write locked in file btr0sea.c line 1347
Mutex spin waits 0, rounds 0, OS waits 0
RW-shared spins 108462, OS waits 37964; RW-excl spins 681824, OS waits
375485
------------------------
LATEST FOREIGN KEY ERROR
------------------------
030709 13:00:59 Transaction:
TRANSACTION 0 290328284, ACTIVE 0 sec, process no 3195, OS thread id 34831
inserting
15 lock struct(s), heap size 2496, undo log entries 9
MySQL thread id 25, query id 4668733 localhost heikki update
insert into ibtest11a (D, B, C) values (5, 'khDk' ,'khDk')
Foreign key constraint fails for table test/ibtest11a:
,
CONSTRAINT `0_219242` FOREIGN KEY (`A`, `D`) REFERENCES `ibtest11b` (`A`,
`D`) ON DELETE CASCADE ON UPDATE CASCADE
Trying to add in child table, in index PRIMARY tuple:
0: len 4; hex 80000101; asc ....;; 1: len 4; hex 80000005; asc ....;; 2:
len 4; hex 6b68446b; asc khDk;; 3: len 6; hex 0000114e0edc; asc ...N..;; 4:
len 7; hex 00000000c3e0a7; asc .......;; 5: len 4; hex 6b68446b; asc khDk;;
But in parent table test/ibtest11b, in index PRIMARY,
the closest match we can find is record:
RECORD: info bits 0 0: len 4; hex 8000015b; asc ...[;; 1: len 4; hex
80000005; asc ....;; 2: len 3; hex 6b6864; asc khd;; 3: len 6; hex
0000111ef3eb; asc ......;; 4: len 7; hex 800001001e0084; asc .......;; 5:
len 3; hex 6b6864; asc khd;;
------------------------
LATEST DETECTED DEADLOCK
------------------------
030709 12:59:58
*** (1) TRANSACTION:
TRANSACTION 0 290252780, ACTIVE 1 sec, process no 3185, OS thread id 30733
inserting
LOCK WAIT 3 lock struct(s), heap size 320, undo log entries 146
MySQL thread id 21, query id 4553379 localhost heikki update
INSERT INTO alex1 VALUES(86, 86, 794,'aA35818','bb','c79166','d4766t',
'e187358f','g84586','h794',date_format('2001-04-03 12:54:22','%Y-%m-%d
%H:%i'),7
*** (1) WAITING FOR THIS LOCK TO BE GRANTED:
RECORD LOCKS space id 0 page no 48310 n bits 568 table test/alex1 index
symbole trx id 0 290252780 lock mode S waiting
Record lock, heap no 324 RECORD: info bits 0 0: len 7; hex 61613335383138;
asc aa35818;; 1:
*** (2) TRANSACTION:
TRANSACTION 0 290251546, ACTIVE 2 sec, process no 3190, OS thread id 32782
inserting
130 lock struct(s), heap size 11584, undo log entries 437
MySQL thread id 23, query id 4554396 localhost heikki update
REPLACE INTO alex1 VALUES(NULL, 32, NULL,'aa3572','','c3572','d6012t','',
NULL,'h396', NULL, NULL, 7.31,7.31,7.31,200)
*** (2) HOLDS THE LOCK(S):
RECORD LOCKS space id 0 page no 48310 n bits 568 table test/alex1 index
symbole trx id 0 290251546 lock_mode X locks rec but not gap
Record lock, heap no 324 RECORD: info bits 0 0: len 7; hex 61613335383138;
asc aa35818;; 1:
*** (2) WAITING FOR THIS LOCK TO BE GRANTED:
RECORD LOCKS space id 0 page no 48310 n bits 568 table test/alex1 index
symbole trx id 0 290251546 lock_mode X locks gap before rec insert intention
waiting
Record lock, heap no 82 RECORD: info bits 0 0: len 7; hex 61613335373230;
asc aa35720;; 1:
*** WE ROLL BACK TRANSACTION (1)
------------
TRANSACTIONS
------------
Trx id counter 0 290328385
Purge done for trx's n:o < 0 290315608 undo n:o < 0 17
Total number of lock structs in row lock hash table 70
LIST OF TRANSACTIONS FOR EACH SESSION:
---TRANSACTION 0 0, not started, process no 3491, OS thread id 42002
MySQL thread id 32, query id 4668737 localhost heikki
show innodb status
---TRANSACTION 0 290328384, ACTIVE 0 sec, process no 3205, OS thread id
38929 inserting
1 lock struct(s), heap size 320
MySQL thread id 29, query id 4668736 localhost heikki update
insert into speedc values (1519229,1, 'hgjhjgghggjgjgjgjgjggjgjgjgjgjgggjgjg
jlhhgghggggghhjhghgggggghjhghghghghghhhhghghghjhhjghjghjkghjghjghjghjfhjfh
---TRANSACTION 0 290328383, ACTIVE 0 sec, process no 3180, OS thread id
28684 committing
1 lock struct(s), heap size 320, undo log entries 1
MySQL thread id 19, query id 4668734 localhost heikki update
insert into speedcm values (1603393,1, 'hgjhjgghggjgjgjgjgjggjgjgjgjgjgggjgj
gjlhhgghggggghhjhghgggggghjhghghghghghhhhghghghjhhjghjghjkghjghjghjghjfhjf
---TRANSACTION 0 290328327, ACTIVE 0 sec, process no 3200, OS thread id
36880 starting index read
LOCK WAIT 2 lock struct(s), heap size 320
MySQL thread id 27, query id 4668644 localhost heikki Searching rows for
update
update ibtest11a set B = 'kHdkkkk' where A = 89572
------- TRX HAS BEEN WAITING 0 SEC FOR THIS LOCK TO BE GRANTED:
RECORD LOCKS space id 0 page no 65556 n bits 232 table test/ibtest11a index
PRIMARY trx id 0 290328327 lock_mode X waiting
Record lock, heap no 1 RECORD: info bits 0 0: len 9; hex 73757072656d756d00;
asc supremum.;;
------------------
---TRANSACTION 0 290328284, ACTIVE 0 sec, process no 3195, OS thread id
34831 rollback of SQL statement
ROLLING BACK 14 lock struct(s), heap size 2496, undo log entries 9
MySQL thread id 25, query id 4668733 localhost heikki update
insert into ibtest11a (D, B, C) values (5, 'khDk' ,'khDk')
---TRANSACTION 0 290327208, ACTIVE 1 sec, process no 3190, OS thread id
32782
58 lock struct(s), heap size 5504, undo log entries 159
MySQL thread id 23, query id 4668732 localhost heikki update
REPLACE INTO alex1 VALUES(86, 46, 538,'aa95666','bb','c95666','d9486t',
'e200498f','g86814','h538',date_format('2001-04-03 12:54:22','%Y-%m-%d
%H:%i'),
---TRANSACTION 0 290323325, ACTIVE 3 sec, process no 3185, OS thread id
30733 inserting
4 lock struct(s), heap size 1024, undo log entries 165
MySQL thread id 21, query id 4668735 localhost heikki update
INSERT INTO alex1 VALUES(NULL, 49, NULL,'aa42837','','c56319','d1719t','',
NULL,'h321', NULL, NULL, 7.31,7.31,7.31,200)
--------
FILE I/O
--------
I/O thread 0 state: waiting for i/o request (insert buffer thread)
I/O thread 1 state: waiting for i/o request (log thread)
I/O thread 2 state: waiting for i/o request (read thread)
I/O thread 3 state: waiting for i/o request (write thread)
Pending normal aio reads: 0, aio writes: 0,
ibuf aio reads: 0, log i/o's: 0, sync i/o's: 0
Pending flushes (fsync) log: 0; buffer pool: 0
151671 OS file reads, 94747 OS file writes, 8750 OS fsyncs
25.44 reads/s, 18494 avg bytes/read, 17.55 writes/s, 2.33 fsyncs/s
-------------------------------------
INSERT BUFFER AND ADAPTIVE HASH INDEX
-------------------------------------
Ibuf for space 0: size 1, free list len 19, seg size 21,
85004 inserts, 85004 merged recs, 26669 merges
Hash table size 207619, used cells 14461, node heap has 16 buffer(s)
1877.67 hash searches/s, 5121.10 non-hash searches/s
---
LOG
---
Log sequence number 18 1212842764
Log flushed up to 18 1212665295
Last checkpoint at 18 1135877290
0 pending log writes, 0 pending chkp writes
4341 log i/o's done, 1.22 log i/o's/second
----------------------
BUFFER POOL AND MEMORY
----------------------
Total memory allocated 84966343; in additional pool allocated 1402624
Buffer pool size 3200
Free buffers 110
Database pages 3074
Modified db pages 2674
Pending reads 0
Pending writes: LRU 0, flush list 0, single page 0
Pages read 171380, created 51968, written 194688
28.72 reads/s, 20.72 creates/s, 47.55 writes/s
Buffer pool hit rate 999 / 1000
--------------
ROW OPERATIONS
--------------
0 queries inside InnoDB, 0 queries in queue
Main thread process no. 3004, id 7176, state: purging
Number of rows inserted 3738558, updated 127415, deleted 33707, read 755779
1586.13 inserts/s, 50.89 updates/s, 28.44 deletes/s, 107.88 reads/s
----------------------------
END OF INNODB MONITOR OUTPUT
============================
</pre><p>
Some notes on the output:
</p><div class="itemizedlist"><ul type="disc"><li><p>
If the <code class="literal">TRANSACTIONS</code> section reports lock
waits, your applications may have lock contention. The
output can also help to trace the reasons for transaction
deadlocks.
</p></li><li><p>
The <code class="literal">SEMAPHORES</code> section reports threads
waiting for a semaphore and statistics on how many times
threads have needed a spin or a wait on a mutex or a rw-lock
semaphore. A large number of threads waiting for semaphores
may be a result of disk I/O, or contention problems inside
<code class="literal">InnoDB</code>. Contention can be due to heavy
parallelism of queries or problems in operating system
thread scheduling. Setting
<code class="literal">innodb_thread_concurrency</code> smaller than
the default value can help in such situations.
</p></li><li><p>
The <code class="literal">BUFFER POOL AND MEMORY</code> section gives
you statistics on pages read and written. You can calculate
from these numbers how many data file I/O operations your
queries currently are doing.
</p></li><li><p>
The <code class="literal">ROW OPERATIONS</code> section shows what the
main thread is doing.
</p></li></ul></div><p>
<code class="literal">InnoDB</code> sends diagnostic output to
<code class="literal">stderr</code> or to files rather than to
<code class="literal">stdout</code> or fixed-size memory buffers, to avoid
potential buffer overflows. As a side effect, the output of
<code class="literal">SHOW ENGINE INNODB STATUS</code> is written to a
status file in the MySQL data directory every fifteen seconds.
The name of the file is
<code class="filename">innodb_status.<em class="replaceable"><code>pid</code></em></code>,
where <em class="replaceable"><code>pid</code></em> is the server process ID.
<code class="literal">InnoDB</code> removes the file for a normal
shutdown. If abnormal shutdowns have occurred, instances of
these status files may be present and must be removed manually.
Before removing them, you might want to examine them to see
whether they contain useful information about the cause of
abnormal shutdowns. The
<code class="filename">innodb_status.<em class="replaceable"><code>pid</code></em></code>
file is created only if the configuration option
<code class="literal">innodb_status_file=1</code> is set.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-multi-versioning"></a>13.2.12. Implementation of Multi-Versioning</h3></div></div></div><p>
Because <code class="literal">InnoDB</code> is a multi-versioned storage
engine, it must keep information about old versions of rows in the
tablespace. This information is stored in a data structure called
a <em class="firstterm">rollback segment</em> (after an analogous data
structure in Oracle).
</p><p>
Internally, <code class="literal">InnoDB</code> adds two fields to each row
stored in the database. A 6-byte field indicates the transaction
identifier for the last transaction that inserted or updated the
row. Also, a deletion is treated internally as an update where a
special bit in the row is set to mark it as deleted. Each row also
contains a 7-byte field called the roll pointer. The roll pointer
points to an undo log record written to the rollback segment. If
the row was updated, the undo log record contains the information
necessary to rebuild the content of the row before it was updated.
</p><p>
<code class="literal">InnoDB</code> uses the information in the rollback
segment to perform the undo operations needed in a transaction
rollback. It also uses the information to build earlier versions
of a row for a consistent read.
</p><p>
Undo logs in the rollback segment are divided into insert and
update undo logs. Insert undo logs are needed only in transaction
rollback and can be discarded as soon as the transaction commits.
Update undo logs are used also in consistent reads, but they can
be discarded only after there is no transaction present for which
<code class="literal">InnoDB</code> has assigned a snapshot that in a
consistent read could need the information in the update undo log
to build an earlier version of a database row.
</p><p>
You must remember to commit your transactions regularly, including
those transactions that issue only consistent reads. Otherwise,
<code class="literal">InnoDB</code> cannot discard data from the update undo
logs, and the rollback segment may grow too big, filling up your
tablespace.
</p><p>
The physical size of an undo log record in the rollback segment is
typically smaller than the corresponding inserted or updated row.
You can use this information to calculate the space need for your
rollback segment.
</p><p>
In the <code class="literal">InnoDB</code> multi-versioning scheme, a row is
not physically removed from the database immediately when you
delete it with an SQL statement. Only when
<code class="literal">InnoDB</code> can discard the update undo log record
written for the deletion can it also physically remove the
corresponding row and its index records from the database. This
removal operation is called a purge, and it is quite fast, usually
taking the same order of time as the SQL statement that did the
deletion.
</p><p>
In a scenario where the user inserts and deletes rows in smallish
batches at about the same rate in the table, it is possible that
the purge thread starts to lag behind, and the table grows bigger
and bigger, making everything disk-bound and very slow. Even if
the table carries just 10MB of useful data, it may grow to occupy
10GB with all the “<span class="quote">dead</span>” rows. In such a case, it
would be good to throttle new row operations, and allocate more
resources to the purge thread. The
<code class="literal">innodb_max_purge_lag</code> system variable exists for
exactly this purpose. See <a href="storage-engines.html#innodb-parameters" title="13.2.4. InnoDB Startup Options and System Variables">Section 13.2.4, “<code class="literal">InnoDB</code> Startup Options and System Variables”</a>, for
more information.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-table-and-index"></a>13.2.13. <code class="literal">InnoDB</code> Table and Index Structures</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#innodb-physical-structure">13.2.13.1. Physical Structure of an Index</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-insert-buffering">13.2.13.2. Insert Buffering</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-adaptive-hash">13.2.13.3. Adaptive Hash Indexes</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-physical-record">13.2.13.4. Physical Row Structure</a></span></dt></dl></div><p>
MySQL stores its data dictionary information for tables in
<code class="filename">.frm</code> files in database directories. This is
true for all MySQL storage engines. But every
<code class="literal">InnoDB</code> table also has its own entry in the
<code class="literal">InnoDB</code> internal data dictionary inside the
tablespace. When MySQL drops a table or a database, it has to
delete both an <code class="filename">.frm</code> file or files, and the
corresponding entries inside the <code class="literal">InnoDB</code> data
dictionary. This is the reason why you cannot move
<code class="literal">InnoDB</code> tables between databases simply by
moving the <code class="filename">.frm</code> files.
</p><p>
Every <code class="literal">InnoDB</code> table has a special index called
the <em class="firstterm">clustered index</em> where the data for the
rows is stored. If you define a <code class="literal">PRIMARY KEY</code> on
your table, the index of the primary key is the clustered index.
</p><p>
If you do not define a <code class="literal">PRIMARY KEY</code> for your
table, MySQL picks the first <code class="literal">UNIQUE</code> index that
has only <code class="literal">NOT NULL</code> columns as the primary key
and <code class="literal">InnoDB</code> uses it as the clustered index. If
there is no such index in the table, <code class="literal">InnoDB</code>
internally generates a clustered index where the rows are ordered
by the row ID that <code class="literal">InnoDB</code> assigns to the rows
in such a table. The row ID is a 6-byte field that increases
monotonically as new rows are inserted. Thus, the rows ordered by
the row ID are physically in insertion order.
</p><p>
Accessing a row through the clustered index is fast because the
row data is on the same page where the index search leads. If a
table is large, the clustered index architecture often saves a
disk I/O when compared to the traditional solution. (In many
database systems, data storage uses a different page from the
index record.)
</p><p>
In <code class="literal">InnoDB</code>, the records in non-clustered indexes
(also called secondary indexes) contain the primary key value for
the row. <code class="literal">InnoDB</code> uses this primary key value to
search for the row from the clustered index. Note that if the
primary key is long, the secondary indexes use more space.
</p><p>
<code class="literal">InnoDB</code> compares <code class="literal">CHAR</code> and
<code class="literal">VARCHAR</code> strings of different lengths such that
the remaining length in the shorter string is treated as if padded
with spaces.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-physical-structure"></a>13.2.13.1. Physical Structure of an Index</h4></div></div></div><p>
All <code class="literal">InnoDB</code> indexes are B-trees where the
index records are stored in the leaf pages of the tree. The
default size of an index page is 16KB. When new records are
inserted, <code class="literal">InnoDB</code> tries to leave 1/16 of the
page free for future insertions and updates of the index
records.
</p><p>
If index records are inserted in a sequential order (ascending
or descending), the resulting index pages are about 15/16 full.
If records are inserted in a random order, the pages are from
1/2 to 15/16 full. If the fill factor of an index page drops
below 1/2, <code class="literal">InnoDB</code> tries to contract the index
tree to free the page.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-insert-buffering"></a>13.2.13.2. Insert Buffering</h4></div></div></div><p>
It is a common situation in database applications that the
primary key is a unique identifier and new rows are inserted in
the ascending order of the primary key. Thus, the insertions to
the clustered index do not require random reads from a disk.
</p><p>
On the other hand, secondary indexes are usually non-unique, and
insertions into secondary indexes happen in a relatively random
order. This would cause a lot of random disk I/O operations
without a special mechanism used in <code class="literal">InnoDB</code>.
</p><p>
If an index record should be inserted to a non-unique secondary
index, <code class="literal">InnoDB</code> checks whether the secondary
index page is in the buffer pool. If that is the case,
<code class="literal">InnoDB</code> does the insertion directly to the
index page. If the index page is not found in the buffer pool,
<code class="literal">InnoDB</code> inserts the record to a special insert
buffer structure. The insert buffer is kept so small that it
fits entirely in the buffer pool, and insertions can be done
very fast.
</p><p>
Periodically, the insert buffer is merged into the secondary
index trees in the database. Often it is possible to merge
several insertions to the same page of the index tree, saving
disk I/O operations. It has been measured that the insert buffer
can speed up insertions into a table up to 15 times.
</p><p>
The insert buffer merging may continue to happen
<span class="emphasis"><em>after</em></span> the inserting transaction has been
committed. In fact, it may continue to happen after a server
shutdown and restart (see <a href="storage-engines.html#forcing-recovery" title="13.2.8.1. Forcing InnoDB Recovery">Section 13.2.8.1, “Forcing <code class="literal">InnoDB</code> Recovery”</a>).
</p><p>
The insert buffer merging may take many hours, when many
secondary indexes must be updated, and many rows have been
inserted. During this time, disk I/O will be increased, which
can cause significant slowdown on disk-bound queries. Another
significant background I/O operation is the purge thread (see
<a href="storage-engines.html#innodb-multi-versioning" title="13.2.12. Implementation of Multi-Versioning">Section 13.2.12, “Implementation of Multi-Versioning”</a>).
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-adaptive-hash"></a>13.2.13.3. Adaptive Hash Indexes</h4></div></div></div><p>
If a table fits almost entirely in main memory, the fastest way
to perform queries on it is to use hash indexes.
<code class="literal">InnoDB</code> has a mechanism that monitors index
searches made to the indexes defined for a table. If
<code class="literal">InnoDB</code> notices that queries could benefit
from building a hash index, it does so automatically.
</p><p>
Note that the hash index is always built based on an existing
B-tree index on the table. <code class="literal">InnoDB</code> can build a
hash index on a prefix of any length of the key defined for the
B-tree, depending on the pattern of searches that
<code class="literal">InnoDB</code> observes for the B-tree index. A hash
index can be partial: It is not required that the whole B-tree
index is cached in the buffer pool. <code class="literal">InnoDB</code>
builds hash indexes on demand for those pages of the index that
are often accessed.
</p><p>
In a sense, <code class="literal">InnoDB</code> tailors itself through the
adaptive hash index mechanism to ample main memory, coming
closer to the architecture of main-memory databases.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-physical-record"></a>13.2.13.4. Physical Row Structure</h4></div></div></div><p>
The physical record structure for InnoDB tables is dependent on
the MySQL version and the optional <code class="literal">ROW_FORMAT</code>
option used when the table was created. For InnoDB tables in
MySQL earlier than 5.0.3, only the <code class="literal">REDUNDANT</code>
row format was available. For MySQL 5.0.3 and later, the default
is to use the <code class="literal">COMPACT</code> row format, but you can
use the <code class="literal">REDUNDANT</code> format to retain
compatibility with older versions of InnoDB tables.
</p><p>
Records in InnoDB <code class="literal">ROW_FORMAT=REDUNDANT</code> tables
have the following characteristics:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Each index record contains a six-byte header. The header is
used to link together consecutive records, and also in
row-level locking.
</p></li><li><p>
Records in the clustered index contain fields for all
user-defined columns. In addition, there is a six-byte field
for the transaction ID and a seven-byte field for the roll
pointer.
</p></li><li><p>
If no primary key was defined for a table, each clustered
index record also contains a six-byte row ID field.
</p></li><li><p>
Each secondary index record contains also all the fields
defined for the clustered index key.
</p></li><li><p>
A record contains also a pointer to each field of the
record. If the total length of the fields in a record is
less than 128 bytes, the pointer is one byte; otherwise, two
bytes. The array of these pointers is called the record
directory. The area where these pointers point is called the
data part of the record.
</p></li><li><p>
Internally, InnoDB stores fixed-length character columns
such as <code class="literal">CHAR(10)</code> in a fixed-length
format. InnoDB truncates trailing spaces from
<code class="literal">VARCHAR</code> columns.
</p></li><li><p>
An SQL <code class="literal">NULL</code> value reserves 1 or 2 bytes
in the record directory. Besides that, an SQL
<code class="literal">NULL</code> value reserves zero bytes in the
data part of the record if stored in a variable length
column. In a fixed-length column, it reserves the fixed
length of the column in the data part of the record. The
motivation behind reserving the fixed space for
<code class="literal">NULL</code> values is that it enables an update
of the column from <code class="literal">NULL</code> to a
non-<code class="literal">NULL</code> value to be done in place
without causing fragmentation of the index page.
</p></li></ul></div><p>
Records in InnoDB <code class="literal">ROW_FORMAT=COMPACT</code> tables
have the following characteristics:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Each index record contains a five-byte header that may be
preceded by a variable-length header. The header is used to
link together consecutive records, and also in row-level
locking.
</p></li><li><p>
The record header contains a bit vector for indicating
<code class="literal">NULL</code> columns. The bit vector occupies
(<code class="literal">n_nullable</code>+7)/8 bytes. Columns that are
<code class="literal">NULL</code> will not occupy other space than the
bit in this vector.
</p></li><li><p>
For each non-<code class="literal">NULL</code> variable-length field,
the record header contains the length of the column in one
or two bytes. Two bytes will only be needed if part of the
column is stored externally or the maximum length exceeds
255 bytes and the actual length exceeds 127 bytes.
</p></li><li><p>
The record header is followed by the data contents of the
columns. Columns that are <code class="literal">NULL</code> are
omitted.
</p></li><li><p>
Records in the clustered index contain fields for all
user-defined columns. In addition, there is a six-byte field
for the transaction ID and a seven-byte field for the roll
pointer.
</p></li><li><p>
If no primary key was defined for a table, each clustered
index record also contains a six-byte row ID field.
</p></li><li><p>
Each secondary index record contains also all the fields
defined for the clustered index key.
</p></li><li><p>
Internally, InnoDB stores fixed-length, fixed-width
character columns such as <code class="literal">CHAR(10)</code> in a
fixed-length format. InnoDB truncates trailing spaces from
<code class="literal">VARCHAR</code> columns.
</p></li><li><p>
Internally, InnoDB attempts to store UTF-8
<code class="literal">CHAR(<code class="literal">n</code>)</code> columns in
<code class="literal">n</code> bytes by trimming trailing spaces. In
<code class="literal">ROW_FORMAT=REDUNDANT</code>, such columns occupy
3*<code class="literal">n</code> bytes. The motivation behind
reserving the minimum space <code class="literal">n</code> is that it
in many cases enables an update of the column to be done in
place without causing fragmentation of the index page.
</p></li></ul></div><p>
The presence of the compact row format decreases row storage
space by about 20% at the cost of increasing CPU use for some
operations. If your workload is a typical one that is limited by
cache hit rates and disk speed it is likely to be faster. If it
is a rare case that is limited by CPU speed, it might be slower.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="file-space-management"></a>13.2.14. <code class="literal">InnoDB</code> File Space Management and Disk I/O</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#innodb-disk-io">13.2.14.1. <code class="literal">InnoDB</code> Disk I/O</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-file-space">13.2.14.2. File Space Management</a></span></dt><dt><span class="section"><a href="storage-engines.html#innodb-file-defragmenting">13.2.14.3. Defragmenting a Table</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-disk-io"></a>13.2.14.1. <code class="literal">InnoDB</code> Disk I/O</h4></div></div></div><p>
<code class="literal">InnoDB</code> uses simulated asynchronous disk I/O:
<code class="literal">InnoDB</code> creates a number of threads to take
care of I/O operations, such as read-ahead.
</p><p>
There are two read-ahead heuristics in
<code class="literal">InnoDB</code>:
</p><div class="itemizedlist"><ul type="disc"><li><p>
In sequential read-ahead, if <code class="literal">InnoDB</code>
notices that the access pattern to a segment in the
tablespace is sequential, it posts in advance a batch of
reads of database pages to the I/O system.
</p></li><li><p>
In random read-ahead, if <code class="literal">InnoDB</code> notices
that some area in a tablespace seems to be in the process of
being fully read into the buffer pool, it posts the
remaining reads to the I/O system.
</p></li></ul></div><p>
<code class="literal">InnoDB</code> uses a novel file flush technique
called <em class="firstterm">doublewrite</em>. It adds safety to
recovery following an operating system crash or a power outage,
and improves performance on most varieties of Unix by reducing
the need for <code class="literal">fsync()</code> operations.
</p><p>
Doublewrite means that before writing pages to a data file,
<code class="literal">InnoDB</code> first writes them to a contiguous
tablespace area called the doublewrite buffer. Only after the
write and the flush to the doublewrite buffer has completed does
<code class="literal">InnoDB</code> write the pages to their proper
positions in the data file. If the operating system crashes in
the middle of a page write, <code class="literal">InnoDB</code> can later
find a good copy of the page from the doublewrite buffer during
recovery.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-file-space"></a>13.2.14.2. File Space Management</h4></div></div></div><p>
The data files that you define in the configuration file form
the tablespace of <code class="literal">InnoDB</code>. The files are
simply concatenated to form the tablespace. There is no striping
in use. Currently, you cannot define where within the tablespace
your tables are allocated. However, in a newly created
tablespace, <code class="literal">InnoDB</code> allocates space starting
from the first data file.
</p><p>
The tablespace consists of database pages with a default size of
16KB. The pages are grouped into extents of 64 consecutive
pages. The “<span class="quote">files</span>” inside a tablespace are called
<em class="firstterm">segments</em> in <code class="literal">InnoDB</code>.
The term “<span class="quote">rollback segment</span>” is somewhat confusing
because it actually contains many tablespace segments.
</p><p>
Two segments are allocated for each index in
<code class="literal">InnoDB</code>. One is for non-leaf nodes of the
B-tree, the other is for the leaf nodes. The idea here is to
achieve better sequentiality for the leaf nodes, which contain
the data.
</p><p>
When a segment grows inside the tablespace,
<code class="literal">InnoDB</code> allocates the first 32 pages to it
individually. After that <code class="literal">InnoDB</code> starts to
allocate whole extents to the segment. <code class="literal">InnoDB</code>
can add to a large segment up to 4 extents at a time to ensure
good sequentiality of data.
</p><p>
Some pages in the tablespace contain bitmaps of other pages, and
therefore a few extents in an <code class="literal">InnoDB</code>
tablespace cannot be allocated to segments as a whole, but only
as individual pages.
</p><p>
When you ask for available free space in the tablespace by
issuing a <code class="literal">SHOW TABLE STATUS</code> statement,
<code class="literal">InnoDB</code> reports the extents that are
definitely free in the tablespace. <code class="literal">InnoDB</code>
always reserves some extents for cleanup and other internal
purposes; these reserved extents are not included in the free
space.
</p><p>
When you delete data from a table, <code class="literal">InnoDB</code>
contracts the corresponding B-tree indexes. Whether the freed
space becomes available for other users depends on whether the
pattern of deletes frees individual pages or extents to the
tablespace. Dropping a table or deleting all rows from it is
guaranteed to release the space to other users, but remember
that deleted rows are physically removed only in an (automatic)
purge operation after they are no longer needed for transaction
rollbacks or consistent reads. (See
<a href="storage-engines.html#innodb-multi-versioning" title="13.2.12. Implementation of Multi-Versioning">Section 13.2.12, “Implementation of Multi-Versioning”</a>.)
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-file-defragmenting"></a>13.2.14.3. Defragmenting a Table</h4></div></div></div><p>
If there are random insertions into or deletions from the
indexes of a table, the indexes may become fragmented.
Fragmentation means that the physical ordering of the index
pages on the disk is not close to the index ordering of the
records on the pages, or that there are many unused pages in the
64-page blocks that were allocated to the index.
</p><p>
A symptom of fragmentation is that a table takes more space than
it “<span class="quote">should</span>” take. How much that is exactly, is
difficult to determine. All <code class="literal">InnoDB</code> data and
indexes are stored in B-trees, and their fill factor may vary
from 50% to 100%. Another symptom of fragmentation is that a
table scan such as this takes more time than it
“<span class="quote">should</span>” take:
</p><pre class="programlisting">SELECT COUNT(*) FROM t WHERE a_non_indexed_column <> 12345;
</pre><p>
(In the preceding query, we are “<span class="quote">fooling</span>” the SQL
optimizer into scanning the clustered index, rather than a
secondary index.) Most disks can read 10 to 50MB/s, which can be
used to estimate how fast a table scan should run.
</p><p>
It can speed up index scans if you periodically perform a
“<span class="quote">null</span>” <code class="literal">ALTER TABLE</code> operation:
</p><pre class="programlisting">ALTER TABLE <em class="replaceable"><code>tbl_name</code></em> ENGINE=INNODB
</pre><p>
That causes MySQL to rebuild the table. Another way to perform a
defragmentation operation is to use <span><strong class="command">mysqldump</strong></span>
to dump the table to a text file, drop the table, and reload it
from the dump file.
</p><p>
If the insertions to an index are always ascending and records
are deleted only from the end, the <code class="literal">InnoDB</code>
filespace management algorithm guarantees that fragmentation in
the index does not occur.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-error-handling"></a>13.2.15. <code class="literal">InnoDB</code> Error Handling</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#innodb-error-codes">13.2.15.1. <code class="literal">InnoDB</code> Error Codes</a></span></dt><dt><span class="section"><a href="storage-engines.html#operating-system-error-codes">13.2.15.2. Operating System Error Codes</a></span></dt></dl></div><p>
Error handling in <code class="literal">InnoDB</code> is not always the same
as specified in the SQL standard. According to the standard, any
error during an SQL statement should cause the rollback of that
statement. <code class="literal">InnoDB</code> sometimes rolls back only
part of the statement, or the whole transaction. The following
items describe how <code class="literal">InnoDB</code> performs error
handling:
</p><div class="itemizedlist"><ul type="disc"><li><p>
If you run out of file space in the tablespace, a MySQL
<code class="literal">Table is full</code> error occurs and
<code class="literal">InnoDB</code> rolls back the SQL statement.
</p></li><li><p>
A transaction deadlock causes <code class="literal">InnoDB</code> to
roll back the entire transaction. In the case of a lock wait
timeout, <code class="literal">InnoDB</code> also rolls back the entire
transaction before MySQL 5.0.13; as of 5.0.13,
<code class="literal">InnoDB</code> rolls back only the most recent SQL
statement.
</p><p>
When a transaction rollback occurs due to a deadlock or lock
wait timeout, it cancels the effect of the statements within
the transaction. But if the start-transaction statement was
<code class="literal">START TRANSACTION</code> or
<code class="literal">BEGIN</code> statement, rollback does not cancel
that statement. Further SQL statements become part of the
transaction until the occurrence of <code class="literal">COMMIT</code>,
<code class="literal">ROLLBACK</code>, or some SQL statement that causes
an implicit commit.
</p></li><li><p>
A duplicate-key error rolls back the SQL statement, if you
have not specified the <code class="literal">IGNORE</code> option in
your statement.
</p></li><li><p>
A <code class="literal">row too long error</code> rolls back the SQL
statement.
</p></li><li><p>
Other errors are mostly detected by the MySQL layer of code
(above the <code class="literal">InnoDB</code> storage engine level),
and they roll back the corresponding SQL statement. Locks are
not released in a rollback of a single SQL statement.
</p></li></ul></div><p>
During implicit rollbacks, as well as during the execution of an
explicit <code class="literal">ROLLBACK</code> SQL statement, <code class="literal">SHOW
PROCESSLIST</code> displays <code class="literal">Rolling back</code> in
the <code class="literal">State</code> column for the relevant connection.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-error-codes"></a>13.2.15.1. <code class="literal">InnoDB</code> Error Codes</h4></div></div></div><p>
The following is a non-exhaustive list of common
<code class="literal">InnoDB</code>-specific errors that you may
encounter, with information about why each occurs and how to
resolve the problem.
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">1005 (ER_CANT_CREATE_TABLE)</code>
</p><p>
Cannot create table. If the error message refers to
<code class="literal">errno</code> 150, table creation failed because
a foreign key constraint was not correctly formed. If the
error message refers to <code class="literal">errno</code> -1, table
creation probably failed because the table included a column
name that matched the name of an internal InnoDB table.
</p></li><li><p>
<code class="literal">1016 (ER_CANT_OPEN_FILE)</code>
</p><p>
Cannot find the <code class="literal">InnoDB</code> table from the
<code class="literal">InnoDB</code> data files, although the
<code class="filename">.frm</code> file for the table exists. See
<a href="storage-engines.html#innodb-troubleshooting-datadict" title="13.2.17.1. Troubleshooting InnoDB Data Dictionary Operations">Section 13.2.17.1, “Troubleshooting <code class="literal">InnoDB</code> Data Dictionary Operations”</a>.
</p></li><li><p>
<code class="literal">1114 (ER_RECORD_FILE_FULL)</code>
</p><p>
<code class="literal">InnoDB</code> has run out of free space in the
tablespace. You should reconfigure the tablespace to add a
new data file.
</p></li><li><p>
<code class="literal">1205 (ER_LOCK_WAIT_TIMEOUT)</code>
</p><p>
Lock wait timeout expired. Transaction was rolled back.
</p></li><li><p>
<code class="literal">1213 (ER_LOCK_DEADLOCK)</code>
</p><p>
Transaction deadlock. You should rerun the transaction.
</p></li><li><p>
<code class="literal">1216 (ER_NO_REFERENCED_ROW)</code>
</p><p>
You are trying to add a row but there is no parent row, and
a foreign key constraint fails. You should add the parent
row first.
</p></li><li><p>
<code class="literal">1217 (ER_ROW_IS_REFERENCED)</code>
</p><p>
You are trying to delete a parent row that has children, and
a foreign key constraint fails. You should delete the
children first.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="operating-system-error-codes"></a>13.2.15.2. Operating System Error Codes</h4></div></div></div><p>
To print the meaning of an operating system error number, use
the <span><strong class="command">perror</strong></span> program that comes with the MySQL
distribution.
</p><p>
The following table provides a list of some common Linux system
error codes. For a more complete list, see
<a href="http://www.iglu.org.il/lxr/source/include/asm-i386/errno.h" target="_top">Linux
source code</a>.
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">1 (EPERM)</code>
</p><p>
Operation not permitted
</p></li><li><p>
<code class="literal">2 (ENOENT)</code>
</p><p>
No such file or directory
</p></li><li><p>
<code class="literal">3 (ESRCH)</code>
</p><p>
No such process
</p></li><li><p>
<code class="literal">4 (EINTR)</code>
</p><p>
Interrupted system call
</p></li><li><p>
<code class="literal">5 (EIO)</code>
</p><p>
I/O error
</p></li><li><p>
<code class="literal">6 (ENXIO)</code>
</p><p>
No such device or address
</p></li><li><p>
<code class="literal">7 (E2BIG)</code>
</p><p>
Arg list too long
</p></li><li><p>
<code class="literal">8 (ENOEXEC)</code>
</p><p>
Exec format error
</p></li><li><p>
<code class="literal">9 (EBADF)</code>
</p><p>
Bad file number
</p></li><li><p>
<code class="literal">10 (ECHILD)</code>
</p><p>
No child processes
</p></li><li><p>
<code class="literal">11 (EAGAIN)</code>
</p><p>
Try again
</p></li><li><p>
<code class="literal">12 (ENOMEM)</code>
</p><p>
Out of memory
</p></li><li><p>
<code class="literal">13 (EACCES)</code>
</p><p>
Permission denied
</p></li><li><p>
<code class="literal">14 (EFAULT)</code>
</p><p>
Bad address
</p></li><li><p>
<code class="literal">15 (ENOTBLK)</code>
</p><p>
Block device required
</p></li><li><p>
<code class="literal">16 (EBUSY)</code>
</p><p>
Device or resource busy
</p></li><li><p>
<code class="literal">17 (EEXIST)</code>
</p><p>
File exists
</p></li><li><p>
<code class="literal">18 (EXDEV)</code>
</p><p>
Cross-device link
</p></li><li><p>
<code class="literal">19 (ENODEV)</code>
</p><p>
No such device
</p></li><li><p>
<code class="literal">20 (ENOTDIR)</code>
</p><p>
Not a directory
</p></li><li><p>
<code class="literal">21 (EISDIR)</code>
</p><p>
Is a directory
</p></li><li><p>
<code class="literal">22 (EINVAL)</code>
</p><p>
Invalid argument
</p></li><li><p>
<code class="literal">23 (ENFILE)</code>
</p><p>
File table overflow
</p></li><li><p>
<code class="literal">24 (EMFILE)</code>
</p><p>
Too many open files
</p></li><li><p>
<code class="literal">25 (ENOTTY)</code>
</p><p>
Inappropriate ioctl for device
</p></li><li><p>
<code class="literal">26 (ETXTBSY)</code>
</p><p>
Text file busy
</p></li><li><p>
<code class="literal">27 (EFBIG)</code>
</p><p>
File too large
</p></li><li><p>
<code class="literal">28 (ENOSPC)</code>
</p><p>
No space left on device
</p></li><li><p>
<code class="literal">29 (ESPIPE)</code>
</p><p>
Illegal seek
</p></li><li><p>
<code class="literal">30 (EROFS)</code>
</p><p>
Read-only file system
</p></li><li><p>
<code class="literal">31 (EMLINK)</code>
</p><p>
Too many links
</p></li></ul></div><p>
The following table provides a list of some common Windows
system error codes. For a complete list see the
<a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/debug/base/system_error_codes.asp" target="_top">Microsoft
Web site</a>.
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">1 (ERROR_INVALID_FUNCTION)</code>
</p><p>
Incorrect function.
</p></li><li><p>
<code class="literal">2 (ERROR_FILE_NOT_FOUND)</code>
</p><p>
The system cannot find the file specified.
</p></li><li><p>
<code class="literal">3 (ERROR_PATH_NOT_FOUND)</code>
</p><p>
The system cannot find the path specified.
</p></li><li><p>
<code class="literal">4 (ERROR_TOO_MANY_OPEN_FILES)</code>
</p><p>
The system cannot open the file.
</p></li><li><p>
<code class="literal">5 (ERROR_ACCESS_DENIED)</code>
</p><p>
Access is denied.
</p></li><li><p>
<code class="literal">6 (ERROR_INVALID_HANDLE)</code>
</p><p>
The handle is invalid.
</p></li><li><p>
<code class="literal">7 (ERROR_ARENA_TRASHED)</code>
</p><p>
The storage control blocks were destroyed.
</p></li><li><p>
<code class="literal">8 (ERROR_NOT_ENOUGH_MEMORY)</code>
</p><p>
Not enough storage is available to process this command.
</p></li><li><p>
<code class="literal">9 (ERROR_INVALID_BLOCK)</code>
</p><p>
The storage control block address is invalid.
</p></li><li><p>
<code class="literal">10 (ERROR_BAD_ENVIRONMENT)</code>
</p><p>
The environment is incorrect.
</p></li><li><p>
<code class="literal">11 (ERROR_BAD_FORMAT)</code>
</p><p>
An attempt was made to load a program with an incorrect
format.
</p></li><li><p>
<code class="literal">12 (ERROR_INVALID_ACCESS)</code>
</p><p>
The access code is invalid.
</p></li><li><p>
<code class="literal">13 (ERROR_INVALID_DATA)</code>
</p><p>
The data is invalid.
</p></li><li><p>
<code class="literal">14 (ERROR_OUTOFMEMORY)</code>
</p><p>
Not enough storage is available to complete this operation.
</p></li><li><p>
<code class="literal">15 (ERROR_INVALID_DRIVE)</code>
</p><p>
The system cannot find the drive specified.
</p></li><li><p>
<code class="literal">16 (ERROR_CURRENT_DIRECTORY)</code>
</p><p>
The directory cannot be removed.
</p></li><li><p>
<code class="literal">17 (ERROR_NOT_SAME_DEVICE)</code>
</p><p>
The system cannot move the file to a different disk drive.
</p></li><li><p>
<code class="literal">18 (ERROR_NO_MORE_FILES)</code>
</p><p>
There are no more files.
</p></li><li><p>
<code class="literal">19 (ERROR_WRITE_PROTECT)</code>
</p><p>
The media is write protected.
</p></li><li><p>
<code class="literal">20 (ERROR_BAD_UNIT)</code>
</p><p>
The system cannot find the device specified.
</p></li><li><p>
<code class="literal">21 (ERROR_NOT_READY)</code>
</p><p>
The device is not ready.
</p></li><li><p>
<code class="literal">22 (ERROR_BAD_COMMAND)</code>
</p><p>
The device does not recognize the command.
</p></li><li><p>
<code class="literal">23 (ERROR_CRC)</code>
</p><p>
Data error (cyclic redundancy check).
</p></li><li><p>
<code class="literal">24 (ERROR_BAD_LENGTH)</code>
</p><p>
The program issued a command but the command length is
incorrect.
</p></li><li><p>
<code class="literal">25 (ERROR_SEEK)</code>
</p><p>
The drive cannot locate a specific area or track on the
disk.
</p></li><li><p>
<code class="literal">26 (ERROR_NOT_DOS_DISK)</code>
</p><p>
The specified disk or diskette cannot be accessed.
</p></li><li><p>
<code class="literal">27 (ERROR_SECTOR_NOT_FOUND)</code>
</p><p>
The drive cannot find the sector requested.
</p></li><li><p>
<code class="literal">28 (ERROR_OUT_OF_PAPER)</code>
</p><p>
The printer is out of paper.
</p></li><li><p>
<code class="literal">29 (ERROR_WRITE_FAULT)</code>
</p><p>
The system cannot write to the specified device.
</p></li><li><p>
<code class="literal">30 (ERROR_READ_FAULT)</code>
</p><p>
The system cannot read from the specified device.
</p></li><li><p>
<code class="literal">31 (ERROR_GEN_FAILURE)</code>
</p><p>
A device attached to the system is not functioning.
</p></li><li><p>
<code class="literal">32 (ERROR_SHARING_VIOLATION)</code>
</p><p>
The process cannot access the file because it is being used
by another process.
</p></li><li><p>
<code class="literal">33 (ERROR_LOCK_VIOLATION)</code>
</p><p>
The process cannot access the file because another process
has locked a portion of the file.
</p></li><li><p>
<code class="literal">34 (ERROR_WRONG_DISK)</code>
</p><p>
The wrong diskette is in the drive. Insert %2 (Volume Serial
Number: %3) into drive %1.
</p></li><li><p>
<code class="literal">36 (ERROR_SHARING_BUFFER_EXCEEDED)</code>
</p><p>
Too many files opened for sharing.
</p></li><li><p>
<code class="literal">38 (ERROR_HANDLE_EOF)</code>
</p><p>
Reached the end of the file.
</p></li><li><p>
<code class="literal">39 (ERROR_HANDLE_DISK_FULL)</code>
</p><p>
The disk is full.
</p></li><li><p>
<code class="literal">87 (ERROR_INVALID_PARAMETER)</code>
</p><p>
The parameter is incorrect. (If this error occurs on Windows
and you have enabled
<code class="literal">innodb_file_per_table</code> in a server option
file, add the line
<code class="literal">innodb_flush_method=unbuffered</code> to the
file as well.)
</p></li><li><p>
<code class="literal">112 (ERROR_DISK_FULL)</code>
</p><p>
The disk is full.
</p></li><li><p>
<code class="literal">123 (ERROR_INVALID_NAME)</code>
</p><p>
The filename, directory name, or volume label syntax is
incorrect.
</p></li><li><p>
<code class="literal">1450 (ERROR_NO_SYSTEM_RESOURCES)</code>
</p><p>
Insufficient system resources exist to complete the
requested service.
</p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-restrictions"></a>13.2.16. Restrictions on <code class="literal">InnoDB</code> Tables</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
Do <span class="emphasis"><em>not</em></span> convert MySQL system tables in
the <code class="literal">mysql</code> database from
<code class="literal">MyISAM</code> to <code class="literal">InnoDB</code>
tables! This is an unsupported operation. If you do this,
MySQL does not restart until you restore the old system
tables from a backup or re-generate them with the
<span><strong class="command">mysql_install_db</strong></span> script.
</p></div></li><li><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
<a class="indexterm" name="id2915877"></a>
<a class="indexterm" name="id2915890"></a>
It is not a good idea to configure <code class="literal">InnoDB</code>
to use datafiles or logfiles on NFS volumes. Otherwise, the
files might be locked by other processes and become
unavailable for use by MySQL.
</p></div></li><li><p>
A table cannot contain more than 1000 columns.
</p></li><li><p>
The internal maximum key length is 3500 bytes, but MySQL
itself restricts this to 3072 bytes. (1024 bytes for
non-64-bit builds before MySQL 5.0.17, and for all builds
before 5.0.15.)
</p></li><li><p>
The maximum row length, except for
<code class="literal">VARBINARY</code>, <code class="literal">VARCHAR</code>,
<code class="literal">BLOB</code> and <code class="literal">TEXT</code> columns,
is slightly less than half of a database page. That is, the
maximum row length is about 8000 bytes.
<code class="literal">LONGBLOB</code> and <code class="literal">LONGTEXT</code>
columns must be less than 4GB, and the total row length,
including also <code class="literal">BLOB</code> and
<code class="literal">TEXT</code> columns, must be less than 4GB.
<code class="literal">InnoDB</code> stores the first 768 bytes of a
<code class="literal">VARBINARY</code>, <code class="literal">VARCHAR</code>,
<code class="literal">BLOB</code>, or <code class="literal">TEXT</code> column in
the row, and the rest into separate pages.
</p></li><li><p>
Although <code class="literal">InnoDB</code> supports row sizes larger
than 65535 internally, you cannot define a row containing
<code class="literal">VARBINARY</code> or <code class="literal">VARCHAR</code>
columns with a combined size larger than 65535:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>CREATE TABLE t (a VARCHAR(8000), b VARCHAR(10000),</code></strong>
-> <strong class="userinput"><code>c VARCHAR(10000), d VARCHAR(10000), e VARCHAR(10000),</code></strong>
-> <strong class="userinput"><code>f VARCHAR(10000), g VARCHAR(10000)) ENGINE=InnoDB;</code></strong>
ERROR 1118 (42000): Row size too large. The maximum row size for the
used table type, not counting BLOBs, is 65535. You have to change some
columns to TEXT or BLOBs
</pre></li><li><p>
On some older operating systems, files must be less than 2GB.
This is not a limitation of <code class="literal">InnoDB</code> itself,
but if you require a large tablespace, you will need to
configure it using several smaller data files rather than one
or a file large data files.
</p></li><li><p>
The combined size of the <code class="literal">InnoDB</code> log files
must be less than 4GB.
</p></li><li><p>
The minimum tablespace size is 10MB. The maximum tablespace
size is four billion database pages (64TB). This is also the
maximum size for a table.
</p></li><li><p>
<code class="literal">InnoDB</code> tables do not support
<code class="literal">FULLTEXT</code> indexes.
</p></li><li><p>
<code class="literal">InnoDB</code> tables do not support spatial data
types before MySQL 5.0.16. As of 5.0.16,
<code class="literal">InnoDB</code> supports spatial types, but not
indexes on them.
</p></li><li><p>
<code class="literal">ANALYZE TABLE</code> determines index cardinality
(as displayed in the <code class="literal">Cardinality</code> column of
<code class="literal">SHOW INDEX</code> output) by doing ten random
dives to each of the index trees and updating index
cardinality estimates accordingly. Note that because these are
only estimates, repeated runs of <code class="literal">ANALYZE
TABLE</code> may produce different numbers. This makes
<code class="literal">ANALYZE TABLE</code> fast on
<code class="literal">InnoDB</code> tables but not 100% accurate as it
doesn't take all rows into account.
</p><p>
MySQL uses index cardinality estimates only in join
optimization. If some join is not optimized in the right way,
you can try using <code class="literal">ANALYZE TABLE</code>. In the few
cases that <code class="literal">ANALYZE TABLE</code> doesn't produce
values good enough for your particular tables, you can use
<code class="literal">FORCE INDEX</code> with your queries to force the
use of a particular index, or set the
<code class="literal">max_seeks_for_key</code> system variable to ensure
that MySQL prefers index lookups over table scans. See
<a href="server-administration.html#server-system-variables" title="5.2.3. System Variables">Section 5.2.3, “System Variables”</a>, and
<a href="error-handling.html#optimizer-issues" title="B.1.6. Optimizer-Related Issues">Section B.1.6, “Optimizer-Related Issues”</a>.
</p></li><li><p>
<code class="literal">SHOW TABLE STATUS</code> does not give accurate
statistics on <code class="literal">InnoDB</code> tables, except for the
physical size reserved by the table. The row count is only a
rough estimate used in SQL optimization.
</p></li><li><p>
<code class="literal">InnoDB</code> does not keep an internal count of
rows in a table. (In practice, this would be somewhat
complicated due to multi-versioning.) To process a
<code class="literal">SELECT COUNT(*) FROM t</code> statement,
<code class="literal">InnoDB</code> must scan an index of the table,
which takes some time if the index is not entirely in the
buffer pool. To get a fast count, you have to use a counter
table you create yourself and let your application update it
according to the inserts and deletes it does. If your table
does not change often, using the MySQL query cache is a good
solution. <code class="literal">SHOW TABLE STATUS</code> also can be
used if an approximate row count is sufficient. See
<a href="storage-engines.html#innodb-tuning" title="13.2.11. InnoDB Performance Tuning Tips">Section 13.2.11, “<code class="literal">InnoDB</code> Performance Tuning Tips”</a>.
</p></li><li><p>
On Windows, <code class="literal">InnoDB</code> always stores database
and table names internally in lowercase. To move databases in
binary format from Unix to Windows or from Windows to Unix,
you should always use explicitly lowercase names when creating
databases and tables.
</p></li><li><p>
For an <code class="literal">AUTO_INCREMENT</code> column, you must
always define an index for the table, and that index must
contain just the <code class="literal">AUTO_INCREMENT</code> column. In
<code class="literal">MyISAM</code> tables, the
<code class="literal">AUTO_INCREMENT</code> column may be part of a
multi-column index.
</p></li><li><p>
In MySQL 5.0 before MySQL 5.0.3,
<code class="literal">InnoDB</code> does not support the
<code class="literal">AUTO_INCREMENT</code> table option for setting the
initial sequence value in a <code class="literal">CREATE TABLE</code> or
<code class="literal">ALTER TABLE</code> statement. To set the value
with <code class="literal">InnoDB</code>, insert a dummy row with a
value one less and delete that dummy row, or insert the first
row with an explicit value specified.
</p></li><li><p>
While initializing a previously specified
<code class="literal">AUTO_INCREMENT</code> column on a table,
<code class="literal">InnoDB</code> sets an exclusive lock on the end of
the index associated with the
<code class="literal">AUTO_INCREMENT</code> column. In accessing the
auto-increment counter, <code class="literal">InnoDB</code> uses a
specific table lock mode <code class="literal">AUTO-INC</code> where the
lock lasts only to the end of the current SQL statement, not
to the end of the entire transaction. Note that other clients
cannot insert into the table while the
<code class="literal">AUTO-INC</code> table lock is held; see
<a href="storage-engines.html#innodb-and-autocommit" title="13.2.10.2. InnoDB and AUTOCOMMIT">Section 13.2.10.2, “<code class="literal">InnoDB</code> and <code class="literal">AUTOCOMMIT</code>”</a>.
</p></li><li><p>
When you restart the MySQL server, <code class="literal">InnoDB</code>
may reuse an old value that was generated for an
<code class="literal">AUTO_INCREMENT</code> column but never stored
(that is, a value that was generated during an old transaction
that was rolled back).
</p></li><li><p>
When an <code class="literal">AUTO_INCREMENT</code> column runs out of
values, <code class="literal">InnoDB</code> wraps a
<code class="literal">BIGINT</code> to
<code class="literal">-9223372036854775808</code> and <code class="literal">BIGINT
UNSIGNED</code> to <code class="literal">1</code>. However,
<code class="literal">BIGINT</code> values have 64 bits, so do note that
if you were to insert one million rows per second, it would
still take nearly three hundred thousand years before
<code class="literal">BIGINT</code> reached its upper bound. With all
other integer type columns, a duplicate-key error results.
This is similar to how <code class="literal">MyISAM</code> works,
because it is mostly general MySQL behavior and not about any
storage engine in particular.
</p></li><li><p>
<code class="literal">DELETE FROM
<em class="replaceable"><code>tbl_name</code></em></code> does not
regenerate the table but instead deletes all rows, one by one.
</p></li><li><p>
Under some conditions, <code class="literal">TRUNCATE
<em class="replaceable"><code>tbl_name</code></em></code> for an
<code class="literal">InnoDB</code> table is mapped to <code class="literal">DELETE
FROM <em class="replaceable"><code>tbl_name</code></em></code> and doesn't
reset the <code class="literal">AUTO_INCREMENT</code> counter. See
<a href="sql-syntax.html#truncate" title="12.2.9. TRUNCATE Syntax">Section 12.2.9, “<code class="literal">TRUNCATE</code> Syntax”</a>.
</p></li><li><p>
In MySQL 5.0, the MySQL <code class="literal">LOCK
TABLES</code> operation acquires two locks on each table if
<code class="literal">innodb_table_locks=1</code> (the default). In
addition to a table lock on the MySQL layer, it also acquires
an <code class="literal">InnoDB</code> table lock. Older versions of
MySQL did not acquire <code class="literal">InnoDB</code> table locks;
the old behavior can be selected by setting
<code class="literal">innodb_table_locks=0</code>. If no
<code class="literal">InnoDB</code> table lock is acquired,
<code class="literal">LOCK TABLES</code> completes even if some records
of the tables are being locked by other transactions.
</p></li><li><p>
All <code class="literal">InnoDB</code> locks held by a transaction are
released when the transaction is committed or aborted. Thus,
it does not make much sense to invoke <code class="literal">LOCK
TABLES</code> on <code class="literal">InnoDB</code> tables in
<code class="literal">AUTOCOMMIT=1</code> mode, because the acquired
<code class="literal">InnoDB</code> table locks would be released
immediately.
</p></li><li><p>
Sometimes it would be useful to lock further tables in the
course of a transaction. Unfortunately, <code class="literal">LOCK
TABLES</code> in MySQL performs an implicit
<code class="literal">COMMIT</code> and <code class="literal">UNLOCK
TABLES</code>. An <code class="literal">InnoDB</code> variant of
<code class="literal">LOCK TABLES</code> has been planned that can be
executed in the middle of a transaction.
</p></li><li><p>
The <code class="literal">LOAD TABLE FROM MASTER</code> statement for
setting up replication slave servers does not work for
<code class="literal">InnoDB</code> tables. A workaround is to alter the
table to <code class="literal">MyISAM</code> on the master, then do the
load, and after that alter the master table back to
<code class="literal">InnoDB</code>. Do not do this if the tables use
<code class="literal">InnoDB</code>-specific features such as foreign
keys.
</p></li><li><p>
The default database page size in <code class="literal">InnoDB</code> is
16KB. By recompiling the code, you can set it to values
ranging from 8KB to 64KB. You must update the values of
<code class="literal">UNIV_PAGE_SIZE</code> and
<code class="literal">UNIV_PAGE_SIZE_SHIFT</code> in the
<code class="filename">univ.i</code> source file.
</p></li><li><p>
Currently, triggers are not activated by cascaded foreign key
actions.
</p></li><li><p>
You cannot create a table with a column name that matches the
name of an internal InnoDB column (including
<code class="literal">DB_ROW_ID</code>, <code class="literal">DB_TRX_ID</code>,
<code class="literal">DB_ROLL_PTR</code> and
<code class="literal">DB_MIX_ID</code>). In versions of MySQL before
5.0.21 this would cause a crash, since 5.0.21 the server will
report error 1005 and refers to <code class="literal">errno</code> -1 in
the error message.
</p></li><li><p>
As of MySQL 5.0.19, <code class="literal">InnoDB</code> does not ignore
trailing spaces when comparing <code class="literal">BINARY</code> or
<code class="literal">VARBINARY</code> column values. See
<a href="data-types.html#binary-varbinary" title="10.4.2. The BINARY and VARBINARY Types">Section 10.4.2, “The <code class="literal">BINARY</code> and <code class="literal">VARBINARY</code> Types”</a> and
<a href="news.html#news-5-0-19" title="E.1.11. Changes in MySQL 5.0.19 (04 March 2006)">Section E.1.11, “Changes in MySQL 5.0.19 (04 March 2006)”</a>.
</p></li><li><p>
<code class="literal">InnoDB</code> has a limit of 1023 concurrent
transactions that have created undo records by modifying data.
Workarounds include keeping transactions as small and fast as
possible, delaying changes until near the end of the
transaction, and using stored routines to reduce client-server
latency delays. Applications should commit transactions before
doing time-consuming client-side operations.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="innodb-troubleshooting"></a>13.2.17. <code class="literal">InnoDB</code> Troubleshooting</h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#innodb-troubleshooting-datadict">13.2.17.1. Troubleshooting <code class="literal">InnoDB</code> Data Dictionary Operations</a></span></dt></dl></div><p>
The following general guidelines apply to troubleshooting
<code class="literal">InnoDB</code> problems:
</p><div class="itemizedlist"><ul type="disc"><li><p>
When an operation fails or you suspect a bug, you should look
at the MySQL server error log, which is the file in the data
directory that has a suffix of <code class="filename">.err</code>.
</p></li><li><p>
When troubleshooting, it is usually best to run the MySQL
server from the command prompt, rather than through the
<span><strong class="command">mysqld_safe</strong></span> wrapper or as a Windows
service. You can then see what <span><strong class="command">mysqld</strong></span>
prints to the console, and so have a better grasp of what is
going on. On Windows, you must start the server with the
<code class="filename">--console</code> option to direct the output to
the console window.
</p></li><li><p>
Use the <code class="literal">InnoDB</code> Monitors to obtain
information about a problem (see
<a href="storage-engines.html#innodb-monitor" title="13.2.11.1. SHOW ENGINE INNODB STATUS and the
InnoDB Monitors">Section 13.2.11.1, “<code class="literal">SHOW ENGINE INNODB STATUS</code> and the
<code class="literal">InnoDB</code> Monitors”</a>). If the problem is
performance-related, or your server appears to be hung, you
should use <code class="literal">innodb_monitor</code> to print
information about the internal state of
<code class="literal">InnoDB</code>. If the problem is with locks, use
<code class="literal">innodb_lock_monitor</code>. If the problem is in
creation of tables or other data dictionary operations, use
<code class="literal">innodb_table_monitor</code> to print the contents
of the <code class="literal">InnoDB</code> internal data dictionary.
</p></li><li><p>
If you suspect that a table is corrupt, run <code class="literal">CHECK
TABLE</code> on that table.
</p></li></ul></div><p class="mnmas"><b>MySQL Enterprise</b>
The MySQL Enterprise Monitor provides a number of advisors
specifically designed for monitoring InnoDB tables. In some
cases, these advisors can anticipate potential problems. For
more information see
<a href="http://www.mysql.com/products/enterprise/advisors.html" target="_top">http://www.mysql.com/products/enterprise/advisors.html</a>.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="innodb-troubleshooting-datadict"></a>13.2.17.1. Troubleshooting <code class="literal">InnoDB</code> Data Dictionary Operations</h4></div></div></div><p>
A specific issue with tables is that the MySQL server keeps data
dictionary information in <code class="filename">.frm</code> files it
stores in the database directories, whereas
<code class="literal">InnoDB</code> also stores the information into its
own data dictionary inside the tablespace files. If you move
<code class="filename">.frm</code> files around, or if the server crashes
in the middle of a data dictionary operation, the locations of
the <code class="filename">.frm</code> files may end up out of synchrony
with the locations recorded in the <code class="literal">InnoDB</code>
internal data dictionary.
</p><p>
A symptom of an out-of-sync data dictionary is that a
<code class="literal">CREATE TABLE</code> statement fails. If this occurs,
you should look in the server's error log. If the log says that
the table already exists inside the <code class="literal">InnoDB</code>
internal data dictionary, you have an orphaned table inside the
<code class="literal">InnoDB</code> tablespace files that has no
corresponding <code class="filename">.frm</code> file. The error message
looks like this:
</p><pre class="programlisting">InnoDB: Error: table test/parent already exists in InnoDB internal
InnoDB: data dictionary. Have you deleted the .frm file
InnoDB: and not used DROP TABLE? Have you used DROP DATABASE
InnoDB: for InnoDB tables in MySQL version <= 3.23.43?
InnoDB: See the Restrictions section of the InnoDB manual.
InnoDB: You can drop the orphaned table inside InnoDB by
InnoDB: creating an InnoDB table with the same name in another
InnoDB: database and moving the .frm file to the current database.
InnoDB: Then MySQL thinks the table exists, and DROP TABLE will
InnoDB: succeed.
</pre><p>
You can drop the orphaned table by following the instructions
given in the error message. If you are still unable to use
<code class="literal">DROP TABLE</code> successfully, the problem may be
due to name completion in the <span><strong class="command">mysql</strong></span> client.
To work around this problem, start the <span><strong class="command">mysql</strong></span>
client with the <code class="option">--skip-auto-rehash</code> option and
try <code class="literal">DROP TABLE</code> again. (With name completion
on, <span><strong class="command">mysql</strong></span> tries to construct a list of table
names, which fails when a problem such as just described
exists.)
</p><p>
Another symptom of an out-of-sync data dictionary is that MySQL
prints an error that it cannot open a
<code class="filename">.InnoDB</code> file:
</p><pre class="programlisting">ERROR 1016: Can't open file: 'child2.InnoDB'. (errno: 1)
</pre><p>
In the error log you can find a message like this:
</p><pre class="programlisting">InnoDB: Cannot find table test/child2 from the internal data dictionary
InnoDB: of InnoDB though the .frm file for the table exists. Maybe you
InnoDB: have deleted and recreated InnoDB data files but have forgotten
InnoDB: to delete the corresponding .frm files of InnoDB tables?
</pre><p>
This means that there is an orphaned <code class="filename">.frm</code>
file without a corresponding table inside
<code class="literal">InnoDB</code>. You can drop the orphaned
<code class="filename">.frm</code> file by deleting it manually.
</p><p>
If MySQL crashes in the middle of an <code class="literal">ALTER
TABLE</code> operation, you may end up with an orphaned
temporary table inside the <code class="literal">InnoDB</code> tablespace.
Using <code class="literal">innodb_table_monitor</code> you can see listed
a table whose name is <code class="filename">#sql-...</code>. You can
perform SQL statements on tables whose name contains the
character “<span class="quote"><code class="literal">#</code></span>” if you enclose the
name within backticks. Thus, you can drop such an orphaned table
like any other orphaned table using the method described
earlier. Note that to copy or rename a file in the Unix shell,
you need to put the file name in double quotes if the file name
contains “<span class="quote"><code class="literal">#</code></span>”.
</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="merge-storage-engine"></a>13.3. The <code class="literal">MERGE</code> Storage Engine</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#merge-table-problems">13.3.1. <code class="literal">MERGE</code> Table Problems</a></span></dt></dl></div><a class="indexterm" name="id2917406"></a><a class="indexterm" name="id2917415"></a><a class="indexterm" name="id2917428"></a><a class="indexterm" name="id2917440"></a><a class="indexterm" name="id2917453"></a><p>
The <code class="literal">MERGE</code> storage engine, also known as the
<code class="literal">MRG_MyISAM</code> engine, is a collection of identical
<code class="literal">MyISAM</code> tables that can be used as one.
“<span class="quote">Identical</span>” means that all tables have identical column
and index information. You cannot merge <code class="literal">MyISAM</code>
tables in which the columns are listed in a different order, do not
have exactly the same columns, or have the indexes in different
order. However, any or all of the <code class="literal">MyISAM</code> tables
can be compressed with <span><strong class="command">myisampack</strong></span>. See
<a href="client-utility-programs.html#myisampack" title="7.6. myisampack — Generate Compressed, Read-Only MyISAM Tables">Section 7.6, “<span><strong class="command">myisampack</strong></span> — Generate Compressed, Read-Only MyISAM Tables”</a>. Differences in table options such as
<code class="literal">AVG_ROW_LENGTH</code>, <code class="literal">MAX_ROWS</code>, or
<code class="literal">PACK_KEYS</code> do not matter.
</p><p>
When you create a <code class="literal">MERGE</code> table, MySQL creates two
files on disk. The files have names that begin with the table name
and have an extension to indicate the file type. An
<code class="filename">.frm</code> file stores the table format, and an
<code class="filename">.MRG</code> file contains the names of the tables that
should be used as one. The tables do not have to be in the same
database as the <code class="literal">MERGE</code> table itself.
</p><p>
Starting with MySQL 5.0.36 the underlying table definitions and
indexes must conform more closely to the definition of the
<code class="literal">MERGE</code> table. Conformance will be checked when the
merged tables are opened, not when the <code class="literal">MERGE</code>
table is created. This means that changes to the definitions of
tables within a <code class="literal">MERGE</code> may cause a failure when
the <code class="literal">MERGE</code> table is accessed.
</p><p>
You can use <code class="literal">SELECT</code>, <code class="literal">DELETE</code>,
<code class="literal">UPDATE</code>, and <code class="literal">INSERT</code> on
<code class="literal">MERGE</code> tables. You must have
<code class="literal">SELECT</code>, <code class="literal">UPDATE</code>, and
<code class="literal">DELETE</code> privileges on the
<code class="literal">MyISAM</code> tables that you map to a
<code class="literal">MERGE</code> table.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The use of <code class="literal">MERGE</code> tables entails the following
security issue: If a user has access to <code class="literal">MyISAM</code>
table <em class="replaceable"><code>t</code></em>, that user can create a
<code class="literal">MERGE</code> table <em class="replaceable"><code>m</code></em> that
accesses <em class="replaceable"><code>t</code></em>. However, if the user's
privileges on <em class="replaceable"><code>t</code></em> are subsequently
revoked, the user can continue to access
<em class="replaceable"><code>t</code></em> by doing so through
<em class="replaceable"><code>m</code></em>. If this behavior is undesirable, you
can start the server with the new <code class="option">--skip-merge</code>
option to disable the <code class="literal">MERGE</code> storage engine.
This option is available as of MySQL 5.0.24.
</p></div><p>
If you <code class="literal">DROP</code> the <code class="literal">MERGE</code> table,
you are dropping only the <code class="literal">MERGE</code> specification.
The underlying tables are not affected.
</p><p>
To create a <code class="literal">MERGE</code> table, you must specify a
<code class="literal">UNION=(<em class="replaceable"><code>list-of-tables</code></em>)</code>
clause that indicates which <code class="literal">MyISAM</code> tables you
want to use as one. You can optionally specify an
<code class="literal">INSERT_METHOD</code> option if you want inserts for the
<code class="literal">MERGE</code> table to take place in the first or last
table of the <code class="literal">UNION</code> list. Use a value of
<code class="literal">FIRST</code> or <code class="literal">LAST</code> to cause inserts
to be made in the first or last table, respectively. If you do not
specify an <code class="literal">INSERT_METHOD</code> option or if you specify
it with a value of <code class="literal">NO</code>, attempts to insert rows
into the <code class="literal">MERGE</code> table result in an error.
</p><p>
The following example shows how to create a <code class="literal">MERGE</code>
table:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>CREATE TABLE t1 (</code></strong>
-> <strong class="userinput"><code>a INT NOT NULL AUTO_INCREMENT PRIMARY KEY,</code></strong>
-> <strong class="userinput"><code>message CHAR(20)) ENGINE=MyISAM;</code></strong>
mysql> <strong class="userinput"><code>CREATE TABLE t2 (</code></strong>
-> <strong class="userinput"><code>a INT NOT NULL AUTO_INCREMENT PRIMARY KEY,</code></strong>
-> <strong class="userinput"><code>message CHAR(20)) ENGINE=MyISAM;</code></strong>
mysql> <strong class="userinput"><code>INSERT INTO t1 (message) VALUES ('Testing'),('table'),('t1');</code></strong>
mysql> <strong class="userinput"><code>INSERT INTO t2 (message) VALUES ('Testing'),('table'),('t2');</code></strong>
mysql> <strong class="userinput"><code>CREATE TABLE total (</code></strong>
-> <strong class="userinput"><code>a INT NOT NULL AUTO_INCREMENT,</code></strong>
-> <strong class="userinput"><code>message CHAR(20), INDEX(a))</code></strong>
-> <strong class="userinput"><code>ENGINE=MERGE UNION=(t1,t2) INSERT_METHOD=LAST;</code></strong>
</pre><p>
The older term <code class="literal">TYPE</code> is supported as a synonym for
<code class="literal">ENGINE</code> for backward compatibility, but
<code class="literal">ENGINE</code> is the preferred term and
<code class="literal">TYPE</code> is deprecated.
</p><p>
Note that the <code class="literal">a</code> column is indexed as a
<code class="literal">PRIMARY KEY</code> in the underlying
<code class="literal">MyISAM</code> tables, but not in the
<code class="literal">MERGE</code> table. There it is indexed but not as a
<code class="literal">PRIMARY KEY</code> because a <code class="literal">MERGE</code>
table cannot enforce uniqueness over the set of underlying tables.
</p><p>
In MySQL 5.0.36 and higher, when a table that is part of a
<code class="literal">MERGE</code> table is opened, the following checks are
applied before opening each table. If any table fails the
conformance checks, then the operation that triggered the opening of
the table will fail. The conformance checks applied to each table
are:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Table must have exactly the same amount of columns that
<code class="literal">MERGE</code> table has.
</p></li><li><p>
Column order in the <code class="literal">MERGE</code> table must match
the column order in the underlying tables.
</p></li><li><p>
Additionally, the specification for each column in the parent
<code class="literal">MERGE</code> table and the underlying table are
compared. For each column, MySQL checks:
</p><div class="itemizedlist"><ul type="circle"><li><p>
Column type in the underlying table equals the column type
of <code class="literal">MERGE</code> table.
</p></li><li><p>
Column length in the underlying table equals the column
length of <code class="literal">MERGE</code> table.
</p></li><li><p>
Column of underlying table and column of
<code class="literal">MERGE</code> table can be
<code class="literal">NULL</code>.
</p></li></ul></div></li><li><p>
Underlying table must have at least the same amount of keys that
merge table has. The underlying table may have morekeys than the
<code class="literal">MERGE</code> table, but cannot have less.
</p></li><li><p>
For each key:
</p><div class="itemizedlist"><ul type="circle"><li><p>
Check if the key type of underlying table equals the key
type of merge table.
</p></li><li><p>
Check if number of key parts (i.e. multiple columns within a
compound key) in the underlying table key definition equals
the number of key parts in merge table key definition.
</p></li><li><p>
For each key part:
</p><div class="itemizedlist"><ul type="square"><li><p>
Check if key part lengths are equal.
</p></li><li><p>
Check if key part types are equal.
</p></li><li><p>
Check if key part languages are equal.
</p></li><li><p>
Check if key part can be <code class="literal">NULL</code>.
</p></li></ul></div></li></ul></div></li></ul></div><p>
After creating the <code class="literal">MERGE</code> table, you can issue
queries that operate on the group of tables as a whole:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>SELECT * FROM total;</code></strong>
+---+---------+
| a | message |
+---+---------+
| 1 | Testing |
| 2 | table |
| 3 | t1 |
| 1 | Testing |
| 2 | table |
| 3 | t2 |
+---+---------+
</pre><p>
To remap a <code class="literal">MERGE</code> table to a different collection
of <code class="literal">MyISAM</code> tables, you can use one of the
following methods:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">DROP</code> the <code class="literal">MERGE</code> table and
re-create it.
</p></li><li><p>
Use <code class="literal">ALTER TABLE <em class="replaceable"><code>tbl_name</code></em>
UNION=(...)</code> to change the list of underlying tables.
</p></li></ul></div><p>
<code class="literal">MERGE</code> tables can help you solve the following
problems:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Easily manage a set of log tables. For example, you can put data
from different months into separate tables, compress some of
them with <span><strong class="command">myisampack</strong></span>, and then create a
<code class="literal">MERGE</code> table to use them as one.
</p></li><li><p>
Obtain more speed. You can split a big read-only table based on
some criteria, and then put individual tables on different
disks. A <code class="literal">MERGE</code> table on this could be much
faster than using the big table.
</p></li><li><p>
Perform more efficient searches. If you know exactly what you
are looking for, you can search in just one of the split tables
for some queries and use a <code class="literal">MERGE</code> table for
others. You can even have many different
<code class="literal">MERGE</code> tables that use overlapping sets of
tables.
</p></li><li><p>
Perform more efficient repairs. It is easier to repair
individual tables that are mapped to a <code class="literal">MERGE</code>
table than to repair a single large table.
</p></li><li><p>
Instantly map many tables as one. A <code class="literal">MERGE</code>
table need not maintain an index of its own because it uses the
indexes of the individual tables. As a result,
<code class="literal">MERGE</code> table collections are
<span class="emphasis"><em>very</em></span> fast to create or remap. (Note that
you must still specify the index definitions when you create a
<code class="literal">MERGE</code> table, even though no indexes are
created.)
</p></li><li><p>
If you have a set of tables from which you create a large table
on demand, you should instead create a <code class="literal">MERGE</code>
table on them on demand. This is much faster and saves a lot of
disk space.
</p></li><li><p>
Exceed the file size limit for the operating system. Each
<code class="literal">MyISAM</code> table is bound by this limit, but a
collection of <code class="literal">MyISAM</code> tables is not.
</p></li><li><p>
You can create an alias or synonym for a
<code class="literal">MyISAM</code> table by defining a
<code class="literal">MERGE</code> table that maps to that single table.
There should be no really notable performance impact from doing
this (only a couple of indirect calls and
<code class="literal">memcpy()</code> calls for each read).
</p></li></ul></div><p>
The disadvantages of <code class="literal">MERGE</code> tables are:
</p><div class="itemizedlist"><ul type="disc"><li><p>
You can use only identical <code class="literal">MyISAM</code> tables for
a <code class="literal">MERGE</code> table.
</p></li><li><p>
You cannot use a number of <code class="literal">MyISAM</code> features in
<code class="literal">MERGE</code> tables. For example, you cannot create
<code class="literal">FULLTEXT</code> indexes on <code class="literal">MERGE</code>
tables. (You can, of course, create <code class="literal">FULLTEXT</code>
indexes on the underlying <code class="literal">MyISAM</code> tables, but
you cannot search the <code class="literal">MERGE</code> table with a
full-text search.)
</p></li><li><p>
If the <code class="literal">MERGE</code> table is non-temporary, all
underlying <code class="literal">MyISAM</code> tables must be
non-temporary, too. If the <code class="literal">MERGE</code> table is
temporary, the <code class="literal">MyISAM</code> tables can be any mix
of temporary and non-temporary.
</p></li><li><p>
<code class="literal">MERGE</code> tables use more file descriptors. If 10
clients are using a <code class="literal">MERGE</code> table that maps to
10 tables, the server uses (10 × 10) + 10 file
descriptors. (10 data file descriptors for each of the 10
clients, and 10 index file descriptors shared among the
clients.)
</p></li><li><p>
Key reads are slower. When you read a key, the
<code class="literal">MERGE</code> storage engine needs to issue a read on
all underlying tables to check which one most closely matches
the given key. To read the next key, the
<code class="literal">MERGE</code> storage engine needs to search the read
buffers to find the next key. Only when one key buffer is used
up does the storage engine need to read the next key block. This
makes <code class="literal">MERGE</code> keys much slower on
<code class="literal">eq_ref</code> searches, but not much slower on
<code class="literal">ref</code> searches. See <a href="optimization.html#explain" title="6.2.1. Optimizing Queries with EXPLAIN">Section 6.2.1, “Optimizing Queries with <code class="literal">EXPLAIN</code>”</a>,
for more information about <code class="literal">eq_ref</code> and
<code class="literal">ref</code>.
</p></li></ul></div><p>
<span class="bold"><strong>Additional resources</strong></span>
</p><div class="itemizedlist"><ul type="disc"><li><p>
A forum dedicated to the <code class="literal">MERGE</code> storage engine
is available at <a href="http://forums.mysql.com/list.php?93" target="_top">http://forums.mysql.com/list.php?93</a>.
</p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="merge-table-problems"></a>13.3.1. <code class="literal">MERGE</code> Table Problems</h3></div></div></div><p>
The following are known problems with <code class="literal">MERGE</code>
tables:
</p><div class="itemizedlist"><ul type="disc"><li><p>
If you use <code class="literal">ALTER TABLE</code> to change a
<code class="literal">MERGE</code> table to another storage engine, the
mapping to the underlying tables is lost. Instead, the rows
from the underlying <code class="literal">MyISAM</code> tables are
copied into the altered table, which then uses the specified
storage engine.
</p></li><li><p>
<code class="literal">REPLACE</code> does not work.
</p></li><li><p>
You cannot use <code class="literal">REPAIR TABLE</code>,
<code class="literal">OPTIMIZE TABLE</code>, <code class="literal">DROP
TABLE</code>, <code class="literal">ALTER TABLE</code>,
<code class="literal">DELETE</code> without a <code class="literal">WHERE</code>
clause, <code class="literal">TRUNCATE TABLE</code>, or <code class="literal">ANALYZE
TABLE</code> on any of the tables that are mapped into an
open <code class="literal">MERGE</code> table. If you do so, the
<code class="literal">MERGE</code> table may still refer to the original
table, which yields unexpected results. The easiest way to
work around this deficiency is to ensure that no
<code class="literal">MERGE</code> tables remain open by issuing a
<code class="literal">FLUSH TABLES</code> statement prior to performing
any of those operations.
</p><p>
The unexpected results include the possibility that the
operation on the <code class="literal">MERGE</code> table will report
table corruption. However, if this occurs after operations on
the underlying <code class="literal">MyISAM</code> tables such as those
listed in the previous paragraph (<code class="literal">REPAIR
TABLE</code>, <code class="literal">OPTIMIZE TABLE</code>, and so
forth), the corruption message is spurious. To deal with this,
issue a <code class="literal">FLUSH TABLES</code> statement after
modifying the <code class="literal">MyISAM</code> tables.
</p></li><li><p>
<code class="literal">DROP TABLE</code> on a table that is in use by a
<code class="literal">MERGE</code> table does not work on Windows
because the <code class="literal">MERGE</code> storage engine's table
mapping is hidden from the upper layer of MySQL. Windows does
not allow open files to be deleted, so you first must flush
all <code class="literal">MERGE</code> tables (with <code class="literal">FLUSH
TABLES</code>) or drop the <code class="literal">MERGE</code> table
before dropping the table.
</p></li><li><p>
A <code class="literal">MERGE</code> table cannot maintain uniqueness
constraints over the entire table. When you perform an
<code class="literal">INSERT</code>, the data goes into the first or
last <code class="literal">MyISAM</code> table (depending on the value
of the <code class="literal">INSERT_METHOD</code> option). MySQL ensures
that unique key values remain unique within that
<code class="literal">MyISAM</code> table, but not across all the tables
in the collection.
</p></li><li><p>
In MySQL 5.0.36 and later, the definition of the
<code class="literal">MyISAM</code> tables and the
<code class="literal">MERGE</code> table are checked when the tables are
accessed (for example, as part of a <code class="literal">SELECT</code>
or <code class="literal">INSERT</code> statement). The checks ensure
that the definitions of the tables and the parent
<code class="literal">MERGE</code> table definition match by comparing
column order, types, sizes and associated indexes. If there is
a difference between the tables then an error will be returned
and the statement will fail.
</p><p>
Because these checks take place when the tables are opened,
any changes to the definition of a single, including column
changes, ocolumn ordering and engine alterations will cause
the statement to fail.
</p><p>
In MySQL 5.0.35 and earlier:
</p><div class="itemizedlist"><ul type="circle"><li><p>
When you create or alter <code class="literal">MERGE</code> table,
there is no check to ensure that the underlying tables are
existing <code class="literal">MyISAM</code> tables and have
identical structures. When the <code class="literal">MERGE</code>
table is used, MySQL checks that the row length for all
mapped tables is equal, but this is not foolproof. If you
create a <code class="literal">MERGE</code> table from dissimilar
<code class="literal">MyISAM</code> tables, you are very likely to
run into strange problems.
</p></li><li><p>
Similarly, if you create a <code class="literal">MERGE</code> table
from non-<code class="literal">MyISAM</code> tables, or if you drop
an underlying table or alter it to be a
non-<code class="literal">MyISAM</code> table, no error for the
<code class="literal">MERGE</code> table occurs until later when you
attempt to use it.
</p></li><li><p>
Because the underlying <code class="literal">MyISAM</code> tables
need not exist when the <code class="literal">MERGE</code> table is
created, you can create the tables in any order, as long
as you do not use the <code class="literal">MERGE</code> table until
all of its underlying tables are in place. Also, if you
can ensure that a <code class="literal">MERGE</code> table will not
be used during a given period, you can perform maintenance
operations on the underlying tables, such as backing up or
restoring them, altering them, or dropping and recreating
them. It is not necessary to redefine the
<code class="literal">MERGE</code> table temporarily to exclude the
underlying tables while you are operating on them.
</p></li></ul></div></li><li><p>
The order of indexes in the <code class="literal">MERGE</code> table and
its underlying tables should be the same. If you use
<code class="literal">ALTER TABLE</code> to add a
<code class="literal">UNIQUE</code> index to a table used in a
<code class="literal">MERGE</code> table, and then use <code class="literal">ALTER
TABLE</code> to add a non-unique index on the
<code class="literal">MERGE</code> table, the index ordering is
different for the tables if there was already a non-unique
index in the underlying table. (This happens because
<code class="literal">ALTER TABLE</code> puts <code class="literal">UNIQUE</code>
indexes before non-unique indexes to facilitate rapid
detection of duplicate keys.) Consequently, queries on tables
with such indexes may return unexpected results.
</p></li><li><p>
If you encounter an error message similar to <code class="literal">ERROR
1017 (HY000): Can't find file:
'<em class="replaceable"><code>mm</code></em>.MRG' (errno: 2)</code> it
generally indicates that some of the base tables are not using
the MyISAM storage engine. Confirm that all tables are MyISAM.
</p></li><li><p>
There is a limit of 2<sup>32</sup>
(~4.295E+09)) rows to a <code class="literal">MERGE</code> table, just
as there is with a <code class="literal">MyISAM</code>, it is therefore
not possible to merge multiple <code class="literal">MyISAM</code>
tables that exceed this limitation. However, you build MySQL
with the <code class="option">--with-big-tables</code> option then the
row limitation is increased to
(2<sup>32</sup>)<sup>2</sup>
(1.844E+19) rows. See <a href="installing.html#configure-options" title="2.4.15.2. Typical configure Options">Section 2.4.15.2, “Typical <span><strong class="command">configure</strong></span> Options”</a>.
Beginning with MySQL 5.0.4 all standard binaries are built
with this option.
</p></li><li><p>
The <code class="literal">MERGE</code> storage engine does not support
<code class="literal">INSERT DELAYED</code> statements.
</p></li><li><p>
Using <code class="literal">MERGE</code> on underlying
<code class="literal">MyISAM</code> tables that have different row
formats is possible.
</p></li></ul></div><p>
As of MySQL 5.0.44, if a <code class="literal">MERGE</code> table cannot be
opened or used because of a problem with an underlying table,
<code class="literal">CHECK TABLE</code> displays information about which
table caused the problem.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="memory-storage-engine"></a>13.4. The <code class="literal">MEMORY</code> (<code class="literal">HEAP</code>) Storage Engine</h2></div></div></div><a class="indexterm" name="id2919436"></a><a class="indexterm" name="id2919445"></a><a class="indexterm" name="id2919454"></a><a class="indexterm" name="id2919466"></a><p>
The <code class="literal">MEMORY</code> storage engine creates tables with
contents that are stored in memory. Formerly, these were known as
<code class="literal">HEAP</code> tables. <code class="literal">MEMORY</code> is the
preferred term, although <code class="literal">HEAP</code> remains supported
for backward compatibility.
</p><p>
Each <code class="literal">MEMORY</code> table is associated with one disk
file. The filename begins with the table name and has an extension
of <code class="filename">.frm</code> to indicate that it stores the table
definition.
</p><p>
To specify explicitly that you want to create a
<code class="literal">MEMORY</code> table, indicate that with an
<code class="literal">ENGINE</code> table option:
</p><pre class="programlisting">CREATE TABLE t (i INT) ENGINE = MEMORY;
</pre><p>
The older term <code class="literal">TYPE</code> is supported as a synonym for
<code class="literal">ENGINE</code> for backward compatibility, but
<code class="literal">ENGINE</code> is the preferred term and
<code class="literal">TYPE</code> is deprecated.
</p><p>
As indicated by the name, <code class="literal">MEMORY</code> tables are
stored in memory. They use hash indexes by default, which makes them
very fast, and very useful for creating temporary tables. However,
when the server shuts down, all rows stored in
<code class="literal">MEMORY</code> tables are lost. The tables themselves
continue to exist because their definitions are stored in
<code class="filename">.frm</code> files on disk, but they are empty when the
server restarts.
</p><p>
This example shows how you might create, use, and remove a
<code class="literal">MEMORY</code> table:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>CREATE TABLE test ENGINE=MEMORY</code></strong>
-> <strong class="userinput"><code>SELECT ip,SUM(downloads) AS down</code></strong>
-> <strong class="userinput"><code>FROM log_table GROUP BY ip;</code></strong>
mysql> <strong class="userinput"><code>SELECT COUNT(ip),AVG(down) FROM test;</code></strong>
mysql> <strong class="userinput"><code>DROP TABLE test;</code></strong>
</pre><p>
<code class="literal">MEMORY</code> tables have the following characteristics:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Space for <code class="literal">MEMORY</code> tables is allocated in small
blocks. Tables use 100% dynamic hashing for inserts. No overflow
area or extra key space is needed. No extra space is needed for
free lists. Deleted rows are put in a linked list and are reused
when you insert new data into the table.
<code class="literal">MEMORY</code> tables also have none of the problems
commonly associated with deletes plus inserts in hashed tables.
</p></li><li><p>
<code class="literal">MEMORY</code> tables can have up to 32 indexes per
table, 16 columns per index and a maximum key length of 500
bytes.
</p></li><li><p>
The <code class="literal">MEMORY</code> storage engine implements both
<code class="literal">HASH</code> and <code class="literal">BTREE</code> indexes.
You can specify one or the other for a given index by adding a
<code class="literal">USING</code> clause as shown here:
</p><pre class="programlisting">CREATE TABLE lookup
(id INT, INDEX USING HASH (id))
ENGINE = MEMORY;
CREATE TABLE lookup
(id INT, INDEX USING BTREE (id))
ENGINE = MEMORY;
</pre><p>
General characteristics of B-tree and hash indexes are described
in <a href="optimization.html#mysql-indexes" title="6.4.5. How MySQL Uses Indexes">Section 6.4.5, “How MySQL Uses Indexes”</a>.
</p></li><li><p>
You can have non-unique keys in a <code class="literal">MEMORY</code>
table. (This is an uncommon feature for implementations of hash
indexes.)
</p></li><li><p>
If you have a hash index on a <code class="literal">MEMORY</code> table
that has a high degree of key duplication (many index entries
containing the same value), updates to the table that affect key
values and all deletes are significantly slower. The degree of
this slowdown is proportional to the degree of duplication (or,
inversely proportional to the index cardinality). You can use a
<code class="literal">BTREE</code> index to avoid this problem.
</p></li><li><p>
Columns that are indexed can contain <code class="literal">NULL</code>
values.
</p></li><li><p>
<code class="literal">MEMORY</code> tables use a fixed-length row storage
format.
</p></li><li><p>
<code class="literal">MEMORY</code> tables cannot contain
<code class="literal">BLOB</code> or <code class="literal">TEXT</code> columns.
</p></li><li><p>
<code class="literal">MEMORY</code> includes support for
<code class="literal">AUTO_INCREMENT</code> columns.
</p></li><li><p>
You can use <code class="literal">INSERT DELAYED</code> with
<code class="literal">MEMORY</code> tables. See
<a href="sql-syntax.html#insert-delayed" title="12.2.4.2. INSERT DELAYED Syntax">Section 12.2.4.2, “<code class="literal">INSERT DELAYED</code> Syntax”</a>.
</p></li><li><p>
<code class="literal">MEMORY</code> tables are shared among all clients
(just like any other non-<code class="literal">TEMPORARY</code> table).
</p></li><li><p>
<code class="literal">MEMORY</code> table contents are stored in memory,
which is a property that <code class="literal">MEMORY</code> tables share
with internal tables that the server creates on the fly while
processing queries. However, the two types of tables differ in
that <code class="literal">MEMORY</code> tables are not subject to storage
conversion, whereas internal tables are:
</p><div class="itemizedlist"><ul type="circle"><li><p>
If an internal table becomes too large, the server
automatically converts it to an on-disk table. The size
limit is determined by the value of the
<code class="literal">tmp_table_size</code> system variable.
</p></li><li><p>
<code class="literal">MEMORY</code> tables are never converted to disk
tables. To ensure that you don't accidentally do anything
foolish, you can set the
<code class="literal">max_heap_table_size</code> system variable to
impose a maximum size on <code class="literal">MEMORY</code> tables.
For individual tables, you can also specify a
<code class="literal">MAX_ROWS</code> table option in the
<code class="literal">CREATE TABLE</code> statement.
</p></li></ul></div></li><li><p>
The server needs sufficient memory to maintain all
<code class="literal">MEMORY</code> tables that are in use at the same
time.
</p></li><li><p>
Memory used by a <code class="literal">MEMORY</code> table is not
reclaimed if you delete individual rows from the table. Memory
is only reclaimed when the entire table is deleted. Memory that
was previously used for rows that have been deleted will be
re-used for new rows only within the same table. To free up the
memory used by rows that have been deleted you should use
<code class="literal">ALTER TABLE ENGINE=MEMORY</code> to force a table
rebuild.
</p><p>
To free all the memory used by a <code class="literal">MEMORY</code> table
when you no longer require its contents, you should execute
<code class="literal">DELETE</code> or <code class="literal">TRUNCATE TABLE</code>,
or remove the table altogether using <code class="literal">DROP
TABLE</code>.
</p></li><li><p>
If you want to populate a <code class="literal">MEMORY</code> table when
the MySQL server starts, you can use the
<code class="option">--init-file</code> option. For example, you can put
statements such as <code class="literal">INSERT INTO ... SELECT</code> or
<code class="literal">LOAD DATA INFILE</code> into this file to load the
table from a persistent data source. See
<a href="server-administration.html#server-options" title="5.2.2. Command Options">Section 5.2.2, “Command Options”</a>, and
<a href="sql-syntax.html#load-data" title="12.2.5. LOAD DATA INFILE Syntax">Section 12.2.5, “<code class="literal">LOAD DATA INFILE</code> Syntax”</a>.
</p></li><li><p>
If you are using replication, the master server's
<code class="literal">MEMORY</code> tables become empty when it is shut
down and restarted. However, a slave is not aware that these
tables have become empty, so it returns out-of-date content if
you select data from them. When a <code class="literal">MEMORY</code>
table is used on the master for the first time since the master
was started, a <code class="literal">DELETE</code> statement is written to
the master's binary log automatically, thus synchronizing the
slave to the master again. Note that even with this strategy,
the slave still has outdated data in the table during the
interval between the master's restart and its first use of the
table. However, if you use the <code class="option">--init-file</code>
option to populate the <code class="literal">MEMORY</code> table on the
master at startup, it ensures that this time interval is zero.
</p></li><li><p>
The memory needed for one row in a <code class="literal">MEMORY</code>
table is calculated using the following expression:
</p><pre class="programlisting">SUM_OVER_ALL_BTREE_KEYS(<em class="replaceable"><code>max_length_of_key</code></em> + sizeof(char*) × 4)
+ SUM_OVER_ALL_HASH_KEYS(sizeof(char*) × 2)
+ ALIGN(<em class="replaceable"><code>length_of_row</code></em>+1, sizeof(char*))
</pre><p>
<code class="literal">ALIGN()</code> represents a round-up factor to cause
the row length to be an exact multiple of the
<code class="literal">char</code> pointer size.
<code class="literal">sizeof(char*)</code> is 4 on 32-bit machines and 8
on 64-bit machines.
</p></li></ul></div><p>
<span class="bold"><strong>Additional resources</strong></span>
</p><div class="itemizedlist"><ul type="disc"><li><p>
A forum dedicated to the <code class="literal">MEMORY</code> storage
engine is available at <a href="http://forums.mysql.com/list.php?92" target="_top">http://forums.mysql.com/list.php?92</a>.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bdb-storage-engine"></a>13.5. The <code class="literal">BDB</code> (<code class="literal">BerkeleyDB</code>) Storage
Engine</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#bdb-portability">13.5.1. Operating Systems Supported by <code class="literal">BDB</code></a></span></dt><dt><span class="section"><a href="storage-engines.html#bdb-install">13.5.2. Installing <code class="literal">BDB</code></a></span></dt><dt><span class="section"><a href="storage-engines.html#bdb-start">13.5.3. <code class="literal">BDB</code> Startup Options</a></span></dt><dt><span class="section"><a href="storage-engines.html#bdb-characteristics">13.5.4. Characteristics of <code class="literal">BDB</code> Tables</a></span></dt><dt><span class="section"><a href="storage-engines.html#bdb-restrictions">13.5.5. Restrictions on <code class="literal">BDB</code> Tables</a></span></dt><dt><span class="section"><a href="storage-engines.html#bdb-errors">13.5.6. Errors That May Occur When Using <code class="literal">BDB</code> Tables</a></span></dt></dl></div><a class="indexterm" name="id2920287"></a><a class="indexterm" name="id2920296"></a><a class="indexterm" name="id2920305"></a><a class="indexterm" name="id2920317"></a><p>
Sleepycat Software has provided MySQL with the Berkeley DB
transactional storage engine. This storage engine typically is
called <code class="literal">BDB</code> for short. <code class="literal">BDB</code>
tables may have a greater chance of surviving crashes and are also
capable of <code class="literal">COMMIT</code> and <code class="literal">ROLLBACK</code>
operations on transactions.
</p><p>
Support for the <code class="literal">BDB</code> storage engine is included in
MySQL source distributions, which come with a <code class="literal">BDB</code>
distribution that is patched to make it work with MySQL. You cannot
use a non-patched version of <code class="literal">BDB</code> with MySQL.
</p><p class="depnote"><b>BDB support will be removed</b>
Note that, as of MySQL 5.1, <code class="literal">BDB</code> isn't supported
any longer.
</p><p>
For general information about Berkeley DB, please visit the
Sleepycat Web site, <a href="http://www.sleepycat.com/" target="_top">http://www.sleepycat.com/</a>.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="bdb-portability"></a>13.5.1. Operating Systems Supported by <code class="literal">BDB</code></h3></div></div></div><p>
Currently, we know that the <code class="literal">BDB</code> storage engine
works with the following operating systems:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Linux 2.x Intel
</p></li><li><p>
Sun Solaris (SPARC and x86)
</p></li><li><p>
FreeBSD 4.x/5.x (x86, sparc64)
</p></li><li><p>
IBM AIX 4.3.x
</p></li><li><p>
SCO OpenServer
</p></li><li><p>
SCO UnixWare 7.1.x
</p></li><li><p>
Windows
</p></li></ul></div><p>
The <code class="literal">BDB</code> storage engine does
<span class="emphasis"><em>not</em></span> work with the following operating
systems:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Linux 2.x Alpha
</p></li><li><p>
Linux 2.x AMD64
</p></li><li><p>
Linux 2.x IA-64
</p></li><li><p>
Linux 2.x s390
</p></li><li><p>
Mac OS X
</p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The preceding lists are not complete. We update them as we
receive more information.
</p></div><p>
If you build MySQL from source with support for
<code class="literal">BDB</code> tables, but the following error occurs when
you start <span><strong class="command">mysqld</strong></span>, it means that the
<code class="literal">BDB</code> storage engine is not supported for your
architecture:
</p><pre class="programlisting">bdb: architecture lacks fast mutexes: applications cannot be threaded
Can't init databases
</pre><p>
In this case, you must rebuild MySQL without
<code class="literal">BDB</code> support or start the server with the
<code class="option">--skip-bdb</code> option.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="bdb-install"></a>13.5.2. Installing <code class="literal">BDB</code></h3></div></div></div><p>
If you have downloaded a binary version of MySQL that includes
support for Berkeley DB, simply follow the usual binary
distribution installation instructions.
</p><p>
If you build MySQL from source, you can enable
<code class="literal">BDB</code> support by invoking
<span><strong class="command">configure</strong></span> with the
<code class="option">--with-berkeley-db</code> option in addition to any
other options that you normally use. Download a MySQL
5.0 distribution, change location into its top-level
directory, and run this command:
</p><pre class="programlisting">shell> <strong class="userinput"><code>./configure --with-berkeley-db [<em class="replaceable"><code>other-options</code></em>]</code></strong>
</pre><p>
For more information, <a href="installing.html#installing-binary" title="2.4.14. Installing MySQL from tar.gz Packages on Other
Unix-Like Systems">Section 2.4.14, “Installing MySQL from <code class="filename">tar.gz</code> Packages on Other
Unix-Like Systems”</a>, and
<a href="installing.html#installing-source" title="2.4.15. MySQL Installation Using a Source Distribution">Section 2.4.15, “MySQL Installation Using a Source Distribution”</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="bdb-start"></a>13.5.3. <code class="literal">BDB</code> Startup Options</h3></div></div></div><p>
The following options to <span><strong class="command">mysqld</strong></span> can be used to
change the behavior of the <code class="literal">BDB</code> storage engine.
For more information, see <a href="server-administration.html#server-options" title="5.2.2. Command Options">Section 5.2.2, “Command Options”</a>.
</p><div class="informaltable"><table border="1"><colgroup><col><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"></colgroup><thead><tr><th><span class="bold"><strong>Name</strong></span></th><th align="center"><span class="bold"><strong>Cmd-line</strong></span></th><th align="center"><span class="bold"><strong>Option file</strong></span></th><th align="center"><span class="bold"><strong>System Var</strong></span></th><th align="center"><span class="bold"><strong>Status Var</strong></span></th><th align="center"><span class="bold"><strong>Var Scope</strong></span></th><th align="center"><span class="bold"><strong>Dynamic</strong></span></th></tr></thead><tbody><tr><td><a href="server-administration.html#option_mysqld_bdb-home">bdb-home</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td> - <span class="emphasis"><em>Variable</em></span>: bdb_home</td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_bdb-lock-detect">bdb-lock-detect</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_bdb-logdir">bdb-logdir</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td> - <span class="emphasis"><em>Variable</em></span>: bdb_logdir</td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_bdb-no-recover">bdb-no-recover</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td><a href="server-administration.html#option_mysqld_bdb-shared-data">bdb-shared-data</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td> - <span class="emphasis"><em>Variable</em></span>: bdb_shared_data</td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_bdb-tmpdir">bdb-tmpdir</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td> - <span class="emphasis"><em>Variable</em></span>: bdb_tmpdir</td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_bdb_cache_size">bdb_cache_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_bdb_log_buffer_size">bdb_log_buffer_size</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_bdb_max_lock">bdb_max_lock</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_have_bdb">have_bdb</a></td><td align="center"> </td><td align="center"> </td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="server-administration.html#option_mysqld_skip-bdb">skip-bdb</a></td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td> - <span class="emphasis"><em>Variable</em></span>: skip_bdb</td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td><a href="storage-engines.html#option_mysqld_sync-bdb-logs">skip-sync-bdb-logs</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr><tr><td><a href="storage-engines.html#option_mysqld_sync-bdb-logs">sync-bdb-logs</a></td><td align="center">Y</td><td align="center">Y</td><td align="center">Y</td><td align="center"> </td><td align="center">global</td><td align="center">no</td></tr></tbody></table></div><div class="itemizedlist"><ul type="disc"><li><p>
<a class="indexterm" name="id2921300"></a>
<a class="indexterm" name="id2921312"></a>
<code class="option">--bdb-home=<em class="replaceable"><code>path</code></em></code>
</p><p>
The base directory for <code class="literal">BDB</code> tables. This
should be the same directory that you use for
<code class="option">--datadir</code>.
</p></li><li><p><a name="option_mysqld_bdb-lock-detect"></a>
<a class="indexterm" name="id2921354"></a>
<a class="indexterm" name="id2921367"></a>
<code class="option">--bdb-lock-detect=<em class="replaceable"><code>method</code></em></code>
</p><p>
The <code class="literal">BDB</code> lock detection method. The option
value should be <code class="literal">DEFAULT</code>,
<code class="literal">OLDEST</code>, <code class="literal">RANDOM</code>, or
<code class="literal">YOUNGEST</code>.
</p></li><li><p>
<a class="indexterm" name="id2921426"></a>
<a class="indexterm" name="id2921439"></a>
<code class="option">--bdb-logdir=<em class="replaceable"><code>file_name</code></em></code>
</p><p>
The <code class="literal">BDB</code> log file directory.
</p></li><li><p><a name="option_mysqld_bdb-no-recover"></a>
<a class="indexterm" name="id2921476"></a>
<a class="indexterm" name="id2921489"></a>
<code class="option">--bdb-no-recover</code>
</p><p>
Do not start Berkeley DB in recover mode.
</p></li><li><p><a name="option_mysqld_bdb-no-sync"></a>
<a class="indexterm" name="id2921519"></a>
<a class="indexterm" name="id2921531"></a>
<code class="option">--bdb-no-sync</code>
</p><p>
Don't synchronously flush the <code class="literal">BDB</code> logs.
This option is deprecated; use
<code class="option">--skip-sync-bdb-logs</code> instead (see the
description for <code class="option">--sync-bdb-logs</code>).
</p></li><li><p>
<a class="indexterm" name="id2921573"></a>
<a class="indexterm" name="id2921585"></a>
<code class="option">--bdb-shared-data</code>
</p><p>
Start Berkeley DB in multi-process mode. (Do not use
<code class="literal">DB_PRIVATE</code> when initializing Berkeley DB.)
</p></li><li><p>
<a class="indexterm" name="id2921619"></a>
<a class="indexterm" name="id2921632"></a>
<code class="option">--bdb-tmpdir=<em class="replaceable"><code>path</code></em></code>
</p><p>
The <code class="literal">BDB</code> temporary file directory.
</p></li><li><p>
<a class="indexterm" name="id2921666"></a>
<a class="indexterm" name="id2921679"></a>
<code class="option">--skip-bdb</code>
</p><p>
Disable the <code class="literal">BDB</code> storage engine.
</p></li><li><p><a name="option_mysqld_sync-bdb-logs"></a>
<a class="indexterm" name="id2921714"></a>
<a class="indexterm" name="id2921726"></a>
<code class="option">--sync-bdb-logs</code>
</p><p>
Synchronously flush the <code class="literal">BDB</code> logs. This
option is enabled by default. Use
<code class="option">--skip-sync-bdb-logs</code> to disable it.
</p></li></ul></div><p>
If you use the <code class="option">--skip-bdb</code> option, MySQL does not
initialize the Berkeley DB library and this saves a lot of memory.
However, if you use this option, you cannot use
<code class="literal">BDB</code> tables. If you try to create a
<code class="literal">BDB</code> table, MySQL uses the default storage
engine instead.
</p><p>
Normally, you should start <span><strong class="command">mysqld</strong></span> without the
<code class="option">--bdb-no-recover</code> option if you intend to use
<code class="literal">BDB</code> tables. However, this may cause problems
when you try to start <span><strong class="command">mysqld</strong></span> if the
<code class="literal">BDB</code> log files are corrupted. See
<a href="installing.html#starting-server" title="2.4.16.2.3. Starting and Troubleshooting the MySQL Server">Section 2.4.16.2.3, “Starting and Troubleshooting the MySQL Server”</a>.
</p><p>
With the <code class="literal">bdb_max_lock</code> variable, you can specify
the maximum number of locks that can be active on a
<code class="literal">BDB</code> table. The default is 10,000. 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 execute a query:
</p><pre class="programlisting">bdb: Lock table is out of available locks
Got error 12 from ...
</pre><p>
You may also want to change the
<code class="literal">binlog_cache_size</code> and
<code class="literal">max_binlog_cache_size</code> variables if you are
using large multiple-statement transactions. See
<a href="server-administration.html#binary-log" title="5.10.3. The Binary Log">Section 5.10.3, “The Binary Log”</a>.
</p><p>
See also <a href="server-administration.html#server-system-variables" title="5.2.3. System Variables">Section 5.2.3, “System Variables”</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="bdb-characteristics"></a>13.5.4. Characteristics of <code class="literal">BDB</code> Tables</h3></div></div></div><p>
Each <code class="literal">BDB</code> table is stored on disk in two files.
The files have names that begin with the table name and have an
extension to indicate the file type. An <code class="filename">.frm</code>
file stores the table format, and a <code class="filename">.db</code> file
contains the table data and indexes.
</p><p>
To specify explicitly that you want a <code class="literal">BDB</code>
table, indicate that with an <code class="literal">ENGINE</code> table
option:
</p><pre class="programlisting">CREATE TABLE t (i INT) ENGINE = BDB;
</pre><p>
The older term <code class="literal">TYPE</code> is supported as a synonym
for <code class="literal">ENGINE</code> for backward compatibility, but
<code class="literal">ENGINE</code> is the preferred term and
<code class="literal">TYPE</code> is deprecated.
</p><p>
<code class="literal">BerkeleyDB</code> is a synonym for
<code class="literal">BDB</code> in the <code class="literal">ENGINE</code> table
option.
</p><p>
The <code class="literal">BDB</code> storage engine provides transactional
tables. The way you use these tables depends on the autocommit
mode:
</p><div class="itemizedlist"><ul type="disc"><li><p>
If you are running with autocommit enabled (which is the
default), changes to <code class="literal">BDB</code> tables are
committed immediately and cannot be rolled back.
</p></li><li><p>
If you are running with autocommit disabled, changes do not
become permanent until you execute a <code class="literal">COMMIT</code>
statement. Instead of committing, you can execute
<code class="literal">ROLLBACK</code> to forget the changes.
</p><p>
You can start a transaction with the <code class="literal">START
TRANSACTION</code> or <code class="literal">BEGIN</code> statement to
suspend autocommit, or with <code class="literal">SET
AUTOCOMMIT=0</code> to disable autocommit explicitly.
</p></li></ul></div><p>
For more information about transactions, see
<a href="sql-syntax.html#commit" title="12.4.1. START TRANSACTION, COMMIT, and
ROLLBACK Syntax">Section 12.4.1, “<code class="literal">START TRANSACTION</code>, <code class="literal">COMMIT</code>, and
<code class="literal">ROLLBACK</code> Syntax”</a>.
</p><p>
The <code class="literal">BDB</code> storage engine has the following
characteristics:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">BDB</code> tables can have up to 31 indexes per
table, 16 columns per index, and a maximum key size of 1024
bytes.
</p></li><li><p>
MySQL requires a primary key in each <code class="literal">BDB</code>
table so that each row can be uniquely identified. If you
don't create one explicitly by declaring a <code class="literal">PRIMARY
KEY</code>, MySQL creates and maintains a hidden primary
key for you. The hidden key has a length of five bytes and is
incremented for each insert attempt. This key does not appear
in the output of <code class="literal">SHOW CREATE TABLE</code> or
<code class="literal">DESCRIBE</code>.
</p></li><li><p>
The primary key is faster than any other index, because it is
stored together with the row data. The other indexes are
stored as the key data plus the primary key, so it's important
to keep the primary key as short as possible to save disk
space and get better speed.
</p><p>
This behavior is similar to that of <code class="literal">InnoDB</code>,
where shorter primary keys save space not only in the primary
index but in secondary indexes as well.
</p></li><li><p>
If all columns that you access in a <code class="literal">BDB</code>
table are part of the same index or part of the primary key,
MySQL can execute the query without having to access the
actual row. In a <code class="literal">MyISAM</code> table, this can be
done only if the columns are part of the same index.
</p></li><li><p>
Sequential scanning is slower for <code class="literal">BDB</code>
tables than for <code class="literal">MyISAM</code> tables because the
data in <code class="literal">BDB</code> tables is stored in B-trees and
not in a separate data file.
</p></li><li><p>
Key values are not prefix- or suffix-compressed like key
values in <code class="literal">MyISAM</code> tables. In other words,
key information takes a little more space in
<code class="literal">BDB</code> tables compared to
<code class="literal">MyISAM</code> tables.
</p></li><li><p>
There are often holes in the <code class="literal">BDB</code> table to
allow you to insert new rows in the middle of the index tree.
This makes <code class="literal">BDB</code> tables somewhat larger than
<code class="literal">MyISAM</code> tables.
</p></li><li><p>
<code class="literal">SELECT COUNT(*) FROM
<em class="replaceable"><code>tbl_name</code></em></code> is slow for
<code class="literal">BDB</code> tables, because no row count is
maintained in the table.
</p></li><li><p>
The optimizer needs to know the approximate number of rows in
the table. MySQL solves this by counting inserts and
maintaining this in a separate segment in each
<code class="literal">BDB</code> table. If you don't issue a lot of
<code class="literal">DELETE</code> or <code class="literal">ROLLBACK</code>
statements, this number should be accurate enough for the
MySQL optimizer. However, MySQL stores the number only on
close, so it may be incorrect if the server terminates
unexpectedly. It should not be fatal even if this number is
not 100% correct. You can update the row count by using
<code class="literal">ANALYZE TABLE</code> or <code class="literal">OPTIMIZE
TABLE</code>. See <a href="sql-syntax.html#analyze-table" title="12.5.2.1. ANALYZE TABLE Syntax">Section 12.5.2.1, “<code class="literal">ANALYZE TABLE</code> Syntax”</a>, and
<a href="sql-syntax.html#optimize-table" title="12.5.2.5. OPTIMIZE TABLE Syntax">Section 12.5.2.5, “<code class="literal">OPTIMIZE TABLE</code> Syntax”</a>.
</p></li><li><p>
Internal locking in <code class="literal">BDB</code> tables is done at
the page level.
</p></li><li><p>
<code class="literal">LOCK TABLES</code> works on <code class="literal">BDB</code>
tables as with other tables. If you do not use <code class="literal">LOCK
TABLES</code>, MySQL issues an internal multiple-write lock
on the table (a lock that does not block other writers) to
ensure that the table is properly locked if another thread
issues a table lock.
</p></li><li><p>
To support transaction rollback, the <code class="literal">BDB</code>
storage engine maintains log files. For maximum performance,
you can use the <code class="option">--bdb-logdir</code> option to place
the <code class="literal">BDB</code> logs on a different disk than the
one where your databases are located.
</p></li><li><p>
MySQL performs a checkpoint each time a new
<code class="literal">BDB</code> log file is started, and removes any
<code class="literal">BDB</code> log files that are not needed for
current transactions. You can also use <code class="literal">FLUSH
LOGS</code> at any time to checkpoint the Berkeley DB
tables.
</p><p>
For disaster recovery, you should use table backups plus
MySQL's binary log. See <a href="server-administration.html#backup" title="5.9.1. Database Backups">Section 5.9.1, “Database Backups”</a>.
</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
If you delete old log files that are still in use,
<code class="literal">BDB</code> is not able to do recovery at all and
you may lose data if something goes wrong.
</p></div></li><li><p>
Applications must always be prepared to handle cases where any
change of a <code class="literal">BDB</code> table may cause an
automatic rollback and any read may fail with a deadlock
error.
</p></li><li><p>
If you get a full disk with a <code class="literal">BDB</code> table,
you get an error (probably error 28) and the transaction
should roll back. This contrasts with
<code class="literal">MyISAM</code> tables, for which
<span><strong class="command">mysqld</strong></span> waits for sufficient free disk space
before continuing.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="bdb-restrictions"></a>13.5.5. Restrictions on <code class="literal">BDB</code> Tables</h3></div></div></div><p>
The following list indicates restrictions that you must observe
when using <code class="literal">BDB</code> tables:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Each <code class="literal">BDB</code> table stores in its
<code class="filename">.db</code> file the path to the file as it was
created. This is done to enable detection of locks in a
multi-user environment that supports symlinks. As a
consequence of this, it is not possible to move
<code class="literal">BDB</code> table files from one database directory
to another.
</p></li><li><p>
When making backups of <code class="literal">BDB</code> tables, you must
either use <span><strong class="command">mysqldump</strong></span> or else make a backup
that includes the files for each <code class="literal">BDB</code> table
(the <code class="filename">.frm</code> and <code class="filename">.db</code>
files) as well as the <code class="literal">BDB</code> log files. The
<code class="literal">BDB</code> storage engine stores unfinished
transactions in its log files and requires them to be present
when <span><strong class="command">mysqld</strong></span> starts. The
<code class="literal">BDB</code> logs are the files in the data
directory with names of the form
<code class="filename">log.<em class="replaceable"><code>NNNNNNNNNN</code></em></code>
(ten digits).
</p></li><li><p>
If a column that allows <code class="literal">NULL</code> values has a
unique index, only a single <code class="literal">NULL</code> value is
allowed. This differs from other storage engines, which allow
multiple <code class="literal">NULL</code> values in unique indexes.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="bdb-errors"></a>13.5.6. Errors That May Occur When Using <code class="literal">BDB</code> Tables</h3></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
If the following error occurs when you start
<span><strong class="command">mysqld</strong></span> after upgrading, it means that the
current version of <code class="literal">BDB</code> doesn't support the
old log file format:
</p><pre class="programlisting">bdb: Ignoring log file: .../log.<em class="replaceable"><code>NNNNNNNNNN</code></em>:
unsupported log version #
</pre><p>
In this case, you must delete all <code class="literal">BDB</code> logs
from your data directory (the files that have names of the
form
<code class="filename">log.<em class="replaceable"><code>NNNNNNNNNN</code></em></code>)
and restart <span><strong class="command">mysqld</strong></span>. We also recommend that
you then use <span><strong class="command">mysqldump --opt</strong></span> to dump your
<code class="literal">BDB</code> tables, drop the tables, and restore
them from the dump file.
</p></li><li><p>
If autocommit mode is disabled and you drop a
<code class="literal">BDB</code> table that is referenced in another
transaction, you may get error messages of the following form
in your MySQL error log:
</p><pre class="programlisting">001119 23:43:56 bdb: Missing log fileid entry
001119 23:43:56 bdb: txn_abort: Log undo failed for LSN:
1 3644744: Invalid
</pre><p>
This is not fatal, but the fix is not trivial. We recommend
that you not drop <code class="literal">BDB</code> tables except while
autocommit mode is enabled.
</p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="example-storage-engine"></a>13.6. The <code class="literal">EXAMPLE</code> Storage Engine</h2></div></div></div><a class="indexterm" name="id2922830"></a><a class="indexterm" name="id2922839"></a><p>
The <code class="literal">EXAMPLE</code> storage engine is a stub engine that
does nothing. Its purpose is to serve as an example in the MySQL
source code that illustrates how to begin writing new storage
engines. As such, it is primarily of interest to developers.
</p><p>
The <code class="literal">EXAMPLE</code> storage engine is included in MySQL
binary distributions. To enable this storage engine if you build
MySQL from source, invoke <span><strong class="command">configure</strong></span> with the
<code class="option">--with-example-storage-engine</code> option.
</p><p>
To examine the source for the <code class="literal">EXAMPLE</code> engine,
look in the <code class="filename">sql/examples</code> directory of a MySQL
source distribution.
</p><p>
When you create an <code class="literal">EXAMPLE</code> table, the server
creates a table format file in the database directory. The file
begins with the table name and has an <code class="filename">.frm</code>
extension. No other files are created. No data can be stored into
the table. Retrievals return an empty result.
</p><pre class="programlisting">mysql> <strong class="userinput"><code>CREATE TABLE test (i INT) ENGINE = EXAMPLE;</code></strong>
Query OK, 0 rows affected (0.78 sec)
mysql> <strong class="userinput"><code>INSERT INTO test VALUES(1),(2),(3);</code></strong>
ERROR 1031 (HY000): Table storage engine for 'test' doesn't have this option
mysql> <strong class="userinput"><code>SELECT * FROM test;</code></strong>
Empty set (0.31 sec)
</pre><p>
The <code class="literal">EXAMPLE</code> storage engine does not support
indexing.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="federated-storage-engine"></a>13.7. The <code class="literal">FEDERATED</code> Storage Engine</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="storage-engines.html#federated-description">13.7.1. Description of the <code class="literal">FEDERATED</code> Storage Engine</a></span></dt><dt><span class="section"><a href="storage-engines.html#federated-use">13.7.2. How to Use <code class="literal">FEDERATED</code> Tables</a></span></dt><dt><span class="section"><a href="storage-engines.html#federated-limitations">13.7.3. Limitations of the <code class="literal">FEDERATED</code> Storage Engine</a></span></dt></dl></div><a class="indexterm" name="id2922978"></a><a class="indexterm" name="id2922987"></a><p>
The <code class="literal">FEDERATED</code> storage engine is available
beginning with MySQL 5.0.3. It is a storage engine that accesses
data in tables of remote databases rather than in local tables.
</p><p>
The <code class="literal">FEDERATED</code> storage engine is included in MySQL
binary distributions. To enable this storage engine if you build
MySQL from source, invoke <span><strong class="command">configure</strong></span> with the
<code class="option">--with-federated-storage-engine</code> option.
</p><p>
To examine the source for the <code class="literal">FEDERATED</code> engine,
look in the <code class="filename">sql</code> directory of a source
distribution for MySQL 5.0.3 or newer.
</p><p>
<span class="bold"><strong>Additional resources</strong></span>
</p><div class="itemizedlist"><ul type="disc"><li><p>
A forum dedicated to the <code class="literal">FEDERATED</code> storage
engine is available at <a href="http://forums.mysql.com/list.php?105" target="_top">http://forums.mysql.com/list.php?105</a>.
</p></li></ul></div><p class="mnmas-kb"><b>MySQL Enterprise</b>
MySQL Enterprise subscribers will find MySQL Knowledge Base
articles about the <code class="literal">FEDERATED</code> storage engine at
<a href="https://kb.mysql.com/search.php?cat=search&category=272" target="_top">
FEDERATED Storage Engine</a>. Access to the Knowledge Base
collection of articles is one of the advantages of subscribing to
MySQL Enterprise. For more information see
<a href="http://www.mysql.com/products/enterprise/advisors.html" target="_top">http://www.mysql.com/products/enterprise/advisors.html</a>.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="federated-description"></a>13.7.1. Description of the <code class="literal">FEDERATED</code> Storage Engine</h3></div></div></div><p>
When you create a <code class="literal">FEDERATED</code> table, the server
creates a table format file in the database directory. The file
begins with the table name and has an <code class="filename">.frm</code>
extension. No other files are created, because the actual data is
in a remote table. This differs from the way that storage engines
for local tables work.
</p><p>
For local database tables, data files are local. For example, if
you create a <code class="literal">MyISAM</code> table named
<code class="literal">users</code>, the <code class="literal">MyISAM</code> handler
creates a data file named <code class="literal">users.MYD</code>. A handler
for local tables reads, inserts, deletes, and updates data in
local data files, and rows are stored in a format particular to
the handler. To read rows, the handler must parse data into
columns. To write rows, column values must be converted to the row
format used by the handler and written to the local data file.
</p><p>
With the MySQL <code class="literal">FEDERATED</code> storage engine, there
are no local data files for a table (for example, there is no
<code class="filename">.MYD</code> file). Instead, a remote database stores
the data that normally would be in the table. The local server
connects to a remote server, and uses the MySQL client API to
read, delete, update, and insert data in the remote table. For
example, data retrieval is initiated via a <code class="literal">SELECT * FROM
<em class="replaceable"><code>tbl_name</code></em></code> SQL statement.
</p><p>
When a client issues a SQL statement that refers to a
<code class="literal">FEDERATED</code> table, the flow of information
between the local server (where the SQL statement is executed) and
the remote server (where the data is physically stored) is as
follows:
</p><div class="orderedlist"><ol type="1"><li><p>
The storage engine looks through each column that the
<code class="literal">FEDERATED</code> table has and constructs an
appropriate SQL statement that refers to the remote table.
</p></li><li><p>
The statement is sent to the remote server using the MySQL
client API.
</p></li><li><p>
The remote server processes the statement and the the local
server retrieves any result that the statement produces (an
affected-rows count or a result set).
</p></li><li><p>
If the statement produces a result set, each column is
converted to internal storage engine format that the
<code class="literal">FEDERATED</code> engine expects and can use to
display the result to the client that issued the original
statement.
</p></li></ol></div><p>
The local server communicates with the remote server using MySQL
client C API functions. It invokes
<a href="apis.html#mysql-real-query" title="23.2.3.54. mysql_real_query()"><code class="literal">mysql_real_query()</code></a> to send the
statement. To read a result set, it uses
<a href="apis.html#mysql-store-result" title="23.2.3.69. mysql_store_result()"><code class="literal">mysql_store_result()</code></a> and fetches
rows one at a time using
<a href="apis.html#mysql-fetch-row" title="23.2.3.21. mysql_fetch_row()"><code class="literal">mysql_fetch_row()</code></a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="federated-use"></a>13.7.2. How to Use <code class="literal">FEDERATED</code> Tables</h3></div></div></div><p>
The procedure for using <code class="literal">FEDERATED</code> tables is
very simple. Normally, you have two servers running, either both
on the same host or on different hosts. (It is possible for a
<code class="literal">FEDERATED</code> table to use another table that is
managed by the same server, although there is little point in
doing so.)
</p><p>
First, you must have a table on the remote server that you want to
access by using a <code class="literal">FEDERATED</code> table. Suppose that
the remote table is in the <code class="literal">federated</code> database
and is defined like this:
</p><pre class="programlisting">CREATE TABLE test_table (
id INT(20) NOT NULL AUTO_INCREMENT,
name VARCHAR(32) NOT NULL DEFAULT '',
other INT(20) NOT NULL DEFAULT '0',
PRIMARY KEY (id),
INDEX name (name),
INDEX other_key (other)
)
ENGINE=MyISAM
DEFAULT CHARSET=latin1;
</pre><p>
The example uses a <code class="literal">MyISAM</code> table, but the table
could use any storage engine.
</p><p>
Next, create a <code class="literal">FEDERATED</code> table on the local
server for accessing the remote table:
</p><pre class="programlisting">CREATE TABLE federated_table (
id INT(20) NOT NULL AUTO_INCREMENT,
name VARCHAR(32) NOT NULL DEFAULT '',
other INT(20) NOT NULL DEFAULT '0',
PRIMARY KEY (id),
INDEX name (name),
INDEX other_key (other)
)
ENGINE=FEDERATED
DEFAULT CHARSET=latin1
CONNECTION='mysql://fed_user@remote_host:9306/federated/test_table';
</pre><p>
(Before MySQL 5.0.13, use <code class="literal">COMMENT</code> rather than
<code class="literal">CONNECTION</code>.)
</p><p>
The structure of this table must be exactly the same as that of
the remote table, except that the <code class="literal">ENGINE</code> table
option should be <code class="literal">FEDERATED</code> and the
<code class="literal">CONNECTION</code> table option is a connection string
that indicates to the <code class="literal">FEDERATED</code> engine how to
connect to the remote server.
</p><p>
The <code class="literal">FEDERATED</code> engine creates only the
<code class="filename">test_table.frm</code> file in the
<code class="literal">federated</code> database.
</p><p>
The remote host information indicates the remote server to which
your local server connects, and the database and table information
indicates which remote table to use as the data source. In this
example, the remote server is indicated to be running as
<code class="literal">remote_host</code> on port 9306, so there must be a
MySQL server running on the remote host and listening to port
9306.
</p><p>
The general form of the connection string in the
<code class="literal">CONNECTION</code> option is as follows:
</p><pre class="programlisting"><em class="replaceable"><code>scheme</code></em>://<em class="replaceable"><code>user_name</code></em>[:<em class="replaceable"><code>password</code></em>]@<em class="replaceable"><code>host_name</code></em>[:<em class="replaceable"><code>port_num</code></em>]/<em class="replaceable"><code>db_name</code></em>/<em class="replaceable"><code>tbl_name</code></em>
</pre><p>
Only <code class="literal">mysql</code> is supported as the
<em class="replaceable"><code>scheme</code></em> value at this point; the
password and port number are optional.
</p><p>
Sample connection strings:
</p><pre class="programlisting">CONNECTION='mysql://username:password@hostname:port/database/tablename'
CONNECTION='mysql://username@hostname/database/tablename'
CONNECTION='mysql://username:password@hostname/database/tablename'
</pre><p>
The use of <code class="literal">CONNECTION</code> for specifying the
connection string is non-optimal and is likely to change in
future. Keep this in mind for applications that use
<code class="literal">FEDERATED</code> tables. Such applications are likely
to need modification if the format for specifying connection
information changes.
</p><p>
Because any password given in the connection string is stored as
plain text, it can be seen by any user who can use <code class="literal">SHOW
CREATE TABLE</code> or <code class="literal">SHOW TABLE STATUS</code> for
the <code class="literal">FEDERATED</code> table, or query the
<code class="literal">TABLES</code> table in the
<code class="literal">INFORMATION_SCHEMA</code> database.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="federated-limitations"></a>13.7.3. Limitations of the <code class="literal">FEDERATED</code> Storage Engine</h3></div></div></div><p>
The following items indicate features that the
<code class="literal">FEDERATED</code> storage engine does and does not
support:
</p><div class="itemizedlist"><ul type="disc"><li><p>
The remote server must be a MySQL server. Support by
<code class="literal">FEDERATED</code> for other database engines may be
added in the future.
</p></li><li><p>
The remote table that a <code class="literal">FEDERATED</code> table
points to <span class="emphasis"><em>must</em></span> exist before you try to
access the table through the <code class="literal">FEDERATED</code>
table.
</p></li><li><p>
It is possible for one <code class="literal">FEDERATED</code> table to
point to another, but you must be careful not to create a
loop.
</p></li><li><p>
There is no support for transactions.
</p></li><li><p>
A <code class="literal">FEDERATED</code> table does not support indexes
per se. Because access to the table is handled remotely, it is
the remote table that supports the indexes. Care should be
taken when creating a <code class="literal">FEDERATED</code> table since
the index definition from an equivalent
<code class="literal">MyISAM</code> or other table may not be supported.
For example, creating a <code class="literal">FEDERATED</code> table
with an index prefix on <code class="literal">VARCHAR</code>,
<code class="literal">TEXT</code> or <code class="literal">BLOB</code> columns
will fail. The following definition in
<code class="literal">MyISAM</code> is valid:
</p><pre class="programlisting">CREATE TABLE `T1`(`A` VARCHAR(100),UNIQUE KEY(`A`(30))) ENGINE=MYISAM;</pre><p>
The key prefix in this example is incompatible with the
<code class="literal">FEDERATED</code> engine, and the equivalent
statement will fail:
</p><pre class="programlisting">CREATE TABLE `T1`(`A` VARCHAR(100),UNIQUE KEY(`A`(30))) ENGINE=FEDERATED
CONNECTION='MYSQL://127.0.0.1:3306/TEST/T1';</pre><p>
If possible, you should try to separate the column and index
definition when creating tables on both the remote server and
the local server to avoid these index issues.
</p></li><li><p>
Internally, the implementation uses <code class="literal">SELECT</code>,
<code class="literal">INSERT</code>, <code class="literal">UPDATE</code>, and
<code class="literal">DELETE</code>, but not <code class="literal">HANDLER</code>.
</p></li><li><p>
The <code class="literal">FEDERATED</code> storage engine supports
<code class="literal">SELECT</code>, <code class="literal">INSERT</code>,
<code class="literal">UPDATE</code>, <code class="literal">DELETE</code>, and
indexes. It does not support <code class="literal">ALTER TABLE</code>,
or any Data Definition Language statements that directly
affect the structure of the table, other than <code class="literal">DROP
TABLE</code>. The current implementation does not use
prepared statements.
</p></li><li><p>
<code class="literal">FEDERATED</code> accepts <code class="literal">INSERT ... ON
DUPLICATE KEY UPDATE</code> statements, but if a
duplicate-key violation occurs, the statement fails with an
error.
</p></li><li><p>
Performance on a <code class="literal">FEDERATED</code> table when
performing bulk inserts (for example, on a <code class="literal">INSERT
INTO ... SELECT ...</code> statement) is slower than with
other table types because each selected row is treated as an
individual <code class="literal">INSERT</code> statement on the
federated table.
</p></li><li><p>
Before MySQL 5.0.46, for a multiple-row insert into a
<code class="literal">FEDERATED</code> table that refers to a remote
transactional table, if the insert failed for a row due to
constraint failure, the remote table would contain a partial
commit (the rows preceding the failed one) instead of rolling
back the statement completely. This occurred because the rows
were treated as individual inserts.
</p><p>
As of MySQL 5.0.46, <code class="literal">FEDERATED</code> performs
bulk-insert handling such that multiple rows are sent to the
remote table in a batch. This provides a performance
improvement. Also, if the remote table is transactional, it
enables the remote storage engine to perform statement
rollback properly should an error occur. This capability has
the following limitations:
</p><div class="itemizedlist"><ul type="circle"><li><p>
The size of the insert cannot exceed the maximum packet
size between servers. If the insert exceeds this size, it
is broken into multiple packets and the rollback problem
can occur.
</p></li><li><p>
Bulk-insert handling does not occur for <code class="literal">INSERT
... ON DUPLICATE KEY UPDATE</code>.
</p></li></ul></div></li><li><p>
There is no way for the <code class="literal">FEDERATED</code> engine to
know if the remote table has changed. The reason for this is
that this table must work like a data file that would never be
written to by anything other than the database system. The
integrity of the data in the local table could be breached if
there was any change to the remote database.
</p></li><li><p>
Any <code class="literal">DROP TABLE</code> statement issued against a
<code class="literal">FEDERATED</code> table drops only the local table,
not the remote table.
</p></li><li><p>
<code class="literal">FEDERATED</code> tables do not work with the query
cache.
</p></li></ul></div><p>
Some of these limitations may be lifted in future versions of the
<code class="literal">FEDERATED</code> handler.
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="archive-storage-engine"></a>13.8. The <code class="literal">ARCHIVE</code> Storage Engine</h2></div></div></div><a class="indexterm" name="id2924112"></a><a class="indexterm" name="id2924121"></a><p>
The <code class="literal">ARCHIVE</code> storage engine is used for storing
large amounts of data without indexes in a very small footprint.
</p><p>
The <code class="literal">ARCHIVE</code> storage engine is included in MySQL
binary distributions. To enable this storage engine if you build
MySQL from source, invoke <span><strong class="command">configure</strong></span> with the
<code class="option">--with-archive-storage-engine</code> option.
</p><p>
To examine the source for the <code class="literal">ARCHIVE</code> engine,
look in the <code class="filename">sql</code> directory of a MySQL source
distribution.
</p><p>
You can check whether the <code class="literal">ARCHIVE</code> storage engine
is available with this statement:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>SHOW VARIABLES LIKE 'have_archive';</code></strong>
</pre><p>
When you create an <code class="literal">ARCHIVE</code> table, the server
creates a table format file in the database directory. The file
begins with the table name and has an <code class="filename">.frm</code>
extension. The storage engine creates other files, all having names
beginning with the table name. The data and metadata files have
extensions of <code class="filename">.ARZ</code> and
<code class="filename">.ARM</code>, respectively. An
<code class="filename">.ARN</code> file may appear during optimization
operations.
</p><p>
The <code class="literal">ARCHIVE</code> engine supports
<code class="literal">INSERT</code> and <code class="literal">SELECT</code>, but not
<code class="literal">DELETE</code>, <code class="literal">REPLACE</code>, or
<code class="literal">UPDATE</code>. It does support <code class="literal">ORDER
BY</code> operations, <code class="literal">BLOB</code> columns, and
basically all but spatial data types (see
<a href="spatial-extensions.html#mysql-spatial-datatypes" title="17.4.1. MySQL Spatial Data Types">Section 17.4.1, “MySQL Spatial Data Types”</a>). The
<code class="literal">ARCHIVE</code> engine uses row-level locking.
</p><p>
<span class="bold"><strong>Storage:</strong></span> Rows are compressed as
they are inserted. The <code class="literal">ARCHIVE</code> engine uses
<code class="literal">zlib</code> lossless data compression (see
<a href="http://www.zlib.net/" target="_top">http://www.zlib.net/</a>). You can use <code class="literal">OPTIMIZE
TABLE</code> to analyze the table and pack it into a smaller
format (for a reason to use <code class="literal">OPTIMIZE TABLE</code>, see
later in this section). Beginning with MySQL 5.0.15, the engine also
supports <code class="literal">CHECK TABLE</code>. There are several types of
insertions that are used:
</p><div class="itemizedlist"><ul type="disc"><li><p>
An <code class="literal">INSERT</code> statement just pushes rows into a
compression buffer, and that buffer flushes as necessary. The
insertion into the buffer is protected by a lock. A
<code class="literal">SELECT</code> forces a flush to occur, unless the
only insertions that have come in were <code class="literal">INSERT
DELAYED</code> (those flush as necessary). See
<a href="sql-syntax.html#insert-delayed" title="12.2.4.2. INSERT DELAYED Syntax">Section 12.2.4.2, “<code class="literal">INSERT DELAYED</code> Syntax”</a>.
</p></li><li><p>
A bulk insert is visible only after it completes, unless other
inserts occur at the same time, in which case it can be seen
partially. A <code class="literal">SELECT</code> never causes a flush of a
bulk insert unless a normal insert occurs while it is loading.
</p></li></ul></div><p>
<span class="bold"><strong>Retrieval</strong></span>: On retrieval, rows are
uncompressed on demand; there is no row cache. A
<code class="literal">SELECT</code> operation performs a complete table scan:
When a <code class="literal">SELECT</code> occurs, it finds out how many rows
are currently available and reads that number of rows.
<code class="literal">SELECT</code> is performed as a consistent read. Note
that lots of <code class="literal">SELECT</code> statements during insertion
can deteriorate the compression, unless only bulk or delayed inserts
are used. To achieve better compression, you can use
<code class="literal">OPTIMIZE TABLE</code> or <code class="literal">REPAIR
TABLE</code>. The number of rows in <code class="literal">ARCHIVE</code>
tables reported by <code class="literal">SHOW TABLE STATUS</code> is always
accurate. See <a href="sql-syntax.html#optimize-table" title="12.5.2.5. OPTIMIZE TABLE Syntax">Section 12.5.2.5, “<code class="literal">OPTIMIZE TABLE</code> Syntax”</a>,
<a href="sql-syntax.html#repair-table" title="12.5.2.6. REPAIR TABLE Syntax">Section 12.5.2.6, “<code class="literal">REPAIR TABLE</code> Syntax”</a>, and
<a href="sql-syntax.html#show-table-status" title="12.5.4.24. SHOW TABLE STATUS Syntax">Section 12.5.4.24, “<code class="literal">SHOW TABLE STATUS</code> Syntax”</a>.
</p><p>
<span class="bold"><strong>Additional resources</strong></span>
</p><div class="itemizedlist"><ul type="disc"><li><p>
A forum dedicated to the <code class="literal">ARCHIVE</code> storage
engine is available at <a href="http://forums.mysql.com/list.php?112" target="_top">http://forums.mysql.com/list.php?112</a>.
</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="csv-storage-engine"></a>13.9. The <code class="literal">CSV</code> Storage Engine</h2></div></div></div><a class="indexterm" name="id2924539"></a><a class="indexterm" name="id2924548"></a><p>
The <code class="literal">CSV</code> storage engine stores data in text files
using comma-separated values format. It is unavailable on Windows
until MySQL 5.1.
</p><p>
The <code class="literal">CSV</code> storage engine is included in MySQL
binary distributions (except on Windows). To enable this storage
engine if you build MySQL from source, invoke
<span><strong class="command">configure</strong></span> with the
<code class="option">--with-csv-storage-engine</code> option.
</p><p>
To examine the source for the <code class="literal">CSV</code> engine, look in
the <code class="filename">sql/examples</code> directory of a MySQL source
distribution.
</p><p>
When you create a <code class="literal">CSV</code> table, the server creates a
table format file in the database directory. The file begins with
the table name and has an <code class="filename">.frm</code> extension. The
storage engine also creates a data file. Its name begins with the
table name and has a <code class="filename">.CSV</code> extension. The data
file is a plain text file. When you store data into the table, the
storage engine saves it into the data file in comma-separated values
format.
</p><pre class="programlisting">mysql> <strong class="userinput"><code>CREATE TABLE test(i INT, c CHAR(10)) ENGINE = CSV;</code></strong>
Query OK, 0 rows affected (0.12 sec)
mysql> <strong class="userinput"><code>INSERT INTO test VALUES(1,'record one'),(2,'record two');</code></strong>
Query OK, 2 rows affected (0.00 sec)
Records: 2 Duplicates: 0 Warnings: 0
mysql> <strong class="userinput"><code>SELECT * FROM test;</code></strong>
+------+------------+
| i | c |
+------+------------+
| 1 | record one |
| 2 | record two |
+------+------------+
2 rows in set (0.00 sec)
</pre><p>
If you examine the <code class="filename">test.CSV</code> file in the
database directory created by executing the preceding statements,
its contents should look like this:
</p><pre class="programlisting">"1","record one"
"2","record two"
</pre><p>
This format can be read, and even written, by spreadsheet
applications such as Microsoft Excel or StarOffice Calc.
</p><p>
The <code class="literal">CSV</code> storage engine does not support indexing.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="blackhole-storage-engine"></a>13.10. The <code class="literal">BLACKHOLE</code> Storage Engine</h2></div></div></div><a class="indexterm" name="id2924719"></a><a class="indexterm" name="id2924728"></a><p>
The <code class="literal">BLACKHOLE</code> storage engine acts as a
“<span class="quote">black hole</span>” that accepts data but throws it away and
does not store it. Retrievals always return an empty result:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>CREATE TABLE test(i INT, c CHAR(10)) ENGINE = BLACKHOLE;</code></strong>
Query OK, 0 rows affected (0.03 sec)
mysql> <strong class="userinput"><code>INSERT INTO test VALUES(1,'record one'),(2,'record two');</code></strong>
Query OK, 2 rows affected (0.00 sec)
Records: 2 Duplicates: 0 Warnings: 0
mysql> <strong class="userinput"><code>SELECT * FROM test;</code></strong>
Empty set (0.00 sec)
</pre><p>
The <code class="literal">BLACKHOLE</code> storage engine is included in MySQL
binary distributions. To enable this storage engine if you build
MySQL from source, invoke <span><strong class="command">configure</strong></span> with the
<code class="option">--with-blackhole-storage-engine</code> option.
</p><p>
To examine the source for the <code class="literal">BLACKHOLE</code> engine,
look in the <code class="filename">sql</code> directory of a MySQL source
distribution.
</p><p>
When you create a <code class="literal">BLACKHOLE</code> table, the server
creates a table format file in the database directory. The file
begins with the table name and has an <code class="filename">.frm</code>
extension. There are no other files associated with the table.
</p><p>
The <code class="literal">BLACKHOLE</code> storage engine supports all kinds
of indexes. That is, you can include index declarations in the table
definition.
</p><p>
You can check whether the <code class="literal">BLACKHOLE</code> storage
engine is available with this statement:
</p><pre class="programlisting">mysql> <strong class="userinput"><code>SHOW VARIABLES LIKE 'have_blackhole_engine';</code></strong>
</pre><p>
Inserts into a <code class="literal">BLACKHOLE</code> table do not store any
data, but if the binary log is enabled, the SQL statements are
logged (and replicated to slave servers). This can be useful as a
repeater or filter mechanism. For example, suppose that your
application requires slave-side filtering rules, but transferring
all binary log data to the slave first results in too much traffic.
In such a case, it is possible to set up on the master host a
“<span class="quote">dummy</span>” slave process whose default storage engine is
<code class="literal">BLACKHOLE</code>, depicted as follows:
</p><div class="mediaobject"><img src="images/blackhole-1.png" alt="Replication using BLACKHOLE
for filtering"></div><p>
The master writes to its binary log. The “<span class="quote">dummy</span>”
<span><strong class="command">mysqld</strong></span> process acts as a slave, applying the
desired combination of <code class="literal">replicate-do-*</code> and
<code class="literal">replicate-ignore-*</code> rules, and writes a new,
filtered binary log of its own. (See
<a href="replication.html#replication-options" title="15.1.2. Replication Startup Options and Variables">Section 15.1.2, “Replication Startup Options and Variables”</a>.) This filtered log is
provided to the slave.
</p><p>
The dummy process does not actually store any data, so there is
little processing overhead incurred by running the additional
<span><strong class="command">mysqld</strong></span> process on the replication master host.
This type of setup can be repeated with additional replication
slaves.
</p><p>
<code class="literal">INSERT</code> triggers for <code class="literal">BLACKHOLE</code>
tables work as expected. However, because the
<code class="literal">BLACKHOLE</code> table does not actually store any data,
<code class="literal">UPDATE</code> and <code class="literal">DELETE</code> triggers are
not activated: The <code class="literal">FOR EACH ROW</code> clause in the
trigger definition does not apply because there are no rows.
</p><p>
Other possible uses for the <code class="literal">BLACKHOLE</code> storage
engine include:
</p><div class="itemizedlist"><ul type="disc"><li><p>
Verification of dump file syntax.
</p></li><li><p>
Measurement of the overhead from binary logging, by comparing
performance using <code class="literal">BLACKHOLE</code> with and without
binary logging enabled.
</p></li><li><p>
<code class="literal">BLACKHOLE</code> is essentially a
“<span class="quote">no-op</span>” storage engine, so it could be used for
finding performance bottlenecks not related to the storage
engine itself.
</p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-syntax.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ha-overview.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 12. SQL Statement Syntax </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 14. High Availability, Scalability, and DRBD</td></tr></table></div></body></html>
distrib
>
Mandriva
>
2008.1
>
x86_64
>
media
>
main-testing
>
by-pkgid
>
b1e2421f2416edfc24c5845fbc1c5a2e
>
files
>
113
