From ebdc832b88537ba8e6d47a83b09cc0ac5f7b497a Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 11 Jun 2020 13:44:19 +0800 Subject: [PATCH 1/5] Update mysql-compatibility.md --- mysql-compatibility.md | 184 +++++++++++++---------------------------- 1 file changed, 57 insertions(+), 127 deletions(-) diff --git a/mysql-compatibility.md b/mysql-compatibility.md index d6efe6f5b1a76..51942a3d7f165 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -1,17 +1,15 @@ --- title: Compatibility with MySQL -summary: Learn about the compatibility of TiDB with MySQL, and the unsupported and different features. +summary: Compares TiDB and MySQL in syntax and features. category: reference aliases: ['/docs/dev/reference/mysql-compatibility/'] --- # Compatibility with MySQL -TiDB supports both the MySQL wire protocol and the majority of its syntax. This means that you can use your existing MySQL connectors and clients, and your existing applications can often be migrated to TiDB without changing any application code. +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. -Currently TiDB Server advertises itself as MySQL 5.7 and works with most MySQL database tools such as PHPMyAdmin, Navicat, MySQL Workbench, mysqldump, and mydumper/myloader. - -However, TiDB does not support some of MySQL features or behaves differently from MySQL because these features cannot be easily implemented in a distributed system. For some MySQL syntax, TiDB can parse but does not process it. For example, the `ENGINE` table option in the `CREATE TABLE` statement can be parsed but is ignored. +TiDB is a distributed database. However, some features have not yet been implemented in TiDB or are only syntactically supported because these features are difficult for engineering or expected to have low output compared with the input. > **Note:** > @@ -45,32 +43,17 @@ However, TiDB does not support some of MySQL features or behaves differently fro ### Auto-increment ID -In TiDB, auto-increment columns are only guaranteed to be incremental and unique but are *not* guaranteed to be allocated sequentially. Currently, TiDB allocates IDs in batches. If data is inserted into multiple TiDB servers simultaneously, the allocated IDs will not be sequential. - -> **Note:** -> -> If you use auto-increment IDs in a cluster with multiple tidb-server instances, do not mix default values and custom values. Otherwise, an error might occur in the following situation. - -Assume that you have a table with the auto-increment ID: - -```sql -CREATE TABLE t(id int unique key AUTO_INCREMENT, c int); -``` - -The principle of the auto-increment ID in TiDB is that each tidb-server instance caches a section of ID values (currently 30000 IDs are cached) for allocation and fetches the next section after this section is used up. - -Assume that the cluster contains two tidb-server instances, namely Instance A and Instance B. Instance A caches the auto-increment ID of [1, 30000], while Instance B caches the auto-increment ID of [30001, 60000]. ++ In TiDB, auto-increment columns are only guaranteed to be incremental and unique but are *not* guaranteed to be allocated sequentially. It is recommended that you do not mix default values and custom values. Otherwise, you might receive the `Duplicated Error` error message. -The operations are executed as follows: ++ The implementation principle of the auto-increment ID in TiDB is that each tidb-server instance caches a section of ID values (currently 30,000 IDs are cached) for allocation. The number of cached IDs is determined by `AUTO_ID_CACHE`. Note that both the auto-increment columns and `_tidb_rowid` consume the cached IDs. If the `INSERT` statement requires that the number of consecutive IDs is greater than the `AUTO_ID_CACHE` value, the system automatically adjusts this value so that this statement can be executed. -1. The client issues the `INSERT INTO t VALUES (1, 1)` statement to Instance B which sets the `id` to 1 and the statement is executed successfully. -2. The client issues the `INSERT INTO t (c) (1)` statement to Instance A. This statement does not specify the value of `id`, so Instance A allocates the value. Currently, Instances A caches the auto-increment ID of [1, 30000], so it allocates the `id` value to 1 and adds 1 to the local counter. However, at this time the data with the `id` of 1 already exists in the cluster, therefore it reports `Duplicated Error`. - -Also, starting from TiDB 2.1.18 and 3.0.4, TiDB supports using the system variable `tidb_allow_remove_auto_inc` to control whether the `AUTO_INCREMENT` property of a column is allowed to be removed by executing `ALTER TABLE MODIFY` or `ALTER TABLE CHANGE` statements. It is not allowed by default. ++ You can use the `tidb_allow_remove_auto_inc` system variable to enable or disable the `AUTO_INCREMENT` column attribute. The syntax of removing the column attribute is `alter table modify` or `alter table change`. > **Note:** > -> If the primary key is not specified, TiDB uses the `_tibd_rowid` column to identify rows. The values of the `_tibd_rowid` column and the auto-increment column (if there is) are assigned by the same allocator. If the auto-increment column is specified as the primary key, then TiDB uses this column to identify rows. Therefore, there might be the following situations. +> + To use the `tidb_allow_remove_auto_inc` system variable, your TiDB version must be >= v2.1.18 or >= v3.0.4. +> + The `AUTO_ID_CACHE` table attribute requires that your TiDB version >= v3.0.14 or >= v3.1.2 or >= v4.0.rc-2. +> + If you have not specify the primary key when creating a table, TiDB uses `_tidb_rowid` to identify the row. The allocation of this value shares an allocator with the auto-increment column (if such column exists). If you specify an auto-increment column as the primary key, TiDB uses this column to identify the row. In this situation, the following example might happen: ```sql mysql> create table t(id int unique key AUTO_INCREMENT); @@ -93,13 +76,11 @@ mysql> select _tidb_rowid, id from t; ### Performance schema -Performance schema tables return empty results in TiDB. TiDB uses a combination of [Prometheus and Grafana](/monitor-a-tidb-cluster.md) for performance metrics instead. - -TiDB supports the `events_statements_summary_by_digest` table from TiDB 3.0.4. For more information, see [Statement Summary Table](/statement-summary-tables.md). +TiDB uses a combination of Prometheus and Grafana to store and query the performance monitoring metrics, so the Performance schema is an empty schema. ### Query Execution Plan -The output format of Query Execution Plan (`EXPLAIN`/`EXPLAIN FOR`) in TiDB is greatly different from that in MySQL. Besides, the output content and the privileges setting of `EXPLAIN FOR` are not the same as those of MySQL. See [Understand the Query Execution Plan](/query-execution-plan.md) for more details. +The output format of Query Execution Plan (`EXPLAIN`/`EXPLAIN FOR`) in TiDB is greatly different from that in MySQL. In addition, the output content and the privileges setting of `EXPLAIN FOR` are also different from those of MySQL. See [Understand the Query Execution Plan](/query-execution-plan.md) for more details. ### Built-in functions @@ -107,25 +88,31 @@ TiDB supports most of the MySQL built-in functions, but not all. See [TiDB SQL G ### DDL -In TiDB DDL does not block reads or writes to tables while in operation. However, some restrictions currently apply to DDL changes: - + Add Index: - - Does not support creating multiple indexes at the same time. - - Does not support the `VISIBLE/INVISIBLE` index. - - Other Index Type (HASH/BTREE/RTREE) is supported in syntax, but not applicable. + - Does not support creating multiple indexes using a single SQL statement. + - Supports creating index of different types (HASH/BTREE/RTREE) only in syntax, but not applicable. + - Supports the `VISIBLE`/`INVISIBLE` index and ignores other options. + Add Column: - - Does not support creating multiple columns at the same time. - - Does not support setting a column as the `PRIMARY KEY`, or creating a unique index, or specifying `AUTO_INCREMENT` while adding it. -+ Drop Column: Does not support dropping the `PRIMARY KEY` column or index 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 `VARCHAR(255)` to `VARCHAR(10)`. - - Does not support modifying the precision of `DECIMAL` data types. - - Does not support changing the `UNSIGNED` attribute. -+ `LOCK [=] {DEFAULT|NONE|SHARED|EXCLUSIVE}`: the syntax is supported, but is not applicable to TiDB. All DDL changes that are supported do not lock the table. -+ `ALGORITHM [=] {DEFAULT|INSTANT|INPLACE|COPY}`: the syntax for `ALGORITHM=INSTANT` and `ALGORITHM=INPLACE` is fully supported, but it works differently from MySQL because some operations that are `INPLACE` in MySQL are `INSTANT` in TiDB. The syntax `ALGORITHM=COPY` is not applicable to TIDB and returns a warning. -+ Multiple operations cannot be completed in a single `ALTER TABLE` statement. For example, it's not possible to add multiple columns or indexes in a single statement. - -+ The following Table Options are not supported in syntax: + - 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 is not applicable to TiDB. All DDL changes that are supported do not lock the table. ++ `ALGORITHM [=] {DEFAULT|INSTANT|INPLACE|COPY}` + - The syntax for `ALGORITHM=INSTANT` and `ALGORITHM=INPLACE` is fully supported, but it works differently from MySQL because some operations that are `INPLACE` in MySQL are `INSTANT` in TiDB. + - The syntax `ALGORITHM=COPY` is not applicable to TiDB and 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` @@ -133,98 +120,42 @@ In TiDB DDL does not block reads or writes to tables while in operation. However - `SECONDARY_ENGINE` - `ENCRYPTION` -+ The following Table Partition syntaxes are not supported: ++ 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: - `PARTITION BY LIST` - `PARTITION BY KEY` - `SUBPARTITION` - `{CHECK|EXCHANGE|TRUNCATE|OPTIMIZE|REPAIR|IMPORT|DISCARD|REBUILD|REORGANIZE} PARTITION` -For more information, see [Online Schema Changes](/key-features.md#online-schema-changes). - ### 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. ### Views -Views in TiDB are currently non-insertable and non-updatable. +Views in TiDB are currently non-insertable, non-updatable, and non-deletable. ### Storage engines -For compatibility reasons, TiDB supports the syntax to create tables with alternative storage engines. Metadata commands describe tables as being of engine InnoDB: - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (a INT) ENGINE=MyISAM; -``` - -``` -Query OK, 0 rows affected (0.14 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` +For compatibility reasons, TiDB supports the syntax to create tables with alternative storage engines. In actual implementation, TiDB describes the metadata as InnoDB storage engines. -``` -*************************** 1. row *************************** - Table: t1 -Create Table: CREATE TABLE `t1` ( - `a` int(11) DEFAULT NULL -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin -1 row in set (0.00 sec) -``` - -Architecturally, TiDB does support a similar storage engine abstraction to MySQL, and user tables are created in the engine specified by the [`--store`](/command-line-flags-for-tidb-configuration.md#--store) option used when you start tidb-server (typically `tikv`). +Architecturally, TiDB supports a similar storage engine abstraction to MySQL, and user tables are created in the engine specified by the [`--store`](/command-line-flags-for-tidb-configuration.md#--store) option used when you start TiDB server. ### SQL modes -TiDB supports **all of the SQL modes** from MySQL 5.7 with minor exceptions: - -- The compatibility modes deprecated in MySQL 5.7 and removed in MySQL 8.0 are not supported (such as `ORACLE`, `POSTGRESQL` etc). -- The mode `ONLY_FULL_GROUP_BY` has minor [semantic differences](/functions-and-operators/aggregate-group-by-functions.md#differences-from-mysql) to MySQL 5.7, which we plan to address in the future. -- The SQL modes `NO_DIR_IN_CREATE` and `NO_ENGINE_SUBSTITUTION` are supported for compatibility, but are not applicable to TiDB. - -### Version-specific comments - -TiDB executes all MySQL version-specific comments, regardless of the version they apply to. For example, the comment `/*!90000 */` would instruct a MySQL server less than 9.0 to not execute code. In TiDB this code will always be executed: - -```sql -mysql 8.0.16> SELECT /*!90000 "I should not run", */ "I should run" FROM dual; -+--------------+ -| I should run | -+--------------+ -| I should run | -+--------------+ -1 row in set (0.00 sec) - -tidb> SELECT /*!90000 "I should not run", */ "I should run" FROM dual; -+------------------+--------------+ -| I should not run | I should run | -+------------------+--------------+ -| I should not run | I should run | -+------------------+--------------+ -1 row in set (0.00 sec) -``` - -### Lock tables - -Support for `LOCK TABLE` syntax is currently experimental, and must be explicitly enabled ([TiDB #10343](https://github.com/pingcap/tidb/pull/10343)). - -It is recommended to use the historical reads feature of `tidb_snapshot` to produce consistent reads, instead of `FLUSH TABLES WITH READ LOCK`. Support for `tidb_snapshot` is available in [Mydumper](/mydumper-overview.md)). +- The compatibility modes deprecated in MySQL 5.7 and removed in MySQL 8.0 are not supported (such as `ORACLE` and `POSTGRESQL`). +- The `ONLY_FULL_GROUP_BY` mode has minor [semantic differences](/functions-and-operators/aggregate-group-by-functions.md#differences-from-mysql) to 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. ### Default differences - Default character set: - The default value in TiDB is `utf8mb4`. - - The default value in MySQL 5.7 is `latin1`, but changes to `utf8mb4` in MySQL 8.0. + - The default value in MySQL 5.7 is `latin1`. + - The default value in MySQL 8.0 is `utf8mb4`. - Default collation: - The default collation of `utf8mb4` in TiDB is `utf8mb4_bin`. - - The default collation of `utf8mb4` in MySQL 5.7 is `utf8mb4_general_ci`, but changes to `utf8mb4_0900_ai_ci` in MySQL 8.0. - - You can use the [`SHOW CHARACTER SET`](/sql-statements/sql-statement-show-character-set.md) statement to check the default collations of all character sets. + - The default collation of `utf8mb4` in MySQL 5.7 is `utf8mb4_general_ci`. + - The default collation of `utf8mb4` in MySQL 8.0 is `utf8mb4_0900_ai_ci`. - Default value of `foreign_key_checks`: - The default value in TiDB is `OFF` and currently TiDB only supports `OFF`. - The default value in MySQL 5.7 is `ON`. @@ -232,32 +163,31 @@ It is recommended to use the historical reads feature of `tidb_snapshot` to prod - The default SQL mode in TiDB includes these modes: `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION`. - The default SQL mode in MySQL: - The default SQL mode in MySQL 5.7 is the same as TiDB. - - The default SQL mode in MySQL 8.0 includes these modes: `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION`. + - The default SQL mode in MySQL 8.0 includes these modes: ``ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION`. - Default value of `lower_case_table_names`: - - The default value in TiDB is 2 and currently TiDB only supports 2. + - The default value in TiDB is `2` and currently TiDB only supports `2`. - The default value in MySQL: - - On Linux: 0 - - On Windows: 1 - - On macOS: 2 + - On Linux: `0` + - On Windows: `1` + - On macOS: `2` - Default value of `explicit_defaults_for_timestamp`: - The default value in TiDB is `ON` and currently TiDB only supports `ON`. - The default value in MySQL: - - For MySQL 5.7: `OFF` - - For MySQL 8.0: `ON` + - For MySQL 5.7: `OFF`. + - For MySQL 8.0: `ON`. ### Date and Time #### Named timezone -TiDB supports named timezones such as `America/Los_Angeles` without having to load the [time zone information tables](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html#time-zone-installation) as in MySQL. - -Because they are built-in, named time zones in TiDB might behave slightly differently to MySQL, and cannot be modified. For example, in TiDB the names are case-sensitive [#8087](https://github.com/pingcap/tidb/issues/8087). ++ TiDB uses all timezone rules currently installed in the system for calculation (usually the tzdata package). You can use all timezone names without importing the timezone table data. You cannot modify the calculation rules by importing the timezone table data. ++ MySQL uses the local timezone by default and relies on the current timezone rules built into the system (such as when to start daylight saving time) for calculation; and the timezone cannot be specified by the timezone name without [importing the timezone table data](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html#time-zone-installation). > **Note:** > -> TiKV calculates time-related expressions that can be pushed down to it. This calculation uses the built-in time zone rule and does not depend on the time zone rule installed in the system. If the time zone rule installed in the system does not match the version of the built-in time zone rule in TiKV, the time data that can be inserted might result in a statement error in a few cases. +> TiKV calculates time-related expressions that can be pushed down to it. This calculation uses the built-in timezone rule and does not depend on the timezone rule installed in the system. If the timezone rule installed in the system does not match the version of the built-in timezone rule in TiKV, the time data that can be inserted might result in a statement error in a few cases. > -> For example, if the tzdata 2018a time zone rule is installed in the system, the time `1988-04-17 02:00:00` can be inserted into TiDB of the 3.0.0-rc.1 version when the time zone is set to Asia/Shanghai or the time zone is set to the local time zone and the local time zone is Asia/Shanghai. But reading this record might result in a statement error because this time does not exist in the Asia/Shanghai time zone according to the tzdata 2018i time zone rule used by TiKV 3.0.0-rc.1. Daylight saving time is one hour late. +> For example, if the tzdata 2018a timezone rule is installed in the system, the time `1988-04-17 02:00:00` can be inserted into TiDB of the 3.0 RC.1 version when the timezone is set to Asia/Shanghai or the timezone is set to the local timezone and the local timezone is Asia/Shanghai. But reading this record might result in a statement error because this time does not exist in the Asia/Shanghai timezone according to the tzdata 2018i timezone rule used by TiKV 3.0 RC.1. Daylight saving time is one hour late. > > The named timezone rules in TiKV of two versions are as follows: > @@ -266,11 +196,11 @@ Because they are built-in, named time zones in TiDB might behave slightly differ #### Zero month and zero day -It is not recommended to unset the `NO_ZERO_DATE` and `NO_ZERO_IN_DATE` SQL modes, which are enabled by default in TiDB as in MySQL. While TiDB supports operating with these modes disabled, the TiKV coprocessor does not. Executing certain statements that push down date and time processing functions to TiKV might result in a statement error. +It is not recommended to unset the `NO_ZERO_DATE` and `NO_ZERO_IN_DATE` SQL modes, which are enabled by default in TiDB as in MySQL. Although TiDB supports operating with these modes disabled, the TiKV coprocessor might be affected. Executing certain statements that push down date and time processing functions to TiKV might result in a statement error. ### Type system differences -The following column types are supported by MySQL, but not by TiDB: +The following column types are supported by MySQL, but **NOT** by TiDB: + FLOAT4/FLOAT8 + FIXED (alias for DECIMAL) From 9f3e2bf3c493f3cf2dfee74b4761d75a6bf1f7b9 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Thu, 11 Jun 2020 17:47:11 +0800 Subject: [PATCH 2/5] Update mysql-compatibility.md Co-authored-by: tangenta --- mysql-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mysql-compatibility.md b/mysql-compatibility.md index 51942a3d7f165..5148d8bf386d6 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -76,7 +76,7 @@ mysql> select _tidb_rowid, id from t; ### Performance schema -TiDB uses a combination of Prometheus and Grafana to store and query the performance monitoring metrics, so the Performance schema is an empty schema. +TiDB uses a combination of Prometheus and Grafana to store and query the performance monitoring metrics. The Performance schema is an empty schema. ### Query Execution Plan From 2ce344990764a4f6d810abfb534c7f4518674a7d Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Fri, 12 Jun 2020 18:40:05 +0800 Subject: [PATCH 3/5] address comments from lilian Co-authored-by: Lilian Lee --- mysql-compatibility.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/mysql-compatibility.md b/mysql-compatibility.md index 5148d8bf386d6..4a0d2919133d1 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -1,6 +1,6 @@ --- title: Compatibility with MySQL -summary: Compares TiDB and MySQL in syntax and features. +summary: Learn about the compatibility of TiDB with MySQL, and the unsupported and different features. category: reference aliases: ['/docs/dev/reference/mysql-compatibility/'] --- @@ -9,7 +9,7 @@ aliases: ['/docs/dev/reference/mysql-compatibility/'] 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. -TiDB is a distributed database. However, some features have not yet been implemented in TiDB or are only syntactically supported because these features are difficult for engineering or expected to have low output compared with the input. +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). > **Note:** > @@ -43,7 +43,7 @@ TiDB is a distributed database. However, some features have not yet been impleme ### Auto-increment ID -+ In TiDB, auto-increment columns are only guaranteed to be incremental and unique but are *not* guaranteed to be allocated sequentially. It is recommended that you do not mix default values and custom values. Otherwise, you might receive the `Duplicated Error` error message. ++ In TiDB, auto-increment columns are only guaranteed to be incremental and unique but are *not* guaranteed to be allocated sequentially. It is recommended that you do not mix default values and custom values. Otherwise, you might encounter the `Duplicated Error` error message. + The implementation principle of the auto-increment ID in TiDB is that each tidb-server instance caches a section of ID values (currently 30,000 IDs are cached) for allocation. The number of cached IDs is determined by `AUTO_ID_CACHE`. Note that both the auto-increment columns and `_tidb_rowid` consume the cached IDs. If the `INSERT` statement requires that the number of consecutive IDs is greater than the `AUTO_ID_CACHE` value, the system automatically adjusts this value so that this statement can be executed. @@ -52,8 +52,8 @@ TiDB is a distributed database. However, some features have not yet been impleme > **Note:** > > + To use the `tidb_allow_remove_auto_inc` system variable, your TiDB version must be >= v2.1.18 or >= v3.0.4. -> + The `AUTO_ID_CACHE` table attribute requires that your TiDB version >= v3.0.14 or >= v3.1.2 or >= v4.0.rc-2. -> + If you have not specify the primary key when creating a table, TiDB uses `_tidb_rowid` to identify the row. The allocation of this value shares an allocator with the auto-increment column (if such column exists). If you specify an auto-increment column as the primary key, TiDB uses this column to identify the row. In this situation, the following example might happen: +> + The `AUTO_ID_CACHE` table attribute requires that your TiDB version >= v3.0.14 or >= v3.1.2 or >= v4.0.0-rc.2. +> + If you have not specified the primary key when creating a table, TiDB uses `_tidb_rowid` to identify the row. The allocation of this value shares an allocator with the auto-increment column (if such a column exists). If you specify an auto-increment column as the primary key, TiDB uses this column to identify the row. In this situation, the following situation might happen: ```sql mysql> create table t(id int unique key AUTO_INCREMENT); @@ -76,11 +76,11 @@ mysql> select _tidb_rowid, id from t; ### Performance schema -TiDB uses a combination of Prometheus and Grafana to store and query the performance monitoring metrics. The Performance schema is an empty schema. +TiDB uses a combination of Prometheus and Grafana to store and query the performance monitoring metrics. Some performance schema tables return empty results in TiDB. ### Query Execution Plan -The output format of Query Execution Plan (`EXPLAIN`/`EXPLAIN FOR`) in TiDB is greatly different from that in MySQL. In addition, the output content and the privileges setting of `EXPLAIN FOR` are also different from those of MySQL. See [Understand the Query Execution Plan](/query-execution-plan.md) for more details. +The output format, output content, and the privilege setting of Query Execution Plan (`EXPLAIN`/`EXPLAIN FOR`) in TiDB is greatly different from those in MySQL. See [Understand the Query Execution Plan](/query-execution-plan.md) for more details. ### Built-in functions @@ -90,7 +90,7 @@ TiDB supports most of the MySQL built-in functions, but not all. See [TiDB SQL G + 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, but not applicable. + - 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. @@ -106,10 +106,10 @@ TiDB supports most of the MySQL built-in functions, but not all. See [TiDB SQL G - 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 is not applicable to TiDB. All DDL changes that are supported do not lock the table. + - 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}` - - The syntax for `ALGORITHM=INSTANT` and `ALGORITHM=INPLACE` is fully supported, but it works differently from MySQL because some operations that are `INPLACE` in MySQL are `INSTANT` in TiDB. - - The syntax `ALGORITHM=COPY` is not applicable to TiDB and returns a warning. + - 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: @@ -120,7 +120,7 @@ TiDB supports most of the MySQL built-in functions, but not all. See [TiDB SQL G - `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: ++ 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: - `PARTITION BY LIST` - `PARTITION BY KEY` - `SUBPARTITION` @@ -132,18 +132,18 @@ TiDB supports most of the MySQL built-in functions, but not all. See [TiDB SQL G ### Views -Views in TiDB are currently non-insertable, non-updatable, and non-deletable. +For the views feature, TiDB does not support write operations like `UPDATE`, `INSERT`, and `DELETE`. ### Storage engines -For compatibility reasons, TiDB supports the syntax to create tables with alternative storage engines. In actual implementation, TiDB describes the metadata as InnoDB storage engines. +For compatibility reasons, TiDB supports the syntax to create tables with alternative storage engines. In implementation, TiDB describes the metadata as the InnoDB storage engine. -Architecturally, TiDB supports a similar storage engine abstraction to MySQL, and user tables are created in the engine specified by the [`--store`](/command-line-flags-for-tidb-configuration.md#--store) option used when you start TiDB server. +TiDB supports storage engine abstraction similar to MySQL, but you need to specify the storage engine using the [`--store`](/command-line-flags-for-tidb-configuration.md#--store) option when you start the TiDB server. ### SQL modes - The compatibility modes deprecated in MySQL 5.7 and removed in MySQL 8.0 are not supported (such as `ORACLE` and `POSTGRESQL`). -- The `ONLY_FULL_GROUP_BY` mode has minor [semantic differences](/functions-and-operators/aggregate-group-by-functions.md#differences-from-mysql) to MySQL 5.7. +- 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. ### Default differences @@ -163,7 +163,7 @@ Architecturally, TiDB supports a similar storage engine abstraction to MySQL, an - The default SQL mode in TiDB includes these modes: `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION`. - The default SQL mode in MySQL: - The default SQL mode in MySQL 5.7 is the same as TiDB. - - The default SQL mode in MySQL 8.0 includes these modes: ``ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION`. + - The default SQL mode in MySQL 8.0 includes these modes: `ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION`. - Default value of `lower_case_table_names`: - The default value in TiDB is `2` and currently TiDB only supports `2`. - The default value in MySQL: @@ -180,12 +180,12 @@ Architecturally, TiDB supports a similar storage engine abstraction to MySQL, an #### Named timezone -+ TiDB uses all timezone rules currently installed in the system for calculation (usually the tzdata package). You can use all timezone names without importing the timezone table data. You cannot modify the calculation rules by importing the timezone table data. ++ TiDB uses all time zone rules currently installed in the system for calculation (usually the `tzdata` package). You can use all time zone names without importing the time zone table data. You cannot modify the calculation rules by importing the time zone table data. + MySQL uses the local timezone by default and relies on the current timezone rules built into the system (such as when to start daylight saving time) for calculation; and the timezone cannot be specified by the timezone name without [importing the timezone table data](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html#time-zone-installation). > **Note:** > -> TiKV calculates time-related expressions that can be pushed down to it. This calculation uses the built-in timezone rule and does not depend on the timezone rule installed in the system. If the timezone rule installed in the system does not match the version of the built-in timezone rule in TiKV, the time data that can be inserted might result in a statement error in a few cases. +> TiKV calculates time-related expressions that can be pushed down to it. This calculation uses the built-in time zone rule and does not depend on the time zone rule installed in the system. If the time zone rule installed in the system does not match the version of the built-in time zone rule in TiKV, the time data that can be inserted might result in a statement error in a few cases. > > For example, if the tzdata 2018a timezone rule is installed in the system, the time `1988-04-17 02:00:00` can be inserted into TiDB of the 3.0 RC.1 version when the timezone is set to Asia/Shanghai or the timezone is set to the local timezone and the local timezone is Asia/Shanghai. But reading this record might result in a statement error because this time does not exist in the Asia/Shanghai timezone according to the tzdata 2018i timezone rule used by TiKV 3.0 RC.1. Daylight saving time is one hour late. > From deccdde3ce159643935b02fe8e2dd581ba426ec6 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Fri, 12 Jun 2020 18:42:18 +0800 Subject: [PATCH 4/5] Update mysql-compatibility.md --- mysql-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mysql-compatibility.md b/mysql-compatibility.md index 4a0d2919133d1..22f5d63fb8fd7 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -142,7 +142,7 @@ TiDB supports storage engine abstraction similar to MySQL, but you need to speci ### SQL modes -- The compatibility modes deprecated in MySQL 5.7 and removed in MySQL 8.0 are not supported (such as `ORACLE` and `POSTGRESQL`). +- 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. - 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. From 192deefa2e7fdd5e7bcc46eae5c58c4e94bd2a98 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Fri, 12 Jun 2020 18:43:01 +0800 Subject: [PATCH 5/5] address comment Co-authored-by: Lilian Lee --- mysql-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mysql-compatibility.md b/mysql-compatibility.md index 22f5d63fb8fd7..4f6bfa32b2933 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -181,7 +181,7 @@ TiDB supports storage engine abstraction similar to MySQL, but you need to speci #### Named timezone + TiDB uses all time zone rules currently installed in the system for calculation (usually the `tzdata` package). You can use all time zone names without importing the time zone table data. You cannot modify the calculation rules by importing the time zone table data. -+ MySQL uses the local timezone by default and relies on the current timezone rules built into the system (such as when to start daylight saving time) for calculation; and the timezone cannot be specified by the timezone name without [importing the timezone table data](https://dev.mysql.com/doc/refman/8.0/en/time-zone-support.html#time-zone-installation). ++ MySQL uses the local time zone by default and relies on the current time zone rules built into the system (such as when to start daylight saving time) for calculation; and the time zone cannot be specified by the time zone name without [importing the time zone table data](https://dev.mysql.com/doc/refman/5.7/en/time-zone-support.html#time-zone-installation). > **Note:** >