Table of Contents
- 13.1 Data Definition Statements
- 13.1.1 Atomic Data Definition Statement Support
- 13.1.2 ALTER DATABASE Statement
- 13.1.3 ALTER EVENT Statement
- 13.1.4 ALTER FUNCTION Statement
- 13.1.5 ALTER INSTANCE Statement
- 13.1.6 ALTER LOGFILE GROUP Statement
- 13.1.7 ALTER PROCEDURE Statement
- 13.1.8 ALTER SERVER Statement
- 13.1.9 ALTER TABLE Statement
- 13.1.10 ALTER TABLESPACE Statement
- 13.1.11 ALTER VIEW Statement
- 13.1.12 CREATE DATABASE Statement
- 13.1.13 CREATE EVENT Statement
- 13.1.14 CREATE FUNCTION Statement
- 13.1.15 CREATE INDEX Statement
- 13.1.16 CREATE LOGFILE GROUP Statement
- 13.1.17 CREATE PROCEDURE and CREATE FUNCTION Statements
- 13.1.18 CREATE SERVER Statement
- 13.1.19 CREATE SPATIAL REFERENCE SYSTEM Statement
- 13.1.20 CREATE TABLE Statement
- 13.1.21 CREATE TABLESPACE Statement
- 13.1.22 CREATE TRIGGER Statement
- 13.1.23 CREATE VIEW Statement
- 13.1.24 DROP DATABASE Statement
- 13.1.25 DROP EVENT Statement
- 13.1.26 DROP FUNCTION Statement
- 13.1.27 DROP INDEX Statement
- 13.1.28 DROP LOGFILE GROUP Statement
- 13.1.29 DROP PROCEDURE and DROP FUNCTION Statements
- 13.1.30 DROP SERVER Statement
- 13.1.31 DROP SPATIAL REFERENCE SYSTEM Statement
- 13.1.32 DROP TABLE Statement
- 13.1.33 DROP TABLESPACE Statement
- 13.1.34 DROP TRIGGER Statement
- 13.1.35 DROP VIEW Statement
- 13.1.36 RENAME TABLE Statement
- 13.1.37 TRUNCATE TABLE Statement
- 13.2 Data Manipulation Statements
- 13.2.1 CALL Statement
- 13.2.2 DELETE Statement
- 13.2.3 DO Statement
- 13.2.4 HANDLER Statement
- 13.2.5 IMPORT TABLE Statement
- 13.2.6 INSERT Statement
- 13.2.7 LOAD DATA Statement
- 13.2.8 LOAD XML Statement
- 13.2.9 REPLACE Statement
- 13.2.10 SELECT Statement
- 13.2.11 Subqueries
- 13.2.12 TABLE Statement
- 13.2.13 UPDATE Statement
- 13.2.14 VALUES Statement
- 13.2.15 WITH (Common Table Expressions)
- 13.3 Transactional and Locking Statements
- 13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Statements
- 13.3.2 Statements That Cannot Be Rolled Back
- 13.3.3 Statements That Cause an Implicit Commit
- 13.3.4 SAVEPOINT, ROLLBACK TO SAVEPOINT, and RELEASE SAVEPOINT Statements
- 13.3.5 LOCK INSTANCE FOR BACKUP and UNLOCK INSTANCE Statements
- 13.3.6 LOCK TABLES and UNLOCK TABLES Statements
- 13.3.7 SET TRANSACTION Statement
- 13.3.8 XA Transactions
- 13.4 Replication Statements
- 13.5 Prepared Statements
- 13.6 Compound Statement Syntax
- 13.7 Database Administration Statements
- 13.8 Utility Statements
This chapter describes the syntax for the SQL statements supported by MySQL.
- 13.1.1 Atomic Data Definition Statement Support
- 13.1.2 ALTER DATABASE Statement
- 13.1.3 ALTER EVENT Statement
- 13.1.4 ALTER FUNCTION Statement
- 13.1.5 ALTER INSTANCE Statement
- 13.1.6 ALTER LOGFILE GROUP Statement
- 13.1.7 ALTER PROCEDURE Statement
- 13.1.8 ALTER SERVER Statement
- 13.1.9 ALTER TABLE Statement
- 13.1.10 ALTER TABLESPACE Statement
- 13.1.11 ALTER VIEW Statement
- 13.1.12 CREATE DATABASE Statement
- 13.1.13 CREATE EVENT Statement
- 13.1.14 CREATE FUNCTION Statement
- 13.1.15 CREATE INDEX Statement
- 13.1.16 CREATE LOGFILE GROUP Statement
- 13.1.17 CREATE PROCEDURE and CREATE FUNCTION Statements
- 13.1.18 CREATE SERVER Statement
- 13.1.19 CREATE SPATIAL REFERENCE SYSTEM Statement
- 13.1.20 CREATE TABLE Statement
- 13.1.21 CREATE TABLESPACE Statement
- 13.1.22 CREATE TRIGGER Statement
- 13.1.23 CREATE VIEW Statement
- 13.1.24 DROP DATABASE Statement
- 13.1.25 DROP EVENT Statement
- 13.1.26 DROP FUNCTION Statement
- 13.1.27 DROP INDEX Statement
- 13.1.28 DROP LOGFILE GROUP Statement
- 13.1.29 DROP PROCEDURE and DROP FUNCTION Statements
- 13.1.30 DROP SERVER Statement
- 13.1.31 DROP SPATIAL REFERENCE SYSTEM Statement
- 13.1.32 DROP TABLE Statement
- 13.1.33 DROP TABLESPACE Statement
- 13.1.34 DROP TRIGGER Statement
- 13.1.35 DROP VIEW Statement
- 13.1.36 RENAME TABLE Statement
- 13.1.37 TRUNCATE TABLE Statement
MySQL 8.0 supports atomic Data Definition Language (DDL) statements. This feature is referred to as atomic DDL. An atomic DDL statement combines the data dictionary updates, storage engine operations, and binary log writes associated with a DDL operation into a single, atomic operation. The operation is either committed, with applicable changes persisted to the data dictionary, storage engine, and binary log, or is rolled back, even if the server halts during the operation.
Atomic DDL is not transactional
DDL. DDL statements, atomic or otherwise, implicitly
end any transaction that is active in the current session, as if
you had done a COMMIT
before
executing the statement. This means that DDL statements cannot
be performed within another transaction, within transaction
control statements such as
START TRANSACTION ...
COMMIT
, or combined with other statements within the
same transaction.
Atomic DDL is made possible by the introduction of the MySQL data dictionary in MySQL 8.0. In earlier MySQL versions, metadata was stored in metadata files, nontransactional tables, and storage engine-specific dictionaries, which necessitated intermediate commits. Centralized, transactional metadata storage provided by the MySQL data dictionary removed this barrier, making it possible to restructure DDL statement operations to be atomic.
The atomic DDL feature is described under the following topics in this section:
The atomic DDL feature supports both table and non-table DDL
statements. Table-related DDL operations require storage engine
support, whereas non-table DDL operations do not. Currently,
only the InnoDB
storage engine supports
atomic DDL.
Supported table DDL statements include
CREATE
,ALTER
, andDROP
statements for databases, tablespaces, tables, and indexes, and theTRUNCATE TABLE
statement.Supported non-table DDL statements include:
The following statements are not supported by the atomic DDL feature:
Table-related DDL statements that involve a storage engine other than
InnoDB
.INSTALL PLUGIN
andUNINSTALL PLUGIN
statements.INSTALL COMPONENT
andUNINSTALL COMPONENT
statements.CREATE SERVER
,ALTER SERVER
, andDROP SERVER
statements.
The characteristics of atomic DDL statements include the following:
Metadata updates, binary log writes, and storage engine operations, where applicable, are combined into a single atomic operation.
There are no intermediate commits at the SQL layer during the DDL operation.
Where applicable:
The state of data dictionary, routine, event, and UDF caches is consistent with the status of the DDL operation, meaning that caches are updated to reflect whether or not the DDL operation was completed successfully or rolled back.
The storage engine methods involved in a DDL operation do not perform intermediate commits, and the storage engine registers itself as part of the DDL operation.
The storage engine supports redo and rollback of DDL operations, which is performed in the Post-DDL phase of the DDL operation.
The visible behaviour of DDL operations is atomic, which changes the behavior of some DDL statements. See Changes in DDL Statement Behavior.
This section describes changes in DDL statement behavior due to the introduction of atomic DDL support.
DROP TABLE
operations are fully atomic if all named tables use an atomic DDL-supported storage engine. The statement either drops all tables successfully or is rolled back.DROP TABLE
fails with an error if a named table does not exist, and no changes are made, regardless of the storage engine. This change in behavior is demonstrated in the following example, where theDROP TABLE
statement fails because a named table does not exist:mysql>
CREATE TABLE t1 (c1 INT);
mysql>DROP TABLE t1, t2;
ERROR 1051 (42S02): Unknown table 'test.t2' mysql>SHOW TABLES;
+----------------+ | Tables_in_test | +----------------+ | t1 | +----------------+Prior to the introduction of atomic DDL,
DROP TABLE
reports an error for the named table that does not exist but succeeds for the named table that does exist:mysql>
CREATE TABLE t1 (c1 INT);
mysql>DROP TABLE t1, t2;
ERROR 1051 (42S02): Unknown table 'test.t2' mysql>SHOW TABLES;
Empty set (0.00 sec)NoteDue to this change in behavior, a partially completed
DROP TABLE
statement on a MySQL 5.7 replication source server fails when replicated on a MySQL 8.0 replica. To avoid this failure scenario, useIF EXISTS
syntax inDROP TABLE
statements to prevent errors from occurring for tables that do not exist.DROP DATABASE
is atomic if all tables use an atomic DDL-supported storage engine. The statement either drops all objects successfully or is rolled back. However, removal of the database directory from the file system occurs last and is not part of the atomic operation. If removal of the database directory fails due to a file system error or server halt, theDROP DATABASE
transaction is not rolled back.For tables that do not use an atomic DDL-supported storage engine, table deletion occurs outside of the atomic
DROP TABLE
orDROP DATABASE
transaction. Such table deletions are written to the binary log individually, which limits the discrepancy between the storage engine, data dictionary, and binary log to one table at most in the case of an interruptedDROP TABLE
orDROP DATABASE
operation. For operations that drop multiple tables, the tables that do not use an atomic DDL-supported storage engine are dropped before tables that do.CREATE TABLE
,ALTER TABLE
,RENAME TABLE
,TRUNCATE TABLE
,CREATE TABLESPACE
, andDROP TABLESPACE
operations for tables that use an atomic DDL-supported storage engine are either fully committed or rolled back if the server halts during their operation. In earlier MySQL releases, interruption of these operations could cause discrepancies between the storage engine, data dictionary, and binary log, or leave behind orphan files.RENAME TABLE
operations are only atomic if all named tables use an atomic DDL-supported storage engine.As of MySQL 8.0.21, on storage engines that support atomic DDL, the
CREATE TABLE ... SELECT
statement is logged as one transaction in the binary log when row-based replication is in use. Previously, it was logged as two transactions, one to create the table, and the other to insert data. A server failure between the two transactions or while inserting data could result in replication of an empty table. With the introduction of atomic DDL support,CREATE TABLE ... SELECT
statements are now safe for row-based replication and permitted for use with GTID-based replication.On storage engines that support both atomic DDL and foreign key constraints, creation of foreign keys is not permitted in
CREATE TABLE ... SELECT
statements when row-based replication is in use. Foreign key constraints can be added later usingALTER TABLE
.When
CREATE TABLE ... SELECT
is applied as an atomic operation, a metadata lock is held on the table while data is inserted, which prevents concurrent access to the table for the duration of the operation.DROP VIEW
fails if a named view does not exist, and no changes are made. The change in behavior is demonstrated in this example, where theDROP VIEW
statement fails because a named view does not exist:mysql>
CREATE VIEW test.viewA AS SELECT * FROM t;
mysql>DROP VIEW test.viewA, test.viewB;
ERROR 1051 (42S02): Unknown table 'test.viewB' mysql>SHOW FULL TABLES IN test WHERE TABLE_TYPE LIKE 'VIEW';
+----------------+------------+ | Tables_in_test | Table_type | +----------------+------------+ | viewA | VIEW | +----------------+------------+Prior to the introduction of atomic DDL,
DROP VIEW
returns an error for the named view that does not exist but succeeds for the named view that does exist:mysql>
CREATE VIEW test.viewA AS SELECT * FROM t;
mysql>DROP VIEW test.viewA, test.viewB;
ERROR 1051 (42S02): Unknown table 'test.viewB' mysql>SHOW FULL TABLES IN test WHERE TABLE_TYPE LIKE 'VIEW';
Empty set (0.00 sec)NoteDue to this change in behavior, a partially completed
DROP VIEW
operation on a MySQL 5.7 replication source server fails when replicated on a MySQL 8.0 replica. To avoid this failure scenario, useIF EXISTS
syntax inDROP VIEW
statements to prevent an error from occurring for views that do not exist.Partial execution of account management statements is no longer permitted. Account management statements either succeed for all named users or roll back and have no effect if an error occurs. In earlier MySQL versions, account management statements that name multiple users could succeed for some users and fail for others.
The change in behavior is demonstrated in this example, where the second
CREATE USER
statement returns an error but fails because it cannot succeed for all named users.mysql>
CREATE USER userA;
mysql>CREATE USER userA, userB;
ERROR 1396 (HY000): Operation CREATE USER failed for 'userA'@'%' mysql>SELECT User FROM mysql.user WHERE User LIKE 'user%';
+-------+ | User | +-------+ | userA | +-------+Prior to the introduction of atomic DDL, the second
CREATE USER
statement returns an error for the named user that does not exist but succeeds for the named user that does exist:mysql>
CREATE USER userA;
mysql>CREATE USER userA, userB;
ERROR 1396 (HY000): Operation CREATE USER failed for 'userA'@'%' mysql>SELECT User FROM mysql.user WHERE User LIKE 'user%';
+-------+ | User | +-------+ | userA | | userB | +-------+NoteDue to this change in behavior, partially completed account management statements on a MySQL 5.7 replication source server fail when replicated on a MySQL 8.0 replica. To avoid this failure scenario, use
IF EXISTS
orIF NOT EXISTS
syntax, as appropriate, in account management statements to prevent errors related to named users.
Currently, only the InnoDB
storage engine
supports atomic DDL. Storage engines that do not support atomic
DDL are exempted from DDL atomicity. DDL operations involving
exempted storage engines remain capable of introducing
inconsistencies that can occur when operations are interrupted
or only partially completed.
To support redo and rollback of DDL operations,
InnoDB
writes DDL logs to the
mysql.innodb_ddl_log
table, which is a hidden
data dictionary table that resides in the
mysql.ibd
data dictionary tablespace.
To view DDL logs that are written to the
mysql.innodb_ddl_log
table during a DDL
operation, enable the
innodb_print_ddl_logs
configuration option. For more information, see
Viewing DDL Logs.
The redo logs for changes to the
mysql.innodb_ddl_log
table are flushed to
disk immediately regardless of the
innodb_flush_log_at_trx_commit
setting. Flushing the redo logs immediately avoids situations
where data files are modified by DDL operations but the redo
logs for changes to the
mysql.innodb_ddl_log
table resulting from
those operations are not persisted to disk. Such a situation
could cause errors during rollback or recovery.
The InnoDB
storage engine executes DDL
operations in phases. DDL operations such as
ALTER TABLE
may perform the
Prepare and Perform
phases multiple times prior to the Commit
phase.
Prepare: Create the required objects and write the DDL logs to the
mysql.innodb_ddl_log
table. The DDL logs define how to roll forward and roll back the DDL operation.Perform: Perform the DDL operation. For example, perform a create routine for a
CREATE TABLE
operation.Commit: Update the data dictionary and commit the data dictionary transaction.
Post-DDL: Replay and remove DDL logs from the
mysql.innodb_ddl_log
table. To ensure that rollback can be performed safely without introducing inconsistencies, file operations such as renaming or removing data files are performed in this final phase. This phase also removes dynamic metadata from themysql.innodb_dynamic_metadata
data dictionary table forDROP TABLE
,TRUNCATE TABLE
, and other DDL operations that rebuild the table.
DDL logs are replayed and removed from the
mysql.innodb_ddl_log
table during the
Post-DDL phase, regardless of whether the
DDL operation is committed or rolled back. DDL logs should only
remain in the mysql.innodb_ddl_log
table if
the server is halted during a DDL operation. In this case, the
DDL logs are replayed and removed after recovery.
In a recovery situation, a DDL operation may be committed or
rolled back when the server is restarted. If the data dictionary
transaction that was performed during the
Commit phase of a DDL operation is present
in the redo log and binary log, the operation is considered
successful and is rolled forward. Otherwise, the incomplete data
dictionary transaction is rolled back when
InnoDB
replays data dictionary redo logs, and
the DDL operation is rolled back.
To view DDL logs that are written to the
mysql.innodb_ddl_log
data dictionary table
during atomic DDL operations that involve the
InnoDB
storage engine, enable
innodb_print_ddl_logs
to have
MySQL write the DDL logs to stderr
. Depending
on the host operating system and MySQL configuration,
stderr
may be the error log, terminal, or
console window. See
Section 5.4.2.2, “Default Error Log Destination Configuration”.
InnoDB
writes DDL logs to the
mysql.innodb_ddl_log
table to support redo
and rollback of DDL operations. The
mysql.innodb_ddl_log
table is a hidden data
dictionary table that resides in the
mysql.ibd
data dictionary tablespace. Like
other hidden data dictionary tables, the
mysql.innodb_ddl_log
table cannot be accessed
directly in non-debug versions of MySQL. (See
Section 14.1, “Data Dictionary Schema”.) The structure of the
mysql.innodb_ddl_log
table corresponds to
this definition:
CREATE TABLE mysql.innodb_ddl_log ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, thread_id BIGINT UNSIGNED NOT NULL, type INT UNSIGNED NOT NULL, space_id INT UNSIGNED, page_no INT UNSIGNED, index_id BIGINT UNSIGNED, table_id BIGINT UNSIGNED, old_file_path VARCHAR(512) COLLATE UTF8_BIN, new_file_path VARCHAR(512) COLLATE UTF8_BIN, KEY(thread_id) );
id
: A unique identifier for a DDL log record.thread_id
: Each DDL log record is assigned athread_id
, which is used to replay and remove DDL logs that belong to a particular DDL operation. DDL operations that involve multiple data file operations generate multiple DDL log records.type
: The DDL operation type. Types includeFREE
(drop an index tree),DELETE
(delete a file),RENAME
(rename a file), orDROP
(drop metadata from themysql.innodb_dynamic_metadata
data dictionary table).space_id
: The tablespace ID.page_no
: A page that contains allocation information; an index tree root page, for example.index_id
: The index ID.table_id
: The table ID.old_file_path
: The old tablespace file path. Used by DDL operations that create or drop tablespace files; also used by DDL operations that rename a tablespace.new_file_path
: The new tablespace file path. Used by DDL operations that rename tablespace files.
This example demonstrates enabling
innodb_print_ddl_logs
to view
DDL logs written to strderr
for a
CREATE TABLE
operation.
mysql> SET GLOBAL innodb_print_ddl_logs=1; mysql> CREATE TABLE t1 (c1 INT) ENGINE = InnoDB;
[Note] [000000] InnoDB: DDL log insert : [DDL record: DELETE SPACE, id=18, thread_id=7, space_id=5, old_file_path=./test/t1.ibd] [Note] [000000] InnoDB: DDL log delete : by id 18 [Note] [000000] InnoDB: DDL log insert : [DDL record: REMOVE CACHE, id=19, thread_id=7, table_id=1058, new_file_path=test/t1] [Note] [000000] InnoDB: DDL log delete : by id 19 [Note] [000000] InnoDB: DDL log insert : [DDL record: FREE, id=20, thread_id=7, space_id=5, index_id=132, page_no=4] [Note] [000000] InnoDB: DDL log delete : by id 20 [Note] [000000] InnoDB: DDL log post ddl : begin for thread id : 7 [Note] [000000] InnoDB: DDL log post ddl : end for thread id : 7
ALTER {DATABASE | SCHEMA} [db_name
]alter_option
...alter_option
: { [DEFAULT] CHARACTER SET [=]charset_name
| [DEFAULT] COLLATE [=]collation_name
| [DEFAULT] ENCRYPTION [=] {'Y' | 'N'} | READ ONLY [=] {DEFAULT | 0 | 1} }
ALTER DATABASE
enables you to
change the overall characteristics of a database. These
characteristics are stored in the data dictionary. This statement
requires the ALTER
privilege on the
database. ALTER
SCHEMA
is a synonym for ALTER
DATABASE
.
If the database name is omitted, the statement applies to the default database. In that case, an error occurs if there is no default database.
For any alter_option
omitted from the
statement, the database retains its current option value, with the
exception that changing the character set may change the collation
and vice versa.
Character Set and Collation Options
The CHARACTER SET
option changes the default
database character set. The COLLATE
option
changes the default database collation. For information about
character set and collation names, see Chapter 10, Character Sets, Collations, Unicode.
To see the available character sets and collations, use the
SHOW CHARACTER SET
and
SHOW COLLATION
statements,
respectively. See Section 13.7.7.3, “SHOW CHARACTER SET Statement”, and
Section 13.7.7.4, “SHOW COLLATION Statement”.
A stored routine that uses the database defaults when the routine is created includes those defaults as part of its definition. (In a stored routine, variables with character data types use the database defaults if the character set or collation are not specified explicitly. See Section 13.1.17, “CREATE PROCEDURE and CREATE FUNCTION Statements”.) If you change the default character set or collation for a database, any stored routines that are to use the new defaults must be dropped and recreated.
Encryption Option
The ENCRYPTION
option, introduced in MySQL
8.0.16, defines the default database encryption, which is
inherited by tables created in the database. The permitted values
are 'Y'
(encryption enabled) and
'N'
(encryption disabled). Only newly created
tables inherit the default database encryption. For existing
tables associated with the database, their encryption remains
unchanged. If the
table_encryption_privilege_check
system variable is enabled, the
TABLE_ENCRYPTION_ADMIN
privilege is
required to specify a default encryption setting that differs from
the value of the
default_table_encryption
system
variable. For more information, see
Defining an Encryption Default for Schemas and General Tablespaces.
Read Only Option
The READ ONLY
option, introduced in MySQL
8.0.22, controls whether to permit modification of the database
and objects within it. The permitted values are
DEFAULT
or 0
(not read only)
and 1
(read only). This option is useful for
database migration because a database for which READ
ONLY
is enabled can be migrated to another MySQL
instance without concern that the database might be changed during
the operation.
With NDB Cluster, making a database read only on one mysqld server is synchronized to other mysqld servers in the same cluster, so that the database becomes read only on all mysqld servers.
The READ ONLY
option, if enabled, is displayed
in the INFORMATION_SCHEMA
SCHEMATA_EXTENSIONS
table. See
Section 26.32, “The INFORMATION_SCHEMA SCHEMATA_EXTENSIONS Table”.
The READ ONLY
option cannot be enabled for
these system schemas: mysql
,
information_schema
,
performance_schema
.
In ALTER DATABASE
statements, the
READ ONLY
option interacts with other instances
of itself and with other options as follows:
An error occurs if multiple instances of
READ ONLY
conflict (for example,READ ONLY = 1 READ ONLY = 0
).An
ALTER DATABASE
statement that contains only (nonconflicting)READ ONLY
options is permitted even for a read-only database.A mix of (nonconflicting)
READ ONLY
options with other options is permitted if the read-only state of the database either before or after the statement permits modifications. If the read-only state both before and after prohibits changes, an error occurs.This statement succeeds whether or not the database is read only:
ALTER DATABASE mydb READ ONLY = 0 DEFAULT COLLATE utf8mb4_bin;
This statement succeeds if the database is not read only, but fails if it is already read only:
ALTER DATABASE mydb READ ONLY = 1 DEFAULT COLLATE utf8mb4_bin;
Enabling READ ONLY
affects all users of the
database, with these exceptions that are not subject to read-only
checks:
Statements executed by the server as part of server initialization, restart, upgrade, or replication.
Statements in a file named at server startup by the
init_file
system variable.TEMPORARY
tables; it is possible to create, alter, drop, and write toTEMPORARY
tables in a read-only database.NDB Cluster non-SQL inserts and updates.
Other than for the excepted operations just listed, enabling
READ ONLY
prohibits write operations to the
database and its objects, including their definitions, data, and
metadata. The following list details affected SQL statements and
operations:
The database itself:
ALTER DATABASE
(except to change theREAD ONLY
option)
Views:
Selecting from views that invoke functions with side effects.
Updating updatable views.
Statements that create or drop objects in a writable database are rejected if they affect metadata of a view in a read-only database (for example, by making the view valid or invalid).
Stored routines:
CALL
(of procedures with side effects)SELECT
(of functions with side effects)For procedures and functions, read-only checks follow prelocking behavior. For
CALL
statements, read-only checks are done on a per-statement basis, so if some conditionally executed statement writing to a read-only database does not actually execute, the call still succeeds. On the other hand, for a function called within aSELECT
, execution of the function body happens in prelocked mode. As long as a some statement within the function writes to a read-only database, execution of the function fails with an error regardless of whether the statement actually executes.
Triggers:
Trigger invocation.
Events:
Event execution:
Executing an event in the database fails because that would change the last-execution timestamp, which is event metadata stored in the data dictionary. Failure of event execution also has the effect of causing the event scheduler to stop.
If an event writes to an object in a read-only database, execution of the event fails with an error, but the event scheduler is not stopped.
Tables:
For cascading foreign keys where the child table is in a read-only database, updates and deletes on the parent are rejected even if the child table is not directly affected.
For a
MERGE
table such asCREATE TABLE s1.t(i int) ENGINE MERGE UNION (s2.t, s3.t), INSERT_METHOD=...
, the following behavior applies:Inserting into the
MERGE
table (INSERT into s1.t
) fails if at least one ofs1
,s2
,s3
is read only, regardless of insert method. The insert is refused even if it would actually end up in a writable table.Dropping the
MERGE
table (DROP TABLE s1.t
) succeeds as long ass1
is not read only. It is permitted to drop aMERGE
table that refers to a read-only database.
An ALTER DATABASE
statement blocks
until all concurrent transactions that have already accessed an
object in the database being altered have committed. Conversely, a
write transaction accessing an object in a database being altered
in a concurrent ALTER DATABASE
blocks until the ALTER DATABASE
has
committed.
If the Clone plugin is used to clone a local or remote data
directory, the databases in the clone retain the read-only state
they had in the source data directory. The read-only state does
not affect the cloning process itself. If it is not desirable to
have the same database read-only state in the clone, the option
must be changed explicitly for the clone after the cloning process
has finished, using ALTER DATABASE
operations on the clone.
When cloning from a donor to a recipient, if the recipient has a user database that is read only, cloning fails with an error message. Cloning may be retried after making the database writable.
READ ONLY
is permitted for
ALTER DATABASE
, but not for
CREATE DATABASE
. However, for a
read-only database, the statement produced by
SHOW CREATE DATABASE
does include
READ ONLY=1
within a comment to indicate its
read-only status:
mysql>ALTER DATABASE mydb READ ONLY = 1;
mysql>SHOW CREATE DATABASE mydb\G
*************************** 1. row *************************** Database: mydb Create Database: CREATE DATABASE `mydb` /*!40100 DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci */ /*!80016 DEFAULT ENCRYPTION='N' */ /* READ ONLY = 1 */
If the server executes a CREATE
DATABASE
statement containing such a comment, the server
ignores the comment and the READ ONLY
option is
not processed. This has implications for
mysqldump and mysqlpump,
which use SHOW CREATE DATABASE
to
produce CREATE DATABASE
statements
in dump output:
In a dump file, the
CREATE DATABASE
statement for a read-only database contains the commentedREAD ONLY
option.The dump file can be restored as usual, but because the server ignores the commented
READ ONLY
option, the restored database is not read only. If the database is to be read ony after being restored, you must executeALTER DATABASE
manually to make it so.
Suppose that mydb
is read only and you dump it
as follows:
shell> mysqldump --databases mydb > mydb.sql
A restore operation later must be followed by
ALTER DATABASE
if
mydb
should still be read only:
shell>mysql
mysql>SOURCE mydb.sql;
mysql>ALTER DATABASE mydb READ ONLY = 1;
MySQL Enterprise Backup is not subject to this issue. It backs up and restores a
read-only database like any other, but enables the READ
ONLY
option at restore time if it was enabled at backup
time.
ALTER DATABASE
is written to the
binary log, so a change to the READ ONLY
option
on a replication source server also affects replicas. To prevent
this from happening, binary logging must be disabled prior to
execution of the ALTER DATABASE
statement. For example, to prepare for migrating a database
without affecting replicas, perform these operations:
Within a single session, disable binary logging and enable
READ ONLY
for the database:mysql>
SET sql_log_bin = OFF;
mysql>ALTER DATABASE mydb READ ONLY = 1;
Dump the database, for example, with mysqldump or mysqlpump:
shell>
mysqldump --databases mydb > mydb.sql
Within a single session, disable binary logging and disable
READ ONLY
for the database:mysql>
SET sql_log_bin = OFF;
mysql>ALTER DATABASE mydb READ ONLY = 0;
ALTER [DEFINER =user
] EVENTevent_name
[ON SCHEDULEschedule
] [ON COMPLETION [NOT] PRESERVE] [RENAME TOnew_event_name
] [ENABLE | DISABLE | DISABLE ON SLAVE] [COMMENT 'string
'] [DOevent_body
]
The ALTER EVENT
statement changes
one or more of the characteristics of an existing event without
the need to drop and recreate it. The syntax for each of the
DEFINER
, ON SCHEDULE
,
ON COMPLETION
, COMMENT
,
ENABLE
/ DISABLE
, and
DO
clauses is exactly the same as
when used with CREATE EVENT
. (See
Section 13.1.13, “CREATE EVENT Statement”.)
Any user can alter an event defined on a database for which that
user has the EVENT
privilege. When
a user executes a successful ALTER
EVENT
statement, that user becomes the definer for the
affected event.
ALTER EVENT
works only with an
existing event:
mysql>ALTER EVENT no_such_event
>ON SCHEDULE
>EVERY '2:3' DAY_HOUR;
ERROR 1517 (HY000): Unknown event 'no_such_event'
In each of the following examples, assume that the event named
myevent
is defined as shown here:
CREATE EVENT myevent ON SCHEDULE EVERY 6 HOUR COMMENT 'A sample comment.' DO UPDATE myschema.mytable SET mycol = mycol + 1;
The following statement changes the schedule for
myevent
from once every six hours starting
immediately to once every twelve hours, starting four hours from
the time the statement is run:
ALTER EVENT myevent ON SCHEDULE EVERY 12 HOUR STARTS CURRENT_TIMESTAMP + INTERVAL 4 HOUR;
It is possible to change multiple characteristics of an event in a
single statement. This example changes the SQL statement executed
by myevent
to one that deletes all records from
mytable
; it also changes the schedule for the
event such that it executes once, one day after this
ALTER EVENT
statement is run.
ALTER EVENT myevent ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 1 DAY DO TRUNCATE TABLE myschema.mytable;
Specify the options in an ALTER
EVENT
statement only for those characteristics that you
want to change; omitted options keep their existing values. This
includes any default values for CREATE
EVENT
such as ENABLE
.
To disable myevent
, use this
ALTER EVENT
statement:
ALTER EVENT myevent DISABLE;
The ON SCHEDULE
clause may use expressions
involving built-in MySQL functions and user variables to obtain
any of the timestamp
or
interval
values which it contains. You
cannot use stored routines or user-defined functions in such
expressions, and you cannot use any table references; however, you
can use SELECT FROM DUAL
. This is true for both
ALTER EVENT
and
CREATE EVENT
statements. References
to stored routines, user-defined functions, and tables in such
cases are specifically not permitted, and fail with an error (see
Bug #22830).
Although an ALTER EVENT
statement
that contains another ALTER EVENT
statement in its DO
clause appears
to succeed, when the server attempts to execute the resulting
scheduled event, the execution fails with an error.
To rename an event, use the ALTER
EVENT
statement's RENAME TO
clause.
This statement renames the event myevent
to
yourevent
:
ALTER EVENT myevent RENAME TO yourevent;
You can also move an event to a different database using
ALTER EVENT ... RENAME TO ...
and
notation, as shown here:
db_name.event_name
ALTER EVENT olddb.myevent RENAME TO newdb.myevent;
To execute the previous statement, the user executing it must have
the EVENT
privilege on both the
olddb
and newdb
databases.
There is no RENAME EVENT
statement.
The value DISABLE ON SLAVE
is used on a replica
instead of ENABLE
or DISABLE
to indicate an event that was created on the replication source
server and replicated to the replica, but that is not executed on
the replica. Normally, DISABLE ON SLAVE
is set
automatically as required; however, there are some circumstances
under which you may want or need to change it manually. See
Section 17.5.1.16, “Replication of Invoked Features”, for more
information.
ALTER FUNCTIONfunc_name
[characteristic
...]characteristic
: { COMMENT 'string
' | LANGUAGE SQL | { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA } | SQL SECURITY { DEFINER | INVOKER } }
This statement can be used to change the characteristics of a
stored function. More than one change may be specified in an
ALTER FUNCTION
statement. However,
you cannot change the parameters or body of a stored function
using this statement; to make such changes, you must drop and
re-create the function using DROP
FUNCTION
and CREATE
FUNCTION
.
You must have the ALTER ROUTINE
privilege for the function. (That privilege is granted
automatically to the function creator.) If binary logging is
enabled, the ALTER FUNCTION
statement might also require the
SUPER
privilege, as described in
Section 25.7, “Stored Program Binary Logging”.
ALTER INSTANCEinstance_action
instance_action
: { | {ENABLE|DISABLE} INNODB REDO_LOG | ROTATE INNODB MASTER KEY | ROTATE BINLOG MASTER KEY | RELOAD TLS [FOR CHANNEL {mysql_main | mysql_admin}] [NO ROLLBACK ON ERROR] }
ALTER INSTANCE
defines actions applicable to a
MySQL server instance. The statement supports these actions:
ALTER INSTANCE {ENABLE | DISABLE} INNODB REDO_LOG
This action enables or disables
InnoDB
redo logging. Redo logging is enabled by default. This feature is intended only for loading data into a new MySQL instance. The statement is not written to the binary log. Introduced in MySQL 8.0.21.WarningDo not disable redo logging on a production system. While it is permitted to shutdown and restart the server while redo logging is disabled, an unexpected server stoppage while redo logging is disabled can cause data loss and instance corruption.
An
ALTER INSTANCE [ENABLE|DISABLE] INNODB REDO_LOG
operation requires an exclusive backup lock, which prevents otherALTER INSTANCE
operations from executing concurrently. OtherALTER INSTANCE
operations must wait for the lock to be released before executing.For more information, see Disabling Redo Logging.
ALTER INSTANCE ROTATE INNODB MASTER KEY
This action rotates the master encryption key used for
InnoDB
tablespace encryption. Key rotation requires theENCRYPTION_KEY_ADMIN
orSUPER
privilege. To perform this action, a keyring plugin must be installed and configured. For instructions, see Section 6.4.4, “The MySQL Keyring”.ALTER INSTANCE ROTATE INNODB MASTER KEY
supports concurrent DML. However, it cannot be run concurrently withCREATE TABLE ... ENCRYPTION
orALTER TABLE ... ENCRYPTION
operations, and locks are taken to prevent conflicts that could arise from concurrent execution of these statements. If one of the conflicting statements is running, it must complete before another can proceed.ALTER INSTANCE ROTATE INNODB MASTER KEY
statements are written to the binary log so that they can be executed on replicated servers.For additional
ALTER INSTANCE ROTATE INNODB MASTER KEY
usage information, see Section 15.13, “InnoDB Data-at-Rest Encryption”.ALTER INSTANCE ROTATE BINLOG MASTER KEY
This action rotates the binary log master key used for binary log encryption. Key rotation for the binary log master key requires the
BINLOG_ENCRYPTION_ADMIN
orSUPER
privilege. The statement cannot be used if thebinlog_encryption
system variable is set toOFF
. To perform this action, a keyring plugin must be installed and configured. For instructions, see Section 6.4.4, “The MySQL Keyring”.ALTER INSTANCE ROTATE BINLOG MASTER KEY
actions are not written to the binary log and are not executed on replicas. Binary log master key rotation can therefore be carried out in replication environments including a mix of MySQL versions. To schedule regular rotation of the binary log master key on all applicable source and replica servers, you can enable the MySQL Event Scheduler on each server and issue theALTER INSTANCE ROTATE BINLOG MASTER KEY
statement using aCREATE EVENT
statement. If you rotate the binary log master key because you suspect that the current or any of the previous binary log master keys might have been compromised, issue the statement on every applicable source and replica server, which enables you to verify immediate compliance.For additional
ALTER INSTANCE ROTATE BINLOG MASTER KEY
usage information, including what to do if the process does not complete correctly or is interrupted by an unexpected server halt, see Section 17.3.2, “Encrypting Binary Log Files and Relay Log Files”.This action reconfigures a TLS context from the current values of the system variables that define the context. It also updates the status variables that reflect the active context values. This action requires the
CONNECTION_ADMIN
privilege. For additional information about reconfiguring the TLS context, including which system and status variables are context-related, see Server-Side Runtime Configuration and Monitoring for Encrypted Connections.By default, the statement reloads the TLS context for the main connection interface. If the
FOR CHANNEL
clause (available as of MySQL 8.0.21) is given, the statement reloads the TLS context for the named channel:mysql_main
for the main connection interface,mysql_admin
for the administrative connection interface. For information about the different interfaces, see Section 5.1.12.1, “Connection Interfaces”. The updated TLS context properties are exposed in the Performance Schematls_channel_status
table. See Section 27.12.19.8, “The tls_channel_status Table”.Updating the TLS context for the main interface may also affect the administrative interface because unless some nondefault TLS value is configured for that interface, it uses the same TLS context as the main interface.
By default, the
RELOAD TLS
action rolls back with an error and has no effect if the configuration values do not permit creation of the new TLS context. The previous context values continue to be used for new connections. If the optionalNO ROLLBACK ON ERROR
clause is given and the new context cannot be created, rollback does not occur. Instead, a warning is generated and encryption is disabled for new connections on the interface to which the statement applies.ALTER INSTANCE RELOAD TLS
statements are not written to the binary log (and thus are not replicated). TLS configuration is local and depends on local files not necessarily present on all servers involved.
ALTER LOGFILE GROUPlogfile_group
ADD UNDOFILE 'file_name
' [INITIAL_SIZE [=]size
] [WAIT] ENGINE [=]engine_name
This statement adds an UNDO
file named
'file_name
' to an existing log file
group logfile_group
. An
ALTER LOGFILE GROUP
statement has
one and only one ADD UNDOFILE
clause. No
DROP UNDOFILE
clause is currently supported.
All NDB Cluster Disk Data objects share the same namespace. This means that each Disk Data object must be uniquely named (and not merely each Disk Data object of a given type). For example, you cannot have a tablespace and an undo log file with the same name, or an undo log file and a data file with the same name.
The optional INITIAL_SIZE
parameter sets the
UNDO
file's initial size in bytes; if not
specified, the initial size defaults to 134217728 (128 MB). You
may optionally follow size
with a
one-letter abbreviation for an order of magnitude, similar to
those used in my.cnf
. Generally, this is one
of the letters M
(megabytes) or
G
(gigabytes). (Bug #13116514, Bug #16104705,
Bug #62858)
On 32-bit systems, the maximum supported value for
INITIAL_SIZE
is 4294967296 (4 GB). (Bug #29186)
The minimum allowed value for INITIAL_SIZE
is
1048576 (1 MB). (Bug #29574)
WAIT
is parsed but otherwise ignored. This
keyword currently has no effect, and is intended for future
expansion.
The ENGINE
parameter (required) determines the
storage engine which is used by this log file group, with
engine_name
being the name of the
storage engine. Currently, the only accepted values for
engine_name
are
“NDBCLUSTER
” and
“NDB
”. The two values
are equivalent.
Here is an example, which assumes that the log file group
lg_3
has already been created using
CREATE LOGFILE GROUP
(see
Section 13.1.16, “CREATE LOGFILE GROUP Statement”):
ALTER LOGFILE GROUP lg_3 ADD UNDOFILE 'undo_10.dat' INITIAL_SIZE=32M ENGINE=NDBCLUSTER;
When ALTER LOGFILE GROUP
is used
with ENGINE = NDBCLUSTER
(alternatively,
ENGINE = NDB
), an UNDO
log
file is created on each NDB Cluster data node. You can verify that
the UNDO
files were created and obtain
information about them by querying the
INFORMATION_SCHEMA.FILES
table. For
example:
mysql>SELECT FILE_NAME, LOGFILE_GROUP_NUMBER, EXTRA
->FROM INFORMATION_SCHEMA.FILES
->WHERE LOGFILE_GROUP_NAME = 'lg_3';
+-------------+----------------------+----------------+ | FILE_NAME | LOGFILE_GROUP_NUMBER | EXTRA | +-------------+----------------------+----------------+ | newdata.dat | 0 | CLUSTER_NODE=3 | | newdata.dat | 0 | CLUSTER_NODE=4 | | undo_10.dat | 11 | CLUSTER_NODE=3 | | undo_10.dat | 11 | CLUSTER_NODE=4 | +-------------+----------------------+----------------+ 4 rows in set (0.01 sec)
(See Section 26.15, “The INFORMATION_SCHEMA FILES Table”.)
Memory used for UNDO_BUFFER_SIZE
comes from the
global pool whose size is determined by the value of the
SharedGlobalMemory
data
node configuration parameter. This includes any default value
implied for this option by the setting of the
InitialLogFileGroup
data
node configuration parameter.
ALTER LOGFILE GROUP
is useful only
with Disk Data storage for NDB Cluster. For more information, see
Section 23.5.10, “NDB Cluster Disk Data Tables”.
ALTER PROCEDUREproc_name
[characteristic
...]characteristic
: { COMMENT 'string
' | LANGUAGE SQL | { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA } | SQL SECURITY { DEFINER | INVOKER } }
This statement can be used to change the characteristics of a
stored procedure. More than one change may be specified in an
ALTER PROCEDURE
statement. However,
you cannot change the parameters or body of a stored procedure
using this statement; to make such changes, you must drop and
re-create the procedure using DROP
PROCEDURE
and CREATE
PROCEDURE
.
You must have the ALTER ROUTINE
privilege for the procedure. By default, that privilege is granted
automatically to the procedure creator. This behavior can be
changed by disabling the
automatic_sp_privileges
system
variable. See Section 25.2.2, “Stored Routines and MySQL Privileges”.
ALTER SERVERserver_name
OPTIONS (option
[,option
] ...)
Alters the server information for
,
adjusting any of the options permitted in the
server_name
CREATE SERVER
statement. The
corresponding fields in the mysql.servers
table
are updated accordingly. This statement requires the
SUPER
privilege.
For example, to update the USER
option:
ALTER SERVER s OPTIONS (USER 'sally');
ALTER SERVER
causes an implicit commit. See
Section 13.3.3, “Statements That Cause an Implicit Commit”.
ALTER SERVER
is not written to the binary log,
regardless of the logging format that is in use.
ALTER TABLEtbl_name
[alter_option
[,alter_option
] ...] [partition_options
]alter_option
: {table_options
| ADD [COLUMN]col_name
column_definition
[FIRST | AFTERcol_name
] | ADD [COLUMN] (col_name
column_definition
,...) | ADD {INDEX | KEY} [index_name
] [index_type
] (key_part
,...) [index_option
] ... | ADD {FULLTEXT | SPATIAL} [INDEX | KEY] [index_name
] (key_part
,...) [index_option
] ... | ADD [CONSTRAINT [symbol
]] PRIMARY KEY [index_type
] (key_part
,...) [index_option
] ... | ADD [CONSTRAINT [symbol
]] UNIQUE [INDEX | KEY] [index_name
] [index_type
] (key_part
,...) [index_option
] ... | ADD [CONSTRAINT [symbol
]] FOREIGN KEY [index_name
] (col_name
,...)reference_definition
| ADD [CONSTRAINT [symbol
]] CHECK (expr
) [[NOT] ENFORCED] | DROP {CHECK | CONSTRAINT}symbol
| ALTER {CHECK | CONSTRAINT}symbol
[NOT] ENFORCED | ALGORITHM [=] {DEFAULT | INSTANT | INPLACE | COPY} | ALTER [COLUMN]col_name
{ SET DEFAULT {literal
| (expr
)} | SET {VISIBLE | INVISIBLE} | DROP DEFAULT } | ALTER INDEXindex_name
{VISIBLE | INVISIBLE} | CHANGE [COLUMN]old_col_name
new_col_name
column_definition
[FIRST | AFTERcol_name
] | [DEFAULT] CHARACTER SET [=]charset_name
[COLLATE [=]collation_name
] | CONVERT TO CHARACTER SETcharset_name
[COLLATEcollation_name
] | {DISABLE | ENABLE} KEYS | {DISCARD | IMPORT} TABLESPACE | DROP [COLUMN]col_name
| DROP {INDEX | KEY}index_name
| DROP PRIMARY KEY | DROP FOREIGN KEYfk_symbol
| FORCE | LOCK [=] {DEFAULT | NONE | SHARED | EXCLUSIVE} | MODIFY [COLUMN]col_name
column_definition
[FIRST | AFTERcol_name
] | ORDER BYcol_name
[,col_name
] ... | RENAME COLUMNold_col_name
TOnew_col_name
| RENAME {INDEX | KEY}old_index_name
TOnew_index_name
| RENAME [TO | AS]new_tbl_name
| {WITHOUT | WITH} VALIDATION }partition_options
:partition_option
[partition_option
] ...partition_option
: { ADD PARTITION (partition_definition
) | DROP PARTITIONpartition_names
| DISCARD PARTITION {partition_names
| ALL} TABLESPACE | IMPORT PARTITION {partition_names
| ALL} TABLESPACE | TRUNCATE PARTITION {partition_names
| ALL} | COALESCE PARTITIONnumber
| REORGANIZE PARTITIONpartition_names
INTO (partition_definitions
) | EXCHANGE PARTITIONpartition_name
WITH TABLEtbl_name
[{WITH | WITHOUT} VALIDATION] | ANALYZE PARTITION {partition_names
| ALL} | CHECK PARTITION {partition_names
| ALL} | OPTIMIZE PARTITION {partition_names
| ALL} | REBUILD PARTITION {partition_names
| ALL} | REPAIR PARTITION {partition_names
| ALL} | REMOVE PARTITIONING }key_part
: {col_name
[(length
)] | (expr
)} [ASC | DESC]index_type
: USING {BTREE | HASH}index_option
: { KEY_BLOCK_SIZE [=]value
|index_type
| WITH PARSERparser_name
| COMMENT 'string
' | {VISIBLE | INVISIBLE} }table_options
:table_option
[[,]table_option
] ...table_option
: { AUTOEXTEND_SIZE [=]value
| AUTO_INCREMENT [=]value
| AVG_ROW_LENGTH [=]value
| [DEFAULT] CHARACTER SET [=]charset_name
| CHECKSUM [=] {0 | 1} | [DEFAULT] COLLATE [=]collation_name
| COMMENT [=] 'string
' | COMPRESSION [=] {'ZLIB' | 'LZ4' | 'NONE'} | CONNECTION [=] 'connect_string
' | {DATA | INDEX} DIRECTORY [=] 'absolute path to directory
' | DELAY_KEY_WRITE [=] {0 | 1} | ENCRYPTION [=] {'Y' | 'N'} | ENGINE [=]engine_name
| ENGINE_ATTRIBUTE [=] 'string
' | INSERT_METHOD [=] { NO | FIRST | LAST } | KEY_BLOCK_SIZE [=]value
| MAX_ROWS [=]value
| MIN_ROWS [=]value
| PACK_KEYS [=] {0 | 1 | DEFAULT} | PASSWORD [=] 'string
' | ROW_FORMAT [=] {DEFAULT | DYNAMIC | FIXED | COMPRESSED | REDUNDANT | COMPACT} | SECONDARY_ENGINE_ATTRIBUTE [=] 'string
' | STATS_AUTO_RECALC [=] {DEFAULT | 0 | 1} | STATS_PERSISTENT [=] {DEFAULT | 0 | 1} | STATS_SAMPLE_PAGES [=]value
| TABLESPACEtablespace_name
[STORAGE {DISK | MEMORY}] | UNION [=] (tbl_name
[,tbl_name
]...) }partition_options
: (seeCREATE TABLE
options)
ALTER TABLE
changes the structure
of a 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 characteristics
such as the storage engine used for the table or the table
comment.
To use
ALTER TABLE
, you needALTER
,CREATE
, andINSERT
privileges for the table. Renaming a table requiresALTER
andDROP
on the old table,ALTER
,CREATE
, andINSERT
on the new table.Following the table name, specify the alterations to be made. If none are given,
ALTER TABLE
does nothing.The syntax for many of the permissible alterations is similar to clauses of the
CREATE TABLE
statement.column_definition
clauses use the same syntax forADD
andCHANGE
as forCREATE TABLE
. For more information, see Section 13.1.20, “CREATE TABLE Statement”.The word
COLUMN
is optional and can be omitted, except forRENAME COLUMN
(to distinguish a column-renaming operation from theRENAME
table-renaming operation).Multiple
ADD
,ALTER
,DROP
, andCHANGE
clauses are permitted in a singleALTER TABLE
statement, separated by commas. This is a MySQL extension to standard SQL, which permits only one of each clause perALTER TABLE
statement. For example, to drop multiple columns in a single statement, do this:ALTER TABLE t2 DROP COLUMN c, DROP COLUMN d;
If a storage engine does not support an attempted
ALTER TABLE
operation, a warning may result. Such warnings can be displayed withSHOW WARNINGS
. See Section 13.7.7.42, “SHOW WARNINGS Statement”. For information on troubleshootingALTER TABLE
, see Section B.3.6.1, “Problems with ALTER TABLE”.For information about generated columns, see Section 13.1.9.2, “ALTER TABLE and Generated Columns”.
For usage examples, see Section 13.1.9.3, “ALTER TABLE Examples”.
InnoDB
in MySQL 8.0.17 and later supports addition of multi-valued indexes on JSON columns using akey_part
specification can take the form(CAST
. See Multi-Valued Indexes, for detailed information regarding multi-valued index creation and usage of, as well as restrictions and limitations on multi-valued indexes.json_path
AStype
ARRAY)With the
mysql_info()
C API function, you can find out how many rows were copied byALTER TABLE
. See mysql_info().
There are several additional aspects to the ALTER
TABLE
statement, described under the following topics in
this section:
Table Options
table_options
signifies table options
of the kind that can be used in the CREATE
TABLE
statement, such as ENGINE
,
AUTO_INCREMENT
,
AVG_ROW_LENGTH
, MAX_ROWS
,
ROW_FORMAT
, or TABLESPACE
.
For descriptions of all table options, see
Section 13.1.20, “CREATE TABLE Statement”. However,
ALTER TABLE
ignores DATA
DIRECTORY
and INDEX DIRECTORY
when
given as table options. ALTER TABLE
permits them only as partitioning options, and requires that you
have the FILE
privilege.
Use of table options with ALTER
TABLE
provides a convenient way of altering single table
characteristics. For example:
If
t1
is currently not anInnoDB
table, this statement changes its storage engine toInnoDB
:ALTER TABLE t1 ENGINE = InnoDB;
See Section 15.6.1.5, “Converting Tables from MyISAM to InnoDB” for considerations when switching tables to the
InnoDB
storage engine.When you specify an
ENGINE
clause,ALTER TABLE
rebuilds the table. This is true even if the table already has the specified storage engine.Running
ALTER TABLE
on an existingtbl_name
ENGINE=INNODBInnoDB
table performs a “null”ALTER TABLE
operation, which can be used to defragment anInnoDB
table, as described in Section 15.11.4, “Defragmenting a Table”. RunningALTER TABLE
on antbl_name
FORCEInnoDB
table performs the same function.ALTER TABLE
andtbl_name
ENGINE=INNODBALTER TABLE
use online DDL. For more information, see Section 15.12, “InnoDB and Online DDL”.tbl_name
FORCEThe outcome of attempting to change the storage engine of a table 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.11, “Server SQL Modes”.To prevent inadvertent loss of data,
ALTER TABLE
cannot be used to change the storage engine of a table toMERGE
orBLACKHOLE
.
To change the
InnoDB
table to use compressed row-storage format:ALTER TABLE t1 ROW_FORMAT = COMPRESSED;
The
ENCRYPTION
clause enables or disables page-level data encryption for anInnoDB
table. A keyring plugin must be installed and configured to enable encryption.If the
table_encryption_privilege_check
variable is enabled, theTABLE_ENCRYPTION_ADMIN
privilege is required to use anENCRYPTION
clause with a setting that differs from the default schema encryption setting.Prior to MySQL 8.0.16, the
ENCRYPTION
clause was only supported when altering tables residing in file-per-table tablespaces. As of MySQL 8.0.16, theENCRYPTION
clause is also supported for tables residing in general tablespaces.For tables that reside in general tablespaces, table and tablespace encryption must match.
Altering table encryption by moving a table to a different tablespace or changing the storage engine is not permitted without explicitly specifying an
ENCRYPTION
clause.As of MySQL 8.0.16, specifying an
ENCRYPTION
clause with a value other than'N'
or''
is not permitted if the table uses a storage engine that does not support encryption. Previously, the clause was accepted. Attempting to create a table without anENCRYPTION
clause in an encryption-enabled schema using a storage engine that does not support encryption is also not permitted.For more information, see Section 15.13, “InnoDB Data-at-Rest Encryption”.
To reset the current auto-increment value:
ALTER TABLE t1 AUTO_INCREMENT = 13;
You cannot reset the counter to a value less than or equal to the value that is currently in use. For both
InnoDB
andMyISAM
, if the value is less than or equal to the maximum value currently in theAUTO_INCREMENT
column, the value is reset to the current maximumAUTO_INCREMENT
column value plus one.To change the default table character set:
ALTER TABLE t1 CHARACTER SET = utf8;
See also Changing the Character Set.
To add (or change) a table comment:
ALTER TABLE t1 COMMENT = 'New table comment';
Use
ALTER TABLE
with theTABLESPACE
option to moveInnoDB
tables between existing general tablespaces, file-per-table tablespaces, and the system tablespace. See Moving Tables Between Tablespaces Using ALTER TABLE.ALTER TABLE ... TABLESPACE
operations always cause a full table rebuild, even if theTABLESPACE
attribute has not changed from its previous value.ALTER TABLE ... TABLESPACE
syntax does not support moving a table from a temporary tablespace to a persistent tablespace.The
DATA DIRECTORY
clause, which is supported withCREATE TABLE ... TABLESPACE
, is not supported withALTER TABLE ... TABLESPACE
, and is ignored if specified.For more information about the capabilities and limitations of the
TABLESPACE
option, seeCREATE TABLE
.
MySQL NDB Cluster 8.0 supports setting
NDB_TABLE
options for controlling a table's partition balance (fragment count type), read-from-any-replica capability, full replication, or any combination of these, as part of the table comment for anALTER TABLE
statement in the same manner as forCREATE TABLE
, as shown in this example:ALTER TABLE t1 COMMENT = "NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RA_BY_NODE";
Bear in mind that
ALTER TABLE ... COMMENT ...
discards any existing comment for the table. See Setting NDB_TABLE options, for additional information and examples.ENGINE_ATTRIBUTE
andSECONDARY_ENGINE_ATTRIBUTE
options (available as of MySQL 8.0.21) are used to specify table, column, and index attributes for primary and secondary storage engines. The options are reserved for future use. Index attributes cannot be altered. An index must be dropped and added back with the desired change, which can be performed in a singleALTER TABLE
statement.
To verify that the table options were changed as intended, use
SHOW CREATE TABLE
, or query the
INFORMATION_SCHEMA.TABLES
table.
Performance and Space Requirements
ALTER TABLE
operations are
processed using one of the following algorithms:
COPY
: Operations are performed on a copy of the original table, and table data is copied from the original table to the new table row by row. Concurrent DML is not permitted.INPLACE
: Operations avoid copying table data but may rebuild the table in place. An exclusive metadata lock on the table may be taken briefly during preparation and execution phases of the operation. Typically, concurrent DML is supported.INSTANT
: Operations only modify metadata in the data dictionary. No exclusive metadata locks are taken on the table during preparation and execution, and table data is unaffected, making operations instantaneous. Concurrent DML is permitted. (Introduced in MySQL 8.0.12)
The ALGORITHM
clause is optional. If the
ALGORITHM
clause is omitted, MySQL uses
ALGORITHM=INSTANT
for storage engines and
ALTER TABLE
clauses that support
it. Otherwise, ALGORITHM=INPLACE
is used. If
ALGORITHM=INPLACE
is not supported,
ALGORITHM=COPY
is used.
Specifying an ALGORITHM
clause requires the
operation to use the specified algorithm for clauses and storage
engines that support it, or fail with an error otherwise.
Specifying ALGORITHM=DEFAULT
is the same as
omitting the ALGORITHM
clause.
ALTER TABLE
operations that use the
COPY
algorithm wait for other operations that
are modifying the table to complete. After alterations are applied
to the table copy, data is copied over, the original table is
deleted, and the table copy is renamed to the name of the original
table. While the ALTER TABLE
operation executes, the original table is readable by other
sessions (with the exception noted shortly). Updates and writes to
the table started after the ALTER
TABLE
operation begins are stalled until the new table
is ready, then are automatically redirected to the new table. The
temporary copy of the table is created in the database directory
of the original table unless it is a RENAME TO
operation that moves the table to a database that resides in a
different directory.
The exception referred to earlier is that
ALTER TABLE
blocks reads (not just
writes) at the point where it is ready to clear outdated table
structures from the table and table definition caches. At this
point, it must acquire an exclusive lock. To do so, it waits for
current readers to finish, and blocks new reads and writes.
An ALTER TABLE
operation that uses
the COPY
algorithm prevents concurrent DML
operations. Concurrent queries are still allowed. That is, a
table-copying operation always includes at least the concurrency
restrictions of LOCK=SHARED
(allow queries but
not DML). You can further restrict concurrency for operations that
support the LOCK
clause by specifying
LOCK=EXCLUSIVE
, which prevents DML and queries.
For more information, see
Concurrency Control.
To force use of the COPY
algorithm for an
ALTER TABLE
operation that would
otherwise not use it, specify ALGORITHM=COPY
or
enable the old_alter_table
system
variable. If there is a conflict between the
old_alter_table
setting and an
ALGORITHM
clause with a value other than
DEFAULT
, the ALGORITHM
clause takes precedence.
For InnoDB
tables, an
ALTER TABLE
operation that uses the
COPY
algorithm on a table that resides in a
shared tablespace
can increase the amount of space used by the tablespace. Such
operations require as much additional space as the data in the
table plus indexes. For a table residing in a shared tablespace,
the additional space used during the operation is not released
back to the operating system as it is for a table that resides in
a file-per-table
tablespace.
For information about space requirements for online DDL operations, see Section 15.12.3, “Online DDL Space Requirements”.
ALTER TABLE
operations that support
the INPLACE
algorithm include:
ALTER TABLE
operations supported by theInnoDB
online DDL feature. See Section 15.12.1, “Online DDL Operations”.Renaming a table. MySQL renames files that correspond to the table
tbl_name
without making a copy. (You can also use theRENAME TABLE
statement to rename tables. See Section 13.1.36, “RENAME TABLE Statement”.) Privileges granted specifically for the renamed table are not migrated to the new name. They must be changed manually.Operations that only modify table metadata. These operations are immediate because the server does not touch table contents. Metadata-only operations include:
Renaming a column. In NDB Cluster 8.0.18 and later, this operation can also be performed online.
Changing the default value of a column (except for
NDB
tables).Modifying the definition of an
ENUM
orSET
column by adding new enumeration or set members to the end of the list of valid member values, as long as the storage size of the data type does not change. For example, adding a member to aSET
column that has 8 members changes the required storage per value from 1 byte to 2 bytes; this requires a table copy. Adding members in the middle of the list causes renumbering of existing members, which requires a table copy.Changing the definition of a spatial column to remove the
SRID
attribute. (Adding or changing anSRID
attribute does require a rebuild and cannot be done in place because the server must verify that all values have the specified SRID value.)As of MySQL 8.0.14, changing a column character set, when these conditions apply:
As of MySQL 8.0.14, changing a generated column, when these conditions apply:
For
InnoDB
tables, statements that modify generated stored columns but do not change their type, expression, or nullability.For non-
InnoDB
tables, statements that modify generated stored or virtual columns but do not change their type, expression, or nullability.
An example of such a change is a change to the column comment.
Renaming an index.
Adding or dropping a secondary index, for
InnoDB
andNDB
tables. See Section 15.12.1, “Online DDL Operations”.For
NDB
tables, operations that add and drop indexes on variable-width columns. These operations occur online, without table copying and without blocking concurrent DML actions for most of their duration. See Section 23.5.11, “Online Operations with ALTER TABLE in NDB Cluster”.Modifying index visibility with an
ALTER INDEX
operation.Column modifications of tables containing generated columns that depend on columns with a
DEFAULT
value if the modified columns are not involved in the generated column expressions. For example, changing theNULL
property of a separate column can be done in place without a table rebuild.
ALTER TABLE
operations that support the
INSTANT
algorithm include:
Adding a column. This feature is referred to as “Instant
ADD COLUMN
”. Limitations apply. See Section 15.12.1, “Online DDL Operations”.Adding or dropping a virtual column.
Adding or dropping a column default value.
Modifying the definition of an
ENUM
orSET
column. The same restrictions apply as described above forALGORITHM=INSTANT
.Changing the index type.
Renaming a table. The same restrictions apply as described above for
ALGORITHM=INSTANT
.
For more information about operations that support
ALGORITHM=INSTANT
, see
Section 15.12.1, “Online DDL Operations”.
ALTER TABLE
upgrades MySQL 5.5
temporal columns to 5.6 format for ADD COLUMN
,
CHANGE COLUMN
, MODIFY
COLUMN
, ADD INDEX
, and
FORCE
operations. This conversion cannot be
done using the INPLACE
algorithm because the
table must be rebuilt, so specifying
ALGORITHM=INPLACE
in these cases results in an
error. Specify ALGORITHM=COPY
if necessary.
If an ALTER TABLE
operation on a multicolumn
index used to partition a table by KEY
changes
the order of the columns, it can only be performed using
ALGORITHM=COPY
.
The WITHOUT VALIDATION
and WITH
VALIDATION
clauses affect whether
ALTER TABLE
performs an in-place
operation for
virtual generated
column modifications. See
Section 13.1.9.2, “ALTER TABLE and Generated Columns”.
NDB Cluster 8.0 supports online operations using the same
ALGORITHM=INPLACE
syntax used with the standard
MySQL Server. NDB
does not support changing a
tablespace online; beginning with NDB 8.0.21, it is disallowed.
See Section 23.5.11, “Online Operations with ALTER TABLE in NDB Cluster”, for more
information.
ALTER TABLE
with DISCARD ... PARTITION
... TABLESPACE
or IMPORT ... PARTITION ...
TABLESPACE
does not create any temporary tables or
temporary partition files.
ALTER TABLE
with ADD
PARTITION
, DROP PARTITION
,
COALESCE PARTITION
, REBUILD
PARTITION
, or REORGANIZE PARTITION
does not create temporary tables (except when used with
NDB
tables); however, these
operations can and do create temporary partition files.
ADD
or DROP
operations for
RANGE
or LIST
partitions are
immediate operations or nearly so. ADD
or
COALESCE
operations for HASH
or KEY
partitions copy data between all
partitions, unless LINEAR HASH
or
LINEAR KEY
was used; this is effectively the
same as creating a new table, although the ADD
or COALESCE
operation is performed partition by
partition. REORGANIZE
operations copy only
changed partitions and do not touch unchanged ones.
For MyISAM
tables, you can speed up index
re-creation (the slowest part of the alteration process) by
setting the
myisam_sort_buffer_size
system
variable to a high value.
Concurrency Control
For ALTER TABLE
operations that
support it, you can use the LOCK
clause to
control the level of concurrent reads and writes on a table while
it is being altered. Specifying a non-default value for this
clause enables you to require a certain amount of concurrent
access or exclusivity during the alter operation, and halts the
operation if the requested degree of locking is not available.
Only LOCK = DEFAULT
is permitted for operations
that use ALGORITHM=INSTANT
. The other
LOCK
clause parameters are not applicable.
The parameters for the LOCK
clause are:
LOCK = DEFAULT
Maximum level of concurrency for the given
ALGORITHM
clause (if any) andALTER TABLE
operation: Permit concurrent reads and writes if supported. If not, permit concurrent reads if supported. If not, enforce exclusive access.LOCK = NONE
If supported, permit concurrent reads and writes. Otherwise, an error occurs.
LOCK = SHARED
If supported, permit concurrent reads but block writes. Writes are blocked even if concurrent writes are supported by the storage engine for the given
ALGORITHM
clause (if any) andALTER TABLE
operation. If concurrent reads are not supported, an error occurs.LOCK = EXCLUSIVE
Enforce exclusive access. This is done even if concurrent reads/writes are supported by the storage engine for the given
ALGORITHM
clause (if any) andALTER TABLE
operation.
Adding and Dropping Columns
Use ADD
to add new columns to a table, and
DROP
to remove existing columns. DROP
is a MySQL extension
to standard SQL.
col_name
To add a column at a specific position within a table row, use
FIRST
or AFTER
. The default is to
add the column last.
col_name
If a table contains only one column, the column cannot be dropped.
If what you intend is to remove the table, use the
DROP TABLE
statement instead.
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.
For ALTER TABLE ... ADD
, if the column has an
expression default value that uses a nondeterministic function,
the statement may produce a warning or error. For further
information, see Section 11.6, “Data Type Default Values”, and
Section 17.1.3.7, “Restrictions on Replication with GTIDs”.
Renaming, Redefining, and Reordering Columns
The CHANGE
, MODIFY
,
RENAME COLUMN
, and ALTER
clauses enable the names and definitions of existing columns to be
altered. They have these comparative characteristics:
CHANGE
:Can rename a column and change its definition, or both.
Has more capability than
MODIFY
orRENAME COLUMN
, but at the expense of convenience for some operations.CHANGE
requires naming the column twice if not renaming it, and requires respecifying the column definition if only renaming it.With
FIRST
orAFTER
, can reorder columns.
MODIFY
:Can change a column definition but not its name.
More convenient than
CHANGE
to change a column definition without renaming it.With
FIRST
orAFTER
, can reorder columns.
RENAME COLUMN
:Can change a column name but not its definition.
More convenient than
CHANGE
to rename a column without changing its definition.
ALTER
: Used only to change a column default value.
CHANGE
is a MySQL extension to standard SQL.
MODIFY
and RENAME COLUMN
are
MySQL extensions for Oracle compatibility.
To alter a column to change both its name and definition, use
CHANGE
, specifying the old and new names and
the new definition. For example, to rename an INT NOT
NULL
column from a
to
b
and change its definition to use the
BIGINT
data type while retaining the
NOT NULL
attribute, do this:
ALTER TABLE t1 CHANGE a b BIGINT NOT NULL;
To change a column definition but not its name, use
CHANGE
or MODIFY
. With
CHANGE
, the syntax requires two column names,
so you must specify the same name twice to leave the name
unchanged. For example, to change the definition of column
b
, do this:
ALTER TABLE t1 CHANGE b b INT NOT NULL;
MODIFY
is more convenient to change the
definition without changing the name because it requires the
column name only once:
ALTER TABLE t1 MODIFY b INT NOT NULL;
To change a column name but not its definition, use
CHANGE
or RENAME COLUMN
.
With CHANGE
, the syntax requires a column
definition, so to leave the definition unchanged, you must
respecify the definition the column currently has. For example, to
rename an INT NOT NULL
column from
b
to a
, do this:
ALTER TABLE t1 CHANGE b a INT NOT NULL;
RENAME COLUMN
is more convenient to change the
name without changing the definition because it requires only the
old and new names:
ALTER TABLE t1 RENAME COLUMN b TO a;
In general, you cannot rename a column to a name that already
exists in the table. However, this is sometimes not the case, such
as when you swap names or move them through a cycle. If a table
has columns named a
, b
, and
c
, these are valid operations:
-- swap a and b ALTER TABLE t1 RENAME COLUMN a TO b, RENAME COLUMN b TO a; -- "rotate" a, b, c through a cycle ALTER TABLE t1 RENAME COLUMN a TO b, RENAME COLUMN b TO c, RENAME COLUMN c TO a;
For column definition changes using CHANGE
or
MODIFY
, the 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, intending
to change only INT
to
BIGINT
:
ALTER TABLE t1 MODIFY col1 BIGINT;
That statement changes the data type from INT
to BIGINT
, but it also drops the
UNSIGNED
, DEFAULT
, and
COMMENT
attributes. To retain them, the
statement must include them explicitly:
ALTER TABLE t1 MODIFY col1 BIGINT UNSIGNED DEFAULT 1 COMMENT 'my column';
For data type changes using CHANGE
or
MODIFY
, MySQL tries to convert existing column
values to the new type as well as possible.
This conversion may result in alteration of data. For example,
if you shorten a string column, values may be truncated. 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.11, “Server SQL Modes”).
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.
For columns renamed by CHANGE
or
RENAME COLUMN
, MySQL automatically renames
these references to the renamed column:
Indexes that refer to the old column, including invisible indexes and disabled
MyISAM
indexes.Foreign keys that refer to the old column.
For columns renamed by CHANGE
or
RENAME COLUMN
, MySQL does not automatically
rename these references to the renamed column:
Generated column and partition expressions that refer to the renamed column. You must use
CHANGE
to redefine such expressions in the sameALTER TABLE
statement as the one that renames the column.Views and stored programs that refer to the renamed column. You must manually alter the definition of these objects to refer to the new column name.
To reorder columns within a table, use FIRST
and AFTER
in CHANGE
or
MODIFY
operations.
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 11.6, “Data Type Default Values”.
As of MySQL 8.0.23, ALTER ... SET VISIBLE
and
ALTER ... SET INVISIBLE
enable column
visibility to be changed. See Section 13.1.20.10, “Invisible Columns”.
Primary Keys and Indexes
DROP PRIMARY KEY
drops the
primary key. If there is
no primary key, an error occurs. For information about the
performance characteristics of primary keys, especially for
InnoDB
tables, see
Section 8.3.2, “Primary Key Optimization”.
If the sql_require_primary_key
system variable is enabled, attempting to drop a primary key
produces an error.
If you add a UNIQUE INDEX
or PRIMARY
KEY
to a table, MySQL stores it before any nonunique
index to permit detection of duplicate keys as early as possible.
DROP INDEX
removes an index. This
is a MySQL extension to standard SQL. See
Section 13.1.27, “DROP INDEX Statement”. To determine index names, use
SHOW INDEX FROM
.
tbl_name
Some storage engines permit you to specify an index type when
creating an index. The syntax for the
index_type
specifier is USING
. For details about
type_name
USING
, see Section 13.1.15, “CREATE INDEX Statement”. The
preferred position is after the column list. Expect support for
use of the option before the column list to be removed in a future
MySQL release.
index_option
values specify additional
options for an index. USING
is one such option.
For details about permissible
index_option
values, see
Section 13.1.15, “CREATE INDEX Statement”.
RENAME INDEX
renames an
index. This is a MySQL extension to standard SQL. The content of
the table remains unchanged.
old_index_name
TO
new_index_name
old_index_name
must be the name of an
existing index in the table that is not dropped by the same
ALTER TABLE
statement.
new_index_name
is the new index name,
which cannot duplicate the name of an index in the resulting table
after changes have been applied. Neither index name can be
PRIMARY
.
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.
For MyISAM
tables, key updating can be
controlled explicitly. Use ALTER TABLE ... DISABLE
KEYS
to tell MySQL to stop updating nonunique indexes.
Then use ALTER TABLE ... ENABLE KEYS
to
re-create missing indexes. MyISAM
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.
After an ALTER TABLE
statement, it
may be necessary to run ANALYZE
TABLE
to update index cardinality information. See
Section 13.7.7.22, “SHOW INDEX Statement”.
The ALTER INDEX
operation permits an index to
be made visible or invisible. An invisible index is not used by
the optimizer. Modification of index visibility applies to indexes
other than primary keys (either explicit or implicit). This
feature is storage engine neutral (supported for any engine). For
more information, see Section 8.3.12, “Invisible Indexes”.
Foreign Keys and Other Constraints
The FOREIGN KEY
and
REFERENCES
clauses are supported by the
InnoDB
and NDB
storage
engines, which implement ADD [CONSTRAINT
[
. See Section 13.1.20.5, “FOREIGN KEY Constraints”.
For other storage engines, the clauses are parsed but ignored.
symbol
]] FOREIGN KEY
[index_name
] (...) REFERENCES ...
(...)
For ALTER TABLE
, unlike
CREATE TABLE
, ADD FOREIGN
KEY
ignores index_name
if
given and uses an automatically generated foreign key name. As a
workaround, include the CONSTRAINT
clause to
specify the foreign key name:
ADD CONSTRAINT name
FOREIGN KEY (....) ...
MySQL silently ignores inline REFERENCES
specifications, where the references are defined as part of the
column specification. MySQL accepts only
REFERENCES
clauses defined as part of a
separate FOREIGN KEY
specification.
Partitioned InnoDB
tables do not support
foreign keys. This restriction does not apply to
NDB
tables, including those explicitly
partitioned by [LINEAR] KEY
. For more
information, see
Section 24.6.2, “Partitioning Limitations Relating to Storage Engines”.
MySQL Server and NDB Cluster both support the use of
ALTER TABLE
to drop foreign keys:
ALTER TABLEtbl_name
DROP FOREIGN KEYfk_symbol
;
Adding and dropping a foreign key in the same
ALTER TABLE
statement is supported
for ALTER TABLE ...
ALGORITHM=INPLACE
but not for
ALTER TABLE ...
ALGORITHM=COPY
.
The server prohibits changes to foreign key columns that have the
potential to cause loss of referential integrity. A workaround is
to use ALTER TABLE
... DROP FOREIGN KEY
before changing the column
definition and ALTER
TABLE ... ADD FOREIGN KEY
afterward. Examples of
prohibited changes include:
Changes to the data type of foreign key columns that may be unsafe. For example, changing
VARCHAR(20)
toVARCHAR(30)
is permitted, but changing it toVARCHAR(1024)
is not because that alters the number of length bytes required to store individual values.Changing a
NULL
column toNOT NULL
in non-strict mode is prohibited to prevent convertingNULL
values to default non-NULL
values, for which there are no corresponding values in the referenced table. The operation is permitted in strict mode, but an error is returned if any such conversion is required.
ALTER TABLE
changes
internally generated foreign key constraint names and user-defined
foreign key constraint names that begin with the string
“tbl_name
RENAME
new_tbl_name
tbl_name
_ibfk_” to
reflect the new table name. InnoDB
interprets
foreign key constraint names that begin with the string
“tbl_name
_ibfk_” as
internally generated names.
Prior to MySQL 8.0.16, ALTER TABLE
permits only the following limited version of
CHECK
constraint-adding syntax, which is parsed
and ignored:
ADD CHECK (expr
)
As of MySQL 8.0.16, ALTER TABLE
permits CHECK
constraints for existing tables
to be added, dropped, or altered:
Add a new
CHECK
constraint:ALTER TABLE
tbl_name
ADD CONSTRAINT [symbol
] CHECK (expr
) [[NOT] ENFORCED];The meaning of constraint syntax elements is the same as for
CREATE TABLE
. See Section 13.1.20.6, “CHECK Constraints”.Drop an existing
CHECK
constraint namedsymbol
:ALTER TABLE
tbl_name
DROP CHECKsymbol
;Alter whether an existing
CHECK
constraint namedsymbol
is enforced:ALTER TABLE
tbl_name
ALTER CHECKsymbol
[NOT] ENFORCED;
The DROP CHECK
and ALTER
CHECK
clauses are MySQL extensions to standard SQL.
As of MySQL 8.0.19, ALTER TABLE
permits more general (and SQL standard) syntax for dropping and
altering existing constraints of any type, where the constraint
type is determined from the constraint name:
Drop an existing constraint named
symbol
:ALTER TABLE
tbl_name
DROP CONSTRAINTsymbol
;If the
sql_require_primary_key
system variable is enabled, attempting to drop a primary key produces an error.Alter whether an existing constraint named
symbol
is enforced:ALTER TABLE
tbl_name
ALTER CONSTRAINTsymbol
[NOT] ENFORCED;Only
CHECK
constraints can be altered to be unenforced. All other constraint types are always enforced.
The SQL standard specifies that all types of constraints (primary
key, unique index, foreign key, check) belong to the same
namespace. In MySQL, each constraint type has its own namespace
per schema. Consequently, names for each type of constraint must
be unique per schema, but constraints of different types can have
the same name. When multiple constraints have the same name,
DROP CONSTRAINT
and ADD
CONSTRAINT
are ambiguous and an error occurs. In such
cases, constraint-specific syntax must be used to modify the
constraint. For example, use DROP PRIMARY KEY
or DROP FOREIGN KEY to drop a primary key or foreign key.
If a table alteration causes a violation of an enforced
CHECK
constraint, an error occurs and the table
is not modified. Examples of operations for which an error occurs:
Attempts to add the
AUTO_INCREMENT
attribute to a column that is used in aCHECK
constraint.Attempts to add an enforced
CHECK
constraint or enforce a nonenforcedCHECK
constraint for which existing rows violate the constraint condition.Attempts to modify, rename, or drop a column that is used in a
CHECK
constraint, unless that constraint is also dropped in the same statement. Exception: If aCHECK
constraint refers only to a single column, dropping the column automatically drops the constraint.
ALTER TABLE
changes
internally generated and user-defined tbl_name
RENAME
new_tbl_name
CHECK
constraint names that begin with the string
“tbl_name
_chk_” to reflect
the new table name. MySQL interprets CHECK
constraint names that begin with the string
“tbl_name
_chk_” as
internally generated names.
Changing the Character Set
To change the table default character set and all character
columns (CHAR
,
VARCHAR
,
TEXT
) to a new character set, use a
statement like this:
ALTER TABLEtbl_name
CONVERT TO CHARACTER SETcharset_name
;
The statement also changes the collation of all character columns.
If you specify no COLLATE
clause to indicate
which collation to use, the statement uses default collation for
the character set. If this collation is inappropriate for the
intended table use (for example, if it would change from a
case-sensitive collation to a case-insensitive collation), specify
a collation explicitly.
For a column that has a data type of
VARCHAR
or one of the
TEXT
types, CONVERT TO
CHARACTER SET
changes the data type as necessary to
ensure that the new column is long enough to store as many
characters as the original column. For example, a
TEXT
column has two length bytes,
which store the byte-length of values in the column, up to a
maximum of 65,535. For a latin1
TEXT
column, each character
requires a single byte, so the column can store up to 65,535
characters. If the column is converted to utf8
,
each character might require up to three bytes, for a maximum
possible length of 3 × 65,535 = 196,605 bytes. That length
does not fit in a TEXT
column's
length bytes, so MySQL converts 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 have a character set and a subsequent CONVERT
TO
operation does not apply to them.
If charset_name
is
DEFAULT
in a CONVERT TO CHARACTER
SET
operation, the character set named by the
character_set_database
system
variable is used.
The CONVERT TO
operation converts column
values between the original and named character sets. This is
not what you want if you have a column in
one character set (like latin1
) but the
stored values actually use some other, incompatible character
set (like utf8
). In this case, you have to do
the following for each such column:
ALTER TABLE t1 CHANGE c1 c1 BLOB; ALTER TABLE t1 CHANGE c1 c1 TEXT CHARACTER SET utf8;
The reason this works is that there is no conversion when you
convert to or from BLOB
columns.
To change only the default character set for a table, use this statement:
ALTER TABLEtbl_name
DEFAULT CHARACTER SETcharset_name
;
The word DEFAULT
is optional. The default
character set is the character set that is used if you do not
specify the character set for columns that you add to a table
later (for example, with ALTER TABLE ... ADD
column
).
When the foreign_key_checks
system variable is enabled, which is the default setting,
character set conversion is not permitted on tables that include a
character string column used in a foreign key constraint. The
workaround is to disable
foreign_key_checks
before
performing the character set conversion. You must perform the
conversion on both tables involved in the foreign key constraint
before re-enabling
foreign_key_checks
. If you
re-enable foreign_key_checks
after converting only one of the tables, an ON DELETE
CASCADE
or ON UPDATE CASCADE
operation could corrupt data in the referencing table due to
implicit conversion that occurs during these operations (Bug
#45290, Bug #74816).
Importing InnoDB Tables
An InnoDB
table created in its own
file-per-table
tablespace can be imported from a backup or from another MySQL
server instance using DISCARD TABLEPACE
and
IMPORT TABLESPACE
clauses. See
Section 15.6.1.3, “Importing InnoDB Tables”.
Row Order for MyISAM Tables
ORDER BY
enables you to create the new table
with the rows in a specific order. This option is useful primarily
when you know that you 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.
The table does not remain in the specified order after inserts and deletes.
ORDER BY
syntax permits one or more column
names to be specified for sorting, each of which optionally can be
followed by ASC
or DESC
to
indicate ascending or descending sort order, respectively. The
default is ascending order. Only column names are permitted as
sort criteria; arbitrary expressions are not permitted. This
clause should be given last after any other clauses.
ORDER BY
does not make sense for
InnoDB
tables because InnoDB
always orders table rows according to the
clustered index.
When used on a partitioned table, ALTER TABLE ... ORDER
BY
orders rows within each partition only.
Partitioning Options
partition_options
signifies options
that can be used with partitioned tables for repartitioning, to
add, drop, discard, import, merge, and split partitions, and to
perform partitioning maintenance.
It is possible for an ALTER TABLE
statement to contain a PARTITION BY
or
REMOVE PARTITIONING
clause in an addition to
other alter specifications, but the PARTITION
BY
or REMOVE PARTITIONING
clause must
be specified last after any other specifications. The ADD
PARTITION
, DROP PARTITION
,
DISCARD PARTITION
, IMPORT
PARTITION
, COALESCE PARTITION
,
REORGANIZE PARTITION
, EXCHANGE
PARTITION
, ANALYZE PARTITION
,
CHECK PARTITION
, and REPAIR
PARTITION
options cannot be combined with other alter
specifications in a single ALTER TABLE
, since
the options just listed act on individual partitions.
For more information about partition options, see
Section 13.1.20, “CREATE TABLE Statement”, and
Section 13.1.9.1, “ALTER TABLE Partition Operations”. For
information about and examples of ALTER TABLE ...
EXCHANGE PARTITION
statements, see
Section 24.3.3, “Exchanging Partitions and Subpartitions with Tables”.
Partitioning-related clauses for ALTER
TABLE
can be used with partitioned tables for
repartitioning, to add, drop, discard, import, merge, and split
partitions, and to perform partitioning maintenance.
Simply using a
partition_options
clause withALTER TABLE
on a partitioned table repartitions the table according to the partitioning scheme defined by thepartition_options
. This clause always begins withPARTITION BY
, and follows the same syntax and other rules as apply to thepartition_options
clause forCREATE TABLE
(for more detailed information, see Section 13.1.20, “CREATE TABLE Statement”), and can also be used to partition an existing table that is not already partitioned. For example, consider a (nonpartitioned) table defined as shown here:CREATE TABLE t1 ( id INT, year_col INT );
This table can be partitioned by
HASH
, using theid
column as the partitioning key, into 8 partitions by means of this statement:ALTER TABLE t1 PARTITION BY HASH(id) PARTITIONS 8;
MySQL supports an
ALGORITHM
option with[SUB]PARTITION BY [LINEAR] KEY
.ALGORITHM=1
causes the server to use the same key-hashing functions as MySQL 5.1 when computing the placement of rows in partitions;ALGORITHM=2
means that the server employs the key-hashing functions implemented and used by default for newKEY
partitioned tables in MySQL 5.5 and later. (Partitioned tables created with the key-hashing functions employed in MySQL 5.5 and later cannot be used by a MySQL 5.1 server.) Not specifying the option has the same effect as usingALGORITHM=2
. This option is intended for use chiefly when upgrading or downgrading[LINEAR] KEY
partitioned tables between MySQL 5.1 and later MySQL versions, or for creating tables partitioned byKEY
orLINEAR KEY
on a MySQL 5.5 or later server which can be used on a MySQL 5.1 server.The table that results from using an
ALTER TABLE ... PARTITION BY
statement must follow the same rules as one created usingCREATE TABLE ... PARTITION BY
. This includes the rules governing the relationship between any unique keys (including any primary key) that the table might have, and the column or columns used in the partitioning expression, as discussed in Section 24.6.1, “Partitioning Keys, Primary Keys, and Unique Keys”. TheCREATE TABLE ... PARTITION BY
rules for specifying the number of partitions also apply toALTER TABLE ... PARTITION BY
.The
partition_definition
clause forALTER TABLE ADD PARTITION
supports the same options as the clause of the same name for theCREATE TABLE
statement. (See Section 13.1.20, “CREATE TABLE Statement”, for the syntax and description.) Suppose that you have the partitioned table created as shown here:CREATE TABLE t1 ( id INT, year_col INT ) PARTITION BY RANGE (year_col) ( PARTITION p0 VALUES LESS THAN (1991), PARTITION p1 VALUES LESS THAN (1995), PARTITION p2 VALUES LESS THAN (1999) );
You can add a new partition
p3
to this table for storing values less than2002
as follows:ALTER TABLE t1 ADD PARTITION (PARTITION p3 VALUES LESS THAN (2002));
DROP PARTITION
can be used to drop one or moreRANGE
orLIST
partitions. This statement cannot be used withHASH
orKEY
partitions; instead, useCOALESCE PARTITION
(see later in this section). Any data that was stored in the dropped partitions named in thepartition_names
list is discarded. For example, given the tablet1
defined previously, you can drop the partitions namedp0
andp1
as shown here:ALTER TABLE t1 DROP PARTITION p0, p1;
NoteDROP PARTITION
does not work with tables that use theNDB
storage engine. See Section 24.3.1, “Management of RANGE and LIST Partitions”, and Section 23.1.7, “Known Limitations of NDB Cluster”.ADD PARTITION
andDROP PARTITION
do not currently supportIF [NOT] EXISTS
.The
DISCARD PARTITION ... TABLESPACE
andIMPORT PARTITION ... TABLESPACE
options extend the Transportable Tablespace feature to individualInnoDB
table partitions. EachInnoDB
table partition has its own tablespace file (.ibd
file). The Transportable Tablespace feature makes it easy to copy the tablespaces from a running MySQL server instance to another running instance, or to perform a restore on the same instance. Both options take a comma-separated list of one or more partition names. For example:ALTER TABLE t1 DISCARD PARTITION p2, p3 TABLESPACE;
ALTER TABLE t1 IMPORT PARTITION p2, p3 TABLESPACE;
When running
DISCARD PARTITION ... TABLESPACE
andIMPORT PARTITION ... TABLESPACE
on subpartitioned tables, both partition and subpartition names are allowed. When a partition name is specified, subpartitions of that partition are included.The Transportable Tablespace feature also supports copying or restoring partitioned
InnoDB
tables. For more information, see Section 15.6.1.3, “Importing InnoDB Tables”.Renames of partitioned tables are supported. You can rename individual partitions indirectly using
ALTER TABLE ... REORGANIZE PARTITION
; however, this operation copies the partition's data.To delete rows from selected partitions, use the
TRUNCATE PARTITION
option. This option takes a list of one or more comma-separated partition names. Consider the tablet1
created by this statement:CREATE TABLE t1 ( id INT, year_col INT ) PARTITION BY RANGE (year_col) ( PARTITION p0 VALUES LESS THAN (1991), PARTITION p1 VALUES LESS THAN (1995), PARTITION p2 VALUES LESS THAN (1999), PARTITION p3 VALUES LESS THAN (2003), PARTITION p4 VALUES LESS THAN (2007) );
To delete all rows from partition
p0
, use the following statement:ALTER TABLE t1 TRUNCATE PARTITION p0;
The statement just shown has the same effect as the following
DELETE
statement:DELETE FROM t1 WHERE year_col < 1991;
When truncating multiple partitions, the partitions do not have to be contiguous: This can greatly simplify delete operations on partitioned tables that would otherwise require very complex
WHERE
conditions if done withDELETE
statements. For example, this statement deletes all rows from partitionsp1
andp3
:ALTER TABLE t1 TRUNCATE PARTITION p1, p3;
An equivalent
DELETE
statement is shown here:DELETE FROM t1 WHERE (year_col >= 1991 AND year_col < 1995) OR (year_col >= 2003 AND year_col < 2007);
If you use the
ALL
keyword in place of the list of partition names, the statement acts on all table partitions.TRUNCATE PARTITION
merely deletes rows; it does not alter the definition of the table itself, or of any of its partitions.To verify that the rows were dropped, check the
INFORMATION_SCHEMA.PARTITIONS
table, using a query such as this one:SELECT PARTITION_NAME, TABLE_ROWS FROM INFORMATION_SCHEMA.PARTITIONS WHERE TABLE_NAME = 't1';
COALESCE PARTITION
can be used with a table that is partitioned byHASH
orKEY
to reduce the number of partitions bynumber
. Suppose that you have created tablet2
as follows:CREATE TABLE t2 ( name VARCHAR (30), started DATE ) PARTITION BY HASH( YEAR(started) ) PARTITIONS 6;
To reduce the number of partitions used by
t2
from 6 to 4, use the following statement:ALTER TABLE t2 COALESCE PARTITION 2;
The data contained in the last
number
partitions is merged into the remaining partitions. In this case, partitions 4 and 5 are merged into the first 4 partitions (the partitions numbered 0, 1, 2, and 3).To change some but not all the partitions used by a partitioned table, you can use
REORGANIZE PARTITION
. This statement can be used in several ways:To merge a set of partitions into a single partition. This is done by naming several partitions in the
partition_names
list and supplying a single definition forpartition_definition
.To split an existing partition into several partitions. Accomplish this by naming a single partition for
partition_names
and providing multiplepartition_definitions
.To change the ranges for a subset of partitions defined using
VALUES LESS THAN
or the value lists for a subset of partitions defined usingVALUES IN
.
NoteFor partitions that have not been explicitly named, MySQL automatically provides the default names
p0
,p1
,p2
, and so on. The same is true with regard to subpartitions.For more detailed information about and examples of
ALTER TABLE ... REORGANIZE PARTITION
statements, see Section 24.3.1, “Management of RANGE and LIST Partitions”.To exchange a table partition or subpartition with a table, use the
ALTER TABLE ... EXCHANGE PARTITION
statement—that is, to move any existing rows in the partition or subpartition to the nonpartitioned table, and any existing rows in the nonpartitioned table to the table partition or subpartition.For usage information and examples, see Section 24.3.3, “Exchanging Partitions and Subpartitions with Tables”.
Several options provide partition maintenance and repair functionality analogous to that implemented for nonpartitioned tables by statements such as
CHECK TABLE
andREPAIR TABLE
(which are also supported for partitioned tables; for more information, see Section 13.7.3, “Table Maintenance Statements”). These includeANALYZE PARTITION
,CHECK PARTITION
,OPTIMIZE PARTITION
,REBUILD PARTITION
, andREPAIR PARTITION
. Each of these options takes apartition_names
clause consisting of one or more names of partitions, separated by commas. The partitions must already exist in the target table. You can also use theALL
keyword in place ofpartition_names
, in which case the statement acts on all table partitions. For more information and examples, see Section 24.3.4, “Maintenance of Partitions”.InnoDB
does not currently support per-partition optimization;ALTER TABLE ... OPTIMIZE PARTITION
causes the entire table to rebuilt and analyzed, and an appropriate warning to be issued. (Bug #11751825, Bug #42822) To work around this problem, useALTER TABLE ... REBUILD PARTITION
andALTER TABLE ... ANALYZE PARTITION
instead.The
ANALYZE PARTITION
,CHECK PARTITION
,OPTIMIZE PARTITION
, andREPAIR PARTITION
options are not supported for tables which are not partitioned.REMOVE PARTITIONING
enables you to remove a table's partitioning without otherwise affecting the table or its data. This option can be combined with otherALTER TABLE
options such as those used to add, drop, or rename columns or indexes.Using the
ENGINE
option withALTER TABLE
changes the storage engine used by the table without affecting the partitioning. The target storage engine must provide its own partitioning handler. Only theInnoDB
andNDB
storage engines have native partitioning handlers;NDB
is not currently supported in MySQL 8.0.
It is possible for an ALTER TABLE
statement to contain a PARTITION BY
or
REMOVE PARTITIONING
clause in an addition to
other alter specifications, but the PARTITION
BY
or REMOVE PARTITIONING
clause
must be specified last after any other specifications.
The ADD PARTITION
, DROP
PARTITION
, COALESCE PARTITION
,
REORGANIZE PARTITION
, ANALYZE
PARTITION
, CHECK PARTITION
, and
REPAIR PARTITION
options cannot be combined
with other alter specifications in a single ALTER
TABLE
, since the options just listed act on individual
partitions. For more information, see
Section 13.1.9.1, “ALTER TABLE Partition Operations”.
Only a single instance of any one of the following options can
be used in a given ALTER TABLE
statement: PARTITION BY
, ADD
PARTITION
, DROP PARTITION
,
TRUNCATE PARTITION
, EXCHANGE
PARTITION
, REORGANIZE PARTITION
, or
COALESCE PARTITION
, ANALYZE
PARTITION
, CHECK PARTITION
,
OPTIMIZE PARTITION
, REBUILD
PARTITION
, REMOVE PARTITIONING
.
For example, the following two statements are invalid:
ALTER TABLE t1 ANALYZE PARTITION p1, ANALYZE PARTITION p2; ALTER TABLE t1 ANALYZE PARTITION p1, CHECK PARTITION p2;
In the first case, you can analyze partitions
p1
and p2
of table
t1
concurrently using a single statement with
a single ANALYZE PARTITION
option that lists
both of the partitions to be analyzed, like this:
ALTER TABLE t1 ANALYZE PARTITION p1, p2;
In the second case, it is not possible to perform
ANALYZE
and CHECK
operations on different partitions of the same table
concurrently. Instead, you must issue two separate statements,
like this:
ALTER TABLE t1 ANALYZE PARTITION p1; ALTER TABLE t1 CHECK PARTITION p2;
REBUILD
operations are currently unsupported
for subpartitions. The REBUILD
keyword is
expressly disallowed with subpartitions, and causes
ALTER TABLE
to fail with an error if so used.
CHECK PARTITION
and REPAIR
PARTITION
operations fail when the partition to be
checked or repaired contains any duplicate key errors.
For more information about these statements, see Section 24.3.4, “Maintenance of Partitions”.
ALTER TABLE
operations permitted for
generated columns are ADD
,
MODIFY
, and CHANGE
.
Generated columns can be added.
CREATE TABLE t1 (c1 INT); ALTER TABLE t1 ADD COLUMN c2 INT GENERATED ALWAYS AS (c1 + 1) STORED;
The data type and expression of generated columns can be modified.
CREATE TABLE t1 (c1 INT, c2 INT GENERATED ALWAYS AS (c1 + 1) STORED); ALTER TABLE t1 MODIFY COLUMN c2 TINYINT GENERATED ALWAYS AS (c1 + 5) STORED;
Generated columns can be renamed or dropped, if no other column refers to them.
CREATE TABLE t1 (c1 INT, c2 INT GENERATED ALWAYS AS (c1 + 1) STORED); ALTER TABLE t1 CHANGE c2 c3 INT GENERATED ALWAYS AS (c1 + 1) STORED; ALTER TABLE t1 DROP COLUMN c3;
Virtual generated columns cannot be altered to stored generated columns, or vice versa. To work around this, drop the column, then add it with the new definition.
CREATE TABLE t1 (c1 INT, c2 INT GENERATED ALWAYS AS (c1 + 1) VIRTUAL); ALTER TABLE t1 DROP COLUMN c2; ALTER TABLE t1 ADD COLUMN c2 INT GENERATED ALWAYS AS (c1 + 1) STORED;
Nongenerated columns can be altered to stored but not virtual generated columns.
CREATE TABLE t1 (c1 INT, c2 INT); ALTER TABLE t1 MODIFY COLUMN c2 INT GENERATED ALWAYS AS (c1 + 1) STORED;
Stored but not virtual generated columns can be altered to nongenerated columns. The stored generated values become the values of the nongenerated column.
CREATE TABLE t1 (c1 INT, c2 INT GENERATED ALWAYS AS (c1 + 1) STORED); ALTER TABLE t1 MODIFY COLUMN c2 INT;
ADD COLUMN
is not an in-place operation for stored columns (done without using a temporary table) because the expression must be evaluated by the server. For stored columns, indexing changes are done in place, and expression changes are not done in place. Changes to column comments are done in place.For non-partitioned tables,
ADD COLUMN
andDROP COLUMN
are in-place operations for virtual columns. However, adding or dropping a virtual column cannot be performed in place in combination with otherALTER TABLE
operations.For partitioned tables,
ADD COLUMN
andDROP COLUMN
are not in-place operations for virtual columns.InnoDB
supports secondary indexes on virtual generated columns. Adding or dropping a secondary index on a virtual generated column is an in-place operation. For more information, see Section 13.1.20.9, “Secondary Indexes and Generated Columns”.When a
VIRTUAL
generated column is added to a table or modified, it is not ensured that data being calculated by the generated column expression is be out of range for the column. This can lead to inconsistent data being returned and unexpectedly failed statements. To permit control over whether validation occurs for such columns,ALTER TABLE
supportsWITHOUT VALIDATION
andWITH VALIDATION
clauses:With
WITHOUT VALIDATION
(the default if neither clause is specified), an in-place operation is performed (if possible), data integrity is not checked, and the statement finishes more quickly. However, later reads from the table might report warnings or errors for the column if values are out of range.With
WITH VALIDATION
,ALTER TABLE
copies the table. If an out-of-range or any other error occurs, the statement fails. Because a table copy is performed, the statement takes longer.
WITHOUT VALIDATION
andWITH VALIDATION
are permitted only withADD COLUMN
,CHANGE COLUMN
, andMODIFY COLUMN
operations. Otherwise, anER_WRONG_USAGE
error occurs.If expression evaluation causes truncation or provides incorrect input to a function, the
ALTER TABLE
statement terminates with an error and the DDL operation is rejected.An
ALTER TABLE
statement that changes the default value of a columncol_name
may also change the value of a generated column expression that refers to the column usingcol_name
, which may change the value of a generated column expression that refers to the column usingDEFAULT(
. For this reason,col_name
)ALTER TABLE
operations that change the definition of a column cause a table rebuild if any generated column expression usesDEFAULT()
.
Begin with a table t1
created as shown here:
CREATE TABLE t1 (a INTEGER, b CHAR(10));
To rename the table from t1
to
t2
:
ALTER TABLE t1 RENAME t2;
To change column a
from
INTEGER
to TINYINT NOT
NULL
(leaving the name the same), and to change column
b
from CHAR(10)
to
CHAR(20)
as well as renaming it from
b
to c
:
ALTER TABLE t2 MODIFY a TINYINT NOT NULL, CHANGE b c CHAR(20);
To add a new TIMESTAMP
column
named d
:
ALTER TABLE t2 ADD d TIMESTAMP;
To add an index on column d
and a
UNIQUE
index on column a
:
ALTER TABLE t2 ADD INDEX (d), ADD UNIQUE (a);
To remove column c
:
ALTER TABLE t2 DROP COLUMN c;
To add a new AUTO_INCREMENT
integer column
named c
:
ALTER TABLE t2 ADD c INT UNSIGNED NOT NULL AUTO_INCREMENT, ADD PRIMARY KEY (c);
We indexed c
(as a PRIMARY
KEY
) because AUTO_INCREMENT
columns
must be indexed, and we declare c
as
NOT NULL
because primary key columns cannot
be NULL
.
For NDB
tables, it is also possible
to change the storage type used for a table or column. For
example, consider an NDB
table
created as shown here:
mysql> CREATE TABLE t1 (c1 INT) TABLESPACE ts_1 ENGINE NDB;
Query OK, 0 rows affected (1.27 sec)
To convert this table to disk-based storage, you can use the
following ALTER TABLE
statement:
mysql>ALTER TABLE t1 TABLESPACE ts_1 STORAGE DISK;
Query OK, 0 rows affected (2.99 sec) Records: 0 Duplicates: 0 Warnings: 0 mysql>SHOW CREATE TABLE t1\G
*************************** 1. row *************************** Table: t1 Create Table: CREATE TABLE `t1` ( `c1` int(11) DEFAULT NULL ) /*!50100 TABLESPACE ts_1 STORAGE DISK */ ENGINE=ndbcluster DEFAULT CHARSET=latin1 1 row in set (0.01 sec)
It is not necessary that the tablespace was referenced when the
table was originally created; however, the tablespace must be
referenced by the ALTER TABLE
:
mysql>CREATE TABLE t2 (c1 INT) ts_1 ENGINE NDB;
Query OK, 0 rows affected (1.00 sec) mysql>ALTER TABLE t2 STORAGE DISK;
ERROR 1005 (HY000): Can't create table 'c.#sql-1750_3' (errno: 140) mysql>ALTER TABLE t2 TABLESPACE ts_1 STORAGE DISK;
Query OK, 0 rows affected (3.42 sec) Records: 0 Duplicates: 0 Warnings: 0 mysql>SHOW CREATE TABLE t2\G
*************************** 1. row *************************** Table: t1 Create Table: CREATE TABLE `t2` ( `c1` int(11) DEFAULT NULL ) /*!50100 TABLESPACE ts_1 STORAGE DISK */ ENGINE=ndbcluster DEFAULT CHARSET=latin1 1 row in set (0.01 sec)
To change the storage type of an individual column, you can use
ALTER TABLE ... MODIFY [COLUMN]
. For example,
suppose you create an NDB Cluster Disk Data table with two
columns, using this CREATE TABLE
statement:
mysql>CREATE TABLE t3 (c1 INT, c2 INT)
->TABLESPACE ts_1 STORAGE DISK ENGINE NDB;
Query OK, 0 rows affected (1.34 sec)
To change column c2
from disk-based to
in-memory storage, include a STORAGE MEMORY clause in the column
definition used by the ALTER TABLE statement, as shown here:
mysql> ALTER TABLE t3 MODIFY c2 INT STORAGE MEMORY;
Query OK, 0 rows affected (3.14 sec)
Records: 0 Duplicates: 0 Warnings: 0
You can make an in-memory column into a disk-based column by
using STORAGE DISK
in a similar fashion.
Column c1
uses disk-based storage, since this
is the default for the table (determined by the table-level
STORAGE DISK
clause in the
CREATE TABLE
statement). However,
column c2
uses in-memory storage, as can be
seen here in the output of SHOW CREATE
TABLE
:
mysql> SHOW CREATE TABLE t3\G
*************************** 1. row ***************************
Table: t3
Create Table: CREATE TABLE `t3` (
`c1` int(11) DEFAULT NULL,
`c2` int(11) /*!50120 STORAGE MEMORY */ DEFAULT NULL
) /*!50100 TABLESPACE ts_1 STORAGE DISK */ ENGINE=ndbcluster DEFAULT CHARSET=latin1
1 row in set (0.02 sec)
When you add an AUTO_INCREMENT
column, column
values are filled in with sequence numbers automatically. For
MyISAM
tables, you can set the first sequence
number by executing SET
INSERT_ID=
before
value
ALTER TABLE
or by using the
AUTO_INCREMENT=
table option.
value
With MyISAM
tables, if you do not change the
AUTO_INCREMENT
column, the sequence number is
not affected. If you drop an AUTO_INCREMENT
column and then add another AUTO_INCREMENT
column, the numbers are resequenced beginning with 1.
When replication is used, adding an
AUTO_INCREMENT
column to a table might not
produce the same ordering of the rows on the replica and the
source. 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 source and replica, 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 also produces a new table
t2
identical to t1
, with
the addition of an AUTO_INCREMENT
column:
CREATE TABLE t2 LIKE t1; ALTER TABLE t2 ADD id INT AUTO_INCREMENT PRIMARY KEY; INSERT INTO t2 SELECT * FROM t1 ORDER BY col1, col2;
To guarantee the same ordering on both source and replica,
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 TABLE t1; ALTER TABLE t2 RENAME t1;
ALTER [UNDO] TABLESPACEtablespace_name
NDB only: {ADD | DROP} DATAFILE 'file_name
' [INITIAL_SIZE [=] size] [WAIT] InnoDB and NDB: [RENAME TOtablespace_name
] InnoDB only: [AUTOEXTEND_SIZE [=] 'value
'] [SET {ACTIVE | INACTIVE}] [ENCRYPTION [=] {'Y' | 'N'}] InnoDB and NDB: [ENGINE [=]engine_name
] Reserved for future use: [ENGINE_ATTRIBUTE [=] 'string
']
This statement is used with NDB
and
InnoDB
tablespaces. It can be used to add a new
data file to, or to drop a data file from an
NDB
tablespace. It can also be used to rename
an NDB Cluster Disk Data tablespace, rename an
InnoDB
general tablespace, encrypt an
InnoDB
general tablespace, or mark an
InnoDB
undo tablespace as active or inactive.
The UNDO
keyword, introduced in MySQL 8.0.14,
is used with the SET {ACTIVE | INACTIVE}
clause
to mark an InnoDB
undo tablespace as active or
inactive. For more information, see
Section 15.6.3.4, “Undo Tablespaces”.
The ADD DATAFILE
variant enables you to specify
an initial size for an NDB
Disk Data tablespace
using an INITIAL_SIZE
clause, where
size
is measured in bytes; the default
value is 134217728 (128 MB). You may optionally follow
size
with a one-letter abbreviation for
an order of magnitude, similar to those used in
my.cnf
. Generally, this is one of the letters
M
(megabytes) or G
(gigabytes).
On 32-bit systems, the maximum supported value for
INITIAL_SIZE
is 4294967296 (4 GB). (Bug #29186)
INITIAL_SIZE
is rounded, explicitly, as for
CREATE TABLESPACE
.
Once a data file has been created, its size cannot be changed;
however, you can add more data files to an NDB tablespace using
additional ALTER TABLESPACE ... ADD DATAFILE
statements.
When ALTER TABLESPACE ... ADD DATAFILE
is used
with ENGINE = NDB
, a data file is created on
each Cluster data node, but only one row is generated in the
INFORMATION_SCHEMA.FILES
table. See
the description of this table, as well as
Section 23.5.10.1, “NDB Cluster Disk Data Objects”, for more
information. ADD DATAFILE
is not supported with
InnoDB
tablespaces.
Using DROP DATAFILE
with
ALTER TABLESPACE
drops the data
file 'file_name
' from an NDB
tablespace. You cannot drop a data file from a tablespace which is
in use by any table; in other words, the data file must be empty
(no extents used). See
Section 23.5.10.1, “NDB Cluster Disk Data Objects”. In addition,
any data file to be dropped must previously have been added to the
tablespace with CREATE TABLESPACE
or ALTER TABLESPACE
. DROP
DATAFILE
is not supported with InnoDB
tablespaces.
WAIT
is parsed but otherwise ignored. It is
intended for future expansion.
The ENGINE
clause, which specifies the storage
engine used by the tablespace, is deprecated; expect it to be
removed in a future release. The tablespace storage engine is
known by the data dictionary, making the ENGINE
clause obsolete. If the storage engine is specified, it must match
the tablespace storage engine defined in the data dictionary. The
only values for engine_name
compatible
with NDB
tablespaces are
NDB
and NDBCLUSTER
.
RENAME TO
operations are implicitly performed
in autocommit
mode, regardless of
the autocommit
setting.
A RENAME TO
operation cannot be performed while
LOCK TABLES
or
FLUSH TABLES WITH READ
LOCK
is in effect for tables that reside in the
tablespace.
Exclusive metadata locks are taken on tables that reside in a general tablespace while the tablespace is renamed, which prevents concurrent DDL. Concurrent DML is supported.
The CREATE TABLESPACE
privilege is
required to rename an InnoDB
general
tablespace.
The AUTOEXTEND_SIZE
option defines the amount
by which InnoDB
extends the size of a
tablespace when it becomes full. Introduced in MySQL 8.0.23. The
setting must be a multiple of 4MB. The default setting is 0, which
causes the tablespace to be extended according to the implicit
default behavior. For more information, see
Section 15.6.3.9, “Tablespace AUTOEXTEND_SIZE Configuration”.
The ENCRYPTION
clause enables or disables
page-level data encryption for an InnoDB
general tablespace or the mysql
system
tablespace. Encryption support for general tablespaces was
introduced in MySQL 8.0.13. Encryption support for the
mysql
system tablespace was introduced in MySQL
8.0.16.
A keyring plugin must be installed and configured before encryption can be enabled.
As of MySQL 8.0.16, if the
table_encryption_privilege_check
variable is enabled, the
TABLE_ENCRYPTION_ADMIN
privilege is
required to alter a general tablespace with an
ENCRYPTION
clause setting that differs from the
default_table_encryption
setting.
Enabling encryption for a general tablespace fails if any table in
the tablespace belongs to a schema defined with
DEFAULT
ENCRYPTION='N'
. Similarly, disabling encryption fails if
any table in the general tablespace belongs to a schema defined
with DEFAULT
ENCRYPTION='Y'
. The
DEFAULT
ENCRYPTION
schema option was introduced in MySQL 8.0.16.
If an ALTER TABLESPACE
statement
executed on a general tablespace does not include an
ENCRYPTION
clause, the tablespace retains its
current encryption status, regardless of the
default_table_encryption
setting.
When a general tablespace or the mysql
system
tablespace is encrypted, all tables residing in the tablespace are
encrypted. Likewise, a table created in an encrypted tablespace is
encrypted.
The INPLACE
algorithm is used when altering the
ENCRYPTION
attribute of a general tablespace or
the mysql
system tablespace. The
INPLACE
algorithm permits concurrent DML on
tables that reside in the tablespace. Concurrent DDL is blocked.
For more information, see Section 15.13, “InnoDB Data-at-Rest Encryption”.
The ENGINE_ATTRIBUTE
option (available as of
MySQL 8.0.21) is used to specify tablespace attributes for primary
storage engines. The option is reserved for future use.
Permitted values are a string literal containing a valid
JSON
document or an empty string (''). Invalid
JSON
is rejected.
ALTER TABLESPACE ts1 ENGINE_ATTRIBUTE='{"key
":"value
"}';
ENGINE_ATTRIBUTE
values can be repeated without
error. In this case, the last specified value is used.
ENGINE_ATTRIBUTE
values are not checked by the
server, nor are they cleared when the table's storage engine is
changed.
It is not permitted to alter an individual element of a JSON attribute value. You can only add or replace an attribute.
ALTER [ALGORITHM = {UNDEFINED | MERGE | TEMPTABLE}] [DEFINER =user
] [SQL SECURITY { DEFINER | INVOKER }] VIEWview_name
[(column_list
)] ASselect_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
see Section 13.1.23, “CREATE VIEW Statement”). This statement
requires the CREATE VIEW
and
DROP
privileges for the view, and
some privilege for each column referred to in the
SELECT
statement.
ALTER VIEW
is permitted only to the
definer or users with the
SET_USER_ID
privilege (or the
deprecated SUPER
privilege).
CREATE {DATABASE | SCHEMA} [IF NOT EXISTS]db_name
[create_option
] ...create_option
: [DEFAULT] { CHARACTER SET [=]charset_name
| COLLATE [=]collation_name
| ENCRYPTION [=] {'Y' | 'N'} }
CREATE DATABASE
creates a database
with the given name. To use this statement, you need the
CREATE
privilege for the database.
CREATE
SCHEMA
is a synonym for CREATE
DATABASE
.
An error occurs if the database exists and you did not specify
IF NOT EXISTS
.
CREATE DATABASE
is not permitted
within a session that has an active LOCK
TABLES
statement.
Each create_option
specifies a database
characteristic. Database characteristics are stored in the data
dictionary.
The
CHARACTER SET
option specifies the default database character set. TheCOLLATE
option specifies the default database collation. For information about character set and collation names, see Chapter 10, Character Sets, Collations, Unicode.To see the available character sets and collations, use the the
SHOW CHARACTER SET
andSHOW COLLATION
statements, respectively. See Section 13.7.7.3, “SHOW CHARACTER SET Statement”, and Section 13.7.7.4, “SHOW COLLATION Statement”.The
ENCRYPTION
option, introduced in MySQL 8.0.16, defines the default database encryption, which is inherited by tables created in the database. The permitted values are'Y'
(encryption enabled) and'N'
(encryption disabled). If theENCRYPTION
option is not specified, the value of thedefault_table_encryption
system variable defines the default database encryption. If thetable_encryption_privilege_check
system variable is enabled, theTABLE_ENCRYPTION_ADMIN
privilege is required to specify a default encryption setting that differs from thedefault_table_encryption
setting. For more information, see Defining an Encryption Default for Schemas and General Tablespaces.
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. Rules for
permissible database names are given in
Section 9.2, “Schema Object Names”. If a database name contains special
characters, the name for the database directory contains encoded
versions of those characters as described in
Section 9.2.4, “Mapping of Identifiers to File Names”.
Creating a database directory by manually creating a directory under the data directory (for example, with mkdir) is unsupported in MySQL 8.0.
When you create a database, let the server manage the directory and the files in it. Manipulating database directories and files directly can cause inconsistencies and unexpected results.
MySQL has no limit on the number of databases. The underlying file system may have a limit on the number of directories.
You can also use the mysqladmin program to create databases. See Section 4.5.2, “mysqladmin — A MySQL Server Administration Program”.
CREATE [DEFINER =user
] EVENT [IF NOT EXISTS]event_name
ON SCHEDULEschedule
[ON COMPLETION [NOT] PRESERVE] [ENABLE | DISABLE | DISABLE ON SLAVE] [COMMENT 'string
'] DOevent_body
;schedule
: { ATtimestamp
[+ INTERVALinterval
] ... | EVERYinterval
[STARTStimestamp
[+ INTERVALinterval
] ...] [ENDStimestamp
[+ INTERVALinterval
] ...] }interval
:quantity
{YEAR | QUARTER | MONTH | DAY | HOUR | MINUTE | WEEK | SECOND | YEAR_MONTH | DAY_HOUR | DAY_MINUTE | DAY_SECOND | HOUR_MINUTE | HOUR_SECOND | MINUTE_SECOND}
This statement creates and schedules a new event. The event does not run unless the Event Scheduler is enabled. For information about checking Event Scheduler status and enabling it if necessary, see Section 25.4.2, “Event Scheduler Configuration”.
CREATE EVENT
requires the
EVENT
privilege for the schema in
which the event is to be created. If the
DEFINER
clause is present, the privileges
required depend on the user
value, as
discussed in Section 25.6, “Stored Object Access Control”.
The minimum requirements for a valid CREATE
EVENT
statement are as follows:
The keywords
CREATE EVENT
plus an event name, which uniquely identifies the event in a database schema.An
ON SCHEDULE
clause, which determines when and how often the event executes.A
DO
clause, which contains the SQL statement to be executed by an event.
This is an example of a minimal CREATE
EVENT
statement:
CREATE EVENT myevent ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 1 HOUR DO UPDATE myschema.mytable SET mycol = mycol + 1;
The previous statement creates an event named
myevent
. This event executes once—one
hour following its creation—by running an SQL statement that
increments the value of the myschema.mytable
table's mycol
column by 1.
The event_name
must be a valid MySQL
identifier with a maximum length of 64 characters. Event names are
not case-sensitive, so you cannot have two events named
myevent
and MyEvent
in the
same schema. In general, the rules governing event names are the
same as those for names of stored routines. See
Section 9.2, “Schema Object Names”.
An event is associated with a schema. If no schema is indicated as
part of event_name
, the default
(current) schema is assumed. To create an event in a specific
schema, qualify the event name with a schema using
syntax.
schema_name
.event_name
The DEFINER
clause specifies the MySQL account
to be used when checking access privileges at event execution
time. If the DEFINER
clause is present, the
user
value should be a MySQL account
specified as
'
,
user_name
'@'host_name
'CURRENT_USER
, or
CURRENT_USER()
. The permitted
user
values depend on the privileges
you hold, as discussed in
Section 25.6, “Stored Object Access Control”. Also see that section
for additional information about event security.
If the DEFINER
clause is omitted, the default
definer is the user who executes the CREATE
EVENT
statement. This is the same as specifying
DEFINER = CURRENT_USER
explicitly.
Within an event body, the
CURRENT_USER
function returns the
account used to check privileges at event execution time, which is
the DEFINER
user. For information about user
auditing within events, see
Section 6.2.22, “SQL-Based Account Activity Auditing”.
IF NOT EXISTS
has the same meaning for
CREATE EVENT
as for
CREATE TABLE
: If an event named
event_name
already exists in the same
schema, no action is taken, and no error results. (However, a
warning is generated in such cases.)
The ON SCHEDULE
clause determines when, how
often, and for how long the event_body
defined for the event repeats. This clause takes one of two forms:
AT
is used for a one-time event. It specifies that the event executes one time only at the date and time given bytimestamp
timestamp
, which must include both the date and time, or must be an expression that resolves to a datetime value. You may use a value of either theDATETIME
orTIMESTAMP
type for this purpose. If the date is in the past, a warning occurs, as shown here:mysql>
SELECT NOW();
+---------------------+ | NOW() | +---------------------+ | 2006-02-10 23:59:01 | +---------------------+ 1 row in set (0.04 sec) mysql>CREATE EVENT e_totals
->ON SCHEDULE AT '2006-02-10 23:59:00'
->DO INSERT INTO test.totals VALUES (NOW());
Query OK, 0 rows affected, 1 warning (0.00 sec) mysql>SHOW WARNINGS\G
*************************** 1. row *************************** Level: Note Code: 1588 Message: Event execution time is in the past and ON COMPLETION NOT PRESERVE is set. The event was dropped immediately after creation.CREATE EVENT
statements which are themselves invalid—for whatever reason—fail with an error.You may use
CURRENT_TIMESTAMP
to specify the current date and time. In such a case, the event acts as soon as it is created.To create an event which occurs at some point in the future relative to the current date and time—such as that expressed by the phrase “three weeks from now”—you can use the optional clause
+ INTERVAL
. Theinterval
interval
portion consists of two parts, a quantity and a unit of time, and follows the syntax rules described in Temporal Intervals, except that you cannot use any units keywords that involving microseconds when defining an event. With some interval types, complex time units may be used. For example, “two minutes and ten seconds” can be expressed as+ INTERVAL '2:10' MINUTE_SECOND
.You can also combine intervals. For example,
AT CURRENT_TIMESTAMP + INTERVAL 3 WEEK + INTERVAL 2 DAY
is equivalent to “three weeks and two days from now”. Each portion of such a clause must begin with+ INTERVAL
.To repeat actions at a regular interval, use an
EVERY
clause. TheEVERY
keyword is followed by aninterval
as described in the previous discussion of theAT
keyword. (+ INTERVAL
is not used withEVERY
.) For example,EVERY 6 WEEK
means “every six weeks”.Although
+ INTERVAL
clauses are not permitted in anEVERY
clause, you can use the same complex time units permitted in a+ INTERVAL
.An
EVERY
clause may contain an optionalSTARTS
clause.STARTS
is followed by atimestamp
value that indicates when the action should begin repeating, and may also use+ INTERVAL
to specify an amount of time “from now”. For example,interval
EVERY 3 MONTH STARTS CURRENT_TIMESTAMP + INTERVAL 1 WEEK
means “every three months, beginning one week from now”. Similarly, you can express “every two weeks, beginning six hours and fifteen minutes from now” asEVERY 2 WEEK STARTS CURRENT_TIMESTAMP + INTERVAL '6:15' HOUR_MINUTE
. Not specifyingSTARTS
is the same as usingSTARTS CURRENT_TIMESTAMP
—that is, the action specified for the event begins repeating immediately upon creation of the event.An
EVERY
clause may contain an optionalENDS
clause. TheENDS
keyword is followed by atimestamp
value that tells MySQL when the event should stop repeating. You may also use+ INTERVAL
withinterval
ENDS
; for instance,EVERY 12 HOUR STARTS CURRENT_TIMESTAMP + INTERVAL 30 MINUTE ENDS CURRENT_TIMESTAMP + INTERVAL 4 WEEK
is equivalent to “every twelve hours, beginning thirty minutes from now, and ending four weeks from now”. Not usingENDS
means that the event continues executing indefinitely.ENDS
supports the same syntax for complex time units asSTARTS
does.You may use
STARTS
,ENDS
, both, or neither in anEVERY
clause.If a repeating event does not terminate within its scheduling interval, the result may be multiple instances of the event executing simultaneously. If this is undesirable, you should institute a mechanism to prevent simultaneous instances. For example, you could use the
GET_LOCK()
function, or row or table locking.
The ON SCHEDULE
clause may use expressions
involving built-in MySQL functions and user variables to obtain
any of the timestamp
or
interval
values which it contains. You
may not use stored functions or user-defined functions in such
expressions, nor may you use any table references; however, you
may use SELECT FROM DUAL
. This is true for both
CREATE EVENT
and
ALTER EVENT
statements. References
to stored functions, user-defined functions, and tables in such
cases are specifically not permitted, and fail with an error (see
Bug #22830).
Times in the ON SCHEDULE
clause are interpreted
using the current session
time_zone
value. This becomes the
event time zone; that is, the time zone that is used for event
scheduling and is in effect within the event as it executes. These
times are converted to UTC and stored along with the event time
zone internally. This enables event execution to proceed as
defined regardless of any subsequent changes to the server time
zone or daylight saving time effects. For additional information
about representation of event times, see
Section 25.4.4, “Event Metadata”. See also
Section 13.7.7.18, “SHOW EVENTS Statement”, and
Section 26.14, “The INFORMATION_SCHEMA EVENTS Table”.
Normally, once an event has expired, it is immediately dropped.
You can override this behavior by specifying ON
COMPLETION PRESERVE
. Using ON COMPLETION NOT
PRESERVE
merely makes the default nonpersistent behavior
explicit.
You can create an event but prevent it from being active using the
DISABLE
keyword. Alternatively, you can use
ENABLE
to make explicit the default status,
which is active. This is most useful in conjunction with
ALTER EVENT
(see
Section 13.1.3, “ALTER EVENT Statement”).
A third value may also appear in place of
ENABLE
or DISABLE
;
DISABLE ON SLAVE
is set for the status of an
event on a replica to indicate that the event was created on the
replication source server and replicated to the replica, but is
not executed on the replica. See
Section 17.5.1.16, “Replication of Invoked Features”.
You may supply a comment for an event using a
COMMENT
clause.
comment
may be any string of up to 64
characters that you wish to use for describing the event. The
comment text, being a string literal, must be surrounded by
quotation marks.
The DO
clause specifies an action
carried by the event, and consists of an SQL statement. Nearly any
valid MySQL statement that can be used in a stored routine can
also be used as the action statement for a scheduled event. (See
Section 25.8, “Restrictions on Stored Programs”.) For example, the
following event e_hourly
deletes all rows from
the sessions
table once per hour, where this
table is part of the site_activity
schema:
CREATE EVENT e_hourly ON SCHEDULE EVERY 1 HOUR COMMENT 'Clears out sessions table each hour.' DO DELETE FROM site_activity.sessions;
MySQL stores the sql_mode
system
variable setting in effect when an event is created or altered,
and always executes the event with this setting in force,
regardless of the current server SQL mode when the event
begins executing.
A CREATE EVENT
statement that
contains an ALTER EVENT
statement
in its DO
clause appears to
succeed; however, when the server attempts to execute the
resulting scheduled event, the execution fails with an error.
Statements such as SELECT
or
SHOW
that merely return a result
set have no effect when used in an event; the output from these
is not sent to the MySQL Monitor, nor is it stored anywhere.
However, you can use statements such as
SELECT ...
INTO
and
INSERT INTO ...
SELECT
that store a result. (See the next example in
this section for an instance of the latter.)
The schema to which an event belongs is the default schema for
table references in the DO
clause.
Any references to tables in other schemas must be qualified with
the proper schema name.
As with stored routines, you can use compound-statement syntax in
the DO
clause by using the
BEGIN
and END
keywords, as
shown here:
delimiter | CREATE EVENT e_daily ON SCHEDULE EVERY 1 DAY COMMENT 'Saves total number of sessions then clears the table each day' DO BEGIN INSERT INTO site_activity.totals (time, total) SELECT CURRENT_TIMESTAMP, COUNT(*) FROM site_activity.sessions; DELETE FROM site_activity.sessions; END | delimiter ;
This example uses the delimiter
command to
change the statement delimiter. See
Section 25.1, “Defining Stored Programs”.
More complex compound statements, such as those used in stored routines, are possible in an event. This example uses local variables, an error handler, and a flow control construct:
delimiter | CREATE EVENT e ON SCHEDULE EVERY 5 SECOND DO BEGIN DECLARE v INTEGER; DECLARE CONTINUE HANDLER FOR SQLEXCEPTION BEGIN END; SET v = 0; WHILE v < 5 DO INSERT INTO t1 VALUES (0); UPDATE t2 SET s1 = s1 + 1; SET v = v + 1; END WHILE; END | delimiter ;
There is no way to pass parameters directly to or from events; however, it is possible to invoke a stored routine with parameters within an event:
CREATE EVENT e_call_myproc ON SCHEDULE AT CURRENT_TIMESTAMP + INTERVAL 1 DAY DO CALL myproc(5, 27);
If an event's definer has privileges sufficient to set global system variables (see Section 5.1.9.1, “System Variable Privileges”), the event can read and write global variables. As granting such privileges entails a potential for abuse, extreme care must be taken in doing so.
Generally, any statements that are valid in stored routines may be used for action statements executed by events. For more information about statements permissible within stored routines, see Section 25.2.1, “Stored Routine Syntax”. You can create an event as part of a stored routine, but an event cannot be created by another event.
The CREATE FUNCTION
statement is
used to create stored functions and user-defined functions (UDFs):
For information about creating stored functions, see Section 13.1.17, “CREATE PROCEDURE and CREATE FUNCTION Statements”.
For information about creating user-defined functions, see Section 13.7.4.1, “CREATE FUNCTION Statement for User-Defined Functions”.
CREATE [UNIQUE | FULLTEXT | SPATIAL] INDEXindex_name
[index_type
] ONtbl_name
(key_part
,...) [index_option
] [algorithm_option
|lock_option
] ...key_part
: {col_name
[(length
)] | (expr
)} [ASC | DESC]index_option
: { KEY_BLOCK_SIZE [=]value
|index_type
| WITH PARSERparser_name
| COMMENT 'string
' | {VISIBLE | INVISIBLE} | ENGINE_ATTRIBUTE [=] 'string
' | SECONDARY_ENGINE_ATTRIBUTE [=] 'string
' }index_type
: USING {BTREE | HASH}algorithm_option
: ALGORITHM [=] {DEFAULT | INPLACE | COPY}lock_option
: LOCK [=] {DEFAULT | NONE | SHARED | EXCLUSIVE}
Normally, you create all indexes on a table at the time the table
itself is created with CREATE
TABLE
. See Section 13.1.20, “CREATE TABLE Statement”. This
guideline is especially important for
InnoDB
tables, where the primary key
determines the physical layout of rows in the data file.
CREATE INDEX
enables you to add
indexes to existing tables.
CREATE INDEX
is mapped to an
ALTER TABLE
statement to create
indexes. See Section 13.1.9, “ALTER TABLE Statement”.
CREATE INDEX
cannot be used to
create a PRIMARY KEY
; use
ALTER TABLE
instead. For more
information about indexes, see Section 8.3.1, “How MySQL Uses Indexes”.
InnoDB
supports secondary indexes on
virtual columns. For more information, see
Section 13.1.20.9, “Secondary Indexes and Generated Columns”.
When the innodb_stats_persistent
setting is enabled, run the ANALYZE
TABLE
statement for an
InnoDB
table after creating an index
on that table.
Beginning with MySQL 8.0.17, the expr
for a key_part
specification can take
the form (CAST
to create a
multi-valued index on a json_expression
AS type
ARRAY)JSON
column. See Multi-Valued Indexes.
An index specification of the form
(
creates an
index with multiple key parts. Index key values are formed by
concatenating the values of the given key parts. For example
key_part1
,
key_part2
, ...)(col1, col2, col3)
specifies a multiple-column
index with index keys consisting of values from
col1
, col2
, and
col3
.
A key_part
specification can end with
ASC
or DESC
to specify
whether index values are stored in ascending or descending order.
The default is ascending if no order specifier is given.
ASC
and DESC
are not
permitted for HASH
indexes.
ASC
and DESC
are also not
supported for multi-valued indexes. As of MySQL 8.0.12,
ASC
and DESC
are not
permitted for SPATIAL
indexes.
The following sections describe different aspects of the
CREATE INDEX
statement:
For string columns, indexes can be created that use only the
leading part of column values, using
syntax to specify an index prefix length:
col_name
(length
)
Prefixes can be specified for
CHAR
,VARCHAR
,BINARY
, andVARBINARY
key parts.Prefixes must be specified for
BLOB
andTEXT
key parts. Additionally,BLOB
andTEXT
columns can be indexed only forInnoDB
,MyISAM
, andBLACKHOLE
tables.Prefix limits are measured in bytes. However, prefix lengths for index specifications in
CREATE TABLE
,ALTER TABLE
, andCREATE INDEX
statements are interpreted as number of characters for nonbinary string types (CHAR
,VARCHAR
,TEXT
) and number of bytes for binary string types (BINARY
,VARBINARY
,BLOB
). Take this into account when specifying a prefix length for a nonbinary string column that uses a multibyte character set.Prefix support and lengths of prefixes (where supported) are storage engine dependent. For example, a prefix can be up to 767 bytes long for
InnoDB
tables that use theREDUNDANT
orCOMPACT
row format. The prefix length limit is 3072 bytes forInnoDB
tables that use theDYNAMIC
orCOMPRESSED
row format. ForMyISAM
tables, the prefix length limit is 1000 bytes. TheNDB
storage engine does not support prefixes (see Section 23.1.7.6, “Unsupported or Missing Features in NDB Cluster”).
If a specified index prefix exceeds the maximum column data type
size, CREATE INDEX
handles the
index as follows:
For a nonunique index, either an error occurs (if strict SQL mode is enabled), or the index length is reduced to lie within the maximum column data type size and a warning is produced (if strict SQL mode is not enabled).
For a unique index, an error occurs regardless of SQL mode because reducing the index length might enable insertion of nonunique entries that do not meet the specified uniqueness requirement.
The statement shown here creates an index using the first 10
characters of the name
column (assuming that
name
has a nonbinary string type):
CREATE INDEX part_of_name ON customer (name(10));
If names in the column usually differ in the first 10
characters, lookups performed using this index should not be
much slower than using 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.
A “normal” index indexes column values or prefixes
of column values. For example, in the following table, the index
entry for a given t1
row includes the full
col1
value and a prefix of the
col2
value consisting of its first 10
characters:
CREATE TABLE t1 ( col1 VARCHAR(10), col2 VARCHAR(20), INDEX (col1, col2(10)) );
MySQL 8.0.13 and higher supports functional key parts that index expression values rather than column or column prefix values. Use of functional key parts enables indexing of values not stored directly in the table. Examples:
CREATE TABLE t1 (col1 INT, col2 INT, INDEX func_index ((ABS(col1)))); CREATE INDEX idx1 ON t1 ((col1 + col2)); CREATE INDEX idx2 ON t1 ((col1 + col2), (col1 - col2), col1); ALTER TABLE t1 ADD INDEX ((col1 * 40) DESC);
An index with multiple key parts can mix nonfunctional and functional key parts.
ASC
and DESC
are supported
for functional key parts.
Functional key parts must adhere to the following rules. An error occurs if a key part definition contains disallowed constructs.
In index definitions, enclose expressions within parentheses to distinguish them from columns or column prefixes. For example, this is permitted; the expressions are enclosed within parentheses:
INDEX ((col1 + col2), (col3 - col4))
This produces an error; the expressions are not enclosed within parentheses:
INDEX (col1 + col2, col3 - col4)
A functional key part cannot consist solely of a column name. For example, this is not permitted:
INDEX ((col1), (col2))
Instead, write the key parts as nonfunctional key parts, without parentheses:
INDEX (col1, col2)
A functional key part expression cannot refer to column prefixes. For a workaround, see the discussion of
SUBSTRING()
andCAST()
later in this section.Functional key parts are not permitted in foreign key specifications.
For CREATE
TABLE ... LIKE
, the destination table preserves
functional key parts from the original table.
Functional indexes are implemented as hidden virtual generated columns, which has these implications:
Each functional key part counts against the limit on total number of table columns; see Section 8.4.7, “Limits on Table Column Count and Row Size”.
Functional key parts inherit all restrictions that apply to generated columns. Examples:
Only functions permitted for generated columns are permitted for functional key parts.
Subqueries, parameters, variables, stored functions, and user-defined functions are not permitted.
For more information about applicable restrictions, see Section 13.1.20.8, “CREATE TABLE and Generated Columns”, and Section 13.1.9.2, “ALTER TABLE and Generated Columns”.
The virtual generated column itself requires no storage. The index itself takes up storage space as any other index.
UNIQUE
is supported for indexes that include
functional key parts. However, primary keys cannot include
functional key parts. A primary key requires the generated
column to be stored, but functional key parts are implemented as
virtual generated columns, not stored generated columns.
SPATIAL
and FULLTEXT
indexes cannot have functional key parts.
If a table contains no primary key, InnoDB
automatically promotes the first UNIQUE NOT
NULL
index to the primary key. This is not supported
for UNIQUE NOT NULL
indexes that have
functional key parts.
Nonfunctional indexes raise a warning if there are duplicate indexes. Indexes that contain functional key parts do not have this feature.
To remove a column that is referenced by a functional key part, the index must be removed first. Otherwise, an error occurs.
Although nonfunctional key parts support a prefix length
specification, this is not possible for functional key parts.
The solution is to use
SUBSTRING()
(or
CAST()
, as described later in
this section). For a functional key part containing the
SUBSTRING()
function to be used
in a query, the WHERE
clause must contain
SUBSTRING()
with the same
arguments. In the following example, only the second
SELECT
is able to use the index
because that is the only query in which the arguments to
SUBSTRING()
match the index
specification:
CREATE TABLE tbl ( col1 LONGTEXT, INDEX idx1 ((SUBSTRING(col1, 1, 10))) ); SELECT * FROM tbl WHERE SUBSTRING(col1, 1, 9) = '123456789'; SELECT * FROM tbl WHERE SUBSTRING(col1, 1, 10) = '1234567890';
Functional key parts enable indexing of values that cannot be
indexed otherwise, such as JSON
values. However, this must be done correctly to achieve the
desired effect. For example, this syntax does not work:
CREATE TABLE employees ( data JSON, INDEX ((data->>'$.name')) );
The syntax fails because:
The
->>
operator translates intoJSON_UNQUOTE(JSON_EXTRACT(...))
.JSON_UNQUOTE()
returns a value with a data type ofLONGTEXT
, and the hidden generated column thus is assigned the same data type.MySQL cannot index
LONGTEXT
columns specified without a prefix length on the key part, and prefix lengths are not permitted in functional key parts.
To index the JSON
column, you could try using
the CAST()
function as follows:
CREATE TABLE employees ( data JSON, INDEX ((CAST(data->>'$.name' AS CHAR(30)))) );
The hidden generated column is assigned the
VARCHAR(30)
data type, which can
be indexed. But this approach produces a new issue when trying
to use the index:
CAST()
returns a string with the collationutf8mb4_0900_ai_ci
(the server default collation).JSON_UNQUOTE()
returns a string with the collationutf8mb4_bin
(hard coded).
As a result, there is a collation mismatch between the indexed
expression in the preceding table definition and the
WHERE
clause expression in the following
query:
SELECT * FROM employees WHERE data->>'$.name' = 'James';
The index is not used because the expressions in the query and
the index differ. To support this kind of scenario for
functional key parts, the optimizer automatically strips
CAST()
when looking for an index
to use, but only if the collation of the
indexed expression matches that of the query expression. For an
index with a functional key part to be used, either of the
following two solutions work (although they differ somewhat in
effect):
Solution 1. Assign the indexed expression the same collation as
JSON_UNQUOTE()
:CREATE TABLE employees ( data JSON, INDEX idx ((CAST(data->>"$.name" AS CHAR(30)) COLLATE utf8mb4_bin)) ); INSERT INTO employees VALUES ('{ "name": "james", "salary": 9000 }'), ('{ "name": "James", "salary": 10000 }'), ('{ "name": "Mary", "salary": 12000 }'), ('{ "name": "Peter", "salary": 8000 }'); SELECT * FROM employees WHERE data->>'$.name' = 'James';
The
->>
operator is the same asJSON_UNQUOTE(JSON_EXTRACT(...))
, andJSON_UNQUOTE()
returns a string with collationutf8mb4_bin
. The comparison is thus case-sensitive, and only one row matches:+------------------------------------+ | data | +------------------------------------+ | {"name": "James", "salary": 10000} | +------------------------------------+
Solution 2. Specify the full expression in the query:
CREATE TABLE employees ( data JSON, INDEX idx ((CAST(data->>"$.name" AS CHAR(30)))) ); INSERT INTO employees VALUES ('{ "name": "james", "salary": 9000 }'), ('{ "name": "James", "salary": 10000 }'), ('{ "name": "Mary", "salary": 12000 }'), ('{ "name": "Peter", "salary": 8000 }'); SELECT * FROM employees WHERE CAST(data->>'$.name' AS CHAR(30)) = 'James';
CAST()
returns a string with collationutf8mb4_0900_ai_ci
, so the comparison case-insensitive and two rows match:+------------------------------------+ | data | +------------------------------------+ | {"name": "james", "salary": 9000} | | {"name": "James", "salary": 10000} | +------------------------------------+
Be aware that although the optimizer supports automatically
stripping CAST()
with indexed
generated columns, the following approach does not work because
it produces a different result with and without an index
(Bug#27337092):
mysql>CREATE TABLE employees (
data JSON,
generated_col VARCHAR(30) AS (CAST(data->>'$.name' AS CHAR(30)))
);
Query OK, 0 rows affected, 1 warning (0.03 sec) mysql>INSERT INTO employees (data)
VALUES ('{"name": "james"}'), ('{"name": "James"}');
Query OK, 2 rows affected, 1 warning (0.01 sec) Records: 2 Duplicates: 0 Warnings: 1 mysql>SELECT * FROM employees WHERE data->>'$.name' = 'James';
+-------------------+---------------+ | data | generated_col | +-------------------+---------------+ | {"name": "James"} | James | +-------------------+---------------+ 1 row in set (0.00 sec) mysql>ALTER TABLE employees ADD INDEX idx (generated_col);
Query OK, 0 rows affected, 1 warning (0.03 sec) Records: 0 Duplicates: 0 Warnings: 1 mysql>SELECT * FROM employees WHERE data->>'$.name' = 'James';
+-------------------+---------------+ | data | generated_col | +-------------------+---------------+ | {"name": "james"} | james | | {"name": "James"} | James | +-------------------+---------------+ 2 rows in set (0.01 sec)
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. If you specify a prefix value for a column in a
UNIQUE
index, the column values must be
unique within the prefix length. A UNIQUE
index permits multiple NULL
values for
columns that can contain NULL
.
If a table has a PRIMARY KEY
or
UNIQUE NOT NULL
index that consists of a
single column that has an integer type, you can use
_rowid
to refer to the indexed column in
SELECT
statements, as follows:
_rowid
refers to thePRIMARY KEY
column if there is aPRIMARY KEY
consisting of a single integer column. If there is aPRIMARY KEY
but it does not consist of a single integer column,_rowid
cannot be used.Otherwise,
_rowid
refers to the column in the firstUNIQUE NOT NULL
index if that index consists of a single integer column. If the firstUNIQUE NOT NULL
index does not consist of a single integer column,_rowid
cannot be used.
FULLTEXT
indexes are supported only for
InnoDB
and
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 12.10, “Full-Text Search Functions”, for details of operation.
As of MySQL 8.0.17, InnoDB
supports
multi-valued indexes. A multi-valued index is a secondary index
defined on a column that stores an array of values. A
“normal” index has one index record for each data
record (1:1). A multi-valued index can have multiple index
records for a single data record (N:1). Multi-valued indexes are
intended for indexing JSON
arrays. For
example, a multi-valued index defined on the array of zip codes
in the following JSON document creates an index record for each
zip code, with each index record referencing the same data
record.
{ "user":"Bob", "user_id":31, "zipcode":[94477,94536] }
Creating multi-valued Indexes
You can create a multi-valued index in a
CREATE TABLE
,
ALTER TABLE
, or
CREATE INDEX
statement. This
requires using CAST(... AS ...
ARRAY)
in the index definition, which casts same-typed
scalar values in a JSON
array to an SQL data
type array. A virtual column is then generated transparently
with the values in the SQL data type array; finally, a
functional index (also referred to as a virtual index) is
created on the virtual column. It is the functional index
defined on the virtual column of values from the SQL data type
array that forms the multi-valued index.
The examples in the following list show the three different ways
in which a multi-valued index zips
can be
created on an array $.zipcode
on a
JSON
column custinfo
in a
table named customers
. In each case, the JSON
array is cast to an SQL data type array of
UNSIGNED
integer values.
CREATE TABLE
only:CREATE TABLE customers ( id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY, modified DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, custinfo JSON, INDEX zips( (CAST(custinfo->'$.zip' AS UNSIGNED ARRAY)) ) );
CREATE TABLE
plusALTER TABLE
:CREATE TABLE customers ( id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY, modified DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, custinfo JSON ); ALTER TABLE customers ADD INDEX zips( (CAST(custinfo->'$.zip' AS UNSIGNED ARRAY)) );
CREATE TABLE
plusCREATE INDEX
:CREATE TABLE customers ( id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY, modified DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, custinfo JSON ); CREATE INDEX zips ON customers ( (CAST(custinfo->'$.zip' AS UNSIGNED ARRAY)) );
A multi-valued index can also be defined as part of a composite
index. This example shows a composite index that includes two
single-valued parts (for the id
and
modified
columns), and one multi-valued part
(for the custinfo
column):
CREATE TABLE customers ( id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY, modified DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, custinfo JSON ); ALTER TABLE customers ADD INDEX comp(id, modified, (CAST(custinfo->'$.zipcode' AS UNSIGNED ARRAY)) );
Only one multi-valued key part can be used in a composite index.
The multi-valued key part may be used in any order relative to
the other parts of the key. In other words, the ALTER
TABLE
statement just shown could have used
comp(id, (CAST(custinfo->'$.zipcode' AS UNSIGNED
ARRAY), modified))
(or any other ordering) and still
have been valid.
Using multi-valued Indexes
The optimizer uses a multi-valued index to fetch records when
the following functions are specified in a
WHERE
clause:
We can demonstrate this by creating and populating the
customers
table using the following
CREATE TABLE
and INSERT
statements:
mysql>CREATE TABLE customers (
->id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
->modified DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
->custinfo JSON
->);
Query OK, 0 rows affected (0.51 sec) mysql>INSERT INTO customers VALUES
->(NULL, NOW(), '{"user":"Jack","user_id":37,"zipcode":[94582,94536]}'),
->(NULL, NOW(), '{"user":"Jill","user_id":22,"zipcode":[94568,94507,94582]}'),
->(NULL, NOW(), '{"user":"Bob","user_id":31,"zipcode":[94477,94507]}'),
->(NULL, NOW(), '{"user":"Mary","user_id":72,"zipcode":[94536]}'),
->(NULL, NOW(), '{"user":"Ted","user_id":56,"zipcode":[94507,94582]}');
Query OK, 5 rows affected (0.07 sec) Records: 5 Duplicates: 0 Warnings: 0
First we execute three queries on the
customers
table, one each using
MEMBER OF()
,
JSON_CONTAINS()
, and
JSON_OVERLAPS()
, with the result from each
query shown here:
mysql>SELECT * FROM customers
->WHERE 94507 MEMBER OF(custinfo->'$.zipcode');
+----+---------------------+-------------------------------------------------------------------+ | id | modified | custinfo | +----+---------------------+-------------------------------------------------------------------+ | 2 | 2019-06-29 22:23:12 | {"user": "Jill", "user_id": 22, "zipcode": [94568, 94507, 94582]} | | 3 | 2019-06-29 22:23:12 | {"user": "Bob", "user_id": 31, "zipcode": [94477, 94507]} | | 5 | 2019-06-29 22:23:12 | {"user": "Ted", "user_id": 56, "zipcode": [94507, 94582]} | +----+---------------------+-------------------------------------------------------------------+ 3 rows in set (0.00 sec) mysql>SELECT * FROM customers
->WHERE JSON_CONTAINS(custinfo->'$.zipcode', CAST('[94507,94582]' AS JSON));
+----+---------------------+-------------------------------------------------------------------+ | id | modified | custinfo | +----+---------------------+-------------------------------------------------------------------+ | 2 | 2019-06-29 22:23:12 | {"user": "Jill", "user_id": 22, "zipcode": [94568, 94507, 94582]} | | 5 | 2019-06-29 22:23:12 | {"user": "Ted", "user_id": 56, "zipcode": [94507, 94582]} | +----+---------------------+-------------------------------------------------------------------+ 2 rows in set (0.00 sec) mysql>SELECT * FROM customers
->WHERE JSON_OVERLAPS(custinfo->'$.zipcode', CAST('[94507,94582]' AS JSON));
+----+---------------------+-------------------------------------------------------------------+ | id | modified | custinfo | +----+---------------------+-------------------------------------------------------------------+ | 1 | 2019-06-29 22:23:12 | {"user": "Jack", "user_id": 37, "zipcode": [94582, 94536]} | | 2 | 2019-06-29 22:23:12 | {"user": "Jill", "user_id": 22, "zipcode": [94568, 94507, 94582]} | | 3 | 2019-06-29 22:23:12 | {"user": "Bob", "user_id": 31, "zipcode": [94477, 94507]} | | 5 | 2019-06-29 22:23:12 | {"user": "Ted", "user_id": 56, "zipcode": [94507, 94582]} | +----+---------------------+-------------------------------------------------------------------+ 4 rows in set (0.00 sec)
Next, we run EXPLAIN
on each of
the previous three queries:
mysql>EXPLAIN SELECT * FROM customers
->WHERE 94507 MEMBER OF(custinfo->'$.zipcode');
+----+-------------+-----------+------------+------+---------------+------+---------+------+------+----------+-------------+ | id | select_type | table | partitions | type | possible_keys | key | key_len | ref | rows | filtered | Extra | +----+-------------+-----------+------------+------+---------------+------+---------+------+------+----------+-------------+ | 1 | SIMPLE | customers | NULL | ALL | NULL | NULL | NULL | NULL | 5 | 100.00 | Using where | +----+-------------+-----------+------------+------+---------------+------+---------+------+------+----------+-------------+ 1 row in set, 1 warning (0.00 sec) mysql>EXPLAIN SELECT * FROM customers
->WHERE JSON_CONTAINS(custinfo->'$.zipcode', CAST('[94507,94582]' AS JSON));
+----+-------------+-----------+------------+------+---------------+------+---------+------+------+----------+-------------+ | id | select_type | table | partitions | type | possible_keys | key | key_len | ref | rows | filtered | Extra | +----+-------------+-----------+------------+------+---------------+------+---------+------+------+----------+-------------+ | 1 | SIMPLE | customers | NULL | ALL | NULL | NULL | NULL | NULL | 5 | 100.00 | Using where | +----+-------------+-----------+------------+------+---------------+------+---------+------+------+----------+-------------+ 1 row in set, 1 warning (0.00 sec) mysql>EXPLAIN SELECT * FROM customers
->WHERE JSON_OVERLAPS(custinfo->'$.zipcode', CAST('[94507,94582]' AS JSON));
+----+-------------+-----------+------------+------+---------------+------+---------+------+------+----------+-------------+ | id | select_type | table | partitions | type | possible_keys | key | key_len | ref | rows | filtered | Extra | +----+-------------+-----------+------------+------+---------------+------+---------+------+------+----------+-------------+ | 1 | SIMPLE | customers | NULL | ALL | NULL | NULL | NULL | NULL | 5 | 100.00 | Using where | +----+-------------+-----------+------------+------+---------------+------+---------+------+------+----------+-------------+ 1 row in set, 1 warning (0.01 sec)
None of the three queries just shown are able to use any keys.
To solve this problem, we can add a multi-valued index on the
zipcode
array in the JSON
column (custinfo
), like this:
mysql>ALTER TABLE customers
->ADD INDEX zips( (CAST(custinfo->'$.zipcode' AS UNSIGNED ARRAY)) );
Query OK, 0 rows affected (0.47 sec) Records: 0 Duplicates: 0 Warnings: 0
When we run the previous EXPLAIN
statements
again, we can now observe that the queries can (and do) use the
index zips
that was just created:
mysql>EXPLAIN SELECT * FROM customers
->WHERE 94507 MEMBER OF(custinfo->'$.zipcode');
+----+-------------+-----------+------------+------+---------------+------+---------+-------+------+----------+-------------+ | id | select_type | table | partitions | type | possible_keys | key | key_len | ref | rows | filtered | Extra | +----+-------------+-----------+------------+------+---------------+------+---------+-------+------+----------+-------------+ | 1 | SIMPLE | customers | NULL | ref | zips | zips | 9 | const | 1 | 100.00 | Using where | +----+-------------+-----------+------------+------+---------------+------+---------+-------+------+----------+-------------+ 1 row in set, 1 warning (0.00 sec) mysql>EXPLAIN SELECT * FROM customers
->WHERE JSON_CONTAINS(custinfo->'$.zipcode', CAST('[94507,94582]' AS JSON));
+----+-------------+-----------+------------+-------+---------------+------+---------+------+------+----------+-------------+ | id | select_type | table | partitions | type | possible_keys | key | key_len | ref | rows | filtered | Extra | +----+-------------+-----------+------------+-------+---------------+------+---------+------+------+----------+-------------+ | 1 | SIMPLE | customers | NULL | range | zips | zips | 9 | NULL | 6 | 100.00 | Using where | +----+-------------+-----------+------------+-------+---------------+------+---------+------+------+----------+-------------+ 1 row in set, 1 warning (0.00 sec) mysql>EXPLAIN SELECT * FROM customers
->WHERE JSON_OVERLAPS(custinfo->'$.zipcode', CAST('[94507,94582]' AS JSON));
+----+-------------+-----------+------------+-------+---------------+------+---------+------+------+----------+-------------+ | id | select_type | table | partitions | type | possible_keys | key | key_len | ref | rows | filtered | Extra | +----+-------------+-----------+------------+-------+---------------+------+---------+------+------+----------+-------------+ | 1 | SIMPLE | customers | NULL | range | zips | zips | 9 | NULL | 6 | 100.00 | Using where | +----+-------------+-----------+------------+-------+---------------+------+---------+------+------+----------+-------------+ 1 row in set, 1 warning (0.01 sec)
A multi-valued index can be defined as a unique key. If defined as a unique key, attempting to insert a value already present in the multi-valued index returns a duplicate key error. If duplicate values are already present, attempting to add a unique multi-valued index fails, as shown here:
mysql>ALTER TABLE customers DROP INDEX zips;
Query OK, 0 rows affected (0.55 sec) Records: 0 Duplicates: 0 Warnings: 0 mysql>ALTER TABLE customers
->ADD UNIQUE INDEX zips((CAST(custinfo->'$.zipcode' AS UNSIGNED ARRAY)));
ERROR 1062 (23000): Duplicate entry '[94507, ' for key 'customers.zips' mysql>ALTER TABLE customers
->ADD INDEX zips((CAST(custinfo->'$.zipcode' AS UNSIGNED ARRAY)));
Query OK, 0 rows affected (0.36 sec) Records: 0 Duplicates: 0 Warnings: 0
Characteristics of Multi-Valued Indexes
Multi-valued indexes have the additional characteristics listed here:
DML operations that affect multi-valued indexes are handled in the same way as DML operations that affect a normal index, with the only difference being that there may be more than one insert or update for a single clustered index record.
Nullability and multi-valued indexes:
If multi-valued key part has an empty array, no entries are added to the index, and the data record is not accessible by an index scan.
If multi-valued key part generation returns a
NULL
value, a single entry containingNULL
is added to the multi-valued index. If the key part is defined asNOT NULL
, an error is reported.If the typed array column is set to
NULL
, the storage engine stores single record containingNULL
that points to the data record.JSON
null values are not permitted in indexed arrays. If any returned value isNULL
, it is treated as a JSON null and an Invalid JSON value error is reported.
Because multi-valued indexes are virtual indexes on virtual columns, they must adhere to the same rules as secondary indexes on virtual generated columns.
Index records are not added for empty arrays.
Limitations and Restrictions on Multi-valued Indexes
Multi-valued indexes are subject to the limitations and restrictions listed here:
Only one multi-valued key part is permitted per multi-valued index. However, the
CAST(... AS ... ARRAY)
expression can refer to multiple arrays within aJSON
document, as shown here:CAST(data->'$.arr[*][*]' AS UNSIGNED ARRAY)
In this case, all values matching the JSON expression are stored in the index as a single flat array.
An index with a multi-valued key part does not support ordering and therefore cannot be used as a primary key. For the same reason, a multi-valued index cannot be defined using the
ASC
orDESC
keyword.A multi-valued index cannot be a covering index.
The maximum number of values per record for a multi-valued index is determined by the amount of data than can be stored on a single undo log page, which is 65221 bytes (64K minus 315 bytes for overhead), which means that the maximum total length of key values is also 65221 bytes. The maximum number of keys depends on various factors, which prevents defining a specific limit. Tests have shown a multi-valued index to permit as many as 1604 integer keys per record, for example. When the limit is reached, an error similar to the following is reported: ERROR 3905 (HY000): Exceeded max number of values per record for multi-valued index 'idx' by 1 value(s).
The only type of expression that is permitted in a multi-valued key part is a
JSON
expression. The expression need not reference an existing element in a JSON document inserted into the indexed column, but must itself be syntactically valid.Because index records for the same clustered index record are dispersed throughout a multi-valued index, a multi-valued index does not support range scans or index-only scans.
Multi-valued indexes are not permitted in foreign key specifications.
Index prefixes cannot be defined for multi-valued indexes.
Multi-valued indexes cannot be defined on data cast as
BINARY
(see the description of theCAST()
function).Online creation of a multi-value index is not supported, which means the operation uses
ALGORITHM=COPY
. See Performance and Space Requirements.Character sets and collations other than the following two combinations of character set and collation are not supported for multi-valued indexes:
The
binary
character set with the defaultbinary
collationThe
utf8mb4
character set with the defaultutf8mb4_0900_as_cs
collation.
As with other indexes on columns of
InnoDB
tables, a multi-valued index cannot be created withUSING HASH
; attempting to do so results in a warning: This storage engine does not support the HASH index algorithm, storage engine default was used instead. (USING BTREE
is supported as usual.)
The MyISAM
,
InnoDB
,
NDB
, and
ARCHIVE
storage engines support
spatial columns such as POINT
and
GEOMETRY
.
(Section 11.4, “Spatial Data Types”, describes the spatial data
types.) However, support for spatial column indexing varies
among engines. Spatial and nonspatial indexes on spatial columns
are available according to the following rules.
Spatial indexes on spatial columns have these characteristics:
Available only for
InnoDB
andMyISAM
tables. SpecifyingSPATIAL INDEX
for other storage engines results in an error.As of MySQL 8.0.12, an index on a spatial column must be a
SPATIAL
index. TheSPATIAL
keyword is thus optional but implicit for creating an index on a spatial column.Available for single spatial columns only. A spatial index cannot be created over multiple spatial columns.
Indexed columns must be
NOT NULL
.Column prefix lengths are prohibited. The full width of each column is indexed.
Not permitted for a primary key or unique index.
Nonspatial indexes on spatial columns (created with
INDEX
, UNIQUE
, or
PRIMARY KEY
) have these characteristics:
Permitted for any storage engine that supports spatial columns except
ARCHIVE
.Columns can be
NULL
unless the index is a primary key.The index type for a non-
SPATIAL
index depends on the storage engine. Currently, B-tree is used.Permitted for a column that can have
NULL
values only forInnoDB
,MyISAM
, andMEMORY
tables.
Following the key part list, index options can be given. An
index_option
value can be any of the
following:
KEY_BLOCK_SIZE [=]
value
For
MyISAM
tables,KEY_BLOCK_SIZE
optionally specifies the size in bytes to use for index key blocks. The value is treated as a hint; a different size could be used if necessary. AKEY_BLOCK_SIZE
value specified for an individual index definition overrides a table-levelKEY_BLOCK_SIZE
value.KEY_BLOCK_SIZE
is not supported at the index level forInnoDB
tables. See Section 13.1.20, “CREATE TABLE Statement”.index_type
Some storage engines permit you to specify an index type when creating an index. For example:
CREATE TABLE lookup (id INT) ENGINE = MEMORY; CREATE INDEX id_index ON lookup (id) USING BTREE;
Table 13.1, “Index Types Per Storage Engine” shows the permissible index type values supported by different storage engines. Where multiple index types are listed, the first one is the default when no index type specifier is given. Storage engines not listed in the table do not support an
index_type
clause in index definitions.The
index_type
clause cannot be used forFULLTEXT INDEX
or (prior to MySQL 8.0.12)SPATIAL INDEX
specifications. Full-text index implementation is storage engine dependent. Spatial indexes are implemented as R-tree indexes.If you specify an index type that is not valid for a given storage engine, but another index type is available that the engine can use without affecting query results, the engine uses the available type. The parser recognizes
RTREE
as a type name. As of MySQL 8.0.12, this is permitted only forSPATIAL
indexes. Prior to 8.0.12,RTREE
cannot be specified for any storage engine.BTREE
indexes are implemented by theNDB
storage engine as T-tree indexes.NoteFor indexes on
NDB
table columns, theUSING
option can be specified only for a unique index or primary key.USING HASH
prevents the creation of an ordered index; otherwise, creating a unique index or primary key on anNDB
table automatically results in the creation of both an ordered index and a hash index, each of which indexes the same set of columns.For unique indexes that include one or more
NULL
columns of anNDB
table, the hash index can be used only to look up literal values, which means thatIS [NOT] NULL
conditions require a full scan of the table. One workaround is to make sure that a unique index using one or moreNULL
columns on such a table is always created in such a way that it includes the ordered index; that is, avoid employingUSING HASH
when creating the index.If you specify an index type that is not valid for a given storage engine, but another index type is available that the engine can use without affecting query results, the engine uses the available type. The parser recognizes
RTREE
as a type name, but currently this cannot be specified for any storage engine.NoteUse of the
index_type
option before theON
clause is deprecated; expect support for use of the option in this position to be removed in a future MySQL release. If antbl_name
index_type
option is given in both the earlier and later positions, the final option applies.TYPE
is recognized as a synonym fortype_name
USING
. However,type_name
USING
is the preferred form.The following tables show index characteristics for the storage engines that support the
index_type
option.Table 13.2 InnoDB Storage Engine Index Characteristics
Index Class Index Type Stores NULL VALUES Permits Multiple NULL Values IS NULL Scan Type IS NOT NULL Scan Type Primary key BTREE
No No N/A N/A Unique BTREE
Yes Yes Index Index Key BTREE
Yes Yes Index Index FULLTEXT
N/A Yes Yes Table Table SPATIAL
N/A No No N/A N/A
Table 13.3 MyISAM Storage Engine Index Characteristics
Index Class Index Type Stores NULL VALUES Permits Multiple NULL Values IS NULL Scan Type IS NOT NULL Scan Type Primary key BTREE
No No N/A N/A Unique BTREE
Yes Yes Index Index Key BTREE
Yes Yes Index Index FULLTEXT
N/A Yes Yes Table Table SPATIAL
N/A No No N/A N/A
Table 13.4 MEMORY Storage Engine Index Characteristics
Index Class Index Type Stores NULL VALUES Permits Multiple NULL Values IS NULL Scan Type IS NOT NULL Scan Type Primary key BTREE
No No N/A N/A Unique BTREE
Yes Yes Index Index Key BTREE
Yes Yes Index Index Primary key HASH
No No N/A N/A Unique HASH
Yes Yes Index Index Key HASH
Yes Yes Index Index
Table 13.5 NDB Storage Engine Index Characteristics
Index Class Index Type Stores NULL VALUES Permits Multiple NULL Values IS NULL Scan Type IS NOT NULL Scan Type Primary key BTREE
No No Index Index Unique BTREE
Yes Yes Index Index Key BTREE
Yes Yes Index Index Primary key HASH
No No Table (see note 1) Table (see note 1) Unique HASH
Yes Yes Table (see note 1) Table (see note 1) Key HASH
Yes Yes Table (see note 1) Table (see note 1) Table note:
1.
USING HASH
prevents creation of an implicit ordered index.WITH PARSER
parser_name
This option can be used only with
FULLTEXT
indexes. It associates a parser plugin with the index if full-text indexing and searching operations need special handling.InnoDB
andMyISAM
support full-text parser plugins. If you have aMyISAM
table with an associated full-text parser plugin, you can convert the table toInnoDB
usingALTER TABLE
. See Full-Text Parser Plugins and Writing Full-Text Parser Plugins for more information.COMMENT '
string
'Index definitions can include an optional comment of up to 1024 characters.
The
MERGE_THRESHOLD
for index pages can be configured for individual indexes using theindex_option
COMMENT
clause of theCREATE INDEX
statement. For example:CREATE TABLE t1 (id INT); CREATE INDEX id_index ON t1 (id) COMMENT 'MERGE_THRESHOLD=40';
If the page-full percentage for an index page falls below the
MERGE_THRESHOLD
value when a row is deleted or when a row is shortened by an update operation,InnoDB
attempts to merge the index page with a neighboring index page. The defaultMERGE_THRESHOLD
value is 50, which is the previously hardcoded value.MERGE_THRESHOLD
can also be defined at the index level and table level usingCREATE TABLE
andALTER TABLE
statements. For more information, see Section 15.8.11, “Configuring the Merge Threshold for Index Pages”.VISIBLE
,INVISIBLE
Specify index visibility. Indexes are visible by default. An invisible index is not used by the optimizer. Specification of index visibility applies to indexes other than primary keys (either explicit or implicit). For more information, see Section 8.3.12, “Invisible Indexes”.
ENGINE_ATTRIBUTE
andSECONDARY_ENGINE_ATTRIBUTE
options (available as of MySQL 8.0.21) are used to specify index attributes for primary and secondary storage engines. The options are reserved for future use.Permitted values are a string literal containing a valid
JSON
document or an empty string (''). InvalidJSON
is rejected.CREATE INDEX i1 ON t1 (c1) ENGINE_ATTRIBUTE='{"
key
":"value
"}';ENGINE_ATTRIBUTE
andSECONDARY_ENGINE_ATTRIBUTE
values can be repeated without error. In this case, the last specified value is used.ENGINE_ATTRIBUTE
andSECONDARY_ENGINE_ATTRIBUTE
values are not checked by the server, nor are they cleared when the table's storage engine is changed.
ALGORITHM
and LOCK
clauses
may be given to influence the table copying method and level of
concurrency for reading and writing the table while its indexes
are being modified. They have the same meaning as for the
ALTER TABLE
statement. For more
information, see Section 13.1.9, “ALTER TABLE Statement”
NDB Cluster supports online operations using the same
ALGORITHM=INPLACE
syntax used with the
standard MySQL Server. See
Section 23.5.11, “Online Operations with ALTER TABLE in NDB Cluster”, for more
information.
CREATE LOGFILE GROUPlogfile_group
ADD UNDOFILE 'undo_file
' [INITIAL_SIZE [=]initial_size
] [UNDO_BUFFER_SIZE [=]undo_buffer_size
] [REDO_BUFFER_SIZE [=]redo_buffer_size
] [NODEGROUP [=]nodegroup_id
] [WAIT] [COMMENT [=] 'string
'] ENGINE [=]engine_name
This statement creates a new log file group named
logfile_group
having a single
UNDO
file named
'undo_file
'. A
CREATE LOGFILE GROUP
statement has
one and only one ADD UNDOFILE
clause. For rules
covering the naming of log file groups, see
Section 9.2, “Schema Object Names”.
All NDB Cluster Disk Data objects share the same namespace. This means that each Disk Data object must be uniquely named (and not merely each Disk Data object of a given type). For example, you cannot have a tablespace and a log file group with the same name, or a tablespace and a data file with the same name.
There can be only one log file group per NDB Cluster instance at any given time.
The optional INITIAL_SIZE
parameter sets the
UNDO
file's initial size; if not specified, it
defaults to 128M
(128 megabytes). The optional
UNDO_BUFFER_SIZE
parameter sets the size used
by the UNDO
buffer for the log file group; The
default value for UNDO_BUFFER_SIZE
is
8M
(eight megabytes); this value cannot exceed
the amount of system memory available. Both of these parameters
are specified in bytes. You may optionally follow either or both
of these with a one-letter abbreviation for an order of magnitude,
similar to those used in my.cnf
. Generally,
this is one of the letters M
(for megabytes)
or G
(for gigabytes).
Memory used for UNDO_BUFFER_SIZE
comes from the
global pool whose size is determined by the value of the
SharedGlobalMemory
data
node configuration parameter. This includes any default value
implied for this option by the setting of the
InitialLogFileGroup
data
node configuration parameter.
The maximum permitted for UNDO_BUFFER_SIZE
is
629145600 (600 MB).
On 32-bit systems, the maximum supported value for
INITIAL_SIZE
is 4294967296 (4 GB). (Bug #29186)
The minimum allowed value for INITIAL_SIZE
is
1048576 (1 MB).
The ENGINE
option determines the storage engine
to be used by this log file group, with
engine_name
being the name of the
storage engine. In MySQL 8.0, this must be
NDB
(or
NDBCLUSTER
). If
ENGINE
is not set, MySQL tries to use the
engine specified by the
default_storage_engine
server
system variable (formerly
storage_engine
). In any case, if
the engine is not specified as NDB
or
NDBCLUSTER
, the CREATE
LOGFILE GROUP
statement appears to succeed but actually
fails to create the log file group, as shown here:
mysql>CREATE LOGFILE GROUP lg1
->ADD UNDOFILE 'undo.dat' INITIAL_SIZE = 10M;
Query OK, 0 rows affected, 1 warning (0.00 sec) mysql>SHOW WARNINGS;
+-------+------+------------------------------------------------------------------------------------------------+ | Level | Code | Message | +-------+------+------------------------------------------------------------------------------------------------+ | Error | 1478 | Table storage engine 'InnoDB' does not support the create option 'TABLESPACE or LOGFILE GROUP' | +-------+------+------------------------------------------------------------------------------------------------+ 1 row in set (0.00 sec) mysql>DROP LOGFILE GROUP lg1 ENGINE = NDB;
ERROR 1529 (HY000): Failed to drop LOGFILE GROUP mysql>CREATE LOGFILE GROUP lg1
->ADD UNDOFILE 'undo.dat' INITIAL_SIZE = 10M
->ENGINE = NDB;
Query OK, 0 rows affected (2.97 sec)
The fact that the CREATE LOGFILE GROUP
statement does not actually return an error when a
non-NDB
storage engine is named, but rather
appears to succeed, is a known issue which we hope to address in a
future release of NDB Cluster.
REDO_BUFFER_SIZE
,
NODEGROUP
, WAIT
, and
COMMENT
are parsed but ignored, and so have no
effect in MySQL 8.0. These options are intended for
future expansion.
When used with ENGINE [=] NDB
, a log file group
and associated UNDO
log file are created on
each Cluster data node. You can verify that the
UNDO
files were created and obtain information
about them by querying the
INFORMATION_SCHEMA.FILES
table. For
example:
mysql>SELECT LOGFILE_GROUP_NAME, LOGFILE_GROUP_NUMBER, EXTRA
->FROM INFORMATION_SCHEMA.FILES
->WHERE FILE_NAME = 'undo_10.dat';
+--------------------+----------------------+----------------+ | LOGFILE_GROUP_NAME | LOGFILE_GROUP_NUMBER | EXTRA | +--------------------+----------------------+----------------+ | lg_3 | 11 | CLUSTER_NODE=3 | | lg_3 | 11 | CLUSTER_NODE=4 | +--------------------+----------------------+----------------+ 2 rows in set (0.06 sec)
CREATE LOGFILE GROUP
is useful only
with Disk Data storage for NDB Cluster. See
Section 23.5.10, “NDB Cluster Disk Data Tables”.
CREATE [DEFINER =user
] PROCEDUREsp_name
([proc_parameter
[,...]]) [characteristic
...]routine_body
CREATE [DEFINER =user
] FUNCTIONsp_name
([func_parameter
[,...]]) RETURNStype
[characteristic
...]routine_body
proc_parameter
: [ IN | OUT | INOUT ]param_name
type
func_parameter
:param_name
type
type
:Any valid MySQL data type
characteristic
: { COMMENT 'string
' | LANGUAGE SQL | [NOT] DETERMINISTIC | { CONTAINS SQL | NO SQL | READS SQL DATA | MODIFIES SQL DATA } | SQL SECURITY { DEFINER | INVOKER } }routine_body
:Valid SQL routine statement
These statements are used to create a stored routine (a stored
procedure or function). That is, the specified routine becomes
known to the server. By default, a stored 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 13.7.4.1, “CREATE FUNCTION Statement for User-Defined Functions”. A UDF can be regarded as an
external stored function. Stored functions share their namespace
with UDFs. See Section 9.2.5, “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 13.2.1, “CALL Statement”). To invoke a stored function, refer to it
in an expression. The function returns a value during expression
evaluation.
CREATE PROCEDURE
and
CREATE FUNCTION
require the
CREATE ROUTINE
privilege. If the
DEFINER
clause is present, the privileges
required depend on the user
value, as
discussed in Section 25.6, “Stored Object Access Control”. If binary
logging is enabled, CREATE FUNCTION
might require the SUPER
privilege,
as discussed in Section 25.7, “Stored Program Binary Logging”.
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 25.2.2, “Stored Routines and MySQL Privileges”.
The DEFINER
and SQL SECURITY
clauses specify the security context to be used when checking
access privileges at routine execution time, as described later in
this section.
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 permissible 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.
Specifying a parameter as IN
,
OUT
, or INOUT
is valid
only for a PROCEDURE
. For a
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 OUT
or INOUT
parameter. If you are calling the
procedure from within a trigger, you can also pass
NEW.
as an
col_name
OUT
or INOUT
parameter.
For information about the effect of unhandled conditions on procedure parameters, see Section 13.6.7.8, “Condition Handling and OUT or INOUT Parameters”.
Routine parameters cannot be referenced in statements prepared within the routine; see Section 25.8, “Restrictions on Stored Programs”.
The following example shows a simple stored procedure that, given
a country code, counts the number of cities for that country that
appear in the city
table of the
world
database. The country code is passed
using an IN
parameter, and the city count is
returned using an OUT
parameter:
mysql>delimiter //
mysql>CREATE PROCEDURE citycount (IN country CHAR(3), OUT cities INT)
BEGIN
SELECT COUNT(*) INTO cities FROM world.city
WHERE CountryCode = country;
END//
Query OK, 0 rows affected (0.01 sec) mysql>delimiter ;
mysql>CALL citycount('JPN', @cities); -- cities in Japan
Query OK, 1 row affected (0.00 sec) mysql>SELECT @cities;
+---------+ | @cities | +---------+ | 248 | +---------+ 1 row in set (0.00 sec) mysql>CALL citycount('FRA', @cities); -- cities in France
Query OK, 1 row affected (0.00 sec) mysql>SELECT @cities;
+---------+ | @cities | +---------+ | 40 | +---------+ 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 enables the
;
delimiter used in the procedure body to be
passed through to the server rather than being interpreted by
mysql itself. See
Section 25.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
statement. If the
value
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. The COLLATE
attribute can
be used if preceded by a CHARACTER SET
specification.
The routine_body
consists of a valid
SQL routine statement. This can be a simple statement such as
SELECT
or
INSERT
, or 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 13.6, “Compound Statement Syntax”. In
practice, stored functions tend to use compound statements, unless
the body consists of a single
RETURN
statement.
MySQL permits routines to contain DDL statements, such as
CREATE
and DROP
. MySQL also
permits 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
permit them.
Statements that return a result set can be used within a stored
procedure but not within a stored function. This prohibition
includes SELECT
statements that do
not have an INTO
clause and other
statements such as var_list
SHOW
,
EXPLAIN
, and
CHECK TABLE
. For statements that
can be determined at function definition time to return a result
set, a Not allowed to return a result set from a
function
error occurs
(ER_SP_NO_RETSET
). For statements
that can be determined only at runtime to return a result set, a
PROCEDURE %s can't return a result set in the given
context
error occurs
(ER_SP_BADSELECT
).
USE
statements within stored
routines are not permitted. When a routine is invoked, an implicit
USE
is
performed (and undone when the routine terminates). The 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.
db_name
For additional information about statements that are not permitted in stored routines, see Section 25.8, “Restrictions on Stored Programs”.
For information about invoking stored procedures from within programs written in a language that has a MySQL interface, see Section 13.2.1, “CALL Statement”.
MySQL stores the sql_mode
system
variable setting in effect when a routine is created or altered,
and always executes the routine with this setting in force,
regardless of the current server SQL mode when the
routine begins executing.
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.
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 LANGUAGE
characteristic indicates the
language in which the routine is written. The server ignores this
characteristic; only SQL routines are supported.
A routine 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
. To declare that a
function is deterministic, you must specify
DETERMINISTIC
explicitly.
Assessment of the nature of a routine is based on the
“honesty” of the creator: MySQL does not check that a
routine declared DETERMINISTIC
is free of
statements that produce nondeterministic results. However,
misdeclaring a routine might affect results or affect performance.
Declaring a nondeterministic routine as
DETERMINISTIC
might lead to unexpected results
by causing the optimizer to make incorrect execution plan choices.
Declaring a deterministic routine as
NONDETERMINISTIC
might diminish performance by
causing available optimizations not to be used.
If binary logging is enabled, the DETERMINISTIC
characteristic affects which routine definitions MySQL accepts.
See Section 25.7, “Stored Program Binary Logging”.
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
source and replica.)
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 is permitted 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 areSET @x = 1
orDO 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
orDELETE
).
The SQL SECURITY
characteristic can be
DEFINER
or INVOKER
to
specify the security context; that is, whether the routine
executes using the privileges of the account named in the routine
DEFINER
clause or the user who invokes it. This
account must have permission to access the database with which the
routine is associated. The default value is
DEFINER
. The user who invokes the routine must
have the EXECUTE
privilege for it,
as must the DEFINER
account if the routine
executes in definer security context.
The 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.
If the DEFINER
clause is present, the
user
value should be a MySQL account
specified as
'
,
user_name
'@'host_name
'CURRENT_USER
, or
CURRENT_USER()
. The permitted
user
values depend on the privileges
you hold, as discussed in
Section 25.6, “Stored Object Access Control”. Also see that section
for additional information about stored routine security.
If the DEFINER
clause is omitted, the default
definer is the user who executes the CREATE
PROCEDURE
or CREATE
FUNCTION
statement. This is the same as specifying
DEFINER = CURRENT_USER
explicitly.
Within the body of a stored routine that is defined with the
SQL SECURITY DEFINER
characteristic, the
CURRENT_USER
function returns the
routine's DEFINER
value. For information about
user auditing within stored routines, see
Section 6.2.22, “SQL-Based Account Activity Auditing”.
Consider the following procedure, which displays a count of the
number of MySQL accounts listed in the
mysql.user
system 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 invoker has the
EXECUTE
privilege for it and
'admin'@'localhost'
has 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 EXECUTE
privilege for it and
the SELECT
privilege for the
mysql.user
table.
The server handles the data type of a routine parameter, local
routine variable created with
DECLARE
, or function return value
as follows:
Assignments are checked for data type mismatches and overflow. Conversion and overflow problems result in warnings, or errors in strict SQL mode.
Only scalar values can be assigned. For example, a statement such as
SET x = (SELECT 1, 2)
is invalid.For character data types, if
CHARACTER SET
is includedd in the declaration, the specified character set and its default collation is used. If theCOLLATE
attribute is also present, that collation is used rather than the default collation.If
CHARACTER SET
andCOLLATE
are not present, the database character set and collation in effect at routine creation time are used. To avoid having the server use the database character set and collation, provide an explicitCHARACTER SET
and aCOLLATE
attribute for character data parameters.If you alter the database default character set or collation, stored routines that are to use the new database defaults must be dropped and recreated.
The database character set and collation are given by the value of the
character_set_database
andcollation_database
system variables. For more information, see Section 10.3.3, “Database Character Set and Collation”.
CREATE SERVERserver_name
FOREIGN DATA WRAPPERwrapper_name
OPTIONS (option
[,option
] ...)option
: { HOSTcharacter-literal
| DATABASEcharacter-literal
| USERcharacter-literal
| PASSWORDcharacter-literal
| SOCKETcharacter-literal
| OWNERcharacter-literal
| PORTnumeric-literal
}
This statement creates the definition of a server for use with the
FEDERATED
storage engine. The CREATE
SERVER
statement creates a new row in the
servers
table in the mysql
database. This statement requires the
SUPER
privilege.
The
should be a unique reference to the server. Server definitions are
global within the scope of the server, it is not possible to
qualify the server definition to a specific database.
server_name
has a
maximum length of 64 characters (names longer than 64 characters
are silently truncated), and is case-insensitive. You may specify
the name as a quoted string.
server_name
The
is
an identifier and may be quoted with single quotation marks.
wrapper_name
For each
you
must specify either a character literal or numeric literal.
Character literals are UTF-8, support a maximum length of 64
characters and default to a blank (empty) string. String literals
are silently truncated to 64 characters. Numeric literals must be
a number between 0 and 9999, default value is 0.
option
The OWNER
option is currently not applied,
and has no effect on the ownership or operation of the server
connection that is created.
The CREATE SERVER
statement creates an entry in
the mysql.servers
table that can later be used
with the CREATE TABLE
statement
when creating a FEDERATED
table. The options
that you specify are used to populate the columns in the
mysql.servers
table. The table columns are
Server_name
, Host
,
Db
, Username
,
Password
, Port
and
Socket
.
For example:
CREATE SERVER s FOREIGN DATA WRAPPER mysql OPTIONS (USER 'Remote', HOST '198.51.100.106', DATABASE 'test');
Be sure to specify all options necessary to establish a connection to the server. The user name, host name, and database name are mandatory. Other options might be required as well, such as password.
The data stored in the table can be used when creating a
connection to a FEDERATED
table:
CREATE TABLE t (s1 INT) ENGINE=FEDERATED CONNECTION='s';
For more information, see Section 16.8, “The FEDERATED Storage Engine”.
CREATE SERVER
causes an implicit commit. See
Section 13.3.3, “Statements That Cause an Implicit Commit”.
CREATE SERVER
is not written to the binary log,
regardless of the logging format that is in use.
CREATE OR REPLACE SPATIAL REFERENCE SYSTEMsrid
srs_attribute
... CREATE SPATIAL REFERENCE SYSTEM [IF NOT EXISTS]srid
srs_attribute
...srs_attribute
: { NAME 'srs_name
' | DEFINITION 'definition
' | ORGANIZATION 'org_name
' IDENTIFIED BYorg_id
| DESCRIPTION 'description
' }srid
,org_id
:32-bit unsigned integer
This statement creates a
spatial reference
system (SRS) definition and stores it in the data
dictionary. It requires the SUPER
privilege. The resulting data dictionary entry can be inspected
using the INFORMATION_SCHEMA
ST_SPATIAL_REFERENCE_SYSTEMS
table.
SRID values must be unique, so if neither OR
REPLACE
nor IF NOT EXISTS
is
specified, an error occurs if an SRS definition with the given
srid
value already exists.
With CREATE OR REPLACE
syntax, any existing SRS
definition with the same SRID value is replaced, unless the SRID
value is used by some column in an existing table. In that case,
an error occurs. For example:
mysql> CREATE OR REPLACE SPATIAL REFERENCE SYSTEM 4326 ...;
ERROR 3716 (SR005): Can't modify SRID 4326. There is at
least one column depending on it.
To identify which column or columns use the SRID, use this query, replacing 4326 with the SRID of the definition you are trying to create:
SELECT * FROM INFORMATION_SCHEMA.ST_GEOMETRY_COLUMNS WHERE SRS_ID=4326;
With CREATE ... IF NOT EXISTS
syntax, any
existing SRS definition with the same SRID value causes the new
definition to be ignored and a warning occurs.
SRID values must be in the range of 32-bit unsigned integers, with these restrictions:
SRID 0 is a valid SRID but cannot be used with
CREATE SPATIAL REFERENCE SYSTEM
.If the value is in a reserved SRID range, a warning occurs. Reserved ranges are [0, 32767] (reserved by EPSG), [60,000,000, 69,999,999] (reserved by EPSG), and [2,000,000,000, 2,147,483,647] (reserved by MySQL). EPSG stands for the European Petroleum Survey Group.
Users should not create SRSs with SRIDs in the reserved ranges. Doing so runs the risk of the SRIDs conflicting with future SRS definitions distributed with MySQL, with the result that the new system-provided SRSs are not installed for MySQL upgrades or that the user-defined SRSs are overwritten.
Attributes for the statement must satisfy these conditions:
Attributes can be given in any order, but no attribute can be given more than once.
The
NAME
andDEFINITION
attributes are mandatory.The
NAME
srs_name
attribute value must be unique. The combination of theORGANIZATION
org_name
andorg_id
attribute values must be unique.The
NAME
srs_name
attribute value andORGANIZATION
org_name
attribute value cannot be empty or begin or end with whitespace.String values in attribute specifications cannot contain control characters, including newline.
The following table shows the maximum lengths for string attribute values.
Table 13.6 CREATE SPATIAL REFERENCE SYSTEM Attribute Lengths
Attribute Maximum Length (characters) NAME
80 DEFINITION
4096 ORGANIZATION
256 DESCRIPTION
2048
Here is an example CREATE SPATIAL REFERENCE
SYSTEM
statement. The DEFINITION
value is reformatted across multiple lines for readability. (For
the statement to be legal, the value actually must be given on a
single line.)
CREATE SPATIAL REFERENCE SYSTEM 4120 NAME 'Greek' ORGANIZATION 'EPSG' IDENTIFIED BY 4120 DEFINITION 'GEOGCS["Greek",DATUM["Greek",SPHEROID["Bessel 1841", 6377397.155,299.1528128,AUTHORITY["EPSG","7004"]], AUTHORITY["EPSG","6120"]],PRIMEM["Greenwich",0, AUTHORITY["EPSG","8901"]],UNIT["degree",0.017453292519943278, AUTHORITY["EPSG","9122"]],AXIS["Lat",NORTH],AXIS["Lon",EAST], AUTHORITY["EPSG","4120"]]';
The grammar for SRS definitions is based on the grammar defined in OpenGIS Implementation Specification: Coordinate Transformation Services, Revision 1.00, OGC 01-009, January 12, 2001, Section 7.2. This specification is available at http://www.opengeospatial.org/standards/ct.
MySQL incorporates these changes to the specification:
Only the
<horz cs>
production rule is implemented (that is, geographic and projected SRSs).There is an optional, nonstandard
<authority>
clause for<parameter>
. This makes it possible to recognize projection parameters by authority instead of name.The specification does not make
AXIS
clauses mandatory inGEOGCS
spatial reference system definitions. However, if there are noAXIS
clauses, MySQL cannot determine whether a definition has axes in latitude-longitude order or longitude-latitude order. MySQL enforces the nonstandard requirement that eachGEOGCS
definition must include twoAXIS
clauses. One must beNORTH
orSOUTH
, and the otherEAST
orWEST
. TheAXIS
clause order determines whether the definition has axes in latitude-longitude order or longitude-latitude order.SRS definitions may not contain newlines.
If an SRS definition specifies an authority code for the projection (which is recommended), an error occurs if the definition is missing mandatory parameters. In this case, the error message indicates what the problem is. The projection methods and mandatory parameters that MySQL supports are shown in Table 13.7, “Supported Spatial Reference System Projection Methods” and Table 13.8, “Spatial Reference System Projection Parameters”.
For additional information about writing SRS definitions for MySQL, see Geographic Spatial Reference Systems in MySQL 8.0 and Projected Spatial Reference Systems in MySQL 8.0
The following table shows the projection methods that MySQL supports. MySQL permits unknown projection methods but cannot check the defintion for mandatory paramters and cannot convert spatial data to or from an unknown projection. For detailed explanations of how each projection works, including formulas, see EPSG Guidance Note 7-2.
Table 13.7 Supported Spatial Reference System Projection Methods
EPSG Code | Projection Name | Mandatory Parameters (EPSG Codes) |
---|---|---|
1024 | Popular Visualisation Pseudo Mercator | 8801, 8802, 8806, 8807 |
1027 | Lambert Azimuthal Equal Area (Spherical) | 8801, 8802, 8806, 8807 |
1028 | Equidistant Cylindrical | 8823, 8802, 8806, 8807 |
1029 | Equidistant Cylindrical (Spherical) | 8823, 8802, 8806, 8807 |
1041 | Krovak (North Orientated) | 8811, 8833, 1036, 8818, 8819, 8806, 8807 |
1042 | Krovak Modified | 8811, 8833, 1036, 8818, 8819, 8806, 8807, 8617, 8618, 1026, 1027, 1028, 1029, 1030, 1031, 1032, 1033, 1034, 1035 |
1043 | Krovak Modified (North Orientated) | 8811, 8833, 1036, 8818, 8819, 8806, 8807, 8617, 8618, 1026, 1027, 1028, 1029, 1030, 1031, 1032, 1033, 1034, 1035 |
1051 | Lambert Conic Conformal (2SP Michigan) | 8821, 8822, 8823, 8824, 8826, 8827, 1038 |
1052 | Colombia Urban | 8801, 8802, 8806, 8807, 1039 |
9801 | Lambert Conic Conformal (1SP) | 8801, 8802, 8805, 8806, 8807 |
9802 | Lambert Conic Conformal (2SP) | 8821, 8822, 8823, 8824, 8826, 8827 |
9803 | Lambert Conic Conformal (2SP Belgium) | 8821, 8822, 8823, 8824, 8826, 8827 |
9804 | Mercator (variant A) | 8801, 8802, 8805, 8806, 8807 |
9805 | Mercator (variant B) | 8823, 8802, 8806, 8807 |
9806 | Cassini-Soldner | 8801, 8802, 8806, 8807 |
9807 | Transverse Mercator | 8801, 8802, 8805, 8806, 8807 |
9808 | Transverse Mercator (South Orientated) | 8801, 8802, 8805, 8806, 8807 |
9809 | Oblique Stereographic | 8801, 8802, 8805, 8806, 8807 |
9810 | Polar Stereographic (variant A) | 8801, 8802, 8805, 8806, 8807 |
9811 | New Zealand Map Grid | 8801, 8802, 8806, 8807 |
9812 | Hotine Oblique Mercator (variant A) | 8811, 8812, 8813, 8814, 8815, 8806, 8807 |
9813 | Laborde Oblique Mercator | 8811, 8812, 8813, 8815, 8806, 8807 |
9815 | Hotine Oblique Mercator (variant B) | 8811, 8812, 8813, 8814, 8815, 8816, 8817 |
9816 | Tunisia Mining Grid | 8821, 8822, 8826, 8827 |
9817 | Lambert Conic Near-Conformal | 8801, 8802, 8805, 8806, 8807 |
9818 | American Polyconic | 8801, 8802, 8806, 8807 |
9819 | Krovak | 8811, 8833, 1036, 8818, 8819, 8806, 8807 |
9820 | Lambert Azimuthal Equal Area | 8801, 8802, 8806, 8807 |
9822 | Albers Equal Area | 8821, 8822, 8823, 8824, 8826, 8827 |
9824 | Transverse Mercator Zoned Grid System | 8801, 8830, 8831, 8805, 8806, 8807 |
9826 | Lambert Conic Conformal (West Orientated) | 8801, 8802, 8805, 8806, 8807 |
9828 | Bonne (South Orientated) | 8801, 8802, 8806, 8807 |
9829 | Polar Stereographic (variant B) | 8832, 8833, 8806, 8807 |
9830 | Polar Stereographic (variant C) | 8832, 8833, 8826, 8827 |
9831 | Guam Projection | 8801, 8802, 8806, 8807 |
9832 | Modified Azimuthal Equidistant | 8801, 8802, 8806, 8807 |
9833 | Hyperbolic Cassini-Soldner | 8801, 8802, 8806, 8807 |
9834 | Lambert Cylindrical Equal Area (Spherical) | 8823, 8802, 8806, 8807 |
9835 | Lambert Cylindrical Equal Area | 8823, 8802, 8806, 8807 |
The following table shows the projection parameters that MySQL recognizes. Recognition occurs primarily by authority code. If there is no authority code, MySQL falls back to case-insensitive string matching on the parameter name. For details about each parameter, look it up by code in the EPSG Online Registry.
Table 13.8 Spatial Reference System Projection Parameters
EPSG Code | Fallback Name (Recognized by MySQL) | EPSG Name |
---|---|---|
1026 | c1 | C1 |
1027 | c2 | C2 |
1028 | c3 | C3 |
1029 | c4 | C4 |
1030 | c5 | C5 |
1031 | c6 | C6 |
1032 | c7 | C7 |
1033 | c8 | C8 |
1034 | c9 | C9 |
1035 | c10 | C10 |
1036 | azimuth | Co-latitude of cone axis |
1038 | ellipsoid_scale_factor | Ellipsoid scaling factor |
1039 | projection_plane_height_at_origin | Projection plane origin height |
8617 | evaluation_point_ordinate_1 | Ordinate 1 of evaluation point |
8618 | evaluation_point_ordinate_2 | Ordinate 2 of evaluation point |
8801 | latitude_of_origin | Latitude of natural origin |
8802 | central_meridian | Longitude of natural origin |
8805 | scale_factor | Scale factor at natural origin |
8806 | false_easting | False easting |
8807 | false_northing | False northing |
8811 | latitude_of_center | Latitude of projection centre |
8812 | longitude_of_center | Longitude of projection centre |
8813 | azimuth | Azimuth of initial line |
8814 | rectified_grid_angle | Angle from Rectified to Skew Grid |
8815 | scale_factor | Scale factor on initial line |
8816 | false_easting | Easting at projection centre |
8817 | false_northing | Northing at projection centre |
8818 | pseudo_standard_parallel_1 | Latitude of pseudo standard parallel |
8819 | scale_factor | Scale factor on pseudo standard parallel |
8821 | latitude_of_origin | Latitude of false origin |
8822 | central_meridian | Longitude of false origin |
8823 | standard_parallel_1, standard_parallel1 | Latitude of 1st standard parallel |
8824 | standard_parallel_2, standard_parallel2 | Latitude of 2nd standard parallel |
8826 | false_easting | Easting at false origin |
8827 | false_northing | Northing at false origin |
8830 | initial_longitude | Initial longitude |
8831 | zone_width | Zone width |
8832 | standard_parallel | Latitude of standard parallel |
8833 | longitude_of_center | Longitude of origin |
- 13.1.20.1 Files Created by CREATE TABLE
- 13.1.20.2 CREATE TEMPORARY TABLE Statement
- 13.1.20.3 CREATE TABLE ... LIKE Statement
- 13.1.20.4 CREATE TABLE ... SELECT Statement
- 13.1.20.5 FOREIGN KEY Constraints
- 13.1.20.6 CHECK Constraints
- 13.1.20.7 Silent Column Specification Changes
- 13.1.20.8 CREATE TABLE and Generated Columns
- 13.1.20.9 Secondary Indexes and Generated Columns
- 13.1.20.10 Invisible Columns
- 13.1.20.11 Setting NDB_TABLE Options
CREATE [TEMPORARY] TABLE [IF NOT EXISTS]tbl_name
(create_definition
,...) [table_options
] [partition_options
] CREATE [TEMPORARY] TABLE [IF NOT EXISTS]tbl_name
[(create_definition
,...)] [table_options
] [partition_options
] [IGNORE | REPLACE] [AS]query_expression
CREATE [TEMPORARY] TABLE [IF NOT EXISTS]tbl_name
{ LIKEold_tbl_name
| (LIKEold_tbl_name
) }create_definition
: {col_name
column_definition
| {INDEX | KEY} [index_name
] [index_type
] (key_part
,...) [index_option
] ... | {FULLTEXT | SPATIAL} [INDEX | KEY] [index_name
] (key_part
,...) [index_option
] ... | [CONSTRAINT [symbol
]] PRIMARY KEY [index_type
] (key_part
,...) [index_option
] ... | [CONSTRAINT [symbol
]] UNIQUE [INDEX | KEY] [index_name
] [index_type
] (key_part
,...) [index_option
] ... | [CONSTRAINT [symbol
]] FOREIGN KEY [index_name
] (col_name
,...)reference_definition
|check_constraint_definition
}column_definition
: {data_type
[NOT NULL | NULL] [DEFAULT {literal
| (expr
)} ] [VISIBLE | INVISIBLE] [AUTO_INCREMENT] [UNIQUE [KEY]] [[PRIMARY] KEY] [COMMENT 'string
'] [COLLATEcollation_name
] [COLUMN_FORMAT {FIXED | DYNAMIC | DEFAULT}] [ENGINE_ATTRIBUTE [=] 'string
'] [SECONDARY_ENGINE_ATTRIBUTE [=] 'string
'] [STORAGE {DISK | MEMORY}] [reference_definition
] [check_constraint_definition
] |data_type
[COLLATEcollation_name
] [GENERATED ALWAYS] AS (expr
) [VIRTUAL | STORED] [NOT NULL | NULL] [VISIBLE | INVISIBLE] [UNIQUE [KEY]] [[PRIMARY] KEY] [COMMENT 'string
'] [reference_definition
] [check_constraint_definition
] }data_type
: (see Chapter 11, Data Types)key_part
: {col_name
[(length
)] | (expr
)} [ASC | DESC]index_type
: USING {BTREE | HASH}index_option
: { KEY_BLOCK_SIZE [=]value
|index_type
| WITH PARSERparser_name
| COMMENT 'string
' | {VISIBLE | INVISIBLE} |ENGINE_ATTRIBUTE
[=] 'string
' |SECONDARY_ENGINE_ATTRIBUTE
[=] 'string
' }check_constraint_definition
: [CONSTRAINT [symbol
]] CHECK (expr
) [[NOT] ENFORCED]reference_definition
: REFERENCEStbl_name
(key_part
,...) [MATCH FULL | MATCH PARTIAL | MATCH SIMPLE] [ON DELETEreference_option
] [ON UPDATEreference_option
]reference_option
: RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULTtable_options
:table_option
[[,]table_option
] ...table_option
: { AUTOEXTEND_SIZE [=]value
| AUTO_INCREMENT [=]value
| AVG_ROW_LENGTH [=]value
| [DEFAULT] CHARACTER SET [=]charset_name
| CHECKSUM [=] {0 | 1} | [DEFAULT] COLLATE [=]collation_name
| COMMENT [=] 'string
' | COMPRESSION [=] {'ZLIB' | 'LZ4' | 'NONE'} | CONNECTION [=] 'connect_string
' | {DATA | INDEX} DIRECTORY [=] 'absolute path to directory
' | DELAY_KEY_WRITE [=] {0 | 1} | ENCRYPTION [=] {'Y' | 'N'} | ENGINE [=]engine_name
| ENGINE_ATTRIBUTE [=] 'string
' | INSERT_METHOD [=] { NO | FIRST | LAST } | KEY_BLOCK_SIZE [=]value
| MAX_ROWS [=]value
| MIN_ROWS [=]value
| PACK_KEYS [=] {0 | 1 | DEFAULT} | PASSWORD [=] 'string
' | ROW_FORMAT [=] {DEFAULT | DYNAMIC | FIXED | COMPRESSED | REDUNDANT | COMPACT} | SECONDARY_ENGINE_ATTRIBUTE [=] 'string
' | STATS_AUTO_RECALC [=] {DEFAULT | 0 | 1} | STATS_PERSISTENT [=] {DEFAULT | 0 | 1} | STATS_SAMPLE_PAGES [=]value
| TABLESPACEtablespace_name
[STORAGE {DISK | MEMORY}] | UNION [=] (tbl_name
[,tbl_name
]...) }partition_options
: PARTITION BY { [LINEAR] HASH(expr
) | [LINEAR] KEY [ALGORITHM={1 | 2}] (column_list
) | RANGE{(expr
) | COLUMNS(column_list
)} | LIST{(expr
) | COLUMNS(column_list
)} } [PARTITIONSnum
] [SUBPARTITION BY { [LINEAR] HASH(expr
) | [LINEAR] KEY [ALGORITHM={1 | 2}] (column_list
) } [SUBPARTITIONSnum
] ] [(partition_definition
[,partition_definition
] ...)]partition_definition
: PARTITIONpartition_name
[VALUES {LESS THAN {(expr
|value_list
) | MAXVALUE} | IN (value_list
)}] [[STORAGE] ENGINE [=]engine_name
] [COMMENT [=] 'string
' ] [DATA DIRECTORY [=] ''] [INDEX DIRECTORY [=] '
data_dir
'] [MAX_ROWS [=]
index_dir
max_number_of_rows
] [MIN_ROWS [=]min_number_of_rows
] [TABLESPACE [=] tablespace_name] [(subpartition_definition
[,subpartition_definition
] ...)]subpartition_definition
: SUBPARTITIONlogical_name
[[STORAGE] ENGINE [=]engine_name
] [COMMENT [=] 'string
' ] [DATA DIRECTORY [=] ''] [INDEX DIRECTORY [=] '
data_dir
'] [MAX_ROWS [=]
index_dir
max_number_of_rows
] [MIN_ROWS [=]min_number_of_rows
] [TABLESPACE [=] tablespace_name]query_expression:
SELECT ... (Some valid select or union statement
)
CREATE TABLE
creates a table with
the given name. You must have the
CREATE
privilege for the table.
By default, tables are created in the default database, using the
InnoDB
storage engine. An error
occurs if the table exists, if there is no default database, or if
the database does not exist.
MySQL has no limit on the number of tables. The underlying file
system may have a limit on the number of files that represent
tables. Individual storage engines may impose engine-specific
constraints. InnoDB
permits up to 4 billion
tables.
For information about the physical representation of a table, see Section 13.1.20.1, “Files Created by CREATE TABLE”.
There are several aspects to the CREATE
TABLE
statement, described under the following topics in
this section:
Table Name
tbl_name
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`
.Rules for permissible table names are given in Section 9.2, “Schema Object Names”.
IF NOT EXISTS
Prevents 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.
Temporary Tables
You can use the TEMPORARY
keyword when creating
a table. A TEMPORARY
table is visible only
within the current session, and is dropped automatically when the
session is closed. For more information, see
Section 13.1.20.2, “CREATE TEMPORARY TABLE Statement”.
Table Cloning and Copying
LIKE
Use
CREATE TABLE ... 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
LIKEorig_tbl
;For more information, see Section 13.1.20.3, “CREATE TABLE ... LIKE Statement”.
[AS]
query_expression
To create one table from another, add a
SELECT
statement at the end of theCREATE TABLE
statement:CREATE TABLE
new_tbl
AS SELECT * FROMorig_tbl
;For more information, see Section 13.1.20.4, “CREATE TABLE ... SELECT Statement”.
IGNORE | REPLACE
The
IGNORE
andREPLACE
options indicate how to handle rows that duplicate unique key values when copying a table using aSELECT
statement.For more information, see Section 13.1.20.4, “CREATE TABLE ... SELECT Statement”.
Column Data Types and Attributes
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 8.4.7, “Limits on Table Column Count and Row Size”.
data_type
data_type
represents the data type in a column definition. 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 11, Data Types.Some attributes do not apply to all data types.
AUTO_INCREMENT
applies only to integer and floating-point types. Prior to MySQL 8.0.13,DEFAULT
does not apply to theBLOB
,TEXT
,GEOMETRY
, andJSON
types.Character data types (
CHAR
,VARCHAR
, theTEXT
types,ENUM
,SET
, and any synonyms) can includeCHARACTER SET
to specify the character set for the column.CHARSET
is a synonym forCHARACTER SET
. A collation for the character set can be specified with theCOLLATE
attribute, along with any other attributes. For details, see Chapter 10, Character Sets, Collations, Unicode. Example:CREATE TABLE t (c CHAR(20) CHARACTER SET utf8 COLLATE utf8_bin);
MySQL 8.0 interprets length specifications in character column definitions in characters. Lengths for
BINARY
andVARBINARY
are in bytes.For
CHAR
,VARCHAR
,BINARY
, andVARBINARY
columns, indexes can be created that use only the leading part of column values, using
syntax to specify an index prefix length.col_name
(length
)BLOB
andTEXT
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 firstlength
characters of each column value forCHAR
,VARCHAR
, andTEXT
columns, and the firstlength
bytes of each column value forBINARY
,VARBINARY
, andBLOB
columns. Indexing only a prefix of column values like this can make the index file much smaller. For additional information about index prefixes, see Section 13.1.15, “CREATE INDEX Statement”.Only the
InnoDB
andMyISAM
storage engines support indexing onBLOB
andTEXT
columns. For example:CREATE TABLE test (blob_col BLOB, INDEX(blob_col(10)));
If a specified index prefix exceeds the maximum column data type size,
CREATE TABLE
handles the index as follows:For a nonunique index, either an error occurs (if strict SQL mode is enabled), or the index length is reduced to lie within the maximum column data type size and a warning is produced (if strict SQL mode is not enabled).
For a unique index, an error occurs regardless of SQL mode because reducing the index length might enable insertion of nonunique entries that do not meet the specified uniqueness requirement.
JSON
columns cannot be indexed. You can work around this restriction by creating an index on a generated column that extracts a scalar value from theJSON
column. See Indexing a Generated Column to Provide a JSON Column Index, for a detailed example.
NOT NULL | NULL
If neither
NULL
norNOT NULL
is specified, the column is treated as thoughNULL
had been specified.In MySQL 8.0, only the
InnoDB
,MyISAM
, andMEMORY
storage engines support indexes on columns that can haveNULL
values. In other cases, you must declare indexed columns asNOT NULL
or an error results.DEFAULT
Specifies a default value for a column. For more information about default value handling, including the case that a column definition includes no explicit
DEFAULT
value, see Section 11.6, “Data Type Default Values”.If the
NO_ZERO_DATE
orNO_ZERO_IN_DATE
SQL mode is enabled and a date-valued default is not correct according to that mode,CREATE TABLE
produces a warning if strict SQL mode is not enabled and an error if strict mode is enabled. For example, withNO_ZERO_IN_DATE
enabled,c1 DATE DEFAULT '2010-00-00'
produces a warning.VISIBLE
,INVISIBLE
Specify column visibility. The default is
VISIBLE
if neither keyword is present. A table must have at least one visible column. Attempting to make all columns invisible produces an error. For more information, see Section 13.1.20.10, “Invisible Columns”.The
VISIBLE
andINVISIBLE
keywords are available as of MySQL 8.0.23. Prior to MySQL 8.0.23, all columns are visible.AUTO_INCREMENT
An integer or floating-point column can have the additional attribute
AUTO_INCREMENT
. When you insert a value ofNULL
(recommended) or0
into an indexedAUTO_INCREMENT
column, the column is set to the next sequence value. Typically this is
, wherevalue
+1value
is the largest value for the column currently in the table.AUTO_INCREMENT
sequences begin with1
.To retrieve an
AUTO_INCREMENT
value after inserting a row, use theLAST_INSERT_ID()
SQL function or themysql_insert_id()
C API function. See Section 12.16, “Information Functions”, and mysql_insert_id().If the
NO_AUTO_VALUE_ON_ZERO
SQL mode is enabled, you can store0
inAUTO_INCREMENT
columns as0
without generating a new sequence value. See Section 5.1.11, “Server SQL Modes”.There can be only one
AUTO_INCREMENT
column per table, it must be indexed, and it cannot have aDEFAULT
value. AnAUTO_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 anAUTO_INCREMENT
column that contains0
.For
MyISAM
tables, you can specify anAUTO_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
WHEREauto_col
IS NULLThis method requires that
sql_auto_is_null
variable is not set to 0. See Section 5.1.8, “Server System Variables”.For information about
InnoDB
andAUTO_INCREMENT
, see Section 15.6.1.6, “AUTO_INCREMENT Handling in InnoDB”. For information aboutAUTO_INCREMENT
and MySQL Replication, see Section 17.5.1.1, “Replication and AUTO_INCREMENT”.COMMENT
A comment for a column can be specified with the
COMMENT
option, up to 1024 characters long. The comment is displayed by theSHOW CREATE TABLE
andSHOW FULL COLUMNS
statements.COLUMN_FORMAT
In NDB Cluster, it is also possible to specify a data storage format for individual columns of
NDB
tables usingCOLUMN_FORMAT
. Permissible column formats areFIXED
,DYNAMIC
, andDEFAULT
.FIXED
is used to specify fixed-width storage,DYNAMIC
permits the column to be variable-width, andDEFAULT
causes the column to use fixed-width or variable-width storage as determined by the column's data type (possibly overridden by aROW_FORMAT
specifier).For
NDB
tables, the default value forCOLUMN_FORMAT
isFIXED
.In NDB Cluster, the maximum possible offset for a column defined with
COLUMN_FORMAT=FIXED
is 8188 bytes. For more information and possible workarounds, see Section 23.1.7.5, “Limits Associated with Database Objects in NDB Cluster”.COLUMN_FORMAT
currently has no effect on columns of tables using storage engines other thanNDB
. MySQL 8.0 silently ignoresCOLUMN_FORMAT
.ENGINE_ATTRIBUTE
andSECONDARY_ENGINE_ATTRIBUTE
options (available as of MySQL 8.0.21) are used to specify column attributes for primary and secondary storage engines. The options are reserved for future use.Permitted values are a string literal containing a valid
JSON
document or an empty string (''). InvalidJSON
is rejected.CREATE TABLE t1 (c1 INT ENGINE_ATTRIBUTE='{"
key
":"value
"}');ENGINE_ATTRIBUTE
andSECONDARY_ENGINE_ATTRIBUTE
values can be repeated without error. In this case, the last specified value is used.ENGINE_ATTRIBUTE
andSECONDARY_ENGINE_ATTRIBUTE
values are not checked by the server, nor are they cleared when the table's storage engine is changed.STORAGE
For
NDB
tables, it is possible to specify whether the column is stored on disk or in memory by using aSTORAGE
clause.STORAGE DISK
causes the column to be stored on disk, andSTORAGE MEMORY
causes in-memory storage to be used. TheCREATE TABLE
statement used must still include aTABLESPACE
clause:mysql>
CREATE TABLE t1 (
->c1 INT STORAGE DISK,
->c2 INT STORAGE MEMORY
->) ENGINE NDB;
ERROR 1005 (HY000): Can't create table 'c.t1' (errno: 140) mysql>CREATE TABLE t1 (
->c1 INT STORAGE DISK,
->c2 INT STORAGE MEMORY
->) TABLESPACE ts_1 ENGINE NDB;
Query OK, 0 rows affected (1.06 sec)For
NDB
tables,STORAGE DEFAULT
is equivalent toSTORAGE MEMORY
.The
STORAGE
clause has no effect on tables using storage engines other thanNDB
. TheSTORAGE
keyword is supported only in the build of mysqld that is supplied with NDB Cluster; it is not recognized in any other version of MySQL, where any attempt to use theSTORAGE
keyword causes a syntax error.GENERATED ALWAYS
Used to specify a generated column expression. For information about generated columns, see Section 13.1.20.8, “CREATE TABLE and Generated Columns”.
Stored generated columns can be indexed.
InnoDB
supports secondary indexes on virtual generated columns. See Section 13.1.20.9, “Secondary Indexes and Generated Columns”.
Indexes, Foreign Keys, and CHECK Constraints
Several keywords apply to creation of indexes, foreign keys, and
CHECK
constraints. For general background in
addition to the following descriptions, see
Section 13.1.15, “CREATE INDEX Statement”,
Section 13.1.20.5, “FOREIGN KEY Constraints”, and
Section 13.1.20.6, “CHECK Constraints”.
CONSTRAINT
symbol
The
CONSTRAINT
clause may be given to name a constraint. If the clause is not given, or asymbol
symbol
is not included following theCONSTRAINT
keyword, MySQL automatically generates a constraint name, with the exception noted below. Thesymbol
value, if used, must be unique per schema (database), per constraint type. A duplicatesymbol
results in an error. See also the discussion about length limits of generated constraint identifiers at Section 9.2.1, “Identifier Length Limits”.NoteIf the
CONSTRAINT
clause is not given in a foreign key definition, or asymbol
symbol
is not included following theCONSTRAINT
keyword, MySQL uses the foreign key index name up to MySQL 8.0.15, and automatically generates a constraint name thereafter.The SQL standard specifies that all types of constraints (primary key, unique index, foreign key, check) belong to the same namespace. In MySQL, each constraint type has its own namespace per schema. Consequently, names for each type of constraint must be unique per schema, but constraints of different types can have the same name.
PRIMARY KEY
A unique index where all key columns must be defined as
NOT NULL
. If they are not explicitly declared asNOT NULL
, MySQL declares them so implicitly (and silently). A table can have only onePRIMARY KEY
. The name of aPRIMARY KEY
is alwaysPRIMARY
, which thus cannot be used as the name for any other kind of index.If you do not have a
PRIMARY KEY
and an application asks for thePRIMARY KEY
in your tables, MySQL returns the firstUNIQUE
index that has noNULL
columns as thePRIMARY KEY
.In
InnoDB
tables, keep thePRIMARY KEY
short to minimize storage overhead for secondary indexes. Each secondary index entry contains a copy of the primary key columns for the corresponding row. (See Section 15.6.2.1, “Clustered and Secondary Indexes”.)In the created table, a
PRIMARY KEY
is placed first, followed by allUNIQUE
indexes, and then the nonunique indexes. This helps the MySQL optimizer to prioritize which index to use and also more quickly to detect duplicatedUNIQUE
keys.A
PRIMARY KEY
can be a multiple-column index. However, you cannot create a multiple-column index using thePRIMARY KEY
key attribute in a column specification. Doing so only marks that single column as primary. You must use a separatePRIMARY KEY(
clause.key_part
, ...)If a table has a
PRIMARY KEY
orUNIQUE NOT NULL
index that consists of a single column that has an integer type, you can use_rowid
to refer to the indexed column inSELECT
statements, as described in Unique Indexes.In MySQL, the name of a
PRIMARY KEY
isPRIMARY
. 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 usingSHOW INDEX FROM
. See Section 13.7.7.22, “SHOW INDEX Statement”.tbl_name
KEY | INDEX
KEY
is normally a synonym forINDEX
. The key attributePRIMARY KEY
can also be specified as justKEY
when given in a column definition. This was implemented for compatibility with other database systems.UNIQUE
A
UNIQUE
index creates a constraint such that all values in the index must be distinct. An error occurs if you try to add a new row with a key value that matches an existing row. For all engines, aUNIQUE
index permits multipleNULL
values for columns that can containNULL
. If you specify a prefix value for a column in aUNIQUE
index, the column values must be unique within the prefix length.If a table has a
PRIMARY KEY
orUNIQUE NOT NULL
index that consists of a single column that has an integer type, you can use_rowid
to refer to the indexed column inSELECT
statements, as described in Unique Indexes.FULLTEXT
A
FULLTEXT
index is a special type of index used for full-text searches. Only theInnoDB
andMyISAM
storage engines supportFULLTEXT
indexes. They can be created only fromCHAR
,VARCHAR
, andTEXT
columns. Indexing always happens over the entire column; column prefix indexing is not supported and any prefix length is ignored if specified. See Section 12.10, “Full-Text Search Functions”, for details of operation. AWITH PARSER
clause can be specified as anindex_option
value to associate a parser plugin with the index if full-text indexing and searching operations need special handling. This clause is valid only forFULLTEXT
indexes.InnoDB
andMyISAM
support full-text parser plugins. See Full-Text Parser Plugins and Writing Full-Text Parser Plugins for more information.SPATIAL
You can create
SPATIAL
indexes on spatial data types. Spatial types are supported only forInnoDB
andMyISAM
tables, and indexed columns must be declared asNOT NULL
. See Section 11.4, “Spatial Data Types”.FOREIGN KEY
MySQL supports foreign keys, which let you cross-reference related data across tables, and foreign key constraints, which help keep this spread-out data consistent. For definition and option information, see
reference_definition
, andreference_option
.Partitioned tables employing the
InnoDB
storage engine do not support foreign keys. See Section 24.6, “Restrictions and Limitations on Partitioning”, for more information.CHECK
The
CHECK
clause enables the creation of constraints to be checked for data values in table rows. See Section 13.1.20.6, “CHECK Constraints”.key_part
A
key_part
specification can end withASC
orDESC
to specify whether index values are stored in ascending or descending order. The default is ascending if no order specifier is given.Prefixes, defined by the
length
attribute, can be up to 767 bytes long forInnoDB
tables that use theREDUNDANT
orCOMPACT
row format. The prefix length limit is 3072 bytes forInnoDB
tables that use theDYNAMIC
orCOMPRESSED
row format. ForMyISAM
tables, the prefix length limit is 1000 bytes.Prefix limits are measured in bytes. However, prefix lengths for index specifications in
CREATE TABLE
,ALTER TABLE
, andCREATE INDEX
statements are interpreted as number of characters for nonbinary string types (CHAR
,VARCHAR
,TEXT
) and number of bytes for binary string types (BINARY
,VARBINARY
,BLOB
). Take this into account when specifying a prefix length for a nonbinary string column that uses a multibyte character set.Beginning with MySQL 8.0.17, the
expr
for akey_part
specification can take the form(CAST
to create a multi-valued index on ajson_path
AStype
ARRAY)JSON
column. Multi-Valued Indexes, provides detailed information regarding creation of, usage of, and restrictions and limitations on multi-valued indexes.
index_type
Some storage engines permit you to specify an index type when creating an index. The syntax for the
index_type
specifier isUSING
.type_name
Example:
CREATE TABLE lookup (id INT, INDEX USING BTREE (id)) ENGINE = MEMORY;
The preferred position for
USING
is after the index column list. It can be given before the column list, but support for use of the option in that position is deprecated and you should expect it to be removed in a future MySQL release.index_option
index_option
values specify additional options for an index.KEY_BLOCK_SIZE
For
MyISAM
tables,KEY_BLOCK_SIZE
optionally specifies the size in bytes to use for index key blocks. The value is treated as a hint; a different size could be used if necessary. AKEY_BLOCK_SIZE
value specified for an individual index definition overrides the table-levelKEY_BLOCK_SIZE
value.For information about the table-level
KEY_BLOCK_SIZE
attribute, see Table Options.WITH PARSER
The
WITH PARSER
option can be used only withFULLTEXT
indexes. It associates a parser plugin with the index if full-text indexing and searching operations need special handling.InnoDB
andMyISAM
support full-text parser plugins. If you have aMyISAM
table with an associated full-text parser plugin, you can convert the table toInnoDB
usingALTER TABLE
.COMMENT
Index definitions can include an optional comment of up to 1024 characters.
You can set the
InnoDB
MERGE_THRESHOLD
value for an individual index using theindex_option
COMMENT
clause. See Section 15.8.11, “Configuring the Merge Threshold for Index Pages”.VISIBLE
,INVISIBLE
Specify index visibility. Indexes are visible by default. An invisible index is not used by the optimizer. Specification of index visibility applies to indexes other than primary keys (either explicit or implicit). For more information, see Section 8.3.12, “Invisible Indexes”.
ENGINE_ATTRIBUTE
andSECONDARY_ENGINE_ATTRIBUTE
options (available as of MySQL 8.0.21) are used to specify index attributes for primary and secondary storage engines. The options are reserved for future use.
For more information about permissible
index_option
values, see Section 13.1.15, “CREATE INDEX Statement”. For more information about indexes, see Section 8.3.1, “How MySQL Uses Indexes”.For
reference_definition
syntax details and examples, see Section 13.1.20.5, “FOREIGN KEY Constraints”.InnoDB
andNDB
tables support checking of foreign key constraints. The columns of the referenced table must always be explicitly named. BothON DELETE
andON UPDATE
actions on foreign keys are supported. For more detailed information and examples, see Section 13.1.20.5, “FOREIGN KEY Constraints”.For other storage engines, MySQL Server parses and ignores the
FOREIGN KEY
andREFERENCES
syntax inCREATE TABLE
statements. See Section 1.7.2.3, “FOREIGN KEY Constraint Differences”.ImportantFor users familiar with the ANSI/ISO SQL Standard, please note that no storage engine, including
InnoDB
, recognizes or enforces theMATCH
clause used in referential integrity constraint definitions. Use of an explicitMATCH
clause does not have the specified effect, and also causesON DELETE
andON UPDATE
clauses to be ignored. For these reasons, specifyingMATCH
should be avoided.The
MATCH
clause in the SQL standard controls howNULL
values in a composite (multiple-column) foreign key are handled when comparing to a primary key.InnoDB
essentially implements the semantics defined byMATCH SIMPLE
, which permit a foreign key to be all or partiallyNULL
. In that case, the (child table) row containing such a foreign key is permitted to be inserted, and does not match any row in the referenced (parent) table. It is possible to implement other semantics using triggers.Additionally, MySQL requires that the referenced columns be indexed for performance. However,
InnoDB
does not enforce any requirement that the referenced columns be declaredUNIQUE
orNOT NULL
. The handling of foreign key references to nonunique keys or keys that containNULL
values is not well defined for operations such asUPDATE
orDELETE CASCADE
. You are advised to use foreign keys that reference only keys that are bothUNIQUE
(orPRIMARY
) andNOT NULL
.MySQL parses but ignores “inline
REFERENCES
specifications” (as defined in the SQL standard) where the references are defined as part of the column specification. MySQL acceptsREFERENCES
clauses only when specified as part of a separateFOREIGN KEY
specification.For information about the
RESTRICT
,CASCADE
,SET NULL
,NO ACTION
, andSET DEFAULT
options, see Section 13.1.20.5, “FOREIGN KEY Constraints”.
Table Options
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.
ENGINE
Specifies the storage engine for the table, using one of the names shown in the following table. The engine name can be unquoted or quoted. The quoted name
'DEFAULT'
is recognized but ignored.Storage Engine Description InnoDB
Transaction-safe tables with row locking and foreign keys. The default storage engine for new tables. See Chapter 15, The InnoDB Storage Engine, and in particular Section 15.1, “Introduction to InnoDB” if you have MySQL experience but are new to InnoDB
.MyISAM
The binary portable storage engine that is primarily used for read-only or read-mostly workloads. See Section 16.2, “The MyISAM Storage Engine”. MEMORY
The data for this storage engine is stored only in memory. See Section 16.3, “The MEMORY Storage Engine”. CSV
Tables that store rows in comma-separated values format. See Section 16.4, “The CSV Storage Engine”. ARCHIVE
The archiving storage engine. See Section 16.5, “The ARCHIVE Storage Engine”. EXAMPLE
An example engine. See Section 16.9, “The EXAMPLE Storage Engine”. FEDERATED
Storage engine that accesses remote tables. See Section 16.8, “The FEDERATED Storage Engine”. HEAP
This is a synonym for MEMORY
.MERGE
A collection of MyISAM
tables used as one table. Also known asMRG_MyISAM
. See Section 16.7, “The MERGE Storage Engine”.NDB
Clustered, fault-tolerant, memory-based tables, supporting transactions and foreign keys. Also known as NDBCLUSTER
. See Chapter 23, MySQL NDB Cluster 8.0.By default, if a storage engine is specified that is not available, the statement fails with an error. You can override this behavior by removing
NO_ENGINE_SUBSTITUTION
from the server SQL mode (see Section 5.1.11, “Server SQL Modes”) so that MySQL allows substitution of the specified engine with the default storage engine instead. Normally in such cases, this isInnoDB
, which is the default value for thedefault_storage_engine
system variable. WhenNO_ENGINE_SUBSTITUTION
is disabled, a warning occurs if the storage engine specification is not honored.AUTOEXTEND_SIZE
Defines the amount by which
InnoDB
extends the size of the tablespace when it becomes full. Introduced in MySQL 8.0.23. The setting must be a multiple of 4MB. The default setting is 0, which causes the tablespace to be extended according to the implicit default behavior. For more information, see Section 15.6.3.9, “Tablespace AUTOEXTEND_SIZE Configuration”.AUTO_INCREMENT
The initial
AUTO_INCREMENT
value for the table. In MySQL 8.0, this works forMyISAM
,MEMORY
,InnoDB
, andARCHIVE
tables. To set the first auto-increment value for engines that do not support theAUTO_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 inCREATE TABLE
statements, you can also useALTER TABLE
to reset thetbl_name
AUTO_INCREMENT =N
AUTO_INCREMENT
value. The value cannot be set lower than the maximum value currently in the column.AVG_ROW_LENGTH
An approximation of the average row length for your table. You need to set this only for large tables with variable-size rows.
When you create a
MyISAM
table, MySQL uses the product of theMAX_ROWS
andAVG_ROW_LENGTH
options to decide how big the resulting table is. If you don't specify either option, the maximum size forMyISAM
data and index files is 256TB by default. (If your operating system does not support files that large, table sizes are constrained by the file size limit.) If you want to keep down the pointer sizes to make the index smaller and faster and you don't really need big files, you can decrease the default pointer size by setting themyisam_data_pointer_size
system variable. (See Section 5.1.8, “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 permits table sizes up to 65,536TB.[DEFAULT] CHARACTER SET
Specifies a default character set for the table.
CHARSET
is a synonym forCHARACTER SET
. If the character set name isDEFAULT
, 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
Specifies a default collation for the table.
COMMENT
A comment for the table, up to 2048 characters long.
You can set the
InnoDB
MERGE_THRESHOLD
value for a table using thetable_option
COMMENT
clause. See Section 15.8.11, “Configuring the Merge Threshold for Index Pages”.Setting NDB_TABLE options. The table comment in a
CREATE TABLE
that creates anNDB
table or anALTER TABLE
statement which alters one can also be used to specify one to four of theNDB_TABLE
optionsNOLOGGING
,READ_BACKUP
,PARTITION_BALANCE
, orFULLY_REPLICATED
as a set of name-value pairs, separated by commas if need be, immediately following the stringNDB_TABLE=
that begins the quoted comment text. An example statement using this syntax is shown here (emphasized text):CREATE TABLE t1 ( c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY, c2 VARCHAR(100), c3 VARCHAR(100) ) ENGINE=NDB COMMENT="NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RP_BY_NODE";
Spaces are not permitted within the quoted string. The string is case-insensitive.
The comment is displayed as part of the ouput of
SHOW CREATE TABLE
. The text of the comment is also available as the TABLE_COMMENT column of the MySQL Information SchemaTABLES
table.This comment syntax is also supported with
ALTER TABLE
statements forNDB
tables. Keep in mind that a table comment used withALTER TABLE
replaces any existing comment which the table might have had perviously.Setting the
MERGE_THRESHOLD
option in table comments is not supported forNDB
tables (it is ignored).For complete syntax information and examples, see Section 13.1.20.11, “Setting NDB_TABLE Options”.
COMPRESSION
The compression algorithm used for page level compression for
InnoDB
tables. Supported values includeZlib
,LZ4
, andNone
. TheCOMPRESSION
attribute was introduced with the transparent page compression feature. Page compression is only supported withInnoDB
tables that reside in file-per-table tablespaces, and is only available on Linux and Windows platforms that support sparse files and hole punching. For more information, see Section 15.9.2, “InnoDB Page Compression”.CONNECTION
The connection string for a
FEDERATED
table.NoteOlder versions of MySQL used a
COMMENT
option for the connection string.DATA DIRECTORY
,INDEX DIRECTORY
For
InnoDB
, theDATA DIRECTORY='
clause permits creating tables outside of the data directory. Thedirectory
'innodb_file_per_table
variable must be enabled to use theDATA DIRECTORY
clause. The full directory path must be specified. As of MySQL 8.0.21, the directory specified must be known toInnoDB
. For more information, see Section 15.6.1.2, “Creating Tables Externally”.When creating
MyISAM
tables, you can use theDATA DIRECTORY='
clause, thedirectory
'INDEX DIRECTORY='
clause, or both. They specify where to put adirectory
'MyISAM
table's data file and index file, respectively. UnlikeInnoDB
tables, MySQL does not create subdirectories that correspond to the database name when creating aMyISAM
table with aDATA DIRECTORY
orINDEX DIRECTORY
option. Files are created in the directory that is specified.You must have the
FILE
privilege to use theDATA DIRECTORY
orINDEX DIRECTORY
table option.ImportantTable-level
DATA DIRECTORY
andINDEX DIRECTORY
options are ignored for partitioned tables. (Bug #32091)These options work only when you are not using the
--skip-symbolic-links
option. Your operating system must also have a working, thread-saferealpath()
call. See Section 8.12.2.2, “Using Symbolic Links for MyISAM Tables on Unix”, for more complete information.If a
MyISAM
table is created with noDATA DIRECTORY
option, the.MYD
file is created in the database directory. By default, ifMyISAM
finds an existing.MYD
file in this case, it overwrites it. The same applies to.MYI
files for tables created with noINDEX DIRECTORY
option. To suppress this behavior, start the server with the--keep_files_on_create
option, in which caseMyISAM
does not overwrite existing files and returns an error instead.If a
MyISAM
table is created with aDATA DIRECTORY
orINDEX DIRECTORY
option and an existing.MYD
or.MYI
file is found,MyISAM
always returns an error, and does not overwrite a file in the specified directory.ImportantYou cannot use path names that contain the MySQL data directory with
DATA DIRECTORY
orINDEX DIRECTORY
. This includes partitioned tables and individual table partitions. (See Bug #32167.)DELAY_KEY_WRITE
Set this to 1 if you want to delay key updates for the table until the table is closed. See the description of the
delay_key_write
system variable in Section 5.1.8, “Server System Variables”. (MyISAM
only.)ENCRYPTION
The
ENCRYPTION
clause enables or disables page-level data encryption for anInnoDB
table. A keyring plugin must be installed and configured before encryption can be enabled. Prior to MySQL 8.0.16, theENCRYPTION
clause can only be specified when creating a table in an a file-per-table tablespace. As of MySQL 8.0.16, theENCRYPTION
clause can also be specified when creating a table in a general tablespace.As of MySQL 8.0.16, a table inherits the default schema encryption if an
ENCRYPTION
clause is not specified. If thetable_encryption_privilege_check
variable is enabled, theTABLE_ENCRYPTION_ADMIN
privilege is required to create a table with anENCRYPTION
clause setting that differs from the default schema encryption. When creating a table in a general tablespace, table and tablespace encryption must match.As of MySQL 8.0.16, specifying an
ENCRYPTION
clause with a value other than'N'
or''
is not permitted when using a storage engine that does not support encryption. Previously, the clause was accepted.For more information, see Section 15.13, “InnoDB Data-at-Rest Encryption”.
ENGINE_ATTRIBUTE
andSECONDARY_ENGINE_ATTRIBUTE
options (available as of MySQL 8.0.21) are used to specify table attributes for primary and secondary storage engines. The options are reserved for future use.Permitted values are a string literal containing a valid
JSON
document or an empty string (''). InvalidJSON
is rejected.CREATE TABLE t1 (c1 INT) ENGINE_ATTRIBUTE='{"
key
":"value
"}';ENGINE_ATTRIBUTE
andSECONDARY_ENGINE_ATTRIBUTE
values can be repeated without error. In this case, the last specified value is used.ENGINE_ATTRIBUTE
andSECONDARY_ENGINE_ATTRIBUTE
values are not checked by the server, nor are they cleared when the table's storage engine is changed.INSERT_METHOD
If you want to insert data into a
MERGE
table, you must specify withINSERT_METHOD
the table into which the row should be inserted.INSERT_METHOD
is an option useful forMERGE
tables only. Use a value ofFIRST
orLAST
to have inserts go to the first or last table, or a value ofNO
to prevent inserts. See Section 16.7, “The MERGE Storage Engine”.KEY_BLOCK_SIZE
For
MyISAM
tables,KEY_BLOCK_SIZE
optionally specifies the size in bytes to use for index key blocks. The value is treated as a hint; a different size could be used if necessary. AKEY_BLOCK_SIZE
value specified for an individual index definition overrides the table-levelKEY_BLOCK_SIZE
value.For
InnoDB
tables,KEY_BLOCK_SIZE
specifies the page size in kilobytes to use for compressedInnoDB
tables. TheKEY_BLOCK_SIZE
value is treated as a hint; a different size could be used byInnoDB
if necessary.KEY_BLOCK_SIZE
can only be less than or equal to theinnodb_page_size
value. A value of 0 represents the default compressed page size, which is half of theinnodb_page_size
value. Depending oninnodb_page_size
, possibleKEY_BLOCK_SIZE
values include 0, 1, 2, 4, 8, and 16. See Section 15.9.1, “InnoDB Table Compression” for more information.Oracle recommends enabling
innodb_strict_mode
when specifyingKEY_BLOCK_SIZE
forInnoDB
tables. Wheninnodb_strict_mode
is enabled, specifying an invalidKEY_BLOCK_SIZE
value returns an error. Ifinnodb_strict_mode
is disabled, an invalidKEY_BLOCK_SIZE
value results in a warning, and theKEY_BLOCK_SIZE
option is ignored.The
Create_options
column in response toSHOW TABLE STATUS
reports the actualKEY_BLOCK_SIZE
used by the table, as doesSHOW CREATE TABLE
.InnoDB
only supportsKEY_BLOCK_SIZE
at the table level.KEY_BLOCK_SIZE
is not supported with 32KB and 64KBinnodb_page_size
values.InnoDB
table compression does not support these pages sizes.InnoDB
does not support theKEY_BLOCK_SIZE
option when creating temporary tables.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.
ImportantThe use of
MAX_ROWS
withNDB
tables to control the number of table partitions is deprecated. It remains supported in later versions for backward compatibility, but is subject to removal in a future release. Use PARTITION_BALANCE instead; see Setting NDB_TABLE options.The
NDB
storage engine treats this value as a maximum. If you plan to create very large NDB Cluster tables (containing millions of rows), you should use this option to insure thatNDB
allocates sufficient number of index slots in the hash table used for storing hashes of the table's primary keys by settingMAX_ROWS = 2 *
, whererows
rows
is the number of rows that you expect to insert into the table.The maximum
MAX_ROWS
value is 4294967295; larger values are truncated to this limit.MIN_ROWS
The minimum number of rows you plan to store in the table. The
MEMORY
storage engine uses this option as a hint about memory use.PACK_KEYS
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 toDEFAULT
tells the storage engine to pack only longCHAR
,VARCHAR
,BINARY
, orVARBINARY
columns.If you do not use
PACK_KEYS
, the default is to pack strings, but not numbers. If you usePACK_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 haveNULL
values. (In this case, the packed key length is stored in the same byte that is used to mark if a key isNULL
.)PASSWORD
This option is unused.
ROW_FORMAT
Defines the physical format in which the rows are stored.
When creating a table with strict mode disabled, the storage engine's default row format is used if the specified row format is not supported. The actual row format of the table is reported in the
Row_format
column in response toSHOW TABLE STATUS
. TheCreate_options
column shows the row format that was specified in theCREATE TABLE
statement, as doesSHOW CREATE TABLE
.Row format choices differ depending on the storage engine used for the table.
For
InnoDB
tables:The default row format is defined by
innodb_default_row_format
, which has a default setting ofDYNAMIC
. The default row format is used when theROW_FORMAT
option is not defined or whenROW_FORMAT=DEFAULT
is used.If the
ROW_FORMAT
option is not defined, or ifROW_FORMAT=DEFAULT
is used, operations that rebuild a table also silently change the row format of the table to the default defined byinnodb_default_row_format
. For more information, see Defining the Row Format of a Table.For more efficient
InnoDB
storage of data types, especiallyBLOB
types, use theDYNAMIC
. See DYNAMIC Row Format for requirements associated with theDYNAMIC
row format.To enable compression for
InnoDB
tables, specifyROW_FORMAT=COMPRESSED
. TheROW_FORMAT=COMPRESSED
option is not supported when creating temporary tables. See Section 15.9, “InnoDB Table and Page Compression” for requirements associated with theCOMPRESSED
row format.The row format used in older versions of MySQL can still be requested by specifying the
REDUNDANT
row format.When you specify a non-default
ROW_FORMAT
clause, consider also enabling theinnodb_strict_mode
configuration option.ROW_FORMAT=FIXED
is not supported. IfROW_FORMAT=FIXED
is specified whileinnodb_strict_mode
is disabled,InnoDB
issues a warning and assumesROW_FORMAT=DYNAMIC
. IfROW_FORMAT=FIXED
is specified whileinnodb_strict_mode
is enabled, which is the default,InnoDB
returns an error.For additional information about
InnoDB
row formats, see Section 15.10, “InnoDB Row Formats”.
For
MyISAM
tables, the option value can beFIXED
orDYNAMIC
for static or variable-length row format. myisampack sets the type toCOMPRESSED
. See Section 16.2.3, “MyISAM Table Storage Formats”.For
NDB
tables, the defaultROW_FORMAT
isDYNAMIC
.STATS_AUTO_RECALC
Specifies whether to automatically recalculate persistent statistics for an
InnoDB
table. The valueDEFAULT
causes the persistent statistics setting for the table to be determined by theinnodb_stats_auto_recalc
configuration option. The value1
causes statistics to be recalculated when 10% of the data in the table has changed. The value0
prevents automatic recalculation for this table; with this setting, issue anANALYZE TABLE
statement to recalculate the statistics after making substantial changes to the table. For more information about the persistent statistics feature, see Section 15.8.10.1, “Configuring Persistent Optimizer Statistics Parameters”.STATS_PERSISTENT
Specifies whether to enable persistent statistics for an
InnoDB
table. The valueDEFAULT
causes the persistent statistics setting for the table to be determined by theinnodb_stats_persistent
configuration option. The value1
enables persistent statistics for the table, while the value0
turns off this feature. After enabling persistent statistics through aCREATE TABLE
orALTER TABLE
statement, issue anANALYZE TABLE
statement to calculate the statistics, after loading representative data into the table. For more information about the persistent statistics feature, see Section 15.8.10.1, “Configuring Persistent Optimizer Statistics Parameters”.STATS_SAMPLE_PAGES
The number of index pages to sample when estimating cardinality and other statistics for an indexed column, such as those calculated by
ANALYZE TABLE
. For more information, see Section 15.8.10.1, “Configuring Persistent Optimizer Statistics Parameters”.TABLESPACE
The
TABLESPACE
clause can be used to create a table in an existing general tablespace, a file-per-table tablespace, or the system tablespace.CREATE TABLE
tbl_name
... TABLESPACE [=]tablespace_name
The general tablespace that you specify must exist prior to using the
TABLESPACE
clause. For information about general tablespaces, see Section 15.6.3.3, “General Tablespaces”.The
is a case-sensitive identifier. It may be quoted or unquoted. The forward slash character (“/”) is not permitted. Names beginning with “innodb_” are reserved for special use.tablespace_name
To create a table in the system tablespace, specify
innodb_system
as the tablespace name.CREATE TABLE
tbl_name
... TABLESPACE [=] innodb_systemUsing
TABLESPACE [=] innodb_system
, you can place a table of any uncompressed row format in the system tablespace regardless of theinnodb_file_per_table
setting. For example, you can add a table withROW_FORMAT=DYNAMIC
to the system tablespace usingTABLESPACE [=] innodb_system
.To create a table in a file-per-table tablespace, specify
innodb_file_per_table
as the tablespace name.CREATE TABLE
tbl_name
... TABLESPACE [=] innodb_file_per_tableNoteIf
innodb_file_per_table
is enabled, you need not specifyTABLESPACE=innodb_file_per_table
to create anInnoDB
file-per-table tablespace.InnoDB
tables are created in file-per-table tablespaces by default wheninnodb_file_per_table
is enabled.The
DATA DIRECTORY
clause is permitted withCREATE TABLE ... TABLESPACE=innodb_file_per_table
but is otherwise not supported for use in combination with theTABLESPACE
clause. As of MySQL 8.0.21, the directory specified in aDATA DIRECTORY
clause must be known toInnoDB
. For more information, see Using the DATA DIRECTORY Clause.NoteSupport for
TABLESPACE = innodb_file_per_table
andTABLESPACE = innodb_temporary
clauses withCREATE TEMPORARY TABLE
is deprecated as of MySQL 8.0.13; expect it to be removed in a future version of MySQL.The
STORAGE
table option is employed only withNDB
tables.STORAGE
determines the type of storage used (disk or memory), and can be eitherDISK
orMEMORY
.TABLESPACE ... STORAGE DISK
assigns a table to an NDB Cluster Disk Data tablespace. The tablespace must already have been created usingCREATE TABLESPACE
. See Section 23.5.10, “NDB Cluster Disk Data Tables”, for more information.ImportantA
STORAGE
clause cannot be used in aCREATE TABLE
statement without aTABLESPACE
clause.Used to access a collection of identical
MyISAM
tables as one. This works only withMERGE
tables. See Section 16.7, “The MERGE Storage Engine”.You must have
SELECT
,UPDATE
, andDELETE
privileges for the tables you map to aMERGE
table.NoteFormerly, all tables used had to be in the same database as the
MERGE
table itself. This restriction no longer applies.
Table Partitioning
partition_options
can be used to
control partitioning of the table created with
CREATE TABLE
.
Not all options shown in the syntax for
partition_options
at the beginning of
this section are available for all partitioning types. Please see
the listings for the following individual types for information
specific to each type, and see Chapter 24, Partitioning, for
more complete information about the workings of and uses for
partitioning in MySQL, as well as additional examples of table
creation and other statements relating to MySQL partitioning.
Partitions can be modified, merged, added to tables, and dropped from tables. For basic information about the MySQL statements to accomplish these tasks, see Section 13.1.9, “ALTER TABLE Statement”. For more detailed descriptions and examples, see Section 24.3, “Partition Management”.
PARTITION BY
If used, a
partition_options
clause begins withPARTITION BY
. This clause contains the function that is used to determine the partition; the function returns an integer value ranging from 1 tonum
, wherenum
is the number of partitions. (The maximum number of user-defined partitions which a table may contain is 1024; the number of subpartitions—discussed later in this section—is included in this maximum.)NoteThe expression (
expr
) used in aPARTITION BY
clause cannot refer to any columns not in the table being created; such references are specifically not permitted and cause the statement to fail with an error. (Bug #29444)HASH(
expr
)Hashes one or more columns to create a key for placing and locating rows.
expr
is an expression using one or more table columns. This can be any valid MySQL expression (including MySQL functions) that yields a single integer value. For example, these are both validCREATE TABLE
statements usingPARTITION BY HASH
:CREATE TABLE t1 (col1 INT, col2 CHAR(5)) PARTITION BY HASH(col1); CREATE TABLE t1 (col1 INT, col2 CHAR(5), col3 DATETIME) PARTITION BY HASH ( YEAR(col3) );
You may not use either
VALUES LESS THAN
orVALUES IN
clauses withPARTITION BY HASH
.PARTITION BY HASH
uses the remainder ofexpr
divided by the number of partitions (that is, the modulus). For examples and additional information, see Section 24.2.4, “HASH Partitioning”.The
LINEAR
keyword entails a somewhat different algorithm. In this case, the number of the partition in which a row is stored is calculated as the result of one or more logicalAND
operations. For discussion and examples of linear hashing, see Section 24.2.4.1, “LINEAR HASH Partitioning”.KEY(
column_list
)This is similar to
HASH
, except that MySQL supplies the hashing function so as to guarantee an even data distribution. Thecolumn_list
argument is simply a list of 1 or more table columns (maximum: 16). This example shows a simple table partitioned by key, with 4 partitions:CREATE TABLE tk (col1 INT, col2 CHAR(5), col3 DATE) PARTITION BY KEY(col3) PARTITIONS 4;
For tables that are partitioned by key, you can employ linear partitioning by using the
LINEAR
keyword. This has the same effect as with tables that are partitioned byHASH
. That is, the partition number is found using the&
operator rather than the modulus (see Section 24.2.4.1, “LINEAR HASH Partitioning”, and Section 24.2.5, “KEY Partitioning”, for details). This example uses linear partitioning by key to distribute data between 5 partitions:CREATE TABLE tk (col1 INT, col2 CHAR(5), col3 DATE) PARTITION BY LINEAR KEY(col3) PARTITIONS 5;
The
ALGORITHM={1 | 2}
option is supported with[SUB]PARTITION BY [LINEAR] KEY
.ALGORITHM=1
causes the server to use the same key-hashing functions as MySQL 5.1;ALGORITHM=2
means that the server employs the key-hashing functions implemented and used by default for newKEY
partitioned tables in MySQL 5.5 and later. (Partitioned tables created with the key-hashing functions employed in MySQL 5.5 and later cannot be used by a MySQL 5.1 server.) Not specifying the option has the same effect as usingALGORITHM=2
. This option is intended for use chiefly when upgrading or downgrading[LINEAR] KEY
partitioned tables between MySQL 5.1 and later MySQL versions, or for creating tables partitioned byKEY
orLINEAR KEY
on a MySQL 5.5 or later server which can be used on a MySQL 5.1 server. For more information, see Section 13.1.9.1, “ALTER TABLE Partition Operations”.mysqldump in MySQL 5.7 (and later) writes this option encased in versioned comments, like this:
CREATE TABLE t1 (a INT) /*!50100 PARTITION BY KEY */ /*!50611 ALGORITHM = 1 */ /*!50100 () PARTITIONS 3 */
This causes MySQL 5.6.10 and earlier servers to ignore the option, which would otherwise cause a syntax error in those versions. If you plan to load a dump made on a MySQL 5.7 server where you use tables that are partitioned or subpartitioned by
KEY
into a MySQL 5.6 server previous to version 5.6.11, be sure to consult Changes in MySQL 5.6, before proceeding. (The information found there also applies if you are loading a dump containingKEY
partitioned or subpartitioned tables made from a MySQL 5.7—actually 5.6.11 or later—server into a MySQL 5.5.30 or earlier server.)Also in MySQL 5.6.11 and later,
ALGORITHM=1
is shown when necessary in the output ofSHOW CREATE TABLE
using versioned comments in the same manner as mysqldump.ALGORITHM=2
is always omitted fromSHOW CREATE TABLE
output, even if this option was specified when creating the original table.You may not use either
VALUES LESS THAN
orVALUES IN
clauses withPARTITION BY KEY
.RANGE(
expr
)In this case,
expr
shows a range of values using a set ofVALUES LESS THAN
operators. When using range partitioning, you must define at least one partition usingVALUES LESS THAN
. You cannot useVALUES IN
with range partitioning.NoteFor tables partitioned by
RANGE
,VALUES LESS THAN
must be used with either an integer literal value or an expression that evaluates to a single integer value. In MySQL 8.0, you can overcome this limitation in a table that is defined usingPARTITION BY RANGE COLUMNS
, as described later in this section.Suppose that you have a table that you wish to partition on a column containing year values, according to the following scheme.
Partition Number: Years Range: 0 1990 and earlier 1 1991 to 1994 2 1995 to 1998 3 1999 to 2002 4 2003 to 2005 5 2006 and later A table implementing such a partitioning scheme can be realized by the
CREATE TABLE
statement shown here:CREATE TABLE t1 ( year_col INT, some_data INT ) PARTITION BY RANGE (year_col) ( PARTITION p0 VALUES LESS THAN (1991), PARTITION p1 VALUES LESS THAN (1995), PARTITION p2 VALUES LESS THAN (1999), PARTITION p3 VALUES LESS THAN (2002), PARTITION p4 VALUES LESS THAN (2006), PARTITION p5 VALUES LESS THAN MAXVALUE );
PARTITION ... VALUES LESS THAN ...
statements work in a consecutive fashion.VALUES LESS THAN MAXVALUE
works to specify “leftover” values that are greater than the maximum value otherwise specified.VALUES LESS THAN
clauses work sequentially in a manner similar to that of thecase
portions of aswitch ... case
block (as found in many programming languages such as C, Java, and PHP). That is, the clauses must be arranged in such a way that the upper limit specified in each successiveVALUES LESS THAN
is greater than that of the previous one, with the one referencingMAXVALUE
coming last of all in the list.RANGE COLUMNS(
column_list
)This variant on
RANGE
facilitates partition pruning for queries using range conditions on multiple columns (that is, having conditions such asWHERE a = 1 AND b < 10
orWHERE a = 1 AND b = 10 AND c < 10
). It enables you to specify value ranges in multiple columns by using a list of columns in theCOLUMNS
clause and a set of column values in eachPARTITION ... VALUES LESS THAN (
partition definition clause. (In the simplest case, this set consists of a single column.) The maximum number of columns that can be referenced in thevalue_list
)column_list
andvalue_list
is 16.The
column_list
used in theCOLUMNS
clause may contain only names of columns; each column in the list must be one of the following MySQL data types: the integer types; the string types; and time or date column types. Columns usingBLOB
,TEXT
,SET
,ENUM
,BIT
, or spatial data types are not permitted; columns that use floating-point number types are also not permitted. You also may not use functions or arithmetic expressions in theCOLUMNS
clause.The
VALUES LESS THAN
clause used in a partition definition must specify a literal value for each column that appears in theCOLUMNS()
clause; that is, the list of values used for eachVALUES LESS THAN
clause must contain the same number of values as there are columns listed in theCOLUMNS
clause. An attempt to use more or fewer values in aVALUES LESS THAN
clause than there are in theCOLUMNS
clause causes the statement to fail with the error Inconsistency in usage of column lists for partitioning.... You cannot useNULL
for any value appearing inVALUES LESS THAN
. It is possible to useMAXVALUE
more than once for a given column other than the first, as shown in this example:CREATE TABLE rc ( a INT NOT NULL, b INT NOT NULL ) PARTITION BY RANGE COLUMNS(a,b) ( PARTITION p0 VALUES LESS THAN (10,5), PARTITION p1 VALUES LESS THAN (20,10), PARTITION p2 VALUES LESS THAN (50,MAXVALUE), PARTITION p3 VALUES LESS THAN (65,MAXVALUE), PARTITION p4 VALUES LESS THAN (MAXVALUE,MAXVALUE) );
Each value used in a
VALUES LESS THAN
value list must match the type of the corresponding column exactly; no conversion is made. For example, you cannot use the string'1'
for a value that matches a column that uses an integer type (you must use the numeral1
instead), nor can you use the numeral1
for a value that matches a column that uses a string type (in such a case, you must use a quoted string:'1'
).For more information, see Section 24.2.1, “RANGE Partitioning”, and Section 24.4, “Partition Pruning”.
LIST(
expr
)This is useful when assigning partitions based on a table column with a restricted set of possible values, such as a state or country code. In such a case, all rows pertaining to a certain state or country can be assigned to a single partition, or a partition can be reserved for a certain set of states or countries. It is similar to
RANGE
, except that onlyVALUES IN
may be used to specify permissible values for each partition.VALUES IN
is used with a list of values to be matched. For instance, you could create a partitioning scheme such as the following:CREATE TABLE client_firms ( id INT, name VARCHAR(35) ) PARTITION BY LIST (id) ( PARTITION r0 VALUES IN (1, 5, 9, 13, 17, 21), PARTITION r1 VALUES IN (2, 6, 10, 14, 18, 22), PARTITION r2 VALUES IN (3, 7, 11, 15, 19, 23), PARTITION r3 VALUES IN (4, 8, 12, 16, 20, 24) );
When using list partitioning, you must define at least one partition using
VALUES IN
. You cannot useVALUES LESS THAN
withPARTITION BY LIST
.NoteFor tables partitioned by
LIST
, the value list used withVALUES IN
must consist of integer values only. In MySQL 8.0, you can overcome this limitation using partitioning byLIST COLUMNS
, which is described later in this section.LIST COLUMNS(
column_list
)This variant on
LIST
facilitates partition pruning for queries using comparison conditions on multiple columns (that is, having conditions such asWHERE a = 5 AND b = 5
orWHERE a = 1 AND b = 10 AND c = 5
). It enables you to specify values in multiple columns by using a list of columns in theCOLUMNS
clause and a set of column values in eachPARTITION ... VALUES IN (
partition definition clause.value_list
)The rules governing regarding data types for the column list used in
LIST COLUMNS(
and the value list used incolumn_list
)VALUES IN(
are the same as those for the column list used invalue_list
)RANGE COLUMNS(
and the value list used incolumn_list
)VALUES LESS THAN(
, respectively, except that in thevalue_list
)VALUES IN
clause,MAXVALUE
is not permitted, and you may useNULL
.There is one important difference between the list of values used for
VALUES IN
withPARTITION BY LIST COLUMNS
as opposed to when it is used withPARTITION BY LIST
. When used withPARTITION BY LIST COLUMNS
, each element in theVALUES IN
clause must be a set of column values; the number of values in each set must be the same as the number of columns used in theCOLUMNS
clause, and the data types of these values must match those of the columns (and occur in the same order). In the simplest case, the set consists of a single column. The maximum number of columns that can be used in thecolumn_list
and in the elements making up thevalue_list
is 16.The table defined by the following
CREATE TABLE
statement provides an example of a table usingLIST COLUMNS
partitioning:CREATE TABLE lc ( a INT NULL, b INT NULL ) PARTITION BY LIST COLUMNS(a,b) ( PARTITION p0 VALUES IN( (0,0), (NULL,NULL) ), PARTITION p1 VALUES IN( (0,1), (0,2), (0,3), (1,1), (1,2) ), PARTITION p2 VALUES IN( (1,0), (2,0), (2,1), (3,0), (3,1) ), PARTITION p3 VALUES IN( (1,3), (2,2), (2,3), (3,2), (3,3) ) );
PARTITIONS
num
The number of partitions may optionally be specified with a
PARTITIONS
clause, wherenum
num
is the number of partitions. If both this clause and anyPARTITION
clauses are used,num
must be equal to the total number of any partitions that are declared usingPARTITION
clauses.NoteWhether or not you use a
PARTITIONS
clause in creating a table that is partitioned byRANGE
orLIST
, you must still include at least onePARTITION VALUES
clause in the table definition (see below).SUBPARTITION BY
A partition may optionally be divided into a number of subpartitions. This can be indicated by using the optional
SUBPARTITION BY
clause. Subpartitioning may be done byHASH
orKEY
. Either of these may beLINEAR
. These work in the same way as previously described for the equivalent partitioning types. (It is not possible to subpartition byLIST
orRANGE
.)The number of subpartitions can be indicated using the
SUBPARTITIONS
keyword followed by an integer value.Rigorous checking of the value used in
PARTITIONS
orSUBPARTITIONS
clauses is applied and this value must adhere to the following rules:The value must be a positive, nonzero integer.
No leading zeros are permitted.
The value must be an integer literal, and cannot not be an expression. For example,
PARTITIONS 0.2E+01
is not permitted, even though0.2E+01
evaluates to2
. (Bug #15890)
partition_definition
Each partition may be individually defined using a
partition_definition
clause. The individual parts making up this clause are as follows:PARTITION
partition_name
Specifies a logical name for the partition.
VALUES
For range partitioning, each partition must include a
VALUES LESS THAN
clause; for list partitioning, you must specify aVALUES IN
clause for each partition. This is used to determine which rows are to be stored in this partition. See the discussions of partitioning types in Chapter 24, Partitioning, for syntax examples.[STORAGE] ENGINE
MySQL accepts a
[STORAGE] ENGINE
option for bothPARTITION
andSUBPARTITION
. Currently, the only way in which this option can be used is to set all partitions or all subpartitions to the same storage engine, and an attempt to set different storage engines for partitions or subpartitions in the same table raises the error ERROR 1469 (HY000): The mix of handlers in the partitions is not permitted in this version of MySQL.COMMENT
An optional
COMMENT
clause may be used to specify a string that describes the partition. Example:COMMENT = 'Data for the years previous to 1999'
The maximum length for a partition comment is 1024 characters.
DATA DIRECTORY
andINDEX DIRECTORY
DATA DIRECTORY
andINDEX DIRECTORY
may be used to indicate the directory where, respectively, the data and indexes for this partition are to be stored. Both the
and thedata_dir
must be absolute system path names.index_dir
As of MySQL 8.0.21, the directory specified in a
DATA DIRECTORY
clause must be known toInnoDB
. For more information, see Using the DATA DIRECTORY Clause.You must have the
FILE
privilege to use theDATA DIRECTORY
orINDEX DIRECTORY
partition option.Example:
CREATE TABLE th (id INT, name VARCHAR(30), adate DATE) PARTITION BY LIST(YEAR(adate)) ( PARTITION p1999 VALUES IN (1995, 1999, 2003) DATA DIRECTORY = '
/var/appdata/95/data
' INDEX DIRECTORY = '/var/appdata/95/idx
', PARTITION p2000 VALUES IN (1996, 2000, 2004) DATA DIRECTORY = '/var/appdata/96/data
' INDEX DIRECTORY = '/var/appdata/96/idx
', PARTITION p2001 VALUES IN (1997, 2001, 2005) DATA DIRECTORY = '/var/appdata/97/data
' INDEX DIRECTORY = '/var/appdata/97/idx
', PARTITION p2002 VALUES IN (1998, 2002, 2006) DATA DIRECTORY = '/var/appdata/98/data
' INDEX DIRECTORY = '/var/appdata/98/idx
' );DATA DIRECTORY
andINDEX DIRECTORY
behave in the same way as in theCREATE TABLE
statement'stable_option
clause as used forMyISAM
tables.One data directory and one index directory may be specified per partition. If left unspecified, the data and indexes are stored by default in the table's database directory.
The
DATA DIRECTORY
andINDEX DIRECTORY
options are ignored for creating partitioned tables ifNO_DIR_IN_CREATE
is in effect.MAX_ROWS
andMIN_ROWS
May be used to specify, respectively, the maximum and minimum number of rows to be stored in the partition. The values for
max_number_of_rows
andmin_number_of_rows
must be positive integers. As with the table-level options with the same names, these act only as “suggestions” to the server and are not hard limits.TABLESPACE
May be used to designate an
InnoDB
file-per-table tablespace for the partition by specifyingTABLESPACE `innodb_file_per_table`
. All partitions must belong to the same storage engine.Placing
InnoDB
table partitions in sharedInnoDB
tablespaces is not supported. Shared tablespaces include theInnoDB
system tablespace and general tablespaces.
subpartition_definition
The partition definition may optionally contain one or more
subpartition_definition
clauses. Each of these consists at a minimum of theSUBPARTITION
, wherename
name
is an identifier for the subpartition. Except for the replacement of thePARTITION
keyword withSUBPARTITION
, the syntax for a subpartition definition is identical to that for a partition definition.Subpartitioning must be done by
HASH
orKEY
, and can be done only onRANGE
orLIST
partitions. See Section 24.2.6, “Subpartitioning”.
Partitioning by Generated Columns
Partitioning by generated columns is permitted. For example:
CREATE TABLE t1 ( s1 INT, s2 INT AS (EXP(s1)) STORED ) PARTITION BY LIST (s2) ( PARTITION p1 VALUES IN (1) );
Partitioning sees a generated column as a regular column, which
enables workarounds for limitations on functions that are not
permitted for partitioning (see
Section 24.6.3, “Partitioning Limitations Relating to Functions”). The
preceding example demonstrates this technique:
EXP()
cannot be used directly in
the PARTITION BY
clause, but a generated column
defined using EXP()
is permitted.
For an InnoDB
table created in a
file-per-table tablespace or general tablespace, table data and
associated indexes are stored in a
.ibd file in the database
directory. When an InnoDB
table is created in
the system tablespace, table data and indexes are stored in the
ibdata* files that
represent the system tablespace. The
innodb_file_per_table
option
controls whether tables are created in file-per-table
tablespaces or the system tablespace, by default. The
TABLESPACE
option can be used to place a
table in a file-per-table tablespace, general tablespace, or the
system tablespace, regardless of the
innodb_file_per_table
setting.
For MyISAM
tables, the storage engine creates
data and index files. Thus, for each MyISAM
table tbl_name
, there are two disk
files.
File | Purpose |
---|---|
|
Data file |
|
Index file |
Chapter 16, Alternative Storage Engines, describes what files each storage engine creates to represent tables. If a table name contains special characters, the names for the table files contain encoded versions of those characters as described in Section 9.2.4, “Mapping of Identifiers to File Names”.
You can use the TEMPORARY
keyword when
creating a table. A TEMPORARY
table is
visible only within the current session, and is dropped
automatically when the session is closed. This means that two
different sessions 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.)
InnoDB
does not support compressed temporary
tables. When innodb_strict_mode
is enabled (the default),
CREATE TEMPORARY
TABLE
returns an error if
ROW_FORMAT=COMPRESSED
or
KEY_BLOCK_SIZE
is specified. If
innodb_strict_mode
is disabled,
warnings are issued and the temporary table is created using a
non-compressed row format. The
innodb_file_per-table
option
does not affect the creation of InnoDB
temporary tables.
CREATE TABLE
causes an implicit
commit, except when used with the TEMPORARY
keyword. See Section 13.3.3, “Statements That Cause an Implicit Commit”.
TEMPORARY
tables have a very loose
relationship with databases (schemas). Dropping a database does
not automatically drop any TEMPORARY
tables
created within that database.
To create a temporary table, you must have the
CREATE TEMPORARY TABLES
privilege. After a session has created a temporary table, the
server performs no further privilege checks on the table. The
creating session can perform any operation on the table, such as
DROP TABLE
,
INSERT
,
UPDATE
, or
SELECT
.
One implication of this behavior is that a session can
manipulate its temporary tables even if the current user has no
privilege to create them. Suppose that the current user does not
have the CREATE TEMPORARY TABLES
privilege but is able to execute a definer-context stored
procedure that executes with the privileges of a user who does
have CREATE TEMPORARY TABLES
and
that creates a temporary table. While the procedure executes,
the session uses the privileges of the defining user. After the
procedure returns, the effective privileges revert to those of
the current user, which can still see the temporary table and
perform any operation on it.
You cannot use CREATE TEMPORY TABLE ... LIKE
to create an empty table based on the definition of a table that
resides in the mysql
tablespace,
InnoDB
system tablespace
(innodb_system
), or a general tablespace. The
tablespace definition for such a table includes a
TABLESPACE
attribute that defines the
tablespace where the table resides, and the aforementioned
tablespaces do not support temporary tables. To create a
temporary table based on the definition of such a table, use
this syntax instead:
CREATE TEMPORARY TABLEnew_tbl
SELECT * FROMorig_tbl
LIMIT 0;
Support for TABLESPACE =
innodb_file_per_table
and TABLESPACE =
innodb_temporary
clauses with
CREATE TEMPORARY
TABLE
is deprecated as of MySQL 8.0.13; expect it be
removed in a future version of MySQL.
Use CREATE TABLE ... 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 TABLEnew_tbl
LIKEorig_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.
You cannot execute CREATE TABLE
or
CREATE TABLE ... LIKE
while a
LOCK TABLES
statement is in
effect.
CREATE TABLE ...
LIKE
makes the same checks as
CREATE TABLE
. This means that
if the current SQL mode is different from the mode in effect
when the original table was created, the table definition
might be considered invalid for the new mode and cause the
statement to fail.
For CREATE TABLE ... LIKE
, the destination
table preserves generated column information from the original
table.
For CREATE TABLE ... LIKE
, the destination
table preserves expression default values from the original
table.
For CREATE TABLE ... LIKE
, the destination
table preserves CHECK
constraints from the
original table, except that all the constraint names are
generated.
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
.
Tables created in the mysql
tablespace, the
InnoDB
system tablespace
(innodb_system
), or general tablespaces
include a TABLESPACE
attribute in the table
definition, which defines the tablespace where the table
resides. Due to a temporary regression, CREATE TABLE
... LIKE
preserves the TABLESPACE
attribute and creates the table in the defined tablespace
regardless of the
innodb_file_per_table
setting.
To avoid the TABLESPACE
attribute when
creating an empty table based on the definition of such a table,
use this syntax instead:
CREATE TABLEnew_tbl
SELECT * FROMorig_tbl
LIMIT 0;
CREATE TABLE
... LIKE
operations apply all
ENGINE_ATTRIBUTE
and
SECONDARY_ENGINE_ATTRIBUTE
values to the new
table.
You can create one table from another by adding a
SELECT
statement at the end of
the CREATE TABLE
statement:
CREATE TABLEnew_tbl
[AS] SELECT * FROMorig_tbl
;
MySQL creates new columns for all elements in the
SELECT
. For example:
mysql>CREATE TABLE test (a INT NOT NULL AUTO_INCREMENT,
->PRIMARY KEY (a), KEY(b))
->ENGINE=MyISAM SELECT b,c FROM test2;
This creates a MyISAM
table with
three columns, a
, b
, and
c
. The ENGINE
option is
part of the CREATE TABLE
statement, and should not be used following the
SELECT
; this would result in a
syntax error. The same is true for other
CREATE TABLE
options such as
CHARSET
.
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 errors occur while copying data to the table, the table is
automatically dropped and not created. However, prior to MySQL
8.0.21, when row-based replication is in use, a
CREATE
TABLE ... SELECT
statement is recorded in the binary
log as two transactions, one to create the table, and the other
to insert data. When the statement applied from the binary log,
a failure between the two transactions or while copying data can
result in replication of an empty table. That limitation is
removed in MySQL 8.0.21. On storage engines that support atomic
DDL, CREATE
TABLE ... SELECT
is now recorded and applied as one
transaction when row-based replication is in use. For more
information, see Section 13.1.1, “Atomic Data Definition Statement Support”.
As of MySQL 8.0.21, on storage engines that support both atomic
DDL and foreign key constraints, creation of foreign keys is not
permitted in
CREATE
TABLE ... SELECT
statements when row-based replication
is in use. Foreign key constraints can be added later using
ALTER TABLE
.
You can precede the SELECT
by
IGNORE
or REPLACE
to
indicate how to handle rows that duplicate unique key values.
With IGNORE
, 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. For more information, see
The Effect of IGNORE on Statement Execution.
In MySQL 8.0.19 and later, you can also use a
VALUES
statement in the
SELECT
part of CREATE
TABLE ... SELECT
; the VALUES
portion of the statement must include a table alias using an
AS
clause. To name the columns coming from
VALUES
, supply column aliases with the table
alias; otherwise, the default column names
column_0
, column_1
,
column_2
, ..., are used.
Otherwise, naming of columns in the table thus created follows the same rules as described previously in this section. Examples:
mysql>CREATE TABLE tv1
>SELECT * FROM (VALUES ROW(1,3,5), ROW(2,4,6)) AS v;
mysql>TABLE tv1;
+----------+----------+----------+ | column_0 | column_1 | column_2 | +----------+----------+----------+ | 1 | 3 | 5 | | 2 | 4 | 6 | +----------+----------+----------+ mysql> CREATE TABLE tv2 > SELECT * FROM (VALUES ROW(1,3,5), ROW(2,4,6)) AS v(x,y,z); mysql>TABLE tv2;
+---+---+---+ | x | y | z | +---+---+---+ | 1 | 3 | 5 | | 2 | 4 | 6 | +---+---+---+ mysql>CREATE TABLE tv3 (a INT, b INT, c INT)
>SELECT * FROM (VALUES ROW(1,3,5), ROW(2,4,6)) AS v(x,y,z);
mysql> TABLE tv3; +------+------+------+----------+----------+----------+ | a | b | c | column_0 | column_1 | column_2 | +------+------+------+----------+----------+----------+ | NULL | NULL | NULL | 1 | 3 | 5 | | NULL | NULL | NULL | 2 | 4 | 6 | +------+------+------+----------+----------+----------+ mysql>CREATE TABLE tv4 (a INT, b INT, c INT)
>SELECT * FROM (VALUES ROW(1,3,5), ROW(2,4,6)) AS v(x,y,z);
mysql>TABLE tv4;
+------+------+------+---+---+---+ | a | b | c | x | y | z | +------+------+------+---+---+---+ | NULL | NULL | NULL | 1 | 3 | 5 | | NULL | NULL | NULL | 2 | 4 | 6 | +------+------+------+---+---+---+ mysql>CREATE TABLE tv5 (a INT, b INT, c INT)
>SELECT * FROM (VALUES ROW(1,3,5), ROW(2,4,6)) AS v(a,b,c);
mysql>TABLE tv5;
+------+------+------+ | a | b | c | +------+------+------+ | 1 | 3 | 5 | | 2 | 4 | 6 | +------+------+------+
When selecting all columns and using the default column names,
you can omit SELECT *
, so the statement just
used to create table tv1
can also be written
as shown here:
mysql>CREATE TABLE tv1 VALUES ROW(1,3,5), ROW(2,4,6);
mysql>TABLE tv1;
+----------+----------+----------+ | column_0 | column_1 | column_2 | +----------+----------+----------+ | 1 | 3 | 5 | | 2 | 4 | 6 | +----------+----------+----------+
When using VALUES
as the source
of the SELECT
, all columns are
always selected into the new table, and individual columns
cannot be selected as they can be when selecting from a named
table; each of the following statements produces an error
(ER_OPERAND_COLUMNS
):
CREATE TABLE tvx SELECT (x,z) FROM (VALUES ROW(1,3,5), ROW(2,4,6)) AS v(x,y,z); CREATE TABLE tvx (a INT, c INT) SELECT (x,z) FROM (VALUES ROW(1,3,5), ROW(2,4,6)) AS v(x,y,z);
Similarly, you can use a TABLE
statement in place of the SELECT
.
This follows the same rules as with
VALUES
; all columns of the source
table and their names in the source table are always inserted
into the new table. Examples:
mysql>TABLE t1;
+----+----+ | a | b | +----+----+ | 1 | 2 | | 6 | 7 | | 10 | -4 | | 14 | 6 | +----+----+ mysql>CREATE TABLE tt1 TABLE t1;
mysql>TABLE tt1;
+----+----+ | a | b | +----+----+ | 1 | 2 | | 6 | 7 | | 10 | -4 | | 14 | 6 | +----+----+ mysql>CREATE TABLE tt2 (x INT) TABLE t1;
mysql>TABLE tt2;
+------+----+----+ | x | a | b | +------+----+----+ | NULL | 1 | 2 | | NULL | 6 | 7 | | NULL | 10 | -4 | | NULL | 14 | 6 | +------+----+----+
Because the ordering of the rows in the underlying
SELECT
statements cannot always
be determined, CREATE TABLE ... IGNORE SELECT
and CREATE TABLE ... REPLACE SELECT
statements are flagged as unsafe for statement-based
replication. Such statements produce a warning in the error log
when using statement-based mode and are written to the binary
log using the row-based format when using
MIXED
mode. See also
Section 17.2.1.1, “Advantages and Disadvantages of Statement-Based and Row-Based
Replication”.
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;
For CREATE TABLE ... SELECT
, the destination
table does not preserve information about whether columns in the
selected-from table are generated columns. The
SELECT
part of the statement
cannot assign values to generated columns in the destination
table.
For CREATE TABLE ... SELECT
, the destination
table does preserve expression default values from the original
table.
Some conversion of data types might occur. For example, the
AUTO_INCREMENT
attribute is not preserved,
and VARCHAR
columns can become
CHAR
columns. Retrained
attributes are NULL
(or NOT
NULL
) and, for those columns that have them,
CHARACTER SET
, COLLATION
,
COMMENT
, and the DEFAULT
clause.
When creating a table with
CREATE
TABLE ... SELECT
, make sure to alias any function
calls or expressions in the query. If you do not, the
CREATE
statement might fail or result in
undesirable column names.
CREATE TABLE artists_and_works SELECT artist.name, COUNT(work.artist_id) AS number_of_works FROM artist LEFT JOIN work ON artist.id = work.artist_id GROUP BY artist.id;
You can also explicitly specify the data type for a column in the created table:
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 target table exists, nothing is inserted into the
destination table, and the statement is not logged.
To ensure that the binary log can be used to re-create the
original tables, MySQL does not permit concurrent inserts during
CREATE TABLE ...
SELECT
. However, prior to MySQL 8.0.21, when a
CREATE TABLE ...
SELECT
operation is applied from the binary log when
row-based replication is in use, concurrent inserts are
permitted on the replicated table while copying data. That
limitation is removed in MySQL 8.0.21 on storage engines that
support atomic DDL. For more information, see
Section 13.1.1, “Atomic Data Definition Statement Support”.
You cannot use FOR UPDATE
as part of the
SELECT
in a statement such as
CREATE
TABLE
. If you
attempt to do so, the statement fails.
new_table
SELECT ... FROM
old_table
...
CREATE
TABLE ... SELECT
operations apply
ENGINE_ATTRIBUTE
and
SECONDARY_ENGINE_ATTRIBUTE
values to columns
only. Table and index ENGINE_ATTRIBUTE
and
SECONDARY_ENGINE_ATTRIBUTE
values are not
applied to the new table unless specified explicitly.
MySQL supports foreign keys, which permit cross-referencing related data across tables, and foreign key constraints, which help keep the related data consistent.
A foreign key relationship involves a parent table that holds the initial column values, and a child table with column values that reference the parent column values. A foreign key constraint is defined on the child table.
The essential syntax for a defining a foreign key constraint in
a CREATE TABLE
or
ALTER TABLE
statement includes
the following:
[CONSTRAINT [symbol
]] FOREIGN KEY [index_name
] (col_name
, ...) REFERENCEStbl_name
(col_name
,...) [ON DELETEreference_option
] [ON UPDATEreference_option
]reference_option
: RESTRICT | CASCADE | SET NULL | NO ACTION | SET DEFAULT
Foreign key constraint usage is described under the following topics in this section:
Foreign key constraint naming is governed by the following rules:
The
CONSTRAINT
symbol
value is used, if defined.If the
CONSTRAINT
symbol
clause is not defined, or a symbol is not included following theCONSTRAINT
keyword, a constraint name name is generated automatically.Prior to MySQL 8.0.16, if the
CONSTRAINT
symbol
clause was not defined, or a symbol was not included following theCONSTRAINT
keyword, bothInnoDB
andNDB
storage engines would use theFOREIGN_KEY
if defined. In MySQL 8.0.16 and higher, theindex_name
FOREIGN_KEY
is ignored.index_name
The
CONSTRAINT
value, if defined, must be unique in the database. A duplicatesymbol
symbol
results in an error similar to: ERROR 1005 (HY000): Can't create table 'test.fk1' (errno: 121).NDB Cluster stores foreign names using the same lettercase with which they are created. Prior to version 8.0.20, when processing
SELECT
and other SQL statements,NDB
compared the names of foreign keys in such statements with the names as stored in a case-sensitive fashion whenlower_case_table_names
was equal to 0. In NDB 8.0.20 and later, this value no longer has any effect on how such comparisons are made, and they are always done without regard to lettercase. (Bug #30512043)
Table and column identifiers in a FOREIGN KEY ...
REFERENCES
clause can be quoted within backticks
(`
). Alternatively, double quotation marks
("
) can be used if the
ANSI_QUOTES
SQL mode is
enabled. The
lower_case_table_names
system
variable setting is also taken into account.
Foreign key constraints are subject to the following conditions and restrictions:
Parent and child tables must use the same storage engine, and they cannot be defined as temporary tables.
Creating a foreign key constraint requires the
REFERENCES
privilege on the parent table.Corresponding columns in the foreign key and the referenced key must have similar data types. The size and sign of fixed precision types such as
INTEGER
andDECIMAL
must be the same. The length of string types need not be the same. For nonbinary (character) string columns, the character set and collation must be the same.MySQL supports foreign key references between one column and another within a table. (A column cannot have a foreign key reference to itself.) In these cases, a “child table record” refers to a dependent record within the same table.
MySQL requires indexes on foreign keys and referenced keys so that foreign key checks can be fast and not require a table scan. In the referencing table, there must be an index where the foreign key columns are listed as the first columns in the same order. Such an index is created on the referencing table automatically if it does not exist. This index might be silently dropped later if you create another index that can be used to enforce the foreign key constraint.
index_name
, if given, is used as described previously.InnoDB
permits a foreign key to reference any index column or group of columns. However, in the referenced table, there must be an index where the referenced columns are the first columns in the same order. Hidden columns thatInnoDB
adds to an index are also considered (see Section 15.6.2.1, “Clustered and Secondary Indexes”).NDB
requires an explicit unique key (or primary key) on any column referenced as a foreign key.InnoDB
does not, which is an extension of standard SQL.Index prefixes on foreign key columns are not supported. Consequently,
BLOB
andTEXT
columns cannot be included in a foreign key because indexes on those columns must always include a prefix length.InnoDB
does not currently support foreign keys for tables with user-defined partitioning. This includes both parent and child tables.This restriction does not apply for
NDB
tables that are partitioned byKEY
orLINEAR KEY
(the only user partitioning types supported by theNDB
storage engine); these may have foreign key references or be the targets of such references.A table in a foreign key relationship cannot be altered to use another storage engine. To change the storage engine, you must drop any foreign key constraints first.
A foreign key constraint cannot reference a virtual generated column.
For information about how the MySQL implementation of foreign key constraints differs from the SQL standard, see Section 1.7.2.3, “FOREIGN KEY Constraint Differences”.
When an UPDATE
or
DELETE
operation affects a key
value in the parent table that has matching rows in the child
table, the result depends on the referential
action specified by ON UPDATE
and ON DELETE
subclauses of the
FOREIGN KEY
clause. Referential actions
include:
CASCADE
: Delete or update the row from the parent table and automatically delete or update the matching rows in the child table. BothON DELETE CASCADE
andON UPDATE CASCADE
are supported. Between two tables, do not define severalON UPDATE CASCADE
clauses that act on the same column in the parent table or in the child table.If a
FOREIGN KEY
clause is defined on both tables in a foreign key relationship, making both tables a parent and child, anON UPDATE CASCADE
orON DELETE CASCADE
subclause defined for oneFOREIGN KEY
clause must be defined for the other in order for cascading operations to succeed. If anON UPDATE CASCADE
orON DELETE CASCADE
subclause is only defined for oneFOREIGN KEY
clause, cascading operations fail with an error.NoteCascaded foreign key actions do not activate triggers.
SET NULL
: Delete or update the row from the parent table and set the foreign key column or columns in the child table toNULL
. BothON DELETE SET NULL
andON UPDATE SET NULL
clauses are supported.If you specify a
SET NULL
action, make sure that you have not declared the columns in the child table asNOT NULL
.RESTRICT
: Rejects the delete or update operation for the parent table. SpecifyingRESTRICT
(orNO ACTION
) is the same as omitting theON DELETE
orON UPDATE
clause.NO ACTION
: A keyword from standard SQL. In MySQL, equivalent toRESTRICT
. The MySQL Server rejects the delete or update operation for the parent table if there is a related foreign key value in the referenced table. Some database systems have deferred checks, andNO ACTION
is a deferred check. In MySQL, foreign key constraints are checked immediately, soNO ACTION
is the same asRESTRICT
.SET DEFAULT
: This action is recognized by the MySQL parser, but bothInnoDB
andNDB
reject table definitions containingON DELETE SET DEFAULT
orON UPDATE SET DEFAULT
clauses.
For storage engines that support foreign keys, MySQL rejects
any INSERT
or
UPDATE
operation that attempts
to create a foreign key value in a child table if there is no
matching candidate key value in the parent table.
For an ON DELETE
or ON
UPDATE
that is not specified, the default action is
always NO ACTION
.
As the default, an ON DELETE NO ACTION
or
ON UPDATE NO ACTION
clause that is
specified explicitly does not appear in
SHOW CREATE TABLE
output or in
tables dumped with mysqldump.
RESTRICT
, which is an equivalent
non-default keyword, appears in SHOW
CREATE TABLE
output and in tables dumped with
mysqldump.
For NDB
tables, ON
UPDATE CASCADE
is not supported where the reference
is to the parent table's primary key.
As of NDB 8.0.16: For NDB
tables,
ON DELETE CASCADE
is not supported where
the child table contains one or more columns of any of the
TEXT
or
BLOB
types. (Bug #89511, Bug
#27484882)
InnoDB
performs cascading operations using
a depth-first search algorithm on the records of the index
that corresponds to the foreign key constraint.
A foreign key constraint on a stored generated column cannot
use CASCADE
, SET NULL
,
or SET DEFAULT
as ON
UPDATE
referential actions, nor can it use
SET NULL
or SET DEFAULT
as ON DELETE
referential actions.
A foreign key constraint on the base column of a stored
generated column cannot use CASCADE
,
SET NULL
, or SET DEFAULT
as ON UPDATE
or ON
DELETE
referential actions.
This simple example relates parent
and
child
tables through a single-column
foreign key:
CREATE TABLE parent ( id INT NOT NULL, PRIMARY KEY (id) ) ENGINE=INNODB; CREATE TABLE child ( id INT, parent_id INT, INDEX par_ind (parent_id), FOREIGN KEY (parent_id) REFERENCES parent(id) ON DELETE CASCADE ) ENGINE=INNODB;
This is a more complex example in which a
product_order
table has foreign keys for
two other tables. One foreign key references a two-column
index in the product
table. The other
references a single-column index in the
customer
table:
CREATE TABLE product ( category INT NOT NULL, id INT NOT NULL, price DECIMAL, PRIMARY KEY(category, id) ) ENGINE=INNODB; CREATE TABLE customer ( id INT NOT NULL, PRIMARY KEY (id) ) ENGINE=INNODB; CREATE TABLE product_order ( no INT NOT NULL AUTO_INCREMENT, product_category INT NOT NULL, product_id INT NOT NULL, customer_id INT NOT NULL, PRIMARY KEY(no), INDEX (product_category, product_id), INDEX (customer_id), FOREIGN KEY (product_category, product_id) REFERENCES product(category, id) ON UPDATE CASCADE ON DELETE RESTRICT, FOREIGN KEY (customer_id) REFERENCES customer(id) ) ENGINE=INNODB;
You can add a foreign key constraint to an existing table
using the following ALTER TABLE
syntax:
ALTER TABLEtbl_name
ADD [CONSTRAINT [symbol
]] FOREIGN KEY [index_name
] (col_name
, ...) REFERENCEStbl_name
(col_name
,...) [ON DELETEreference_option
] [ON UPDATEreference_option
]
The foreign key can be self referential (referring to the same
table). When you add a foreign key constraint to a table using
ALTER TABLE
, remember
to first create an index on the column(s) referenced by the
foreign key.
You can drop a foreign key constraint using the following
ALTER TABLE
syntax:
ALTER TABLEtbl_name
DROP FOREIGN KEYfk_symbol
;
If the FOREIGN KEY
clause defined a
CONSTRAINT
name when you created the
constraint, you can refer to that name to drop the foreign key
constraint. Otherwise, a constraint name was generated
internally, and you must use that value. To determine the
foreign key constraint name, use SHOW
CREATE TABLE
:
mysql>SHOW CREATE TABLE child\G
*************************** 1. row *************************** Table: child Create Table: CREATE TABLE `child` ( `id` int DEFAULT NULL, `parent_id` int DEFAULT NULL, KEY `par_ind` (`parent_id`), CONSTRAINT `child_ibfk_1` FOREIGN KEY (`parent_id`) REFERENCES `parent` (`id`) ON DELETE CASCADE ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci mysql>ALTER TABLE child DROP FOREIGN KEY `child_ibfk_1`;
Adding and dropping a foreign key in the same
ALTER TABLE
statement is
supported for
ALTER TABLE ...
ALGORITHM=INPLACE
. It is not supported for
ALTER TABLE ...
ALGORITHM=COPY
.
Foreign key checking is controlled by the
foreign_key_checks
variable,
which is enabled by default. Typically, you leave this
variable enabled during normal operation to enforce
referential integrity. The
foreign_key_checks
variable
has the same effect on NDB
tables
as it does for InnoDB
tables.
The foreign_key_checks
variable is dynamic and supports both global and session
scopes. For information about using system variables, see
Section 5.1.9, “Using System Variables”.
Disabling foreign key checking is useful when:
Dropping a table that is referenced by a foreign key constraint. A referenced table can only be dropped after
foreign_key_checks
is disabled. When you drop a table, constraints defined on the table are also dropped.Reloading tables in different order than required by their foreign key relationships. For example, mysqldump produces correct definitions of tables in the dump file, including foreign key constraints for child tables. To make it easier to reload dump files for tables with foreign key relationships, mysqldump automatically includes a statement in the dump output that disables
foreign_key_checks
. This enables you to import the tables in any order in case the dump file contains tables that are not correctly ordered for foreign keys. Disablingforeign_key_checks
also speeds up the import operation by avoiding foreign key checks.Executing
LOAD DATA
operations, to avoid foreign key checking.Performing an
ALTER TABLE
operation on a table that has a foreign key relationship.
When foreign_key_checks
is
disabled, foreign key constraints are ignored, with the
following exceptions:
Recreating a table that was previously dropped returns an error if the table definition does not conform to the foreign key constraints that reference the table. The table must have the correct column names and types. It must also have indexes on the referenced keys. If these requirements are not satisfied, MySQL returns Error 1005 that refers to errno: 150 in the error message, which means that a foreign key constraint was not correctly formed.
Altering a table returns an error (errno: 150) if a foreign key definition is incorrectly formed for the altered table.
Dropping an index required by a foreign key constraint. The foreign key constraint must be removed before dropping the index.
Creating a foreign key constraint where a column references a nonmatching column type.
Disabling foreign_key_checks
has these additional implications:
It is permitted to drop a database that contains tables with foreign keys that are referenced by tables outside the database.
It is permitted to drop a table with foreign keys referenced by other tables.
Enabling
foreign_key_checks
does not trigger a scan of table data, which means that rows added to a table whileforeign_key_checks
is disabled are not checked for consistency whenforeign_key_checks
is re-enabled.
MySQL extends metadata locks, as necessary, to tables that are related by a foreign key constraint. Extending metadata locks prevents conflicting DML and DDL operations from executing concurrently on related tables. This feature also enables updates to foreign key metadata when a parent table is modified. In earlier MySQL releases, foreign key metadata, which is owned by the child table, could not be updated safely.
If a table is locked explicitly with LOCK
TABLES
, any tables related by a foreign key
constraint are opened and locked implicitly. For foreign key
checks, a shared read-only lock
(LOCK TABLES
READ
) is taken on related tables. For cascading
updates, a shared-nothing write lock
(LOCK TABLES
WRITE
) is taken on related tables that are involved
in the operation.
To view a foreign key definition, use
SHOW CREATE TABLE
:
mysql> SHOW CREATE TABLE child\G
*************************** 1. row ***************************
Table: child
Create Table: CREATE TABLE `child` (
`id` int DEFAULT NULL,
`parent_id` int DEFAULT NULL,
KEY `par_ind` (`parent_id`),
CONSTRAINT `child_ibfk_1` FOREIGN KEY (`parent_id`)
REFERENCES `parent` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
You can obtain information about foreign keys from the
INFORMATION_SCHEMA.KEY_COLUMN_USAGE
table. An example of a query against this table is shown here:
mysql>SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, CONSTRAINT_NAME
FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
WHERE REFERENCED_TABLE_SCHEMA IS NOT NULL;
+--------------+------------+-------------+-----------------+ | TABLE_SCHEMA | TABLE_NAME | COLUMN_NAME | CONSTRAINT_NAME | +--------------+------------+-------------+-----------------+ | test | child | parent_id | child_ibfk_1 | +--------------+------------+-------------+-----------------+
You can obtain information specific to
InnoDB
foreign keys from the
INNODB_FOREIGN
and
INNODB_FOREIGN_COLS
tables.
Example queries are show here:
mysql>SELECT * FROM INFORMATION_SCHEMA.INNODB_FOREIGN \G
*************************** 1. row *************************** ID: test/child_ibfk_1 FOR_NAME: test/child REF_NAME: test/parent N_COLS: 1 TYPE: 1 mysql>SELECT * FROM INFORMATION_SCHEMA.INNODB_FOREIGN_COLS \G
*************************** 1. row *************************** ID: test/child_ibfk_1 FOR_COL_NAME: parent_id REF_COL_NAME: id POS: 0
In the event of a foreign key error involving
InnoDB
tables (usually Error 150 in the
MySQL Server), information about the latest foreign key error
can be obtained by checking
SHOW ENGINE
INNODB STATUS
output.
mysql> SHOW ENGINE INNODB STATUS\G ... ------------------------ LATEST FOREIGN KEY ERROR ------------------------ 2018-04-12 14:57:24 0x7f97a9c91700 Transaction: TRANSACTION 7717, ACTIVE 0 sec inserting mysql tables in use 1, locked 1 4 lock struct(s), heap size 1136, 3 row lock(s), undo log entries 3 MySQL thread id 8, OS thread handle 140289365317376, query id 14 localhost root update INSERT INTO child VALUES (NULL, 1), (NULL, 2), (NULL, 3), (NULL, 4), (NULL, 5), (NULL, 6) Foreign key constraint fails for table `test`.`child`: , CONSTRAINT `child_ibfk_1` FOREIGN KEY (`parent_id`) REFERENCES `parent` (`id`) ON DELETE CASCADE ON UPDATE CASCADE Trying to add in child table, in index par_ind tuple: DATA TUPLE: 2 fields; 0: len 4; hex 80000003; asc ;; 1: len 4; hex 80000003; asc ;; But in parent table `test`.`parent`, in index PRIMARY, the closest match we can find is record: PHYSICAL RECORD: n_fields 3; compact format; info bits 0 0: len 4; hex 80000004; asc ;; 1: len 6; hex 000000001e19; asc ;; 2: len 7; hex 81000001110137; asc 7;; ...
If a user has table-level privileges for all parent tables,
ER_NO_REFERENCED_ROW_2
and
ER_ROW_IS_REFERENCED_2
error
messages for foreign key operations expose information about
parent tables. If a user does not have table-level
privileges for all parent tables, more generic error
messages are displayed instead
(ER_NO_REFERENCED_ROW
and
ER_ROW_IS_REFERENCED
).
An exception is that, for stored programs defined to execute
with DEFINER
privileges, the user against
which privileges are assessed is the user in the program
DEFINER
clause, not the invoking user. If
that user has table-level parent table privileges, parent
table information is still displayed. In this case, it is
the responsibility of the stored program creator to hide the
information by including appropriate condition handlers.
Prior to MySQL 8.0.16, CREATE
TABLE
permits only the following limited version of
table CHECK
constraint syntax, which is
parsed and ignored:
CHECK (expr
)
As of MySQL 8.0.16, CREATE TABLE
permits the core features of table and column
CHECK
constraints, for all storage engines.
CREATE TABLE
permits the
following CHECK
constraint syntax, for both
table constraints and column constraints:
[CONSTRAINT [symbol
]] CHECK (expr
) [[NOT] ENFORCED]
The optional symbol
specifies a name
for the constraint. If omitted, MySQL generates a name from the
table name, a literal _chk_
, and an ordinal
number (1, 2, 3, ...). Constraint names have a maximum length of
64 characters. They are case-sensitive, but not
accent-sensitive.
expr
specifies the constraint
condition as a boolean expression that must evaluate to
TRUE
or UNKNOWN
(for
NULL
values) for each row of the table. If
the condition evaluates to FALSE
, it fails
and a constraint violation occurs. The effect of a violation
depends on the statement being executed, as described later in
this section.
The optional enforcement clause indicates whether the constraint is enforced:
If omitted or specified as
ENFORCED
, the constraint is created and enforced.If specified as
NOT ENFORCED
, the constraint is created but not enforced.
A CHECK
constraint is specified as either a
table constraint or column constraint:
A table constraint does not appear within a column definition and can refer to any table column or columns. Forward references are permitted to columns appearing later in the table definition.
A column constraint appears within a column definition and can refer only to that column.
Consider this table definition:
CREATE TABLE t1 ( CHECK (c1 <> c2), c1 INT CHECK (c1 > 10), c2 INT CONSTRAINT c2_positive CHECK (c2 > 0), c3 INT CHECK (c3 < 100), CONSTRAINT c1_nonzero CHECK (c1 <> 0), CHECK (c1 > c3) );
The definition includes table constraints and column constraints, in named and unnamed formats:
The first constraint is a table constraint: It occurs outside any column definition, so it can (and does) refer to multiple table columns. This constraint contains forward references to columns not defined yet. No constraint name is specified, so MySQL generates a name.
The next three constraints are column constraints: Each occurs within a column definition, and thus can refer only to the column being defined. One of the constraints is named explicitly. MySQL generates a name for each of the other two.
The last two constraints are table constraints. One of them is named explicitly. MySQL generates a name for the other one.
As mentioned, MySQL generates a name for any
CHECK
constraint specified without one. To
see the names generated for the preceding table definition, use
SHOW CREATE TABLE
:
mysql> SHOW CREATE TABLE t1\G
*************************** 1. row ***************************
Table: t1
Create Table: CREATE TABLE `t1` (
`c1` int(11) DEFAULT NULL,
`c2` int(11) DEFAULT NULL,
`c3` int(11) DEFAULT NULL,
CONSTRAINT `c1_nonzero` CHECK ((`c1` <> 0)),
CONSTRAINT `c2_positive` CHECK ((`c2` > 0)),
CONSTRAINT `t1_chk_1` CHECK ((`c1` <> `c2`)),
CONSTRAINT `t1_chk_2` CHECK ((`c1` > 10)),
CONSTRAINT `t1_chk_3` CHECK ((`c3` < 100)),
CONSTRAINT `t1_chk_4` CHECK ((`c1` > `c3`))
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
The SQL standard specifies that all types of constraints
(primary key, unique index, foreign key, check) belong to the
same namespace. In MySQL, each constraint type has its own
namespace per schema (database). Consequently,
CHECK
constraint names must be unique per
schema; no two tables in the same schema can share a
CHECK
constraint name. (Exception: A
TEMPORARY
table hides a
non-TEMPORARY
table of the same name, so it
can have the same CHECK
constraint names as
well.)
Beginning generated constraint names with the table name helps ensure schema uniqueness because table names also must be unique within the schema.
CHECK
condition expressions must adhere to
the following rules. An error occurs if an expression contains
disallowed constructs.
Nongenerated and generated columns are permitted, except columns with the
AUTO_INCREMENT
attribute and columns in other tables.Literals, deterministic built-in functions, and operators are permitted. A function is deterministic if, given the same data in tables, multiple invocations produce the same result, independently of the connected user. Examples of functions that are nondeterministic and fail this definition:
CONNECTION_ID()
,CURRENT_USER()
,NOW()
.Stored functions and user-defined functions are not permitted.
Stored procedure and function parameters are not permitted.
Variables (system variables, user-defined variables, and stored program local variables) are not permitted.
Subqueries are not permitted.
Foreign key referential actions (ON UPDATE
,
ON DELETE
) are prohibited on columns used in
CHECK
constraints. Likewise,
CHECK
constraints are prohibited on columns
used in foreign key referential actions.
CHECK
constraints are evaluated for
INSERT
,
UPDATE
,
REPLACE
,
LOAD DATA
, and
LOAD XML
statements and an error
occurs if a constraint evaluates to FALSE
. If
an error occurs, handling of changes already applied differs for
transactional and nontransactional storage engines, and also
depends on whether strict SQL mode is in effect, as described in
Strict SQL Mode.
CHECK
constraints are evaluated for
INSERT IGNORE
,
UPDATE IGNORE
,
LOAD DATA ...
IGNORE
, and
LOAD XML ...
IGNORE
statements and a warning occurs if a constraint
evaluates to FALSE
. The insert or update for
any offending row is skipped.
If the constraint expression evaluates to a data type that differs from the declared column type, implicit coercion to the declared type occurs according to the usual MySQL type-conversion rules. See Section 12.3, “Type Conversion in Expression Evaluation”. If type conversion fails or results in a loss of precision, an error occurs.
Constraint expression evaluation uses the SQL mode in effect at evaluation time. If any component of the expression depends on the SQL mode, different results may occur for different uses of the table unless the SQL mode is the same during all uses.
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.
All changes are subject to the internal row-size limit of 65,535 bytes, which may cause some attempts at data type changes to fail. See Section 8.4.7, “Limits on Table Column Count and Row Size”.
Columns that are part of a
PRIMARY KEY
are madeNOT NULL
even if not declared that way.Trailing spaces are automatically deleted from
ENUM
andSET
member values when the table is created.MySQL maps certain data types used by other SQL database vendors to MySQL types. See Section 11.9, “Using Data Types from Other Database Engines”.
If you include a
USING
clause to specify an index type that is not permitted for a given storage engine, but there is another index type available that the engine can use without affecting query results, the engine uses the available type.If strict SQL mode is not enabled, a
VARCHAR
column with a length specification greater than 65535 is converted toTEXT
, and aVARBINARY
column with a length specification greater than 65535 is converted toBLOB
. Otherwise, an error occurs in either of these cases.Specifying the
CHARACTER SET binary
attribute for a character data type causes the column to be created as the corresponding binary data type:CHAR
becomesBINARY
,VARCHAR
becomesVARBINARY
, andTEXT
becomesBLOB
. For theENUM
andSET
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 16.2.3.3, “Compressed Table Characteristics”.
CREATE TABLE
supports the
specification of generated columns. Values of a generated column
are computed from an expression included in the column
definition.
Generated columns are also supported by the
NDB
storage engine.
The following simple example shows a table that stores the
lengths of the sides of right triangles in the
sidea
and sideb
columns,
and computes the length of the hypotenuse in
sidec
(the square root of the sums of the
squares of the other sides):
CREATE TABLE triangle ( sidea DOUBLE, sideb DOUBLE, sidec DOUBLE AS (SQRT(sidea * sidea + sideb * sideb)) ); INSERT INTO triangle (sidea, sideb) VALUES(1,1),(3,4),(6,8);
Selecting from the table yields this result:
mysql> SELECT * FROM triangle;
+-------+-------+--------------------+
| sidea | sideb | sidec |
+-------+-------+--------------------+
| 1 | 1 | 1.4142135623730951 |
| 3 | 4 | 5 |
| 6 | 8 | 10 |
+-------+-------+--------------------+
Any application that uses the triangle
table
has access to the hypotenuse values without having to specify
the expression that calculates them.
Generated column definitions have this syntax:
col_name
data_type
[GENERATED ALWAYS] AS (expr
) [VIRTUAL | STORED] [NOT NULL | NULL] [UNIQUE [KEY]] [[PRIMARY] KEY] [COMMENT 'string
']
AS (
indicates that the column is generated and defines the
expression used to compute column values. expr
)AS
may be preceded by GENERATED ALWAYS
to make
the generated nature of the column more explicit. Constructs
that are permitted or prohibited in the expression are discussed
later.
The VIRTUAL
or STORED
keyword indicates how column values are stored, which has
implications for column use:
VIRTUAL
: Column values are not stored, but are evaluated when rows are read, immediately after anyBEFORE
triggers. A virtual column takes no storage.InnoDB
supports secondary indexes on virtual columns. See Section 13.1.20.9, “Secondary Indexes and Generated Columns”.STORED
: Column values are evaluated and stored when rows are inserted or updated. A stored column does require storage space and can be indexed.
The default is VIRTUAL
if neither keyword is
specified.
It is permitted to mix VIRTUAL
and
STORED
columns within a table.
Other attributes may be given to indicate whether the column is
indexed or can be NULL
, or provide a comment.
Generated column expressions must adhere to the following rules. An error occurs if an expression contains disallowed constructs.
Literals, deterministic built-in functions, and operators are permitted. A function is deterministic if, given the same data in tables, multiple invocations produce the same result, independently of the connected user. Examples of functions that are nondeterministic and fail this definition:
CONNECTION_ID()
,CURRENT_USER()
,NOW()
.Stored functions and user-defined functions are not permitted.
Stored procedure and function parameters are not permitted.
Variables (system variables, user-defined variables, and stored program local variables) are not permitted.
Subqueries are not permitted.
A generated column definition can refer to other generated columns, but only those occurring earlier in the table definition. A generated column definition can refer to any base (nongenerated) column in the table whether its definition occurs earlier or later.
The
AUTO_INCREMENT
attribute cannot be used in a generated column definition.An
AUTO_INCREMENT
column cannot be used as a base column in a generated column definition.If expression evaluation causes truncation or provides incorrect input to a function, the
CREATE TABLE
statement terminates with an error and the DDL operation is rejected.
If the expression evaluates to a data type that differs from the declared column type, implicit coercion to the declared type occurs according to the usual MySQL type-conversion rules. See Section 12.3, “Type Conversion in Expression Evaluation”.
If a generated column uses the
TIMESTAMP
data type, the setting
for
explicit_defaults_for_timestamp
is ignored. In such cases, if this variable is disabled then
NULL
is not converted to
CURRENT_TIMESTAMP
. In MySQL
8.0.22 and later, if the column is also declared as NOT
NULL
, attempting to insert NULL
is
explicitly rejected with
ER_BAD_NULL_ERROR.
Expression evaluation uses the SQL mode in effect at evaluation time. If any component of the expression depends on the SQL mode, different results may occur for different uses of the table unless the SQL mode is the same during all uses.
For CREATE
TABLE ... LIKE
, the destination table preserves
generated column information from the original table.
For CREATE
TABLE ... SELECT
, the destination table does not
preserve information about whether columns in the selected-from
table are generated columns. The
SELECT
part of the statement
cannot assign values to generated columns in the destination
table.
Partitioning by generated columns is permitted. See Table Partitioning.
A foreign key constraint on a stored generated column cannot use
CASCADE
, SET NULL
, or
SET DEFAULT
as ON UPDATE
referential actions, nor can it use SET NULL
or SET DEFAULT
as ON
DELETE
referential actions.
A foreign key constraint on the base column of a stored
generated column cannot use CASCADE
,
SET NULL
, or SET DEFAULT
as ON UPDATE
or ON DELETE
referential actions.
A foreign key constraint cannot reference a virtual generated column.
Triggers cannot use
NEW.
or
use col_name
OLD.
to refer to generated columns.
col_name
For INSERT
,
REPLACE
, and
UPDATE
, if a generated column is
inserted into, replaced, or updated explicitly, the only
permitted value is DEFAULT
.
A generated column in a view is considered updatable because it
is possible to assign to it. However, if such a column is
updated explicitly, the only permitted value is
DEFAULT
.
Generated columns have several use cases, such as these:
Virtual generated columns can be used as a way to simplify and unify queries. A complicated condition can be defined as a generated column and referred to from multiple queries on the table to ensure that all of them use exactly the same condition.
Stored generated columns can be used as a materialized cache for complicated conditions that are costly to calculate on the fly.
Generated columns can simulate functional indexes: Use a generated column to define a functional expression and index it. This can be useful for working with columns of types that cannot be indexed directly, such as
JSON
columns; see Indexing a Generated Column to Provide a JSON Column Index, for a detailed example.For stored generated columns, the disadvantage of this approach is that values are stored twice; once as the value of the generated column and once in the index.
If a generated column is indexed, the optimizer recognizes query expressions that match the column definition and uses indexes from the column as appropriate during query execution, even if a query does not refer to the column directly by name. For details, see Section 8.3.11, “Optimizer Use of Generated Column Indexes”.
Example:
Suppose that a table t1
contains
first_name
and last_name
columns and that applications frequently construct the full name
using an expression like this:
SELECT CONCAT(first_name,' ',last_name) AS full_name FROM t1;
One way to avoid writing out the expression is to create a view
v1
on t1
, which simplifies
applications by enabling them to select
full_name
directly without using an
expression:
CREATE VIEW v1 AS SELECT *, CONCAT(first_name,' ',last_name) AS full_name FROM t1; SELECT full_name FROM v1;
A generated column also enables applications to select
full_name
directly without the need to define
a view:
CREATE TABLE t1 ( first_name VARCHAR(10), last_name VARCHAR(10), full_name VARCHAR(255) AS (CONCAT(first_name,' ',last_name)) ); SELECT full_name FROM t1;
InnoDB
supports secondary indexes on virtual
generated columns. Other index types are not supported. A
secondary index defined on a virtual column is sometimes
referred to as a “virtual index”.
A secondary index may be created on one or more virtual columns
or on a combination of virtual columns and regular columns or
stored generated columns. Secondary indexes that include virtual
columns may be defined as UNIQUE
.
When a secondary index is created on a virtual generated column, generated column values are materialized in the records of the index. If the index is a covering index (one that includes all the columns retrieved by a query), generated column values are retrieved from materialized values in the index structure instead of computed “on the fly”.
There are additional write costs to consider when using a
secondary index on a virtual column due to computation performed
when materializing virtual column values in secondary index
records during INSERT
and
UPDATE
operations. Even with
additional write costs, secondary indexes on virtual columns may
be preferable to generated stored columns,
which are materialized in the clustered index, resulting in
larger tables that require more disk space and memory. If a
secondary index is not defined on a virtual column, there are
additional costs for reads, as virtual column values must be
computed each time the column's row is examined.
Values of an indexed virtual column are MVCC-logged to avoid
unnecessary recomputation of generated column values during
rollback or during a purge operation. The data length of logged
values is limited by the index key limit of 767 bytes for
COMPACT
and REDUNDANT
row
formats, and 3072 bytes for DYNAMIC
and
COMPRESSED
row formats.
Adding or dropping a secondary index on a virtual column is an in-place operation.
As noted elsewhere, JSON
columns cannot be indexed directly. To create an index that
references such a column indirectly, you can define a
generated column that extracts the information that should be
indexed, then create an index on the generated column, as
shown in this example:
mysql>CREATE TABLE jemp (
->c JSON,
->g INT GENERATED ALWAYS AS (c->"$.id"),
->INDEX i (g)
->);
Query OK, 0 rows affected (0.28 sec) mysql>INSERT INTO jemp (c) VALUES
>('{"id": "1", "name": "Fred"}'), ('{"id": "2", "name": "Wilma"}'),
>('{"id": "3", "name": "Barney"}'), ('{"id": "4", "name": "Betty"}');
Query OK, 4 rows affected (0.04 sec) Records: 4 Duplicates: 0 Warnings: 0 mysql>SELECT c->>"$.name" AS name
>FROM jemp WHERE g > 2;
+--------+ | name | +--------+ | Barney | | Betty | +--------+ 2 rows in set (0.00 sec) mysql>EXPLAIN SELECT c->>"$.name" AS name
>FROM jemp WHERE g > 2\G
*************************** 1. row *************************** id: 1 select_type: SIMPLE table: jemp partitions: NULL type: range possible_keys: i key: i key_len: 5 ref: NULL rows: 2 filtered: 100.00 Extra: Using where 1 row in set, 1 warning (0.00 sec) mysql>SHOW WARNINGS\G
*************************** 1. row *************************** Level: Note Code: 1003 Message: /* select#1 */ select json_unquote(json_extract(`test`.`jemp`.`c`,'$.name')) AS `name` from `test`.`jemp` where (`test`.`jemp`.`g` > 2) 1 row in set (0.00 sec)
(We have wrapped the output from the last statement in this example to fit the viewing area.)
When you use EXPLAIN
on a
SELECT
or other SQL statement
containing one or more expressions that use the
->
or ->>
operator, these expressions are translated into their
equivalents using JSON_EXTRACT()
and (if
needed) JSON_UNQUOTE()
instead, as shown
here in the output from SHOW
WARNINGS
immediately following this
EXPLAIN
statement:
mysql>EXPLAIN SELECT c->>"$.name"
>FROM jemp WHERE g > 2 ORDER BY c->"$.name"\G
*************************** 1. row *************************** id: 1 select_type: SIMPLE table: jemp partitions: NULL type: range possible_keys: i key: i key_len: 5 ref: NULL rows: 2 filtered: 100.00 Extra: Using where; Using filesort 1 row in set, 1 warning (0.00 sec) mysql>SHOW WARNINGS\G
*************************** 1. row *************************** Level: Note Code: 1003 Message: /* select#1 */ select json_unquote(json_extract(`test`.`jemp`.`c`,'$.name')) AS `c->>"$.name"` from `test`.`jemp` where (`test`.`jemp`.`g` > 2) order by json_extract(`test`.`jemp`.`c`,'$.name') 1 row in set (0.00 sec)
See the descriptions of the
->
and
->>
operators, as well as those of the
JSON_EXTRACT()
and
JSON_UNQUOTE()
functions, for
additional information and examples.
This technique also can be used to provide indexes that
indirectly reference columns of other types that cannot be
indexed directly, such as GEOMETRY
columns.
In MySQL 8.0.21 and later, it is also possible to create an
index on a JSON
column using
the JSON_VALUE()
function with
an expression that can be used to optimize queries employing
the expression. See the description of that function for more
information and examples.
JSON columns and indirect indexing in NDB Cluster
It is also possible to use indirect indexing of JSON columns in MySQL NDB Cluster, subject to the following conditions:
NDB
handles aJSON
column value internally as aBLOB
. This means that anyNDB
table having one or more JSON columns must have a primary key, else it cannot be recorded in the binary log.The
NDB
storage engine does not support indexing of virtual columns. Since the default for generated columns isVIRTUAL
, you must specify explicitly the generated column to which to apply the indirect index asSTORED
.
The CREATE TABLE
statement
used to create the table jempn
shown here
is a version of the jemp
table shown
previously, with modifications making it compatible with
NDB
:
CREATE TABLE jempn ( a BIGINT(20) NOT NULL AUTO_INCREMENT PRIMARY KEY, c JSON DEFAULT NULL, g INT GENERATED ALWAYS AS (c->"$.name") STORED, INDEX i (g) ) ENGINE=NDB;
We can populate this table using the following
INSERT
statement:
INSERT INTO jempn (a, c) VALUES (NULL, '{"id": "1", "name": "Fred"}'), (NULL, '{"id": "2", "name": "Wilma"}'), (NULL, '{"id": "3", "name": "Barney"}'), (NULL, '{"id": "4", "name": "Betty"}');
Now NDB
can use index i
,
as shown here:
mysql>EXPLAIN SELECT c->>"$.name" AS name FROM jempn WHERE g > 2\G
*************************** 1. row *************************** id: 1 select_type: SIMPLE table: jempn partitions: p0,p1 type: range possible_keys: i key: i key_len: 5 ref: NULL rows: 3 filtered: 100.00 Extra: Using where with pushed condition (`test`.`jempn`.`g` > 2) 1 row in set, 1 warning (0.00 sec) mysql>SHOW WARNINGS\G
*************************** 1. row *************************** Level: Note Code: 1003 Message: /* select#1 */ select json_unquote(json_extract(`test`.`jempn`.`c`,'$.name')) AS `name` from `test`.`jempn` where (`test`.`jempn`.`g` > 2) 1 row in set (0.00 sec)
You should keep in mind that a stored generated column uses
DataMemory
, and that
an index on such a column uses
IndexMemory
.
MySQL supports invisible columns as of MySQL 8.0.23. An invisible column is normally hidden to queries, but can be accessed if explicitly referenced. Prior to MySQL 8.0.23, all columns are visible.
As an illustration of when invisible columns may be useful,
suppose that an application uses SELECT *
queries to access a table, and must continue to work without
modification even if the table is altered to add a new column
that the application does not expect to be there. In a
SELECT *
query, the *
evaluates to all table columns, except those that are invisible,
so the solution is to add the new column as an invisible column.
The column remains “hidden” from SELECT
*
queries, and the application continues to work as
previously. A newer version of the application can refer to the
invisible column if necessary by explicitly referencing it.
The following sections detail how MySQL treats invisible columns.
Columns are visible by default. To explicitly specify
visibility for a new column, use a VISIBLE
or INVISIBLE
keyword as part of the column
definition for CREATE TABLE
or
ALTER TABLE
:
CREATE TABLE t1 ( i INT, j DATE INVISIBLE ) ENGINE = InnoDB; ALTER TABLE t1 ADD COLUMN k INT INVISIBLE;
To alter the visibility of an existing column, use a
VISIBLE
or INVISIBLE
keyword with one of the ALTER TABLE
column-modification clauses:
ALTER TABLE t1 CHANGE COLUMN j j DATE VISIBLE; ALTER TABLE t1 MODIFY COLUMN j DATE INVISIBLE; ALTER TABLE t1 ALTER COLUMN j SET VISIBLE;
A table must have at least one visible column. Attempting to make all columns invisible produces an error.
Invisible columns support the usual column attributes:
NULL
, NOT NULL
,
AUTO_INCREMENT
, and so forth.
Generated columns can be invisible.
Index definitions can name invisible columns, including
definitions for PRIMARY KEY
and
UNIQUE
indexes. Although a table must have
at least one visible column, an index definition need not have
any visible columns.
An invisible column dropped from a table is dropped in the usual way from any index definition that names the column.
Foreign key constraints can be defined on invisible columns, and foreign key constraints can reference invisible columns.
CHECK
constraints can be defined on
invisible columns. For new or modified rows, violation of a
CHECK
constraint on an invisible column
produces an error.
CREATE
TABLE ... LIKE
includes invisible columns, and they
are invisible in the new table.
CREATE
TABLE ... SELECT
does not include invisible columns,
unless they are explicitly referenced in the
SELECT
part. However, even if
explicitly referenced, a column that is invisible in the
existing table is visible in the new table:
mysql>CREATE TABLE t1 (col1 INT, col2 INT INVISIBLE);
mysql>CREATE TABLE t2 AS SELECT col1, col2 FROM t1;
mysql>SHOW CREATE TABLE t2\G
*************************** 1. row *************************** Table: t2 Create Table: CREATE TABLE `t2` ( `col1` int DEFAULT NULL, `col2` int DEFAULT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
If invisibility should be preserved, provide a definition for
the invisible column in the CREATE
TABLE
part of the
CREATE
TABLE ... SELECT
statement:
mysql>CREATE TABLE t1 (col1 INT, col2 INT INVISIBLE);
mysql>CREATE TABLE t2 (col2 INT INVISIBLE) AS SELECT col1, col2 FROM t1;
mysql>SHOW CREATE TABLE t2\G
*************************** 1. row *************************** Table: t2 Create Table: CREATE TABLE `t2` ( `col1` int DEFAULT NULL, `col2` int DEFAULT NULL /*!80023 INVISIBLE */ ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
Views can refer to invisible columns by explicitly referencing
them in the SELECT
statement that defines
the view. Changing a column's visibility subsequent to
defining a view that references the column does not change
view behavior.
For SELECT
statements, an
invisible column is not part of the result set unless
explicitly referenced in the select list. In a select list,
the *
and
shorthands do not include invisible columns. Natural joins do
not include invisible columns.
tbl_name
.*
Consider the following statement sequence:
mysql>CREATE TABLE t1 (col1 INT, col2 INT INVISIBLE);
mysql>INSERT INTO t1 (col1, col2) VALUES(1, 2), (3, 4);
mysql>SELECT * FROM t1;
+------+ | col1 | +------+ | 1 | | 3 | +------+ mysql>SELECT col1, col2 FROM t1;
+------+------+ | col1 | col2 | +------+------+ | 1 | 2 | | 3 | 4 | +------+------+
The first SELECT
does not
reference the invisible column col2
in the
select list (because *
does not include
invisible columns), so col2
does not appear
in the statement result. The second
SELECT
does reference
col2
, so it does appear in the result.
For statements that create new rows, an invisible column is assigned its implicit default value unless explicitly referenced and assigned a value. For information about implicit defaults, see Implicit Default Handling.
For INSERT
(and
REPLACE
, for non-replaced
rows), implicit default assignment occurs with a missing
column list, an empty column list, or a nonempty column list
that does not include the invisible column:
CREATE TABLE t1 (col1 INT, col2 INT INVISIBLE); INSERT INTO t1 VALUES(...); INSERT INTO t1 () VALUES(...); INSERT INTO t1 (col1) VALUES(...);
For the first two INSERT
statements, the VALUES()
list must provide
a value for each visible column and no invisible column. For
the third INSERT
statement, the
VALUES()
list must provide the same number
of values as the number of named columns.
For LOAD DATA
and
LOAD XML
, implicit default
assignment occurs with a missing column list or a nonempty
column list that does not include the invisible column. Input
rows should not include a value for the invisible column.
To assign a value other than the implicit default for the preceding statements, explicitly name the invisible column in the column list and provide a value for it.
INSERT INTO ...
SELECT *
and
REPLACE INTO ...
SELECT *
do not include invisible columns because
*
does not include invisible columns.
Implicit default assignment occurs as described previously.
For statements that insert or ignore new rows, or that replace
or modify existing rows, based on values in a PRIMARY
KEY
or UNIQUE
index, MySQL treats
invisible columns the same as visible columns: Invisible
columns participate in key value comparisons. Specifically, if
a new row has the same value as an existing row for a unique
key value, these behaviors occur whether the index columns are
visible or invisible:
To update invisible columns for
UPDATE
statements, name them
and assign a value, just as for visible columns.
Information about whether a column is visible or invisible is
available from the EXTRA
column of the
INFORMATION_SCHEMA.COLUMNS
table
or SHOW COLUMNS
output. For
example:
mysql>SELECT TABLE_NAME, COLUMN_NAME, EXTRA
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = 'test' AND TABLE_NAME = 't1';
+------------+-------------+-----------+ | TABLE_NAME | COLUMN_NAME | EXTRA | +------------+-------------+-----------+ | t1 | i | | | t1 | j | | | t1 | k | INVISIBLE | +------------+-------------+-----------+
Columns are visible by default, so in that case,
EXTRA
displays no visibility information.
For invisible columns, EXTRA
displays
INVISIBLE
.
SHOW CREATE TABLE
displays invisible
columns in the table definition, with the
INVISIBLE
keyword in a version-specific
comment:
mysql> SHOW CREATE TABLE t1\G
*************************** 1. row ***************************
Table: t1
Create Table: CREATE TABLE `t1` (
`i` int DEFAULT NULL,
`j` int DEFAULT NULL,
`k` int DEFAULT NULL /*!80023 INVISIBLE */
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
mysqldump and mysqlpump
use SHOW CREATE TABLE
, so they include
invisible columns in dumped table definitions. They also
include invisible column values in dumped data.
Reloading a dump file into an older version of MySQL that does not support invisible columns causes the version-specific comment to be ignored, which creates any invisible columns as visible.
MySQL treats invisible columns as follows with respect to events in the binary log:
Table-creation events include the
INVISIBLE
attribute for invisible columns.Invisible columns are treated like visible columns in row events. They are included if needed according to the
binlog_row_image
system variable setting.When row events are applied, invisible columns are treated like visible columns in row events. In particular, the algorithm and index to use are chosen according to the
slave_rows_search_algorithms
system variable setting.Invisible columns are treated like visible columns when computing writesets. In particular, writesets include indexes defined on invisible columns.
The mysqlbinlog command includes visibility in column metadata.
In MySQL NDB Cluster, the table comment in a CREATE
TABLE
or ALTER TABLE
statement can also be used to specify an
NDB_TABLE
option, which consists of one or
more name-value pairs, separated by commas if need be, following
the string NDB_TABLE=
. Complete syntax for
names and values syntax is shown here:
COMMENT="NDB_TABLE=ndb_table_option
[,ndb_table_option
[,...]]"ndb_table_option
: { NOLOGGING={1 | 0} | READ_BACKUP={1 | 0} | PARTITION_BALANCE={FOR_RP_BY_NODE | FOR_RA_BY_NODE | FOR_RP_BY_LDM | FOR_RA_BY_LDM | FOR_RA_BY_LDM_X_2 | FOR_RA_BY_LDM_X_3 | FOR_RA_BY_LDM_X_4} | FULLY_REPLICATED={1 | 0} }
Spaces are not permitted within the quoted string. The string is case-insensitive.
The four NDB
table options that can be set as
part of a comment in this way are described in more detail in
the next few paragraphs.
NOLOGGING
: Using 1 corresponds to having
ndb_table_no_logging
enabled,
but has no actual effect. Provided as a placeholder, mostly for
completeness of ALTER TABLE
statements.
READ_BACKUP
: Setting this option to 1 has the
same effect as though
ndb_read_backup
were enabled;
enables reading from any replica. Doing so greatly improves the
performance of reads from the table at a relatively small cost
to write performance. Beginning with NDB 8.0.19, 1 is the
default for READ_BACKUP
, and the default for
ndb_read_backup
is
ON
(previously, read from any replica was
disabled by default).
You can set READ_BACKUP
for an existing table
online, using an ALTER TABLE
statement
similar to one of those shown here:
ALTER TABLE ... ALGORITHM=INPLACE, COMMENT="NDB_TABLE=READ_BACKUP=1"; ALTER TABLE ... ALGORITHM=INPLACE, COMMENT="NDB_TABLE=READ_BACKUP=0";
For more information about the ALGORITHM
option for ALTER TABLE
, see
Section 23.5.11, “Online Operations with ALTER TABLE in NDB Cluster”.
PARTITION_BALANCE
: Provides additional
control over assignment and placement of partitions. The
following four schemes are supported:
FOR_RP_BY_NODE
: One partition per node.Only one LDM on each node stores a primary partition. Each partition is stored in the same LDM (same ID) on all nodes.
FOR_RA_BY_NODE
: One partition per node group.Each node stores a single partition, which can be either a primary replica or a backup replica. Each partition is stored in the same LDM on all nodes.
FOR_RP_BY_LDM
: One partition for each LDM on each node; the default.This is the setting used if
READ_BACKUP
is set to 1.FOR_RA_BY_LDM
: One partition per LDM in each node group.These partitions can be primary or backup partitions.
FOR_RA_BY_LDM_X_2
: Two partitions per LDM in each node group.These partitions can be primary or backup partitions.
FOR_RA_BY_LDM_X_3
: Three partitions per LDM in each node group.These partitions can be primary or backup partitions.
FOR_RA_BY_LDM_X_4
: Four partitions per LDM in each node group.These partitions can be primary or backup partitions.
PARTITION_BALANCE
is the preferred interface
for setting the number of partitions per table. Using
MAX_ROWS
to force the number of partitions is
deprecated but continues to be supported for backward
compatibility; it is subject to removal in a future release of
MySQL NDB Cluster. (Bug #81759, Bug #23544301)
FULLY_REPLICATED
controls whether the table
is fully replicated, that is, whether each data node has a
complete copy of the table. To enable full replication of the
table, use FULLY_REPLICATED=1
.
This setting can also be controlled using the
ndb_fully_replicated
system variable. Setting
it to ON
enables the option by default for
all new NDB
tables; the default is
OFF
. The
ndb_data_node_neighbour
system
variable is also used for fully replicated tables, to ensure
that when a fully replicated table is accessed, we access the
data node which is local to this MySQL Server.
An example of a CREATE TABLE
statement using
such a comment when creating an NDB
table is
shown here:
mysql>CREATE TABLE t1 (
>c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
>c2 VARCHAR(100),
>c3 VARCHAR(100) )
>ENGINE=NDB
>COMMENT="NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RP_BY_NODE";
The comment is displayed as part of the ouput of
SHOW CREATE TABLE
. The text of
the comment is also available from querying the MySQL
Information Schema TABLES
table, as
in this example:
mysql>SELECT TABLE_NAME, TABLE_SCHEMA, TABLE_COMMENT
>FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME="t1"\G
*************************** 1. row *************************** TABLE_NAME: t1 TABLE_SCHEMA: test TABLE_COMMENT: NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RP_BY_NODE 1 row in set (0.01 sec)
This comment syntax is also supported with
ALTER TABLE
statements for
NDB
tables, as shown here:
mysql> ALTER TABLE t1 COMMENT="NDB_TABLE=PARTITION_BALANCE=FOR_RA_BY_NODE";
Query OK, 0 rows affected (0.40 sec)
Records: 0 Duplicates: 0 Warnings: 0
Beginning with NDB 8.0.21, the TABLE_COMMENT
column displays the comment that is required to re-create the
table as it is following the ALTER TABLE
statement, like this:
mysql>SELECT TABLE_NAME, TABLE_SCHEMA, TABLE_COMMENT
->FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME="t1"\G
*************************** 1. row *************************** TABLE_NAME: t1 TABLE_SCHEMA: test TABLE_COMMENT: NDB_TABLE=READ_BACKUP=0,PARTITION_BALANCE=FOR_RP_BY_NODE 1 row in set (0.01 sec)
mysql>SELECT TABLE_NAME, TABLE_SCHEMA, TABLE_COMMENT
>FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME="t1";
+------------+--------------+--------------------------------------------------+ | TABLE_NAME | TABLE_SCHEMA | TABLE_COMMENT | +------------+--------------+--------------------------------------------------+ | t1 | c | NDB_TABLE=PARTITION_BALANCE=FOR_RA_BY_NODE | | t1 | d | | +------------+--------------+--------------------------------------------------+ 2 rows in set (0.01 sec)
Keep in mind that a table comment used with ALTER
TABLE
replaces any existing comment which the table
might have.
mysql>ALTER TABLE t1 COMMENT="NDB_TABLE=PARTITION_BALANCE=FOR_RA_BY_NODE";
Query OK, 0 rows affected (0.40 sec) Records: 0 Duplicates: 0 Warnings: 0 mysql>SELECT TABLE_NAME, TABLE_SCHEMA, TABLE_COMMENT
>FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME="t1";
+------------+--------------+--------------------------------------------------+ | TABLE_NAME | TABLE_SCHEMA | TABLE_COMMENT | +------------+--------------+--------------------------------------------------+ | t1 | c | NDB_TABLE=PARTITION_BALANCE=FOR_RA_BY_NODE | | t1 | d | | +------------+--------------+--------------------------------------------------+ 2 rows in set (0.01 sec)
Prior to NDB 8.0.21, the table comment used with ALTER
TABLE
replaced any existing comment which the table
might have had. This meant that (for example) the
READ_BACKUP
value was not carried over to the
new comment set by the ALTER TABLE
statement,
and that any unspecified values reverted to their defaults.
(BUG#30428829) There was thus no longer any way using SQL to
retrieve the value previously set for the comment. To keep
comment values from reverting to their defaults, it was necessry
to preserve any such values from the existing comment string and
include them in the comment passed to ALTER
TABLE
.
You can also see the value of the
PARTITION_BALANCE
option in the output of
ndb_desc. ndb_desc also
shows whether the READ_BACKUP
and
FULLY_REPLICATED
options are set for the
table. See the description of this program for more information.
CREATE [UNDO] TABLESPACEtablespace_name
InnoDB and NDB: [ADD DATAFILE 'file_name
'] [AUTOEXTEND_SIZE [=]value
] InnoDB only: [FILE_BLOCK_SIZE = value] [ENCRYPTION [=] {'Y' | 'N'}] NDB only: USE LOGFILE GROUPlogfile_group
[EXTENT_SIZE [=]extent_size
] [INITIAL_SIZE [=]initial_size
] [MAX_SIZE [=]max_size
] [NODEGROUP [=]nodegroup_id
] [WAIT] [COMMENT [=] 'string
'] InnoDB and NDB: [ENGINE [=]engine_name
] Reserved for future use: [ENGINE_ATTRIBUTE [=] 'string
']
This statement is used to create a tablespace. The precise syntax
and semantics depend on the storage engine used. In standard MySQL
releases, this is always an InnoDB
tablespace. MySQL NDB Cluster also supports tablespaces using the
NDB
storage engine.
Considerations for InnoDB
CREATE TABLESPACE
syntax is used to
create general tablespaces or undo tablespaces. The
UNDO
keyword, introduced in MySQL 8.0.14, must
be specified to create an undo tablespace.
A general tablespace is a shared tablespace. It can hold multiple tables, and supports all table row formats. General tablespaces can be created in a location relative to or independent of the data directory.
After creating an InnoDB
general tablespace,
use CREATE TABLE
or
tbl_name
... TABLESPACE [=]
tablespace_name
ALTER TABLE
to add tables
to the tablespace. For more information, see
Section 15.6.3.3, “General Tablespaces”.
tbl_name
TABLESPACE [=]
tablespace_name
Undo tablespaces contain undo logs. Undo tablespaces can be created in a chosen location by specifying a fully qualified data file path. For more information, see Section 15.6.3.4, “Undo Tablespaces”.
Considerations for NDB Cluster
This statement is used to create a tablespace, which can contain
one or more data files, providing storage space for NDB Cluster
Disk Data tables (see Section 23.5.10, “NDB Cluster Disk Data Tables”).
One data file is created and added to the tablespace using this
statement. Additional data files may be added to the tablespace by
using the ALTER TABLESPACE
statement (see Section 13.1.10, “ALTER TABLESPACE Statement”).
All NDB Cluster Disk Data objects share the same namespace. This means that each Disk Data object must be uniquely named (and not merely each Disk Data object of a given type). For example, you cannot have a tablespace and a log file group with the same name, or a tablespace and a data file with the same name.
A log file group of one or more UNDO
log files
must be assigned to the tablespace to be created with the
USE LOGFILE GROUP
clause.
logfile_group
must be an existing log
file group created with CREATE LOGFILE
GROUP
(see Section 13.1.16, “CREATE LOGFILE GROUP Statement”).
Multiple tablespaces may use the same log file group for
UNDO
logging.
When setting EXTENT_SIZE
or
INITIAL_SIZE
, you may optionally follow the
number with a one-letter abbreviation for an order of magnitude,
similar to those used in my.cnf
. Generally,
this is one of the letters M
(for megabytes) or
G
(for gigabytes).
INITIAL_SIZE
and EXTENT_SIZE
are subject to rounding as follows:
EXTENT_SIZE
is rounded up to the nearest whole multiple of 32K.INITIAL_SIZE
is rounded down to the nearest whole multiple of 32K; this result is rounded up to the nearest whole multiple ofEXTENT_SIZE
(after any rounding).
NDB
reserves 4% of a tablespace for
data node restart operations. This reserved space cannot be used
for data storage.
The rounding just described is done explicitly, and a warning is
issued by the MySQL Server when any such rounding is performed.
The rounded values are also used by the NDB kernel for calculating
INFORMATION_SCHEMA.FILES
column
values and other purposes. However, to avoid an unexpected result,
we suggest that you always use whole multiples of 32K in
specifying these options.
When CREATE TABLESPACE
is used with
ENGINE [=] NDB
, a tablespace and associated
data file are created on each Cluster data node. You can verify
that the data files were created and obtain information about them
by querying the
INFORMATION_SCHEMA.FILES
table. (See
the example later in this section.)
(See Section 26.15, “The INFORMATION_SCHEMA FILES Table”.)
Options
ADD DATAFILE
: Defines the name of a tablespace data file. This option is always required when creating anNDB
tablespace; forInnoDB
in MySQL 8.0.14 and later, it is required only when creating an undo tablespace. The
, including any specified path, must be quoted with single or double quotation marks. File names (not counting the file extension) and directory names must be at least one byte in length. Zero length file names and directory names are not supported.file_name
Because there are considerable differences in how
InnoDB
andNDB
treat data files, the two storage engines are covered separately in the discussion that follows.InnoDB data files. An
InnoDB
tablespace supports only a single data file, whose name must include a.ibd
extension.To place an
InnoDB
general tablespace data file in a location outside of the data directory, include a fully qualified path or a path relative to the data directory. Only a fully qualified path is permitted for undo tablespaces. If you do not specify a path, a general tablespace is created in the data directory. An undo tablespace created without specifying a path is created in the directory defined by theinnodb_undo_directory
variable. If theinnodb_undo_directory
variable is undefined, undo tablespaces are created in the data directory.To avoid conflicts with implicitly created file-per-table tablespaces, creating an
InnoDB
general tablespace in a subdirectory under the data directory is not supported. When creating a general tablespace or undo tablespace outside of the data directory, the directory must exist and must be known toInnoDB
prior to creating the tablespace. To make a directory known toInnoDB
, add it to theinnodb_directories
value or to one of the variables whose values are appended to theinnodb_directories
value.innodb_directories
is a read-only variable. Configuring it requires restarting the server.If the
ADD DATAFILE
clause is not specified when creating anInnoDB
tablespace, a tablespace data file with a unique file name is created implicitly. The unique file name is a 128 bit UUID formatted into five groups of hexadecimal numbers separated by dashes (aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
). A file extension is added if required by the storage engine. An.ibd
file extension is added forInnoDB
general tablespace data files. In a replication environment, the data file name created on the replication source server is not the same as the data file name created on the replica.As of MySQL 8.0.17, the
ADD DATAFILE
clause does not permit circular directory references when creating anInnoDB
tablespace. For example, the circular directory reference (/../
) in the following statement is not permitted:CREATE TABLESPACE ts1 ADD DATAFILE ts1.ibd '
any_directory
/../ts1.ibd';An exception to this restriction exists on Linux, where a circular directory reference is permitted if the preceding directory is a symbolic link. For example, the data file path in the example above is permitted if
any_directory
is a symbolic link. (It is still permitted for data file paths to begin with '../
'.)NDB data files. An
NDB
tablespace supports multiple data files which can have any legal file names; more data files can be added to an NDB Cluster tablespace following its creation by using anALTER TABLESPACE
statement.An
NDB
tablespace data file is created by default in the data node file system directory—that is, the directory namedndb_
under the data node's data directory (nodeid
_fs/TSDataDir
), wherenodeid
is the data node'sNodeId
. To place the data file in a location other than the default, include an absolute directory path or a path relative to the default location. If the directory specified does not exist,NDB
attempts to create it; the system user account under which the data node process is running must have the appropriate permissions to do so.NoteWhen determining the path used for a data file,
NDB
does not expand the~
(tilde) character.When multiple data nodes are run on the same physical host, the following considerations apply:
You cannot specify an absolute path when creating a data file.
It is not possible to create tablespace data files outside the data node file system directory, unless each data node has a separate data directory.
If each data node has its own data directory, data files can be created anywhere within this directory.
If each data node has its own data directory, it may also be possible to create a data file outside the node's data directory using a relative path, as long as this path resolves to a unique location on the host file system for each data node running on that host.
FILE_BLOCK_SIZE
: This option—which is specific toInnoDB
general tablespaces, and is ignored byNDB
—defines the block size for the tablespace data file. Values can be specified in bytes or kilobytes. For example, an 8 kilobyte file block size can be specified as 8192 or 8K. If you do not specify this option,FILE_BLOCK_SIZE
defaults to theinnodb_page_size
value.FILE_BLOCK_SIZE
is required when you intend to use the tablespace for storing compressedInnoDB
tables (ROW_FORMAT=COMPRESSED
). In this case, you must define the tablespaceFILE_BLOCK_SIZE
when creating the tablespace.If
FILE_BLOCK_SIZE
is equal theinnodb_page_size
value, the tablespace can contain only tables having an uncompressed row format (COMPACT
,REDUNDANT
, andDYNAMIC
). Tables with aCOMPRESSED
row format have a different physical page size than uncompressed tables. Therefore, compressed tables cannot coexist in the same tablespace as uncompressed tables.For a general tablespace to contain compressed tables,
FILE_BLOCK_SIZE
must be specified, and theFILE_BLOCK_SIZE
value must be a valid compressed page size in relation to theinnodb_page_size
value. Also, the physical page size of the compressed table (KEY_BLOCK_SIZE
) must be equal toFILE_BLOCK_SIZE/1024
. For example, ifinnodb_page_size=16K
, andFILE_BLOCK_SIZE=8K
, theKEY_BLOCK_SIZE
of the table must be 8. For more information, see Section 15.6.3.3, “General Tablespaces”.USE LOGFILE GROUP
: Required forNDB
, this is the name of a log file group previously created usingCREATE LOGFILE GROUP
. Not supported forInnoDB
, where it fails with an error.EXTENT_SIZE
: This option is specific to NDB, and is not supported by InnoDB, where it fails with an error.EXTENT_SIZE
sets the size, in bytes, of the extents used by any files belonging to the tablespace. The default value is 1M. The minimum size is 32K, and theoretical maximum is 2G, although the practical maximum size depends on a number of factors. In most cases, changing the extent size does not have any measurable effect on performance, and the default value is recommended for all but the most unusual situations.An extent is a unit of disk space allocation. One extent is filled with as much data as that extent can contain before another extent is used. In theory, up to 65,535 (64K) extents may used per data file; however, the recommended maximum is 32,768 (32K). The recommended maximum size for a single data file is 32G—that is, 32K extents × 1 MB per extent. In addition, once an extent is allocated to a given partition, it cannot be used to store data from a different partition; an extent cannot store data from more than one partition. This means, for example that a tablespace having a single datafile whose
INITIAL_SIZE
(described in the following item) is 256 MB and whoseEXTENT_SIZE
is 128M has just two extents, and so can be used to store data from at most two different disk data table partitions.You can see how many extents remain free in a given data file by querying the
INFORMATION_SCHEMA.FILES
table, and so derive an estimate for how much space remains free in the file. For further discussion and examples, see Section 26.15, “The INFORMATION_SCHEMA FILES Table”.INITIAL_SIZE
: This option is specific toNDB
, and is not supported byInnoDB
, where it fails with an error.The
INITIAL_SIZE
parameter sets the total size in bytes of the data file that was specific usingADD DATATFILE
. Once this file has been created, its size cannot be changed; however, you can add more data files to the tablespace usingALTER TABLESPACE ... ADD DATAFILE
.INITIAL_SIZE
is optional; its default value is 134217728 (128 MB).On 32-bit systems, the maximum supported value for
INITIAL_SIZE
is 4294967296 (4 GB).AUTOEXTEND_SIZE
: Ignored by MySQL prior to MySQL 8.0.23; From MySQL 8.0.23, defines the amount by whichInnoDB
extends the size of the tablespace when it becomes full. The setting must be a multiple of 4MB. The default setting is 0, which causes the tablespace to be extended according to the implicit default behavior. For more information, see Section 15.6.3.9, “Tablespace AUTOEXTEND_SIZE Configuration”.Has no effect in any release of MySQL NDB Cluster 8.0, regardless of the storage engine used.
MAX_SIZE
: Currently ignored by MySQL; reserved for possible future use. Has no effect in any release of MySQL 8.0 or MySQL NDB Cluster 8.0, regardless of the storage engine used.NODEGROUP
: Currently ignored by MySQL; reserved for possible future use. Has no effect in any release of MySQL 8.0 or MySQL NDB Cluster 8.0, regardless of the storage engine used.WAIT
: Currently ignored by MySQL; reserved for possible future use. Has no effect in any release of MySQL 8.0 or MySQL NDB Cluster 8.0, regardless of the storage engine used.COMMENT
: Currently ignored by MySQL; reserved for possible future use. Has no effect in any release of MySQL 8.0 or MySQL NDB Cluster 8.0, regardless of the storage engine used.The
ENCRYPTION
clause enables or disables page-level data encryption for anInnoDB
general tablespace. Encryption support for general tablespaces was introduced in MySQL 8.0.13.As of MySQL 8.0.16, if the
ENCRYPTION
clause is not specified, thedefault_table_encryption
setting controls whether encryption is enabled. TheENCRYPTION
clause overrides thedefault_table_encryption
setting. However, if thetable_encryption_privilege_check
variable is enabled, theTABLE_ENCRYPTION_ADMIN
privilege is required to use anENCRYPTION
clause setting that differs from thedefault_table_encryption
setting.A keyring plugin must be installed and configured before an encryption-enabled tablespace can be created.
When a general tablespace is encrypted, all tables residing in the tablespace are encrypted. Likewise, a table created in an encrypted tablespace is encrypted.
For more information, see Section 15.13, “InnoDB Data-at-Rest Encryption”
ENGINE
: Defines the storage engine which uses the tablespace, whereengine_name
is the name of the storage engine. Currently, only theInnoDB
storage engine is supported by standard MySQL 8.0 releases. MySQL NDB Cluster supports bothNDB
andInnoDB
tablespaces. The value of thedefault_storage_engine
system variable is used forENGINE
if the option is not specified.The
ENGINE_ATTRIBUTE
option (available as of MySQL 8.0.21) is used to specify tablespace attributes for primary storage engines. The option is reserved for future use.Permitted values are a string literal containing a valid
JSON
document or an empty string (''). InvalidJSON
is rejected.CREATE TABLESPACE ts1 ENGINE_ATTRIBUTE='{"
key
":"value
"}';ENGINE_ATTRIBUTE
values can be repeated without error. In this case, the last specified value is used.ENGINE_ATTRIBUTE
values are not checked by the server, nor are they cleared when the table's storage engine is changed.
Notes
For the rules covering the naming of MySQL tablespaces, see Section 9.2, “Schema Object Names”. In addition to these rules, the slash character (“/”) is not permitted, nor can you use names beginning with
innodb_
, as this prefix is reserved for system use.Creation of temporary general tablespaces is not supported.
General tablespaces do not support temporary tables.
The
TABLESPACE
option may be used withCREATE TABLE
orALTER TABLE
to assign anInnoDB
table partition or subpartition to a file-per-table tablespace. All partitions must belong to the same storage engine. Assigning table partitions to sharedInnoDB
tablespaces is not supported. Shared tablespaces include theInnoDB
system tablespace and general tablespaces.General tablespaces support the addition of tables of any row format using
CREATE TABLE ... TABLESPACE
.innodb_file_per_table
does not need to be enabled.innodb_strict_mode
is not applicable to general tablespaces. Tablespace management rules are strictly enforced independently ofinnodb_strict_mode
. IfCREATE TABLESPACE
parameters are incorrect or incompatible, the operation fails regardless of theinnodb_strict_mode
setting. When a table is added to a general tablespace usingCREATE TABLE ... TABLESPACE
orALTER TABLE ... TABLESPACE
,innodb_strict_mode
is ignored but the statement is evaluated as ifinnodb_strict_mode
is enabled.Use
DROP TABLESPACE
to remove a tablespace. All tables must be dropped from a tablespace usingDROP TABLE
prior to dropping the tablespace. Before dropping an NDB Cluster tablespace you must also remove all its data files using one or moreALTER TABLESPACE ... DROP DATATFILE
statements. See Section 23.5.10.1, “NDB Cluster Disk Data Objects”.All parts of an
InnoDB
table added to anInnoDB
general tablespace reside in the general tablespace, including indexes andBLOB
pages.For an
NDB
table assigned to a tablespace, only those columns which are not indexed are stored on disk, and actually use the tablespace data files. Indexes and indexed columns for allNDB
tables are always kept in memory.Similar to the system tablespace, truncating or dropping tables stored in a general tablespace creates free space internally in the general tablespace .ibd data file which can only be used for new
InnoDB
data. Space is not released back to the operating system as it is for file-per-table tablespaces.A general tablespace is not associated with any database or schema.
ALTER TABLE ... DISCARD TABLESPACE
andALTER TABLE ...IMPORT TABLESPACE
are not supported for tables that belong to a general tablespace.The server uses tablespace-level metadata locking for DDL that references general tablespaces. By comparison, the server uses table-level metadata locking for DDL that references file-per-table tablespaces.
A generated or existing tablespace cannot be changed to a general tablespace.
There is no conflict between general tablespace names and file-per-table tablespace names. The “/” character, which is present in file-per-table tablespace names, is not permitted in general tablespace names.
mysqldump and mysqlpump do not dump
InnoDB
CREATE TABLESPACE
statements.
InnoDB Examples
This example demonstrates creating a general tablespace and adding three uncompressed tables of different row formats.
mysql>CREATE TABLESPACE `ts1` ADD DATAFILE 'ts1.ibd' ENGINE=INNODB;
mysql>CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=REDUNDANT;
mysql>CREATE TABLE t2 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=COMPACT;
mysql>CREATE TABLE t3 (c1 INT PRIMARY KEY) TABLESPACE ts1 ROW_FORMAT=DYNAMIC;
This example demonstrates creating a general tablespace and adding
a compressed table. The example assumes a default
innodb_page_size
value of 16K.
The FILE_BLOCK_SIZE
of 8192 requires that the
compressed table have a KEY_BLOCK_SIZE
of 8.
mysql>CREATE TABLESPACE `ts2` ADD DATAFILE 'ts2.ibd' FILE_BLOCK_SIZE = 8192 Engine=InnoDB;
mysql>CREATE TABLE t4 (c1 INT PRIMARY KEY) TABLESPACE ts2 ROW_FORMAT=COMPRESSED KEY_BLOCK_SIZE=8;
This example demonstrates creating a general tablespace without
specifying the ADD DATAFILE
clause, which is
optional as of MySQL 8.0.14.
mysql> CREATE TABLESPACE `ts3` ENGINE=INNODB;
This example demonstrates creating an undo tablespace.
mysql> CREATE UNDO TABLESPACE undo_003
ADD DATAFILE 'undo_003
.ibu';
NDB Example
Suppose that you wish to create an NDB Cluster Disk Data
tablespace named myts
using a datafile named
mydata-1.dat
. An NDB
tablespace always requires the use of a log file group consisting
of one or more undo log files. For this example, we first create a
log file group named mylg
that contains one
undo long file named myundo-1.dat
, using the
CREATE LOGFILE GROUP
statement
shown here:
mysql>CREATE LOGFILE GROUP myg1
->ADD UNDOFILE 'myundo-1.dat'
->ENGINE=NDB;
Query OK, 0 rows affected (3.29 sec)
Now you can create the tablespace previously described using the following statement:
mysql>CREATE TABLESPACE myts
->ADD DATAFILE 'mydata-1.dat'
->USE LOGFILE GROUP mylg
->ENGINE=NDB;
Query OK, 0 rows affected (2.98 sec)
You can now create a Disk Data table using a
CREATE TABLE
statement with the
TABLESPACE
and STORAGE DISK
options, similar to what is shown here:
mysql>CREATE TABLE mytable (
->id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
->lname VARCHAR(50) NOT NULL,
->fname VARCHAR(50) NOT NULL,
->dob DATE NOT NULL,
->joined DATE NOT NULL,
->INDEX(last_name, first_name)
->)
->TABLESPACE myts STORAGE DISK
->ENGINE=NDB;
Query OK, 0 rows affected (1.41 sec)
It is important to note that only the dob
and
joined
columns from mytable
are actually stored on disk, due to the fact that the
id
, lname
, and
fname
columns are all indexed.
As mentioned previously, when CREATE TABLESPACE
is used with ENGINE [=] NDB
, a tablespace and
associated data file are created on each NDB Cluster data node.
You can verify that the data files were created and obtain
information about them by querying the
INFORMATION_SCHEMA.FILES
table, as
shown here:
mysql>SELECT FILE_NAME, FILE_TYPE, LOGFILE_GROUP_NAME, STATUS, EXTRA
->FROM INFORMATION_SCHEMA.FILES
->WHERE TABLESPACE_NAME = 'myts';
+--------------+------------+--------------------+--------+----------------+ | file_name | file_type | logfile_group_name | status | extra | +--------------+------------+--------------------+--------+----------------+ | mydata-1.dat | DATAFILE | mylg | NORMAL | CLUSTER_NODE=5 | | mydata-1.dat | DATAFILE | mylg | NORMAL | CLUSTER_NODE=6 | | NULL | TABLESPACE | mylg | NORMAL | NULL | +--------------+------------+--------------------+--------+----------------+ 3 rows in set (0.01 sec)
For additional information and examples, see Section 23.5.10.1, “NDB Cluster Disk Data Objects”.
CREATE [DEFINER =user
] TRIGGERtrigger_name
trigger_time
trigger_event
ONtbl_name
FOR EACH ROW [trigger_order
]trigger_body
trigger_time
: { BEFORE | AFTER }trigger_event
: { INSERT | UPDATE | DELETE }trigger_order
: { FOLLOWS | PRECEDES }other_trigger_name
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.
Trigger names exist in the schema namespace, meaning that all triggers must have unique names within a schema. Triggers in different schemas can have the same name.
This section describes CREATE
TRIGGER
syntax. For additional discussion, see
Section 25.3.1, “Trigger Syntax and Examples”.
CREATE TRIGGER
requires the
TRIGGER
privilege for the table
associated with the trigger. If the DEFINER
clause is present, the privileges required depend on the
user
value, as discussed in
Section 25.6, “Stored Object Access Control”. If binary logging is
enabled, CREATE TRIGGER
might
require the SUPER
privilege, as
discussed in Section 25.7, “Stored Program Binary Logging”.
The DEFINER
clause determines the security
context to be used when checking access privileges at trigger
activation time, as described later in this section.
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.
Basic column value checks occur prior to trigger activation, so
you cannot use BEFORE
triggers to convert
values inappropriate for the column type to valid values.
trigger_event
indicates the kind of
operation that activates the trigger. These
trigger_event
values are permitted:
INSERT
: The trigger activates whenever a new row is inserted into the table (for example, throughINSERT
,LOAD DATA
, andREPLACE
statements).UPDATE
: The trigger activates whenever a row is modified (for example, throughUPDATE
statements).DELETE
: The trigger activates whenever a row is deleted from the table (for example, throughDELETE
andREPLACE
statements).DROP TABLE
andTRUNCATE TABLE
statements on the table do not activate this trigger, because they do not useDELETE
. Dropping a partition does not activateDELETE
triggers, either.
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 activates not only
for 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 activates 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.
Cascaded foreign key actions do not activate triggers.
It is possible to define multiple triggers for a given table that
have the same trigger event and action time. For example, you can
have two BEFORE UPDATE
triggers for a table. By
default, triggers that have the same trigger event and action time
activate in the order they were created. To affect trigger order,
specify a trigger_order
clause that
indicates FOLLOWS
or
PRECEDES
and the name of an existing trigger
that also has the same trigger event and action time. With
FOLLOWS
, the new trigger activates after the
existing trigger. With PRECEDES
, the new
trigger activates before the existing trigger.
trigger_body
is the statement to
execute when the trigger activates. To execute multiple
statements, use the
BEGIN ... END
compound statement construct. This also enables you to use the
same statements that are permitted within stored routines. See
Section 13.6.1, “BEGIN ... END Compound Statement”. Some statements are not permitted in
triggers; see Section 25.8, “Restrictions on Stored Programs”.
Within the trigger body, you can refer to columns in the subject
table (the table associated with the trigger) by using the aliases
OLD
and NEW
.
OLD.
refers
to a column of an existing row before it is updated or deleted.
col_name
NEW.
refers
to the column of a new row to be inserted or an existing row after
it is updated.
col_name
Triggers cannot use
NEW.
or use
col_name
OLD.
to
refer to generated columns. For information about generated
columns, see Section 13.1.20.8, “CREATE TABLE and Generated Columns”.
col_name
MySQL stores the sql_mode
system
variable setting in effect when a trigger is created, and always
executes the trigger body with this setting in force,
regardless of the current server SQL mode when the
trigger begins executing.
The DEFINER
clause specifies the MySQL account
to be used when checking access privileges at trigger activation
time. If the DEFINER
clause is present, the
user
value should be a MySQL account
specified as
'
,
user_name
'@'host_name
'CURRENT_USER
, or
CURRENT_USER()
. The permitted
user
values depend on the privileges
you hold, as discussed in
Section 25.6, “Stored Object Access Control”. Also see that section
for additional information about trigger security.
If the DEFINER
clause is omitted, the default
definer is the user who executes the CREATE
TRIGGER
statement. This is the same as specifying
DEFINER = CURRENT_USER
explicitly.
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 theTRIGGER
privilege.At trigger activation time, privileges are checked against the
DEFINER
user. This user must have these privileges:The
TRIGGER
privilege for the subject table.The
SELECT
privilege for the subject table if references to table columns occur usingOLD.
orcol_name
NEW.
in the trigger body.col_name
The
UPDATE
privilege for the subject table if table columns are targets ofSET NEW.
assignments in the trigger body.col_name
=value
Whatever other privileges normally are required for the statements executed by the trigger.
Within a trigger body, the
CURRENT_USER
function returns the
account used to check privileges at trigger activation time. This
is the DEFINER
user, not the user whose actions
caused the trigger to be activated. For information about user
auditing within triggers, see
Section 6.2.22, “SQL-Based Account Activity Auditing”.
If you use LOCK TABLES
to lock a
table that has triggers, the tables used within the trigger are
also locked, as described in
LOCK TABLES and Triggers.
For additional discussion of trigger use, see Section 25.3.1, “Trigger Syntax and Examples”.
CREATE [OR REPLACE] [ALGORITHM = {UNDEFINED | MERGE | TEMPTABLE}] [DEFINER =user
] [SQL SECURITY { DEFINER | INVOKER }] VIEWview_name
[(column_list
)] ASselect_statement
[WITH [CASCADED | LOCAL] CHECK OPTION]
The CREATE VIEW
statement creates a
new view, or replaces an existing view if the OR
REPLACE
clause is given. If the view does not exist,
CREATE OR REPLACE
VIEW
is the same as CREATE
VIEW
. If the view does exist,
CREATE OR REPLACE
VIEW
replaces it.
For information about restrictions on view use, see Section 25.9, “Restrictions on Views”.
The select_statement
is a
SELECT
statement that provides the
definition of the view. (Selecting from the view selects, in
effect, using the SELECT
statement.) The select_statement
can
select from base tables, other views. Beginning with MySQL 8.0.19,
the SELECT
statement can use a
VALUES
statement as its source, or
can be replaced with a TABLE
statement, as with
CREATE TABLE
... SELECT
.
The view definition is “frozen” at creation time and
is not affected by subsequent changes to the definitions of the
underlying tables. 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, and columns dropped
from the table result in an error when selecting from 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. If the DEFINER
clause is present, the
privileges required depend on the user
value, as discussed in Section 25.6, “Stored Object Access Control”.
When a view is referenced, privilege checking occurs as described later in this section.
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, use db_name.view_name
syntax
to qualify the view name with the database name:
CREATE VIEW test.v AS SELECT * FROM t;
Unqualified table or view names in the
SELECT
statement are also
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 appropriate database name.
Within a database, base tables and views share the same namespace, so a base table and a view cannot have the same name.
Columns retrieved by the SELECT
statement can be simple references to table columns, or
expressions that use functions, constant values, operators, and so
forth.
A view must have unique column names with no duplicates, just like
a base table. 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, specify the optional
column_list
clause 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.
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:
CREATE VIEW v_today (today) AS SELECT CURRENT_DATE;
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 refer to system variables or user-defined variables.Within a stored program, the
SELECT
statement 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. If, after the view has been created, a table or view that the definition refers to is dropped, 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 aTEMPORARY
view.You cannot associate a trigger with a view.
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 permitted 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
,
FOR SHARE
, LOCK IN SHARE
MODE
, and PROCEDURE
.
The results obtained from a view may be affected if you change the query processing environment by changing system variables:
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. The valid SQL SECURITY
characteristic values are DEFINER
(the default)
and INVOKER
. These indicate that the required
privileges must be held by the user who defined or invoked the
view, respectively.
If the DEFINER
clause is present, the
user
value should be a MySQL account
specified as
'
,
user_name
'@'host_name
'CURRENT_USER
, or
CURRENT_USER()
. The permitted
user
values depend on the privileges
you hold, as discussed in
Section 25.6, “Stored Object Access Control”. Also see that section
for additional information about view security.
If the DEFINER
clause is omitted, the default
definer is the user who executes the CREATE
VIEW
statement. This is the same as specifying
DEFINER = CURRENT_USER
explicitly.
Within a view definition, the
CURRENT_USER
function returns the
view's DEFINER
value by default. 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 6.2.22, “SQL-Based Account Activity Auditing”.
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 routine, if the view definition contains a
DEFINER
value of
CURRENT_USER
.
MySQL checks view privileges 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 some privilege for each column in the select list of the definition, and the
SELECT
privilege for each column used elsewhere in the definition. If the definition refers to a stored function, only the privileges needed to invoke the function can be checked. The privileges required at function invocation time can be checked only as it executes: For different invocations, different execution paths within the function might be taken.The user who references a view must have appropriate privileges to access it (
SELECT
to select from it,INSERT
to insert into it, and so forth.)When a view has been referenced, privileges for objects accessed by the view are checked against the privileges held by the view
DEFINER
account or invoker, depending on whether theSQL SECURITY
characteristic isDEFINER
orINVOKER
, 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
SQL SECURITY
characteristic isDEFINER
orINVOKER
. If the security characteristic isDEFINER
, the function runs with the privileges of theDEFINER
account. If the characteristic isINVOKER
, the function runs with the privileges determined by the view'sSQL SECURITY
characteristic.
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.
This is why the default DEFINER
value is the
account of the view creator.
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
. For more information, see
Section 25.5.2, “View Processing Algorithms”, as well as
Section 8.2.2.4, “Optimizing Derived Tables, View References, and Common Table Expressions
with Merging or Materialization”.
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.
A generated column in a view is considered updatable because it is
possible to assign to it. However, if such a column is updated
explicitly, the only permitted value is
DEFAULT
. For information about generated
columns, see Section 13.1.20.8, “CREATE TABLE and Generated Columns”.
The WITH CHECK OPTION
clause can be given for
an updatable view to prevent inserts or updates to rows except
those for which the WHERE
clause in the
select_statement
is true.
In a WITH CHECK OPTION
clause for an updatable
view, the LOCAL
and CASCADED
keywords determine the scope of check testing when the view is
defined in terms of another view. The LOCAL
keyword restricts the CHECK OPTION
only to the
view being defined. CASCADED
causes the checks
for underlying views to be evaluated as well. When neither keyword
is given, the default is CASCADED
.
For more information about updatable views and the WITH
CHECK OPTION
clause, see
Section 25.5.3, “Updatable and Insertable Views”, and
Section 25.5.4, “The View WITH CHECK OPTION Clause”.
DROP {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
.
When a database is dropped, privileges granted specifically for the database are not automatically dropped. They must be dropped manually. See Section 13.7.1.6, “GRANT Statement”.
IF EXISTS
is used to prevent an error from
occurring if the database does not exist.
If the default database is dropped, the default database is unset
(the DATABASE()
function returns
NULL
).
If you use DROP DATABASE
on a
symbolically linked database, both the link and the original
database are deleted.
DROP DATABASE
returns the number of
tables that were removed.
The DROP DATABASE
statement removes
from the given database directory those files and directories that
MySQL itself may create during normal operation. This includes all
files with the extensions shown in the following list:
.BAK
.DAT
.HSH
.MRG
.MYD
.MYI
.cfg
.db
.ibd
.ndb
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.
Dropping a database does not remove any
TEMPORARY
tables that were created in that
database. TEMPORARY
tables are automatically
removed when the session that created them ends. See
Section 13.1.20.2, “CREATE TEMPORARY TABLE Statement”.
You can also drop databases with mysqladmin. See Section 4.5.2, “mysqladmin — A MySQL Server Administration Program”.
DROP EVENT [IF EXISTS] event_name
This statement drops the event named
event_name
. The event immediately
ceases being active, and is deleted completely from the server.
If the event does not exist, the error ERROR 1517
(HY000): Unknown event
'event_name
' results. You
can override this and cause the statement to generate a warning
for nonexistent events instead using IF EXISTS
.
This statement requires the EVENT
privilege for the schema to which the event to be dropped belongs.
The DROP FUNCTION
statement is used
to drop stored functions and user-defined functions (UDFs):
For information about dropping stored functions, see Section 13.1.29, “DROP PROCEDURE and DROP FUNCTION Statements”.
For information about dropping user-defined functions, see Section 13.7.4.2, “DROP FUNCTION Statement for User-Defined Functions”.
DROP INDEXindex_name
ONtbl_name
[algorithm_option
|lock_option
] ...algorithm_option
: ALGORITHM [=] {DEFAULT | INPLACE | COPY}lock_option
: LOCK [=] {DEFAULT | NONE | SHARED | EXCLUSIVE}
DROP INDEX
drops the index named
index_name
from the table
tbl_name
. This statement is mapped to
an ALTER TABLE
statement to drop
the index. See Section 13.1.9, “ALTER TABLE Statement”.
To drop a primary key, the index name is always
PRIMARY
, which must be specified as a quoted
identifier because PRIMARY
is a reserved word:
DROP INDEX `PRIMARY` ON t;
Indexes on variable-width columns of
NDB
tables are dropped online; that
is, without any table copying. The table is not locked against
access from other NDB Cluster API nodes, although it is locked
against other operations on the same API node
for the duration of the operation. This is done automatically by
the server whenever it determines that it is possible to do so;
you do not have to use any special SQL syntax or server options to
cause it to happen.
ALGORITHM
and LOCK
clauses
may be given to influence the table copying method and level of
concurrency for reading and writing the table while its indexes
are being modified. They have the same meaning as for the
ALTER TABLE
statement. For more
information, see Section 13.1.9, “ALTER TABLE Statement”
MySQL NDB Cluster supports online operations using the same
ALGORITHM=INPLACE
syntax supported in the
standard MySQL Server. See
Section 23.5.11, “Online Operations with ALTER TABLE in NDB Cluster”, for more
information.
DROP LOGFILE GROUPlogfile_group
ENGINE [=]engine_name
This statement drops the log file group named
logfile_group
. The log file group must
already exist or an error results. (For information on creating
log file groups, see Section 13.1.16, “CREATE LOGFILE GROUP Statement”.)
Before dropping a log file group, you must drop all tablespaces
that use that log file group for UNDO
logging.
The required ENGINE
clause provides the name of
the storage engine used by the log file group to be dropped.
Currently, the only permitted values for
engine_name
are
NDB
and
NDBCLUSTER
.
DROP LOGFILE GROUP
is useful only
with Disk Data storage for NDB Cluster. See
Section 23.5.10, “NDB Cluster Disk Data Tables”.
DROP {PROCEDURE | FUNCTION} [IF EXISTS] sp_name
These statements are used to drop a stored routine (a stored
procedure or function). That is, the specified routine is removed
from the server. (DROP FUNCTION
is also used to
drop user-defined functions; see
Section 13.7.4.2, “DROP FUNCTION Statement for User-Defined Functions”.)
To drop a stored routine, you must have the
ALTER ROUTINE
privilege for it. (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 25.2.2, “Stored Routines and MySQL Privileges”.)
The IF EXISTS
clause is a MySQL extension. It
prevents an error from occurring if the procedure or function does
not exist. A warning is produced that can be viewed with
SHOW WARNINGS
.
DROP FUNCTION
is also used to drop
user-defined functions (see Section 13.7.4.2, “DROP FUNCTION Statement for User-Defined Functions”).
DROP SERVER [ IF EXISTS ] server_name
Drops the server definition for the server named
. The
corresponding row in the server_name
mysql.servers
table is
deleted. This statement requires the
SUPER
privilege.
Dropping a server for a table does not affect any
FEDERATED
tables that used this connection
information when they were created. See
Section 13.1.18, “CREATE SERVER Statement”.
DROP SERVER
causes an implicit commit. See
Section 13.3.3, “Statements That Cause an Implicit Commit”.
DROP SERVER
is not written to the binary log,
regardless of the logging format that is in use.
DROP SPATIAL REFERENCE SYSTEM [IF EXISTS]srid
srid
:32-bit unsigned integer
This statement removes a
spatial reference
system (SRS) definition from the data dictionary. It
requires the SUPER
privilege.
Example:
DROP SPATIAL REFERENCE SYSTEM 4120;
If no SRS definition with the SRID value exists, an error occurs
unless IF EXISTS
is specified. In that case, a
warning occurs rather than an error.
If the SRID value is used by some column in an existing table, an error occurs. For example:
mysql> DROP SPATIAL REFERENCE SYSTEM 4326;
ERROR 3716 (SR005): Can't modify SRID 4326. There is at
least one column depending on it.
To identify which column or columns use the SRID, use this query:
SELECT * FROM INFORMATION_SCHEMA.ST_GEOMETRY_COLUMNS WHERE SRS_ID=4326;
SRID values must be in the range of 32-bit unsigned integers, with these restrictions:
SRID 0 is a valid SRID but cannot be used with
DROP SPATIAL REFERENCE SYSTEM
.If the value is in a reserved SRID range, a warning occurs. Reserved ranges are [0, 32767] (reserved by EPSG), [60,000,000, 69,999,999] (reserved by EPSG), and [2,000,000,000, 2,147,483,647] (reserved by MySQL). EPSG stands for the European Petroleum Survey Group.
Users should not drop SRSs with SRIDs in the reserved ranges. If system-installed SRSs are dropped, the SRS definitions may be recreated for MySQL upgrades.
DROP [TEMPORARY] TABLE [IF EXISTS]tbl_name
[,tbl_name
] ... [RESTRICT | CASCADE]
DROP TABLE
removes one or more
tables. You must have the DROP
privilege for each table.
Be careful with this statement! For each table, it removes the table definition and all table data. If the table is partitioned, the statement removes the table definition, all its partitions, all data stored in those partitions, and all partition definitions associated with the dropped table.
Dropping a table also drops any triggers for the table.
DROP TABLE
causes an implicit
commit, except when used with the TEMPORARY
keyword. See Section 13.3.3, “Statements That Cause an Implicit Commit”.
When a table is dropped, privileges granted specifically for the table are not automatically dropped. They must be dropped manually. See Section 13.7.1.6, “GRANT Statement”.
If any tables named in the argument list do not exist,
DROP TABLE
behavior depends on
whether the IF EXISTS
clause is given:
Without
IF EXISTS
, the statement fails with an error indicating which nonexisting tables it was unable to drop, and no changes are made.With
IF EXISTS
, no error occurs for nonexisting tables. The statement drops all named tables that do exist, and generates aNOTE
diagnostic for each nonexistent table. These notes can be displayed withSHOW WARNINGS
. See Section 13.7.7.42, “SHOW WARNINGS Statement”.
IF EXISTS
can also be useful for dropping
tables in unusual circumstances under which there is an entry in
the data dictionary but no table managed by the storage engine.
(For example, if an abnormal server exit occurs after removal of
the table from the storage engine but before removal of the data
dictionary entry.)
The TEMPORARY
keyword has the following
effects:
The statement drops only
TEMPORARY
tables.The statement does not cause an implicit commit.
No access rights are checked. A
TEMPORARY
table is visible only with the session that created it, so no check is necessary.
Including the TEMPORARY
keyword is a good way
to prevent accidentally dropping non-TEMPORARY
tables.
The RESTRICT
and CASCADE
keywords do nothing. They are permitted to make porting easier
from other database systems.
DROP TABLE
is not supported with
all innodb_force_recovery
settings. See Section 15.21.2, “Forcing InnoDB Recovery”.
DROP [UNDO] TABLESPACEtablespace_name
[ENGINE [=]engine_name
]
This statement drops a tablespace that was previously created
using CREATE TABLESPACE
. It is
supported by the NDB
and
InnoDB
storage engines.
The UNDO
keyword, introduced in MySQL 8.0.14,
must be specified to drop an undo tablespace. Only undo
tablespaces created using
CREATE UNDO
TABLESPACE
syntax can be dropped. An undo tablespace
must be in an empty
state before it can be
dropped. For more information, see
Section 15.6.3.4, “Undo Tablespaces”.
ENGINE
sets the storage engine that uses the
tablespace, where engine_name
is the
name of the storage engine. Currently, the values
InnoDB
and NDB
are
supported. If not set, the value of
default_storage_engine
is used.
If it is not the same as the storage engine used to create the
tablespace, the DROP TABLESPACE
statement
fails.
is a
case-sensitive identifier in MySQL.
tablespace_name
For an InnoDB
general tablespace, all tables
must be dropped from the tablespace prior to a DROP
TABLESPACE
operation. If the tablespace is not empty,
DROP TABLESPACE
returns an error.
An NDB
tablespace to be dropped must not
contain any data files; in other words, before you can drop an
NDB
tablespace, you must first drop each of its
data files using
ALTER TABLESPACE
... DROP DATAFILE
.
Notes
A general
InnoDB
tablespace is not deleted automatically when the last table in the tablespace is dropped. The tablespace must be dropped explicitly usingDROP TABLESPACE
.tablespace_name
A
DROP DATABASE
operation can drop tables that belong to a general tablespace but it cannot drop the tablespace, even if the operation drops all tables that belong to the tablespace. The tablespace must be dropped explicitly usingDROP TABLESPACE
.tablespace_name
Similar to the system tablespace, truncating or dropping tables stored in a general tablespace creates free space internally in the general tablespace .ibd data file which can only be used for new
InnoDB
data. Space is not released back to the operating system as it is for file-per-table tablespaces.
InnoDB Examples
This example demonstrates how to drop an InnoDB
general tablespace. The general tablespace ts1
is created with a single table. Before dropping the tablespace,
the table must be dropped.
mysql>CREATE TABLESPACE `ts1` ADD DATAFILE 'ts1.ibd' Engine=InnoDB;
mysql>CREATE TABLE t1 (c1 INT PRIMARY KEY) TABLESPACE ts1 Engine=InnoDB;
mysql>DROP TABLE t1;
mysql>DROP TABLESPACE ts1;
This example demonstrates dropping an undo tablespace. An undo
tablespace must be in an empty
state before it
can be dropped. For more information, see
Section 15.6.3.4, “Undo Tablespaces”.
mysql> DROP UNDO TABLESPACE undo_003
;
NDB Example
This example shows how to drop an NDB
tablespace myts
having a data file named
mydata-1.dat
after first creating the
tablespace, and assumes the existence of a log file group named
mylg
(see
Section 13.1.16, “CREATE LOGFILE GROUP Statement”).
mysql>CREATE TABLESPACE myts
->ADD DATAFILE 'mydata-1.dat'
->USE LOGFILE GROUP mylg
->ENGINE=NDB;
You must remove all data files from the tablespace using
ALTER TABLESPACE
, as shown here,
before it can be dropped:
mysql>ALTER TABLESPACE myts
->DROP DATAFILE 'mydata-1.dat'
->ENGINE=NDB;
mysql>DROP TABLESPACE myts;
DROP 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
requires the TRIGGER
privilege for
the table associated with the trigger.
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 13.7.7.42, “SHOW WARNINGS Statement”.
Triggers for a table are also dropped if you drop the table.
DROP 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 views named in the argument list do not exist, the statement fails with an error indicating by name which nonexisting views it was unable to drop, and no changes are made.
In MySQL 5.7 and earlier,
DROP VIEW
returns an error if any
views named in the argument list do not exist, but also drops
all views in the list that do exist. Due to the change in
behavior in MySQL 8.0, a partially completed
DROP VIEW
operation on a MySQL
5.7 replication source server fails when
replicated on a MySQL 8.0 replica. To avoid this
failure scenario, use IF EXISTS
syntax in
DROP VIEW
statements to prevent
an error from occurring for views that do not exist. For more
information, see Section 13.1.1, “Atomic Data Definition Statement Support”.
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 13.7.7.42, “SHOW WARNINGS Statement”.
RESTRICT
and CASCADE
, if
given, are parsed and ignored.
RENAME TABLEtbl_name
TOnew_tbl_name
[,tbl_name2
TOnew_tbl_name2
] ...
RENAME TABLE
renames one or more
tables. You must have ALTER
and
DROP
privileges for the original
table, and CREATE
and
INSERT
privileges for the new
table.
For example, to rename a table named old_table
to new_table
, use this statement:
RENAME TABLE old_table TO new_table;
That statement is equivalent to the following
ALTER TABLE
statement:
ALTER TABLE old_table RENAME new_table;
RENAME TABLE
, unlike ALTER
TABLE
, can rename multiple tables within a single
statement:
RENAME TABLE old_table1 TO new_table1, old_table2 TO new_table2, old_table3 TO new_table3;
Renaming operations are performed left to right. Thus, to swap two
table names, do this (assuming that a table with the intermediary
name tmp_table
does not already exist):
RENAME TABLE old_table TO tmp_table, new_table TO old_table, tmp_table TO new_table;
Metadata locks on tables are acquired in name order, which in some cases can make a difference in operation outcome when multiple transactions execute concurrently. See Section 8.11.4, “Metadata Locking”.
As of MySQL 8.0.13, you can rename tables locked with a
LOCK TABLES
statement, provided
that they are locked with a WRITE
lock or are
the product of renaming WRITE
-locked tables
from earlier steps in a multiple-table rename operation. For
example, this is permitted:
LOCK TABLE old_table1 WRITE; RENAME TABLE old_table1 TO new_table1, new_table1 TO new_table2;
This is not permitted:
LOCK TABLE old_table1 READ; RENAME TABLE old_table1 TO new_table1, new_table1 TO new_table2;
Prior to MySQL 8.0.13, to execute RENAME TABLE
,
there must be no tables locked with LOCK
TABLES
.
With the transaction table locking conditions satisfied, the rename operation is done atomically; no other session can access any of the tables while the rename is in progress.
If any errors occur during a RENAME TABLE
, the
statement fails and no changes are made.
You can use RENAME TABLE
to move a table from
one database to another:
RENAME TABLEcurrent_db.tbl_name
TOother_db.tbl_name;
Using this method to move all tables from one database to a different one in effect renames the database (an operation for which MySQL has no single statement), except that the original database continues to exist, albeit with no tables.
Like RENAME TABLE
, ALTER TABLE ...
RENAME
can also be used to move a table to a different
database. Regardless of the statement used, if the rename
operation would move the table to a database located on a
different file system, the success of the outcome is platform
specific and depends on the underlying operating system calls used
to move table files.
If a table has triggers, attempts to rename the table into a
different database fail with a Trigger in wrong
schema
(ER_TRG_IN_WRONG_SCHEMA
) error.
An unencrypted table can be moved to an encryption-enabled
database and vice versa. However, if the
table_encryption_privilege_check
variable is enabled, the
TABLE_ENCRYPTION_ADMIN
privilege is
required if the table encryption setting differs from the default
database encryption.
To rename TEMPORARY
tables, RENAME
TABLE
does not work. Use ALTER
TABLE
instead.
RENAME TABLE
works for views, except that views
cannot be renamed into a different database.
Any privileges granted specifically for a renamed table or view are not migrated to the new name. They must be changed manually.
RENAME TABLE
changes
internally generated foreign key constraint names and user-defined
foreign key constraint names that begin with the string
“tbl_name
TO
new_tbl_name
tbl_name
_ibfk_” to
reflect the new table name. InnoDB
interprets
foreign key constraint names that begin with the string
“tbl_name
_ibfk_” as
internally generated names.
Foreign key constraint names that point to the renamed table are automatically updated unless there is a conflict, in which case the statement fails with an error. A conflict occurs if the renamed constraint name already exists. In such cases, you must drop and re-create the foreign keys for them to function properly.
RENAME TABLE
changes
internally generated and user-defined tbl_name
TO
new_tbl_name
CHECK
constraint names that begin with the string
“tbl_name
_chk_” to reflect
the new table name. MySQL interprets CHECK
constraint names that begin with the string
“tbl_name
_chk_” as
internally generated names. Example:
mysql>SHOW CREATE TABLE t1\G
*************************** 1. row *************************** Table: t1 Create Table: CREATE TABLE `t1` ( `i1` int(11) DEFAULT NULL, `i2` int(11) DEFAULT NULL, CONSTRAINT `t1_chk_1` CHECK ((`i1` > 0)), CONSTRAINT `t1_chk_2` CHECK ((`i2` < 0)) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci 1 row in set (0.02 sec) mysql>RENAME TABLE t1 TO t3;
Query OK, 0 rows affected (0.03 sec) mysql>SHOW CREATE TABLE t3\G
*************************** 1. row *************************** Table: t3 Create Table: CREATE TABLE `t3` ( `i1` int(11) DEFAULT NULL, `i2` int(11) DEFAULT NULL, CONSTRAINT `t3_chk_1` CHECK ((`i1` > 0)), CONSTRAINT `t3_chk_2` CHECK ((`i2` < 0)) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci 1 row in set (0.01 sec)
TRUNCATE [TABLE] tbl_name
TRUNCATE TABLE
empties a table
completely. It requires the DROP
privilege. Logically, TRUNCATE
TABLE
is similar to a
DELETE
statement that deletes all
rows, or a sequence of DROP TABLE
and CREATE TABLE
statements.
To achieve high performance, TRUNCATE
TABLE
bypasses the DML method of deleting data. Thus, it
does not cause ON DELETE
triggers to fire, it
cannot be performed for InnoDB
tables with
parent-child foreign key relationships, and it cannot be rolled
back like a DML operation. However, TRUNCATE
TABLE
operations on tables that use an atomic
DDL-supported storage engine are either fully committed or rolled
back if the server halts during their operation. For more
information, see Section 13.1.1, “Atomic Data Definition Statement Support”.
Although TRUNCATE TABLE
is similar
to DELETE
, it is classified as a
DDL statement rather than a DML statement. It differs from
DELETE
in the following ways:
Truncate operations drop and re-create the table, which is much faster than deleting rows one by one, particularly for large tables.
Truncate operations cause an implicit commit, and so cannot be rolled back. See Section 13.3.3, “Statements That Cause an Implicit Commit”.
Truncation operations cannot be performed if the session holds an active table lock.
TRUNCATE TABLE
fails for anInnoDB
table orNDB
table if there are anyFOREIGN KEY
constraints from other tables that reference the table. Foreign key constraints between columns of the same table are permitted.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 definition 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.Any
AUTO_INCREMENT
value is reset to its start value. This is true even forMyISAM
andInnoDB
, which normally do not reuse sequence values.When used with partitioned tables,
TRUNCATE TABLE
preserves the partitioning; that is, the data and index files are dropped and re-created, while the partition definitions are unaffected.The
TRUNCATE TABLE
statement does not invokeON DELETE
triggers.Truncating a corrupted
InnoDB
table is supported.
TRUNCATE TABLE
for a table closes
all handlers for the table that were opened with
HANDLER OPEN
.
TRUNCATE TABLE
is treated for
purposes of binary logging and replication as
DROP TABLE
followed by
CREATE TABLE
—that is, as DDL
rather than DML. This is due to the fact that, when using
InnoDB
and other transactional
storage engines where the transaction isolation level does not
permit statement-based logging (READ
COMMITTED
or READ
UNCOMMITTED
), the statement was not logged and
replicated when using STATEMENT
or
MIXED
logging mode. (Bug #36763) However, it is
still applied on replicas using
InnoDB
in the manner described
previously.
In MySQL 5.7 and earlier, on a system with a large buffer pool and
innodb_adaptive_hash_index
enabled, a TRUNCATE TABLE
operation could cause
a temporary drop in system performance due to an LRU scan that
occurred when removing the table's adaptive hash index entries
(Bug #68184). The remapping of TRUNCATE
TABLE
to DROP TABLE
and
CREATE TABLE
in MySQL 8.0 avoids
the problematic LRU scan.
TRUNCATE TABLE
can be used with
Performance Schema summary tables, but the effect is to reset the
summary columns to 0 or NULL
, not to remove
rows. See Section 27.12.18, “Performance Schema Summary Tables”.
Truncating an InnoDB
table that resides in a
file-per-table tablespace drops the existing tablespace and
creates a new one. As of MySQL 8.0.21, if the tablespace was
created with an earlier version and resides in an unknown
directory, InnoDB
creates the new tablespace in
the default location and writes the following warning to the error
log: The DATA DIRECTORY location must be in a known
directory. The DATA DIRECTORY location will be ignored and the
file will be put into the default datadir location.
Known directories are those defined by the
datadir
,
innodb_data_home_dir
, and
innodb_directories
variables. To
have TRUNCATE TABLE
create the
tablespace in its current location, add the directory to the
innodb_directories
setting before
running TRUNCATE TABLE
.
- 13.2.1 CALL Statement
- 13.2.2 DELETE Statement
- 13.2.3 DO Statement
- 13.2.4 HANDLER Statement
- 13.2.5 IMPORT TABLE Statement
- 13.2.6 INSERT Statement
- 13.2.7 LOAD DATA Statement
- 13.2.8 LOAD XML Statement
- 13.2.9 REPLACE Statement
- 13.2.10 SELECT Statement
- 13.2.11 Subqueries
- 13.2.12 TABLE Statement
- 13.2.13 UPDATE Statement
- 13.2.14 VALUES Statement
- 13.2.15 WITH (Common Table Expressions)
CALLsp_name
([parameter
[,...]]) CALLsp_name
[()]
The CALL
statement invokes a stored
procedure that was defined previously with
CREATE PROCEDURE
.
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.
For information about the effect of unhandled conditions on procedure parameters, see Section 13.6.7.8, “Condition Handling and OUT or INOUT Parameters”.
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, you can see that the values of the two variables are
set or modified:
mysql>SET @increment = 10;
mysql>CALL p(@version, @increment);
mysql>SELECT @version, @increment;
+--------------------+------------+ | @version | @increment | +--------------------+------------+ | 8.0.3-rc-debug-log | 11 | +--------------------+------------+
In prepared CALL
statements used
with PREPARE
and
EXECUTE
, placeholders can be used
for IN
parameters, OUT
, and
INOUT
parameters. These types of parameters can
be used as follows:
mysql>SET @increment = 10;
mysql>PREPARE s FROM 'CALL p(?, ?)';
mysql>EXECUTE s USING @version, @increment;
mysql>SELECT @version, @increment;
+--------------------+------------+ | @version | @increment | +--------------------+------------+ | 8.0.3-rc-debug-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 produce result sets, so it is necessary to assume that
they do so.
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
).
CLIENT_MULTI_RESULTS
is enabled by default.
To process the result of a CALL
statement executed using
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
C API Multiple Statement Execution Support.
C programs can use the prepared-statement interface to execute
CALL
statements and access
OUT
and INOUT
parameters.
This is done by processing the result of a
CALL
statement using a loop that
calls mysql_stmt_next_result()
to
determine whether there are more results. For an example, see
C API Prepared CALL Statement Support. Languages that
provide a MySQL interface can use prepared
CALL
statements to directly
retrieve OUT
and INOUT
procedure parameters.
Metadata changes to objects referred to by stored programs are detected and cause automatic reparsing of the affected statements when the program is next executed. For more information, see Section 8.10.3, “Caching of Prepared Statements and Stored Programs”.
DELETE
is a DML statement that
removes rows from a table.
A DELETE
statement can start with a
WITH
clause to define common table
expressions accessible within the
DELETE
. See Section 13.2.15, “WITH (Common Table Expressions)”.
Single-Table Syntax
DELETE [LOW_PRIORITY] [QUICK] [IGNORE] FROMtbl_name
[[AS]tbl_alias
] [PARTITION (partition_name
[,partition_name
] ...)] [WHEREwhere_condition
] [ORDER BY ...] [LIMITrow_count
]
The DELETE
statement deletes rows from
tbl_name
and returns the number of
deleted rows. To check the number of deleted rows, call the
ROW_COUNT()
function described in
Section 12.16, “Information Functions”.
Main Clauses
The conditions in the optional WHERE
clause
identify which rows to delete. With no WHERE
clause, all rows are deleted.
where_condition
is an expression that
evaluates to true for each row to be deleted. It is specified as
described in Section 13.2.10, “SELECT Statement”.
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. These clauses apply to single-table
deletes, but not multi-table deletes.
Multiple-Table Syntax
DELETE [LOW_PRIORITY] [QUICK] [IGNORE]tbl_name
[.*] [,tbl_name
[.*]] ... FROMtable_references
[WHEREwhere_condition
] DELETE [LOW_PRIORITY] [QUICK] [IGNORE] FROMtbl_name
[.*] [,tbl_name
[.*]] ... USINGtable_references
[WHEREwhere_condition
]
Privileges
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.
Performance
When you do not need to know the number of deleted rows, the
TRUNCATE TABLE
statement is a
faster way to empty a table than a
DELETE
statement with no
WHERE
clause. Unlike
DELETE
,
TRUNCATE TABLE
cannot be used
within a transaction or if you have a lock on the table. See
Section 13.1.37, “TRUNCATE TABLE Statement” and
Section 13.3.6, “LOCK TABLES and UNLOCK TABLES Statements”.
The speed of delete operations may also be affected by factors discussed in Section 8.2.5.3, “Optimizing DELETE Statements”.
To ensure that a given DELETE
statement does not take too much time, the MySQL-specific
LIMIT
clause for row_count
DELETE
specifies the
maximum number of rows to be deleted. If the number of rows to
delete is larger than the limit, repeat the
DELETE
statement until the number of affected
rows is less than the LIMIT
value.
Subqueries
You cannot delete from a table and select from the same table in a subquery.
Partitioned Table Support
DELETE
supports explicit partition selection
using the PARTITION
option, which takes a list
of the comma-separated names of one or more partitions or
subpartitions (or both) from which to select rows to be dropped.
Partitions not included in the list are ignored. Given a
partitioned table t
with a partition named
p0
, executing the statement DELETE
FROM t PARTITION (p0)
has the same effect on the table
as executing ALTER
TABLE t TRUNCATE PARTITION (p0)
; in both cases, all rows
in partition p0
are dropped.
PARTITION
can be used along with a
WHERE
condition, in which case the condition is
tested only on rows in the listed partitions. For example,
DELETE FROM t PARTITION (p0) WHERE c < 5
deletes rows only from partition p0
for which
the condition c < 5
is true; rows in any
other partitions are not checked and thus not affected by the
DELETE
.
The PARTITION
option can also be used in
multiple-table DELETE
statements. You can use
up to one such option per table named in the
FROM
option.
For more information and examples, see Section 24.5, “Partition Selection”.
Auto-Increment Columns
If you delete the row containing the maximum value for an
AUTO_INCREMENT
column, the value is not reused
for a MyISAM
or InnoDB
table. If you delete all rows in the table with DELETE
FROM
(without a
tbl_name
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 15.6.1.6, “AUTO_INCREMENT Handling in InnoDB”.
For MyISAM
tables, you can specify an
AUTO_INCREMENT
secondary column in a
multiple-column key. In this case, reuse of values deleted from
the top of the sequence occurs even for MyISAM
tables. See Section 3.6.9, “Using AUTO_INCREMENT”.
Modifiers
The DELETE
statement supports the
following modifiers:
If you specify the
LOW_PRIORITY
modifier, the server delays execution of theDELETE
until no other clients are reading from the table. This affects only storage engines that use only table-level locking (such asMyISAM
,MEMORY
, andMERGE
).For
MyISAM
tables, if you use theQUICK
modifier, the storage engine does not merge index leaves during delete, which may speed up some kinds of delete operations.The
IGNORE
modifier causes MySQL to ignore ignorable 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 ofIGNORE
are returned as warnings. For more information, see The Effect of IGNORE on Statement Execution.
Order of Deletion
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
also helps to delete rows in an order
required to avoid referential integrity violations.
InnoDB Tables
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 13.1.36, “RENAME TABLE Statement”.
MyISAM Tables
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 13.7.3.4, “OPTIMIZE TABLE Statement”, and Section 4.6.4, “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.
Multi-Table Deletes
You can specify multiple tables in a
DELETE
statement to delete rows
from one or more tables depending on the condition in the
WHERE
clause. You cannot use ORDER
BY
or LIMIT
in a multiple-table
DELETE
. The
table_references
clause lists the
tables involved in the join, as described in
Section 13.2.10.2, “JOIN Clause”.
For the first multiple-table syntax, only matching rows from the
tables listed before the FROM
clause are
deleted. For the second multiple-table syntax, only matching rows
from the tables listed in the FROM
clause
(before the USING
clause) are deleted. The
effect is that you can delete rows from many tables at the same
time and have additional tables that are used only for searching:
DELETE t1, t2 FROM t1 INNER JOIN t2 INNER JOIN t3 WHERE t1.id=t2.id AND t2.id=t3.id;
Or:
DELETE FROM t1, t2 USING t1 INNER JOIN t2 INNER JOIN t3 WHERE t1.id=t2.id AND t2.id=t3.id;
These statements use all three tables when searching for rows to
delete, but delete matching rows only from tables
t1
and t2
.
The preceding examples use INNER JOIN
, but
multiple-table DELETE
statements
can use other types of join permitted in
SELECT
statements, such as
LEFT JOIN
. For example, to delete rows that
exist in t1
that have no match in
t2
, use a LEFT JOIN
:
DELETE t1 FROM t1 LEFT JOIN t2 ON t1.id=t2.id WHERE t2.id IS NULL;
The syntax permits .*
after each
tbl_name
for compatibility with
Access.
If you use a multiple-table DELETE
statement involving InnoDB
tables for which
there are foreign key constraints, the MySQL optimizer might
process tables in an order that differs from that of their
parent/child relationship. In this case, the statement fails and
rolls back. Instead, you should delete from a single table and
rely on the ON DELETE
capabilities that
InnoDB
provides to cause the other tables to be
modified accordingly.
If you declare an alias for a table, you must use the alias when referring to the table:
DELETE t1 FROM test AS t1, test2 WHERE ...
Table aliases in a multiple-table
DELETE
should be declared only in
the table_references
part of the
statement. Elsewhere, alias references are permitted but not alias
declarations.
Correct:
DELETE a1, a2 FROM t1 AS a1 INNER JOIN t2 AS a2 WHERE a1.id=a2.id; DELETE FROM a1, a2 USING t1 AS a1 INNER JOIN t2 AS a2 WHERE a1.id=a2.id;
Incorrect:
DELETE t1 AS a1, t2 AS a2 FROM t1 INNER JOIN t2 WHERE a1.id=a2.id; DELETE FROM t1 AS a1, t2 AS a2 USING t1 INNER JOIN t2 WHERE a1.id=a2.id;
Table aliases are also supported for single-table
DELETE
statements beginning with MySQL 8.0.16.
(Bug #89410,Bug #27455809)
DOexpr
[,expr
] ...
DO
executes the expressions but
does not return any results. In most respects,
DO
is shorthand for SELECT
, but has the
advantage that it is slightly faster when you do not care about
the result.
expr
, ...
DO
is useful primarily with
functions that have side effects, such as
RELEASE_LOCK()
.
Example: This SELECT
statement
pauses, but also produces a result set:
mysql> SELECT SLEEP(5);
+----------+
| SLEEP(5) |
+----------+
| 0 |
+----------+
1 row in set (5.02 sec)
DO
, on the other hand, pauses
without producing a result set.:
mysql> DO SLEEP(5);
Query OK, 0 rows affected (4.99 sec)
This could be useful, for example in a stored function or trigger, which prohibit statements that produce result sets.
DO
only executes expressions. It
cannot be used in all cases where SELECT
can be
used. For example, DO id FROM t1
is invalid
because it references a table.
HANDLERtbl_name
OPEN [ [AS]alias
] HANDLERtbl_name
READindex_name
{ = | <= | >= | < | > } (value1
,value2
,...) [ WHEREwhere_condition
] [LIMIT ... ] HANDLERtbl_name
READindex_name
{ FIRST | NEXT | PREV | LAST } [ WHEREwhere_condition
] [LIMIT ... ] HANDLERtbl_name
READ { FIRST | NEXT } [ WHEREwhere_condition
] [LIMIT ... ] HANDLERtbl_name
CLOSE
The HANDLER
statement provides direct access to
table storage engine interfaces. It is available for
InnoDB
and MyISAM
tables.
The HANDLER ... OPEN
statement opens a table,
making it accessible using subsequent HANDLER ...
READ
statements. This table object is not shared by
other sessions and is not closed until the session calls
HANDLER ... CLOSE
or the session terminates.
If you open the table using an alias, further references to the
open table with other HANDLER
statements must
use the alias rather than the table name. If you do not use an
alias, but open the table using a table name qualified by the
database name, further references must use the unqualified table
name. For example, for a table opened using
mydb.mytable
, further references must use
mytable
.
The first HANDLER ... READ
syntax fetches a row
where the index specified satisfies the given values and the
WHERE
condition is met. If you have a
multiple-column index, specify the index column values as a
comma-separated list. Either specify values for all the columns in
the index, or specify values for a leftmost prefix of the index
columns. Suppose that an index my_idx
includes
three columns named col_a
,
col_b
, and col_c
, in that
order. The HANDLER
statement can specify values
for all three columns in the index, or for the columns in a
leftmost prefix. For example:
HANDLER ... READ my_idx = (col_a_val,col_b_val,col_c_val) ... HANDLER ... READ my_idx = (col_a_val,col_b_val) ... HANDLER ... READ my_idx = (col_a_val) ...
To employ the HANDLER
interface to refer to a
table's PRIMARY KEY
, use the quoted identifier
`PRIMARY`
:
HANDLER tbl_name
READ `PRIMARY` ...
The second HANDLER ... READ
syntax fetches a
row from the table in index order that matches the
WHERE
condition.
The third HANDLER ... READ
syntax fetches a row
from the table in natural row order that matches the
WHERE
condition. It is faster than
HANDLER
when a full table
scan is desired. Natural row order is the order in which rows are
stored in a tbl_name
READ
index_name
MyISAM
table data file. This
statement works for InnoDB
tables as well, but
there is no such concept because there is no separate data file.
Without a LIMIT
clause, all forms of
HANDLER ... READ
fetch a single row if one is
available. To return a specific number of rows, include a
LIMIT
clause. It has the same syntax as for the
SELECT
statement. See
Section 13.2.10, “SELECT Statement”.
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 thanSELECT
:A designated storage engine handler object is allocated for the
HANDLER ... OPEN
. The object is reused for subsequentHANDLER
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 handler interface does not have to provide a consistent look of the data (for example, dirty reads are permitted), so the storage engine can use optimizations that
SELECT
does not normally permit.
HANDLER
makes it easier to port to MySQL applications that use a low-levelISAM
-like interface. (See Section 15.20, “InnoDB memcached Plugin” for an alternative way to adapt applications that use the key-value store paradigm.)HANDLER
enables you to traverse a database in a manner that is difficult (or even impossible) to accomplish withSELECT
. TheHANDLER
interface is a more natural way to look at data when working with applications that provide an interactive user interface to the database.
HANDLER
is a somewhat low-level statement. For
example, it does not provide consistency. That is,
HANDLER ... OPEN
does not
take a snapshot of the table, and does not
lock the table. This means that after a HANDLER ...
OPEN
statement is issued, table data can be modified (by
the current session or other sessions) and these modifications
might be only partially visible to HANDLER ...
NEXT
or HANDLER ... PREV
scans.
An open handler can be closed and marked for reopen, in which case the handler loses its position in the table. This occurs when both of the following circumstances are true:
Any session executes
FLUSH TABLES
or DDL statements on the handler's table.The session in which the handler is open executes non-
HANDLER
statements that use tables.
TRUNCATE TABLE
for a table closes
all handlers for the table that were opened with
HANDLER OPEN
.
If a table is flushed with
FLUSH
TABLES
was opened with tbl_name
WITH READ
LOCKHANDLER
, the
handler is implicitly flushed and loses its position.
IMPORT TABLE FROMsdi_file
[,sdi_file
] ...
The IMPORT TABLE
statement imports
MyISAM
tables based on information contained in
.sdi
(serialized dictionary information)
metadata files. IMPORT TABLE
requires the FILE
privilege to read
the .sdi
and table content files, and the
CREATE
privilege for the table to
be created.
Tables can be exported from one server using
mysqldump to write a file of SQL statements and
imported into another server using mysql to
process the dump file. IMPORT TABLE
provides a faster alternative using the “raw” table
files.
Prior to import, the files that provide the table content must be
placed in the appropriate schema directory for the import server,
and the .sdi
file must be located in a
directory accessible to the server. For example, the
.sdi
file can be placed in the directory
named by the secure_file_priv
system variable, or (if
secure_file_priv
is empty) in a
directory under the server data directory.
The following example describes how to export
MyISAM
tables named
employees
and managers
from
the hr
schema of one server and import them
into the hr
schema of another server. The
example uses these assumptions (to perform a similar operation on
your own system, modify the path names as appropriate):
For the export server,
export_basedir
represents its base directory, and its data directory is
.export_basedir
/dataFor the import server,
import_basedir
represents its base directory, and its data directory is
.import_basedir
/dataTable files are exported from the export server into the
/tmp/export
directory and this directory is secure (not accessible to other users).The import server uses
/tmp/mysql-files
as the directory named by itssecure_file_priv
system variable.
To export tables from the export server, use this procedure:
Ensure a consistent snapshot by executing this statement to lock the tables so that they cannot be modified during export:
mysql>
FLUSH TABLES hr.employees, hr.managers WITH READ LOCK;
While the lock is in effect, the tables can still be used, but only for read access.
At the file system level, copy the
.sdi
and table content files from thehr
schema directory to the secure export directory:The
.sdi
file is located in thehr
schema directory, but might not have exactly the same basename as the table name. For example, the.sdi
files for theemployees
andmanagers
tables might be namedemployees_125.sdi
andmanagers_238.sdi
.For a
MyISAM
table, the content files are its.MYD
data file and.MYI
index file.
Given those file names, the copy commands look like this:
shell>
cd
shell>export_basedir
/data/hrcp employees_125.sdi /tmp/export
shell>cp managers_238.sdi /tmp/export
shell>cp employees.{MYD,MYI} /tmp/export
shell>cp managers.{MYD,MYI} /tmp/export
Unlock the tables:
mysql>
UNLOCK TABLES;
To import tables into the import server, use this procedure:
The import schema must exist. If necessary, execute this statement to create it:
mysql>
CREATE SCHEMA hr;
At the file system level, copy the
.sdi
files to the import serversecure_file_priv
directory,/tmp/mysql-files
. Also, copy the table content files to thehr
schema directory:shell>
cd /tmp/export
shell>cp employees_125.sdi /tmp/mysql-files
shell>cp managers_238.sdi /tmp/mysql-files
shell>cp employees.{MYD,MYI}
shell>import_basedir
/data/hrcp managers.{MYD,MYI}
import_basedir
/data/hrImport the tables by executing an
IMPORT TABLE
statement that names the.sdi
files:mysql>
IMPORT TABLE FROM
'/tmp/mysql-files/employees.sdi',
'/tmp/mysql-files/managers.sdi';
The .sdi
file need not be placed in the
import server directory named by the
secure_file_priv
system variable
if that variable is empty; it can be in any directory accessible
to the server, including the schema directory for the imported
table. If the .sdi
file is placed in that
directory, however, it may be rewritten; the import operation
creates a new .sdi
file for the table, which
overwrites the old .sdi
file if the operation
uses the same file name for the new file.
Each sdi_file
value must be a string
literal that names the .sdi
file for a table
or is a pattern that matches .sdi
files. If
the string is a pattern, any leading directory path and the
.sdi
file name suffix must be given
literally. Pattern characters are permitted only in the base name
part of the file name:
?
matches any single character*
matches any sequence of characters, including no characters
Using a pattern, the previous IMPORT
TABLE
statement could have been written like this
(assuming that the /tmp/mysql-files
directory
contains no other .sdi
files matching the
pattern):
IMPORT TABLE FROM '/tmp/mysql-files/*.sdi';
To interpret the location of .sdi
file path
names, the server uses the same rules for
IMPORT TABLE
as the server-side
rules for LOAD DATA
(that is, the
non-LOCAL
rules). See
Section 13.2.7, “LOAD DATA Statement”, paying particular attention to the
rules used to interpret relative path names.
IMPORT TABLE
fails if the
.sdi
or table files cannot be located. After
importing a table, the server attempts to open it and reports as
warnings any problems detected. To attempt a repair to correct any
reported issues, use REPAIR TABLE
.
IMPORT TABLE
is not written to the
binary log.
IMPORT TABLE
applies only to
non-TEMPORARY
MyISAM
tables. It does not apply to tables created with a transactional
storage engine, tables created with
CREATE TEMPORARY
TABLE
, or views.
An .sdi
file used in an import operation
must be generated on a server with the same data dictionary
version and sdi version as the import server. The version
information of the generating server is found in the
.sdi
file:
{ "mysqld_version_id":80019, "dd_version":80017, "sdi_version":80016, ... }
To determine the data dictionary and sdi version of the import
server, you can check the .sdi
file of a
recently created table on the import server.
The table data and index files must be placed in the schema
directory for the import server prior to the import operation,
unless the table as defined on the export server uses the
DATA DIRECTORY
or INDEX
DIRECTORY
table options. In that case, modify the
import procedure using one of these alternatives before
executing the IMPORT TABLE
statement:
Put the data and index files into the same directory on the import server host as on the export server host, and create symlinks in the import server schema directory to those files.
Put the data and index files into an import server host directory different from that on the export server host, and create symlinks in the import server schema directory to those files. In addition, modify the
.sdi
file to reflect the different file locations.Put the data and index files into the schema directory on the import server host, and modify the
.sdi
file to remove the data and index directory table options.
Any collation IDs stored in the .sdi
file
must refer to the same collations on the export and import
servers.
Trigger information for a table is not serialized into the table
.sdi
file, so triggers are not restored by
the import operation.
Some edits to an .sdi
file are permissible
prior to executing the IMPORT
TABLE
statement, whereas others are problematic or may
even cause the import operation to fail:
Changing the data directory and index directory table options is required if the locations of the data and index files differ between the export and import servers.
Changing the schema name is required to import the table into a different schema on the import server than on the export server.
Changing schema and table names may be required to accommodate differences between file system case-sensitivity semantics on the export and import servers or differences in
lower_case_table_names
settings. Changing the table names in the.sdi
file may require renaming the table files as well.In some cases, changes to column definitions are permitted. Changing data types is likely to cause problems.
INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE] [INTO]tbl_name
[PARTITION (partition_name
[,partition_name
] ...)] [(col_name
[,col_name
] ...)] { {VALUES | VALUE} (value_list
) [, (value_list
)] ... | VALUESrow_constructor_list
} [ASrow_alias
[(col_alias
[,col_alias
] ...)]] [ON DUPLICATE KEY UPDATEassignment_list
] INSERT [LOW_PRIORITY | DELAYED | HIGH_PRIORITY] [IGNORE] [INTO]tbl_name
[PARTITION (partition_name
[,partition_name
] ...)] [ASrow_alias
[(col_alias
[,col_alias
] ...)]] SETassignment_list
[ON DUPLICATE KEY UPDATEassignment_list
] INSERT [LOW_PRIORITY | HIGH_PRIORITY] [IGNORE] [INTO]tbl_name
[PARTITION (partition_name
[,partition_name
] ...)] [(col_name
[,col_name
] ...)] [ASrow_alias
[(col_alias
[,col_alias
] ...)]] {SELECT ... | TABLEtable_name
} [ON DUPLICATE KEY UPDATEassignment_list
]value
: {expr
| DEFAULT}value_list
:value
[,value
] ...row_constructor_list
: ROW(value_list
)[, ROW(value_list
)][, ...]assignment
:col_name
= [row_alias
.]value
assignment_list
:assignment
[,assignment
] ...
INSERT
inserts new rows into an
existing table. The INSERT
... VALUES
,
INSERT ... VALUES
ROW()
, 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. You can also use
INSERT ... TABLE
in MySQL 8.0.19 and later to insert rows from a single table.
INSERT
with an ON
DUPLICATE KEY UPDATE
clause enables existing rows to be
updated if a row to be inserted would cause a duplicate value in a
UNIQUE
index or PRIMARY KEY
.
In MySQL 8.0.19 and later, a row alias with one or more optional
column alises can be used with ON DUPLICATE KEY
UPDATE
to refer to the row to be inserted.
For additional information about
INSERT ...
SELECT
and
INSERT ... ON
DUPLICATE KEY UPDATE
, see
Section 13.2.6.1, “INSERT ... SELECT Statement”, and
Section 13.2.6.2, “INSERT ... ON DUPLICATE KEY UPDATE Statement”.
In MySQL 8.0, the DELAYED
keyword
is accepted but ignored by the server. For the reasons for this,
see Section 13.2.6.3, “INSERT DELAYED Statement”,
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).
When inserting into a partitioned table, you can control which
partitions and subpartitions accept new rows. The
PARTITION
option takes a list of the
comma-separated names of one or more partitions or subpartitions
(or both) of the table. If any of the rows to be inserted by a
given INSERT
statement do not match
one of the partitions listed, the
INSERT
statement fails with the
error Found a row not matching the given partition
set. For more information and examples, see
Section 24.5, “Partition Selection”.
tbl_name
is the table into which rows
should be inserted. Specify the columns for which the statement
provides values as follows:
Provide a parenthesized list of comma-separated column names following the table name. In this case, a value for each named column must be provided by the
VALUES
list,VALUES ROW()
list, orSELECT
statement. For theINSERT TABLE
form, the number of columns in the source table must match the number of columns to be inserted.If you do not specify a list of column names for
INSERT ... VALUES
orINSERT ... SELECT
, values for every column in the table must be provided by theVALUES
list,SELECT
statement, orTABLE
statement. If you do not know the order of the columns in the table, useDESCRIBE
to find out.tbl_name
A
SET
clause indicates columns explicitly by name, together with the value to assign each one.
Column values can be given in several ways:
If strict SQL mode is not enabled, 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 11.6, “Data Type Default Values”. See also Section 1.7.3.3, “Enforced Constraints on Invalid Data”.
If strict SQL mode is enabled, an
INSERT
statement generates an error if it does not specify an explicit value for every column that has no default value. See Section 5.1.11, “Server SQL Modes”.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();If strict mode is not enabled, MySQL uses the implicit default value for any column that has no explicitly defined default. If strict mode is enabled, an error occurs if any column has no default value.
Use the keyword
DEFAULT
to set a column explicitly to its default value. This makes it easier to writeINSERT
statements that assign values to all but a few columns, because it enables you to avoid writing an incompleteVALUES
list that does not include a value for each column in the table. Otherwise, you must provide the list of column names corresponding to each value in theVALUES
list.If a generated column is inserted into explicitly, the only permitted value is
DEFAULT
. For information about generated columns, see Section 13.1.20.8, “CREATE TABLE and Generated Columns”.In expressions, you can use
DEFAULT(
to produce the default value for columncol_name
)col_name
.Type conversion of an expression
expr
that provides a column value might occur if the expression data type does not match the column data type. Conversion of a given value can result in different inserted values depending on the column type. For example, inserting the string'1999.0e-2'
into anINT
,FLOAT
,DECIMAL(10,6)
, orYEAR
column inserts the value1999
,19.9921
,19.992100
, or1999
, respectively. The value stored in theINT
andYEAR
columns is1999
because the string-to-number conversion looks only at as much of the initial part of the string as may be considered a valid integer or year. For theFLOAT
and