|
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_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 as of MySQL 5.0.2.
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.3, “SHOW CHARACTER SET Syntax”, and
Section 12.5.5.4, “SHOW COLLATION Syntax”, for more information.
The database name can be omitted, in which case the statement
applies to the default database.
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 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 .
As of MySQL 5.0.3, 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 18.5, “Binary Logging of Stored Programs”.
12.1.3. 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 .
As of MySQL 5.0.3, you must have the ALTER
ROUTINE privilege for the procedure. (That privilege is
granted automatically to the procedure creator.)
12.1.4. ALTER TABLE SyntaxALTER [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_type ]
| ADD [CONSTRAINT [symbol ]] PRIMARY KEY
[index_type ] (index_col_name ,...) [index_type ]
| ADD [CONSTRAINT [symbol ]]
UNIQUE [INDEX|KEY] [index_name ]
[index_type ] (index_col_name ,...) [index_type ]
| ADD [FULLTEXT|SPATIAL] [INDEX|KEY] [index_name ]
(index_col_name ,...) [index_type ]
| 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
index_col_name :
col_name [(length )] [ASC | DESC]
index_type :
USING {BTREE | HASH | RTREE}
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.10, “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.37, “SHOW WARNINGS Syntax”.
If you use ALTER TABLE to change a
column specification but DESCRIBE
tbl_name indicates that your
column was not changed, it is possible that MySQL ignored your
modification for one of the reasons described in
Section 12.1.10.1, “Silent Column Specification Changes”.
In most cases, ALTER TABLE works by
making a temporary copy of the original table. The alteration is
performed on the copy, and then the original table is deleted and
the new one is renamed. While ALTER
TABLE is executing, the original table is readable by
other sessions. Updates and writes to the table are stalled until
the new table is ready, and then are automatically redirected to
the new table without any failed updates. The temporary table is
created in the database directory of the new table. This can be
different from the database directory of the original table if
ALTER TABLE is renaming the table
to a different database.
If you use ALTER TABLE
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.20, “RENAME TABLE Syntax”.) Any privileges
granted specifically for the renamed table are not migrated to the
new name. They must be changed manually.
If you use any option to ALTER
TABLE other than RENAME , MySQL always
creates a temporary table, even if the data wouldn't strictly need
to be copied (such as when you change the name of a column). For
MyISAM tables, you can speed up the index
re-creation operation (which is the slowest part of the alteration
process) by setting the
myisam_sort_buffer_size system
variable to a high value.
For information on troubleshooting ALTER
TABLE , see Section B.5.7.1, “Problems with ALTER TABLE ”.
To use ALTER TABLE , you need
ALTER ,
INSERT , and
CREATE privileges for the
table.
IGNORE is a MySQL extension to standard
SQL. It controls how ALTER
TABLE works if there are duplicates on unique keys
in the new table or if warnings occur when strict mode is
enabled. If IGNORE is not specified, the
copy is aborted and rolled back if duplicate-key errors occur.
If IGNORE is specified, only the first row
is used of rows with duplicates on a unique key, The other
conflicting rows are deleted. Incorrect values are truncated
to the closest matching acceptable value.
table_option signifies a table
option of the kind that can be used in the
CREATE TABLE statement, such as
ENGINE , AUTO_INCREMENT ,
or AVG_ROW_LENGTH .
(Section 12.1.10, “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.7, “Server SQL Modes”.
As of MySQL 5.0.23, 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 , you can use ALTER TABLE
... AUTO_INCREMENT =
value as of MySQL 5.0.3,
but if the value is less than the current maximum
value in the column, no error occurs and the current sequence
value is not changed.
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.10, “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.7, “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.15, “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.8, “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.18, “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. The same is true for
BDB tables that contain a user-defined
PRIMARY KEY .
If you use ALTER TABLE on a
MyISAM table, all nonunique indexes are
created in a separate batch (as for
REPAIR TABLE ). This should make
ALTER TABLE much faster when
you have many indexes.
This feature can be activated explicitly for a
MyISAM table. ALTER TABLE ...
DISABLE KEYS tells MySQL to stop updating nonunique
indexes. ALTER TABLE ... ENABLE KEYS then
should be used to re-create missing indexes. MySQL does this
with a special algorithm that is much faster than inserting
keys one by one, so disabling keys before performing bulk
insert operations should give a considerable speedup. Using
ALTER TABLE ... DISABLE KEYS requires the
INDEX privilege in addition to
the privileges mentioned earlier.
While the nonunique indexes are disabled, they are ignored for
statements such as SELECT and
EXPLAIN that otherwise would
use them.
If ALTER TABLE for an
InnoDB table results in changes to column
values (for example, because a column is truncated),
InnoDB 's FOREIGN KEY
constraint checks do not notice possible violations caused by
changing the values.
The FOREIGN KEY and
REFERENCES clauses are supported by the
InnoDB storage engine, which implements
ADD [CONSTRAINT [symbol ]]
FOREIGN KEY (...) REFERENCES ... (...) . See
Section 13.2.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.10, “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.2.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.2.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 3
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 ).
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 20.8.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);
Note that we indexed c (as a PRIMARY
KEY ) because AUTO_INCREMENT columns
must be indexed, and also that we declare c as
NOT NULL because primary key columns cannot be
NULL .
When you add an AUTO_INCREMENT column, column
values are filled in with sequence numbers automatically. For
MyISAM tables, you can set the first sequence
number by executing SET
INSERT_ID=value before
ALTER TABLE or by using the
AUTO_INCREMENT=value
table option. See Section 5.1.4, “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.5. 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.12, “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.0.52, ALTER VIEW is allowed only
to the original definer or users with the
SUPER privilege.
This statement was added in MySQL 5.0.1. The
DEFINER and SQL SECURITY
clauses may be used as of MySQL 5.0.16 to specify the security
context to be used when checking access privileges at view
invocation time. For details, see Section 12.1.12, “CREATE VIEW Syntax”.
12.1.6. 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 as of MySQL 5.0.2.
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 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.7. CREATE FUNCTION Syntax
The CREATE FUNCTION statement is
used to create stored functions and user-defined functions (UDFs):
12.1.8. CREATE INDEX SyntaxCREATE [UNIQUE|FULLTEXT|SPATIAL] INDEX index_name
[index_type ]
ON tbl_name (index_col_name ,...)
[index_type ]
index_col_name :
col_name [(length )] [ASC | DESC]
index_type :
USING {BTREE | HASH | RTREE}
CREATE INDEX is mapped to an
ALTER TABLE statement to create
indexes. See Section 12.1.4, “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.10, “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 can be given as described
later in this section.
The statement shown here creates an index using the first 10
characters of the name column:
CREATE INDEX part_of_name ON customer (name(10));
If names in the column usually differ in the first 10 characters,
this index should not be much slower than an index created from
the entire name column. Also, using column
prefixes for indexes can make the index file much smaller, which
could save a lot of disk space and might also speed up
INSERT operations.
Prefix support and lengths of prefixes (where supported) are
storage engine dependent. For example, a prefix can be up to 1000
bytes long for MyISAM tables, and 767 bytes for
InnoDB tables. The
NDBCLUSTER storage engine does not support
prefixes (see
Section 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.
A UNIQUE index creates a constraint such that
all values in the index must be distinct. An error occurs if you
try to add a new row with a key value that matches an existing
row. This constraint does not apply to NULL
values except for the BDB storage engine. For
other engines, a UNIQUE index 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 , BDB , and
ARCHIVE storage engines support spatial columns
such as (POINT and GEOMETRY .
(Section 11.12, “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.0, the full width of each column is
indexed by default, but column prefix lengths are allowed.
However, as of MySQL 5.0.40, the length is not displayed in
SHOW CREATE TABLE output.
mysqldump uses that statement. As of that
version, if a table with SPATIAL indexes
containing prefixed columns is dumped and reloaded, the index
is created with no prefixes. (The full column width of each
column is indexed.)
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.0:
You can add an index on a column that can have
NULL values only if you are using the
MyISAM , InnoDB ,
BDB , or MEMORY storage
engine.
You can add an index on a BLOB
or TEXT column only if you are
using the MyISAM , BDB ,
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.
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.0.60, the index_type option can
be given only before the ON
tbl_name clause. Use of the
option in this position is deprecated as of 5.0.60; support for it
is to be dropped in a future MySQL release. As of 5.0.60, the
option should be given following the index column list. If an
index_type option is given in both the earlier
and later positions, the final option applies.
12.1.9. 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 21.2, “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.3, “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.
As of MySQL 5.0.3, 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 18.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 18.5, “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 18.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 ).
Note
Before MySQL 5.0.10, stored functions created with
CREATE FUNCTION must not contain
references to tables, with limited exceptions. They may include
some SET
statements that contain table references, for example
SET a:= (SELECT MAX(id) FROM t) , and
SELECT statements that fetch
values directly into variables, for example SELECT i
INTO var1 FROM t .
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 and Triggers”.
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.0.44, 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 18.5, “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. As of MySQL 5.0.3, 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.0.20.
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.
As of MySQL 5.0.18, the 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, as of MySQL 5.0.25, the database character
set and collation that are in effect at the time the server
loads the routine into the routine cache are used. (These are
given by the values of the
character_set_database and
collation_database system
variables.) If the database character set or collation change
while the routine is in the cache, routine execution is
unaffected by the change until the next time the server
reloads the routine into the cache. The
COLLATE attribute is not supported. (This
includes use of BINARY , which in this
context specifies the binary collation of the character set.)
Before MySQL 5.0.18, parameters, return values, and local
variables are treated as items in expressions, and are subject to
automatic (silent) conversion and truncation. Stored functions
ignore the sql_mode setting.
12.1.10. CREATE TABLE SyntaxCREATE [TEMPORARY] TABLE [IF NOT EXISTS] tbl_name
(create_definition ,...)
[table_options ]
Or:
CREATE [TEMPORARY] TABLE [IF NOT EXISTS] tbl_name
[(create_definition ,...)]
[table_options ]
select_statement
Or:
CREATE [TEMPORARY] TABLE [IF NOT EXISTS] tbl_name
{ LIKE old_tbl_name | (LIKE old_tbl_name ) }
create_definition :
col_name column_definition
| [CONSTRAINT [symbol ]] PRIMARY KEY [index_type ] (index_col_name ,...)
[index_type ]
| {INDEX|KEY} [index_name ] [index_type ] (index_col_name ,...)
[index_type ]
| [CONSTRAINT [symbol ]] UNIQUE [INDEX|KEY]
[index_name ] [index_type ] (index_col_name ,...)
[index_type ]
| {FULLTEXT|SPATIAL} [INDEX|KEY] [index_name ] (index_col_name ,...)
[index_type ]
| [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 '] [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}
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|TYPE} [=] 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 }
| MAX_ROWS [=] value
| MIN_ROWS [=] value
| PACK_KEYS [=] {0 | 1 | DEFAULT}
| PASSWORD [=] 'string '
| ROW_FORMAT [=] {DEFAULT|DYNAMIC|FIXED|COMPRESSED|REDUNDANT|COMPACT}
| UNION [=] (tbl_name [,tbl_name ]...)
select_statement:
[IGNORE | REPLACE] [AS] SELECT ... (Some legal select statement )
CREATE TABLE creates a table with
the given name. You must have the
CREATE privilege for the table.
Rules for 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.
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.12, “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.10.3, “Information Functions”, and
Section 20.8.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.7, “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 and BDB
tables, you can specify an AUTO_INCREMENT
secondary column in a multiple-column key. See
Section 3.6.9, “Using AUTO_INCREMENT ”.
To make MySQL compatible with some ODBC applications, you can
find the AUTO_INCREMENT value for the last
inserted row with the following query:
SELECT * FROM tbl_name WHERE auto_col IS NULL
For information about InnoDB and
AUTO_INCREMENT , see
Section 13.2.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.0 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' .
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.
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. This constraint does not apply to
NULL values except for the
BDB storage engine. For other 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.2.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.18, “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;
For details about USING , see
Section 12.1.8, “CREATE INDEX Syntax”.
For more information about indexes, see
Section 7.4.4, “How MySQL Uses Indexes”.
In MySQL 5.0, only the MyISAM ,
InnoDB , BDB , 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 , BDB ,
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.
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.12, “Spatial Extensions”.
InnoDB tables support checking of foreign
key constraints. See Section 13.2, “The InnoDB Storage Engine”. Note that the
FOREIGN KEY syntax in
InnoDB is more restrictive than the syntax
presented for the CREATE TABLE
statement at the beginning of this section: The columns of the
referenced table must always be explicitly named.
InnoDB supports both ON
DELETE and ON UPDATE actions on
foreign keys. For the precise syntax, see
Section 13.2.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 ENGINE table option specifies the storage
engine for the table. TYPE is a synonym, but
ENGINE is the preferred option name.
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=BDB option but the MySQL
server does not support BDB tables, the table
is created as a MyISAM table. This makes it
possible to have a replication setup where you have transactional
tables on the master but tables created on the slave are
nontransactional (to get more speed). In MySQL 5.0, 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.7, “Server SQL Modes”.
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.0, this works for
MyISAM and MEMORY
tables. It is also supported for InnoDB as
of MySQL 5.0.3. 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
table files is 256TB of data by default (4GB before MySQL
5.0.6). (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, which was added in MySQL 4.1.2. (See
Section 5.1.3, “Server System Variables”.) If you want all
your tables to be able to grow above the default limit and are
willing to have your tables slightly slower and larger than
necessary, you 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. This option is available as of MySQL 5.0.13; before
that, use 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.
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.0.48, 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.0.60, you cannot use path names that
contain the MySQL data directory with DATA
DIRECTORY or INDEX DIRECTORY .
(See Bug#32167.)
DELAY_KEY_WRITE
Set this to 1 if you want to delay key updates for the table
until the table is closed. See the description of the
delay_key_write system
variable in Section 5.1.3, “Server System Variables”.
(MyISAM only.)
INSERT_METHOD
If you want to insert data into a MERGE
table, you must specify with INSERT_METHOD
the table into which the row should be inserted.
INSERT_METHOD is an option useful for
MERGE tables only. Use a value of
FIRST or LAST to have
inserts go to the first or last table, or a value of
NO to prevent inserts. See
Section 13.3, “The MERGE Storage Engine”.
MAX_ROWS
The maximum number of rows you plan to store in the table.
This is not a hard limit, but rather a hint to the storage
engine that the table must be able to store at least this many
rows.
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.
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.1.3, “MyISAM Table Storage Formats”.
Starting with MySQL 5.0.3, 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.
RAID_TYPE
RAID support has been removed as of MySQL
5.0. For information on RAID , see
CREATE TABLE Syntax.
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.3, “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.
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.10.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.
Some silent column specification changes include modifications
to attribute or index specifications:
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.
Possible data type changes are given in the following list. If a
version number is given, the change occurs only up to the
versions listed. After that, an error occurs if a column cannot
be created using the specified data type.
Before MySQL 5.0.3, VARCHAR
columns with a length less than four are changed to
CHAR .
Before MySQL 5.0.3, if any column in a table has a variable
length, the entire row becomes variable-length as a result.
Therefore, if a table contains any variable-length columns
(VARCHAR ,
TEXT , or
BLOB ), all
CHAR columns longer than
three characters are changed to
VARCHAR columns. This does
not affect how you use the columns in any way; in MySQL,
VARCHAR is just a different
way to store characters. MySQL performs this conversion
because it saves space and makes table operations faster.
See Chapter 13, Storage Engines.
Before MySQL 5.0.3, a CHAR or
VARCHAR column with a length
specification greater than 255 is converted to the smallest
TEXT type that can hold
values of the given length. For example,
VARCHAR(500) is converted to
TEXT , and
VARCHAR(200000) is converted to
MEDIUMTEXT . Similar
conversions occur for BINARY
and VARBINARY , except that
they are converted to a BLOB
type.
Note that these conversions result in a change in behavior
with regard to treatment of trailing spaces.
As of MySQL 5.0.3, a CHAR or
BINARY column with a length
specification greater than 255 is not silently converted.
Instead, an error occurs. From MySQL 5.0.6 on, silent
conversion of VARCHAR and
VARBINARY columns with a
length specification greater than 65535 does not occur if
strict SQL mode is enabled. Instead, an error occurs.
Before MySQL 5.0.10, for a specification of
DECIMAL(M ,D ) ,
if M is not larger than
D , it is adjusted upward. For
example, DECIMAL(10,10) becomes
DECIMAL(11,10) . As of MySQL 5.0.10,
DECIMAL(10,10) is created as specified.
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.1.3.3, “Compressed Table Characteristics”.
12.1.11. 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.
CREATE TRIGGER was added in MySQL
5.0.2.
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.
In MySQL 5.0 CREATE
TRIGGER 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 and Triggers”.
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 current server SQL
mode.
Note
Currently, triggers are not activated by cascaded foreign key
actions. This limitation will be lifted as soon as possible.
Note
Before MySQL 5.0.10, triggers cannot contain direct references
to tables by name. Beginning with MySQL 5.0.10, you can write
triggers such as the one 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. It was added in MySQL 5.0.17. 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: Because MySQL currently requires the
SUPER privilege for the use of
CREATE TRIGGER , only the second of
the preceding rules applies. (MySQL 5.1.6 implements the
TRIGGER privilege and requires that
privilege for trigger creation, so at that point both rules come
into play and SUPER is required
only for specifying a DEFINER value other than
your own account.)
From MySQL 5.0.17 on, 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
SUPER privilege.
At trigger activation time, privileges are checked against the
DEFINER user. This user must have these
privileges:
The SUPER privilege.
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.
Before MySQL 5.0.17, DEFINER is not available
and MySQL checks trigger privileges like this:
At CREATE TRIGGER time, the
user who issues the statement must have the
SUPER privilege.
At trigger activation time, privileges are checked against the
user whose actions cause the trigger to be activated. This
user must have whatever 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.
Consistent with the privilege-checking rules just given,
CURRENT_USER() returns the
DEFINER user from MySQL 5.0.17 on. Before
5.0.17, CURRENT_USER() returns 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.12. 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. This statement was added in
MySQL 5.0.1. 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
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.0.52, 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.0.13, but have no
effect until MySQL 5.0.16. 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.0.24.
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.0.16 (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.0.16 (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
DEFINER . The standard says that the definer of the view,
which is the same as the owner of the view's schema, gets
applicable privileges on the view (for example,
SELECT ) and may grant them. MySQL
has no concept of a schema “owner”, so MySQL adds a
clause to identify the definer. The DEFINER clause is an extension
where the intent is to have what the standard has; that is, a
permanent record of who defined the view.
If you invoke a view that was created before MySQL 5.0.13, 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 18.4.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. The
WITH CHECK OPTION clause was implemented in
MySQL 5.0.2.
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 18.4.3, “Updatable and Insertable Views”.
12.1.13. 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 as of MySQL 5.0.2.
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:
All files with the following extensions.
All subdirectories with names that consist of two hex digits
00 -ff . These are
subdirectories used for RAID tables. (These
directories are not removed as of MySQL 5.0, when support for
RAID tables was removed. You should convert
any existing RAID tables and remove these
directories manually before upgrading to MySQL 5.0. See
Section 2.18.1.2, “Upgrading from MySQL 4.1 to 5.0”.)
The db.opt file, if it exists.
If other files or directories remain in the database directory
after MySQL removes those just listed, the database directory
cannot be removed. In this case, you must remove any remaining
files or directories manually and issue the
DROP DATABASE statement again.
You can also drop databases with mysqladmin.
See Section 4.5.2, “mysqladmin — Client for Administering a MySQL Server”.
12.1.14. DROP FUNCTION Syntax
The DROP FUNCTION statement is used
to drop stored functions and user-defined functions (UDFs):
12.1.16. 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. As of
MySQL 5.0.3, 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 18.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 .
Note
DROP PROCEDURE IF EXISTS and DROP
FUNCTION IF EXISTS are not written to the binary log
(and thus not replicated) if the stored procedure or function
named in the DROP statement does not exist on
the master. This is a known issue, which is resolved in MySQL
5.1 and later. (Bug#13684)
DROP FUNCTION is also used to drop
user-defined functions (see Section 12.5.3.2, “DROP FUNCTION Syntax”).
12.1.17. 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.
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.37, “SHOW WARNINGS Syntax”.
RESTRICT and CASCADE are
allowed to make porting easier. In MySQL 5.0, 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.18. 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
SUPER privilege.
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.37, “SHOW WARNINGS Syntax”. The IF EXISTS
clause was added in MySQL 5.0.32.
Triggers for a table are also dropped if you drop the table.
Note
Prior to MySQL 5.0.10, the table name was required instead of
the schema name
(table_name .trigger_name ).
When upgrading from a previous version of MySQL 5.0 to MySQL
5.0.10 or newer, you must drop all triggers before
upgrading and re-create them afterwards, or else
DROP TRIGGER does not work after
the upgrade. See
Section 2.18.1.2, “Upgrading from MySQL 4.1 to 5.0”, for a
suggested upgrade procedure.
In addition, triggers created in MySQL 5.0.16 or later cannot be
dropped following a downgrade to MySQL 5.0.15 or earlier. If you
wish to perform such a downgrade, you must also in this case drop
all triggers prior to the downgrade, and then
re-create them afterwards.
(For more information about these two issues, see Bug#15921 and
Bug#18588.)
12.1.19. 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.37, “SHOW WARNINGS Syntax”.
RESTRICT and CASCADE , if
given, are parsed and ignored.
This statement was added in MySQL 5.0.1.
12.1.20. 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;
Beginning with MySQL 5.0.2, 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.
As of MySQL 5.0.14, 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.0.30, 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.0.25-log | 11 |
+------------+------------+
In prepared CALL statements used
with PREPARE and
EXECUTE , placeholder support is
available in MySQL 5.0 for IN
parameters, but not for OUT or
INOUT parameters. To work around this
limitation for OUT and INOUT
parameters, to forgo the use of placeholders: 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 |
+-----------------+------------+
| 6.0.7-alpha-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 20.8.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.10.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 reused
later for a BDB table, but not 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.2.4.3, “AUTO_INCREMENT Handling in InnoDB ”.
For MyISAM and BDB tables,
you can specify an AUTO_INCREMENT secondary
column in a multiple-column key. In this case, reuse of values
deleted from the top of the sequence occurs even for
MyISAM tables. See
Section 3.6.9, “Using AUTO_INCREMENT ”.
The DELETE statement supports the
following modifiers:
If you specify LOW_PRIORITY , the server
delays execution of the DELETE
until no other clients are reading from the table. This
affects only storage engines that use only table-level locking
(such as MyISAM , MEMORY ,
and MERGE ).
For MyISAM tables, if you use the
QUICK keyword, the storage engine does not
merge index leaves during delete, which may speed up some
kinds of delete operations.
The IGNORE keyword causes MySQL to ignore
all errors during the process of deleting rows. (Errors
encountered during the parsing stage are processed in the
usual manner.) Errors that are ignored due to the use of
IGNORE are returned as warnings.
The speed of delete operations may also be affected by factors
discussed in Section 7.2.21, “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.20, “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 ...
If table aliases are used, they should be declared in the
table_references part of the statement.
Elsewhere in the statement, aliases references are allowed but
should not be declared.
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:
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.7, “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.10.3, “Information Functions”), or the
mysql_affected_rows() C API
function (see Section 20.8.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 20.8.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.10.3, “Information Functions”, and
Section 20.8.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.0.42, 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. 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 ,
and ARCHIVE 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.
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.
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 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 ... UPDATE statement. In other words,
VALUES(col_name )
in the 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 ... UPDATE inserts a row, the
LAST_INSERT_ID() function returns
the AUTO_INCREMENT value. If the statement
updates a row instead,
LAST_INSERT_ID() is not
meaningful. However, you can work around this by using
LAST_INSERT_ID(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.19, “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.0.38. 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.0.19, 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.
CONCURRENT is not replicated. See
Section 16.3.1.10, “Replication and LOAD Operations”, for more information.
The LOCAL keyword, if specified, is interpreted
with respect to the client end of the connection:
If LOCAL is specified, the file is read by
the client program on the client host and sent to the server.
The file can be given as a full path name to specify its exact
location. If given as a relative path name, the name is
interpreted relative to the directory in which the client
program was started.
If LOCAL is not specified, the file must be
located on the server host and is read directly by the server.
The server uses the following rules to locate the file:
If the file name is an absolute path name, the server uses
it as given.
If the file name is a relative path name with one or more
leading components, the server searches for the file
relative to the server's data directory.
If a file name with no leading components is given, the
server looks for the file in the database directory of the
default database.
Note that, in the non-LOCAL case, these rules
mean that a file named as ./myfile.txt is
read from the server's data directory, whereas the file named as
myfile.txt is read from the database
directory of the default database. For example, if
db1 is the default database, the following
LOAD DATA statement reads the file
data.txt from the database directory for
db1 , even though the statement explicitly loads
the file into a table in the db2 database:
LOAD DATA INFILE 'data.txt' INTO TABLE db2.my_table;
Windows path names are specified using forward slashes rather than
backslashes. If you do use backslashes, you must double them.
For security reasons, when reading text files located on the
server, the files must either reside in the database directory or
be readable by all. Also, to use
LOAD DATA
INFILE on server files, you must have the
FILE privilege. See
Section 5.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.19, “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.
Note
Before MySQL 5.0.6, fixed-row format used the display width
of the column. For example, INT(4) was
read or written using a field with a width of 4. However, if
the column contained wider values, they were dumped to their
full width, leading to the possibility of a
“ragged” field holding values of different
widths. Using a field wide enough to hold all values in the
field prevents this problem. However, data files written
before this change was made might not be reloaded correctly
with LOAD DATA
INFILE for MySQL 5.0.6 and up. This change also
affects data files read by mysqlimport
and written by mysqldump --tab, which use
LOAD DATA
INFILE and
SELECT ... INTO
OUTFILE .
Handling of NULL values varies according to the
FIELDS and LINES options in
use:
For the default FIELDS and
LINES values, NULL is
written as a field value of \N for output,
and a field value of \N is read as
NULL for input (assuming that the
ESCAPED BY character is
“\ ”).
If FIELDS ENCLOSED BY is not empty, a field
containing the literal word NULL as its
value is read as a NULL value. This differs
from the word NULL enclosed within
FIELDS ENCLOSED BY characters, which is
read as the string 'NULL' .
If FIELDS ESCAPED BY is empty,
NULL is written as the word
NULL .
With fixed-row format (which is used when FIELDS
TERMINATED BY and FIELDS ENCLOSED
BY are both empty), NULL is
written as an empty string. Note that this causes both
NULL values and empty strings in the table
to be indistinguishable when written to the file because both
are written as empty strings. If you need to be able to tell
the two apart when reading the file back in, you should not
use fixed-row format.
An attempt to load NULL into a NOT
NULL column causes assignment of the implicit default
value for the column's data type and a warning, 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.
Before MySQL 5.0.3, the column list must contain only names of
columns in the table being loaded, and the SET
clause is not supported. As of MySQL 5.0.3, 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 20.8.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.37, “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 ' 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.3, “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.11, “Functions and Modifiers for Use with GROUP BY Clauses”.
GROUP BY allows a WITH
ROLLUP modifier. See
Section 11.11.2, “GROUP BY Modifiers”.
The HAVING clause is applied nearly last,
just before items are sent to the client, with no
optimization. (LIMIT is applied after
HAVING .)
A HAVING clause can refer to any column or
alias named in a select_expr in the
SELECT list or in outer
subqueries, and to aggregate functions. However, the SQL
standard requires that HAVING must
reference only columns in the GROUP BY
clause or columns used in aggregate functions. To accommodate
both standard SQL and the MySQL-specific behavior of being
able to refer columns in the
SELECT list, MySQL 5.0.2 and up
allows HAVING to refer to columns in the
SELECT list, columns in the
GROUP BY clause, columns in outer
subqueries, and to aggregate functions.
For example, the following statement works in MySQL 5.0.2 but
produces an error for earlier versions:
mysql> SELECT COUNT(*) FROM t GROUP BY col1 HAVING col1 = 2;
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 (supported
as of MySQL version 5.0.7). The following statements will
return one row from the tbl table:
SET @a=1;
PREPARE STMT FROM 'SELECT * FROM tbl LIMIT ?';
EXECUTE STMT USING @a;
The following statements will return the second to sixth row
from the tbl table:
SET @skip=1; SET @numrows=5;
PREPARE STMT FROM 'SELECT * FROM tbl LIMIT ?, ?';
EXECUTE STMT USING @skip, @numrows;
For compatibility with PostgreSQL, MySQL also supports the
LIMIT 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 21.3.1, “PROCEDURE ANALYSE ”, which describes
ANALYSE , a procedure that can be used to
obtain suggestions for optimal column data types that may help
reduce table sizes.
The SELECT ... INTO OUTFILE
'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.0.19, 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 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.
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.2.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.10.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 )]
| 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 :
USE {INDEX|KEY} [FOR JOIN] (index_list )
| IGNORE {INDEX|KEY} [FOR JOIN] (index_list )
| FORCE {INDEX|KEY} [FOR JOIN] (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 versions of MySQL prior to 5.0.1, parentheses in
table_references were just omitted
and all join operations were grouped to the left. In general,
parentheses can be ignored in join expressions containing only
inner join operations. As of 5.0.1, nested joins are allowed
(see Section 7.2.11, “Nested Join Optimization”).
Further changes in join processing were made in 5.0.12 to make
MySQL more compliant with standard SQL. These charges are
described later in this section.
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;
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
Beginning with MySQL 5.0.12, 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 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
the 5.0.12 change in join processing. 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 ]
index_hint :
USE {INDEX|KEY} [FOR JOIN] (index_list )
| IGNORE {INDEX|KEY} [FOR JOIN] (index_list )
| FORCE {INDEX|KEY} [FOR JOIN] (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.
USE INDEX , IGNORE INDEX ,
and FORCE INDEX affect only which indexes are
used when MySQL decides how to find rows in the table and how to
do the join. They do not affect whether an index is used when
resolving an ORDER BY or GROUP
BY clause. As of MySQL 5.0.40, the optional
FOR JOIN clause can be added to make this
explicit.
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;
For FULLTEXT searches, index hints do not
work before MySQL 5.0.74. As of 5.0.74, 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 are honored.
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”.
MySQL Enterprise
MySQL Enterprise subscribers will find a discussion of this
topic in the Knowledge Base article,
How do
Subqueries Work in MySQL? For information about MySQL
Enterprise see
http://www.mysql.com/products/enterprise/advisors.html.
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.0, 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.0.26, 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.10.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.0 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. Logically, this is equivalent to a
DELETE statement that deletes all
rows, but there are practical differences under some
circumstances.
For an InnoDB table before version 5.0.3,
InnoDB processes TRUNCATE
TABLE by deleting rows one by one. As of MySQL 5.0.3,
row by row deletion is used only 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. (When fast
truncation is used, it resets any
AUTO_INCREMENT counter to zero. From MySQL
5.0.13 on, 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.0:
Truncate operations drop and re-create the table, which is
much faster than deleting rows one by one, particularly for
large tables.
As of MySQL 5.0.8, truncate operations cause an implicit
commit. Before 5.0.8, truncate operations are not
transaction-safe; an error occurs when attempting one in the
course of an active transaction.
Truncation operations cannot be performed if the session holds
an active table lock.
Truncation operations do not return a meaningful value for the
number of deleted rows. The usual result is “0 rows
affected,” which should be interpreted as “no
information.”
As long as the table format file
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.
Since truncation of a table does not make any use of
DELETE , the
TRUNCATE TABLE statement does
not invoke ON DELETE triggers.
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.2.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 . As of MySQL 5.0.1, these statements also display
information for views. (See Section 12.5.5.5, “SHOW COLUMNS Syntax”.)
col_name can be a column name, or a
string containing the SQL “% ” and
“_ ” wildcard characters to obtain
output only for the columns with names matching the string. There
is no need to enclose the string within 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.5, “SHOW COLUMNS Syntax”).
If the data types differ from what you expect them to be based on
a CREATE TABLE statement, note that
MySQL sometimes changes data types when you create or alter a
table. The conditions under which this occurs are described in
Section 12.1.10.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] 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:
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.8, “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 |
+----------------------+-------------------------+----------------+
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.
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”. Beginning with MySQL 5.0, XA transaction
support is available, which 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.
Beginning with MySQL 5.0.3, 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.3, “Server System Variables”.
Note
Within stored programs (stored procedures and functions, and
triggers), 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 , BDB , 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 20, 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.2.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
BDB ), and the transaction isolation level
is not SERIALIZABLE , it is
possible that when one transaction commits, another ongoing
transaction that uses the same tables will see only some of
the changes made by the first transaction. That is, the
atomicity of transactions is not guaranteed with mixed engines
and inconsistencies can result. (If mixed-engine transactions
are infrequent, you can use
SET
TRANSACTION ISOLATION LEVEL to set the isolation
level to SERIALIZABLE on a
per-transaction basis as necessary.)
If you use tables that are not transaction-safe within a
transaction, changes to those tables are stored at once,
regardless of the status of autocommit mode.
If you issue a
ROLLBACK
statement after updating a nontransactional table within a
transaction, an
ER_WARNING_NOT_COMPLETE_ROLLBACK
warning occurs. Changes to transaction-safe tables are rolled
back, but not changes to nontransaction-safe tables.
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.3, “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 TABLE ,
CREATE INDEX ,
DROP INDEX ,
DROP TABLE ,
RENAME TABLE .
ALTER TABLE ,
CREATE TABLE , and
DROP TABLE do not commit a
transaction if the TEMPORARY keyword is
used. (This does not apply to other operations on temporary
tables such as CREATE INDEX ,
which do cause a commit.) However, although no implicit commit
occurs, neither can the statement be rolled back. Therefore,
use of such statements will violate transaction atomicity: For
example, if you use
CREATE TEMPORARY
TABLE and then roll back the transaction, the table
remains in existence.
The CREATE TABLE statement in
InnoDB is processed as a single
transaction. This means that a
ROLLBACK
from the user does not undo CREATE
TABLE statements the user made during that
transaction.
Beginning with MySQL 5.0.8, CREATE
TABLE , CREATE
DATABASE DROP
DATABASE , and TRUNCATE
TABLE cause an implicit commit.
Beginning with MySQL 5.0.13, ALTER
PROCEDURE , CREATE
PROCEDURE , and DROP
PROCEDURE cause an implicit commit.
Also beginning with MySQL 5.0.13, ALTER
FUNCTION , CREATE
FUNCTION and DROP
FUNCTION cause an implicit commit when used with
stored functions, but not with UDFs.
(ALTER FUNCTION can only be
used with stored functions.)
Beginning with MySQL 5.0.15, ALTER
VIEW , CREATE TRIGGER ,
CREATE VIEW ,
DROP TRIGGER , and
DROP VIEW cause an implicit
commit.
Statements that implicitly use or modify
tables in the mysql database.
Beginning with MySQL 5.0.15, CREATE
USER , DROP USER , and
RENAME USER 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 MASTER DATA ,
LOAD DATA
INFILE . Before MySQL 5.0.26,
LOAD DATA
INFILE caused an implicit commit for all storage
engines. As of MySQL 5.0.26, it causes an implicit commit only
for tables using the NDB storage
engine. For more information, see Bug#11151.
12.4.4. SAVEPOINT and
ROLLBACK TO
SAVEPOINT SyntaxSAVEPOINT identifier
ROLLBACK [WORK] TO [SAVEPOINT] identifier
RELEASE SAVEPOINT identifier
InnoDB supports the SQL statements
SAVEPOINT and
ROLLBACK TO
SAVEPOINT . Starting from MySQL 5.0.3,
RELEASE
SAVEPOINT and the optional WORK
keyword for
ROLLBACK are
supported as well.
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. (The
SAVEPOINT keyword is optional as of
MySQL 5.0.3.) 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.
Beginning with MySQL 5.0.17, 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 (as of MySQL 5.0.6) 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.2, “FLUSH Syntax”. (This is a very
convenient way to get backups if you have a file system such as
Veritas that can take snapshots in time.)
A table lock protects only against inappropriate reads or writes
by other sessions. The session holding the lock, even a read lock,
can perform table-level operations such as
DROP TABLE . Truncate operations are
not transaction-safe, so an error occurs if the session attempts
one during an active transaction or while holding a table lock.
The following discussion applies only to
non-TEMPORARY tables. LOCK
TABLES is 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 as of MySQL 5.0.13. (Before that,
READ LOCAL essentially does nothing: It
does not lock the table at all, so for
InnoDB tables, the use of READ
LOCAL is deprecated because a plain consistent-read
SELECT does the same thing, and
no locks are needed.)
[LOW_PRIORITY] WRITE lock:
The session that holds the lock can read and write the table.
Only the session that holds the lock can access the table. No
other session can access it until the lock is released.
Lock requests for the table by other sessions block while the
WRITE lock is held.
The LOW_PRIORITY modifier affects lock
scheduling if the WRITE lock request must
wait, as described later.
If the LOCK TABLES statement must
wait due to locks held by other sessions on any of the tables, it
blocks until all locks can be acquired.
A session that requires locks must acquire all the locks that it
needs in a single LOCK TABLES
statement. While the locks thus obtained are held, the session can
access only the locked tables. For example, in the following
sequence of statements, an error occurs for the attempt to access
t2 because it was not locked in the
LOCK TABLES statement:
mysql> LOCK TABLES t1 READ;
mysql> SELECT COUNT(*) FROM t1;
+----------+
| COUNT(*) |
+----------+
| 3 |
+----------+
mysql> SELECT COUNT(*) FROM t2;
ERROR 1100 (HY000): Table 't2' was not locked with LOCK TABLES
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 20.8.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.2, “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.3, “KILL Syntax”.
You should not lock any tables that you are
using with INSERT DELAYED . An
INSERT DELAYED in this case
results in an error because the insert must be handled by a
separate thread, not by the session which holds the lock.
Normally, you do not need to lock tables, because all single
UPDATE statements are atomic; no
other session can interfere with any other currently executing
SQL statement. However, there are a few cases when locking
tables may provide an advantage:
If you are going to run many operations on a set of
MyISAM tables, it is much faster to lock
the tables you are going to use. Locking
MyISAM tables speeds up inserting,
updating, or deleting on them because MySQL does not flush
the key cache for the locked tables until
UNLOCK
TABLES is called. Normally, the key cache is
flushed after each SQL statement.
The downside to locking the tables is that no session can
update a READ -locked table (including the
one holding the lock) and no session can access a
WRITE -locked table other than the one
holding the lock.
If you are using tables for a nontransactional storage
engine, you must use LOCK
TABLES if you want to ensure that no other session
modifies the tables between a
SELECT and an
UPDATE . The example shown
here requires LOCK TABLES to
execute safely:
LOCK TABLES trans READ, customer WRITE;
SELECT SUM(value) FROM trans WHERE customer_id=some_id ;
UPDATE customer
SET total_value=sum_from_previous_statement
WHERE customer_id=some_id ;
UNLOCK TABLES;
Without LOCK TABLES , it is
possible that another session might insert a new row in the
trans table between execution of the
SELECT and
UPDATE statements.
You can avoid using LOCK TABLES
in many cases by using relative updates (UPDATE
customer SET
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.10.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.2.8.4, “InnoDB Record, Gap, and Next-Key Locks”, and
Section 13.2.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.2.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.
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.2.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.)
MySQL 5.0.3 and up provides server-side support for XA
transactions. Currently, this support 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.
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.
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.
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”.
MySQL Enterprise
MySQL Enterprise subscribers will find more information on
this subject in the Knowledge Base article,
Can I Undo
a Set of SQL Statements? To subscribe to MySQL
Enterprise see
http://www.mysql.com/products/enterprise/advisors.html.
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.9, “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 was
added in MySQL 5.0.2. This 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 record
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. To use it, 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”.
DROP USER as present in MySQL
5.0.0 removes only accounts that have no privileges. In MySQL
5.0.2, it was modified to remove account privileges as well.
This means that the procedure for removing an account depends on
your version of MySQL.
As of MySQL 5.0.2, you can remove an account and its privileges
as follows:
DROP USER user ;
The statement removes privilege rows for the account from all
grant tables.
Before MySQL 5.0.2, DROP USER
serves only to remove account rows from the
user table for accounts that have no
privileges. To remove a MySQL account completely (including all
of its privileges), you should use the following procedure,
performing these steps in the order shown:
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, and triggers.
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.17, “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 EXECUTE privilege is not
operational until MySQL 5.0.3. CREATE
VIEW and SHOW VIEW were
added in MySQL 5.0.1. CREATE
USER , CREATE ROUTINE ,
and ALTER ROUTINE were added in
MySQL 5.0.3.
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.9, “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.0.23, privileges also are assigned at the global
level if you use ON * syntax and you have
not selected a default database. As of
5.0.23, 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 , 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 , 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 was added in
MySQL 5.0.6. If present, it 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.9, “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, implemented
in MySQL 5.0.3, 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, and does not support the
TRIGGER privilege until MySQL
5.1.6.
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 5.0.2
and up if you use DROP USER .
Before 5.0.2, the granted privileges are not automatically
revoked; you must revoke them yourself. 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.7, “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, and triggers.
The RENAME USER statement was
added in MySQL 5.0.2.
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.17, “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 and
BDB . For InnoDB the table
is locked with a write lock. This statement works with
MyISAM , BDB , 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.2.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.
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.18, “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 (as of MySQL 5.0.16) ARCHIVE tables. For
MyISAM tables, the key statistics are updated
as well.
As of MySQL 5.0.2, CHECK TABLE
can also check views for problems, such as tables that are
referenced in the view definition that no longer exist.
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.0.19. 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.0.62, 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.18.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.10, “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, as of MySQL
5.0.3, 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.
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
only for MyISAM ,
InnoDB , and (as of MySQL 5.0.16)
ARCHIVE tables. It does
not work for tables created using any other
storage engine.
For MyISAM tables,
OPTIMIZE TABLE works as follows:
If the table has deleted or split rows, repair the table.
If the index pages are not sorted, sort them.
If the table's statistics are not up to date (and the repair
could not be accomplished by sorting the index), update
them.
For BDB tables, OPTIMIZE
TABLE currently is mapped to
ANALYZE TABLE . See
Section 12.5.2.1, “ANALYZE TABLE Syntax”.
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.
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. See Section 13.1, “The MyISAM Storage Engine”, and
Section 13.8, “The ARCHIVE Storage Engine”.
This statement requires SELECT
and INSERT privileges for the
table.
Normally, you should never have to run this statement. However,
if disaster strikes, REPAIR TABLE
is very likely to get back all your data from a
MyISAM table. If 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.1.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.0.62, 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.0.62, 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 `" 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.0.62, 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. 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. As of MySQL 5.0.3,
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. As of MySQL 5.0.67, the file must be located in
the plugin directory. This directory is given by the value of
the plugin_dir system variable.
If the value of plugin_dir is
empty, the behavior that is used before 5.0.67 applies: The file
must be located in a 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.9, “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 21.2.2, “Adding a New User-Defined Function”. For the UDF mechanism to work,
functions must be written in C or C++ (or another language that
can use C calling conventions), your operating system must
support dynamic loading and you must have compiled
mysqld dynamically (not statically).
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.9, “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.16, “DROP PROCEDURE and
DROP FUNCTION Syntax”).
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.3, “Server System Variables”,
Section 5.1.4, “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.5, “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.5.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.36, “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 CHARACTER SET [like_or_where ]
SHOW COLLATION [like_or_where ]
SHOW [FULL] COLUMNS FROM tbl_name [FROM db_name ] [like_or_where ]
SHOW CREATE DATABASE db_name
SHOW CREATE FUNCTION func_name
SHOW CREATE PROCEDURE proc_name
SHOW CREATE TABLE tbl_name
SHOW DATABASES [like_or_where ]
SHOW ENGINE engine_name {LOGS | STATUS }
SHOW [STORAGE] ENGINES
SHOW ERRORS [LIMIT [offset ,] row_count ]
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 PROCEDURE CODE proc_name
SHOW PROCEDURE STATUS [like_or_where ]
SHOW [BDB] LOGS
SHOW MUTEX STATUS
SHOW OPEN TABLES [FROM db_name ] [like_or_where ]
SHOW PRIVILEGES
SHOW [FULL] PROCESSLIST
SHOW PROFILE [types ] [FOR QUERY n ] [OFFSET n ] [LIMIT n ]
SHOW PROFILES
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 19.19, “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 20, 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 19, INFORMATION_SCHEMA Tables.
12.5.5.1. 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 . The File_size column is
displayed as of MySQL 5.0.7.
12.5.5.2. 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.3. 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 19.19, “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.4. 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 19.19, “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.5. 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 as
of MySQL 5.0.1. 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 19.19, “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.10.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. If not, the column contains
NO as of MySQL 5.0.3, and
'' before that.
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.
Before MySQL 5.0.11, if the column allows
NULL values, the Key value
can be MUL even when a single-column
UNIQUE index is used. The rationale was that
multiple rows in a UNIQUE index can hold a
NULL value if the column is not declared
NOT NULL . As of MySQL 5.0.11, the display is
UNI rather than MUL
regardless of whether the column allows NULL ;
you can see from the Null field whether or
not the column can contain NULL .
The Default field indicates the default value
that is assigned to the column.
The Extra field contains any additional
information that is available about a given column. The value is
auto_increment for columns that have the
AUTO_INCREMENT attribute and empty otherwise.
Privileges indicates the privileges you have
for the column. This value is displayed only if you use the
FULL keyword.
Comment indicates any comment the column has.
This value is displayed only if you use the
FULL keyword.
SHOW FIELDS is a synonym for
SHOW COLUMNS . You can also list a
table's columns with the mysqlshow
db_name
tbl_name command.
The DESCRIBE statement provides
information similar to SHOW
COLUMNS . See Section 12.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.6. 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 as of MySQL
5.0.2.
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.4, “Session System Variables”.
12.5.5.8. 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.7, “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
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,'!')
12.5.5.9. 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.
As of MySQL 5.0.1, 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.4, “Session System Variables”.
12.5.5.10. 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;
+------+----------------------------------------------------+
| View | Create View |
+------+----------------------------------------------------+
| v | CREATE VIEW `test`.`v` AS select 1 AS `a`,2 AS `b` |
+------+----------------------------------------------------+
This statement was added in MySQL 5.0.1.
Prior to MySQL 5.0.11, the output columns from this statement
were shown as Table and Create
Table .
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 19.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.11. 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 as of MySQL 5.0.2. 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 19.19, “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.12. SHOW ENGINE SyntaxSHOW ENGINE engine_name {LOGS | STATUS }
SHOW ENGINE displays log or
status information about a storage engine. The following
statements currently are supported:
SHOW ENGINE BDB LOGS
SHOW ENGINE INNODB STATUS
SHOW ENGINE NDB STATUS
SHOW ENGINE NDBCLUSTER STATUS
SHOW ENGINE BDB
LOGS displays status information about existing
BDB log files. It returns the following
fields:
File
The full path to the log file.
Type
The log file type (BDB for Berkeley DB
log files).
Status
The status of the log file (FREE if the
file can be removed, or IN USE if the
file is needed by the transaction subsystem)
SHOW ENGINE INNODB
STATUS displays extensive information from the
standard InnoDB Monitor about the state of
the InnoDB storage engine. For information
about the standard monitor and other InnoDB
Monitors that provide information about
InnoDB processing, see
Section 13.2.13.2, “SHOW ENGINE INNODB
STATUS and the InnoDB Monitors”.
Older (and now deprecated) synonyms for
SHOW ENGINE BDB
LOGS and
SHOW ENGINE INNODB
STATUS are SHOW [BDB] LOGS and
SHOW INNODB STATUS , respectively.
If the server has the NDBCLUSTER
storage engine enabled,
SHOW ENGINE NDB
STATUS can be used to display cluster status
information. Sample output from this statement is shown here:
mysql> SHOW ENGINE NDB STATUS;
+-----------------------+---------+------+--------+
| free_list | created | free | sizeof |
+-----------------------+---------+------+--------+
| NdbTransaction | 5 | 0 | 208 |
| NdbOperation | 4 | 4 | 660 |
| NdbIndexScanOperation | 1 | 1 | 736 |
| NdbIndexOperation | 0 | 0 | 1060 |
| NdbRecAttr | 645 | 645 | 72 |
| NdbApiSignal | 16 | 16 | 136 |
| NdbLabel | 0 | 0 | 196 |
| NdbBranch | 0 | 0 | 24 |
| NdbSubroutine | 0 | 0 | 68 |
| NdbCall | 0 | 0 | 16 |
| NdbBlob | 2 | 2 | 204 |
| NdbReceiver | 2 | 0 | 68 |
+-----------------------+---------+------+--------+
12 rows in set (0.00 sec)
The most useful of the rows from the output of this statement
are described in the following list:
NdbTransaction : The number and size of
NdbTransaction objects that have been
created. An NdbTransaction is created
each time a table schema operation (such as
CREATE TABLE or
ALTER TABLE ) is performed on
an NDB table.
NdbOperation : The number and size of
NdbOperation objects that have been
created.
NdbIndexScanOperation : The number and
size of NdbIndexScanOperation objects
that have been created.
NdbIndexOperation : The number and size of
NdbIndexOperation objects that have been
created.
NdbRecAttr : The number and size of
NdbRecAttr objects that have been
created. In general, one of these is created each time a
data manipulation statement is performed by an SQL node.
NdbBlob : The number and size of
NdbBlob objects that have been created.
An NdbBlob is created for each new
operation involving a BLOB
column in an NDB table.
NdbReceiver : The number and size of any
NdbReceiver object that have been
created. The number in the created column
is the same as the number of data nodes in the cluster to
which the MySQL server has connected.
Note
SHOW ENGINE NDB
STATUS returns an empty result if no operations
involving NDB tables have been
performed by the MySQL client accessing the SQL node on which
this statement is run.
SHOW ENGINE
NDBCLUSTER STATUS is a synonym for
SHOW ENGINE NDB
STATUS .
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.13. 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: MyISAM
Support: DEFAULT
Comment: Default engine as of MySQL 3.23 with great performance
*************************** 2. row ***************************
Engine: MEMORY
Support: YES
Comment: Hash based, stored in memory, useful for temporary tables
*************************** 3. row ***************************
Engine: HEAP
Support: YES
Comment: Alias for MEMORY
*************************** 4. row ***************************
Engine: MERGE
Support: YES
Comment: Collection of identical MyISAM tables
*************************** 5. row ***************************
Engine: MRG_MYISAM
Support: YES
Comment: Alias for MERGE
*************************** 6. row ***************************
Engine: ISAM
Support: NO
Comment: Obsolete storage engine, now replaced by MyISAM
*************************** 7. row ***************************
Engine: MRG_ISAM
Support: NO
Comment: Obsolete storage engine, now replaced by MERGE
*************************** 8. row ***************************
Engine: InnoDB
Support: YES
Comment: Supports transactions, row-level locking, and foreign keys
*************************** 9. row ***************************
Engine: INNOBASE
Support: YES
Comment: Alias for INNODB
*************************** 10. row ***************************
Engine: BDB
Support: YES
Comment: Supports transactions and page-level locking
*************************** 11. row ***************************
Engine: BERKELEYDB
Support: YES
Comment: Alias for BDB
*************************** 12. row ***************************
Engine: NDBCLUSTER
Support: NO
Comment: Clustered, fault-tolerant, memory-based tables
*************************** 13. row ***************************
Engine: NDB
Support: NO
Comment: Alias for NDBCLUSTER
*************************** 14. row ***************************
Engine: EXAMPLE
Support: NO
Comment: Example storage engine
*************************** 15. row ***************************
Engine: ARCHIVE
Support: YES
Comment: Archive storage engine
*************************** 16. row ***************************
Engine: CSV
Support: NO
Comment: CSV storage engine
*************************** 17. row ***************************
Engine: FEDERATED
Support: YES
Comment: Federated MySQL storage engine
*************************** 18. row ***************************
Engine: BLACKHOLE
Support: YES
Comment: /dev/null storage engine (anything you write to it disappears)
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.1, “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 example,
--skip-innodb
disables the InnoDB engine. 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 .
12.5.5.14. 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.37, “SHOW WARNINGS Syntax”.
12.5.5.17. 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.0.24, 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.18. 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 values and '' if
not.
Index_type
The index method used (BTREE ,
FULLTEXT , HASH ,
RTREE ).
Comment
Various remarks.
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 19.19, “Extensions to SHOW Statements”.
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.21. 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.22. SHOW MUTEX STATUS SyntaxSHOW MUTEX STATUS
SHOW MUTEX STATUS displays
InnoDB mutex statistics. From MySQL 5.0.3 to
5.0.32, the statement displays the following output fields:
Mutex
The mutex name. The name indicates the mutex 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.
Module
The source file where the mutex is implemented.
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
that a 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_waits_time 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_waits_time is 0.
timed_mutexes is off by
default.
From MySQL 5.0.33 on, the statement uses the same output format
as that just described, 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 the following fields. In the latter case (without
UNIV_DEBUG ), the information on which the
statement 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.
SHOW MUTEX STATUS was added in MySQL 5.0.3.
In MySQL 5.1, SHOW MUTEX STATUS is
renamed to SHOW
ENGINE INNODB MUTEX . The latter statement displays
similar information but in a somewhat different output format.
12.5.5.23. 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 19.19, “Extensions to SHOW Statements”.
The FROM and
LIKE clauses may be used as of
MySQL 5.0.12. 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.24. 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.17, “SHOW GRANTS Syntax”, for more information.
12.5.5.25. 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.15, “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 .
SHOW PROCEDURE CODE was added in
MySQL 5.0.17.
12.5.5.26. 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.16, “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 19.19, “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:
You can also get information about stored routines from the
ROUTINES table in
INFORMATION_SCHEMA . See
Section 19.14, “The INFORMATION_SCHEMA ROUTINES Table”.
12.5.5.27. SHOW PROCESSLIST SyntaxSHOW [FULL] PROCESSLIST
SHOW PROCESSLIST shows you which
threads are running. You can also get this information using the
mysqladmin processlist command. If you have
the PROCESS privilege, you can
see all threads. Otherwise, you can see only your own threads
(that is, threads associated with the MySQL account that you are
using). If you do not use the FULL keyword,
only the first 100 characters of each statement are shown in the
Info field.
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.3, “KILL Syntax”.
Here is an example of what SHOW
PROCESSLIST output looks like:
mysql> SHOW FULL PROCESSLIST\G
*************************** 1. row ***************************
Id: 1
User: system user
Host:
db: NULL
Command: Connect
Time: 1030455
State: Waiting for master to send event
Info: NULL
*************************** 2. row ***************************
Id: 2
User: system user
Host:
db: NULL
Command: Connect
Time: 1004
State: Has read all relay log; waiting for the slave
I/O thread to update it
Info: NULL
*************************** 3. row ***************************
Id: 3112
User: replikator
Host: artemis:2204
db: NULL
Command: Binlog Dump
Time: 2144
State: Has sent all binlog to slave; waiting for binlog to be updated
Info: NULL
*************************** 4. row ***************************
Id: 3113
User: replikator
Host: iconnect2:45781
db: NULL
Command: Binlog Dump
Time: 2086
State: Has sent all binlog to slave; waiting for binlog to be updated
Info: NULL
*************************** 5. row ***************************
Id: 3123
User: stefan
Host: localhost
db: apollon
Command: Query
Time: 0
State: NULL
Info: SHOW FULL PROCESSLIST
5 rows in set (0.00 sec)
The columns have the following meaning:
Id
The connection identifier.
User
The MySQL user who issued the statement. If this is
system user , it refers to a nonclient
thread spawned by the server to handle tasks internally.
This could be the I/O or SQL thread used on replication
slaves or a delayed-row handler. unauthenticated
user refers to a thread that has become associated
with a client connection but for which authentication of the
client user has not yet been done. For system
user , there is no host specified in the
Host column.
Host
The host name of the client issuing the statement (except
for system user where there is no host).
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.6, “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.29. SHOW PROFILES SyntaxThis section does not apply to MySQL Enterprise Server users. SHOW 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.0.37.
You can also get profiling information from the
PROFILING table in
INFORMATION_SCHEMA . See
Section 19.17, “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.30. 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.31. 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
The following list describes the fields returned by
SHOW SLAVE STATUS . For additional
information about interpreting their meanings, see
Section 16.1.3.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”. For
versions of MySQL prior to 5.0.12, it is necessary to check
this field for connection problems. In those versions, the
thread could be running while unsuccessfully trying to
connect to the master; only this field makes you aware of
the problem. The state of the SQL thread is not copied
because it is simpler. If it is running, there is no
problem; if it is not, you can find the error in the
Last_Error field (described later).
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
The error number and error message returned by the most
recently executed statement. An error number of 0 and
message of the empty string mean “no error.” If
the Last_Error value is not empty, it
also appears as a message in the slave's error log. For
example:
Last_Errno: 1051
Last_Error: error 'Unknown table 'z'' on query 'drop table z'
The message indicates that the table z
existed on the master and was dropped there, but it did not
exist on the slave, so DROP
TABLE failed on the slave. (This might occur, for
example, if you forget to copy the table to the slave when
setting up replication.)
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
These fields show the SSL parameters used by the slave to
connect to the master, if any.
Master_SSL_Allowed has these values:
Yes if an SSL connection to the
master is permitted
No if an SSL connection to the master
is not permitted
Ignored if an SSL connection is
permitted but the slave server does not have SSL support
enabled
The values of the other SSL-related fields correspond to the
values of the MASTER_SSL_CA ,
MASTER_SSL_CAPATH ,
MASTER_SSL_CERT ,
MASTER_SSL_CIPHER , and
MASTER_SSL_KEY options to the
CHANGE MASTER TO statement.
See Section 12.6.2.1, “CHANGE MASTER TO Syntax”.
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.
12.5.5.32. 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 19.19, “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.6, “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 |
+--------------------+----------+
The GLOBAL and SESSION
options are new in MySQL 5.0.2. 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.6, “Server Status Variables”.
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.
Note
Before MySQL 5.0.2, SHOW STATUS
returned global status values. Because the default as of 5.0.2
is to return session values, this is incompatible with
previous versions. To issue a SHOW
STATUS statement that will retrieve global status
values for all versions of MySQL, write it like this:
SHOW /*!50002 GLOBAL */ STATUS;
12.5.5.33. 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 19.19, “Extensions to SHOW Statements”.
As of MySQL 5.0.1, 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 ).
Starting with MySQL/InnoDB 5.0.3, the format of
InnoDB tables is reported as
Redundant or Compact .
Prior to 5.0.3, InnoDB tables are always
in the Redundant format.
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.
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).
In the table comment, InnoDB tables report
the free space of the tablespace to which the table belongs. For
a table located in the shared tablespace, this is the free space
of the shared tablespace. If you are using multiple tablespaces
and the table has its own tablespace, the free space is for only
that table. Free space means the number of completely free 1MB
extents minus a safety margin. Even if free space displays as 0,
it may be possible to insert rows as long as new extents need
not be allocated.
For MEMORY 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.
Beginning with MySQL 5.0.3, 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. In addition, the number of replicas is now shown in the
Comment column (as
number_of_replicas ).
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.34. 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 19.19, “Extensions to SHOW Statements”.
Before MySQL 5.0.1, the output from SHOW
TABLES contains a single column of table names.
Beginning with MySQL 5.0.1, this statement also lists any views
in the database. As of MySQL 5.0.2, 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.35. 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 SUPER
privilege. It was implemented in MySQL 5.0.10. 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 19.19, “Extensions to SHOW Statements”.
For the trigger ins_sum as defined in
Section 18.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
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. This
column was added in MySQL 5.0.11.
Definer
The account that created the trigger. This column was added
in MySQL 5.0.17.
You must have the SUPER privilege
to execute SHOW TRIGGERS .
See also Section 19.16, “The INFORMATION_SCHEMA TRIGGERS Table”.
12.5.5.36. 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 19.19, “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.5, “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.3, “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 | / |
| bdb_cache_size | 8388600 |
| bdb_home | /var/lib/mysql/ |
| bdb_log_buffer_size | 32768 |
...
| max_connections | 100 |
| max_connect_errors | 10 |
| max_delayed_threads | 20 |
| max_error_count | 64 |
| max_heap_table_size | 16777216 |
| max_join_size | 4294967295 |
| max_relay_log_size | 0 |
| max_sort_length | 1024 |
...
| 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.0.19-Max |
| version_comment | MySQL Community Edition - Max (GPL) |
| version_compile_machine | i686 |
| version_compile_os | pc-linux-gnu |
| 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.37. 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.14, “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 20.8.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.
As of MySQL 5.0.3, 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.1. 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.5.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.5, “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 and
CREATE USER statements. This
memory is not released by the corresponding
REVOKE and
DROP USER 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:
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.5, “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.
Using FLUSH statements within
stored functions or triggers is not supported in MySQL
5.0. However, you may use
FLUSH in stored procedures, so
long as these are not called from stored functions or triggers.
See Section D.1, “Restrictions on Stored Routines and Triggers”.
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.
In MySQL 5.0.0, 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.4. 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.
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.0.87, 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.2, “FLUSH Syntax”.
reset_option can be any of the
following:
MASTER
Deletes all binary logs listed in the index file, resets the
binary log index file to be empty, and creates a new binary
log file.
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.3, “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.3, “Server System Variables”).
If you are using replication, you should set the variable no
lower than the maximum number of days your slaves might lag
behind the master.
Prior to MySQL 5.0.60, 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.0.60,
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.31, “SHOW SLAVE STATUS Syntax”.
12.6.2.1. CHANGE MASTER TO SyntaxCHANGE MASTER TO master_def [, master_def ] ...
master_def :
MASTER_HOST = 'host_name '
| MASTER_USER = 'user_name '
| MASTER_PASSWORD = 'password '
| MASTER_PORT = port_num
| MASTER_CONNECT_RETRY = interval
| MASTER_LOG_FILE = 'master_log_name '
| MASTER_LOG_POS = master_log_pos
| RELAY_LOG_FILE = 'relay_log_name '
| RELAY_LOG_POS = relay_log_pos
| MASTER_SSL = {0|1}
| MASTER_SSL_CA = 'ca_file_name '
| MASTER_SSL_CAPATH = 'ca_directory_name '
| MASTER_SSL_CERT = 'cert_file_name '
| MASTER_SSL_KEY = 'key_file_name '
| MASTER_SSL_CIPHER = 'cipher_list '
CHANGE MASTER TO changes the
parameters that the slave server uses for connecting to 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 it at all.
Setting this option to an empty string causes
START SLAVE subsequently to
fail. (Bug#28796)
MASTER_USER and
MASTER_PASSWORD are the user name and
password of the account to use for connecting to the master.
MASTER_SSL , MASTER_SSL_CA ,
MASTER_SSL_CAPATH ,
MASTER_SSL_CERT ,
MASTER_SSL_KEY , and
MASTER_SSL_CIPHER 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”. 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.2, “Replication and Binary Logging Options and Variables”.
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.
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.3, “Server System Variables”.
Note that LOAD DATA FROM MASTER does
not copy any tables from the
mysql database. This makes it easy to have
different users and privileges on the master and the slave.
To use LOAD DATA FROM MASTER , the replication
account that is used to connect to the master must have the
RELOAD and
SUPER privileges on the master
and the SELECT privilege for all
master tables you want to load. All master tables for which the
user does not have the SELECT
privilege are ignored by LOAD DATA FROM
MASTER . This is because the master hides them from the
user: LOAD DATA FROM MASTER calls
SHOW DATABASES to know the master
databases to load, but SHOW
DATABASES returns only databases for which the user
has some privilege. See Section 12.5.5.11, “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.10.4, “Miscellaneous Functions”, for a full
description.
The following table shows the maximum allowable length for the
string-valued options.
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.31, “SHOW SLAVE STATUS Syntax”, and
Section 16.1.3.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.0 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.0.82. Previously, it took
effect immediately; beginning with MySQL 5.0.82, it waits
until the current replication event group (if any) has
finished executing, 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.0 for backward compatibility,
but is deprecated.
12.7. SQL Syntax for Prepared Statements
MySQL 5.0 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 20.8.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.
ANALYZE TABLE ,
OPTIMIZE TABLE , and
REPAIR TABLE are also supported as of
MySQL 5.0.23.
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 18.2, “Using Stored Routines (Procedures and Functions)”.
As of MySQL 5.0.7, 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.0. 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 cannot be used within stored
routines (procedures or functions), or triggers. This restriction is
lifted as of MySQL 5.0.13 for stored procedures, but not for 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).
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.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 and triggers.
These objects are defined in terms of SQL code that is stored on the
server for later invocation (see
Chapter 18, 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 18.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.9, “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”.
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 and Triggers”.
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 procedures and functions and
triggers. 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 or triggers.
|
|