pingcap · hfxsd · Mar 12, 2025 · Mar 18, 2025 · Mar 18, 2025 · Mar 18, 2025
diff --git a/TOC.md b/TOC.md
@@ -424,6 +424,7 @@
     - [在三数据中心下就近读取数据](/best-practices/three-dc-local-read.md)
     - [使用 UUID](/best-practices/uuid.md)
     - [只读存储节点最佳实践](/best-practices/readonly-nodes.md)
+    - [SaaS 多租户场景最佳实践](/best-practices/saas-best-practices.md)
   - [Placement Rules 使用文档](/configure-placement-rules.md)
   - [Load Base Split 使用文档](/configure-load-base-split.md)
   - [Store Limit 使用文档](/configure-store-limit.md)

diff --git a/best-practices/saas-best-practices.md b/best-practices/saas-best-practices.md
@@ -0,0 +1,97 @@
+---
+title: SaaS 多租户场景最佳实践
+summary: 介绍 TiDB 在 SaaS (Software as a service) 多租户场景的最佳实践，特别适用于单集群表数量超过百万级别的场景。
+---
+
+# SaaS 多租户场景最佳实践
+
+本文档介绍 TiDB 在 SaaS (Software as a service) 多租户环境中的最佳实践，特别适用于**单集群表数量超过百万级别**的场景。通过合理的配置和选择，可以实现 TiDB 在 SaaS 场景下的高效稳定运行，同时降低资源消耗和成本。
+
+> **注意：**
+> 
+> 推荐使用 TiDB v8.5.0 及以上版本。
+
+## 硬件配置建议
+
+建议使用高内存规格的 TiDB 实例，例如：
+
+- 100 万张表：使用 32 GiB 或更高内存。
+- 300 万张表：使用 64 GiB 或更高内存。
+
+高内存规格的 TiDB 实例可以为 Infoschema、Statistics 和执行计划缓存分配更多的缓存空间，提高缓存命中率，从而提升业务性能。同时，更大的内存可以缓解 TiDB GC 带来的性能波动和稳定性问题。
+
+TiKV 和 PD 推荐的硬件配置如下：
+
+* **TiKV**：8 vCPU 和 32 GiB 或更高内存。
+* **PD**：8 CPU 和 16 GiB 或更高内存。
+
+## 控制 Region 数量
+
+如果需要创建大量的表（例如 10 万张以上），建议将 TiDB 的配置 [`split-table`](/tidb-configuration-file.md#split-table) 设置为 `false`，减少集群 Region 数量，从而降低 TiKV 内存压力。
+
+## 缓存配置
+
+* 从 TiDB v8.4.0 开始，TiDB 在执行 SQL 语句时，会按需将 SQL 语句涉及的表信息加载到 Infoschema 缓存中。
+
+    * 通过 TiDB 监控中 **Schema Load** 面板下的 **Infoschema v2 Cache Size** 和 **Infoschema v2 Cache Operation** 子面板，可以查看 Infoschema 缓存的大小和命中率。
+    * 使用系统变量 [`tidb_schema_cache_size`](/system-variables.md#tidb_schema_cache_size-从-v800-版本开始引入) 可以调整 Infoschema 缓存的内存上限，以满足业务需求。Infoschema 缓存大小与执行 SQL 语句涉及的不同表数量呈线性关系。在实际测试中，全量缓存 100 万张表（每张表含 4 列、1 个主键和 1 个索引）的元数据大约需要 2.4 GiB 内存。
+
+* TiDB 在执行 SQL 语句时，也会按需将相关表的统计信息加载到 Statistics 缓存中。
+
+    * 通过 TiDB 监控中 **Statistics & Plan Management** 面板下的 **Stats Cache Cost** 和 **Stats Cache OPS** 子面板，可以查看 Statistics 缓存的使用情况。
+    * 使用系统变量 [`tidb_stats_cache_mem_quota`](/system-variables.md#tidb_stats_cache_mem_quota-从-v610-版本开始引入) 可以调整 Statistics 缓存的内存上限，以满足业务需求。在实际测试中，执行 10 万张表的简单 SQL（使用 IndexRangeScan 操作符）时，Statistics 缓存大约消耗 3.96 GiB 内存。
+
+## 统计信息收集
+
+* 从 TiDB v8.4.0 开始，TiDB 引入了 [`tidb_auto_analyze_concurrency`](/system-variables.md#tidb_auto_analyze_concurrency-从-v840-版本开始引入) 系统变量，用来设置 TiDB 集群中自动更新统计信息操作的并发度。多表场景下，适当提升并发度可提高自动分析吞吐量。随着并发值的增加，自动分析的吞吐量和 TiDB Owner 节点的 CPU 使用率会线性增加。在实际测试中，使用并发度 16 时，每分钟可自动分析 320 张表（每张表有 1 万行数据、4 列和 1 个索引），占用 TiDB Owner 节点一个 CPU 核心。
+* [`tidb_auto_build_stats_concurrency`](/system-variables.md#tidb_auto_build_stats_concurrency-从-v650-版本开始引入) 和 [`tidb_build_sampling_stats_concurrency`](/system-variables.md#tidb_build_sampling_stats_concurrency-从-v750-版本开始引入) 影响 TiDB 统计信息构建的并发度，需根据具体场景调整：
+    - 分区表较多时，优先提高 `tidb_auto_build_stats_concurrency` 的值。
+    - 列数较多时，优先提高 `tidb_build_sampling_stats_concurrency` 的值。
+* 建议确保 `tidb_auto_analyze_concurrency`、`tidb_auto_build_stats_concurrency` 和 `tidb_build_sampling_stats_concurrency` 三个变量的值的乘积不超过 TiDB CPU 核心数，避免过度占用资源。
+
+## 系统表查询
+
+在查询系统表时，建议添加 `TABLE_SCHEMA` 和 `TABLE_NAME` 或 `TIDB_TABLE_ID` 等过滤条件，以避免扫描大量无关数据，从而提高查询速度并降低资源消耗。
+
+例如，在 300 万表的场景下：
+
+- 执行以下 SQL 语句要消耗约 8 GiB 内存：
+
+    ```sql
+    SELECT COUNT(*) FROM information_schema.tables;
+    ```
+
+- 执行以下 SQL 语句需要约 20 分钟：
+
+    ```sql
+    SELECT COUNT(*) FROM information_schema.views;
+    ```
+
+在以上示例中的两个 SQL 语句加上建议的查询条件之后，内存消耗可以忽略不计，查询耗时降至毫秒级别。
+
+## 大量连接场景
+
+在 SaaS 多租户场景中，通常每个用户连接到 TiDB 操作各自租户 (database) 的数据。为支持更多连接数，建议：
+
+* 调高 TiDB 的配置项 [`token-limit`](/tidb-configuration-file.md#token-limit)（默认值为 `1000`）以支持更多并发请求。
+* TiDB 内存使用量与连接数基本上呈线性关系。在实际测试中，20 万个空闲连接将使 TiDB 进程增加约 30 GiB 内存。建议根据实际连接数调整 TiDB 内存规格。
+* 使用 `PREPARED` 语句时，每个连接都会维护一个会话级的 Prepared Plan Cache。如果长时间未执行 `DEALLOCATE` 预编译语句，可能导致缓存中的计划数量过多，增加内存消耗。在实际测试中，40 万条涉及 IndexRangeScan 的执行计划占用约 5 GiB 内存。建议相应提高内存规格。
+
+## Stale Read
+
+使用 [Stale Read](/stale-read.md) 时，如果使用的 schema 版本过于陈旧，可能触发历史 schema 全量加载，影响性能。建议通过提高 [`tidb_schema_version_cache_limit`](/system-variables.md#tidb_schema_version_cache_limit-从-v740-版本开始引入) 的值（例如 `255`）来缓解此问题。
+
+## BR 备份恢复
+
+* 在全量恢复百万张表的场景中，建议使用高内存 BR 实例。例如：
+    - 100 万张表：使用 32 GiB 或更高内存的 BR 实例
+    - 300 万张表：使用 64 GiB 或更高内存的 BR 实例
+* BR 日志备份和快照恢复会额外消耗 TiKV 内存，建议 TiKV 使用 32 GiB 或更高规格的内存。
+* 可根据业务需求，适当增加 BR 的 [`pitr-batch-count` 和 `pitr-concurrency`](/br/use-br-command-line-tool.md#常用选项) 配置以提升 BR 日志恢复速度。
+
+## TiDB Lightning 数据导入
+
+在使用 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 导入百万张表数据时，建议：
+
+- 对大表（超过 100 GiB）使用 TiDB Lightning [物理导入模式](/tidb-lightning/tidb-lightning-physical-import-mode.md)。
+- 对小表（通常数量较多）使用 TiDB Lightning [逻辑导入模式](/tidb-lightning/tidb-lightning-logical-import-mode.md)。
diff --git a/character-set-and-collation.md b/character-set-and-collation.md
@@ -104,7 +104,7 @@ SHOW CHARACTER SET;
 +---------+-------------------------------------+-------------------+--------+
 | ascii   | US ASCII                            | ascii_bin         |      1 |
 | binary  | binary                              | binary            |      1 |
-| gbk     | Chinese Internal Code Specification | gbk_bin           |      2 |
+| gbk     | Chinese Internal Code Specification | gbk_chinese_ci    |      2 |
 | latin1  | Latin1                              | latin1_bin        |      1 |
 | utf8    | UTF-8 Unicode                       | utf8_bin          |      3 |
 | utf8mb4 | UTF-8 Unicode                       | utf8mb4_bin       |      4 |

diff --git a/character-set-gbk.md b/character-set-gbk.md
@@ -7,6 +7,8 @@ summary: 本文介绍 TiDB 对 GBK 字符集的支持情况。
 
 TiDB 从 v5.4.0 开始支持 GBK 字符集。本文档介绍 TiDB 对 GBK 字符集的支持和兼容情况。
 
+从 TiDB v6.0.0 开始，[新的排序规则框架](/character-set-and-collation.md#新框架下的排序规则支持)默认启用，即 TiDB GBK 字符集的默认排序规则为 `gbk_chinese_ci`，与 MySQL 保持一致。
+
 ```sql
 SHOW CHARACTER SET WHERE CHARSET = 'gbk';
 ```
@@ -15,7 +17,7 @@ SHOW CHARACTER SET WHERE CHARSET = 'gbk';
 +---------+-------------------------------------+-------------------+--------+
 | Charset | Description                         | Default collation | Maxlen |
 +---------+-------------------------------------+-------------------+--------+
-| gbk     | Chinese Internal Code Specification | gbk_bin           |      2 |
+| gbk     | Chinese Internal Code Specification | gbk_chinese_ci    |      2 |
 +---------+-------------------------------------+-------------------+--------+
 1 row in set (0.00 sec)
 ```
@@ -40,38 +42,12 @@ SHOW COLLATION WHERE CHARSET = 'gbk';
 
 ### 排序规则兼容性
 
-MySQL 的字符集默认排序规则是 `gbk_chinese_ci`。与 MySQL 不同，TiDB GBK 字符集的默认排序规则为 `gbk_bin`。另外，TiDB 支持的 `gbk_bin` 与 MySQL 支持的 `gbk_bin` 排序规则也不一致，TiDB 是将 GBK 转换成 `utf8mb4`，然后再进行二进制排序。
-
-如果要使 TiDB 兼容 MySQL 的 GBK 字符集排序规则，你需要在初次初始化 TiDB 集群时设置 TiDB 配置项 [`new_collations_enabled_on_first_bootstrap`](/tidb-configuration-file.md#new_collations_enabled_on_first_bootstrap) 为 `true` 来开启[新的排序规则框架](/character-set-and-collation.md#新框架下的排序规则支持)。对于新部署的系统，该设置是默认值。
-
-开启新的排序规则框架后，如果查看 GBK 字符集对应的排序规则，你可以看到 TiDB GBK 默认排序规则已经切换为 `gbk_chinese_ci`。
+MySQL 的 GBK 字符集默认排序规则是 `gbk_chinese_ci`。TiDB 的 GBK 字符集的默认排序规则取决于 TiDB 配置项 [`new_collations_enabled_on_first_bootstrap`](/tidb-configuration-file.md#new_collations_enabled_on_first_bootstrap) 的值：
 
-```sql
-SHOW CHARACTER SET WHERE CHARSET = 'gbk';
-```
+- 默认情况下，TiDB 配置项 [`new_collations_enabled_on_first_bootstrap`](/tidb-configuration-file.md#new_collations_enabled_on_first_bootstrap) 为 `true`，表示开启[新的排序规则框架](/character-set-and-collation.md#新框架下的排序规则支持)。GBK 字符集的默认排序规则是 `gbk_chinese_ci`。
+- 当 TiDB 配置项 [`new_collations_enabled_on_first_bootstrap`](/tidb-configuration-file.md#new_collations_enabled_on_first_bootstrap) 为 `false` 时，表示关闭新的排序规则框架，GBK 字符集的默认排序规则是 `gbk_bin`。
 
-```
-+---------+-------------------------------------+-------------------+--------+
-| Charset | Description                         | Default collation | Maxlen |
-+---------+-------------------------------------+-------------------+--------+
-| gbk     | Chinese Internal Code Specification | gbk_chinese_ci    |      2 |
-+---------+-------------------------------------+-------------------+--------+
-1 row in set (0.00 sec)
-```
-
-```sql
-SHOW COLLATION WHERE CHARSET = 'gbk';
-```
-
-```
-+----------------+---------+----+---------+----------+---------+---------------+
-| Collation      | Charset | Id | Default | Compiled | Sortlen | Pad_attribute |
-+----------------+---------+----+---------+----------+---------+---------------+
-| gbk_bin        | gbk     | 87 |         | Yes      |       1 | PAD SPACE     |
-| gbk_chinese_ci | gbk     | 28 | Yes     | Yes      |       1 | PAD SPACE     |
-+----------------+---------+----+---------+----------+---------+---------------+
-2 rows in set (0.00 sec)
-```
+另外，TiDB 支持的 `gbk_bin` 与 MySQL 支持的 `gbk_bin` 排序规则不一致，TiDB 是将 GBK 转换成 `utf8mb4`，然后再进行二进制排序。
 
 ### 非法字符兼容性
 

diff --git a/develop/dev-guide-optimize-sql.md b/develop/dev-guide-optimize-sql.md
@@ -108,7 +108,7 @@ EXPLAIN SELECT * FROM books WHERE title = 'Marian Yost';
 
 从执行计划中的 **IndexLookUp_10** 可以看出，TiDB 将会通过索引 `title_idx` 来查询数据，其 `estRows` 值为 `1.27`，说明优化器估计只会扫描 `1.27` 行数据，远远小于之前全表扫的 `1000000.00` 行数据。
 
-**IndexLookUp_10** 执行计划的执行流程是先用 **IndexRangeScan_8** 算子通过 `title_idx` 索引获取符合条件的索引数据，然后 **TableRowIDScan_9** 再更据索引数据里面的 Row ID 回表查询相应的行数据。
+**IndexLookUp_10** 执行计划的执行流程是先用 **IndexRangeScan_8** 算子通过 `title_idx` 索引获取符合条件的索引数据，然后 **TableRowIDScan_9** 再根据索引数据里面的 Row ID 回表查询相应的行数据。
 
 更多关于 TiDB 执行计划的内容，可以阅读[TiDB 执行计划概览](/explain-overview.md)。
 

diff --git 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` 未配置或配置为 `UTF-8`，JDBC 连接所使用的排序规则取决于 JDBC 驱动版本。详情请参考 [JDBC 连接所使用的排序规则](/faq/sql-faq.md#jdbc-连接所使用的排序规则)。
 
 ## 前置需求
 

diff --git 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 支持的字符集和排序规则，请参考[字符集和排序规则](/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` 未配置或配置为 `UTF-8`，TiDB [`collation_connection`](/system-variables.md#collation_connection) 变量将默认使用 `utf8mb4_bin` 排序规则。
+
+从 TiDB v7.4 开始，如果 JDBC URL 中未配置 `connectionCollation`，且 `characterEncoding` 未配置或配置为 `UTF-8`，[`collation_connection`](/system-variables.md#collation_connection) 变量值取决于 JDBC 驱动版本。例如，对于 Connector/J8.0.26 及之后版本，JDBC 驱动程序默认使用 `utf8mb4` 字符集，使用 `utf8mb4_general_ci` 作为连接排序规则，TiDB 将遵循驱动程序，[`collation_connection`](/system-variables.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=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=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` 排序规则有何区别？
+
+| 排序规则             | 是否区分大小写 | 是否忽略末尾空格 | 是否区分重音 | 比较方式               |
+|----------------------|----------------|------------------|--------------|------------------------|
+| `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)。