From 947c8240ec3e362d0ebbef45c61ffaf2add88329 Mon Sep 17 00:00:00 2001 From: Test User Date: Thu, 24 Apr 2025 17:32:32 +0800 Subject: [PATCH 01/13] add FAQs about JDBC connectionCollation --- faq/sql-faq.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/faq/sql-faq.md b/faq/sql-faq.md index 9532903c68c6..5d707e65fd3e 100644 --- a/faq/sql-faq.md +++ b/faq/sql-faq.md @@ -413,3 +413,70 @@ ID 没什么规律，只要是唯一就行。不过在生成执行计划时， ### TiKV 性能参数调优 详情参考 [TiKV 性能参数调优](/tune-tikv-memory-performance.md)。 + +## JDBC 连接所使用的排序规则 + +本节列出了 JDBC 连接的排序规则，并介绍了如何解决 TiDB 升级后排序规则变化带来的问题。关于 TiDB 中支持的字符集和排序规则，请参考[字符集和排序规则](/character-set-and-collation.md)。 + +### 当 JDBC URL 中未配置 `connectionCollation` 时，JDBC 连接使用什么排序规则？ + +当 JDBC URL 中未配置 `connectionCollation` 时，有以下两种场景： + +**场景一**：JDBC URL 中 `connectionCollation` 和 `characterEncoding` 均未配置 + +- 对于 Connector/J8.0.25 及之前版本，JDBC 驱动程序将尝试使用服务器的默认字符集。因为 TiDB 的默认字符集为 `utf8mb4`，驱动程序将使用 `utf8mb4_bin` 作为连接排序规则。 +- 对于 Connector/J8.0.26 及之后版本，JDBC 驱动程序将使用 `utf8mb4` 字符集，并根据 `SELECT VERSION()` 的返回值自动选择排序规则。 + + - 当返回值小于 `8.0.1` 时，驱动程序使用 `utf8mb4_general_ci` 作为连接排序规则。TiDB 将遵循驱动程序，使用 `utf8mb4_general_ci` 作为排序规则。 + - 当返回值大于等于 `8.0.1` 时，驱动程序使用 `utf8mb4_0900_ai_ci` 作为连接排序规则。v7.4.0 及更高版本的 TiDB 将遵循驱动程序，使用 `utf8mb4_0900_ai_ci` 作为排序规则，而 v7.4.0 之前版本的 TiDB 由于不支持 `utf8mb4_0900_ai_ci` 排序规则，将回退到使用默认的排序规则 `utf8mb4_bin`。 + +**场景二**： JDBC URL 中配置了 `characterEncoding=utf8` 但未配置 `connectionCollation`，JDBC 驱动程序将按照映射规则使用 `utf8mb4` 字符集，并按照场景一中的描述选择排序规则。 + +### 如何解决 TiDB 升级后排序规则变化带来的问题？ + +在 TiDB v7.4 及之前版本中，如果 JDBC URL 中 `connectionCollation` 未配置，且 `characterEncoding` 未配置或配置为 `utf8`，TiDB [`collation_connection`](/system-variable-reference.md#collation_connection) 变量将默认使用 `utf8mb4_bin` 排序规则。 + +从 TiDB v7.4 开始，如果 JDBC URL 中 `connectionCollation` 未配置且 `characterEncoding` 未配置或配置为 `utf8`，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量值取决于 JDBC 驱动版本。例如，对于 Connector/J8.0.26 及之后版本，JDBC 驱动程序默认使用 `utf8mb4` 字符集，使用 `utf8mb4_general_ci` 作为连接排序规则，TiDB 将遵循驱动程序，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量将使用 `utf8mb4_0900_ai_ci` 排序规则。详情请参考[JDBC 连接的排序规则](#当-jdbc-url-中未配置-connectioncollation-时jdbc-连接使用什么排序规则)。 + +当从较低版本升级到 v7.4 或更高版本时（例如，从 v6.5 升级到 v7.5），如需保持 JDBC 连接的 `collation_connection` 为 `utf8mb4_bin`，建议在 JDBC URL 中配置 `connectionCollation` 参数。 + +以下为 TiDB v6.5 中常见的 JDBC URL 配置： + +``` +spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=utf8&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultfetchsize=-2147483648&allowMultiQueries=true +``` + +升级到 TiDB v7.5 或更高版本后，建议在 JDBC URL 中配置 `connectionCollation` 参数： + +``` +spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=utf8&connectionCollation=utf8mb4_bin&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultFetchSize=-2147483648&allowMultiQueries=true +``` + +### `utf8mb4_bin` 与 `utf8mb4_0900_ai_ci` 排序规则有何区别？ + +| 排序规则 | 是否区分大小写 | 是否忽略末尾空格 | 是否区分重音 | 比较方式 | +|----------------------|----------------|------------------|--------------|------------------------| +| `utf8mb4_bin` | 区分 | 忽略 | 区分 | 按二进制编码值比较 | +| `utf8mb4_0900_ai_ci` | 不区分 | 不忽略 | 不区分 | 使用 Unicode 排序算法 | + +例如： + +```sql +-- utf8mb4_bin 区分大小写 +SELECT 'apple' = 'Apple' COLLATE utf8mb4_bin; -- 返回 0 (FALSE) + +-- utf8mb4_0900_ai_ci 不区分大小写 +SELECT 'apple' = 'Apple' COLLATE utf8mb4_0900_ai_ci; -- 返回 1 (TRUE) + +-- utf8mb4_bin 忽略末尾空格 +SELECT 'Apple ' = 'Apple' COLLATE utf8mb4_bin; -- 返回 1 (TRUE) + +-- utf8mb4_0900_ai_ci 不忽略末尾空格 +SELECT 'Apple ' = 'Apple' COLLATE utf8mb4_0900_ai_ci; -- 返回 0 (FALSE) + +-- utf8mb4_bin 区分重音 +SELECT 'café' = 'cafe' COLLATE utf8mb4_bin; -- 返回 0 (FALSE) + +-- utf8mb4_0900_ai_ci 不区分重音 +SELECT 'café' = 'cafe' COLLATE utf8mb4_0900_ai_ci; -- 返回 1 (TRUE) +``` \ No newline at end of file From 01bf89410feba62b7b6e1333184bd896116b31fa Mon Sep 17 00:00:00 2001 From: Test User Date: Thu, 24 Apr 2025 17:32:32 +0800 Subject: [PATCH 02/13] add FAQs about JDBC connectionCollation --- faq/sql-faq.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-) diff --git a/faq/sql-faq.md b/faq/sql-faq.md index 9532903c68c6..2dd3753f474a 100644 --- a/faq/sql-faq.md +++ b/faq/sql-faq.md @@ -325,6 +325,73 @@ TiDB 在执行 SQL 语句时，会根据隔离级别确定一个对象的 `schem - 如果 Owner 不存在，尝试手动触发 Owner 选举：`curl -X POST http://{TiDBIP}:10080/ddl/owner/resign`。 - 如果 Owner 存在，导出 Goroutine 堆栈并检查可能卡住的地方。 +## JDBC 连接所使用的排序规则 + +本节列出了 JDBC 连接的排序规则，并介绍了如何解决 TiDB 升级后排序规则变化带来的问题。关于 TiDB 中支持的字符集和排序规则，请参考[字符集和排序规则](/character-set-and-collation.md)。 + +### 当 JDBC URL 中未配置 `connectionCollation` 时，JDBC 连接使用什么排序规则？ + +当 JDBC URL 中未配置 `connectionCollation` 时，有以下两种场景： + +**场景一**：JDBC URL 中 `connectionCollation` 和 `characterEncoding` 均未配置 + +- 对于 Connector/J8.0.25 及之前版本，JDBC 驱动程序将尝试使用服务器的默认字符集。因为 TiDB 的默认字符集为 `utf8mb4`，驱动程序将使用 `utf8mb4_bin` 作为连接排序规则。 +- 对于 Connector/J8.0.26 及之后版本，JDBC 驱动程序将使用 `utf8mb4` 字符集，并根据 `SELECT VERSION()` 的返回值自动选择排序规则。 + + - 当返回值小于 `8.0.1` 时，驱动程序使用 `utf8mb4_general_ci` 作为连接排序规则。TiDB 将遵循驱动程序，使用 `utf8mb4_general_ci` 作为排序规则。 + - 当返回值大于等于 `8.0.1` 时，驱动程序使用 `utf8mb4_0900_ai_ci` 作为连接排序规则。v7.4.0 及更高版本的 TiDB 将遵循驱动程序，使用 `utf8mb4_0900_ai_ci` 作为排序规则，而 v7.4.0 之前版本的 TiDB 由于不支持 `utf8mb4_0900_ai_ci` 排序规则，将回退到使用默认的排序规则 `utf8mb4_bin`。 + +**场景二**： JDBC URL 中配置了 `characterEncoding=utf8` 但未配置 `connectionCollation`，JDBC 驱动程序将按照映射规则使用 `utf8mb4` 字符集，并按照场景一中的描述选择排序规则。 + +### 如何解决 TiDB 升级后排序规则变化带来的问题？ + +在 TiDB v7.4 及之前版本中，如果 JDBC URL 中 `connectionCollation` 未配置，且 `characterEncoding` 未配置或配置为 `utf8`，TiDB [`collation_connection`](/system-variable-reference.md#collation_connection) 变量将默认使用 `utf8mb4_bin` 排序规则。 + +从 TiDB v7.4 开始，如果 JDBC URL 中 `connectionCollation` 未配置且 `characterEncoding` 未配置或配置为 `utf8`，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量值取决于 JDBC 驱动版本。例如，对于 Connector/J8.0.26 及之后版本，JDBC 驱动程序默认使用 `utf8mb4` 字符集，使用 `utf8mb4_general_ci` 作为连接排序规则，TiDB 将遵循驱动程序，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量将使用 `utf8mb4_0900_ai_ci` 排序规则。详情请参考[JDBC 连接的排序规则](#当-jdbc-url-中未配置-connectioncollation-时jdbc-连接使用什么排序规则)。 + +当从较低版本升级到 v7.4 或更高版本时（例如，从 v6.5 升级到 v7.5），如需保持 JDBC 连接的 `collation_connection` 为 `utf8mb4_bin`，建议在 JDBC URL 中配置 `connectionCollation` 参数。 + +以下为 TiDB v6.5 中常见的 JDBC URL 配置： + +``` +spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=utf8&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultfetchsize=-2147483648&allowMultiQueries=true +``` + +升级到 TiDB v7.5 或更高版本后，建议在 JDBC URL 中配置 `connectionCollation` 参数： + +``` +spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=utf8&connectionCollation=utf8mb4_bin&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultFetchSize=-2147483648&allowMultiQueries=true +``` + +### `utf8mb4_bin` 与 `utf8mb4_0900_ai_ci` 排序规则有何区别？ + +| 排序规则 | 是否区分大小写 | 是否忽略末尾空格 | 是否区分重音 | 比较方式 | +|----------------------|----------------|------------------|--------------|------------------------| +| `utf8mb4_bin` | 区分 | 忽略 | 区分 | 按二进制编码值比较 | +| `utf8mb4_0900_ai_ci` | 不区分 | 不忽略 | 不区分 | 使用 Unicode 排序算法 | + +例如： + +```sql +-- utf8mb4_bin 区分大小写 +SELECT 'apple' = 'Apple' COLLATE utf8mb4_bin; -- 返回 0 (FALSE) + +-- utf8mb4_0900_ai_ci 不区分大小写 +SELECT 'apple' = 'Apple' COLLATE utf8mb4_0900_ai_ci; -- 返回 1 (TRUE) + +-- utf8mb4_bin 忽略末尾空格 +SELECT 'Apple ' = 'Apple' COLLATE utf8mb4_bin; -- 返回 1 (TRUE) + +-- utf8mb4_0900_ai_ci 不忽略末尾空格 +SELECT 'Apple ' = 'Apple' COLLATE utf8mb4_0900_ai_ci; -- 返回 0 (FALSE) + +-- utf8mb4_bin 区分重音 +SELECT 'café' = 'cafe' COLLATE utf8mb4_bin; -- 返回 0 (FALSE) + +-- utf8mb4_0900_ai_ci 不区分重音 +SELECT 'café' = 'cafe' COLLATE utf8mb4_0900_ai_ci; -- 返回 1 (TRUE) +``` + ## SQL 优化 ### TiDB 执行计划解读 @@ -412,4 +479,4 @@ ID 没什么规律，只要是唯一就行。不过在生成执行计划时， ### TiKV 性能参数调优 -详情参考 [TiKV 性能参数调优](/tune-tikv-memory-performance.md)。 +详情参考 [TiKV 性能参数调优](/tune-tikv-memory-performance.md)。 \ No newline at end of file From 69632e9bb7d6596e152141e2397683e593c09d0a Mon Sep 17 00:00:00 2001 From: Test User Date: Fri, 25 Apr 2025 10:42:00 +0800 Subject: [PATCH 03/13] Update sql-faq.md --- faq/sql-faq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/faq/sql-faq.md b/faq/sql-faq.md index 2dd3753f474a..62a2617ac0f8 100644 --- a/faq/sql-faq.md +++ b/faq/sql-faq.md @@ -327,7 +327,7 @@ TiDB 在执行 SQL 语句时，会根据隔离级别确定一个对象的 `schem ## JDBC 连接所使用的排序规则 -本节列出了 JDBC 连接的排序规则，并介绍了如何解决 TiDB 升级后排序规则变化带来的问题。关于 TiDB 中支持的字符集和排序规则，请参考[字符集和排序规则](/character-set-and-collation.md)。 +本节介绍了 JDBC 连接的排序规则行为，并提供了解决 TiDB 升级后排序规则变化问题的方案。关于 TiDB 支持的字符集和排序规则，请参考[字符集和排序规则](/character-set-and-collation.md)。 ### 当 JDBC URL 中未配置 `connectionCollation` 时，JDBC 连接使用什么排序规则？ @@ -345,9 +345,9 @@ TiDB 在执行 SQL 语句时，会根据隔离级别确定一个对象的 `schem ### 如何解决 TiDB 升级后排序规则变化带来的问题？ -在 TiDB v7.4 及之前版本中，如果 JDBC URL 中 `connectionCollation` 未配置，且 `characterEncoding` 未配置或配置为 `utf8`，TiDB [`collation_connection`](/system-variable-reference.md#collation_connection) 变量将默认使用 `utf8mb4_bin` 排序规则。 +在 TiDB v7.4 及之前版本中，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `utf8`，TiDB [`collation_connection`](/system-variable-reference.md#collation_connection) 变量将默认使用 `utf8mb4_bin` 排序规则。 -从 TiDB v7.4 开始，如果 JDBC URL 中 `connectionCollation` 未配置且 `characterEncoding` 未配置或配置为 `utf8`，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量值取决于 JDBC 驱动版本。例如，对于 Connector/J8.0.26 及之后版本，JDBC 驱动程序默认使用 `utf8mb4` 字符集，使用 `utf8mb4_general_ci` 作为连接排序规则，TiDB 将遵循驱动程序，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量将使用 `utf8mb4_0900_ai_ci` 排序规则。详情请参考[JDBC 连接的排序规则](#当-jdbc-url-中未配置-connectioncollation-时jdbc-连接使用什么排序规则)。 +从 TiDB v7.4 开始，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `utf8`，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量值取决于 JDBC 驱动版本。例如，对于 Connector/J8.0.26 及之后版本，JDBC 驱动程序默认使用 `utf8mb4` 字符集，使用 `utf8mb4_general_ci` 作为连接排序规则，TiDB 将遵循驱动程序，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量将使用 `utf8mb4_0900_ai_ci` 排序规则。详情请参考[JDBC 连接的排序规则](#当-jdbc-url-中未配置-connectioncollation-时jdbc-连接使用什么排序规则)。 当从较低版本升级到 v7.4 或更高版本时（例如，从 v6.5 升级到 v7.5），如需保持 JDBC 连接的 `collation_connection` 为 `utf8mb4_bin`，建议在 JDBC URL 中配置 `connectionCollation` 参数。 From e2ae1508fc00f6ccfab881eebb0dcb767f8af32c Mon Sep 17 00:00:00 2001 From: Test User Date: Fri, 25 Apr 2025 11:39:52 +0800 Subject: [PATCH 04/13] Update sql-faq.md --- faq/sql-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/faq/sql-faq.md b/faq/sql-faq.md index 62a2617ac0f8..eedeb5d6e4a4 100644 --- a/faq/sql-faq.md +++ b/faq/sql-faq.md @@ -327,7 +327,7 @@ TiDB 在执行 SQL 语句时，会根据隔离级别确定一个对象的 `schem ## JDBC 连接所使用的排序规则 -本节介绍了 JDBC 连接的排序规则行为，并提供了解决 TiDB 升级后排序规则变化问题的方案。关于 TiDB 支持的字符集和排序规则，请参考[字符集和排序规则](/character-set-and-collation.md)。 +本节列出了 JDBC 连接排序规则的相关问题。关于 TiDB 支持的字符集和排序规则，请参考[字符集和排序规则](/character-set-and-collation.md)。 ### 当 JDBC URL 中未配置 `connectionCollation` 时，JDBC 连接使用什么排序规则？ From fa9713897ddbd697f63591dd34f787a503860a74 Mon Sep 17 00:00:00 2001 From: Test User Date: Fri, 25 Apr 2025 11:46:31 +0800 Subject: [PATCH 05/13] Update sql-faq.md --- faq/sql-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/faq/sql-faq.md b/faq/sql-faq.md index eedeb5d6e4a4..dec5c3a5e47d 100644 --- a/faq/sql-faq.md +++ b/faq/sql-faq.md @@ -341,7 +341,7 @@ TiDB 在执行 SQL 语句时，会根据隔离级别确定一个对象的 `schem - 当返回值小于 `8.0.1` 时，驱动程序使用 `utf8mb4_general_ci` 作为连接排序规则。TiDB 将遵循驱动程序，使用 `utf8mb4_general_ci` 作为排序规则。 - 当返回值大于等于 `8.0.1` 时，驱动程序使用 `utf8mb4_0900_ai_ci` 作为连接排序规则。v7.4.0 及更高版本的 TiDB 将遵循驱动程序，使用 `utf8mb4_0900_ai_ci` 作为排序规则，而 v7.4.0 之前版本的 TiDB 由于不支持 `utf8mb4_0900_ai_ci` 排序规则，将回退到使用默认的排序规则 `utf8mb4_bin`。 -**场景二**： JDBC URL 中配置了 `characterEncoding=utf8` 但未配置 `connectionCollation`，JDBC 驱动程序将按照映射规则使用 `utf8mb4` 字符集，并按照场景一中的描述选择排序规则。 +**场景二**：JDBC URL 中配置了 `characterEncoding=utf8` 但未配置 `connectionCollation`，JDBC 驱动程序将按照映射规则使用 `utf8mb4` 字符集，并按照场景一中的描述选择排序规则。 ### 如何解决 TiDB 升级后排序规则变化带来的问题？ From 92929388adb7ea0b32712365dc84b685e3cabfa6 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 25 Apr 2025 13:32:50 +0800 Subject: [PATCH 06/13] Update faq/sql-faq.md Co-authored-by: Aolin --- faq/sql-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/faq/sql-faq.md b/faq/sql-faq.md index dec5c3a5e47d..0911e7b98979 100644 --- a/faq/sql-faq.md +++ b/faq/sql-faq.md @@ -339,7 +339,7 @@ TiDB 在执行 SQL 语句时，会根据隔离级别确定一个对象的 `schem - 对于 Connector/J8.0.26 及之后版本，JDBC 驱动程序将使用 `utf8mb4` 字符集，并根据 `SELECT VERSION()` 的返回值自动选择排序规则。 - 当返回值小于 `8.0.1` 时，驱动程序使用 `utf8mb4_general_ci` 作为连接排序规则。TiDB 将遵循驱动程序，使用 `utf8mb4_general_ci` 作为排序规则。 - - 当返回值大于等于 `8.0.1` 时，驱动程序使用 `utf8mb4_0900_ai_ci` 作为连接排序规则。v7.4.0 及更高版本的 TiDB 将遵循驱动程序，使用 `utf8mb4_0900_ai_ci` 作为排序规则，而 v7.4.0 之前版本的 TiDB 由于不支持 `utf8mb4_0900_ai_ci` 排序规则，将回退到使用默认的排序规则 `utf8mb4_bin`。 + - 当返回值大于等于 `8.0.1` 时，驱动程序使用 `utf8mb4_0900_ai_ci` 作为连接排序规则。v7.4.0 及之后版本的 TiDB 将遵循驱动程序，使用 `utf8mb4_0900_ai_ci` 作为排序规则，而 v7.4.0 之前版本的 TiDB 由于不支持 `utf8mb4_0900_ai_ci` 排序规则，将回退到使用默认的排序规则 `utf8mb4_bin`。 **场景二**：JDBC URL 中配置了 `characterEncoding=utf8` 但未配置 `connectionCollation`，JDBC 驱动程序将按照映射规则使用 `utf8mb4` 字符集，并按照场景一中的描述选择排序规则。 From 70ff849868d02447def88c2193a1305c39437ccb Mon Sep 17 00:00:00 2001 From: Test User Date: Fri, 25 Apr 2025 13:39:02 +0800 Subject: [PATCH 07/13] Update dev-guide-sample-application-java-jdbc.md --- develop/dev-guide-sample-application-java-jdbc.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/develop/dev-guide-sample-application-java-jdbc.md b/develop/dev-guide-sample-application-java-jdbc.md index 6e43b0d65882..f0285ea7a825 100644 --- a/develop/dev-guide-sample-application-java-jdbc.md +++ b/develop/dev-guide-sample-application-java-jdbc.md @@ -16,7 +16,8 @@ TiDB 是一个兼容 MySQL 的数据库。JDBC 是 Java 的数据访问 API。[M > **注意** > -> 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> - 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 +> - 从 TiDB v7.4 起，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `utf8`，JDBC 连接所使用的排序规则取决于 JDBC 驱动版本。详情请参考[JDBC 连接所使用的排序规则](/faq/sql-faq.md#jdbc-连接所使用的排序规则)。 ## 前置需求 From 5a04f7d8284a6a1ac970b57896482e30bf15e874 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 25 Apr 2025 14:06:26 +0800 Subject: [PATCH 08/13] Apply suggestions from code review Co-authored-by: Aolin --- develop/dev-guide-sample-application-java-jdbc.md | 2 +- faq/sql-faq.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/develop/dev-guide-sample-application-java-jdbc.md b/develop/dev-guide-sample-application-java-jdbc.md index f0285ea7a825..f68f7c2cd4e6 100644 --- a/develop/dev-guide-sample-application-java-jdbc.md +++ b/develop/dev-guide-sample-application-java-jdbc.md @@ -17,7 +17,7 @@ TiDB 是一个兼容 MySQL 的数据库。JDBC 是 Java 的数据访问 API。[M > **注意** > > - 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 -> - 从 TiDB v7.4 起，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `utf8`，JDBC 连接所使用的排序规则取决于 JDBC 驱动版本。详情请参考[JDBC 连接所使用的排序规则](/faq/sql-faq.md#jdbc-连接所使用的排序规则)。 +> - 从 TiDB v7.4 起，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `utf8`，JDBC 连接所使用的排序规则取决于 JDBC 驱动版本。详情请参考 [JDBC 连接所使用的排序规则](/faq/sql-faq.md#jdbc-连接所使用的排序规则)。 ## 前置需求 diff --git a/faq/sql-faq.md b/faq/sql-faq.md index 0911e7b98979..83e427165113 100644 --- a/faq/sql-faq.md +++ b/faq/sql-faq.md @@ -357,7 +357,7 @@ TiDB 在执行 SQL 语句时，会根据隔离级别确定一个对象的 `schem spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=utf8&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultfetchsize=-2147483648&allowMultiQueries=true ``` -升级到 TiDB v7.5 或更高版本后，建议在 JDBC URL 中配置 `connectionCollation` 参数： +升级到 TiDB v7.4 或更高版本后，建议在 JDBC URL 中配置 `connectionCollation` 参数： ``` spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=utf8&connectionCollation=utf8mb4_bin&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultFetchSize=-2147483648&allowMultiQueries=true From 8d845d679eb2b4947ebc2556e3d9ae1b8972d2b2 Mon Sep 17 00:00:00 2001 From: Test User Date: Sun, 27 Apr 2025 10:14:58 +0800 Subject: [PATCH 09/13] characterEncoding: utf8 -> UTF-8 --- develop/dev-guide-sample-application-java-jdbc.md | 2 +- faq/sql-faq.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/develop/dev-guide-sample-application-java-jdbc.md b/develop/dev-guide-sample-application-java-jdbc.md index f68f7c2cd4e6..00325680cd9e 100644 --- a/develop/dev-guide-sample-application-java-jdbc.md +++ b/develop/dev-guide-sample-application-java-jdbc.md @@ -17,7 +17,7 @@ TiDB 是一个兼容 MySQL 的数据库。JDBC 是 Java 的数据访问 API。[M > **注意** > > - 本文档适用于 TiDB Cloud Serverless、TiDB Cloud Dedicated 和本地部署的 TiDB。 -> - 从 TiDB v7.4 起，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `utf8`，JDBC 连接所使用的排序规则取决于 JDBC 驱动版本。详情请参考 [JDBC 连接所使用的排序规则](/faq/sql-faq.md#jdbc-连接所使用的排序规则)。 +> - 从 TiDB v7.4 起，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `UTF-8`，JDBC 连接所使用的排序规则取决于 JDBC 驱动版本。详情请参考 [JDBC 连接所使用的排序规则](/faq/sql-faq.md#jdbc-连接所使用的排序规则)。 ## 前置需求 diff --git a/faq/sql-faq.md b/faq/sql-faq.md index 83e427165113..bd333db49a61 100644 --- a/faq/sql-faq.md +++ b/faq/sql-faq.md @@ -345,9 +345,9 @@ TiDB 在执行 SQL 语句时，会根据隔离级别确定一个对象的 `schem ### 如何解决 TiDB 升级后排序规则变化带来的问题？ -在 TiDB v7.4 及之前版本中，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `utf8`，TiDB [`collation_connection`](/system-variable-reference.md#collation_connection) 变量将默认使用 `utf8mb4_bin` 排序规则。 +在 TiDB v7.4 及之前版本中，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `UTF-8`，TiDB [`collation_connection`](/system-variable-reference.md#collation_connection) 变量将默认使用 `utf8mb4_bin` 排序规则。 -从 TiDB v7.4 开始，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `utf8`，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量值取决于 JDBC 驱动版本。例如，对于 Connector/J8.0.26 及之后版本，JDBC 驱动程序默认使用 `utf8mb4` 字符集，使用 `utf8mb4_general_ci` 作为连接排序规则，TiDB 将遵循驱动程序，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量将使用 `utf8mb4_0900_ai_ci` 排序规则。详情请参考[JDBC 连接的排序规则](#当-jdbc-url-中未配置-connectioncollation-时jdbc-连接使用什么排序规则)。 +从 TiDB v7.4 开始，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `UTF-8`，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量值取决于 JDBC 驱动版本。例如，对于 Connector/J8.0.26 及之后版本，JDBC 驱动程序默认使用 `utf8mb4` 字符集，使用 `utf8mb4_general_ci` 作为连接排序规则，TiDB 将遵循驱动程序，[`collation_connection`](/system-variable-reference.md#collation_connection) 变量将使用 `utf8mb4_0900_ai_ci` 排序规则。详情请参考[JDBC 连接的排序规则](#当-jdbc-url-中未配置-connectioncollation-时jdbc-连接使用什么排序规则)。 当从较低版本升级到 v7.4 或更高版本时（例如，从 v6.5 升级到 v7.5），如需保持 JDBC 连接的 `collation_connection` 为 `utf8mb4_bin`，建议在 JDBC URL 中配置 `connectionCollation` 参数。 From 7294af6dc1567053f2a82b423f506f12a1b4ff03 Mon Sep 17 00:00:00 2001 From: Test User Date: Sun, 27 Apr 2025 10:26:25 +0800 Subject: [PATCH 10/13] Update upgrade-faq.md --- faq/upgrade-faq.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/faq/upgrade-faq.md b/faq/upgrade-faq.md index bab9edfb403a..fc7e251770d9 100644 --- a/faq/upgrade-faq.md +++ b/faq/upgrade-faq.md @@ -36,6 +36,12 @@ aliases: ['/docs-cn/dev/faq/upgrade-faq/','/docs-cn/dev/faq/upgrade/'] 本小节列出了一些升级后可能会遇到的问题与解决办法。 +## TiDB 升级后的排序规则变化 + +当从较低版本升级到 v7.4 或更高版本时（例如，从 v6.5 升级到 v7.5），如果 JDBC URL 中未配置 `connectionCollation`，升级后 JDBC 连接的默认排序规则可能会从 `utf8mb4_bin` 更改为 `utf8mb4_0900_ai_ci`。如需保持排序规则为 `utf8mb4_bin`，请在 JDBC URL 中配置 `connectionCollation=utf8mb4_bin`。 + +更多信息，请参考 [JDBC 连接所使用的排序规则](/faq/sql-faq.md#jdbc-连接所使用的排序规则)。 + ### 执行 DDL 操作时遇到的字符集 (charset) 问题 TiDB 在 v2.1.0 以及之前版本（包括 v2.0 所有版本）中，默认字符集是 UTF8。从 v2.1.1 开始，默认字符集变更为 UTF8MB4。如果在 v2.1.0 及之前版本中，建表时显式指定了 table 的 charset 为 UTF8，那么升级到 v2.1.1 之后，执行 DDL 操作可能会失败。 From 6ed7b7835cf54042745ad9720d59c7b47fa670ca Mon Sep 17 00:00:00 2001 From: Test User Date: Sun, 27 Apr 2025 10:48:36 +0800 Subject: [PATCH 11/13] Update upgrade-faq.md --- faq/upgrade-faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/faq/upgrade-faq.md b/faq/upgrade-faq.md index fc7e251770d9..f2b889aab5dc 100644 --- a/faq/upgrade-faq.md +++ b/faq/upgrade-faq.md @@ -36,9 +36,9 @@ aliases: ['/docs-cn/dev/faq/upgrade-faq/','/docs-cn/dev/faq/upgrade/'] 本小节列出了一些升级后可能会遇到的问题与解决办法。 -## TiDB 升级后的排序规则变化 +## TiDB 升级后 JDBC 连接的排序规则变化问题 -当从较低版本升级到 v7.4 或更高版本时（例如，从 v6.5 升级到 v7.5），如果 JDBC URL 中未配置 `connectionCollation`，升级后 JDBC 连接的默认排序规则可能会从 `utf8mb4_bin` 更改为 `utf8mb4_0900_ai_ci`。如需保持排序规则为 `utf8mb4_bin`，请在 JDBC URL 中配置 `connectionCollation=utf8mb4_bin`。 +当从较低版本升级到 v7.4 或更高版本时，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `UTF-8`，升级后 JDBC 连接的默认排序规则可能会从 `utf8mb4_bin` 变更为 `utf8mb4_0900_ai_ci`。如需保持排序规则为 `utf8mb4_bin`，请在 JDBC URL 中配置 `connectionCollation=utf8mb4_bin`。 更多信息，请参考 [JDBC 连接所使用的排序规则](/faq/sql-faq.md#jdbc-连接所使用的排序规则)。 From 9fd9a687873c0bb523a8cdd49589ca67d70ce667 Mon Sep 17 00:00:00 2001 From: Test User Date: Sun, 27 Apr 2025 10:48:36 +0800 Subject: [PATCH 12/13] Update upgrade-faq.md --- faq/upgrade-faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/faq/upgrade-faq.md b/faq/upgrade-faq.md index fc7e251770d9..a0394af4f3a3 100644 --- a/faq/upgrade-faq.md +++ b/faq/upgrade-faq.md @@ -36,9 +36,9 @@ aliases: ['/docs-cn/dev/faq/upgrade-faq/','/docs-cn/dev/faq/upgrade/'] 本小节列出了一些升级后可能会遇到的问题与解决办法。 -## TiDB 升级后的排序规则变化 +### TiDB 升级后 JDBC 连接的排序规则变化问题 -当从较低版本升级到 v7.4 或更高版本时（例如，从 v6.5 升级到 v7.5），如果 JDBC URL 中未配置 `connectionCollation`，升级后 JDBC 连接的默认排序规则可能会从 `utf8mb4_bin` 更改为 `utf8mb4_0900_ai_ci`。如需保持排序规则为 `utf8mb4_bin`，请在 JDBC URL 中配置 `connectionCollation=utf8mb4_bin`。 +当从较低版本升级到 v7.4 或更高版本时，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `UTF-8`，升级后 JDBC 连接的默认排序规则可能会从 `utf8mb4_bin` 变更为 `utf8mb4_0900_ai_ci`。如需保持排序规则为 `utf8mb4_bin`，请在 JDBC URL 中配置 `connectionCollation=utf8mb4_bin`。 更多信息，请参考 [JDBC 连接所使用的排序规则](/faq/sql-faq.md#jdbc-连接所使用的排序规则)。 From ebce143f3d3b1c4efd06cc01eda10a976010d780 Mon Sep 17 00:00:00 2001 From: Test User Date: Sun, 27 Apr 2025 14:43:39 +0800 Subject: [PATCH 13/13] Update sql-faq.md --- faq/sql-faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/faq/sql-faq.md b/faq/sql-faq.md index bd333db49a61..e4e532e0ff86 100644 --- a/faq/sql-faq.md +++ b/faq/sql-faq.md @@ -354,13 +354,13 @@ TiDB 在执行 SQL 语句时，会根据隔离级别确定一个对象的 `schem 以下为 TiDB v6.5 中常见的 JDBC URL 配置： ``` -spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=utf8&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultfetchsize=-2147483648&allowMultiQueries=true +spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=UTF-8&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultfetchsize=-2147483648&allowMultiQueries=true ``` 升级到 TiDB v7.4 或更高版本后，建议在 JDBC URL 中配置 `connectionCollation` 参数： ``` -spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=utf8&connectionCollation=utf8mb4_bin&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultFetchSize=-2147483648&allowMultiQueries=true +spring.datasource.url=JDBC:mysql://{TiDBIP}:{TiDBPort}/{DBName}?characterEncoding=UTF-8&connectionCollation=utf8mb4_bin&useSSL=false&useServerPrepStmts=true&cachePrepStmts=true&prepStmtCacheSqlLimit=10000&prepStmtCacheSize=1000&useConfigs=maxPerformance&rewriteBatchedStatements=true&defaultFetchSize=-2147483648&allowMultiQueries=true ``` ### `utf8mb4_bin` 与 `utf8mb4_0900_ai_ci` 排序规则有何区别？