From dc53a32e3506f82a505297079c8e64eb26137821 Mon Sep 17 00:00:00 2001 From: Icemap Date: Mon, 19 Sep 2022 17:12:13 +0800 Subject: [PATCH 01/11] 3rd party tools compatibility --- TOC.md | 1 + ...v-guide-third-party-tools-compatibility.md | 139 ++++++++++++++++++ 2 files changed, 140 insertions(+) create mode 100644 develop/dev-guide-third-party-tools-compatibility.md diff --git a/TOC.md b/TOC.md index 4180675e4cc3f..27b736131137e 100644 --- a/TOC.md +++ b/TOC.md @@ -86,6 +86,7 @@ - [Gitpod](/develop/dev-guide-playground-gitpod.md) - Third-party Support - [Third-Party Tools Supported by TiDB](/develop/dev-guide-third-party-support.md) + - [Known Incompatibility Issues with Third-Party Tools](/develop/dev-guide-third-party-tools-compatibility.md) - [Integrate with ProxySQL](/develop/dev-guide-proxysql-integration.md) - Deploy - [Software and Hardware Requirements](/hardware-and-software-requirements.md) diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md new file mode 100644 index 0000000000000..0f41dfec38925 --- /dev/null +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -0,0 +1,139 @@ +--- +title: Known Incompatibility Issues with Third-Party Tools +summary: List the third-party tools incompatibility issues encountered while testing by PingCAP +--- + +# Known Incompatibility Issues with Third-Party Tools + +> **Note:** +> +> TiDB has listed the [unsupported features](/mysql-compatibility.md#unsupported-features), typically unsupported features: +> +> - Stored procedures and functions +> - Triggers +> - Events +> - User-defined functions +> - `FOREIGN KEY` constraints +> - `SPATIAL` functions, data types and indexes +> - `XA` syntax +> +> Such incompatibilities issues are considered expected behavior and will not be repeated. See the [MySQL Compatibility](/mysql-compatibility.md) for more descriptions. + +## General + +### `SELECT CONNECTION_ID()` returns a 64-bit integer + +**Description** + +`SELECT CONNECTION_ID()` return value for TiDB is 64-bit, such as `2199023260887`, while for MySQL it is 32-bit, such as `391650`. + +**Ways to Avoid** + +Please use each language's 64-bit integer type (or string type) for the reception to prevent overflow. For example, Java should use `Long` or `String` for reception, and JS/TS should use `string` type for the reception. + +### TiDB does not set `Com_*` counters + +**Description** + +MySQL maintains a series of [server status variables starting with `Com_`](https://dev.mysql.com/doc/refman/8.0/en/server-status-variables.html#statvar_Com_xxx) to keep track of the total number of operations you have performed on the database. For example, `Com_select` keeps track of the total number of `SELECT` statements initiated by the MySQL database since it was last started (even if the statements were not queried successfully). TiDB does not maintain this variable. You can use the statement `SHOW GLOBAL STATUS LIKE 'Com_%'` to see the difference between the two databases. + +**Ways to Avoid** + +Please do not use these variables. Common usage scenarios such as monitoring. TiDB is well observable and does not require querying from server status variables. For custom monitoring tools, read the [TiDB Monitoring Framework Overview](/tidb-monitoring-framework.md) for more information. + +### TiDB error messages distinguish between `timestamp` and `datetime` + +**Description** + +TiDB error messages distinguish between `timestamp` and `datetime`, while MySQL does not, and returns them all as `datetime`. That is, MySQL incorrectly writes `timestamp` type error messages as `datetime` type. + +**Ways to Avoid** + +Do not use the error messages for string matching, but use [Error Codes](/error-codes.md) for troubleshooting. + +### The `CHECK TABLE` statement is not supported + +**Description** + +TiDB uses the [ADMIN CHECK [TABLE|INDEX]](/sql-statements/sql-statement-admin-check-table-index.md) statement to check the consistency of data and corresponding indexes in tables. The `CHECK TABLE` statement is not supported. + +**Ways to Avoid** + +Use `ADMIN CHECK [TABLE|INDEX]`. + +## MySQL Connector/J + +- Test Version: `8.0.29` + +### Default Collations are inconsistent + +**Description** + +The collations of MySQL Connector/J are stored in the client and are distinguished by the server version. + +已知的客户端与服务端排序规则不一致的字符集： + +Known character sets for which client-side and server-side collations do not match: + +| Character Sets | Client Default Collations | Server Default Collations | +| - | - | - | +| `ascii` | `ascii_general_ci` | `ascii_bin` | +| `latin1` | `latin1_swedish_ci` | `latin1_bin` | +| `utf8mb4` | `utf8mb4_0900_ai_ci` | `utf8mb4_bin` | + +**Ways to Avoid** + +Set the sorting rules manually and do not rely on the client default sorting rules (client default sorting rules are saved by the MySQL Connector/J configuration file). + +### Parameter `NO_BACKSLASH_ESCAPES` not effect + +**Description** + +The `NO_BACKSLASH_ESCAPES` parameter cannot be used so that `\` character is not escaped. Tracking the [issue](https://github.com/pingcap/tidb/issues/35302). + +**Ways to Avoid** + +Do not use `NO_BACKSLASH_ESCAPES` with `\`, but use normal `\\` for SQL writing. + +### Not Support INDEX_USED Parameters + +**Description** + +TiDB does not set the `SERVER_QUERY_NO_GOOD_INDEX_USED` and `SERVER_QUERY_NO_INDEX_USED` parameters in the protocol. This will cause the following parameters to be returned inconsistently with the actual: + +- `com.mysql.cj.protocol.ServerSession.noIndexUsed()` +- `com.mysql.cj.protocol.ServerSession.noGoodIndexUsed()` + +**Ways to Avoid** + +Do not use the `noIndexUsed()` and `noGoodIndexUsed()` functions. + +### Not Support `enablePacketDebug` Parameters + +**Description** + +TiDB does not support the [enablePacketDebug](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-connp-props-debugging-profiling.html) parameter, which is a MySQL Connector/J parameter used for debugging that will retain the packet's ring buffer. this will cause the connection to **_UNEXPECTED CLOSE_**, **_DO NOT_** turn it on. + +**Ways to Avoid** + +Do not set the `enablePacketDebug` parameter. + +### Not Support `UpdatableResultSet` + +**Description** + +TiDB does not support `UpdatableResultSet`, that means **_DO NOT_** specify the `ResultSet.CONCUR_UPDATABLE` parameter and updates data inside the ResultSet. + +**Ways to Avoid** + +Using additional `UPDATE` statements for data updates, you can use transactions to ensure data consistency. + +### Not Support `useLocalTransactionState` Parameters + +**Description** + +TiDB relies on `COMMIT()` and `ROLLBACK()` for committing or rolling back transactions. the [useLocalTransactionState](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-connp-props-performance-extensions.html) parameter may omit `COMMIT()` and `ROLLBACK()`, which are unnecessary in MySQL. But those statements are necessary for TiDB. + +**Ways to Avoid** + +Do not turn on the `useLocalTransactionState` parameter, as this may lead to transactions not being committed or rolled back. \ No newline at end of file From 1164d9ad1c99e16a0352f8df7d2aab88d85886cd Mon Sep 17 00:00:00 2001 From: Icemap Date: Thu, 29 Sep 2022 17:20:46 +0800 Subject: [PATCH 02/11] mention mysql-connector-j bugs --- ...v-guide-third-party-tools-compatibility.md | 29 +++++++++++++++---- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index 0f41dfec38925..020671163455b 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -71,8 +71,6 @@ Use `ADMIN CHECK [TABLE|INDEX]`. The collations of MySQL Connector/J are stored in the client and are distinguished by the server version. -已知的客户端与服务端排序规则不一致的字符集： - Known character sets for which client-side and server-side collations do not match: | Character Sets | Client Default Collations | Server Default Collations | @@ -128,12 +126,33 @@ TiDB does not support `UpdatableResultSet`, that means **_DO NOT_** specify the Using additional `UPDATE` statements for data updates, you can use transactions to ensure data consistency. -### Not Support `useLocalTransactionState` Parameters +## MySQL Connector/J Bug + +### `useLocalTransactionState` and `rewriteBatchedStatements` are true at the same time will cause the transaction to fail to commit + +**Description** + +`useLocalTransactionState` 和 `rewriteBatchedStatements` 两参数同时开启时，将导致事务无法提交的问题。你可以使用[代码](https://github.com/Icemap/tidb-java-gitpod/tree/reproduction-local-transaction-state-txn-error)复现。 + +**Ways to Avoid** + +> **Note:** +> +> This bug has been reported to MySQL, you can follow this [Bug Report](https://bugs.mysql.com/bug.php?id=108643) to keep track of the latest news. + +**_DO NOT_** turn on `useLocalTransactionState`, as this may prevent transactions from being committed or rolled back. + +### Connector Forward Compatibility Issue **Description** -TiDB relies on `COMMIT()` and `ROLLBACK()` for committing or rolling back transactions. the [useLocalTransactionState](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-connp-props-performance-extensions.html) parameter may omit `COMMIT()` and `ROLLBACK()`, which are unnecessary in MySQL. But those statements are necessary for TiDB. +Newer versions of MySQL Connector/J work with MySQL servers below version **5.7.5**, or databases using MySQL server protocols below version **5.7.5** (e.g. TiDB below version **6.3**). It will cause the database connection to hang under certain circumstances, see [Bug Report](https://bugs.mysql.com/bug.php?id=106252) for more details. **Ways to Avoid** -Do not turn on the `useLocalTransactionState` parameter, as this may lead to transactions not being committed or rolled back. \ No newline at end of file +This is a known issue, and MySQL Connector/J has not merged the fix code so far. + +PingCAP made two dimensional fixes to it: + +- Client side: You can replace the official MySQL Connector/J with [pingcap/mysql-connector-j](https://github.com/pingcap/mysql-connector-j). The bug is fixed in **pingcap/mysql-connector-j**. +- Server side: you can upgrade the server to version **6.3** or above; TiDB has fixed this compatibility issue in version **6.3**. \ No newline at end of file From 47f7dba96ba67297d68736a2da005ae48a81379e Mon Sep 17 00:00:00 2001 From: Icemap Date: Thu, 29 Sep 2022 18:02:00 +0800 Subject: [PATCH 03/11] discern MySQL JDBC and MySQL Connector/J --- develop/dev-guide-third-party-tools-compatibility.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index 020671163455b..58ed0191a1eb4 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -61,9 +61,9 @@ TiDB uses the [ADMIN CHECK [TABLE|INDEX]](/sql-statements/sql-statement-admin-ch Use `ADMIN CHECK [TABLE|INDEX]`. -## MySQL Connector/J +## MySQL JDBC Incompatibility -- Test Version: `8.0.29` +- Test Version: MySQL Connector/J `8.0.29` ### Default Collations are inconsistent @@ -126,13 +126,13 @@ TiDB does not support `UpdatableResultSet`, that means **_DO NOT_** specify the Using additional `UPDATE` statements for data updates, you can use transactions to ensure data consistency. -## MySQL Connector/J Bug +## MySQL JDBC Bug ### `useLocalTransactionState` and `rewriteBatchedStatements` are true at the same time will cause the transaction to fail to commit **Description** -`useLocalTransactionState` 和 `rewriteBatchedStatements` 两参数同时开启时，将导致事务无法提交的问题。你可以使用[代码](https://github.com/Icemap/tidb-java-gitpod/tree/reproduction-local-transaction-state-txn-error)复现。 +When the `useLocalTransactionState` and `rewriteBatchedStatements` parameters turned on at the same time, will cause the transaction to fail to commit. You can reproduce with [this code](https://github.com/Icemap/tidb-java-gitpod/tree/reproduction-local-transaction-state-txn-error). **Ways to Avoid** From 6236a1510027617532361b7e2a741f9f4d8a64f4 Mon Sep 17 00:00:00 2001 From: Cheese Date: Fri, 30 Sep 2022 11:36:30 +0800 Subject: [PATCH 04/11] Update develop/dev-guide-third-party-tools-compatibility.md Co-authored-by: winkyao --- develop/dev-guide-third-party-tools-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index 58ed0191a1eb4..b1190b3c56f85 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -138,7 +138,7 @@ When the `useLocalTransactionState` and `rewriteBatchedStatements` parameters tu > **Note:** > -> This bug has been reported to MySQL, you can follow this [Bug Report](https://bugs.mysql.com/bug.php?id=108643) to keep track of the latest news. +> This bug has been reported to MySQL JDBC, you can follow this [Bug Report](https://bugs.mysql.com/bug.php?id=108643) to keep track of the latest news. **_DO NOT_** turn on `useLocalTransactionState`, as this may prevent transactions from being committed or rolled back. From ef7d9f518030479b5f678d5eddbcbf1cae27c3a0 Mon Sep 17 00:00:00 2001 From: Icemap Date: Tue, 11 Oct 2022 14:54:05 +0800 Subject: [PATCH 05/11] Apply suggestions from code review --- ...ev-guide-third-party-tools-compatibility.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index b1190b3c56f85..ca1ba6bd25663 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -1,6 +1,6 @@ --- title: Known Incompatibility Issues with Third-Party Tools -summary: List the third-party tools incompatibility issues encountered while testing by PingCAP +summary: Describes TiDB compatibility issues with third-party tools found during testing. --- # Known Incompatibility Issues with Third-Party Tools @@ -29,23 +29,23 @@ summary: List the third-party tools incompatibility issues encountered while tes **Ways to Avoid** -Please use each language's 64-bit integer type (or string type) for the reception to prevent overflow. For example, Java should use `Long` or `String` for reception, and JS/TS should use `string` type for the reception. +Please use each language's 64-bit integer type (or string type) to store the result of `SELECT CONNECTION_ID()` to prevent overflow. For example, Java should use `Long` or `String` for reception, and JavaScript/TypeScript should use `string` type for the reception. ### TiDB does not set `Com_*` counters **Description** -MySQL maintains a series of [server status variables starting with `Com_`](https://dev.mysql.com/doc/refman/8.0/en/server-status-variables.html#statvar_Com_xxx) to keep track of the total number of operations you have performed on the database. For example, `Com_select` keeps track of the total number of `SELECT` statements initiated by the MySQL database since it was last started (even if the statements were not queried successfully). TiDB does not maintain this variable. You can use the statement `SHOW GLOBAL STATUS LIKE 'Com_%'` to see the difference between the two databases. +MySQL maintains a series of [server status variables starting with `Com_`](https://dev.mysql.com/doc/refman/8.0/en/server-status-variables.html#statvar_Com_xxx) to keep track of the total number of operations you have performed on the database. For example, `Com_select` keeps track of the total number of `SELECT` statements initiated by the MySQL database since it was last started (even if the statements were not queried successfully). TiDB does not maintain this variable. You can use the statement `SHOW GLOBAL STATUS LIKE 'Com_%'` to see the difference between the MySQL and TiDB. **Ways to Avoid** Please do not use these variables. Common usage scenarios such as monitoring. TiDB is well observable and does not require querying from server status variables. For custom monitoring tools, read the [TiDB Monitoring Framework Overview](/tidb-monitoring-framework.md) for more information. -### TiDB error messages distinguish between `timestamp` and `datetime` +### TiDB error messages distinguish between `TIMESTAMP` and `DATETIME` type **Description** -TiDB error messages distinguish between `timestamp` and `datetime`, while MySQL does not, and returns them all as `datetime`. That is, MySQL incorrectly writes `timestamp` type error messages as `datetime` type. +TiDB error messages distinguish between `TIMESTAMP` and `DATETIME`, while MySQL does not, and returns them all as `DATETIME`. That is, MySQL incorrectly writes `TIMESTAMP` type error messages as `DATETIME` type. **Ways to Avoid** @@ -55,15 +55,15 @@ Do not use the error messages for string matching, but use [Error Codes](/error- **Description** -TiDB uses the [ADMIN CHECK [TABLE|INDEX]](/sql-statements/sql-statement-admin-check-table-index.md) statement to check the consistency of data and corresponding indexes in tables. The `CHECK TABLE` statement is not supported. +TiDB uses the [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) statement to check the consistency of data and corresponding indexes in tables. The `CHECK TABLE` statement is not supported. **Ways to Avoid** -Use `ADMIN CHECK [TABLE|INDEX]`. +Use [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md). ## MySQL JDBC Incompatibility -- Test Version: MySQL Connector/J `8.0.29` +Test Version: MySQL Connector/J `8.0.29` ### Default Collations are inconsistent @@ -152,7 +152,7 @@ Newer versions of MySQL Connector/J work with MySQL servers below version **5.7. This is a known issue, and MySQL Connector/J has not merged the fix code so far. -PingCAP made two dimensional fixes to it: +TiDB made two dimensional fixes to it: - Client side: You can replace the official MySQL Connector/J with [pingcap/mysql-connector-j](https://github.com/pingcap/mysql-connector-j). The bug is fixed in **pingcap/mysql-connector-j**. - Server side: you can upgrade the server to version **6.3** or above; TiDB has fixed this compatibility issue in version **6.3**. \ No newline at end of file From 25555b7e978c6a116ccebdbecb712796da275ceb Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 11 Oct 2022 17:23:53 +0800 Subject: [PATCH 06/11] review --- TOC.md | 2 +- ...v-guide-third-party-tools-compatibility.md | 76 +++++++++---------- 2 files changed, 39 insertions(+), 39 deletions(-) diff --git a/TOC.md b/TOC.md index 27b736131137e..7610b350c818c 100644 --- a/TOC.md +++ b/TOC.md @@ -84,7 +84,7 @@ - [For mysql-connector-python](/develop/dev-guide-outdated-for-python-mysql-connector.md) - Cloud Native Development Environment - [Gitpod](/develop/dev-guide-playground-gitpod.md) - - Third-party Support + - Third-Party Support - [Third-Party Tools Supported by TiDB](/develop/dev-guide-third-party-support.md) - [Known Incompatibility Issues with Third-Party Tools](/develop/dev-guide-third-party-tools-compatibility.md) - [Integrate with ProxySQL](/develop/dev-guide-proxysql-integration.md) diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index ca1ba6bd25663..41146ca1e4aaa 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -7,7 +7,7 @@ summary: Describes TiDB compatibility issues with third-party tools found during > **Note:** > -> TiDB has listed the [unsupported features](/mysql-compatibility.md#unsupported-features), typically unsupported features: +> The [Unsupported features](/mysql-compatibility.md#unsupported-features) lists features that are not supported in TiDB, including: > > - Stored procedures and functions > - Triggers @@ -17,55 +17,55 @@ summary: Describes TiDB compatibility issues with third-party tools found during > - `SPATIAL` functions, data types and indexes > - `XA` syntax > -> Such incompatibilities issues are considered expected behavior and will not be repeated. See the [MySQL Compatibility](/mysql-compatibility.md) for more descriptions. +> Such incompatibilities are considered expected behavior and will not be listed in this document. For more details, see [MySQL Compatibility](/mysql-compatibility.md). ## General -### `SELECT CONNECTION_ID()` returns a 64-bit integer +### `SELECT CONNECTION_ID()` returns a 64-bit integer in TiDB **Description** -`SELECT CONNECTION_ID()` return value for TiDB is 64-bit, such as `2199023260887`, while for MySQL it is 32-bit, such as `391650`. +The `SELECT CONNECTION_ID()` function returns a 64-bit integer in TiDB, such as `2199023260887`, while it returns a 32-bit integer in MySQL, such as `391650`. -**Ways to Avoid** +**Way to avoid** -Please use each language's 64-bit integer type (or string type) to store the result of `SELECT CONNECTION_ID()` to prevent overflow. For example, Java should use `Long` or `String` for reception, and JavaScript/TypeScript should use `string` type for the reception. +In a TiDB application, to avoid data overflow, you should use a 64-bit integer or string type to store the result of `SELECT CONNECTION_ID()`. For example, you can use `Long` or `String` in Java and use `string` in JavaScript or TypeScript. -### TiDB does not set `Com_*` counters +### TiDB does not maintain `Com_*` counters **Description** -MySQL maintains a series of [server status variables starting with `Com_`](https://dev.mysql.com/doc/refman/8.0/en/server-status-variables.html#statvar_Com_xxx) to keep track of the total number of operations you have performed on the database. For example, `Com_select` keeps track of the total number of `SELECT` statements initiated by the MySQL database since it was last started (even if the statements were not queried successfully). TiDB does not maintain this variable. You can use the statement `SHOW GLOBAL STATUS LIKE 'Com_%'` to see the difference between the MySQL and TiDB. +MySQL maintains a series of [server status variables starting with `Com_`](https://dev.mysql.com/doc/refman/8.0/en/server-status-variables.html#statvar_Com_xxx) to keep track of the total number of operations you have performed on the database. For example, `Com_select` records the total number of `SELECT` statements initiated by MySQL since it was last started (even if the statements were not queried successfully). TiDB does not maintain these variables. You can use the statement `SHOW GLOBAL STATUS LIKE 'Com_%'` to see the difference between TiDB and MySQL. -**Ways to Avoid** +**Way to avoid** -Please do not use these variables. Common usage scenarios such as monitoring. TiDB is well observable and does not require querying from server status variables. For custom monitoring tools, read the [TiDB Monitoring Framework Overview](/tidb-monitoring-framework.md) for more information. +Please do not use these variables. One of the common usage scenarios is monitoring. TiDB is well observable and does not require querying from server status variables. For custom monitoring tools, refer to [TiDB Monitoring Framework Overview](/tidb-monitoring-framework.md). ### TiDB error messages distinguish between `TIMESTAMP` and `DATETIME` type **Description** -TiDB error messages distinguish between `TIMESTAMP` and `DATETIME`, while MySQL does not, and returns them all as `DATETIME`. That is, MySQL incorrectly writes `TIMESTAMP` type error messages as `DATETIME` type. +TiDB error messages distinguish between `TIMESTAMP` and `DATETIME`, while MySQL does not, and returns them all as `DATETIME`. That is, MySQL incorrectly converts `TIMESTAMP` type error messages as `DATETIME` type. -**Ways to Avoid** +**Way to avoid** Do not use the error messages for string matching, but use [Error Codes](/error-codes.md) for troubleshooting. -### The `CHECK TABLE` statement is not supported +### TiDB does not support the `CHECK TABLE` statement **Description** -TiDB uses the [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) statement to check the consistency of data and corresponding indexes in tables. The `CHECK TABLE` statement is not supported. +The `CHECK TABLE` statement is not supported in TiDB. To check the consistency of data and corresponding indexes, you can use the [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) statement in TiDB. -**Ways to Avoid** +**Way to avoid** -Use [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md). +Use [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) instead. -## MySQL JDBC Incompatibility +## MySQL JDBC incompatibility Test Version: MySQL Connector/J `8.0.29` -### Default Collations are inconsistent +### Default collations are inconsistent **Description** @@ -79,7 +79,7 @@ Known character sets for which client-side and server-side collations do not mat | `latin1` | `latin1_swedish_ci` | `latin1_bin` | | `utf8mb4` | `utf8mb4_0900_ai_ci` | `utf8mb4_bin` | -**Ways to Avoid** +**Way to avoid** Set the sorting rules manually and do not rely on the client default sorting rules (client default sorting rules are saved by the MySQL Connector/J configuration file). @@ -89,11 +89,11 @@ Set the sorting rules manually and do not rely on the client default sorting rul The `NO_BACKSLASH_ESCAPES` parameter cannot be used so that `\` character is not escaped. Tracking the [issue](https://github.com/pingcap/tidb/issues/35302). -**Ways to Avoid** +**Way to avoid** Do not use `NO_BACKSLASH_ESCAPES` with `\`, but use normal `\\` for SQL writing. -### Not Support INDEX_USED Parameters +### Not support `INDEX_USED` parameters **Description** @@ -102,29 +102,29 @@ TiDB does not set the `SERVER_QUERY_NO_GOOD_INDEX_USED` and `SERVER_QUERY_NO_IND - `com.mysql.cj.protocol.ServerSession.noIndexUsed()` - `com.mysql.cj.protocol.ServerSession.noGoodIndexUsed()` -**Ways to Avoid** +**Way to avoid** Do not use the `noIndexUsed()` and `noGoodIndexUsed()` functions. -### Not Support `enablePacketDebug` Parameters +### Not support `enablePacketDebug` parameters **Description** -TiDB does not support the [enablePacketDebug](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-connp-props-debugging-profiling.html) parameter, which is a MySQL Connector/J parameter used for debugging that will retain the packet's ring buffer. this will cause the connection to **_UNEXPECTED CLOSE_**, **_DO NOT_** turn it on. +TiDB does not support the [enablePacketDebug](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-connp-props-debugging-profiling.html) parameter, which is a MySQL Connector/J parameter used for debugging that will retain the packet's ring buffer. This might cause the connection to **UNEXPECTED CLOSE** and **DO NOT** turn it on. -**Ways to Avoid** +**Way to avoid** Do not set the `enablePacketDebug` parameter. -### Not Support `UpdatableResultSet` +### Not Support UpdatableResultSet **Description** -TiDB does not support `UpdatableResultSet`, that means **_DO NOT_** specify the `ResultSet.CONCUR_UPDATABLE` parameter and updates data inside the ResultSet. +TiDB does not support `UpdatableResultSet`, that is **DO NOT** specify the `ResultSet.CONCUR_UPDATABLE` parameter and update data inside the ResultSet. -**Ways to Avoid** +**Way to avoid** -Using additional `UPDATE` statements for data updates, you can use transactions to ensure data consistency. +To ensure data consistency by transaction, you can use additional `UPDATE` statements to update data. ## MySQL JDBC Bug @@ -132,27 +132,27 @@ Using additional `UPDATE` statements for data updates, you can use transactions **Description** -When the `useLocalTransactionState` and `rewriteBatchedStatements` parameters turned on at the same time, will cause the transaction to fail to commit. You can reproduce with [this code](https://github.com/Icemap/tidb-java-gitpod/tree/reproduction-local-transaction-state-txn-error). +When the `useLocalTransactionState` and `rewriteBatchedStatements` parameters are set to `true` at the same time, the transaction might fail to to commit. You can reproduce with [this code](https://github.com/Icemap/tidb-java-gitpod/tree/reproduction-local-transaction-state-txn-error). -**Ways to Avoid** +**Way to avoid** > **Note:** > > This bug has been reported to MySQL JDBC, you can follow this [Bug Report](https://bugs.mysql.com/bug.php?id=108643) to keep track of the latest news. -**_DO NOT_** turn on `useLocalTransactionState`, as this may prevent transactions from being committed or rolled back. +**DO NOT** turn on `useLocalTransactionState` as this might prevent transactions from being committed or rolled back. -### Connector Forward Compatibility Issue +### Connector forward compatibility issue **Description** -Newer versions of MySQL Connector/J work with MySQL servers below version **5.7.5**, or databases using MySQL server protocols below version **5.7.5** (e.g. TiDB below version **6.3**). It will cause the database connection to hang under certain circumstances, see [Bug Report](https://bugs.mysql.com/bug.php?id=106252) for more details. +The database connection might hang under certain conditions when using MySQL Connector/J 8.0.29 with a MySQL server < 5.7.5 or a database that using the MySQL server < 5.7.5 protocol (such as TiDB earlier than v6.3.0). For more details, see the [Bug Report](https://bugs.mysql.com/bug.php?id=106252). -**Ways to Avoid** +**Way to avoid** This is a known issue, and MySQL Connector/J has not merged the fix code so far. -TiDB made two dimensional fixes to it: +There are two dimensional fix in TiDB: -- Client side: You can replace the official MySQL Connector/J with [pingcap/mysql-connector-j](https://github.com/pingcap/mysql-connector-j). The bug is fixed in **pingcap/mysql-connector-j**. -- Server side: you can upgrade the server to version **6.3** or above; TiDB has fixed this compatibility issue in version **6.3**. \ No newline at end of file +- Client side: you can replace the official MySQL Connector/J with [pingcap/mysql-connector-j](https://github.com/pingcap/mysql-connector-j). The bug is fixed in **pingcap/mysql-connector-j**. +- Server side: you can upgrade the server to v6.3.0 or later versions. In TiDB v6.3.0, this compatibility issue has been fixed. From b6f1f18f83f7b258071f65b15f726ed7e99ba1fa Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 12 Oct 2022 11:53:13 +0800 Subject: [PATCH 07/11] review from @Oreoxmt --- ...v-guide-third-party-tools-compatibility.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index 41146ca1e4aaa..1d04141c8d648 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -17,9 +17,9 @@ summary: Describes TiDB compatibility issues with third-party tools found during > - `SPATIAL` functions, data types and indexes > - `XA` syntax > -> Such incompatibilities are considered expected behavior and will not be listed in this document. For more details, see [MySQL Compatibility](/mysql-compatibility.md). +> The preceding unsupported features are considered expected behavior and are not listed in this document. For more details, see [MySQL Compatibility](/mysql-compatibility.md). -## General +## General incompatibility ### `SELECT CONNECTION_ID()` returns a 64-bit integer in TiDB @@ -41,11 +41,11 @@ MySQL maintains a series of [server status variables starting with `Com_`](https Please do not use these variables. One of the common usage scenarios is monitoring. TiDB is well observable and does not require querying from server status variables. For custom monitoring tools, refer to [TiDB Monitoring Framework Overview](/tidb-monitoring-framework.md). -### TiDB error messages distinguish between `TIMESTAMP` and `DATETIME` type +### TiDB distinguishes between `TIMESTAMP` and `DATETIME` in error messages **Description** -TiDB error messages distinguish between `TIMESTAMP` and `DATETIME`, while MySQL does not, and returns them all as `DATETIME`. That is, MySQL incorrectly converts `TIMESTAMP` type error messages as `DATETIME` type. +TiDB error messages distinguish between `TIMESTAMP` and `DATETIME`, while MySQL does not, and returns them all as `DATETIME`. That is, MySQL incorrectly converts `TIMESTAMP` type error messages to `DATETIME` type. **Way to avoid** @@ -83,7 +83,7 @@ Known character sets for which client-side and server-side collations do not mat Set the sorting rules manually and do not rely on the client default sorting rules (client default sorting rules are saved by the MySQL Connector/J configuration file). -### Parameter `NO_BACKSLASH_ESCAPES` not effect +### The `NO_BACKSLASH_ESCAPES` parameter is ineffective **Description** @@ -93,7 +93,7 @@ The `NO_BACKSLASH_ESCAPES` parameter cannot be used so that `\` character is not Do not use `NO_BACKSLASH_ESCAPES` with `\`, but use normal `\\` for SQL writing. -### Not support `INDEX_USED` parameters +### The `INDEX_USED` parameters are not supported **Description** @@ -106,7 +106,7 @@ TiDB does not set the `SERVER_QUERY_NO_GOOD_INDEX_USED` and `SERVER_QUERY_NO_IND Do not use the `noIndexUsed()` and `noGoodIndexUsed()` functions. -### Not support `enablePacketDebug` parameters +### The `enablePacketDebug` parameter is not supported **Description** @@ -116,7 +116,7 @@ TiDB does not support the [enablePacketDebug](https://dev.mysql.com/doc/connecto Do not set the `enablePacketDebug` parameter. -### Not Support UpdatableResultSet +### The UpdatableResultSet is not supported **Description** @@ -126,13 +126,13 @@ TiDB does not support `UpdatableResultSet`, that is **DO NOT** specify the `Resu To ensure data consistency by transaction, you can use additional `UPDATE` statements to update data. -## MySQL JDBC Bug +## MySQL JDBC bugs ### `useLocalTransactionState` and `rewriteBatchedStatements` are true at the same time will cause the transaction to fail to commit **Description** -When the `useLocalTransactionState` and `rewriteBatchedStatements` parameters are set to `true` at the same time, the transaction might fail to to commit. You can reproduce with [this code](https://github.com/Icemap/tidb-java-gitpod/tree/reproduction-local-transaction-state-txn-error). +When the `useLocalTransactionState` and `rewriteBatchedStatements` parameters are set to `true` at the same time, the transaction might fail to commit. You can reproduce with [this code](https://github.com/Icemap/tidb-java-gitpod/tree/reproduction-local-transaction-state-txn-error). **Way to avoid** @@ -142,17 +142,17 @@ When the `useLocalTransactionState` and `rewriteBatchedStatements` parameters ar **DO NOT** turn on `useLocalTransactionState` as this might prevent transactions from being committed or rolled back. -### Connector forward compatibility issue +### Connector is incompatible with the server version earlier than 5.7.5 **Description** -The database connection might hang under certain conditions when using MySQL Connector/J 8.0.29 with a MySQL server < 5.7.5 or a database that using the MySQL server < 5.7.5 protocol (such as TiDB earlier than v6.3.0). For more details, see the [Bug Report](https://bugs.mysql.com/bug.php?id=106252). +The database connection might hang under certain conditions when using MySQL Connector/J 8.0.29 with a MySQL server < 5.7.5 or a database using the MySQL server < 5.7.5 protocol (such as TiDB earlier than v6.3.0). For more details, see the [Bug Report](https://bugs.mysql.com/bug.php?id=106252). **Way to avoid** -This is a known issue, and MySQL Connector/J has not merged the fix code so far. +This is a known issue, and MySQL Connector/J has not merged the fixed code so far. -There are two dimensional fix in TiDB: +There are two-dimensional fixes in TiDB: - Client side: you can replace the official MySQL Connector/J with [pingcap/mysql-connector-j](https://github.com/pingcap/mysql-connector-j). The bug is fixed in **pingcap/mysql-connector-j**. - Server side: you can upgrade the server to v6.3.0 or later versions. In TiDB v6.3.0, this compatibility issue has been fixed. From 662f17cbf933f7f77f1995a6393fa4302efe6e46 Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 12 Oct 2022 17:48:48 +0800 Subject: [PATCH 08/11] Apply suggestions from code review Co-authored-by: xixirangrang --- ...v-guide-third-party-tools-compatibility.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index 1d04141c8d648..3357461d75d6b 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -17,7 +17,7 @@ summary: Describes TiDB compatibility issues with third-party tools found during > - `SPATIAL` functions, data types and indexes > - `XA` syntax > -> The preceding unsupported features are considered expected behavior and are not listed in this document. For more details, see [MySQL Compatibility](/mysql-compatibility.md). +> The preceding unsupported features are expected behavior and are not listed in this document. For more details, see [MySQL Compatibility](/mysql-compatibility.md). ## General incompatibility @@ -39,7 +39,7 @@ MySQL maintains a series of [server status variables starting with `Com_`](https **Way to avoid** -Please do not use these variables. One of the common usage scenarios is monitoring. TiDB is well observable and does not require querying from server status variables. For custom monitoring tools, refer to [TiDB Monitoring Framework Overview](/tidb-monitoring-framework.md). +Do not use these variables. One common scenario is monitoring. TiDB is well observable and does not require querying from server status variables. For custom monitoring tools, refer to [TiDB Monitoring Framework Overview](/tidb-monitoring-framework.md). ### TiDB distinguishes between `TIMESTAMP` and `DATETIME` in error messages @@ -49,21 +49,21 @@ TiDB error messages distinguish between `TIMESTAMP` and `DATETIME`, while MySQL **Way to avoid** -Do not use the error messages for string matching, but use [Error Codes](/error-codes.md) for troubleshooting. +Do not use the error messages for string matching. Instead, use [Error Codes](/error-codes.md) for troubleshooting. ### TiDB does not support the `CHECK TABLE` statement **Description** -The `CHECK TABLE` statement is not supported in TiDB. To check the consistency of data and corresponding indexes, you can use the [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) statement in TiDB. +The `CHECK TABLE` statement is not supported in TiDB. **Way to avoid** -Use [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) instead. +To check the consistency of data and corresponding indexes, you can use the [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) statement in TiDB. ## MySQL JDBC incompatibility -Test Version: MySQL Connector/J `8.0.29` +Test Version: MySQL Connector/J `8.0.29`. ### Default collations are inconsistent @@ -71,7 +71,7 @@ Test Version: MySQL Connector/J `8.0.29` The collations of MySQL Connector/J are stored in the client and are distinguished by the server version. -Known character sets for which client-side and server-side collations do not match: +The following table shows known character sets for which client-side and server-side collations do not match: | Character Sets | Client Default Collations | Server Default Collations | | - | - | - | @@ -81,23 +81,23 @@ Known character sets for which client-side and server-side collations do not mat **Way to avoid** -Set the sorting rules manually and do not rely on the client default sorting rules (client default sorting rules are saved by the MySQL Connector/J configuration file). +Set the sorting rules manually and do not rely on the client default sorting rules. Client default sorting rules are saved in the MySQL Connector/J configuration file. -### The `NO_BACKSLASH_ESCAPES` parameter is ineffective +### The `NO_BACKSLASH_ESCAPES` parameter does not work **Description** -The `NO_BACKSLASH_ESCAPES` parameter cannot be used so that `\` character is not escaped. Tracking the [issue](https://github.com/pingcap/tidb/issues/35302). +The `NO_BACKSLASH_ESCAPES` parameter cannot be used so that `\` character is not escaped. Track this [issue](https://github.com/pingcap/tidb/issues/35302). **Way to avoid** -Do not use `NO_BACKSLASH_ESCAPES` with `\`, but use normal `\\` for SQL writing. +Do not use `NO_BACKSLASH_ESCAPES` with `\`, but use `\\` for SQL writing. ### The `INDEX_USED` parameters are not supported **Description** -TiDB does not set the `SERVER_QUERY_NO_GOOD_INDEX_USED` and `SERVER_QUERY_NO_INDEX_USED` parameters in the protocol. This will cause the following parameters to be returned inconsistently with the actual: +TiDB does not set the `SERVER_QUERY_NO_GOOD_INDEX_USED` and `SERVER_QUERY_NO_INDEX_USED` parameters in the protocol. This will cause the following parameters to be returned inconsistently with the actual situation: - `com.mysql.cj.protocol.ServerSession.noIndexUsed()` - `com.mysql.cj.protocol.ServerSession.noGoodIndexUsed()` @@ -110,7 +110,7 @@ Do not use the `noIndexUsed()` and `noGoodIndexUsed()` functions. **Description** -TiDB does not support the [enablePacketDebug](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-connp-props-debugging-profiling.html) parameter, which is a MySQL Connector/J parameter used for debugging that will retain the packet's ring buffer. This might cause the connection to **UNEXPECTED CLOSE** and **DO NOT** turn it on. +TiDB does not support the [enablePacketDebug](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-connp-props-debugging-profiling.html) parameter. It is a MySQL Connector/J parameter used for debugging that will retain the packet's ring buffer. This might cause the connection to **UNEXPECTED CLOSE**. **DO NOT** turn it on. **Way to avoid** @@ -120,7 +120,7 @@ Do not set the `enablePacketDebug` parameter. **Description** -TiDB does not support `UpdatableResultSet`, that is **DO NOT** specify the `ResultSet.CONCUR_UPDATABLE` parameter and update data inside the ResultSet. +TiDB does not support `UpdatableResultSet`. **DO NOT** specify the `ResultSet.CONCUR_UPDATABLE` parameter or update data inside the `ResultSet`. **Way to avoid** @@ -152,7 +152,7 @@ The database connection might hang under certain conditions when using MySQL Con This is a known issue, and MySQL Connector/J has not merged the fixed code so far. -There are two-dimensional fixes in TiDB: +TiDB fixes it in the following ways: - Client side: you can replace the official MySQL Connector/J with [pingcap/mysql-connector-j](https://github.com/pingcap/mysql-connector-j). The bug is fixed in **pingcap/mysql-connector-j**. - Server side: you can upgrade the server to v6.3.0 or later versions. In TiDB v6.3.0, this compatibility issue has been fixed. From 3bf42fe41124b5126ffd50510b0cffa616abad12 Mon Sep 17 00:00:00 2001 From: Icemap Date: Thu, 13 Oct 2022 11:23:33 +0800 Subject: [PATCH 09/11] apply suggestions --- develop/dev-guide-third-party-tools-compatibility.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index 3357461d75d6b..6b0e417dfaa38 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -35,7 +35,7 @@ In a TiDB application, to avoid data overflow, you should use a 64-bit integer o **Description** -MySQL maintains a series of [server status variables starting with `Com_`](https://dev.mysql.com/doc/refman/8.0/en/server-status-variables.html#statvar_Com_xxx) to keep track of the total number of operations you have performed on the database. For example, `Com_select` records the total number of `SELECT` statements initiated by MySQL since it was last started (even if the statements were not queried successfully). TiDB does not maintain these variables. You can use the statement `SHOW GLOBAL STATUS LIKE 'Com_%'` to see the difference between TiDB and MySQL. +MySQL maintains a series of [server status variables starting with `Com_`](https://dev.mysql.com/doc/refman/8.0/en/server-status-variables.html#statvar_Com_xxx) to keep track of the total number of operations you have performed on the database. For example, `Com_select` records the total number of `SELECT` statements initiated by MySQL since it was last started (even if the statements were not queried successfully). TiDB does not maintain these variables. You can use the statement [`SHOW GLOBAL STATUS LIKE 'Com_%'`](/sql-statements/sql-statement-show-status.md) to see the difference between TiDB and MySQL. **Way to avoid** @@ -120,11 +120,11 @@ Do not set the `enablePacketDebug` parameter. **Description** -TiDB does not support `UpdatableResultSet`. **DO NOT** specify the `ResultSet.CONCUR_UPDATABLE` parameter or update data inside the `ResultSet`. +TiDB does not support `UpdatableResultSet`. **DO NOT** specify the `ResultSet.CONCUR_UPDATABLE` parameter and **DO NOT** update data inside the `ResultSet`. **Way to avoid** -To ensure data consistency by transaction, you can use additional `UPDATE` statements to update data. +To ensure data consistency by transaction, you can use `UPDATE` statements to update data. ## MySQL JDBC bugs @@ -150,7 +150,7 @@ The database connection might hang under certain conditions when using MySQL Con **Way to avoid** -This is a known issue, and MySQL Connector/J has not merged the fixed code so far. +This is a known issue and as of October 12, 2022, MySQL Connector/J has not merged the fixed code so far. TiDB fixes it in the following ways: From 6c3aaa5e4c065f55cea0fb3d5d151686b40f2cdf Mon Sep 17 00:00:00 2001 From: Aolin Date: Thu, 13 Oct 2022 11:50:10 +0800 Subject: [PATCH 10/11] review --- ...v-guide-third-party-tools-compatibility.md | 46 +++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index 6b0e417dfaa38..9754845734d29 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -55,45 +55,45 @@ Do not use the error messages for string matching. Instead, use [Error Codes](/e **Description** -The `CHECK TABLE` statement is not supported in TiDB. +The `CHECK TABLE` statement is not supported in TiDB. **Way to avoid** To check the consistency of data and corresponding indexes, you can use the [`ADMIN CHECK [TABLE|INDEX]`](/sql-statements/sql-statement-admin-check-table-index.md) statement in TiDB. -## MySQL JDBC incompatibility +## Compatibility with MySQL JDBC -Test Version: MySQL Connector/J `8.0.29`. +The test version is MySQL Connector/J 8.0.29. -### Default collations are inconsistent +### The default collation is inconsistent **Description** -The collations of MySQL Connector/J are stored in the client and are distinguished by the server version. +The collations of MySQL Connector/J are stored on the client side and distinguished by the server version. -The following table shows known character sets for which client-side and server-side collations do not match: +The following table lists known client-side and server-side collation inconsistencies in character sets: -| Character Sets | Client Default Collations | Server Default Collations | -| - | - | - | -| `ascii` | `ascii_general_ci` | `ascii_bin` | -| `latin1` | `latin1_swedish_ci` | `latin1_bin` | +| Character | Client-side default collation | Server-side default collation | +| --------- | -------------------- | ------------- | +| `ascii` | `ascii_general_ci` | `ascii_bin` | +| `latin1` | `latin1_swedish_ci` | `latin1_bin` | | `utf8mb4` | `utf8mb4_0900_ai_ci` | `utf8mb4_bin` | **Way to avoid** -Set the sorting rules manually and do not rely on the client default sorting rules. Client default sorting rules are saved in the MySQL Connector/J configuration file. +Set the collation manually, and do not rely on the client-side default collation. The client-side default collation is stored by the MySQL Connector/J configuration file. -### The `NO_BACKSLASH_ESCAPES` parameter does not work +### The `NO_BACKSLASH_ESCAPES` parameter does not take effect **Description** -The `NO_BACKSLASH_ESCAPES` parameter cannot be used so that `\` character is not escaped. Track this [issue](https://github.com/pingcap/tidb/issues/35302). +In TiDB, you cannot use the `NO_BACKSLASH_ESCAPES` parameter without escaping the `\` character. For more details, track this [issue](https://github.com/pingcap/tidb/issues/35302). **Way to avoid** -Do not use `NO_BACKSLASH_ESCAPES` with `\`, but use `\\` for SQL writing. +Do not use `NO_BACKSLASH_ESCAPES` with `\` in TiDB, but use `\\` in SQL statements. -### The `INDEX_USED` parameters are not supported +### The `INDEX_USED` related parameters are not supported **Description** @@ -104,17 +104,17 @@ TiDB does not set the `SERVER_QUERY_NO_GOOD_INDEX_USED` and `SERVER_QUERY_NO_IND **Way to avoid** -Do not use the `noIndexUsed()` and `noGoodIndexUsed()` functions. +Do not use the `noIndexUsed()` and `noGoodIndexUsed()` functions in TiDB. ### The `enablePacketDebug` parameter is not supported **Description** -TiDB does not support the [enablePacketDebug](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-connp-props-debugging-profiling.html) parameter. It is a MySQL Connector/J parameter used for debugging that will retain the packet's ring buffer. This might cause the connection to **UNEXPECTED CLOSE**. **DO NOT** turn it on. +TiDB does not support the [enablePacketDebug](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-connp-props-debugging-profiling.html) parameter. It is a MySQL Connector/J parameter used for debugging that will keep the buffer of the data packet. This might cause the connection to close unexpectedly. **DO NOT** turn it on. **Way to avoid** -Do not set the `enablePacketDebug` parameter. +Do not set the `enablePacketDebug` parameter in TiDB. ### The UpdatableResultSet is not supported @@ -128,7 +128,7 @@ To ensure data consistency by transaction, you can use `UPDATE` statements to up ## MySQL JDBC bugs -### `useLocalTransactionState` and `rewriteBatchedStatements` are true at the same time will cause the transaction to fail to commit +### `useLocalTransactionState` and `rewriteBatchedStatements` are true at the same time will cause the transaction to fail to commit or roll back **Description** @@ -138,7 +138,7 @@ When the `useLocalTransactionState` and `rewriteBatchedStatements` parameters ar > **Note:** > -> This bug has been reported to MySQL JDBC, you can follow this [Bug Report](https://bugs.mysql.com/bug.php?id=108643) to keep track of the latest news. +> This bug has been reported to MySQL JDBC. To keep track of the process, you can follow this [Bug Report](https://bugs.mysql.com/bug.php?id=108643). **DO NOT** turn on `useLocalTransactionState` as this might prevent transactions from being committed or rolled back. @@ -150,9 +150,9 @@ The database connection might hang under certain conditions when using MySQL Con **Way to avoid** -This is a known issue and as of October 12, 2022, MySQL Connector/J has not merged the fixed code so far. +This is a known issue. As of October 12, 2022, MySQL Connector/J has not fixed the issue. TiDB fixes it in the following ways: -- Client side: you can replace the official MySQL Connector/J with [pingcap/mysql-connector-j](https://github.com/pingcap/mysql-connector-j). The bug is fixed in **pingcap/mysql-connector-j**. -- Server side: you can upgrade the server to v6.3.0 or later versions. In TiDB v6.3.0, this compatibility issue has been fixed. +- Client side: This bug has been fixed in **pingcap/mysql-connector-j** and you can use the [pingcap/mysql-connector-j](https://github.com/pingcap/mysql-connector-j) instead of the official MySQL Connector/J. +- Server side: This compatibility issue has been fixed since TiDB v6.3.0 and you can upgrade the server to v6.3.0 or later versions. From 385ced8c92a6a8d5e4fcd4786a26f9f0b6efe32d Mon Sep 17 00:00:00 2001 From: Aolin Date: Thu, 13 Oct 2022 15:51:28 +0800 Subject: [PATCH 11/11] Apply suggestions from code review Co-authored-by: xixirangrang --- develop/dev-guide-third-party-tools-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index 9754845734d29..57cd9e58a9951 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -7,7 +7,7 @@ summary: Describes TiDB compatibility issues with third-party tools found during > **Note:** > -> The [Unsupported features](/mysql-compatibility.md#unsupported-features) lists features that are not supported in TiDB, including: +> The [Unsupported features](/mysql-compatibility.md#unsupported-features) section lists the unsupported features in TiDB, including: > > - Stored procedures and functions > - Triggers