+ + +
+
+
+
+ +
+ + + + +
+
+
+
+
+ + + + +
+
+
+
+ Documentation Home
+
MySQL 8.4 Reference Manual
+
+ + + Related Documentation +
+
+ MySQL 8.4 Release Notes
+
+
+ + + Download + this Manual + + +
+
+ PDF (US Ltr) + - 40.2Mb
+ PDF (A4) + - 40.3Mb
+ Man Pages (TGZ) + - 261.9Kb
+ Man Pages (Zip) + - 367.5Kb
+ Info (Gzip) + - 4.0Mb
+ Info (Zip) + - 4.0Mb
+
+
+

+
+
+
+
+
+ version 8.4 + + +
+ +
+ MySQL 8.4 Reference Manual  /  + ...  /  + + Online DDL Operations +
+
+
+
+
+
+

17.12.1 Online DDL Operations

+
+
+
+

+ Online support details, syntax examples, and usage notes for DDL + operations are provided under the following topics in this + section. +

+
+ +
+
+
+
+
+

Index Operations

+
+
+
+

+ The following table provides an overview of online DDL support + for index operations. An asterisk indicates additional + information, an exception, or a dependency. For details, see + Syntax and Usage Notes. +

+
+

Table 17.15 Online DDL Support for Index Operations

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperationInstantIn PlaceRebuilds TablePermits Concurrent DMLOnly Modifies Metadata
Creating or adding a secondary indexNoYesNoYesNo
Dropping an indexNoYesNoYesYes
Renaming an indexNoYesNoYesYes
Adding a FULLTEXT indexNoYes*No*NoNo
Adding a SPATIAL indexNoYesNoNoNo
Changing the index typeYesYesNoYesYes
+
+
+
+
Syntax and Usage Notes
+
+

  • + Creating or adding a secondary index + 

    CREATE INDEX name ON table (col_list);
    ALTER TABLE tbl_name ADD INDEX name (col_list);

    + The table remains available for read and write operations + while the index is being created. The + CREATE INDEX statement only + finishes after all transactions that are accessing the table + are completed, so that the initial state of the index + reflects the most recent contents of the table. +

    + Online DDL support for adding secondary indexes means that + you can generally speed the overall process of creating and + loading a table and associated indexes by creating the table + without secondary indexes, then adding secondary indexes + after the data is loaded. +

    + A newly created secondary index contains only the committed + data in the table at the time the + CREATE INDEX or + ALTER TABLE statement + finishes executing. It does not contain any uncommitted + values, old versions of values, or values marked for + deletion but not yet removed from the old index. +

    + Some factors affect the performance, space usage, and + semantics of this operation. For details, see + Section 17.12.8, “Online DDL Limitations”. +

  • + Dropping an index + 

    DROP INDEX name ON table;
    ALTER TABLE tbl_name DROP INDEX name;

    + The table remains available for read and write operations + while the index is being dropped. The + DROP INDEX statement only + finishes after all transactions that are accessing the table + are completed, so that the initial state of the index + reflects the most recent contents of the table. +

  • + Renaming an index + 

    ALTER TABLE tbl_name RENAME INDEX old_index_name TO new_index_name, ALGORITHM=INPLACE, LOCK=NONE;

  • + Adding a FULLTEXT index + 

    CREATE FULLTEXT INDEX name ON table(column);

    + Adding the first FULLTEXT index rebuilds + the table if there is no user-defined + FTS_DOC_ID column. Additional + FULLTEXT indexes may be added without + rebuilding the table. +

  • + Adding a SPATIAL index + 

    CREATE TABLE geom (g GEOMETRY NOT NULL);
+ALTER TABLE geom ADD SPATIAL INDEX(g), ALGORITHM=INPLACE, LOCK=SHARED;

  • + Changing the index type (USING {BTREE | + HASH}) + 

    ALTER TABLE tbl_name DROP INDEX i1, ADD INDEX i1(key_part,...) USING BTREE, ALGORITHM=INSTANT;
+
+
+
+
+
+
+

Primary Key Operations

+
+
+
+

+ The following table provides an overview of online DDL support + for primary key operations. An asterisk indicates additional + information, an exception, or a dependency. See + Syntax and Usage Notes. +

+
+

