From 2bc8451e88c8ab7d6c852a8f430bf146f02cd3e0 Mon Sep 17 00:00:00 2001 From: Nullnotnil Date: Fri, 3 Jul 2020 08:30:10 -0600 Subject: [PATCH 1/5] Improve MySQL Compatibility Better explain differences in DDL, ANALYZE TABLE, why features may not be offered. --- mysql-compatibility.md | 66 +++++++------------ sql-statements/sql-statement-analyze-table.md | 7 +- 2 files changed, 29 insertions(+), 44 deletions(-) diff --git a/mysql-compatibility.md b/mysql-compatibility.md index 723e8e16fb5bf..e34c4793e8655 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -9,7 +9,7 @@ aliases: ['/docs/dev/mysql-compatibility/','/docs/dev/reference/mysql-compatibil TiDB is fully compatible with the MySQL 5.7 protocol and the common features and syntax of MySQL 5.7. The ecosystem tools for MySQL 5.7 (PHPMyAdmin, Navicat, MySQL Workbench, mysqldump, and Mydumper/myloader) and the MySQL client can be used for TiDB. -However, some features of MySQL have not been implemented in the distributed database TiDB yet, or are only syntactically supported, because these features are difficult to implement or have low ROI (Return On Investment). +However, some features of MySQL are not supported. This could be because there is now a better way to solve the problem (such as XML functions superceded by JSON), security issues (such as SELECT INTO OUTFILE), or a lack of current demand versus effort required (such as stored procedures and functions). Some features may also be difficult to implement as a distributed system. > **Note:** > @@ -21,8 +21,8 @@ However, some features of MySQL have not been implemented in the distributed dat + Triggers + Events + User-defined functions -+ `FOREIGN KEY` constraints -+ `FULLTEXT`/`SPATIAL` functions and indexes ++ `FOREIGN KEY` constraints [#18209](https://github.com/pingcap/tidb/issues/18209) ++ `FULLTEXT`/`SPATIAL` functions and indexes [#1793](https://github.com/pingcap/tidb/issues/1793) + Character sets other than `utf8`, `utf8mb4`, `ascii`, `latin1` and `binary` + Add/drop primary key + SYS schema @@ -36,8 +36,8 @@ However, some features of MySQL have not been implemented in the distributed dat + `CREATE TEMPORARY TABLE` syntax + `CHECK TABLE` syntax + `CHECKSUM TABLE` syntax -+ `SELECT INTO FILE` syntax -+ `GET_LOCK` and `RELEASE_LOCK` functions ++ `SELECT INTO OUTFILE/DUMPFILE` syntax [#4350](https://github.com/pingcap/tidb/issues/4350) ++ `GET_LOCK` and `RELEASE_LOCK` functions [#14994](https://github.com/pingcap/tidb/issues/14994) ## Features that are different from MySQL @@ -76,7 +76,7 @@ mysql> select _tidb_rowid, id from t; ### Performance schema -TiDB uses a combination of [Prometheus and Grafana](/tidb-monitoring-api.md) to store and query the performance monitoring metrics. Some performance schema tables return empty results in TiDB. +TiDB uses a combination of [Prometheus and Grafana](/tidb-monitoring-api.md) to store and query the performance monitoring metrics. Performance schema tables return empty results in TiDB. ### Query Execution Plan @@ -84,43 +84,23 @@ The output format, output content, and the privilege setting of Query Execution ### Built-in functions -TiDB supports most of the MySQL built-in functions, but not all. See [TiDB SQL Grammar](https://pingcap.github.io/sqlgram/#functioncallkeyword) for the supported functions. +TiDB supports most of the MySQL built-in functions, but not all. The statement `SHOW BUILTINS` provides a list of functions that are available. + +See also: [TiDB SQL Grammar](https://pingcap.github.io/sqlgram/#functioncallkeyword). ### DDL -+ Add Index: - - Does not support creating multiple indexes using a single SQL statement. - - Supports creating index of different types (HASH/BTREE/RTREE) only in syntax, not implemented yet. - - Supports the `VISIBLE`/`INVISIBLE` index and ignores other options. -+ Add Column: - - Does not support setting the `PRIMARY KEY` and `UNIQUE KEY`. Does not support setting the `AUTO_INCREMENT` attribute. Otherwise, the `unsupported add column '%s' constraint PRIMARY/UNIQUE/AUTO_INCREMENT KEY` error might be output. -+ Drop Column - - Does not support dropping the `PRIMARY KEY` column or index column. Otherwise, the `Unsupported drop integer primary key/column a with index covered` error might be output. -+ Drop Primary Key - - Only supports dropping the primary key of the tables with `alter-primary-key` enabled when the tables are created. Otherwise, the `Unsupported drop primary key when alter-primary-key is false` error might be output. -+ Order By - - Ignores all options related to column ordering. -+ Change/Modify Column: - - Does not support lossy changes, such as from `BIGINT` to `INTEGER` or from `VARCHAR(255)` to `VARCHAR(10)`. Otherwise, the `length %d is less than origin %d` error might be output. - - Does not support modifying the precision of `DECIMAL` data types. Otherwise, the `can't change decimal column precision` error might be output. - - Does not support changing the `UNSIGNED` attribute. Otherwise, the `can't change unsigned integer to signed or vice versa` error might be output. - - Only supports changing the `CHARACTER SET` attribute from `utf8` to `utf8mb4`. -+ `LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}` - - The syntax is supported, but not implemented in TiDB yet. All DDL changes that are supported do not lock the table. -+ `ALGORITHM [=] {DEFAULT|INSTANT|INPLACE|COPY}` - - TiDB supports the `ALGORITHM=INSTANT` and `ALGORITHM=INPLACE` syntax, but they work differently from MySQL because some operations that are `INPLACE` in MySQL are `INSTANT` in TiDB. - - The syntax of `ALGORITHM=COPY` is supported, but not implemented in TiDB yet. It returns a warning. -+ Multiple operations cannot be completed in a single `ALTER TABLE` statement. For example, it is not possible to add multiple columns or indexes in a single statement. Otherwise, the `Unsupported multi schema change` error might be output. - -+ The `AUTO_INCREMENT`, `CHARACTER SET`, `COLLATE`, and `COMMENT` Table Options are supported in syntax. The following Table Options are not supported in syntax: - - `WITH/WITHOUT VALIDATION` - - `SECONDARY_LOAD/SECONDARY_UNLOAD` - - `CHECK/DROP CHECK` - - `STATS_AUTO_RECALC/STATS_SAMPLE_PAGES` - - `SECONDARY_ENGINE` - - `ENCRYPTION` - -+ The Table Partition supports Hash, Range, and `Add`/`Drop`/`Truncate`/`Coalesce`. The other partition operations are ignored. The `Warning: Unsupported partition type, treat as normal table` error might be output. The following Table Partition syntaxes are not supported: +In TIDB, all supported DDL changes are performed online. The MySQL DDL assertions `ALGORITHM=INSTANT` and `ALGORITHM=INPLACE` can also be used to assert which algorithm will be used to modify the table (which may differ from MySQL). + +The following major restrictions apply to DDL versus MySQL: + +* Multiple operations cannot be completed in a single `ALTER TABLE` statement. For example, it is not possible to add multiple columns or indexes in a single statement. Otherwise, the `Unsupported multi schema change` error might be output. +* Support for different types of indexes (HASH/BTREE/RTREE/FULLTEXT) is not supported, and will be parsed and ignored when specified. +* Adding/Dropping the primary key is unsupported unless `alter-primary-key` is enabled. +* Change/Modify data type does not currently support "lossy changes", such as changing from BIGINT to INT. +* Change/Modify decimal columns does not support changing the prevision. +* Change/Modify integer columns does not permit changing the `UNSIGNED` attribute. +* Table Partitioning supports Hash, Range, and `Add`/`Drop`/`Truncate`/`Coalesce`. The other partition operations are ignored. The `Warning: Unsupported partition type, treat as normal table` error might be output. The following Table Partition syntaxes are not supported: - `PARTITION BY LIST` - `PARTITION BY KEY` - `SUBPARTITION` @@ -128,11 +108,13 @@ TiDB supports most of the MySQL built-in functions, but not all. See [TiDB SQL G ### Analyze table -[`ANALYZE TABLE`](/statistics.md#manual-collection) works differently in TiDB than in MySQL, in that it is a relatively lightweight and short-lived operation in MySQL/InnoDB, while in TiDB it completely rebuilds the statistics for a table and can take much longer to complete. +[Statistics Collection](/statistics.md#manual-collection) works differently in TiDB than in MySQL, in that it is a relatively lightweight and short-lived operation in MySQL/InnoDB, while in TiDB it completely rebuilds the statistics for a table and can take much longer to complete. + +These differences are documented futher in [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md). ### Views -For the views feature, TiDB does not support write operations like `UPDATE`, `INSERT`, and `DELETE`. +Views in TiDB do not support write operations such as `UPDATE`, `INSERT`, and `DELETE`. ### Storage engines diff --git a/sql-statements/sql-statement-analyze-table.md b/sql-statements/sql-statement-analyze-table.md index dcaf7bd699ee3..43c72be362b16 100644 --- a/sql-statements/sql-statement-analyze-table.md +++ b/sql-statements/sql-statement-analyze-table.md @@ -64,11 +64,14 @@ mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; ## MySQL compatibility -This statement is syntactically similar with MySQL. However, `ANALYZE TABLE` may take significantly longer to execute on TiDB, as internally it operates in a different manner. +TiDB differs from MySQL in **both** the statistics it collects and how it makes use of statistics during query execution. While this statement is syntactically similar to MySQL, the following differences apply: + +1. TiDB may not include very recently committed changes when running `ANALYZE TABLE`. After a batch-update of rows, you may need to `sleep(1)` before executing `ANALYZE TABLE` in order for the statistics update to reflect these changes. [#16570](https://github.com/pingcap/tidb/issues/16570). +2. `ANALYZE TABLE` takes significantly longer to execute in TiDB than MySQL. This performance difference can be partially mitigated by enabling fast analyze with `SET GLOBAL tidb_enable_fast_analyze=1`. Fast analyze makes use of sampling, leading to less accurate statistics. Its usage is still considered experimental. MySQL does not support the `ANALYZE INCREMENTAL TABLE` statement. TiDB supports incremental collection of statistics. For detailed usage, refer to [incremental collection](/statistics.md#incremental-collection). ## See also * [EXPLAIN](/sql-statements/sql-statement-explain.md) -* [EXPLAIN ANALYZE](/sql-statements/sql-statement-explain-analyze.md) +* [EXPLAIN ANALYZE](/sql-statements/sql-statement-explain-analyze.md) \ No newline at end of file From d4d58b2918955efcf3cc1062d345012d3c8f3411 Mon Sep 17 00:00:00 2001 From: Nullnotnil Date: Fri, 3 Jul 2020 08:35:27 -0600 Subject: [PATCH 2/5] Updated formatting --- mysql-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mysql-compatibility.md b/mysql-compatibility.md index e34c4793e8655..aa58656159f25 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -95,7 +95,7 @@ In TIDB, all supported DDL changes are performed online. The MySQL DDL assertion The following major restrictions apply to DDL versus MySQL: * Multiple operations cannot be completed in a single `ALTER TABLE` statement. For example, it is not possible to add multiple columns or indexes in a single statement. Otherwise, the `Unsupported multi schema change` error might be output. -* Support for different types of indexes (HASH/BTREE/RTREE/FULLTEXT) is not supported, and will be parsed and ignored when specified. +* Support for different types of indexes (`HASH|BTREE|RTREE|FULLTEXT`) is not supported, and will be parsed and ignored when specified. * Adding/Dropping the primary key is unsupported unless `alter-primary-key` is enabled. * Change/Modify data type does not currently support "lossy changes", such as changing from BIGINT to INT. * Change/Modify decimal columns does not support changing the prevision. From 8f87e30d6486a0f13e0308fe8b3a9e83b82b4420 Mon Sep 17 00:00:00 2001 From: Kolbe Kegel Date: Fri, 3 Jul 2020 09:28:07 -0700 Subject: [PATCH 3/5] Update mysql-compatibility.md --- mysql-compatibility.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/mysql-compatibility.md b/mysql-compatibility.md index aa58656159f25..0affdb3c12da7 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -95,8 +95,8 @@ In TIDB, all supported DDL changes are performed online. The MySQL DDL assertion The following major restrictions apply to DDL versus MySQL: * Multiple operations cannot be completed in a single `ALTER TABLE` statement. For example, it is not possible to add multiple columns or indexes in a single statement. Otherwise, the `Unsupported multi schema change` error might be output. -* Support for different types of indexes (`HASH|BTREE|RTREE|FULLTEXT`) is not supported, and will be parsed and ignored when specified. -* Adding/Dropping the primary key is unsupported unless `alter-primary-key` is enabled. +* Different types of indexes (`HASH|BTREE|RTREE|FULLTEXT`) are not supported, and will be parsed and ignored when specified. +* Adding/Dropping the primary key is unsupported unless [`alter-primary-key`](/tidb-configuration-file.md#alter-primary-key) is enabled. * Change/Modify data type does not currently support "lossy changes", such as changing from BIGINT to INT. * Change/Modify decimal columns does not support changing the prevision. * Change/Modify integer columns does not permit changing the `UNSIGNED` attribute. @@ -114,7 +114,7 @@ These differences are documented futher in [`ANALYZE TABLE`](/sql-statements/sql ### Views -Views in TiDB do not support write operations such as `UPDATE`, `INSERT`, and `DELETE`. +Views in TiDB are not updatable. They do not support write operations such as `UPDATE`, `INSERT`, and `DELETE`. ### Storage engines @@ -124,9 +124,9 @@ TiDB supports storage engine abstraction similar to MySQL, but you need to speci ### SQL modes -- Does not support the compatibility mode, such as `ORACLE` and `POSTGRESQL`. The compatibility mode is deprecated in MySQL 5.7 and removed in MySQL 8.0. +- Does not support the compatibility modes, such as `ORACLE` and `POSTGRESQL`. Compatibility modes are deprecated in MySQL 5.7 and removed in MySQL 8.0. - The `ONLY_FULL_GROUP_BY` mode has minor [semantic differences](/functions-and-operators/aggregate-group-by-functions.md#differences-from-mysql) from MySQL 5.7. -- The `NO_DIR_IN_CREATE` and `NO_ENGINE_SUBSTITUTION` SQL modes in MySQL are supported for compatibility, but are not applicable to TiDB. +- The `NO_DIR_IN_CREATE` and `NO_ENGINE_SUBSTITUTION` SQL modes in MySQL are accepted for compatibility, but are not applicable to TiDB. ### Default differences From 9181d9fb273b681764678038f4e731874798b5fb Mon Sep 17 00:00:00 2001 From: Null not nil <67764674+nullnotnil@users.noreply.github.com> Date: Sun, 5 Jul 2020 22:15:17 -0600 Subject: [PATCH 4/5] Update mysql-compatibility.md --- mysql-compatibility.md | 1 - 1 file changed, 1 deletion(-) diff --git a/mysql-compatibility.md b/mysql-compatibility.md index 0affdb3c12da7..89f4e6f4c7ec3 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -36,7 +36,6 @@ However, some features of MySQL are not supported. This could be because there i + `CREATE TEMPORARY TABLE` syntax + `CHECK TABLE` syntax + `CHECKSUM TABLE` syntax -+ `SELECT INTO OUTFILE/DUMPFILE` syntax [#4350](https://github.com/pingcap/tidb/issues/4350) + `GET_LOCK` and `RELEASE_LOCK` functions [#14994](https://github.com/pingcap/tidb/issues/14994) ## Features that are different from MySQL From 637318f6ea676c4d01421917e0cee80fff31dd8d Mon Sep 17 00:00:00 2001 From: Lilian Lee Date: Mon, 6 Jul 2020 19:56:19 +0800 Subject: [PATCH 5/5] Update wording and format --- mysql-compatibility.md | 4 ++-- sql-statements/sql-statement-analyze-table.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/mysql-compatibility.md b/mysql-compatibility.md index c3469d34c4087..7134d716b2656 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -9,7 +9,7 @@ aliases: ['/docs/dev/mysql-compatibility/','/docs/dev/reference/mysql-compatibil TiDB is fully compatible with the MySQL 5.7 protocol and the common features and syntax of MySQL 5.7. The ecosystem tools for MySQL 5.7 (PHPMyAdmin, Navicat, MySQL Workbench, mysqldump, and Mydumper/myloader) and the MySQL client can be used for TiDB. -However, some features of MySQL are not supported. This could be because there is now a better way to solve the problem (such as XML functions superceded by JSON), security issues (such as SELECT INTO OUTFILE), or a lack of current demand versus effort required (such as stored procedures and functions). Some features may also be difficult to implement as a distributed system. +However, some features of MySQL are not supported. This could be because there is now a better way to solve the problem (such as XML functions superceded by JSON), security issues (such as `SELECT INTO OUTFILE`), or a lack of current demand versus effort required (such as stored procedures and functions). Some features might also be difficult to implement as a distributed system. > **Note:** > @@ -89,7 +89,7 @@ See also: [TiDB SQL Grammar](https://pingcap.github.io/sqlgram/#functioncallkeyw ### DDL -In TIDB, all supported DDL changes are performed online. The MySQL DDL assertions `ALGORITHM=INSTANT` and `ALGORITHM=INPLACE` can also be used to assert which algorithm will be used to modify the table (which may differ from MySQL). +In TiDB, all supported DDL changes are performed online. The MySQL DDL assertions `ALGORITHM=INSTANT` and `ALGORITHM=INPLACE` can also be used to assert which algorithm will be used to modify the table (which might differ from MySQL). The following major restrictions apply to DDL versus MySQL: diff --git a/sql-statements/sql-statement-analyze-table.md b/sql-statements/sql-statement-analyze-table.md index 43c72be362b16..1766af28b6f94 100644 --- a/sql-statements/sql-statement-analyze-table.md +++ b/sql-statements/sql-statement-analyze-table.md @@ -66,7 +66,7 @@ mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3; TiDB differs from MySQL in **both** the statistics it collects and how it makes use of statistics during query execution. While this statement is syntactically similar to MySQL, the following differences apply: -1. TiDB may not include very recently committed changes when running `ANALYZE TABLE`. After a batch-update of rows, you may need to `sleep(1)` before executing `ANALYZE TABLE` in order for the statistics update to reflect these changes. [#16570](https://github.com/pingcap/tidb/issues/16570). +1. TiDB might not include very recently committed changes when running `ANALYZE TABLE`. After a batch-update of rows, you might need to `sleep(1)` before executing `ANALYZE TABLE` in order for the statistics update to reflect these changes. [#16570](https://github.com/pingcap/tidb/issues/16570). 2. `ANALYZE TABLE` takes significantly longer to execute in TiDB than MySQL. This performance difference can be partially mitigated by enabling fast analyze with `SET GLOBAL tidb_enable_fast_analyze=1`. Fast analyze makes use of sampling, leading to less accurate statistics. Its usage is still considered experimental. MySQL does not support the `ANALYZE INCREMENTAL TABLE` statement. TiDB supports incremental collection of statistics. For detailed usage, refer to [incremental collection](/statistics.md#incremental-collection). @@ -74,4 +74,4 @@ MySQL does not support the `ANALYZE INCREMENTAL TABLE` statement. TiDB supports ## See also * [EXPLAIN](/sql-statements/sql-statement-explain.md) -* [EXPLAIN ANALYZE](/sql-statements/sql-statement-explain-analyze.md) \ No newline at end of file +* [EXPLAIN ANALYZE](/sql-statements/sql-statement-explain-analyze.md)