|
Chapter 12. SQL Statement Syntax
This chapter describes the syntax for the SQL statements supported
by MySQL.
12.1. Data Definition Statements12.1.1. ALTER DATABASE SyntaxALTER {DATABASE | SCHEMA} [db_name ]
alter_specification ...
ALTER {DATABASE | SCHEMA} db_name
UPGRADE DATA DIRECTORY NAME
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.
ALTER
SCHEMA is a synonym for ALTER
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.
You can see what character sets and collations are available
using, respectively, the SHOW CHARACTER
SET and SHOW COLLATION
statements. See Section 12.5.5.4, “SHOW CHARACTER SET Syntax”, and
Section 12.5.5.5, “SHOW COLLATION Syntax”, for more information.
The database name can be omitted from the first syntax, in which
case the statement applies to the default database.
The syntax that includes the UPGRADE DATA DIRECTORY
NAME clause was added in MySQL 5.1.23. It updates the
name of the directory associated with the database to use the
encoding implemented in MySQL 5.1 for mapping database names to
database directory names (see
Section 8.2.3, “Mapping of Identifiers to File Names”). This clause is for use
under these conditions:
It is intended when upgrading MySQL to 5.1 or later from older
versions.
It is intended to update a database directory name to the
current encoding format if the name contains special
characters that need encoding.
The statement is used by mysqlcheck (as
invoked by mysql_upgrade).
For example,if a database in MySQL 5.0 has a name of
a-b-c , the name contains instance of the
‘- ’ character. In 5.0, the database
directory is also named a-b-c , which is not
necessarily safe for all file systems. In MySQL 5.1 and up, the
same database name is encoded as a@002db@002dc
to produce a file system-neutral directory name.
When a MySQL installation is upgraded to MySQL 5.1 or later from
an older version,the server displays a name such as
a-b-c (which is in the old format) as
#mysql50#a-b-c , and you must refer to the name
using the #mysql50# prefix. Use
UPGRADE DATA DIRECTORY NAME in this case to
explicitly tell the server to re-encode the database directory
name to the current encoding format:
ALTER DATABASE `#mysql50#a-b-c` UPGRADE DATA DIRECTORY NAME;
After executing this statement, you can refer to the database as
a-b-c without the special
#mysql50# prefix.
MySQL Enterprise
In a production environment, alteration of a database is not a
common occurrence and may indicate a security breach. Advisors
provided as part of the MySQL Enterprise Monitor automatically
alert you when data definition statements are issued. For more
information, see
http://www.mysql.com/products/enterprise/advisors.html.
12.1.2. ALTER EVENT SyntaxALTER
[DEFINER = { user | CURRENT_USER }]
EVENT event_name
[ON SCHEDULE schedule ]
[ON COMPLETION [NOT] PRESERVE]
[RENAME TO new_event_name ]
[ENABLE | DISABLE | DISABLE ON SLAVE]
[COMMENT 'comment ']
[DO sql_statement ]
The ALTER EVENT statement is used
to change one or more of the characteristics of an existing event
without the need to drop and recreate it. The syntax for each of
the DEFINER , ON SCHEDULE ,
ON COMPLETION , COMMENT ,
ENABLE / DISABLE , and
DO clauses is exactly the same as
when used with CREATE EVENT . (See
Section 12.1.11, “CREATE EVENT Syntax”.)
Support for the DEFINER clause was added in
MySQL 5.1.17.
Beginning with MySQL 5.1.12, this statement requires the
EVENT privilege. When a user
executes a successful ALTER EVENT
statement, that user becomes the definer for the affected event.
(In MySQL 5.1.11 and earlier, an event could be altered only by
its definer, or by a user having the
SUPER privilege.)
ALTER EVENT works only with an
existing event:
mysql> ALTER EVENT no_such_event
> ON SCHEDULE
> EVERY '2:3' DAY_HOUR;
ERROR 1517 (HY000): Unknown event 'no_such_event'
In each of the following examples, assume that the event named
myevent is defined as shown here:
CREATE EVENT myevent
ON SCHEDULE
EVERY 6 HOUR
COMMENT 'A sample comment.'
DO
UPDATE myschema.mytable SET mycol = mycol + 1;
The following statement changes the schedule for
myevent from once every six hours starting
immediately to once every twelve hours, starting four hours from
the time the statement is run:
ALTER EVENT myevent
ON SCHEDULE
EVERY 12 HOUR
STARTS CURRENT_TIMESTAMP + INTERVAL 4 HOUR;
It is possible to change multiple characteristics of an event in a
single statement. This example changes the SQL statement executed
by myevent to one that deletes all records from
mytable ; it also changes the schedule for the
event such that it executes once, one day after this
ALTER EVENT statement is run.
ALTER TABLE myevent
ON SCHEDULE
AT CURRENT_TIMESTAMP + INTERVAL 1 DAY
DO
TRUNCATE TABLE myschema.mytable;
It is necessary to include only those options in an
ALTER EVENT statement which
correspond to characteristics that you actually wish to change;
options which are omitted retain their existing values. This
includes any default values for CREATE
EVENT such as ENABLE .
To disable myevent , use this
ALTER EVENT statement:
ALTER EVENT myevent
DISABLE;
The ON SCHEDULE clause may use expressions
involving built-in MySQL functions and user variables to obtain
any of the timestamp or
interval values which it contains. You
may not use stored routines or user-defined functions in such
expressions, nor may you use any table references; however, you
may use SELECT FROM DUAL . This is true for both
ALTER EVENT and
CREATE EVENT statements. Beginning
with MySQL 5.1.13, references to stored routines, user-defined
functions, and tables in such cases are specifically disallowed,
and fail with an error (see Bug#22830).
An ALTER EVENT statement that
contains another ALTER EVENT
statement in its DO clause appears
to succeed; however, when the server attempts to execute the
resulting scheduled event, the execution fails with an error.
To rename an event, use the ALTER
EVENT statement's RENAME TO clause.
This statement renames the event myevent to
yourevent :
ALTER EVENT myevent
RENAME TO yourevent;
You can also move an event to a different database using
ALTER EVENT ... RENAME TO ... and
db_name.event_name
notation, as shown here:
ALTER EVENT olddb.myevent
RENAME TO newdb.myevent;
To execute the previous statement, the user executing it must have
the EVENT privilege on both the
olddb and newdb databases.
Note
There is no RENAME EVENT statement.
Beginning with MySQL 5.1.18, a third value may also appear in
place of ENABLED or
DISABLED ; DISABLE ON SLAVE
is used on a replication slave to indicate an event which was
created on the master and replicated to the slave, but which is
not executed on the slave. Normally, DISABLE ON
SLAVE is set automatically as required; however, there
are some circumstances under which you may want or need to change
it manually. See Section 16.3.1.8, “Replication of Invoked Features”,
for more information.
12.1.3. ALTER LOGFILE GROUP SyntaxALTER LOGFILE GROUP logfile_group
ADD UNDOFILE 'file_name '
[INITIAL_SIZE [=] size ]
[WAIT]
ENGINE [=] engine_name
This statement adds an UNDO file named
'file_name ' to an existing log file
group logfile_group . An ALTER
LOGFILE GROUP statement has one and only one
ADD UNDOFILE clause. No DROP
UNDOFILE clause is currently supported.
Note
All MySQL Cluster Disk Data objects share the same namespace.
This means that each Disk Data object must
be uniquely named (and not merely each Disk Data object of a
given type). For example, you cannot have a tablespace and an
undo log file with the same name, or an undo log file and a data
file with the same name.
Prior to MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, path and
file names for undo log files could not be longer than 128
characters. (Bug#31769)
The optional INITIAL_SIZE parameter sets the
UNDO file's initial size in bytes; if not
specified, the initial size default to 128M
(128 megabytes). You may optionally follow
size with a one-letter abbreviation for
an order of magnitude, similar to those used in
my.cnf . Generally, this is one of the letters
M (for megabytes) or G (for
gigabytes).
On 32-bit systems, the maximum supported value for
INITIAL_SIZE is 4G .
(Bug#29186)
Beginning with MySQL Cluster NDB 2.1.18, 6.3.24, and 7.0.4, the
minimum allowed value for INITIAL_SIZE is
1M . (Bug#29574)
Note
WAIT is parsed but otherwise ignored, and so
has no effect in MySQL 5.1 and MySQL Cluster NDB 6.x. It is
intended for future expansion.
The ENGINE parameter (required) determines the
storage engine which is used by this log file group, with
engine_name being the name of the
storage engine. In MySQL 5.1 and MySQL Cluster NDB 6.x, the only
accepted values for engine_name are
“NDBCLUSTER ” and
“NDB ”. The two values
are equivalent.
Here is an example, which assumes that the log file group
lg_3 has already been created using
CREATE LOGFILE GROUP (see
Section 12.1.14, “CREATE LOGFILE GROUP Syntax”):
ALTER LOGFILE GROUP lg_3
ADD UNDOFILE 'undo_10.dat'
INITIAL_SIZE=32M
ENGINE=NDBCLUSTER;
When ALTER LOGFILE GROUP is used with
ENGINE = NDBCLUSTER (alternatively,
ENGINE = NDB ), an UNDO log
file is created on each MySQL Cluster data node. You can verify
that the UNDO files were created and obtain
information about them by querying the
INFORMATION_SCHEMA.FILES table. For
example:
mysql> SELECT FILE_NAME, LOGFILE_GROUP_NUMBER, EXTRA
-> FROM INFORMATION_SCHEMA.FILES
-> WHERE LOGFILE_GROUP_NAME = 'lg_3';
+-------------+----------------------+----------------+
| FILE_NAME | LOGFILE_GROUP_NUMBER | EXTRA |
+-------------+----------------------+----------------+
| newdata.dat | 0 | CLUSTER_NODE=3 |
| newdata.dat | 0 | CLUSTER_NODE=4 |
| undo_10.dat | 11 | CLUSTER_NODE=3 |
| undo_10.dat | 11 | CLUSTER_NODE=4 |
+-------------+----------------------+----------------+
4 rows in set (0.01 sec)
(See Section 20.21, “The INFORMATION_SCHEMA FILES Table”.)
ALTER LOGFILE GROUP was added in MySQL 5.1.6.
In MySQL 5.1 and MySQL Cluster NDB 6.x, it is useful only with
Disk Data storage for MySQL Cluster. For more information, see
Section 17.5.10, “MySQL Cluster Disk Data Tables”.
12.1.4. ALTER FUNCTION SyntaxALTER FUNCTION func_name [characteristic ...]
characteristic :
{ CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA }
| SQL SECURITY { DEFINER | INVOKER }
| COMMENT 'string '
This statement can be used to change the characteristics of a
stored function. More than one change may be specified in an
ALTER FUNCTION statement. However,
you cannot change the parameters or body of a stored function
using this statement; to make such changes, you must drop and
re-create the function using DROP
FUNCTION and CREATE
FUNCTION .
You must have the ALTER ROUTINE
privilege for the function. (That privilege is granted
automatically to the function creator.) If binary logging is
enabled, the ALTER FUNCTION
statement might also require the
SUPER privilege, as described in
Section 19.6, “Binary Logging of Stored Programs”.
12.1.5. ALTER PROCEDURE SyntaxALTER PROCEDURE proc_name [characteristic ...]
characteristic :
{ CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA }
| SQL SECURITY { DEFINER | INVOKER }
| COMMENT 'string '
This statement can be used to change the characteristics of a
stored procedure. More than one change may be specified in an
ALTER PROCEDURE statement. However,
you cannot change the parameters or body of a stored procedure
using this statement; to make such changes, you must drop and
re-create the procedure using DROP
PROCEDURE and CREATE
PROCEDURE .
You must have the ALTER ROUTINE
privilege for the procedure. (That privilege is granted
automatically to the procedure creator.)
12.1.6. ALTER SERVER SyntaxALTER SERVER server_name
OPTIONS (option [, option ] ...)
Alters the server information for
server_name ,
adjusting the specified options as per the
CREATE SERVER command. See
Section 12.1.16, “CREATE SERVER Syntax”. The corresponding fields in the
mysql.servers table are updated accordingly.
This statement requires the SUPER
privilege.
For example, to update the USER option:
ALTER SERVER s OPTIONS (USER 'sally');
ALTER SERVER does not cause an
automatic commit.
ALTER SERVER was added in MySQL
5.1.15.
12.1.7. ALTER TABLE SyntaxALTER [ONLINE | OFFLINE] [IGNORE] TABLE tbl_name
alter_specification [, alter_specification ] ...
alter_specification :
table_options
| ADD [COLUMN] col_name column_definition
[FIRST | AFTER col_name ]
| ADD [COLUMN] (col_name column_definition ,...)
| ADD {INDEX|KEY} [index_name ]
[index_type ] (index_col_name ,...) [index_option ] ...
| ADD [CONSTRAINT [symbol ]] PRIMARY KEY
[index_type ] (index_col_name ,...) [index_option ] ...
| ADD [CONSTRAINT [symbol ]]
UNIQUE [INDEX|KEY] [index_name ]
[index_type ] (index_col_name ,...) [index_option ] ...
| ADD FULLTEXT [INDEX|KEY] [index_name ]
(index_col_name ,...) [index_option ] ...
| ADD SPATIAL [INDEX|KEY] [index_name ]
(index_col_name ,...) [index_option ] ...
| ADD [CONSTRAINT [symbol ]]
FOREIGN KEY [index_name ] (index_col_name ,...)
reference_definition
| ALTER [COLUMN] col_name {SET DEFAULT literal | DROP DEFAULT}
| CHANGE [COLUMN] old_col_name new_col_name column_definition
[FIRST|AFTER col_name ]
| MODIFY [COLUMN] col_name column_definition
[FIRST | AFTER col_name ]
| DROP [COLUMN] col_name
| DROP PRIMARY KEY
| DROP {INDEX|KEY} index_name
| DROP FOREIGN KEY fk_symbol
| DISABLE KEYS
| ENABLE KEYS
| RENAME [TO] new_tbl_name
| ORDER BY col_name [, col_name ] ...
| CONVERT TO CHARACTER SET charset_name [COLLATE collation_name ]
| [DEFAULT] CHARACTER SET [=] charset_name [COLLATE [=] collation_name ]
| DISCARD TABLESPACE
| IMPORT TABLESPACE
| partition_options
| ADD PARTITION (partition_definition )
| DROP PARTITION partition_names
| COALESCE PARTITION number
| REORGANIZE PARTITION [partition_names INTO (partition_definitions )]
| ANALYZE PARTITION {partition_names | ALL }
| CHECK PARTITION {partition_names | ALL }
| OPTIMIZE PARTITION {partition_names | ALL }
| REBUILD PARTITION {partition_names | ALL }
| REPAIR PARTITION {partition_names | ALL }
| REMOVE PARTITIONING
index_col_name :
col_name [(length )] [ASC | DESC]
index_type :
USING {BTREE | HASH | RTREE}
index_option :
KEY_BLOCK_SIZE [=] value
| index_type
| WITH PARSER parser_name
table_options :
table_option [[,] table_option ] ...
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 allowable alterations is similar to
clauses of the CREATE TABLE
statement. See Section 12.1.17, “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. These
warnings can be displayed with SHOW
WARNINGS . See Section 12.5.5.42, “SHOW WARNINGS Syntax”.
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.
In some cases, no temporary table is necessary:
Alterations that modify only table metadata and not table data
can be made immediately by altering the table's
.frm file and not touching table
contents. The following changes are fast alterations that can
be made this way:
Renaming a column or index.
Changing the default value of a column.
Changing the definition of an
ENUM or
SET column by adding new
enumeration or set members to the end
of the list of valid member values.
Changing default column values or data types online is
currently not supported by MySQL Cluster (see the
Limitations
discussed later in this section).
In some cases, an operation such as changing a
VARCHAR(10) column to
VARCHAR(15) may be immediate, but this
depends on the storage engine for the table. A change such as
VARCHAR(10) to a length greater than 255 is
not immediate because data values must be modified from using
one byte to store the length to using two bytes.
If you use ALTER TABLE
tbl_name RENAME TO
new_tbl_name without any
other options, MySQL simply renames any files that correspond
to the table tbl_name . (You can
also use the RENAME TABLE
statement to rename tables. See
Section 12.1.33, “RENAME TABLE Syntax”.) Any privileges granted
specifically for the renamed table are not migrated to the new
name. They must be changed manually.
ALTER TABLE ... ADD PARTITION creates no
temporary table except for MySQL Cluster.
ADD or DROP operations
for RANGE or LIST
partitions are immediate operations or nearly so.
ADD or COALESCE
operations for HASH or
KEY partitions copy data between changed
partitions; unless LINEAR HASH or
LINEAR KEY was used, this is much the same
as creating a new table (although the operation is done
partition by partition). REORGANIZE
operations copy only changed partitions and do not touch
unchanged ones.
If other cases, MySQL creates a temporary table, even if the data
wouldn't strictly need to be copied. 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.
You can force an ALTER TABLE operation to use
the temporary table method (as supported in MySQL 5.0) by setting
old-alter-table to ON .
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.
Beginning with MySQL 5.1.7, ADD INDEX and
DROP INDEX operations are
performed online when the indexes are on variable-width
columns only.
The ONLINE keyword can be used to perform
online ADD COLUMN , ADD
INDEX (including CREATE INDEX
statements), and DROP INDEX
operations on NDBCLUSTER tables
beginning with MySQL Cluster NDB 6.2.5 and MySQL Cluster NDB
6.3.3. Online renaming of
NDBCLUSTER tables is also
supported.
Currently you cannot add disk-based columns to
NDBCLUSTER tables online. This
means that, if you wish to add an in-memory column to an
NDBCLUSTER table that uses a
table-level STORAGE DISK option, you must
declare the new column as using memory-based storage
explicitly. For example — assuming that you have already
created tablespace ts1 — suppose that
you create table t1 as follows:
mysql> CREATE TABLE t1 (
> c1 INT NOT NULL PRIMARY KEY,
> c2 VARCHAR(30)
> )
> TABLESPACE ts1 STORAGE DISK
> ENGINE NDBCLUSTER;
Query OK, 0 rows affected (1.73 sec)
Records: 0 Duplicates: 0 Warnings: 0
You can add a new in-memory column to this table online as
shown here:
mysql> ALTER ONLINE TABLE t1 ADD COLUMN c3 INT COLUMN_FORMAT DYNAMIC STORAGE MEMORY;
Query OK, 0 rows affected (1.25 sec)
Records: 0 Duplicates: 0 Warnings: 0
This statement fails if the STORAGE MEMORY
option is omitted:
mysql> ALTER ONLINE TABLE t1 ADD COLUMN c3 INT COLUMN_FORMAT DYNAMIC;
ERROR 1235 (42000): This version of MySQL doesn't yet support
'ALTER ONLINE TABLE t1 ADD COLUMN c3 INT COLUMN_FORMAT DYNAMIC'
If you omit the COLUMN_FORMAT DYNAMIC
option, the dynamic column format is employed automatically,
but a warning is issued, as shown here:
mysql> ALTER ONLINE TABLE t1 ADD COLUMN c3 INT STORAGE MEMORY;
Query OK, 0 rows affected, 1 warning (1.17 sec)
Records: 0 Duplicates: 0 Warnings: 0
mysql> SHOW WARNINGS;
+---------+------+---------------------------------------------------------------+
| Level | Code | Message |
+---------+------+---------------------------------------------------------------+
| Warning | 1478 | Converted FIXED field to DYNAMIC to enable on-line ADD COLUMN |
+---------+------+---------------------------------------------------------------+
1 row in set (0.00 sec)
mysql> SHOW CREATE TABLE t1\G
*************************** 1. row ***************************
Table: t1
Create Table: CREATE TABLE `t1` (
`c1` int(11) NOT NULL,
`c2` varchar(30) DEFAULT NULL,
`c3` int(11) /*!50120 STORAGE MEMORY */ /*!50120 COLUMN_FORMAT DYNAMIC */ DEFAULT NULL,
`t4` int(11) /*!50120 STORAGE MEMORY */ DEFAULT NULL,
PRIMARY KEY (`c1`)
) /*!50100 TABLESPACE ts_1 STORAGE DISK */ ENGINE=ndbcluster DEFAULT CHARSET=latin1
1 row in set (0.03 sec)
Prior to MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, adding
in-memory columns to tables that were created using a
table-level or column-level STORAGE DISK
option did not work correctly. (Bug#42549)
It is also possible to rename
MyISAM tables and columns online.
However, you cannot use ONLINE with
operations that add or drop columns or indexes of
MyISAM tables.
Online operations are noncopying; that is, they do not require
that indexes be re-created. They do not lock the table being
altered from access my other API nodes in a MySQL Cluster (but
see Limitations later in this section).
Such operations do not require single user mode for
NDBCLUSTER table alterations made
in a cluster with multiple API nodes; transactions can
continue uninterrupted during online DDL operations.
In MySQL Cluster NDB 7.0, it is also possible to use the
statement ALTER ONLINE TABLE ... REORGANIZE
PARTITION with no
partition_names INTO
(partition_definitions )
option on NDBCLUSTER tables. This
can be used to redistribute MySQL Cluster data among new data
nodes that have been added to the cluster online. More
information about this statement is given later in this
section. For more information about adding data nodes online
to a MySQL Cluster, see
Section 17.5.11, “Adding MySQL Cluster Data Nodes Online”.
Prior to MySQL Cluster NDB 6.4.3, ALTER ONLINE TABLE
... REORGANIZE PARTITION with no
partition_names INTO
(partition_definitions )
option did not work correctly with Disk Data tables or with
in-memory NDBCLUSTER tables
having one or more disk-based columns. (Bug#42549)
The ONLINE and OFFLINE
keywords are supported only in MySQL Cluster NDB 6.2, 6.3, 7.0
(beginning with versions 6.2.5, 6.3.3, and 6.4.0), and later
MySQL Cluster release series. In other versions of MySQL
(5.1.17 and later):
The server determines automatically whether an
ADD INDEX or
DROP INDEX operation can
be (and is) performed online or offline; if the column
is of a variable-width data type, then the operation is
performed online. It is not possible to override the
server behavior in this regard.
Attempting to use the ONLINE or
OFFLINE keyword in an
ALTER TABLE statement
results in an error.
Limitations.
Online ALTER TABLE operations
that add columns are subject to the following limitations:
The table being altered is not locked with respect to
API nodes other than the one on which an online
ALTER TABLE ,
ADD COLUMN , CREATE
INDEX or DROP INDEX
statement is run. However, the table is locked against
any other operations originating on the
same API node while the online
operation is being executed.
The table to be altered must have an explicit primary
key; the hidden primary key created by the
NDBCLUSTER storage engine
is not sufficient for this purpose. Columns to be
added online must meet the following criteria:
Such columns must be dynamic; that is, it must be
possible to create them using
COLUMN_FORMAT DYNAMIC .
Such columns must be nullable, and not have any
explicit default value other than
NULL . Columns added online are
automatically created as DEFAULT
NULL , as can be seen here:
mysql> CREATE TABLE t1 (
> c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY
> ) ENGINE=NDBCLUSTER;
Query OK, 0 rows affected (1.44 sec)
mysql> ALTER ONLINE TABLE t1
> ADD COLUMN c2 INT,
> ADD COLUMN c3 INT;
Query OK, 0 rows affected, 2 warnings (0.93 sec)
mysql> SHOW CREATE TABLE t2\G
*************************** 1. row ***************************
Table: t2
Create Table: CREATE TABLE `t2` (
`c1` int(11) NOT NULL AUTO_INCREMENT,
`c2` int(11) DEFAULT NULL,
`c3` int(11) DEFAULT NULL,
PRIMARY KEY (`c1`)
) ENGINE=ndbcluster DEFAULT CHARSET=latin1
1 row in set (0.00 sec)
Columns must be added following any existing
columns. If you attempt to add a column online
before any existing columns, the statement fails
with an error. Trying to add a column online using
the FIRST keyword also fails.
In addition, existing table columns cannot be
reordered online.
The storage engine used by the table cannot be
changed online.
The preceding limitations do not apply to operations
that merely rename tables or columns.
If the storage engine supports online
ALTER TABLE , then
fixed-format columns will be converted to dynamic when
columns are added online, or when indexes are created
or dropped online, as shown here:
mysql> CREATE TABLE t1 (
> c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY
> ) ENGINE=NDBCLUSTER;
Query OK, 0 rows affected (1.44 sec)
mysql> ALTER ONLINE TABLE t1 ADD COLUMN c2 INT, ADD COLUMN c3 INT;
Query OK, 0 rows affected, 2 warnings (0.93 sec)
Records: 0 Duplicates: 0 Warnings: 0
mysql> SHOW WARNINGS;
+---------+------+---------------------------------------------------------------+
| Level | Code | Message |
+---------+------+---------------------------------------------------------------+
| Warning | 1475 | Converted FIXED field to DYNAMIC to enable on-line ADD COLUMN |
| Warning | 1475 | Converted FIXED field to DYNAMIC to enable on-line ADD COLUMN |
+---------+------+---------------------------------------------------------------+
2 rows in set (0.00 sec)
Note
Existing columns, including the table's primary key,
need not be dynamic; only the column or columns to
be added online must be dynamic.
mysql> CREATE TABLE t2 (
> c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY COLUMN_FORMAT FIXED
> ) ENGINE=NDBCLUSTER;
Query OK, 0 rows affected (2.10 sec)
mysql> ALTER ONLINE TABLE t2 ADD COLUMN c2 INT;
Query OK, 0 rows affected, 1 warning (0.78 sec)
Records: 0 Duplicates: 0 Warnings: 0
mysql> SHOW WARNINGS;
+---------+------+---------------------------------------------------------------+
| Level | Code | Message |
+---------+------+---------------------------------------------------------------+
| Warning | 1475 | Converted FIXED field to DYNAMIC to enable on-line ADD COLUMN |
+---------+------+---------------------------------------------------------------+
1 row in set (0.00 sec)
Columns are not converted from
FIXED to DYNAMIC
column format by renaming operations. For more
information about COLUMN_FORMAT ,
see Section 12.1.17, “CREATE TABLE Syntax”.
Online DROP COLUMN operations are
not supported.
A given online ALTER
TABLE can use only one of ADD
COLUMN , ADD INDEX , or
DROP INDEX . One or more
columns can be added online in a single statement;
only one index may be created or dropped online in a
single statement.
The KEY , CONSTRAINT , and
IGNORE keywords are supported in
ALTER TABLE statements using
the ONLINE keyword.
The ONLINE and OFFLINE
keywords are also supported in ALTER TABLE ... CHANGE
... statements that rename columns of
MyISAM tables.
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.17, “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;
The outcome of attempting to change a table's storage engine
is affected by whether the desired storage engine is available
and the setting of the
NO_ENGINE_SUBSTITUTION SQL
mode, as described in Section 5.1.8, “Server SQL Modes”.
As of MySQL 5.1.11, to prevent inadvertent loss of data,
ALTER TABLE cannot be used to
change the storage engine of a table to
MERGE or BLACKHOLE .
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 , if the value is less than
the current maximum value in the column, no error occurs and
the current sequence value is not changed.
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 allows 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 col_name ,
and 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.17, “CREATE TABLE Syntax”.
You can rename a column using a CHANGE
old_col_name
new_col_name
column_definition clause.
To do so, specify the old and new column names and the
definition that the column currently has. For example, to
rename an 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;
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.
Warning
This conversion may result in alteration of data. For
example, if you shorten a string column, values may be
truncated. To prevent the operation from succeeding if
conversions to the new data type would result in loss of
data, enable strict SQL mode before using
ALTER TABLE (see
Section 5.1.8, “Server SQL Modes”).
To add a column at a specific position within a table row, use
FIRST or AFTER
col_name . The default is
to add the column last. You can also use
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.24, “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.
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.
Some storage engines allow you to specify an index type when
creating an index. The syntax for the
index_type specifier is
USING type_name .
For details about USING , see
Section 12.1.13, “CREATE INDEX Syntax”. Before MySQL 5.1.10,
USING can be given only before the index
column list. As of 5.1.10, the preferred position is after the
column list. Use of the option before the column list will no
longer be recognized in a future MySQL release.
index_option values specify
additional options for an index. USING is
one such option. For details about allowable
index_option values, see
Section 12.1.13, “CREATE INDEX Syntax”.
After an ALTER TABLE statement,
it may be necessary to run ANALYZE
TABLE to update index cardinality information. See
Section 12.5.5.23, “SHOW 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 allows for 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 allowed as sort criteria; arbitrary
expressions are not allowed.
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.
Note
When used on a partitioned table, ALTER TABLE ...
ORDER BY orders rows within each partition only.
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.
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.
ENABLE KEYS and DISABLE
KEYS were not supported for partitioned tables prior
to MySQL 5.1.11.
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 [symbol ]]
FOREIGN KEY (...) REFERENCES ... (...) . See
Section 13.6.4.4, “FOREIGN KEY Constraints”. For other
storage engines, the clauses are parsed but ignored. The
CHECK clause is parsed but ignored by all
storage engines. See Section 12.1.17, “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.8.5, “MySQL Differences from Standard SQL”.
Important
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.
InnoDB supports the use of
ALTER TABLE to drop foreign
keys:
ALTER TABLE tbl_name DROP FOREIGN KEY fk_symbol ;
For more information, see
Section 13.6.4.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;
See Section 13.6.2.1, “Using Per-Table Tablespaces”.
Pending INSERT DELAYED
statements are lost if a table is write locked and
ALTER TABLE is used to modify
the table structure.
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 TABLE tbl_name CONVERT TO CHARACTER SET charset_name ;
For a column that has a data type of
VARCHAR or one of the
TEXT types, CONVERT TO
CHARACTER SET will change the data type as necessary
to ensure that the new column is long enough to store as many
characters as the original column. For example, a
TEXT column has two length
bytes, which store the byte-length of values in the column, up
to a maximum of 65,535. For a latin1
TEXT column, each character
requires a single byte, so the column can store up to 65,535
characters. If the column is converted to
utf8 , each character might require up to
three bytes, for a maximum possible length of 3 ? 65,535
= 196,605 bytes. That length will not fit in a
TEXT column's length bytes, so
MySQL will convert the data type to
MEDIUMTEXT , which is the
smallest string type for which the length bytes can record a
value of 196,605. Similarly, a
VARCHAR column might be
converted to MEDIUMTEXT .
To avoid data type changes of the type just described, do not
use CONVERT TO CHARACTER SET . Instead, use
MODIFY to change individual columns. For
example:
ALTER TABLE t MODIFY latin1_text_col TEXT CHARACTER SET utf8;
ALTER TABLE t MODIFY latin1_varchar_col VARCHAR(M ) CHARACTER SET utf8;
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.
Warning
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 TABLE tbl_name DEFAULT CHARACTER SET charset_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 ).
A number of partitioning-related extensions to
ALTER TABLE were added in MySQL
5.1.5. These can be used with partitioned tables for
repartitioning, for adding, dropping, merging, and splitting
partitions, and for performing partitioning maintenance.
Simply using a partition_options
clause with ALTER TABLE on a
partitioned table repartitions the table according to the
partitioning scheme defined by the
partition_options . This clause
always begins with PARTITION BY , and
follows the same syntax and other rules as apply to the
partition_options clause for
CREATE TABLE (see
Section 12.1.17, “CREATE TABLE Syntax”, for more detailed
information), and can also be used to partition an existing
table that is not already partitioned. For example, consider a
(nonpartitioned) table defined as shown here:
CREATE TABLE t1 (
id INT,
year_col INT
);
This table can be partitioned by HASH ,
using the id column as the partitioning
key, into 8 partitions by means of this statement:
ALTER TABLE t1
PARTITION BY HASH(id)
PARTITIONS 8;
The table that results from using an ALTER TABLE ...
PARTITION BY statement must follow the same rules as
one created using CREATE TABLE ... PARTITION
BY . This includes the rules governing the
relationship between any unique keys (including any primary
key) that the table might have, and the column or columns used
in the partitioning expression, as discussed in
Section 18.5.1, “Partitioning Keys, Primary Keys, and Unique Keys”.
The CREATE TABLE ... PARTITION BY rules for
specifying the number of partitions also apply to
ALTER TABLE ... PARTITION BY .
ALTER TABLE ... PARTITION BY became
available in MySQL 5.1.6.
The partition_definition clause for
ALTER TABLE ADD PARTITION supports the same
options as the clause of the same name for the
CREATE TABLE statement. (See
Section 12.1.17, “CREATE TABLE Syntax”, for the syntax and
description.) Suppose that you have the partitioned table
created as shown here:
CREATE TABLE t1 (
id INT,
year_col INT
)
PARTITION BY RANGE (year_col) (
PARTITION p0 VALUES LESS THAN (1991),
PARTITION p1 VALUES LESS THAN (1995),
PARTITION p2 VALUES LESS THAN (1999)
);
You can add a new partition p3 to this
table for storing values less than 2002 as
follows:
ALTER TABLE t1 ADD PARTITION (PARTITION p3 VALUES LESS THAN (2002));
DROP PARTITION can be used to drop one or
more RANGE or LIST
partitions. This statement cannot be used with
HASH or KEY partitions;
instead, use COALESCE PARTITION (see
below). Any data that was stored in the dropped partitions
named in the partition_names list
is discarded. For example, given the table
t1 defined previously, you can drop the
partitions named p0 and
p1 as shown here:
ALTER TABLE t1 DROP PARTITION p0, p1;
ADD PARTITION and DROP
PARTITION do not currently support IF [NOT]
EXISTS . It is also not possible to rename a
partition or a partitioned table. Instead, if you wish to
rename a partition, you must drop and re-create the partition;
if you wish to rename a partitioned table, you must instead
drop all partitions, rename the table, and then add back the
partitions that were dropped.
COALESCE PARTITION can be used with a table
that is partitioned by HASH or
KEY to reduce the number of partitions by
number . Suppose that you have
created table t2 using the following
definition:
CREATE TABLE t2 (
name VARCHAR (30),
started DATE
)
PARTITION BY HASH( YEAR(started) )
PARTITIONS 6;
You can reduce the number of partitions used by
t2 from 6 to 4 using the following
statement:
ALTER TABLE t2 COALESCE PARTITION 2;
The data contained in the last
number partitions will be merged
into the remaining partitions. In this case, partitions 4 and
5 will be merged into the first 4 partitions (the partitions
numbered 0, 1, 2, and 3).
To change some but not all the partitions used by a
partitioned table, you can use REORGANIZE
PARTITION . This statement can be used in several
ways:
To merge a set of partitions into a single partition. This
can be done by naming several partitions in the
partition_names list and
supplying a single definition for
partition_definition .
To split an existing partition into several partitions.
You can accomplish this by naming a single partition for
partition_names and providing
multiple partition_definitions .
To change the ranges for a subset of partitions defined
using VALUES LESS THAN or the value
lists for a subset of partitions defined using
VALUES IN .
This statement may also be used without the
partition_names INTO
(partition_definitions )
option on tables that are automatically partitioned using
HASH partitioning in order to force
redistribution of data. (Currently, only
NDBCLUSTER tables are
automatically partitioned in this way.) This is useful in
MySQL Cluster NDB 6.4.0 and later where, after you have
added new MySQL Cluster data nodes online to an existing
MySQL Cluster, you wish to redistribute existing MySQL
Cluster table data to the new data nodes. In such cases,
you should invoke the satement with the
ONLINE option; in words words, as shown
here:
ALTER ONLINE TABLE table REORGANIZE PARTITION;
You cannot perform other DDL concurrently with online
table reorganization — that is, no other DDL
statements can be issued while an ALTER ONLINE
TABLE ... REORGANIZE PARTITION statement is
executing. For more information about adding MySQL Cluster
data nodes online, see
Section 17.5.11, “Adding MySQL Cluster Data Nodes Online”.
Attempting to use REORGANIZE PARTITION
without the
partition_names INTO
(partition_definitions )
option on explicitly partitioned tables results in the
error REORGANIZE PARTITION without parameters
can only be used on auto-partitioned tables using HASH
partitioning.
Note
For partitions that have not been explicitly named, MySQL
automatically provides the default names
p0 , p1 ,
p2 , and so on. As of MySQL 5.1.7, the
same is true with regard to subpartitions.
For more detailed information about and examples of
ALTER TABLE ... REORGANIZE PARTITION
statements, see
Section 18.3.1, “Management of RANGE and LIST
Partitions”.
Important
Only a single PARTITION BY , ADD
PARTITION , DROP PARTITION ,
REORGANIZE PARTITION , or
COALESCE PARTITION clause can be used in
a given ALTER TABLE
statement.
Several additional options were introduced in MySQL 5.1.5 for
providing partition maintenance and repair functionality
analogous to that implemented for nonpartitioned tables by
statements such as CHECK TABLE
and REPAIR TABLE (which are
also supported for partitioned tables, beginning with MySQL
5.1.27 — see note at the end of this item). These
include ANALYZE PARTITION , CHECK
PARTITION , OPTIMIZE PARTITION ,
REBUILD PARTITION , and REPAIR
PARTITION . Each of these options takes a
partition_names clause consisting
of one or more names of partitions, separated by commas. The
partitions must already exist in the table to be altered. You
can also use the ALL keyword in place of
partition_names , in which case the
statement acts on all partitions in the table. For more
information and examples, see
Section 18.3.3, “Maintenance of Partitions”.
The ANALYZE PARTITION , CHECK
PARTITION , OPTIMIZE PARTITION ,
and REPAIR PARTITION options were disabled
in MySQL 5.1.24, and re-enabled in MySQL 5.1.27. (Bug#20129)
They are not supported for tables which are not partitioned;
beginning with MySQL 5.1.31, they are disallowed for such
tables.
REMOVE PARTITIONING was introduced in MySQL
5.1.8 for the purpose of removing a table's partitioning
without otherwise affecting the table or its data.
(Previously, this was done using the ENGINE
option.) This option can be combined with other
ALTER TABLE options such as
those used to add, drop, or rename drop columns or indexes.
In MySQL 5.1.7 and earlier, using the
ENGINE option with
ALTER TABLE caused any
partitioning that a table might have had to be removed.
Beginning with MySQL 5.1.8, this option merely changes the
storage engine used by the table and no longer affects
partitioning in any way.
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 21.9.3.35, “mysql_info() ”.
Here are some examples that show uses of
ALTER TABLE . 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);
We indexed c (as a PRIMARY
KEY ) because AUTO_INCREMENT columns
must be indexed, and we declare c as
NOT NULL because primary key columns cannot be
NULL .
For NDB tables, it is also possible
to change the storage type used for a table or column. For
example, consider an NDB table
created as shown here:
mysql> CREATE TABLE t1 (c1 INT) TABLESPACE ts_1 ENGINE NDB;
Query OK, 0 rows affected (1.27 sec)
To convert this table to disk-based storage, you can use the
following ALTER TABLE statement:
mysql> ALTER TABLE t1 TABLESPACE ts_1 STORAGE DISK;
Query OK, 0 rows affected (2.99 sec)
Records: 0 Duplicates: 0 Warnings: 0
mysql> SHOW CREATE TABLE t1\G
*************************** 1. row ***************************
Table: t1
Create Table: CREATE TABLE `t1` (
`c1` int(11) DEFAULT NULL
) /*!50100 TABLESPACE ts_1 STORAGE DISK */
ENGINE=ndbcluster DEFAULT CHARSET=latin1
1 row in set (0.01 sec)
It is not necessary that the tablespace was referenced when the
table was originally created; however, the tablespace must be
referenced by the ALTER TABLE :
mysql> CREATE TABLE t2 (c1 INT) ts_1 ENGINE NDB;
Query OK, 0 rows affected (1.00 sec)
mysql> ALTER TABLE t2 STORAGE DISK;
ERROR 1005 (HY000): Can't create table 'c.#sql-1750_3' (errno: 140)
mysql> ALTER TABLE t2 TABLESPACE ts_1 STORAGE DISK;
Query OK, 0 rows affected (3.42 sec)
Records: 0 Duplicates: 0 Warnings: 0
mysql> SHOW CREATE TABLE t2\G
*************************** 1. row ***************************
Table: t1
Create Table: CREATE TABLE `t2` (
`c1` int(11) DEFAULT NULL
) /*!50100 TABLESPACE ts_1 STORAGE DISK */
ENGINE=ndbcluster DEFAULT CHARSET=latin1
1 row in set (0.01 sec)
To change the storage type of an individual column, you can use
ALTER TABLE ... MODIFY [COLUMN] . For example,
suppose you create a MySQL Cluster Disk Data table with two
columns, using this CREATE TABLE
statement:
mysql> CREATE TABLE t3 (c1 INT, c2 INT)
-> TABLESPACE ts_1 STORAGE DISK ENGINE NDB;
Query OK, 0 rows affected (1.34 sec)
To change column c2 from disk-based to
in-memory storage, include a STORAGE MEMORY clause in the column
definition used by the ALTER TABLE statement, as shown here:
mysql> ALTER TABLE t3 MODIFY c2 INT STORAGE MEMORY;
Query OK, 0 rows affected (3.14 sec)
Records: 0 Duplicates: 0 Warnings: 0
You can make an in-memory column into a disk-based column by using
STORAGE DISK in a similar fashion.
Column c1 uses disk-based storage, since this
is the default for the table (determined by the table-level
STORAGE DISK clause in the
CREATE TABLE statement). However,
column c2 uses in-memory storage, as can be
seen here in the output of SHOW CREATE
TABLE :
mysql> SHOW CREATE TABLE t3\G
*************************** 1. row ***************************
Table: t3
Create Table: CREATE TABLE `t3` (
`c1` int(11) DEFAULT NULL,
`c2` int(11) /*!50120 STORAGE MEMORY */ DEFAULT NULL
) /*!50100 TABLESPACE ts_1 STORAGE DISK */ ENGINE=ndbcluster DEFAULT CHARSET=latin1
1 row in set (0.02 sec)
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=value before
ALTER TABLE or by using the
AUTO_INCREMENT=value
table option. See Section 5.1.5, “Session System Variables”.
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;
Important
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;
12.1.8. ALTER TABLESPACE SyntaxALTER TABLESPACE tablespace_name
{ADD|DROP} DATAFILE 'file_name '
[INITIAL_SIZE [=] size ]
[WAIT]
ENGINE [=] engine_name
This statement can be used either to add a new data file, or to
drop a data file from a tablespace.
The ADD DATAFILE variant allows you to specify
an initial size using an INITIAL_SIZE clause,
where size is measured in bytes; the
default value is 128M (128 megabytes). You may
optionally follow this integer value with a one-letter
abbreviation for an order of magnitude, similar to those used in
my.cnf . Generally, this is one of the letters
M (for megabytes) or G (for
gigabytes).
Note
All MySQL Cluster Disk Data objects share the same namespace.
This means that each Disk Data object must
be uniquely named (and not merely each Disk Data object of a
given type). For example, you cannot have a tablespace and an
data file with the same name, or an undo log file and a with the
same name.
Prior to MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, path and
file names for data files could not be longer than 128 characters.
(Bug#31770)
On 32-bit systems, the maximum supported value for
INITIAL_SIZE is 4G .
(Bug#29186)
INITIAL_SIZE is rounded as for
CREATE TABLESPACE . Beginning with
MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.32, MySQL Cluster
NDB 7.0.13, and MySQL Cluster NDB 7.1.2, this rounding is done
explicitly (also as with CREATE
TABLESPACE ).
Once a data file has been created, its size cannot be changed;
however, you can add more data files to the tablespace using
additional ALTER TABLESPACE ... ADD DATAFILE
statements.
Using DROP DATAFILE with ALTER
TABLESPACE drops the data file
'file_name ' from the tablespace. This
file must already have been added to the tablespace using
CREATE TABLESPACE or ALTER
TABLESPACE ; otherwise an error will result.
Both ALTER TABLESPACE ... ADD DATAFILE and
ALTER TABLESPACE ... DROP DATAFILE require an
ENGINE clause which specifies the storage
engine used by the tablespace. In MySQL 5.1, the only accepted
values for engine_name are
NDB and
NDBCLUSTER .
WAIT is parsed but otherwise ignored, and so
has no effect in MySQL 5.1. It is intended for future
expansion.
When ALTER TABLESPACE ... ADD DATAFILE is used
with ENGINE = NDB , a data file is created on
each Cluster data node. You can verify that the data files were
created and obtain information about them by querying the
INFORMATION_SCHEMA.FILES table. For
example, the following query shows all data files belonging to the
tablespace named newts :
mysql> SELECT LOGFILE_GROUP_NAME, FILE_NAME, EXTRA
-> FROM INFORMATION_SCHEMA.FILES
-> WHERE TABLESPACE_NAME = 'newts' AND FILE_TYPE = 'DATAFILE';
+--------------------+--------------+----------------+
| LOGFILE_GROUP_NAME | FILE_NAME | EXTRA |
+--------------------+--------------+----------------+
| lg_3 | newdata.dat | CLUSTER_NODE=3 |
| lg_3 | newdata.dat | CLUSTER_NODE=4 |
| lg_3 | newdata2.dat | CLUSTER_NODE=3 |
| lg_3 | newdata2.dat | CLUSTER_NODE=4 |
+--------------------+--------------+----------------+
2 rows in set (0.03 sec)
See Section 20.21, “The INFORMATION_SCHEMA FILES Table”.
ALTER TABLESPACE was added in MySQL 5.1.6. In
MySQL 5.1, it is useful only with Disk Data storage for MySQL
Cluster. See Section 17.5.10, “MySQL Cluster Disk Data Tables”.
12.1.9. ALTER VIEW SyntaxALTER
[ALGORITHM = {UNDEFINED | MERGE | TEMPTABLE}]
[DEFINER = { user | CURRENT_USER }]
[SQL SECURITY { DEFINER | INVOKER }]
VIEW view_name [(column_list )]
AS select_statement
[WITH [CASCADED | LOCAL] CHECK OPTION]
This statement changes the definition of a view, which must exist.
The syntax is similar to that for CREATE
VIEW and the effect is the same as for CREATE
OR REPLACE VIEW . See Section 12.1.20, “CREATE VIEW Syntax”. This
statement requires the CREATE VIEW
and DROP privileges for the view,
and some privilege for each column referred to in the
SELECT statement. As of MySQL
5.1.23, ALTER VIEW is allowed only
to the definer or users with the
SUPER privilege.
12.1.10. CREATE DATABASE SyntaxCREATE {DATABASE | SCHEMA} [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.
CREATE
SCHEMA is a synonym for CREATE
DATABASE .
An error occurs if the database exists and you did not specify
IF NOT EXISTS .
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 creates
only a directory under the MySQL data directory and the
db.opt file. Rules for allowable database
names are given in Section 8.2, “Schema Object Names”. If a database
name contains special characters, the name for the database
directory contains encoded versions of those characters as
described in Section 8.2.3, “Mapping of Identifiers to File 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”.
12.1.11. CREATE EVENT SyntaxCREATE
[DEFINER = { user | CURRENT_USER }]
EVENT
[IF NOT EXISTS]
event_name
ON SCHEDULE schedule
[ON COMPLETION [NOT] PRESERVE]
[ENABLE | DISABLE | DISABLE ON SLAVE]
[COMMENT 'comment ']
DO sql_statement ;
schedule :
AT timestamp [+ INTERVAL interval ] ...
| EVERY interval
[STARTS timestamp [+ INTERVAL interval] ...]
[ENDS timestamp [+ INTERVAL interval] ...]
interval :
quantity {YEAR | QUARTER | MONTH | DAY | HOUR | MINUTE |
WEEK | SECOND | YEAR_MONTH | DAY_HOUR | DAY_MINUTE |
DAY_SECOND | HOUR_MINUTE | HOUR_SECOND | MINUTE_SECOND}
This statement creates and schedules a new event. It requires the
EVENT privilege for the schema in
which the event is to be created. The event will not run unless
the Event Scheduler is enabled. For information about checking
Event Scheduler status and enabling it if necessary, see
Section 19.4.2, “Event Scheduler Configuration”.
The minimum requirements for a valid CREATE
EVENT statement are as follows:
The keywords CREATE EVENT plus
an event name, which uniquely identifies the event within a
database schema. (Prior to MySQL 5.1.12, the event name needed
to be unique only among events created by the same user within
a schema.)
An ON SCHEDULE clause, which determines
when and how often the event executes.
A DO clause, which contains the
SQL statement to be executed by an event.
This is an example of a minimal CREATE
EVENT statement:
CREATE EVENT myevent
ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 1 HOUR
DO
UPDATE myschema.mytable SET mycol = mycol + 1;
The previous statement creates an event named
myevent . This event executes once — one
hour following its creation — by running an SQL statement
that increments the value of the
myschema.mytable table's
mycol column by 1.
The event_name must be a valid MySQL
identifier with a maximum length of 64 characters. Event names are
not case sensitive, so you cannot have two events named
myevent and MyEvent in the
same schema. In general, the rules governing event names are the
same as those for names of stored routines. See
Section 8.2, “Schema Object Names”.
An event is associated with a schema. If no schema is indicated as
part of event_name , the default
(current) schema is assumed. To create an event in a specific
schema, qualify the event name with a schema using
schema_name .event_name
syntax.
The DEFINER clause specifies the MySQL account
to be used when checking access privileges at event execution
time. If a user value is given, it
should be a MySQL account in
'user_name '@'host_name '
format (the same format used in the
GRANT statement). The
user_name and
host_name values both are required. The
definer can also be given as
CURRENT_USER or
CURRENT_USER() . The default
DEFINER value is the user who executes the
CREATE EVENT statement. (This is
the same as DEFINER = CURRENT_USER .)
If you specify the DEFINER clause, these rules
determine the legal DEFINER user values:
If you do not have the SUPER
privilege, the only legal user
value is your own account, either specified literally or by
using CURRENT_USER . You cannot
set the definer to some other account.
If you have the SUPER
privilege, you can specify any syntactically legal account
name. If the account does not actually exist, a warning is
generated.
Although it is possible to create events with a nonexistent
DEFINER value, an error occurs if the event
executes with definer privileges but the definer does not
exist at execution time.
The DEFINER clause was added in MySQL 5.1.17.
(Prior to MySQL 5.1.12, it was possible for two different users to
create different events having the same name on the same database
schema.)
Within an event, the CURRENT_USER()
function returns the account used to check privileges at event
execution time, which is the DEFINER user. For
information about user auditing within events, see
Section 5.5.9, “Auditing MySQL Account Activity”.
IF NOT EXISTS has the same meaning for
CREATE EVENT as for
CREATE TABLE : If an event named
event_name already exists in the same
schema, no action is taken, and no error results. (However, a
warning is generated in such cases.)
The ON SCHEDULE clause determines when, how
often, and for how long the
sql_statement defined for the event
repeats. This clause takes one of two forms:
AT timestamp is
used for a one-time event. It specifies that the event
executes one time only at the date and time given by
timestamp , which must include both
the date and time, or must be an expression that resolves to a
datetime value. You may use a value of either the
DATETIME or
TIMESTAMP type for this
purpose. If the date is in the past, a warning occurs, as
shown here:
mysql> SELECT NOW();
+---------------------+
| NOW() |
+---------------------+
| 2006-02-10 23:59:01 |
+---------------------+
1 row in set (0.04 sec)
mysql> CREATE EVENT e_totals
-> ON SCHEDULE AT '2006-02-10 23:59:00'
-> DO INSERT INTO test.totals VALUES (NOW());
Query OK, 0 rows affected, 1 warning (0.00 sec)
mysql> SHOW WARNINGS\G
*************************** 1. row ***************************
Level: Note
Code: 1588
Message: Event execution time is in the past and ON COMPLETION NOT
PRESERVE is set. The event was dropped immediately after
creation.
CREATE EVENT statements which
are themselves invalid — for whatever reason —
fail with an error.
You may use CURRENT_TIMESTAMP
to specify the current date and time. In such a case, the
event acts as soon as it is created.
To create an event which occurs at some point in the future
relative to the current date and time — such as that
expressed by the phrase “three weeks from now”
— you can use the optional clause + INTERVAL
interval . The
interval portion consists of two
parts, a quantity and a unit of time, and follows the same
syntax rules that govern intervals used in the
DATE_ADD() function (see
Section 11.6, “Date and Time Functions”. The units keywords
are also the same, except that you cannot use any units
involving microseconds when defining an event. With some
interval types, complex time units may be used. For example,
“two minutes and ten seconds” can be expressed as
+ INTERVAL '2:10' MINUTE_SECOND .
You can also combine intervals. For example, AT
CURRENT_TIMESTAMP + INTERVAL 3 WEEK + INTERVAL 2 DAY
is equivalent to “three weeks and two days from
now”. Each portion of such a clause must begin with
+ INTERVAL .
To repeat actions at a regular interval, use an
EVERY clause. The EVERY
keyword is followed by an interval
as described in the previous dicussion of the
AT keyword. (+ INTERVAL
is not used with
EVERY .) For example, EVERY 6
WEEK means “every six weeks”.
Although + INTERVAL clauses are not allowed
in an EVERY clause, you can use the same
complex time units allowed in a + INTERVAL .
An EVERY clause may contain an optional
STARTS clause. STARTS is
followed by a timestamp value that
indicates when the action should begin repeating, and may also
use + INTERVAL
interval in order to
specify an amount of time “from now”. For
example, EVERY 3 MONTH STARTS CURRENT_TIMESTAMP +
INTERVAL 1 WEEK means “every three months,
beginning one week from now”. Similarly, you can
express “every two weeks, beginning six hours and
fifteen minutes from now” as EVERY 2 WEEK
STARTS CURRENT_TIMESTAMP + INTERVAL '6:15'
HOUR_MINUTE . Not specifying
STARTS is the same as using STARTS
CURRENT_TIMESTAMP — that is, the action
specified for the event begins repeating immediately upon
creation of the event.
An EVERY clause may contain an optional
ENDS clause. The ENDS
keyword is followed by a timestamp
value that tells MySQL when the event should stop repeating.
You may also use + INTERVAL
interval with
ENDS ; for instance, EVERY 12 HOUR
STARTS CURRENT_TIMESTAMP + INTERVAL 30 MINUTE ENDS
CURRENT_TIMESTAMP + INTERVAL 4 WEEK is equivalent to
“every twelve hours, beginning thirty minutes from now,
and ending four weeks from now”. Not using
ENDS means that the event continues
executing indefinitely.
ENDS supports the same syntax for complex
time units as STARTS does.
You may use STARTS ,
ENDS , both, or neither in an
EVERY clause.
If a repeating event does not terminate within its scheduling
interval, the result may be multiple instances of the event
executing simultaneously. If this is undesirable, you should
institute a mechanism to prevent simultaneous instances. For
example, you could use the
GET_LOCK() function, or row or
table locking.
The ON SCHEDULE clause may use expressions
involving built-in MySQL functions and user variables to obtain
any of the timestamp or
interval values which it contains. You
may not use stored functions or user-defined functions in such
expressions, nor may you use any table references; however, you
may use SELECT FROM DUAL . This is true for both
CREATE EVENT and
ALTER EVENT statements. Beginning
with MySQL 5.1.13, references to stored functions, user-defined
functions, and tables in such cases are specifically disallowed,
and fail with an error (see Bug#22830).
Times in the ON SCHEDULE clause are interpreted
using the current session
time_zone value. This becomes the
event time zone; that is, the time zone that is used for event
scheduling and is in effect within the event as it executes. These
times are converted to UTC and stored along with the event time
zone in the mysql.event table. This enables
event execution to proceed as defined regardless of any subsequent
changes to the server time zone or daylight saving time effects.
For additional information about representation of event times,
see Section 19.4.4, “Event Metadata”. See also
Section 12.5.5.19, “SHOW EVENTS Syntax”, and Section 20.20, “The INFORMATION_SCHEMA EVENTS Table”.
Normally, once an event has expired, it is immediately dropped.
You can override this behavior by specifying ON
COMPLETION PRESERVE . Using ON COMPLETION NOT
PRESERVE merely makes the default nonpersistent behavior
explicit.
You can create an event but prevent it from being active using the
DISABLE keyword. Alternatively, you can use
ENABLE to make explicit the default status,
which is active. This is most useful in conjunction with
ALTER EVENT (see
Section 12.1.2, “ALTER EVENT Syntax”).
Beginning with MySQL 5.1.18, a third value may also appear in
place of ENABLED or
DISABLED ; DISABLE ON SLAVE
is set for the status of an event on a replication slave to
indicate that the event was created on the master and replicated
to the slave, but is not executed on the slave. See
Section 16.3.1.8, “Replication of Invoked Features”.
You may supply a comment for an event using a
COMMENT clause.
comment may be any string of up to 64
characters that you wish to use for describing the event. The
comment text, being a string literal, must be surrounded by
quotation marks.
The DO clause specifies an action
carried by the event, and consists of an SQL statement. Nearly any
valid MySQL statement that can be used in a stored routine can
also be used as the action statement for a scheduled event. (See
Section D.1, “Restrictions on Stored Routines, Triggers, and Events”.) For example, the
following event e_hourly deletes all rows from
the sessions table once per hour, where this
table is part of the site_activity schema:
CREATE EVENT e_hourly
ON SCHEDULE
EVERY 1 HOUR
COMMENT 'Clears out sessions table each hour.'
DO
DELETE FROM site_activity.sessions;
MySQL stores the sql_mode system
variable setting that is in effect at the time an event is
created, and always executes the event with this setting in force,
regardless of the current server SQL mode.
A CREATE EVENT statement that
contains an ALTER EVENT statement
in its DO clause appears to
succeed; however, when the server attempts to execute the
resulting scheduled event, the execution fails with an error.
Note
Statements such as SELECT or
SHOW that merely return a result
set have no effect when used in an event; the output from these
is not sent to the MySQL Monitor, nor is it stored anywhere.
However, you can use statements such as
SELECT ...
INTO and
INSERT INTO ...
SELECT that store a result. (See the next example in
this section for an instance of the latter.)
The schema to which an event belongs is the default schema for
table references in the DO clause.
Any references to tables in other schemas must be qualified with
the proper schema name. (In MySQL 5.1.6, all tables referenced in
event DO clauses had to include a
reference to the schema.)
As with stored routines, you can use compound-statement syntax in
the DO clause by using the
BEGIN and END keywords, as
shown here:
delimiter |
CREATE EVENT e_daily
ON SCHEDULE
EVERY 1 DAY
COMMENT 'Saves total number of sessions then clears the table each day'
DO
BEGIN
INSERT INTO site_activity.totals (time, total)
SELECT CURRENT_TIMESTAMP, COUNT(*)
FROM site_activity.sessions;
DELETE FROM site_activity.sessions;
END |
delimiter ;
This example uses the delimiter command to
change the statement delimiter. See
Section 19.1, “Defining Stored Programs”.
More complex compound statements, such as those used in stored
routines, are possible in an event. This example uses local
variables, an error handler, and a flow control construct:
delimiter |
CREATE EVENT e
ON SCHEDULE
EVERY 5 SECOND
DO
BEGIN
DECLARE v INTEGER;
DECLARE CONTINUE HANDLER FOR SQLEXCEPTION BEGIN END;
SET v = 0;
WHILE v < 5 DO
INSERT INTO t1 VALUES (0);
UPDATE t2 SET s1 = s1 + 1;
SET v = v + 1;
END WHILE;
END |
delimiter ;
There is no way to pass parameters directly to or from events;
however, it is possible to invoke a stored routine with parameters
within an event:
CREATE EVENT e_call_myproc
ON SCHEDULE
AT CURRENT_TIMESTAMP + INTERVAL 1 DAY
DO CALL myproc(5, 27);
If an event's definer has the SUPER
privilege, the event can read and write global variables. As
granting this privilege entails a potential for abuse, extreme
care must be taken in doing so.
Generally, any statements that are valid in stored routines may be
used for action statements executed by events. For more
information about statements allowable within stored routines, see
Section 19.2.1, “Stored Routine Syntax”. You can create an event
as part of a stored routine, but an event cannot be created by
another event.
12.1.12. CREATE FUNCTION Syntax
The CREATE FUNCTION statement is
used to create stored functions and user-defined functions (UDFs):
12.1.13. CREATE INDEX SyntaxCREATE [ONLINE|OFFLINE] [UNIQUE|FULLTEXT|SPATIAL] INDEX index_name
[index_type ]
ON tbl_name (index_col_name ,...)
[index_option ] ...
index_col_name :
col_name [(length )] [ASC | DESC]
index_type :
USING {BTREE | HASH | RTREE}
index_option :
KEY_BLOCK_SIZE [=] value
| index_type
| WITH PARSER parser_name
CREATE INDEX is mapped to an
ALTER TABLE statement to create
indexes. See Section 12.1.7, “ALTER TABLE Syntax”.
CREATE INDEX cannot be used to
create a PRIMARY KEY ; use
ALTER TABLE instead. For more
information about indexes, see Section 7.4.4, “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.17, “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
col_name (length )
syntax to specify an index prefix 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 cannot 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 17.1.5.6, “Unsupported or Missing Features in MySQL Cluster”).
Note
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.
Beginning with MySQL 5.1.7, indexes on variable-width columns are
created online; that is, creating the indexes does not require any
copying of the table. For NDBCLUSTER
tables, the table is not locked against access from other MySQL
Cluster API nodes, although it is locked against other operations
on the same API node for the duration of the
online operation. This is done automatically by the server
whenever it determines that it is possible to do so; you do not
have to use any special SQL syntax or server options to cause it
to happen.
In standard MySQL 5.1 releases, it is not possible to
override the server when it determines that an index is to be
created online. In MySQL Cluster, beginning with MySQL Cluster NDB
6.2.5 and MySQL Cluster NDB 6.3.3, you can create indexes offline
(which causes the table to be locked to all API nodes in the
cluster) using the OFFLINE keyword. The rules
and limitations governing online CREATE OFFLINE
INDEX and CREATE ONLINE INDEX are the
same as for ALTER OFFLINE TABLE ... ADD INDEX
and ALTER ONLINE TABLE ... ADD INDEX . You
cannot cause the online creation of an index that would normally
be created offline by using the ONLINE keyword
(if it is not possible to perform the CREATE
INDEX operation online, then the
ONLINE keyword is ignored). For more
information, see Section 12.1.7, “ALTER TABLE Syntax”.
Note
The ONLINE and OFFLINE
keywords are available only in MySQL Cluster NDB 6.2 and MySQL
Cluster NDB 6.3 releases beginning with versions 6.2.5 and
6.3.3, respectively; attempting to use them in earlier MySQL
Cluster NDB 6.2 or 6.3 releases, standard MySQL 5.1 releases, or
MySQL Cluster NDB 6.1 releases results in a syntax error.
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. For all engines, a UNIQUE index allows
multiple NULL values for columns that can
contain NULL . If you specify a prefix value for
a column in a UNIQUE index, the column values
must be unique within the prefix.
MySQL Enterprise
Lack of proper indexes can greatly reduce performance. Subscribe
to the MySQL Enterprise Monitor for notification of inefficient
use of indexes. For more information, see
http://www.mysql.com/products/enterprise/advisors.html.
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.8, “Full-Text Search Functions”, for details of operation.
The MyISAM , InnoDB ,
NDB , and ARCHIVE
storage engines support spatial columns such as
(POINT and GEOMETRY .
(Section 11.13, “Spatial Extensions”, describes the spatial data
types.) However, support for spatial column indexing varies among
engines. Spatial and nonspatial indexes are available according to
the following rules.
Spatial indexes (created using SPATIAL INDEX ):
Available only for MyISAM tables.
Specifying a SPATIAL INDEX for other
storage engines results in an error.
Indexed columns must be NOT NULL .
In MySQL 5.1, column prefix lengths are
prohibited. The full width of each column is indexed.
Nonspatial indexes (created with INDEX ,
UNIQUE , or PRIMARY KEY ):
Allowed for any storage engine that supports spatial columns
except ARCHIVE .
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.
In MySQL 5.1:
You can add an index on a column that can have
NULL values only if you are using the
MyISAM , InnoDB , or
MEMORY storage engine.
You can add an index on a BLOB
or TEXT column only if you are
using the MyISAM , or
InnoDB storage engine.
An index_col_name specification can end
with ASC or DESC . These
keywords are allowed 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.
As of MySQL 5.1.10, index options can be given following the index
column list. An index_option value can
be any of the following:
KEY_BLOCK_SIZE [=]
value
This option provides a hint to the storage engine about the
size in bytes to use for index key blocks. The engine is
allowed to change the value if necessary. A value of 0
indicates that the default value should be used.
index_type
Some storage engines allow you to specify an index type when
creating an index. The allowable 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.
Note
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 RTREE index type is allowable only for
SPATIAL indexes.
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.
Examples:
CREATE TABLE lookup (id INT) ENGINE = MEMORY;
CREATE INDEX id_index USING BTREE ON lookup (id);
TYPE type_name
is recognized as a synonym for USING
type_name . However,
USING is the preferred form.
Before MySQL 5.1.10, this option can be given only before the
ON tbl_name
clause. Use of the option in this position is deprecated as of
5.1.10; support for it is to be dropped in a future MySQL
release. If an index_type option is given
in both the earlier and later positions, the final option
applies.
WITH PARSER
parser_name
This option can be used only with FULLTEXT
indexes. It associates a parser plugin with the index if
full-text indexing and searching operations need special
handling. See Section 22.2, “The MySQL Plugin Interface”, for details on
creating plugins.
12.1.14. CREATE LOGFILE GROUP SyntaxCREATE LOGFILE GROUP logfile_group
ADD UNDOFILE 'undo_file '
[INITIAL_SIZE [=] initial_size ]
[UNDO_BUFFER_SIZE [=] undo_buffer_size ]
[REDO_BUFFER_SIZE [=] redo_buffer_size ]
[NODEGROUP [=] nodegroup_id ]
[WAIT]
[COMMENT [=] comment_text ]
ENGINE [=] engine_name
This statement creates a new log file group named
logfile_group having a single
UNDO file named
'undo_file '. A CREATE LOGFILE
GROUP statement has one and only one ADD
UNDOFILE clause. For rules covering the naming of log
file groups, see Section 8.2, “Schema Object Names”.
Note
All MySQL Cluster Disk Data objects share the same namespace.
This means that each Disk Data object must
be uniquely named (and not merely each Disk Data object of a
given type). For example, you cannot have a tablespace and a log
file group with the same name, or a tablespace and a data file
with the same name.
Beginning with MySQL 5.1.8, you can have only one log file group
per Cluster at any given time. (See Bug#16386)
Prior to MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, path and
file names for undo log files could not be longer than 128
characters. (Bug#31769)
The optional INITIAL_SIZE parameter sets the
UNDO file's initial size; if not specified, it
defaults to 128M (128 megabytes). The optional
UNDO_BUFFER_SIZE parameter sets the size used
by the UNDO buffer for the log file group; The
default value for UNDO_BUFFER_SIZE is
8M (eight megabytes); this value cannot exceed
the amount of system memory available. Both of these parameters
are specified in bytes. You may optionally follow either or both
of these with a one-letter abbreviation for an order of magnitude,
similar to those used in my.cnf . Generally,
this is one of the letters M (for megabytes)
or G (for gigabytes).
Beginning with MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, the
maximum permitted for UNDO_BUFFER_SIZE is
600M ; previously, it was
150M . (Bug#34102)
On 32-bit systems, the maximum supported value for
INITIAL_SIZE is 4G .
(Bug#29186)
Beginning with MySQL Cluster NDB 2.1.18, 6.3.24, and 7.0.4, the
minimum allowed value for INITIAL_SIZE is
1M . (Bug#29574)
The ENGINE parameter determines the storage
engine to be used by this log file group, with
engine_name being the name of the
storage engine. In MySQL 5.1.
engine_name must be one of the values
NDB or
NDBCLUSTER .
REDO_BUFFER_SIZE ,
NODEGROUP , WAIT , and
COMMENT are parsed but ignored, and so have no
effect in MySQL 5.1. These options are intended for
future expansion.
When used with ENGINE [=] NDB , a log file group
and associated UNDO log file are created on
each Cluster data node. You can verify that the
UNDO files were created and obtain information
about them by querying the
INFORMATION_SCHEMA.FILES table. For
example:
mysql> SELECT LOGFILE_GROUP_NAME, LOGFILE_GROUP_NUMBER, EXTRA
-> FROM INFORMATION_SCHEMA.FILES
-> WHERE FILE_NAME = 'undo_10.dat';
+--------------------+----------------------+----------------+
| LOGFILE_GROUP_NAME | LOGFILE_GROUP_NUMBER | EXTRA |
+--------------------+----------------------+----------------+
| lg_3 | 11 | CLUSTER_NODE=3 |
| lg_3 | 11 | CLUSTER_NODE=4 |
+--------------------+----------------------+----------------+
2 rows in set (0.06 sec)
CREATE LOGFILE GROUP was added in MySQL 5.1.6.
In MySQL 5.1, it is useful only with Disk Data storage for MySQL
Cluster. See Section 17.5.10, “MySQL Cluster Disk Data Tables”.
12.1.15. CREATE PROCEDURE and
CREATE FUNCTION SyntaxCREATE
[DEFINER = { user | CURRENT_USER }]
PROCEDURE sp_name ([proc_parameter [,...]])
[characteristic ...] routine_body
CREATE
[DEFINER = { user | CURRENT_USER }]
FUNCTION sp_name ([func_parameter [,...]])
RETURNS type
[characteristic ...] routine_body
proc_parameter :
[ IN | OUT | INOUT ] param_name type
func_parameter :
param_name type
type :
Any valid MySQL data type
characteristic :
LANGUAGE SQL
| [NOT] DETERMINISTIC
| { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA }
| SQL SECURITY { DEFINER | INVOKER }
| COMMENT 'string '
routine_body :
Valid SQL procedure statement
These statements create stored routines. By default, a routine is
associated with the default database. To associate the routine
explicitly with a given database, specify the name as
db_name.sp_name when you create it.
The CREATE FUNCTION statement is
also used in MySQL to support UDFs (user-defined functions). See
Section 22.3, “Adding New Functions to MySQL”. A UDF can be regarded as an
external stored function. However, do note that stored functions
share their namespace with UDFs. See
Section 8.2.4, “Function Name Parsing and Resolution”, for the rules describing
how the server interprets references to different kinds of
functions.
To invoke a stored procedure, use the
CALL statement (see
Section 12.2.1, “CALL Syntax”). To invoke a stored function, refer to it
in an expression. The function returns a value during expression
evaluation.
To execute the CREATE PROCEDURE or
CREATE FUNCTION statement, it is
necessary to have the CREATE
ROUTINE privilege. By default, MySQL automatically
grants the ALTER ROUTINE and
EXECUTE privileges to the routine
creator. This behavior can be changed by disabling the
automatic_sp_privileges system
variable. See Section 19.2.2, “Stored Routines and MySQL Privileges”. If
binary logging is enabled, the CREATE
FUNCTION statement might also require the
SUPER privilege, as described in
Section 19.6, “Binary Logging of Stored Programs”.
The DEFINER and SQL SECURITY
clauses specify the security context to be used when checking
access privileges at routine execution time, as described later.
If the routine name is the same as the name of a built-in SQL
function, a syntax error occurs unless you use a space between the
name and the following parenthesis when defining the routine or
invoking it later. For this reason, avoid using the names of
existing SQL functions for your own stored routines.
The IGNORE_SPACE SQL mode
applies to built-in functions, not to stored routines. It is
always allowable to have spaces after a stored routine name,
regardless of whether
IGNORE_SPACE is enabled.
The parameter list enclosed within parentheses must always be
present. If there are no parameters, an empty parameter list of
() should be used. Parameter names are not case
sensitive.
Each parameter is an IN parameter by default.
To specify otherwise for a parameter, use the keyword
OUT or INOUT before the
parameter name.
Note
Specifying a parameter as IN ,
OUT , or INOUT is valid
only for a PROCEDURE .
(FUNCTION parameters are always regarded as
IN parameters.)
An IN parameter passes a value into a
procedure. The procedure might modify the value, but the
modification is not visible to the caller when the procedure
returns. An OUT parameter passes a value from
the procedure back to the caller. Its initial value is
NULL within the procedure, and its value is
visible to the caller when the procedure returns. An
INOUT parameter is initialized by the caller,
can be modified by the procedure, and any change made by the
procedure is visible to the caller when the procedure returns.
For each OUT or INOUT
parameter, pass a user-defined variable in the
CALL statement that invokes the
procedure so that you can obtain its value when the procedure
returns. If you are calling the procedure from within another
stored procedure or function, you can also pass a routine
parameter or local routine variable as an IN or
INOUT parameter.
The following example shows a simple stored procedure that uses an
OUT parameter:
mysql> delimiter //
mysql> CREATE PROCEDURE simpleproc (OUT param1 INT)
-> BEGIN
-> SELECT COUNT(*) INTO param1 FROM t;
-> END//
Query OK, 0 rows affected (0.00 sec)
mysql> delimiter ;
mysql> CALL simpleproc(@a);
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT @a;
+------+
| @a |
+------+
| 3 |
+------+
1 row in set (0.00 sec)
The example uses the mysql client
delimiter command to change the statement
delimiter from ; to // while
the procedure is being defined. This allows the
; delimiter used in the procedure body to be
passed through to the server rather than being interpreted by
mysql itself. See
Section 19.1, “Defining Stored Programs”.
The RETURNS clause may be specified only for a
FUNCTION , for which it is mandatory. It
indicates the return type of the function, and the function body
must contain a RETURN
value statement. If the
RETURN statement returns a value of
a different type, the value is coerced to the proper type. For
example, if a function specifies an
ENUM or
SET value in the
RETURNS clause, but the
RETURN statement returns an
integer, the value returned from the function is the string for
the corresponding ENUM member of
set of SET members.
The following example function takes a parameter, performs an
operation using an SQL function, and returns the result. In this
case, it is unnecessary to use delimiter
because the function definition contains no internal
; statement delimiters:
mysql> CREATE FUNCTION hello (s CHAR(20))
mysql> RETURNS CHAR(50) DETERMINISTIC
-> RETURN CONCAT('Hello, ',s,'!');
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT hello('world');
+----------------+
| hello('world') |
+----------------+
| Hello, world! |
+----------------+
1 row in set (0.00 sec)
Parameter types and function return types can be declared to use
any valid data type, except that the COLLATE
attribute cannot be used.
The routine_body consists of a valid
SQL procedure statement. This can be a simple statement such as
SELECT or
INSERT , or it can be a compound
statement written using BEGIN and
END . Compound statements can contain
declarations, loops, and other control structure statements. The
syntax for these statements is described in
Section 12.8, “MySQL Compound-Statement Syntax”.
MySQL allows routines to contain DDL statements, such as
CREATE and DROP . MySQL also
allows stored procedures (but not stored functions) to contain SQL
transaction statements such as
COMMIT . Stored functions may not
contain statements that perform explicit or implicit commit or
rollback. Support for these statements is not required by the SQL
standard, which states that each DBMS vendor may decide whether to
allow them.
Statements that return a result set can be used within a stored
procedcure but not within a stored function. This prohibition
includes SELECT statements that do
not have an INTO
var_list clause and other
statements such as SHOW ,
EXPLAIN , and
CHECK TABLE . For statements that
can be determined at function definition time to return a result
set, a Not allowed to return a result set from a
function error occurs
(ER_SP_NO_RETSET ). For statements
that can be determined only at runtime to return a result set, a
PROCEDURE %s can't return a result set in the given
context error occurs
(ER_SP_BADSELECT ).
USE statements within stored
routines are disallowed. When a routine is invoked, an implicit
USE db_name is
performed (and undone when the routine terminates). This causes
the routine to have the given default database while it executes.
References to objects in databases other than the routine default
database should be qualified with the appropriate database name.
For additional information about statements that are not allowed
in stored routines, see
Section D.1, “Restrictions on Stored Routines, Triggers, and Events”.
For information about invoking stored procedures from within
programs written in a language that has a MySQL interface, see
Section 12.2.1, “CALL Syntax”.
MySQL stores the sql_mode system
variable setting that is in effect at the time a routine is
created, and always executes the routine with this setting in
force, regardless of the server SQL mode in effect when
the routine is invoked.
The switch from the SQL mode of the invoker to that of the routine
occurs after evaluation of arguments and assignment of the
resulting values to routine parameters. If you define a routine in
strict SQL mode but invoke it in nonstrict mode, assignment of
arguments to routine parameters does not take place in strict
mode. If you require that expressions passed to a routine be
assigned in strict SQL mode, you should invoke the routine with
strict mode in effect.
A procedure or function is considered “deterministic”
if it always produces the same result for the same input
parameters, and “not deterministic” otherwise. If
neither DETERMINISTIC nor NOT
DETERMINISTIC is given in the routine definition, the
default is NOT DETERMINISTIC .
A routine that contains the NOW()
function (or its synonyms) or
RAND() is nondeterministic, but it
might still be replication-safe. For
NOW() , the binary log includes the
timestamp and replicates correctly.
RAND() also replicates correctly as
long as it is called only a single time during the execution of a
routine. (You can consider the routine execution timestamp and
random number seed as implicit inputs that are identical on the
master and slave.)
Prior to MySQL 5.1.21, the DETERMINISTIC
characteristic is accepted, but not used by the optimizer.
However, if binary logging is enabled, this characteristic always
affects which routine definitions MySQL accepts. See
Section 19.6, “Binary Logging of Stored Programs”.
Several characteristics provide information about the nature of
data use by the routine. In MySQL, these characteristics are
advisory only. The server does not use them to constrain what
kinds of statements a routine will be allowed to execute.
CONTAINS SQL indicates that the routine
does not contain statements that read or write data. This is
the default if none of these characteristics is given
explicitly. Examples of such statements are SET @x =
1 or DO RELEASE_LOCK('abc') ,
which execute but neither read nor write data.
NO SQL indicates that the routine contains
no SQL statements.
READS SQL DATA indicates that the routine
contains statements that read data (for example,
SELECT ), but not statements
that write data.
MODIFIES SQL DATA indicates that the
routine contains statements that may write data (for example,
INSERT or
DELETE ).
The SQL SECURITY characteristic can be used to
specify whether the routine should be executed using the
permissions of the user who creates the routine or the user who
invokes it. The default value is DEFINER . This
feature is new in SQL:2003. The creator or invoker must have
permission to access the database with which the routine is
associated. It is necessary to have the
EXECUTE privilege to be able to
execute the routine. The user that must have this privilege is
either the definer or invoker, depending on how the SQL
SECURITY characteristic is set.
The COMMENT characteristic is a MySQL
extension, and may be used to describe the stored routine. This
information is displayed by the SHOW CREATE
PROCEDURE and SHOW CREATE
FUNCTION statements.
The optional DEFINER clause specifies the MySQL
account to be used when checking access privileges at routine
execution time for routines that have the SQL SECURITY
DEFINER characteristic. The DEFINER
clause was added in MySQL 5.1.8.
If a user value is given for the
DEFINER clause, it should be a MySQL account in
'user_name '@'host_name '
format (the same format used in the
GRANT statement). The
user_name and
host_name values both are required. The
definer can also be given as
CURRENT_USER or
CURRENT_USER() . The default
DEFINER value is the user who executes the
CREATE PROCEDURE or
CREATE FUNCTION or statement. (This
is the same as DEFINER = CURRENT_USER .)
If you specify the DEFINER clause, these rules
determine the legal DEFINER user values:
If you do not have the SUPER
privilege, the only legal user
value is your own account, either specified literally or by
using CURRENT_USER . You cannot
set the definer to some other account.
If you have the SUPER
privilege, you can specify any syntactically legal account
name. If the account does not actually exist, a warning is
generated.
Although it is possible to create routines with a nonexistent
DEFINER value, an error occurs if the
routine executes with definer privileges but the definer does
not exist at execution time.
Within a stored routine that is defined with the SQL
SECURITY DEFINER characteristic,
CURRENT_USER returns the routine's
DEFINER value. For information about user
auditing within stored routines, see
Section 5.5.9, “Auditing MySQL Account Activity”.
Consider the following procedure, which displays a count of the
number of MySQL accounts listed in the
mysql.user table:
CREATE DEFINER = 'admin'@'localhost' PROCEDURE account_count()
BEGIN
SELECT 'Number of accounts:', COUNT(*) FROM mysql.user;
END;
The procedure is assigned a DEFINER account of
'admin'@'localhost' no matter which user
defines it. It executes with the privileges of that account no
matter which user invokes it (because the default security
characteristic is DEFINER ). The procedure
succeeds or fails depending on whether
'admin'@'localhost' has the
EXECUTE privilege for it and the
SELECT privilege for the
mysql.user table.
Now suppose that the procedure is defined with the SQL
SECURITY INVOKER characteristic:
CREATE DEFINER = 'admin'@'localhost' PROCEDURE account_count()
SQL SECURITY INVOKER
BEGIN
SELECT 'Number of accounts:', COUNT(*) FROM mysql.user;
END;
The procedure still has a DEFINER of
'admin'@'localhost' , but in this case, it
executes with the privileges of the invoking user. Thus, the
procedure succeeds or fails depending on whether the invoker has
the required privileges.
The server handles the data type of a routine parameter, local
routine variable created with
DECLARE , or function return value
as follows:
Assignments are checked for data type mismatches and overflow.
Conversion and overflow problems result in warnings, or errors
in strict SQL mode.
Only scalar values can be assigned. For example, a statement
such as SET x = (SELECT 1, 2) is invalid.
For character data types, if there is a CHARACTER
SET attribute in the declaration, the specified
character set and its default collation are used. If there is
no such attribute, the database character set in effect at
routine creation time and its default collation are used. (The
database character set is given by the value of the
character_set_database system
variable.) The COLLATE attribute is not
supported. (This includes use of BINARY ,
which in this context specifies the binary collation of the
character set.)
12.1.16. CREATE SERVER SyntaxCREATE SERVER server_name
FOREIGN DATA WRAPPER wrapper_name
OPTIONS (option [, option ] ...)
option :
{ HOST character-literal
| DATABASE character-literal
| USER character-literal
| PASSWORD character-literal
| SOCKET character-literal
| OWNER character-literal
| PORT numeric-literal }
This statement creates the definition of a server for use with the
FEDERATED storage engine. The
CREATE SERVER statement creates a
new row within the servers table within the
mysql database. This statement requires the
SUPER privilege.
The server_name
should be a unique reference to the server. Server definitions are
global within the scope of the server, it is not possible to
qualify the server definition to a specific database.
server_name has a
maximum length of 64 characters (names longer than 64 characters
are silently truncated), and is case insensitive. You may specify
the name as a quoted string.
The wrapper_name
should be mysql , and may be quoted with single
quotes. Other values for
wrapper_name are not
currently supported.
For each option you
must specify either a character literal or numeric literal.
Character literals are UTF-8, support a maximum length of 64
characters and default to a blank (empty) string. String literals
are silently truncated to 64 characters. Numeric literals must be
a number between 0 and 9999, default value is 0.
Note
Note that the OWNER option is currently not
applied, and has no effect on the ownership or operation of the
server connection that is created.
The CREATE SERVER statement creates
an entry in the mysql.server table that can
later be used with the CREATE TABLE
statement when creating a FEDERATED table. The
options that you specify will be used to populate the columns in
the mysql.server table. The table columns are
Server_name , Host ,
Db , Username ,
Password , Port and
Socket .
For example:
CREATE SERVER s
FOREIGN DATA WRAPPER mysql
OPTIONS (USER 'Remote', HOST '192.168.1.106', DATABASE 'test');
The data stored in the table can be used when creating a
connection to a FEDERATED table:
CREATE TABLE t (s1 INT) ENGINE=FEDERATED CONNECTION='s';
For more information, see
Section 13.11, “The FEDERATED Storage Engine”.
CREATE SERVER does not cause an
automatic commit.
CREATE SERVER was added in MySQL
5.1.15.
12.1.17. CREATE TABLE SyntaxCREATE [TEMPORARY] TABLE [IF NOT EXISTS] tbl_name
(create_definition ,...)
[table_options ]
[partition_options ]
Or:
CREATE [TEMPORARY] TABLE [IF NOT EXISTS] tbl_name
[(create_definition ,...)]
[table_options ]
[partition_options ]
select_statement
Or:
CREATE [TEMPORARY] TABLE [IF NOT EXISTS] tbl_name
{ LIKE old_tbl_name | (LIKE old_tbl_name ) }
create_definition :
col_name column_definition
| [CONSTRAINT [symbol ]] PRIMARY KEY [index_type ] (index_col_name ,...)
[index_option ] ...
| {INDEX|KEY} [index_name ] [index_type ] (index_col_name ,...)
[index_option ] ...
| [CONSTRAINT [symbol ]] UNIQUE [INDEX|KEY]
[index_name ] [index_type ] (index_col_name ,...)
[index_option ] ...
| {FULLTEXT|SPATIAL} [INDEX|KEY] [index_name ] (index_col_name ,...)
[index_option ] ...
| [CONSTRAINT [symbol ]] FOREIGN KEY
[index_name ] (index_col_name ,...) reference_definition
| CHECK (expr )
column_definition :
data_type [NOT NULL | NULL] [DEFAULT default_value ]
[AUTO_INCREMENT] [UNIQUE [KEY] | [PRIMARY] KEY]
[COMMENT 'string ']
[COLUMN_FORMAT {FIXED|DYNAMIC|DEFAULT}]
[STORAGE {DISK|MEMORY|DEFAULT}]
[reference_definition ]
data_type :
BIT[(length )]
| 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 SET charset_name ] [COLLATE collation_name ]
| VARCHAR(length )
[CHARACTER SET charset_name ] [COLLATE collation_name ]
| BINARY[(length )]
| VARBINARY(length )
| TINYBLOB
| BLOB
| MEDIUMBLOB
| LONGBLOB
| TINYTEXT [BINARY]
[CHARACTER SET charset_name ] [COLLATE collation_name ]
| TEXT [BINARY]
[CHARACTER SET charset_name ] [COLLATE collation_name ]
| MEDIUMTEXT [BINARY]
[CHARACTER SET charset_name ] [COLLATE collation_name ]
| LONGTEXT [BINARY]
[CHARACTER SET charset_name ] [COLLATE collation_name ]
| ENUM(value1 ,value2 ,value3 ,...)
[CHARACTER SET charset_name ] [COLLATE collation_name ]
| SET(value1 ,value2 ,value3 ,...)
[CHARACTER SET charset_name ] [COLLATE collation_name ]
| spatial_type
index_col_name :
col_name [(length )] [ASC | DESC]
index_type :
USING {BTREE | HASH | RTREE}
index_option :
KEY_BLOCK_SIZE [=] value
| index_type
| WITH PARSER parser_name
reference_definition :
REFERENCES tbl_name (index_col_name ,...)
[MATCH FULL | MATCH PARTIAL | MATCH SIMPLE]
[ON DELETE reference_option ]
[ON UPDATE reference_option ]
reference_option :
RESTRICT | CASCADE | SET NULL | NO ACTION
table_options :
table_option [[,] table_option ] ...
table_option :
ENGINE [=] engine_name
| AUTO_INCREMENT [=] value
| AVG_ROW_LENGTH [=] value
| [DEFAULT] CHARACTER SET [=] charset_name
| CHECKSUM [=] {0 | 1}
| [DEFAULT] COLLATE [=] collation_name
| COMMENT [=] 'string '
| CONNECTION [=] 'connect_string '
| DATA DIRECTORY [=] 'absolute path to directory '
| DELAY_KEY_WRITE [=] {0 | 1}
| INDEX DIRECTORY [=] 'absolute path to directory '
| INSERT_METHOD [=] { NO | FIRST | LAST }
| KEY_BLOCK_SIZE [=] value
| MAX_ROWS [=] value
| MIN_ROWS [=] value
| PACK_KEYS [=] {0 | 1 | DEFAULT}
| PASSWORD [=] 'string '
| ROW_FORMAT [=] {DEFAULT|DYNAMIC|FIXED|COMPRESSED|REDUNDANT|COMPACT}
| TABLESPACE tablespace_name [STORAGE {DISK|MEMORY|DEFAULT}]
| UNION [=] (tbl_name [,tbl_name ]...)
partition_options :
PARTITION BY
{ [LINEAR] HASH(expr )
| [LINEAR] KEY(column_list )
| RANGE(expr )
| LIST(expr ) }
[PARTITIONS num ]
[SUBPARTITION BY
{ [LINEAR] HASH(expr )
| [LINEAR] KEY(column_list ) }
[SUBPARTITIONS num ]
]
[(partition_definition [, partition_definition ] ...)]
partition_definition :
PARTITION partition_name
[VALUES {LESS THAN {(expr ) | MAXVALUE } | IN (value_list )}]
[[STORAGE] ENGINE [=] engine_name ]
[COMMENT [=] 'comment_text' ]
[DATA DIRECTORY [=] 'data_dir ']
[INDEX DIRECTORY [=] 'index_dir ']
[MAX_ROWS [=] max_number_of_rows ]
[MIN_ROWS [=] min_number_of_rows ]
[TABLESPACE [=] tablespace_name ]
[NODEGROUP [=] node_group_id ]
[(subpartition_definition [, subpartition_definition ] ...)]
subpartition_definition :
SUBPARTITION logical_name
[[STORAGE] ENGINE [=] engine_name ]
[COMMENT [=] 'comment_text' ]
[DATA DIRECTORY [=] 'data_dir ']
[INDEX DIRECTORY [=] 'index_dir ']
[MAX_ROWS [=] max_number_of_rows ]
[MIN_ROWS [=] min_number_of_rows ]
[TABLESPACE [=] tablespace_name ]
[NODEGROUP [=] node_group_id ]
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 allowable table names are given in
Section 8.2, “Schema Object 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.
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` .
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.) To create temporary tables, you must
have the CREATE TEMPORARY TABLES
privilege.
Note
CREATE TABLE does not
automatically commit the current active transaction if you use
the TEMPORARY keyword.
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.
Chapter 13, Storage Engines, describes what files each
storage engine creates to represent tables. If a table name
contains special characters, the names for the table files contain
encoded versions of those characters as described in
Section 8.2.3, “Mapping of Identifiers to File Names”.
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
Section 11.13, “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
value +1 , where
value 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.11.3, “Information Functions”, and
Section 21.9.3.37, “mysql_insert_id() ”.
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.8, “Server SQL Modes”.
Note
There can be only one AUTO_INCREMENT
column per table, it must be indexed, and it cannot have a
DEFAULT value. 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 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 * FROM tbl_name WHERE auto_col IS NULL
For information about InnoDB and
AUTO_INCREMENT , see
Section 13.6.4.3, “AUTO_INCREMENT Handling in InnoDB ”.
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);
MySQL 5.1 interprets length specifications in
character column definitions in characters. (Versions before
MySQL 4.1 interpreted them in bytes.) Lengths for
BINARY and
VARBINARY are in bytes.
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.
See Section 10.3.1.1, “TIMESTAMP Properties”.
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”.
BLOB and
TEXT columns cannot be assigned
a default value.
CREATE TABLE fails if a
date-valued default is not correct according to the
NO_ZERO_IN_DATE SQL mode,
even if strict SQL mode is not enabled. For example,
c1 DATE DEFAULT '2010-00-00' causes
CREATE TABLE to fail with
Invalid default value for 'c1' .
Native default value handling in MySQL Cluster NDB 7.1 and later.
Starting with MySQL Cluster NDB 7.1.0, default values for
table columns are stored by
NDBCLUSTER , rather than by the
MySQL server as was previously the case. Because less data
must be sent from an SQL node to the data nodes, inserts on
tables having column value defaults can be performed more
efficiently than before.
Tables created using previous MySQL Cluster releases can still
be used in MySQL Cluster 7.1.0 and later, although they do not
support native default values and continue to use defaults
supplied by the MySQL server until they are upgraded. This can
be done by means of an offline ALTER
TABLE statement.
Important
You cannot set or change a table column's default value
using an online ALTER TABLE
operation
Tables created in MySQL Cluster NDB 7.1.0 and later cannot be
used with earlier versions of MySQL Cluster.
NDBCLUSTER tables supporting
native default values are still subject to the restrictions on
default values imposed by the MySQL server. For more
information, see Section 10.1.4, “Data Type Default Values”.
A comment for a column can be specified with the
COMMENT option, up to 255 characters long.
The comment is displayed by the SHOW
CREATE TABLE and
SHOW FULL
COLUMNS statements.
Beginning with MySQL Cluster NDB 6.2.5 and MySQL Cluster NDB
6.3.2, it is also possible to specify a data storage format
for individual columns of NDB
tables using COLUMN_FORMAT . Allowable
column formats are FIXED ,
DYNAMIC , and DEFAULT .
FIXED is used to specify
fixed-width storage, DYNAMIC allows the
column to be variable-width, and DEFAULT
causes the column to use fixed-width or variable-width storage
as determined by the column's data type (possibly overridden
by a ROW_FORMAT specifier).
For NDB tables, the default value
for COLUMN_FORMAT is
DEFAULT .
COLUMN_FORMAT currently has no effect on
columns of tables using storage engines other than
NDB .
For NDB tables, beginning with
MySQL Cluster NDB 6.2.5 and MySQL Cluster NDB 6.3.2, it is
also possible to specify whether the column is stored on disk
or in memory by using a STORAGE clause.
STORAGE DISK causes the column to be stored
on disk, and STORAGE MEMORY causes
in-memory storage to be used. The CREATE
TABLE statement used must still include a
TABLESPACE clause:
mysql> CREATE TABLE t1 (
-> c1 INT STORAGE DISK,
-> c2 INT STORAGE MEMORY
-> ) ENGINE NDB;
ERROR 1005 (HY000): Can't create table 'c.t1' (errno: 140)
mysql> CREATE TABLE t1 (
-> c1 INT STORAGE DISK,
-> c2 INT STORAGE MEMORY
-> ) TABLESPACE ts_1 ENGINE NDB;
Query OK, 0 rows affected (1.06 sec)
For NDB tables, STORAGE
DEFAULT is equivalent to STORAGE
MEMORY .
The STORAGE clause has no effect on tables
using storage engines other than
NDB .
KEY is normally a synonym for
INDEX . 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. For all engines, a UNIQUE
index allows 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.6.10, “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(index_col_name , ...)
clause.
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.
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
tbl_name . See
Section 12.5.5.23, “SHOW INDEX Syntax”.
Some storage engines allow 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;
Before MySQL 5.1.10, USING can be given
only before the index column list. As of 5.1.10, the preferred
position is after the column list. Use of the option before
the column list will no longer be recognized in a future MySQL
release.
index_option values specify
additional options for an index. USING is
one such option. For details about allowable
index_option values, see
Section 12.1.13, “CREATE INDEX Syntax”.
For more information about indexes, see
Section 7.4.4, “How MySQL Uses Indexes”.
In MySQL 5.1, only the MyISAM ,
InnoDB , and 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
col_name (length )
syntax to specify an index prefix 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.2, “Column Indexes”.
Only the MyISAM and
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). 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 allowed 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”.
You can create special FULLTEXT indexes,
which are used for full-text searches. Only the
MyISAM storage engine 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.8, “Full-Text Search Functions”, for details of operation. A
WITH PARSER clause can be specified as an
index_option value to associate a
parser plugin with the index if full-text indexing and
searching operations need special handling. This clause is
legal only for FULLTEXT indexes. See
Section 22.2, “The MySQL Plugin Interface”, for details on creating plugins.
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
Section 11.13, “Spatial Extensions”.
InnoDB tables support checking of foreign
key constraints. See Section 13.6, “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. For the precise syntax, see
Section 13.6.4.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.8.5.4, “Foreign Keys”.
Important
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. InnoDB essentially
implements the semantics defined by MATCH
SIMPLE , which allow a foreign key to be all or
partially NULL . In that case, the (child
table) row containing such a foreign key is allowed to be
inserted, and does not match any row in the referenced
(parent) table. It is possible to implement other semantics
using triggers.
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.7.2, “The Maximum Number of Columns Per Table”.
The TABLESPACE and STORAGE
table options were both introduced in MySQL 5.1.6. In MySQL 5.1,
they are employed only with
NDBCLUSTER tables. The tablespace
named tablespace_name must already have
been created using CREATE TABLESPACE .
STORAGE determines the type of storage used
(disk or memory), and can be one of DISK ,
MEMORY , or DEFAULT .
TABLESPACE ... STORAGE DISK assigns a table to
a MySQL Cluster Disk Data tablespace. See
Section 17.5.10, “MySQL Cluster Disk Data Tables”, for more information.
Important
A STORAGE clause cannot be used in a
CREATE TABLE statement without a
TABLESPACE clause.
The ENGINE table option specifies the storage
engine for the table.
The ENGINE table option takes the storage
engine names shown in the following table.
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=INNODB option but the MySQL
server does not support INNODB 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
5.1, a warning occurs if the storage engine
specification is not honored.
Engine substitution can be controlled by the setting of the
NO_ENGINE_SUBSTITUTION SQL mode,
as described in Section 5.1.8, “Server SQL Modes”.
Note
The older TYPE option was synonymous with
ENGINE . TYPE has been
deprecated since MySQL 4.0 but is still supported for backward
compatibility in MySQL 5.1 (excepting MySQL 5.1.7). Since MySQL
5.1.8, it produces a warning. It will be removed in a future
MySQL release. You should not use
TYPE in any new applications, and you should
immediately begin conversion of existing applications to use
ENGINE instead. (See
Section C.1.42, “Changes in MySQL 5.1.8 (Not released)”.)
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. In MySQL 5.1, this works for
MyISAM , MEMORY , and
InnoDB tables. It also works for
ARCHIVE tables as of MySQL 5.1.6. 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
tbl_name AUTO_INCREMENT =
N to reset the
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 don't specify either option,
the maximum size for MyISAM data and index
files is 256TB by default. (If your operating system does not
support files that large, table sizes are constrained by the
file size limit.) If you want to keep down the pointer sizes
to make the index smaller and faster and you don't really need
big files, you can decrease the default pointer size by
setting the
myisam_data_pointer_size
system variable. (See
Section 5.1.4, “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 can increase the default pointer size by
setting this variable. Setting the value to 7 allows 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.
CONNECTION
The connection string for a FEDERATED
table.
Note
Older versions of MySQL used a COMMENT
option for the connection string.
DATA DIRECTORY , INDEX
DIRECTORY
By using DATA
DIRECTORY='directory ' or
INDEX
DIRECTORY='directory ' you
can specify where the 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.
Important
Beginning with MySQL 5.1.23, table-level DATA
DIRECTORY and INDEX DIRECTORY
options are ignored for partitioned tables. (Bug#32091)
These options work only 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.6.1.2, “Using Symbolic Links for Tables on Unix”, for more complete
information.
If a MyISAM table is created with no
DATA DIRECTORY option, the
.MYD file is created in the database
directory. By default, if MyISAM finds an
existing .MYD file in this case, it
overwrites it. The same applies to .MYI
files for tables created with no INDEX
DIRECTORY option. As of MySQL 5.1.23, to suppress
this behavior, start the server with the
--keep_files_on_create option,
in which case MyISAM will not overwrite
existing files and returns an error instead.
If a MyISAM table is created with a
DATA DIRECTORY or INDEX
DIRECTORY option and an existing
.MYD or .MYI file is
found, MyISAM always returns an error. It will not overwrite a
file in the specified directory.
Important
Beginning with MySQL 5.1.24, you cannot use path names that
contain the MySQL data directory with DATA
DIRECTORY or INDEX DIRECTORY .
This includes partitioned tables and individual table
partitions. (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.4, “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. See
Section 13.8, “The MERGE Storage Engine”.
KEY_BLOCK_SIZE
This option provides a hint to the storage engine about the
size in bytes to use for index key blocks. The engine is
allowed to change the value if necessary. A value of 0
indicates that the default value should be used. Individual
index definitions can specify a
KEY_BLOCK_SIZE value of their own to
override the table value. KEY_BLOCK_SIZE
was added in MySQL 5.1.10.
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.
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.
RAID_TYPE
RAID support has been removed as of MySQL
5.0. For information on RAID , see
CREATE TABLE Syntax.
ROW_FORMAT
Defines how the rows should be stored. For
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.5.3, “MyISAM Table Storage Formats”.
For InnoDB tables, rows are stored in
compact format (ROW_FORMAT=COMPACT ) by
default. The noncompact format used in older versions of MySQL
can still be requested by specifying
ROW_FORMAT=REDUNDANT .
Note
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
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.8, “The MERGE Storage Engine”.
You must have SELECT ,
UPDATE , and
DELETE privileges for the
tables you map to a MERGE table.
Note
Formerly, all tables used had to be in the same database as
the MERGE table itself. This restriction
no longer applies.
partition_options can be used to
control partitioning of the table created with
CREATE TABLE .
Important
Not all options shown in the syntax for
partition_options at the beginning of
this section are available for all partitioning types. Please
see the listings for the following individual types for
information specific to each type, and see
Chapter 18, Partitioning, for more complete information
about the workings of and uses for partitioning in MySQL, as
well as additional examples of table creation and other
statements relating to MySQL partitioning.
If used, a partition_options clause
begins with PARTITION BY . This clause contains
the function that is used to determine the partition; the function
returns an integer value ranging from 1 to
num , where
num is the number of partitions. (The
maximum number of user-defined partitions which a table may
contain is 1024; the number of subpartitions — discussed
later in this section — is included in this maximum.) The
choices that are available for this function in MySQL
5.1 are shown in the following list:
HASH(expr ) :
Hashes one or more columns to create a key for placing and
locating rows. expr is an
expression using one or more table columns. This can be any
legal MySQL expression (including MySQL functions) that yields
a single integer value. For example, these are all valid
CREATE TABLE statements using
PARTITION BY HASH :
CREATE TABLE t1 (col1 INT, col2 CHAR(5))
PARTITION BY HASH(col1);
CREATE TABLE t1 (col1 INT, col2 CHAR(5))
PARTITION BY HASH( ORD(col2) );
CREATE TABLE t1 (col1 INT, col2 CHAR(5), col3 DATETIME)
PARTITION BY HASH ( YEAR(col3) );
You may not use either VALUES LESS THAN or
VALUES IN clauses with PARTITION
BY HASH .
PARTITION BY HASH uses the remainder of
expr divided by the number of
partitions (that is, the modulus). For examples and additional
information, see Section 18.2.3, “HASH Partitioning”.
The LINEAR keyword entails a somewhat
different algorithm. In this case, the number of the partition
in which a row is stored is calculated as the result of one or
more logical AND operations. For
discussion and examples of linear hashing, see
Section 18.2.3.1, “LINEAR HASH Partitioning”.
KEY(column_list ) :
This is similar to HASH , except that MySQL
supplies the hashing function so as to guarantee an even data
distribution. The column_list
argument is simply a list of table columns. This example shows
a simple table partitioned by key, with 4 partitions:
CREATE TABLE tk (col1 INT, col2 CHAR(5), col3 DATE)
PARTITION BY KEY(col3)
PARTITIONS 4;
For tables that are partitioned by key, you can employ linear
partitioning by using the LINEAR keyword.
This has the same effect as with tables that are partitioned
by HASH . That is, the partition number is
found using the
&
operator rather than the modulus (see
Section 18.2.3.1, “LINEAR HASH Partitioning”, and
Section 18.2.4, “KEY Partitioning”, for details). This example
uses linear partitioning by key to distribute data between 5
partitions:
CREATE TABLE tk (col1 INT, col2 CHAR(5), col3 DATE)
PARTITION BY LINEAR KEY(col3)
PARTITIONS 5;
You may not use either VALUES LESS THAN or
VALUES IN clauses with PARTITION
BY KEY .
RANGE : In this case,
expr shows a range of values using
a set of VALUES LESS THAN operators. When
using range partitioning, you must define at least one
partition using VALUES LESS THAN . You
cannot use VALUES IN with range
partitioning.
VALUES LESS THAN can be used with either a
literal value or an expression that evaluates to a single
value.
Suppose that you have a table that you wish to partition on a
column containing year values, according to the following
scheme.
A table implementing such a partitioning scheme can be
realized by the CREATE TABLE
statement shown here:
CREATE TABLE t1 (
year_col INT,
some_data INT
)
PARTITION BY RANGE (year_col) (
PARTITION p0 VALUES LESS THAN (1991),
PARTITION p1 VALUES LESS THAN (1995),
PARTITION p2 VALUES LESS THAN (1999),
PARTITION p3 VALUES LESS THAN (2002),
PARTITION p4 VALUES LESS THAN (2006),
PARTITION p5 VALUES LESS THAN MAXVALUE
);
PARTITION ... VALUES LESS THAN ...
statements work in a consecutive fashion. VALUES LESS
THAN MAXVALUE works to specify
“leftover” values that are greater than the
maximum value otherwise specified.
Note that VALUES LESS THAN clauses work
sequentially in a manner similar to that of the
case portions of a switch ...
case block (as found in many programming languages
such as C, Java, and PHP). That is, the clauses must be
arranged in such a way that the upper limit specified in each
successive VALUES LESS THAN is greater than
that of the previous one, with the one referencing
MAXVALUE coming last of all in the list.
LIST(expr ) : This
is useful when assigning partitions based on a table column
with a restricted set of possible values, such as a state or
country code. In such a case, all rows pertaining to a certain
state or country can be assigned to a single partition, or a
partition can be reserved for a certain set of states or
countries. It is similar to RANGE , except
that only VALUES IN may be used to specify
allowable values for each partition.
VALUES IN is used with a list of values to
be matched. For instance, you could create a partitioning
scheme such as the following:
CREATE TABLE client_firms (
id INT,
name VARCHAR(35)
)
PARTITION BY LIST (id) (
PARTITION r0 VALUES IN (1, 5, 9, 13, 17, 21),
PARTITION r1 VALUES IN (2, 6, 10, 14, 18, 22),
PARTITION r2 VALUES IN (3, 7, 11, 15, 19, 23),
PARTITION r3 VALUES IN (4, 8, 12, 16, 20, 24)
);
When using list partitioning, you must define at least one
partition using VALUES IN . You cannot use
VALUES LESS THAN with PARTITION BY
LIST .
Note
Currently, the value list used with VALUES
IN must consist of integer values only.
The number of partitions may optionally be specified with a
PARTITIONS num
clause, where num is the number of
partitions. If both this clause and any
PARTITION clauses are used,
num must be equal to the total
number of any partitions that are declared using
PARTITION clauses.
Note
Whether or not you use a PARTITIONS
clause in creating a table that is partitioned by
RANGE or LIST , you
must still include at least one PARTITION
VALUES clause in the table definition (see below).
A partition may optionally be divided into a number of
subpartitions. This can be indicated by using the optional
SUBPARTITION BY clause. Subpartitioning may
be done by HASH or KEY .
Either of these may be LINEAR . These work
in the same way as previously described for the equivalent
partitioning types. (It is not possible to subpartition by
LIST or RANGE .)
The number of subpartitions can be indicated using the
SUBPARTITIONS keyword followed by an
integer value.
MySQL 5.1.12 introduces rigorous checking of the value used in
a PARTITIONS or
SUBPARTITIONS clause. Beginning with this
version, this value must adhere to the following rules:
The value must be a positive, nonzero integer.
No leading zeroes are permitted.
The value must be an integer literal, and cannot not be an
expression. For example, PARTITIONS
0.2E+01 is not allowed, even though
0.2E+01 evaluates to
2 . (Bug#15890)
Note
The expression (expr ) used in a
PARTITION BY clause cannot refer to any
columns not in the table being created; beginning with MySQL
5.1.23, such references are specifically disallowed and cause
the statement to fail with an error. (Bug#29444)
Each partition may be individually defined using a
partition_definition clause. The
individual parts making up this clause are as follows:
PARTITION
partition_name : This
specifies a logical name for the partition.
A VALUES clause: For range partitioning,
each partition must include a VALUES LESS
THAN clause; for list partitioning, you must specify
a VALUES IN clause for each partition. This
is used to determine which rows are to be stored in this
partition. See the discussions of partitioning types in
Chapter 18, Partitioning, for syntax examples.
An optional COMMENT clause may be used to
specify a string that describes the partition. Example:
COMMENT = 'Data for the years previous to 1999'
DATA DIRECTORY and INDEX
DIRECTORY may be used to indicate the directory
where, respectively, the data and indexes for this partition
are to be stored. Both the
data_dir and
the index_dir
must be absolute system path names. Example:
CREATE TABLE th (id INT, name VARCHAR(30), adate DATE)
PARTITION BY LIST(YEAR(adate))
(
PARTITION p1999 VALUES IN (1995, 1999, 2003)
DATA DIRECTORY = '/var/appdata/95/data '
INDEX DIRECTORY = '/var/appdata/95/idx ',
PARTITION p2000 VALUES IN (1996, 2000, 2004)
DATA DIRECTORY = '/var/appdata/96/data '
INDEX DIRECTORY = '/var/appdata/96/idx ',
PARTITION p2001 VALUES IN (1997, 2001, 2005)
DATA DIRECTORY = '/var/appdata/97/data '
INDEX DIRECTORY = '/var/appdata/97/idx ',
PARTITION p2000 VALUES IN (1998, 2002, 2006)
DATA DIRECTORY = '/var/appdata/98/data '
INDEX DIRECTORY = '/var/appdata/98/idx '
);
DATA DIRECTORY and INDEX
DIRECTORY behave in the same way as in the
CREATE TABLE statement's
table_option clause as used for
MyISAM tables.
One data directory and one index directory may be specified
per partition. If left unspecified, the data and indexes are
stored by default in the table's database directory.
On Windows, the DATA DIRECTORY and
INDEX DIRECTORY options are not supported
for individual partitions or subpartitions. Beginning with
MySQL 5.1.24, these options are ignored on Windows, except
that a warning is generated. (Bug#30459)
Note
Prior to MySQL 5.1.18, DATA DIRECTORY and
INDEX DIRECTORY were allowed even if the
NO_DIR_IN_CREATE server
SQL mode was in effect at the time that a partitioned table
was created. Beginning with MySQL 5.1.18, these options are
ignored for creating partitioned tables if
NO_DIR_IN_CREATE is in
effect. (Bug#24633)
MAX_ROWS and MIN_ROWS
may be used to specify, respectively, the maximum and minimum
number of rows to be stored in the partition. The values for
max_number_of_rows and
min_number_of_rows must be positive
integers. As with the table-level options with the same names,
these act only as “suggestions” to the server and
are not hard limits.
The optional TABLESPACE clause may be used
to designate a tablespace for the partition. Used for MySQL
Cluster only.
The partitioning handler accepts a [STORAGE]
ENGINE option for both PARTITION
and SUBPARTITION . Currently, the only way
in which this can be used is to set all partitions or all
subpartitions to the same storage engine, and an attempt to
set different storage engines for partitions or subpartitions
in the same table will give rise to the error ERROR
1469 (HY000): The mix of handlers in the partitions is not
allowed in this version of MySQL. We expect to
lift this restriction on partitioning in a future MySQL
release.
The NODEGROUP option can be used to make
this partition act as part of the node group identified by
node_group_id . This option is
applicable only to MySQL Cluster.
The partition definition may optionally contain one or more
subpartition_definition clauses.
Each of these consists at a minimum of the
SUBPARTITION
name , where
name is an identifier for the
subpartition. Except for the replacement of the
PARTITION keyword with
SUBPARTITION , the syntax for a subpartition
definition is identical to that for a partition definition.
Subpartitioning must be done by HASH or
KEY , and can be done only on
RANGE or LIST
partitions. See Section 18.2.5, “Subpartitioning”.
Partitions can be modified, merged, added to tables, and dropped
from tables. For basic information about the MySQL statements to
accomplish these tasks, see Section 12.1.7, “ALTER TABLE Syntax”. For
more detailed descriptions and examples, see
Section 18.3, “Partition Management”.
Important
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 allows 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.
You can create one table from another by adding a
SELECT statement at the end of the
CREATE TABLE statement:
CREATE TABLE new_tbl SELECT * FROM orig_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))
-> ENGINE=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.
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 ... 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;
You can also 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 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.
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.
If strict SQL mode is enabled and any of these initial columns
do not have an explicit default value, the statement fails
with an error.
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)
Use LIKE to create an empty table based on the
definition of another table, including any column attributes and
indexes defined in the original table:
CREATE TABLE new_tbl LIKE orig_tbl ;
The copy is created using the same version of the table storage
format as the original table. The
SELECT privilege is required on the
original table.
LIKE works only for base tables, not for views.
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 .
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.
To ensure that the binary log can be used to re-create the
original tables, MySQL does not allow concurrent inserts during
CREATE TABLE ...
SELECT .
12.1.17.1. Silent Column Specification Changes
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.
TIMESTAMP display sizes are
discarded.
Also note that TIMESTAMP
columns are NOT NULL by default.
Columns that are part of a PRIMARY KEY
are made NOT NULL even if not declared
that way.
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.
If strict SQL mode is not enabled, a
VARCHAR column with a length
specification greater than 65535 is converted to
TEXT , and a
VARBINARY column with a
length specification greater than 65535 is converted to
BLOB . Otherwise, an error
occurs in either of these cases.
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
);
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.5.3.3, “Compressed Table Characteristics”.
12.1.18. CREATE TABLESPACE SyntaxCREATE TABLESPACE tablespace_name
ADD DATAFILE 'file_name '
USE LOGFILE GROUP logfile_group
[EXTENT_SIZE [=] extent_size ]
[INITIAL_SIZE [=] initial_size ]
[AUTOEXTEND_SIZE [=] autoextend_size ]
[MAX_SIZE [=] max_size ]
[NODEGROUP [=] nodegroup_id ]
[WAIT]
[COMMENT [=] comment_text ]
ENGINE [=] engine_name
This statement is used to create a tablespace, which can contain
one or more data files, providing storage space for tables. One
data file is created and added to the tablespace using this
statement. Additional data files may be added to the tablespace by
using the ALTER TABLESPACE statement (see
Section 12.1.8, “ALTER TABLESPACE Syntax”). For rules covering the naming
of tablespaces, see Section 8.2, “Schema Object Names”.
Note
All MySQL Cluster Disk Data objects share the same namespace.
This means that each Disk Data object must
be uniquely named (and not merely each Disk Data object of a
given type). For example, you cannot have a tablespace and a log
file group with the same name, or a tablespace and a data file
with the same name.
Prior to MySQL Cluster NDB 6.2.17, 6.3.23, and 6.4.3, path and
file names for data files could not be longer than 128 characters.
(Bug#31770)
A log file group of one or more UNDO log files
must be assigned to the tablespace to be created with the
USE LOGFILE GROUP clause.
logfile_group must be an existing log
file group created with CREATE LOGFILE GROUP
(see Section 12.1.14, “CREATE LOGFILE GROUP Syntax”). Multiple tablespaces
may use the same log file group for UNDO
logging.
The EXTENT_SIZE sets the size, in bytes, of the
extents used by any files belonging to the tablespace. The default
value is 1M. The minimum size is 32K, and theoretical maximum is
2G, although the practical maximum size depends on a number of
factors. In most cases, changing the extent size does not have any
measurable effect on performance, and the default value is
recommended for all but the most unusual situations.
An extent is a unit of disk space
allocation. One extent is filled with as much data as that extent
can contain before another extent is used. In theory, up to 65,535
(64K) extents may used per data file; however, the recommended
maximum is 32,768 (32K). The recommended maximum size for a single
data file is 32G — that is, 32K extents ? 1 MB per
extent. In addition, once an extent is allocated to a given
partition, it cannot be used to store data from a different
partition; an extent cannot store data from more than one
partition. This means, for example that a tablespace having a
single datafile whose INITIAL_SIZE is 256 MB
and whose EXTENT_SIZE is 128M has just two
extents, and so can be used to store data from at most two
different disk data table partitions.
You can see how many extents remain free in a given data file by
querying the INFORMATION_SCHEMA.FILES
table, and so derive an estimate for how much space remains free
in the file. For further discussion and examples, see
Section 20.21, “The INFORMATION_SCHEMA FILES Table”.
The INITIAL_SIZE parameter sets the data file's
total size in bytes. Once the file has been created, its size
cannot be changed; however, you can add more data files to the
tablespace using ALTER TABLESPACE ... ADD
DATAFILE . See Section 12.1.8, “ALTER TABLESPACE Syntax”.
INITIAL_SIZE is optional; its default value is
128M .
On 32-bit systems, the maximum supported value for
INITIAL_SIZE is 4G .
(Bug#29186)
When setting EXTENT_SIZE or
INITIAL_SIZE (either or both), you may
optionally follow the number with a one-letter abbreviation for an
order of magnitude, similar to those used in
my.cnf . Generally, this is one of the letters
M (for megabytes) or G (for
gigabytes).
INITIAL_SIZE , EXTENT_SIZE ,
and UNDO_BUFFER_SIZE are subject to rounding as
follows:
EXTENT_SIZE and
UNDO_BUFFER_SIZE are each rounded up to the
nearest whole multiple of 32K.
INITIAL_SIZE is rounded
down to the nearest whole multiple of
32K.
For data files, INITIAL_SIZE is subject
to further rounding; the result just obtained is rounded up to
the nearest whole multiple of EXTENT_SIZE
(after any rounding).
The rounding just described has always (since Disk Data
tablespaces were introduced in MySQL 5.1.6) been performed
implicitly, but beginning with MySQL Cluster NDB 6.2.19, MySQL
Cluster NDB 6.3.32, MySQL Cluster NDB 7.0.13, and MySQL Cluster
NDB 7.1.2, this rounding is done explicitly, and a warning is
issued by the MySQL Server when any such rounding is performed.
The rounded values are also used by the NDB kernel for calculating
INFORMATION_SCHEMA.FILES column
values and other purposes. However, to avoid an unexpected result,
we suggest that you always use whole multiples of 32K in
specifying these options.
AUTOEXTEND_SIZE , MAX_SIZE ,
NODEGROUP , WAIT , and
COMMENT are parsed but ignored, and so
currently have no effect. These options are intended for future
expansion.
The ENGINE parameter determines the storage
engine which uses this tablespace, with
engine_name being the name of the
storage engine. In MySQL 5.1,
engine_name must be one of the values
NDB or
NDBCLUSTER .
When CREATE TABLESPACE is used with
ENGINE = NDB , a tablespace and associated data
file are created on each Cluster data node. You can verify that
the data files were created and obtain information about them by
querying the INFORMATION_SCHEMA.FILES
table. For example:
mysql> SELECT LOGFILE_GROUP_NAME, FILE_NAME, EXTRA
-> FROM INFORMATION_SCHEMA.FILES
-> WHERE TABLESPACE_NAME = 'newts' AND FILE_TYPE = 'DATAFILE';
+--------------------+-------------+----------------+
| LOGFILE_GROUP_NAME | FILE_NAME | EXTRA |
+--------------------+-------------+----------------+
| lg_3 | newdata.dat | CLUSTER_NODE=3 |
| lg_3 | newdata.dat | CLUSTER_NODE=4 |
+--------------------+-------------+----------------+
2 rows in set (0.01 sec)
(See Section 20.21, “The INFORMATION_SCHEMA FILES Table”.)
CREATE TABLESPACE was added in MySQL 5.1.6. In
MySQL 5.1, it is useful only with Disk Data storage for MySQL
Cluster. See Section 17.5.10, “MySQL Cluster Disk Data Tables”.
12.1.19. CREATE TRIGGER SyntaxCREATE
[DEFINER = { user | CURRENT_USER }]
TRIGGER trigger_name trigger_time trigger_event
ON tbl_name FOR EACH ROW trigger_stmt
This statement creates a new trigger. A trigger is a named
database object that is associated with a table, and that
activates when a particular event occurs for the table. The
trigger becomes associated with the table named
tbl_name , which must refer to a
permanent table. You cannot associate a trigger with a
TEMPORARY table or a view.
MySQL Enterprise
For expert advice on creating triggers, subscribe to the MySQL
Enterprise Monitor. For more information, see
http://www.mysql.com/products/enterprise/advisors.html.
CREATE TRIGGER requires the
TRIGGER privilege for the table
associated with the trigger. (Before MySQL 5.1.6, this statement
requires the SUPER privilege.)
The DEFINER clause determines the security
context to be used when checking access privileges at trigger
activation time.
trigger_time is the trigger action
time. It can be BEFORE or
AFTER to indicate that the trigger activates
before or after each row to be modified.
trigger_event indicates the kind of
statement that activates the trigger. The
trigger_event can be one of the
following:
It is important to understand that the
trigger_event does not represent a
literal type of SQL statement that activates the trigger so much
as it represents a type of table operation. For example, an
INSERT trigger is activated by not
only INSERT statements but also
LOAD DATA statements because both
statements insert rows into a table.
A potentially confusing example of this is the INSERT
INTO ... ON DUPLICATE KEY UPDATE ... syntax: a
BEFORE INSERT trigger will activate for every
row, followed by either an AFTER INSERT trigger
or both the BEFORE UPDATE and AFTER
UPDATE triggers, depending on whether there was a
duplicate key for the row.
There cannot be two triggers for a given table that have the same
trigger action time and event. For example, you cannot have two
BEFORE UPDATE triggers for a table. But you can
have a BEFORE UPDATE and a BEFORE
INSERT trigger, or a BEFORE UPDATE
and an AFTER UPDATE trigger.
trigger_stmt is the statement to
execute when the trigger activates. If you want to execute
multiple statements, use the
BEGIN ... END
compound statement construct. This also enables you to use the
same statements that are allowable within stored routines. See
Section 12.8.1, “BEGIN ... END
Compound Statement Syntax”. Some statements are not allowed in
triggers; see Section D.1, “Restrictions on Stored Routines, Triggers, and Events”.
MySQL stores the sql_mode system
variable setting that is in effect at the time a trigger is
created, and always executes the trigger with this setting in
force, regardless of the server SQL mode in effect when
the event begins executing.
Note
Currently, triggers are not activated by cascaded foreign key
actions. This limitation will be lifted as soon as possible.
In MySQL 5.1, you can write triggers containing
direct references to tables by name, such as the trigger named
testref shown in this example:
CREATE TABLE test1(a1 INT);
CREATE TABLE test2(a2 INT);
CREATE TABLE test3(a3 INT NOT NULL AUTO_INCREMENT PRIMARY KEY);
CREATE TABLE test4(
a4 INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
b4 INT DEFAULT 0
);
delimiter |
CREATE TRIGGER testref BEFORE INSERT ON test1
FOR EACH ROW BEGIN
INSERT INTO test2 SET a2 = NEW.a1;
DELETE FROM test3 WHERE a3 = NEW.a1;
UPDATE test4 SET b4 = b4 + 1 WHERE a4 = NEW.a1;
END;
|
delimiter ;
INSERT INTO test3 (a3) VALUES
(NULL), (NULL), (NULL), (NULL), (NULL),
(NULL), (NULL), (NULL), (NULL), (NULL);
INSERT INTO test4 (a4) VALUES
(0), (0), (0), (0), (0), (0), (0), (0), (0), (0);
Suppose that you insert the following values into table
test1 as shown here:
mysql> INSERT INTO test1 VALUES
-> (1), (3), (1), (7), (1), (8), (4), (4);
Query OK, 8 rows affected (0.01 sec)
Records: 8 Duplicates: 0 Warnings: 0
As a result, the data in the four tables will be as follows:
mysql> SELECT * FROM test1;
+------+
| a1 |
+------+
| 1 |
| 3 |
| 1 |
| 7 |
| 1 |
| 8 |
| 4 |
| 4 |
+------+
8 rows in set (0.00 sec)
mysql> SELECT * FROM test2;
+------+
| a2 |
+------+
| 1 |
| 3 |
| 1 |
| 7 |
| 1 |
| 8 |
| 4 |
| 4 |
+------+
8 rows in set (0.00 sec)
mysql> SELECT * FROM test3;
+----+
| a3 |
+----+
| 2 |
| 5 |
| 6 |
| 9 |
| 10 |
+----+
5 rows in set (0.00 sec)
mysql> SELECT * FROM test4;
+----+------+
| a4 | b4 |
+----+------+
| 1 | 3 |
| 2 | 0 |
| 3 | 1 |
| 4 | 2 |
| 5 | 0 |
| 6 | 0 |
| 7 | 1 |
| 8 | 1 |
| 9 | 0 |
| 10 | 0 |
+----+------+
10 rows in set (0.00 sec)
You can refer to columns in the subject table (the table
associated with the trigger) by using the aliases
OLD and NEW .
OLD.col_name refers
to a column of an existing row before it is updated or deleted.
NEW.col_name refers
to the column of a new row to be inserted or an existing row after
it is updated.
The DEFINER clause specifies the MySQL account
to be used when checking access privileges at trigger activation
time. If a user value is given, it
should be a MySQL account in
'user_name '@'host_name '
format (the same format used in the
GRANT statement). The
user_name and
host_name values both are required. The
definer can also be given as
CURRENT_USER or
CURRENT_USER() . The default
DEFINER value is the user who executes the
CREATE TRIGGER statement. (This is
the same as DEFINER = CURRENT_USER .)
If you specify the DEFINER clause, these rules
determine the legal DEFINER user values:
If you do not have the SUPER
privilege, the only legal user
value is your own account, either specified literally or by
using CURRENT_USER . You cannot
set the definer to some other account.
If you have the SUPER
privilege, you can specify any syntactically legal account
name. If the account does not actually exist, a warning is
generated.
Although it is possible to create triggers with a nonexistent
DEFINER value, it is not a good idea for
such triggers to be activated until the definer actually does
exist. Otherwise, the behavior with respect to privilege
checking is undefined.
Note: Prior to MySQL 5.1.6, MySQL requires the
SUPER privilege for the use of
CREATE TRIGGER , so only the second
of the preceding rules applies. As of 5.1.6,
CREATE TRIGGER requires the
TRIGGER privilege and
SUPER is required only to be able
to set DEFINER to a value other than your own
account.
MySQL takes the DEFINER user into account when
checking trigger privileges, as follows:
At CREATE TRIGGER time, the
user who issues the statement must have the
TRIGGER privilege.
(SUPER prior to MySQL 5.1.6.)
At trigger activation time, privileges are checked against the
DEFINER user. This user must have these
privileges:
The TRIGGER privilege.
(SUPER prior to MySQL
5.1.6.)
The SELECT privilege for
the subject table if references to table columns occur via
OLD.col_name
or
NEW.col_name
in the trigger definition.
The UPDATE privilege for
the subject table if table columns are targets of
SET NEW.col_name =
value assignments in
the trigger definition.
Whatever other privileges normally are required for the
statements executed by the trigger.
Within a trigger, the
CURRENT_USER() function returns the
account used to check privileges at trigger activation time. This
is the DEFINER user, not the user whose actions
caused the trigger to be activated. For information about user
auditing within triggers, see
Section 5.5.9, “Auditing MySQL Account Activity”.
If you use LOCK TABLES to lock a
table that has triggers, the tables used within the trigger are
also locked, as described in
Section 12.4.5.2, “LOCK TABLES and Triggers”.
12.1.20. CREATE VIEW SyntaxCREATE
[OR REPLACE]
[ALGORITHM = {UNDEFINED | MERGE | TEMPTABLE}]
[DEFINER = { user | CURRENT_USER }]
[SQL SECURITY { DEFINER | INVOKER }]
VIEW view_name [(column_list )]
AS select_statement
[WITH [CASCADED | LOCAL] CHECK OPTION]
The CREATE VIEW statement creates a
new view, or replaces an existing one if the OR
REPLACE clause is given. If the view does not exist,
CREATE OR REPLACE VIEW is the same as
CREATE VIEW . If the view does
exist, CREATE OR REPLACE VIEW is the same as
ALTER VIEW .
The select_statement is a
SELECT statement that provides the
definition of the view. (When you select from the view, you select
in effect using the SELECT
statement.) select_statement can select
from base tables or other views.
The view definition is “frozen” at creation time, so
changes to the underlying tables afterward do not affect the view
definition. For example, if a view is defined as SELECT
* on a table, new columns added to the table later do
not become part of the view.
The ALGORITHM clause affects how MySQL
processes the view. The DEFINER and
SQL SECURITY clauses specify the security
context to be used when checking access privileges at view
invocation time. The WITH CHECK OPTION clause
can be given to constrain inserts or updates to rows in tables
referenced by the view. These clauses are described later in this
section.
The CREATE VIEW statement requires
the CREATE VIEW privilege for the
view, and some privilege for each column selected by the
SELECT statement. For columns used
elsewhere in the SELECT statement
you must have the SELECT privilege.
If the OR REPLACE clause is present, you must
also have the DROP privilege for
the view.
A view belongs to a database. By default, a new view is created in
the default database. To create the view explicitly in a given
database, specify the name as
db_name.view_name when you create it.
mysql> CREATE VIEW test.v AS SELECT * FROM t;
Base tables and views share the same namespace within a database,
so a database cannot contain a base table and a view that have the
same name.
Views must have unique column names with no duplicates, just like
base tables. By default, the names of the columns retrieved by the
SELECT statement are used for the
view column names. To define explicit names for the view columns,
the optional column_list clause can be
given as a list of comma-separated identifiers. The number of
names in column_list must be the same
as the number of columns retrieved by the
SELECT statement.
Note
Prior to MySQL 5.1.29, when you modify an existing view, the
current view definition is backed up and saved. It is stored in
that table's database directory, in a subdirectory named
arc . The backup file for a view
v is named v.frm-00001 .
If you alter the view again, the next backup is named
v.frm-00002 . The three latest view backup
definitions are stored.
Backed up view definitions are not preserved by
mysqldump, or any other such programs, but
you can retain them using a file copy operation. However, they
are not needed for anything but to provide you with a backup of
your previous view definition.
It is safe to remove these backup definitions, but only while
mysqld is not running. If you delete the
arc subdirectory or its files while
mysqld is running, you will receive an error
the next time you try to alter the view:
mysql> ALTER VIEW v AS SELECT * FROM t;
ERROR 6 (HY000): Error on delete of '.\test\arc/v.frm-0004' (Errcode:
2)
Columns retrieved by the SELECT
statement can be simple references to table columns. They can also
be expressions that use functions, constant values, operators, and
so forth.
Unqualified table or view names in the
SELECT statement are interpreted
with respect to the default database. A view can refer to tables
or views in other databases by qualifying the table or view name
with the proper database name.
A view can be created from many kinds of
SELECT statements. It can refer to
base tables or other views. It can use joins,
UNION , and subqueries. The
SELECT need not even refer to any
tables. The following example defines a view that selects two
columns from another table, as well as an expression calculated
from those columns:
mysql> CREATE TABLE t (qty INT, price INT);
mysql> INSERT INTO t VALUES(3, 50);
mysql> CREATE VIEW v AS SELECT qty, price, qty*price AS value FROM t;
mysql> SELECT * FROM v;
+------+-------+-------+
| qty | price | value |
+------+-------+-------+
| 3 | 50 | 150 |
+------+-------+-------+
A view definition is subject to the following restrictions:
The SELECT statement cannot
contain a subquery in the FROM clause.
The SELECT statement cannot
refer to system or user variables.
Within a stored program, the definition cannot refer to
program parameters or local variables.
The SELECT statement cannot
refer to prepared statement parameters.
Any table or view referred to in the definition must exist.
However, after a view has been created, it is possible to drop
a table or view that the definition refers to. In this case,
use of the view results in an error. To check a view
definition for problems of this kind, use the
CHECK TABLE statement.
The definition cannot refer to a TEMPORARY
table, and you cannot create a TEMPORARY
view.
Any tables named in the view definition must exist at
definition time.
You cannot associate a trigger with a view.
As of MySQL 5.1.23, aliases for column names in the
SELECT statement are checked
against the maximum column length of 64 characters (not the
maximum alias length of 256 characters).
ORDER BY is allowed in a view definition, but
it is ignored if you select from a view using a statement that has
its own ORDER BY .
For other options or clauses in the definition, they are added to
the options or clauses of the statement that references the view,
but the effect is undefined. For example, if a view definition
includes a LIMIT clause, and you select from
the view using a statement that has its own
LIMIT clause, it is undefined which limit
applies. This same principle applies to options such as
ALL , DISTINCT , or
SQL_SMALL_RESULT that follow the
SELECT keyword, and to clauses such
as INTO , FOR UPDATE ,
LOCK IN SHARE MODE , and
PROCEDURE .
If you create a view and then change the query processing
environment by changing system variables, that may affect the
results that you get from the view:
mysql> CREATE VIEW v (mycol) AS SELECT 'abc';
Query OK, 0 rows affected (0.01 sec)
mysql> SET sql_mode = '';
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT "mycol" FROM v;
+-------+
| mycol |
+-------+
| mycol |
+-------+
1 row in set (0.01 sec)
mysql> SET sql_mode = 'ANSI_QUOTES';
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT "mycol" FROM v;
+-------+
| mycol |
+-------+
| abc |
+-------+
1 row in set (0.00 sec)
The DEFINER and SQL SECURITY
clauses determine which MySQL account to use when checking access
privileges for the view when a statement is executed that
references the view. They were addded in MySQL 5.1.2. The legal
SQL SECURITY characteristic values are
DEFINER and INVOKER . These
indicate that the required privileges must be held by the user who
defined or invoked the view, respectively. The default
SQL SECURITY value is
DEFINER .
If a user value is given for the
DEFINER clause, it should be a MySQL account in
'user_name '@'host_name '
format (the same format used in the
GRANT statement). The
user_name and
host_name values both are required. The
definer can also be given as
CURRENT_USER or
CURRENT_USER() . The default
DEFINER value is the user who executes the
CREATE VIEW statement. This is the
same as specifying DEFINER = CURRENT_USER
explicitly.
If you specify the DEFINER clause, these rules
determine the legal DEFINER user values:
If you do not have the SUPER
privilege, the only legal user
value is your own account, either specified literally or by
using CURRENT_USER . You cannot
set the definer to some other account.
If you have the SUPER
privilege, you can specify any syntactically legal account
name. If the account does not actually exist, a warning is
generated.
If the SQL SECURITY value is
DEFINER but the definer account does not
exist when the view is referenced, an error occurs.
Within a view definition,
CURRENT_USER returns the view's
DEFINER value by default as of MySQL 5.1.12.
For older versions, and for views defined with the SQL
SECURITY INVOKER characteristic,
CURRENT_USER returns the account
for the view's invoker. For information about user auditing within
views, see Section 5.5.9, “Auditing MySQL Account Activity”.
Within a stored routine that is defined with the SQL
SECURITY DEFINER characteristic,
CURRENT_USER returns the routine's
DEFINER value. This also affects a view defined
within such a program, if the view definition contains a
DEFINER value of
CURRENT_USER .
As of MySQL 5.1.2 (when the DEFINER and
SQL SECURITY clauses were implemented), view
privileges are checked like this:
At view definition time, the view creator must have the
privileges needed to use the top-level objects accessed by the
view. For example, if the view definition refers to table
columns, the creator must have privileges for the columns, as
described previously. If the definition refers to a stored
function, only the privileges needed to invoke the function
can be checked. The privileges required when the function runs
can be checked only as it executes: For different invocations
of the function, different execution paths within the function
might be taken.
When a view is referenced, privileges for objects accessed by
the view are checked against the privileges held by the view
creator or invoker, depending on whether the SQL
SECURITY characteristic is
DEFINER or INVOKER ,
respectively.
If reference to a view causes execution of a stored function,
privilege checking for statements executed within the function
depend on whether the function is defined with a SQL
SECURITY characteristic of
DEFINER or INVOKER . If
the security characteristic is DEFINER , the
function runs with the privileges of its creator. If the
characteristic is INVOKER , the function
runs with the privileges determined by the view's SQL
SECURITY characteristic.
Prior to MySQL 5.1.2 (before the DEFINER and
SQL SECURITY clauses were implemented),
privileges required for objects used in a view are checked at view
creation time.
Example: A view might depend on a stored function, and that
function might invoke other stored routines. For example, the
following view invokes a stored function f() :
CREATE VIEW v AS SELECT * FROM t WHERE t.id = f(t.name);
Suppose that f() contains a statement such as
this:
IF name IS NULL then
CALL p1();
ELSE
CALL p2();
END IF;
The privileges required for executing statements within
f() need to be checked when
f() executes. This might mean that privileges
are needed for p1() or p2() ,
depending on the execution path within f() .
Those privileges must be checked at runtime, and the user who must
possess the privileges is determined by the SQL
SECURITY values of the view v and the
function f() .
The DEFINER and SQL SECURITY
clauses for views are extensions to standard SQL. In standard SQL,
views are handled using the rules for SQL SECURITY
INVOKER .
If you invoke a view that was created before MySQL 5.1.2, it is
treated as though it was created with a SQL SECURITY
DEFINER clause and with a DEFINER
value that is the same as your account. However, because the
actual definer is unknown, MySQL issues a warning. To make the
warning go away, it is sufficient to re-create the view so that
the view definition includes a DEFINER clause.
The optional ALGORITHM clause is a MySQL
extension to standard SQL. It affects how MySQL processes the
view. ALGORITHM takes three values:
MERGE , TEMPTABLE , or
UNDEFINED . The default algorithm is
UNDEFINED if no ALGORITHM
clause is present. For more information, see
Section 19.5.2, “View Processing Algorithms”.
Some views are updatable. That is, you can use them in statements
such as UPDATE ,
DELETE , or
INSERT to update the contents of
the underlying table. For a view to be updatable, there must be a
one-to-one relationship between the rows in the view and the rows
in the underlying table. There are also certain other constructs
that make a view nonupdatable.
The WITH CHECK OPTION clause can be given for
an updatable view to prevent inserts or updates to rows except
those for which the WHERE clause in the
select_statement is true.
In a WITH CHECK OPTION clause for an updatable
view, the LOCAL and CASCADED
keywords determine the scope of check testing when the view is
defined in terms of another view. The LOCAL
keyword restricts the CHECK OPTION only to the
view being defined. CASCADED causes the checks
for underlying views to be evaluated as well. When neither keyword
is given, the default is CASCADED .
For more information about updatable views and the WITH
CHECK OPTION clause, see
Section 19.5.3, “Updatable and Insertable Views”.
12.1.21. DROP DATABASE SyntaxDROP {DATABASE | SCHEMA} [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.
DROP
SCHEMA is a synonym for DROP
DATABASE .
IF EXISTS is used to prevent an error from
occurring if the database does not exist.
If you use DROP DATABASE on a
symbolically linked database, both the link and the original
database are deleted.
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:
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”.
12.1.22. DROP EVENT SyntaxDROP EVENT [IF EXISTS] event_name
This statement drops the event named
event_name . The event immediately
ceases being active, and is deleted completely from the server.
If the event does not exist, the error ERROR 1517
(HY000): Unknown event
'event_name ' results. You
can override this and cause the statement to generate a warning
for nonexistent events instead using IF EXISTS .
Beginning with MySQL 5.1.12, this statement requires the
EVENT privilege for the schema to
which the event to be dropped belongs. (In MySQL 5.1.11 and
earlier, an event could be dropped only by its definer, or by a
user having the SUPER privilege.)
12.1.23. DROP FUNCTION Syntax
The DROP FUNCTION statement is used
to drop stored functions and user-defined functions (UDFs):
12.1.24. DROP INDEX SyntaxDROP [ONLINE|OFFLINE] INDEX index_name ON tbl_name
DROP INDEX drops the index named
index_name from the table
tbl_name . This statement is mapped to
an ALTER TABLE statement to drop
the index. See Section 12.1.7, “ALTER TABLE Syntax”.
Beginning with MySQL 5.1.7, indexes on variable-width columns are
dropped online; that is, dropping the indexes does not require any
copying of the table. For NDBCLUSTER
tables, the table is not locked against access from other MySQL
Cluster API nodes, although it is locked against other operations
on the same API node for the duration of the
online operation. This is done automatically by the server
whenever it determines that it is possible to do so; you do not
have to use any special SQL syntax or server options to cause it
to happen.
In standard MySQL 5.1 releases, it is not possible to
override the server when it determines that an index is to be
dropped online. In MySQL Cluster, beginning with MySQL Cluster NDB
6.2.5 and MySQL Cluster NDB 6.3.3, you can drop indexes offline
(which causes the table to be locked for all API nodes in the
cluster) using the OFFLINE keyword. The rules
and limitations governing online DROP OFFLINE
INDEX and DROP ONLINE INDEX are the
same as for ALTER OFFLINE TABLE ... DROP INDEX
and ALTER ONLINE TABLE ... DROP INDEX . You
cannot cause the online dropping of an index that would normally
be dropped offline by using the ONLINE keyword
(if it is not possible to perform the DROP
operation online, then the ONLINE keyword is
ignored). For more information, see Section 12.1.7, “ALTER TABLE Syntax”.
Note
The ONLINE and OFFLINE
keywords are available only in MySQL Cluster NDB 6.2 and MySQL
Cluster NDB 6.3 releases beginning with versions 6.2.5 and
6.3.3, respectively; attempting to use them in earlier MySQL
Cluster NDB 6.2 or 6.3 releases, standard MySQL 5.1 releases, or
MySQL Cluster NDB 6.1 releases results in a syntax error.
12.1.25. DROP LOGFILE GROUP SyntaxDROP LOGFILE GROUP logfile_group
ENGINE [=] engine_name
This statement drops the log file group named
logfile_group . The log file group must
already exist or an error results. (For information on creating
log file groups, see Section 12.1.14, “CREATE LOGFILE GROUP Syntax”.)
Important
Before dropping a log file group, you must drop all tablespaces
that use that log file group for UNDO
logging.
The required ENGINE clause provides the name of
the storage engine used by the log file group to be dropped. In
MySQL 5.1, the only permitted values for
engine_name are
NDB and
NDBCLUSTER .
DROP LOGFILE GROUP was added in MySQL 5.1.6. In
MySQL 5.1, it is useful only with Disk Data storage for MySQL
Cluster. See Section 17.5.10, “MySQL Cluster Disk Data Tables”.
12.1.26. DROP PROCEDURE and
DROP FUNCTION SyntaxDROP {PROCEDURE | FUNCTION} [IF EXISTS] sp_name
This statement is used to drop a stored procedure or function.
That is, the specified routine is removed from the server. You
must have the ALTER ROUTINE
privilege for the routine. (If the
automatic_sp_privileges system variable is
enabled, that privilege and EXECUTE
are granted automatically to the routine creator when the routine
is created and dropped from the creator when the routine is
dropped. See Section 19.2.2, “Stored Routines and MySQL Privileges”.)
The IF EXISTS clause is a MySQL extension. It
prevents an error from occurring if the procedure or function does
not exist. A warning is produced that can be viewed with
SHOW WARNINGS .
DROP FUNCTION is also used to drop
user-defined functions (see Section 12.5.3.2, “DROP FUNCTION Syntax”).
12.1.27. DROP SERVER SyntaxDROP SERVER [ IF EXISTS ] server_name
Drops the server definition for the server named
server_name . The
corresponding row within the mysql.servers
table will be deleted. This statement requires the
SUPER privilege.
Dropping a server for a table does not affect any
FEDERATED tables that used this connection
information when they were created. See
Section 12.1.16, “CREATE SERVER Syntax”.
DROP SERVER does not cause an
automatic commit.
DROP SERVER was added in MySQL
5.1.15.
12.1.28. DROP TABLE SyntaxDROP [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.
Note that for a partitioned table, DROP
TABLE permanently removes the table definition, all of
its partitions, and all of the data which was stored in those
partitions. It also removes the partitioning definition
(.par ) file associated with the dropped
table.
Use IF EXISTS to prevent an error from
occurring for tables that do not exist. A NOTE
is generated for each nonexistent table when using IF
EXISTS . See Section 12.5.5.42, “SHOW WARNINGS Syntax”.
RESTRICT and CASCADE are
allowed to make porting easier. In MySQL 5.1, they do
nothing.
Note
DROP TABLE automatically commits
the current active transaction, unless you use the
TEMPORARY keyword.
The TEMPORARY keyword has the following
effects:
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.
12.1.29. DROP TABLESPACE SyntaxDROP TABLESPACE tablespace_name
ENGINE [=] engine_name
This statement drops a tablespace that was previously created
using CREATE TABLESPACE (see
Section 12.1.18, “CREATE TABLESPACE Syntax”).
Important
The tablespace to be dropped must not contain any data files; in
other words, before you can drop a tablespace, you must first
drop each of its data files using ALTER TABLESPACE ...
DROP DATAFILE (see
Section 12.1.8, “ALTER TABLESPACE Syntax”).
The ENGINE clause (required) specifies the
storage engine used by the tablespace. In MySQL 5.1, the only
accepted values for engine_name are
NDB and
NDBCLUSTER .
DROP TABLESPACE was added in MySQL 5.1.6. In
MySQL 5.1, it is useful only with Disk Data storage for MySQL
Cluster. See Section 17.5.10, “MySQL Cluster Disk Data Tables”.
12.1.30. DROP TRIGGER SyntaxDROP TRIGGER [IF EXISTS] [schema_name .]trigger_name
This statement drops a trigger. The schema (database) name is
optional. If the schema is omitted, the trigger is dropped from
the default schema. DROP TRIGGER
was added in MySQL 5.0.2. Its use requires the
TRIGGER privilege for the table
associated with the trigger. (This statement requires the
SUPER privilege prior to MySQL
5.1.6.)
Use IF EXISTS to prevent an error from
occurring for a trigger that does not exist. A
NOTE is generated for a nonexistent trigger
when using IF EXISTS . See
Section 12.5.5.42, “SHOW WARNINGS Syntax”. The IF EXISTS
clause was added in MySQL 5.1.14.
Triggers for a table are also dropped if you drop the table.
Note
When upgrading from a version of MySQL older than MySQL 5.0.10
to 5.0.10 or newer — including all MySQL 5.1
releases — you must drop all triggers before
upgrading and re-create them afterward, or else
DROP TRIGGER does not work after
the upgrade. See
Section 2.4.1.1, “Upgrading from MySQL 5.0 to 5.1”, for a
suggested upgrade procedure.
12.1.31. DROP VIEW SyntaxDROP VIEW [IF EXISTS]
view_name [, view_name ] ...
[RESTRICT | CASCADE]
DROP VIEW removes one or more
views. You must have the DROP
privilege for each view. If any of the views named in the argument
list do not exist, MySQL returns an error indicating by name which
nonexisting views it was unable to drop, but it also drops all of
the views in the list that do exist.
The IF EXISTS clause prevents an error from
occurring for views that don't exist. When this clause is given, a
NOTE is generated for each nonexistent view.
See Section 12.5.5.42, “SHOW WARNINGS Syntax”.
RESTRICT and CASCADE , if
given, are parsed and ignored.
12.1.32. RENAME DATABASE SyntaxRENAME {DATABASE | SCHEMA} db_name TO new_db_name ;
This statement was added in MySQL 5.1.7 but was found to be
dangerous and was removed in MySQL 5.1.23. It was intended to
enable upgrading pre-5.1 databases to use the encoding implemented
in 5.1 for mapping database names to database directory names (see
Section 8.2.3, “Mapping of Identifiers to File Names”). However, use of this
statement could result in loss of database contents, which is why
it was removed. Do not use RENAME DATABASE in
earlier versions in which it is present.
To perform the task of upgrading database names with the new
encoding, use ALTER DATABASE
db_name UPGRADE DATA DIRECTORY
NAME instead (see Section 12.1.1, “ALTER DATABASE Syntax”).
12.1.33. RENAME TABLE SyntaxRENAME TABLE tbl_name TO new_tbl_name
[, tbl_name2 TO new_tbl_name2 ] ...
This statement renames one or more tables.
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 TABLE current_db.tbl_name TO other_db.tbl_name;
If there are any triggers associated with a table which is moved
to a different database using RENAME
TABLE , then the statement fails with the error
Trigger in wrong schema.
RENAME TABLE also works for views,
as long as you do not try to rename a view into a different
database.
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;
12.2. Data Manipulation StatementsCALL sp_name ([parameter [,...]])
CALL sp_name [()]
The CALL statement invokes a stored
procedure that was defined previously with
CREATE PROCEDURE .
As of MySQL 5.1.13, stored procedures that take no arguments can
be invoked without parentheses. That is, CALL
p() and CALL p are equivalent.
CALL can pass back values to its
caller using parameters that are declared as
OUT or INOUT parameters.
When the procedure returns, a client program can also obtain the
number of rows affected for the final statement executed within
the routine: At the SQL level, call the
ROW_COUNT() function; from the C
API, call the
mysql_affected_rows() function.
To get back a value from a procedure using an
OUT or INOUT parameter, pass
the parameter by means of a user variable, and then check the
value of the variable after the procedure returns. (If you are
calling the procedure from within another stored procedure or
function, you can also pass a routine parameter or local routine
variable as an IN or INOUT
parameter.) For an INOUT parameter, initialize
its value before passing it to the procedure. The following
procedure has an OUT parameter that the
procedure sets to the current server version, and an
INOUT value that the procedure increments by
one from its current value:
CREATE PROCEDURE p (OUT ver_param VARCHAR(25), INOUT incr_param INT)
BEGIN
# Set value of OUT parameter
SELECT VERSION() INTO ver_param;
# Increment value of INOUT parameter
SET incr_param = incr_param + 1;
END;
Before calling the procedure, initialize the variable to be passed
as the INOUT parameter. After calling the
procedure, the values of the two variables will have been set or
modified:
mysql> SET @increment = 10;
mysql> CALL p(@version, @increment);
mysql> SELECT @version, @increment;
+------------+------------+
| @version | @increment |
+------------+------------+
| 5.1.32-log | 11 |
+------------+------------+
In prepared CALL statements used
with PREPARE and
EXECUTE , placeholder support is
available in MySQL 5.1 for IN
parameters, but not for OUT or
INOUT parameters. To work around this
limitation for OUT and INOUT
parameters, forego the use of placeholders; instead, refer to user
variables in the CALL statement
itself and do not specify them in the
EXECUTE statement:
mysql> SET @increment = 10;
mysql> PREPARE s FROM 'CALL p(@version, @increment)';
mysql> EXECUTE s;
mysql> SELECT @version, @increment;
+------------+------------+
| @version | @increment |
+------------+------------+
| 5.1.32-log | 11 |
+------------+------------+
To write C programs that use the
CALL SQL statement to execute
stored procedures that produce result sets, the
CLIENT_MULTI_RESULTS flag must be enabled. This
is because each CALL returns a
result to indicate the call status, in addition to any result sets
that might be returned by statements executed within the
procedure. CLIENT_MULTI_RESULTS must also be
enabled if CALL is used to execute
any stored procedure that contains prepared statements. It cannot
be determined when such a procedure is loaded whether those
statements will produce result sets, so it is necessary to assume
that they will.
CLIENT_MULTI_RESULTS can be enabled when you
call mysql_real_connect() , either
explicitly by passing the CLIENT_MULTI_RESULTS
flag itself, or implicitly by passing
CLIENT_MULTI_STATEMENTS (which also enables
CLIENT_MULTI_RESULTS ).
To process the result of a CALL
statement executed via
mysql_query() or
mysql_real_query() , use a loop
that calls mysql_next_result() to
determine whether there are more results. For an example, see
Section 21.9.12, “C API Support for Multiple Statement Execution”.
For programs written in a language that provides a MySQL
interface, there is no native method for directly retrieving the
results of OUT or INOUT
parameters from CALL statements. To
get the parameter values, pass user-defined variables to the
procedure in the CALL statement and
then execute a SELECT statement to
produce a result set containing the variable values. To handle an
INOUT parameter, execute a statement prior to
the CALL that sets the
corresponding user variable to the value to be passed to the
procedure.
The following example illustrates the technique (without error
checking) for the stored procedure p described
earlier that has an OUT parameter and an
INOUT parameter:
mysql_query(mysql, "SET @increment = 10");
mysql_query(mysql, "CALL p(@version, @increment)");
mysql_query(mysql, "SELECT @version, @increment");
result = mysql_store_result(mysql);
row = mysql_fetch_row(result);
mysql_free_result(result);
After the preceding code executes, row[0] and
row[1] contain the values of
@version and @increment ,
respectively.
Single-table syntax:
DELETE [LOW_PRIORITY] [QUICK] [IGNORE] FROM tbl_name
[WHERE where_condition ]
[ORDER BY ...]
[LIMIT row_count ]
Multiple-table syntax:
DELETE [LOW_PRIORITY] [QUICK] [IGNORE]
tbl_name [.*] [, tbl_name [.*]] ...
FROM table_references
[WHERE where_condition ]
Or:
DELETE [LOW_PRIORITY] [QUICK] [IGNORE]
FROM tbl_name [.*] [, tbl_name [.*]] ...
USING table_references
[WHERE where_condition ]
For the single-table syntax, the
DELETE statement deletes rows from
tbl_name and returns a count of the
number of deleted rows. This count can be obtained by calling the
ROW_COUNT() function (see
Section 11.11.3, “Information Functions”). 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.8, “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.2.10, “TRUNCATE TABLE Syntax”, and
Section 12.4.5, “LOCK TABLES and
UNLOCK
TABLES Syntax”.
If you delete the row containing the maximum value for an
AUTO_INCREMENT column, the value is not reused
for a MyISAM or InnoDB
table. If you delete all rows in the table with DELETE
FROM tbl_name (without a
WHERE clause) in
autocommit mode, the sequence
starts over for all storage engines except
InnoDB and MyISAM . There are
some exceptions to this behavior for InnoDB
tables, as discussed in
Section 13.6.4.3, “AUTO_INCREMENT Handling in InnoDB ”.
For MyISAM 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.
The speed of delete operations may also be affected by factors
discussed in Section 7.2.23, “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.5.2.5, “OPTIMIZE TABLE Syntax”, and Section 4.6.3, “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
row_count option to
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.
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.33, “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.8.1, “JOIN Syntax”.
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 allowed 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 allows .* 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.
Note
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 ...
Table aliases in a multiple-table
DELETE statement should be declared
only in the table_references part.
Elsewhere in the statement, alias references are allowed but not
alias declarations.
Correct:
DELETE a1, a2 FROM t1 AS a1 INNER JOIN t2 AS a2
WHERE a1.id=a2.id;
DELETE FROM a1, a2 USING t1 AS a1 INNER JOIN t2 AS a2
WHERE a1.id=a2.id;
Incorrect:
DELETE t1 AS a1, t2 AS a2 FROM t1 INNER JOIN t2
WHERE a1.id=a2.id;
DELETE FROM t1 AS a1, t2 AS a2 USING t1 INNER JOIN t2
WHERE a1.id=a2.id;
Declaration of aliases other than in the
table_references part can lead to
ambiguous statements that have unexpected results such as deleting
rows from the wrong table. This is such a statement:
DELETE FROM t1 AS a2 USING t1 AS a1 INNER JOIN t2 AS a2;
Before MySQL 5.1.23, alias declarations are allowed in other than
the table_references part, but should
be avoided for the reason just mentioned.
Cross-database deletes are supported for multiple-table deletes,
but you should be aware that in the list of tables from which to
delete rows, aliases will have a default database unless one is
specified explicitly. For example, if the default database is
test , the following statement does not work
because the unqualified alias a1 has a default
database of test :
DELETE a1, a2 FROM db1.t1 AS a1 INNER JOIN db2.t2 AS a2
WHERE a1.id=a2.id;
To correctly match the alias, you must explicitly qualify it with
the database of the table being aliased:
DELETE db1.a1, db2.a2 FROM db1.t1 AS a1 INNER JOIN db2.t2 AS a2
WHERE a1.id=a2.id;
DO expr [, expr ] ...
DO executes the expressions but
does not return any results. In most respects,
DO is shorthand for SELECT
expr , ... , but has the
advantage that it is slightly faster when you do not care about
the result.
DO is useful primarily with
functions that have side effects, such as
RELEASE_LOCK() .
HANDLER tbl_name OPEN [ [AS] alias ]
HANDLER tbl_name READ index_name { = | >= | <= | < } (value1 ,value2 ,...)
[ WHERE where_condition ] [LIMIT ... ]
HANDLER tbl_name READ index_name { FIRST | NEXT | PREV | LAST }
[ WHERE where_condition ] [LIMIT ... ]
HANDLER tbl_name READ { FIRST | NEXT }
[ WHERE where_condition ] [LIMIT ... ]
HANDLER tbl_name CLOSE
The HANDLER statement provides
direct access to table storage engine interfaces. It is available
for MyISAM and InnoDB
tables.
The HANDLER ... OPEN statement opens a table,
making it accessible via 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 tbl_name READ
index_name when a full table
scan is desired. Natural row order is the order in which rows are
stored in a 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.8, “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
allowed), so the storage engine can use optimizations that
SELECT does not normally
allow.
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:
As of MySQL 5.1.39, TRUNCATE TABLE
for a table closes all handlers for the table that were opened
with HANDLER
OPEN .
INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
[INTO] tbl_name [(col_name ,...)]
{VALUES | VALUE} ({expr | DEFAULT},...),(...),...
[ ON DUPLICATE KEY UPDATE
col_name =expr
[, col_name =expr ] ... ]
Or:
INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE]
[INTO] tbl_name
SET col_name ={expr | DEFAULT}, ...
[ ON DUPLICATE KEY UPDATE
col_name =expr
[, col_name =expr ] ... ]
Or:
INSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE]
[INTO] tbl_name [(col_name ,...)]
SELECT ...
[ ON DUPLICATE KEY UPDATE
col_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. INSERT
... SELECT is discussed further in
Section 12.2.5.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.7, “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
tbl_name to find out.
The SET clause indicates the column names
explicitly.
Column values can be given in several ways:
If you are not running in strict SQL mode, 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”. See also
Section 1.8.6.2, “Constraints on Invalid Data”.
If you want an INSERT statement
to generate an error unless you explicitly specify values for
all columns that do not have a default value, you should use
strict mode. See Section 5.1.8, “Server SQL Modes”.
Use the keyword DEFAULT to set a column
explicitly to its default value. 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.
You can also use
DEFAULT(col_name )
as a more general form that can be used in expressions to
produce a given column's default value.
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();
In strict mode, an error occurs if any column doesn't have a
default value. Otherwise, MySQL uses the implicit default
value for any column that does not have an explicitly defined
default.
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
ROW_COUNT() function (see
Section 11.11.3, “Information Functions”), or the
mysql_affected_rows() C API
function (see Section 21.9.3.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 21.9.3.35, “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.11.3, “Information Functions”, and
Section 21.9.3.37, “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.5.2, “INSERT DELAYED Syntax”.
DELAYED is ignored with
INSERT ...
SELECT or
INSERT
... ON DUPLICATE KEY UPDATE .
Beginning with MySQL 5.1.19, DELAYED is
also disregarded for an INSERT
that uses functions accessing tables or triggers, or that is
called from a function or a trigger.
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.3.3, “Concurrent Inserts”.
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.3.3, “Concurrent Inserts”.
LOW_PRIORITY and
HIGH_PRIORITY affect only storage engines
that use only table-level locking (such as
MyISAM , MEMORY , and
MERGE ).
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.
IGNORE has a similar effect on inserts into
partitioned tables where no partition matching a given value
is found. Without IGNORE , such
INSERT statements are aborted
with an error; however, when
INSERT
IGNORE is used, the insert operation fails silently
for the row containing the unmatched value, but any rows that
are matched are inserted. For an example, see
Section 18.2.2, “LIST Partitioning”.
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. 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.5.3, “INSERT ... ON
DUPLICATE KEY UPDATE Syntax”.
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).
12.2.5.1. INSERT ...
SELECT SyntaxINSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE]
[INTO] tbl_name [(col_name ,...)]
SELECT ...
[ ON DUPLICATE KEY UPDATE col_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:
Specify IGNORE to ignore rows that would
cause duplicate-key violations.
DELAYED is ignored with
INSERT ...
SELECT .
The target table of the
INSERT statement may appear
in the FROM clause of the
SELECT part of the query.
(This was not possible in some older versions of MySQL.) 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.3, “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 allow 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.
12.2.5.2. INSERT DELAYED SyntaxINSERT 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.
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 MyISAM , MEMORY ,
ARCHIVE , and (as of MySQL 5.1.19)
BLACKHOLE 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. 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 and the global logging format is to use
statement-based logging (binlog_format is
set to STATEMENT ). This restriction does
not apply to row-based binary logging.
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.
INSERT DELAYED is not
supported for views.
INSERT DELAYED is not
supported for partitioned tables.
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 allows 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
thread_id . However,
before exiting, it first stores all queued rows into the
table. During this time it does not accept any new
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
thread_id ), or someone
executes a FLUSH
TABLES .
The following status variables provide information about
INSERT DELAYED statements.
You can view these variables by issuing a
SHOW STATUS statement or by
executing a mysqladmin extended-status
command.
12.2.5.3. INSERT ... ON
DUPLICATE KEY UPDATE Syntax
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. 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.
You can use the
VALUES(col_name )
function in the UPDATE clause to
refer to column values from the
INSERT portion of the
INSERT ...
ON DUPLICATE KEY UPDATE statement. In other words,
VALUES(col_name )
in the 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 prior to MySQL 5.1.12. However, you can work around
this by using
LAST_INSERT_ID(expr ) .
Suppose that 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 .
12.2.6. LOAD DATA INFILE
SyntaxLOAD DATA [LOW_PRIORITY | CONCURRENT] [LOCAL] INFILE 'file_name '
[REPLACE | IGNORE]
INTO TABLE tbl_name
[CHARACTER SET charset_name ]
[{FIELDS | COLUMNS}
[TERMINATED BY 'string ']
[[OPTIONALLY] ENCLOSED BY 'char ']
[ESCAPED BY 'char ']
]
[LINES
[STARTING BY 'string ']
[TERMINATED BY 'string ']
]
[IGNORE number LINES]
[(col_name_or_user_var ,...)]
[SET col_name = expr ,...]
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.8, “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.2.21, “Speed of INSERT Statements”.
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
character_set_client do not
affect interpretation of input. If the contents of the input file
use a character set that differs from the default, it is usually
preferable to specify the character set of the file by using the
CHARACTER SET clause, which is available as of
MySQL 5.1.17. A character set of binary
specifies “no conversion.”
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.
As of MySQL 5.1.6, the
character_set_filesystem system
variable controls the interpretation of the file name.
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.
Prior to MySQL 5.1.43, CONCURRENT was not
replicated when using statement-based replication (see Bug#34628).
However, it is replicated when using row-based replication,
regardless of the version. See
Section 16.3.1.13, “Replication and LOAD DATA
INFILE ”, for more
information.
Note
Prior to MySQL 5.1.23, LOAD DATA
performed very poorly when importing into partitioned tables.
The statement now uses buffering to improve performance;
however, the buffer uses 130KB memory per partition to achieve
this. (Bug#26527)
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.
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.
Note
A regression in MySQL 5.1.40 caused the database referenced in a
fully qualified table name to be ignored by
LOAD DATA when using replication
with either STATEMENT or
MIXED as the binary logging format; this
could lead to problems if the table was not in the current
database. As a workaround, you can specify the correct database
with the USE statement prior to
executing LOAD DATA . If
necessary, you can reset the default database with a second
USE statement following the
LOAD DATA statement.
This issue was fixed in MySQL 5.1.41. (Bug#48297)
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.4.1, “Privileges Provided by MySQL”. For
non-LOCAL load operations, if the
secure_file_priv system variable
is set to a nonempty directory name, the file to be loaded must be
located in that directory.
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.
LOCAL works only if your server and your client
both have been enabled to allow it. For example, if
mysqld was started with
--local-infile=0 ,
LOCAL does not work. See
Section 5.3.4, “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.
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.7, “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.
If you want to ignore foreign key constraints during the load
operation, you can 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.2.21, “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.
Note
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
'prefix_string ' 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:
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 number
LINES option can be used to ignore lines at the start of
the file. For example, you can use IGNORE 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 quotes, 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 quotes,
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, quotes 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.
For more information about
“\ ”-escape syntax, see
Section 8.1.1, “Strings”.
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.
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, or an error in
strict SQL mode. 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.
The column list can contain either column names or user variables.
With user variables, the SET clause enables you
to perform transformations on their values before assigning the
result to columns.
User variables in the SET clause can be used in
several ways. The following example uses the first input column
directly for the value of t1.column1 , and
assigns the second input column to a user variable that is
subjected to a division operation before being used for the value
of t1.column2 :
LOAD DATA INFILE 'file.txt'
INTO TABLE t1
(column1, @var1)
SET column2 = @var1/100;
The SET clause can be used to supply values not
derived from the input file. The following statement sets
column3 to the current date and time:
LOAD DATA INFILE 'file.txt'
INTO TABLE t1
(column1, column2)
SET column3 = CURRENT_TIMESTAMP;
You can also discard an input value by assigning it to a user
variable and not assigning the variable to a table column:
LOAD DATA INFILE 'file.txt'
INTO TABLE t1
(column1, @dummy, column2, @dummy, column3);
Use of the column/variable list and SET clause
is subject to the following restrictions:
Assignments in the SET clause should have
only column names on the left hand side of assignment
operators.
You can use subqueries in the right hand side of
SET assignments. A subquery that returns a
value to be assigned to a column may be a scalar subquery
only. Also, you cannot use a subquery to select from the table
that is being loaded.
Lines ignored by an IGNORE clause are not
processed for the column/variable list or
SET clause.
User variables cannot be used when loading data with fixed-row
format because user variables do not have a display width.
When processing an input line, LOAD
DATA splits it into fields and uses the values according
to the column/variable list and the SET clause,
if they are present. Then the resulting row is inserted into the
table. If there are BEFORE INSERT or
AFTER INSERT triggers for the table, they are
activated before or after inserting the row, respectively.
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 differently than if the field
value is missing:
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 allow 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.
BIT values cannot be loaded using
binary notation (for example, b'011010' ). To
work around this, specify the values as regular integers and use
the SET clause to convert them so that MySQL
performs a numeric type conversion and loads them into the
BIT column properly:
shell> cat /tmp/bit_test.txt
2
127
shell> mysql test
mysql> LOAD DATA INFILE '/tmp/bit_test.txt'
-> INTO TABLE bit_test (@var1) SET b= CAST(@var1 AS UNSIGNED);
Query OK, 2 rows affected (0.00 sec)
Records: 2 Deleted: 0 Skipped: 0 Warnings: 0
mysql> SELECT BIN(b+0) FROM bit_test;
+----------+
| bin(b+0) |
+----------+
| 10 |
| 1111111 |
+----------+
2 rows in set (0.00 sec)
When the LOAD DATA
INFILE statement finishes, it returns an information
string in the following format:
Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
If you are using the C API, you can get information about the
statement by calling the
mysql_info() function. See
Section 21.9.3.35, “mysql_info() ”.
Warnings occur under the same circumstances as when values are
inserted via the INSERT statement
(see Section 12.2.5, “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.
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.5.5.42, “SHOW WARNINGS Syntax”.
REPLACE [LOW_PRIORITY | DELAYED]
[INTO] tbl_name [(col_name ,...)]
{VALUES | VALUE} ({expr | DEFAULT},...),(...),...
Or:
REPLACE [LOW_PRIORITY | DELAYED]
[INTO] tbl_name
SET col_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.5, “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.5.3, “INSERT ... ON
DUPLICATE KEY UPDATE Syntax”.
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
col_name =
col_name + 1 , the reference
to the column name on the right hand side is treated as
DEFAULT(col_name ) ,
so the assignment is equivalent to 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
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 ...]
[FROM table_references
[WHERE where_condition ]
[GROUP BY {col_name | expr | position }
[ASC | DESC], ... [WITH ROLLUP]]
[HAVING where_condition ]
[ORDER BY {col_name | expr | position }
[ASC | DESC], ...]
[LIMIT {[offset ,] row_count | row_count OFFSET offset }]
[PROCEDURE procedure_name (argument_list )]
[INTO OUTFILE 'file_name '
[CHARACTER SET charset_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, and can include
UNION statements and subqueries.
See Section 12.2.8.3, “UNION Syntax”, and Section 12.2.9, “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.8.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 clause, you can use any of the
functions and operators that MySQL supports, except for
aggregate (summary) functions. See
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
You are allowed 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 ...
tbl_name .* can
be used as a qualified shorthand to select all columns from
the named table:
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
tbl_name .*
reference
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
alias_name . The alias is
used as the expression's column name and can be used in
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 . 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 allowable 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
table_references 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.8.1, “JOIN Syntax”. For
each table specified, you can optionally specify an alias.
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.8.2, “Index Hint Syntax”.
You can use SET
max_seeks_for_key=value
as an alternative way to force MySQL to prefer key scans
instead of table scans. See
Section 5.1.4, “Server System Variables”.
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
tbl_name AS
alias_name or
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 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 allow
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.12, “Functions and Modifiers for Use with GROUP BY Clauses”.
GROUP BY allows a WITH
ROLLUP modifier. See
Section 11.12.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 .)
The SQL standard requires that HAVING must
reference only columns in the GROUP BY
clause or columns used in aggregate functions. However, MySQL
supports an extension to this behavior, and allows
HAVING to refer to columns in the
SELECT list and columns in
outer subqueries as well.
If the HAVING clause refers to a column
that is ambiguous, a warning occurs. In the following
statement, col2 is ambiguous because it is
used as both an alias and a column name:
SELECT COUNT(col1) AS col2 FROM t GROUP BY col2 HAVING col2 = 2;
Preference is given to standard SQL behavior, so if a
HAVING column name is used both in
GROUP BY and as an aliased column in the
output column list, preference is given to the column in the
GROUP BY column.
Do not use HAVING for items that should be
in the WHERE clause. For example, do not
write the following:
SELECT col_name FROM tbl_name HAVING col_name > 0;
Write this instead:
SELECT col_name FROM tbl_name WHERE col_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;
(This did not work in some older versions of MySQL.)
MySQL allows 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 allows 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 .
MySQL resolves unqualified column or alias references in
ORDER BY clauses by searching in the
select_expr values, then in the
columns of the tables in the FROM clause.
For GROUP BY or HAVING
clauses, it searches the FROM clause before
searching in the select_expr
values. (For GROUP BY and
HAVING , this differs from the pre-MySQL 5.0
behavior that used the same rules as for ORDER
BY .)
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
row_count is equivalent
to LIMIT 0,
row_count .
For prepared statements, you can use placeholders. 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 row_count OFFSET
offset syntax.
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 22.4.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
'file_name ' form of
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. As of MySQL 5.1.6, the
character_set_filesystem
system variable controls the interpretation of the file name.
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
client host other than the server host, you cannot use
SELECT ... INTO
OUTFILE . In that case, you should instead use a
command such as mysql -e "SELECT ..." >
file_name to generate the
file on the client host.
SELECT ... INTO
OUTFILE is the complement of
LOAD DATA
INFILE . Column values are written converted to the
character set specified in the CHARACTER
SET clause, which is available as of MySQL 5.1.38.
Prior to 5.1.38 or if no such clause is present, 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.6, “LOAD DATA INFILE
Syntax”,
for information about the FIELDS and
LINES clauses, including their default
values and allowable 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.
Note
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.
If the secure_file_priv
system variable is set to a nonempty directory name, the
file to be written must be located in that directory.
The INTO clause can name a list of one or
more variables, which can be user-defined variables, or
parameters or local variables within a stored function or
procedure body (see Section 12.8.3.3, “SELECT ... INTO
Statement”).
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, a
warning with error code 1329 occurs (No
data ), and the variable values remain unchanged. If
the query returns multiple rows, error 1172 occurs
(Result consisted of more than one row ). If
it is possible that the statement may retrieve multiple rows,
you can use LIMIT 1 to limit the result set
to a single row.
In the context of such statements that occur as part of events
executed by the Event Scheduler, diagnostics messages (not
only errors, but also warnings) are written to the error log,
and, on Windows, to the application event log. For additional
information, see Section 19.4.5, “Event Scheduler Status”.
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
allows other transactions to read the examined rows but not to
update or delete them. See
Section 13.6.8.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.
The ALL , DISTINCT , and
DISTINCTROW options specify whether duplicate
rows should be returned. If none of these options are given, the
default is ALL (all matching rows are
returned). DISTINCT and
DISTINCTROW are synonyms and specify removal of
duplicate rows from the result set.
HIGH_PRIORITY ,
STRAIGHT_JOIN , and options beginning with
SQL_ are MySQL extensions to standard SQL.
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.8.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 can be used with
GROUP BY or DISTINCT to
tell the optimizer that the result set has many rows. In this
case, 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.
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_SMALL_RESULT can be used with
GROUP BY or DISTINCT to
tell the optimizer that the result set is small. In this case,
MySQL uses fast temporary tables to store the resulting table
instead of using sorting. This should not normally be needed.
SQL_CALC_FOUND_ROWS 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.11.3, “Information Functions”.
The SQL_CACHE and
SQL_NO_CACHE options affect caching of
query results in the query cache (see
Section 7.5.5, “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 , subqueries, or views,
the following rules apply:
SQL_NO_CACHE applies if it appears in
any SELECT in the query.
For a cacheable query, SQL_CACHE
applies if it appears in the first
SELECT of the query, or in
the first SELECT of a view
referred to by the query.
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 :
table_factor
| join_table
table_factor :
tbl_name [[AS] alias ] [index_hint_list ]
| table_subquery [AS] alias
| ( table_references )
| { OJ table_reference LEFT OUTER JOIN table_reference
ON conditional_expr }
join_table :
table_reference [INNER | CROSS] JOIN table_factor [join_condition ]
| table_reference STRAIGHT_JOIN table_factor
| table_reference STRAIGHT_JOIN table_factor ON conditional_expr
| table_reference {LEFT|RIGHT} [OUTER] JOIN table_reference join_condition
| table_reference NATURAL [{LEFT|RIGHT} [OUTER]] JOIN table_factor
join_condition :
ON conditional_expr
| USING (column_list )
index_hint_list :
index_hint [, index_hint ] ...
index_hint :
USE {INDEX|KEY}
[{FOR {JOIN|ORDER BY|GROUP BY}] ([index_list ])
| IGNORE {INDEX|KEY}
[{FOR {JOIN|ORDER BY|GROUP BY}] (index_list )
| FORCE {INDEX|KEY}
[{FOR {JOIN|ORDER BY|GROUP BY}] (index_list )
index_list :
index_name [, index_name ] ...
A table reference is also known as a join expression.
The syntax of table_factor is
extended in comparison with the SQL Standard. The latter accepts
only table_reference , not a list of
them inside a pair of parentheses.
This is a conservative extension if we consider each comma in a
list of table_reference items as
equivalent to an inner join. For example:
SELECT * FROM t1 LEFT JOIN (t2, t3, t4)
ON (t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c)
is equivalent to:
SELECT * FROM t1 LEFT JOIN (t2 CROSS JOIN t3 CROSS JOIN t4)
ON (t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c)
In MySQL, CROSS JOIN is a syntactic
equivalent to INNER JOIN (they can replace
each other). In standard SQL, they are not equivalent.
INNER JOIN is used with an
ON clause, CROSS JOIN is
used otherwise.
In general, parentheses can be ignored in join expressions
containing only inner join operations. MySQL also supports
nested joins (see Section 7.2.11, “Nested Join Optimization”).
Index hints can be specified to affect how the MySQL optimizer
makes use of indexes. For more information, see
Section 12.2.8.2, “Index Hint Syntax”.
The following list describes general factors to take into
account when writing joins.
A table reference can be aliased using
tbl_name AS
alias_name or
tbl_name alias_name :
SELECT t1.name, t2.salary
FROM employee AS t1 INNER JOIN info AS t2 ON t1.name = t2.name;
SELECT t1.name, t2.salary
FROM employee t1 INNER JOIN info t2 ON 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.9.8, “Subqueries in the FROM clause”.
SELECT * FROM (SELECT 1, 2, 3) AS t1;
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).
However, the precedence of the comma operator is less than
of INNER JOIN , CROSS
JOIN , LEFT JOIN , and so on. If
you mix comma joins with the other join types when there is
a join condition, an error of the form Unknown
column 'col_name ' in 'on
clause' may occur. Information about dealing with
this problem is given later in this section.
The conditional_expr used with
ON is any conditional expression of the
form that can be used in a WHERE clause.
Generally, you should use the ON clause
for conditions that specify how to join tables, and the
WHERE clause to restrict which rows you
want in the result set.
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.2.9, “LEFT JOIN and RIGHT JOIN
Optimization”.
The
USING(column_list )
clause names a list of columns that must exist in both
tables. If tables a and
b both contain columns
c1 , c2 , and
c3 , the following join compares
corresponding columns from the two tables:
a LEFT JOIN b USING (c1,c2,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.
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 join syntax description 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;
As of MySQL 5.1.24, you can use other types of joins within
{ OJ ... } , such as INNER
JOIN or RIGHT OUTER JOIN . This
helps with compatibility with some third-party applications,
but is not official ODBC syntax.
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;
SELECT * FROM table1 INNER JOIN table2 ON 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;
Join Processing Changes in MySQL
5.0.12
Note
Natural joins and joins with USING ,
including outer join variants, are processed according to the
SQL:2003 standard. The goal was to align the syntax and
semantics of MySQL with respect to NATURAL
JOIN and JOIN ... USING according
to SQL:2003. However, these changes in join processing can
result in different output columns for some joins. Also, some
queries that appeared to work correctly in older versions
(prior to 5.0.12) must be rewritten to comply with the
standard.
These changes have five main aspects:
The way that MySQL determines the result columns of
NATURAL or USING join
operations (and thus the result of the entire
FROM clause).
Expansion of SELECT * and SELECT
tbl_name .* into a list
of selected columns.
Resolution of column names in NATURAL or
USING joins.
Transformation of NATURAL or
USING joins into JOIN ...
ON .
Resolution of column names in the ON
condition of a JOIN ... ON .
The following list provides more detail about several effects of
current join processing versus join processing in older
versions. The term “previously” means “prior
to MySQL 5.0.12.”
The columns of a NATURAL join or a
USING join may be different from
previously. Specifically, redundant output columns no longer
appear, and the order of columns for SELECT
* expansion may be different from before.
Consider this set of statements:
CREATE TABLE t1 (i INT, j INT);
CREATE TABLE t2 (k INT, j INT);
INSERT INTO t1 VALUES(1,1);
INSERT INTO t2 VALUES(1,1);
SELECT * FROM t1 NATURAL JOIN t2;
SELECT * FROM t1 JOIN t2 USING (j);
Previously, the statements produced this output:
+------+------+------+------+
| i | j | k | j |
+------+------+------+------+
| 1 | 1 | 1 | 1 |
+------+------+------+------+
+------+------+------+------+
| i | j | k | j |
+------+------+------+------+
| 1 | 1 | 1 | 1 |
+------+------+------+------+
In the first SELECT
statement, column j appears in both
tables and thus becomes a join column, so, according to
standard SQL, it should appear only once in the output, not
twice. Similarly, in the second SELECT statement, column
j is named in the
USING clause and should appear only once
in the output, not twice. But in both cases, the redundant
column is not eliminated. Also, the order of the columns is
not correct according to standard SQL.
Now the statements produce this output:
+------+------+------+
| j | i | k |
+------+------+------+
| 1 | 1 | 1 |
+------+------+------+
+------+------+------+
| j | i | k |
+------+------+------+
| 1 | 1 | 1 |
+------+------+------+
The redundant column is eliminated and the column order is
correct according to standard SQL:
First, coalesced common columns of the two joined
tables, in the order in which they occur in the first
table
Second, columns unique to the first table, in order in
which they occur in that table
Third, columns unique to the second table, in order in
which they occur in that table
The single result column that replaces two common columns is
defined via the coalesce operation. That is, for two
t1.a and t2.a the
resulting single join column a is defined
as a = COALESCE(t1.a, t2.a) , where:
COALESCE(x, y) = (CASE WHEN V1 IS NOT NULL THEN V1 ELSE V2 END)
If the join operation is any other join, the result columns
of the join consists of the concatenation of all columns of
the joined tables. This is the same as previously.
A consequence of the definition of coalesced columns is
that, for outer joins, the coalesced column contains the
value of the non-NULL column if one of
the two columns is always NULL . If
neither or both columns are NULL , both
common columns have the same value, so it doesn't matter
which one is chosen as the value of the coalesced column. A
simple way to interpret this is to consider that a coalesced
column of an outer join is represented by the common column
of the inner table of a JOIN . Suppose
that the tables t1(a,b) and
t2(a,c) have the following contents:
t1 t2
---- ----
1 x 2 z
2 y 3 w
Then:
mysql> SELECT * FROM t1 NATURAL LEFT JOIN t2;
+------+------+------+
| a | b | c |
+------+------+------+
| 1 | x | NULL |
| 2 | y | z |
+------+------+------+
Here column a contains the values of
t1.a .
mysql> SELECT * FROM t1 NATURAL RIGHT JOIN t2;
+------+------+------+
| a | c | b |
+------+------+------+
| 2 | z | y |
| 3 | w | NULL |
+------+------+------+
Here column a contains the values of
t2.a .
Compare these results to the otherwise equivalent queries
with JOIN ... ON :
mysql> SELECT * FROM t1 LEFT JOIN t2 ON (t1.a = t2.a);
+------+------+------+------+
| a | b | a | c |
+------+------+------+------+
| 1 | x | NULL | NULL |
| 2 | y | 2 | z |
+------+------+------+------+
mysql> SELECT * FROM t1 RIGHT JOIN t2 ON (t1.a = t2.a);
+------+------+------+------+
| a | b | a | c |
+------+------+------+------+
| 2 | y | 2 | z |
| NULL | NULL | 3 | w |
+------+------+------+------+
Previously, a USING clause could be
rewritten as an ON clause that compares
corresponding columns. For example, the following two
clauses were semantically identical:
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
Now the two clauses no longer are quite the same:
With respect to determining which rows satisfy the join
condition, both joins remain semantically identical.
With respect to determining which columns to display for
SELECT * expansion, the two joins are
not semantically identical. The USING
join selects the coalesced value of corresponding
columns, whereas the ON join selects
all columns from all tables. For the preceding
USING join, SELECT
* selects these values:
COALESCE(a.c1,b.c1), COALESCE(a.c2,b.c2), COALESCE(a.c3,b.c3)
For the ON join, SELECT
* selects these values:
a.c1, a.c2, a.c3, b.c1, b.c2, b.c3
With an inner join,
COALESCE(a.c1,b.c1) is
the same as either a.c1 or
b.c1 because both columns will have
the same value. With an outer join (such as
LEFT JOIN ), one of the two columns
can be NULL . That column will be
omitted from the result.
The evaluation of multi-way natural joins differs in a very
important way that affects the result of
NATURAL or USING joins
and that can require query rewriting. Suppose that you have
three tables t1(a,b) ,
t2(c,b) , and t3(a,c)
that each have one row: t1(1,2) ,
t2(10,2) , and
t3(7,10) . Suppose also that you have this
NATURAL JOIN on the three tables:
SELECT ... FROM t1 NATURAL JOIN t2 NATURAL JOIN t3;
Previously, the left operand of the second join was
considered to be t2 , whereas it should be
the nested join (t1 NATURAL JOIN t2) . As
a result, the columns of t3 are checked
for common columns only in t2 , and, if
t3 has common columns with
t1 , these columns are not used as
equi-join columns. Thus, previously, the preceding query was
transformed to the following equi-join:
SELECT ... FROM t1, t2, t3
WHERE t1.b = t2.b AND t2.c = t3.c;
That join is missing one more equi-join predicate
(t1.a = t3.a) . As a result, it produces
one row, not the empty result that it should. The correct
equivalent query is this:
SELECT ... FROM t1, t2, t3
WHERE t1.b = t2.b AND t2.c = t3.c AND t1.a = t3.a;
If you require the same query result in current versions of
MySQL as in older versions, rewrite the natural join as the
first equi-join.
Previously, the comma operator (, ) and
JOIN both had the same precedence, so the
join expression t1, t2 JOIN t3 was
interpreted as ((t1, t2) JOIN t3) . Now
JOIN has higher precedence, so the
expression is interpreted as (t1, (t2 JOIN
t3)) . This change affects statements that use an
ON clause, because that clause can refer
only to columns in the operands of the join, and the change
in precedence changes interpretation of what those operands
are.
Example:
CREATE TABLE t1 (i1 INT, j1 INT);
CREATE TABLE t2 (i2 INT, j2 INT);
CREATE TABLE t3 (i3 INT, j3 INT);
INSERT INTO t1 VALUES(1,1);
INSERT INTO t2 VALUES(1,1);
INSERT INTO t3 VALUES(1,1);
SELECT * FROM t1, t2 JOIN t3 ON (t1.i1 = t3.i3);
Previously, the SELECT was
legal due to the implicit grouping of
t1,t2 as (t1,t2) . Now
the JOIN takes precedence, so the
operands for the ON clause are
t2 and t3 . Because
t1.i1 is not a column in either of the
operands, the result is an Unknown column 't1.i1'
in 'on clause' error. To allow the join to be
processed, group the first two tables explicitly with
parentheses so that the operands for the
ON clause are (t1,t2)
and t3 :
SELECT * FROM (t1, t2) JOIN t3 ON (t1.i1 = t3.i3);
Alternatively, avoid the use of the comma operator and use
JOIN instead:
SELECT * FROM t1 JOIN t2 JOIN t3 ON (t1.i1 = t3.i3);
This change also applies to statements that mix the comma
operator with INNER JOIN , CROSS
JOIN , LEFT JOIN , and
RIGHT JOIN , all of which now have higher
precedence than the comma operator.
Previously, the ON clause could refer to
columns in tables named to its right. Now an
ON clause can refer only to its operands.
Example:
CREATE TABLE t1 (i1 INT);
CREATE TABLE t2 (i2 INT);
CREATE TABLE t3 (i3 INT);
SELECT * FROM t1 JOIN t2 ON (i1 = i3) JOIN t3;
Previously, the SELECT
statement was legal. Now the statement fails with an
Unknown column 'i3' in 'on clause' error
because i3 is a column in
t3 , which is not an operand of the
ON clause. The statement should be
rewritten as follows:
SELECT * FROM t1 JOIN t2 JOIN t3 ON (i1 = i3);
Resolution of column names in NATURAL or
USING joins is different than previously.
For column names that are outside the
FROM clause, MySQL now handles a superset
of the queries compared to previously. That is, in cases
when MySQL formerly issued an error that some column is
ambiguous, the query now is handled correctly. This is due
to the fact that MySQL now treats the common columns of
NATURAL or USING joins
as a single column, so when a query refers to such columns,
the query compiler does not consider them as ambiguous.
Example:
SELECT * FROM t1 NATURAL JOIN t2 WHERE b > 1;
Previously, this query would produce an error ERROR
1052 (23000): Column 'b' in where clause is
ambiguous . Now the query produces the correct
result:
+------+------+------+
| b | c | y |
+------+------+------+
| 4 | 2 | 3 |
+------+------+------+
One extension of MySQL compared to the SQL:2003 standard is
that MySQL allows you to qualify the common (coalesced)
columns of NATURAL or
USING joins (just as previously), while
the standard disallows that.
12.2.8.2. Index Hint Syntax
You can provide hints to give the optimizer information about
how to choose indexes during query processing.
Section 12.2.8.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_list ]
index_hint_list :
index_hint [, index_hint ] ...
index_hint :
USE {INDEX|KEY}
[{FOR {JOIN|ORDER BY|GROUP BY}] ([index_list ])
| IGNORE {INDEX|KEY}
[{FOR {JOIN|ORDER BY|GROUP BY}] (index_list )
| FORCE {INDEX|KEY}
[{FOR {JOIN|ORDER BY|GROUP BY}] (index_list )
index_list :
index_name [, index_name ] ...
By specifying USE INDEX
(index_list ) , you can tell
MySQL to use only one of the named indexes to find rows in the
table. The alternative syntax IGNORE INDEX
(index_list ) can be used to
tell MySQL to not use some particular index or indexes. These
hints are useful if EXPLAIN shows
that MySQL is using the wrong index from the list of possible
indexes.
You can also use FORCE INDEX , which acts like
USE INDEX
(index_list ) 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.
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.
Prior to MySQL 5.1.17, 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 process joins.
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;
As of MySQL 5.1.17, the syntax for index hints is extended in
the following ways:
It is syntactically valid to specify an empty
index_list for USE
INDEX , which means “use no indexes.”
Specifying an empty index_list
for FORCE INDEX or IGNORE
INDEX is a syntax error.
You can specify the scope of a index hint by adding a
FOR clause to the hint. This provides
more fine-grained control over the optimizer's selection of
an execution plan for various phases of query processing. To
affect only the indexes used when MySQL decides how to find
rows in the table and how to process joins, use FOR
JOIN . To influence index usage for sorting or
grouping rows, use FOR ORDER BY or
FOR GROUP BY . (However, if there is a
covering index for the table and it is used to access the
table, the optimizer will ignore IGNORE INDEX FOR
{ORDER BY|GROUP BY} hints that disable that
index.)
You can specify multiple index hints:
SELECT * FROM t1 USE INDEX (i1) IGNORE INDEX FOR ORDER BY (i2) ORDER BY a;
It is not a error to name the same index in several hints
(even within the same hint):
SELECT * FROM t1 USE INDEX (i1) USE INDEX (i1,i1);
However, it is an error to mix USE INDEX
and FORCE INDEX for the same table:
SELECT * FROM t1 USE INDEX FOR JOIN (i1) FORCE INDEX FOR JOIN (i2);
The default scope of index hints also is changed as of MySQL
5.1.17. Formerly, index hints applied only to how indexes are
used for retrieval of records and not during resolution of
ORDER BY or GROUP BY
clauses. As of 5.1.17, if you specify no FOR
clause for an index hint, the hint by default applies to all
parts of the statement. For example, this hint:
IGNORE INDEX (i1)
is equivalent to this combination of hints:
IGNORE INDEX FOR JOIN (i1)
IGNORE INDEX FOR ORDER BY (i1)
IGNORE INDEX FOR GROUP BY (i1)
To cause the server to use the older behavior for hint scope
when no FOR clause is present (so that hints
apply only to row retrieval), enable the
old system variable at server
startup. Take care about enabling this variable in a replication
setup. With statement-based binary logging, having different
modes for the master and slaves might lead to replication
errors.
When index hints are processed, they are collected in a single
list by type (USE ,
FORCE , IGNORE ) and by
scope (FOR JOIN , FOR ORDER
BY , FOR GROUP BY ). For example:
SELECT * FROM t1
USE INDEX () IGNORE INDEX (i2) USE INDEX (i1) USE INDEX (i2);
is equivalent to:
SELECT * FROM t1
USE INDEX (i1,i2) IGNORE INDEX (i2);
The index hints then are applied for each scope in the following
order:
{USE|FORCE} INDEX is applied if present.
(If not, the optimizer-determined set of indexes is used.)
IGNORE INDEX is applied over the result
of the previous step. For example, the following two queries
are equivalent:
SELECT * FROM t1 USE INDEX (i1) IGNORE INDEX (i2) USE INDEX (i2);
SELECT * FROM t1 USE INDEX (i1);
For FULLTEXT searches, index hints do not
work before MySQL 5.1.31. As of 5.1.31, index hints work as
follows:
For natural language mode searches, index hints are silently
ignored. For example, IGNORE INDEX(i) is
ignored with no warning and the index is still used.
For boolean mode searches, index hints with FOR
ORDER BY or FOR GROUP BY are
silently ignored. Index hints with FOR
JOIN or no FOR modifier are
honored. In contrast to how hints apply for
non-FULLTEXT searches, the hint is used
for all phases of query execution (finding rows and
retrieval, grouping, and ordering). This is true even if the
hint is given for a non-FULLTEXT index.
For example, the following two queries are equivalent:
SELECT * FROM t
USE INDEX (index1)
IGNORE INDEX (index1) FOR ORDER BY
IGNORE INDEX (index1) FOR GROUP BY
WHERE ... IN BOOLEAN MODE ... ;
SELECT * FROM t
USE INDEX (index1)
WHERE ... IN BOOLEAN MODE ... ;
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.
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.)
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 |
+---------------+
(In some earlier versions of MySQL, 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.)
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 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.
You can mix UNION
ALL and UNION
DISTINCT in the same query. 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.
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.
They are, in many people's opinion, 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 any 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 ,
UPDATE , and (because subqueries can
be used in the SET clause)
LOAD DATA
INFILE .
A more comprehensive discussion of restrictions on subquery use,
including performance issues for certain forms of subquery syntax,
is given in Section D.3, “Restrictions on Subqueries”.
12.2.9.1. The Subquery as Scalar Operand
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 whether 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 . In fact, almost all subqueries can be
NULL . If the table used in the example were
empty, the value of the subquery would be
NULL .
There are a few contexts in which a scalar subquery cannot be
used. If a statement allows 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;
12.2.9.2. Comparisons Using Subqueries
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:
... 'a' = (SELECT column1 FROM t1)
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.9.5, “Row Subqueries”.
12.2.9.3. Subqueries with ANY , IN , and
SOME
Syntax:
operand comparison_operator ANY (subquery )
operand IN (subquery )
operand comparison_operator SOME (subquery )
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 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.2.3, “Comparison Functions and Operators”.
NOT IN is not an alias for <>
ANY , but for <> ALL . See
Section 12.2.9.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's ears, 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.
12.2.9.4. Subqueries with ALL
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, if table t2 is empty, the result is
TRUE . So, the following statement is
TRUE when table t2 is
empty:
SELECT * FROM t1 WHERE 1 > ALL (SELECT s1 FROM t2);
But this statement is NULL when table
t2 is empty:
SELECT * FROM t1 WHERE 1 > (SELECT s1 FROM t2);
In addition, the following statement 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 subquery code, 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 (1,2) = (SELECT column1, column2 FROM t2);
SELECT * FROM t1 WHERE ROW(1,2) = (SELECT column1, column2 FROM t2);
The queries here are both TRUE if table
t2 has a row where column1 =
1 and column2 = 2 .
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.
In MySQL 5.1, 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; a row constructor cannot be used
with a subquery that does not return at least two columns. Thus,
a query such as SELECT * FROM t1 WHERE ROW(1) = (SELECT
column1 FROM t2) fails with a syntax error.
Row constructors are legal in other contexts. For example, the
following two statements are semantically equivalent:
SELECT * FROM t1 WHERE (column1,column2) = (1,1);
SELECT * FROM t1 WHERE column1 = 1 AND column2 = 1;
Prior to MySQL 5.1.12, only the second of the preceding two
expressions could be optimized. (Bug#16081)
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);
12.2.9.6. EXISTS and NOT EXISTS
If a subquery returns any rows at all, EXISTS
subquery is
TRUE , and NOT EXISTS
subquery is
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 ?”
12.2.9.7. Correlated Subqueries
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 subquery 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 (SELECT key_val FROM tbl_name WHERE correlated_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.
12.2.9.8. Subqueries in the FROM clause
Subqueries are legal in a SELECT
statement's FROM clause. The actual syntax
is:
SELECT ... FROM (subquery ) [AS] name ...
The [AS] name
clause is mandatory, because every table in a
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,
unless used within the ON clause of a
JOIN operation.
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, then 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:
EXPLAIN SELECT * FROM t1 AS a1, (SELECT BENCHMARK(1000000, MD5(NOW())));
This is because the BENCHMARK()
function is executed once for each row in t1 .
12.2.9.9. Subquery Errors
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 does not yet support
'LIMIT & IN/ALL/ANY/SOME subquery'"
This means that statements of the following form do not work
yet:
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 comparison. In other contexts, the subquery must
be a scalar operand. See Section 12.2.9.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 returns
more than one row. 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:
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's
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.
12.2.9.10. Optimizing Subqueries
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 that do not
support subqueries. However, in some cases, converting a
subquery to a join may improve performance. See
Section 12.2.9.11, “Rewriting Subqueries as Joins”.
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 (table containing
(1,2) ) rather than 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.11.3, “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 (SELECT indexed_column FROM single_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)
See also the MySQL Internals Manual chapter
How
MySQL Transforms Subqueries.
12.2.9.11. Rewriting Subqueries as Joins
Although MySQL 5.1 supports subqueries (see
Section 12.2.9, “Subquery Syntax”), it is still true that there are
sometimes other ways to test membership in a set of values. It
is also true that on some occasions, it is not only possible to
rewrite a query without a subquery, but it can be more efficient
to make use of some of these techniques rather than to use
subqueries. One of these is the IN()
construct:
For example, this query:
SELECT * FROM t1 WHERE id IN (SELECT id FROM t2);
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.
MySQL Server 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. See Section 12.2.2, “DELETE Syntax”, and
Section 12.2.11, “UPDATE Syntax”.
12.2.10. TRUNCATE TABLE SyntaxTRUNCATE [TABLE] tbl_name
TRUNCATE TABLE empties a table
completely. It requires the DROP
privilege as of MySQL 5.1.16. (Before 5.1.16, it requires the
DELETE privilege.
Logically, TRUNCATE TABLE is
equivalent to a DELETE statement
that deletes all rows, but there are practical differences under
some circumstances.
For an InnoDB table, InnoDB
processes TRUNCATE TABLE by
deleting rows one by one if there are any FOREIGN
KEY constraints that reference the table. If there are
no FOREIGN KEY constraints,
InnoDB performs fast truncation by dropping the
original table and creating an empty one with the same definition,
which is much faster than deleting rows one by one. The
AUTO_INCREMENT counter is reset to zero by
TRUNCATE TABLE , regardless of
whether there is a FOREIGN KEY constraint.
In the case that FOREIGN KEY constraints
reference the table, InnoDB deletes rows one by
one and processes the constraints on each one. If the
FOREIGN KEY constraint specifies
DELETE CASCADE , rows from the child
(referenced) table are deleted, and the truncated table becomes
empty. If the FOREIGN KEY constraint does
not specify CASCADE , the
TRUNCATE TABLE statement deletes
rows one by one and stops if it encounters a parent row that is
referenced by the child, returning this error:
ERROR 1451 (23000): Cannot delete or update a parent row: a foreign
key constraint fails (`test`.`child`, CONSTRAINT `child_ibfk_1`
FOREIGN KEY (`parent_id`) REFERENCES `parent` (`id`))
This is the same as a DELETE
statement with no WHERE clause.
The count of rows affected by TRUNCATE
TABLE is accurate only when it is mapped to a
DELETE statement.
For other storage engines, TRUNCATE
TABLE differs from DELETE
in the following ways in MySQL 5.1:
Truncate operations drop and re-create the table, which is
much faster than deleting rows one by one, particularly for
large tables.
Truncate operations cause an implicit commit.
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
tbl_name .frm
is valid, the table can be re-created as an empty table with
TRUNCATE 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.
When used with partitioned tables,
TRUNCATE TABLE preserves the
partitioning; that is, the data and index files are dropped
and re-created, while the partition definitions
(.par ) file is unaffected.
Since truncation of a table does not make any use of
DELETE , the
TRUNCATE TABLE statement does
not invoke ON DELETE triggers.
As of MySQL 5.1.39, TRUNCATE TABLE
for a table closes all handlers for the table that were opened
with HANDLER
OPEN .
Beginning with MySQL 5.1.32, TRUNCATE
TABLE is treated for purposes of binary logging and
replication as DROP TABLE followed
by CREATE TABLE — that is, as
DDL rather than DML. This is due to the fact that, when using
InnoDB and other transactional
storage engines where the transaction isolation level does not
allow for statement-based logging (READ
COMMITTED or READ UNCOMMITTED ), the
statement was not logged and replicated when using
STATEMENT or MIXED logging
mode. (Bug#36763) However, it is still applied on replication
slaves using InnoDB in the manner
described previously.
Single-table syntax:
UPDATE [LOW_PRIORITY] [IGNORE] table_reference
SET col_name1 ={expr1 |DEFAULT} [, col_name2 ={expr2 |DEFAULT}] ...
[WHERE where_condition ]
[ORDER BY ...]
[LIMIT row_count ]
Multiple-table syntax:
UPDATE [LOW_PRIORITY] [IGNORE] table_references
SET col_name1 ={expr1 |DEFAULT} [, col_name2 ={expr2 |DEFAULT}] ...
[WHERE where_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. In this case, ORDER BY and
LIMIT cannot be used.
where_condition is an expression that
evaluates to true for each row to be updated.
table_references and
where_condition are is specified as
described in Section 12.2.8, “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:
If you use 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 ).
If you use 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 the
age column to one more than its current value:
UPDATE persondata SET age=age+1;
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 , an error
occurs if strict SQL mode is enabled; otherwise, the column is set
to the implicit default value for the column data type and the
warning count is incremented. The implicit default value is
0 for numeric types, the empty string
('' ) for string types, and the
“zero” value for date and time types. See
Section 10.1.4, “Data Type Default Values”.
UPDATE returns the number of rows
that were actually changed. 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
row_count to restrict the
scope of the UPDATE . A
LIMIT clause 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. 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;
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.8.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 allowed in
SELECT statements, such as
LEFT JOIN .
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.6.4.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.8.2, “Index Hint Syntax”) are accepted but
ignored for UPDATE statements.
12.3. MySQL Utility 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 . These statements also display information for
views. (See Section 12.5.5.6, “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 quotes unless it contains
spaces or other special characters.
mysql> DESCRIBE City;
+------------+----------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+------------+----------+------+-----+---------+----------------+
| Id | int(11) | NO | PRI | NULL | auto_increment |
| Name | char(35) | NO | | | |
| Country | char(3) | NO | UNI | | |
| District | char(20) | YES | MUL | | |
| Population | int(11) | NO | | 0 | |
+------------+----------+------+-----+---------+----------------+
5 rows in set (0.00 sec)
The description for SHOW COLUMNS
provides more information about the output columns (see
Section 12.5.5.6, “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.17.1, “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.5.5, “SHOW Syntax”.
EXPLAIN tbl_name
Or:
EXPLAIN [EXTENDED | PARTITIONS] SELECT select_options
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:
EXPLAIN tbl_name
is synonymous with DESCRIBE
tbl_name or SHOW
COLUMNS FROM tbl_name .
For a description of the
DESCRIBE and
SHOW COLUMNS statements, see
Section 12.3.1, “DESCRIBE Syntax”, and
Section 12.5.5.6, “SHOW COLUMNS Syntax”.
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.
EXPLAIN
EXTENDED can be used to provide additional
information.
For information regarding the use of
EXPLAIN and
EXPLAIN
EXTENDED for obtaining query execution plan
information, see Section 7.2.1, “Optimizing Queries with EXPLAIN ”.
EXPLAIN
PARTITIONS is available beginning with MySQL 5.1.5.
It is useful only when examining queries involving partitioned
tables.
For details, see Section 18.3.4, “Obtaining Information About Partitions”.
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.9, “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:
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 PROCEDURE 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 |
+----------------------+-------------------------+----------------+
Before MySQL 5.1.17, if you intend to use the
HELP statement while other tables
are locked with LOCK TABLES , you
must also lock the required
mysql.help_xxx
tables. See Section 12.4.5, “LOCK TABLES and
UNLOCK
TABLES Syntax”.
USE db_name
The USE db_name
statement tells MySQL to use the
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.
12.4. MySQL Transactional and Locking Statements
MySQL supports local transactions (within a given client session)
through statements such as
SET autocommit ,
START TRANSACTION ,
COMMIT , and
ROLLBACK . See
Section 12.4.1, “START TRANSACTION ,
COMMIT , and
ROLLBACK Syntax”. XA transaction support enables MySQL to
participate in distributed transactions as well. See
Section 12.4.7, “XA Transactions”.
12.4.1. START TRANSACTION ,
COMMIT , and
ROLLBACK SyntaxSTART TRANSACTION [WITH CONSISTENT SNAPSHOT] | BEGIN [WORK]
COMMIT [WORK] [AND [NO] CHAIN] [[NO] RELEASE]
ROLLBACK [WORK] [AND [NO] CHAIN] [[NO] RELEASE]
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.
The optional WORK keyword is supported for
COMMIT and
ROLLBACK , as are
the CHAIN and RELEASE
clauses. CHAIN and RELEASE
can be used for additional control over transaction completion.
The value of the completion_type
system variable determines the default completion behavior. See
Section 5.1.4, “Server System Variables”.
Note
Within all stored programs (stored procedures and functions,
triggers, and events), the parser treats
BEGIN [WORK]
as the beginning of a
BEGIN ...
END block. Begin a transaction in this context with
START
TRANSACTION instead.
The AND CHAIN clause causes a new transaction
to begin as soon as the current one ends, and the new transaction
has the same isolation level as the just-terminated transaction.
The RELEASE clause causes the server to
disconnect the current client session after terminating the
current transaction. Including the NO keyword
suppresses CHAIN or RELEASE
completion, which can be useful if the
completion_type system variable
is set to cause chaining or release completion by default.
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:
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.
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 is standard SQL syntax and is the
recommended way to start an ad-hoc transaction.
Important
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 21, Connectors and APIs, or the documentation for your
API, for more information.
The BEGIN
statement differs from the use of the BEGIN
keyword that starts a
BEGIN ... END
compound statement. The latter does not begin a transaction. See
Section 12.8.1, “BEGIN ... END
Compound Statement Syntax”.
You can also 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.6.8.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 allows consistent
read (REPEATABLE READ or
SERIALIZABLE ).
Beginning a transaction causes any pending transaction to be
committed. See Section 12.4.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
Falcon ), 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.
Each transaction is 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.) See
Section 5.2.4, “The Binary Log”.
You can change the isolation level for transactions with
SET TRANSACTION
ISOLATION LEVEL . See Section 12.4.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, 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.
12.4.2. Statements That Cannot Be Rolled Back
Some statements cannot be rolled back. In general, these include
data definition language (DDL) statements, such as those that
create or drop databases, those that create, drop, or alter tables
or stored routines.
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.
12.4.3. Statements That Cause an Implicit Commit
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 DATABASE ... UPGRADE DATA DIRECTORY
NAME , ALTER EVENT ,
ALTER PROCEDURE ,
ALTER TABLE ,
CREATE DATABASE ,
CREATE EVENT ,
CREATE INDEX ,
CREATE PROCEDURE ,
CREATE TABLE ,
DROP DATABASE ,
DROP EVENT ,
DROP INDEX ,
DROP PROCEDURE ,
DROP TABLE ,
RENAME TABLE ,
TRUNCATE TABLE .
ALTER FUNCTION ,
CREATE FUNCTION and
DROP FUNCTION also cause an
implicit commit when used with stored functions, but not with
UDFs. (ALTER FUNCTION can only
be used with stored functions.)
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.
Beginning with MySQL 5.1.3, ALTER
VIEW , CREATE TRIGGER ,
CREATE VIEW ,
DROP TRIGGER , and
DROP VIEW cause an implicit
commit.
Beginning with MySQL 5.1.15,
CREATE TABLE ...
SELECT causes an implicit commit before and after
the statement is executed when you are creating nontemporary
tables. (No commit occurs for CREATE TEMPORARY TABLE
... SELECT .) This is to prevent an issue during
replication where the table could be created on the master
after a rollback, but fail to be recorded in the binary log,
and therefore not replicated to the slave. For more
information, see Bug#22865.
Statements that implicitly use or modify
tables in the mysql database.
Beginning with MySQL 5.1.3, CREATE
USER , DROP USER , and
RENAME USER cause an implicit
commit. Beginning with MySQL 5.1.23,
GRANT ,
REVOKE , and
SET PASSWORD statements cause
an implicit commit.
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.
Statements that cause an implicit commit cannot be used in an
XA transaction while the transaction is in an
ACTIVE state.
The BEGIN
statement differs from the use of the BEGIN
keyword that starts a
BEGIN ...
END compound statement. The latter does not cause an
implicit commit. See Section 12.8.1, “BEGIN ... END
Compound Statement Syntax”.
Data loading statements.
LOAD DATA
INFILE . Before MySQL 5.1.12,
LOAD DATA
INFILE caused an implicit commit for all storage
engines. As of MySQL 5.1.12, it causes an implicit commit only
for tables using the NDB storage
engine. For more information, see Bug#11151.
Administrative statements.
CACHE INDEX ,
LOAD INDEX INTO
CACHE . Beginning with MySQL 5.1.10,
ANALYZE TABLE ,
CHECK TABLE ,
OPTIMIZE TABLE , and
REPAIR TABLE cause an implicit
commit.
12.4.4. SAVEPOINT and
ROLLBACK TO
SAVEPOINT SyntaxSAVEPOINT identifier
ROLLBACK [WORK] TO [SAVEPOINT] identifier
RELEASE SAVEPOINT identifier
InnoDB supports the SQL statements
SAVEPOINT ,
ROLLBACK TO
SAVEPOINT ,
RELEASE
SAVEPOINT and the optional WORK
keyword for
ROLLBACK .
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 1305 (42000): SAVEPOINT identifier does not exist
The RELEASE
SAVEPOINT statement removes the named savepoint from the
set of savepoints of the current transaction. No commit or
rollback occurs. It is an error if the savepoint does not exist.
All savepoints of the current transaction are deleted if you
execute a COMMIT , or a
ROLLBACK that
does not name a savepoint.
A new savepoint level is created when a stored function is invoked
or a trigger is activated. The savepoints on previous levels
become unavailable and thus do not conflict with savepoints on the
new level. When the function or trigger terminates, any savepoints
it created are released and the previous savepoint level is
restored.
12.4.5. LOCK TABLES and
UNLOCK
TABLES SyntaxLOCK TABLES
tbl_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 explicitly acquires
table locks for the current client session. Table locks can be
acquired for base tables or views. You must have the
LOCK TABLES privilege, and the
SELECT privilege for each object to
be locked.
For view locking, LOCK TABLES adds
all base tables used in the view to the set of tables to be locked
and locks them automatically. If you lock a table explicitly with
LOCK TABLES , any tables used in
triggers are also locked implicitly, as described in
Section 12.4.5.2, “LOCK TABLES and Triggers”.
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.5.6.3, “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 allowed (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.
LOCK TABLES and
UNLOCK
TABLES cannot be used within stored programs.
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.3.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 .
[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
Tables in the INFORMATION_SCHEMA database are
an exception. They can be accessed without being locked explicitly
even while a session holds table locks obtained 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, allows 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.
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 21.9.11, “Controlling Automatic Reconnection Behavior”.
Note
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
'tbl_name ' was not locked with LOCK
TABLES . To handle this, lock the table again prior to
the second alteration. See also
Section B.5.7.1, “Problems with ALTER TABLE ”.
12.4.5.1. Interaction of Table Locking and Transactions
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.4.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.
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.5.6.3, “FLUSH Syntax”.
12.4.5.2. LOCK TABLES and Triggers
If you lock a table explicitly with LOCK
TABLES , any tables used in triggers are also locked
implicitly:
The locks are taken as the same time as those acquired
explicitly with the LOCK
TABLES statement.
The lock on a table used in a trigger depends on whether the
table is used only for reading. If so, a read lock suffices.
Otherwise, a write lock is used.
If a table is locked explicitly for reading with
LOCK TABLES , but needs to be
locked for writing because it might be modified within a
trigger, a write lock is taken rather than a read lock.
(That is, an implicit write lock needed due to the table's
appearance within a trigger causes an explicit read lock
request for the table to be converted to a write lock
request.)
Suppose that you lock two tables, t1 and
t2 , using this statement:
LOCK TABLES t1 WRITE, t2 READ;
If t1 or t2 have any
triggers, tables used within the triggers will also be locked.
Suppose that t1 has a trigger defined like
this:
CREATE TRIGGER t1_a_ins AFTER INSERT ON t1 FOR EACH ROW
BEGIN
UPDATE t4 SET count = count+1
WHERE id = NEW.id AND EXISTS (SELECT a FROM t3);
INSERT INTO t2 VALUES(1, 2);
END;
The result of the LOCK TABLES
statement is that t1 and
t2 are locked because they appear in the
statement, and t3 and t4
are locked because they are used within the trigger:
t1 is locked for writing per the
WRITE lock request.
t2 is locked for writing, even though the
request is for a READ lock. This occurs
because t2 is inserted into within the
trigger, so the READ request is converted
to a WRITE request.
t3 is locked for reading because it is
only read from within the trigger.
t4 is locked for writing because it might
be updated within the trigger.
12.4.5.3. Other Table-Locking Notes
You can safely use KILL to
terminate a session that is waiting for a table lock. See
Section 12.5.6.4, “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.
For some operations, system tables in the
mysql database must be accessed. For example,
the HELP statement requires the
contents of the server-side help tables, and
CONVERT_TZ() might need to read
the time zone tables. Before MySQL 5.1.17, to perform such
operations while a LOCK TABLES
statement is in effect, you must also lock the requisite system
tables explicitly or a lock error occurs. As of 5.1.17, the
server implicitly locks the system tables for reading as
necessary so that you need not lock them explicitly. These
tables are treated as just described:
mysql.help_category
mysql.help_keyword
mysql.help_relation
mysql.help_topic
mysql.proc
mysql.time_zone
mysql.time_zone_leap_second
mysql.time_zone_name
mysql.time_zone_transition
mysql.time_zone_transition_type
If you want to explicitly place a WRITE lock
on any of those tables with a LOCK
TABLES statement, the table must be the only one
locked; no other table can be locked with the same statement.
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
value =value +new_value )
or the LAST_INSERT_ID() function.
See Section 1.8.5.2, “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.11.4, “Miscellaneous Functions”.
See Section 7.3.1, “Internal Locking Methods”, for more information on
locking policy.
12.4.6. SET TRANSACTION SyntaxSET [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=level
option to mysqld on the command line or in an
option file. Values of level for this
option use dashes rather than spaces, so the allowable 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;
InnoDB supports each of the translation
isolation levels described here using different locking
strategies. 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.6.8.4, “InnoDB Record, Gap, and Next-Key Locks”, and
Section 13.6.8.6, “Locks Set by Different SQL Statements in InnoDB ”.
The following list describes how MySQL supports the different
transaction levels:
READ UNCOMMITTED
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 .
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.6.8.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 allows 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.
Note
In MySQL 5.1, if the
READ COMMITTED isolation
level is used or the
innodb_locks_unsafe_for_binlog
system variable is enabled, there is no
InnoDB gap locking except for foreign-key
constraint checking and duplicate-key checking. Also, record
locks for nonmatching rows are released after MySQL has
evaluated the WHERE condition.
As of MySQL 5.1, if you use READ
COMMITTED or enable
innodb_locks_unsafe_for_binlog ,
you must use row-based binary logging.
REPEATABLE READ
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.6.8.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.
SERIALIZABLE
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.)
Support for XA transactions is available for the
InnoDB storage engine. The MySQL XA
implementation is based on the X/Open CAE document
Distributed Transaction Processing: The XA
Specification. This document is published by The Open
Group and available at
http://www.opengroup.org/public/pubs/catalog/c193.htm.
Limitations of the current XA implementation are described in
Section D.5, “Restrictions on XA Transactions”.
On the client side, there are no special requirements. The XA
interface to a MySQL server consists of SQL statements that begin
with the XA keyword. MySQL client programs must
be able to send SQL statements and to understand the semantics of
the XA statement interface. They do not need be linked against a
recent client library. Older client libraries also will work.
Currently, among the MySQL Connectors, MySQL Connector/J 5.0.0
supports XA directly (by means of a class interface that handles
the Xan SQL statement interface for you).
XA supports distributed transactions; that is, the ability to
allow multiple separate transactional resources to participate in
a global transaction. Transactional resources often are RDBMSs but
may be other kinds of resources.
A global transaction involves several actions that are
transactional in themselves, but that all must either complete
successfully as a group, or all be rolled back as a group. In
essence, this extends ACID properties “up a level” so
that multiple ACID transactions can be executed in concert as
components of a global operation that also has ACID properties.
(However, for a distributed transaction, you must use the
SERIALIZABLE isolation level to
achieve ACID properties. It is enough to use
REPEATABLE READ for a
nondistributed transaction, but not for a distributed
transaction.)
Some examples of distributed transactions:
An application may act as an integration tool that combines a
messaging service with an RDBMS. The application makes sure
that transactions dealing with message sending, retrieval, and
processing that also involve a transactional database all
happen in a global transaction. You can think of this as
“transactional email.”
An application performs actions that involve different
database servers, such as a MySQL server and an Oracle server
(or multiple MySQL servers), where actions that involve
multiple servers must happen as part of a global transaction,
rather than as separate transactions local to each server.
A bank keeps account information in an RDBMS and distributes
and receives money via automated teller machines (ATMs). It is
necessary to ensure that ATM actions are correctly reflected
in the accounts, but this cannot be done with the RDBMS alone.
A global transaction manager integrates the ATM and database
resources to ensure overall consistency of financial
transactions.
Applications that use global transactions involve one or more
Resource Managers and a Transaction Manager:
A Resource Manager (RM) provides access to transactional
resources. A database server is one kind of resource manager.
It must be possible to either commit or roll back transactions
managed by the RM.
A Transaction Manager (TM) coordinates the transactions that
are part of a global transaction. It communicates with the RMs
that handle each of these transactions. The individual
transactions within a global transaction are
“branches” of the global transaction. Global
transactions and their branches are identified by a naming
scheme described later.
The MySQL implementation of XA MySQL enables a MySQL server to act
as a Resource Manager that handles XA transactions within a global
transaction. A client program that connects to the MySQL server
acts as the Transaction Manager.
To carry out a global transaction, it is necessary to know which
components are involved, and bring each component to a point when
it can be committed or rolled back. Depending on what each
component reports about its ability to succeed, they must all
commit or roll back as an atomic group. That is, either all
components must commit, or all components musts roll back. To
manage a global transaction, it is necessary to take into account
that any component or the connecting network might fail.
The process for executing a global transaction uses two-phase
commit (2PC). This takes place after the actions performed by the
branches of the global transaction have been executed.
In the first phase, all branches are prepared. That is, they
are told by the TM to get ready to commit. Typically, this
means each RM that manages a branch records the actions for
the branch in stable storage. The branches indicate whether
they are able to do this, and these results are used for the
second phase.
In the second phase, the TM tells the RMs whether to commit or
roll back. If all branches indicated when they were prepared
that they will be able to commit, all branches are told to
commit. If any branch indicated when it was prepared that it
will not be able to commit, all branches are told to roll
back.
In some cases, a global transaction might use one-phase commit
(1PC). For example, when a Transaction Manager finds that a global
transaction consists of only one transactional resource (that is,
a single branch), that resource can be told to prepare and commit
at the same time.
12.4.7.1. XA Transaction SQL Syntax
To perform XA transactions in MySQL, use the following
statements:
XA {START|BEGIN} xid [JOIN|RESUME]
XA END xid [SUSPEND [FOR MIGRATE]]
XA PREPARE xid
XA COMMIT xid [ONE PHASE]
XA ROLLBACK xid
XA RECOVER
For XA
START , the JOIN and
RESUME clauses are not supported.
For XA
END the SUSPEND [FOR MIGRATE]
clause is not supported.
Each XA statement begins with the XA keyword,
and most of them require an xid
value. An xid is an XA transaction
identifier. It indicates which transaction the statement applies
to. xid values are supplied by the
client, or generated by the MySQL server. An
xid value has from one to three
parts:
xid : gtrid [, bqual [, formatID ]]
gtrid is a global transaction
identifier, bqual is a branch
qualifier, and formatID is a number
that identifies the format used by the
gtrid and
bqual values. As indicated by the
syntax, bqual and
formatID are optional. The default
bqual value is ''
if not given. The default formatID
value is 1 if not given.
gtrid and
bqual must be string literals, each
up to 64 bytes (not characters) long.
gtrid and
bqual can be specified in several
ways. You can use a quoted string ('ab' ), hex
string (0x6162 , X'ab' ), or
bit value
(b'nnnn ' ).
formatID is an unsigned integer.
The gtrid and
bqual values are interpreted in bytes
by the MySQL server's underlying XA support routines. However,
while an SQL statement containing an XA statement is being
parsed, the server works with some specific character set. To be
safe, write gtrid and
bqual as hex strings.
xid values typically are generated by
the Transaction Manager. Values generated by one TM must be
different from values generated by other TMs. A given TM must be
able to recognize its own xid values
in a list of values returned by the
XA
RECOVER statement.
MySQL Enterprise
For expert advice on XA Distributed Transaction Support
subscribe to the MySQL Enterprise Monitor. For more
information, see
http://www.mysql.com/products/enterprise/advisors.html.
XA START xid
starts an XA transaction with the given
xid value. Each XA transaction must
have a unique xid value, so the value
must not currently be used by another XA transaction. Uniqueness
is assessed using the gtrid and
bqual values. All following XA
statements for the XA transaction must be specified using the
same xid value as that given in the
XA
START statement. If you use any of those statements
but specify an xid value that does
not correspond to some existing XA transaction, an error occurs.
One or more XA transactions can be part of the same global
transaction. All XA transactions within a given global
transaction must use the same gtrid
value in the xid value. For this
reason, gtrid values must be globally
unique so that there is no ambiguity about which global
transaction a given XA transaction is part of. The
bqual part of the
xid value must be different for each
XA transaction within a global transaction. (The requirement
that bqual values be different is a
limitation of the current MySQL XA implementation. It is not
part of the XA specification.)
The XA
RECOVER statement returns information for those XA
transactions on the MySQL server that are in the
PREPARED state. (See
Section 12.4.7.2, “XA Transaction States”.) The output includes a row for each
such XA transaction on the server, regardless of which client
started it.
XA
RECOVER output rows look like this (for an example
xid value consisting of the parts
'abc' , 'def' , and
7 ):
mysql> XA RECOVER;
+----------+--------------+--------------+--------+
| formatID | gtrid_length | bqual_length | data |
+----------+--------------+--------------+--------+
| 7 | 3 | 3 | abcdef |
+----------+--------------+--------------+--------+
The output columns have the following meanings:
formatID is the
formatID part of the transaction
xid
gtrid_length is the length in bytes of
the gtrid part of the
xid
bqual_length is the length in bytes of
the bqual part of the
xid
data is the concatenation of the
gtrid and
bqual parts of the
xid
12.4.7.2. XA Transaction States
An XA transaction progresses through the following states:
Use XA
START to start an XA transaction and put it in the
ACTIVE state.
For an ACTIVE XA transaction, issue the
SQL statements that make up the transaction, and then issue
an XA
END statement.
XA
END puts the transaction in the
IDLE state.
For an IDLE XA transaction, you can issue
either an XA
PREPARE statement or an XA COMMIT ... ONE
PHASE statement:
XA
PREPARE puts the transaction in the
PREPARED state. An
XA
RECOVER statement at this point will include
the transaction's xid value
in its output, because
XA
RECOVER lists all XA transactions that are in
the PREPARED state.
XA COMMIT ... ONE PHASE prepares and
commits the transaction. The
xid value will not be listed
by XA
RECOVER because the transaction terminates.
For a PREPARED XA transaction, you can
issue an XA
COMMIT statement to commit and terminate the
transaction, or
XA
ROLLBACK to roll back and terminate the
transaction.
Here is a simple XA transaction that inserts a row into a table
as part of a global transaction:
mysql> XA START 'xatest';
Query OK, 0 rows affected (0.00 sec)
mysql> INSERT INTO mytable (i) VALUES(10);
Query OK, 1 row affected (0.04 sec)
mysql> XA END 'xatest';
Query OK, 0 rows affected (0.00 sec)
mysql> XA PREPARE 'xatest';
Query OK, 0 rows affected (0.00 sec)
mysql> XA COMMIT 'xatest';
Query OK, 0 rows affected (0.00 sec)
Within the context of a given client connection, XA transactions
and local (non-XA) transactions are mutually exclusive. For
example, if XA
START has been issued to begin an XA transaction, a
local transaction cannot be started until the XA transaction has
been committed or rolled back. Conversely, if a local
transaction has been started with
START
TRANSACTION , no XA statements can be used until the
transaction has been committed or rolled back.
Note that if an XA transaction is in the
ACTIVE state, you cannot issue any statements
that cause an implicit commit. That would violate the XA
contract because you could not roll back the XA transaction. You
will receive the following error if you try to execute such a
statement:
ERROR 1399 (XAE07): XAER_RMFAIL: The command cannot be executed
when global transaction is in the ACTIVE state
Statements to which the preceding remark applies are listed at
Section 12.4.3, “Statements That Cause an Implicit Commit”.
12.5. Database Administration Statements12.5.1. Account Management Statements
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.
Important
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.8, “mysql_upgrade — Check Tables for MySQL Upgrade”.
MySQL Enterprise
In a production environment it is always prudent to examine any
changes to users' accounts. The MySQL Enterprise Monitor
provides notification whenever users' privileges are altered.
For more information, see
http://www.mysql.com/products/enterprise/advisors.html.
12.5.1.1. CREATE USER SyntaxCREATE USER user [IDENTIFIED BY [PASSWORD] 'password ']
[, user [IDENTIFIED BY [PASSWORD] 'password ']] ...
The CREATE USER statement creates
new MySQL accounts. To use it, you must have the global
CREATE USER privilege or the
INSERT privilege for the
mysql database. For each account,
CREATE USER creates a new row in
the mysql.user table that has no privileges.
An error occurs if the account already exists. 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.5.1.3, “GRANT Syntax”.
The account can be given a password with the optional
IDENTIFIED BY clause. The
user value and the password are given
the same way as for the GRANT
statement. In particular, to specify the password in plain text,
omit the PASSWORD keyword. To specify the
password as the hashed value as returned by the
PASSWORD() function, include the
PASSWORD keyword. See
Section 12.5.1.3, “GRANT Syntax”.
Important
This statement may be recorded in a history file such as
~/.mysql_history , which means that
plaintext passwords may be read by anyone having read access
to such files.
12.5.1.2. DROP USER SyntaxDROP USER user [, user ] ...
The DROP USER statement removes
one or more MySQL accounts. It removes privilege rows for the
account from all grant tables. To use this statement, you must
have the global CREATE USER
privilege or 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.5.1.3, “GRANT Syntax”.
With DROP USER , you can remove an
account and its privileges as follows:
DROP USER user ;
Important
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.
DROP USER does not automatically
delete or invalidate any database objects that the user created.
This applies to tables, views, stored routines, triggers, and
events.
GRANT
priv_type [(column_list )]
[, priv_type [(column_list )]] ...
ON [object_type ] priv_level
TO user [IDENTIFIED BY [PASSWORD] 'password ']
[, user [IDENTIFIED BY [PASSWORD] 'password ']] ...
[REQUIRE {NONE | ssl_option [[AND] ssl_option ] ...}]
[WITH with_option [with_option ] ...]
object_type :
TABLE
| FUNCTION
| PROCEDURE
priv_level :
*
| *.*
| db_name .*
| db_name.tbl_name
| tbl_name
| db_name .routine_name
with_option :
GRANT OPTION
| MAX_QUERIES_PER_HOUR count
| MAX_UPDATES_PER_HOUR count
| MAX_CONNECTIONS_PER_HOUR count
| MAX_USER_CONNECTIONS count
ssl_option :
SSL
| X509
| CIPHER 'cipher '
| ISSUER 'issuer '
| SUBJECT 'subject '
The GRANT statement enables
system administrators to create MySQL user accounts and to grant
rights to accounts. To use GRANT ,
you must have the GRANT OPTION
privilege, and you must have the privileges that you are
granting. The REVOKE statement is
related and enables administrators to remove account privileges.
To determine what privileges an account has, use
SHOW GRANTS . See
Section 12.5.1.5, “REVOKE Syntax”, and Section 12.5.5.22, “SHOW GRANTS Syntax”.
MySQL Enterprise
For automated notification of users with inappropriate
privileges, subscribe to the MySQL Enterprise Monitor. For
more information, see
http://www.mysql.com/products/enterprise/advisors.html.
The following table summarizes the allowable
priv_type privilege types that can be
specified for the GRANT and
REVOKE statements. For additional
information about these privileges, see
Section 5.4.1, “Privileges Provided by MySQL”.
The EVENT and
TRIGGER privileges were added in
MySQL 5.1.6. A trigger is associated with a table, so to create
or drop a trigger, you must have the
TRIGGER privilege for the table,
not the trigger. (Before MySQL 5.1.6, the
SUPER privilege was required to
create or drop triggers.)
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 when you
want to create a user that has no privileges, or to modify 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
Chapter 5, MySQL Server Administration, which you should
consult for additional details.
Important
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.8, “mysql_upgrade — Check Tables for MySQL Upgrade”.
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.)
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
'password ' clause for
brevity, but you should include one if the account does not
already exist to avoid creating an account with no password.
Global privileges
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';
Before MySQL 5.1.12, privileges also are assigned at the global
level if you use ON * syntax and you have
not selected a default database. As of
5.1.12, ON * requires a default database and
produces an error is there is none.
The CREATE USER ,
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.
Global privileges are stored in the
mysql.user table.
Database privileges
Database privileges apply to all objects in a given database. To
assign database-level privileges, use ON
db_name .* syntax:
GRANT ALL ON mydb.* TO 'someuser'@'somehost';
GRANT SELECT, INSERT ON mydb.* TO 'someuser'@'somehost';
Privileges also are assigned at the database level (for the
default database) if you use ON * syntax and
you have selected a default database.
The CREATE ,
DROP ,
EVENT , and
GRANT OPTION privileges can be
specified at the database level. Table or routine privileges
also can be specified at the database level, in which case they
apply to all tables or routines in the database.
Database privileges are stored in the
mysql.db and mysql.host
tables. GRANT and
REVOKE affect the
db table, but not the host
table, which is rarely used.
Table privileges
Table privileges apply to all columns in a given table. To
assign table-level privileges, use ON
db_name.tbl_name syntax:
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 allowable priv_type values for a
table are ALTER ,
CREATE VIEW ,
CREATE ,
DELETE ,
DROP , GRANT
OPTION , INDEX ,
INSERT ,
SELECT , SHOW
VIEW , TRIGGER , and
UPDATE .
Table privileges are stored in the
mysql.tables_priv table.
Column privileges
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 allowable priv_type values for a
column (that is, when you use a
column_list clause) are
INSERT ,
SELECT , and
UPDATE .
Column privileges are stored in the
mysql.columns_priv table.
Routine privileges
The ALTER ROUTINE ,
CREATE ROUTINE ,
EXECUTE , and
GRANT OPTION privileges apply to
stored routines (procedures and functions). They can be granted
at the global and database levels. Except for
CREATE ROUTINE , these privileges
can be granted at the routine level for individual routines.
GRANT CREATE ROUTINE ON mydb.* TO 'someuser'@'somehost';
GRANT EXECUTE ON PROCEDURE mydb.myproc TO 'someuser'@'somehost';
The allowable priv_type values at the
routine level are ALTER ROUTINE ,
EXECUTE , and
GRANT OPTION .
CREATE ROUTINE is not a
routine-level privilege because you must have this privilege to
create a routine in the first place.
Routine-level privileges are stored in the
mysql.procs_priv table.
For the global, database, table, and routine levels,
GRANT ALL
assigns only the privileges that exist at the level you are
granting. For example, GRANT ALL ON
db_name .* is a
database-level statement, so it does not grant any global-only
privileges such as FILE .
The object_type clause, if present,
should be specified as TABLE ,
FUNCTION , or PROCEDURE
when the following object is a table, a stored function, or a
stored procedure.
The privileges for a database, table, column, or routine 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.4.5, “Access Control, Stage 2: Request Verification”.
MySQL enables you to grant privileges even on database objects
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 database objects that are to be
created at a later time.
Important
MySQL does not automatically revoke any privileges
when you drop a database or table. However, if you
drop a routine, any routine-level privileges granted for that
routine are revoked.
The user value indicates which MySQL
account to grant the privileges to. To accommodate granting
rights to users from arbitrary hosts, MySQL supports specifying
the user value in the form
user_name @host_name .
If a user_name or
host_name value is legal as an
unquoted identifier, you need not quote it. However, quotes 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,
user_name @'%.example.com'
applies to user_name for any host in
the example.com domain, and
user_name @'192.168.1.%'
applies to 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 allowed access,
with the privileges associated with the anonymous-user account.
For additional information about user and host values in account
names, see Section 5.4.3, “Specifying Account Names”.
To specify quoted values, quote database, table, column, and
routine names as identifiers, using backticks
(“` ”). Quote user names and host
names as identifiers or as strings, using either backticks
(“` ”), single quotes
(“' ”), or double quotes
(“" ”). Quote passwords as
strings, using single quotes.
The “_ ” and
“% ” wildcards are allowed 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 ... .
Warning
If you allow anonymous users to connect to the MySQL server,
you should also grant privileges to all local users as
user_name @localhost .
Otherwise, the anonymous user account for
localhost 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.4.4, “Access Control, Stage 1: Connection Verification”.
You can determine whether the preceding warning applies to you
by executing 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, column, and routine names
can be up to 64 characters. User names can be up to 16
characters.
Warning
The allowable 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.8, “mysql_upgrade — Check Tables for MySQL Upgrade”.
If the NO_AUTO_CREATE_USER SQL
mode is not enabled and 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.
If NO_AUTO_CREATE_USER is
enabled and the account does not exist,
GRANT fails and does not create
the account unless the IDENTIFIED BY clause
is given to provide a nonempty password.
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.
MySQL Enterprise
The MySQL Enterprise Monitor specifically guards against user
accounts with no passwords. To find out more, see
http://www.mysql.com/products/enterprise/advisors.html.
REVOKE does not remove
mysql.user table entries; you must do that
using DROP USER or
DELETE .
Passwords can also be set with the SET
PASSWORD statement. See
Section 12.5.1.6, “SET PASSWORD Syntax”.
In the IDENTIFIED BY clause, the password
should be given as the literal password value. It is unnecessary
to use the PASSWORD() function as
it is for the SET PASSWORD
statement. For example:
GRANT ... IDENTIFIED BY 'mypass';
If you do not want to send the password in clear text and you
know the hashed value that
PASSWORD() would return for the
password, you can specify the hashed value preceded by the
keyword PASSWORD :
GRANT ...
IDENTIFIED BY PASSWORD '*6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4';
The WITH clause is used for several purposes:
To enable a user to grant privileges to other users
To specify resource-use limitations on 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.4.1, “Privileges Provided by MySQL”.
The MAX_QUERIES_PER_HOUR
count ,
MAX_UPDATES_PER_HOUR
count , and
MAX_CONNECTIONS_PER_HOUR
count options limit the
number of queries, updates, and logins a user can perform during
any given one-hour period. (Queries for which results are served
from the query cache do not count against the
MAX_QUERIES_PER_HOUR limit.) If
count is 0 (the
default), this means that there is no limitation for that user.
The MAX_USER_CONNECTIONS
count option limits the
maximum number of simultaneous connections that the account can
make. If count is
0 (the default), the
max_user_connections system
variable determines the number of simultaneous connections for
the account.
To specify any of these resource-limit options for an existing
user without affecting existing privileges, use GRANT
USAGE ON *.* ... WITH MAX_... .
For more information on restricting resources, see
Section 5.5.4, “Limiting Account Resources”.
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.5.7, “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 allowed 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 allow 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
'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
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
'issuer ' value
should be entered as a single string.
REQUIRE SUBJECT
'subject ' places the
restriction on connection attempts that the client must
present a valid X509 certificate containing the 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
'subject '
value should be entered as a single string.
REQUIRE CIPHER
'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 to allow a
connection.
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. The AND keyword is optional
between REQUIRE options.
If you are using table, column, or routine privileges for even
one user, the server examines table, column, and routine
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 standard SQL and MySQL
versions of GRANT are:
In MySQL, privileges are associated 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.
Standard SQL privileges are structured in a hierarchical
manner. If you remove a user, all privileges the user has
been granted are revoked. This is also true in MySQL if you
use DROP USER . See
Section 12.5.1.2, “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
REVOKE statements or by
manipulating values stored in the MySQL grant tables.
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 omit those columns for which
you do not have the INSERT
privilege. The omitted columns are set to their implicit
default values if strict SQL mode is not enabled. In strict
mode, the statement is rejected if any of the omitted
columns have no default value. (Standard SQL requires you to
have the INSERT privilege on
all columns.) Section 5.1.8, “Server SQL Modes”, discusses
strict mode. Section 10.1.4, “Data Type Default Values”, discusses
implicit default values.
12.5.1.4. RENAME USER SyntaxRENAME USER old_user TO new_user
[, old_user TO new_user ] ...
The RENAME USER statement renames
existing MySQL accounts. To use it, you must have the global
CREATE USER privilege or the
UPDATE privilege for the
mysql database. An error occurs if any old
account does not exist or any new account exists. 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.5.1.3, “GRANT Syntax”.
RENAME USER does not
automatically migrate any database objects that the user
created, nor does it migrate any privileges that the user had
prior to the renaming. This applies to tables, views, stored
routines, triggers, and events.
REVOKE
priv_type [(column_list )]
[, priv_type [(column_list )]] ...
ON [object_type ] priv_level
FROM user [, user ] ...
REVOKE ALL PRIVILEGES, GRANT OPTION
FROM user [, user ] ...
The REVOKE statement enables
system administrators to revoke privileges from MySQL accounts.
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 details on the levels at
which privileges exist, the allowable
priv_type and
priv_level values, and the syntax for
specifying users and passwords, see Section 12.5.1.3, “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 revoke all privileges, use the second syntax, which drops all
global, database, table, column, and routine privileges for the
named user or users:
REVOKE ALL PRIVILEGES, GRANT OPTION FROM user [, user ] ...
To use this REVOKE syntax, you
must have the global CREATE USER
privilege or the UPDATE privilege
for the mysql database.
REVOKE removes privileges, but
does not drop mysql.user table entries. To
remove a user account entirely, use DROP
USER (see Section 12.5.1.2, “DROP USER Syntax”) or
DELETE .
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.5.5.22, “SHOW GRANTS Syntax”.
12.5.1.6. SET PASSWORD SyntaxSET PASSWORD [FOR user ] =
{
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
user_name @host_name
format, where 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;
Note
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.5.6.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.
You can see which account the server authenticated you as by
executing SELECT CURRENT_USER() .
MySQL Enterprise
For automated notification of users without passwords,
subscribe to the MySQL Enterprise Monitor. For more
information, see
http://www.mysql.com/products/enterprise/advisors.html.
12.5.2. Table Maintenance Statements12.5.2.1. ANALYZE TABLE SyntaxANALYZE [NO_WRITE_TO_BINLOG | LOCAL] TABLE
tbl_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 . For
InnoDB the table is locked with a write lock.
This statement works with MyISAM and
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.6.14, “Restrictions on InnoDB Tables”.
MySQL Enterprise
For expert advice on optimizing tables, subscribe to the MySQL
Enterprise Monitor. For more information, see
http://www.mysql.com/products/enterprise/advisors.html.
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.
Beginning with MySQL 5.1.27, ANALYZE
TABLE is also supported for partitioned tables. Also
beginning with MySQL 5.1.27, you can use ALTER TABLE
... ANALYZE PARTITION to analyze one or more
partitions; for more information, see
Section 12.1.7, “ALTER TABLE Syntax”, and
Section 18.3.3, “Maintenance of Partitions”.
ANALYZE TABLE returns a result
set with the following columns.
You can check the stored key distribution with the
SHOW INDEX statement. See
Section 12.5.5.23, “SHOW INDEX Syntax”.
If the table has not changed since the last
ANALYZE TABLE statement, the
table is not analyzed again.
By default, 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 .
12.5.2.2. BACKUP TABLE SyntaxBACKUP TABLE tbl_name [, tbl_name ] ... TO '/path/to/backup/directory '
Note
This statement is deprecated. We are working on a better
replacement for it that will provide online backup
capabilities. In the meantime, the
mysqlhotcopy script 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.
12.5.2.3. CHECK TABLE SyntaxCHECK TABLE tbl_name [, tbl_name ] ... [option ] ...
option = {FOR UPGRADE | QUICK | FAST | MEDIUM | EXTENDED | CHANGED}
CHECK TABLE checks a table or
tables for errors. CHECK TABLE
works for MyISAM , InnoDB ,
and ARCHIVE tables. Starting with MySQL
5.1.9, CHECK TABLE is also valid
for CSV tables, see
Section 13.13, “The CSV Storage Engine”. For
MyISAM tables, the key statistics are updated
as well.
CHECK TABLE can also check views
for problems, such as tables that are referenced in the view
definition that no longer exist.
Beginning with MySQL 5.1.27, CHECK
TABLE is also supported for partitioned tables. Also
beginning with MySQL 5.1.27, you can use ALTER TABLE
... CHECK PARTITION to check one or more partitions;
for more information, see Section 12.1.7, “ALTER TABLE Syntax”, and
Section 18.3.3, “Maintenance of Partitions”.
CHECK TABLE returns a result set
with the following columns.
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.5, “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 FOR UPGRADE option checks whether the
named tables are compatible with the current version of MySQL.
This option was added in MySQL 5.1.7. With FOR
UPGRADE , the server checks each table to determine
whether there have been any incompatible changes in any of the
table's data types or indexes since the table was created. If
not, the check succeeds. Otherwise, if there is a possible
incompatibility, the server runs a full check on the table
(which might take some time). If the full check succeeds, the
server marks the table's .frm file with the
current MySQL version number. Marking the
.frm file ensures that further checks for
the table with the same version of the server will be fast.
Incompatibilities might occur because the storage format for a
data type has changed or because its sort order has changed. Our
aim is to avoid these changes, but occasionally they are
necessary to correct problems that would be worse than an
incompatibility between releases.
Currently, FOR UPGRADE discovers these
incompatibilities:
The indexing order for end-space in
TEXT columns for
InnoDB and MyISAM
tables changed between MySQL 4.1 and 5.0.
The storage method of the new
DECIMAL data type changed
between MySQL 5.0.3 and 5.0.5.
As of MySQL 5.1.25, if your table was created by a different
version of the MySQL server than the one you are currently
running, FOR UPGRADE indicates that the
table has an .frm file with an
incompatible version. In this case, the result set returned
by CHECK TABLE contains a
line with a Msg_type value of
error and a Msg_text
value of Table upgrade required. Please do "REPAIR
TABLE `tbl_name `" to fix
it!
Changes are sometimes made to character sets or collations
that require table indexes to be rebuilt. For details about
these changes and when FOR UPGRADE
detects them, see
Section 2.4.3, “Checking Whether Tables or Indexes Must Be Rebuilt”.
The other 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 and views.
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;
Note
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.
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.
12.5.2.4. CHECKSUM TABLE SyntaxCHECKSUM TABLE tbl_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.17, “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 and generates a
warning.
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.
Important
If the checksums for two tables are different, then the tables
are different in some way. However, the fact that two tables
produce the same checksum does not mean
that the tables are identical.
12.5.2.5. OPTIMIZE TABLE SyntaxOPTIMIZE [NO_WRITE_TO_BINLOG | LOCAL] TABLE
tbl_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.
This statement requires SELECT
and INSERT privileges for the
table.
Beginning with MySQL 5.1.27, OPTIMIZE
TABLE is also supported for partitioned tables. Also
beginning with MySQL 5.1.27, you can use ALTER TABLE
... OPTIMIZE PARTITION to optimize one or more
partitions; for more information, see
Section 12.1.7, “ALTER TABLE Syntax”, and
Section 18.3.3, “Maintenance of Partitions”.
In most setups, you need not run OPTIMIZE
TABLE at all. Even if you do a lot of updates to
variable-length rows, it is not likely that you need to do this
more than once a week or month and only on certain tables.
OPTIMIZE TABLE works for
MyISAM , InnoDB , and
ARCHIVE tables.
Beginning with MySQL Cluster NDB 6.3.7,
OPTIMIZE TABLE is also supported
for dynamic columns of in-memory
NDBCLUSTER tables. It does not work
for Disk Data tables. The performance of
OPTIMIZE on Cluster tables can be tuned by
adjusting the value of the
ndb_optimization_delay system variable, which
controls the number of milliseconds to wait between processing
batches of rows by OPTIMIZE
TABLE . See
Section 17.1.5.11, “Previous MySQL Cluster Issues Resolved in MySQL 5.1, MySQL Cluster NDB
6.x, and MySQL Cluster NDB 7.x”, for more
information.
OPTIMIZE TABLE is not supported
for tables using other storage engines except as noted
previously.
Beginning with MySQL Cluster NDB 6.3.8,
OPTIMIZE TABLE can be interrupted
by (for example) killing the SQL thread performing the
OPTIMIZE operation.
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 InnoDB tables,
OPTIMIZE TABLE is mapped to
ALTER TABLE , which rebuilds the
table to update index statistics and free unused space in the
clustered index. Beginning with MySQL 5.1.27, this is displayed
in the output of OPTIMIZE TABLE
when you run it on an InnoDB table, as shown
here:
mysql> OPTIMIZE TABLE foo;
+----------+----------+----------+-------------------------------------------------------------------+
| Table | Op | Msg_type | Msg_text |
+----------+----------+----------+-------------------------------------------------------------------+
| test.foo | optimize | note | Table does not support optimize, doing recreate + analyze instead |
| test.foo | optimize | status | OK |
+----------+----------+----------+-------------------------------------------------------------------+
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.
Note that MySQL locks the table during the time
OPTIMIZE TABLE is running.
By default, 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 .
OPTIMIZE TABLE does not sort
R-tree indexes, such as spatial indexes on
POINT columns. (Bug#23578)
12.5.2.6. REPAIR TABLE SyntaxREPAIR [NO_WRITE_TO_BINLOG | LOCAL] TABLE
tbl_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. Starting with MySQL 5.1.9, REPAIR is
also valid for CSV tables. See
Section 13.5, “The MyISAM Storage Engine”, and
Section 13.12, “The ARCHIVE Storage Engine”, and
Section 13.13, “The CSV Storage Engine”
This statement requires SELECT
and INSERT privileges for the
table.
Beginning with MySQL 5.1.27, REPAIR
TABLE is also supported for partitioned tables.
However, the USE_FRM option cannot be used
with this statement on a partitioned table.
Also beginning with MySQL 5.1.27, you can use ALTER
TABLE ... REPAIR PARTITION to repair one or more
partitions; for more information, see
Section 12.1.7, “ALTER TABLE Syntax”, and
Section 18.3.3, “Maintenance of Partitions”.
Normally, you should never have to run
REPAIR TABLE . However, if
disaster strikes, this statement is very likely to get back all
your data from a MyISAM table. If your tables
become corrupted often, you should try to find the reason for
it, to eliminate the need to use REPAIR
TABLE . See Section B.5.4.2, “What to Do If MySQL Keeps Crashing”, and
Section 13.5.4, “MyISAM Table Problems”.
Caution
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.
Warning
If the server dies 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.
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. This type of repair is like that done by
myisamchk --safe-recover.
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.
Note
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.
Caution
As of MySQL 5.1.25, if you use USE_FRM for
a table that was created by a different version of the MySQL
server than the one you are currently running,
REPAIR TABLE will not attempt
to repair the table. In this case, the result set returned by
REPAIR TABLE contains a line
with a Msg_type value of
error and a Msg_text
value of Failed repairing incompatible .FRM
file .
Prior to MySQL 5.1.25, do not use
USE_FRM if your table was created by a
different version of the MySQL server. 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 `"
or dump/reload to fix it!
If USE_FRM is not used,
REPAIR TABLE checks the table to
see whether an upgrade is required. If so, it performs the
upgrade, following the same rules as
CHECK TABLE ... FOR
UPGRADE . See Section 12.5.2.3, “CHECK TABLE Syntax”, for more
information. As of MySQL 5.1.25, REPAIR
TABLE without USE_FRM upgrades the
.frm file to the current version.
By default, 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 .
12.5.2.7. RESTORE TABLE SyntaxRESTORE TABLE tbl_name [, tbl_name ] ... FROM '/path/to/backup/directory '
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.
12.5.3. Plugin and User-Defined Function Statements12.5.3.1. CREATE FUNCTION SyntaxCREATE [AGGREGATE] FUNCTION function_name RETURNS {STRING|INTEGER|REAL|DECIMAL}
SONAME shared_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. DECIMAL
is a legal value after RETURNS , but currently
DECIMAL functions return string
values and should be written like STRING
functions.
shared_library_name is the basename
of the shared object file that contains the code that implements
the function. The file must be located in the plugin directory.
This directory is given by the value of the
plugin_dir system variable.
Note
This is a change in MySQL 5.1. For earlier versions of MySQL,
the shared object can be located in any directory that is
searched by your system's dynamic linker.
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_upgrade command to create it. See
Section 4.4.8, “mysql_upgrade — Check Tables for MySQL Upgrade”.
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 22.3.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).
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_upgrade program to
create it (see Section 4.4.8, “mysql_upgrade — Check Tables for MySQL Upgrade”).
Note
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.
12.5.3.2. DROP FUNCTION SyntaxDROP 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.
Note
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 is also used to
drop stored functions (see Section 12.1.26, “DROP PROCEDURE and
DROP FUNCTION Syntax”).
12.5.3.3. INSTALL PLUGIN SyntaxINSTALL PLUGIN plugin_name SONAME 'plugin_library '
This statement installs a plugin.
plugin_name is the name of the plugin
as defined in the plugin declaration structure contained in the
library file. Plugin names are not case sensitive. For maximal
compatibility, plugin names should be limited to ASCII letters,
digits, and underscore because they are used in C source files,
shell command lines, M4 and Bourne shell scripts, and SQL
environments.
plugin_library is the name of the
shared library that contains the plugin code. The name includes
the file name extension (for example,
libmyplugin.so or
libmyplugin.dylib ).
The shared library must be located in the plugin directory (that
is, the directory named by the
plugin_dir system variable).
The library must be in the plugin directory itself, not in a
subdirectory. By default,
plugin_dir is
plugin directory under the directory named
by the pkglibdir configuration variable, but
it can be changed by setting the value of
plugin_dir at server startup.
For example, set its value in a my.cnf
file:
[mysqld]
plugin_dir=/path/to/plugin/directory
If the value of plugin_dir is a
relative path name, it is taken to be relative to the MySQL base
directory (the value of the
basedir system variable).
INSTALL PLUGIN adds a line to the
mysql.plugin table that describes the
plugin . This table contains the plugin name
and library file name.
As of MySQL 5.1.33, INSTALL
PLUGIN causes the server to read option
(my.cnf ) files just as during server
startup. This enables the plugin to pick up any relevant options
from those files. It is possible to add plugin options to an
option file even before loading a plugin (if the
loose prefix is used). It is also possible to
uninstall a plugin, edit my.cnf , and
install the plugin again. Restarting the plugin this way enables
it to the new option values without a server restart.
Before MySQL 5.1.33, a plugin is started with each option set to
its default value.
INSTALL PLUGIN also loads and
initializes the plugin code to make the plugin available for
use. A plugin is initialized by executing its initialization
function, which handles any setup that the plugin must perform
before it can be used.
To use INSTALL PLUGIN , you must
have the INSERT privilege for the
mysql.plugin table.
At server startup, the server loads and initializes any plugin
that is listed in the mysql.plugin table.
This means that a plugin is installed with
INSTALL PLUGIN only once, not
every time the server starts. Plugin loading at startup does not
occur if the server is started with the
--skip-grant-tables option.
When the server shuts down, it executes the deinitialization
function for each plugin that is loaded so that the plugin has a
change to perform any final cleanup.
For options that control individual plugin loading at server
startup, see Section 5.1.3, “Server Options for Loading Plugins”. If you
need to load plugins for a single server startup when the
--skip-grant-tables option is
given (which tells the server not to read system tables), use
the --plugin-load option. See
Section 5.1.2, “Server Command Options”.
To remove a plugin entirely, use the
UNINSTALL PLUGIN statement:
To see what plugins are installed, use the SHOW
PLUGIN statement.
If you recompile a plugin library and need to reinstall it, you
can use either of the following procedures:
Use UNINSTALL PLUGIN to
uninstall all plugins in the library, install the new plugin
library file in the plugin directory, and then use
INSTALL PLUGIN to install all
plugins in the library. This procedure has the advantage
that it can be used without stopping the server. However, if
the plugin library contains many plugins, you must issue
many INSTALL PLUGIN and
UNINSTALL PLUGIN statements.
Alternatively, stop the server, install the new plugin
library file in the plugin directory, and then restart the
server.
12.5.3.4. UNINSTALL PLUGIN SyntaxUNINSTALL PLUGIN plugin_name
This statement removes an installed plugin. You cannot uninstall
a plugin if any table that uses it is open.
plugin_name must be the name of some
plugin that is listed in the mysql.plugin
table. The server executes the plugin's deinitialization
function and removes the row for the plugin from the
mysql.plugin table, so that subsequent server
restarts will not load and initialize the plugin.
UNINSTALL PLUGIN does not remove
the plugin's shared library file.
To use UNINSTALL PLUGIN , you must
have the DELETE privilege for the
mysql.plugin table.
Plugin removal has implications for the use of associated
tables. For example, if a full-text parser plugin is associated
with a FULLTEXT index on the table,
uninstalling the plugin makes the table unusable. Any attempt to
access the table results in an error. The table cannot even be
opened, so you cannot drop an index for which the plugin is
used. This means that uninstalling a plugin is something to do
with care unless you do not care about the table contents. If
you are uninstalling a plugin with no intention of reinstalling
it later and you care about the table contents, you should dump
the table with mysqldump and remove the
WITH PARSER clause from the dumped
CREATE TABLE statement so that
you can reload the table later. If you do not care about the
table, DROP TABLE can be used
even if any plugins associated with the table are missing.
SET variable_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.4, “Server System Variables”,
Section 5.1.5, “Session System Variables”, and
Section 8.4, “User-Defined Variables”. System variables also can be set
at server startup, as described in
Section 5.1.6, “Using System Variables”.
Some variants of
SET syntax
are used in other contexts:
The following discussion shows the different
SET syntaxes
that you can use to set variables. The examples use the
= assignment operator, but the
:= operator also is allowable.
A user variable is written as
@var_name and can be
set as follows:
SET @var_name = expr ;
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.6.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.
MySQL Enterprise
The MySQL Enterprise Monitor makes extensive use of system
variables to determine the state of your server. For more
information, see
http://www.mysql.com/products/enterprise/advisors.html.
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 @@var_name
syntax for system variables is supported for compatibility with
some other database systems.
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
@@var_name (that is,
when you do not specify @@global. or
@@session. ), MySQL returns the session value if
it exists and the global value otherwise. (This differs from
SET @@var_name =
value , which always refers to
the session value.)
Note
Some variables displayed by SHOW VARIABLES
may not be available using SELECT
@@var_name syntax; an
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.5.5.41, “SHOW VARIABLES Syntax”.)
The following list describes
SET options
that have nonstandard syntax (that is, options that are not set
with name =
value syntax).
CHARACTER SET
{charset_name | DEFAULT}
This maps all strings from and to the client with the given
mapping. You can add new mappings by editing
sql/convert.cc in the MySQL source
distribution. 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 .
ONE_SHOT
This option is a modifier, not a variable. It can be used to
influence the effect of variables that set the character set,
the collation, and the time zone. ONE_SHOT
is primarily used for replication purposes:
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 for internal use only and is
deprecated for MySQL 5.0 and up.
You cannot use ONE_SHOT with other than the
allowed set of variables; if you try, you get an error like
this:
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 allowed
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 AUTHORS
SHOW CHARACTER SET [like_or_where ]
SHOW COLLATION [like_or_where ]
SHOW [FULL] COLUMNS FROM tbl_name [FROM db_name ] [like_or_where ]
SHOW CONTRIBUTORS
SHOW CREATE DATABASE db_name
SHOW CREATE EVENT event_name
SHOW CREATE FUNCTION func_name
SHOW CREATE PROCEDURE proc_name
SHOW CREATE TABLE tbl_name
SHOW CREATE TRIGGER trigger_name
SHOW CREATE VIEW view_name
SHOW DATABASES [like_or_where ]
SHOW ENGINE engine_name {STATUS | MUTEX}
SHOW [STORAGE] ENGINES
SHOW ERRORS [LIMIT [offset ,] row_count ]
SHOW EVENTS
SHOW FUNCTION CODE func_name
SHOW FUNCTION STATUS [like_or_where ]
SHOW GRANTS FOR user
SHOW INDEX FROM tbl_name [FROM db_name ]
SHOW INNODB STATUS
SHOW OPEN TABLES [FROM db_name ] [like_or_where ]
SHOW PLUGINS
SHOW PROCEDURE CODE proc_name
SHOW PROCEDURE STATUS [like_or_where ]
SHOW PRIVILEGES
SHOW [FULL] PROCESSLIST
SHOW PROFILE [types ] [FOR QUERY n ] [OFFSET n ] [LIMIT n ]
SHOW PROFILES
SHOW SCHEDULER STATUS
SHOW [GLOBAL | SESSION] STATUS [like_or_where ]
SHOW TABLE STATUS [FROM db_name ] [like_or_where ]
SHOW [FULL] TABLES [FROM db_name ] [like_or_where ]
SHOW TRIGGERS [FROM db_name ] [like_or_where ]
SHOW [GLOBAL | SESSION] VARIABLES [like_or_where ]
SHOW WARNINGS [LIMIT [offset ,] row_count ]
like_or_where :
LIKE 'pattern '
| WHERE expr
If the syntax for a given SHOW
statement includes a LIKE
'pattern ' part,
'pattern ' is a
string that can contain the SQL
“% ” and
“_ ” wildcard characters. The
pattern is useful for restricting statement output to matching
values.
Several SHOW statements also accept
a WHERE clause that provides more flexibility
in specifying which rows to display. See
Section 20.28, “Extensions to SHOW Statements”.
Many MySQL APIs (such as PHP) allow you to treat the result
returned from a SHOW statement as
you would a result set from a
SELECT ; see
Chapter 21, Connectors and APIs, or your API documentation for
more information. In addition, you can work in SQL with results
from queries on tables in the
INFORMATION_SCHEMA database, which you cannot
easily do with results from SHOW
statements. See Chapter 20, INFORMATION_SCHEMA Tables.
12.5.5.1. SHOW AUTHORS SyntaxSHOW AUTHORS
The SHOW AUTHORS statement
displays information about the people who work on MySQL. For
each author, it displays Name ,
Location , and Comment
values.
This statement was added in MySQL 5.1.3.
12.5.5.2. SHOW BINARY LOGS SyntaxSHOW 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.6.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 is equivalent to SHOW BINARY
LOGS .
12.5.5.3. SHOW BINLOG EVENTS SyntaxSHOW BINLOG EVENTS
[IN 'log_name '] [FROM pos ] [LIMIT [offset ,] row_count ]
Shows the events in the binary log. If you do not specify
'log_name ' , the
first binary log is displayed.
The LIMIT clause has the same syntax as for
the SELECT statement. See
Section 12.2.8, “SELECT Syntax”.
Note
Events relating to the setting of variables are not included
in the output from SHOW BINLOG
EVENTS . To get complete coverage of events within a
binary log, use
mysqlbinlog .
12.5.5.4. SHOW CHARACTER SET SyntaxSHOW CHARACTER SET
[LIKE 'pattern ' | WHERE expr ]
The SHOW CHARACTER SET statement
shows all available character sets. The
LIKE clause, if present, indicates
which character set names to match. The WHERE
clause can be given to select rows using more general
conditions, as discussed in Section 20.28, “Extensions to SHOW Statements”. 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.
12.5.5.5. SHOW COLLATION SyntaxSHOW COLLATION
[LIKE 'pattern ' | WHERE expr ]
This statement lists collations supported by the server. By
default, the output from SHOW
COLLATION includes all available collations. The
LIKE clause, if present, indicates
which collation names to match. The WHERE
clause can be given to select rows using more general
conditions, as discussed in Section 20.28, “Extensions to SHOW Statements”. 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 |
...
12.5.5.6. SHOW COLUMNS SyntaxSHOW [FULL] COLUMNS {FROM | IN} tbl_name [{FROM | IN} db_name ]
[LIKE 'pattern ' | WHERE expr ]
SHOW COLUMNS displays information
about the columns in a given table. It also works for views. The
LIKE clause, if present, indicates
which column names to match. The WHERE clause
can be given to select rows using more general conditions, as
discussed in Section 20.28, “Extensions to SHOW Statements”.
mysql> SHOW COLUMNS FROM City;
+------------+----------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+------------+----------+------+-----+---------+----------------+
| Id | int(11) | NO | PRI | NULL | auto_increment |
| Name | char(35) | NO | | | |
| Country | char(3) | NO | UNI | | |
| District | char(20) | YES | MUL | | |
| Population | int(11) | NO | | 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.17.1, “Silent Column Specification Changes”.
The FULL keyword causes the output to include
the column collation and comments, as well as the privileges you
have for each column.
You can use db_name.tbl_name as an
alternative to the tbl_name
FROM db_name syntax. In
other words, these two statements are equivalent:
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 contains
YES if NULL values can be
stored in the column, NO if not.
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 allowed 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.
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
nonempty in these cases: auto_increment for
columns that have the AUTO_INCREMENT
attribute; as of MySQL 5.1.23, on update
CURRENT_TIMESTAMP for
TIMESTAMP columns that have the
ON UPDATE CURRENT_TIMESTAMP attribute.
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.3.1, “DESCRIBE Syntax”.
The SHOW CREATE TABLE ,
SHOW TABLE STATUS , and
SHOW INDEX statements also
provide information about tables. See Section 12.5.5, “SHOW Syntax”.
12.5.5.7. SHOW CONTRIBUTORS SyntaxSHOW CONTRIBUTORS
The SHOW CONTRIBUTORS statement
displays information about the people who contribute to MySQL
source or to causes that we support. For each contributor, it
displays Name , Location ,
and Comment values.
This statement was added in MySQL 5.1.12.
12.5.5.8. SHOW CREATE DATABASE SyntaxSHOW CREATE {DATABASE | SCHEMA} db_name
Shows the CREATE DATABASE
statement that creates the given database.
SHOW
CREATE SCHEMA is a synonym for
SHOW CREATE DATABASE .
mysql> SHOW CREATE DATABASE test\G
*************************** 1. row ***************************
Database: test
Create Database: CREATE DATABASE `test`
/*!40100 DEFAULT CHARACTER SET latin1 */
mysql> SHOW CREATE SCHEMA 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.5, “Session System Variables”.
12.5.5.9. SHOW CREATE EVENT SyntaxSHOW CREATE EVENT event_name
This statement displays the CREATE
EVENT statement needed to re-create a given event. For
example (using the same event e_daily defined
and then altered in Section 12.5.5.19, “SHOW EVENTS Syntax”):
mysql> SHOW CREATE EVENT test.e_daily\G
*************************** 1. row ***************************
Event: e_daily
sql_mode:
time_zone: SYSTEM
Create Event: CREATE EVENT `e_daily`
ON SCHEDULE EVERY 1 DAY
STARTS CURRENT_TIMESTAMP + INTERVAL 6 HOUR
ON COMPLETION NOT PRESERVE
ENABLE
COMMENT 'Saves total number of sessions then
clears the table each day'
DO BEGIN
INSERT INTO site_activity.totals (time, total)
SELECT CURRENT_TIMESTAMP, COUNT(*)
FROM site_activity.sessions;
DELETE FROM site_activity.sessions;
END
character_set_client: latin1
collation_connection: latin1_swedish_ci
Database Collation: latin1_swedish_ci
character_set_client is the
session value of the
character_set_client system
variable when the event was created.
collation_connection is the
session value of the
collation_connection system
variable when the event was created. Database
Collation is the collation of the database with which
the event is associated. These columns were added in MySQL
5.1.21.
Note that the output reflects the current status of the event
(ENABLE ) rather than the status with which it
was created.
This statement was implemented in MySQL 5.1.6.
12.5.5.11. SHOW CREATE PROCEDURE SyntaxSHOW CREATE PROCEDURE proc_name
This statement is a MySQL extension. It returns the exact string
that can be used to re-create the named stored procedure. A
similar statement, SHOW CREATE
FUNCTION , displays information about stored functions
(see Section 12.5.5.10, “SHOW CREATE FUNCTION Syntax”).
Both statements require that you be the owner of the routine or
have SELECT access to the
mysql.proc table. If you do not have
privileges for the routine itself, the value displayed for the
Create Procedure or Create
Function field will be NULL .
mysql> SHOW CREATE PROCEDURE test.simpleproc\G
*************************** 1. row ***************************
Procedure: simpleproc
sql_mode:
Create Procedure: CREATE PROCEDURE `simpleproc`(OUT param1 INT)
BEGIN
SELECT COUNT(*) INTO param1 FROM t;
END
character_set_client: latin1
collation_connection: latin1_swedish_ci
Database Collation: latin1_swedish_ci
mysql> SHOW CREATE FUNCTION test.hello\G
*************************** 1. row ***************************
Function: hello
sql_mode:
Create Function: CREATE FUNCTION `hello`(s CHAR(20))
RETURNS CHAR(50)
RETURN CONCAT('Hello, ',s,'!')
character_set_client: latin1
collation_connection: latin1_swedish_ci
Database Collation: latin1_swedish_ci
character_set_client is the
session value of the
character_set_client system
variable when the routine was created.
collation_connection is the
session value of the
collation_connection system
variable when the routine was created. Database
Collation is the collation of the database with which
the routine is associated. These columns were added in MySQL
5.1.21.
12.5.5.12. SHOW CREATE TABLE SyntaxSHOW CREATE TABLE tbl_name
Shows the CREATE TABLE statement
that creates the given table. The statement requires the
SELECT privilege for the table.
This statement also works with views.
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.5, “Session System Variables”.
12.5.5.13. SHOW CREATE TRIGGER SyntaxSHOW CREATE TRIGGER trigger_name
This statement shows a CREATE
TRIGGER statement that creates the given trigger.
mysql> SHOW CREATE TRIGGER ins_sum \G
*************************** 1. row ***************************
Trigger: ins_sum
sql_mode:
SQL Original Statement: CREATE DEFINER=`bob`@`localhost` TRIGGER ins_sum
BEFORE INSERT ON account
FOR EACH ROW SET @sum = @sum + NEW.amount
character_set_client: latin1
collation_connection: latin1_swedish_ci
Database Collation: latin1_swedish_ci
This statement was added in MySQL 5.1.21.
You can also obtain information about trigger objects from
INFORMATION_SCHEMA , which contains a
TRIGGERS table. See
Section 20.16, “The INFORMATION_SCHEMA TRIGGERS Table”.
12.5.5.14. SHOW CREATE VIEW SyntaxSHOW CREATE VIEW view_name
This statement shows a CREATE
VIEW statement that creates the given view.
mysql> SHOW CREATE VIEW v\G
*************************** 1. row ***************************
View: v
Create View: CREATE ALGORITHM=UNDEFINED
DEFINER=`bob`@`localhost`
SQL SECURITY DEFINER VIEW
`v` AS select 1 AS `a`,2 AS `b`
character_set_client: latin1
collation_connection: latin1_swedish_ci
character_set_client is the
session value of the
character_set_client system
variable when the view was created.
collation_connection is the
session value of the
collation_connection system
variable when the view was created. These columns were added in
MySQL 5.1.21.
Use of SHOW CREATE VIEW requires
the SHOW VIEW privilege and the
SELECT privilege for the view in
question.
You can also obtain information about view objects from
INFORMATION_SCHEMA , which contains a
VIEWS table. See
Section 20.15, “The INFORMATION_SCHEMA VIEWS Table”.
MySQL lets you use different
sql_mode settings to tell the
server the type of SQL syntax to support. For example, you might
use the ANSI SQL mode to
ensure MySQL correctly interprets the standard SQL concatenation
operator, the double bar (|| ), in your
queries. If you then create a view that concatenates items, you
might worry that changing the
sql_mode setting to a value
different from ANSI could
cause the view to become invalid. But this is not the case. No
matter how you write out a view definition, MySQL always stores
it the same way, in a canonical form. Here is an example that
shows how the server changes a double bar concatenation operator
to a CONCAT() function:
mysql> SET sql_mode = 'ANSI';
Query OK, 0 rows affected (0.00 sec)
mysql> CREATE VIEW test.v AS SELECT 'a' || 'b' as col1;
Query OK, 0 rows affected (0.01 sec)
mysql> SHOW CREATE VIEW test.v\G
*************************** 1. row ***************************
View: v
Create View: CREATE VIEW "v" AS select concat('a','b') AS "col1"
...
1 row in set (0.00 sec)
The advantage of storing a view definition in canonical form is
that changes made later to the value of
sql_mode will not affect the
results from the view. However an additional consequence is that
comments prior to SELECT are
stripped from the definition by the server.
12.5.5.15. SHOW DATABASES SyntaxSHOW {DATABASES | SCHEMAS}
[LIKE 'pattern ' | WHERE expr ]
SHOW DATABASES lists the
databases on the MySQL server host.
SHOW
SCHEMAS is a synonym for SHOW
DATABASES . The LIKE
clause, if present, indicates which database names to match. The
WHERE clause can be given to select rows
using more general conditions, as discussed in
Section 20.28, “Extensions to SHOW Statements”.
You see only those databases for which you have some kind of
privilege, unless you 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.
12.5.5.16. SHOW ENGINE SyntaxSHOW ENGINE engine_name {STATUS | MUTEX}
SHOW ENGINE displays operational
information about a storage engine. The following statements
currently are supported:
SHOW ENGINE INNODB STATUS
SHOW ENGINE INNODB MUTEX
SHOW ENGINE {NDB | NDBCLUSTER} STATUS
Older (and now deprecated) synonyms are
SHOW INNODB STATUS for
SHOW ENGINE INNODB
STATUS and SHOW MUTEX STATUS for
SHOW ENGINE INNODB
MUTEX .
In MySQL 5.0,
SHOW ENGINE INNODB
MUTEX is invoked as SHOW MUTEX
STATUS . The latter statement displays similar
information but in a somewhat different output format.
SHOW ENGINE BDB
LOGS formerly displayed status information about
BDB log files. As of MySQL 5.1.12, the
BDB storage engine is not supported, and this
statement produces a warning.
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.6.13.2, “SHOW ENGINE INNODB
STATUS and the InnoDB Monitors”.
SHOW ENGINE INNODB
MUTEX displays InnoDB mutex
statistics. From MySQL 5.1.2 to 5.1.14, the statement displays
the following output fields:
Type
Always InnoDB .
Name
The mutex name and the source file where it is implemented.
Example: &pool->mutex:mem0pool.c
The mutex name indicates its purpose. For example, the
log_sys mutex is used by the
InnoDB logging subsystem and indicates
how intensive logging activity is. The
buf_pool mutex protects the
InnoDB buffer pool.
Status
The mutex status. The fields contains several values:
count indicates how many times the
mutex was requested.
spin_waits indicates how many times
the spinlock had to run.
spin_rounds indicates the number of
spinlock rounds. (spin_rounds divided
by spin_waits provides the average
round count.)
os_waits indicates the number of
operating system waits. This occurs when the spinlock
did not work (the mutex was not locked during the
spinlock and it was necessary to yield to the operating
system and wait).
os_yields indicates the number of
times a the thread trying to lock a mutex gave up its
timeslice and yielded to the operating system (on the
presumption that allowing other threads to run will free
the mutex so that it can be locked).
os_wait_times indicates the amount of
time (in ms) spent in operating system waits, if the
timed_mutexes system
variable is 1 (ON ). If
timed_mutexes is 0
(OFF ), timing is disabled, so
os_wait_times is 0.
timed_mutexes is off by
default.
From MySQL 5.1.15 on, the statement displays the following
output fields:
Type
Always InnoDB .
Name
The source file where the mutex is implemented, and the line
number in the file where the mutex is created. The line
number may change depending on your version of MySQL.
Status
This field displays the same values as previously described
(count , spin_waits ,
spin_rounds , os_waits ,
os_yields ,
os_wait_times ), but only if
UNIV_DEBUG was defined at MySQL
compilation time (for example, in
include/univ.h in the
InnoDB part of the MySQL source tree). If
UNIV_DEBUG was not defined, the statement
displays only the os_waits value. In the
latter case (without UNIV_DEBUG ), the
information on which the output is based is insufficient to
distinguish regular mutexes and mutexes that protect
rw-locks (which allow multiple readers or a single writer).
Consequently, the output may appear to contain multiple rows
for the same mutex.
Information from this statement can be used to diagnose system
problems. For example, large values of
spin_waits and spin_rounds
may indicate scalability problems.
If the server has the NDBCLUSTER
storage engine enabled,
SHOW ENGINE NDB
STATUS displays cluster status information such as the
number of connected data nodes, the cluster connectstring, and
cluster binlog epochs, as well as counts of various Cluster API
objects created by the MySQL Server when connected to the
cluster. Sample output from this statement is shown here:
mysql> SHOW ENGINE NDB STATUS;
+------------+-----------------------+--------------------------------------------------+
| Type | Name | Status |
+------------+-----------------------+--------------------------------------------------+
| ndbcluster | connection | cluster_node_id=7,
connected_host=192.168.0.103, connected_port=1186, number_of_data_nodes=4,
number_of_ready_data_nodes=3, connect_count=0 |
| ndbcluster | NdbTransaction | created=6, free=0, sizeof=212 |
| ndbcluster | NdbOperation | created=8, free=8, sizeof=660 |
| ndbcluster | NdbIndexScanOperation | created=1, free=1, sizeof=744 |
| ndbcluster | NdbIndexOperation | created=0, free=0, sizeof=664 |
| ndbcluster | NdbRecAttr | created=1285, free=1285, sizeof=60 |
| ndbcluster | NdbApiSignal | created=16, free=16, sizeof=136 |
| ndbcluster | NdbLabel | created=0, free=0, sizeof=196 |
| ndbcluster | NdbBranch | created=0, free=0, sizeof=24 |
| ndbcluster | NdbSubroutine | created=0, free=0, sizeof=68 |
| ndbcluster | NdbCall | created=0, free=0, sizeof=16 |
| ndbcluster | NdbBlob | created=1, free=1, sizeof=264 |
| ndbcluster | NdbReceiver | created=4, free=0, sizeof=68 |
| ndbcluster | binlog | latest_epoch=155467, latest_trans_epoch=148126,
latest_received_binlog_epoch=0, latest_handled_binlog_epoch=0,
latest_applied_binlog_epoch=0 |
+------------+-----------------------+--------------------------------------------------+
The rows with connection and
binlog in the Name column
were added to the output of this statement in MySQL 5.1. The
Status column in each of these rows provides
information about the MySQL server's connection to the cluster
and about the cluster binary log's status, respectively. The
Status information is in the form of
comma-delimited set of name/value pairs.
The connection row's
Status column contains the name/value pairs
described in the following table.
The binlog row's Status
column contains information relating to MySQL Cluster
Replication. The name/value pairs it contains are described in
the following table.
See Section 17.6, “MySQL Cluster Replication”, for more
information.
The remaining rows from the output of
SHOW ENGINE NDB
STATUS which are most likely to prove useful in
monitoring the cluster are listed here by
Name :
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.
Note
SHOW ENGINE NDB
STATUS returns an empty result if no operations
involving NDB tables have been
performed during the current session by the MySQL client
accessing the SQL node on which this statement is run.
MySQL Enterprise
The SHOW ENGINE
engine_name STATUS
statement provides valuable information about the state of
your server. For expert interpretation of this information,
subscribe to the MySQL Enterprise Monitor. For more
information, see
http://www.mysql.com/products/enterprise/advisors.html.
12.5.5.17. SHOW ENGINES SyntaxSHOW [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. SHOW
TABLE TYPES is a deprecated synonym.
mysql> SHOW ENGINES\G
*************************** 1. row ***************************
Engine: MEMORY
Support: YES
Comment: Hash based, stored in memory, useful for temporary tables
Transactions: NO
XA: NO
Savepoints: NO
*************************** 2. row ***************************
Engine: MyISAM
Support: DEFAULT
Comment: Default engine as of MySQL 3.23 with great performance
Transactions: NO
XA: NO
Savepoints: NO
*************************** 3. row ***************************
Engine: InnoDB
Support: YES
Comment: Supports transactions, row-level locking, and foreign keys
Transactions: YES
XA: YES
Savepoints: YES
*************************** 4. row ***************************
Engine: EXAMPLE
Support: YES
Comment: Example storage engine
Transactions: NO
XA: NO
Savepoints: NO
*************************** 5. row ***************************
Engine: ARCHIVE
Support: YES
Comment: Archive storage engine
Transactions: NO
XA: NO
Savepoints: NO
*************************** 6. row ***************************
Engine: CSV
Support: YES
Comment: CSV storage engine
Transactions: NO
XA: NO
Savepoints: NO
*************************** 7. row ***************************
Engine: BLACKHOLE
Support: YES
Comment: /dev/null storage engine (anything you write »
to it disappears)
Transactions: NO
XA: NO
Savepoints: NO
*************************** 8. row ***************************
Engine: FEDERATED
Support: YES
Comment: Federated MySQL storage engine
Transactions: NO
XA: NO
Savepoints: NO
*************************** 9. row ***************************
Engine: MRG_MYISAM
Support: YES
Comment: Collection of identical MyISAM tables
Transactions: NO
XA: NO
Savepoints: NO
The output from SHOW ENGINES may
vary according to the MySQL version used and other factors. The
values shown in the Support column indicate
the server's level of support for the storage engine, as shown
in the following table.
A value of NO means that the server was
compiled without support for the engine, so it cannot be
activated at runtime.
A value of DISABLED occurs either because the
server was started with an option that disables the engine, or
because not all options required to enable it were given. In the
latter case, the error log file should contain a reason
indicating why the option is disabled. See
Section 5.2.2, “The Error Log”.
You might also see DISABLED for a storage
engine if the server was compiled to support it, but was started
with a
--skip-engine_name
option. For the NDBCLUSTER storage
engine, DISABLED means the server was
compiled with support for MySQL Cluster, but was not started
with the --ndbcluster option.
All MySQL servers support MyISAM tables,
because MyISAM is the default storage engine.
It is not possible to disable MyISAM .
The Transactions , XA , and
Savepoints columns were added in MySQL 5.1.2.
They indicate whether the storage engine supports transactions,
XA transactions, and savepoints, respectively.
12.5.5.18. SHOW ERRORS SyntaxSHOW 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.
The LIMIT clause has the same syntax as for
the SELECT statement. See
Section 12.2.8, “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.5.5.42, “SHOW WARNINGS Syntax”.
12.5.5.19. SHOW EVENTS SyntaxSHOW EVENTS [{FROM | IN} schema_name ]
[LIKE 'pattern ' | WHERE expr ]
In its simplest form, SHOW EVENTS
lists all of the events in the current schema:
mysql> SELECT CURRENT_USER(), SCHEMA();
+----------------+----------+
| CURRENT_USER() | SCHEMA() |
+----------------+----------+
| jon@ghidora | myschema |
+----------------+----------+
1 row in set (0.00 sec)
mysql> SHOW EVENTS\G
*************************** 1. row ***************************
Db: myschema
Name: e_daily
Definer: jon@ghidora
Time zone: SYSTEM
Type: RECURRING
Execute at: NULL
Interval value: 10
Interval field: SECOND
Starts: 2006-02-09 10:41:23
Ends: NULL
Status: ENABLED
Originator: 0
character_set_client: latin1
collation_connection: latin1_swedish_ci
Database Collation: latin1_swedish_ci
To see events for a specific schema, use the
FROM clause. For example, to see events for
the test schema, use the following statement:
SHOW EVENTS FROM test;
The LIKE clause, if present,
indicates which event names to match. The
WHERE clause can be given to select rows
using more general conditions, as discussed in
Section 20.28, “Extensions to SHOW Statements”.
SHOW EVENTS output has the
following columns:
Db : The schema (database) on which the
event is defined.
Name : The name of the event.
Time zone : The event time zone, which is
the time zone used for scheduling the event and that is in
effect within the event as it executes. The default value is
SYSTEM .
This column was added in MySQL 5.1.17. See
Section C.1.33, “Changes in MySQL 5.1.17 (04 April 2007)”, for important information if
you are using the Event Scheduler and are upgrading to MySQL
5.1.17 or later from an earlier version.
Definer : The account of the user who
created the event, in
'user_name '@'host_name '
format.
Type : The event repetition type, either
ONE TIME (transient) or
RECURRING (repeating).
Execute At : The date and time when a
transient event is set to execute. Shown as a
DATETIME value.
For a recurring event, the value of this column is always
NULL .
Interval Value : For a recurring event,
the number of intervals to wait between event executions.
For a transient event, the value of this column is always
NULL .
Interval Field : The time units used for
the interval which a recurring event waits before repeating.
For a transient event, the value of this column is always
NULL .
Starts : The start date and time for a
recurring event. This is displayed as a
DATETIME value, and is
NULL if no start date and time are
defined for the event. (Prior to MySQL 5.1.8, it defaulted
to '0000-00-00 00:00:00' in such cases.)
For a transient event, this column is always
NULL .
Ends : The end date and time for a
recurring event. This is displayed as a
DATETIME value, and defaults
to NULL if no end date and time is
defined for the event.
For a transient event, this column is always
NULL .
Status : The event status. One of
ENABLED , DISABLED , or
SLAVESIDE_DISABLED .
SLAVESIDE_DISABLED was added in MySQL
5.1.18. This value indicates that the creation of the event
occurred on another MySQL server acting as a replication
master and replicated to the current MySQL server which is
acting as a slave, but the event is not presently being
executed on the slave.
Originator : The server ID of the MySQL
server on which the event was created. Defaults to 0. This
column was added in MySQL 5.1.18.
character_set_client is the
session value of the
character_set_client system
variable when the routine was created.
collation_connection is the
session value of the
collation_connection system
variable when the routine was created. Database
Collation is the collation of the database with
which the routine is associated. These columns were added in
MySQL 5.1.21.
For more information about SLAVE_DISABLED and
the Originator column, see
Section 16.3.1.8, “Replication of Invoked Features”.
The event action statement is not shown in the output of
SHOW EVENTS . Use
SHOW CREATE EVENT or the
INFORMATION_SCHEMA.EVENTS table.
Times displayed by SHOW EVENTS
are given in the event time zone (or UTC prior to MySQL 5.1.17),
as discussed in Section 19.4.4, “Event Metadata”.
The columns in the output of SHOW
EVENTS are similar to, but not identical to the
columns in the
INFORMATION_SCHEMA.EVENTS table.
See Section 20.20, “The INFORMATION_SCHEMA EVENTS Table”.
SHOW EVENTS was added in MySQL
5.1.6.
Note
In MySQL 5.1.11 and earlier, SHOW
EVENTS displayed only those events for which the
current user was the definer, and the
SHOW FULL
EVENTS statement was used for viewing events defined
by all users on a given schema.
SHOW FULL
EVENTS was removed in MySQL 5.1.12.
12.5.5.22. SHOW GRANTS SyntaxSHOW 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.5.1.3, “GRANT Syntax”.
mysql> SHOW GRANTS FOR 'root'@'localhost';
+---------------------------------------------------------------------+
| Grants for root@localhost |
+---------------------------------------------------------------------+
| GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost' WITH GRANT OPTION |
+---------------------------------------------------------------------+
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();
As of MySQL 5.1.12, if SHOW GRANTS FOR
CURRENT_USER (or any of the equivalent syntaxes) is
used in DEFINER context, such as within a
stored procedure that is defined with SQL SECURITY
DEFINER ), the grants displayed are those of the
definer and not the invoker.
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.
12.5.5.23. SHOW INDEX SyntaxSHOW {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.
Collation
How the column is sorted in the index. In MySQL, this can
have values “A ” (Ascending)
or NULL (Not sorted).
Cardinality
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, the column contains
NO .
Contains YES if the column may contain
NULL values and '' if
not.
Index_type
The index method used (BTREE ,
FULLTEXT , HASH ,
RTREE ).
Comment
Various remarks.
You can use
db_name .tbl_name
as an alternative to the
tbl_name FROM
db_name syntax. These two
statements are equivalent:
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.
12.5.5.25. SHOW MASTER STATUS SyntaxSHOW 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 |
+---------------+----------+--------------+------------------+
12.5.5.26. SHOW OPEN TABLES SyntaxSHOW OPEN TABLES [{FROM | IN} db_name ]
[LIKE 'pattern ' | WHERE expr ]
SHOW OPEN TABLES lists the
non-TEMPORARY tables that are currently open
in the table cache. See Section 7.4.8, “How MySQL Opens and Closes Tables”. The
WHERE clause can be given to select rows
using more general conditions, as discussed in
Section 20.28, “Extensions to SHOW Statements”.
The FROM and
LIKE clauses may be used beginning
with MySQL 5.1.24. The LIKE clause,
if present, indicates which table names to match. The
FROM clause, if present, restricts the tables
shown to those present in the db_name
database.
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.
12.5.5.27. SHOW PLUGINS SyntaxSHOW PLUGINS
SHOW PLUGINS displays information
about known plugins.
mysql> SHOW PLUGINS;
+------------+--------+----------------+---------+
| Name | Status | Type | Library |
+------------+--------+----------------+---------+
| MEMORY | ACTIVE | STORAGE ENGINE | NULL |
| MyISAM | ACTIVE | STORAGE ENGINE | NULL |
| InnoDB | ACTIVE | STORAGE ENGINE | NULL |
| ARCHIVE | ACTIVE | STORAGE ENGINE | NULL |
| CSV | ACTIVE | STORAGE ENGINE | NULL |
| BLACKHOLE | ACTIVE | STORAGE ENGINE | NULL |
| FEDERATED | ACTIVE | STORAGE ENGINE | NULL |
| MRG_MYISAM | ACTIVE | STORAGE ENGINE | NULL |
+------------+--------+----------------+---------+
SHOW PLUGIN was added in MySQL 5.1.5 and
renamed to SHOW PLUGINS in 5.1.9.
(As of 5.1.9, SHOW PLUGIN is deprecated and
generates a warning.)
12.5.5.28. SHOW PRIVILEGES SyntaxSHOW PRIVILEGES
SHOW PRIVILEGES shows the list of
system privileges that the MySQL server supports. 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: Alter routine
Context: Functions,Procedures
Comment: To alter or drop stored functions/procedures
*************************** 3. row ***************************
Privilege: Create
Context: Databases,Tables,Indexes
Comment: To create new databases and tables
*************************** 4. row ***************************
Privilege: Create routine
Context: Functions,Procedures
Comment: To use CREATE FUNCTION/PROCEDURE
*************************** 5. row ***************************
Privilege: Create temporary tables
Context: Databases
Comment: To use CREATE TEMPORARY TABLE
...
Privileges belonging to a specific user are displayed by the
SHOW GRANTS statement. See
Section 12.5.5.22, “SHOW GRANTS Syntax”, for more information.
12.5.5.29. SHOW PROCEDURE CODE SyntaxSHOW PROCEDURE CODE proc_name
This statement is a MySQL extension that is available only for
servers that have been built with debugging support. It displays
a representation of the internal implementation of the named
stored procedure. A similar statement, SHOW
FUNCTION CODE , displays information about stored
functions (see Section 12.5.5.20, “SHOW FUNCTION CODE Syntax”).
Both statements require that you be the owner of the routine or
have SELECT access to the
mysql.proc table.
If the named routine is available, each statement produces a
result set. Each row in the result set corresponds to one
“instruction” in the routine. The first column is
Pos , which is an ordinal number beginning
with 0. The second column is Instruction ,
which contains an SQL statement (usually changed from the
original source), or a directive which has meaning only to the
stored-routine handler.
mysql> DELIMITER //
mysql> CREATE PROCEDURE p1 ()
-> BEGIN
-> DECLARE fanta INT DEFAULT 55;
-> DROP TABLE t2;
-> LOOP
-> INSERT INTO t3 VALUES (fanta);
-> END LOOP;
-> END//
Query OK, 0 rows affected (0.00 sec)
mysql> SHOW PROCEDURE CODE p1//
+-----+----------------------------------------+
| Pos | Instruction |
+-----+----------------------------------------+
| 0 | set fanta@0 55 |
| 1 | stmt 9 "DROP TABLE t2" |
| 2 | stmt 5 "INSERT INTO t3 VALUES (fanta)" |
| 3 | jump 2 |
+-----+----------------------------------------+
4 rows in set (0.00 sec)
In this example, the nonexecutable BEGIN and
END statements have disappeared, and for the
DECLARE
variable_name statement,
only the executable part appears (the part where the default is
assigned). For each statement that is taken from source, there
is a code word stmt followed by a type (9
means DROP , 5 means
INSERT , and so on). The final row
contains an instruction jump 2 , meaning
GOTO instruction #2 .
These statements were added in MySQL 5.1.3.
12.5.5.30. SHOW PROCEDURE STATUS SyntaxSHOW PROCEDURE STATUS
[LIKE 'pattern ' | WHERE expr ]
This statement is a MySQL extension. It returns characteristics
of a stored procedure, such as the database, name, type,
creator, creation and modification dates, and character set
information. A similar statement, SHOW
FUNCTION STATUS , displays information about stored
functions (see Section 12.5.5.21, “SHOW FUNCTION STATUS Syntax”).
The LIKE clause, if present,
indicates which procedure or function names to match. The
WHERE clause can be given to select rows
using more general conditions, as discussed in
Section 20.28, “Extensions to SHOW Statements”.
mysql> SHOW PROCEDURE STATUS LIKE 'sp1'\G
*************************** 1. row ***************************
Db: test
Name: sp1
Type: PROCEDURE
Definer: testuser@localhost
Modified: 2004-08-03 15:29:37
Created: 2004-08-03 15:29:37
Security_type: DEFINER
Comment:
character_set_client: latin1
collation_connection: latin1_swedish_ci
Database Collation: latin1_swedish_ci
character_set_client is the
session value of the
character_set_client system
variable when the routine was created.
collation_connection is the
session value of the
collation_connection system
variable when the routine was created. Database
Collation is the collation of the database with which
the routine is associated. These columns were added in MySQL
5.1.21.
You can also get information about stored routines from the
ROUTINES table in
INFORMATION_SCHEMA . See
Section 20.14, “The INFORMATION_SCHEMA ROUTINES Table”.
12.5.5.31. SHOW PROCESSLIST SyntaxSHOW [FULL] PROCESSLIST
SHOW PROCESSLIST shows you which
threads are running. You can also get this information from the
INFORMATION_SCHEMA
PROCESSLIST table or 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.
MySQL Enterprise
Subscribers to MySQL Enterprise Monitor receive instant
notification and expert advice on resolution when there are
too many concurrent processes. For more information, see
http://www.mysql.com/products/enterprise/advisors.html.
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.5.6.4, “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.
event_scheduler refers to
the thread that monitors scheduled events. For
system user or
event_scheduler , 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).
SHOW PROCESSLIST reports the
host name for TCP/IP connections in
host_name :client_port
format to make it easier to determine which client is doing
what.
db
The default database, if one is selected, otherwise
NULL .
Command
The type of command the thread is executing. Descriptions
for thread commands can be found at
Section 7.5.6, “Examining Thread Information”. The value of this
column corresponds to the
COM_xxx
commands of the client/server protocol. See
Section 5.1.7, “Server Status Variables”
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.5.6, “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. The statement might be the one sent to the
server, or an innermost statement if the statement executes
other statements. For example, if a CALL
p1() statement executes a stored procedure
p1() , and the procedure is executing a
SELECT statement, the
Info value shows the
SELECT statement.
12.5.5.33. SHOW PROFILES SyntaxSHOW PROFILE [type [, type ] ... ]
[FOR QUERY n ]
[LIMIT row_count [OFFSET offset ]]
type :
ALL
| BLOCK IO
| CONTEXT SWITCHES
| CPU
| IPC
| MEMORY
| PAGE FAULTS
| SOURCE
| SWAPS
The SHOW PROFILES and
SHOW PROFILE statements display
profiling information that indicates resource usage for
statements executed during the course of the current session.
Profiling is controlled by the
profiling session variable,
which has a default value of 0 (OFF ).
Profiling is enabled by setting
profiling to 1 or
ON :
mysql> SET profiling = 1;
SHOW PROFILES displays a list of
the most recent statements sent to the master. The size of the
list is controlled by the
profiling_history_size session
variable, which has a default value of 15. The maximum value is
100. Setting the value to 0 has the practical effect of
disabling profiling.
All statements are profiled except SHOW
PROFILES and SHOW
PROFILE , so you will find neither of those statements
in the profile list. Malformed statements are profiled. For
example, SHOW PROFILING is an illegal
statement, and a syntax error occurs if you try to execute it,
but it will show up in the profiling list.
SHOW PROFILE displays detailed
information about a single statement. Without the FOR
QUERY n clause, the output
pertains to the most recently executed statement. If
FOR QUERY n is
included, SHOW PROFILE displays
information for statement n . The
values of n correspond to the
Query_ID values displayed by
SHOW PROFILES .
The LIMIT
row_count clause may be
given to limit the output to
row_count rows. If
LIMIT is given, OFFSET
offset may be added to
begin the output offset rows into the
full set of rows.
By default, SHOW PROFILE displays
Status and Duration
columns. The Status values are like the
State values displayed by
SHOW PROCESSLIST , althought there
might be some minor differences in interpretion for the two
statements for some status values (see
Section 7.5.6, “Examining Thread Information”).
Optional type values may be specified
to display specific additional types of information:
ALL displays all information
BLOCK IO displays counts for block input
and output operations
CONTEXT SWITCHES displays counts for
voluntary and involuntary context switches
CPU displays user and system CPU usage
times
IPC displays counts for messages sent and
received
MEMORY is not currently implemented
PAGE FAULTS displays counts for major and
minor page faults
SOURCE displays the names of functions
from the source code, together with the name and line number
of the file in which the function occurs
SWAPS displays swap counts
Profiling is enabled per session. When a session ends, its
profiling information is lost.
mysql> SELECT @@profiling;
+-------------+
| @@profiling |
+-------------+
| 0 |
+-------------+
1 row in set (0.00 sec)
mysql> SET profiling = 1;
Query OK, 0 rows affected (0.00 sec)
mysql> DROP TABLE IF EXISTS t1;
Query OK, 0 rows affected, 1 warning (0.00 sec)
mysql> CREATE TABLE T1 (id INT);
Query OK, 0 rows affected (0.01 sec)
mysql> SHOW PROFILES;
+----------+----------+--------------------------+
| Query_ID | Duration | Query |
+----------+----------+--------------------------+
| 0 | 0.000088 | SET PROFILING = 1 |
| 1 | 0.000136 | DROP TABLE IF EXISTS t1 |
| 2 | 0.011947 | CREATE TABLE t1 (id INT) |
+----------+----------+--------------------------+
3 rows in set (0.00 sec)
mysql> SHOW PROFILE;
+----------------------+----------+
| Status | Duration |
+----------------------+----------+
| checking permissions | 0.000040 |
| creating table | 0.000056 |
| After create | 0.011363 |
| query end | 0.000375 |
| freeing items | 0.000089 |
| logging slow query | 0.000019 |
| cleaning up | 0.000005 |
+----------------------+----------+
7 rows in set (0.00 sec)
mysql> SHOW PROFILE FOR QUERY 1;
+--------------------+----------+
| Status | Duration |
+--------------------+----------+
| query end | 0.000107 |
| freeing items | 0.000008 |
| logging slow query | 0.000015 |
| cleaning up | 0.000006 |
+--------------------+----------+
4 rows in set (0.00 sec)
mysql> SHOW PROFILE CPU FOR QUERY 2;
+----------------------+----------+----------+------------+
| Status | Duration | CPU_user | CPU_system |
+----------------------+----------+----------+------------+
| checking permissions | 0.000040 | 0.000038 | 0.000002 |
| creating table | 0.000056 | 0.000028 | 0.000028 |
| After create | 0.011363 | 0.000217 | 0.001571 |
| query end | 0.000375 | 0.000013 | 0.000028 |
| freeing items | 0.000089 | 0.000010 | 0.000014 |
| logging slow query | 0.000019 | 0.000009 | 0.000010 |
| cleaning up | 0.000005 | 0.000003 | 0.000002 |
+----------------------+----------+----------+------------+
7 rows in set (0.00 sec)
Note
Profiling is only partially functional on some architectures.
For values that depend on the getrusage()
system call, NULL is returned on systems
such as Windows that do not support the call. In addition,
profiling is per process and not per thread. This means that
activity on threads within the server other than your own may
affect the timing information that you see.
SHOW PROFILES and
SHOW PROFILE were added in MySQL
5.1.24 (but were not added to binary distributions by default
until 5.1.28).
You can also get profiling information from the
PROFILING table in
INFORMATION_SCHEMA . See
Section 20.26, “The INFORMATION_SCHEMA PROFILING Table”. For example, the following
queries produce the same result:
SHOW PROFILE FOR QUERY 2;
SELECT STATE, FORMAT(DURATION, 6) AS DURATION
FROM INFORMATION_SCHEMA.PROFILING
WHERE QUERY_ID = 2 ORDER BY SEQ;
12.5.5.34. SHOW SCHEDULER STATUS SyntaxSHOW SCHEDULER STATUS
This statement provides debugging information regarding the
Event Scheduler's state. It is supported only in
-debug builds of MySQL 5.1.11, and was
removed in 5.1.12 and subsequent releases.
Sample output is shown here:
+--------------------------------+---------------------+
| Name | Value |
+--------------------------------+---------------------+
| scheduler state | INITIALIZED |
| thread_id | NULL |
| scheduler last locked at | init_scheduler::313 |
| scheduler last unlocked at | init_scheduler::318 |
| scheduler waiting on condition | 0 |
| scheduler workers count | 0 |
| scheduler executed events | 0 |
| scheduler data locked | 0 |
| queue element count | 1 |
| queue data locked | 0 |
| queue data attempting lock | 0 |
| queue last locked at | create_event::218 |
| queue last unlocked at | create_event::222 |
| queue last attempted lock at | ::0 |
| queue waiting on condition | 0 |
| next activation at | 0-00-00 00:00:00 |
+--------------------------------+---------------------+
In MySQL 5.1.12 and later, this information can be obtained
using mysqladmin debug. (See
Section 4.5.2, “mysqladmin — Client for Administering a MySQL Server”.) For more information about
obtaining Event Scheduler status information, see
Section 19.4.5, “Event Scheduler Status”.
12.5.5.35. SHOW SLAVE HOSTS SyntaxSHOW SLAVE HOSTS
Displays a list of replication slaves currently registered with
the master. Only slaves started with the
--report-host=host_name
option are visible in this list.
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=host_name .
Note that this can differ from the machine name as
configured in the operating system.
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.
12.5.5.36. SHOW SLAVE STATUS SyntaxSHOW 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:
Replicate_Do_Table:
Replicate_Ignore_Table:
Replicate_Wild_Do_Table:
Replicate_Wild_Ignore_Table:
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
Master_SSL_Verify_Server_Cert: No
Last_IO_Errno: 0
Last_IO_Error:
Last_SQL_Errno: 0
Last_SQL_Error:
The following list describes the fields returned by
SHOW SLAVE STATUS . For additional
information about interpreting their meanings, see
Section 16.1.4.1, “Checking Replication Status”.
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 16.4.1, “Replication Implementation Details”.
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_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.
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.
Last_Errno , Last_Error
As of MySQL 5.1.20, these columns are aliases for
Last_SQL_Errno and
Last_SQL_Error . Before 5.1.20, they
indicate 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, the
error values also appear in the slave's error log.
Beginning with MySQL 5.1.37, and with MySQL Cluster NDB
6.2.17, MySQL Cluster NDB 6.3.23, and MySQL Cluster NDB
6.4.3: Issuing RESET MASTER
or RESET SLAVE resets the
values shown in these columns. (Bug#34654, Bug#44270)
Note
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.6.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.
Master_SSL_Allowed ,
Master_SSL_CA_File ,
Master_SSL_CA_Path ,
Master_SSL_Cert ,
Master_SSL_Cipher ,
Master_SSL_Key ,
Master_SSL_Verify_Server_Cert
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 ,
MASTER_SSL_KEY , and
MASTER_SSL_VERIFY_SERVER_CERT options to
the CHANGE MASTER TO
statement. See Section 12.6.2.1, “CHANGE MASTER TO Syntax”.
MASTER_SSL_VERIFY_SERVER_CERT was added
in MySQL 5.1.18.
Seconds_Behind_Master
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.
Last_IO_Errno ,
Last_IO_Error
The error number and error message of the last error that
caused the I/O thread to stop. An error number of 0 and
message of the empty string mean “no error.” If
the Last_IO_Error value is not empty, the
error values also appear in the slave's error log. These
columns were added in MySQL 5.1.20.
MySQL Cluster.
Beginning with MySQL Cluster NDB 6.2.17, 6.3.23, and
6.4.3: Issuing RESET MASTER
or RESET SLAVE resets the
values shown in these columns. This applies to MySQL
Cluster only. (Bug#34654)
Last_SQL_Errno ,
Last_SQL_Error
The error number and error message of the last error that
caused the SQL thread to stop. An error number of 0 and
message of the empty string mean “no error.” If
the Last_SQL_Error value is not empty,
the error values also appear in the slave's error log. These
columns were added in MySQL 5.1.20.
Example:
Last_SQL_Errno: 1051
Last_SQL_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.)
MySQL Cluster.
Beginning with MySQL Cluster NDB 6.2.17, 6.3.23, and
6.4.3: Issuing RESET MASTER
or RESET SLAVE resets the
values shown in these columns. This applies to MySQL
Cluster only. (Bug#34654)
12.5.5.37. SHOW STATUS SyntaxSHOW [GLOBAL | SESSION] STATUS
[LIKE 'pattern ' | WHERE expr ]
SHOW STATUS provides server
status information. This information also can be obtained using
the mysqladmin extended-status command. The
LIKE clause, if present, indicates
which variable names to match. The WHERE
clause can be given to select rows using more general
conditions, as discussed in Section 20.28, “Extensions to SHOW Statements”.
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.7, “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 |
+--------------------+----------+
With the GLOBAL modifier,
SHOW STATUS displays the status
values for all connections to MySQL. With
SESSION , it displays the status values for
the current connection. If no modifier is present, the default
is SESSION . LOCAL is a
synonym for SESSION .
Some status variables have only a global value. For these, you
get the same value for both GLOBAL and
SESSION . The scope for each status variable
is listed at Section 5.1.7, “Server Status Variables”.
Each invocation of the SHOW
STATUS statement uses an internal temporary table and
increments the global
Created_tmp_tables value.
MySQL Enterprise
Status variables provide valuable clues to the state of your
servers. For expert interpretation of the information provided
by status variables, subscribe to the MySQL Enterprise
Monitor. For more information, see
http://www.mysql.com/products/enterprise/advisors.html.
12.5.5.38. SHOW TABLE STATUS SyntaxSHOW TABLE STATUS [{FROM | IN} db_name ]
[LIKE 'pattern ' | WHERE expr ]
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.
The LIKE clause, if present,
indicates which table names to match. The
WHERE clause can be given to select rows
using more general conditions, as discussed in
Section 20.28, “Extensions to SHOW Statements”.
This statement also displays information about views.
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.
Version
The version number of the table's .frm
file.
Row_format
The row storage format (Fixed ,
Dynamic , Compressed ,
Redundant , Compact ).
The format of InnoDB tables is reported
as Redundant or
Compact . For the
Barracuda file format of the
InnoDB Plugin , the format may be
Compressed or Dynamic .
Rows
The number of rows. Some storage engines, such as
MyISAM , 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.
The Rows value is NULL
for tables in the INFORMATION_SCHEMA
database.
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.
Beginning with MySQL 5.1.24, this information is also shown
for InnoDB tables (previously, it was in
the Comment value).
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 partitioned tables, this value is only an estimate and
may not be absolutely correct. A more accurate method of
obtaining this information in such cases is to query the
INFORMATION_SCHEMA.PARTITIONS table, as
shown in this example:
SELECT SUM(DATA_FREE)
FROM INFORMATION_SCHEMA.PARTITIONS
WHERE TABLE_SCHEMA = 'mydb'
AND TABLE_NAME = 'mytable';
For more information, see
Section 20.19, “The INFORMATION_SCHEMA PARTITIONS Table”.
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.
Checksum
The live checksum value (if any).
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).
Before MySQL 5.1.24, free space for
InnoDB tables is reported in the comment.
As of 5.1.24, it is reported in the
Data_free column.
For MEMORY 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 NDBCLUSTER tables, the output
of this statement shows appropriate values for the
Avg_row_length and
Data_length columns, with the exception that
BLOB columns are not taken into
account. Prior to MySQL 5.1.21, the number of MySQL Cluster
replicas was shown in the Comment column as
number_of_replicas (Bug#11379).
For views, all the fields displayed by SHOW
TABLE STATUS are NULL except that
Name indicates the view name and
Comment says view .
12.5.5.39. SHOW TABLES SyntaxSHOW [FULL] TABLES [{FROM | IN} db_name ]
[LIKE 'pattern ' | WHERE expr ]
SHOW TABLES lists the
non-TEMPORARY tables in a given database. You
can also get this list using the mysqlshow
db_name command. The
LIKE clause, if present, indicates
which table names to match. The WHERE clause
can be given to select rows using more general conditions, as
discussed in Section 20.28, “Extensions to SHOW Statements”.
This statement also lists any views in the database. The
FULL modifier is supported such that
SHOW FULL TABLES displays a second output
column. Values for the second column are BASE
TABLE for a table and VIEW for a
view.
If you have no privileges for a base table or view, it does not
show up in the output from SHOW
TABLES or mysqlshow db_name.
12.5.5.40. SHOW TRIGGERS SyntaxSHOW TRIGGERS [{FROM | IN} db_name ]
[LIKE 'pattern ' | WHERE expr ]
SHOW TRIGGERS lists the triggers
currently defined for tables in a database (the default database
unless a FROM clause is given). This
statement requires the TRIGGER
privilege (prior to MySQL 5.1.22, it requires the
SUPER privilege). The
LIKE clause, if present, indicates
which table names to match and causes the statement to display
triggers for those tables. The WHERE clause
can be given to select rows using more general conditions, as
discussed in Section 20.28, “Extensions to SHOW Statements”.
For the trigger ins_sum as defined in
Section 19.3, “Using Triggers”, the output of this statement is as
shown here:
mysql> SHOW TRIGGERS LIKE 'acc%'\G
*************************** 1. row ***************************
Trigger: ins_sum
Event: INSERT
Table: account
Statement: SET @sum = @sum + NEW.amount
Timing: BEFORE
Created: NULL
sql_mode:
Definer: myname@localhost
character_set_client: latin1
collation_connection: latin1_swedish_ci
Database Collation: latin1_swedish_ci
character_set_client is the
session value of the
character_set_client system
variable when the trigger was created.
collation_connection is the
session value of the
collation_connection system
variable when the trigger was created. Database
Collation is the collation of the database with which
the trigger is associated. These columns were added in MySQL
5.1.21.
Note
When using a LIKE clause with
SHOW TRIGGERS , the expression
to be matched (expr ) is compared
with the name of the table on which the trigger is declared,
and not with the name of the trigger:
mysql> SHOW TRIGGERS LIKE 'ins%';
Empty set (0.01 sec)
A brief explanation of the columns in the output of this
statement is shown here:
Trigger
The name of the trigger.
Event
The event that causes trigger activation: one of
'INSERT' , 'UPDATE' , or
'DELETE' .
Table
The table for which the trigger is defined.
Statement
The statement to be executed when the trigger is activated.
This is the same as the text shown in the
ACTION_STATEMENT column of
INFORMATION_SCHEMA.TRIGGERS .
Timing
One of the two values 'BEFORE' or
'AFTER' .
Created
Currently, the value of this column is always
NULL .
sql_mode
The SQL mode in effect when the trigger executes.
Definer
The account that created the trigger.
See also Section 20.16, “The INFORMATION_SCHEMA TRIGGERS Table”.
12.5.5.41. SHOW VARIABLES SyntaxSHOW [GLOBAL | SESSION] VARIABLES
[LIKE 'pattern ' | WHERE expr ]
SHOW VARIABLES shows the values
of MySQL system variables. This information also can be obtained
using the mysqladmin variables command. The
LIKE clause, if present, indicates
which variable names to match. The WHERE
clause can be given to select rows using more general
conditions, as discussed in Section 20.28, “Extensions to SHOW Statements”.
This statement does not require any privilege. It requires only
the ability to connect to the server.
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.6, “Using System Variables”, and
Section 12.5.4, “SET Syntax”.
Partial output is shown here. The list of names and values may
be different for your server.
Section 5.1.4, “Server System Variables”, describes the meaning
of each variable, and Section 7.5.3, “Tuning Server Parameters”,
provides information about tuning them.
mysql> SHOW VARIABLES;
+---------------------------------+---------------------------+
| Variable_name | Value |
+---------------------------------+---------------------------+
| auto_increment_increment | 1 |
| auto_increment_offset | 1 |
| automatic_sp_privileges | ON |
| back_log | 50 |
| basedir | /home/jon/bin/mysql-5.1/ |
| binlog_cache_size | 32768 |
| bulk_insert_buffer_size | 8388608 |
| character_set_client | latin1 |
| character_set_connection | latin1 |
...
| max_user_connections | 0 |
| max_write_lock_count | 4294967295 |
| multi_range_count | 256 |
| myisam_data_pointer_size | 6 |
| myisam_max_sort_file_size | 2147483647 |
| myisam_recover_options | OFF |
| myisam_repair_threads | 1 |
| myisam_sort_buffer_size | 8388608 |
| ndb_autoincrement_prefetch_sz | 32 |
| ndb_cache_check_time | 0 |
| ndb_force_send | ON |
...
| time_zone | SYSTEM |
| timed_mutexes | OFF |
| tmp_table_size | 33554432 |
| tmpdir | |
| transaction_alloc_block_size | 8192 |
| transaction_prealloc_size | 4096 |
| tx_isolation | REPEATABLE-READ |
| updatable_views_with_limit | YES |
| version | 5.1.6-alpha-log |
| version_comment | Source distribution |
| version_compile_machine | i686 |
| version_compile_os | suse-linux |
| 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.
12.5.5.42. SHOW WARNINGS SyntaxSHOW 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 .
A related statement, SHOW ERRORS ,
shows only the errors. See Section 12.5.5.18, “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.8, “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 21.9.3.72, “mysql_warning_count() ”.
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.
You can set the sql_notes
session variable to 0 to cause Note -level
warnings not to be recorded.
12.5.6. Other Administrative Statements12.5.6.2. CACHE INDEX SyntaxCACHE INDEX
tbl_index_list [, tbl_index_list ] ...
IN key_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.
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.6.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.
FLUSH [NO_WRITE_TO_BINLOG | LOCAL]
flush_option [, flush_option ] ...
The FLUSH statement clears or
reloads various internal caches used by MySQL. To execute
FLUSH , you must have the
RELOAD privilege.
The RESET statement is similar to
FLUSH . See
Section 12.5.6.6, “RESET Syntax”.
flush_option can be any of the
following:
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 number or if you get
the error message Host
'host_name ' is blocked .
When more than
max_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 binary logging is
enabled, the sequence number of the binary log file is
incremented by one relative to the previous file. 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 ).
If the server is writing error output to a named file (for
example, if it was started with the
--log-error option),
FLUSH LOGS
causes it to rename the current error log file with a suffix
of -old and create a new empty log file.
No renaming occurs if the server is not writing to a named
file (for example, if it is writing errors to the console).
MASTER (DEPRECATED).
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.6.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 ,
CREATE USER ,
CREATE SERVER , and
INSTALL PLUGIN statements.
This memory is not released by the corresponding
REVOKE ,
DROP USER ,
DROP SERVER , and
UNINSTALL PLUGIN 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 (DEPRECATED).
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.6.2.5, “RESET SLAVE Syntax”.
STATUS
This option adds the current thread's session status
variable values to the global values and resets the session
values to zero. It also resets the counters for key caches
(default and named) to zero and sets
Max_used_connections to
the current number of open connections. This is something
you should use only when debugging a query. See
Section 1.7, “How to Report Bugs or Problems”.
{TABLE | TABLES}
[tbl_name [,
tbl_name ] ...]
When no tables are named, closes all open tables, forces all
tables in use to be closed, and flushes the query cache.
With one or more table names, flushes only the given tables.
FLUSH
TABLES also removes all query results from the
query cache, like the RESET QUERY CACHE
statement. No error occurs if a named table does not exist.
TABLES WITH READ LOCK
Closes all open tables and locks all tables for all
databases with a 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:
FLUSH TABLES WITH
READ LOCK does not prevent the server from
inserting rows into the log tables (see
Section 5.2.1, “Selecting General Query and Slow Query Log Output Destinations”).
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 12.5.1.3, “GRANT Syntax”.
By default, 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 .
See also Section 12.5.6.6, “RESET Syntax”, for information about how the
RESET statement is used with
replication.
The mysqladmin utility provides a
command-line interface to some flush operations, via the
flush-hosts , flush-logs ,
flush-privileges ,
flush-status , and
flush-tables commands.
KILL [CONNECTION | QUERY] 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
thread_id statement.
KILL allows the optional
CONNECTION or QUERY
modifier:
KILL
CONNECTION is the same as
KILL with no modifier: It
terminates the connection associated with the given
thread_id .
KILL QUERY
terminates the statement that the connection is currently
executing, but leaves the connection itself intact.
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.
Note
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.
Warning
Killing a REPAIR TABLE or
OPTIMIZE TABLE operation on
a MyISAM table results in a table that
is corrupted and unusable. Any reads or writes to such a
table fail until you optimize or repair it again (without
interruption).
12.5.6.5. LOAD INDEX INTO
CACHE SyntaxLOAD INDEX INTO CACHE
tbl_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. It is not supported for tables having user-defined
partitioning (see Section 18.5, “Restrictions and Limitations on Partitioning”.)
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 ... IGNORE LEAVES fails unless all indexes in a
table have the same block size. (Prior to MySQL 5.1.19, it fails
even without IGNORE LEAVES .) You can
determine index block sizes for a table by using
myisamchk -dv and checking the
Blocksize column.
RESET reset_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.5.6.3, “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.
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.
12.6. Replication Statements
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.
12.6.1. SQL Statements for Controlling Master Servers
This section discusses statements for managing master replication
servers. Section 12.6.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.5.5, “SHOW Syntax”.
12.6.1.1. PURGE BINARY LOGS SyntaxPURGE { BINARY | MASTER } LOGS
{ TO 'log_name ' | BEFORE datetime_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.2.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. 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.4, “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.
Prior to MySQL 5.1.24, PURGE BINARY LOGS TO
and PURGE BINARY LOGS BEFORE did not behave
in the same way (and neither one behaved correctly) when binary
log files listed in the .index file had
been removed from the system by some other means (such as using
rm on Linux). Beginning with MySQL 5.1.24,
both variants of the statement fail with an error in such cases.
(Bug#18199, Bug#18453) To handle such errors, edit the
.index file (which is a simple text file)
manually to ensure that it lists only the binary log files that
are actually present, then run again the
PURGE BINARY LOGS statement that
failed.
12.6.1.2. RESET MASTER SyntaxRESET 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.
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 16.1.1, “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.
12.6.1.3. SET sql_log_bin SyntaxSET sql_log_bin = {0|1}
Disables or enables binary logging for the current session
(sql_log_bin is a session
variable) if the client has the
SUPER privilege. The statement
fails with an error if the client does not have that privilege.
12.6.2. SQL Statements for Controlling Slave Servers
This section discusses statements for managing slave replication
servers. Section 12.6.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.5.5.36, “SHOW SLAVE STATUS Syntax”.
12.6.2.1. CHANGE MASTER TO SyntaxCHANGE MASTER TO master_def [, master_def ] ...
master_def :
MASTER_BIND = 'interface_name '
| MASTER_HOST = 'host_name '
| MASTER_USER = 'user_name '
| MASTER_PASSWORD = 'password '
| MASTER_PORT = port_num
| MASTER_CONNECT_RETRY = interval
| MASTER_HEARTBEAT_PERIOD = 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 '
| MASTER_SSL_VERIFY_SERVER_CERT = {0|1}
CHANGE MASTER TO changes the
parameters that the slave server uses for connecting to and
communicating with the master server. It also updates the
contents of the master.info and
relay-log.info files.
If you do not specify a given parameter, it keeps its old value,
except as indicated in the following discussion. 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
There is no need to specify the parameters that do not change.
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.
Note
Replication cannot use Unix socket files. You must be able
to connect to the master MySQL server using TCP/IP.
If you specify MASTER_HOST or
MASTER_PORT , the slave assumes that the
master server is different from before (even if you specify
a host or port value that is the same as the current value.)
In this case, the old values for the master binary log 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
MASTER_HOST at all. Setting this option
to an empty string causes START
SLAVE subsequently to fail. This issue is
addressed in MySQL 5.5. (Bug#28796)
MASTER_USER and
MASTER_PASSWORD are the user name and
password of the account to use for connecting to the master.
MASTER_SSL , MASTER_SSL_CA ,
MASTER_SSL_CAPATH ,
MASTER_SSL_CERT ,
MASTER_SSL_KEY ,
MASTER_SSL_CIPHER , and
MASTER_SSL_VERIFY_SERVER_CERT provide
information about using SSL for the connection. See
Section 5.5.7.3, “SSL Command Options”, and
Section 16.2.7, “Setting Up Replication Using SSL”.
MASTER_SSL_VERIFY_SERVER_CERT was added in
MySQL 5.1.18. These options can be changed even on slaves that
are compiled without SSL support. They are saved to the
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 16.1.3, “Replication and Binary Logging Options and Variables”.
The next two options (MASTER_BIND and
MASTER_HEARTBEAT_PERIOD ) are available in
MySQL Cluster NDB 6.3 and later, but are not supported in
mainline MySQL 5.1:
MASTER_BIND is for use on replication
slaves having multiple network interfaces, and determines
which of the slave's network interfaces is chosen for
connecting to the master. It is also possible to determine
which network interface is to be used in such cases by
starting the slave mysqld process with the
--master-bind option.
The ability to bind a replication slave to specific network
interface was added in MySQL Cluster NDB 6.3.4.
MASTER_HEARTBEAT_PERIOD is used to set
the interval in seconds between replication heartbeats.
Whenever the master's binlog is updated with an event, the
waiting period for the next heartbeat is reset.
interval is a decimal value
having the range 0 to 4294967 seconds and a resolution to
hundredths of a second; the smallest nonzero value is 0.001.
Heartbeats are sent by the master only if there are no
unsent events in the binlog file for a period longer than
interval .
Setting interval to 0 disables
heartbeats altogether. The default value for
interval is equal to the value of
slave_net_timeout divided
by 2.
Setting @@global.slave_net_timeout to a
value less than that of the current heartbeat interval
results in a warning being issued. The effect of issuing
RESET SLAVE on the heartbeat
interval is to reset it to the default value.
MASTER_HEARTBEAT_PERIOD was added in
MySQL Cluster NDB 6.3.4.
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. If you specify either of them, you
cannot specify RELAY_LOG_FILE or
RELAY_LOG_POS . If neither of
MASTER_LOG_FILE or
MASTER_LOG_POS are specified, the slave uses
the last coordinates of the slave SQL
thread before CHANGE MASTER
TO was issued. This ensures that there is no
discontinuity in replication, even if the slave SQL thread was
late compared to the slave I/O thread, when you merely want to
change, say, the password to use.
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; 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
it. After loading the snapshot into the slave, you can run
CHANGE MASTER TO
MASTER_LOG_FILE='log_name ',
MASTER_LOG_POS=log_pos on
the slave to specify the master binary log coodinates.
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 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. Use
SET GLOBAL relay_log_purge=0 for additional
safety. Then start the server without the
--log-bin option, Instead, use
the --replicate-same-server-id ,
--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.
The following table shows the maximum allowable length for the
string-valued options.
12.6.2.2. LOAD DATA FROM MASTER SyntaxLOAD 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 in versions 4.1
of MySQL and above. We will introduce a more advanced technique
(called “online backup”) in a future version. That
technique will have the additional advantage of working with
more storage engines.
For MySQL 5.1 and earlier, 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.4, “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.5.5.15, “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.
12.6.2.3. LOAD TABLE tbl_name FROM
MASTER SyntaxLOAD 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 in versions 4.1
of MySQL and above. We will introduce a more advanced technique
(called “online backup”) in a future version. That
technique will have the additional advantage of working with
more storage engines.
For MySQL 5.1 and earlier, 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.
12.6.2.4. MASTER_POS_WAIT() SyntaxSELECT 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.11.4, “Miscellaneous Functions”, for a full
description.
12.6.2.5. RESET SLAVE SyntaxRESET 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.
Note
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.
12.6.2.6. SET GLOBAL sql_slave_skip_counter SyntaxSET 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.
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.
Note
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.
12.6.2.7. START SLAVE SyntaxSTART 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
acknowledgement 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.5.5.36, “SHOW SLAVE STATUS Syntax”, and
Section 16.1.4.1, “Checking Replication Status”.
You can add IO_THREAD and
SQL_THREAD options to the statement to name
which of the threads to start.
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.
In old versions of MySQL (before 4.0.5), this statement was
called SLAVE START . This usage is still
accepted in MySQL 5.1 for backward compatibility,
but is deprecated.
12.6.2.8. STOP SLAVE SyntaxSTOP SLAVE [thread_type [, thread_type ] ... ]
thread_type : IO_THREAD | SQL_THREAD
Stops the slave threads. STOP
SLAVE requires the
SUPER privilege.
Like START SLAVE , this statement
may be used with the IO_THREAD and
SQL_THREAD options to name the thread or
threads to be stopped.
Note
The transactional behavior of STOP
SLAVE changed in MySQL 5.1.35. Previously, it took
effect immediately. Beginning with MySQL 5.1.35, it waits
until any current replication event group affecting one or
more non-transactional tables has finished executing (if there
is any such replication group), or until the user issues a
KILL QUERY or
KILL
CONNECTION statement. (Bug#319, Bug#38205)
In old versions of MySQL (before 4.0.5), this statement was
called SLAVE STOP . This usage is still
accepted in MySQL 5.1 for backward compatibility,
but is deprecated.
12.7. SQL Syntax for Prepared Statements
MySQL 5.1 provides support for server-side prepared
statements. This support takes advantage of the efficient
client/server binary protocol implemented in MySQL 4.1, 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 21.9.4, “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.
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 allows 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:
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 run time, 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.
A prepared statement is also global to the session. If you create a
prepared statement within a stored routine, it is not deallocated
when the stored routine ends.
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 ,
CALL ,
COMMIT , CREATE
INDEX , CREATE TABLE ,
DELETE ,
DO , DROP
INDEX , DROP TABLE ,
INSERT , RENAME
TABLE , REPLACE ,
SELECT ,
SET ,
UPDATE , and most
SHOW statements.
As of MySQL 5.1.10, the following additional statements are
supported:
ANALYZE TABLE
OPTIMIZE TABLE
REPAIR TABLE
As of MySQL 5.1.12, the following additional statements are
supported:
CACHE INDEX
CHANGE MASTER
CHECKSUM {TABLE | TABLES}
{CREATE | DROP} DATABASE
{CREATE | RENAME | DROP} USER
FLUSH {TABLE | TABLES | TABLES WITH READ LOCK | HOSTS | PRIVILEGES
| LOGS | STATUS | MASTER | SLAVE | DES_KEY_FILE | USER_RESOURCES}
GRANT
REVOKE
KILL
LOAD INDEX INTO CACHE
RESET {MASTER | SLAVE | QUERY CACHE}
SHOW BINLOG EVENTS
SHOW CREATE {PROCEDURE | FUNCTION | EVENT | TABLE | VIEW}
SHOW {AUTHORS | CONTRIBUTORS | WARNINGS | ERRORS}
SHOW {MASTER | BINARY} LOGS
SHOW {MASTER | SLAVE} STATUS
SLAVE {START | STOP}
INSTALL PLUGIN
UNINSTALL PLUGIN
Other statements are not yet supported.
Statements not allowed in SQL prepared statements are generally also
not permitted in stored routines. Any exceptions to this rule are
noted in Section 19.2, “Using Stored Routines (Procedures and Functions)”.
Placeholders can be used for the arguments of the
LIMIT clause when using prepared statements. See
Section 12.2.8, “SELECT Syntax”.
In prepared CALL statements used with
PREPARE and
EXECUTE , placeholder support for
OUT and INOUT parameters is
not available in MySQL 5.1. See Section 12.2.1, “CALL Syntax”,
for an example and a workaround. Placeholders can be used for
IN parameters regardless of version.
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 can be used within stored
procedures, but not in stored functions or triggers. However, a
cursor cannot be used for a dynamic statement that is prepared and
executed with PREPARE and
EXECUTE . The statement for a cursor
is checked at cursor creation time, so the statement cannot be
dynamic.
SQL syntax for prepared statements does not support multi-statements
(that is, multiple statements within a single string separated by
“; ” characters).
Before MySQL 5.1.17, prepared statements do not use the query cache.
As of 5.1.17, prepared statements use the query cache under the
conditions described in Section 7.5.5.1, “How the Query Cache Operates”.
To write C programs that use the CALL
SQL statement to execute stored procedures that contain prepared
statements, the CLIENT_MULTI_RESULTS flag must be
enabled. This is because each CALL
returns a result to indicate the call status, in addition to any
result sets that might be returned by statements executed within the
procedure.
CLIENT_MULTI_RESULTS can be enabled when you call
mysql_real_connect() , either
explicitly by passing the CLIENT_MULTI_RESULTS
flag itself, or implicitly by passing
CLIENT_MULTI_STATEMENTS (which also enables
CLIENT_MULTI_RESULTS ). For additional
information, see Section 12.2.1, “CALL Syntax”.
PREPARE stmt_name FROM preparable_stmt
The PREPARE statement prepares a
statement and assigns it a name,
stmt_name , by which to refer to the
statement later. Statement names are not case sensitive.
preparable_stmt is either a string
literal or a user variable that contains the text of the
statement. The text must represent a single SQL 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 quotes, 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.
A prepared statement is executed with
EXECUTE and released with
DEALLOCATE PREPARE .
The scope of a prepared statement is the session within which it
is created. Other sessions cannot see it.
For examples, see
Section 12.7, “SQL Syntax for Prepared Statements”.
EXECUTE stmt_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.7, “SQL Syntax for Prepared Statements”.
12.7.4. Automatic Prepared Statement Repreparation
As of MySQL 5.1.25, metadata changes to tables or views referred
to by prepared statements are detected and cause automatic
repreparation of the statement when it is next executed. This
applies to prepared statements processed at the SQL level (using
the PREPARE statement) and those
processed using the binary client-server protocol (using the
mysql_stmt_prepare() C API
function).
Metadata changes occur for DDL statements such as those that
create, drop, alter, rename, or truncate tables, or that analyze,
optimize, or repair tables. Repreparation also occurs after
referenced tables or views are flushed from the table definition
cache, either implicitly to make room for new entries in the
cache, or explicitly due to
FLUSH TABLES .
Repreparation is automatic, but to the extent that it occurs,
performance of prepared statements is diminished.
When a statement is reprepared, the default database and SQL mode
that were in effect for the original preparation are used.
Table content changes (for example, with
INSERT or
UPDATE ) do not cause repreparation,
nor do SELECT statements.
An incompatibility with previous versions of MySQL is that a
prepared statement may return a different set of columns or
different column types from one execution to the next. For
example, if the prepared statement is SELECT * FROM
t1 , altering t1 to contain a
different number of columns causes the next execution to return a
number of columns different from the previous execution.
Older versions of the client library cannot handle this change in
behavior. For applications that use prepared statements with a
server that performs automatic repreparation, an upgrade to the
new client library is strongly recommended.
The Com_stmt_reprepare status variable tracks
the number of repreparations.
12.8. MySQL Compound-Statement Syntax
This section describes the syntax for the
BEGIN ... END
compound statement and other statements that can be used in the body
of stored programs: Stored procedures and functions, triggers, and
events. These objects are defined in terms of of SQL code that is
stored on the server for later invocation (see
Chapter 19, Stored Programs and Views).
12.8.1. BEGIN ... END
Compound Statement Syntax[begin_label :] BEGIN
[statement_list ]
END [end_label ]
BEGIN ... END
syntax is used for writing compound statements, which can appear
within stored programs. A compound statement can contain multiple
statements, enclosed by the BEGIN and
END keywords.
statement_list represents a list of one
or more statements, each terminated by a semicolon
(; ) statement delimiter.
statement_list is optional, which means
that the empty compound statement (BEGIN END )
is legal.
Use of multiple statements requires that a client is able to send
statement strings containing the ; statement
delimiter. This is handled in the mysql
command-line client with the delimiter command.
Changing the ; end-of-statement delimiter (for
example, to // ) allows ; to
be used in a program body. For an example, see
Section 19.1, “Defining Stored Programs”.
A BEGIN ...
END block can be labeled. Labels follow these rules:
end_label cannot be given unless
begin_label is also present.
If both begin_label and
end_label are present, they must be
the same.
Labels can be up to 16 characters long.
Labels are also allowed for the
LOOP ,
REPEAT ,
and
WHILE
statements.
The optional [NOT] ATOMIC clause is not
supported. This means that no transactional savepoint is set at
the start of the instruction block and the
BEGIN clause used in this context has no effect
on the current transaction.
The DECLARE statement is used to
define various items local to a program:
The SIGNAL and RESIGNAL
statements are not supported until MySQL 5.5.
DECLARE is allowed only inside a
BEGIN ... END
compound statement and must be at its start, before any other
statements.
Declarations must follow a certain order. Cursors must be declared
before declaring handlers, and variables and conditions must be
declared before declaring either cursors or handlers.
12.8.3. Variables in Stored Programs
You may declare and use variables within stored programs.
12.8.3.1. DECLARE for Local VariablesDECLARE var_name [, var_name ] ... type [DEFAULT value ]
This statement is used to declare local variables within stored
programs. To provide a default value for the variable, include a
DEFAULT clause. The value can be specified as
an expression; it need not be a constant. If the
DEFAULT clause is missing, the initial value
is NULL .
Local variables are treated like stored routine parameters with
respect to data type and overflow checking. See
Section 12.1.15, “CREATE PROCEDURE and
CREATE FUNCTION Syntax”.
Local variable names are not case sensitive.
The scope of a local variable is within the
BEGIN ...
END block where it is declared. The variable can be
referred to in blocks nested within the declaring block, except
those blocks that declare a variable with the same name.
12.8.3.2. Variable SET StatementSET var_name = expr [, var_name = expr ] ...
The SET statement in stored programs is an
extended version of the general
SET
statement (see Section 12.5.4, “SET Syntax”). Each
var_name may refer to a local
variable declared inside a stored program, a system variable, or
a user-defined variable.
The SET statement in stored programs is
implemented as part of the pre-existing
SET
syntax. This allows an extended syntax of SET a=x, b=y,
... where different variable types (locally declared
variables, global and session system variables, user-defined
variables) can be mixed. This also allows combinations of local
variables and some options that make sense only for system
variables; in that case, the options are recognized but ignored.
12.8.3.3. SELECT ... INTO
StatementSELECT col_name [, col_name ] ...
INTO var_name [, var_name ] ...
table_expr
SELECT ...
INTO syntax enables selected columns to be stored
directly into variables. The query should return a single row.
If the query returns no rows, a warning with error code 1329
occurs (No data ), and the variable values
remain unchanged. If the query returns multiple rows, error 1172
occurs (Result consisted of more than one
row ). If it is possible that the statement may
retrieve multiple rows, you can use LIMIT 1
to limit the result set to a single row.
SELECT id,data INTO x,y FROM test.t1 LIMIT 1;
User variable names are not case sensitive. See
Section 8.4, “User-Defined Variables”.
In the context of SELECT
... INTO statements that occur as part of events
executed by the Event Scheduler, diagnostics messages (not only
errors, but also warnings) are written to the error log, and, on
Windows, to the application event log. For additional
information, see Section 19.4.5, “Event Scheduler Status”.
12.8.3.4. Scope and Resolution of Local Variables
The scope of a local variable is within the
BEGIN ...
END block where it is declared. The variable can be
referred to in blocks nested within the declaring block, except
those blocks that declare a variable with the same name.
Local variables are within scope only during stored routine
execution, so references to them are disallowed within prepared
statements because those are global to the current session and
the variables might have gone out of scope when the statement is
executed. For example, SELECT ... INTO
local_var cannot be used as
a prepared statement.
Local variable names should not be the same as column names. If
an SQL statement, such as a
SELECT ...
INTO statement, contains a reference to a column and a
declared local variable with the same name, MySQL currently
interprets the reference as the name of a variable. For example,
in the following statement, xname is
interpreted as a reference to the xname
variable rather than the
xname column:
CREATE PROCEDURE sp1 (x VARCHAR(5))
BEGIN
DECLARE xname VARCHAR(5) DEFAULT 'bob';
DECLARE newname VARCHAR(5);
DECLARE xid INT;
SELECT xname,id INTO newname,xid
FROM table1 WHERE xname = xname;
SELECT newname;
END;
When this procedure is called, the newname
variable returns the value 'bob' regardless
of the value of the table1.xname column.
See also Section D.1, “Restrictions on Stored Routines, Triggers, and Events”.
12.8.4. Conditions and Handlers
Certain conditions may require specific handling. These conditions
can relate to errors or warnings, as well as to general flow
control inside a stored program.
12.8.4.1. DECLARE for ConditionsDECLARE condition_name CONDITION FOR condition_value
condition_value :
SQLSTATE [VALUE] sqlstate_value
| mysql_error_code
The DECLARE ... CONDITION statement defines a
named error condition. It specifies a condition that needs
specific handling and associates a name with that condition. The
name can be referred to in a subsequence DECLARE ...
HANDLER statement. See
Section 12.8.4.2, “DECLARE for Handlers”.
A condition_value for
DECLARE ... CONDITION can be an SQLSTATE
value (a 5-character string literal) or a MySQL error code (a
number). You should not use SQLSTATE value
'00000' or MySQL error code 0, because those
indicate sucess rather than an error condition. For a list of
SQLSTATE values and MySQL error codes, see
Section B.3, “Server Error Codes and Messages”.
12.8.4.2. DECLARE for HandlersDECLARE handler_type HANDLER
FOR condition_value [, condition_value ] ...
statement
handler_type :
CONTINUE
| EXIT
| UNDO
condition_value :
SQLSTATE [VALUE] sqlstate_value
| condition_name
| SQLWARNING
| NOT FOUND
| SQLEXCEPTION
| mysql_error_code
The DECLARE ... HANDLER statement specifies
handlers that each may deal with one or more conditions. If one
of these conditions occurs, the specified
statement is executed.
statement can be a simple statement
(for example, SET var_name =
value ), or it can be a
compound statement written using BEGIN and
END (see Section 12.8.1, “BEGIN ... END
Compound Statement Syntax”).
For a CONTINUE handler, execution of the
current program continues after execution of the handler
statement. For an EXIT handler, execution
terminates for the
BEGIN ...
END compound statement in which the handler is
declared. (This is true even if the condition occurs in an inner
block.) The UNDO handler type statement is
not supported.
If a condition occurs for which no handler has been declared,
the default action is EXIT .
A condition_value for
DECLARE ... HANDLER can be any of the
following values:
An SQLSTATE value (a 5-character string literal) or a MySQL
error code (a number). You should not use SQLSTATE value
'00000' or MySQL error code 0, because
those indicate sucess rather than an error condition. For a
list of SQLSTATE values and MySQL error codes, see
Section B.3, “Server Error Codes and Messages”.
A condition name previously specified with DECLARE
... CONDITION . See
Section 12.8.4.1, “DECLARE for Conditions”.
SQLWARNING is shorthand for the class of
SQLSTATE values that begin with '01' .
NOT FOUND is shorthand for the class of
SQLSTATE values that begin with '02' .
This is relevant only the context of cursors and is used to
control what happens when a cursor reaches the end of a data
set. If no more rows are available, a No Data condition
occurs with SQLSTATE value 02000. To detect this condition,
you can set up a handler for it (or for a NOT
FOUND condition). An example is shown in
Section 12.8.5, “Cursors”. This condition also occurs for
SELECT ... INTO
var_list statements
that retrieve no rows.
SQLEXCEPTION is shorthand for the class
of SQLSTATE values that do not begin with
'00' , '01' , or
'02' .
Example:
mysql> CREATE TABLE test.t (s1 INT, PRIMARY KEY (s1));
Query OK, 0 rows affected (0.00 sec)
mysql> delimiter //
mysql> CREATE PROCEDURE handlerdemo ()
-> BEGIN
-> DECLARE CONTINUE HANDLER FOR SQLSTATE '23000' SET @x2 = 1;
-> SET @x = 1;
-> INSERT INTO test.t VALUES (1);
-> SET @x = 2;
-> INSERT INTO test.t VALUES (1);
-> SET @x = 3;
-> END;
-> //
Query OK, 0 rows affected (0.00 sec)
mysql> CALL handlerdemo()//
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT @x//
+------+
| @x |
+------+
| 3 |
+------+
1 row in set (0.00 sec)
The example associates a handler with SQLSTATE value
'23000' , which occurs for a duplicate-key
error. Notice that @x is 3
after the procedure executes, which shows that execution
continued to the end of the procedure. If the DECLARE
... HANDLER statement had not been present, MySQL
would have taken the default path (EXIT )
after the second INSERT failed
due to the PRIMARY KEY constraint, and
SELECT @x would have returned
2 .
If you want to ignore a condition, you can declare a
CONTINUE handler for it and associate it with
an empty block. For example:
DECLARE CONTINUE HANDLER FOR SQLWARNING BEGIN END;
The statement associated with a handler cannot use
ITERATE
or
LEAVE
to refer to labels for blocks that enclose the handler
declaration. That is, the scope of a block label does not
include the code for handlers declared within the block.
Consider the following example, where the
REPEAT
block has a label of retry :
CREATE PROCEDURE p ()
BEGIN
DECLARE i INT DEFAULT 3;
retry:
REPEAT
BEGIN
DECLARE CONTINUE HANDLER FOR SQLWARNING
BEGIN
ITERATE retry; # illegal
END;
END;
IF i < 0 THEN
LEAVE retry; # legal
END IF;
SET i = i - 1;
UNTIL FALSE END REPEAT;
END;
The label is in scope for the
IF
statement within the block. It is not in scope for the
CONTINUE handler, so the reference there is
invalid and results in an error:
ERROR 1308 (42000): LEAVE with no matching label: retry
To avoid using references to outer labels in handlers, you can
use these strategies:
To leave the block, use an EXIT handler:
DECLARE EXIT HANDLER FOR SQLWARNING BEGIN END;
To iterate, set a status variable in the handler that can be
checked in the enclosing block to determine whether the
handler was invoked. The following example uses the variable
done for this purpose:
CREATE PROCEDURE p ()
BEGIN
DECLARE i INT DEFAULT 3;
DECLARE done INT DEFAULT FALSE;
retry:
REPEAT
BEGIN
DECLARE CONTINUE HANDLER FOR SQLWARNING
BEGIN
SET done = TRUE;
END;
END;
IF NOT done AND i < 0 THEN
LEAVE retry;
END IF;
SET i = i - 1;
UNTIL FALSE END REPEAT;
END;
Cursors are supported inside stored routines, triggers, and
events. The syntax is as in embedded SQL. Cursors in MySQL have
these properties:
Cursors must be declared before declaring handlers. Variables and
conditions must be declared before declaring either cursors or
handlers.
Example:
CREATE PROCEDURE curdemo()
BEGIN
DECLARE done INT DEFAULT 0;
DECLARE a CHAR(16);
DECLARE b,c INT;
DECLARE cur1 CURSOR FOR SELECT id,data FROM test.t1;
DECLARE cur2 CURSOR FOR SELECT i FROM test.t2;
DECLARE CONTINUE HANDLER FOR NOT FOUND SET done = 1;
OPEN cur1;
OPEN cur2;
REPEAT
FETCH cur1 INTO a, b;
FETCH cur2 INTO c;
IF NOT done THEN
IF b < c THEN
INSERT INTO test.t3 VALUES (a,b);
ELSE
INSERT INTO test.t3 VALUES (a,c);
END IF;
END IF;
UNTIL done END REPEAT;
CLOSE cur1;
CLOSE cur2;
END
12.8.5.1. DECLARE for CursorsDECLARE cursor_name CURSOR FOR select_statement
This statement declares a cursor. Multiple cursors may be
declared in a stored program, but each cursor in a given block
must have a unique name.
The SELECT statement cannot have
an INTO clause.
For information available through
SHOW statements, it is possible
in many cases to obtain equivalent information by using a cursor
with an INFORMATION_SCHEMA table.
12.8.5.2. Cursor OPEN StatementOPEN cursor_name
This statement opens a previously declared cursor.
12.8.5.3. Cursor FETCH StatementFETCH cursor_name INTO var_name [, var_name ] ...
This statement fetches the next row (if a row exists) using the
specified open cursor, and advances the cursor pointer.
If no more rows are available, a No Data condition occurs with
SQLSTATE value 02000. To detect this condition, you can set up a
handler for it (or for a NOT FOUND
condition). An example is shown in Section 12.8.5, “Cursors”.
12.8.5.4. Cursor CLOSE StatementCLOSE cursor_name
This statement closes a previously opened cursor.
If not closed explicitly, a cursor is closed at the end of the
compound statement in which it was declared.
12.8.6. Flow Control Constructs
MySQL supports the
IF ,
CASE ,
ITERATE ,
LEAVE
LOOP ,
WHILE ,
and
REPEAT
constructs for flow control within stored programs.
Many of these constructs contain other statements, as indicated by
the grammar specifications in the following sections. Such
constructs may be nested. For example, an
IF
statement might contain a
WHILE
loop, which itself contains a
CASE
statement.
FOR loops are not supported.
IF search_condition THEN statement_list
[ELSEIF search_condition THEN statement_list ] ...
[ELSE statement_list ]
END IF
IF
implements a basic conditional construct. If the
search_condition evaluates to true,
the corresponding SQL statement list is executed. If no
search_condition matches, the
statement list in the ELSE clause is
executed. Each statement_list
consists of one or more statements.
An IF ... END IF block, like all other
flow-control blocks used within stored programs, must be
terminated with a semicolon, as shown in this example:
DELIMITER //
CREATE FUNCTION SimpleCompare(n INT, m INT)
RETURNS VARCHAR(20)
BEGIN
DECLARE s VARCHAR(20);
IF n > m THEN SET s = '>';
ELSEIF n = m THEN SET s = '=';
ELSE SET s = '<';
END IF;
SET s = CONCAT(n, ' ', s, ' ', m);
RETURN s;
END //
DELIMITER ;
As with other flow-control constructs, IF ... END
IF blocks may be nested within other flow-control
constructs, including other
IF
statements. Each
IF must
be terminated by its own END IF followed by a
semicolon. You can use indentation to make nested flow-control
blocks more easily readable by humans (although this is not
required by MySQL), as shown here:
DELIMITER //
CREATE FUNCTION VerboseCompare (n INT, m INT)
RETURNS VARCHAR(50)
BEGIN
DECLARE s VARCHAR(50);
IF n = m THEN SET s = 'equals';
ELSE
IF n > m THEN SET s = 'greater';
ELSE SET s = 'less';
END IF;
SET s = CONCAT('is ', s, ' than');
END IF;
SET s = CONCAT(n, ' ', s, ' ', m, '.');
RETURN s;
END //
DELIMITER ;
In this example, the inner
IF is
evaluated only if n is not equal to
m .
CASE case_value
WHEN when_value THEN statement_list
[WHEN when_value THEN statement_list ] ...
[ELSE statement_list ]
END CASE
Or:
CASE
WHEN search_condition THEN statement_list
[WHEN search_condition THEN statement_list ] ...
[ELSE statement_list ]
END CASE
The
CASE
statement for stored programs implements a complex conditional
construct. If a search_condition
evaluates to true, the corresponding SQL statement list is
executed. If no search condition matches, the statement list in
the ELSE clause is executed. Each
statement_list consists of one or
more statements.
If no when_value or
search_condition matches the value
tested and the
CASE
statement contains no ELSE clause, a
Case not found for CASE statement error
results.
Each statement_list consists of one
or more statements; an empty
statement_list is not allowed. To
handle situations where no value is matched by any
WHEN clause, use an ELSE
containing an empty
BEGIN ...
END block, as shown in this example:
DELIMITER |
CREATE PROCEDURE p()
BEGIN
DECLARE v INT DEFAULT 1;
CASE v
WHEN 2 THEN SELECT v;
WHEN 3 THEN SELECT 0;
ELSE
BEGIN
END;
END CASE;
END;
|
(The indentation used here in the ELSE clause
is for purposes of clarity only, and is not otherwise
significant.)
Note
The syntax of the
CASE
statement used inside stored programs
differs slightly from that of the SQL
CASE
expression described in
Section 11.3, “Control Flow Functions”. The
CASE
statement cannot have an ELSE NULL clause,
and it is terminated with END CASE instead
of END .
[begin_label :] LOOP
statement_list
END LOOP [end_label ]
LOOP
implements a simple loop construct, enabling repeated execution
of the statement list, which consists of one or more statements,
each terminated by a semicolon (; ) statement
delimiter. The statements within the loop are repeated until the
loop is exited; usually this is accomplished with a
LEAVE
statement.
A LOOP
statement can be labeled. See Section 12.8.1, “BEGIN ... END
Compound Statement Syntax” for
the rules regarding label use.
12.8.6.4. LEAVE
StatementLEAVE label
This statement is used to exit the flow control construct that
has the given label. It can be used within
BEGIN ...
END or loop constructs
(LOOP ,
REPEAT ,
WHILE ).
12.8.6.5. ITERATE
StatementITERATE label
ITERATE
can appear only within
LOOP ,
REPEAT ,
and
WHILE
statements.
ITERATE
means “do the loop again.”
Example:
CREATE PROCEDURE doiterate(p1 INT)
BEGIN
label1: LOOP
SET p1 = p1 + 1;
IF p1 < 10 THEN ITERATE label1; END IF;
LEAVE label1;
END LOOP label1;
SET @x = p1;
END
12.8.6.6. REPEAT
Statement[begin_label :] REPEAT
statement_list
UNTIL search_condition
END REPEAT [end_label ]
The statement list within a
REPEAT
statement is repeated until the
search_condition is true. Thus, a
REPEAT
always enters the loop at least once.
statement_list consists of one or
more statements, each terminated by a semicolon
(; ) statement delimiter.
A
REPEAT
statement can be labeled. See Section 12.8.1, “BEGIN ... END
Compound Statement Syntax” for
the rules regarding label use.
Example:
mysql> delimiter //
mysql> CREATE PROCEDURE dorepeat(p1 INT)
-> BEGIN
-> SET @x = 0;
-> REPEAT SET @x = @x + 1; UNTIL @x > p1 END REPEAT;
-> END
-> //
Query OK, 0 rows affected (0.00 sec)
mysql> CALL dorepeat(1000)//
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT @x//
+------+
| @x |
+------+
| 1001 |
+------+
1 row in set (0.00 sec)
12.8.6.7. WHILE
Statement[begin_label :] WHILE search_condition DO
statement_list
END WHILE [end_label ]
The statement list within a
WHILE
statement is repeated as long as the
search_condition is true.
statement_list consists of one or
more statements.
A
WHILE
statement can be labeled. See Section 12.8.1, “BEGIN ... END
Compound Statement Syntax” for
the rules regarding label use.
Example:
CREATE PROCEDURE dowhile()
BEGIN
DECLARE v1 INT DEFAULT 5;
WHILE v1 > 0 DO
...
SET v1 = v1 - 1;
END WHILE;
END
RETURN expr
The RETURN statement terminates
execution of a stored function and returns the value
expr to the function caller. There must
be at least one RETURN statement in
a stored function. There may be more than one if the function has
multiple exit points.
This statement is not used in stored procedures, triggers, or
events.
|
|