Table 17.16 Online DDL Support for Primary Key Operations

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperationInstantIn PlaceRebuilds TablePermits Concurrent DMLOnly Modifies Metadata
Adding a primary keyNoYes*Yes*YesNo
Dropping a primary keyNoNoYesNoNo
Dropping a primary key and adding anotherNoYesYesYesNo
+
+
+
+
Syntax and Usage Notes
+
+

  • + Adding a primary key + 

    ALTER TABLE tbl_name ADD PRIMARY KEY (column), ALGORITHM=INPLACE, LOCK=NONE;

    + Rebuilds the table in place. Data is reorganized + substantially, making it an expensive operation. + ALGORITHM=INPLACE is not permitted under + certain conditions if columns have to be converted to + NOT NULL. +

    + Restructuring the + clustered index + always requires copying of table data. Thus, it is best to + define the primary + key when you create a table, rather than issuing + ALTER TABLE ... ADD PRIMARY KEY later. +

    + When you create a UNIQUE or + PRIMARY KEY index, MySQL must do some + extra work. For UNIQUE indexes, MySQL + checks that the table contains no duplicate values for the + key. For a PRIMARY KEY index, MySQL also + checks that none of the PRIMARY KEY + columns contains a NULL. +

    + When you add a primary key using the + ALGORITHM=COPY clause, MySQL converts + NULL values in the associated columns to + default values: 0 for numbers, an empty string for + character-based columns and BLOBs, and 0000-00-00 00:00:00 + for DATETIME. This is a non-standard + behavior that Oracle recommends you not rely on. Adding a + primary key using ALGORITHM=INPLACE is + only permitted when the + SQL_MODE setting includes + the strict_trans_tables or + strict_all_tables flags; when the + SQL_MODE setting is strict, + ALGORITHM=INPLACE is permitted, but the + statement can still fail if the requested primary key + columns contain NULL values. The + ALGORITHM=INPLACE behavior is more + standard-compliant. +

    + If you create a table without a primary key, + InnoDB chooses one for you, which can be + the first UNIQUE key defined on + NOT NULL columns, or a system-generated + key. To avoid uncertainty and the potential space + requirement for an extra hidden column, specify the + PRIMARY KEY clause as part of the + CREATE TABLE statement. +

    + MySQL creates a new clustered index by copying the existing + data from the original table to a temporary table that has + the desired index structure. Once the data is completely + copied to the temporary table, the original table is renamed + with a different temporary table name. The temporary table + comprising the new clustered index is renamed with the name + of the original table, and the original table is dropped + from the database. +

    + The online performance enhancements that apply to operations + on secondary indexes do not apply to the primary key index. + The rows of an InnoDB table are stored in a + clustered index + organized based on the + primary key, forming + what some database systems call an “index-organized + table”. Because the table structure is closely tied + to the primary key, redefining the primary key still + requires copying the data. +

    + When an operation on the primary key uses + ALGORITHM=INPLACE, even though the data + is still copied, it is more efficient than using + ALGORITHM=COPY because: +

    +
    +

    • + No undo logging or associated redo logging is required + for ALGORITHM=INPLACE. These + operations add overhead to DDL statements that use + ALGORITHM=COPY. +

    • + The secondary index entries are pre-sorted, and so can + be loaded in order. +

    • + The change buffer is not used, because there are no + random-access inserts into the secondary indexes. +

    +
    +

  • + Dropping a primary key + 

    ALTER TABLE tbl_name DROP PRIMARY KEY, ALGORITHM=COPY;

    + Only ALGORITHM=COPY supports dropping a + primary key without adding a new one in the same + ALTER TABLE statement. +

  • + Dropping a primary key and adding another + 

    ALTER TABLE tbl_name DROP PRIMARY KEY, ADD PRIMARY KEY (column), ALGORITHM=INPLACE, LOCK=NONE;

    + Data is reorganized substantially, making it an expensive + operation. +

+
+
+
+
+
+
+

Column Operations

+
+
+
+

+ The following table provides an overview of online DDL support + for column operations. An asterisk indicates additional + information, an exception, or a dependency. For details, see + Syntax and Usage Notes. +

+
+

Table 17.17 Online DDL Support for Column Operations

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperationInstantIn PlaceRebuilds TablePermits Concurrent DMLOnly Modifies Metadata
Adding a columnYes*YesNo*Yes*Yes
Dropping a columnYes*YesYesYesYes
Renaming a columnYes*YesNoYes*Yes
Reordering columnsNoYesYesYesNo
Setting a column default valueYesYesNoYesYes
Changing the column data typeNoNoYesNoNo
Extending VARCHAR column sizeNoYesNoYesYes
Dropping the column default valueYesYesNoYesYes
Changing the auto-increment valueNoYesNoYesNo*
Making a column NULLNoYesYes*YesNo
Making a column NOT NULLNoYes*Yes*YesNo
Modifying the definition of an ENUM or + SET columnYesYesNoYesYes