Table of Contents
This chapter describes the syntax for the SQL statements supported in MySQL versions 4.1 and earlier.
ALTER DATABASE [db_name
]alter_specification
...alter_specification
: [DEFAULT] CHARACTER SET [=]charset_name
| [DEFAULT] COLLATE [=]collation_name
ALTER DATABASE
enables you to
change the overall characteristics of a database. These
characteristics are stored in the db.opt
file
in the database directory. To use ALTER
DATABASE
, you need the
ALTER
privilege on the database.
The CHARACTER SET
clause changes the default
database character set. The COLLATE
clause
changes the default database collation. Section 9.1, “Character Set Support”,
discusses character set and collation names.
Beginning with MySQL 4.1.0, you can see what character sets and
collations are available using, respectively, the
SHOW CHARACTER SET
and
SHOW COLLATION
statements. See
Section 12.4.5.3, “SHOW CHARACTER SET Syntax”, and
Section 12.4.5.4, “SHOW COLLATION Syntax”, for more information.
ALTER DATABASE
was added in MySQL
4.1.1. Beginning with MySQL 4.1.8, the database name can be
omitted, in which case the statement applies to the default
database.
ALTER [IGNORE] TABLEtbl_name
alter_specification
[,alter_specification
] ...alter_specification
:table_options
| ADD [COLUMN]col_name
column_definition
[FIRST | AFTERcol_name
] | ADD [COLUMN] (col_name
column_definition
,...) | ADD {INDEX|KEY} [index_name
] [index_type
] (index_col_name
,...) | ADD [CONSTRAINT [symbol
]] PRIMARY KEY [index_type
] (index_col_name
,...) | ADD [CONSTRAINT [symbol
]] UNIQUE [INDEX|KEY] [index_name
] [index_type
] (index_col_name
,...) | ADD [FULLTEXT|SPATIAL] [INDEX|KEY] [index_name
] (index_col_name
,...) | ADD [CONSTRAINT [symbol
]] FOREIGN KEY [index_name
] (index_col_name
,...)reference_definition
| ALTER [COLUMN]col_name
{SET DEFAULTliteral
| DROP DEFAULT} | CHANGE [COLUMN]old_col_name
new_col_name
column_definition
[FIRST|AFTERcol_name
] | MODIFY [COLUMN]col_name
column_definition
[FIRST | AFTERcol_name
] | DROP [COLUMN]col_name
| DROP PRIMARY KEY | DROP {INDEX|KEY}index_name
| DROP FOREIGN KEYfk_symbol
| DISABLE KEYS | ENABLE KEYS | RENAME [TO]new_tbl_name
| ORDER BYcol_name
[,col_name
] ... | CONVERT TO CHARACTER SETcharset_name
[COLLATEcollation_name
] | [DEFAULT] CHARACTER SET [=]charset_name
[COLLATE [=]collation_name
] | DISCARD TABLESPACE | IMPORT TABLESPACEindex_col_name
:col_name
[(length
)] [ASC | DESC]index_type
: USING {BTREE | HASH}table_options
:table_option
[[,]table_option
] ... (seeCREATE TABLE
options)
ALTER TABLE
enables you to change
the structure of an existing table. For example, you can add or
delete columns, create or destroy indexes, change the type of
existing columns, or rename columns or the table itself. You can
also change the comment for the table and type of the table.
The syntax for many of the permissible alterations is similar to
clauses of the CREATE TABLE
statement. See Section 12.1.5, “CREATE TABLE Syntax”, for more
information.
Some operations may result in warnings if attempted on a table for
which the storage engine does not support the operation. In MySQL
4.1 and up, these warnings can be displayed with
SHOW WARNINGS
. See
Section 12.4.5.26, “SHOW WARNINGS Syntax”.
If you use ALTER TABLE
to change a
column specification but DESCRIBE
indicates that your
column was not changed, it is possible that MySQL ignored your
modification for one of the reasons described in
Section 12.1.5.2, “Silent Column Specification Changes”. For example, if you try
to change a tbl_name
VARCHAR
column to
CHAR
, MySQL still uses
VARCHAR
if the table contains other
variable-length columns.
In most cases, ALTER TABLE
works by
making a temporary copy of the original table. The alteration is
performed on the copy, and then the original table is deleted and
the new one is renamed. While ALTER
TABLE
is executing, the original table is readable by
other sessions. Updates and writes to the table are stalled until
the new table is ready, and then are automatically redirected to
the new table without any failed updates. The temporary table is
created in the database directory of the new table. This can be
different from the database directory of the original table if
ALTER TABLE
is renaming the table
to a different database.
If you use ALTER TABLE
without any
other options, MySQL simply renames any files that correspond to
the table tbl_name
RENAME TO
new_tbl_name
tbl_name
. (You can also use
the RENAME TABLE
statement to
rename tables. See Section 12.1.9, “RENAME TABLE Syntax”.) Any privileges
granted specifically for the renamed table are not migrated to the
new name. They must be changed manually.
If you use any option to ALTER
TABLE
other than RENAME
, MySQL always
creates a temporary table, even if the data wouldn't strictly need
to be copied (such as when you change the name of a column). For
MyISAM
tables, you can speed up the index
re-creation operation (which is the slowest part of the alteration
process) by setting the
myisam_sort_buffer_size
system
variable to a high value.
For information on troubleshooting ALTER
TABLE
, see Section B.5.7.1, “Problems with ALTER TABLE”.
To use ALTER TABLE
, you need
ALTER
,
INSERT
, and
CREATE
privileges for the
table.
IGNORE
is a MySQL extension to standard
SQL. It controls how ALTER
TABLE
works if there are duplicates on unique keys
in the new table or if warnings occur when strict mode is
enabled. If IGNORE
is not specified, the
copy is aborted and rolled back if duplicate-key errors occur.
If IGNORE
is specified, only the first row
is used of rows with duplicates on a unique key, The other
conflicting rows are deleted. Incorrect values are truncated
to the closest matching acceptable value.
table_option
signifies a table
option of the kind that can be used in the
CREATE TABLE
statement, such as
ENGINE
, AUTO_INCREMENT
,
or AVG_ROW_LENGTH
.
(Section 12.1.5, “CREATE TABLE Syntax”, lists all table options.)
However, ALTER TABLE
ignores
the DATA DIRECTORY
and INDEX
DIRECTORY
table options.
For example, to convert a table to be an
InnoDB
table, use this statement:
ALTER TABLE t1 ENGINE = InnoDB;
To change the value of the AUTO_INCREMENT
counter to be used for new rows, do this:
ALTER TABLE t2 AUTO_INCREMENT = value
;
You cannot reset the counter to a value less than or equal to
any that have already been used. For
MyISAM
, if the value is less than or equal
to the maximum value currently in the
AUTO_INCREMENT
column, the value is reset
to the current maximum plus one. For
InnoDB
, you can use ALTER TABLE
... AUTO_INCREMENT =
as of MySQL 4.1.12,
but if the value is less than the current maximum
value in the column, no error occurs and the current sequence
value is not changed.
value
You can issue multiple ADD
,
ALTER
, DROP
, and
CHANGE
clauses in a single
ALTER TABLE
statement,
separated by commas. This is a MySQL extension to standard
SQL, which permits only one of each clause per
ALTER TABLE
statement. For
example, to drop multiple columns in a single statement, do
this:
ALTER TABLE t2 DROP COLUMN c, DROP COLUMN d;
CHANGE
,
col_name
DROP
,
and col_name
DROP INDEX
are MySQL extensions to
standard SQL.
MODIFY
is an Oracle extension to
ALTER TABLE
.
The word COLUMN
is optional and can be
omitted.
column_definition
clauses use the
same syntax for ADD
and
CHANGE
as for CREATE
TABLE
. See Section 12.1.5, “CREATE TABLE Syntax”.
You can rename a column using a CHANGE
clause.
To do so, specify the old and new column names and the
definition that the column currently has. For example, to
rename an old_col_name
new_col_name
column_definition
INTEGER
column from
a
to b
, you can do this:
ALTER TABLE t1 CHANGE a b INTEGER;
If you want to change a column's type but not the name,
CHANGE
syntax still requires an old and new
column name, even if they are the same. For example:
ALTER TABLE t1 CHANGE b b BIGINT NOT NULL;
However, as of MySQL 3.22.16a, you can also use
MODIFY
to change a column's type without
renaming it:
ALTER TABLE t1 MODIFY b BIGINT NOT NULL;
When you use CHANGE
or
MODIFY
,
column_definition
must include the
data type and all attributes that should apply to the new
column, other than index attributes such as PRIMARY
KEY
or UNIQUE
. Attributes present
in the original definition but not specified for the new
definition are not carried forward. Suppose that a column
col1
is defined as INT UNSIGNED
DEFAULT 1 COMMENT 'my column'
and you modify the
column as follows:
ALTER TABLE t1 MODIFY col1 BIGINT;
The resulting column will be defined as
BIGINT
, but will not include the attributes
UNSIGNED DEFAULT 1 COMMENT 'my column'
. To
retain them, the statement should be:
ALTER TABLE t1 MODIFY col1 BIGINT UNSIGNED DEFAULT 1 COMMENT 'my column';
When you change a data type using CHANGE
or
MODIFY
, MySQL tries to convert existing
column values to the new type as well as possible.
This conversion may result in alteration of data. For example, if you shorten a string column, values may be truncated.
In MySQL 3.22 or later, to add a column at a specific position
within a table row, use FIRST
or
AFTER
.
The default is to add the column last. From MySQL 4.0.1 on,
you can also use col_name
FIRST
and
AFTER
in CHANGE
or
MODIFY
operations to reorder columns within
a table.
ALTER ... SET DEFAULT
or ALTER ...
DROP DEFAULT
specify a new default value for a
column or remove the old default value, respectively. If the
old default is removed and the column can be
NULL
, the new default is
NULL
. If the column cannot be
NULL
, MySQL assigns a default value as
described in Section 10.1.4, “Data Type Default Values”.
DROP INDEX
removes an index.
This is a MySQL extension to standard SQL. See
Section 12.1.7, “DROP INDEX Syntax”. If you are unsure of the index
name, use SHOW INDEX FROM
.
tbl_name
If columns are dropped from a table, the columns are also
removed from any index of which they are a part. If all
columns that make up an index are dropped, the index is
dropped as well. If you use CHANGE
or
MODIFY
to shorten a column for which an
index exists on the column, and the resulting column length is
less than the index length, MySQL shortens the index
automatically.
If a table contains only one column, the column cannot be
dropped. If what you intend is to remove the table, use
DROP TABLE
instead.
DROP PRIMARY KEY
drops the primary key. If
there is no primary key, an error occurs. (Prior to MySQL
4.1.2, if no primary key exists, DROP PRIMARY
KEY
drops the first UNIQUE
index
in the table. MySQL marks the first UNIQUE
key as the PRIMARY KEY
if no
PRIMARY KEY
was specified explicitly.)
If you add a UNIQUE INDEX
or
PRIMARY KEY
to a table, it is stored before
any nonunique index so that MySQL can detect duplicate keys as
early as possible.
From MySQL 4.1.0 on, some storage engines permit you to
specify an index type when creating an index. The syntax for
the index_type
specifier is
USING
.
For details about type_name
USING
, see
Section 12.1.4, “CREATE INDEX Syntax”.
ORDER BY
enables you to create the new
table with the rows in a specific order. Note that the table
does not remain in this order after inserts and deletes. This
option is useful primarily when you know that you are mostly
to query the rows in a certain order most of the time. By
using this option after major changes to the table, you might
be able to get higher performance. In some cases, it might
make sorting easier for MySQL if the table is in order by the
column that you want to order it by later.
ORDER BY
syntax permits one or more column
names to be specified for sorting, each of which optionally
can be followed by ASC
or
DESC
to indicate ascending or descending
sort order, respectively. The default is ascending order. Only
column names are permitted as sort criteria; arbitrary
expressions are not permitted.
ORDER BY
does not make sense for
InnoDB
tables that contain a user-defined
clustered index (PRIMARY KEY
or
NOT NULL UNIQUE
index).
InnoDB
always orders table rows according
to such an index if one is present. The same is true for
BDB
tables that contain a user-defined
PRIMARY KEY
.
If you use ALTER TABLE
on a
MyISAM
table, all nonunique indexes are
created in a separate batch (as for
REPAIR TABLE
). This should make
ALTER TABLE
much faster when
you have many indexes.
As of MySQL 4.0, this feature can be activated explicitly for
a MyISAM
table. ALTER TABLE ...
DISABLE KEYS
tells MySQL to stop updating nonunique
indexes. ALTER TABLE ... ENABLE KEYS
then
should be used to re-create missing indexes. MySQL does this
with a special algorithm that is much faster than inserting
keys one by one, so disabling keys before performing bulk
insert operations should give a considerable speedup. Using
ALTER TABLE ... DISABLE KEYS
requires the
INDEX
privilege in addition to
the privileges mentioned earlier.
While the nonunique indexes are disabled, they are ignored for
statements such as SELECT
and
EXPLAIN
that otherwise would
use them.
If ALTER TABLE
for an
InnoDB
table results in changes to column
values (for example, because a column is truncated),
InnoDB
's FOREIGN KEY
constraint checks do not notice possible violations caused by
changing the values.
The FOREIGN KEY
and
REFERENCES
clauses are supported by the
InnoDB
storage engine, which implements
ADD [CONSTRAINT [
. See
Section 13.2.5.4, “FOREIGN KEY Constraints”. For other
storage engines, the clauses are parsed but ignored. The
symbol
]]
FOREIGN KEY (...) REFERENCES ... (...)CHECK
clause is parsed but ignored by all
storage engines. See Section 12.1.5, “CREATE TABLE Syntax”. The
reason for accepting but ignoring syntax clauses is for
compatibility, to make it easier to port code from other SQL
servers, and to run applications that create tables with
references. See Section 1.9.5, “MySQL Differences from Standard SQL”.
The inline REFERENCES
specifications
where the references are defined as part of the column
specification are silently ignored by
InnoDB
. InnoDB only accepts
REFERENCES
clauses defined as part of a
separate FOREIGN KEY
specification.
Starting from MySQL 4.0.13, InnoDB
supports
the use of ALTER TABLE
to drop
foreign keys:
ALTER TABLEtbl_name
DROP FOREIGN KEYfk_symbol
;
For more information, see Section 13.2.5.4, “FOREIGN KEY Constraints”.
You cannot add a foreign key and drop a foreign key in
separate clauses of a single ALTER
TABLE
statement. You must use separate statements.
For an InnoDB
table that is created with
its own tablespace in an .ibd
file, that
file can be discarded and imported. To discard the
.ibd
file, use this statement:
ALTER TABLE tbl_name
DISCARD TABLESPACE;
This deletes the current .ibd
file, so be
sure that you have a backup first. Attempting to access the
table while the tablespace file is discarded results in an
error.
To import the backup .ibd
file back into
the table, copy it into the database directory, and then issue
this statement:
ALTER TABLE tbl_name
IMPORT TABLESPACE;
The tablespace file must have been created on the server into which it is imported later.
Pending INSERT DELAYED
statements are lost if a table is write locked and
ALTER TABLE
is used to modify
the table structure.
From MySQL 4.1.2 on, if you want to change the table default
character set and all character columns
(CHAR
,
VARCHAR
,
TEXT
) to a new character set,
use a statement like this:
ALTER TABLEtbl_name
CONVERT TO CHARACTER SETcharset_name
;
This is useful, for example, after upgrading from MySQL 4.0.x to 4.1.x. See Section 9.1.11, “Upgrading Character Sets from MySQL 4.0”.
If you specify CONVERT TO CHARACTER SET
binary
, the CHAR
,
VARCHAR
, and
TEXT
columns are converted to
their corresponding binary string types
(BINARY
,
VARBINARY
,
BLOB
). This means that the
columns no longer will have a character set and a subsequent
CONVERT TO
operation will not apply to
them.
If charset_name
is
DEFAULT
, the database character set is
used.
The CONVERT TO
operation converts column
values between the character sets. This is
not what you want if you have a column
in one character set (like latin1
) but
the stored values actually use some other, incompatible
character set (like utf8
). In this case,
you have to do the following for each such column:
ALTER TABLE t1 CHANGE c1 c1 BLOB; ALTER TABLE t1 CHANGE c1 c1 TEXT CHARACTER SET utf8;
The reason this works is that there is no conversion when
you convert to or from BLOB
columns.
To change only the default character set for a table, use this statement:
ALTER TABLEtbl_name
DEFAULT CHARACTER SETcharset_name
;
The word DEFAULT
is optional. The default
character set is the character set that is used if you do not
specify the character set for columns that you add to a table
later (for example, with ALTER TABLE ... ADD
column
).
From MySQL 4.1.2 and up, ALTER TABLE ... DEFAULT
CHARACTER SET
and ALTER TABLE ...
CHARACTER SET
are equivalent and change only the
default table character set. In MySQL 4.1 releases before
4.1.2, ALTER TABLE ... DEFAULT CHARACTER
SET
changes the default character set, but
ALTER TABLE ... CHARACTER SET
(without
DEFAULT
) changes the default character
set and also converts all columns to the new
character set.
With the mysql_info()
C API
function, you can find out how many rows were copied, and (when
IGNORE
is used) how many rows were deleted due
to duplication of unique key values. See
Section 17.6.6.33, “mysql_info()”.
Begin with a table t1
that is created as shown
here:
CREATE TABLE t1 (a INTEGER,b CHAR(10));
To rename the table from t1
to
t2
:
ALTER TABLE t1 RENAME t2;
To change column a
from
INTEGER
to TINYINT NOT
NULL
(leaving the name the same), and to change column
b
from CHAR(10)
to
CHAR(20)
as well as renaming it from
b
to c
:
ALTER TABLE t2 MODIFY a TINYINT NOT NULL, CHANGE b c CHAR(20);
To add a new TIMESTAMP
column named
d
:
ALTER TABLE t2 ADD d TIMESTAMP;
To add an index on column d
and a
UNIQUE
index on column a
:
ALTER TABLE t2 ADD INDEX (d), ADD UNIQUE (a);
To remove column c
:
ALTER TABLE t2 DROP COLUMN c;
To add a new AUTO_INCREMENT
integer column
named c
:
ALTER TABLE t2 ADD c INT UNSIGNED NOT NULL AUTO_INCREMENT, ADD PRIMARY KEY (c);
Note that we indexed c
(as a PRIMARY
KEY
) because AUTO_INCREMENT
columns
must be indexed, and also that we declare c
as
NOT NULL
because primary key columns cannot be
NULL
.
When you add an AUTO_INCREMENT
column, column
values are filled in with sequence numbers automatically. For
MyISAM
tables, you can set the first sequence
number by executing SET
INSERT_ID=
before
value
ALTER TABLE
or by using the
AUTO_INCREMENT=
table option. See Section 5.1.3, “Server System Variables”.
value
With MyISAM
tables, if you do not change the
AUTO_INCREMENT
column, the sequence number is
not affected. If you drop an AUTO_INCREMENT
column and then add another AUTO_INCREMENT
column, the numbers are resequenced beginning with 1.
When replication is used, adding an
AUTO_INCREMENT
column to a table might not
produce the same ordering of the rows on the slave and the master.
This occurs because the order in which the rows are numbered
depends on the specific storage engine used for the table and the
order in which the rows were inserted. If it is important to have
the same order on the master and slave, the rows must be ordered
before assigning an AUTO_INCREMENT
number.
Assuming that you want to add an AUTO_INCREMENT
column to the table t1
, the following
statements produce a new table t2
identical to
t1
but with an
AUTO_INCREMENT
column:
CREATE TABLE t2 (id INT AUTO_INCREMENT PRIMARY KEY) SELECT * FROM t1 ORDER BY col1, col2;
This assumes that the table t1
has columns
col1
and col2
.
This set of statements will also produce a new table
t2
identical to t1
, with the
addition of an AUTO_INCREMENT
column:
CREATE TABLE t2 LIKE t1; ALTER TABLE t2 ADD id INT AUTO_INCREMENT PRIMARY KEY; INSERT INTO t2 SELECT * FROM t1 ORDER BY col1, col2;
To guarantee the same ordering on both master and slave,
all columns of t1
must
be referenced in the ORDER BY
clause.
Regardless of the method used to create and populate the copy
having the AUTO_INCREMENT
column, the final
step is to drop the original table and then rename the copy:
DROP t1; ALTER TABLE t2 RENAME t1;
CREATE DATABASE [IF NOT EXISTS]db_name
[create_specification
] ...create_specification
: [DEFAULT] CHARACTER SET [=]charset_name
| [DEFAULT] COLLATE [=]collation_name
CREATE DATABASE
creates a database
with the given name. To use this statement, you need the
CREATE
privilege for the database.
An error occurs if the database exists and you did not specify
IF NOT EXISTS
.
As of MySQL 4.1.1, create_specification
options specify database characteristics. Database characteristics
are stored in the db.opt
file in the database
directory. The CHARACTER SET
clause specifies
the default database character set. The COLLATE
clause specifies the default database collation.
Section 9.1, “Character Set Support”, discusses character set and collation
names.
A database in MySQL is implemented as a directory containing files
that correspond to tables in the database. Because there are no
tables in a database when it is initially created, the
CREATE DATABASE
statement only
creates a directory under the MySQL data directory (and the
db.opt
file, for MySQL 4.1.1 and up). Rules
for permissible database names are given in
Section 8.2, “Database, Table, Index, Column, and Alias Names”.
If you manually create a directory under the data directory (for
example, with mkdir), the server considers it a
database directory and it shows up in the output of
SHOW DATABASES
.
You can also use the mysqladmin program to create databases. See Section 4.5.2, “mysqladmin — Client for Administering a MySQL Server”.
CREATE [UNIQUE|FULLTEXT|SPATIAL] INDEXindex_name
[index_type
] ONtbl_name
(index_col_name
,...)index_col_name
:col_name
[(length
)] [ASC | DESC]index_type
: USING {BTREE | HASH}
In MySQL 3.22 or later, CREATE
INDEX
is mapped to an ALTER
TABLE
statement to create indexes. See
Section 12.1.2, “ALTER TABLE Syntax”. The CREATE
INDEX
statement does not do anything prior to MySQL
3.22. For more information about indexes, see
Section 7.4.3, “How MySQL Uses Indexes”.
Normally, you create all indexes on a table at the time the table
itself is created with CREATE
TABLE
. See Section 12.1.5, “CREATE TABLE Syntax”.
CREATE INDEX
enables you to add
indexes to existing tables.
A column list of the form (col1,col2,...)
creates a multiple-column index. Index values are formed by
concatenating the values of the given columns.
Indexes can be created that use only the leading part of column
values, using
syntax to specify an index prefix length:
col_name
(length
)
Prefixes can be specified for
CHAR
,
VARCHAR
,
BINARY
, and
VARBINARY
columns.
BLOB
and
TEXT
columns also can be
indexed, but a prefix length must be
given.
Prefix lengths are given in characters for nonbinary string
types and in bytes for binary string types. That is, index
entries consist of the first length
characters of each column value for
CHAR
,
VARCHAR
, and
TEXT
columns, and the first
length
bytes of each column value
for BINARY
,
VARBINARY
, and
BLOB
columns.
For spatial columns, prefix values can be given as described later in this section.
The statement shown here creates an index using the first 10
characters of the name
column:
CREATE INDEX part_of_name ON customer (name(10));
If names in the column usually differ in the first 10 characters,
this index should not be much slower than an index created from
the entire name
column. Also, using column
prefixes for indexes can make the index file much smaller, which
could save a lot of disk space and might also speed up
INSERT
operations.
Prefix support and lengths of prefixes (where supported) are
storage engine dependent. For example, a prefix can be up to 1000
bytes long for MyISAM
tables, and 767 bytes for
InnoDB
tables. The
NDBCLUSTER
storage engine does not support
prefixes (see
Section 15.1.4.6, “Unsupported or Missing Features in MySQL Cluster”).
Prior to MySQL 4.1.2, the limit is 255 bytes for all storage engines supporting prefixes.
Prefix limits are measured in bytes, whereas the prefix length
in CREATE INDEX
statements is
interpreted as number of characters for nonbinary data types
(CHAR
,
VARCHAR
,
TEXT
). Take this into account
when specifying a prefix length for a column that uses a
multi-byte character set.
A UNIQUE
index creates a constraint such that
all values in the index must be distinct. An error occurs if you
try to add a new row with a key value that matches an existing
row. This constraint does not apply to NULL
values except for the BDB
storage engine. For
other engines, a UNIQUE
index permits multiple
NULL
values for columns that can contain
NULL
.
FULLTEXT
indexes are supported only for
MyISAM
tables and can include only
CHAR
,
VARCHAR
, and
TEXT
columns. Indexing always
happens over the entire column; column prefix indexing is not
supported and any prefix length is ignored if specified. See
Section 11.9, “Full-Text Search Functions”, for details of operation.
FULLTEXT
indexes are available in MySQL 3.23.23
or later.
The MyISAM
storage engine supports spatial
columns such as (POINT
and
GEOMETRY
.
(Chapter 16, Spatial Extensions, describes the spatial data
types.) Spatial and nonspatial indexes are available according to
the following rules.
Characteristics of spatial indexes (created using SPATIAL
INDEX
):
Available only for MyISAM
tables in MySQL
4.1 or later.
Indexed columns must be NOT NULL
.
The full width of each column is indexed by default, but
column prefix lengths are permitted. However, as of MySQL
5.0.40, the length is not displayed in
SHOW CREATE TABLE
output.
mysqldump uses that statement. As of that
version, if a table with SPATIAL
indexes
containing prefixed columns is dumped and reloaded, the index
is created with no prefixes. (The full column width of each
column is indexed.)
Characteristics of nonspatial indexes (created with
INDEX
, UNIQUE
, or
PRIMARY KEY
):
Permitted for MyISAM
tables.
Columns can be NULL
unless the index is a
primary key.
For each spatial column in a non-SPATIAL
index except POINT
columns, a column prefix
length must be specified. (This is the same requirement as for
indexed BLOB
columns.) The
prefix length is given in bytes.
The index type for a non-SPATIAL
index
depends on the storage engine. Currently, B-tree is used.
You can add an index on a column that can have
NULL
values only if you are using MySQL 3.23.2
or newer and are using the MyISAM
,
InnoDB
, or BDB
storage
engine. This is also true for MEMORY
tables as
of MySQL 4.0.2. You can only add an index on a
BLOB
or
TEXT
column if you are using MySQL
3.23.2 or newer and are using the MyISAM
or
BDB
storage engine, or MySQL 4.0.14 or newer
and the InnoDB
storage engine.
An index_col_name
specification can end
with ASC
or DESC
. These
keywords are permitted for future extensions for specifying
ascending or descending index value storage. Currently, they are
parsed but ignored; index values are always stored in ascending
order.
From MySQL 4.1.0 on, some storage engines permit you to specify an index type when creating an index. The permissible index type values supported by different storage engines are shown in the following table. Where multiple index types are listed, the first one is the default when no index type specifier is given.
Storage Engine | Permissible Index Types |
---|---|
MyISAM | BTREE |
InnoDB | BTREE |
MEMORY /HEAP | HASH , BTREE |
NDB (MySQL 4.1.3 and later) | HASH , BTREE (see note in text) |
Example:
CREATE TABLE lookup (id INT) ENGINE = MEMORY; CREATE INDEX id_index USING BTREE ON lookup (id);
BTREE
indexes are implemented by the
NDBCLUSTER
storage engine as T-tree
indexes.
For indexes on NDBCLUSTER
table
columns, the USING
clause can be specified
only for a unique index or primary key. In such cases, the
USING HASH
clause prevents the creation of an
implicit ordered index. Without USING HASH
, a
statement defining a unique index or primary key automatically
results in the creation of a HASH
index in
addition to the ordered index, both of which index the same set
of columns.
The index_type
clause cannot be used
together with SPATIAL INDEX
.
If you specify an index type that is not legal for a given storage
engine, but there is another index type available that the engine
can use without affecting query results, the engine uses the
available type. The parser recognizes RTREE
as
a type name, but currently this cannot be specfied for any storage
engine.
TYPE
is
recognized as a synonym for type_name
USING
. However,
type_name
USING
is the preferred form.
CREATE [TEMPORARY] TABLE [IF NOT EXISTS]tbl_name
(create_definition
,...) [table_options
]
Or:
CREATE [TEMPORARY] TABLE [IF NOT EXISTS]tbl_name
[(create_definition
,...)] [table_options
]select_statement
Or:
CREATE [TEMPORARY] TABLE [IF NOT EXISTS]tbl_name
{ LIKEold_tbl_name
| (LIKEold_tbl_name
) }
create_definition
:col_name
column_definition
| [CONSTRAINT [symbol
]] PRIMARY KEY [index_type
] (index_col_name
,...) | {INDEX|KEY} [index_name
] [index_type
] (index_col_name
,...) | [CONSTRAINT [symbol
]] UNIQUE [INDEX|KEY] [index_name
] [index_type
] (index_col_name
,...) | {FULLTEXT|SPATIAL} [INDEX|KEY] [index_name
] (index_col_name
,...) | [CONSTRAINT [symbol
]] FOREIGN KEY [index_name
] (index_col_name
,...)reference_definition
| CHECK (expr
)column_definition
:data_type
[NOT NULL | NULL] [DEFAULTdefault_value
] [AUTO_INCREMENT] [UNIQUE [KEY] | [PRIMARY] KEY] [COMMENT 'string
'] [reference_definition
]data_type
: TINYINT[(length
)] [UNSIGNED] [ZEROFILL] | SMALLINT[(length
)] [UNSIGNED] [ZEROFILL] | MEDIUMINT[(length
)] [UNSIGNED] [ZEROFILL] | INT[(length
)] [UNSIGNED] [ZEROFILL] | INTEGER[(length
)] [UNSIGNED] [ZEROFILL] | BIGINT[(length
)] [UNSIGNED] [ZEROFILL] | REAL[(length
,decimals
)] [UNSIGNED] [ZEROFILL] | DOUBLE[(length
,decimals
)] [UNSIGNED] [ZEROFILL] | FLOAT[(length
,decimals
)] [UNSIGNED] [ZEROFILL] | DECIMAL[(length
[,decimals
])] [UNSIGNED] [ZEROFILL] | NUMERIC[(length
[,decimals
])] [UNSIGNED] [ZEROFILL] | DATE | TIME | TIMESTAMP | DATETIME | YEAR | CHAR[(length
)] [CHARACTER SETcharset_name
] [COLLATEcollation_name
] | VARCHAR(length
) [CHARACTER SETcharset_name
] [COLLATEcollation_name
] | BINARY[(length
)] | VARBINARY(length
) | TINYBLOB | BLOB | MEDIUMBLOB | LONGBLOB | TINYTEXT [BINARY] [CHARACTER SETcharset_name
] [COLLATEcollation_name
] | TEXT [BINARY] [CHARACTER SETcharset_name
] [COLLATEcollation_name
] | MEDIUMTEXT [BINARY] [CHARACTER SETcharset_name
] [COLLATEcollation_name
] | LONGTEXT [BINARY] [CHARACTER SETcharset_name
] [COLLATEcollation_name
] | ENUM(value1
,value2
,value3
,...) [CHARACTER SETcharset_name
] [COLLATEcollation_name
] | SET(value1
,value2
,value3
,...) [CHARACTER SETcharset_name
] [COLLATEcollation_name
] |spatial_type
index_col_name
:col_name
[(length
)] [ASC | DESC]index_type
: USING {BTREE | HASH}reference_definition
: REFERENCEStbl_name
(index_col_name
,...) [MATCH FULL | MATCH PARTIAL | MATCH SIMPLE] [ON DELETEreference_option
] [ON UPDATEreference_option
]reference_option
: RESTRICT | CASCADE | SET NULL | NO ACTIONtable_options
:table_option
[[,]table_option
] ...table_option
: {ENGINE|TYPE} =engine_name
| AUTO_INCREMENT =value
| AVG_ROW_LENGTH =value
| [DEFAULT] CHARACTER SET =charset_name
| CHECKSUM = {0 | 1} | [DEFAULT] COLLATE =collation_name
| COMMENT = 'string
' | DATA DIRECTORY = 'absolute path to directory
' | DELAY_KEY_WRITE = {0 | 1} | INDEX DIRECTORY = 'absolute path to directory
' | INSERT_METHOD = { NO | FIRST | LAST } | MAX_ROWS =value
| MIN_ROWS =value
| PACK_KEYS = {0 | 1 | DEFAULT} | PASSWORD = 'string
' | RAID_TYPE = { 1 | STRIPED | RAID0 } RAID_CHUNKS =value
RAID_CHUNKSIZE =value
| ROW_FORMAT = {DEFAULT|DYNAMIC|FIXED|COMPRESSED} | UNION = (tbl_name
[,tbl_name
]...)select_statement:
[IGNORE | REPLACE] [AS] SELECT ... (Some legal select statement
)
CREATE TABLE
creates a table with
the given name. You must have the
CREATE
privilege for the table.
Rules for permissible table names are given in Section 8.2, “Database, Table, Index, Column, and Alias Names”. By default, the table is created in the default database. An error occurs if the table exists, if there is no default database, or if the database does not exist.
In MySQL 3.22 or later, the table name can be specified as
db_name.tbl_name
to create the table in
a specific database. This works regardless of whether there is a
default database, assuming that the database exists. If you use
quoted identifiers, quote the database and table names separately.
For example, write `mydb`.`mytbl`
, not
`mydb.mytbl`
.
From MySQL 3.23 on, you can use the TEMPORARY
keyword when creating a table. A TEMPORARY
table is visible only to the current connection, and is dropped
automatically when the connection is closed. This means that two
different connections can use the same temporary table name
without conflicting with each other or with an existing
non-TEMPORARY
table of the same name. (The
existing table is hidden until the temporary table is dropped.)
From MySQL 4.0.2 on, to create temporary tables, you must have the
CREATE TEMPORARY TABLES
privilege.
CREATE TABLE
does not
automatically commit the current active transaction if you use
the TEMPORARY
keyword.
In MySQL 3.23 or later, the keywords IF NOT
EXISTS
prevent an error from occurring if the table
exists. However, there is no verification that the existing table
has a structure identical to that indicated by the
CREATE TABLE
statement.
MySQL represents each table by an .frm
table
format (definition) file in the database directory. The storage
engine for the table might create other files as well. In the case
of MyISAM
tables, the storage engine creates
data and index files. Thus, for each MyISAM
table tbl_name
, there are three disk
files.
File | Purpose |
---|---|
| Table format (definition) file |
| Data file |
| Index file |
Chapter 13, Storage Engines, describes what files each storage engine creates to represent tables.
data_type
represents the data type in a
column definition. spatial_type
represents a spatial data type. The data type syntax shown is
representative only. For a full description of the syntax
available for specifying column data types, as well as information
about the properties of each type, see
Chapter 10, Data Types, and
Chapter 16, Spatial Extensions.
Some attributes do not apply to all data types.
AUTO_INCREMENT
applies only to integer and
floating-point types. DEFAULT
does not apply to
the BLOB
or
TEXT
types.
If neither NULL
nor NOT
NULL
is specified, the column is treated as though
NULL
had been specified.
An integer or floating-point column can have the additional
attribute AUTO_INCREMENT
. When you insert a
value of NULL
(recommended) or
0
into an indexed
AUTO_INCREMENT
column, the column is set to
the next sequence value. Typically this is
, where
value
+1value
is the largest value for the
column currently in the table.
AUTO_INCREMENT
sequences begin with
1
.
To retrieve an AUTO_INCREMENT
value after
inserting a row, use the
LAST_INSERT_ID()
SQL function
or the mysql_insert_id()
C API
function. See Section 11.13, “Information Functions”, and
Section 17.6.6.35, “mysql_insert_id()”.
As of MySQL 4.1.1, if the
NO_AUTO_VALUE_ON_ZERO
SQL
mode is enabled, you can store 0
in
AUTO_INCREMENT
columns as
0
without generating a new sequence value.
See Section 5.1.6, “Server SQL Modes”.
There can be only one AUTO_INCREMENT
column per table, it must be indexed, and it cannot have a
DEFAULT
value. As of MySQL 3.23, an
AUTO_INCREMENT
column works properly only
if it contains only positive values. Inserting a negative
number is regarded as inserting a very large positive
number. This is done to avoid precision problems when
numbers “wrap” over from positive to negative
and also to ensure that you do not accidentally get an
AUTO_INCREMENT
column that contains
0
.
For MyISAM
and BDB
tables, you can specify an AUTO_INCREMENT
secondary column in a multiple-column key. See
Section 3.6.9, “Using AUTO_INCREMENT”.
To make MySQL compatible with some ODBC applications, you can
find the AUTO_INCREMENT
value for the last
inserted row with the following query:
SELECT * FROMtbl_name
WHEREauto_col
IS NULL
For information about InnoDB
and
AUTO_INCREMENT
, see
Section 13.2.5.3, “AUTO_INCREMENT Handling in InnoDB”.
As of MySQL 4.1, character data types
(CHAR
,
VARCHAR
,
TEXT
) can include
CHARACTER SET
and
COLLATE
attributes to specify the character
set and collation for the column. For details, see
Section 9.1, “Character Set Support”. CHARSET
is a
synonym for CHARACTER SET
. Example:
CREATE TABLE t (c CHAR(20) CHARACTER SET utf8 COLLATE utf8_bin);
Also as of 4.1, MySQL interprets length specifications in
character column definitions in characters. (Earlier versions
interpret them in bytes.) Lengths for
BINARY
and
VARBINARY
are in bytes.
NULL
values are handled differently for
TIMESTAMP
columns than for
other column types. Before MySQL 4.1.6, you cannot store a
literal NULL
in a
TIMESTAMP
column; setting the
column to NULL
sets it to the current date
and time. Because TIMESTAMP
columns behave this way, the NULL
and
NOT NULL
attributes do not apply in the
normal way and are ignored if you specify them. On the other
hand, to make it easier for MySQL clients to use
TIMESTAMP
columns, the server
reports that such columns can be assigned
NULL
values (which is true), even though
TIMESTAMP
never actually
contains a NULL
value. You can see this
when you use DESCRIBE
to get a
description of your table.
tbl_name
Note that setting a TIMESTAMP
column to 0
is not the same as setting it
to NULL
, because 0
is a
valid TIMESTAMP
value.
The DEFAULT
clause specifies a default
value for a column. With one exception, the default value must
be a constant; it cannot be a function or an expression. This
means, for example, that you cannot set the default for a date
column to be the value of a function such as
NOW()
or
CURRENT_DATE
. The exception is
that you can specify
CURRENT_TIMESTAMP
as the
default for a TIMESTAMP
column
as of MySQL 4.1.2. See Section 10.3.1.2, “TIMESTAMP Properties as of MySQL 4.1”.
If a column definition includes no explicit
DEFAULT
value, MySQL determines the default
value as described in Section 10.1.4, “Data Type Default Values”.
A comment for a column can be specified with the
COMMENT
option. The comment is displayed by
the SHOW CREATE TABLE
and
SHOW FULL
COLUMNS
statements. This option is operational as of
MySQL 4.1. (It is permitted but ignored in earlier versions.)
KEY
is normally a synonym for
INDEX
. From MySQL 4.1, the key attribute
PRIMARY KEY
can also be specified as just
KEY
when given in a column definition. This
was implemented for compatibility with other database systems.
A UNIQUE
index creates a constraint such
that all values in the index must be distinct. An error occurs
if you try to add a new row with a key value that matches an
existing row. This constraint does not apply to
NULL
values except for the
BDB
storage engine. For other engines, a
UNIQUE
index permits multiple
NULL
values for columns that can contain
NULL
.
A PRIMARY KEY
is a unique index where all
key columns must be defined as NOT NULL
. If
they are not explicitly declared as NOT
NULL
, MySQL declares them so implicitly (and
silently). A table can have only one PRIMARY
KEY
. If you do not have a PRIMARY
KEY
and an application asks for the PRIMARY
KEY
in your tables, MySQL returns the first
UNIQUE
index that has no
NULL
columns as the PRIMARY
KEY
.
In InnoDB
tables, having a long
PRIMARY KEY
wastes a lot of space. (See
Section 13.2.11, “InnoDB Table and Index Structures”.)
In the created table, a PRIMARY KEY
is
placed first, followed by all UNIQUE
indexes, and then the nonunique indexes. This helps the MySQL
optimizer to prioritize which index to use and also more
quickly to detect duplicated UNIQUE
keys.
A PRIMARY KEY
can be a multiple-column
index. However, you cannot create a multiple-column index
using the PRIMARY KEY
key attribute in a
column specification. Doing so only marks that single column
as primary. You must use a separate PRIMARY
KEY(
clause.
index_col_name
, ...)
If a PRIMARY KEY
or
UNIQUE
index consists of only one column
that has an integer type, you can also refer to the column as
_rowid
in
SELECT
statements (new in MySQL
3.23.11).
In MySQL, the name of a PRIMARY KEY
is
PRIMARY
. For other indexes, if you do not
assign a name, the index is assigned the same name as the
first indexed column, with an optional suffix
(_2
, _3
,
...
) to make it unique. You can see index
names for a table using SHOW INDEX FROM
. See
Section 12.4.5.13, “SHOW INDEX Syntax”.
tbl_name
From MySQL 4.1.0 on, some storage engines permit you to
specify an index type when creating an index. The syntax for
the index_type
specifier is
USING
.
type_name
Example:
CREATE TABLE lookup (id INT, INDEX USING BTREE (id)) ENGINE = MEMORY;
For details about USING
, see
Section 12.1.4, “CREATE INDEX Syntax”.
For more information about indexes, see Section 7.4.3, “How MySQL Uses Indexes”.
Only the MyISAM
, InnoDB
,
BDB
, and (as of MySQL 4.0.2)
MEMORY
storage engines support indexes on
columns that can have NULL
values. In other
cases, you must declare indexed columns as NOT
NULL
or an error results.
For CHAR
,
VARCHAR
,
BINARY
, and
VARBINARY
columns, indexes can
be created that use only the leading part of column values,
using
syntax to specify an index prefix length.
col_name
(length
)BLOB
and
TEXT
columns also can be
indexed, but a prefix length must be
given. Prefix lengths are given in characters for nonbinary
string types and in bytes for binary string types. That is,
index entries consist of the first
length
characters of each column
value for CHAR
,
VARCHAR
, and
TEXT
columns, and the first
length
bytes of each column value
for BINARY
,
VARBINARY
, and
BLOB
columns. Indexing only a
prefix of column values like this can make the index file much
smaller. See Section 7.4.1, “Column Indexes”.
Only the MyISAM
and (as of MySQL 4.0.14)
InnoDB
storage engines support indexing on
BLOB
and
TEXT
columns. For example:
CREATE TABLE test (blob_col BLOB, INDEX(blob_col(10)));
Prefixes can be up to 1000 bytes long (767 bytes for
InnoDB
tables). (Before MySQL 4.1.2, the
limit is 255 bytes for all tables.) Note that prefix limits
are measured in bytes, whereas the prefix length in
CREATE TABLE
statements is
interpreted as number of characters for nonbinary data types
(CHAR
,
VARCHAR
,
TEXT
). Take this into account
when specifying a prefix length for a column that uses a
multi-byte character set.
An index_col_name
specification can
end with ASC
or DESC
.
These keywords are permitted for future extensions for
specifying ascending or descending index value storage.
Currently, they are parsed but ignored; index values are
always stored in ascending order.
When you use ORDER BY
or GROUP
BY
on a TEXT
or
BLOB
column in a
SELECT
, the server sorts values
using only the initial number of bytes indicated by the
max_sort_length
system
variable. See Section 10.4.3, “The BLOB and TEXT Types”.
In MySQL 3.23.23 or later, you can create special
FULLTEXT
indexes, which are used for
full-text searches. Only the MyISAM
table
type supports FULLTEXT
indexes. They can be
created only from CHAR
,
VARCHAR
, and
TEXT
columns. Indexing always
happens over the entire column; column prefix indexing is not
supported and any prefix length is ignored if specified. See
Section 11.9, “Full-Text Search Functions”, for details of operation.
In MySQL 4.1 or later, you can create
SPATIAL
indexes on spatial data types.
Spatial types are supported only for MyISAM
tables and indexed columns must be declared as NOT
NULL
. See Chapter 16, Spatial Extensions.
In MySQL 3.23.44 or later, InnoDB
tables
support checking of foreign key constraints. See
Section 13.2, “The InnoDB Storage Engine”. Note that the
FOREIGN KEY
syntax in
InnoDB
is more restrictive than the syntax
presented for the CREATE TABLE
statement at the beginning of this section: The columns of the
referenced table must always be explicitly named.
InnoDB
supports both ON
DELETE
and ON UPDATE
actions on
foreign keys as of MySQL 3.23.50 and 4.0.8, respectively. For
the precise syntax, see
Section 13.2.5.4, “FOREIGN KEY Constraints”.
For other storage engines, MySQL Server parses and ignores the
FOREIGN KEY
and
REFERENCES
syntax in
CREATE TABLE
statements. The
CHECK
clause is parsed but ignored by all
storage engines. See Section 1.9.5.6, “Foreign Keys”.
For users familiar with the ANSI/ISO SQL Standard, please
note that no storage engine, including
InnoDB
, recognizes or enforces the
MATCH
clause used in referential
integrity constraint definitions. Use of an explicit
MATCH
clause will not have the specified
effect, and also causes ON DELETE
and
ON UPDATE
clauses to be ignored. For
these reasons, specifying MATCH
should be
avoided.
The MATCH
clause in the SQL standard
controls how NULL
values in a composite
(multiple-column) foreign key are handled when comparing to
a primary key. Starting from MySQL 3.23.50,
InnoDB
does not check foreign key
constraints on those foreign key or referenced key values
that contain a NULL
column.
InnoDB
essentially implements the
semantics defined by MATCH SIMPLE
, which
permit a foreign key to be all or partially
NULL
. In that case, the (child table) row
containing such a foreign key is permitted to be inserted,
and does not match any row in the referenced (parent) table.
Additionally, MySQL and InnoDB
require
that the referenced columns be indexed for performance.
However, the system does not enforce a requirement that the
referenced columns be UNIQUE
or be
declared NOT NULL
. The handling of
foreign key references to nonunique keys or keys that
contain NULL
values is not well defined
for operations such as UPDATE
or DELETE CASCADE
. You are advised to use
foreign keys that reference only UNIQUE
and NOT NULL
keys.
Furthermore, InnoDB
does not recognize or
support “inline REFERENCES
specifications” (as defined in the SQL standard)
where the references are defined as part of the column
specification. InnoDB
accepts
REFERENCES
clauses only when specified as
part of a separate FOREIGN KEY
specification. For other storage engines, MySQL Server
parses and ignores foreign key specifications.
There is a hard limit of 4096 columns per table, but the effective maximum may be less for a given table and depends on the factors discussed in Section D.3.2, “The Maximum Number of Columns Per Table”.
The table_option
part of the
CREATE TABLE
syntax can be used in
MySQL 3.23 and above. The =
that separates an
option name and its value is optional as of MySQL 4.1.
The ENGINE
and TYPE
options
specify the storage engine for the table.
ENGINE
was added in MySQL 4.0.18 (for 4.0) and
4.1.2 (for 4.1). It is the preferred option name as of those
versions, and TYPE
has become deprecated.
TYPE
is supported throughout the 4.x series,
but likely will be removed in the future.
The ENGINE
and TYPE
table
options take the storage engine names shown in the following
table.
Storage Engine | Description |
---|---|
ARCHIVE | The archiving storage engine. See Section 13.7, “The ARCHIVE Storage Engine”. |
BDB | Transaction-safe tables with page locking. Also known as
BerkeleyDB . See
Section 13.5, “The BDB (BerkeleyDB) Storage Engine”. |
CSV | Tables that store rows in comma-separated values format. See Section 13.8, “The CSV Storage Engine”. |
EXAMPLE | An example engine. See Section 13.6, “The EXAMPLE Storage Engine”. |
HEAP | The data for this table is stored only in memory. See Section 13.4, “The MEMORY (HEAP) Storage Engine”. |
ISAM | The original MySQL storage engine. See Section 13.10, “The ISAM Storage Engine”. |
InnoDB | Transaction-safe tables with row locking and foreign keys. See Section 13.2, “The InnoDB Storage Engine”. |
MEMORY | An alias for HEAP . (Actually, as of MySQL 4.1,
MEMORY is the preferred term.) |
MERGE | A collection of MyISAM tables used as one table. Also
known as MRG_MyISAM . See
Section 13.3, “The MERGE Storage Engine”. |
MyISAM | The binary portable storage engine that is the improved replacement for
ISAM . See
Section 13.1, “The MyISAM Storage Engine”. |
NDBCLUSTER | Clustered, fault-tolerant, memory-based tables. Also known as
NDB . See
Chapter 15, MySQL Cluster. |
If a storage engine is specified that is not available, MySQL uses
the default engine instead. Normally, this is
MyISAM
. For example, if a table definition
includes the ENGINE=BDB
option but the MySQL
server does not support BDB
tables, the table
is created as a MyISAM
table. This makes it
possible to have a replication setup where you have transactional
tables on the master but tables created on the slave are
nontransactional (to get more speed). In MySQL 4.1.1, a warning
occurs if the storage engine specification is not honored.
The other table options are used to optimize the behavior of the
table. In most cases, you do not have to specify any of them.
These options apply to all storage engines unless otherwise
indicated. Options that do not apply to a given storage engine may
be accepted and remembered as part of the table definition. Such
options then apply if you later use ALTER
TABLE
to convert the table to use a different storage
engine.
AUTO_INCREMENT
The initial AUTO_INCREMENT
value for the
table. This works for MyISAM
only, for
MEMORY
as of MySQL 4.1.0, and for
InnoDB
as of MySQL 4.1.2. To set the first
auto-increment value for engines that do not support the
AUTO_INCREMENT
table option, insert a
“dummy” row with a value one less than the
desired value after creating the table, and then delete the
dummy row.
For engines that support the AUTO_INCREMENT
table option in CREATE TABLE
statements, you can also use ALTER TABLE
to reset the
tbl_name
AUTO_INCREMENT =
N
AUTO_INCREMENT
value. The value cannot be
set lower than the maximum value currently in the column.
AVG_ROW_LENGTH
An approximation of the average row length for your table. You need to set this only for large tables with variable-size rows.
When you create a MyISAM
table, MySQL uses
the product of the MAX_ROWS
and
AVG_ROW_LENGTH
options to decide how big
the resulting table is. If you do not specify either option,
the maximum size for MyISAM
data and index
files is 4GB. (If your operating system does not support files
that large, table sizes are constrained by the operating
system limit.) If you want to keep down the pointer sizes to
make the index smaller and faster and you do not really need
big files, you can decrease the default pointer size by
setting the
myisam_data_pointer_size
system variable, which was added in MySQL 4.1.2. (See
Section 5.1.3, “Server System Variables”.) If you want all
your tables to be able to grow above the default limit and are
willing to have your tables slightly slower and larger than
necessary, you may increase the default pointer size by
setting this variable. Setting the value to 7 permits table
sizes up to 65,536TB.
[DEFAULT] CHARACTER SET
Specify a default character set for the table.
CHARSET
is a synonym for CHARACTER
SET
. If the character set name is
DEFAULT
, the database character set is
used.
CHECKSUM
Set this to 1 if you want MySQL to maintain a live checksum
for all rows (that is, a checksum that MySQL updates
automatically as the table changes). This makes the table a
little slower to update, but also makes it easier to find
corrupted tables. The CHECKSUM
TABLE
statement reports the checksum.
(MyISAM
only.)
[DEFAULT] COLLATE
Specify a default collation for the table.
COMMENT
A comment for the table, up to 60 characters long.
DATA DIRECTORY
, INDEX
DIRECTORY
By using DATA
DIRECTORY='
or
directory
'INDEX
DIRECTORY='
you
can specify where the directory
'MyISAM
storage engine
should put a table's data file and index file. The directory
must be the full path name to the directory, not a relative
path.
These options work only for MyISAM
tables
from MySQL 4.0 on, when you are not using the
--skip-symbolic-links
option. Your operating system must also have a working,
thread-safe realpath()
call. See
Section 7.10.2, “Using Symbolic Links for Tables on Unix”, for more complete
information.
Beginning with MySQL 4.1.24, you cannot use path names that
contain the MySQL data directory with DATA
DIRECTORY
or INDEX DIRECTORY
.
(See Bug #32167.)
DELAY_KEY_WRITE
Set this to 1 if you want to delay key updates for the table
until the table is closed. See the description of the
delay_key_write
system
variable in Section 5.1.3, “Server System Variables”.
(MyISAM
only.)
INSERT_METHOD
If you want to insert data into a MERGE
table, you must specify with INSERT_METHOD
the table into which the row should be inserted.
INSERT_METHOD
is an option useful for
MERGE
tables only. Use a value of
FIRST
or LAST
to have
inserts go to the first or last table, or a value of
NO
to prevent inserts. This option was
introduced in MySQL 4.0.0. See
Section 13.3, “The MERGE Storage Engine”.
MAX_ROWS
The maximum number of rows you plan to store in the table. This is not a hard limit, but rather a hint to the storage engine that the table must be able to store at least this many rows.
The NDB
storage engine treats
this value as a maxmimum. If you plan to create very large
MySQL Cluster tables (containing millions of rows), you should
use this option to insure that
NDB
allocates sufficient number
of index slots in the hash table used for storing hashes of
the table's primary keys by setting MAX_ROWS = 2
*
, where
rows
rows
is the number of rows that you
expect to insert into the table.
The maximum MAX_ROWS
value is 4294967295;
larger values are truncated to this limit.
MIN_ROWS
The minimum number of rows you plan to store in the table. The
MEMORY
storage engine uses this
option as a hint about memory use.
PACK_KEYS
PACK_KEYS
takes effect only with
MyISAM
tables. Set this option to 1 if you
want to have smaller indexes. This usually makes updates
slower and reads faster. Setting the option to 0 disables all
packing of keys. Setting it to DEFAULT
tells the storage engine to pack only long
CHAR
,
VARCHAR
,
BINARY
, or
VARBINARY
columns.
If you do not use PACK_KEYS
, the default is
to pack strings, but not numbers. If you use
PACK_KEYS=1
, numbers are packed as well.
When packing binary number keys, MySQL uses prefix compression:
Every key needs one extra byte to indicate how many bytes of the previous key are the same for the next key.
The pointer to the row is stored in high-byte-first order directly after the key, to improve compression.
This means that if you have many equal keys on two consecutive
rows, all following “same” keys usually only take
two bytes (including the pointer to the row). Compare this to
the ordinary case where the following keys takes
storage_size_for_key + pointer_size
(where
the pointer size is usually 4). Conversely, you get a
significant benefit from prefix compression only if you have
many numbers that are the same. If all keys are totally
different, you use one byte more per key, if the key is not a
key that can have NULL
values. (In this
case, the packed key length is stored in the same byte that is
used to mark if a key is NULL
.)
PASSWORD
This option is unused. If you have a need to scramble your
.frm
files and make them unusable to any
other MySQL server, please contact our sales department.
The RAID_TYPE
option can help you to exceed
the 2GB/4GB limit for the MyISAM
data file
(not the index file) on operating systems that do not support
big files. This option is unnecessary and not recommended for
file systems that support big files.
You can get more speed from the I/O bottleneck by putting
RAID
directories on different physical
disks. The only permitted RAID_TYPE
is
STRIPED
. 1
and
RAID0
are aliases for
STRIPED
.
If you specify the RAID_TYPE
option for a
MyISAM
table, specify the
RAID_CHUNKS
and
RAID_CHUNKSIZE
options as well. The maximum
RAID_CHUNKS
value is 255.
MyISAM
creates
RAID_CHUNKS
subdirectories named
00
, 01
,
02
, ... 09
,
0a
, 0b
, ... in the
database directory. In each of these directories,
MyISAM
creates a file
.
When writing data to the data file, the
tbl_name
.MYDRAID
handler maps the first
RAID_CHUNKSIZE*1024
bytes to the first
file, the next RAID_CHUNKSIZE*1024
bytes to
the next file, and so on.
RAID_TYPE
works on any operating system, as
long as you have built MySQL with the
--with-raid
option to
configure. To determine whether a server
supports RAID
tables, use SHOW
VARIABLES LIKE 'have_raid'
to see whether the
variable value is YES
.
ROW_FORMAT
Defines how the rows should be stored. Currently, this option
works only with MyISAM
tables. The option
value can be FIXED
or
DYNAMIC
for static or variable-length row
format. myisampack sets the type to
COMPRESSED
. See
Section 13.1.3, “MyISAM Table Storage Formats”.
When executing a CREATE TABLE
statement, if you specify a row format which is not
supported by the storage engine that is used for the table,
the table is created using that storage engine's
default row format. The information reported in this column
in response to SHOW TABLE
STATUS
is the actual row format used. This may
differ from the value in the
Create_options
column because the
original CREATE TABLE
definition is retained during creation.
UNION
is used when you want to
access a collection of identical MyISAM
tables as one. This works only with MERGE
tables. See Section 13.3, “The MERGE Storage Engine”.
In MySQL 4.1, you must have
SELECT
,
UPDATE
, and
DELETE
privileges for the
tables you map to a MERGE
table.
Originally, all tables used had to be in the same database
as the MERGE
table itself. This
restriction has been lifted as of MySQL 4.1.1.
The original CREATE TABLE
statement, including all specifications and table options are
stored by MySQL when the table is created. The information is
retained so that if you change storage engines, collations or
other settings using an ALTER
TABLE
statement, the original table options specified
are retained. This enables you to change between
InnoDB
and MyISAM
table
types even though the row formats supported by the two engines
are different.
Because the text of the original statement is retained, but due
to the way that certain values and options may be silently
reconfigured (such as the ROW_FORMAT
), the
active table definition (accessible through
DESCRIBE
or with
SHOW TABLE STATUS
) and the table
creation string (accessible through SHOW
CREATE TABLE
) will report different values.
As of MySQL 3.23, you can create one table from another by adding
a SELECT
statement at the end of
the CREATE TABLE
statement:
CREATE TABLEnew_tbl
SELECT * FROMorig_tbl
;
For more information, see Section 12.1.5.1, “CREATE TABLE ... SELECT Syntax”.
In MySQL 4.1, you can also use LIKE
to create
an empty table based on the definition of another table, including
any column attributes and indexes the original table has:
CREATE TABLEnew_tbl
LIKEorig_tbl
;
The copy is created using the same version of the table storage format as the original table.
CREATE TABLE ... LIKE
does not preserve any
DATA DIRECTORY
or INDEX
DIRECTORY
table options that were specified for the
original table, or any foreign key definitions.
If the original table is a TEMPORARY
table,
CREATE TABLE ... LIKE
does not preserve
TEMPORARY
. To create a
TEMPORARY
destination table, use
CREATE TEMPORARY TABLE ... LIKE
.
As of MySQL 3.23, you can create one table from another by
adding a SELECT
statement at the
end of the CREATE TABLE
statement:
CREATE TABLEnew_tbl
[AS] SELECT * FROMorig_tbl
;
MySQL creates new columns for all elements in the
SELECT
. For example:
mysql>CREATE TABLE test (a INT NOT NULL AUTO_INCREMENT,
->PRIMARY KEY (a), KEY(b))
->TYPE=MyISAM SELECT b,c FROM test2;
This creates a MyISAM
table with three
columns, a
, b
, and
c
. Notice that the columns from the
SELECT
statement are appended to
the right side of the table, not overlapped onto it. Take the
following example:
mysql>SELECT * FROM foo;
+---+ | n | +---+ | 1 | +---+ mysql>CREATE TABLE bar (m INT) SELECT n FROM foo;
Query OK, 1 row affected (0.02 sec) Records: 1 Duplicates: 0 Warnings: 0 mysql>SELECT * FROM bar;
+------+---+ | m | n | +------+---+ | NULL | 1 | +------+---+ 1 row in set (0.00 sec)
For each row in table foo
, a row is inserted
in bar
with the values from
foo
and default values for the new columns.
In a table resulting from
CREATE TABLE ...
SELECT
, columns named only in the
CREATE TABLE
part come first.
Columns named in both parts or only in the
SELECT
part come after that. The
data type of SELECT
columns can
be overridden by also specifying the column in the
CREATE TABLE
part.
If any errors occur while copying the data to the table, it is automatically dropped and not created.
You can precede the SELECT
by
IGNORE
or
REPLACE
to indicate how to handle
rows that duplicate unique key values. With
IGNORE
, new rows that duplicate an existing
row on a unique key value are discarded. With
REPLACE
, new rows replace rows
that have the same unique key value. If neither
IGNORE
nor
REPLACE
is specified, duplicate
unique key values result in an error.
CREATE TABLE ...
SELECT
does not automatically create any indexes for
you. This is done intentionally to make the statement as
flexible as possible. If you want to have indexes in the created
table, you should specify these before the
SELECT
statement:
mysql> CREATE TABLE bar (UNIQUE (n)) SELECT n FROM foo;
Some conversion of data types might occur. For example, the
AUTO_INCREMENT
attribute is not preserved,
and VARCHAR
columns can become
CHAR
columns. Retrained
attributes are NULL
(or NOT
NULL
) and, for those columns that have them,
CHARACTER SET
, COLLATION
,
COMMENT
, and the DEFAULT
clause.
When creating a table with
CREATE
TABLE ... SELECT
, make sure to alias any function
calls or expressions in the query. If you do not, the
CREATE
statement might fail or result in
undesirable column names.
CREATE TABLE artists_and_works SELECT artist.name, COUNT(work.artist_id) AS number_of_works FROM artist LEFT JOIN work ON artist.id = work.artist_id GROUP BY artist.id;
As of MySQL 4.1, you can explicitly specify the data type for a generated column:
CREATE TABLE foo (a TINYINT NOT NULL) SELECT b+1 AS a FROM bar;
For CREATE TABLE
... SELECT
, if IF NOT EXISTS
is
given and the destination table already exists, MySQL handles
the statement as follows:
The table definition given in the
CREATE TABLE
part is ignored.
No error occurs, even if the definition does not match that
of the existing table. MySQL attempts to insert the rows
from the SELECT
part anyway.
If there is a mismatch between the number of columns in the
table and the number of columns produced by the
SELECT
part, the selected
values are assigned to the rightmost columns. For example,
if the table contains n
columns
and the SELECT
produces
m
columns, where
m
<
n
, the selected values are
assigned to the m
rightmost
columns in the table. Each of the initial
n
–
m
columns is assigned its default
value, either that specified explicitly in the column
definition or the implicit column data type default if the
definition contains no default. If the
SELECT
part produces too many
columns (m
>
n
), an error occurs.
The following example illustrates IF NOT
EXISTS
handling:
mysql>CREATE TABLE t1 (i1 INT DEFAULT 0, i2 INT, i3 INT, i4 INT);
Query OK, 0 rows affected (0.05 sec) mysql>CREATE TABLE IF NOT EXISTS t1 (c1 CHAR(10)) SELECT 1, 2;
Query OK, 1 row affected, 1 warning (0.01 sec) Records: 1 Duplicates: 0 Warnings: 0 mysql>SELECT * FROM t1;
+------+------+------+------+ | i1 | i2 | i3 | i4 | +------+------+------+------+ | 0 | NULL | 1 | 2 | +------+------+------+------+ 1 row in set (0.00 sec)
To ensure that the update log or binary log can be used to
re-create the original tables, MySQL does not permit concurrent
inserts for CREATE
TABLE ... SELECT
statements.
In some cases, MySQL silently changes column specifications from
those given in a CREATE TABLE
or
ALTER TABLE
statement. These
might be changes to a data type, to attributes associated with a
data type, or to an index specification.
Possible data type changes are given in the following list.
VARCHAR
columns with a length
less than four are changed to
CHAR
.
If any column in a table has a variable length, the entire
row becomes variable-length as a result. Therefore, if a
table contains any variable-length columns
(VARCHAR
,
TEXT
, or
BLOB
), all
CHAR
columns longer than
three characters are changed to
VARCHAR
columns. This does
not affect how you use the columns in any way; in MySQL,
VARCHAR
is just a different
way to store characters. MySQL performs this conversion
because it saves space and makes table operations faster.
See Chapter 13, Storage Engines.
From MySQL 4.1.0 onward, a
CHAR
or
VARCHAR
column with a length
specification greater than 255 is converted to the smallest
TEXT
type that can hold
values of the given length. For example,
VARCHAR(500)
is converted to
TEXT
, and
VARCHAR(200000)
is converted to
MEDIUMTEXT
. Similar
conversions occur for BINARY
and VARBINARY
, except that
they are converted to a BLOB
type.
Note that these conversions result in a change in behavior with regard to treatment of trailing spaces.
From MySQL 4.1.2 on, specifying the CHARACTER SET
binary
attribute for a character data type causes
the column to be created as the corresponding binary data
type: CHAR
becomes
BINARY
,
VARCHAR
becomes
VARBINARY
, and
TEXT
becomes
BLOB
. For the
ENUM
and
SET
data types, this does not
occur; they are created as declared. Suppose that you
specify a table using this definition:
CREATE TABLE t ( c1 VARCHAR(10) CHARACTER SET binary, c2 TEXT CHARACTER SET binary, c3 ENUM('a','b','c') CHARACTER SET binary );
The resulting table has this definition:
CREATE TABLE t ( c1 VARBINARY(10), c2 BLOB, c3 ENUM('a','b','c') CHARACTER SET binary );
For a specification of
DECIMAL(
,
if M
,D
)M
is not larger than
D
, it is adjusted upward. For
example, DECIMAL(10,10)
becomes
DECIMAL(11,10)
.
Other silent column specification changes include modifications to attribute or index specifications:
TIMESTAMP
display sizes are
discarded from MySQL 4.1 on, due to changes made to the
TIMESTAMP
data type in that
version. Before MySQL 4.1,
TIMESTAMP
display sizes must
be even and in the range from 2 to 14. If you specify a
display size of 0 or greater than 14, the size is coerced to
14. Odd-valued sizes in the range from 1 to 13 are coerced
to the next higher even number.
Also note that, in MySQL 4.1 and later,
TIMESTAMP
columns are
NOT NULL
by default.
Before MySQL 4.1.6, you cannot store a literal
NULL
in a
TIMESTAMP
column; setting it
to NULL
sets it to the current date and
time. Because TIMESTAMP
columns behave this way, the NULL
and
NOT NULL
attributes do not apply in the
normal way and are ignored if you specify them.
DESCRIBE
always reports
that a tbl_name
TIMESTAMP
column can
be assigned NULL
values.
Columns that are part of a PRIMARY KEY
are made NOT NULL
even if not declared
that way.
Starting from MySQL 3.23.51, trailing spaces are
automatically deleted from
ENUM
and
SET
member values when the
table is created.
MySQL maps certain data types used by other SQL database vendors to MySQL types. See Section 10.7, “Using Data Types from Other Database Engines”.
If you include a USING
clause to specify
an index type that is not legal for a given storage engine,
but there is another index type available that the engine
can use without affecting query results, the engine uses the
available type.
To see whether MySQL used a data type other than the one you
specified, issue a DESCRIBE
or
SHOW CREATE TABLE
statement after
creating or altering the table.
Certain other data type changes can occur if you compress a table using myisampack. See Section 13.1.3.3, “Compressed Table Characteristics”.
DROP DATABASE [IF EXISTS] db_name
DROP DATABASE
drops all tables in
the database and deletes the database. Be
very careful with this statement! To use
DROP DATABASE
, you need the
DROP
privilege on the database.
When a database is dropped, user privileges on the database are not automatically dropped. See Section 12.4.1.2, “GRANT Syntax”.
In MySQL 3.22 or later, you can use the keywords IF
EXISTS
to prevent an error from occurring if the
database does not exist.
As of MySQL 4.1.1, if the default database is dropped, the default
database is unset (the DATABASE()
function returns NULL
).
If you use DROP DATABASE
on a
symbolically linked database, both the link and the original
database are deleted.
As of MySQL 4.1.2, DROP DATABASE
returns the number of tables that were removed. This corresponds
to the number of .frm
files removed.
The DROP DATABASE
statement removes
from the given database directory those files and directories that
MySQL itself may create during normal operation:
All files with the following extensions.
.BAK | .DAT | .HSH | .ISD |
.ISM | .MRG | .MYD | .MYI |
.db | .frm | .ibd | .ndb |
All subdirectories with names that consist of two hex digits
00
-ff
. These are
subdirectories used for RAID
tables. (These
directories are not removed in versions of MySQL after 4.1,
where support for RAID
tables is removed.
You should convert any existing RAID
tables
and remove these directories manually before upgrading to
later MySQL versions.)
The db.opt
file, if it exists.
If other files or directories remain in the database directory
after MySQL removes those just listed, the database directory
cannot be removed. In this case, you must remove any remaining
files or directories manually and issue the
DROP DATABASE
statement again.
You can also drop databases with mysqladmin. See Section 4.5.2, “mysqladmin — Client for Administering a MySQL Server”.
DROP INDEXindex_name
ONtbl_name
DROP INDEX
drops the index named
index_name
from the table
tbl_name
. In MySQL 3.22 or later,
DROP INDEX
is mapped to an
ALTER TABLE
statement to drop the
index. See Section 12.1.2, “ALTER TABLE Syntax”.
DROP INDEX
does not do anything
prior to MySQL 3.22.
DROP [TEMPORARY] TABLE [IF EXISTS]tbl_name
[,tbl_name
] ... [RESTRICT | CASCADE]
DROP TABLE
removes one or more
tables. You must have the DROP
privilege for each table. All table data and the table definition
are removed, so be
careful with this statement! If any of the tables named
in the argument list do not exist, MySQL returns an error
indicating by name which nonexisting tables it was unable to drop,
but it also drops all of the tables in the list that do exist.
When a table is dropped, user privileges on the table are not automatically dropped. See Section 12.4.1.2, “GRANT Syntax”.
In MySQL 3.22 or later, you can use the keywords IF
EXISTS
to prevent an error from occurring for tables
that do not exist. As of MySQL 4.1, a NOTE
is
generated for each nonexistent table when using IF
EXISTS
. See Section 12.4.5.26, “SHOW WARNINGS Syntax”.
RESTRICT
and CASCADE
are
permitted to make porting easier. In MySQL 4.1 and
earlier, they do nothing.
DROP TABLE
automatically commits
the current active transaction, unless you are using MySQL 4.1
or higher and the TEMPORARY
keyword.
The TEMPORARY
keyword is ignored in MySQL 4.0.
As of 4.1, it has the following effect:
The statement drops only TEMPORARY
tables.
The statement does not end an ongoing transaction.
No access rights are checked. (A TEMPORARY
table is visible only to the session that created it, so no
check is necessary.)
Using TEMPORARY
is a good way to ensure that
you do not accidentally drop a non-TEMPORARY
table.
RENAME TABLEtbl_name
TOnew_tbl_name
[,tbl_name2
TOnew_tbl_name2
] ...
This statement renames one or more tables. It was added in MySQL 3.23.23.
The rename operation is done atomically, which means that no other
session can access any of the tables while the rename is running.
For example, if you have an existing table
old_table
, you can create another table
new_table
that has the same structure but is
empty, and then replace the existing table with the empty one as
follows (assuming that backup_table
does not
already exist):
CREATE TABLE new_table (...); RENAME TABLE old_table TO backup_table, new_table TO old_table;
If the statement renames more than one table, renaming operations
are done from left to right. If you want to swap two table names,
you can do so like this (assuming that
tmp_table
does not already exist):
RENAME TABLE old_table TO tmp_table, new_table TO old_table, tmp_table TO new_table;
As long as two databases are on the same file system, you can use
RENAME TABLE
to move a table from
one database to another:
RENAME TABLEcurrent_db.tbl_name
TOother_db.tbl_name;
Any privileges granted specifically for the renamed table or view are not migrated to the new name. They must be changed manually.
When you execute RENAME
, you cannot have any
locked tables or active transactions. You must also have the
ALTER
and
DROP
privileges on the original
table, and the CREATE
and
INSERT
privileges on the new table.
If MySQL encounters any errors in a multiple-table rename, it does a reverse rename for all renamed tables to return everything to its original state.
You cannot use RENAME
to rename a
TEMPORARY
table. However, you can use
ALTER TABLE
instead:
mysql> ALTER TABLE orig_name RENAME new_name;
TRUNCATE [TABLE] tbl_name
TRUNCATE TABLE
empties a table
completely. Logically, this is equivalent to a
DELETE
statement that deletes all
rows, but there are practical differences under some
circumstances.
For InnoDB
, TRUNCATE
TABLE
is mapped to
DELETE
, so there is no difference.
For other storage engines, TRUNCATE
TABLE
differs from DELETE
in the following ways from MySQL 4.0 onward:
Truncate operations drop and re-create the table, which is much faster than deleting rows one by one, particularly for large tables.
As of MySQL 4.1.13, truncate operations cause an implicit commit. Before 4.1.13, truncate operations are not transaction-safe; an error occurs when attempting one in the course of an active transaction.
Truncation operations cannot be performed if the session holds an active table lock.
Truncation operations do not return a meaningful value for the number of deleted rows. The usual result is “0 rows affected,” which should be interpreted as “no information.”
As long as the table format file
is valid, the table can be re-created as an empty table with
tbl_name
.frmTRUNCATE TABLE
, even if the
data or index files have become corrupted.
The table handler does not remember the last used
AUTO_INCREMENT
value, but starts counting
from the beginning. This is true even for
MyISAM
and InnoDB
, which
normally do not reuse sequence values. (Some older versions
may not reset the AUTO_INCREMENT
value. In
this case, you can use ALTER TABLE
after the tbl_name
AUTO_INCREMENT=1TRUNCATE TABLE
statement.)
In MySQL 3.23, TRUNCATE TABLE
is
mapped to COMMIT; DELETE FROM
, so it behaves like
tbl_name
DELETE
. See
Section 12.2.1, “DELETE Syntax”.
TRUNCATE TABLE
was added in MySQL
3.23.28, although from 3.23.28 to 3.23.32, the keyword
TABLE
must be omitted.
Single-table syntax:
DELETE [LOW_PRIORITY] [QUICK] [IGNORE] FROMtbl_name
[WHEREwhere_condition
] [ORDER BY ...] [LIMITrow_count
]
Multiple-table syntax:
DELETE [LOW_PRIORITY] [QUICK] [IGNORE]tbl_name
[.*] [,tbl_name
[.*]] ... FROMtable_references
[WHEREwhere_condition
]
Or:
DELETE [LOW_PRIORITY] [QUICK] [IGNORE] FROMtbl_name
[.*] [,tbl_name
[.*]] ... USINGtable_references
[WHEREwhere_condition
]
For the single-table syntax, the
DELETE
statement deletes rows from
tbl_name
. The number of rows deleted
can be determined by calling the
mysql_info()
C API function. The
WHERE
clause, if given, specifies the
conditions that identify which rows to delete. With no
WHERE
clause, all rows are deleted. If the
ORDER BY
clause is specified, the rows are
deleted in the order that is specified. The
LIMIT
clause places a limit on the number of
rows that can be deleted.
For the multiple-table syntax,
DELETE
deletes from each
tbl_name
the rows that satisfy the
conditions. In this case, ORDER BY
and
LIMIT
cannot be used.
where_condition
is an expression that
evaluates to true for each row to be deleted. It is specified as
described in Section 12.2.7, “SELECT Syntax”.
Currently, you cannot delete from a table and select from the same table in a subquery.
You need the DELETE
privilege on a
table to delete rows from it. You need only the
SELECT
privilege for any columns
that are only read, such as those named in the
WHERE
clause.
As stated, a DELETE
statement with
no WHERE
clause deletes all rows. A faster way
to do this, when you do not need to know the number of deleted
rows, is to use TRUNCATE TABLE
.
However, within a transaction or if you have a lock on the table,
TRUNCATE TABLE
cannot be used
whereas DELETE
can. See
Section 12.1.10, “TRUNCATE TABLE Syntax”, and
Section 12.3.5, “LOCK TABLES and UNLOCK TABLES Syntax”.
In MySQL 3.23, DELETE
without a
WHERE
clause returns zero as the number of
affected rows.
In MySQL 3.23, if you really want to know how many rows are
deleted when you are deleting all rows, and are willing to suffer
a speed penalty, you can use a
DELETE
statement that includes a
WHERE
clause with an expression that is true
for every row. For example:
mysql> DELETE FROM tbl_name
WHERE 1>0;
This is much slower than TRUNCATE
, because it deletes
rows one at a time.
tbl_name
If you delete the row containing the maximum value for an
AUTO_INCREMENT
column, the value is reused
later for an ISAM
or BDB
table, but not for a MyISAM
or
InnoDB
table. If you delete all rows in the
table with DELETE FROM
(without a
tbl_name
WHERE
clause) in
autocommit
mode, the sequence
starts over for all storage engines except
InnoDB
and (as of MySQL 4.0)
MyISAM
. There are some exceptions to this
behavior for InnoDB
tables, as discussed in
Section 13.2.5.3, “AUTO_INCREMENT Handling in InnoDB”.
For MyISAM
and BDB
tables,
you can specify an AUTO_INCREMENT
secondary
column in a multiple-column key. In this case, reuse of values
deleted from the top of the sequence occurs even for
MyISAM
tables. See
Section 3.6.9, “Using AUTO_INCREMENT”.
The DELETE
statement supports the
following modifiers:
If you specify LOW_PRIORITY
, the server
delays execution of the DELETE
until no other clients are reading from the table. This
affects only storage engines that use only table-level locking
(such as MyISAM
, MEMORY
,
and MERGE
).
For MyISAM
tables, if you use the
QUICK
keyword, the storage engine does not
merge index leaves during delete, which may speed up some
kinds of delete operations.
The IGNORE
keyword causes MySQL to ignore
all errors during the process of deleting rows. (Errors
encountered during the parsing stage are processed in the
usual manner.) Errors that are ignored due to the use of
IGNORE
are returned as warnings. This
option first appeared in MySQL 4.1.1.
The speed of delete operations may also be affected by factors discussed in Section 7.3.2.3, “Speed of DELETE Statements”.
In MyISAM
tables, deleted rows are maintained
in a linked list and subsequent
INSERT
operations reuse old row
positions. To reclaim unused space and reduce file sizes, use the
OPTIMIZE TABLE
statement or the
myisamchk utility to reorganize tables.
OPTIMIZE TABLE
is easier to use,
but myisamchk is faster. See
Section 12.4.2.5, “OPTIMIZE TABLE Syntax”, and Section 4.6.2, “myisamchk — MyISAM Table-Maintenance Utility”.
The QUICK
modifier affects whether index leaves
are merged for delete operations. DELETE QUICK
is most useful for applications where index values for deleted
rows are replaced by similar index values from rows inserted
later. In this case, the holes left by deleted values are reused.
DELETE QUICK
is not useful when deleted values
lead to underfilled index blocks spanning a range of index values
for which new inserts occur again. In this case, use of
QUICK
can lead to wasted space in the index
that remains unreclaimed. Here is an example of such a scenario:
Create a table that contains an indexed
AUTO_INCREMENT
column.
Insert many rows into the table. Each insert results in an index value that is added to the high end of the index.
Delete a block of rows at the low end of the column range
using DELETE QUICK
.
In this scenario, the index blocks associated with the deleted
index values become underfilled but are not merged with other
index blocks due to the use of QUICK
. They
remain underfilled when new inserts occur, because new rows do not
have index values in the deleted range. Furthermore, they remain
underfilled even if you later use
DELETE
without
QUICK
, unless some of the deleted index values
happen to lie in index blocks within or adjacent to the
underfilled blocks. To reclaim unused index space under these
circumstances, use OPTIMIZE TABLE
.
If you are going to delete many rows from a table, it might be
faster to use DELETE QUICK
followed by
OPTIMIZE TABLE
. This rebuilds the
index rather than performing many index block merge operations.
The MySQL-specific LIMIT
option to
row_count
DELETE
tells the server the maximum
number of rows to be deleted before control is returned to the
client. This can be used to ensure that a given
DELETE
statement does not take too
much time. You can simply repeat the
DELETE
statement until the number
of affected rows is less than the LIMIT
value.
If the DELETE
statement includes an
ORDER BY
clause, rows are deleted in the order
specified by the clause. This is useful primarily in conjunction
with LIMIT
. For example, the following
statement finds rows matching the WHERE
clause,
sorts them by timestamp_column
, and deletes the
first (oldest) one:
DELETE FROM somelog WHERE user = 'jcole' ORDER BY timestamp_column LIMIT 1;
ORDER BY
may also be useful in some cases to
delete rows in an order required to avoid referential integrity
violations.
ORDER BY
can be used with
DELETE
beginning with MySQL 4.0.0.
From MySQL 4.0, you can specify multiple tables in the
DELETE
statement to delete rows
from one or more tables depending on a particular condition in
multiple tables. However, you cannot use ORDER
BY
or LIMIT
in a multiple-table
DELETE
.
If you are deleting many rows from a large table, you may exceed
the lock table size for an InnoDB
table. To
avoid this problem, or simply to minimize the time that the table
remains locked, the following strategy (which does not use
DELETE
at all) might be helpful:
Select the rows not to be deleted into an empty table that has the same structure as the original table:
INSERT INTO t_copy SELECT * FROM t WHERE ... ;
Use RENAME TABLE
to atomically
move the original table out of the way and rename the copy to
the original name:
RENAME TABLE t TO t_old, t_copy TO t;
Drop the original table:
DROP TABLE t_old;
No other sessions can access the tables involved while
RENAME TABLE
executes, so the
rename operation is not subject to concurrency problems. See
Section 12.1.9, “RENAME TABLE Syntax”.
You can specify multiple tables in a
DELETE
statement to delete rows
from one or more tables depending on the particular condition in
the WHERE
clause. However, you cannot use
ORDER BY
or LIMIT
in a
multiple-table DELETE
. The
table_references
clause lists the
tables involved in the join. Its syntax is described in
Section 12.2.7.1, “JOIN Syntax”.
The first multiple-table DELETE
syntax is supported starting from MySQL 4.0.0. The second is
supported starting from MySQL 4.0.2.
For the first multiple-table syntax, only matching rows from the
tables listed before the FROM
clause are
deleted. For the second multiple-table syntax, only matching rows
from the tables listed in the FROM
clause
(before the USING
clause) are deleted. The
effect is that you can delete rows from many tables at the same
time and have additional tables that are used only for searching:
DELETE t1, t2 FROM t1 INNER JOIN t2 INNER JOIN t3 WHERE t1.id=t2.id AND t2.id=t3.id;
Or:
DELETE FROM t1, t2 USING t1 INNER JOIN t2 INNER JOIN t3 WHERE t1.id=t2.id AND t2.id=t3.id;
These statements use all three tables when searching for rows to
delete, but delete matching rows only from tables
t1
and t2
.
The preceding examples use INNER JOIN
, but
multiple-table DELETE
statements
can use other types of join permitted in
SELECT
statements, such as
LEFT JOIN
. For example, to delete rows that
exist in t1
that have no match in
t2
, use a LEFT JOIN
:
DELETE t1 FROM t1 LEFT JOIN t2 ON t1.id=t2.id WHERE t2.id IS NULL;
The syntax permits .*
after each
tbl_name
for compatibility with
Access.
If you use a multiple-table DELETE
statement involving InnoDB
tables for which
there are foreign key constraints, the MySQL optimizer might
process tables in an order that differs from that of their
parent/child relationship. In this case, the statement fails and
rolls back. Instead, you should delete from a single table and
rely on the ON DELETE
capabilities that
InnoDB
provides to cause the other tables to be
modified accordingly.
Table aliases in a multiple-table
DELETE
should be declared only in
the table_references
part of the
statement. Elsewhere, aliases references are permitted but should
not be declared.
The syntax for multiple-table
DELETE
statements that use table
aliases changed between MySQL 4.0 and 4.1. In MySQL 4.0, you
should use the true table name to refer to any table from which
rows should be deleted:
DELETE test FROM test AS t1, test2 WHERE ...
In MySQL 4.1, if you declare an alias for a table, you must use the alias when referring to the table:
DELETE t1 FROM test AS t1, test2 WHERE ...
We did not make this change in 4.0 to avoid breaking any old 4.0
applications that were using the old syntax. However, if you use
such DELETE
statements and are
using replication, the change in syntax means that a 4.0 master
cannot replicate to 4.1 (or higher) slaves.
For multiple-table deletes, prior to MySQL 4.1.2 you must refer to the tables without using aliases. For example:
DELETE test1.tmp1, test2.tmp2 FROM test1.tmp1, test2.tmp2 WHERE ...
As of MySQL 4.1.2, aliases can be used, but for alias references
in the list of tables from which to delete rows, the default
database is used unless one is specified explicitly. For example,
if the default database is db1
, the following
statement does not work because the unqualified alias reference
a2
is interpreted as having a database of
db1
:
DELETE a1, a2 FROM db1.t1 AS a1 INNER JOIN db2.t2 AS a2 WHERE a1.id=a2.id;
To correctly match an alias that refers to a table outside the default database, you must explicitly qualify the reference with the name of the proper database:
DELETE a1, db2.a2 FROM db1.t1 AS a1 INNER JOIN db2.t2 AS a2 WHERE a1.id=a2.id;
DOexpr
[,expr
] ...
DO
executes the expressions but
does not return any results. In most respects,
DO
is shorthand for SELECT
, but has the
advantage that it is slightly faster when you do not care about
the result.
expr
, ...
DO
is useful primarily with
functions that have side effects, such as
RELEASE_LOCK()
.
DO
was added in MySQL 3.23.47.
HANDLERtbl_name
OPEN [ [AS]alias
] HANDLERtbl_name
READindex_name
{ = | <= | >= | < | > } (value1
,value2
,...) [ WHEREwhere_condition
] [LIMIT ... ] HANDLERtbl_name
READindex_name
{ FIRST | NEXT | PREV | LAST } [ WHEREwhere_condition
] [LIMIT ... ] HANDLERtbl_name
READ { FIRST | NEXT } [ WHEREwhere_condition
] [LIMIT ... ] HANDLERtbl_name
CLOSE
The HANDLER
statement provides
direct access to table storage engine interfaces. It is available
for MyISAM
tables as MySQL 4.0.0 and
InnoDB
tables as of MySQL 4.0.3.
The HANDLER ... OPEN
statement opens a table,
making it accessible using subsequent HANDLER ...
READ
statements. This table object is not shared by
other sessions and is not closed until the session calls
HANDLER ... CLOSE
or the session terminates. If
you open the table using an alias, further references to the open
table with other HANDLER
statements
must use the alias rather than the table name.
The first HANDLER ... READ
syntax fetches a row
where the index specified satisfies the given values and the
WHERE
condition is met. If you have a
multiple-column index, specify the index column values as a
comma-separated list. Either specify values for all the columns in
the index, or specify values for a leftmost prefix of the index
columns. Suppose that an index my_idx
includes
three columns named col_a
,
col_b
, and col_c
, in that
order. The HANDLER
statement can
specify values for all three columns in the index, or for the
columns in a leftmost prefix. For example:
HANDLER ... READ my_idx = (col_a_val,col_b_val,col_c_val) ... HANDLER ... READ my_idx = (col_a_val,col_b_val) ... HANDLER ... READ my_idx = (col_a_val) ...
To employ the HANDLER
interface to
refer to a table's PRIMARY KEY
, use the quoted
identifier `PRIMARY`
:
HANDLER tbl_name
READ `PRIMARY` ...
The second HANDLER ... READ
syntax fetches a
row from the table in index order that matches the
WHERE
condition.
The third HANDLER ... READ
syntax fetches a row
from the table in natural row order that matches the
WHERE
condition. It is faster than
HANDLER
when a full table
scan is desired. Natural row order is the order in which rows are
stored in a tbl_name
READ
index_name
MyISAM
table data file. This
statement works for InnoDB
tables as well, but
there is no such concept because there is no separate data file.
Without a LIMIT
clause, all forms of
HANDLER ... READ
fetch a single row if one is
available. To return a specific number of rows, include a
LIMIT
clause. It has the same syntax as for the
SELECT
statement. See
Section 12.2.7, “SELECT Syntax”.
HANDLER ... CLOSE
closes a table that was
opened with HANDLER ... OPEN
.
There are several reasons to use the
HANDLER
interface instead of normal
SELECT
statements:
HANDLER
is faster than
SELECT
:
A designated storage engine handler object is allocated
for the HANDLER ... OPEN
. The object is
reused for subsequent
HANDLER
statements for that
table; it need not be reinitialized for each one.
There is less parsing involved.
There is no optimizer or query-checking overhead.
The table does not have to be locked between two handler requests.
The handler interface does not have to provide a
consistent look of the data (for example, dirty reads are
permitted), so the storage engine can use optimizations
that SELECT
does not
normally permit.
For applications that use a low-level
ISAM
-like interface,
HANDLER
makes it much easier to
port them to MySQL.
HANDLER
enables you to traverse
a database in a manner that is difficult (or even impossible)
to accomplish with SELECT
. The
HANDLER
interface is a more
natural way to look at data when working with applications
that provide an interactive user interface to the database.
HANDLER
is a somewhat low-level
statement. For example, it does not provide consistency. That is,
HANDLER ... OPEN
does not
take a snapshot of the table, and does not
lock the table. This means that after a HANDLER ...
OPEN
statement is issued, table data can be modified (by
the current session or other sessions) and these modifications
might be only partially visible to HANDLER ...
NEXT
or HANDLER ... PREV
scans.
An open handler can be closed and marked for reopen, in which case the handler loses its position in the table. This occurs when both of the following circumstances are true:
Any session executes
FLUSH TABLES
or DDL statements on the handler's table.
The session in which the handler is open executes
non-HANDLER
statements that use
tables.
INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE] [INTO]tbl_name
[(col_name
,...)] {VALUES | VALUE} ({expr
| DEFAULT},...),(...),... [ ON DUPLICATE KEY UPDATEcol_name
=expr
[,col_name
=expr
] ... ]
Or:
INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE] [INTO]tbl_name
SETcol_name
={expr
| DEFAULT}, ... [ ON DUPLICATE KEY UPDATEcol_name
=expr
[,col_name
=expr
] ... ]
Or:
INSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE] [INTO]tbl_name
[(col_name
,...)] SELECT ... [ ON DUPLICATE KEY UPDATEcol_name
=expr
[,col_name
=expr
] ... ]
INSERT
inserts new rows into an
existing table. The INSERT
... VALUES
and
INSERT ... SET
forms of the statement insert rows based on explicitly specified
values. The INSERT
... SELECT
form inserts rows selected from another table
or tables. The INSERT ...
VALUES
form with multiple value lists is supported in
MySQL 3.22.5 or later. The
INSERT ... SET
syntax is supported in MySQL 3.22.10 or later.
INSERT ...
SELECT
is discussed further in
Section 12.2.4.1, “INSERT ... SELECT Syntax”.
You can use REPLACE
instead of
INSERT
to overwrite old rows.
REPLACE
is the counterpart to
INSERT IGNORE
in
the treatment of new rows that contain unique key values that
duplicate old rows: The new rows are used to replace the old rows
rather than being discarded. See Section 12.2.6, “REPLACE Syntax”.
tbl_name
is the table into which rows
should be inserted. The columns for which the statement provides
values can be specified as follows:
You can provide a comma-separated list of column names
following the table name. In this case, a value for each named
column must be provided by the VALUES
list
or the SELECT
statement.
If you do not specify a list of column names for
INSERT ...
VALUES
or
INSERT ...
SELECT
, values for every column in the table must be
provided by the VALUES
list or the
SELECT
statement. If you do not
know the order of the columns in the table, use
DESCRIBE
to find out.
tbl_name
The SET
clause indicates the column names
explicitly.
Column values can be given in several ways:
Normally, any column not explicitly given a value is set to its default (explicit or implicit) value. For example, if you specify a column list that does not name all the columns in the table, unnamed columns are set to their default values. Default value assignment is described in Section 10.1.4, “Data Type Default Values”, and Section 1.9.6.2, “Constraints on Invalid Data”.
You can use the keyword DEFAULT
to
explicitly set a column to its default value. (New in MySQL
4.0.3.) This makes it easier to write
INSERT
statements that assign
values to all but a few columns, because it enables you to
avoid writing an incomplete VALUES
list
that does not include a value for each column in the table.
Otherwise, you would have to write out the list of column
names corresponding to each value in the
VALUES
list.
As of MySQL 4.1.0, you can use
DEFAULT(
as a more general form that can be used in expressions to
produce a given column's default value.
col_name
)
If both the column list and the VALUES
list
are empty, INSERT
creates a row
with each column set to its default value:
INSERT INTO tbl_name
() VALUES();
You can specify an expression expr
to provide a column value. This might involve type conversion
if the type of the expression does not match the type of the
column, and conversion of a given value can result in
different inserted values depending on the data type. For
example, inserting the string '1999.0e-2'
into an INT
,
FLOAT
,
DECIMAL(10,6)
, or
YEAR
column results in the
values 1999
, 19.9921
,
19.992100
, and 1999
being inserted, respectively. The reason the value stored in
the INT
and
YEAR
columns is
1999
is that the string-to-integer
conversion looks only at as much of the initial part of the
string as may be considered a valid integer or year. For the
floating-point and fixed-point columns, the
string-to-floating-point conversion considers the entire
string a valid floating-point value.
An expression expr
can refer to any
column that was set earlier in a value list. For example, you
can do this because the value for col2
refers to col1
, which has previously been
assigned:
INSERT INTO tbl_name
(col1,col2) VALUES(15,col1*2);
But the following is not legal, because the value for
col1
refers to col2
,
which is assigned after col1
:
INSERT INTO tbl_name
(col1,col2) VALUES(col2*2,15);
One exception involves columns that contain
AUTO_INCREMENT
values. Because the
AUTO_INCREMENT
value is generated after
other value assignments, any reference to an
AUTO_INCREMENT
column in the assignment
returns a 0
.
INSERT
statements that use
VALUES
syntax can insert multiple rows. To do
this, include multiple lists of column values, each enclosed
within parentheses and separated by commas. Example:
INSERT INTO tbl_name
(a,b,c) VALUES(1,2,3),(4,5,6),(7,8,9);
The values list for each row must be enclosed within parentheses. The following statement is illegal because the number of values in the list does not match the number of column names:
INSERT INTO tbl_name
(a,b,c) VALUES(1,2,3,4,5,6,7,8,9);
VALUE
is a synonym for
VALUES
in this context. Neither implies
anything about the number of values lists, and either may be used
whether there is a single values list or multiple lists.
The affected-rows value for an
INSERT
can be obtained using the
mysql_affected_rows()
C API
function (see Section 17.6.6.1, “mysql_affected_rows()”).
If you use an INSERT ...
VALUES
statement with multiple value lists or
INSERT ...
SELECT
, the statement returns an information string in
this format:
Records: 100 Duplicates: 0 Warnings: 0
Records
indicates the number of rows processed
by the statement. (This is not necessarily the number of rows
actually inserted because Duplicates
can be
nonzero.) Duplicates
indicates the number of
rows that could not be inserted because they would duplicate some
existing unique index value. Warnings
indicates
the number of attempts to insert column values that were
problematic in some way. Warnings can occur under any of the
following conditions:
Inserting NULL
into a column that has been
declared NOT NULL
. For multiple-row
INSERT
statements or
INSERT INTO ...
SELECT
statements, the column is set to the implicit
default value for the column data type. This is
0
for numeric types, the empty string
(''
) for string types, and the
“zero” value for date and time types.
INSERT INTO ...
SELECT
statements are handled the same way as
multiple-row inserts because the server does not examine the
result set from the SELECT
to
see whether it returns a single row. (For a single-row
INSERT
, no warning occurs when
NULL
is inserted into a NOT
NULL
column. Instead, the statement fails with an
error.)
Setting a numeric column to a value that lies outside the column's range. The value is clipped to the closest endpoint of the range.
Assigning a value such as '10.34 a'
to a
numeric column. The trailing nonnumeric text is stripped off
and the remaining numeric part is inserted. If the string
value has no leading numeric part, the column is set to
0
.
Inserting a string into a string column
(CHAR
,
VARCHAR
,
TEXT
, or
BLOB
) that exceeds the column's
maximum length. The value is truncated to the column's maximum
length.
Inserting a value into a date or time column that is illegal for the data type. The column is set to the appropriate zero value for the type.
If you are using the C API, the information string can be obtained
by invoking the mysql_info()
function. See Section 17.6.6.33, “mysql_info()”.
If INSERT
inserts a row into a
table that has an AUTO_INCREMENT
column, you
can find the value used for that column by using the SQL
LAST_INSERT_ID()
function. From
within the C API, use the
mysql_insert_id()
function.
However, you should note that the two functions do not always
behave identically. The behavior of
INSERT
statements with respect to
AUTO_INCREMENT
columns is discussed further in
Section 11.13, “Information Functions”, and
Section 17.6.6.35, “mysql_insert_id()”.
The INSERT
statement supports the
following modifiers:
If you use the DELAYED
keyword, the server
puts the row or rows to be inserted into a buffer, and the
client issuing the INSERT
DELAYED
statement can then continue immediately. If
the table is in use, the server holds the rows. When the table
is free, the server begins inserting rows, checking
periodically to see whether there are any new read requests
for the table. If there are, the delayed row queue is
suspended until the table becomes free again. See
Section 12.2.4.2, “INSERT DELAYED Syntax”. DELAYED
was added in MySQL 3.22.5.
DELAYED
is ignored with
INSERT ...
SELECT
or
INSERT
... ON DUPLICATE KEY UPDATE
.
If you use the LOW_PRIORITY
keyword,
execution of the INSERT
is
delayed until no other clients are reading from the table.
This includes other clients that began reading while existing
clients are reading, and while the INSERT
LOW_PRIORITY
statement is waiting. It is possible,
therefore, for a client that issues an INSERT
LOW_PRIORITY
statement to wait for a very long time
(or even forever) in a read-heavy environment. (This is in
contrast to INSERT DELAYED
,
which lets the client continue at once.) Note that
LOW_PRIORITY
should normally not be used
with MyISAM
tables because doing so
disables concurrent inserts. See
Section 7.6.3, “Concurrent Inserts”.
LOW_PRIORITY
was added in MySQL 3.22.5.
LOW_PRIORITY
and
HIGH_PRIORITY
affect only storage engines
that use only table-level locking (such as
MyISAM
, MEMORY
, and
MERGE
).
If you specify HIGH_PRIORITY
, it overrides
the effect of the
--low-priority-updates
option
if the server was started with that option. It also causes
concurrent inserts not to be used. See
Section 7.6.3, “Concurrent Inserts”.
HIGH_PRIORITY
was added in MySQL 3.23.11.
If you use the IGNORE
keyword, errors that
occur while executing the
INSERT
statement are treated as
warnings instead. For example, without
IGNORE
, a row that duplicates an existing
UNIQUE
index or PRIMARY
KEY
value in the table causes a duplicate-key error
and the statement is aborted. With IGNORE
,
the row still is not inserted, but no error is issued. Data
conversions that would trigger errors abort the statement if
IGNORE
is not specified. With
IGNORE
, invalid values are adjusted to the
closest values and inserted; warnings are produced but the
statement does not abort. You can determine with the
mysql_info()
C API function
how many rows were actually inserted into the table.
If you specify ON DUPLICATE KEY UPDATE
, and
a row is inserted that would cause a duplicate value in a
UNIQUE
index or PRIMARY
KEY
, an UPDATE
of the
old row is performed. is performed. The affected-rows value
per row is 1 if the row is inserted as a new row and 2 if an
existing row is updated. See
Section 12.2.4.3, “INSERT ... ON DUPLICATE KEY UPDATE Syntax”. ON DUPLICATE
KEY UPDATE
was added in MySQL 4.1.0.
Inserting into a table requires the
INSERT
privilege for the table. If
the ON DUPLICATE KEY UPDATE
clause is used and
a duplicate key causes an UPDATE
to
be performed instead, the statement requires the
UPDATE
privilege for the columns to
be updated. For columns that are read but not modified you need
only the SELECT
privilege (such as
for a column referenced only on the right hand side of an
col_name
=expr
assignment in an ON DUPLICATE KEY UPDATE
clause).
INSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE] [INTO]tbl_name
[(col_name
,...)] SELECT ... [ ON DUPLICATE KEY UPDATEcol_name
=expr
, ... ]
With INSERT ...
SELECT
, you can quickly insert many rows into a table
from one or many tables. For example:
INSERT INTO tbl_temp2 (fld_id) SELECT tbl_temp1.fld_order_id FROM tbl_temp1 WHERE tbl_temp1.fld_order_id > 100;
The following conditions hold for a
INSERT ...
SELECT
statements:
Prior to MySQL 4.0.1,
INSERT ...
SELECT
implicitly operates in
IGNORE
mode. As of MySQL 4.0.1, specify
IGNORE
explicitly to ignore rows that
would cause duplicate-key violations.
DELAYED
is ignored with
INSERT ...
SELECT
.
Prior to MySQL 4.0.14, the target table of the
INSERT
statement cannot
appear in the FROM
clause of the
SELECT
part of the query.
This limitation is lifted in 4.0.14. In this case, MySQL
creates a temporary table to hold the rows from the
SELECT
and then inserts those
rows into the target table. However, it remains true that
you cannot use INSERT INTO t ... SELECT ... FROM
t
when t
is a
TEMPORARY
table, because
TEMPORARY
tables cannot be referred to
twice in the same statement (see
Section B.5.7.2, “TEMPORARY Table Problems”).
AUTO_INCREMENT
columns work as usual.
To ensure that the binary log can be used to re-create the
original tables, MySQL does not permit concurrent inserts
for INSERT
... SELECT
statements.
Currently, you cannot insert into a table and select from the same table in a subquery.
To avoid ambiguous column reference problems when the
SELECT
and the
INSERT
refer to the same
table, provide a unique alias for each table used in the
SELECT
part, and qualify
column names in that part with the appropriate alias.
In the values part of ON DUPLICATE KEY
UPDATE
, you can refer to columns in other tables, as
long as you do not use GROUP BY
in the
SELECT
part. One side effect is
that you must qualify nonunique column names in the values part.
INSERT DELAYED ...
The DELAYED
option for the
INSERT
statement is a MySQL
extension to standard SQL that is very useful if you have
clients that cannot or need not wait for the
INSERT
to complete. This is a
common situation when you use MySQL for logging and you also
periodically run SELECT
and
UPDATE
statements that take a
long time to complete. DELAYED
was introduced
in MySQL 3.22.15.
When a client uses INSERT
DELAYED
, it gets an okay from the server at once, and
the row is queued to be inserted when the table is not in use by
any other thread.
Another major benefit of using INSERT
DELAYED
is that inserts from many clients are bundled
together and written in one block. This is much faster than
performing many separate inserts.
Note that INSERT DELAYED
is
slower than a normal INSERT
if
the table is not otherwise in use. There is also the additional
overhead for the server to handle a separate thread for each
table for which there are delayed rows. This means that you
should use INSERT DELAYED
only
when you are really sure that you need it.
The queued rows are held only in memory until they are inserted
into the table. This means that if you terminate
mysqld forcibly (for example, with
kill -9
) or if mysqld dies
unexpectedly, any queued rows that have not been
written to disk are lost.
There are some constraints on the use of
DELAYED
:
INSERT DELAYED
works only
with ISAM
, MyISAM
, and
(beginning with MySQL 4.1) MEMORY
tables.
For engines that do not support DELAYED
,
an error occurs.
An error occurs for INSERT
DELAYED
if used with a table that has been locked
with LOCK TABLES
because the insert must
be handled by a separate thread, not by the session that
holds the lock.
For MyISAM
tables, if there are no free
blocks in the middle of the data file, concurrent
SELECT
and
INSERT
statements are
supported. Under these circumstances, you very seldom need
to use INSERT DELAYED
with
MyISAM
.
INSERT DELAYED
should be used
only for INSERT
statements
that specify value lists. This is enforced as of MySQL
4.0.18. The server ignores DELAYED
for
INSERT ...
SELECT
or
INSERT
... ON DUPLICATE KEY UPDATE
statements.
Because the INSERT DELAYED
statement returns immediately, before the rows are inserted,
you cannot use
LAST_INSERT_ID()
to get the
AUTO_INCREMENT
value that the statement
might generate.
DELAYED
rows are not visible to
SELECT
statements until they
actually have been inserted.
INSERT DELAYED
is treated as
a normal INSERT
if the
statement inserts multiple rows and binary logging is
enabled.
DELAYED
is ignored on slave replication
servers, so that INSERT
DELAYED
is treated as a normal
INSERT
on slaves. This is
because DELAYED
could cause the slave to
have different data than the master.
Pending INSERT DELAYED
statements are lost if a table is write locked and
ALTER TABLE
is used to modify
the table structure.
The following describes in detail what happens when you use the
DELAYED
option to
INSERT
or
REPLACE
. In this description, the
“thread” is the thread that received an
INSERT DELAYED
statement and
“handler” is the thread that handles all
INSERT DELAYED
statements for a
particular table.
When a thread executes a DELAYED
statement for a table, a handler thread is created to
process all DELAYED
statements for the
table, if no such handler already exists.
The thread checks whether the handler has previously
acquired a DELAYED
lock; if not, it tells
the handler thread to do so. The DELAYED
lock can be obtained even if other threads have a
READ
or WRITE
lock on
the table. However, the handler waits for all
ALTER TABLE
locks or
FLUSH
TABLES
statements to finish, to ensure that the
table structure is up to date.
The thread executes the
INSERT
statement, but instead
of writing the row to the table, it puts a copy of the final
row into a queue that is managed by the handler thread. Any
syntax errors are noticed by the thread and reported to the
client program.
The client cannot obtain from the server the number of
duplicate rows or the AUTO_INCREMENT
value for the resulting row, because the
INSERT
returns before the
insert operation has been completed. (If you use the C API,
the mysql_info()
function
does not return anything meaningful, for the same reason.)
The binary log is updated by the handler thread when the row is inserted into the table. In case of multiple-row inserts, the binary log is updated when the first row is inserted.
Each time that
delayed_insert_limit
rows
are written, the handler checks whether any
SELECT
statements are still
pending. If so, it permits these to execute before
continuing.
When the handler has no more rows in its queue, the table is
unlocked. If no new INSERT
DELAYED
statements are received within
delayed_insert_timeout
seconds, the handler terminates.
If more than
delayed_queue_size
rows are
pending in a specific handler queue, the thread requesting
INSERT DELAYED
waits until
there is room in the queue. This is done to ensure that
mysqld does not use all memory for the
delayed memory queue.
The handler thread shows up in the MySQL process list with
delayed_insert
in the
Command
column. It is killed if you
execute a FLUSH
TABLES
statement or kill it with KILL
. However,
before exiting, it first stores all queued rows into the
table. During this time it does not accept any new
thread_id
INSERT
statements from other
threads. If you execute an INSERT
DELAYED
statement after this, a new handler thread
is created.
Note that this means that INSERT
DELAYED
statements have higher priority than
normal INSERT
statements if
there is an INSERT DELAYED
handler running. Other update statements have to wait until
the INSERT DELAYED
queue is
empty, someone terminates the handler thread (with
KILL
), or someone
executes a thread_id
FLUSH
TABLES
.
The following status variables provide information about
INSERT DELAYED
statements.
Status Variable | Meaning |
---|---|
Delayed_insert_threads | Number of handler threads |
Delayed_writes | Number of rows written with INSERT
DELAYED |
Not_flushed_delayed_rows | Number of rows waiting to be written |
You can view these variables by issuing a
SHOW STATUS
statement or by
executing a mysqladmin extended-status
command.
If you specify ON DUPLICATE KEY UPDATE
(added
in MySQL 4.1.0), and a row is inserted that would cause a
duplicate value in a UNIQUE
index or
PRIMARY KEY
, an
UPDATE
of the old row is
performed. For example, if column a
is
declared as UNIQUE
and contains the value
1
, the following two statements have
identical effect:
INSERT INTO table (a,b,c) VALUES (1,2,3) ON DUPLICATE KEY UPDATE c=c+1; UPDATE table SET c=c+1 WHERE a=1;
With ON DUPLICATE KEY UPDATE
, the
affected-rows value per row is 1 if the row is inserted as a new
row and 2 if an existing row is updated.
If column b
is also unique, the
INSERT
is equivalent to this
UPDATE
statement instead:
UPDATE table SET c=c+1 WHERE a=1 OR b=2 LIMIT 1;
If a=1 OR b=2
matches several rows, only
one row is updated. In general, you should
try to avoid using an ON DUPLICATE KEY UPDATE
clause on tables with multiple unique indexes.
The ON DUPLICATE KEY UPDATE
clause can
contain multiple column assignments, separated by commas.
As of MySQL 4.1.1, you can use the
VALUES(
function in the col_name
)UPDATE
clause to
refer to column values from the
INSERT
portion of the
INSERT ...
ON DUPLICATE KEY UPDATE
statement. In other words,
VALUES(
in the col_name
)ON DUPLICATE KEY UPDATE
clause refers
to the value of col_name
that would
be inserted, had no duplicate-key conflict occurred. This
function is especially useful in multiple-row inserts. The
VALUES()
function is meaningful
only in INSERT ... UPDATE
statements and
returns NULL
otherwise. Example:
INSERT INTO table (a,b,c) VALUES (1,2,3),(4,5,6) ON DUPLICATE KEY UPDATE c=VALUES(a)+VALUES(b);
That statement is identical to the following two statements:
INSERT INTO table (a,b,c) VALUES (1,2,3) ON DUPLICATE KEY UPDATE c=3; INSERT INTO table (a,b,c) VALUES (4,5,6) ON DUPLICATE KEY UPDATE c=9;
If a table contains an AUTO_INCREMENT
column
and INSERT
... ON DUPLICATE KEY UPDATE
inserts a row, the
LAST_INSERT_ID()
function returns
the AUTO_INCREMENT
value. If the statement
updates a row instead,
LAST_INSERT_ID()
is not
meaningful. However, you can work around this by using
LAST_INSERT_ID(
.
Suppose that expr
)id
is the
AUTO_INCREMENT
column. To make
LAST_INSERT_ID()
meaningful for
updates, insert rows as follows:
INSERT INTO table (a,b,c) VALUES (1,2,3) ON DUPLICATE KEY UPDATE id=LAST_INSERT_ID(id), c=3;
The DELAYED
option is ignored when you use
ON DUPLICATE KEY UPDATE
.
LOAD DATA [LOW_PRIORITY | CONCURRENT] [LOCAL] INFILE 'file_name
' [REPLACE | IGNORE] INTO TABLEtbl_name
[{FIELDS | COLUMNS} [TERMINATED BY 'string
'] [[OPTIONALLY] ENCLOSED BY 'char
'] [ESCAPED BY 'char
'] ] [LINES [STARTING BY 'string
'] [TERMINATED BY 'string
'] ] [IGNOREnumber
LINES] [(col_name
,...)]
The LOAD DATA
INFILE
statement reads rows from a text file into a
table at a very high speed. The file name must be given as a
literal string.
LOAD DATA
INFILE
is the complement of
SELECT ... INTO
OUTFILE
. (See Section 12.2.7, “SELECT Syntax”.) To write data
from a table to a file, use
SELECT ... INTO
OUTFILE
. To read the file back into a table, use
LOAD DATA
INFILE
. The syntax of the FIELDS
and
LINES
clauses is the same for both statements.
Both clauses are optional, but FIELDS
must
precede LINES
if both are specified.
For more information about the efficiency of
INSERT
versus
LOAD DATA
INFILE
and speeding up
LOAD DATA
INFILE
, see Section 7.3.2.1, “Speed of INSERT Statements”.
As of MySQL 4.1, the character set indicated by the
character_set_database
system
variable is used to interpret the information in the file.
SET NAMES
and the setting of the
character_set_client
system
variable do not affect interpretation of input.
LOAD DATA
INFILE
interprets all fields in the file as having the
same character set, regardless of the data types of the columns
into which field values are loaded. For proper interpretation of
file contents, you must ensure that it was written with the
correct character set. For example, if you write a data file with
mysqldump -T or by issuing a
SELECT ... INTO
OUTFILE
statement in mysql, be sure
to use a --default-character-set
option with
mysqldump or mysql so that
output is written in the character set to be used when the file is
loaded with LOAD DATA
INFILE
.
Note that it is currently not possible to load data files that use
the ucs2
character set.
You can also load data files by using the
mysqlimport utility; it operates by sending a
LOAD DATA
INFILE
statement to the server. The
--local
option causes
mysqlimport to read data files from the client
host. You can specify the
--compress
option to get
better performance over slow networks if the client and server
support the compressed protocol. See
Section 4.5.5, “mysqlimport — A Data Import Program”.
If you use LOW_PRIORITY
, execution of the
LOAD DATA
statement is delayed
until no other clients are reading from the table. This affects
only storage engines that use only table-level locking (such as
MyISAM
, MEMORY
, and
MERGE
).
If you specify CONCURRENT
with a
MyISAM
table that satisfies the condition for
concurrent inserts (that is, it contains no free blocks in the
middle), other threads can retrieve data from the table while
LOAD DATA
is executing. Using this
option affects the performance of LOAD
DATA
a bit, even if no other thread is using the table
at the same time.
CONCURRENT
is not replicated. See
Section 14.7, “Replication Features and Issues”, for more information.
The LOCAL
keyword, if specified, is interpreted
with respect to the client end of the connection:
If LOCAL
is specified, the file is read by
the client program on the client host and sent to the server.
The file can be given as a full path name to specify its exact
location. If given as a relative path name, the name is
interpreted relative to the directory in which the client
program was started.
LOCAL
is available in MySQL 3.22.6 or
later.
If LOCAL
is not specified, the file must be
located on the server host and is read directly by the server.
The server uses the following rules to locate the file:
If the file name is an absolute path name, the server uses it as given.
If the file name is a relative path name with one or more leading components, the server searches for the file relative to the server's data directory.
If a file name with no leading components is given, the server looks for the file in the database directory of the default database.
Note that, in the non-LOCAL
case, these rules
mean that a file named as ./myfile.txt
is
read from the server's data directory, whereas the file named as
myfile.txt
is read from the database
directory of the default database. For example, if
db1
is the default database, the following
LOAD DATA
statement reads the file
data.txt
from the database directory for
db1
, even though the statement explicitly loads
the file into a table in the db2
database:
LOAD DATA INFILE 'data.txt' INTO TABLE db2.my_table;
Windows path names are specified using forward slashes rather than backslashes. If you do use backslashes, you must double them.
For security reasons, when reading text files located on the
server, the files must either reside in the database directory or
be readable by all. Also, to use
LOAD DATA
INFILE
on server files, you must have the
FILE
privilege. See
Section 5.5.1, “Privileges Provided by MySQL”.
Using LOCAL
is a bit slower than letting the
server access the files directly, because the contents of the file
must be sent over the connection by the client to the server. On
the other hand, you do not need the
FILE
privilege to load local files.
With LOCAL
, the default duplicate-key handling
behavior is the same as if IGNORE
is specified;
this is because the server has no way to stop transmission of the
file in the middle of the operation. IGNORE
is
explained further later in this section.
As of MySQL 3.23.49 and MySQL 4.0.2 (4.0.13 on Windows),
LOCAL
works only if your server and your client
both have been configured to permit it. For example, if
mysqld was started with
--local-infile=0
,
LOCAL
does not work. See
Section 5.4.5, “Security Issues with LOAD DATA LOCAL”.
On Unix, if you need LOAD DATA
to
read from a pipe, you can use the following technique (the example
loads a listing of the /
directory into the
table db1.t1
):
mkfifo /mysql/data/db1/ls.dat chmod 666 /mysql/data/db1/ls.dat find / -ls > /mysql/data/db1/ls.dat & mysql -e "LOAD DATA INFILE 'ls.dat' INTO TABLE t1" db1
Note that you must run the command that generates the data to be loaded and the mysql commands either on separate terminals, or run the data generation process in the background (as shown in the preceding example). If you do not do this, the pipe will block until data is read by the mysql process.
If you are using a version of MySQL older than 3.23.25, you can
use this technique only with
LOAD DATA LOCAL
INFILE
.
If you are using MySQL before version 3.23.24, you cannot read
from a FIFO with LOAD
DATA INFILE
. If you need to read from a FIFO (for
example, the output from gunzip
), use
LOAD DATA LOCAL
INFILE
instead.
The REPLACE
and IGNORE
keywords control handling of input rows that duplicate existing
rows on unique key values:
If you specify REPLACE
, input rows replace
existing rows. In other words, rows that have the same value
for a primary key or unique index as an existing row. See
Section 12.2.6, “REPLACE Syntax”.
If you specify IGNORE
, input rows that
duplicate an existing row on a unique key value are skipped.
If you do not specify either option, the behavior depends on
whether the LOCAL
keyword is specified.
Without LOCAL
, an error occurs when a
duplicate key value is found, and the rest of the text file is
ignored. With LOCAL
, the default behavior
is the same as if IGNORE
is specified; this
is because the server has no way to stop transmission of the
file in the middle of the operation.
To ignore foreign key constraints during the load operation, issue
a SET foreign_key_checks = 0
statement before
executing LOAD DATA
.
If you use LOAD DATA
INFILE
on an empty MyISAM
table, all
nonunique indexes are created in a separate batch (as for
REPAIR TABLE
). Normally, this makes
LOAD DATA
INFILE
much faster when you have many indexes. In some
extreme cases, you can create the indexes even faster by turning
them off with ALTER TABLE ... DISABLE KEYS
before loading the file into the table and using ALTER
TABLE ... ENABLE KEYS
to re-create the indexes after
loading the file. See Section 7.3.2.1, “Speed of INSERT Statements”.
For both the LOAD DATA
INFILE
and
SELECT ... INTO
OUTFILE
statements, the syntax of the
FIELDS
and LINES
clauses is
the same. Both clauses are optional, but FIELDS
must precede LINES
if both are specified.
If you specify a FIELDS
clause, each of its
subclauses (TERMINATED BY
,
[OPTIONALLY] ENCLOSED BY
, and ESCAPED
BY
) is also optional, except that you must specify at
least one of them.
If you specify no FIELDS
or
LINES
clause, the defaults are the same as if
you had written this:
FIELDS TERMINATED BY '\t' ENCLOSED BY '' ESCAPED BY '\\' LINES TERMINATED BY '\n' STARTING BY ''
(Backslash is the MySQL escape character within strings in SQL
statements, so to specify a literal backslash, you must specify
two backslashes for the value to be interpreted as a single
backslash. The escape sequences '\t'
and
'\n'
specify tab and newline characters,
respectively.)
In other words, the defaults cause
LOAD DATA
INFILE
to act as follows when reading input:
Look for line boundaries at newlines.
Do not skip over any line prefix.
Break lines into fields at tabs.
Do not expect fields to be enclosed within any quoting characters.
Interpret characters preceded by the escape character
“\
” as escape sequences. For
example, “\t
”,
“\n
”, and
“\\
” signify tab, newline, and
backslash, respectively. See the discussion of FIELDS
ESCAPED BY
later for the full list of escape
sequences.
Conversely, the defaults cause
SELECT ... INTO
OUTFILE
to act as follows when writing output:
Write tabs between fields.
Do not enclose fields within any quoting characters.
Use “\
” to escape instances of
tab, newline, or “\
” that
occur within field values.
Write newlines at the ends of lines.
If you have generated the text file on a Windows system, you
might have to use LINES TERMINATED BY '\r\n'
to read the file properly, because Windows programs typically
use two characters as a line terminator. Some programs, such as
WordPad, might use \r
as a
line terminator when writing files. To read such files, use
LINES TERMINATED BY '\r'
.
If all the lines you want to read in have a common prefix that you
want to ignore, you can use LINES STARTING BY
'
to skip over
the prefix, and anything before it. If a line
does not include the prefix, the entire line is skipped. Suppose
that you issue the following statement:
prefix_string
'
LOAD DATA INFILE '/tmp/test.txt' INTO TABLE test FIELDS TERMINATED BY ',' LINES STARTING BY 'xxx';
If the data file looks like this:
xxx"abc",1 something xxx"def",2 "ghi",3
The resulting rows will be ("abc",1)
and
("def",2)
. The third row in the file is skipped
because it does not contain the prefix.
The IGNORE
option can be used to ignore lines at the start of
the file. For example, you can use number
LINESIGNORE 1
LINES
to skip over an initial header line containing
column names:
LOAD DATA INFILE '/tmp/test.txt' INTO TABLE test IGNORE 1 LINES;
When you use SELECT ...
INTO OUTFILE
in tandem with
LOAD DATA
INFILE
to write data from a database into a file and
then read the file back into the database later, the field- and
line-handling options for both statements must match. Otherwise,
LOAD DATA
INFILE
will not interpret the contents of the file
properly. Suppose that you use
SELECT ... INTO
OUTFILE
to write a file with fields delimited by commas:
SELECT * INTO OUTFILE 'data.txt' FIELDS TERMINATED BY ',' FROM table2;
To read the comma-delimited file back in, the correct statement would be:
LOAD DATA INFILE 'data.txt' INTO TABLE table2 FIELDS TERMINATED BY ',';
If instead you tried to read in the file with the statement shown
following, it wouldn't work because it instructs
LOAD DATA
INFILE
to look for tabs between fields:
LOAD DATA INFILE 'data.txt' INTO TABLE table2 FIELDS TERMINATED BY '\t';
The likely result is that each input line would be interpreted as a single field.
LOAD DATA
INFILE
can be used to read files obtained from external
sources. For example, many programs can export data in
comma-separated values (CSV) format, such that lines have fields
separated by commas and enclosed within double quotation marks,
with an initial line of column names. If the lines in such a file
are terminated by carriage return/newline pairs, the statement
shown here illustrates the field- and line-handling options you
would use to load the file:
LOAD DATA INFILE 'data.txt' INTO TABLE tbl_name
FIELDS TERMINATED BY ',' ENCLOSED BY '"'
LINES TERMINATED BY '\r\n'
IGNORE 1 LINES;
If the input values are not necessarily enclosed within quotation
marks, use OPTIONALLY
before the
ENCLOSED BY
keywords.
Any of the field- or line-handling options can specify an empty
string (''
). If not empty, the FIELDS
[OPTIONALLY] ENCLOSED BY
and FIELDS ESCAPED
BY
values must be a single character. The
FIELDS TERMINATED BY
, LINES STARTING
BY
, and LINES TERMINATED BY
values
can be more than one character. For example, to write lines that
are terminated by carriage return/linefeed pairs, or to read a
file containing such lines, specify a LINES TERMINATED BY
'\r\n'
clause.
To read a file containing jokes that are separated by lines
consisting of %%
, you can do this
CREATE TABLE jokes (a INT NOT NULL AUTO_INCREMENT PRIMARY KEY, joke TEXT NOT NULL); LOAD DATA INFILE '/tmp/jokes.txt' INTO TABLE jokes FIELDS TERMINATED BY '' LINES TERMINATED BY '\n%%\n' (joke);
FIELDS [OPTIONALLY] ENCLOSED BY
controls
quoting of fields. For output
(SELECT ... INTO
OUTFILE
), if you omit the word
OPTIONALLY
, all fields are enclosed by the
ENCLOSED BY
character. An example of such
output (using a comma as the field delimiter) is shown here:
"1","a string","100.20" "2","a string containing a , comma","102.20" "3","a string containing a \" quote","102.20" "4","a string containing a \", quote and comma","102.20"
If you specify OPTIONALLY
, the
ENCLOSED BY
character is used only to enclose
values from columns that have a string data type (such as
CHAR
,
BINARY
,
TEXT
, or
ENUM
):
1,"a string",100.20 2,"a string containing a , comma",102.20 3,"a string containing a \" quote",102.20 4,"a string containing a \", quote and comma",102.20
Note that occurrences of the ENCLOSED BY
character within a field value are escaped by prefixing them with
the ESCAPED BY
character. Also note that if you
specify an empty ESCAPED BY
value, it is
possible to inadvertently generate output that cannot be read
properly by LOAD DATA
INFILE
. For example, the preceding output just shown
would appear as follows if the escape character is empty. Observe
that the second field in the fourth line contains a comma
following the quote, which (erroneously) appears to terminate the
field:
1,"a string",100.20 2,"a string containing a , comma",102.20 3,"a string containing a " quote",102.20 4,"a string containing a ", quote and comma",102.20
For input, the ENCLOSED BY
character, if
present, is stripped from the ends of field values. (This is true
regardless of whether OPTIONALLY
is specified;
OPTIONALLY
has no effect on input
interpretation.) Occurrences of the ENCLOSED BY
character preceded by the ESCAPED BY
character
are interpreted as part of the current field value.
If the field begins with the ENCLOSED BY
character, instances of that character are recognized as
terminating a field value only if followed by the field or line
TERMINATED BY
sequence. To avoid ambiguity,
occurrences of the ENCLOSED BY
character within
a field value can be doubled and are interpreted as a single
instance of the character. For example, if ENCLOSED BY
'"'
is specified, quotation marks are handled as shown
here:
"The ""BIG"" boss" -> The "BIG" boss The "BIG" boss -> The "BIG" boss The ""BIG"" boss -> The ""BIG"" boss
FIELDS ESCAPED BY
controls how to read or write
special characters:
For input, if the FIELDS ESCAPED BY
character is not empty, occurrences of that character are
stripped and the following character is taken literally as
part of a field value. Some two-character sequences that are
exceptions, where the first character is the escape character.
These sequences are shown in the following table (using
“\
” for the escape character).
The rules for NULL
handling are described
later in this section.
Character | Escape Sequence |
---|---|
\0
| An ASCII NUL (0x00 ) character |
\b
| A backspace character |
\n
| A newline (linefeed) character |
\r
| A carriage return character |
\t
| A tab character. |
\Z
| ASCII 26 (Control-Z) |
\N
| NULL |
For more information about
“\
”-escape syntax, see
Section 8.1.1, “String Literals”.
If the FIELDS ESCAPED BY
character is
empty, escape-sequence interpretation does not occur.
For output, if the FIELDS ESCAPED BY
character is not empty, it is used to prefix the following
characters on output:
The FIELDS ESCAPED BY
character
The FIELDS [OPTIONALLY] ENCLOSED BY
character
The first character of the FIELDS TERMINATED
BY
and LINES TERMINATED BY
values
ASCII 0
(what is actually written
following the escape character is ASCII
“0
”, not a zero-valued
byte)
If the FIELDS ESCAPED BY
character is
empty, no characters are escaped and NULL
is output as NULL
, not
\N
. It is probably not a good idea to
specify an empty escape character, particularly if field
values in your data contain any of the characters in the list
just given.
In certain cases, field- and line-handling options interact:
If LINES TERMINATED BY
is an empty string
and FIELDS TERMINATED BY
is nonempty, lines
are also terminated with FIELDS TERMINATED
BY
.
If the FIELDS TERMINATED BY
and
FIELDS ENCLOSED BY
values are both empty
(''
), a fixed-row (nondelimited) format is
used. With fixed-row format, no delimiters are used between
fields (but you can still have a line terminator). Instead,
column values are read and written using a field width wide
enough to hold all values in the field. For
TINYINT
,
SMALLINT
,
MEDIUMINT
,
INT
, and
BIGINT
, the field widths are 4,
6, 8, 11, and 20, respectively, no matter what the declared
display width is.
LINES TERMINATED BY
is still used to
separate lines. If a line does not contain all fields, the
rest of the columns are set to their default values. If you do
not have a line terminator, you should set this to
''
. In this case, the text file must
contain all fields for each row.
Fixed-row format also affects handling of
NULL
values, as described later. Note that
fixed-size format does not work if you are using a multi-byte
character set.
Before MySQL 4.1.12, fixed-row format used the display width
of the column. For example, INT(4)
was
read or written using a field with a width of 4. However, if
the column contained wider values, they were dumped to their
full width, leading to the possibility of a
“ragged” field holding values of different
widths. Using a field wide enough to hold all values in the
field prevents this problem. However, data files written
before this change was made might not be reloaded correctly
with LOAD DATA
INFILE
for MySQL 4.1.12 and up. This change also
affects data files read by mysqlimport
and written by mysqldump --tab, which use
LOAD DATA
INFILE
and
SELECT ... INTO
OUTFILE
.
Handling of NULL
values varies according to the
FIELDS
and LINES
options in
use:
For the default FIELDS
and
LINES
values, NULL
is
written as a field value of \N
for output,
and a field value of \N
is read as
NULL
for input (assuming that the
ESCAPED BY
character is
“\
”).
If FIELDS ENCLOSED BY
is not empty, a field
containing the literal word NULL
as its
value is read as a NULL
value. This differs
from the word NULL
enclosed within
FIELDS ENCLOSED BY
characters, which is
read as the string 'NULL'
.
If FIELDS ESCAPED BY
is empty,
NULL
is written as the word
NULL
.
With fixed-row format (which is used when FIELDS
TERMINATED BY
and FIELDS ENCLOSED
BY
are both empty), NULL
is
written as an empty string. Note that this causes both
NULL
values and empty strings in the table
to be indistinguishable when written to the file because both
are written as empty strings. If you need to be able to tell
the two apart when reading the file back in, you should not
use fixed-row format.
An attempt to load NULL
into a NOT
NULL
column causes assignment of the implicit default
value for the column's data type and a warning. Implicit default
values are discussed in Section 10.1.4, “Data Type Default Values”.
Some cases are not supported by
LOAD DATA
INFILE
:
Fixed-size rows (FIELDS TERMINATED BY
and
FIELDS ENCLOSED BY
both empty) and
BLOB
or
TEXT
columns.
If you specify one separator that is the same as or a prefix
of another, LOAD
DATA INFILE
cannot interpret the input properly. For
example, the following FIELDS
clause would
cause problems:
FIELDS TERMINATED BY '"' ENCLOSED BY '"'
If FIELDS ESCAPED BY
is empty, a field
value that contains an occurrence of FIELDS ENCLOSED
BY
or LINES TERMINATED BY
followed by the FIELDS TERMINATED BY
value
causes LOAD DATA
INFILE
to stop reading a field or line too early.
This happens because
LOAD DATA
INFILE
cannot properly determine where the field or
line value ends.
The following example loads all columns of the
persondata
table:
LOAD DATA INFILE 'persondata.txt' INTO TABLE persondata;
By default, when no column list is provided at the end of the
LOAD DATA
INFILE
statement, input lines are expected to contain a
field for each table column. If you want to load only some of a
table's columns, specify a column list:
LOAD DATA INFILE 'persondata.txt' INTO TABLE persondata (col1,col2,...);
You must also specify a column list if the order of the fields in the input file differs from the order of the columns in the table. Otherwise, MySQL cannot tell how to match input fields with table columns.
If an input line has too many fields, the extra fields are ignored and the number of warnings is incremented.
If an input line has too few fields, the table columns for which input fields are missing are set to their default values. Default value assignment is described in Section 10.1.4, “Data Type Default Values”.
An empty field value is interpreted different from a missing field:
For string types, the column is set to the empty string.
For numeric types, the column is set to 0
.
For date and time types, the column is set to the appropriate “zero” value for the type. See Section 10.3, “Date and Time Types”.
These are the same values that result if you assign an empty
string explicitly to a string, numeric, or date or time type
explicitly in an INSERT
or
UPDATE
statement.
TIMESTAMP
columns are set to the
current date and time only if there is a NULL
value for the column (that is, \N
) and the
column is not declared to permit NULL
values,
or if the TIMESTAMP
column's
default value is the current timestamp and it is omitted from the
field list when a field list is specified.
LOAD DATA
INFILE
regards all input as strings, so you cannot use
numeric values for ENUM
or
SET
columns the way you can with
INSERT
statements. All
ENUM
and
SET
values must be specified as
strings.
When the LOAD DATA
INFILE
statement finishes, it returns an information
string in the following format:
Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
Warnings occur under the same circumstances as when values are
inserted using the INSERT
statement
(see Section 12.2.4, “INSERT Syntax”), except that
LOAD DATA
INFILE
also generates warnings when there are too few or
too many fields in the input row. The warnings are not stored
anywhere; the number of warnings can be used only as an indication
of whether everything went well.
From MySQL 4.1.1 on, you can use SHOW
WARNINGS
to get a list of the first
max_error_count
warnings as
information about what went wrong. See
Section 12.4.5.26, “SHOW WARNINGS Syntax”.
If you are using the C API, you can get information about the
statement by calling the
mysql_info()
function. See
Section 17.6.6.33, “mysql_info()”.
Before MySQL 4.1.1, only a warning count is available to indicate
that something went wrong. If you get warnings and want to know
exactly why you got them, one way to do this is to dump the table
into another file using
SELECT ... INTO
OUTFILE
and compare the file to your original input
file.
REPLACE [LOW_PRIORITY | DELAYED] [INTO]tbl_name
[(col_name
,...)] {VALUES | VALUE} ({expr
| DEFAULT},...),(...),...
Or:
REPLACE [LOW_PRIORITY | DELAYED] [INTO]tbl_name
SETcol_name
={expr
| DEFAULT}, ...
Or:
REPLACE [LOW_PRIORITY | DELAYED] [INTO]tbl_name
[(col_name
,...)] SELECT ...
REPLACE
works exactly like
INSERT
, except that if an old row
in the table has the same value as a new row for a
PRIMARY KEY
or a UNIQUE
index, the old row is deleted before the new row is inserted. See
Section 12.2.4, “INSERT Syntax”.
REPLACE
is a MySQL extension to the
SQL standard. It either inserts, or deletes
and inserts. For another MySQL extension to standard
SQL—that either inserts or
updates—see
Section 12.2.4.3, “INSERT ... ON DUPLICATE KEY UPDATE Syntax”.
INSERT ... ON
DUPLICATE KEY UPDATE
is available as of MySQL 4.1.0.
Note that unless the table has a PRIMARY KEY
or
UNIQUE
index, using a
REPLACE
statement makes no sense.
It becomes equivalent to INSERT
,
because there is no index to be used to determine whether a new
row duplicates another.
Values for all columns are taken from the values specified in the
REPLACE
statement. Any missing
columns are set to their default values, just as happens for
INSERT
. You cannot refer to values
from the current row and use them in the new row. If you use an
assignment such as SET
, the reference
to the column name on the right hand side is treated as
col_name
=
col_name
+ 1DEFAULT(
,
so the assignment is equivalent to col_name
)SET
.
col_name
=
DEFAULT(col_name
) + 1
To use REPLACE
, you must have both
the INSERT
and
DELETE
privileges for the table.
The REPLACE
statement returns a
count to indicate the number of rows affected. This is the sum of
the rows deleted and inserted. If the count is 1 for a single-row
REPLACE
, a row was inserted and no
rows were deleted. If the count is greater than 1, one or more old
rows were deleted before the new row was inserted. It is possible
for a single row to replace more than one old row if the table
contains multiple unique indexes and the new row duplicates values
for different old rows in different unique indexes.
The affected-rows count makes it easy to determine whether
REPLACE
only added a row or whether
it also replaced any rows: Check whether the count is 1 (added) or
greater (replaced).
If you are using the C API, the affected-rows count can be
obtained using the
mysql_affected_rows()
function.
Currently, you cannot replace into a table and select from the same table in a subquery.
MySQL uses the following algorithm for
REPLACE
(and LOAD DATA ...
REPLACE
):
Try to insert the new row into the table
While the insertion fails because a duplicate-key error occurs for a primary key or unique index:
Delete from the table the conflicting row that has the duplicate key value
Try again to insert the new row into the table
It is possible that in the case of a duplicate-key error, a
storage engine may perform the REPLACE
as an
update rather than a delete plus insert, but the semantics are the
same. There are no user-visible effects other than a possible
difference in how the storage engine increments
Handler_
status
variables.
xxx
SELECT [ALL | DISTINCT | DISTINCTROW ] [HIGH_PRIORITY] [STRAIGHT_JOIN] [SQL_SMALL_RESULT] [SQL_BIG_RESULT] [SQL_BUFFER_RESULT] [SQL_CACHE | SQL_NO_CACHE] [SQL_CALC_FOUND_ROWS]select_expr
[,select_expr
...] [FROMtable_references
[WHEREwhere_condition
] [GROUP BY {col_name
|expr
|position
} [ASC | DESC], ... [WITH ROLLUP]] [HAVINGwhere_condition
] [ORDER BY {col_name
|expr
|position
} [ASC | DESC], ...] [LIMIT {[offset
,]row_count
|row_count
OFFSEToffset
}] [PROCEDUREprocedure_name
(argument_list
)] [INTO OUTFILE 'file_name
'export_options
| INTO DUMPFILE 'file_name
' | INTO @var_name
[, @var_name
]] [FOR UPDATE | LOCK IN SHARE MODE]]
SELECT
is used to retrieve rows
selected from one or more tables. Support for
UNION
statements and subqueries is
available as of MySQL 4.0 and 4.1, respectively. See
Section 12.2.7.3, “UNION Syntax”, and Section 12.2.8, “Subquery Syntax”.
The most commonly used clauses of
SELECT
statements are these:
Each select_expr
indicates a column
that you want to retrieve. There must be at least one
select_expr
.
table_references
indicates the
table or tables from which to retrieve rows. Its syntax is
described in Section 12.2.7.1, “JOIN Syntax”.
The WHERE
clause, if given, indicates the
condition or conditions that rows must satisfy to be selected.
where_condition
is an expression
that evaluates to true for each row to be selected. The
statement selects all rows if there is no
WHERE
clause.
In the WHERE
expression, you can use any of
the functions and operators that MySQL supports, except for
aggregate (summary) functions. See
Section 8.5, “Expression Syntax”, and
Chapter 11, Functions and Operators.
SELECT
can also be used to retrieve
rows computed without reference to any table.
For example:
mysql> SELECT 1 + 1;
-> 2
From MySQL 4.1.0 on, you are permitted to specify
DUAL
as a dummy table name in situations where
no tables are referenced:
mysql> SELECT 1 + 1 FROM DUAL;
-> 2
DUAL
is purely for the convenience of people
who require that all SELECT
statements should have FROM
and possibly other
clauses. MySQL may ignore the clauses. MySQL does not require
FROM DUAL
if no tables are referenced.
In general, clauses used must be given in exactly the order shown
in the syntax description. For example, a
HAVING
clause must come after any
GROUP BY
clause and before any ORDER
BY
clause. The exception is that the
INTO
clause can appear either as shown in the
syntax description or immediately following the
select_expr
list.
The list of select_expr
terms comprises
the select list that indicates which columns to retrieve. Terms
specify a column or expression or can use
*
-shorthand:
A select list consisting only of a single unqualified
*
can be used as shorthand to select all
columns from all tables:
SELECT * FROM t1 INNER JOIN t2 ...
can
be used as a qualified shorthand to select all columns from
the named table:
tbl_name
.*
SELECT t1.*, t2.* FROM t1 INNER JOIN t2 ...
Use of an unqualified *
with other items in
the select list may produce a parse error. To avoid this
problem, use a qualified
reference
tbl_name
.*
SELECT AVG(score), t1.* FROM t1 ...
The following list provides additional information about other
SELECT
clauses:
A select_expr
can be given an alias
using AS
. The alias is
used as the expression's column name and can be used in
alias_name
GROUP BY
, ORDER BY
, or
HAVING
clauses. For example:
SELECT CONCAT(last_name,', ',first_name) AS full_name FROM mytable ORDER BY full_name;
The AS
keyword is optional when aliasing a
select_expr
with an identifier. The
preceding example could have been written like this:
SELECT CONCAT(last_name,', ',first_name) full_name FROM mytable ORDER BY full_name;
However, because the AS
is optional, a
subtle problem can occur if you forget the comma between two
select_expr
expressions: MySQL
interprets the second as an alias name. For example, in the
following statement, columnb
is treated as
an alias name:
SELECT columna columnb FROM mytable;
For this reason, it is good practice to be in the habit of
using AS
explicitly when specifying column
aliases.
It is not permissible to refer to a column alias in a
WHERE
clause, because the column value
might not yet be determined when the WHERE
clause is executed. See Section B.5.5.4, “Problems with Column Aliases”.
The FROM
clause
indicates the table or tables from which to retrieve rows. If
you name more than one table, you are performing a join. For
information on join syntax, see Section 12.2.7.1, “JOIN Syntax”. For
each table specified, you can optionally specify an alias.
table_references
tbl_name
[[AS]alias
] [index_hint
)]
The use of index hints provides the optimizer with information about how to choose indexes during query processing. For a description of the syntax for specifying these hints, see Section 12.2.7.2, “Index Hint Syntax”.
In MySQL 4.0.14, you can use SET
max_seeks_for_key=
as an alternative way to force MySQL to prefer key scans
instead of table scans. See
Section 5.1.3, “Server System Variables”.
value
You can refer to a table within the default database as
tbl_name
, or as
db_name
.tbl_name
to specify a database explicitly. You can refer to a column as
col_name
,
tbl_name
.col_name
,
or
db_name
.tbl_name
.col_name
.
You need not specify a tbl_name
or
db_name
.tbl_name
prefix for a column reference unless the reference would be
ambiguous. See Section 8.2.1, “Identifier Qualifiers”, for
examples of ambiguity that require the more explicit column
reference forms.
A table reference can be aliased using
or
tbl_name
AS
alias_name
tbl_name alias_name
:
SELECT t1.name, t2.salary FROM employee AS t1, info AS t2 WHERE t1.name = t2.name; SELECT t1.name, t2.salary FROM employee t1, info t2 WHERE t1.name = t2.name;
Columns selected for output can be referred to in
ORDER BY
and GROUP BY
clauses using column names, column aliases, or column
positions. Column positions are integers and begin with 1:
SELECT college, region, seed FROM tournament ORDER BY region, seed; SELECT college, region AS r, seed AS s FROM tournament ORDER BY r, s; SELECT college, region, seed FROM tournament ORDER BY 2, 3;
To sort in reverse order, add the DESC
(descending) keyword to the name of the column in the
ORDER BY
clause that you are sorting by.
The default is ascending order; this can be specified
explicitly using the ASC
keyword.
If ORDER BY
occurs within a subquery and
also is applied in the outer query, the outermost
ORDER BY
takes precedence. For example,
results for the following statement are sorted in descending
order, not ascending order:
(SELECT ... ORDER BY a) ORDER BY a DESC;
Use of column positions is deprecated because the syntax has been removed from the SQL standard.
If you use GROUP BY
, output rows are sorted
according to the GROUP BY
columns as if you
had an ORDER BY
for the same columns. To
avoid the overhead of sorting that GROUP BY
produces, add ORDER BY NULL
:
SELECT a, COUNT(b) FROM test_table GROUP BY a ORDER BY NULL;
MySQL extends the GROUP BY
clause as of
version 3.23.34 so that you can also specify
ASC
and DESC
after
columns named in the clause:
SELECT a, COUNT(b) FROM test_table GROUP BY a DESC;
MySQL extends the use of GROUP BY
to permit
selecting fields that are not mentioned in the GROUP
BY
clause. If you are not getting the results that
you expect from your query, please read the description of
GROUP BY
found in
Section 11.15, “Functions and Modifiers for Use with GROUP BY Clauses”.
As of MySQL 4.1.1, GROUP BY
permits a
WITH ROLLUP
modifier. See
Section 11.15.2, “GROUP BY Modifiers”.
The HAVING
clause is applied nearly last,
just before items are sent to the client, with no
optimization. (LIMIT
is applied after
HAVING
.)
A HAVING
clause can refer to any column or
alias named in a select_expr
in the
SELECT
list or in outer
subqueries, and to aggregate functions. (Standard SQL requires
that HAVING
must reference only columns in
the GROUP BY
clause or columns used in
aggregate functions.)
Do not use HAVING
for items that should be
in the WHERE
clause. For example, do not
write the following:
SELECTcol_name
FROMtbl_name
HAVINGcol_name
> 0;
Write this instead:
SELECTcol_name
FROMtbl_name
WHEREcol_name
> 0;
The HAVING
clause can refer to aggregate
functions, which the WHERE
clause cannot:
SELECT user, MAX(salary) FROM users GROUP BY user HAVING MAX(salary) > 10;
However, that does not work in older MySQL servers (before
version 3.22.5). In those versions, you can use a column alias
in the select list and refer to the alias in the
HAVING
clause:
SELECT user, MAX(salary) AS max_salary FROM users GROUP BY user HAVING max_salary>10;
MySQL permits duplicate column names. That is, there can be
more than one select_expr
with the
same name. This is an extension to standard SQL. Because MySQL
also permits GROUP BY
and
HAVING
to refer to
select_expr
values, this can result
in an ambiguity:
SELECT 12 AS a, a FROM t GROUP BY a;
In that statement, both columns have the name
a
. To ensure that the correct column is
used for grouping, use different names for each
select_expr
.
When MySQL resolves an unqualified column or alias reference
in an ORDER BY
, GROUP
BY
, or HAVING
clause, it first
searches for the name in the
select_expr
values. If the name is
not found, it looks in the columns of the tables named in the
FROM
clause.
The LIMIT
clause can be used to constrain
the number of rows returned by the
SELECT
statement.
LIMIT
takes one or two numeric arguments,
which must both be nonnegative integer constants (except when
using prepared statements).
With two arguments, the first argument specifies the offset of the first row to return, and the second specifies the maximum number of rows to return. The offset of the initial row is 0 (not 1):
SELECT * FROM tbl LIMIT 5,10; # Retrieve rows 6-15
To retrieve all rows from a certain offset up to the end of the result set, you can use some large number for the second parameter. This statement retrieves all rows from the 96th row to the last:
SELECT * FROM tbl LIMIT 95,18446744073709551615;
With one argument, the value specifies the number of rows to return from the beginning of the result set:
SELECT * FROM tbl LIMIT 5; # Retrieve first 5 rows
In other words, LIMIT
is equivalent
to row_count
LIMIT 0,
.
row_count
For prepared statements, you can use placeholders (supported
as of MySQL version 5.0.7). The following statements will
return one row from the tbl
table:
SET @a=1; PREPARE STMT FROM 'SELECT * FROM tbl LIMIT ?'; EXECUTE STMT USING @a;
The following statements will return the second to sixth row
from the tbl
table:
SET @skip=1; SET @numrows=5; PREPARE STMT FROM 'SELECT * FROM tbl LIMIT ?, ?'; EXECUTE STMT USING @skip, @numrows;
For compatibility with PostgreSQL, MySQL also supports the
LIMIT
syntax.
row_count
OFFSET
offset
If LIMIT
occurs within a subquery and also
is applied in the outer query, the outermost
LIMIT
takes precedence. For example, the
following statement produces two rows, not one:
(SELECT ... LIMIT 1) LIMIT 2;
A PROCEDURE
clause names a procedure that
should process the data in the result set. For an example, see
Section 18.3.1, “PROCEDURE ANALYSE”, which describes
ANALYSE
, a procedure that can be used to
obtain suggestions for optimal column data types that may help
reduce table sizes.
The SELECT ... INTO OUTFILE
'
form of
file_name
'SELECT
writes the selected rows
to a file. The file is created on the server host, so you must
have the FILE
privilege to use
this syntax. file_name
cannot be an
existing file, which among other things prevents files such as
/etc/passwd
and database tables from
being destroyed.
The SELECT ... INTO
OUTFILE
statement is intended primarily to let you
very quickly dump a table to a text file on the server
machine. If you want to create the resulting file on some
other host than the server host, you normally cannot use
SELECT ... INTO
OUTFILE
since there is no way to write a path to the
file relative to the server host's file system.
However, if the MySQL client software is installed on the
remote machine, you can instead use a client command such as
mysql -e "SELECT ..." >
to generate the
file on the client host.
file_name
It is also possible to create the resulting file on a different host other than the server host, if the location of the file on the remote host can be accessed using a network-mapped path on the server's file system. In this case, the presence of mysql (or some other MySQL client program) is not required on the target host.
SELECT ... INTO
OUTFILE
is the complement of
LOAD DATA
INFILE
. Column values are dumped using the
binary
character set. In effect, there is
no character set conversion. If a table contains columns in
several character sets, the output data file will as well and
you may not be able to reload the file correctly.
The syntax for the export_options
part of the statement consists of the same
FIELDS
and LINES
clauses
that are used with the
LOAD DATA
INFILE
statement. See Section 12.2.5, “LOAD DATA INFILE Syntax”,
for information about the FIELDS
and
LINES
clauses, including their default
values and permissible values.
FIELDS ESCAPED BY
controls how to write
special characters. If the FIELDS ESCAPED
BY
character is not empty, it is used as a prefix
that precedes following characters on output:
The FIELDS ESCAPED BY
character
The FIELDS [OPTIONALLY] ENCLOSED BY
character
The first character of the FIELDS TERMINATED
BY
and LINES TERMINATED BY
values
ASCII NUL
(the zero-valued byte; what
is actually written following the escape character is
ASCII “0
”, not a
zero-valued byte)
The FIELDS TERMINATED BY
, ENCLOSED
BY
, ESCAPED BY
, or LINES
TERMINATED BY
characters must
be escaped so that you can read the file back in reliably.
ASCII NUL
is escaped to make it easier to
view with some pagers.
The resulting file does not have to conform to SQL syntax, so nothing else need be escaped.
If the FIELDS ESCAPED BY
character is
empty, no characters are escaped and NULL
is output as NULL
, not
\N
. It is probably not a good idea to
specify an empty escape character, particularly if field
values in your data contain any of the characters in the list
just given.
Here is an example that produces a file in the comma-separated values (CSV) format used by many programs:
SELECT a,b,a+b INTO OUTFILE '/tmp/result.txt' FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"' LINES TERMINATED BY '\n' FROM test_table;
If you use INTO DUMPFILE
instead of
INTO OUTFILE
, MySQL writes only one row
into the file, without any column or line termination and
without performing any escape processing. This is useful if
you want to store a BLOB
value
in a file.
Any file created by INTO OUTFILE
or
INTO DUMPFILE
is writable by all users on
the server host. The reason for this is that the MySQL
server cannot create a file that is owned by anyone other
than the user under whose account it is running. (You should
never run mysqld as
root
for this and other reasons.) The
file thus must be world-writable so that you can manipulate
its contents.
As of MySQL 4.1, the INTO
clause can name a
list of one or more user-defined variables. The selected
values are assigned to the variables. The number of variables
must match the number of columns. The query should return a
single row. If the query returns no rows, error 1065 occurs
(Query was empty
). If the query returns
multiple rows, error 1172 occurs (Result consisted of
more than one row
).
The SELECT
syntax description
at the beginning this section shows the
INTO
clause near the end of the statement.
It is also possible to use INTO
immediately
following the select_expr
list.
An INTO
clause should not be used in a
nested SELECT
because such a
SELECT
must return its result
to the outer context.
If you use FOR UPDATE
with a storage engine
that uses page or row locks, rows examined by the query are
write-locked until the end of the current transaction. Using
LOCK IN SHARE MODE
sets a shared lock that
permits other transactions to read the examined rows but not
to update or delete them. See
Section 13.2.9.3, “SELECT ... FOR UPDATE and SELECT ... LOCK IN SHARE MODE Locking Reads”.
Following the SELECT
keyword, you
can use a number of options that affect the operation of the
statement. HIGH_PRIORITY
,
STRAIGHT_JOIN
, and options beginning with
SQL_
are MySQL extensions to standard SQL.
The ALL
and DISTINCT
options specify whether duplicate rows should be returned.
ALL
(the default) specifies that all
matching rows should be returned, including duplicates.
DISTINCT
specifies removal of duplicate
rows from the result set. As of MySQL 4.1, it is an error to
specify both options. DISTINCTROW
is a
synonym for DISTINCT
.
HIGH_PRIORITY
gives the
SELECT
higher priority than a
statement that updates a table. You should use this only for
queries that are very fast and must be done at once. A
SELECT HIGH_PRIORITY
query that is issued
while the table is locked for reading runs even if there is an
update statement waiting for the table to be free. This
affects only storage engines that use only table-level locking
(such as MyISAM
, MEMORY
,
and MERGE
).
HIGH_PRIORITY
cannot be used with
SELECT
statements that are part
of a UNION
.
STRAIGHT_JOIN
forces the optimizer to join
the tables in the order in which they are listed in the
FROM
clause. You can use this to speed up a
query if the optimizer joins the tables in nonoptimal order.
STRAIGHT_JOIN
also can be used in the
table_references
list. See
Section 12.2.7.1, “JOIN Syntax”.
STRAIGHT_JOIN
does not apply to any table
that the optimizer treats as a
const
or
system
table. Such a table
produces a single row, is read during the optimization phase
of query execution, and references to its columns are replaced
with the appropriate column values before query execution
proceeds. These tables will appear first in the query plan
displayed by EXPLAIN
. See
Section 7.2.1, “Optimizing Queries with EXPLAIN”. This exception may not apply
to const
or
system
tables that are used
on the NULL
-complemented side of an outer
join (that is, the right-side table of a LEFT
JOIN
or the left-side table of a RIGHT
JOIN
.
SQL_BIG_RESULT
or
SQL_SMALL_RESULT
can be used with
GROUP BY
or DISTINCT
to
tell the optimizer that the result set has many rows or is
small, respectively. For SQL_BIG_RESULT
,
MySQL directly uses disk-based temporary tables if needed, and
prefers sorting to using a temporary table with a key on the
GROUP BY
elements. For
SQL_SMALL_RESULT
, MySQL uses fast temporary
tables to store the resulting table instead of using sorting.
This should not normally be needed.
SQL_BUFFER_RESULT
forces the result to be
put into a temporary table. This helps MySQL free the table
locks early and helps in cases where it takes a long time to
send the result set to the client. This option can be used
only for top-level SELECT
statements, not for subqueries or following
UNION
.
SQL_CALC_FOUND_ROWS
(available in MySQL
4.0.0 and up) tells MySQL to calculate how many rows there
would be in the result set, disregarding any
LIMIT
clause. The number of rows can then
be retrieved with SELECT FOUND_ROWS()
. See
Section 11.13, “Information Functions”.
Before MySQL 4.1.0, this option does not work with
LIMIT 0
, which is optimized to return
instantly (resulting in a row count of 0). See
Section 7.3.1.10, “LIMIT Optimization”.
The SQL_CACHE
and
SQL_NO_CACHE
options affect caching of
query results in the query cache (see
Section 7.5.3, “The MySQL Query Cache”). SQL_CACHE
tells MySQL to store the result in the query cache if it is
cacheable and the value of the
query_cache_type
system
variable is 2
or DEMAND
.
SQL_NO_CACHE
tells MySQL not to store the
result in the query cache. For a query that uses
UNION
or subqueries, the
following rules apply:
MySQL supports the following JOIN
syntaxes
for the table_references
part of
SELECT
statements and
multiple-table DELETE
and
UPDATE
statements:
table_references:
table_reference
,table_reference
|table_reference
[INNER | CROSS] JOINtable_reference
[join_condition
] |table_reference
STRAIGHT_JOINtable_reference
|table_reference
{LEFT|RIGHT} [OUTER] JOINtable_reference
join_condition
|table_reference
NATURAL [{LEFT|RIGHT} [OUTER]] JOINtable_reference
| { OJtable_reference
LEFT OUTER JOINtable_reference
ONconditional_expr
}table_reference
:tbl_name
[[AS]alias
] [index_hint
)] |table_subquery
[AS]alias
join_condition
: ONconditional_expr
| USING (column_list
)index_hint
: USE {INDEX|KEY} (index_list
)] | IGNORE {INDEX|KEY} (index_list
)] | FORCE {INDEX|KEY} (index_list
)]index_list
:index_name
[,index_name
] ...
Index hints can be specified to affect how the MySQL optimizer makes use of indexes. For more information, see Section 12.2.7.2, “Index Hint Syntax”.
Note that several changes in join processing were made in MySQL 5.0.12 to make MySQL more compliant with standard SQL. These changes include the ability to handle nested joins (including outer joins) according to the standard. If a nested join returns results that are not what you expect, please consider upgrading to MySQL 5.0. Further details about the changes in join processing can be found at JOIN Syntax.
You should generally not have any conditions in the
ON
part that are used to restrict which rows
you want in the result set, but rather specify these conditions
in the WHERE
clause. There are exceptions to
this rule.
Note that INNER JOIN
syntax permits a
join_condition
only from MySQL 3.23.17 on.
The same is true for JOIN
and CROSS
JOIN
only as of MySQL 4.0.11.
A table reference can be aliased using
or
tbl_name
AS
alias_name
tbl_name alias_name
:
SELECT t1.name, t2.salary FROM employee AS t1, info AS t2 WHERE t1.name = t2.name; SELECT t1.name, t2.salary FROM employee t1, info t2 WHERE t1.name = t2.name;
A table_subquery
is also known as
a subquery in the FROM
clause. Such
subqueries must include an alias to
give the subquery result a table name. A trivial example
follows; see also Section 12.2.8.8, “Subqueries in the FROM Clause”.
SELECT * FROM (SELECT 1, 2, 3) AS t1;
The conditional_expr
used with
ON
is any conditional expression of the
form that can be used in a WHERE
clause.
If there is no matching row for the right table in the
ON
or USING
part in a
LEFT JOIN
, a row with all columns set to
NULL
is used for the right table. You can
use this fact to find rows in a table that have no
counterpart in another table:
SELECT left_tbl.* FROM left_tbl LEFT JOIN right_tbl ON left_tbl.id = right_tbl.id WHERE right_tbl.id IS NULL;
This example finds all rows in left_tbl
with an id
value that is not present in
right_tbl
(that is, all rows in
left_tbl
with no corresponding row in
right_tbl
). This assumes that
right_tbl.id
is declared NOT
NULL
. See
Section 7.3.1.5, “LEFT JOIN and RIGHT JOIN Optimization”.
The
USING(
clause names a list of columns that must exist in both
tables. The following two clauses are semantically
identical:
column_list
)
a LEFT JOIN b USING (c1,c2,c3) a LEFT JOIN b ON a.c1=b.c1 AND a.c2=b.c2 AND a.c3=b.c3
The NATURAL [LEFT] JOIN
of two tables is
defined to be semantically equivalent to an INNER
JOIN
or a LEFT JOIN
with a
USING
clause that names all columns that
exist in both tables.
INNER JOIN
and ,
(comma) are semantically equivalent in the absence of a join
condition: both produce a Cartesian product between the
specified tables (that is, each and every row in the first
table is joined to each and every row in the second table).
RIGHT JOIN
works analogously to
LEFT JOIN
. To keep code portable across
databases, it is recommended that you use LEFT
JOIN
instead of RIGHT JOIN
.
The { OJ ... LEFT OUTER JOIN ...}
syntax
shown in the preceding list exists only for compatibility
with ODBC. The curly braces in the syntax should be written
literally; they are not metasyntax as used elsewhere in
syntax descriptions.
SELECT left_tbl.* FROM { OJ left_tbl LEFT OUTER JOIN right_tbl ON left_tbl.id = right_tbl.id } WHERE right_tbl.id IS NULL;
STRAIGHT_JOIN
is similar to
JOIN
, except that the left table is
always read before the right table. This can be used for
those (few) cases for which the join optimizer puts the
tables in the wrong order.
Some join examples:
SELECT * FROM table1,table2 WHERE table1.id=table2.id; SELECT * FROM table1 LEFT JOIN table2 ON table1.id=table2.id; SELECT * FROM table1 LEFT JOIN table2 USING (id); SELECT * FROM table1 LEFT JOIN table2 ON table1.id=table2.id LEFT JOIN table3 ON table2.id=table3.id;
As of MySQL 3.23.12, you can provide hints to give the optimizer
information about how to choose indexes during query processing.
Section 12.2.7.1, “JOIN Syntax”, describes the general syntax for
specifying tables in a SELECT
statement. The syntax for an individual table, including that
for index hints, looks like this:
tbl_name
[[AS]alias
] [index_hint
)]index_hint
: USE {INDEX|KEY} (index_list
)] | IGNORE {INDEX|KEY} (index_list
)] | FORCE {INDEX|KEY} (index_list
)]index_list
:index_name
[,index_name
] ...
By specifying USE INDEX
(
, you can tell
MySQL to use only one of the named indexes to find rows in the
table. The alternative syntax index_list
)IGNORE INDEX
(
can be used to
tell MySQL to not use some particular index or indexes. These
hints are useful if index_list
)EXPLAIN
shows
that MySQL is using the wrong index from the list of possible
indexes.
From MySQL 4.0.9 on, you can also use FORCE
INDEX
, which acts like USE INDEX
(
but with the
addition that a table scan is assumed to be
very expensive. In other words, a table
scan is used only if there is no way to use one of the given
indexes to find rows in the table.
index_list
)
Each hint requires the names of indexes,
not the names of columns. The name of a PRIMARY
KEY
is PRIMARY
. To see the index
names for a table, use SHOW
INDEX
.
An index_name
value need not be a
full index name. It can be an unambiguous prefix of an index
name. If a prefix is ambiguous, an error occurs.
Index hints do not work for FULLTEXT
indexes.
USE INDEX
, IGNORE INDEX
,
and FORCE INDEX
affect only which indexes are
used when MySQL decides how to find rows in the table and how to
do the join. They do not affect whether an index is used when
resolving an ORDER BY
or GROUP
BY
clause.
Examples:
SELECT * FROM table1 USE INDEX (col1_index,col2_index) WHERE col1=1 AND col2=2 AND col3=3; SELECT * FROM table1 IGNORE INDEX (col3_index) WHERE col1=1 AND col2=2 AND col3=3;
Index hints are accepted but ignored for
UPDATE
statements.
SELECT ... UNION [ALL | DISTINCT] SELECT ... [UNION [ALL | DISTINCT] SELECT ...]
UNION
is used to combine the
result from multiple SELECT
statements into a single result set.
UNION
is available from MySQL
4.0.0 on.
The column names from the first
SELECT
statement are used as the
column names for the results returned. Selected columns listed
in corresponding positions of each
SELECT
statement should have the
same data type. (For example, the first column selected by the
first statement should have the same type as the first column
selected by the other statements.)
As of MySQL 4.1.1, if the data types of corresponding
SELECT
columns do not match, the
types and lengths of the columns in the
UNION
result take into account
the values retrieved by all of the
SELECT
statements. For example,
consider the following:
mysql> SELECT REPEAT('a',1) UNION SELECT REPEAT('b',10);
+---------------+
| REPEAT('a',1) |
+---------------+
| a |
| bbbbbbbbbb |
+---------------+
Before MySQL 4.1.1, only the type and length from the first
SELECT
would have been used and
the second row would have been truncated to a length of 1:
mysql> SELECT REPEAT('a',1) UNION SELECT REPEAT('b',10);
+---------------+
| REPEAT('a',1) |
+---------------+
| a |
| b |
+---------------+
The SELECT
statements are normal
select statements, but with the following restrictions:
Only the last SELECT
statement can use INTO OUTFILE
. (However,
the entire UNION
result is
written to the file.)
HIGH_PRIORITY
cannot be used with
SELECT
statements that are
part of a UNION
. If you
specify it for the first
SELECT
, it has no effect. If
you specify it for any subsequent
SELECT
statements, a syntax
error results.
The default behavior for UNION
is
that duplicate rows are removed from the result. The optional
DISTINCT
keyword (introduced in MySQL 4.0.17)
has no effect other than the default because it also specifies
duplicate-row removal. With the optional ALL
keyword, duplicate-row removal does not occur and the result
includes all matching rows from all the
SELECT
statements.
Before MySQL 4.1.2, you cannot mix
UNION ALL
and
UNION DISTINCT
in the same query. If you use ALL
for one
UNION
, it is used for all of
them. As of MySQL 4.1.2, mixed
UNION
types are treated such that
a DISTINCT
union overrides any
ALL
union to its left. A
DISTINCT
union can be produced explicitly by
using UNION
DISTINCT
or implicitly by using
UNION
with no following
DISTINCT
or ALL
keyword.
To use an ORDER BY
or
LIMIT
clause to sort or limit the entire
UNION
result, parenthesize the
individual SELECT
statements and
place the ORDER BY
or
LIMIT
after the last one. The following
example uses both clauses:
(SELECT a FROM t1 WHERE a=10 AND B=1) UNION (SELECT a FROM t2 WHERE a=11 AND B=2) ORDER BY a LIMIT 10;
This kind of ORDER BY
cannot use column
references that include a table name (that is, names in
tbl_name
.col_name
format). Instead, provide a column alias in the first
SELECT
statement and refer to the
alias in the ORDER BY
. (Alternatively, refer
to the column in the ORDER BY
using its
column position. However, use of column positions is
deprecated.)
Also, if a column to be sorted is aliased, the ORDER
BY
clause must refer to the
alias, not the column name. The first of the following
statements will work, but the second will fail with an
Unknown column 'a' in 'order clause'
error:
(SELECT a AS b FROM t) UNION (SELECT ...) ORDER BY b; (SELECT a AS b FROM t) UNION (SELECT ...) ORDER BY a;
To apply ORDER BY
or LIMIT
to an individual SELECT
, place
the clause inside the parentheses that enclose the
SELECT
:
(SELECT a FROM t1 WHERE a=10 AND B=1 ORDER BY a LIMIT 10) UNION (SELECT a FROM t2 WHERE a=11 AND B=2 ORDER BY a LIMIT 10);
However, use of ORDER BY
for individual
SELECT
statements implies nothing
about the order in which the rows appear in the final result
because UNION
by default produces
an unordered set of rows. Therefore, the use of ORDER
BY
in this context is typically in conjunction with
LIMIT
, so that it is used to determine the
subset of the selected rows to retrieve for the
SELECT
, even though it does not
necessarily affect the order of those rows in the final
UNION
result. If ORDER
BY
appears without LIMIT
in a
SELECT
, it is optimized away
because it will have no effect anyway.
To cause rows in a UNION
result
to consist of the sets of rows retrieved by each
SELECT
one after the other,
select an additional column in each
SELECT
to use as a sort column
and add an ORDER BY
following the last
SELECT
:
(SELECT 1 AS sort_col, col1a, col1b, ... FROM t1) UNION (SELECT 2, col2a, col2b, ... FROM t2) ORDER BY sort_col;
To additionally maintain sort order within individual
SELECT
results, add a secondary
column to the ORDER BY
clause:
(SELECT 1 AS sort_col, col1a, col1b, ... FROM t1) UNION (SELECT 2, col2a, col2b, ... FROM t2) ORDER BY sort_col, col1a;
Use of an additional column also enables you to determine which
SELECT
each row comes from. Extra
columns can provide other identifying information as well, such
as a string that indicates a table name.
A subquery is a SELECT
statement
within another statement.
Starting with MySQL 4.1, all subquery forms and operations that the SQL standard requires are supported, as well as a few features that are MySQL-specific.
With MySQL versions prior to 4.1, it was necessary to work around or avoid the use of subqueries. In many cases, subqueries can successfully be rewritten using joins and other methods. See Section 12.2.8.11, “Rewriting Subqueries as Joins for Earlier MySQL Versions”.
Here is an example of a subquery:
SELECT * FROM t1 WHERE column1 = (SELECT column1 FROM t2);
In this example, SELECT * FROM t1 ...
is the
outer query (or outer
statement), and (SELECT column1 FROM
t2)
is the subquery. We say that
the subquery is nested within the outer
query, and in fact it is possible to nest subqueries within other
subqueries, to a considerable depth. A subquery must always appear
within parentheses.
The main advantages of subqueries are:
They allow queries that are structured so that it is possible to isolate each part of a statement.
They provide alternative ways to perform operations that would otherwise require complex joins and unions.
Many people find subqueries more readable than complex joins or unions. Indeed, it was the innovation of subqueries that gave people the original idea of calling the early SQL “Structured Query Language.”
Here is an example statement that shows the major points about subquery syntax as specified by the SQL standard and supported in MySQL:
DELETE FROM t1 WHERE s11 > ANY (SELECT COUNT(*) /* no hint */ FROM t2 WHERE NOT EXISTS (SELECT * FROM t3 WHERE ROW(5*t2.s1,77)= (SELECT 50,11*s1 FROM t4 UNION SELECT 50,77 FROM (SELECT * FROM t5) AS t5)));
A subquery can return a scalar (a single value), a single row, a single column, or a table (one or more rows of one or more columns). These are called scalar, column, row, and table subqueries. Subqueries that return a particular kind of result often can be used only in certain contexts, as described in the following sections.
There are few restrictions on the type of statements in which
subqueries can be used. A subquery can contain many of the
keywords or clauses that an ordinary
SELECT
can contain:
DISTINCT
, GROUP BY
,
ORDER BY
, LIMIT
, joins,
index hints, UNION
constructs,
comments, functions, and so on.
One restriction is that a subquery's outer statement must be one
of: SELECT
,
INSERT
,
UPDATE
,
DELETE
,
SET
, or
DO
. Another restriction is that
currently you cannot modify a table and select from the same table
in a subquery. This applies to statements such as
DELETE
,
INSERT
,
REPLACE
, and
UPDATE
.
A more comprehensive discussion of restrictions on subquery use, including performance issues for certain forms of subquery syntax, is given in Section D.1, “Restrictions on Subqueries”.
In its simplest form, a subquery is a scalar subquery that
returns a single value. A scalar subquery is a simple operand,
and you can use it almost anywhere a single column value or
literal is legal, and you can expect it to have those
characteristics that all operands have: a data type, a length,
an indication that it can be NULL
, and so on.
For example:
CREATE TABLE t1 (s1 INT, s2 CHAR(5) NOT NULL); INSERT INTO t1 VALUES(100, 'abcde'); SELECT (SELECT s2 FROM t1);
The subquery in this SELECT
returns a single value ('abcde'
) that has a
data type of CHAR
, a length of 5,
a character set and collation equal to the defaults in effect at
CREATE TABLE
time, and an
indication that the value in the column can be
NULL
. Nullability of the value selected by a
scalar subquery is not copied because if the subquery result is
empty, the result is NULL
. For the subquery
just shown, if t1
were empty, the result
would be NULL
even though
s2
is NOT NULL
.
There are a few contexts in which a scalar subquery cannot be
used. If a statement permits only a literal value, you cannot
use a subquery. For example, LIMIT
requires
literal integer arguments, and
LOAD DATA
INFILE
requires a literal string file name. You cannot
use subqueries to supply these values.
When you see examples in the following sections that contain the
rather spartan construct (SELECT column1 FROM
t1)
, imagine that your own code contains much more
diverse and complex constructions.
Suppose that we make two tables:
CREATE TABLE t1 (s1 INT); INSERT INTO t1 VALUES (1); CREATE TABLE t2 (s1 INT); INSERT INTO t2 VALUES (2);
Then perform a SELECT
:
SELECT (SELECT s1 FROM t2) FROM t1;
The result is 2
because there is a row in
t2
containing a column s1
that has a value of 2
.
A scalar subquery can be part of an expression, but remember the parentheses, even if the subquery is an operand that provides an argument for a function. For example:
SELECT UPPER((SELECT s1 FROM t1)) FROM t2;
The most common use of a subquery is in the form:
non_subquery_operand
comparison_operator
(subquery
)
Where comparison_operator
is one of
these operators:
= > < >= <= <> != <=>
For example:
... WHERE 'a' = (SELECT column1 FROM t1)
MySQL also permits this construct:
non_subquery_operand
LIKE (subquery
)
At one time the only legal place for a subquery was on the right side of a comparison, and you might still find some old DBMSs that insist on this.
Here is an example of a common-form subquery comparison that you
cannot do with a join. It finds all the rows in table
t1
for which the column1
value is equal to a maximum value in table
t2
:
SELECT * FROM t1 WHERE column1 = (SELECT MAX(column2) FROM t2);
Here is another example, which again is impossible with a join
because it involves aggregating for one of the tables. It finds
all rows in table t1
containing a value that
occurs twice in a given column:
SELECT * FROM t1 AS t WHERE 2 = (SELECT COUNT(*) FROM t1 WHERE t1.id = t.id);
For a comparison of the subquery to a scalar, the subquery must return a scalar. For a comparison of the subquery to a row constructor, the subquery must be a row subquery that returns a row with the same number of values as the row constructor. See Section 12.2.8.5, “Row Subqueries”.
Syntax:
operand
comparison_operator
ANY (subquery
)operand
IN (subquery
)operand
comparison_operator
SOME (subquery
)
Where comparison_operator
is one of
these operators:
= > < >= <= <> !=
The ANY
keyword, which must follow a
comparison operator, means “return TRUE
if the comparison is TRUE
for
ANY
of the values in the column that the
subquery returns.” For example:
SELECT s1 FROM t1 WHERE s1 > ANY (SELECT s1 FROM t2);
Suppose that there is a row in table t1
containing (10)
. The expression is
TRUE
if table t2
contains
(21,14,7)
because there is a value
7
in t2
that is less than
10
. The expression is
FALSE
if table t2
contains
(20,10)
, or if table t2
is
empty. The expression is unknown (that is,
NULL
) if table t2
contains
(NULL,NULL,NULL)
.
When used with a subquery, the word IN
is an
alias for = ANY
. Thus, these two statements
are the same:
SELECT s1 FROM t1 WHERE s1 = ANY (SELECT s1 FROM t2); SELECT s1 FROM t1 WHERE s1 IN (SELECT s1 FROM t2);
IN
and = ANY
are not
synonyms when used with an expression list.
IN
can take an expression list, but
= ANY
cannot. See
Section 11.3.2, “Comparison Functions and Operators”.
NOT IN
is not an alias for <>
ANY
, but for <> ALL
. See
Section 12.2.8.4, “Subqueries with ALL”.
The word SOME
is an alias for
ANY
. Thus, these two statements are the same:
SELECT s1 FROM t1 WHERE s1 <> ANY (SELECT s1 FROM t2); SELECT s1 FROM t1 WHERE s1 <> SOME (SELECT s1 FROM t2);
Use of the word SOME
is rare, but this
example shows why it might be useful. To most people, the
English phrase “a is not equal to any b” means
“there is no b which is equal to a,” but that is
not what is meant by the SQL syntax. The syntax means
“there is some b to which a is not equal.” Using
<> SOME
instead helps ensure that
everyone understands the true meaning of the query.
Syntax:
operand
comparison_operator
ALL (subquery
)
The word ALL
, which must follow a comparison
operator, means “return TRUE
if the
comparison is TRUE
for ALL
of the values in the column that the subquery returns.”
For example:
SELECT s1 FROM t1 WHERE s1 > ALL (SELECT s1 FROM t2);
Suppose that there is a row in table t1
containing (10)
. The expression is
TRUE
if table t2
contains
(-5,0,+5)
because 10
is
greater than all three values in t2
. The
expression is FALSE
if table
t2
contains
(12,6,NULL,-100)
because there is a single
value 12
in table t2
that
is greater than 10
. The expression is
unknown (that is, NULL
)
if table t2
contains
(0,NULL,1)
.
Finally, the expression is TRUE
if table
t2
is empty. So, the following expression is
TRUE
when table t2
is
empty:
SELECT * FROM t1 WHERE 1 > ALL (SELECT s1 FROM t2);
But this expression is NULL
when table
t2
is empty:
SELECT * FROM t1 WHERE 1 > (SELECT s1 FROM t2);
In addition, the following expression is NULL
when table t2
is empty:
SELECT * FROM t1 WHERE 1 > ALL (SELECT MAX(s1) FROM t2);
In general, tables containing NULL
values and empty tables are
“edge cases.” When writing subqueries, always
consider whether you have taken those two possibilities into
account.
NOT IN
is an alias for <>
ALL
. Thus, these two statements are the same:
SELECT s1 FROM t1 WHERE s1 <> ALL (SELECT s1 FROM t2); SELECT s1 FROM t1 WHERE s1 NOT IN (SELECT s1 FROM t2);
The discussion to this point has been of scalar or column subqueries; that is, subqueries that return a single value or a column of values. A row subquery is a subquery variant that returns a single row and can thus return more than one column value. Legal operators for row subquery comparisons are:
= > < >= <= <> != <=>
Here are two examples:
SELECT * FROM t1 WHERE (col1,col2) = (SELECT col3, col4 FROM t2 WHERE id = 10); SELECT * FROM t1 WHERE ROW(col1,col2) = (SELECT col3, col4 FROM t2 WHERE id = 10);
For both queries, if the table t2
contains a
single row with id = 10
, the subquery returns
a single row. If this row has col3
and
col4
values equal to the
col1
and col2
values of
any rows in t1
, the WHERE
expression is TRUE
and each query returns
those t1
rows. If the t2
row col3
and col4
values
are not equal the col1
and
col2
values of any t1
row,
the expression is FALSE
and the query returns
an empty result set. The expression is
unknown (that is, NULL
)
if the subquery produces no rows. An error occurs if the
subquery produces multiple rows because a row subquery can
return at most one row.
The expressions (1,2)
and
ROW(1,2)
are sometimes called row
constructors. The two are equivalent. The row
constructor and the row returned by the subquery must contain
the same number of values.
A row constructor is used for comparisons with subqueries that return two or more columns. When a subquery returns a single column, this is regarded as a scalar value and not as a row, so a row constructor cannot be used with a subquery that does not return at least two columns. Thus, the following query fails with a syntax error:
SELECT * FROM t1 WHERE ROW(1) = (SELECT column1 FROM t2)
Row constructors are legal in other contexts. For example, the following two statements are semantically equivalent (although in MySQL 4.1 only the second one can be optimized):
SELECT * FROM t1 WHERE (column1,column2) = (1,1); SELECT * FROM t1 WHERE column1 = 1 AND column2 = 1;
The following query answers the request, “find all rows in
table t1
that also exist in table
t2
”:
SELECT column1,column2,column3 FROM t1 WHERE (column1,column2,column3) IN (SELECT column1,column2,column3 FROM t2);
If a subquery returns any rows at all, EXISTS
is
subquery
TRUE
, and NOT EXISTS
is
subquery
FALSE
. For example:
SELECT column1 FROM t1 WHERE EXISTS (SELECT * FROM t2);
Traditionally, an EXISTS
subquery starts with
SELECT *
, but it could begin with
SELECT 5
or SELECT column1
or anything at all. MySQL ignores the
SELECT
list in such a subquery,
so it makes no difference.
For the preceding example, if t2
contains any
rows, even rows with nothing but NULL
values,
the EXISTS
condition is
TRUE
. This is actually an unlikely example
because a [NOT] EXISTS
subquery almost always
contains correlations. Here are some more realistic examples:
What kind of store is present in one or more cities?
SELECT DISTINCT store_type FROM stores WHERE EXISTS (SELECT * FROM cities_stores WHERE cities_stores.store_type = stores.store_type);
What kind of store is present in no cities?
SELECT DISTINCT store_type FROM stores WHERE NOT EXISTS (SELECT * FROM cities_stores WHERE cities_stores.store_type = stores.store_type);
What kind of store is present in all cities?
SELECT DISTINCT store_type FROM stores s1 WHERE NOT EXISTS ( SELECT * FROM cities WHERE NOT EXISTS ( SELECT * FROM cities_stores WHERE cities_stores.city = cities.city AND cities_stores.store_type = stores.store_type));
The last example is a double-nested NOT
EXISTS
query. That is, it has a NOT
EXISTS
clause within a NOT EXISTS
clause. Formally, it answers the question “does a city
exist with a store that is not in
Stores
”? But it is easier to say that
a nested NOT EXISTS
answers the question
“is x
TRUE
for all y
?”
A correlated subquery is a subquery that contains a reference to a table that also appears in the outer query. For example:
SELECT * FROM t1 WHERE column1 = ANY (SELECT column1 FROM t2 WHERE t2.column2 = t1.column2);
Notice that the subquery contains a reference to a column of
t1
, even though the subquery's
FROM
clause does not mention a table
t1
. So, MySQL looks outside the subquery, and
finds t1
in the outer query.
Suppose that table t1
contains a row where
column1 = 5
and column2 =
6
; meanwhile, table t2
contains a
row where column1 = 5
and column2 =
7
. The simple expression ... WHERE column1 =
ANY (SELECT column1 FROM t2)
would be
TRUE
, but in this example, the
WHERE
clause within the subquery is
FALSE
(because (5,6)
is
not equal to (5,7)
), so the expression as a
whole is FALSE
.
Scoping rule: MySQL evaluates from inside to outside. For example:
SELECT column1 FROM t1 AS x WHERE x.column1 = (SELECT column1 FROM t2 AS x WHERE x.column1 = (SELECT column1 FROM t3 WHERE x.column2 = t3.column1));
In this statement, x.column2
must be a column
in table t2
because SELECT column1
FROM t2 AS x ...
renames t2
. It is
not a column in table t1
because
SELECT column1 FROM t1 ...
is an outer query
that is farther out.
For subqueries in HAVING
or ORDER
BY
clauses, MySQL also looks for column names in the
outer select list.
For certain cases, a correlated subquery is optimized. For example:
val
IN (SELECTkey_val
FROMtbl_name
WHEREcorrelated_condition
)
Otherwise, they are inefficient and likely to be slow. Rewriting the query as a join might improve performance.
Aggregate functions in correlated subqueries may contain outer references, provided the function contains nothing but outer references, and provided the function is not contained in another function or expression.
Subqueries are legal in a SELECT
statement's FROM
clause. The actual syntax
is:
SELECT ... FROM (subquery
) [AS]name
...
The [AS]
clause is mandatory, because every table in a
name
FROM
clause must have a name. Any columns in
the subquery
select list must have
unique names.
For the sake of illustration, assume that you have this table:
CREATE TABLE t1 (s1 INT, s2 CHAR(5), s3 FLOAT);
Here is how to use a subquery in the FROM
clause, using the example table:
INSERT INTO t1 VALUES (1,'1',1.0); INSERT INTO t1 VALUES (2,'2',2.0); SELECT sb1,sb2,sb3 FROM (SELECT s1 AS sb1, s2 AS sb2, s3*2 AS sb3 FROM t1) AS sb WHERE sb1 > 1;
Result: 2, '2', 4.0
.
Here is another example: Suppose that you want to know the average of a set of sums for a grouped table. This does not work:
SELECT AVG(SUM(column1)) FROM t1 GROUP BY column1;
However, this query provides the desired information:
SELECT AVG(sum_column1) FROM (SELECT SUM(column1) AS sum_column1 FROM t1 GROUP BY column1) AS t1;
Notice that the column name used within the subquery
(sum_column1
) is recognized in the outer
query.
Subqueries in the FROM
clause can return a
scalar, column, row, or table. Subqueries in the
FROM
clause cannot be correlated subqueries.
Subqueries in the FROM
clause are executed
even for the EXPLAIN
statement
(that is, derived temporary tables are built). This occurs
because upper-level queries need information about all tables
during the optimization phase, and the table represented by a
subquery in the FROM
clause is unavailable
unless the subquery is executed.
It is possible under certain circumstances to modify table data
using EXPLAIN
SELECT
. This can occur if the outer query accesses any
tables and an inner query invokes a stored function that changes
one or more rows of a table. Suppose that there are two tables
t1
and t2
in database
d1
, created as shown here:
mysql>CREATE DATABASE d1;
Query OK, 1 row affected (0.00 sec) mysql>USE d1;
Database changed mysql>CREATE TABLE t1 (c1 INT);
Query OK, 0 rows affected (0.15 sec) mysql>CREATE TABLE t2 (c1 INT);
Query OK, 0 rows affected (0.08 sec)
Now we create a stored function f1
which
modifies t2
:
mysql>DELIMITER //
mysql>CREATE FUNCTION f1(p1 INT) RETURNS INT
mysql>BEGIN
mysql>INSERT INTO t2 VALUES (p1);
mysql>RETURN p1;
mysql>END //
Query OK, 0 rows affected (0.01 sec) mysql>DELIMITER ;
Referencing the function directly in an
EXPLAIN
SELECT
does not have any effect on
t2
, as shown here:
mysql>SELECT * FROM t2;
Empty set (0.00 sec) mysql>EXPLAIN SELECT f1(5);
+----+-------------+-------+------+---------------+------+---------+------+------+----------------+ | id | select_type | table | type | possible_keys | key | key_len | ref | rows | Extra | +----+-------------+-------+------+---------------+------+---------+------+------+----------------+ | 1 | SIMPLE | NULL | NULL | NULL | NULL | NULL | NULL | NULL | No tables used | +----+-------------+-------+------+---------------+------+---------+------+------+----------------+ 1 row in set (0.00 sec) mysql>SELECT * FROM t2;
Empty set (0.00 sec)
This is because the SELECT
statement did not reference any tables, as can be seen in the
table
and Extra
columns of
the output. This is also true of the following nested
SELECT
:
mysql>EXPLAIN SELECT NOW() AS a1, (SELECT f1(5)) AS a2;
+----+-------------+-------+------+---------------+------+---------+------+------+----------------+ | id | select_type | table | type | possible_keys | key | key_len | ref | rows | Extra | +----+-------------+-------+------+---------------+------+---------+------+------+----------------+ | 1 | PRIMARY | NULL | NULL | NULL | NULL | NULL | NULL | NULL | No tables used | +----+-------------+-------+------+---------------+------+---------+------+------+----------------+ 1 row in set, 1 warning (0.00 sec) mysql>SHOW WARNINGS;
+-------+------+------------------------------------------+ | Level | Code | Message | +-------+------+------------------------------------------+ | Note | 1249 | Select 2 was reduced during optimization | +-------+------+------------------------------------------+ 1 row in set (0.00 sec) mysql>SELECT * FROM t2;
Empty set (0.00 sec)
However, if the outer SELECT
references any tables, the optimizer executes the statement in
the subquery as well:
mysql>EXPLAIN SELECT * FROM t1 AS a1, (SELECT f1(5)) AS a2;
+----+-------------+------------+--------+---------------+------+---------+------+------+---------------------+ | id | select_type | table | type | possible_keys | key | key_len | ref | rows | Extra | +----+-------------+------------+--------+---------------+------+---------+------+------+---------------------+ | 1 | PRIMARY | a1 | system | NULL | NULL | NULL | NULL | 0 | const row not found | | 1 | PRIMARY | <derived2> | system | NULL | NULL | NULL | NULL | 1 | | | 2 | DERIVED | NULL | NULL | NULL | NULL | NULL | NULL | NULL | No tables used | +----+-------------+------------+--------+---------------+------+---------+------+------+---------------------+ 3 rows in set (0.00 sec) mysql>SELECT * FROM t2;
+------+ | c1 | +------+ | 5 | +------+ 1 row in set (0.00 sec)
This also means that an
EXPLAIN
SELECT
statement such as the one shown here may take a
long time to execute because the
BENCHMARK()
function is executed
once for each row in t1
:
EXPLAIN SELECT * FROM t1 AS a1, (SELECT BENCHMARK(1000000, MD5(NOW())));
There are some errors that apply only to subqueries. This section describes them.
Unsupported subquery syntax:
ERROR 1235 (ER_NOT_SUPPORTED_YET) SQLSTATE = 42000 Message = "This version of MySQL doesn't yet support 'LIMIT & IN/ALL/ANY/SOME subquery'"
This means that MySQL does not support statements of the following form:
SELECT * FROM t1 WHERE s1 IN (SELECT s2 FROM t2 ORDER BY s1 LIMIT 1)
Incorrect number of columns from subquery:
ERROR 1241 (ER_OPERAND_COL) SQLSTATE = 21000 Message = "Operand should contain 1 column(s)"
This error occurs in cases like this:
SELECT (SELECT column1, column2 FROM t2) FROM t1;
You may use a subquery that returns multiple columns, if the purpose is row comparison. In other contexts, the subquery must be a scalar operand. See Section 12.2.8.5, “Row Subqueries”.
Incorrect number of rows from subquery:
ERROR 1242 (ER_SUBSELECT_NO_1_ROW) SQLSTATE = 21000 Message = "Subquery returns more than 1 row"
This error occurs for statements where the subquery must return at most one row but returns multiple rows. Consider the following example:
SELECT * FROM t1 WHERE column1 = (SELECT column1 FROM t2);
If SELECT column1 FROM t2
returns just
one row, the previous query will work. If the subquery
returns more than one row, error 1242 will occur. In that
case, the query should be rewritten as:
SELECT * FROM t1 WHERE column1 = ANY (SELECT column1 FROM t2);
Incorrectly used table in subquery:
Error 1093 (ER_UPDATE_TABLE_USED) SQLSTATE = HY000 Message = "You can't specify target table 'x' for update in FROM clause"
This error occurs in cases such as the following, which attempts to modify a table and select from the same table in the subquery:
UPDATE t1 SET column2 = (SELECT MAX(column1) FROM t1);
You can use a subquery for assignment within an
UPDATE
statement because
subqueries are legal in
UPDATE
and
DELETE
statements as well as
in SELECT
statements.
However, you cannot use the same table (in this case, table
t1
) for both the subquery
FROM
clause and the update target.
For transactional storage engines, the failure of a subquery causes the entire statement to fail. For nontransactional storage engines, data modifications made before the error was encountered are preserved.
Development is ongoing, so no optimization tip is reliable for the long term. The following list provides some interesting tricks that you might want to play with:
Use subquery clauses that affect the number or order of the rows in the subquery. For example:
SELECT * FROM t1 WHERE t1.column1 IN (SELECT column1 FROM t2 ORDER BY column1); SELECT * FROM t1 WHERE t1.column1 IN (SELECT DISTINCT column1 FROM t2); SELECT * FROM t1 WHERE EXISTS (SELECT * FROM t2 LIMIT 1);
Replace a join with a subquery. For example, try this:
SELECT DISTINCT column1 FROM t1 WHERE t1.column1 IN ( SELECT column1 FROM t2);
Instead of this:
SELECT DISTINCT t1.column1 FROM t1, t2 WHERE t1.column1 = t2.column1;
Some subqueries can be transformed to joins for compatibility with older versions of MySQL before 4.1 that do not support subqueries. However, in some cases, converting a subquery to a join may also improve performance. See Section 12.2.8.11, “Rewriting Subqueries as Joins for Earlier MySQL Versions”.
Move clauses from outside to inside the subquery. For example, use this query:
SELECT * FROM t1 WHERE s1 IN (SELECT s1 FROM t1 UNION ALL SELECT s1 FROM t2);
Instead of this query:
SELECT * FROM t1 WHERE s1 IN (SELECT s1 FROM t1) OR s1 IN (SELECT s1 FROM t2);
For another example, use this query:
SELECT (SELECT column1 + 5 FROM t1) FROM t2;
Instead of this query:
SELECT (SELECT column1 FROM t1) + 5 FROM t2;
Use a row subquery instead of a correlated subquery. For example, use this query:
SELECT * FROM t1 WHERE (column1,column2) IN (SELECT column1,column2 FROM t2);
Instead of this query:
SELECT * FROM t1 WHERE EXISTS (SELECT * FROM t2 WHERE t2.column1=t1.column1 AND t2.column2=t1.column2);
Use NOT (a = ANY (...))
rather than
a <> ALL (...)
.
Use x = ANY (
rather than table containing
(1,2)
)x=1 OR
x=2
.
Use = ANY
rather than
EXISTS
.
For uncorrelated subqueries that always return one row,
IN
is always slower than
=
. For example, use this query:
SELECT * FROM t1 WHERE t1.col_name
= (SELECT a FROM t2 WHERE b =some_const
);
Instead of this query:
SELECT * FROM t1 WHERE t1.col_name
IN (SELECT a FROM t2 WHERE b =some_const
);
These tricks might cause programs to go faster or slower. Using
MySQL facilities like the
BENCHMARK()
function, you can get
an idea about what helps in your own situation. See
Section 11.13, “Information Functions”.
Some optimizations that MySQL itself makes are:
MySQL executes uncorrelated subqueries only once. Use
EXPLAIN
to make sure that a
given subquery really is uncorrelated.
MySQL rewrites IN
,
ALL
, ANY
, and
SOME
subqueries in an attempt to take
advantage of the possibility that the select-list columns in
the subquery are indexed.
MySQL replaces subqueries of the following form with an
index-lookup function, which
EXPLAIN
describes as a
special join type
(unique_subquery
or
index_subquery
):
... IN (SELECTindexed_column
FROMsingle_table
...)
MySQL enhances expressions of the following form with an
expression involving MIN()
or
MAX()
, unless
NULL
values or empty sets are involved:
value
{ALL|ANY|SOME} {> | < | >= | <=} (uncorrelated subquery
)
For example, this WHERE
clause:
WHERE 5 > ALL (SELECT x FROM t)
might be treated by the optimizer like this:
WHERE 5 > (SELECT MAX(x) FROM t)
Before MySQL 4.1, only nested queries of the form
INSERT ... SELECT ...
and REPLACE
... SELECT ...
are supported. The
IN()
construct can be used in other contexts
to test membership in a set of values.
It is often possible to rewrite a query without a subquery:
SELECT * FROM t1 WHERE id IN (SELECT id FROM t2);
This can be rewritten as:
SELECT DISTINCT t1.* FROM t1, t2 WHERE t1.id=t2.id;
The queries:
SELECT * FROM t1 WHERE id NOT IN (SELECT id FROM t2); SELECT * FROM t1 WHERE NOT EXISTS (SELECT id FROM t2 WHERE t1.id=t2.id);
Can be rewritten as:
SELECT table1.* FROM table1 LEFT JOIN table2 ON table1.id=table2.id WHERE table2.id IS NULL;
A LEFT [OUTER] JOIN
can be faster than an
equivalent subquery because the server might be able to optimize
it better—a fact that is not specific to MySQL Server
alone. Prior to SQL-92, outer joins did not exist, so subqueries
were the only way to do certain things. Today, MySQL Server and
many other modern database systems offer a wide range of outer
join types.
For more complicated subqueries, you can often create temporary
tables to hold the subquery. In some cases, however, this option
does not work. The most frequently encountered of these cases
arises with DELETE
statements,
for which standard SQL does not support joins (except in
subqueries). For this situation, there are three options
available:
The first option is to upgrade to MySQL 4.1, which does
support subqueries in DELETE
statements.
The second option is to use a procedural programming
language (such as Perl or PHP) to submit a
SELECT
query which obtains
the primary keys for the rows to be deleted, and then use
these values to construct the appropriate
DELETE
statement
(DELETE FROM ... WHERE key_col IN (key1,
key2,...)
).
The third option is to use interactive SQL to construct a
set of DELETE
statements
automatically, using the MySQL extension
CONCAT()
(in lieu of the
standard ||
operator). For example:
SELECT CONCAT('DELETE FROM tab1 WHERE pkid = ', "'", tab1.pkid, "'", ';') FROM tab1, tab2 WHERE tab1.col1 = tab2.col2;
You can place this query in a script file, use the file as input to one instance of the mysql program, and use the program output as input to a second instance of mysql:
shell> mysql --skip-column-names mydb < myscript.sql | mysql mydb
MySQL Server 4.0 supports multiple-table
DELETE
statements that can be
used to efficiently delete rows based on information from one
table or even from many tables at the same time. Multiple-table
UPDATE
statements are also
supported as of MySQL 4.0.
Single-table syntax:
UPDATE [LOW_PRIORITY] [IGNORE]table_reference
SETcol_name1
={expr1
|DEFAULT} [,col_name2
={expr2
|DEFAULT}] ... [WHEREwhere_condition
] [ORDER BY ...] [LIMITrow_count
]
Multiple-table syntax:
UPDATE [LOW_PRIORITY] [IGNORE]table_references
SETcol_name1
={expr1
|DEFAULT} [,col_name2
={expr2
|DEFAULT}] ... [WHEREwhere_condition
]
For the single-table syntax, the
UPDATE
statement updates columns of
existing rows in the named table with new values. The
SET
clause indicates which columns to modify
and the values they should be given. Each value can be given as an
expression, or the keyword DEFAULT
to set a
column explicitly to its default value. The
WHERE
clause, if given, specifies the
conditions that identify which rows to update. With no
WHERE
clause, all rows are updated. If the
ORDER BY
clause is specified, the rows are
updated in the order that is specified. The
LIMIT
clause places a limit on the number of
rows that can be updated.
For the multiple-table syntax,
UPDATE
updates rows in each table
named in table_references
that satisfy
the conditions. Each matching row is updated once, even if it
matches the conditions multiple times. For multiple-table syntax,
ORDER BY
and LIMIT
cannot be
used.
where_condition
is an expression that
evaluates to true for each row to be updated. For expression
syntax, see Section 8.5, “Expression Syntax”.
table_references
and
where_condition
are is specified as
described in Section 12.2.7, “SELECT Syntax”.
You need the UPDATE
privilege only
for columns referenced in an UPDATE
that are actually updated. You need only the
SELECT
privilege for any columns
that are read but not modified.
The UPDATE
statement supports the
following modifiers:
With the LOW_PRIORITY
keyword, execution of
the UPDATE
is delayed until no
other clients are reading from the table. This affects only
storage engines that use only table-level locking (such as
MyISAM
, MEMORY
, and
MERGE
).
With the IGNORE
keyword, the update
statement does not abort even if errors occur during the
update. Rows for which duplicate-key conflicts occur are not
updated. Rows for which columns are updated to values that
would cause data conversion errors are updated to the closest
valid values instead.
If you access a column from the table to be updated in an
expression, UPDATE
uses the current
value of the column. For example, the following statement sets
col1
to one more than its current value:
UPDATE t1 SET col1 = col1 + 1;
The second assignment in the following statement sets
col2
to the current (updated)
col1
value, not the original
col1
value. The result is that
col1
and col2
have the same
value. This behavior differs from standard SQL.
UPDATE t1 SET col1 = col1 + 1, col2 = col1;
Single-table UPDATE
assignments are
generally evaluated from left to right. For multiple-table
updates, there is no guarantee that assignments are carried out in
any particular order.
If you set a column to the value it currently has, MySQL notices this and does not update it.
If you update a column that has been declared NOT
NULL
by setting to NULL
, the column
is set to the default value appropriate for the data type and the
warning count is incremented. The default value is
0
for numeric types, the empty string
(''
) for string types, and the
“zero” value for date and time types.
UPDATE
returns the number of rows
that were actually changed. In MySQL 3.22 or later, the
mysql_info()
C API function
returns the number of rows that were matched and updated and the
number of warnings that occurred during the
UPDATE
.
You can use LIMIT
to restrict the
scope of the row_count
UPDATE
. A
LIMIT
clause works as follows:
Before MySQL 4.0.13, LIMIT
is a
rows-affected restriction. The statement stops as soon as it
has changed row_count
rows that
satisfy the WHERE
clause.
From 4.0.13 on, LIMIT
is a rows-matched
restriction. The statement stops as soon as it has found
row_count
rows that satisfy the
WHERE
clause, whether or not they actually
were changed.
If an UPDATE
statement includes an
ORDER BY
clause, the rows are updated in the
order specified by the clause. ORDER BY
can be
used from MySQL 4.0.0. This can be useful in certain situations
that might otherwise result in an error. Suppose that a table
t
contains a column id
that
has a unique index. The following statement could fail with a
duplicate-key error, depending on the order in which rows are
updated:
UPDATE t SET id = id + 1;
For example, if the table contains 1 and 2 in the
id
column and 1 is updated to 2 before 2 is
updated to 3, an error occurs. To avoid this problem, add an
ORDER BY
clause to cause the rows with larger
id
values to be updated before those with
smaller values:
UPDATE t SET id = id + 1 ORDER BY id DESC;
Starting with MySQL 4.0.4, you can also perform
UPDATE
operations covering multiple
tables. However, you cannot use ORDER BY
or
LIMIT
with a multiple-table
UPDATE
. The
table_references
clause lists the
tables involved in the join. Its syntax is described in
Section 12.2.7.1, “JOIN Syntax”. Here is an example:
UPDATE items,month SET items.price=month.price WHERE items.id=month.id;
The preceding example shows an inner join that uses the comma
operator, but multiple-table UPDATE
statements can use any type of join permitted in
SELECT
statements, such as
LEFT JOIN
.
Before MySQL 4.0.18, you need the
UPDATE
privilege for all tables
used in a multiple-table UPDATE
,
even if they were not updated. As of MySQL 4.0.18, you need only
the SELECT
privilege for any
columns that are read but not modified.
If you use a multiple-table UPDATE
statement involving InnoDB
tables for which
there are foreign key constraints, the MySQL optimizer might
process tables in an order that differs from that of their
parent/child relationship. In this case, the statement fails and
rolls back. Instead, update a single table and rely on the
ON UPDATE
capabilities that
InnoDB
provides to cause the other tables to be
modified accordingly. See
Section 13.2.5.4, “FOREIGN KEY Constraints”.
Currently, you cannot update a table and select from the same table in a subquery.
Index hints (see Section 12.2.7.2, “Index Hint Syntax”) are accepted but
ignored for UPDATE
statements.
MySQL supports local transactions (within a given client session)
through statements such as
SET autocommit
,
START TRANSACTION
,
COMMIT
, and
ROLLBACK
. See
Section 12.3.1, “START TRANSACTION, COMMIT, and ROLLBACK Syntax”.
START TRANSACTION [WITH CONSISTENT SNAPSHOT] | BEGIN [WORK] COMMIT ROLLBACK SET autocommit = {0 | 1}
The START
TRANSACTION
or
BEGIN
statement
begins a new transaction. COMMIT
commits the current transaction, making its changes permanent.
ROLLBACK
rolls
back the current transaction, canceling its changes. The
SET autocommit
statement disables or enables the default autocommit mode for the
current session.
By default, MySQL runs with autocommit mode enabled. This means that as soon as you execute a statement that updates (modifies) a table, MySQL stores the update on disk to make it permanent. To disable autocommit mode, use the following statement:
If you are using a transaction-safe storage engine (such as
InnoDB
, BDB
, or
NDBCLUSTER
), you can disable
autocommit mode with the following statement:
SET autocommit=0;
After disabling autocommit mode by setting the
autocommit
variable to zero,
changes to transaction-safe tables (such as those for
InnoDB
or
NDBCLUSTER
) are not made permanent
immediately. You must use COMMIT
to
store your changes to disk or
ROLLBACK
to
ignore the changes.
autocommit
is a session variable
and must be set for each session. For information about how to do
this for each new connection, see the description of the
init_connect
system variable.
To disable autocommit mode for a single series of statements, use
the START
TRANSACTION
statement:
START TRANSACTION; SELECT @A:=SUM(salary) FROM table1 WHERE type=1; UPDATE table2 SET summary=@A WHERE type=1; COMMIT;
With START
TRANSACTION
, autocommit remains disabled until you end
the transaction with COMMIT
or
ROLLBACK
. The
autocommit mode then reverts to its previous state.
BEGIN
and
BEGIN WORK
are
supported as aliases of
START
TRANSACTION
for initiating a transaction.
START
TRANSACTION
was added in MySQL 4.0.11. This is standard
SQL syntax and is the recommended way to start an ad-hoc
transaction.
BEGIN
and
BEGIN WORK
are
available from MySQL 3.23.17 and 3.23.19, respectively.
Many APIs used for writing MySQL client applications (such as
JDBC) provide their own methods for starting transactions that
can (and sometimes should) be used instead of sending a
START
TRANSACTION
statement from the client. See
Chapter 17, Connectors and APIs, or the documentation for your
API, for more information.
As of MySQL 4.1.8, you can begin a transaction like this:
START TRANSACTION WITH CONSISTENT SNAPSHOT;
The WITH CONSISTENT SNAPSHOT
clause starts a
consistent read for storage engines that are capable of it. This
applies only to InnoDB
. The effect is the same
as issuing a START
TRANSACTION
followed by a
SELECT
from any
InnoDB
table. See
Section 13.2.9.2, “Consistent Nonlocking Reads”. The WITH
CONSISTENT SNAPSHOT
clause does not change the current
transaction isolation level, so it provides a consistent snapshot
only if the current isolation level is one that permits consistent
read (REPEATABLE READ
or
SERIALIZABLE
).
Beginning a transaction causes any pending transaction to be committed. See Section 12.3.3, “Statements That Cause an Implicit Commit”, for more information.
Beginning a transaction also causes table locks acquired with
LOCK TABLES
to be released, as
though you had executed
UNLOCK
TABLES
. Beginning a transaction does not release a
global read lock acquired with
FLUSH TABLES WITH READ
LOCK
.
For best results, transactions should be performed using only tables managed by a single transaction-safe storage engine. Otherwise, the following problems can occur:
If you use tables from more than one transaction-safe storage
engine (such as InnoDB
and
BDB
), and the transaction isolation level
is not SERIALIZABLE
, it is
possible that when one transaction commits, another ongoing
transaction that uses the same tables will see only some of
the changes made by the first transaction. That is, the
atomicity of transactions is not guaranteed with mixed engines
and inconsistencies can result. (If mixed-engine transactions
are infrequent, you can use
SET
TRANSACTION ISOLATION LEVEL
to set the isolation
level to SERIALIZABLE
on a
per-transaction basis as necessary.)
If you use tables that are not transaction-safe within a transaction, changes to those tables are stored at once, regardless of the status of autocommit mode.
If you issue a
ROLLBACK
statement after updating a nontransactional table within a
transaction, an
ER_WARNING_NOT_COMPLETE_ROLLBACK
warning occurs. Changes to transaction-safe tables are rolled
back, but not changes to nontransaction-safe tables.
If you are using START
TRANSACTION
or SET autocommit = 0
,
you should use the MySQL binary log for backups instead of the
older update log. Transactions are stored in the binary log in one
chunk, upon COMMIT
. Transactions
that are rolled back are not logged.
(Exception: Modifications to
nontransactional tables cannot be rolled back. If a transaction
that is rolled back includes modifications to nontransactional
tables, the entire transaction is logged with a
ROLLBACK
statement at the end to ensure that modifications to the
nontransactional tables are replicated. This is true as of MySQL
4.0.15.) See Section 5.3.4, “The Binary Log”.
You can change the isolation level for transactions with
SET TRANSACTION
ISOLATION LEVEL
. See Section 12.3.6, “SET TRANSACTION Syntax”.
Rolling back can be a slow operation that may occur implicitly
without the user having explicitly asked for it (for example, when
an error occurs). Because of this, as of MySQL 4.1.8,
SHOW PROCESSLIST
displays
Rolling back
in the State
column for the session, not only for explicit rollbacks performed
with the
ROLLBACK
statement but also for implicit rollbacks.
Some statements cannot be rolled back. In general, these include data definition language (DDL) statements, such as those that create or drop databases or those that create, drop, or alter tables.
You should design your transactions not to include such
statements. If you issue a statement early in a transaction that
cannot be rolled back, and then another statement later fails, the
full effect of the transaction cannot be rolled back in such cases
by issuing a
ROLLBACK
statement.
The statements listed in this section (and any synonyms for them)
implicitly end a transaction, as if you had done a
COMMIT
before executing the
statement.
Data definition language (DDL)
statements that define or modify database objects.
ALTER TABLE
,
CREATE INDEX
,
DROP INDEX
,
DROP TABLE
,
RENAME TABLE
.
ALTER TABLE
,
CREATE TABLE
, and
DROP TABLE
do not commit a
transaction if the TEMPORARY
keyword is
used. (This does not apply to other operations on temporary
tables such as CREATE INDEX
,
which do cause a commit.) However, although no implicit commit
occurs, neither can the statement be rolled back. Therefore,
use of such statements will violate transaction atomicity: For
example, if you use
CREATE TEMPORARY
TABLE
and then roll back the transaction, the table
remains in existence.
The CREATE TABLE
statement in
InnoDB
is processed as a single
transaction. This means that a
ROLLBACK
from the user does not undo CREATE
TABLE
statements the user made during that
transaction.
Prior to MySQL 4.0.13, CREATE
TABLE
commits a transaction if the binary update log
is enabled. The CREATE TABLE
,
CREATE DATABASE
DROP DATABASE
, and
TRUNCATE TABLE
statements cause
an implicit commit beginning with MySQL 4.1.13.
Transaction-control and locking
statements.
BEGIN
,
LOCK TABLES
, SET
autocommit = 1
(if the value is not already 1),
START
TRANSACTION
,
UNLOCK
TABLES
.
UNLOCK
TABLES
commits a transaction only if any tables
currently have been locked with LOCK
TABLES
. This does not occur for
UNLOCK
TABLES
following
FLUSH TABLES WITH READ
LOCK
because the latter statement does not acquire
table-level locks.
Transactions cannot be nested. This is a consequence of the
implicit commit performed for any current transaction when you
issue a START
TRANSACTION
statement or one of its synonyms.
Data loading statements.
LOAD MASTER DATA
.
SAVEPOINTidentifier
ROLLBACK TO SAVEPOINTidentifier
Starting from MySQL 4.0.14 and 4.1.1, InnoDB
supports the SQL statements
SAVEPOINT
and
ROLLBACK TO
SAVEPOINT
.
The SAVEPOINT
statement sets a
named transaction savepoint with a name of
identifier
. If the current transaction
has a savepoint with the same name, the old savepoint is deleted
and a new one is set.
The ROLLBACK TO
SAVEPOINT
statement rolls back a transaction to the
named savepoint without terminating the transaction. Modifications
that the current transaction made to rows after the savepoint was
set are undone in the rollback, but InnoDB
does
not release the row locks that were stored in
memory after the savepoint. (For a new inserted row, the lock
information is carried by the transaction ID stored in the row;
the lock is not separately stored in memory. In this case, the row
lock is released in the undo.) Savepoints that were set at a later
time than the named savepoint are deleted.
If the ROLLBACK TO
SAVEPOINT
statement returns the following error, it
means that no savepoint with the specified name exists:
ERROR 1181: Got error 153 during ROLLBACK
All savepoints of the current transaction are deleted if you
execute a COMMIT
, or a
ROLLBACK
that
does not name a savepoint.
LOCK TABLEStbl_name
[[AS]alias
]lock_type
[,tbl_name
[[AS]alias
]lock_type
] ...lock_type
: READ [LOCAL] | [LOW_PRIORITY] WRITE UNLOCK TABLES
MySQL enables client sessions to acquire table locks explicitly for the purpose of cooperating with other sessions for access to tables, or to prevent other sessions from modifying tables during periods when a session requires exclusive access to them. A session can acquire or release locks only for itself. One session cannot acquire locks for another session or release locks held by another session.
Locks may be used to emulate transactions or to get more speed when updating tables. This is explained in more detail later in this section.
LOCK TABLES
acquires table locks
for the current client session. As of MySQL 4.0.2, to use
LOCK TABLES
you must have the
LOCK TABLES
privilege, and the
SELECT
privilege for each table to
be locked. In MySQL 3.23, you must have
SELECT
,
INSERT
,
DELETE
, and
UPDATE
privileges for the tables.
UNLOCK
TABLES
explicitly releases any table locks held by the
current session.
Another use for
UNLOCK
TABLES
is to release the global read lock acquired with
the FLUSH TABLES WITH READ
LOCK
statement, which enables you to lock all tables in
all databases. See Section 12.4.6.2, “FLUSH Syntax”. (This is a very
convenient way to get backups if you have a file system such as
Veritas that can take snapshots in time.)
A table lock protects only against inappropriate reads or writes
by other sessions. The session holding the lock, even a read lock,
can perform table-level operations such as
DROP TABLE
. Truncate operations are
not transaction-safe, so an error occurs if the session attempts
one during an active transaction or while holding a table lock.
The following discussion applies only to
non-TEMPORARY
tables. LOCK
TABLES
is permitted (but ignored) for a
TEMPORARY
table. The table can be accessed
freely by the session within which it was created, regardless of
what other locking may be in effect. No lock is necessary because
no other session can see the table.
For information about other conditions on the use of
LOCK TABLES
and statements that
cannot be used while LOCK TABLES
is
in effect, see Section 12.3.5.2, “Table-Locking Restrictions and Conditions”
Rules for Lock Acquisition
To acquire table locks within the current session, use the
LOCK TABLES
statement. The
following lock types are available:
READ [LOCAL]
lock:
The session that holds the lock can read the table (but not write it).
Multiple sessions can acquire a READ
lock
for the table at the same time.
Other sessions can read the table without explicitly acquiring
a READ
lock.
The LOCAL
modifier enables nonconflicting
INSERT
statements (concurrent
inserts) by other sessions to execute while the lock is held.
(See Section 7.6.3, “Concurrent Inserts”.) However,
READ LOCAL
cannot be used if you are going
to manipulate the database using processes external to the
server while you hold the lock. For InnoDB
tables, READ LOCAL
is the same as
READ
as of MySQL 4.1.15. (Before that,
READ LOCAL
essentially does nothing: It
does not lock the table at all, so for
InnoDB
tables, the use of READ
LOCAL
is deprecated because a plain consistent-read
SELECT
does the same thing, and
no locks are needed.)
[LOW_PRIORITY] WRITE
lock:
The session that holds the lock can read and write the table.
Only the session that holds the lock can access the table. No other session can access it until the lock is released.
Lock requests for the table by other sessions block while the
WRITE
lock is held.
The LOW_PRIORITY
modifier affects lock
scheduling if the WRITE
lock request must
wait, as described later.
If the LOCK TABLES
statement must
wait due to locks held by other sessions on any of the tables, it
blocks until all locks can be acquired.
A session that requires locks must acquire all the locks that it
needs in a single LOCK TABLES
statement. While the locks thus obtained are held, the session can
access only the locked tables. For example, in the following
sequence of statements, an error occurs for the attempt to access
t2
because it was not locked in the
LOCK TABLES
statement:
mysql>LOCK TABLES t1 READ;
mysql>SELECT COUNT(*) FROM t1;
+----------+ | COUNT(*) | +----------+ | 3 | +----------+ mysql>SELECT COUNT(*) FROM t2;
ERROR 1100 (HY000): Table 't2' was not locked with LOCK TABLES
You cannot refer to a locked table multiple times in a single query using the same name. Use aliases instead, and obtain a separate lock for the table and each alias:
mysql>LOCK TABLE t WRITE, t AS t1 READ;
mysql>INSERT INTO t SELECT * FROM t;
ERROR 1100: Table 't' was not locked with LOCK TABLES mysql>INSERT INTO t SELECT * FROM t AS t1;
The error occurs for the first
INSERT
because there are two
references to the same name for a locked table. The second
INSERT
succeeds because the
references to the table use different names.
If your statements refer to a table by means of an alias, you must lock the table using that same alias. It does not work to lock the table without specifying the alias:
mysql>LOCK TABLE t READ;
mysql>SELECT * FROM t AS myalias;
ERROR 1100: Table 'myalias' was not locked with LOCK TABLES
Conversely, if you lock a table using an alias, you must refer to it in your statements using that alias:
mysql>LOCK TABLE t AS myalias READ;
mysql>SELECT * FROM t;
ERROR 1100: Table 't' was not locked with LOCK TABLES mysql>SELECT * FROM t AS myalias;
WRITE
locks normally have higher priority than
READ
locks to ensure that updates are processed
as soon as possible. This means that if one session obtains a
READ
lock and then another session requests a
WRITE
lock, subsequent READ
lock requests wait until the session that requested the
WRITE
lock has obtained the lock and released
it. A request for a LOW_PRIORITY WRITE
lock, by
contrast, permits subsequent READ
lock requests
by other sessions to be satisfied first if they occur while the
LOW_PRIORITY WRITE
request is waiting. You
should use LOW_PRIORITY WRITE
locks only if you
are sure that eventually there will be a time when no sessions
have a READ
lock. For InnoDB
tables in transactional mode (autocommit = 0), a waiting
LOW_PRIORITY WRITE
lock acts like a regular
WRITE
lock and causes subsequent
READ
lock requests to wait.
LOCK TABLES
acquires locks as
follows:
Sort all tables to be locked in an internally defined order. From the user standpoint, this order is undefined.
If a table is to be locked with a read and a write lock, put the write lock request before the read lock request.
Lock one table at a time until the session gets all locks.
This policy ensures that table locking is deadlock free. There
are, however, other things you need to be aware of about this
policy: If you are using a LOW_PRIORITY WRITE
lock for a table, it means only that MySQL waits for this
particular lock until there are no other sessions that want a
READ
lock. When the session has gotten the
WRITE
lock and is waiting to get the lock for
the next table in the lock table list, all other sessions wait for
the WRITE
lock to be released. If this becomes
a serious problem with your application, you should consider
converting some of your tables to transaction-safe tables.
Rules for Lock Release
When the table locks held by a session are released, they are all released at the same time. A session can release its locks explicitly, or locks may be released implicitly under certain conditions.
A session can release its locks explicitly with
UNLOCK
TABLES
.
If a session issues a LOCK
TABLES
statement to acquire a lock while already
holding locks, its existing locks are released implicitly
before the new locks are granted.
If a session begins a transaction (for example, with
START
TRANSACTION
), an implicit
UNLOCK
TABLES
is performed, which causes existing locks to
be released. (For additional information about the interaction
between table locking and transactions, see
Section 12.3.5.1, “Interaction of Table Locking and Transactions”.)
If the connection for a client session terminates, whether normally or abnormally, the server implicitly releases all table locks held by the session (transactional and nontransactional). If the client reconnects, the locks will no longer be in effect. In addition, if the client had an active transaction, the server rolls back the transaction upon disconnect, and if reconnect occurs, the new session begins with autocommit enabled. For this reason, clients may wish to disable auto-reconnect. With auto-reconnect in effect, the client is not notified if reconnect occurs but any table locks or current transaction will have been lost. With auto-reconnect disabled, if the connection drops, an error occurs for the next statement issued. The client can detect the error and take appropriate action such as reacquiring the locks or redoing the transaction. See Section 17.6.14, “Controlling Automatic Reconnection Behavior”.
If you use ALTER TABLE
on a
locked table, it may become unlocked. For example, if you
attempt a second ALTER TABLE
operation, the result may be an error Table
'
. To handle this, lock the table again prior to
the second alteration. See also
Section B.5.7.1, “Problems with ALTER TABLE”.
tbl_name
' was not locked with LOCK
TABLES
LOCK TABLES
and
UNLOCK
TABLES
interact with the use of transactions as
follows:
LOCK TABLES
is not
transaction-safe and implicitly commits any active
transaction before attempting to lock the tables.
UNLOCK
TABLES
implicitly commits any active transaction,
but only if LOCK TABLES
has
been used to acquire table locks. For example, in the
following set of statements,
UNLOCK
TABLES
releases the global read lock but does not
commit the transaction because no table locks are in effect:
FLUSH TABLES WITH READ LOCK; START TRANSACTION; SELECT ... ; UNLOCK TABLES;
Beginning a transaction (for example, with
START
TRANSACTION
) implicitly commits any current
transaction and releases existing locks.
Other statements that implicitly cause transactions to be committed do not release existing locks. For a list of such statements, see Section 12.3.3, “Statements That Cause an Implicit Commit”.
The correct way to use LOCK
TABLES
and
UNLOCK
TABLES
with transactional tables, such as
InnoDB
tables, is to begin a transaction
with SET autocommit = 0
(not
START
TRANSACTION
) followed by LOCK
TABLES
, and to not call
UNLOCK
TABLES
until you commit the transaction
explicitly. For example, if you need to write to table
t1
and read from table
t2
, you can do this:
SET autocommit=0;
LOCK TABLES t1 WRITE, t2 READ, ...;
... do something with tables t1 and t2 here ...
COMMIT;
UNLOCK TABLES;
When you call LOCK TABLES
,
InnoDB
internally takes its own table
lock, and MySQL takes its own table lock.
InnoDB
releases its internal table lock
at the next commit, but for MySQL to release its table lock,
you have to call
UNLOCK
TABLES
. You should not have
autocommit = 1
, because
then InnoDB
releases its internal table
lock immediately after the call of LOCK
TABLES
, and deadlocks can very easily happen.
Starting from 4.1.9, InnoDB
does not
acquire the internal table lock at all if
autocommit = 1
, to help old
applications avoid unnecessary deadlocks.
ROLLBACK
does not release table locks.
FLUSH TABLES WITH
READ LOCK
acquires a global read lock and not
table locks, so it is not subject to the same behavior as
LOCK TABLES
and
UNLOCK
TABLES
with respect to table locking and implicit
commits. See Section 12.4.6.2, “FLUSH Syntax”.
You can safely use KILL
to
terminate a session that is waiting for a table lock. See
Section 12.4.6.3, “KILL Syntax”.
You should not lock any tables that you are
using with INSERT DELAYED
. An
INSERT DELAYED
in this case
results in an error because the insert must be handled by a
separate thread, not by the session which holds the lock.
Normally, you do not need to lock tables, because all single
UPDATE
statements are atomic; no
other session can interfere with any other currently executing
SQL statement. However, there are a few cases when locking
tables may provide an advantage:
If you are going to run many operations on a set of
MyISAM
tables, it is much faster to lock
the tables you are going to use. Locking
MyISAM
tables speeds up inserting,
updating, or deleting on them because MySQL does not flush
the key cache for the locked tables until
UNLOCK
TABLES
is called. Normally, the key cache is
flushed after each SQL statement.
The downside to locking the tables is that no session can
update a READ
-locked table (including the
one holding the lock) and no session can access a
WRITE
-locked table other than the one
holding the lock.
If you are using tables for a nontransactional storage
engine, you must use LOCK
TABLES
if you want to ensure that no other session
modifies the tables between a
SELECT
and an
UPDATE
. The example shown
here requires LOCK TABLES
to
execute safely:
LOCK TABLES trans READ, customer WRITE; SELECT SUM(value) FROM trans WHERE customer_id=some_id
; UPDATE customer SET total_value=sum_from_previous_statement
WHERE customer_id=some_id
; UNLOCK TABLES;
Without LOCK TABLES
, it is
possible that another session might insert a new row in the
trans
table between execution of the
SELECT
and
UPDATE
statements.
You can avoid using LOCK TABLES
in many cases by using relative updates (UPDATE
customer SET
)
or the value
=value
+new_value
LAST_INSERT_ID()
function.
See Section 1.9.5.4, “Transactions and Atomic Operations”.
You can also avoid locking tables in some cases by using the
user-level advisory lock functions
GET_LOCK()
and
RELEASE_LOCK()
. These locks are
saved in a hash table in the server and implemented with
pthread_mutex_lock()
and
pthread_mutex_unlock()
for high speed. See
Section 11.14, “Miscellaneous Functions”.
See Section 7.6.1, “Internal Locking Methods”, for more information on locking policy.
SET [GLOBAL | SESSION] TRANSACTION ISOLATION LEVEL { READ UNCOMMITTED | READ COMMITTED | REPEATABLE READ | SERIALIZABLE }
This statement sets the transaction isolation level globally, for the current session, or for the next transaction:
With the GLOBAL
keyword, the statement sets
the default transaction level globally for all subsequent
sessions. Existing sessions are unaffected.
With the SESSION
keyword, the statement
sets the default transaction level for all subsequent
transactions performed within the current session.
Without any SESSION
or
GLOBAL
keyword, the statement sets the
isolation level for the next (not started) transaction
performed within the current session.
A change to the global default isolation level requires the
SUPER
privilege. Any session is
free to change its session isolation level (even in the middle of
a transaction), or the isolation level for its next transaction.
To set the global default isolation level at server startup, use
the
--transaction-isolation=
option to mysqld on the command line or in an
option file. Values of level
level
for this
option use dashes rather than spaces, so the permissible values
are READ-UNCOMMITTED
,
READ-COMMITTED
,
REPEATABLE-READ
, or
SERIALIZABLE
. For example, to
set the default isolation level to
REPEATABLE READ
, use these
lines in the [mysqld]
section of an option
file:
[mysqld] transaction-isolation = REPEATABLE-READ
To determine the global and session transaction isolation levels
at runtime, check the value of the
tx_isolation
system variable:
SELECT @@GLOBAL.tx_isolation, @@tx_isolation;
As of MySQL 4.0.5, InnoDB
supports each of the
transaction isolation levels described here using different
locking strategies. (Before 4.0.5, only
REPEATABLE READ
and
SERIALIZABLE
were available.
Before MySQL 3.23.50, SET
TRANSACTION
had no effect on InnoDB
tables.) The default level is REPEATABLE
READ
. For additional information about
InnoDB
record-level locks and how it uses them
to execute various types of statements, see
Section 13.2.9.4, “InnoDB Record, Gap, and Next-Key Locks”, and
Section 13.2.9.6, “Locks Set by Different SQL Statements in InnoDB”.
The following list describes how MySQL supports the different transaction levels:
SELECT
statements are performed
in a nonlocking fashion, but a possible earlier version of a
row might be used. Thus, using this isolation level, such
reads are not consistent. This is also called a “dirty
read.” Otherwise, this isolation level works like
READ COMMITTED
.
A somewhat Oracle-like isolation level with respect to consistent (nonlocking) reads: Each consistent read, even within the same transaction, sets and reads its own fresh snapshot. See Section 13.2.9.2, “Consistent Nonlocking Reads”.
For locking reads (SELECT
with
FOR UPDATE
or LOCK IN SHARE
MODE
), InnoDB
locks only index
records, not the gaps before them, and thus permits the free
insertion of new records next to locked records. For
UPDATE
and
DELETE
statements, locking
depends on whether the statement uses a unique index with a
unique search condition (such as WHERE id =
100
), or a range-type search condition (such as
WHERE id > 100
). For a unique index with
a unique search condition, InnoDB
locks
only the index record found, not the gap before it. For
range-type searches, InnoDB
locks the index
range scanned, using gap locks or next-key (gap plus
index-record) locks to block insertions by other sessions into
the gaps covered by the range. This is necessary because
“phantom rows” must be blocked for MySQL
replication and recovery to work.
This is the default isolation level for
InnoDB
. For consistent reads, there is an
important difference from the READ
COMMITTED
isolation level: All consistent reads
within the same transaction read the snapshot established by
the first read. This convention means that if you issue
several plain (nonlocking)
SELECT
statements within the
same transaction, these SELECT
statements are consistent also with respect to each other. See
Section 13.2.9.2, “Consistent Nonlocking Reads”.
For locking reads (SELECT
with
FOR UPDATE
or LOCK IN SHARE
MODE
), UPDATE
, and
DELETE
statements, locking
depends on whether the statement uses a unique index with a
unique search condition, or a range-type search condition. For
a unique index with a unique search condition,
InnoDB
locks only the index record found,
not the gap before it. For other search conditions,
InnoDB
locks the index range scanned, using
gap locks or next-key (gap plus index-record) locks to block
insertions by other sessions into the gaps covered by the
range.
This level is like REPEATABLE
READ
, but InnoDB
implicitly
converts all plain SELECT
statements to SELECT
... LOCK IN SHARE MODE
if autocommit is disabled. If
autocommit is enabled, the
SELECT
is its own transaction.
It therefore is known to be read only and can be serialized if
performed as a consistent (nonlocking) read and need not block
for other transactions. (This means that to force a plain
SELECT
to block if other
transactions have modified the selected rows, you should
disable autocommit.)
MySQL account information is stored in the tables of the
mysql
database. This database and the access
control system are discussed extensively in
Chapter 5, MySQL Server Administration, which you should consult
for additional details.
Some releases of MySQL introduce changes to the structure of the grant tables to add new privileges or features. Whenever you update to a new version of MySQL, you should update your grant tables to make sure that they have the current structure so that you can take advantage of any new capabilities. See Section 4.4.5, “mysql_fix_privilege_tables — Upgrade MySQL System Tables”.
DROP USERuser
[,user
] ...
The DROP USER
statement removes
one or more MySQL accounts. To use it, you must have the
DELETE
privilege for the
mysql
database. Each account is named using
the same format as for the GRANT
statement; for example,
'jeffrey'@'localhost'
. If you specify only
the user name part of the account name, a host name part of
'%'
is used. For additional information about
specifying account names, see Section 12.4.1.2, “GRANT Syntax”.
DROP USER
was added in MySQL
4.1.1. In MySQL 4.1, it serves only to remove account rows from
the user
table for accounts that have no
privileges. To remove a MySQL account completely (including all
of its privileges), you should use the following procedure,
performing the steps in the order shown:
Use SHOW GRANTS
to determine
what privileges the account has. See
Section 12.4.5.12, “SHOW GRANTS Syntax”.
Use REVOKE
to revoke the
privileges displayed by SHOW
GRANTS
. This removes rows for the account from all
the grant tables except the user
table,
and revokes any global privileges listed in the
user
table. See Section 12.4.1.2, “GRANT Syntax”.
Delete the account by using DROP
USER
to remove the user
table
row.
In MySQL 5.0.2 and up, DROP USER
removes the account row in the user
table and
also revokes the privileges held by the account. It is not
necessary to use DROP USER
in
conjunction with REVOKE
.
DROP USER
does not
automatically close any open user sessions. Rather, in the
event that a user with an open session is dropped, the
statement does not take effect until that user's session is
closed. Once the session is closed, the user is dropped, and
that user's next attempt to log in will fail. This
is by design.
Before MySQL 4.1.1, DROP USER
is
not available. You should first revoke the account privileges
using SHOW GRANTS
and
REVOKE
as just described. Then
delete the user
table row and flush the grant
tables as shown here:
mysql>DELETE FROM mysql.user
->WHERE User='
mysql>user_name
' and Host='host_name
';FLUSH PRIVILEGES;
GRANTpriv_type
[(column_list
)] [,priv_type
[(column_list
)]] ... ONpriv_level
TOuser_specification
[,user_specification
] ... [REQUIRE {NONE |ssl_option
[[AND]ssl_option
] ...}] [WITHwith_option
...]priv_level
: * | *.* |db_name
.* |db_name.tbl_name
|tbl_name
user_specification
:user
[IDENTIFIED BY [PASSWORD] 'password
']ssl_option
: SSL | X509 | CIPHER 'cipher
' | ISSUER 'issuer
' | SUBJECT 'subject
'with_option
= GRANT OPTION | MAX_QUERIES_PER_HOURcount
| MAX_UPDATES_PER_HOURcount
| MAX_CONNECTIONS_PER_HOURcount
The GRANT
statement creates MySQL
user accounts and grants rights to accounts. To use
GRANT
, you must have the
GRANT OPTION
privilege, and you
must have the privileges that you are granting.
GRANT
is implemented in MySQL
3.22.11 or later. For earlier MySQL versions, it does nothing.
The REVOKE
statement is related
to GRANT
and enables
administrators to remove account privileges. See
Section 12.4.1.3, “REVOKE Syntax”.
To determine what privileges an account has, use
SHOW GRANTS
. See
Section 12.4.5.12, “SHOW GRANTS Syntax”.
There are several aspects to the GRANT
statement, described under the folllowing topics in this
section:
Some releases of MySQL introduce changes to the structure of the grant tables to add new privileges or features. Whenever you update to a new version of MySQL, you should update your grant tables to make sure that they have the current structure so that you can take advantage of any new capabilities. See Section 4.4.5, “mysql_fix_privilege_tables — Upgrade MySQL System Tables”.
The following table summarizes the permissible
priv_type
privilege types that can be
specified for the GRANT
and
REVOKE
statements. For additional
information about these privileges, see
Section 5.5.1, “Privileges Provided by MySQL”.
Table 12.1 Permissible Privileges for GRANT and REVOKE
Privilege | Meaning |
---|---|
ALL [PRIVILEGES] | Grant all privileges at specified access level except
GRANT OPTION |
ALTER | Enable use of ALTER TABLE |
CREATE | Enable database and table creation |
CREATE TEMPORARY TABLES | Enable use of CREATE
TEMPORARY TABLE |
DELETE | Enable use of DELETE |
DROP | Enable databases, tables, and views to be dropped |
EXECUTE | Not implemented |
FILE | Enable the user to cause the server to read or write files |
GRANT OPTION | Enable privileges to be granted to or removed from other accounts |
INDEX | Enable indexes to be created or dropped |
INSERT | Enable use of INSERT |
LOCK TABLES | Enable use of LOCK TABLES on tables for
which you have the SELECT
privilege |
PROCESS | Enable the user to see all processes with SHOW
PROCESSLIST |
REFERENCES | Not implemented |
RELOAD | Enable use of FLUSH operations |
REPLICATION CLIENT | Enable the user to ask where master or slave servers are |
REPLICATION SLAVE | Enable replication slaves to read binary log events from the master |
SELECT | Enable use of SELECT |
SHOW DATABASES | Enable SHOW DATABASES to show all
databases |
SHUTDOWN | Enable use of mysqladmin shutdown |
SUPER | Enable use of other adminstrative operations such as
CHANGE MASTER TO ,
KILL ,
PURGE BINARY LOGS ,
SET
GLOBAL , and mysqladmin
debug command |
UPDATE | Enable use of UPDATE |
USAGE | Synonym for “no privileges” |
The CREATE TEMPORARY TABLES
,
EXECUTE
,
LOCK TABLES
,
REPLICATION CLIENT
,
REPLICATION SLAVE
,
SHOW DATABASES
, and
SUPER
privileges were added in
MySQL 4.0.2. To use these privileges when upgrading from an
earlier version of MySQL that does not have them, you must first
upgrade the grant tables. See
Section 4.4.5, “mysql_fix_privilege_tables — Upgrade MySQL System Tables”.
The REFERENCES
and
EXECUTE
privileges are unused in
MySQL versions up to and including the 4.1 release series.
In older MySQL versions that do not have the
SUPER
privilege, specify the
PROCESS
privilege instead.
In GRANT
statements, the
ALL [PRIVILEGES]
privilege is named by itself and cannot be specified along with
other privileges. It stands for all privileges available for the
level at which privileges are to be granted except for the
GRANT OPTION
privilege.
USAGE
can be specified to create
a user that has no privileges, or to specify the
REQUIRE
or WITH
clauses
for an account without changing its existing privileges.
MySQL account information is stored in the tables of the
mysql
database. This database and the access
control system are discussed extensively in
Section 5.5, “The MySQL Access Privilege System”, which you should consult for
additional details.
If the grant tables hold privilege rows that contain mixed-case
database or table names and the
lower_case_table_names
system
variable is set to a nonzero value,
REVOKE
cannot be used to revoke
these privileges. It will be necessary to manipulate the grant
tables directly. (GRANT
will not
create such rows when
lower_case_table_names
is set,
but such rows might have been created prior to setting that
variable.)
Privileges can be granted at several levels, depending on the
syntax used for the ON
clause. For
REVOKE
, the same
ON
syntax specifies which privileges to take
away. The examples shown here include no IDENTIFIED BY
'
clause for
brevity, but you should include one if the account does not
already exist, to avoid creating an insecure account that has no
password.
password
'
Global privileges are administrative or apply to all databases
on a given server. To assign global privileges, use ON
*.*
syntax:
GRANT ALL ON *.* TO 'someuser'@'somehost'; GRANT SELECT, INSERT ON *.* TO 'someuser'@'somehost';
Privileges also are assigned at the global level if you use
ON *
syntax and you have
not selected a default database.
The FILE
,
PROCESS
,
RELOAD
,
REPLICATION CLIENT
,
REPLICATION SLAVE
,
SHOW DATABASES
,
SHUTDOWN
, and
SUPER
privileges are
administrative and can only be granted globally.
Other privileges can be granted globally or at more specific levels.
MySQL stores global privileges in the
mysql.user
table.
Database privileges apply to all tables in a given database. To
assign database-level privileges, use ON
syntax:
db_name
.*
GRANT ALL ON mydb.* TO 'someuser'@'somehost'; GRANT SELECT, INSERT ON mydb.* TO 'someuser'@'somehost';
If you use ON *
syntax (rather than
ON *.*
and you have selected a default
database, privileges are assigned at the database level for the
default database.
The CREATE
, DROP
, and
GRANT OPTION
privileges can be
specified at the database level. Table privileges also can be
specified at the database level, in which case they apply to all
tables in the database.
MySQL stores database privileges in the
mysql.db
table.
Table privileges apply to all columns in a given table. To
assign table-level privileges, use ON
syntax:
db_name.tbl_name
GRANT ALL ON mydb.mytbl TO 'someuser'@'somehost'; GRANT SELECT, INSERT ON mydb.mytbl TO 'someuser'@'somehost';
If you specify tbl_name
rather than
db_name.tbl_name
, the statement
applies to tbl_name
in the default
database. An error occurs if there is no default database.
The permissible priv_type
values for
a table are ALTER
,
CREATE
,
DELETE
,
DROP
, GRANT
OPTION
, INDEX
,
INSERT
,
SELECT
, and
UPDATE
.
MySQL stores table privileges in the
mysql.tables_priv
table.
Column privileges apply to single columns in a given table. Each privilege to be granted at the column level must be followed by the column or columns, enclosed within parentheses.
GRANT SELECT (col1), INSERT (col1,col2) ON mydb.mytbl TO 'someuser'@'somehost';
The permissible column-level
priv_type
values are
INSERT
,
SELECT
, and
UPDATE
.
MySQL stores column privileges in the
mysql.columns_priv
table.
For the global, database, and table levels,
GRANT ALL
assigns only the privileges that exist at the level you are
granting. For example, if you use GRANT ALL ON
, that is a
database-level statement, so none of the global-only privileges
such as db_name
.*FILE
are granted.
The privileges for a database, table, or column are formed
additively as the logical OR
of the
privileges at each of the privilege levels. For example, if a
user has a global SELECT
privilege, the privilege cannot be denied by an absence of the
privilege at the database, table, or column level. Details of
the privilege-checking procedure are presented in
Section 5.5.5, “Access Control, Stage 2: Request Verification”.
MySQL enables you to grant privileges even on databases and
tables that do not exist. In such cases, the privileges to be
granted must include the CREATE
privilege. This behavior is by design, and
is intended to enable the database administrator to prepare user
accounts and privileges for databases and tables that are to be
created at a later time.
MySQL does not automatically revoke any privileges when you drop a database or table.
The user
value indicates the MySQL
account to which the GRANT
statement applies. To accommodate granting rights to users from
arbitrary hosts, MySQL supports specifying the
user
value in the form
.
If a user_name
@host_name
user_name
or
host_name
value is legal as an
unquoted identifier, you need not quote it. However, quotation
marks are necessary to specify a
user_name
string containing special
characters (such as “-
”), or a
host_name
string containing special
characters or wildcard characters (such as
“%
”); for example,
'test-user'@'%.com'
. Quote the user name and
host name separately.
You can specify wildcards in the host name. For example,
applies to user_name
@'%.example.com'user_name
for any host in
the example.com
domain, and
applies to user_name
@'192.168.1.%'user_name
for any host in
the 192.168.1
class C subnet.
The simple form user_name
is a
synonym for
.
user_name
@'%'
MySQL does not support wildcards in user
names. To refer to an anonymous user, specify an
account with an empty user name with the
GRANT
statement:
GRANT ALL ON test.* TO ''@'localhost' ...
In this case, any user who connects from the local host with the correct password for the anonymous user will be permitted access, with the privileges associated with the anonymous-user account.
For additional information about user name and host name values in account names, see Section 5.5.3, “Specifying Account Names”.
To specify quoted values, quote database, table, column, and routine names as identifiers. Quote user names and host names as identifiers or as strings. Quote passwords as strings. For string-quoting and identifier-quoting guidelines, see Section 8.1.1, “String Literals”, and Section 8.2, “Database, Table, Index, Column, and Alias Names”.
The “_
” and
“%
” wildcards are permitted when
specifying database names in
GRANT
statements that grant
privileges at the global or database levels. This means, for
example, that if you want to use a
“_
” character as part of a
database name, you should specify it as
“\_
” in the
GRANT
statement, to prevent the
user from being able to access additional databases matching the
wildcard pattern; for example, GRANT ... ON
`foo\_bar`.* TO ...
.
If you permit anonymous users to connect to the MySQL server,
you should also grant privileges to all local users as
.
Otherwise, the anonymous user account for
user_name
@localhostlocalhost
in the
mysql.user
table (created during MySQL
installation) is used when named users try to log in to the
MySQL server from the local machine. For details, see
Section 5.5.4, “Access Control, Stage 1: Connection Verification”.
To determine whether the preceding warning applies to you, execute the following query, which lists any anonymous users:
SELECT Host, User FROM mysql.user WHERE User='';
To avoid the problem just described, delete the local anonymous user account using this statement:
DROP USER ''@'localhost';
GRANT
supports host names up to
60 characters long. Database, table, and column names can be up
to 64 characters. User names can be up to 16 characters.
The permissible length for user names cannot be
changed by altering the mysql.user
table.
Attempting to do so results in unpredictable behavior which
may even make it impossible for users to log in to the MySQL
server. You should never alter any of the tables in
the mysql
database in any manner whatsoever
except by means of the procedure described in
Section 4.4.5, “mysql_fix_privilege_tables — Upgrade MySQL System Tables”.
In MySQL 3.22.12 or later, if the account named in a
GRANT
statement does not exist in
the mysql.user
table,
GRANT
creates it. If you specify
no IDENTIFIED BY
clause or provide an empty
password, the user has no password. This is very
insecure.
When the IDENTIFIED BY
clause is present and
you have global grant privileges, the password becomes the new
password for the account, even if the account exists and already
has a password.
In the IDENTIFIED BY
clause, the password
should be given as the literal plaintext password value:
GRANT ... IDENTIFIED BY 'mypass';
To avoid specifying the plaintext password if you know its hash
value (the value that PASSWORD()
would return for the password), specify the hash value preceded
by the keyword PASSWORD
:
GRANT ... IDENTIFIED BY PASSWORD '*90E462C37378CED12064BB3388827D2BA3A9B689';
For additional information about setting passwords, see Section 5.6.5, “Assigning Account Passwords”.
GRANT
may be recorded in server
logs or in a history file such as
~/.mysql_history
, which means that
plaintext passwords may be read by anyone having read access
to that information. See Section 5.4.2, “Password Security in MySQL”.
The WITH
clause is used for several purposes:
To enable a user to grant privileges to other users
To specify resource limits for a user
To specify whether and how a user must use secure connections to the server
The WITH GRANT OPTION
clause gives the user
the ability to give to other users any privileges the user has
at the specified privilege level. You should be careful to whom
you give the GRANT OPTION
privilege because two users with different privileges may be
able to combine privileges!
You cannot grant another user a privilege which you yourself do
not have; the GRANT OPTION
privilege enables you to assign only those privileges which you
yourself possess.
Be aware that when you grant a user the
GRANT OPTION
privilege at a
particular privilege level, any privileges the user possesses
(or may be given in the future) at that level can also be
granted by that user to other users. Suppose that you grant a
user the INSERT
privilege on a
database. If you then grant the
SELECT
privilege on the database
and specify WITH GRANT OPTION
, that user can
give to other users not only the
SELECT
privilege, but also
INSERT
. If you then grant the
UPDATE
privilege to the user on
the database, the user can grant
INSERT
,
SELECT
, and
UPDATE
.
For a nonadministrative user, you should not grant the
ALTER
privilege globally or for
the mysql
database. If you do that, the user
can try to subvert the privilege system by renaming tables!
For additional information about security risks associated with particular privileges, see Section 5.5.1, “Privileges Provided by MySQL”.
Several WITH
clause options specify limits on
use of server resources by an account. The
MAX_QUERIES_PER_HOUR
,
count
MAX_UPDATES_PER_HOUR
, and
count
MAX_CONNECTIONS_PER_HOUR
limits were
implemented in MySQL 4.0.2. They restrict the number of queries,
updates, and connections to the server permitted to this account
during any given one-hour period. (Queries for which results are
served from the query cache do not count against the
count
MAX_QUERIES_PER_HOUR
limit.) If
count
is 0
(the
default), this means that there is no limitation for the
account.
To specify resource limits for an existing user without
affecting existing privileges, use
GRANT USAGE
at
the global level (ON *.*
) and name the limits
to be changed. For example:
GRANT USAGE ON *.* TO ... WITH MAX_QUERIES_PER_HOUR 500 MAX_UPDATES_PER_HOUR 100;
Limits not specified retain their current values.
For more information on restricting access to server resources, see Section 5.6.4, “Setting Account Resource Limits”.
MySQL can check X509 certificate attributes in addition to the
usual authentication that is based on the user name and
password. To specify SSL-related options for a MySQL account,
use the REQUIRE
clause of the
GRANT
statement. (For background
information on the use of SSL with MySQL, see
Section 5.6.6, “Using SSL for Secure Connections”.)
There are a number of different possibilities for limiting connection types for a given account:
REQUIRE NONE
indicates that the account
has no SSL or X509 requirements. This is the default if no
SSL-related REQUIRE
options are
specified. Unencrypted connections are permitted if the user
name and password are valid. However, encrypted connections
can also be used, at the client's option, if the client has
the proper certificate and key files. That is, the client
need not specify any SSL command options, in which case the
connection will be unencrypted. To use an encrypted
connection, the client must specify either the
--ssl-ca
option, or all
three of the --ssl-ca
,
--ssl-key
, and
--ssl-cert
options.
The REQUIRE SSL
option tells the server
to permit only SSL-encrypted connections for the account.
GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE SSL;
To connect, the client must specify the
--ssl-ca
option, and may
additionally specify the
--ssl-key
and
--ssl-cert
options.
REQUIRE X509
means that the client must
have a valid certificate but that the exact certificate,
issuer, and subject do not matter. The only requirement is
that it should be possible to verify its signature with one
of the CA certificates.
GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE X509;
To connect, the client must specify the
--ssl-ca
,
--ssl-key
, and
--ssl-cert
options. This is
also true for ISSUER
and
SUBJECT
because those
REQUIRE
options imply
X509
.
REQUIRE ISSUER
'
places the
restriction on connection attempts that the client must
present a valid X509 certificate issued by CA
issuer
''
. If
the client presents a certificate that is valid but has a
different issuer, the server rejects the connection. Use of
X509 certificates always implies encryption, so the
issuer
'SSL
option is unnecessary in this case.
GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE ISSUER '/C=FI/ST=Some-State/L=Helsinki/ O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@example.com';
Note that the
'
value
should be entered as a single string.
issuer
'
REQUIRE SUBJECT
'
places the
restriction on connection attempts that the client must
present a valid X509 certificate containing the subject
subject
'subject
. If the client presents a
certificate that is valid but has a different subject, the
server rejects the connection.
GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/ O=MySQL demo client certificate/ CN=Tonu Samuel/Email=tonu@example.com';
Note that the
'
value should be entered as a single string. MySQL does a
simple string comparison of this value to the value in the
certificate, so lettercase and component ordering must be
given exactly as present in the certificate.
subject
'
REQUIRE CIPHER
'
is needed to
ensure that ciphers and key lengths of sufficient strength
are used. SSL itself can be weak if old algorithms using
short encryption keys are used. Using this option, you can
ask that a specific cipher method is used for a connection.
cipher
'
GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';
The SUBJECT
, ISSUER
, and
CIPHER
options can be combined in the
REQUIRE
clause like this:
GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost' IDENTIFIED BY 'goodsecret' REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/ O=MySQL demo client certificate/ CN=Tonu Samuel/Email=tonu@example.com' AND ISSUER '/C=FI/ST=Some-State/L=Helsinki/ O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@example.com' AND CIPHER 'EDH-RSA-DES-CBC3-SHA';
The order of the options does not matter, but no option can be
specified twice. Starting from MySQL 4.0.4, the
AND
keyword is optional between
REQUIRE
options.
If you are using table or column privileges for even one user, the server examines table and column privileges for all users and this slows down MySQL a bit. Similarly, if you limit the number of queries, updates, or connections for any users, the server must monitor these values.
The biggest differences between the MySQL and standard SQL
versions of GRANT
are:
MySQL associates privileges with the combination of a host name and user name and not with only a user name.
Standard SQL does not have global or database-level privileges, nor does it support all the privilege types that MySQL supports.
MySQL does not support the standard SQL
UNDER
privilege, and does not support the
TRIGGER
privilege until MySQL 5.1.6.
Standard SQL privileges are structured in a hierarchical manner, which means that if you remove a user, all privileges the user has been granted are revoked. This is not the case in MySQL 4.1 and earlier versions, where the granted privileges are not automatically revoked and you must revoke them explicitly. See Section 12.4.1.1, “DROP USER Syntax”.
In standard SQL, when you drop a table, all privileges for
the table are revoked. In standard SQL, when you revoke a
privilege, all privileges that were granted based on that
privilege are also revoked. In MySQL, privileges can be
dropped only with explicit DROP
USER
or REVOKE
statements or by manipulating the MySQL grant tables
directly.
In MySQL, it is possible to have the
INSERT
privilege for only
some of the columns in a table. In this case, you can still
execute INSERT
statements on
the table, provided that you insert values only for those
columns for which you have the
INSERT
privilege. The omitted
columns are set to their implicit default values. (Standard
SQL requires you to have the
INSERT
privilege on all
columns.) Section 10.1.4, “Data Type Default Values”, discusses
implicit default values.
REVOKEpriv_type
[(column_list
)] [,priv_type
[(column_list
)]] ... ONpriv_level
FROMuser
[,user
] ... REVOKE ALL PRIVILEGES, GRANT OPTION FROMuser
[,user
] ...
The REVOKE
statement enables
system administrators to revoke privileges from MySQL accounts.
REVOKE
is implemented in MySQL
3.22.11 or later. For earlier MySQL versions, it does nothing.
Each account name uses the format described in
Section 5.5.3, “Specifying Account Names”. For example:
REVOKE INSERT ON *.* FROM 'jeffrey'@'localhost';
If you specify only the user name part of the account name, a
host name part of '%'
is used.
For details on the levels at which privileges exist, the
permissible priv_type
and
priv_level
values, and the syntax for
specifying users and passwords, see Section 12.4.1.2, “GRANT Syntax”
To use the first REVOKE
syntax,
you must have the GRANT OPTION
privilege, and you must have the privileges that you are
revoking.
To make it easy to revoke all privileges, MySQL 4.1.2 has added the following syntax, which drops all global, database, table, and column privileges for the named users:
REVOKE ALL PRIVILEGES, GRANT OPTION FROMuser
[,user
] ...
To use this REVOKE
syntax, you
must have the UPDATE
privilege
for the mysql
database.
Before MySQL 4.1.2, all privileges cannot be dropped at once. Two statements are necessary:
REVOKE ALL PRIVILEGES ON *.* FROMuser
[,user
] ... REVOKE GRANT OPTION ON *.* FROMuser
[,user
] ...
REVOKE
removes privileges, but
does not drop mysql.user
table entries. To
remove a user account entirely, use
DELETE
. As of MySQL 4.1.1, you
can also use DROP USER
to remove
users; see Section 12.4.1.1, “DROP USER Syntax”.
If the grant tables hold privilege rows that contain mixed-case
database or table names and the
lower_case_table_names
system
variable is set to a nonzero value,
REVOKE
cannot be used to revoke
these privileges. It will be necessary to manipulate the grant
tables directly. (GRANT
will not
create such rows when
lower_case_table_names
is set,
but such rows might have been created prior to setting the
variable.)
To verify an account's privileges after a
REVOKE
operation, use
SHOW GRANTS
. See
Section 12.4.5.12, “SHOW GRANTS Syntax”.
SET PASSWORD [FORuser
] = { PASSWORD('some password
') | OLD_PASSWORD('some password
') | 'encrypted password
' }
The SET PASSWORD
statement
assigns a password to an existing MySQL user account.
If the password is specified using the
PASSWORD()
or
OLD_PASSWORD()
function, the
literal text of the password should be given. If the password is
specified without using either function, the password should be
the already-encrypted password value as returned by
PASSWORD()
.
With no FOR
clause, this statement sets the
password for the current user. Any client that has connected to
the server using a nonanonymous account can change the password
for that account.
With a FOR
clause, this statement sets the
password for a specific account on the current server host. Only
clients that have the UPDATE
privilege for the mysql
database can do this.
The user
value should be given in
format, where user_name
@host_name
user_name
and
host_name
are exactly as they are
listed in the User
and
Host
columns of the
mysql.user
table entry. For example, if you
had an entry with User
and
Host
column values of
'bob'
and '%.loc.gov'
, you
would write the statement like this:
SET PASSWORD FOR 'bob'@'%.loc.gov' = PASSWORD('newpass
');
That is equivalent to the following statements:
UPDATE mysql.user SET Password=PASSWORD('newpass
')
WHERE User='bob' AND Host='%.loc.gov';
FLUSH PRIVILEGES;
Another way to set the password is to use
GRANT
:
GRANT USAGE ON *.* TO 'bob'@'%.loc.gov' IDENTIFIED BY 'newpass
';
SET PASSWORD
may be recorded in
server logs or in a history file such as
~/.mysql_history
, which means that
plaintext passwords may be read by anyone having read access
to that information. See Section 5.4.2, “Password Security in MySQL”.
If you are connecting to a MySQL 4.1 or later server using a
pre-4.1 client program, do not use the preceding
SET PASSWORD
or
UPDATE
statement without
reading Section 5.4.2.3, “Password Hashing in MySQL”, first. The
password format changed in MySQL 4.1, and under certain
circumstances it is possible that if you change your password,
you might not be able to connect to the server afterward.
Starting from MySQL 4.1, to see which account the server
authenticated you as, invoke the
CURRENT_USER()
function.
For more information about setting passwords, see Section 5.6.5, “Assigning Account Passwords”
ANALYZE [NO_WRITE_TO_BINLOG | LOCAL] TABLEtbl_name
[,tbl_name
] ...
ANALYZE TABLE
analyzes and stores
the key distribution for a table. During the analysis, the table
is locked with a read lock for MyISAM
and is
locked with a read lock for MyISAM
,
BDB
, and InnoDB
. This
statement works with MyISAM
,
BDB
, and (as of MySQL 4.0.13)
InnoDB
tables. For MyISAM
tables, this statement is equivalent to using myisamchk
--analyze.
For more information on how the analysis works within
InnoDB
, see
Section 13.2.15, “Restrictions on InnoDB Tables”.
MySQL uses the stored key distribution to decide the order in which tables should be joined when you perform a join on something other than a constant. In addition, key distributions can be used when deciding which indexes to use for a specific table within a query.
This statement requires SELECT
and INSERT
privileges for the
table.
ANALYZE TABLE
returns a result
set with the following columns.
Column | Value |
---|---|
Table | The table name |
Op | Always analyze |
Msg_type | status , error ,
info , note , or
warning |
Msg_text | An informational message |
You can check the stored key distribution with the
SHOW INDEX
statement. See
Section 12.4.5.13, “SHOW INDEX Syntax”.
If the table has not changed since the last
ANALYZE TABLE
statement, the
table is not analyzed again.
Before MySQL 4.1.1, ANALYZE TABLE
statements are not written to the binary log. As of MySQL 4.1.1,
ANALYZE TABLE
statements are
written to the binary log so that they will be replicated to
replication slaves. Logging can be suppressed with the optional
NO_WRITE_TO_BINLOG
keyword or its alias
LOCAL
.
BACKUP TABLEtbl_name
[,tbl_name
] ... TO '/path/to/backup/directory
'
This statement is deprecated and is removed in MySQL 5.5. As an alternative, mysqldump or mysqlhotcopy can be used instead.
BACKUP TABLE
copies to the backup
directory the minimum number of table files needed to restore
the table, after flushing any buffered changes to disk. The
statement works only for MyISAM
tables. It
copies the .frm
definition and
.MYD
data files. The
.MYI
index file can be rebuilt from those
two files. The directory should be specified as a full path
name. To restore the table, use RESTORE
TABLE
.
During the backup, a read lock is held for each table, one at
time, as they are being backed up. If you want to back up
several tables as a snapshot (preventing any of them from being
changed during the backup operation), issue a
LOCK TABLES
statement first, to
obtain a read lock for all tables in the group.
BACKUP TABLE
returns a result set
with the following columns.
Column | Value |
---|---|
Table | The table name |
Op | Always backup |
Msg_type | status , error ,
info , note , or
warning |
Msg_text | An informational message |
BACKUP TABLE
is available in
MySQL 3.23.25 and later.
CHECK TABLEtbl_name
[,tbl_name
] ... [option
] ...option
= {QUICK | FAST | MEDIUM | EXTENDED | CHANGED}
CHECK TABLE
checks a table or
tables for errors. CHECK TABLE
works for MyISAM
and
InnoDB
tables. For MyISAM
tables, the key statistics are updated as well.
CHECK TABLE
returns a result set
with the following columns.
Column | Value |
---|---|
Table | The table name |
Op | Always check |
Msg_type | status , error ,
info , note , or
warning |
Msg_text | An informational message |
Note that the statement might produce many rows of information
for each checked table. The last row has a
Msg_type
value of status
and the Msg_text
normally should be
OK
. If you don't get OK
,
or Table is already up to date
you should
normally run a repair of the table. See
Section 6.6, “MyISAM Table Maintenance and Crash Recovery”. Table is
already up to date
means that the storage engine for
the table indicated that there was no need to check the table.
The different check options that can be given are shown in the
following table. These options are passed to the storage engine,
which may use them or not. MyISAM
uses them;
they are ignored for InnoDB
tables.
Type | Meaning |
---|---|
QUICK | Do not scan the rows to check for incorrect links. |
FAST | Check only tables that have not been closed properly. |
CHANGED | Check only tables that have been changed since the last check or that have not been closed properly. |
MEDIUM | Scan rows to verify that deleted links are valid. This also calculates a key checksum for the rows and verifies this with a calculated checksum for the keys. |
EXTENDED | Do a full key lookup for all keys for each row. This ensures that the table is 100% consistent, but takes a long time. |
If none of the options QUICK
,
MEDIUM
, or EXTENDED
are
specified, the default check type for dynamic-format
MyISAM
tables is MEDIUM
.
This has the same result as running myisamchk
--medium-check tbl_name
on
the table. The default check type also is
MEDIUM
for static-format
MyISAM
tables, unless
CHANGED
or FAST
is
specified. In that case, the default is
QUICK
. The row scan is skipped for
CHANGED
and FAST
because
the rows are very seldom corrupted.
You can combine check options, as in the following example that does a quick check on the table to determine whether it was closed properly:
CHECK TABLE test_table FAST QUICK;
In some cases, CHECK TABLE
changes the table. This happens if the table is marked as
“corrupted” or “not closed properly”
but CHECK TABLE
does not find
any problems in the table. In this case,
CHECK TABLE
marks the table as
okay.
If a table is corrupted, it is most likely that the problem is in the indexes and not in the data part. All of the preceding check types check the indexes thoroughly and should thus find most errors.
If you just want to check a table that you assume is okay, you
should use no check options or the QUICK
option. The latter should be used when you are in a hurry and
can take the very small risk that QUICK
does
not find an error in the data file. (In most cases, under normal
usage, MySQL should find any error in the data file. If this
happens, the table is marked as “corrupted” and
cannot be used until it is repaired.)
FAST
and CHANGED
are
mostly intended to be used from a script (for example, to be
executed from cron) if you want to check
tables from time to time. In most cases, FAST
is to be preferred over CHANGED
. (The only
case when it is not preferred is when you suspect that you have
found a bug in the MyISAM
code.)
EXTENDED
is to be used only after you have
run a normal check but still get strange errors from a table
when MySQL tries to update a row or find a row by key. This is
very unlikely if a normal check has succeeded.
Use of CHECK TABLE
... EXTENDED
might influence the execution plan
generated by the query optimizer.
Some problems reported by CHECK
TABLE
cannot be corrected automatically:
Found row where the auto_increment column has the
value 0
.
This means that you have a row in the table where the
AUTO_INCREMENT
index column contains the
value 0. (It is possible to create a row where the
AUTO_INCREMENT
column is 0 by explicitly
setting the column to 0 with an
UPDATE
statement.)
This is not an error in itself, but could cause trouble if
you decide to dump the table and restore it or do an
ALTER TABLE
on the table. In
this case, the AUTO_INCREMENT
column
changes value according to the rules of
AUTO_INCREMENT
columns, which could cause
problems such as a duplicate-key error.
To get rid of the warning, simply execute an
UPDATE
statement to set the
column to some value other than 0.
CHECKSUM TABLEtbl_name
[,tbl_name
] ... [ QUICK | EXTENDED ]
CHECKSUM TABLE
reports a table
checksum.
With QUICK
, the live table checksum is
reported if it is available, or NULL
otherwise. This is very fast. A live checksum is enabled by
specifying the CHECKSUM=1
table option when
you create the table; currently, this is supported only for
MyISAM
tables. See
Section 12.1.5, “CREATE TABLE Syntax”.
With EXTENDED
, the entire table is read row
by row and the checksum is calculated. This can be very slow for
large tables.
If neither QUICK
nor
EXTENDED
is specified, MySQL returns a live
checksum if the table storage engine supports it and scans the
table otherwise.
For a nonexistent table, CHECKSUM
TABLE
returns NULL
.
The checksum value depends on the table row format. If the row
format changes, the checksum also changes. For example, the
storage format for VARCHAR
changed between MySQL 4.1 and 5.0, so if a 4.1 table is upgraded
to MySQL 5.0, the checksum value may change.
This statement is implemented in MySQL 4.1.1.
If the checksums for two tables are different, then it is
almost certain that the tables are different in some way.
However, because the hashing function used by
CHECKSUM TABLE
is not
guaranteed to be collision-free, there is a slight chance that
two tables which are not identical can produce the same
checksum.
OPTIMIZE [NO_WRITE_TO_BINLOG | LOCAL] TABLEtbl_name
[,tbl_name
] ...
OPTIMIZE TABLE
should be used if
you have deleted a large part of a table or if you have made
many changes to a table with variable-length rows (tables that
have VARCHAR
,
VARBINARY
,
BLOB
, or
TEXT
columns). Deleted rows are
maintained in a linked list and subsequent
INSERT
operations reuse old row
positions. You can use OPTIMIZE
TABLE
to reclaim the unused space and to defragment
the data file. After extensive changes to a table, this
statement may also improve performance of statements that use
the table, sometimes significantly.
This statement requires SELECT
and INSERT
privileges for the
table.
OPTIMIZE TABLE
works
only for MyISAM
,
BDB
, and InnoDB
tables. It
does not work for tables created using any
other storage engine.
For MyISAM
tables,
OPTIMIZE TABLE
works as follows:
If the table has deleted or split rows, repair the table.
If the index pages are not sorted, sort them.
If the table's statistics are not up to date (and the repair could not be accomplished by sorting the index), update them.
For BDB
tables, OPTIMIZE
TABLE
currently is mapped to
ANALYZE TABLE
. See
Section 12.4.2.1, “ANALYZE TABLE Syntax”.
That was also the case for InnoDB
tables
before MySQL 4.1.3. As of 4.1.3, OPTIMIZE
TABLE
is mapped to ALTER
TABLE
, which rebuilds the table to update index
statistics and free unused space in the clustered index.
You can make OPTIMIZE TABLE
work
on other storage engines by starting mysqld
with the --skip-new
or
--safe-mode
option. In this case,
OPTIMIZE TABLE
is just mapped to
ALTER TABLE
.
OPTIMIZE TABLE
returns a result
set with the following columns.
Column | Value |
---|---|
Table | The table name |
Op | Always optimize |
Msg_type | status , error ,
info , note , or
warning |
Msg_text | An informational message |
Note that MySQL locks the table during the time
OPTIMIZE TABLE
is running.
Before MySQL 4.1.1, OPTIMIZE
TABLE
statements are not written to the binary log. As
of MySQL 4.1.1, OPTIMIZE TABLE
statements are written to the binary log so that they will be
replicated to replication slaves. Logging can be suppressed with
the optional NO_WRITE_TO_BINLOG
keyword or
its alias LOCAL
.
REPAIR [NO_WRITE_TO_BINLOG | LOCAL] TABLEtbl_name
[,tbl_name
] ... [QUICK] [EXTENDED] [USE_FRM]
REPAIR TABLE
repairs a possibly
corrupted table. By default, it has the same effect as
myisamchk --recover
tbl_name
.
REPAIR TABLE
works for
MyISAM
and for ARCHIVE
tables. See Section 13.1, “The MyISAM Storage Engine”, and
Section 13.7, “The ARCHIVE Storage Engine”.
This statement requires SELECT
and INSERT
privileges for the
table.
Normally, you should never have to run this statement. However,
if disaster strikes, REPAIR TABLE
is very likely to get back all your data from a
MyISAM
table. If tables become corrupted
often, you should try to find the reason for it and so to
eliminate the need to use REPAIR
TABLE
. See Section B.5.4.2, “What to Do If MySQL Keeps Crashing”, and
Section 13.1.4, “MyISAM Table Problems”.
It is best to make a backup of a table before performing a table repair operation; under some circumstances the operation might cause data loss. Possible causes include but are not limited to file system errors.
If the server crashes during a REPAIR
TABLE
operation, it is essential after restarting it
that you immediately execute another
REPAIR TABLE
statement for the
table before performing any other operations on it. In the
worst case, you might have a new clean index file without
information about the data file, and then the next operation
you perform could overwrite the data file. This is an unlikely
but possible scenario that underscores the value of making a
backup first.
REPAIR TABLE
returns a result set
with the following columns.
Column | Value |
---|---|
Table | The table name |
Op | Always repair |
Msg_type | status , error ,
info , note , or
warning |
Msg_text | An informational message |
The REPAIR TABLE
statement might
produce many rows of information for each repaired table. The
last row has a Msg_type
value of
status
and Msg_test
normally should be OK
. If you do not get
OK
for a MyISAM
table, you
should try repairing it with myisamchk
--safe-recover. (REPAIR
TABLE
does not implement all the options of
myisamchk.) With myisamchk
--safe-recover, you can also use options that
REPAIR TABLE
does not support,
such as --max-record-length
.
If you use the QUICK
option,
REPAIR TABLE
tries to repair only
the index file, and not the data file. This type of repair is
like that done by myisamchk --recover
--quick.
If you use the EXTENDED
option, MySQL creates
the index row by row instead of creating one index at a time
with sorting. (Before MySQL 4.1, this might be better than
sorting on fixed-length keys if you have long
CHAR
keys that compress very
well.) This type of repair is like that done by
myisamchk --safe-recover.
As of MySQL 4.0.2, the USE_FRM
option is
available for use if the .MYI
index file is
missing or if its header is corrupted. This option tells MySQL
not to trust the information in the .MYI
file header and to re-create it using information from the
.frm
file. This kind of repair cannot be
done with myisamchk.
Use the USE_FRM
option
only if you cannot use regular
REPAIR
modes! Telling the server to ignore
the .MYI
file makes important table
metadata stored in the .MYI
unavailable
to the repair process, which can have deleterious
consequences:
The current AUTO_INCREMENT
value is
lost.
The link to deleted records in the table is lost, which means that free space for deleted records will remain unoccupied thereafter.
The .MYI
header indicates whether the
table is compressed. If the server ignores this
information, it cannot tell that a table is compressed and
repair can cause change or loss of table contents. This
means that USE_FRM
should not be used
with compressed tables. That should not be necessary,
anyway: Compressed tables are read only, so they should
not become corrupt.
Do not use USE_FRM
if
your table was created by a different version of the MySQL
server than the one you are currently running. Doing so risks
the loss of all rows in the table. It is particularly
dangerous to use USE_FRM
after the server
returns this message:
Table upgrade required. Please do
"REPAIR TABLE `tbl_name
`" to fix it!
Before MySQL 4.1.1, REPAIR TABLE
statements are not written to the binary log. As of MySQL 4.1.1,
REPAIR TABLE
statements are
written to the binary log so that they will be replicated to
replication slaves. Logging can be suppressed with the optional
NO_WRITE_TO_BINLOG
keyword or its alias
LOCAL
.
You may be able to increase REPAIR
TABLE
performance by setting certain system variables.
See Section 7.3.2.4, “Speed of REPAIR TABLE Statements”.
RESTORE TABLEtbl_name
[,tbl_name
] ... FROM '/path/to/backup/directory
'
This statement is deprecated and is removed in MySQL 5.5.
RESTORE TABLE
restores the table
or tables from a backup that was made with
BACKUP TABLE
. The directory
should be specified as a full path name.
Existing tables are not overwritten; if you try to restore over
an existing table, an error occurs. Just as for
BACKUP TABLE
,
RESTORE TABLE
currently works
only for MyISAM
tables. Restored tables are
not replicated from master to slave.
The backup for each table consists of its
.frm
format file and
.MYD
data file. The restore operation
restores those files, and then uses them to rebuild the
.MYI
index file. Restoring takes longer
than backing up due to the need to rebuild the indexes. The more
indexes the table has, the longer it takes.
RESTORE TABLE
returns a result
set with the following columns.
Column | Value |
---|---|
Table | The table name |
Op | Always restore |
Msg_type | status , error ,
info , note , or
warning |
Msg_text | An informational message |
CREATE [AGGREGATE] FUNCTIONfunction_name
RETURNS {STRING|INTEGER|REAL} SONAMEshared_library_name
A user-defined function (UDF) is a way to extend MySQL with a
new function that works like a native (built-in) MySQL function
such as ABS()
or
CONCAT()
.
function_name
is the name that should
be used in SQL statements to invoke the function. The
RETURNS
clause indicates the type of the
function's return value.
shared_library_name
is the basename
of the shared object file that contains the code that implements
the function. As of MySQL 4.1.25, the file must be located in
the plugin directory. This directory is given by the value of
the plugin_dir
system variable.
If the value of plugin_dir
is
empty, the behavior that is used before 4.1.25 applies: The file
must be located in a directory that is searched by your system's
dynamic linker. For more information, see
Section 18.2.2.5, “Compiling and Installing User-Defined Functions”.
To create a function, you must have the
INSERT
privilege for the
mysql
database. This is necessary because
CREATE FUNCTION
adds a row to the
mysql.func
system table that records the
function's name, type, and shared library name. If you do not
have this table, you should run the
mysql_fix_privilege_tables script to create
it. See Section 4.4.5, “mysql_fix_privilege_tables — Upgrade MySQL System Tables”.
An active function is one that has been loaded with
CREATE FUNCTION
and not removed
with DROP FUNCTION
. All active
functions are reloaded each time the server starts, unless you
start mysqld with the
--skip-grant-tables
option. In
this case, UDF initialization is skipped and UDFs are
unavailable.
For instructions on writing user-defined functions, see Section 18.2.2, “Adding a New User-Defined Function”. For the UDF mechanism to work, functions must be written in C or C++ (or another language that can use C calling conventions), your operating system must support dynamic loading and you must have compiled mysqld dynamically (not statically).
AGGREGATE
is a new option for MySQL 3.23. An
AGGREGATE
function works exactly like a
native MySQL aggregate (summary) function such as
SUM
or
COUNT()
. For
AGGREGATE
to work, your
mysql.func
table must contain a
type
column. If your
mysql.func
table does not have this column,
you should run the mysql_fix_privilege_tables
script to create it.
To upgrade the shared library associated with a UDF, issue a
DROP FUNCTION
statement,
upgrade the shared library, and then issue a
CREATE FUNCTION
statement. If
you upgrade the shared library first and then use
DROP FUNCTION
, the server may
crash.
DROP FUNCTION function_name
This statement drops the user-defined function (UDF) named
function_name
.
To drop a function, you must have the
DELETE
privilege for the
mysql
database. This is because
DROP FUNCTION
removes a row from
the mysql.func
system table that records the
function's name, type, and shared library name.
To upgrade the shared library associated with a UDF, issue a
DROP FUNCTION
statement,
upgrade the shared library, and then issue a
CREATE FUNCTION
statement. If
you upgrade the shared library first and then use
DROP FUNCTION
, the server may
crash.
SETvariable_assignment
[,variable_assignment
] ...variable_assignment
:user_var_name
=expr
| [GLOBAL | SESSION]system_var_name
=expr
| [@@global. | @@session. | @@]system_var_name
=expr
The SET
statement assigns values to different types of variables that
affect the operation of the server or your client. Older versions
of MySQL employed SET OPTION
, but this syntax
is deprecated in favor of
SET
without
OPTION
.
This section describes use of
SET
for
assigning values to system variables or user variables. For
general information about these types of variables, see
Section 5.1.3, “Server System Variables”, and
Section 8.4, “User-Defined Variables”. System variables also can be set
at server startup, as described in
Section 5.1.4, “Using System Variables”.
Some variants of
SET
syntax
are used in other contexts:
SET CHARACTER SET
and SET
NAMES
assign values to character set and collation
variables associated with the connection to the server.
SET ONESHOT
is used for replication. These
variants are described later in this section.
SET PASSWORD
assigns account
passwords. See Section 12.4.1.4, “SET PASSWORD Syntax”.
SET
TRANSACTION ISOLATION LEVEL
sets the isolation level
for transaction processing. See
Section 12.3.6, “SET TRANSACTION Syntax”.
The following discussion shows the different
SET
syntaxes
that you can use to set variables. The examples use the
=
assignment
operator, but you can also use the
:=
assignment operator for this purpose.
A user variable is written as
@
and can be
set as follows:
var_name
SET @var_name
=expr
;
As of MySQL 4.0.3, many system variables are dynamic and can be
changed while the server runs by using the
SET
statement. For a list, see
Section 5.1.4.2, “Dynamic System Variables”. To change a system
variable with
SET
, refer
to it as var_name
, optionally preceded
by a modifier:
To indicate explicitly that a variable is a global variable,
precede its name by GLOBAL
or
@@global.
. The
SUPER
privilege is required to
set global variables.
To indicate explicitly that a variable is a session variable,
precede its name by SESSION
,
@@session.
, or @@
.
Setting a session variable requires no special privilege, but
a client can change only its own session variables, not those
of any other client.
LOCAL
and @@local.
are
synonyms for SESSION
and
@@session.
.
If no modifier is present,
SET
changes the session variable.
A SET
statement can contain multiple variable assignments, separated by
commas. If you set several system variables, the most recent
GLOBAL
or SESSION
modifier
in the statement is used for following variables that have no
modifier specified.
Examples:
SET sort_buffer_size=10000; SET @@local.sort_buffer_size=10000; SET GLOBAL sort_buffer_size=1000000, SESSION sort_buffer_size=1000000; SET @@sort_buffer_size=1000000; SET @@global.sort_buffer_size=1000000, @@local.sort_buffer_size=1000000;
The @@
syntax for system variables is supported for compatibility with
some other database systems.
var_name
If you change a session system variable, the value remains in effect until your session ends or until you change the variable to a different value. The change is not visible to other clients.
If you change a global system variable, the value is remembered
and used for new connections until the server restarts. (To make a
global system variable setting permanent, you should set it in an
option file.) The change is visible to any client that accesses
that global variable. However, the change affects the
corresponding session variable only for clients that connect after
the change. The global variable change does not affect the session
variable for any client that is currently connected (not even that
of the client that issues the
SET GLOBAL
statement).
To prevent incorrect usage, MySQL produces an error if you use
SET GLOBAL
with a variable that can only be used with
SET SESSION
or if you do not specify GLOBAL
(or
@@global.
) when setting a global variable.
To set a SESSION
variable to the
GLOBAL
value or a GLOBAL
value to the compiled-in MySQL default value, use the
DEFAULT
keyword. For example, the following two
statements are identical in setting the session value of
max_join_size
to the global
value:
SET max_join_size=DEFAULT; SET @@session.max_join_size=@@global.max_join_size;
Not all system variables can be set to DEFAULT
.
In such cases, use of DEFAULT
results in an
error.
You can refer to the values of specific global or sesson system
variables in expressions by using one of the
@@
-modifiers. For example, you can retrieve
values in a SELECT
statement like
this:
SELECT @@global.sql_mode, @@session.sql_mode, @@sql_mode;
When you refer to a system variable in an expression as
@@
(that is,
when you do not specify var_name
@@global.
or
@@session.
), MySQL returns the session value if
it exists and the global value otherwise. (This differs from
SET @@
, which always refers to
the session value.)
var_name
=
value
Some variables displayed by SHOW VARIABLES
may not be available using SELECT
@@
syntax; an
var_name
Unknown system variable
occurs. As a
workaround in such cases, you can use SHOW VARIABLES
LIKE '
.
var_name
'
Suffixes for specifying a value multiplier can be used when
setting a variable at server startup, but not to set the value
with SET
at
runtime. On the other hand, with
SET
you can
assign a variable's value using an expression, which is not true
when you set a variable at server startup. For example, the first
of the following lines is legal at server startup, but the second
is not:
shell>mysql --max_allowed_packet=16M
shell>mysql --max_allowed_packet=16*1024*1024
Conversely, the second of the following lines is legal at runtime, but the first is not:
mysql>SET GLOBAL max_allowed_packet=16M;
mysql>SET GLOBAL max_allowed_packet=16*1024*1024;
To display system variables names and values, use the
SHOW VARIABLES
statement. (See
Section 12.4.5.25, “SHOW VARIABLES Syntax”.)
The following list describes
SET
options
that have nonstandard syntax (that is, options that are not set
with
syntax).
name
=
value
CHARACTER SET
{
charset_name
| DEFAULT}
This maps all strings from and to the client with the given
mapping. Before MySQL 4.1, the only permissible value for
charset_name
is
cp1251_koi8
, but you can add new mappings
by editing the sql/convert.cc
file in the
MySQL source distribution. As of MySQL 4.1.1, SET
CHARACTER SET
sets three session system variables:
character_set_client
and
character_set_results
are set
to the given character set, and
character_set_connection
to
the value of
character_set_database
. See
Section 9.1.4, “Connection Character Sets and Collations”.
The default mapping can be restored by using the value
DEFAULT
. The default depends on the server
configuration.
ucs2
cannot be used as a client character
set, which means that it does not work for SET
CHARACTER SET
.
NAMES {'
charset_name
'
[COLLATE 'collation_name
'] |
DEFAULT}
SET NAMES
sets the three session system
variables
character_set_client
,
character_set_connection
, and
character_set_results
to the
given character set. Setting
character_set_connection
to
charset_name
also sets
collation_connection
to the
default collation for charset_name
. The
optional COLLATE
clause may be used to
specify a collation explicitly. See
Section 9.1.4, “Connection Character Sets and Collations”.
The default mapping can be restored by using a value of
DEFAULT
. The default depends on the server
configuration.
ucs2
cannot be used as a client character
set, which means that it does not work for SET
NAMES
.
SET NAMES
is available as of MySQL 4.1.0.
This option is a modifier, not a variable. It is
only for internal use for replication:
mysqlbinlog uses SET
ONE_SHOT
to modify temporarily the values of
character set, collation, and time zone variables to reflect
at rollforward what they were originally.
ONE_SHOT
is available as of MySQL 4.1.3.
ONE_SHOT
is intended for use only with the
permitted set of variables. With other variables, an error
occurs:
mysql> SET ONE_SHOT max_allowed_packet = 1;
ERROR 1382 (HY000): The 'SET ONE_SHOT' syntax is reserved for purposes
internal to the MySQL server
If ONE_SHOT
is used with the permitted
variables, it changes the variables as requested, but only for
the next
non-SET
statement. After that, the server resets all character set,
collation, and time zone-related system variables to their
previous values. Example:
mysql>SET ONE_SHOT character_set_connection = latin5;
mysql>SET ONE_SHOT collation_connection = latin5_turkish_ci;
mysql>SHOW VARIABLES LIKE '%_connection';
+--------------------------+-------------------+ | Variable_name | Value | +--------------------------+-------------------+ | character_set_connection | latin5 | | collation_connection | latin5_turkish_ci | +--------------------------+-------------------+ mysql>SHOW VARIABLES LIKE '%_connection';
+--------------------------+-------------------+ | Variable_name | Value | +--------------------------+-------------------+ | character_set_connection | latin1 | | collation_connection | latin1_swedish_ci | +--------------------------+-------------------+
SHOW
has many forms that provide
information about databases, tables, columns, or status
information about the server. This section describes those
following:
SHOW {BINARY | MASTER} LOGS SHOW BINLOG EVENTS [IN 'log_name
'] [FROMpos
] [LIMIT [offset
,]row_count
] SHOW CHARACTER SET [LIKE 'pattern
'] SHOW COLLATION [LIKE 'pattern
'] SHOW [FULL] COLUMNS FROMtbl_name
[FROMdb_name
] [LIKE 'pattern
'] SHOW CREATE DATABASEdb_name
SHOW CREATE TABLEtbl_name
SHOW DATABASES [LIKE 'pattern
'] SHOW ENGINEengine_name
{LOGS | STATUS } SHOW [STORAGE] ENGINES SHOW ERRORS [LIMIT [offset
,]row_count
] SHOW GRANTS FORuser
SHOW INDEX FROMtbl_name
[FROMdb_name
] SHOW INNODB STATUS SHOW [BDB] LOGS SHOW MASTER STATUS SHOW OPEN TABLES SHOW PRIVILEGES SHOW [FULL] PROCESSLIST SHOW SLAVE HOSTS SHOW SLAVE STATUS SHOW [GLOBAL | SESSION] STATUS [LIKE 'pattern
'] SHOW TABLE STATUS [FROMdb_name
] [LIKE 'pattern
'] SHOW TABLES [FROMdb_name
] [LIKE 'pattern
'] SHOW [GLOBAL | SESSION] VARIABLES [LIKE 'pattern
'] SHOW WARNINGS [LIMIT [offset
,]row_count
]
If the syntax for a given SHOW
statement includes a LIKE
'
part,
pattern
''
is a
string that can contain the SQL
“pattern
'%
” and
“_
” wildcard characters. The
pattern is useful for restricting statement output to matching
values.
Many MySQL APIs (such as PHP) enable you to treat the result
returned from a SHOW
statement as
you would a result set from a
SELECT
; see
Chapter 17, Connectors and APIs, or your API documentation for
more information.
SHOW BINARY LOGS SHOW MASTER LOGS
Lists the binary log files on the server. This statement is used as part of the procedure described in Section 12.5.1.1, “PURGE BINARY LOGS Syntax”, that shows how to determine which logs can be purged.
mysql> SHOW BINARY LOGS;
+---------------+-----------+
| Log_name | File_size |
+---------------+-----------+
| binlog.000015 | 724935 |
| binlog.000016 | 733481 |
+---------------+-----------+
SHOW MASTER
LOGS
was added in MySQL 3.23.38. As of MySQL 4.1.1,
you can also use SHOW BINARY
LOGS
, which is equivalent. The
File_size
column is displayed as of MySQL
5.0.7.
SHOW BINLOG EVENTS [IN 'log_name
'] [FROMpos
] [LIMIT [offset
,]row_count
]
Shows the events in the binary log. If you do not specify
'
, the
first binary log is displayed.
log_name
'
The LIMIT
clause has the same syntax as for
the SELECT
statement. See
Section 12.2.7, “SELECT Syntax”.
This statement is available as of MySQL 4.0.
Issuing a SHOW BINLOG EVENTS
with no LIMIT
clause could start a very
time- and resource-consuming process because the server
returns to the client the complete contents of the binary log
(which includes all statements executed by the server that
modify data). As an alternative to SHOW
BINLOG EVENTS
, use the
mysqlbinlog utility to save the binary log
to a text file for later examination and analysis. See
Section 4.6.6, “mysqlbinlog — Utility for Processing Binary Log Files”.
Some events relating to the setting of user and system
variables are not included in the output from
SHOW BINLOG EVENTS
. To get
complete coverage of events within a binary log, use
mysqlbinlog.
SHOW CHARACTER SET [LIKE 'pattern
']
The SHOW CHARACTER SET
statement
shows all available character sets. It takes an optional
LIKE
clause that indicates which
character set names to match. For example:
mysql> SHOW CHARACTER SET LIKE 'latin%';
+---------+-----------------------------+-------------------+--------+
| Charset | Description | Default collation | Maxlen |
+---------+-----------------------------+-------------------+--------+
| latin1 | cp1252 West European | latin1_swedish_ci | 1 |
| latin2 | ISO 8859-2 Central European | latin2_general_ci | 1 |
| latin5 | ISO 8859-9 Turkish | latin5_turkish_ci | 1 |
| latin7 | ISO 8859-13 Baltic | latin7_general_ci | 1 |
+---------+-----------------------------+-------------------+--------+
The Maxlen
column shows the maximum number of
bytes required to store one character.
SHOW CHARACTER SET
is available
as of MySQL 4.1.0.
SHOW COLLATION [LIKE 'pattern
']
This statement lists collations supported by the server. By
default, the output from SHOW
COLLATION
includes all available collations. It takes
an optional LIKE
clause whose
pattern
indicates which collation
names to match. For example:
mysql> SHOW COLLATION LIKE 'latin1%';
+-------------------+---------+----+---------+----------+---------+
| Collation | Charset | Id | Default | Compiled | Sortlen |
+-------------------+---------+----+---------+----------+---------+
| latin1_german1_ci | latin1 | 5 | | | 0 |
| latin1_swedish_ci | latin1 | 8 | Yes | Yes | 0 |
| latin1_danish_ci | latin1 | 15 | | | 0 |
| latin1_german2_ci | latin1 | 31 | | Yes | 2 |
| latin1_bin | latin1 | 47 | | Yes | 0 |
| latin1_general_ci | latin1 | 48 | | | 0 |
| latin1_general_cs | latin1 | 49 | | | 0 |
| latin1_spanish_ci | latin1 | 94 | | | 0 |
+-------------------+---------+----+---------+----------+---------+
The Collation
and Charset
columns indicate the names of the collation and the character
set with which it is associated. Id
is the
collation ID. Default
indicates whether the
collation is the default for its character set.
Compiled
indicates whether the character set
is compiled into the server. Sortlen
is
related to the amount of memory required to sort strings
expressed in the character set.
To see the default collation for each character set, use the
following statement. Default
is a reserved
word, so to use it as an identifier, it must be quoted as such:
mysql> SHOW COLLATION WHERE `Default` = 'Yes';
+---------------------+----------+----+---------+----------+---------+
| Collation | Charset | Id | Default | Compiled | Sortlen |
+---------------------+----------+----+---------+----------+---------+
| big5_chinese_ci | big5 | 1 | Yes | Yes | 1 |
| dec8_swedish_ci | dec8 | 3 | Yes | Yes | 1 |
| cp850_general_ci | cp850 | 4 | Yes | Yes | 1 |
| hp8_english_ci | hp8 | 6 | Yes | Yes | 1 |
| koi8r_general_ci | koi8r | 7 | Yes | Yes | 1 |
| latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 |
...
SHOW COLLATION
is available as of
MySQL 4.1.0.
SHOW [FULL] COLUMNS {FROM | IN}tbl_name
[{FROM | IN}db_name
] [LIKE 'pattern
']
SHOW COLUMNS
displays information
about the columns in a given table.
mysql> SHOW COLUMNS FROM City;
+------------+----------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+------------+----------+------+-----+---------+----------------+
| Id | int(11) | | PRI | NULL | auto_increment |
| Name | char(35) | | | | |
| Country | char(3) | | UNI | | |
| District | char(20) | YES | MUL | | |
| Population | int(11) | | | 0 | |
+------------+----------+------+-----+---------+----------------+
5 rows in set (0.00 sec)
If the data types differ from what you expect them to be based
on a CREATE TABLE
statement, note
that MySQL sometimes changes data types when you create or alter
a table. The conditions under which this occurs are described in
Section 12.1.5.2, “Silent Column Specification Changes”.
The FULL
keyword can be used from MySQL
3.23.32 on. It causes the output to include the privileges you
have for each column. As of MySQL 4.1, FULL
also causes any per-column collation and comments to be
displayed.
You can use db_name.tbl_name
as an
alternative to the
syntax. In
other words, these two statements are equivalent:
tbl_name
FROM db_name
mysql>SHOW COLUMNS FROM mytable FROM mydb;
mysql>SHOW COLUMNS FROM mydb.mytable;
SHOW COLUMNS
displays the
following values for each table column:
Field
indicates the column name.
Type
indicates the column data type.
Collation
indicates the collation for
nonbinary string columns, or NULL
for other
columns. This value is displayed only if you use the
FULL
keyword.
The Null
field indicates whether
NULL
values can be stored in the column, with
YES
displayed when NULL
values are permitted.
The Key
field indicates whether the column is
indexed:
If Key
is empty, the column either is not
indexed or is indexed only as a secondary column in a
multiple-column, nonunique index.
If Key
is PRI
, the
column is a PRIMARY KEY
or is one of the
columns in a multiple-column PRIMARY KEY
.
If Key
is UNI
, the
column is the first column of a unique-valued index that
cannot contain NULL
values.
If Key
is MUL
,
multiple occurrences of a given value are permitted within
the column. The column is the first column of a nonunique
index or a unique-valued index that can contain
NULL
values.
If more than one of the Key
values applies to
a given column of a table, Key
displays the
one with the highest priority, in the order
PRI
, UNI
,
MUL
.
A UNIQUE
index may be displayed as
PRI
if it cannot contain
NULL
values and there is no PRIMARY
KEY
in the table. A UNIQUE
index
may display as MUL
if several columns form a
composite UNIQUE
index; although the
combination of the columns is unique, each column can still hold
multiple occurrences of a given value.
If the column permits NULL
values, the
Key
value can be MUL
even
when a UNIQUE
index is used. The rationale is
that multiple rows in a UNIQUE
index can hold
a NULL
value if the column is not declared
NOT NULL
. (This behavior changes in MySQL
5.0.)
The Default
field indicates the default value
that is assigned to the column.
The Extra
field contains any additional
information that is available about a given column. The value is
auto_increment
for columns that have the
AUTO_INCREMENT
attribute and empty otherwise.
Privileges
indicates the privileges you have
for the column. This value is displayed only if you use the
FULL
keyword.
Comment
indicates any comment the column has.
This value is displayed only if you use the
FULL
keyword.
SHOW FIELDS
is a synonym for
SHOW COLUMNS
. You can also list a
table's columns with the mysqlshow
db_name
tbl_name
command.
The DESCRIBE
statement provides
information similar to SHOW
COLUMNS
. See Section 12.7.1, “DESCRIBE Syntax”.
The SHOW CREATE TABLE
,
SHOW TABLE STATUS
, and
SHOW INDEX
statements also
provide information about tables. See Section 12.4.5, “SHOW Syntax”.
SHOW CREATE DATABASE db_name
Shows the CREATE DATABASE
statement that creates the given database. It was added in MySQL
4.1.
mysql> SHOW CREATE DATABASE test\G
*************************** 1. row ***************************
Database: test
Create Database: CREATE DATABASE `test`
/*!40100 DEFAULT CHARACTER SET latin1 */
SHOW CREATE DATABASE
quotes table
and column names according to the value of the
sql_quote_show_create
option.
See Section 5.1.3, “Server System Variables”.
SHOW CREATE TABLE tbl_name
Shows the CREATE TABLE
statement
that creates the given table. The statement requires the
SELECT
privilege for the table.
It was added in MySQL 3.23.20.
mysql> SHOW CREATE TABLE t\G
*************************** 1. row ***************************
Table: t
Create Table: CREATE TABLE t (
id INT(11) default NULL auto_increment,
s char(60) default NULL,
PRIMARY KEY (id)
) ENGINE=MyISAM
SHOW CREATE TABLE
quotes table
and column names according to the value of the
sql_quote_show_create
option.
See Section 5.1.3, “Server System Variables”.
SHOW DATABASES [LIKE 'pattern
']
SHOW DATABASES
lists the
databases on the MySQL server host. As of MySQL 4.0.2, you see
only those databases for which you have some kind of privilege,
if you do not have the global SHOW
DATABASES
privilege. You can also get this list using
the mysqlshow command.
If the server was started with the
--skip-show-database
option, you
cannot use this statement at all unless you have the
SHOW DATABASES
privilege.
MySQL implements databases as directories in the data directory, so this statement simply lists directories in that location. However, the output may include names of directories that do not correspond to actual databases.
SHOW ENGINE engine_name
{LOGS | STATUS }
SHOW ENGINE
displays log or
status information about a storage engine. The following
statements currently are supported:
SHOW ENGINE BDB LOGS SHOW ENGINE INNODB STATUS SHOW ENGINE NDB STATUS SHOW ENGINE NDBCLUSTER STATUS
SHOW ENGINE BDB
LOGS
displays status information about existing
BDB
log files. It returns the following
fields:
File
The full path to the log file.
Type
The log file type (BDB
for Berkeley DB
log files).
Status
The status of the log file (FREE
if the
file can be removed, or IN USE
if the
file is needed by the transaction subsystem)
SHOW ENGINE INNODB
STATUS
displays extensive information from the
standard InnoDB
Monitor about the state of
the InnoDB
storage engine. For information
about the standard monitor and other InnoDB
Monitors that provide information about
InnoDB
processing, see
Section 13.2.14.2, “SHOW ENGINE INNODB STATUS and the InnoDB Monitors”.
Older (and now deprecated) synonyms for these statements are
SHOW [BDB] LOGS
and SHOW
INNODB STATUS
.
SHOW ENGINE
can be used as of
MySQL 4.1.2.
Beginning with MySQL 4.1.3, if the server has the
NDBCLUSTER
storage engine enabled,
SHOW ENGINE NDB
STATUS
can be used to display cluster status
information. Sample output from this statement is shown here:
mysql> SHOW ENGINE NDB STATUS;
+-----------------------+---------+------+--------+
| free_list | created | free | sizeof |
+-----------------------+---------+------+--------+
| NdbTransaction | 5 | 0 | 208 |
| NdbOperation | 4 | 4 | 660 |
| NdbIndexScanOperation | 1 | 1 | 736 |
| NdbIndexOperation | 0 | 0 | 1060 |
| NdbRecAttr | 645 | 645 | 72 |
| NdbApiSignal | 16 | 16 | 136 |
| NdbLabel | 0 | 0 | 196 |
| NdbBranch | 0 | 0 | 24 |
| NdbSubroutine | 0 | 0 | 68 |
| NdbCall | 0 | 0 | 16 |
| NdbBlob | 2 | 2 | 204 |
| NdbReceiver | 2 | 0 | 68 |
+-----------------------+---------+------+--------+
12 rows in set (0.00 sec)
The most useful of the rows from the output of this statement are described in the following list:
NdbTransaction
: The number and size of
NdbTransaction
objects that have been
created. An NdbTransaction
is created
each time a table schema operation (such as
CREATE TABLE
or
ALTER TABLE
) is performed on
an NDB
table.
NdbOperation
: The number and size of
NdbOperation
objects that have been
created.
NdbIndexScanOperation
: The number and
size of NdbIndexScanOperation
objects
that have been created.
NdbIndexOperation
: The number and size of
NdbIndexOperation
objects that have been
created.
NdbRecAttr
: The number and size of
NdbRecAttr
objects that have been
created. In general, one of these is created each time a
data manipulation statement is performed by an SQL node.
NdbBlob
: The number and size of
NdbBlob
objects that have been created.
An NdbBlob
is created for each new
operation involving a BLOB
column in an NDB
table.
NdbReceiver
: The number and size of any
NdbReceiver
object that have been
created. The number in the created
column
is the same as the number of data nodes in the cluster to
which the MySQL server has connected.
SHOW ENGINE NDB
STATUS
returns an empty result if no operations
involving NDB
tables have been
performed by the MySQL client accessing the SQL node on which
this statement is run.
SHOW ENGINE
NDBCLUSTER STATUS
is a synonym for
SHOW ENGINE NDB
STATUS
.
SHOW [STORAGE] ENGINES
SHOW ENGINES
displays status
information about the server's storage engines. This is
particularly useful for checking whether a storage engine is
supported, or to see what the default engine is. This statement
is implemented in MySQL 4.1.2. SHOW TABLE
TYPES
is a synonym, but is deprecated and is removed
in MySQL 5.5.
mysql> SHOW ENGINES\G
*************************** 1. row ***************************
Engine: MyISAM
Support: DEFAULT
Comment: Default engine as of MySQL 3.23 with great performance
*************************** 2. row ***************************
Engine: HEAP
Support: YES
Comment: Alias for MEMORY
*************************** 3. row ***************************
Engine: MEMORY
Support: YES
Comment: Hash based, stored in memory, useful for temporary tables
*************************** 4. row ***************************
Engine: MERGE
Support: YES
Comment: Collection of identical MyISAM tables
*************************** 5. row ***************************
Engine: MRG_MYISAM
Support: YES
Comment: Alias for MERGE
*************************** 6. row ***************************
Engine: ISAM
Support: NO
Comment: Obsolete storage engine, now replaced by MyISAM
*************************** 7. row ***************************
Engine: MRG_ISAM
Support: NO
Comment: Obsolete storage engine, now replaced by MERGE
*************************** 8. row ***************************
Engine: InnoDB
Support: YES
Comment: Supports transactions, row-level locking, and foreign keys
*************************** 9. row ***************************
Engine: INNOBASE
Support: YES
Comment: Alias for INNODB
*************************** 10. row ***************************
Engine: BDB
Support: YES
Comment: Supports transactions and page-level locking
*************************** 11. row ***************************
Engine: BERKELEYDB
Support: YES
Comment: Alias for BDB
*************************** 12. row ***************************
Engine: NDBCLUSTER
Support: NO
Comment: Clustered, fault-tolerant, memory-based tables
*************************** 13. row ***************************
Engine: NDB
Support: NO
Comment: Alias for NDBCLUSTER
*************************** 14. row ***************************
Engine: EXAMPLE
Support: NO
Comment: Example storage engine
*************************** 15. row ***************************
Engine: ARCHIVE
Support: NO
Comment: Archive storage engine
*************************** 16. row ***************************
Engine: CSV
Support: NO
Comment: CSV storage engine
*************************** 17. row ***************************
Engine: BLACKHOLE
Support: NO
Comment: Storage engine designed to act as null storage
The Support
value indicates whether the
particular storage engine is supported, and which is the default
engine. For example, if the server is started with the
--default-table-type=InnoDB
option, the Support
value for the
InnoDB
row has the value
DEFAULT
. See
Chapter 13, Storage Engines.
All MySQL servers beginning with the 3.23 release series support
MyISAM
tables, because
MyISAM
is the default storage engine.
SHOW ERRORS [LIMIT [offset
,]row_count
] SHOW COUNT(*) ERRORS
This statement is similar to SHOW
WARNINGS
, except that instead of displaying errors,
warnings, and notes, it displays only errors.
SHOW ERRORS
is available as of
MySQL 4.1.0.
The LIMIT
clause has the same syntax as for
the SELECT
statement. See
Section 12.2.7, “SELECT Syntax”.
The SHOW COUNT(*) ERRORS
statement displays
the number of errors. You can also retrieve this number from the
error_count
variable:
SHOW COUNT(*) ERRORS; SELECT @@error_count;
For more information, see Section 12.4.5.26, “SHOW WARNINGS Syntax”.
SHOW GRANTS [FOR user
]
This statement lists the GRANT
statement or statements that must be issued to duplicate the
privileges that are granted to a MySQL user account. The account
is named using the same format as for the
GRANT
statement; for example,
'jeffrey'@'localhost'
. If you specify only
the user name part of the account name, a host name part of
'%'
is used. For additional information about
specifying account names, see Section 12.4.1.2, “GRANT Syntax”.
mysql> SHOW GRANTS FOR 'root'@'localhost';
+---------------------------------------------------------------------+
| Grants for root@localhost |
+---------------------------------------------------------------------+
| GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost' WITH GRANT OPTION |
+---------------------------------------------------------------------+
As of MySQL 4.1.2, to list the privileges granted to the account that you are using to connect to the server, you can use any of the following statements:
SHOW GRANTS; SHOW GRANTS FOR CURRENT_USER; SHOW GRANTS FOR CURRENT_USER();
Before MySQL 4.1.2, you can find out what user the session was
authenticated as by selecting the value of the
CURRENT_USER()
function (new in
MySQL 4.0.6). Then use that value in the
SHOW GRANTS
statement. See
Section 11.13, “Information Functions”.
SHOW GRANTS
displays only the
privileges granted explicitly to the named account. Other
privileges might be available to the account, but they are not
displayed. For example, if an anonymous account exists, the
named account might be able to use its privileges, but
SHOW GRANTS
will not display
them.
SHOW GRANTS
requires the
SELECT
privilege for the
mysql
database.
SHOW GRANTS
is available as of
MySQL 3.23.4.
SHOW {INDEX | INDEXES | KEYS} {FROM | IN}tbl_name
[{FROM | IN}db_name
]
SHOW INDEX
returns table index
information. The format resembles that of the
SQLStatistics
call in ODBC.
SHOW INDEX
returns the following
fields:
Table
The name of the table.
Non_unique
0 if the index cannot contain duplicates, 1 if it can.
Key_name
The name of the index.
Seq_in_index
The column sequence number in the index, starting with 1.
Column_name
The column name.
How the column is sorted in the index. In MySQL, this can
have values “A
” (Ascending)
or NULL
(Not sorted).
An estimate of the number of unique values in the index.
This is updated by running ANALYZE
TABLE
or myisamchk -a.
Cardinality
is counted based on
statistics stored as integers, so the value is not
necessarily exact even for small tables. The higher the
cardinality, the greater the chance that MySQL uses the
index when doing joins.
Sub_part
The number of indexed characters if the column is only
partly indexed, NULL
if the entire column
is indexed.
Packed
Indicates how the key is packed. NULL
if
it is not.
Null
Contains YES
if the column may contain
NULL
. If not, in MySQL 4.1 and earlier,
the column contains an empty string (''
).
Index_type
The index method used (BTREE
,
FULLTEXT
, HASH
,
RTREE
).
Comment
Various remarks. Before MySQL 4.0.2 when the
Index_type
column was added,
Comment
indicates whether an index is
FULLTEXT
.
The Packed
and Comment
columns were added in MySQL 3.23.0. The Null
and Index_type
columns were added in MySQL
4.0.2.
You can use
db_name
.tbl_name
as an alternative to the
syntax. These two
statements are equivalent:
tbl_name
FROM
db_name
SHOW INDEX FROM mytable FROM mydb; SHOW INDEX FROM mydb.mytable;
You can also list a table's indexes with the mysqlshow
-k db_name
tbl_name
command.
SHOW INNODB STATUS
This statement shows extensive information about the state of
the InnoDB
storage engine. As of MySQL 4.1.2,
it is deprecated and
SHOW ENGINE INNODB
STATUS
should be used instead. See
Section 12.4.5.9, “SHOW ENGINE Syntax”. SHOW INNODB
STATUS
is removed in MySQL 5.5.
SHOW [BDB] LOGS
SHOW LOGS
displays status information about
existing BDB
log files. It was implemented in
MySQL 3.23.29. An alias for it (available as of MySQL 4.1.1) is
SHOW BDB LOGS
. As of MySQL 4.1.2, this
statement is deprecated and
SHOW ENGINE BDB
LOGS
should be used instead. See
Section 12.4.5.9, “SHOW ENGINE Syntax”.
SHOW MASTER STATUS
This statement provides status information about the binary log
files of the master. It requires either the
SUPER
or
REPLICATION CLIENT
privilege.
Example:
mysql> SHOW MASTER STATUS;
+---------------+----------+--------------+------------------+
| File | Position | Binlog_Do_DB | Binlog_Ignore_DB |
+---------------+----------+--------------+------------------+
| mysql-bin.003 | 73 | test | manual,mysql |
+---------------+----------+--------------+------------------+
SHOW OPEN TABLES
SHOW OPEN TABLES
lists the
non-TEMPORARY
tables that are currently open
in the table cache. See Section 7.7.2, “How MySQL Opens and Closes Tables”.
SHOW OPEN TABLES
returns the
following columns:
Database
The database containing the table.
Table
The table name.
In_use
The number of table locks or lock requests there are for the
table. For example, if one client acquires a lock for a
table using LOCK TABLE t1 WRITE
,
In_use
will be 1. If another client
issues LOCK TABLE t1 WRITE
while the
table remains locked, the client will block waiting for the
lock, but the lock request causes In_use
to be 2. If the count is zero, the table is open but not
currently being used. In_use
is also
increased by the
HANDLER ...
OPEN
statement and decreased by
HANDLER ...
CLOSE
.
Name_locked
Whether the table name is locked. Name locking is used for operations such as dropping or renaming tables.
Before MySQL 4.0, SHOW OPEN
TABLES
displays information only for open tables in
the default database, and the output format is somewhat
different. The
Open_tables_in_
column indicates the table name, and the
db_name
Comment
column displays all other available
information.
SHOW OPEN TABLES
was added in
MySQL 3.23.33.
It is not possible to guarantee the order in which the tables are displayed in this output of this statement from one invokation to the next.
SHOW PRIVILEGES
SHOW PRIVILEGES
shows the list of
system privileges that the MySQL server supports. This statement
is implemented as of MySQL 4.1.0. The exact list of privileges
depends on the version of your server.
mysql> SHOW PRIVILEGES\G
*************************** 1. row ***************************
Privilege: Alter
Context: Tables
Comment: To alter the table
*************************** 2. row ***************************
Privilege: Create temporary tables
Context: Databases
Comment: To use CREATE TEMPORARY TABLE
*************************** 3. row ***************************
Privilege: Create
Context: Databases,Tables,Indexes
Comment: To create new databases and tables
*************************** 4. row ***************************
Privilege: Delete
Context: Tables
Comment: To delete existing rows
*************************** 5. row ***************************
Privilege: Drop
Context: Databases,Tables
Comment: To drop databases and tables
...
Privileges belonging to a specific user are displayed by the
SHOW GRANTS
statement. See
Section 12.4.5.12, “SHOW GRANTS Syntax”, for more information.
SHOW [FULL] PROCESSLIST
SHOW PROCESSLIST
shows you which
threads are running. You can also get this information using the
mysqladmin processlist command. If you have
the PROCESS
privilege, you can
see all threads. Otherwise, you can see only your own threads
(that is, threads associated with the MySQL account that you are
using). If you do not use the FULL
keyword,
only the first 100 characters of each statement are shown in the
Info
field.
This statement is very useful if you get the “too many
connections” error message and want to find out what is
going on. MySQL reserves one extra connection to be used by
accounts that have the SUPER
privilege, to ensure that administrators should always be able
to connect and check the system (assuming that you are not
giving this privilege to all your users).
Threads can be killed with the
KILL
statement. See
Section 12.4.6.3, “KILL Syntax”.
Here is an example of what SHOW
PROCESSLIST
output looks like:
mysql> SHOW FULL PROCESSLIST\G *************************** 1. row *************************** Id: 1 User: system user Host: db: NULL Command: Connect Time: 1030455 State: Waiting for master to send event Info: NULL *************************** 2. row *************************** Id: 2 User: system user Host: db: NULL Command: Connect Time: 1004 State: Has read all relay log; waiting for the slave I/O thread to update it Info: NULL *************************** 3. row *************************** Id: 3112 User: replikator Host: artemis:2204 db: NULL Command: Binlog Dump Time: 2144 State: Has sent all binlog to slave; waiting for binlog to be updated Info: NULL *************************** 4. row *************************** Id: 3113 User: replikator Host: iconnect2:45781 db: NULL Command: Binlog Dump Time: 2086 State: Has sent all binlog to slave; waiting for binlog to be updated Info: NULL *************************** 5. row *************************** Id: 3123 User: stefan Host: localhost db: apollon Command: Query Time: 0 State: NULL Info: SHOW FULL PROCESSLIST 5 rows in set (0.00 sec)
The columns have the following meaning:
Id
The connection identifier.
User
The MySQL user who issued the statement. If this is
system user
, it refers to a nonclient
thread spawned by the server to handle tasks internally.
This could be the I/O or SQL thread used on replication
slaves or a delayed-row handler. unauthenticated
user
refers to a thread that has become associated
with a client connection but for which authentication of the
client user has not yet been done. For system
user
, there is no host specified in the
Host
column.
Host
The host name of the client issuing the statement (except
for system user
where there is no host).
As of MySQL 4.0.12, SHOW
PROCESSLIST
reports the host name for TCP/IP
connections in
format to make it easier to determine which client is doing
what.
host_name
:client_port
db
The default database, if one is selected, otherwise
NULL
.
Command
The type of command the thread is executing. For
descriptions for thread commands, see
Section 7.11, “Examining Thread Information”. The value of this
column corresponds to the
COM_
commands of the client/server protocol and
xxx
Com_
status
variables. See Section 5.1.5, “Server Status Variables”
xxx
Time
The time in seconds that the thread has been in its current state.
State
An action, event, or state that indicates what the thread is
doing. Descriptions for State
values can
be found at Section 7.11, “Examining Thread Information”.
Most states correspond to very quick operations. If a thread stays in a given state for many seconds, there might be a problem that needs to be investigated.
For the SHOW PROCESSLIST
statement, the value of State
is
NULL
.
Info
The statement that the thread is executing, or
NULL
if it is not executing any
statement.
SHOW SLAVE HOSTS
Displays a list of replication slaves currently registered with
the master. Only slaves started with the
--report-host=
option are visible in this list.
host_name
The list is displayed on any server (not just the master server). The output looks like this:
mysql> SHOW SLAVE HOSTS
;
+------------+-----------+------+-----------+
| Server_id | Host | Port | Master_id |
+------------+-----------+------+-----------+
| 192168010 | iconnect2 | 3306 | 192168011 |
| 1921680101 | athena | 3306 | 192168011 |
+------------+-----------+------+-----------+
Server_id
: The unique server ID of the
slave server, as configured in the server's option file, or
on the command line with
--server-id=
.
value
Host
: The host name of the slave server,
as configured in the server's option file, or on the command
line with
--report-host=
.
Note that this can differ from the machine name as
configured in the operating system.
host_name
Port
: The port the slave server is
listening on.
Master_id
: The unique server ID of the
master server that the slave server is replicating from.
Some MySQL versions report another variable,
Rpl_recovery_rank
. This variable was never
used, and was eventually removed.
SHOW SLAVE STATUS
This statement provides status information on essential
parameters of the slave threads. It requires either the
SUPER
or
REPLICATION CLIENT
privilege.
If you issue this statement using the mysql
client, you can use a \G
statement terminator
rather than a semicolon to obtain a more readable vertical
layout:
mysql> SHOW SLAVE STATUS\G
*************************** 1. row ***************************
Slave_IO_State: Waiting for master to send event
Master_Host: localhost
Master_User: root
Master_Port: 3306
Connect_Retry: 3
Master_Log_File: gbichot-bin.005
Read_Master_Log_Pos: 79
Relay_Log_File: gbichot-relay-bin.005
Relay_Log_Pos: 548
Relay_Master_Log_File: gbichot-bin.005
Slave_IO_Running: Yes
Slave_SQL_Running: Yes
Replicate_Do_DB:
Replicate_Ignore_DB:
Last_Errno: 0
Last_Error:
Skip_Counter: 0
Exec_Master_Log_Pos: 79
Relay_Log_Space: 552
Until_Condition: None
Until_Log_File:
Until_Log_Pos: 0
Master_SSL_Allowed: No
Master_SSL_CA_File:
Master_SSL_CA_Path:
Master_SSL_Cert:
Master_SSL_Cipher:
Master_SSL_Key:
Seconds_Behind_Master: 8
Depending on your version of MySQL, you may not see all the fields just shown. In particular, several fields are present only as of MySQL 4.1.1.
SHOW SLAVE STATUS
returns the
following fields:
Slave_IO_State
A copy of the State
field of the
SHOW PROCESSLIST
output for
the slave I/O thread. This tells you what the thread is
doing: trying to connect to the master, waiting for events
from the master, reconnecting to the master, and so on.
Possible states are listed in
Section 14.3, “Replication Implementation Details”. For
versions of MySQL prior to 4.1.14, it is necessary to check
this field for connection problems. In those versions, the
thread could be running while unsuccessfully trying to
connect to the master; only this field makes you aware of
the problem. The state of the SQL thread is not copied
because it is simpler. If it is running, there is no
problem; if it is not, you can find the error in the
Last_Error
field (described later).
This field is present beginning with MySQL 4.1.1.
Master_Host
The master host that the slave is connected to.
Master_User
The user name of the account used to connect to the master.
Master_Port
The port used to connect to the master.
Connect_Retry
The number of seconds between connect retries (default 60).
This can be set with the CHANGE MASTER
TO
statement or
--master-connect-retry
option.
Master_Log_File
The name of the master binary log file from which the I/O thread is currently reading.
Read_Master_Log_Pos
The position in the current master binary log file up to which the I/O thread has read.
Relay_Log_File
The name of the relay log file from which the SQL thread is currently reading and executing.
Relay_Log_Pos
The position in the current relay log file up to which the SQL thread has read and executed.
Relay_Master_Log_File
The name of the master binary log file containing the most recent event executed by the SQL thread.
Slave_IO_Running
Whether the I/O thread is started and has connected successfully to the master. Internally, the state of this thread is represented by one of the following three values:
MYSQL_SLAVE_NOT_RUN.
The slave I/O thread is not running. For this state,
Slave_IO_Running
is
No
.
MYSQL_SLAVE_RUN_NOT_CONNECT.
The slave I/O thread is running, but is not connected
to a replication master. For this state,
Slave_IO_Running
depends on the
server version as shown in the following table.
MySQL Version | Slave_IO_Running |
---|---|
4.1 (4.1.13 and earlier); 5.0 (5.0.11 and earlier) | Yes |
4.1 (4.1.14 and later); 5.0 (5.0.12 and later) | No |
5.1, 5.4 | No |
5.5 | Connecting |
MYSQL_SLAVE_RUN_CONNECT.
The slave I/O thread is running, and is connected to a
replication master. For this state,
Slave_IO_Running
is
Yes
.
Slave_SQL_Running
Whether the SQL thread is started.
Replicate_Do_DB
,
Replicate_Ignore_DB
The lists of databases that were specified with the
--replicate-do-db
and
--replicate-ignore-db
options, if any.
These fields are present beginning with MySQL 4.1.1.
Replicate_Do_Table
,
Replicate_Ignore_Table
,
Replicate_Wild_Do_Table
,
Replicate_Wild_Ignore_Table
The lists of tables that were specified with the
--replicate-do-table
,
--replicate-ignore-table
,
--replicate-wild-do-table
,
and
--replicate-wild-ignore-table
options, if any.
These fields are present beginning with MySQL 4.1.1.
Last_Errno
, Last_Error
The error number and error message returned by the most
recently executed statement. An error number of 0 and
message of the empty string mean “no error.” If
the Last_Error
value is not empty, it
also appears as a message in the slave's error log. For
example:
Last_Errno: 1051 Last_Error: error 'Unknown table 'z'' on query 'drop table z'
The message indicates that the table z
existed on the master and was dropped there, but it did not
exist on the slave, so DROP
TABLE
failed on the slave. (This might occur, for
example, if you forget to copy the table to the slave when
setting up replication.)
When the slave SQL thread receives an error, it reports
the error first, then stops the SQL thread. This means
that there is a small window of time during which
SHOW SLAVE STATUS
shows a
nonzero value for Last_Errno
even
though Slave_SQL_Running
still displays
Yes
.
Skip_Counter
The current value of the
sql_slave_skip_counter
system variable. See
Section 12.5.2.6, “SET GLOBAL SQL_SLAVE_SKIP_COUNTER Syntax”.
Exec_Master_Log_Pos
The position in the current master binary file up to which
the SQL thread has read and executed. The coordinates given
by (Relay_Master_Log_File
,
Exec_Master_Log_Pos
) in the master's
binary log correspond to the coordinates given by
(Relay_Log_File
,
Relay_Log_Pos
) in the relay log.
Relay_Log_Space
The total combined size of all existing relay log files.
Until_Condition
,
Until_Log_File
,
Until_Log_Pos
The values specified in the UNTIL
clause
of the START SLAVE
statement.
Until_Condition
has these values:
None
if no UNTIL
clause was specified
Master
if the slave is reading until
a given position in the master's binary log
Relay
if the slave is reading until a
given position in its relay log
Until_Log_File
and
Until_Log_Pos
indicate the log file name
and position that define the coordinates at which the SQL
thread stops executing.
These fields are present beginning with MySQL 4.1.1.
Master_SSL_Allowed
,
Master_SSL_CA_File
,
Master_SSL_CA_Path
,
Master_SSL_Cert
,
Master_SSL_Cipher
,
Master_SSL_Key
These fields show the SSL parameters used by the slave to connect to the master, if any.
Master_SSL_Allowed
has these values:
Yes
if an SSL connection to the
master is permitted
No
if an SSL connection to the master
is not permitted
Ignored
if an SSL connection is
permitted but the slave server does not have SSL support
enabled
The values of the other SSL-related fields correspond to the
values of the MASTER_SSL_CA
,
MASTER_SSL_CAPATH
,
MASTER_SSL_CERT
,
MASTER_SSL_CIPHER
, and
MASTER_SSL_KEY
options to the
CHANGE MASTER TO
statement.
See Section 12.5.2.1, “CHANGE MASTER TO Syntax”.
These fields are present beginning with MySQL 4.1.1.
Seconds_Behind_Master
This field is present beginning with MySQL 4.1.1. It is been experimental and has been changed in MySQL 4.1.9. The following applies to slaves running MySQL 4.1.9 or newer. This field is an indication of how “late” the slave is:
When the slave SQL thread is actively processing updates, this field is the number of seconds that have elapsed since the timestamp of the most recent event on the master executed by that thread.
When the SQL thread has caught up to the slave I/O thread and is idle waiting for more events from the I/O thread, this field is zero.
In essence, this field measures the time difference in seconds between the slave SQL thread and the slave I/O thread.
If the network connection between master and slave is fast,
the slave I/O thread is very close to the master, so this
field is a good approximation of how late the slave SQL
thread is compared to the master. If the network is slow,
this is not a good approximation; the
slave SQL thread may quite often be caught up with the
slow-reading slave I/O thread, so
Seconds_Behind_Master
often shows a value
of 0, even if the I/O thread is late compared to the master.
In other words, this column is useful only for
fast networks.
This time difference computation works even though the
master and slave do not have identical clocks (the clock
difference is computed when the slave I/O thread starts, and
assumed to remain constant from then on).
Seconds_Behind_Master
is
NULL
(“unknown”) if the
slave SQL thread is not running, or if the slave I/O thread
is not running or not connected to master. For example, if
the slave I/O thread is running but is not connected to the
master and is sleeping for the number of seconds given by
the CHANGE MASTER TO
statement or
--master-connect-retry
option
(default 60) before reconnecting, the value is
NULL
. This is because the slave cannot
know what the master is doing, and so cannot say reliably
how late it is.
The value of this field is based on the timestamps stored in
events, which are preserved through replication. This means
that if a master M1 is itself a slave of M0, any event from
M1's binary log that originates from M0's binary log has
M0's timestamp for that event. This enables MySQL to
replicate TIMESTAMP
successfully. However, the problem for
Seconds_Behind_Master
is that if M1 also
receives direct updates from clients, the
Seconds_Behind_Master
value randomly
fluctuates because sometimes the last event from M1
originates from M0 and sometimes is the result of a direct
update on M1.
SHOW STATUS [LIKE 'pattern
']
SHOW STATUS
provides server
status information. This information also can be obtained using
the mysqladmin extended-status command. This
statement does not require any privilege. It requires only the
ability to connect to the server.
Partial output is shown here. The list of names and values may be different for your server. The meaning of each variable is given in Section 5.1.5, “Server Status Variables”.
mysql> SHOW STATUS;
+--------------------------+------------+
| Variable_name | Value |
+--------------------------+------------+
| Aborted_clients | 0 |
| Aborted_connects | 0 |
| Bytes_received | 155372598 |
| Bytes_sent | 1176560426 |
| Connections | 30023 |
| Created_tmp_disk_tables | 0 |
| Created_tmp_tables | 8340 |
| Created_tmp_files | 60 |
...
| Open_tables | 1 |
| Open_files | 2 |
| Open_streams | 0 |
| Opened_tables | 44600 |
| Questions | 2026873 |
...
| Table_locks_immediate | 1920382 |
| Table_locks_waited | 0 |
| Threads_cached | 0 |
| Threads_created | 30022 |
| Threads_connected | 1 |
| Threads_running | 1 |
| Uptime | 80380 |
+--------------------------+------------+
With a LIKE
clause, the statement
displays only rows for those variables with names that match the
pattern:
mysql> SHOW STATUS LIKE 'Key%';
+--------------------+----------+
| Variable_name | Value |
+--------------------+----------+
| Key_blocks_used | 14955 |
| Key_read_requests | 96854827 |
| Key_reads | 162040 |
| Key_write_requests | 7589728 |
| Key_writes | 3813196 |
+--------------------+----------+
SHOW TABLE STATUS [{FROM | IN}db_name
] [LIKE 'pattern
']
SHOW TABLE STATUS
works likes
SHOW TABLES
, but provides a lot
of information about each non-TEMPORARY
table. You can also get this list using the mysqlshow
--status db_name
command.
This statement was added in MySQL 3.23.
SHOW TABLE STATUS
returns the
following fields:
Name
The name of the table.
Engine
The storage engine for the table. See
Chapter 13, Storage Engines. Before MySQL 4.1.2, this
value is labeled as Type
.
Version
The version number of the table's .frm
file.
Row_format
The row-storage format (Fixed
,
Dynamic
, Compressed
,
Redundant
, Compact
).
For MyISAM
tables,
(Dynamic
corresponds to what
myisamchk -dvv reports as
Packed
. InnoDB
tables
are always in the Redundant
format.
Rows
The number of rows. Some storage engines, such as
MyISAM
and ISAM
, store
the exact count. For other storage engines, such as
InnoDB
, this value is an approximation,
and may vary from the actual value by as much as 40 to 50%.
In such cases, use SELECT COUNT(*)
to
obtain an accurate count.
Avg_row_length
The average row length.
Data_length
The length of the data file.
Max_data_length
The maximum length of the data file. This is the total number of bytes of data that can be stored in the table, given the data pointer size used.
Index_length
The length of the index file.
Data_free
The number of allocated but unused bytes.
Auto_increment
The next AUTO_INCREMENT
value.
Create_time
When the table was created.
Update_time
When the data file was last updated. For some storage
engines, this value is NULL
. For example,
InnoDB
stores multiple tables in its
tablespace and the data file timestamp does not apply. For
MyISAM
, the data file timestamp is used;
however, on Windows the timestamp is not updated by updates
so the value is inaccurate.
Check_time
When the table was last checked. Not all storage engines
update this time, in which case the value is always
NULL
.
Collation
The table's character set and collation. (Implemented in 4.1.1)
Checksum
The live checksum value (if any). (Implemented in 4.1.1)
Create_options
Extra options used with CREATE
TABLE
. The original options supplied when
CREATE TABLE
is called are
retained and the options reported here may differ from the
active table settings and options.
Comment
The comment used when creating the table (or information as to why MySQL could not access the table information).
In the table comment, InnoDB
tables report
the free space of the tablespace to which the table belongs. For
a table located in the shared tablespace, this is the free space
of the shared tablespace. If you are using multiple tablespaces
and the table has its own tablespace, the free space is for only
that table. Free space means the number of completely free 1MB
extents minus a safety margin. Even if free space displays as 0,
it may be possible to insert rows as long as new extents need
not be allocated.
For MEMORY
(HEAP
) tables,
the Data_length
,
Max_data_length
, and
Index_length
values approximate the actual
amount of allocated memory. The allocation algorithm reserves
memory in large amounts to reduce the number of allocation
operations.
For views, all the fields displayed by SHOW
TABLE STATUS
are NULL
except that
Name
indicates the view name and
Comment
says view
.
SHOW TABLES [{FROM | IN}db_name
] [LIKE 'pattern
']
SHOW TABLES
lists the
non-TEMPORARY
tables in a given database. You
can also get this list using the mysqlshow
db_name
command.
The output from SHOW TABLES
contains a single column of table names.
If you have no privileges for a table, the table does not show
up in the output from SHOW TABLES
or mysqlshow db_name.
SHOW [GLOBAL | SESSION] VARIABLES [LIKE 'pattern
']
SHOW VARIABLES
shows the values
of MySQL system variables. This information also can be obtained
using the mysqladmin variables command. This
statement does not require any privilege. It requires only the
ability to connect to the server.
The GLOBAL
and SESSION
modifiers are new in MySQL 4.0.3. With the
GLOBAL
modifier, SHOW
VARIABLES
displays the values that are used for new
connections to MySQL. With SESSION
, it
displays the values that are in effect for the current
connection. If no modifier is present, the default is
SESSION
. LOCAL
is a
synonym for SESSION
.
If the default system variable values are unsuitable, you can
set them using command options when mysqld
starts, and most can be changed at runtime with the
SET
statement. See Section 5.1.4, “Using System Variables”, and
Section 12.4.4, “SET Syntax”.
Partial output is shown here. The list of names and values may be different for your server. Section 5.1.3, “Server System Variables”, describes the meaning of each variable, and Section 7.8.2, “Tuning Server Parameters”, provides information about tuning them.
mysql> SHOW VARIABLES;
+---------------------------------+------------------------------+
| Variable_name | Value |
+---------------------------------+------------------------------|
| back_log | 50 |
| basedir | /usr/local/mysql |
| bdb_cache_size | 8388572 |
| bdb_log_buffer_size | 32768 |
| bdb_home | /usr/local/mysql |
...
| max_connections | 100 |
| max_connect_errors | 10 |
| max_delayed_threads | 20 |
| max_error_count | 64 |
| max_heap_table_size | 16777216 |
| max_join_size | 4294967295 |
| max_relay_log_size | 0 |
| max_sort_length | 1024 |
...
| timezone | EEST |
| tmp_table_size | 33554432 |
| tmpdir | /tmp/:/mnt/hd2/tmp/ |
| version | 4.1.18 |
| wait_timeout | 28800 |
+---------------------------------+------------------------------+
With a LIKE
clause, the statement
displays only rows for those variables with names that match the
pattern. To obtain the row for a specific variable, use a
LIKE
clause as shown:
SHOW VARIABLES LIKE 'max_join_size'; SHOW SESSION VARIABLES LIKE 'max_join_size';
To get a list of variables whose name match a pattern, use the
“%
” wildcard character in a
LIKE
clause:
SHOW VARIABLES LIKE '%size%'; SHOW GLOBAL VARIABLES LIKE '%size%';
Wildcard characters can be used in any position within the
pattern to be matched. Strictly speaking, because
“_
” is a wildcard that matches
any single character, you should escape it as
“\_
” to match it literally. In
practice, this is rarely necessary.
SHOW WARNINGS [LIMIT [offset
,]row_count
] SHOW COUNT(*) WARNINGS
SHOW WARNINGS
shows the error,
warning, and note messages that resulted from the last statement
that generated messages in the current session. It shows nothing
if the last statement used a table and generated no messages.
(That is, a statement that uses a table but generates no
messages clears the message list.) Statements that do not use
tables and do not generate messages have no effect on the
message list.
Warnings are generated for DML statements such as
INSERT
,
UPDATE
, and
LOAD DATA
INFILE
as well as DDL statements such as
CREATE TABLE
and
ALTER TABLE
.
SHOW WARNINGS
is implemented as
of MySQL 4.1.0. A related statement, SHOW
ERRORS
, shows only the errors. See
Section 12.4.5.11, “SHOW ERRORS Syntax”.
The SHOW COUNT(*) WARNINGS
statement displays
the total number of errors, warnings, and notes. You can also
retrieve this number from the
warning_count
variable:
SHOW COUNT(*) WARNINGS; SELECT @@warning_count;
The value of warning_count
might be greater than the number of messages displayed by
SHOW WARNINGS
if the
max_error_count
system variable
is set so low that not all messages are stored. An example shown
later in this section demonstrates how this can happen.
The LIMIT
clause has the same syntax as for
the SELECT
statement. See
Section 12.2.7, “SELECT Syntax”.
The MySQL server sends back the total number of errors,
warnings, and notes resulting from the last statement. If you
are using the C API, this value can be obtained by calling
mysql_warning_count()
. See
Section 17.6.6.70, “mysql_warning_count()”.
Note that the framework for warnings was added in MySQL 4.1.0,
at which point many statements did not generate warnings. In
4.1.1, the situation is much improved, with warnings generated
for statements such as
LOAD DATA
INFILE
and DML statements such as
INSERT
,
UPDATE
,
CREATE TABLE
, and
ALTER TABLE
.
The following DROP TABLE
statement results in a note:
mysql>DROP TABLE IF EXISTS no_such_table;
mysql>SHOW WARNINGS;
+-------+------+-------------------------------+ | Level | Code | Message | +-------+------+-------------------------------+ | Note | 1051 | Unknown table 'no_such_table' | +-------+------+-------------------------------+
Here is a simple example that shows a syntax warning for
CREATE TABLE
and conversion
warnings for INSERT
:
mysql>CREATE TABLE t1 (a TINYINT NOT NULL, b CHAR(4)) TYPE=MyISAM;
Query OK, 0 rows affected, 1 warning (0.00 sec) mysql>SHOW WARNINGS\G
*************************** 1. row *************************** Level: Warning Code: 1287 Message: 'TYPE=storage_engine' is deprecated, use 'ENGINE=storage_engine' instead 1 row in set (0.00 sec) mysql>INSERT INTO t1 VALUES(10,'mysql'),(NULL,'test'),
->(300,'Open Source');
Query OK, 3 rows affected, 4 warnings (0.01 sec) Records: 3 Duplicates: 0 Warnings: 4 mysql>SHOW WARNINGS\G
*************************** 1. row *************************** Level: Warning Code: 1265 Message: Data truncated for column 'b' at row 1 *************************** 2. row *************************** Level: Warning Code: 1263 Message: Data truncated, NULL supplied to NOT NULL column 'a' at row 2 *************************** 3. row *************************** Level: Warning Code: 1264 Message: Data truncated, out of range for column 'a' at row 3 *************************** 4. row *************************** Level: Warning Code: 1265 Message: Data truncated for column 'b' at row 3 4 rows in set (0.00 sec)
The maximum number of error, warning, and note messages to store
is controlled by the
max_error_count
system
variable. By default, its value is 64. To change the number of
messages you want stored, change the value of
max_error_count
. In the
following example, the ALTER
TABLE
statement produces three warning messages, but
only one is stored because
max_error_count
has been set to
1:
mysql>SHOW VARIABLES LIKE 'max_error_count';
+-----------------+-------+ | Variable_name | Value | +-----------------+-------+ | max_error_count | 64 | +-----------------+-------+ 1 row in set (0.00 sec) mysql>SET max_error_count=1;
Query OK, 0 rows affected (0.00 sec) mysql>ALTER TABLE t1 MODIFY b CHAR;
Query OK, 3 rows affected, 3 warnings (0.00 sec) Records: 3 Duplicates: 0 Warnings: 3 mysql>SELECT @@warning_count;
+-----------------+ | @@warning_count | +-----------------+ | 3 | +-----------------+ 1 row in set (0.01 sec) mysql>SHOW WARNINGS;
+---------+------+----------------------------------------+ | Level | Code | Message | +---------+------+----------------------------------------+ | Warning | 1263 | Data truncated for column 'b' at row 1 | +---------+------+----------------------------------------+ 1 row in set (0.00 sec)
To disable warnings, set
max_error_count
to 0. In this
case, warning_count
still
indicates how many warnings have occurred, but none of the
messages are stored.
As of MySQL 4.1.11, you can set the
sql_notes
session variable to 0
to cause Note
-level warnings not to be
recorded.
CACHE INDEXtbl_index_list
[,tbl_index_list
] ... INkey_cache_name
tbl_index_list
:tbl_name
[[INDEX|KEY] (index_name
[,index_name
] ...)]
The CACHE INDEX
statement assigns
table indexes to a specific key cache. It is used only for
MyISAM
tables. After the indexes have been
assigned, they can be preloaded into the cache if desired with
LOAD INDEX INTO
CACHE
.
The following statement assigns indexes from the tables
t1
, t2
, and
t3
to the key cache named
hot_cache
:
mysql> CACHE INDEX t1, t2, t3 IN hot_cache;
+---------+--------------------+----------+----------+
| Table | Op | Msg_type | Msg_text |
+---------+--------------------+----------+----------+
| test.t1 | assign_to_keycache | status | OK |
| test.t2 | assign_to_keycache | status | OK |
| test.t3 | assign_to_keycache | status | OK |
+---------+--------------------+----------+----------+
The syntax of CACHE INDEX
enables
you to specify that only particular indexes from a table should
be assigned to the cache. The current implementation assigns all
the table's indexes to the cache, so there is no reason to
specify anything other than the table name.
The key cache referred to in a CACHE
INDEX
statement can be created by setting its size
with a parameter setting statement or in the server parameter
settings. For example:
mysql> SET GLOBAL keycache1.key_buffer_size=128*1024;
Key cache parameters can be accessed as members of a structured system variable. See Section 5.1.4.1, “Structured System Variables”.
A key cache must exist before you can assign indexes to it:
mysql> CACHE INDEX t1 IN non_existent_cache;
ERROR 1284 (HY000): Unknown key cache 'non_existent_cache'
By default, table indexes are assigned to the main (default) key cache created at the server startup. When a key cache is destroyed, all indexes assigned to it become assigned to the default key cache again.
Index assignment affects the server globally: If one client assigns an index to a given cache, this cache is used for all queries involving the index, no matter which client issues the queries.
CACHE INDEX
was added in MySQL
4.1.1.
FLUSH [NO_WRITE_TO_BINLOG | LOCAL]flush_option
[,flush_option
] ...
The FLUSH
statement clears or
reloads various internal caches used by MySQL. One variant
acquires a lock. To execute
FLUSH
, you must have the
RELOAD
privilege.
Before MySQL 4.1.1, FLUSH
statements are not written to the binary log. As of MySQL 4.1.1,
FLUSH
statements are written to
the binary log so that they will be replicated to replication
slaves. Logging can be suppressed with the optional
NO_WRITE_TO_BINLOG
keyword or its alias
LOCAL
.
FLUSH LOGS
,
FLUSH MASTER
,
FLUSH SLAVE
,
and FLUSH TABLES WITH
READ LOCK
are not written to the binary log in any
case because they would cause problems if replicated to a
slave.
The RESET
statement is similar to
FLUSH
. See
Section 12.4.6.5, “RESET Syntax”, for information about using the
RESET
statement with replication.
flush_option
can be any of the
following items:
DES_KEY_FILE
Reloads the DES keys from the file that was specified with
the --des-key-file
option at
server startup time.
HOSTS
Empties the host cache tables. You should flush the host
tables if some of your hosts change IP address or if you get
the error message Host
'
.
When more than
host_name
' is blockedmax_connect_errors
errors
occur successively for a given host while connecting to the
MySQL server, MySQL assumes that something is wrong and
blocks the host from further connection requests. Flushing
the host tables enables further connection attempts from the
host. See Section B.5.2.6, “Host 'host_name' is blocked”. You can start
mysqld with
--max_connect_errors=999999999
to avoid this error message.
LOGS
Closes and reopens all log files. If you have specified an
update log file or a binary log file without an extension,
the extension number of the log file is incremented by one
relative to the previous file. If you have used an extension
in the file name, MySQL closes and reopens the update log or
binary log file. See Section 5.3.4, “The Binary Log”. On Unix,
this is the same thing as sending a
SIGHUP
signal to the
mysqld server (except on some Mac OS X
10.3 versions where mysqld ignores
SIGHUP
and SIGQUIT
).
Beginning with MySQL 4.0.10, if the server was started with
the --log-error
option),
error log file renaming occurs as described in
Section 5.3.1, “The Error Log”.
MASTER
Deletes all binary logs, resets the binary log index file
and creates a new binary log.
FLUSH
MASTER
is deprecated in favor of
RESET MASTER
, and is
supported for backward compatibility only. See
Section 12.5.1.2, “RESET MASTER Syntax”.
PRIVILEGES
Reloads the privileges from the grant tables in the
mysql
database. On Unix, this also occurs
if the server receives a SIGHUP
signal.
The server caches information in memory as a result of
GRANT
statements. This memory
is not released by the corresponding
REVOKE
statements, so for a
server that executes many instances of the statements that
cause caching, there will be an increase in memory use. This
cached memory can be freed with
FLUSH
PRIVILEGES
.
QUERY CACHE
Defragment the query cache to better utilize its memory.
FLUSH QUERY
CACHE
does not remove any queries from the cache,
unlike FLUSH
TABLES
or RESET QUERY CACHE
.
SLAVE
Resets all replication slave parameters, including relay log
files and replication position in the master's binary logs.
FLUSH SLAVE
is deprecated in favor of RESET
SLAVE
, and is supported for backward compatibility
only. See Section 12.5.2.5, “RESET SLAVE Syntax”.
STATUS
Resets most status variables to zero. This is something you should use only when debugging a query. See Section 1.8, “How to Report Bugs or Problems”.
TABLES
FLUSH
TABLES
has several variant forms.
FLUSH TABLE
is a synonym for
FLUSH
TABLES
, except that TABLE
does
not work with the WITH READ LOCK
variant.
FLUSH TABLES
Closes all open tables, forces all tables in use to be
closed, and flushes the query cache.
FLUSH
TABLES
also removes all query results from the
query cache, like the RESET QUERY
CACHE
statement.
FLUSH TABLES
tbl_name
[,
tbl_name
] ...
With a list of one or more comma-separated table names,
this is like
FLUSH
TABLES
with no names except that the server
flushes only the named tables. No error occurs if a
named table does not exist.
FLUSH TABLES WITH READ LOCK
Closes all open tables and locks all tables for all
databases with a global read lock until you explicitly
release the lock by executing
UNLOCK
TABLES
. This is a very convenient way to get
backups if you have a file system such as Veritas or ZFS
that can take snapshots in time.
FLUSH TABLES WITH
READ LOCK
acquires a global read lock and not
table locks, so it is not subject to the same behavior
as LOCK TABLES
and
UNLOCK
TABLES
with respect to table locking and
implicit commits:
UNLOCK
TABLES
implicitly commits any active
transaction only if any tables currently have been
locked with LOCK
TABLES
. The commit does not occur for
UNLOCK
TABLES
following
FLUSH TABLES
WITH READ LOCK
because the latter
statement does not acquire table locks.
Beginning a transaction causes table locks acquired
with LOCK TABLES
to
be released, as though you had executed
UNLOCK
TABLES
. Beginning a transaction does not
release a global read lock acquired with
FLUSH TABLES
WITH READ LOCK
.
USER_RESOURCES
Resets all per-hour user resources to zero. This enables
clients that have reached their hourly connection, query, or
update limits to resume activity immediately.
FLUSH
USER_RESOURCES
does not apply to the limit on
maximum simultaneous connections. See
Section 5.6.4, “Setting Account Resource Limits”.
The mysqladmin utility provides a
command-line interface to some flush operations, using commands
such as flush-hosts
,
flush-logs
,
flush-privileges
,
flush-status
, and
flush-tables
.
KILL thread_id
Each connection to mysqld runs in a separate
thread. You can see which threads are running with the
SHOW PROCESSLIST
statement and
kill a thread with the KILL
statement.
thread_id
If you have the PROCESS
privilege, you can see all threads. If you have the
SUPER
privilege, you can kill all
threads and statements. Otherwise, you can see and kill only
your own threads and statements.
You can also use the mysqladmin processlist and mysqladmin kill commands to examine and kill threads.
You cannot use KILL
with the
Embedded MySQL Server library because the embedded server
merely runs inside the threads of the host application. It
does not create any connection threads of its own.
When you use KILL
, a
thread-specific kill flag is set for the thread. In most cases,
it might take some time for the thread to die because the kill
flag is checked only at specific intervals:
In SELECT
, ORDER
BY
and GROUP BY
loops, the flag
is checked after reading a block of rows. If the kill flag
is set, the statement is aborted.
During ALTER TABLE
, the kill
flag is checked before each block of rows are read from the
original table. If the kill flag was set, the statement is
aborted and the temporary table is deleted.
During UPDATE
or
DELETE
operations, the kill
flag is checked after each block read and after each updated
or deleted row. If the kill flag is set, the statement is
aborted. Note that if you are not using transactions, the
changes are not rolled back.
GET_LOCK()
aborts and returns
NULL
.
An INSERT DELAYED
thread
quickly flushes (inserts) all rows it has in memory and then
terminates.
If the thread is in the table lock handler (state:
Locked
), the table lock is quickly
aborted.
If the thread is waiting for free disk space in a write call, the write is aborted with a “disk full” error message.
Some threads might refuse to be killed. For example,
REPAIR TABLE
,
CHECK TABLE
, and
OPTIMIZE TABLE
cannot be
killed before MySQL 4.1 and run to completion. This is
changed: REPAIR TABLE
and
OPTIMIZE TABLE
can be killed
as of MySQL 4.1.0, as can CHECK
TABLE
as of MySQL 4.1.3. However, killing a
REPAIR TABLE
or
OPTIMIZE TABLE
operation on a
MyISAM
table results in a table that
is corrupted and is unusable (reads and
writes to it fail) until you optimize or repair it again
(without interruption).
If CHECK TABLE
finds a
problem for an InnoDB
table, the server
shuts down to prevent error propagation. Details of the
error will be written to the error log.
LOAD INDEX INTO CACHEtbl_index_list
[,tbl_index_list
] ...tbl_index_list
:tbl_name
[[INDEX|KEY] (index_name
[,index_name
] ...)] [IGNORE LEAVES]
The LOAD INDEX INTO
CACHE
statement preloads a table index into the key
cache to which it has been assigned by an explicit
CACHE INDEX
statement, or into
the default key cache otherwise.
LOAD INDEX INTO
CACHE
is used only for MyISAM
tables.
The IGNORE LEAVES
modifier causes only blocks
for the nonleaf nodes of the index to be preloaded.
The following statement preloads nodes (index blocks) of indexes
for the tables t1
and t2
:
mysql> LOAD INDEX INTO CACHE t1, t2 IGNORE LEAVES;
+---------+--------------+----------+----------+
| Table | Op | Msg_type | Msg_text |
+---------+--------------+----------+----------+
| test.t1 | preload_keys | status | OK |
| test.t2 | preload_keys | status | OK |
+---------+--------------+----------+----------+
This statement preloads all index blocks from
t1
. It preloads only blocks for the nonleaf
nodes from t2
.
The syntax of LOAD
INDEX INTO CACHE
enables you to specify that only
particular indexes from a table should be preloaded. The current
implementation preloads all the table's indexes into the cache,
so there is no reason to specify anything other than the table
name.
LOAD INDEX INTO
CACHE
fails unless all indexes in a table have the
same block size. You can determine index block sizes for a table
by using myisamchk -dv and checking the
Blocksize
column.
LOAD INDEX INTO
CACHE
was added in MySQL 4.1.1.
RESETreset_option
[,reset_option
] ...
The RESET
statement is used to
clear the state of various server operations. You must have the
RELOAD
privilege to execute
RESET
.
RESET
acts as a stronger version
of the FLUSH
statement. See
Section 12.4.6.2, “FLUSH Syntax”.
reset_option
can be any of the
following:
MASTER
Deletes all binary logs listed in the index file, resets the
binary log index file to be empty, and creates a new binary
log file. Previously named
FLUSH
MASTER
. See
Section 12.5.1, “SQL Statements for Controlling Master Servers”.
QUERY CACHE
Removes all query results from the query cache.
SLAVE
Makes the slave forget its replication position in the
master binary logs. Also resets the relay log by deleting
any existing relay log files and beginning a new one.
Previously named
FLUSH
SLAVE
. See
Section 12.5.2, “SQL Statements for Controlling Slave Servers”.
Replication can be controlled through the SQL interface using the statements described in this section. One group of statements controls master servers, the other controls slave servers.
This section discusses statements for managing master replication servers. Section 12.5.2, “SQL Statements for Controlling Slave Servers”, discusses statements for managing slave servers.
In addition to the statements described here, the following
SHOW
statements are used with
master servers in replication. For information about these
statements, see Section 12.4.5, “SHOW Syntax”.
PURGE { BINARY | MASTER } LOGS { TO 'log_name
' | BEFOREdatetime_expr
}
The binary log is a set of files that contain information about data modifications made by the MySQL server. The log consists of a set of binary log files, plus an index file (see Section 5.3.4, “The Binary Log”).
The PURGE BINARY LOGS
statement
deletes all the binary log files listed in the log index file
prior to the specified log file name or date.
BINARY
and MASTER
are
synonyms, but only MASTER
can be used before
MySQL 4.1.1. Deleted log files also are removed from the list
recorded in the index file, so that the given log file becomes
the first in the list.
This statement has no effect if the server was not started with
the --log-bin
option to enable
binary logging.
Examples:
PURGE BINARY LOGS TO 'mysql-bin.010'; PURGE BINARY LOGS BEFORE '2008-04-02 22:46:26';
The BEFORE
variant's
datetime_expr
argument should
evaluate to a DATETIME
value (a
value in 'YYYY-MM-DD hh:mm:ss'
format).
This statement is safe to run while slaves are replicating. You need not stop them. If you have an active slave that currently is reading one of the log files you are trying to delete, this statement does nothing and fails with an error. However, if a slave is not connected and you happen to purge one of the log files it has yet to read, the slave will be unable to replicate after it reconnects.
To safely purge binary log files, follow this procedure:
On each slave server, use SHOW SLAVE
STATUS
to check which log file it is reading.
Obtain a listing of the binary log files on the master
server with SHOW BINARY LOGS
.
Determine the earliest log file among all the slaves. This is the target file. If all the slaves are up to date, this is the last log file on the list.
Make a backup of all the log files you are about to delete. (This step is optional, but always advisable.)
Purge all log files up to but not including the target file.
You can also set the
expire_logs_days
system
variable to expire binary log files automatically after a given
number of days (see Section 5.1.3, “Server System Variables”).
If you are using replication, you should set the variable no
lower than the maximum number of days your slaves might lag
behind the master.
RESET MASTER
Deletes all binary log files listed in the index file, resets the binary log index file to be empty, and creates a new binary log file. This statement is intended to be used only when the master is started for the first time.
This statement was named
FLUSH MASTER
before MySQL 3.23.26.
The effects of RESET MASTER
differ from those of PURGE BINARY
LOGS
in 2 key ways:
RESET MASTER
removes
all binary log files that are listed
in the index file, leaving only a single, empty binary log
file with a numeric suffix of .000001
,
whereas the numbering is not reset by
PURGE BINARY LOGS
.
RESET MASTER
is
not intended to be used while any
replication slaves are running. The behavior of
RESET MASTER
when used
while slaves are running is undefined (and thus
unsupported), whereas PURGE BINARY
LOGS
may be safely used while replication slaves
are running.
RESET MASTER
can prove useful
when you first set up the master and the slave, so that you can
verify the setup as follows:
Start the master and slave, and start replication (see Section 14.4, “How to Set Up Replication”).
Execute a few test queries on the master.
Check that the queries were replicated to the slave.
When replication is running correctly, issue
STOP SLAVE
followed by
RESET SLAVE
on the slave,
then verify that any unwanted data no longer exists on the
slave.
Issue RESET MASTER
on the
master to clean up the test queries.
After verifying the setup and getting rid of any unwanted and log files generated by testing, you can start the slave and begin replicating.
SET sql_log_bin = {0|1}
Disables or enables binary logging for the current session
(sql_log_bin
is a session
variable) if the client that has the
SUPER
privilege. The statement
fails with an error if the client does not have that privilege.
(Before MySQL 4.1.2, the statement was simply ignored in that
case.)
This section discusses statements for managing slave replication servers. Section 12.5.1, “SQL Statements for Controlling Master Servers”, discusses statements for managing master servers.
In addition to the statements described here,
SHOW SLAVE STATUS
is also used with
replication slaves. For information about this statement, see
Section 12.4.5.21, “SHOW SLAVE STATUS Syntax”.
CHANGE MASTER TOoption
[,option
] ...option
: MASTER_HOST = 'host_name
' | MASTER_USER = 'user_name
' | MASTER_PASSWORD = 'password
' | MASTER_PORT =port_num
| MASTER_CONNECT_RETRY =interval
| MASTER_LOG_FILE = 'master_log_name
' | MASTER_LOG_POS =master_log_pos
| RELAY_LOG_FILE = 'relay_log_name
' | RELAY_LOG_POS =relay_log_pos
| MASTER_SSL = {0|1} | MASTER_SSL_CA = 'ca_file_name
' | MASTER_SSL_CAPATH = 'ca_directory_name
' | MASTER_SSL_CERT = 'cert_file_name
' | MASTER_SSL_KEY = 'key_file_name
' | MASTER_SSL_CIPHER = 'cipher_list
'
CHANGE MASTER TO
changes the
parameters that the slave server uses for connecting to the
master server, for reading the master binary log, and reading
the slave relay log. It also updates the contents of the
master.info
and
relay-log.info
files. To use
CHANGE MASTER TO
, the slave
replication threads must be stopped (use
STOP SLAVE
if necessary).
Options not specified retain their value, except as indicated in the following discussion. Thus, in most cases, there is no need to specify options that do not change. For example, if the password to connect to your MySQL master has changed, you just need to issue these statements to tell the slave about the new password:
STOP SLAVE; -- if replication was running CHANGE MASTER TO MASTER_PASSWORD='new3cret'; START SLAVE; -- if you want to restart replication
MASTER_HOST
, MASTER_USER
,
MASTER_PASSWORD
, and
MASTER_PORT
provide information to the slave
about how to connect to its master:
MASTER_HOST
and
MASTER_PORT
are the host name (or IP
address) of the master host and its TCP/IP port.
Replication cannot use Unix socket files. You must be able to connect to the master MySQL server using TCP/IP.
If you specify the MASTER_HOST
or
MASTER_PORT
option, the slave assumes
that the master server is different from before (even if the
option value is the same as its current value.) In this
case, the old values for the master binary log file name and
position are considered no longer applicable, so if you do
not specify MASTER_LOG_FILE
and
MASTER_LOG_POS
in the statement,
MASTER_LOG_FILE=''
and
MASTER_LOG_POS=4
are silently appended to
it.
Setting MASTER_HOST=''
—that is,
setting its value explicitly to an empty string—is
not the same as not setting it at all.
Setting this option to an empty string causes
START SLAVE
subsequently to
fail. (Bug #28796)
MASTER_USER
and
MASTER_PASSWORD
are the user name and
password of the account to use for connecting to the master.
The MASTER_SSL_
options provide information about using SSL for the connection.
They correspond to the
xxx
--ssl-
options
described in Section 5.6.6.3, “SSL Command Options”. These options are
available beginning with MySQL 4.1.1. They can be changed even
on slaves that are compiled without SSL support. They are saved
to the xxx
master.info
file, but are ignored if
the slave does not have SSL support enabled.
MASTER_CONNECT_RETRY
specifies how many
seconds to wait between connect retries. The default is 60. The
number of reconnection attempts is limited
by the --master-retry-count
server option; for more information, see
Section 14.8, “Replication and Binary Logging Options and Variables”.
The relay log options (RELAY_LOG_FILE
and
RELAY_LOG_POS
) are available beginning with
MySQL 4.0.
MASTER_LOG_FILE
and
MASTER_LOG_POS
are the coordinates at which
the slave I/O thread should begin reading from the master the
next time the thread starts. RELAY_LOG_FILE
and RELAY_LOG_POS
are the coordinates at
which the slave SQL thread should begin reading from the relay
log the next time the thread starts. If you specify either of
MASTER_LOG_FILE
or
MASTER_LOG_POS
, you cannot specify
RELAY_LOG_FILE
or
RELAY_LOG_POS
. If neither of
MASTER_LOG_FILE
or
MASTER_LOG_POS
is specified, the slave uses
the last coordinates of the slave SQL
thread before CHANGE MASTER
TO
was issued. This ensures that replication has no
discontinuity, even if the slave SQL thread was late compared to
the slave I/O thread, when you just want to change, say, the
password to use. This safe behavior was introduced starting from
MySQL 4.0.17 and 4.1.1. (Before these versions, the coordinates
used were the last coordinates of the slave I/O thread before
CHANGE MASTER TO
was issued. This
caused the SQL thread to possibly lose some events from the
master, thus breaking replication.)
CHANGE MASTER TO
deletes all relay log files and starts a
new one, unless you specify RELAY_LOG_FILE
or
RELAY_LOG_POS
. In that case, relay log files
are kept; as of MySQL 4.1.1, the
relay_log_purge
global variable
is set silently to 0.
CHANGE MASTER TO
is useful for
setting up a slave when you have the snapshot of the master and
have recorded the master binary log coordinates corresponding to
the time of the snapshot. After loading the snapshot into the
slave to synchronize it to the slave, you can run
CHANGE MASTER TO
MASTER_LOG_FILE='
on
the slave to specify the coodinates at which the slave should
begin reading the master binary log.
log_name
',
MASTER_LOG_POS=log_pos
The following example changes the master server the slave uses and establishes the master binary log coordinates from which the slave begins reading. This is used when you want to set up the slave to replicate the master:
CHANGE MASTER TO MASTER_HOST='master2.mycompany.com', MASTER_USER='replication', MASTER_PASSWORD='bigs3cret', MASTER_PORT=3306, MASTER_LOG_FILE='master2-bin.001', MASTER_LOG_POS=4, MASTER_CONNECT_RETRY=10;
The next example shows an operation that is less frequently
employed. It is used when the slave has relay log files that you
want it to execute again for some reason. To do this, the master
need not be reachable. You need only use
CHANGE MASTER TO
and start the
SQL thread (START SLAVE SQL_THREAD
):
CHANGE MASTER TO RELAY_LOG_FILE='slave-relay-bin.006', RELAY_LOG_POS=4025;
You can even use the second operation in a nonreplication setup
with a standalone, nonslave server for recovery following a
crash. Suppose that your server has crashed and you have
restored it from a backup. You want to replay the server's own
binary log files (not relay log files, but regular binary log
files), named (for example) myhost-bin.*
.
First, make a backup copy of these binary log files in some safe
place, in case you don't exactly follow the procedure below and
accidentally have the server purge the binary log. If using
MySQL 4.1.1 or newer, use SET GLOBAL
relay_log_purge=0
for additional safety. Then start
the server without the --log-bin
option. Before MySQL 4.0.19, start it with a new server ID; in
newer versions there is no need; simply use the
--replicate-same-server-id
option. Start it with
--relay-log=myhost-bin
(to make
the server believe that these regular binary log files are relay
log files) and --skip-slave-start
options. After the server starts, issue these statements:
CHANGE MASTER TO RELAY_LOG_FILE='myhost-bin.153', RELAY_LOG_POS=410, MASTER_HOST='some_dummy_string'; START SLAVE SQL_THREAD;
The server reads and executes its own binary log files, thus
achieving crash recovery. Once the recovery is finished, run
STOP SLAVE
, shut down the server,
delete the master.info
and
relay-log.info
files, and restart the
server with its original options.
Specifying the MASTER_HOST
option (even with
a dummy value) is required to make the server think it is a
slave.
LOAD DATA FROM MASTER
This feature is deprecated and should be avoided. It is subject to removal in a future version of MySQL.
Since the current implementation of LOAD DATA FROM
MASTER
and LOAD TABLE FROM MASTER
is very limited, these statements are deprecated as of MySQL 4.1
and removed in MySQL 5.5.
The recommended alternative solution to using LOAD DATA
FROM MASTER
or LOAD TABLE FROM
MASTER
is using mysqldump or
mysqlhotcopy. The latter requires Perl and
two Perl modules (DBI
and
DBD:mysql
) and works for
MyISAM
and ARCHIVE
tables
only. With mysqldump, you can create SQL
dumps on the master and pipe (or copy) these to a
mysql client on the slave. This has the
advantage of working for all storage engines, but can be quite
slow, since it works using
SELECT
.
This statement takes a snapshot of the master and copies it to
the slave. It updates the values of
MASTER_LOG_FILE
and
MASTER_LOG_POS
so that the slave starts
replicating from the correct position. Any table and database
exclusion rules specified with the
--replicate-*-do-*
and
--replicate-*-ignore-*
options are honored.
--replicate-rewrite-db
is
not taken into account because a user could
use this option to set up a nonunique mapping such as
--replicate-rewrite-db="db1->db3"
and
--replicate-rewrite-db="db2->db3"
,
which would confuse the slave when loading tables from the
master.
Use of this statement is subject to the following conditions:
It works only for MyISAM
tables.
Attempting to load a non-MyISAM
table
results in the following error:
ERROR 1189 (08S01): Net error reading from master
It acquires a global read lock on the master while taking the snapshot, which prevents updates on the master during the load operation.
If you are loading large tables, you might have to increase the
values of net_read_timeout
and
net_write_timeout
on both the
master and slave servers. See
Section 5.1.3, “Server System Variables”.
Note that LOAD DATA FROM MASTER
does
not copy any tables from the
mysql
database. This makes it easy to have
different users and privileges on the master and the slave.
To use LOAD DATA FROM MASTER
, the replication
account that is used to connect to the master must have the
RELOAD
and
SUPER
privileges on the master
and the SELECT
privilege for all
master tables you want to load. All master tables for which the
user does not have the SELECT
privilege are ignored by LOAD DATA FROM
MASTER
. This is because the master hides them from the
user: LOAD DATA FROM MASTER
calls
SHOW DATABASES
to know the master
databases to load, but SHOW
DATABASES
returns only databases for which the user
has some privilege. See Section 12.4.5.8, “SHOW DATABASES Syntax”. On the
slave side, the user that issues LOAD DATA FROM
MASTER
must have privileges for dropping and creating
the databases and tables that are copied.
LOAD TABLE tbl_name
FROM MASTER
This feature is deprecated and should be avoided. It is subject to removal in a future version of MySQL.
Since the current implementation of LOAD DATA FROM
MASTER
and LOAD TABLE FROM MASTER
is very limited, these statements are deprecated as of MySQL 4.1
and removed in MySQL 5.5.
The recommended alternative solution to using LOAD DATA
FROM MASTER
or LOAD TABLE FROM
MASTER
is using mysqldump or
mysqlhotcopy. The latter requires Perl and
two Perl modules (DBI
and
DBD:mysql
) and works for
MyISAM
and ARCHIVE
tables
only. With mysqldump, you can create SQL
dumps on the master and pipe (or copy) these to a
mysql client on the slave. This has the
advantage of working for all storage engines, but can be quite
slow, since it works using
SELECT
.
Transfers a copy of the table from the master to the slave. This
statement is implemented mainly debugging LOAD DATA
FROM MASTER
operations. To use LOAD
TABLE
, the account used for connecting to the master
server must have the RELOAD
and
SUPER
privileges on the master
and the SELECT
privilege for the
master table to load. On the slave side, the user that issues
LOAD TABLE FROM MASTER
must have privileges
for dropping and creating the table.
The conditions for LOAD DATA FROM MASTER
apply here as well. For example, LOAD TABLE FROM
MASTER
works only for MyISAM
tables. The timeout notes for LOAD DATA FROM
MASTER
apply as well.
SELECT MASTER_POS_WAIT('master_log_file
',master_log_pos
[,timeout
])
This is actually a function, not a statement. It is used to ensure that the slave has read and executed events up to a given position in the master's binary log. See Section 11.14, “Miscellaneous Functions”, for a full description.
RESET SLAVE
RESET SLAVE
makes the slave
forget its replication position in the master's binary log. This
statement is meant to be used for a clean start: It deletes the
master.info
and
relay-log.info
files, all the relay log
files, and starts a new relay log file. To use
RESET SLAVE
, the slave
replication threads must be stopped (use
STOP SLAVE
if necessary).
All relay log files are deleted, even if they have not been
completely executed by the slave SQL thread. (This is a
condition likely to exist on a replication slave if you have
issued a STOP SLAVE
statement
or if the slave is highly loaded.)
Connection information stored in the
master.info
file is immediately reset using
any values specified in the corresponding startup options. This
information includes values such as master host, master port,
master user, and master password. If the slave SQL thread was in
the middle of replicating temporary tables when it was stopped,
and RESET SLAVE
is issued, these
replicated temporary tables are deleted on the slave.
This statement was named
FLUSH SLAVE
before MySQL 3.23.26.
SET GLOBAL SQL_SLAVE_SKIP_COUNTER = N
This statement skips the next N
events from the master. This is useful for recovering from
replication stops caused by a statement.
This statement is valid only when the slave threads are not running. Otherwise, it produces an error.
Before MySQL 4.0, omit the GLOBAL
keyword
from the statement.
When using this statement, it is important to understand that the binary log is actually organized as a sequence of groups known as event groups. Each event group consists of a sequence of events.
For transactional tables, an event group corresponds to a transaction.
For nontransactional tables, an event group corresponds to a single SQL statement.
A single transaction can contain changes to both transactional and nontransactional tables.
When you use SET [GLOBAL]
SQL_SLAVE_SKIP_COUNTER
to skip events and the result
is in the middle of a group, the slave continues to skip events
until it reaches the end of the group. Execution then starts
with the next event group.
START SLAVE [thread_type
[,thread_type
] ... ] START SLAVE [SQL_THREAD] UNTIL MASTER_LOG_FILE = 'log_name
', MASTER_LOG_POS =log_pos
START SLAVE [SQL_THREAD] UNTIL RELAY_LOG_FILE = 'log_name
', RELAY_LOG_POS =log_pos
thread_type
: IO_THREAD | SQL_THREAD
START SLAVE
with no
thread_type
options starts both of
the slave threads. The I/O thread reads events from the master
server and stores them in the relay log. The SQL thread reads
events from the relay log and executes them.
START SLAVE
requires the
SUPER
privilege.
If START SLAVE
succeeds in
starting the slave threads, it returns without any error.
However, even in that case, it might be that the slave threads
start and then later stop (for example, because they do not
manage to connect to the master or read its binary log, or some
other problem). START SLAVE
does
not warn you about this. You must check the slave's error log
for error messages generated by the slave threads, or check that
they are running satisfactorily with SHOW
SLAVE STATUS
.
START SLAVE
sends an
acknowledgment to the user after both the I/O thread and the SQL
thread have started. However, the I/O thread may not yet have
connected. For this reason, a successful
START SLAVE
causes
SHOW SLAVE STATUS
to show
Slave_SQL_Running=Yes
, but this does not
guarantee that Slave_IO_Running=Yes
(because
Slave_IO_Running=Yes
only if the I/O thread
is running and connected). For more
information, see Section 12.4.5.21, “SHOW SLAVE STATUS Syntax”.
As of MySQL 4.0.2, you can add IO_THREAD
and
SQL_THREAD
options to the statement to name
which of the threads to start.
As of MySQL 4.1.1, an UNTIL
clause may be
added to specify that the slave should start and run until the
SQL thread reaches a given point in the master binary log or in
the slave relay log. When the SQL thread reaches that point, it
stops. If the SQL_THREAD
option is specified
in the statement, it starts only the SQL thread. Otherwise, it
starts both slave threads. If the SQL thread is running, the
UNTIL
clause is ignored and a warning is
issued.
For an UNTIL
clause, you must specify both a
log file name and position. Do not mix master and relay log
options.
Any UNTIL
condition is reset by a subsequent
STOP SLAVE
statement, a
START SLAVE
statement that
includes no UNTIL
clause, or a server
restart.
The UNTIL
clause can be useful for debugging
replication, or to cause replication to proceed until just
before the point where you want to avoid having the slave
replicate an event. For example, if an unwise
DROP TABLE
statement was executed
on the master, you can use UNTIL
to tell the
slave to execute up to that point but no farther. To find what
the event is, use mysqlbinlog with the master
binary log or slave relay log, or by using a
SHOW BINLOG EVENTS
statement.
If you are using UNTIL
to have the slave
process replicated queries in sections, it is recommended that
you start the slave with the
--skip-slave-start
option to
prevent the SQL thread from running when the slave server
starts. It is probably best to use this option in an option file
rather than on the command line, so that an unexpected server
restart does not cause it to be forgotten.
The SHOW SLAVE STATUS
statement
includes output fields that display the current values of the
UNTIL
condition.
This statement is called SLAVE START
before
MySQL 4.0.5. SLAVE START
is still accepted
for backward compatibility, but is now deprecated.
STOP SLAVE [thread_type
[,thread_type
] ... ]thread_type
: IO_THREAD | SQL_THREAD
Stops the slave threads. STOP
SLAVE
requires the
SUPER
privilege.
Like START SLAVE
, as of MySQL
4.0.2, this statement may be used with the
IO_THREAD
and SQL_THREAD
options to name the thread or threads to be stopped.
This statement is called SLAVE STOP
before
MySQL 4.0.5. SLAVE STOP
is still accepted for
backward compatibility, but is deprecated.
Support for server-side prepared statements was added in MySQL 4.1.
This support takes advantage of the efficient client/server binary
protocol, provided that you use an appropriate client programming
interface. Candidate interfaces include the MySQL C API client
library (for C programs), MySQL Connector/J (for Java programs), and
MySQL Connector/Net. For example, the C API provides a set of
function calls that make up its prepared statement API. See
Section 17.6.7, “C API Prepared Statements”. Other language
interfaces can provide support for prepared statements that use the
binary protocol by linking in the C client library, one example
being the
mysqli
extension, available in PHP 5.0 and later.
Beginning with MySQL 4.1.3, an alternative SQL interface to prepared statements is available. This interface is not as efficient as using the binary protocol through a prepared statement API, but requires no programming because it is available directly at the SQL level:
You can use it when no programming interface is available to you.
You can use it from any program that enables you to send SQL statements to the server to be executed, such as the mysql client program.
You can use it even if the client is using an old version of the client library. The only requirement is that you be able to connect to a server that is recent enough to support SQL syntax for prepared statements.
SQL syntax for prepared statements is intended to be used for situations such as these:
You want to test how prepared statements work in your application before coding it.
An application has problems executing prepared statements and you want to determine interactively what the problem is.
You want to create a test case that describes a problem you are having with prepared statements, so that you can file a bug report.
You need to use prepared statements but do not have access to a programming API that supports them.
SQL syntax for prepared statements is based on three SQL statements:
PREPARE
prepares a statement for
execution (see Section 12.6.1, “PREPARE Syntax”).
EXECUTE
executes a prepared
statement (see Section 12.6.2, “EXECUTE Syntax”).
DEALLOCATE PREPARE
releases a
prepared statement (see Section 12.6.3, “DEALLOCATE PREPARE Syntax”).
The following examples show two equivalent ways of preparing a statement that computes the hypotenuse of a triangle given the lengths of the two sides.
The first example shows how to create a prepared statement by using a string literal to supply the text of the statement:
mysql>PREPARE stmt1 FROM 'SELECT SQRT(POW(?,2) + POW(?,2)) AS hypotenuse';
mysql>SET @a = 3;
mysql>SET @b = 4;
mysql>EXECUTE stmt1 USING @a, @b;
+------------+ | hypotenuse | +------------+ | 5 | +------------+ mysql>DEALLOCATE PREPARE stmt1;
The second example is similar, but supplies the text of the statement as a user variable:
mysql>SET @s = 'SELECT SQRT(POW(?,2) + POW(?,2)) AS hypotenuse';
mysql>PREPARE stmt2 FROM @s;
mysql>SET @a = 6;
mysql>SET @b = 8;
mysql>EXECUTE stmt2 USING @a, @b;
+------------+ | hypotenuse | +------------+ | 10 | +------------+ mysql>DEALLOCATE PREPARE stmt2;
Here is an additional example which demonstrates how to choose the table on which to perform a query at runtime, by storing the name of the table as a user variable:
mysql>USE test;
mysql>CREATE TABLE t1 (a INT NOT NULL);
mysql>INSERT INTO t1 VALUES (4), (8), (11), (32), (80);
mysql>SET @table = 't1';
mysql>SET @s = CONCAT('SELECT * FROM ', @table);
mysql>PREPARE stmt3 FROM @s;
mysql>EXECUTE stmt3;
+----+ | a | +----+ | 4 | | 8 | | 11 | | 32 | | 80 | +----+ mysql>DEALLOCATE PREPARE stmt3;
A prepared statement is specific to the session in which it was created. If you terminate a session without deallocating a previously prepared statement, the server deallocates it automatically.
To guard against too many prepared statements being created
simultaneously, set the
max_prepared_stmt_count
system
variable. To prevent the use of prepared statements, set the value
to 0.
The following SQL statements can be used in prepared statements:
ALTER TABLE COMMIT {CREATE | DROP} INDEX {CREATE | DROP} TABLE DELETE DO INSERT RENAME TABLE REPLACE SELECT SET SHOW (most variants) UPDATE
Other statements are not supported in MySQL 4.1.
SQL syntax for prepared statements cannot be used in nested fashion.
That is, a statement passed to
PREPARE
cannot itself be a
PREPARE
,
EXECUTE
, or
DEALLOCATE PREPARE
statement.
SQL syntax for prepared statements is distinct from using prepared
statement API calls. For example, you cannot use the
mysql_stmt_prepare()
C API function
to prepare a PREPARE
,
EXECUTE
, or
DEALLOCATE PREPARE
statement.
SQL syntax for prepared statements does not support multi-statements
(that is, multiple statements within a single string separated by
“;
” characters).
PREPAREstmt_name
FROMpreparable_stmt
The PREPARE
statement prepares a
SQL statement and assigns it a name,
stmt_name
, by which to refer to the
statement later. The prepared statement is executed with
EXECUTE
and released with
DEALLOCATE PREPARE
. For examples,
see Section 12.6, “SQL Syntax for Prepared Statements”.
Statement names are not case sensitive.
preparable_stmt
is either a string
literal or a user variable that contains the text of the SQL
statement. The text must represent a single statement, not
multiple statements. Within the statement, ?
characters can be used as parameter markers to indicate where data
values are to be bound to the query later when you execute it. The
?
characters should not be enclosed within
quotation marks, even if you intend to bind them to string values.
Parameter markers can be used only where data values should
appear, not for SQL keywords, identifiers, and so forth.
If a prepared statement with the given name already exists, it is deallocated implicitly before the new statement is prepared. This means that if the new statement contains an error and cannot be prepared, an error is returned and no statement with the given name exists.
The scope of a prepared statement is the session within which it is created, which as several implications:
A prepared statement created in one session is not available to other sessions.
When a session ends, whether normally or abnormally, its prepared statements no longer exist. If auto-reconnect is enabled, the client is not notified that the connection was lost. For this reason, clients may wish to disable auto-reconnect. See Section 17.6.14, “Controlling Automatic Reconnection Behavior”.
EXECUTEstmt_name
[USING @var_name
[, @var_name
] ...]
After preparing a statement with
PREPARE
, you execute it with an
EXECUTE
statement that refers to
the prepared statement name. If the prepared statement contains
any parameter markers, you must supply a USING
clause that lists user variables containing the values to be bound
to the parameters. Parameter values can be supplied only by user
variables, and the USING
clause must name
exactly as many variables as the number of parameter markers in
the statement.
You can execute a given prepared statement multiple times, passing different variables to it or setting the variables to different values before each execution.
For examples, see Section 12.6, “SQL Syntax for Prepared Statements”.
{DEALLOCATE | DROP} PREPARE stmt_name
To deallocate a prepared statement produced with
PREPARE
, use a
DEALLOCATE PREPARE
statement that
refers to the prepared statement name. Attempting to execute a
prepared statement after deallocating it results in an error.
For examples, see Section 12.6, “SQL Syntax for Prepared Statements”.
{DESCRIBE | DESC}tbl_name
[col_name
|wild
]
DESCRIBE
provides information about
the columns in a table. It is a shortcut for SHOW COLUMNS
FROM
. (See Section 12.4.5.5, “SHOW COLUMNS Syntax”.)
col_name
can be a column name, or a
string containing the SQL “%
” and
“_
” wildcard characters to obtain
output only for the columns with names matching the string. There
is no need to enclose the string within quotation marks unless it
contains spaces or other special characters.
mysql> DESCRIBE City;
+------------+----------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+------------+----------+------+-----+---------+----------------+
| Id | int(11) | | PRI | NULL | auto_increment |
| Name | char(35) | | | | |
| Country | char(3) | | UNI | | |
| District | char(20) | YES | MUL | | |
| Population | int(11) | | | 0 | |
+------------+----------+------+-----+---------+----------------+
5 rows in set (0.00 sec)
The description for SHOW COLUMNS
provides more information about the output columns (see
Section 12.4.5.5, “SHOW COLUMNS Syntax”).
If the data types differ from what you expect them to be based on
a CREATE TABLE
statement, note that
MySQL sometimes changes data types when you create or alter a
table. The conditions under which this occurs are described in
Section 12.1.5.2, “Silent Column Specification Changes”.
The DESCRIBE
statement is provided
for compatibility with Oracle.
The SHOW CREATE TABLE
,
SHOW TABLE STATUS
, and
SHOW INDEX
statements also provide
information about tables. See Section 12.4.5, “SHOW Syntax”.
EXPLAIN [EXTENDED] SELECT select_options
Or:
EXPLAIN tbl_name
The EXPLAIN
statement can be used
either as a synonym for DESCRIBE
or
as a way to obtain information about how MySQL executes a
SELECT
statement:
When you precede a SELECT
statement with the keyword
EXPLAIN
, MySQL displays
information from the optimizer about the query execution plan.
That is, MySQL explains how it would process the
SELECT
, including information
about how tables are joined and in which order. As of MySQL
4.1, EXPLAIN
EXTENDED
can be used to provide additional
information.
For information on how to use
EXPLAIN
and
EXPLAIN
EXTENDED
to obtain query execution plan information,
see Section 7.2.1, “Optimizing Queries with EXPLAIN”.
EXPLAIN
is synonymous
with tbl_name
DESCRIBE
or tbl_name
SHOW
COLUMNS FROM
.
tbl_name
For a description of the
DESCRIBE
and
SHOW COLUMNS
statements, see
Section 12.7.1, “DESCRIBE Syntax”, and
Section 12.4.5.5, “SHOW COLUMNS Syntax”.
HELP 'search_string
'
The HELP
statement returns online
information from the MySQL Reference manual. Its proper operation
requires that the help tables in the mysql
database be initialized with help topic information (see
Section 5.1.7, “Server-Side Help”).
The HELP
statement searches the
help tables for the given search string and displays the result of
the search. The search string is not case sensitive.
The HELP statement understands several types of search strings:
At the most general level, use contents
to
retrieve a list of the top-level help categories:
HELP 'contents'
For a list of topics in a given help category, such as
Data Types
, use the category name:
HELP 'data types'
For help on a specific help topic, such as the
ASCII()
function or the
CREATE TABLE
statement, use the
associated keyword or keywords:
HELP 'ascii' HELP 'create table'
In other words, the search string matches a category, many topics,
or a single topic. You cannot necessarily tell in advance whether
a given search string will return a list of items or the help
information for a single help topic. However, you can tell what
kind of response HELP
returned by
examining the number of rows and columns in the result set.
The following descriptions indicate the forms that the result set
can take. Output for the example statements is shown using the
familiar “tabular” or “vertical” format
that you see when using the mysql client, but
note that mysql itself reformats
HELP
result sets in a different
way.
Empty result set
No match could be found for the search string.
Result set containing a single row with three columns
This means that the search string yielded a hit for the help topic. The result has three columns:
name
: The topic name.
description
: Descriptive help text for
the topic.
example
: Usage example or examples.
This column might be blank.
Example: HELP 'replace'
Yields:
name: REPLACE description: Syntax: REPLACE(str,from_str,to_str) Returns the string str with all occurrences of the string from_str replaced by the string to_str. REPLACE() performs a case-sensitive match when searching for from_str. example: mysql> SELECT REPLACE('www.mysql.com', 'w', 'Ww'); -> 'WwWwWw.mysql.com'
Result set containing multiple rows with two columns
This means that the search string matched many help topics. The result set indicates the help topic names:
name
: The help topic name.
is_it_category
: Y
if
the name represents a help category, N
if it does not. If it does not, the
name
value when specified as the
argument to the HELP
statement should yield a single-row result set containing
a description for the named item.
Example: HELP 'status'
Yields:
+-----------------------+----------------+ | name | is_it_category | +-----------------------+----------------+ | SHOW | N | | SHOW ENGINE | N | | SHOW INNODB STATUS | N | | SHOW MASTER STATUS | N | | SHOW SLAVE STATUS | N | | SHOW STATUS | N | | SHOW TABLE STATUS | N | +-----------------------+----------------+
Result set containing multiple rows with three columns
This means the search string matches a category. The result set contains category entries:
source_category_name
: The help category
name.
name
: The category or topic name
is_it_category
: Y
if
the name represents a help category, N
if it does not. If it does not, the
name
value when specified as the
argument to the HELP
statement should yield a single-row result set containing
a description for the named item.
Example: HELP 'functions'
Yields:
+----------------------+-------------------------+----------------+ | source_category_name | name | is_it_category | +----------------------+-------------------------+----------------+ | Functions | CREATE FUNCTION | N | | Functions | DROP FUNCTION | N | | Functions | Bit Functions | Y | | Functions | Comparison operators | Y | | Functions | Control flow functions | Y | | Functions | Date and Time Functions | Y | | Functions | Encryption Functions | Y | | Functions | Information Functions | Y | | Functions | Logical operators | Y | | Functions | Miscellaneous Functions | Y | | Functions | Numeric Functions | Y | | Functions | String Functions | Y | +----------------------+-------------------------+----------------+
If you intend to use the HELP
statement while other tables are locked with
LOCK TABLES
, you must also lock the
required
mysql.help_
tables.
xxx
The HELP
statement was added in
MySQL 4.1.
USE db_name
The USE
statement tells MySQL to use the
db_name
db_name
database as the default
(current) database for subsequent statements. The database remains
the default until the end of the session or another
USE
statement is issued:
USE db1; SELECT COUNT(*) FROM mytable; # selects from db1.mytable USE db2; SELECT COUNT(*) FROM mytable; # selects from db2.mytable
Making a particular database the default by means of the
USE
statement does not preclude you
from accessing tables in other databases. The following example
accesses the author
table from the
db1
database and the editor
table from the db2
database:
USE db1; SELECT author_name,editor_name FROM author,db2.editor WHERE author.editor_id = db2.editor.editor_id;
The USE
statement is provided for
compatibility with Sybase.