diff --git a/TOC.md b/TOC.md index 0f4e27c25b0e..c61edf08591e 100644 --- a/TOC.md +++ b/TOC.md @@ -633,6 +633,7 @@ - 权限 - [与 MySQL 安全特性差异](/security-compatibility-with-mysql.md) - [权限管理](/privilege-management.md) + - [列级权限管理](/column-privilege-management.md) - [TiDB 用户账户管理](/user-account-management.md) - [TiDB 密码管理](/password-management.md) - [基于角色的访问控制](/role-based-access-control.md) diff --git a/basic-features.md b/basic-features.md index 0ad6e4319678..1019ac08d31b 100644 --- a/basic-features.md +++ b/basic-features.md @@ -258,7 +258,7 @@ summary: 了解 TiDB 的功能概览。 | [Green GC](/system-variables.md#tidb_gc_scan_lock_mode-从-v50-版本开始引入) | E | E | E | E | E | E | E | | [资源管控 (Resource Control)](/tidb-resource-control-ru-groups.md) | Y | Y | Y | Y | N | N | N | | [Runaway Queries 自动管理](/tidb-resource-control-runaway-queries.md) | Y | Y | E | N | N | N | N | -| [后台任务资源管控](/tidb-resource-control-background-tasks.md) | E | E | E | N | N | N | N | +| [后台任务资源管控](/tidb-resource-control-background-tasks.md) | Y | E | E | N | N | N | N | | [TiFlash 存算分离架构与 S3 支持](/tiflash/tiflash-disaggregated-and-s3.md) | Y | Y | Y | E | N | N | N | | [选择执行分布式执行框架任务的 TiDB 节点](/system-variables.md#tidb_service_scope-从-v740-版本开始引入) | Y | Y | Y | N | N | N | N | | 通过系统变量 [`tidb_enable_tso_follower_proxy`](/system-variables.md#tidb_enable_tso_follower_proxy-从-v530-版本开始引入) 控制 PD Follower Proxy 功能 | Y | Y | Y | Y | Y | Y | Y | diff --git a/column-privilege-management.md b/column-privilege-management.md new file mode 100644 index 000000000000..fc963899bb2f --- /dev/null +++ b/column-privilege-management.md @@ -0,0 +1,172 @@ +--- +title: 列级权限管理 +summary: TiDB 支持兼容 MySQL 的列级权限管理机制。你可以通过 `GRANT` 或 `REVOKE` 在指定表上对指定列授予或回收 `SELECT`、`INSERT`、`UPDATE`、`REFERENCES` 权限，实现更细粒度的访问控制。 +--- + +# 列级权限管理 + +从 v8.5.6 版本开始，TiDB 支持兼容 MySQL 的列级权限管理机制。通过列级权限，你可以在指定表上对指定列授予或回收 `SELECT`、`INSERT`、`UPDATE`、`REFERENCES` 权限，从而实现更细粒度的数据访问控制。 + +> **注意：** +> +> 虽然 MySQL 语法允许 `REFERENCES(col_name)` 这种列级写法，但 `REFERENCES` 本身属于数据库/表级权限，用于外键相关的权限检查。因此，列级 `REFERENCES` 在 MySQL 中不会带来实际的列级权限效果。TiDB 的行为与 MySQL 保持一致。 + +## 语法 + +列级权限的授予和回收语法与表级权限类似，区别如下： + +- 列名列表写在**权限类型**后面，而不是写在**表名**后面。 +- 多个列名之间使用逗号（`,`）分隔。 + +```sql +GRANT priv_type(col_name [, col_name] ...) [, priv_type(col_name [, col_name] ...)] ... + ON db_name.tbl_name + TO 'user'@'host'; + +REVOKE priv_type(col_name [, col_name] ...) [, priv_type(col_name [, col_name] ...)] ... + ON db_name.tbl_name + FROM 'user'@'host'; +``` + +其中： + +* `priv_type` 支持 `SELECT`、`INSERT`、`UPDATE` 和 `REFERENCES`。 +* `ON` 后必须指定具体表，例如 `test.tbl`。 +* 同一条 `GRANT` 或 `REVOKE` 语句可以包含多个权限项，每个权限项都可以指定自己的列名列表。 + +例如，以下语句表示将 `col1`、`col2` 的 `SELECT` 权限和 `col3` 的 `UPDATE` 权限授予用户： + +```sql +GRANT SELECT(col1, col2), UPDATE(col3) ON test.tbl TO 'user'@'host'; +``` + +## 授予列级权限示例 + +以下示例将表 `test.tbl` 中 `col1` 和 `col2` 的 `SELECT` 权限授予用户 `newuser`，并将 `col3` 的 `UPDATE` 权限授予该用户： + +```sql +CREATE DATABASE IF NOT EXISTS test; +USE test; + +DROP TABLE IF EXISTS tbl; +CREATE TABLE tbl (col1 INT, col2 INT, col3 INT); + +DROP USER IF EXISTS 'newuser'@'%'; +CREATE USER 'newuser'@'%'; + +GRANT SELECT(col1, col2), UPDATE(col3) ON test.tbl TO 'newuser'@'%'; +SHOW GRANTS FOR 'newuser'@'%'; +``` + +``` ++---------------------------------------------------------------------+ +| Grants for newuser@% | ++---------------------------------------------------------------------+ +| GRANT USAGE ON *.* TO 'newuser'@'%' | +| GRANT SELECT(col1, col2), UPDATE(col3) ON test.tbl TO 'newuser'@'%' | ++---------------------------------------------------------------------+ +``` + +除了使用 `SHOW GRANTS`，你还可以通过查询 `INFORMATION_SCHEMA.COLUMN_PRIVILEGES` 查看列级权限信息。 + +## 回收列级权限示例 + +以下示例从用户 `newuser` 收回列 `col2` 的 `SELECT` 权限： + +```sql +REVOKE SELECT(col2) ON test.tbl FROM 'newuser'@'%'; +SHOW GRANTS FOR 'newuser'@'%'; +``` + +``` ++---------------------------------------------------------------+ +| Grants for newuser@% | ++---------------------------------------------------------------+ +| GRANT USAGE ON *.* TO 'newuser'@'%' | +| GRANT SELECT(col1), UPDATE(col3) ON test.tbl TO 'newuser'@'%' | ++---------------------------------------------------------------+ +``` + +## 列级权限访问控制示例 + +在授予或回收列级权限后，TiDB 会对 SQL 中引用的列进行权限检查。例如： + +* `SELECT` 语句：`SELECT` 列权限会影响 `SELECT` 列表以及 `WHERE`、`ORDER BY` 等子句中引用的列。 +* `UPDATE` 语句：`SET` 子句中被更新的列需要 `UPDATE` 列权限。在表达式、条件中被读取的列通常还需要 `SELECT` 列权限。 +* `INSERT` 语句：被写入的列需要 `INSERT` 列权限。`INSERT INTO t VALUES (...)` 等价于按表定义顺序向所有列写入值。 + +以下示例中，用户 `newuser` 仅能查询 `col1`，并更新 `col3`： + +```sql +-- 以 newuser 登录执行 +SELECT col1 FROM tbl; +SELECT * FROM tbl; -- 报错（缺少 col2、col3 的 SELECT 列权限） + +UPDATE tbl SET col3 = 1; +UPDATE tbl SET col1 = 2; -- 报错（缺少 col1 的 UPDATE 列权限） + +UPDATE tbl SET col3 = col1; +UPDATE tbl SET col3 = col3 + 1; -- 报错（缺少 col3 的 SELECT 列权限） +UPDATE tbl SET col3 = col1 WHERE col1 > 0; +``` + +## 与 MySQL 的兼容性差异 + +TiDB 的列级权限整体与 MySQL 兼容，但在以下场景存在差异： + +| 场景 | TiDB | MySQL | +| :----------------------- | :-------------------------- | :---------------------------- | +| 收回用户未被授予的列级权限 | `REVOKE` 可以成功执行 | 在未使用 `IF EXISTS` 时，`REVOKE` 会报错 | +| 列裁剪与 `SELECT` 列权限检查的执行顺序 | 先检查 `SELECT` 列权限，再进行列裁剪。例如，执行 `SELECT a FROM (SELECT a, b FROM t) s` 需要同时拥有 `t.a` 和 `t.b` 的 `SELECT` 列权限。 | 先进行列裁剪，再检查 `SELECT` 列权限。例如，执行 `SELECT a FROM (SELECT a, b FROM t) s` 只需要 `t.a` 的 `SELECT` 列权限。 | + +### 视图场景的列裁剪与权限检查 + +在对视图进行 `SELECT` 权限检查时，MySQL 和 TiDB 存在以下差异： + +- MySQL 会先对视图内部查询做列裁剪，再检查内部表的列权限，因此在某些场景下检查相对宽松。 +- TiDB 不会在权限检查之前做列裁剪，因此可能需要额外的列权限。 + +```sql +-- 以 root 登录准备环境 +DROP USER IF EXISTS 'u'@'%'; +CREATE USER 'u'@'%'; + +DROP TABLE IF EXISTS t; +CREATE TABLE t (a INT, b INT, c INT, d INT); + +DROP VIEW IF EXISTS v; +CREATE SQL SECURITY INVOKER VIEW v AS SELECT a, b FROM t WHERE c = 0 ORDER BY d; + +GRANT SELECT ON v TO 'u'@'%'; + +-- 以 u 登录 +SELECT a FROM v; +-- MySQL：报错，缺少对 t.a、t.c、t.d 的访问权限 +-- TiDB：报错，缺少对 t.a、t.b、t.c、t.d 的访问权限 + +-- 以 root 登录 +GRANT SELECT(a, c, d) ON t TO 'u'@'%'; + +-- 以 u 登录 +SELECT a FROM v; +-- MySQL：成功（会将内部查询裁剪为 `SELECT a FROM t WHERE c = 0 ORDER BY d`） +-- TiDB：报错，缺少对 t.b 的访问权限 + +SELECT * FROM v; +-- MySQL：报错，缺少对 t.b 的访问权限 +-- TiDB：报错，缺少对 t.b 的访问权限 + +-- 以 root 登录 +GRANT SELECT(b) ON t TO 'u'@'%'; + +-- 以 u 登录 +SELECT * FROM v; +-- MySQL：成功 +-- TiDB：成功 +``` + +## 另请参阅 + +* [权限管理](/privilege-management.md) +* [`GRANT `](/sql-statements/sql-statement-grant-privileges.md) +* [`REVOKE `](/sql-statements/sql-statement-revoke-privileges.md) diff --git a/dashboard/dashboard-slow-query.md b/dashboard/dashboard-slow-query.md index 60a155b7e7f3..fecaf9d48fde 100644 --- a/dashboard/dashboard-slow-query.md +++ b/dashboard/dashboard-slow-query.md @@ -61,7 +61,8 @@ summary: 了解如何在 TiDB Dashboard 中查看慢查询。 >**注意：** > -> 记录在 `Query` 中的查询的长度会受到 [`tidb_stmt_summary_max_sql_length`](/system-variables.md#tidb_stmt_summary_max_sql_length-从-v40-版本开始引入) 系统变量的限制。 +> - 记录在 `Query` 中的查询的长度会受到 [`tidb_stmt_summary_max_sql_length`](/system-variables.md#tidb_stmt_summary_max_sql_length-从-v40-版本开始引入) 系统变量的限制。 +> - 对于预处理语句，参数会在查询末尾列出，例如：`[arguments: "foo", 123]`。不可打印的参数会以十六进制字面量显示，例如 `0x01`。 点击**展开** (**Expand**) 可以展开相应项的完整内容，点击**复制** (**Copy**) 可以复制内容到剪贴板。 diff --git a/dashboard/top-sql.md b/dashboard/top-sql.md index 50118d6cfbe2..1307ebdc476e 100644 --- a/dashboard/top-sql.md +++ b/dashboard/top-sql.md @@ -1,32 +1,37 @@ --- title: TiDB Dashboard Top SQL 页面 -summary: 使用 Top SQL 找到 CPU 开销较大的 SQL 语句 +summary: 使用 Top SQL 找到消耗 CPU、网络和逻辑 I/O 资源较多的查询。 --- # TiDB Dashboard Top SQL 页面 -TiDB Dashboard 的 Top SQL 功能允许你可视化地监控和探索数据库中各个 SQL 语句在执行过程中的 CPU 开销情况，从而对数据库性能问题进行优化和处理。Top SQL 持续收集各个 TiDB 及 TiKV 实例每秒的实时 CPU 负载等数据（按 SQL 类型分别统计），并存储至多 30 天。你可以通过 Top SQL 展示的图表及表格快速分析某个 TiDB 或 TiKV 实例在某段时间中高 CPU 负载是来自于哪些 SQL 语句。 +在 TiDB Dashboard 的 Top SQL 页面，你可以查看和分析指定的 TiDB 或 TiKV 节点在一段时间内资源消耗最高的 SQL 查询。 + +- 开启 Top SQL 后，该功能会持续采集现有 TiDB 和 TiKV 节点的 CPU 负载数据，并最多保留 30 天。 +- 从 v8.5.6 起，你还可以在 Top SQL 设置中开启 **TiKV 网络 IO 采集（多维度）**，以进一步查看指定 TiKV 节点的 `Network Bytes`、`Logical IO Bytes` 等指标，并按 `By Query`、`By Table`、`By DB` 或 `By Region` 维度进行聚合分析。 Top SQL 具有以下功能： -* 通过图表及表格，可视化地展示 CPU 开销最多的 5 类 SQL 语句。 -* 展示每秒请求数、平均延迟、查询计划等详细执行信息。 +* 支持通过图表和表格展示当前时间范围内资源消耗最高的 Top `5`、`20` 或 `100` 类 SQL 查询，其余记录自动汇总为 `Others`。 +* 支持按 CPU 耗时、网络字节数排序查看资源消耗热点；选择 TiKV 节点时，还支持按逻辑 I/O 字节数排序。 +* 支持按 Query 查看 SQL 及其执行计划详情；选择 TiKV 节点时，还支持按 `By Table`、`By DB` 和 `By Region` 进行聚合分析。 +* 支持框选图表缩放时间范围、手动刷新、自动刷新以及导出 CSV。 * 支持统计所有正在执行、尚未执行完毕的 SQL 语句。 -* 支持查看集群中指定 TiDB 及 TiKV 实例的情况。 +* 支持查看集群中指定 TiDB 及 TiKV 节点的情况。 ## 推荐适用场景 Top SQL 适用于分析性能问题。以下列举了一些典型的 Top SQL 适用场景： -* 通过监控图发现集群中有个别 TiKV 实例的 CPU 非常高，期望了解 CPU 热点来自于哪些 SQL 语句，以便对其进行优化、更好地利用上分布式资源。 -* 集群整体 CPU 占用率非常高、数据库查询缓慢，期望快速知悉目前哪些 SQL 语句开销了最多的 CPU 资源，以便对它们进行优化。 -* 集群整体 CPU 占用率突然发生了显著变化，期望了解变化前后主要的 SQL 资源开销区别。 -* 分析集群当前最消耗资源的 SQL 语句情况，希望对它们进行优化以便降低硬件开支。 +* 通过监控发现个别 TiDB 或 TiKV 节点 CPU 负载很高，希望快速定位是哪类 SQL 正在消耗大量 CPU 资源。 +* 集群整体查询变慢，希望找出当前最消耗资源的 SQL，或者对比负载变化前后最主要的查询差异。 +* 需要从更高维度定位热点，希望按 `Table`、`DB` 或 `Region` 聚合查看 TiKV 侧的资源消耗。 +* 需要从网络流量或逻辑 I/O 角度排查 TiKV 热点，而不仅仅局限于 CPU 维度。 Top SQL 不适用于分析以下问题： - 不能用于解答与性能无关的问题，例如数据正确性或异常崩溃问题。 -- 暂不支持分析并非由于 CPU 负载高导致的数据库性能问题，例如锁冲突。 +- 不适合直接分析锁冲突、事务语义错误等并非由资源消耗导致的问题。 ## 访问页面 @@ -34,9 +39,9 @@ Top SQL 不适用于分析以下问题： - 登录 TiDB Dashboard 后，在左侧导航栏中点击**Top SQL**。 - ![Top SQL](/media/dashboard/top-sql-access.png) + ![Top SQL](/media/dashboard/v8.5-top-sql-access.png) -- 在浏览器中访问 （将 `127.0.0.1:2379` 替换为实际 PD 实例地址和端口）。 +- 在浏览器中访问 （将 `127.0.0.1:2379` 替换为实际 PD 节点地址和端口）。 ## 启用 Top SQL @@ -47,10 +52,10 @@ Top SQL 不适用于分析以下问题： Top SQL 开启后会对集群性能产生轻微的影响（平均 3% 以内），因此该功能默认关闭。你可以通过以下方法启用 Top SQL： 1. 访问 [Top SQL 页面](#访问页面)。 -2. 点击**打开设置** (Open Settings)。在右侧**设置** (Settings) 页面，将**启用特性** (Enable Feature) 下方的开关打开。 +2. 点击**打开设置** (Open Settings)。在右侧**设置** (Settings) 页面，将**启用功能** (Enable Feature) 下方的开关打开。 3. 点击**保存** (Save)。 -你仅能看到开启功能之后的 CPU 负载细节情况，在开启功能之前的 CPU 负载细节无法在界面上呈现。另外，数据有至多 1 分钟左右的延迟，因此你可能需要等待片刻才能看到数据。 +启用 Top SQL 后，你只能查看开启之后新采集到的数据；开启之前的历史数据不会补采。数据展示通常会有约 1 分钟的延迟，因此需要等待片刻才能看到新数据。关闭 Top SQL 后，如果历史数据尚未过期，Top SQL 页面仍然会展示这些历史数据，但不会再采集和展示新的数据。 除了通过图形化界面以外，你也可以配置 TiDB 系统变量 [`tidb_enable_top_sql`](/system-variables.md#tidb_enable_top_sql-从-v540-版本开始引入) 来启用 Top SQL 功能： @@ -60,57 +65,104 @@ Top SQL 开启后会对集群性能产生轻微的影响（平均 3% 以内） SET GLOBAL tidb_enable_top_sql = 1; ``` +### 开启 TiKV 网络 IO 采集（可选）从 v8.5.6 开始引入 + +针对 TiKV 节点，如需按照 `Order By Network`、`Order By Logical IO` 查看 Top SQL，或者使用 `By Region` 聚合，请在 Top SQL 设置面板中打开 **开启 TiKV 网络 IO 采集（多维度）** (Enable TiKV Network IO collection (multi-dimensional)) 开关并保存。 + +- **Order By Network**：按照 TiKV 请求处理过程中产生的网络字节数排序。 +- **Order By Logical IO**：按照 TiKV 请求在 TiKV 存储层处理的逻辑数据字节数排序，例如读取过程中扫描或处理的数据量，以及写请求写入的数据量。 + +如下图所示，右侧**设置** (Settings) 面板中会同时显示 **启用功能** (Enable Feature) 和 **开启 TiKV 网络 IO 采集（多维度）** (Enable TiKV Network IO collection (multi-dimensional)) 两个开关。 + +![开启 TiKV 网络 IO 采集](/media/dashboard/v8.5-top-sql-settings-enable-tikv-network-io.png) + +**开启 TiKV 网络 IO 采集（多维度）**会增加一定的存储和查询开销。开启后，系统会将配置下发到当前所有 TiKV 节点；数据展示可能同样存在约 1 分钟延迟。如果部分 TiKV 节点未成功开启该功能，页面会给出告警提示，此时新数据可能不完整。 + +对于后续新扩容的 TiKV 节点，这个开关不会自动生效。你需要在 Top SQL 设置面板中将 **开启 TiKV 网络 IO 采集（多维度）** 开关设置为全开并保存，使配置重新下发到所有 TiKV 节点。如果你希望新增的 TiKV 节点自动开启该功能，可以在 TiUP 集群拓扑文件的 `server_configs.tikv` 下增加以下配置，并通过 TiUP 重新下发 TiKV 配置： + +```yaml +server_configs: + tikv: + resource-metering.enable-network-io-collection: true +``` + +关于 TiUP 拓扑配置的更多信息，请参见 [TiUP 集群拓扑文件配置](/tiup/tiup-cluster-topology-reference.md)。 + ## 使用 Top SQL 以下是 Top SQL 的常用步骤： 1. 访问 [Top SQL 页面](#访问页面)。 -2. 选择一个你想要观察负载的具体 TiDB 或 TiKV 实例。 +2. 选择一个你想要观察负载的具体 TiDB 或 TiKV 节点。 + + ![选择 TiDB 或 TiKV 节点](/media/dashboard/top-sql-usage-select-instance.png) + + 如果你不知道要观察哪一个节点，可以先从 Grafana 或 [TiDB Dashboard 概况页面](/dashboard/dashboard-overview.md)中定位负载异常的节点，再返回 Top SQL 页面进一步分析。 + +3. 设置时间范围，并根据需要刷新数据。 - ![选择实例](/media/dashboard/top-sql-usage-select-instance.png) + 你可以在时间选择器中调整时间范围，或在图表中框选一个时间范围来缩放观察窗口。更小的时间范围能够展示更细粒度的数据，精度最高可达 1 秒。 - 如果你不知道要观察哪一个 TiDB 或 TiKV 实例，可以选择任意一个实例。在集群 CPU 开销非常不均衡的情况下，你可以首先通过 Grafana 中的 CPU 监控来确定具体期望观察的实例。 + ![修改时间范围](/media/dashboard/v8.5-top-sql-usage-change-timerange.png) -3. 观察 Top SQL 呈现的 Top 5 图表及表格。 + 如果图表中显示的数据已过时，你可以点击**刷新** (Refresh) 按钮执行一次刷新，或在**刷新** (Refresh) 下拉列表中选择数据自动刷新的频率。 - ![图表表格](/media/dashboard/top-sql-usage-chart.png) + ![刷新](/media/dashboard/v8.5-top-sql-usage-refresh.png) - 柱状图中色块的大小代表了 SQL 语句在该时刻消耗的 CPU 资源的多少，不同颜色区分了不同类型的 SQL 语句。大多数情况下，你都应该关注图表中相应时间范围内 CPU 资源开销较大的 SQL 语句。 +4. 选择观察模式。 -4. 点击表格中的某一个 SQL 语句后，可以展开查看该语句不同执行计划的执行情况，例如 Call/sec（平均每秒请求数）、Scan Indexes/sec（平均每秒扫描索引数）等。 + - 通过 `Limit` 选择展示 Top `5`、`20` 或 `100` 类 SQL 查询。 + - 默认的聚合维度为 `By Query`。如果当前选择的是 TiKV 节点，还可以选择按照 `By Table`、`By DB` 或 `By Region` 维度进行聚合。 - ![详情](/media/dashboard/top-sql-details.png) + ![选择聚合维度](/media/dashboard/v8.5-top-sql-usage-select-agg-by.png) -5. 基于这些初步线索，进一步在 [SQL 语句分析](/dashboard/dashboard-statement-list.md)或[慢查询](/dashboard/dashboard-slow-query.md)界面中了解该 SQL 语句开销大量 CPU 资源、或扫大量数据的详细原因。 + - 默认的排序方式是 `Order By CPU`（按 CPU 耗时排序）。如果当前选择的是 TiKV 节点且已[开启 TiKV 网络 IO 采集（多维度）](#开启-tikv-网络-io-采集可选从-v856-开始引入)，还可以选择 `Order By Network`（按网络字节数排序） 或 `Order By Logical IO`（按逻辑 IO 字节数排序）。 - 你可以在时间选择器中调整时间范围，或在图表中框选一个时间范围，来更精确、细致地观察问题。更小的时间范围将能提供细节更丰富的数据，数据最高精度可达 1 秒。 + ![选择排序方式](/media/dashboard/v8.5-top-sql-usage-select-order-by.png) - ![修改时间范围](/media/dashboard/top-sql-usage-change-timerange.png) + > **注意** + > + > `By Region` 以及 `Order By Network`、`Order By Logical IO` 仅在 [TiKV 网络 IO 采集（多维度）](#开启-tikv-网络-io-采集可选从-v856-开始引入)开启时可选。若该功能未开启，但历史数据仍然存在，页面会继续展示历史数据，并提示新数据无法完整采集。 - 如果图表中显示的数据已过时，你可以点击**刷新** (Refresh) 按钮，或在**刷新** (Refresh) 下拉列表中选择自动刷新。 +5. 观察图表和表格中的资源消耗热点记录。 - ![刷新](/media/dashboard/top-sql-usage-refresh.png) + ![图表表格](/media/dashboard/v8.5-top-sql-usage-chart.png) -6. 查看按表或者数据库维度的 CPU 资源使用情况，快速定位更高维度的资源使用情况。目前只支持查看 TiKV 实例。 + 柱状图表示当前排序维度下的资源消耗，不同颜色表示不同记录。表格会按照当前排序维度展示累计值，并在最后提供 `Others` 行，用于汇总所有非 Top N 记录。 - 选择一个 TiKV 实例，然后选择 **By TABLE** 或者 **By DB**： +6. 在 `By Query` 视图中，点击表格中的某一行 SQL，即可查看该类 SQL 的执行计划详情。 - ![选择聚合维度](/media/dashboard/top-sql-usage-select-agg-by.png) + ![详情](/media/dashboard/v8.5-top-sql-details.png) - 查看高维度的聚合结果： + 你可以在 SQL 详情中查看对应的 SQL 模板、SQL 模板 ID、Plan 模板 ID 以及执行计划文本。SQL 详情表会根据节点类型展示不同指标： - ![按 DB 维度聚合结果页面](/media/dashboard/top-sql-usage-agg-by-db-detail.png) + - TiDB 节点通常显示 `Call/sec` 与 `Latency/call`。 + - TiKV 节点通常显示 `Call/sec`、`Scan Rows/sec` 和 `Scan Indexes/sec`。 + + > **注意** + > + > 如果当前选择的是 `By Table`、`By DB` 或 `By Region` 聚合视图，页面展示的是聚合结果，不再按 SQL 执行计划展开详情。 + + 在 `By Query` 视图中，你也可以直接点击 Top SQL 表格中的**在 SQL 语句分析中搜索** (Search in SQL Statements) 跳转到对应的 SQL 语句分析页面。若需要离线分析当前表格结果，可以点击表格上方的 **Download to CSV** 导出当前表格数据。 + +7. 在 TiKV 节点上，如果需要从更高维度定位热点，可以切换到 `By Table`、`By DB` 或 `By Region`，查看聚合后的结果。 + + ![按 DB 维度聚合结果页面](/media/dashboard/v8.5-top-sql-usage-agg-by-db-detail.png) + +8. 基于这些初步线索，进一步在 [SQL 语句分析](/dashboard/dashboard-statement-list.md)或[慢查询](/dashboard/dashboard-slow-query.md)页面中分析根因。 ## 停用 Top SQL 你可以通过以下步骤停用该功能： 1. 访问 [Top SQL 页面](#访问页面)。 -2. 点击右上角**齿轮按钮**打开设置界面，将**启用特性** (Enable Feature) 下方的开关关闭。 +2. 点击右上角**齿轮按钮**打开设置界面，将**启用功能** (Enable Feature) 下方的开关关闭。 3. 点击**保存** (Save)。 4. 在弹出的**关闭 Top SQL 功能** (Disable Top SQL Feature) 对话框中，点击**确认** (Disable)。 +停用后将停止采集新的 Top SQL 数据，但历史数据在过期前仍可查看。 + 除了通过图形化界面以外，你也可以配置 TiDB 系统变量 [`tidb_enable_top_sql`](/system-variables.md#tidb_enable_top_sql-从-v540-版本开始引入) 来停用 Top SQL 功能： {{< copyable "sql" >}} @@ -119,6 +171,15 @@ SET GLOBAL tidb_enable_top_sql = 1; SET GLOBAL tidb_enable_top_sql = 0; ``` +### 停用 TiKV 网络 IO 采集 + +如果你只想停止采集 TiKV 的 `Network Bytes`、`Logical IO Bytes` 等多维度数据，而保留 Top SQL 的 CPU 维度分析能力，可以在 Top SQL 设置面板中关闭 **开启 TiKV 网络 IO 采集（多维度）** 开关。 + +关闭后： + +- Top SQL 页面仍可查看之前已采集到的尚未过期的历史网络 IO 和逻辑 IO 数据。 +- 新的网络 IO 和逻辑 IO 数据，以及 `By Region` 数据将不再继续采集。 + ## 常见问题 **1. 界面上提示“集群中未启动必要组件 NgMonitoring”无法启用功能** @@ -127,15 +188,15 @@ SET GLOBAL tidb_enable_top_sql = 0; **2. 该功能开启后对集群是否有性能影响？** -该功能对集群性能有轻微影响。根据我们的测算，该功能对集群的平均性能影响小于 3%。 +开启 Top SQL 对集群性能有轻微影响。根据测算，该功能对集群的平均性能影响小于 3%。如果你同时开启了 TiKV 网络 IO 采集（多维度），还会额外增加一定的存储和查询开销。 **3. 该功能目前是什么状态？** 该功能是正式特性，在生产环境中可用。 -**4. 界面中显示的其他语句（Other Statements）是什么意思？** +**4. 界面中的 `Others` 是什么意思？** -其他所有非 Top 5 语句产生的 CPU 开销或执行情况都会被统计在该项中。你可以基于这一项了解 Top 5 的 SQL 语句开销在整体所有 SQL 语句的 CPU 开销中的比例。 +`Others` 表示当前排序维度下所有非 Top N 记录的汇总结果。你可以基于这一项了解 Top N 记录在整体负载中的占比。 **5. Top SQL 展示的 CPU 开销总和与进程的实际 CPU 开销是什么关系？** @@ -143,8 +204,21 @@ SET GLOBAL tidb_enable_top_sql = 0; **6. Top SQL 图表的纵坐标是什么意思？** -代表消耗 CPU 资源的多少。消耗资源越多的 SQL 语句，该值越大。在绝大多数情况下，你都不需要关心纵坐标具体数值的含义。 +Top SQL 图表纵坐标表示当前排序维度下的资源消耗大小。 + +- 选择 `Order By CPU` 时，纵坐标表示 CPU 耗时。 +- 选择 `Order By Network` 时，纵坐标表示网络字节数。 +- 选择 `Order By Logical IO` 时，纵坐标表示逻辑 IO 字节数。 **7. 还没有执行完毕的 SQL 语句会被统计到吗？** -会。Top SQL 图表上所展示的每一时刻 CPU 开销比例即为这一时刻所有正在运行的 SQL 语句的 CPU 开销情况。 +会。TiDB Dashboard 会统计 Top SQL 开启后所有正在运行或已经执行完成的 SQL 的资源消耗，因此尚未执行完毕的 SQL 也会被统计在内。 + +**8. 为什么看不到 `Order By Network`、`Order By Logical IO` 或 `By Region` 的新数据？** + +这些视图依赖 TiKV 网络 IO 采集（多维度）。请确认以下事项： + +- 你当前选择的是 TiKV 节点。 +- Top SQL 设置面板中的**开启 TiKV 网络 IO 采集（多维度）**已经打开。 +- 集群中的相关 TiKV 节点都已成功开启该配置；如果只有部分节点开启，Top SQL 页面会提示新数据可能不完整。 +- 如果是新扩容的 TiKV 节点，需要重新在 Top SQL 设置面板中手工操作一次 **开启 TiKV 网络 IO 采集（多维度）** 开关并保存；如果希望后续扩容节点自动生效，请在 TiUP 的 TiKV 默认配置中同步开启 `resource-metering.enable-network-io-collection`。 diff --git a/dm/dm-compatibility-catalog.md b/dm/dm-compatibility-catalog.md index 1ea5b6a1c797..947abc490673 100644 --- a/dm/dm-compatibility-catalog.md +++ b/dm/dm-compatibility-catalog.md @@ -19,18 +19,35 @@ TiDB Data Migration (DM) 数据迁移工具可以将数据从不同类型的数 | MySQL ≤ 5.5 | 未测试 | | MySQL 5.6 | 正式支持 | | | MySQL 5.7 | 正式支持 | | -| MySQL 8.0 | 正式支持 | 不支持 binlog 事务压缩 [Transaction_payload_event](https://dev.mysql.com/doc/refman/8.0/en/binary-log-transaction-compression.html)。 | -| MySQL 8.1 ~ 8.3 | 未测试 | | -| MySQL 8.4 | 不兼容 | 更多信息，请参考 [DM Issue #11020](https://github.com/pingcap/tiflow/issues/11020)。| +| MySQL 8.0 | 正式支持 | 不支持 [binlog 事务压缩 (`Transaction_payload_event`)](https://dev.mysql.com/doc/refman/8.0/en/binary-log-transaction-compression.html)。 | +| MySQL 8.1 ~ 8.3 | 未测试 | 不支持 [binlog 事务压缩 (`Transaction_payload_event`)](https://dev.mysql.com/doc/refman/8.0/en/binary-log-transaction-compression.html)。 | +| MySQL 8.4 | 实验支持（适用于从 v8.5.6 起的 TiDB 版本） | 不支持 [binlog 事务压缩 (`Transaction_payload_event`)](https://dev.mysql.com/doc/refman/8.4/en/binary-log-transaction-compression.html)。 | | MySQL 9.x | 未测试 | | | MariaDB < 10.1.2 | 不兼容 | 与时间类型的 binlog 不兼容。 | | MariaDB 10.1.2 ~ 10.5.10 | 实验支持 | | | MariaDB > 10.5.10 | 未测试 | 在绕过[前置检查](/dm/dm-precheck.md)后，理论上大多数情况下可以正常工作。参见 [MariaDB 说明](#mariadb-说明)。 | -### 与外键 CASCADE 操作的不兼容性 +### 外键 `CASCADE` 操作 -- DM 会在目标端创建外键约束，但在应用事务时不会强制执行，因为 DM 设置了会话变量 [`foreign_key_checks=OFF`](/system-variables.md#foreign_key_checks)。 -- DM 默认**不**支持 `ON DELETE CASCADE` 和 `ON UPDATE CASCADE` 行为，并且不推荐通过 DM 任务会话变量启用 `foreign_key_checks`。如果你的负载依赖于级联操作，**不要假设**级联效果会被复制。 +> **警告：** +> +> 该功能为实验特性。不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tiflow/issues) 反馈。 + +从 v8.5.6 开始，DM 以**实验特性**支持同步包含外键约束的表。该支持包括以下改进： + +- **安全模式**：在安全模式执行期间，DM 会在每个批次中设置 `foreign_key_checks=0`，并对未修改主键或唯一键值的 `UPDATE` 语句跳过冗余的 `DELETE` 步骤。这可以防止 `REPLACE INTO`（其内部执行为 `DELETE` + `INSERT`）在子表行上触发非预期的 `ON DELETE CASCADE` 效果。详情参见 [DM 安全模式](/dm/dm-safe-mode.md#外键处理-从-v856-版本开始引入)。 +- **多 worker 因果关系**：当 `worker-count > 1` 时，DM 会在任务启动时从下游 schema 中读取外键关系并注入因果键。这可确保父表行的 DML 操作先于其依赖的子表行操作完成，从而在多个 worker 之间保持 binlog 顺序。 + +同步包含外键约束的表存在以下限制： + +- 在安全模式下，DM 不支持修改主键或唯一键值的 `UPDATE` 语句。任务会暂停，并报错：`safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported`。如需同步此类语句，请将 `safe-mode` 设置为 `false`。 +- 当 `foreign_key_checks=1` 时，DM 不支持在同步过程中执行创建、修改或删除外键约束的 DDL 语句。 +- 当 `worker-count > 1` 时，不支持表路由。如果对包含外键的表使用表路由，请将 `worker-count` 设置为 `1`。 +- 黑白名单过滤 (Block & Allow List) 必须包含外键依赖链中的所有祖先表。如果祖先表被过滤，在增量复制期间任务会报错并暂停。 +- 源端与下游的外键元数据必须保持一致。如果检测到不一致，请运行 `binlog-schema update --from-target` 以重新同步元数据。 +- 当 `UPDATE` 修改主键或唯一键值时，安全模式下无法正确同步 `ON UPDATE CASCADE`。这是因为 DM 会将此类语句改写为 `DELETE` + `REPLACE`，从而触发 `ON DELETE` 行为而不是 `ON UPDATE` 行为。在这种情况下，DM 会拒绝该语句并暂停任务。未修改键值的 `UPDATE` 语句可以被正确同步。 + +在 v8.5.6 之前的版本中，DM 会在下游创建外键约束，但由于其将会话变量 [`foreign_key_checks=OFF`](/system-variables.md#foreign_key_checks)，这些约束不会被强制执行。因此，级联操作不会被同步到下游。 ### MariaDB 说明 diff --git a/dm/dm-precheck.md b/dm/dm-precheck.md index 89d578b3779d..45c040c8f4eb 100644 --- a/dm/dm-precheck.md +++ b/dm/dm-precheck.md @@ -50,7 +50,7 @@ tiup dmctl check-task ./task.yaml - 上游 MySQL 表结构的兼容性 - - 检查上游表是否设置了外键。TiDB 不支持外键，如果上游表设置了外键，则返回警告。 + - 检查上游表是否设置了外键。TiDB v8.5.0 起正式支持外键 (GA)，DM 从 v8.5.6 开始以实验特性支持同步包含外键约束的表。在前置检查期间，如果检测到外键，DM 会返回警告。有关支持的场景和限制，参见 [DM 兼容性目录](/dm/dm-compatibility-catalog.md#外键-cascade-操作)。 - 检查上游字符集是否与 TiDB 兼容，详见 [TiDB 支持的字符集](/character-set-and-collation.md)。 - 检查上游表中是否存在主键或唯一键约束（从 v1.0.7 版本引入）。 diff --git a/dm/dm-safe-mode.md b/dm/dm-safe-mode.md index 740524c529ec..2c78030cac1e 100644 --- a/dm/dm-safe-mode.md +++ b/dm/dm-safe-mode.md @@ -24,6 +24,8 @@ DM 从 checkpoint 恢复数据同步任务后，可能重复执行某些 binlog * `INSERT` 语句会被改写成 `REPLACE` 语句。 * `UPDATE` 语句会被分析，得到该语句涉及的行的主键或唯一索引的值，然后改写成 `DELETE` + `REPLACE` 语句 ：先根据主键或唯一索引的定位删除对应的行，然后使用 `REPLACE` 语句插入一条最新值的行记录。 + 从 v8.5.6 起，当你在同步任务的会话中设置 `foreign_key_checks=1` 时，对于未修改主键或唯一索引值的 `UPDATE` 语句，DM 会跳过 `DELETE` 步骤。详情参见[外键处理](#外键处理-从-v856-版本开始引入)。 + `REPLACE` 操作是 MySQL 特有的数据插入语法。使用 `REPLACE` 语法插入数据时，如果新插入的数据和现有数据存在主键或唯一约束冲突，MySQL 会删除所有冲突的记录，然后再执行插入记录操作，相当于“强制插入”的操作。具体请参考 [MySQL 官方文档的 `REPLACE` 语句相关介绍](https://dev.mysql.com/doc/refman/8.0/en/replace.html)。 比如，假设一张表 `dummydb.dummytbl` 的主键是 `id`，在这张表中重复执行下面的 SQL 语句： @@ -85,6 +87,53 @@ mysql-instances: syncer-config-name: "global" # syncers 配置的名称 ``` +## 外键处理 从 v8.5.6 版本开始引入 + +> **警告：** +> +> 该功能为实验特性。不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tiflow/issues) 反馈。 + +当你启用安全模式并在下游任务会话中设置 `foreign_key_checks=1` 时，`UPDATE` 语句默认的 `DELETE` + `REPLACE` 改写方式可能会在子表行上触发非预期的 `ON DELETE CASCADE` 效果。从 v8.5.6 起，DM 引入以下改进来解决此问题。 + +### 非键值 `UPDATE` 优化 + +对于未修改主键或唯一键值的 `UPDATE` 语句，DM 会跳过 `DELETE` 步骤，仅执行 `REPLACE INTO`。由于主键保持不变，`REPLACE INTO` 会覆盖现有行，而不会触发外键级联删除。该优化在安全模式下自动生效。 + +以下面这个上游语句为例，其中 `id` 为主键： + +```sql +UPDATE dummydb.dummytbl SET int_value = 888999 WHERE id = 123; +``` + +在 v8.5.6 之前的版本中，安全模式会将该语句改写为： + +```sql +DELETE FROM dummydb.dummytbl WHERE id = 123; -- 触发 ON DELETE CASCADE +REPLACE INTO dummydb.dummytbl (id, int_value, ...) VALUES (123, 888999, ...); +``` + +从 v8.5.6 开始，安全模式会将该语句改写为： + +```sql +REPLACE INTO dummydb.dummytbl (id, int_value, ...) VALUES (123, 888999, ...); -- 不触发级联 +``` + +> **警告：** +> +> 当 `foreign_key_checks=1` 时，DM 不支持同步修改了主键或唯一键值的 `UPDATE` 语句。在这种情况下，同步任务会暂停，并报错：`safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported`。如需在包含外键的表上同步此类 `UPDATE` 语句，请将 `safe-mode` 设置为 `false`。 + +### 会话级 `foreign_key_checks` + +在安全模式下执行批处理时，DM 会在执行 `INSERT` 和 `UPDATE` 批处理之前执行 `SET SESSION foreign_key_checks=0`，并在执行完成后恢复 `foreign_key_checks` 原始值。这可以防止 `REPLACE INTO`（其内部实现为 `DELETE` + `INSERT`）在下游触发外键级联操作。 + +该会话级设置在每个批次中会引入少量开销（两次 `SET SESSION` 往返）。在大多数工作负载中，这种开销可以忽略不计。 + +### 多 worker 外键因果关系 + +当你将 `worker-count` 设置为大于 1 且同步任务包含带有外键的表时，DM 会在任务启动时从下游的 `CREATE TABLE` schema 中读取外键关系。对于每个 DML 操作，DM 会基于这些关系注入因果键，从而确保父表行及其依赖的子表行的操作被分配到同一个 DML worker 队列中。 + +详细限制参见 [DM 兼容性目录](/dm/dm-compatibility-catalog.md#外键-cascade-操作)。 + ## 注意事项 如果你出于安全考虑，希望全程开启安全模式，你需要注意以下事项： diff --git a/download-ecosystem-tools.md b/download-ecosystem-tools.md index 6f08bbe791c7..fdb2b01d3969 100644 --- a/download-ecosystem-tools.md +++ b/download-ecosystem-tools.md @@ -9,11 +9,11 @@ summary: 本文介绍如何下载 TiDB 工具包。TiDB 工具包包含常用工 ## TiDB 工具包下载 -TiDB 工具包中包含了一些常用的 TiDB 工具，例如数据导出工具 Dumpling、数据导入工具 TiDB Lightning、备份恢复工具 BR。 +TiDB 工具包中包含了一些常用的 TiDB 工具，例如数据导出工具 Dumpling、数据导入工具 TiDB Lightning、备份恢复工具 BR、数据一致性检查工具 sync-diff-inspector。 > **建议：** > -> 如果你的部署环境能访问互联网，无需单独下载 TiDB 工具包，可以直接通过使用 [TiUP 命令一键部署](/tiup/tiup-component-management.md)所需的 TiDB 工具。 +> 对于 TiDB v8.5.6 及以上版本，包括 sync-diff-inspector 在内的大多数工具都可以直接通过 TiUP 使用。如果你的部署环境能访问互联网，无需单独下载 TiDB 工具包，可以直接通过使用 [TiUP 命令一键部署](/tiup/tiup-component-management.md)所需的 TiDB 工具。 ### 环境要求 @@ -42,7 +42,7 @@ TiDB 工具包中包含了一些常用的 TiDB 工具，例如数据导出工具 | [TiDB DM (Data Migration)](/dm/dm-overview.md) | `dm-worker-{version}-linux-{arch}.tar.gz`
`dm-master-{version}-linux-{arch}.tar.gz`
`dmctl-{version}-linux-{arch}.tar.gz` | | [TiCDC](/ticdc/ticdc-overview.md) | `cdc-{version}-linux-{arch}.tar.gz` | | [Backup & Restore (BR)](/br/backup-and-restore-overview.md) | `br-{version}-linux-{arch}.tar.gz` | -| [sync-diff-inspector](/sync-diff-inspector/sync-diff-inspector-overview.md) | `sync_diff_inspector` | +| [sync-diff-inspector](/sync-diff-inspector/sync-diff-inspector-overview.md) | TiDB v8.5.6 及以上版本：`tiflow-{version}-linux-{arch}.tar.gz`
TiDB v8.5.6 之前的版本：`sync_diff_inspector` | | [PD Recover](/pd-recover.md) | `pd-recover-{version}-linux-{arch}.tar.gz` | > **注意：** diff --git a/foreign-key.md b/foreign-key.md index ad1b96089a2f..324a96eb59d2 100644 --- a/foreign-key.md +++ b/foreign-key.md @@ -177,9 +177,11 @@ TiDB 支持是否开启外键约束检查，由系统变量 [`foreign_key_checks ## 锁 -在 `INSERT` 或者 `UPDATE` 子表时，外键约束会检查父表中是否存在对应的外键值，并对父表中的该行数据上锁，避免该外键值被其他操作删除，导致破坏外键约束。这里的上锁行为等同于对父表中外键值所在行做 `SELECT FOR UPDATE` 操作。 +在 `INSERT` 或者 `UPDATE` 子表时，外键约束会检查父表中是否存在对应的外键值，并对父表中的该行数据上锁，避免该外键值被其他操作删除，导致破坏外键约束。 -因为 TiDB 目前暂不支持 `LOCK IN SHARE MODE`，所以，在并发写入子表场景，如果引用的外键值大部分都一样，可能会有比较严重的锁冲突。建议在大批量写入子表数据时，关闭 [`foreign_key_checks`](/system-variables.md#foreign_key_checks)。 +默认情况下，在悲观事务中，外键检查对父表中行的加锁行为等价于对该行执行一次 `SELECT ... FOR UPDATE` 的锁定读（即加排他锁）。在子表高并发写入的场景下，如果大量事务反复引用相同的父表行，可能出现较严重的锁冲突。 + +你可以通过开启系统变量 [`tidb_foreign_key_check_in_shared_lock`](/system-variables.md#tidb_foreign_key_check_in_shared_lock-从-v856-版本开始引入) 来让外键检查使用共享锁。共享锁允许多个事务在同一父表行同时完成外键检查，从而减少锁冲突，提升子表并发写入性能。 ## 外键的定义和元信息 @@ -301,7 +303,7 @@ Create Table | CREATE TABLE `child` ( ### 与 TiDB 工具的兼容性 -- [DM](/dm/dm-overview.md) 不兼容外键功能。DM 在同步数据到下游 TiDB 时，会显式关闭下游 TiDB 的 [`foreign_key_checks`](/system-variables.md#foreign_key_checks)，所以由外键产生的级联操作不会从上游同步到下游，这会导致上下游数据不一致。 +- [DM](/dm/dm-overview.md)：从 v8.5.6 开始，DM 以实验特性支持同步包含外键约束的表。具体的使用场景和限制，参见 [TiDB Data Migration 兼容性目录](/dm/dm-compatibility-catalog.md#外键-cascade-操作)。在 v8.5.6 之前的版本中，DM 在同步数据到 TiDB 时会关闭 [`foreign_key_checks`](/system-variables.md#foreign_key_checks) 系统变量，因此级联操作不会从上游同步到下游。 - [TiCDC](/ticdc/ticdc-overview.md) v6.6.0 兼容外键功能。旧版本的 TiCDC 在同步带外键的表时，可能会报错，建议使用 v6.6.0 之前版本 TiCDC 时先关闭下游 TiDB 集群的 `foreign_key_checks`。 - [BR](/br/backup-and-restore-overview.md) v6.6.0 兼容外键功能。之前版本的 BR 在恢复带外键的表到 v6.6.0 及之后版本的集群时，可能会报错，建议先关闭下游 TiDB 集群的 `foreign_key_checks` 后再恢复集群。 - [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 导入数据到 TiDB 前，如果目标表使用了外键，建议先关闭 TiDB 集群的 `foreign_key_checks`。对于 v6.6.0 之前的版本，关闭该系统变量也不会生效，你需要为下游数据库用户添加 `REFERENCES` 权限，或者提前手动在下游数据库中创建好目标表，以确保顺利导入数据。 diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 4eb582daf8eb..deaf3a370f0c 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -172,25 +172,161 @@ Slow Query 基础信息： - `Storage_from_kv`：从 v8.5.5 开始引入，表示该语句是否从 TiKV 读取数据。 - `Storage_from_mpp`：从 v8.5.5 开始引入，表示该语句是否从 TiFlash 读取数据。 +## `tidb_slow_log_rules` 使用方法 + +[`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-从-v856-版本开始引入) 用于定义慢查询日志的触发规则，支持多维度指标组合条件。适合用于慢日志的“定向采样”和“问题复现”，可按具体指标组合条件筛选目标语句。 + +慢查询日志的触发行为取决于 `tidb_slow_log_rules` 的配置情况： + +- 如果未设置 `tidb_slow_log_rules`，慢查询日志触发仍依赖 [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold)（单位：毫秒）。 +- 如果已设置 `tidb_slow_log_rules`，配置的规则优先生效，[`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) 将被忽略。 + +如需了解各字段的具体含义、诊断价值和背景信息，请参见[字段含义说明](#字段含义说明)。 + +### 统一规则语法与类型约束 + +- 规则容量与分隔：`SESSION` 和 `GLOBAL` 各最多支持 10 条规则，同一会话最多可生效 20 条，规则之间用 `;` 分隔。 +- 条件格式：格式为 `字段名:值`，单条规则内的多个条件用 `,` 分隔。 +- 字段与作用域：字段名大小写不敏感（需保留下划线等字符）。`SESSION` 规则不支持 `Conn_ID`，仅 `GLOBAL` 支持 `Conn_ID`。 +- 匹配语义： + - 数值字段按 `>=` 匹配，字符串和布尔字段按等值匹配（`=`）。 + - `DB` 与 `Resource_group` 匹配时不区分大小写。 + - 不支持显式操作符（如 `>`, `<`, `!=`）。 + +类型约束如下： + +- 数值类型（`int64`、`uint64`、`float64`）统一要求 `>= 0`，负值会解析报错。 + - `int64`：上限 `2^63-1`。 + - `uint64`：上限 `2^64-1`。 + - `float64`：常规上限约 `1.79e308`。当前按 Go `ParseFloat` 解析，`NaN`/`Inf` 虽可被解析，但可能导致规则恒真或恒假，不建议使用。 +- `bool`：支持 `true`/`false`、`1`/`0`、`t`/`f`（大小写不敏感）。 +- `string`：当前不支持包含分隔符 `,`（条件分隔符）或 `;`（规则分隔符），即使使用引号（单引号或双引号）也不支持。不支持转义。 +- 重复字段：如果在单条规则内多次设置同一字段，以最后一次出现的值为准。 + +### 支持的字段列表 + +字段的详细解释、诊断含义和背景信息参见 [`identify-slow-queries` 的字段含义说明](/identify-slow-queries.md#字段含义说明)。 + +除非另有说明，下表中的字段默认遵循上文[统一规则语法与类型约束](#统一规则语法与类型约束)中的通用匹配与类型规则。该表仅列出当前支持的字段名、类型、单位以及少量规则的特殊说明，不重复说明字段语义。 + +| 字段名 | 类型 | 单位 | 备注 | +| -------------------------------------- | -------- | ------ | ------------------------------ | +| `Conn_ID` | `uint` | 计数 | 仅 GLOBAL 规则支持 | +| `Session_alias` | `string` | 无 | - | +| `DB` | `string` | 无 | 匹配时不区分大小写 | +| `Exec_retry_count` | `uint` | 计数 | - | +| `Query_time` | `float` | 秒 | - | +| `Parse_time` | `float` | 秒 | - | +| `Compile_time` | `float` | 秒 | - | +| `Rewrite_time` | `float` | 秒 | - | +| `Optimize_time` | `float` | 秒 | - | +| `Wait_TS` | `float` | 秒 | - | +| `Is_internal` | `bool` | 无 | - | +| `Digest` | `string` | 无 | - | +| `Plan_digest` | `string` | 无 | - | +| `Num_cop_tasks` | `int` | 计数 | - | +| `Mem_max` | `int` | bytes | - | +| `Disk_max` | `int` | bytes | - | +| `Write_sql_response_total` | `float` | 秒 | - | +| `Succ` | `bool` | 无 | - | +| `Resource_group` | `string` | 无 | 匹配时不区分大小写 | +| `KV_total` | `float` | 秒 | - | +| `PD_total` | `float` | 秒 | - | +| `Unpacked_bytes_sent_tikv_total` | `int` | bytes | - | +| `Unpacked_bytes_received_tikv_total` | `int` | bytes | - | +| `Unpacked_bytes_sent_tikv_cross_zone` | `int` | bytes | - | +| `Unpacked_bytes_received_tikv_cross_zone` | `int` | bytes | - | +| `Unpacked_bytes_sent_tiflash_total` | `int` | bytes | - | +| `Unpacked_bytes_received_tiflash_total` | `int` | bytes | - | +| `Unpacked_bytes_sent_tiflash_cross_zone` | `int` | bytes | - | +| `Unpacked_bytes_received_tiflash_cross_zone` | `int` | bytes | - | +| `Process_time` | `float` | 秒 | - | +| `Backoff_time` | `float` | 秒 | - | +| `Total_keys` | `uint` | 计数 | - | +| `Process_keys` | `uint` | 计数 | - | +| `cop_mvcc_read_amplification` | `float` | ratio | ratio 值 (Total_keys / Process_keys) | +| `Prewrite_time` | `float` | 秒 | - | +| `Commit_time` | `float` | 秒 | - | +| `Write_keys` | `uint` | 计数 | - | +| `Write_size` | `uint` | bytes | - | +| `Prewrite_region` | `uint` | 计数 | - | + +### 生效行为与匹配顺序 + +- 规则更新行为：每次执行 `SET [SESSION|GLOBAL] tidb_slow_log_rules = '...'` 都会覆盖对应作用域原有规则，不会追加。 +- 规则清空行为：`SET [SESSION|GLOBAL] tidb_slow_log_rules = ''` 会清空对应作用域规则。 +- 在当前会话存在可生效的 `tidb_slow_log_rules`（如 SESSION 规则、GLOBAL 的当前 `Conn_ID` 规则，或未指定 `Conn_ID` 的全局规则）时，慢查询日志输出由规则匹配结果决定，`tidb_slow_log_threshold` 不再参与判断。 +- 在当前会话没有任何可适用规则时，例如 SESSION 和 GLOBAL 都为空，或仅配置了与当前 `Conn_ID` 不匹配的 GLOBAL 规则，慢查询日志触发仍依赖 `tidb_slow_log_threshold`（注意其单位为毫秒）。 +- 如果希望规则中仍使用 SQL 执行时间作为输出慢日志的条件，可在规则中使用 `Query_time`（注意其单位为秒）并设置阈值。 +- 规则匹配逻辑如下： + - 多条规则之间采用 `OR` 关系，单条规则内多个字段条件采用 `AND` 关系。 + - SESSION 作用域规则优先匹配，若未匹配，再按顺序匹配 GLOBAL 的 `Conn_ID` 定向规则和未指定 `Conn_ID` 的全局通用规则。 +- `SHOW VARIABLES LIKE 'tidb_slow_log_rules'` 与 `SELECT @@SESSION.tidb_slow_log_rules` 返回 SESSION 规则文本（未设置时为空字符串），`SELECT @@GLOBAL.tidb_slow_log_rules` 返回 GLOBAL 规则文本。 + +### 使用示例 + +- 标准格式（SESSION 作用域）： + + ```sql + SET SESSION tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; + ``` + +- 错误格式（SESSION 作用域不支持 `Conn_ID`）： + + ```sql + SET SESSION tidb_slow_log_rules = 'Conn_ID: 12, Query_time: 0.5, Is_internal: false'; + ``` + +- 全局规则（适用于所有连接）： + + ```sql + SET GLOBAL tidb_slow_log_rules = 'Query_time: 0.5, Is_internal: false'; + ``` + +- 指定特定连接的全局规则（分别适用于 `Conn_ID:11` 和 `Conn_ID:12` 的两个连接）： + + ```sql + SET GLOBAL tidb_slow_log_rules = 'Conn_ID: 11, Query_time: 0.5, Is_internal: false; Conn_ID: 12, Query_time: 0.6, Process_time: 0.3, DB: db1'; + ``` + +### 使用建议 + +- `tidb_slow_log_rules` 用于替换单一阈值方式，支持多维度指标组合条件，以实现更灵活和精细化的慢查询日志控制。 + +- 在资源充足的测试环境（1 个 TiDB 节点，16 核 CPU、48 GiB 内存；3 个 TiKV 节点，每个 16 核 CPU、48 GiB 内存）中，多次 sysbench 测试结果表明：当多维慢查询日志规则在 30 分钟内生成数百万条慢查询日志时，对性能影响较小；但当日志量达到千万级时，TPS 会明显下降，延迟也会显著增加。因此在业务负载较高，或 CPU、内存资源接近瓶颈的情况下，应谨慎配置 `tidb_slow_log_rules`，避免因规则过宽导致日志洪泛。若需要限制日志输出速率，可通过 [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-从-v856-版本开始引入) 进行限速，以降低对业务性能的影响。 + ## 相关系统变量 -* [tidb_slow_log_threshold](/system-variables.md#tidb_slow_log_threshold)：设置慢日志的阈值，执行时间超过阈值的 SQL 语句将被记录到慢日志中。默认值是 300 ms。 -* [tidb_query_log_max_len](/system-variables.md#tidb_query_log_max_len)：设置慢日志记录 SQL 语句的最大长度。默认值是 4096 byte。 -* [tidb_redact_log](/system-variables.md#tidb_redact_log)：设置慢日志记录 SQL 时是否将用户数据脱敏用 `?` 代替。默认值是 `0`，即关闭该功能。 -* [tidb_enable_collect_execution_info](/system-variables.md#tidb_enable_collect_execution_info)：设置是否记录执行计划中各个算子的物理执行信息，默认值是 `1`。该功能对性能的影响约为 3%。开启该项后查看 `Plan` 的示例如下： +* [`tidb_slow_log_rules`](/system-variables.md#tidb_slow_log_rules-从-v856-版本开始引入)：请参见 [`tidb_slow_log_rules` 使用建议](#tidb_slow_log_rules-使用方法)。 -```sql -> select tidb_decode_plan('jAOIMAk1XzE3CTAJMQlmdW5jczpjb3VudChDb2x1bW4jNyktPkMJC/BMNQkxCXRpbWU6MTAuOTMxNTA1bXMsIGxvb3BzOjIJMzcyIEJ5dGVzCU4vQQoxCTMyXzE4CTAJMQlpbmRleDpTdHJlYW1BZ2dfOQkxCXQRSAwyNzY4LkgALCwgcnBjIG51bTogMQkMEXMQODg0MzUFK0hwcm9jIGtleXM6MjUwMDcJMjA2HXsIMgk1BWM2zwAAMRnIADcVyAAxHcEQNQlOL0EBBPBbCjMJMTNfMTYJMQkzMTI4MS44NTc4MTk5MDUyMTcJdGFibGU6dCwgaW5kZXg6aWR4KGEpLCByYW5nZTpbLWluZiw1MDAwMCksIGtlZXAgb3JkZXI6ZmFsc2UJMjUBrgnQVnsA'); -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| tidb_decode_plan('jAOIMAk1XzE3CTAJMQlmdW5jczpjb3VudChDb2x1bW4jNyktPkMJC/BMNQkxCXRpbWU6MTAuOTMxNTA1bXMsIGxvb3BzOjIJMzcyIEJ5dGVzCU4vQQoxCTMyXzE4CTAJMQlpbmRleDpTdHJlYW1BZ2dfOQkxCXQRSAwyNzY4LkgALCwgcnBjIG51bTogMQkMEXMQODg0MzUFK0hwcm9jIGtleXM6MjUwMDcJMjA2HXsIMg | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| id task estRows operator info actRows execution info memory disk | -| StreamAgg_17 root 1 funcs:count(Column#7)->Column#5 1 time:10.931505ms, loops:2 372 Bytes N/A | -| └─IndexReader_18 root 1 index:StreamAgg_9 1 time:10.927685ms, loops:2, rpc num: 1, rpc time:10.884355ms, proc keys:25007 206 Bytes N/A | -| └─StreamAgg_9 cop 1 funcs:count(1)->Column#7 1 time:11ms, loops:25 N/A N/A | -| └─IndexScan_16 cop 31281.857819905217 table:t, index:idx(a), range:[-inf,50000), keep order:false 25007 time:11ms, loops:25 N/A N/A | -+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -``` +* [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold)：用于设置慢查询日志的阈值，执行时间超过阈值的 SQL 语句将被记录到慢查询日志中。默认值是 `300ms`（单位：毫秒）。 + > **注意：** + > + > `tidb_slow_log_rules` 中 `Query_time`、`Process_time` 等时间类字段单位为秒（可带小数），而 [`tidb_slow_log_threshold`](/system-variables.md#tidb_slow_log_threshold) 的单位为毫秒。 + +* [`tidb_slow_log_max_per_sec`](/system-variables.md#tidb_slow_log_max_per_sec-从-v856-版本开始引入)：用于设置每秒打印慢查询日志数量的上限，默认值为 `0`。 + * 当值为 `0` 时，表示不限制每秒打印的慢查询日志数量。 + * 当值大于 `0` 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢查询日志文件。 + * 建议在启用了 `tidb_slow_log_rules` 后配置该变量，以防止基于规则的慢查询日志触发过于频繁。 + +* [`tidb_query_log_max_len`](/system-variables.md#tidb_query_log_max_len)：设置慢查询日志记录 SQL 语句的最大长度。默认值是 4096 byte。 + +* [`tidb_redact_log`](/system-variables.md#tidb_redact_log)：设置慢查询日志记录 SQL 时，是否将用户数据脱敏用 `?` 代替。默认值是 `0`，即关闭该功能。 + +* [`tidb_enable_collect_execution_info`](/system-variables.md#tidb_enable_collect_execution_info)：设置是否记录执行计划中各个算子的物理执行信息，默认值是 `1`。开启该功能会导致性能降低约 3%。开启后查看 `Plan` 的示例如下： + + ```sql + > select tidb_decode_plan('jAOIMAk1XzE3CTAJMQlmdW5jczpjb3VudChDb2x1bW4jNyktPkMJC/BMNQkxCXRpbWU6MTAuOTMxNTA1bXMsIGxvb3BzOjIJMzcyIEJ5dGVzCU4vQQoxCTMyXzE4CTAJMQlpbmRleDpTdHJlYW1BZ2dfOQkxCXQRSAwyNzY4LkgALCwgcnBjIG51bTogMQkMEXMQODg0MzUFK0hwcm9jIGtleXM6MjUwMDcJMjA2HXsIMgk1BWM2zwAAMRnIADcVyAAxHcEQNQlOL0EBBPBbCjMJMTNfMTYJMQkzMTI4MS44NTc4MTk5MDUyMTcJdGFibGU6dCwgaW5kZXg6aWR4KGEpLCByYW5nZTpbLWluZiw1MDAwMCksIGtlZXAgb3JkZXI6ZmFsc2UJMjUBrgnQVnsA'); + +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | tidb_decode_plan('jAOIMAk1XzE3CTAJMQlmdW5jczpjb3VudChDb2x1bW4jNyktPkMJC/BMNQkxCXRpbWU6MTAuOTMxNTA1bXMsIGxvb3BzOjIJMzcyIEJ5dGVzCU4vQQoxCTMyXzE4CTAJMQlpbmRleDpTdHJlYW1BZ2dfOQkxCXQRSAwyNzY4LkgALCwgcnBjIG51bTogMQkMEXMQODg0MzUFK0hwcm9jIGtleXM6MjUwMDcJMjA2HXsIMg | + +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | id task estRows operator info actRows execution info memory disk | + | StreamAgg_17 root 1 funcs:count(Column#7)->Column#5 1 time:10.931505ms, loops:2 372 Bytes N/A | + | └─IndexReader_18 root 1 index:StreamAgg_9 1 time:10.927685ms, loops:2, rpc num: 1, rpc time:10.884355ms, proc keys:25007 206 Bytes N/A | + | └─StreamAgg_9 cop 1 funcs:count(1)->Column#7 1 time:11ms, loops:25 N/A N/A | + | └─IndexScan_16 cop 31281.857819905217 table:t, index:idx(a), range:[-inf,50000), keep order:false 25007 time:11ms, loops:25 N/A N/A | + +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + ``` 在性能测试中可以关闭自动收集算子的执行信息： diff --git a/information-schema/information-schema.md b/information-schema/information-schema.md index 772e336423d0..344a212f9aed 100644 --- a/information-schema/information-schema.md +++ b/information-schema/information-schema.md @@ -18,7 +18,7 @@ Information Schema 提供了一种查看系统元数据的 ANSI 标准方法。 | [`COLLATIONS`](/information-schema/information-schema-collations.md) | 提供 TiDB 支持的排序规则列表。 | | [`COLLATION_CHARACTER_SET_APPLICABILITY`](/information-schema/information-schema-collation-character-set-applicability.md) | 说明哪些排序规则适用于哪些字符集。 | | [`COLUMNS`](/information-schema/information-schema-columns.md) | 提供所有表中列的列表。 | -| `COLUMN_PRIVILEGES` | TiDB 未实现，返回零行。 | +| `COLUMN_PRIVILEGES` | 汇总当前用户可见的列权限信息。 | | `COLUMN_STATISTICS` | TiDB 未实现，返回零行。 | | [`ENGINES`](/information-schema/information-schema-engines.md) | 提供支持的存储引擎列表。 | | `EVENTS` | TiDB 未实现，返回零行。 | @@ -36,14 +36,14 @@ Information Schema 提供了一种查看系统元数据的 ANSI 标准方法。 | `REFERENTIAL_CONSTRAINTS` | 提供有关 `FOREIGN KEY` 约束的信息。 | | `ROUTINES` | TiDB 未实现，返回零行。 | | [`SCHEMATA`](/information-schema/information-schema-schemata.md) | 提供与 `SHOW DATABASES` 命令类似的信息。 | -| `SCHEMA_PRIVILEGES` | TiDB 未实现，返回零行。 | +| `SCHEMA_PRIVILEGES` | 汇总当前用户可见的数据库权限信息。 | | `SESSION_STATUS` | TiDB 未实现，返回零行。 | | [`SESSION_VARIABLES`](/information-schema/information-schema-session-variables.md) | 提供与 `SHOW SESSION VARIABLES` 命令类似的功能。 | | [`STATISTICS`](/information-schema/information-schema-statistics.md) | 提供有关表索引的信息。 | | [`TABLES`](/information-schema/information-schema-tables.md) | 提供当前用户可见的表的列表。 类似于 `SHOW TABLES`。 | | `TABLESPACES` | TiDB 未实现，返回零行。 | | [`TABLE_CONSTRAINTS`](/information-schema/information-schema-table-constraints.md) | 提供有关主键、唯一索引和外键的信息。 | -| `TABLE_PRIVILEGES` | TiDB 未实现，返回零行。 | +| `TABLE_PRIVILEGES` | 汇总当前用户可见的表权限信息。 | | `TRIGGERS` | TiDB 未实现，返回零行。 | | [`USER_ATTRIBUTES`](/information-schema/information-schema-user-attributes.md) | 汇总用户的注释和属性信息。 | | [`USER_PRIVILEGES`](/information-schema/information-schema-user-privileges.md) | 汇总与当前用户相关的权限。 | diff --git a/media/dashboard/v8.5-top-sql-access.png b/media/dashboard/v8.5-top-sql-access.png new file mode 100644 index 000000000000..03d0bd067684 Binary files /dev/null and b/media/dashboard/v8.5-top-sql-access.png differ diff --git a/media/dashboard/v8.5-top-sql-details.png b/media/dashboard/v8.5-top-sql-details.png new file mode 100644 index 000000000000..1238253c8e32 Binary files /dev/null and b/media/dashboard/v8.5-top-sql-details.png differ diff --git a/media/dashboard/v8.5-top-sql-settings-enable-tikv-network-io.png b/media/dashboard/v8.5-top-sql-settings-enable-tikv-network-io.png new file mode 100644 index 000000000000..a1108241d7b2 Binary files /dev/null and b/media/dashboard/v8.5-top-sql-settings-enable-tikv-network-io.png differ diff --git a/media/dashboard/v8.5-top-sql-usage-agg-by-db-detail.png b/media/dashboard/v8.5-top-sql-usage-agg-by-db-detail.png new file mode 100644 index 000000000000..94b285958ab1 Binary files /dev/null and b/media/dashboard/v8.5-top-sql-usage-agg-by-db-detail.png differ diff --git a/media/dashboard/v8.5-top-sql-usage-change-timerange.png b/media/dashboard/v8.5-top-sql-usage-change-timerange.png new file mode 100644 index 000000000000..b1b80644d211 Binary files /dev/null and b/media/dashboard/v8.5-top-sql-usage-change-timerange.png differ diff --git a/media/dashboard/v8.5-top-sql-usage-chart.png b/media/dashboard/v8.5-top-sql-usage-chart.png new file mode 100644 index 000000000000..7fce9778d1f8 Binary files /dev/null and b/media/dashboard/v8.5-top-sql-usage-chart.png differ diff --git a/media/dashboard/v8.5-top-sql-usage-refresh.png b/media/dashboard/v8.5-top-sql-usage-refresh.png new file mode 100644 index 000000000000..815ebf5ddf21 Binary files /dev/null and b/media/dashboard/v8.5-top-sql-usage-refresh.png differ diff --git a/media/dashboard/v8.5-top-sql-usage-select-agg-by.png b/media/dashboard/v8.5-top-sql-usage-select-agg-by.png new file mode 100644 index 000000000000..967de9aef27c Binary files /dev/null and b/media/dashboard/v8.5-top-sql-usage-select-agg-by.png differ diff --git a/media/dashboard/v8.5-top-sql-usage-select-instance.png b/media/dashboard/v8.5-top-sql-usage-select-instance.png new file mode 100644 index 000000000000..3308b2724398 Binary files /dev/null and b/media/dashboard/v8.5-top-sql-usage-select-instance.png differ diff --git a/media/dashboard/v8.5-top-sql-usage-select-order-by.png b/media/dashboard/v8.5-top-sql-usage-select-order-by.png new file mode 100644 index 000000000000..c9c2a621d7e4 Binary files /dev/null and b/media/dashboard/v8.5-top-sql-usage-select-order-by.png differ diff --git a/mysql-compatibility.md b/mysql-compatibility.md index 017df64218c3..8566690bd570 100644 --- a/mysql-compatibility.md +++ b/mysql-compatibility.md @@ -34,7 +34,6 @@ TiDB 高度兼容 MySQL 协议，以及 MySQL 5.7 和 MySQL 8.0 常用的功能 * MySQL 追踪优化器 * XML 函数 * X-Protocol [#1109](https://github.com/pingcap/tidb/issues/1109) -* 列级权限 [#9766](https://github.com/pingcap/tidb/issues/9766) * `XA` 语法（TiDB 内部使用两阶段提交，但并没有通过 SQL 接口公开） * `CREATE TABLE tblName AS SELECT stmt` 语法 [#4754](https://github.com/pingcap/tidb/issues/4754) * `CHECK TABLE` 语法 [#4673](https://github.com/pingcap/tidb/issues/4673) diff --git a/privilege-management.md b/privilege-management.md index 5f77eea4dbb6..d7ea08d14831 100644 --- a/privilege-management.md +++ b/privilege-management.md @@ -30,6 +30,8 @@ GRANT SELECT ON test.* TO 'xxx'@'%'; GRANT ALL PRIVILEGES ON *.* TO 'xxx'@'%'; ``` +从 v8.5.6 版本开始，TiDB 支持兼容 MySQL 的列级权限管理机制。你可以在指定表上针对特定列授予或回收 `SELECT`、`INSERT`、`UPDATE`、`REFERENCES` 权限。更多信息参见[列级权限管理](/column-privilege-management.md)。 + 默认情况下，如果指定的用户不存在，[`GRANT`](/sql-statements/sql-statement-grant-privileges.md) 语句将报错。该行为受 [SQL 模式](/system-variables.md#sql_mode)中的 `NO_AUTO_CREATE_USER` 控制。 ```sql @@ -514,7 +516,7 @@ SELECT * FROM INFORMATION_SCHEMA.USER_PRIVILEGES WHERE grantee = "'root'@'%'"; - `mysql.user`：用户账户，全局权限 - `mysql.db`：数据库级别的权限 - `mysql.tables_priv`：表级别的权限 -- `mysql.columns_priv`：列级别的权限，当前暂不支持 +- `mysql.columns_priv`：列级别的权限（从 v8.5.6 开始支持） 这几张表包含了数据的生效范围和权限信息。例如，`mysql.user` 表的部分数据： diff --git a/sql-statements/sql-statement-grant-privileges.md b/sql-statements/sql-statement-grant-privileges.md index 8d8d160e0b15..2b878d8f5c65 100644 --- a/sql-statements/sql-statement-grant-privileges.md +++ b/sql-statements/sql-statement-grant-privileges.md @@ -101,7 +101,7 @@ SHOW GRANTS FOR 'newuser'; ## MySQL 兼容性 * 与 MySQL 类似，`USAGE` 权限表示登录 TiDB 服务器的能力。 -* 目前不支持列级权限。 +* 从 v8.5.6 版本开始，TiDB 支持兼容 MySQL 的列级权限管理机制。你可以在指定表上针对特定列授予或回收 `SELECT`、`INSERT`、`UPDATE`、`REFERENCES` 权限。更多信息参见[列级权限管理](/column-privilege-management.md)。 * 与 MySQL 类似，不存在 `NO_AUTO_CREATE_USER` sql 模式时，`GRANT` 语句将在用户不存在时自动创建一个空密码的新用户。删除此 sql-mode（默认情况下已启用）会带来安全风险。 * `GRANT ` 语句执行成功后，在 TiDB 中语句执行的结果会在当前连接立即生效，而 [MySQL 中部分权限的结果需要等到之后的连接才生效](https://dev.mysql.com/doc/refman/8.0/en/privilege-changes.html)。见 [TiDB #39356](https://github.com/pingcap/tidb/issues/39356)。 diff --git a/sql-statements/sql-statement-revoke-privileges.md b/sql-statements/sql-statement-revoke-privileges.md index 8f32a86ccd88..c16f982b684d 100644 --- a/sql-statements/sql-statement-revoke-privileges.md +++ b/sql-statements/sql-statement-revoke-privileges.md @@ -7,6 +7,8 @@ summary: TiDB 数据库中 REVOKE 的使用概况。 `REVOKE ` 语句用于删除已有用户的权限。执行 `REVOKE ` 语句需要拥有分配的权限，并且拥有 `GRANT OPTION` 权限。 +从 v8.5.6 版本开始，TiDB 支持兼容 MySQL 的列级权限管理机制，你可以在 `REVOKE` 中指定列名列表，例如，`REVOKE SELECT(col2) ON test.tbl FROM 'user'@'host';`。更多信息参见[列级权限管理](/column-privilege-management.md)。 + ## 语法图 ```ebnf+diagram diff --git a/sql-statements/sql-statement-select.md b/sql-statements/sql-statement-select.md index 9b065d664221..68dc60f5b4f2 100644 --- a/sql-statements/sql-statement-select.md +++ b/sql-statements/sql-statement-select.md @@ -106,7 +106,8 @@ TableSample ::= > **注意：** > -> TiDB 从 v6.6.0 版本开始支持[使用资源管控 (Resource Control) 实现资源组限制和流控](/tidb-resource-control-ru-groups.md)功能。该功能可以将不同优先级的语句放在不同的资源组中执行，并为这些资源组分配不同的配额和优先级，可以达到更好的资源管控效果。在开启资源管控功能后，语句的调度主要受资源组的控制，`HIGH_PRIORITY` 将不再生效。建议在支持资源管控的版本优先使用资源管控功能。 +> - TiDB 从 v8.5.6 版本开始支持在 `FOR UPDATE OF` 子句中使用表别名。为保持向后兼容性，在定义了别名的情况下，你仍然可以引用基础表名，但这会触发一条推荐使用显式别名的警告。当查询涉及不同数据库中具有相同名称的多张表时（例如 `FROM db1.t, db2.t FOR UPDATE OF t`），TiDB 现在会根据 `FROM` 子句中的顺序从左到右匹配目标表，而不是基于当前数据库的上下文。为避免歧义，建议在 `FOR UPDATE OF` 子句中指定数据库名称或使用表别名。 +> - TiDB 从 v6.6.0 版本开始支持[使用资源管控 (Resource Control) 实现资源组限制和流控](/tidb-resource-control-ru-groups.md)功能。该功能可以将不同优先级的语句放在不同的资源组中执行，并为这些资源组分配不同的配额和优先级，可以达到更好的资源管控效果。在开启资源管控功能后，语句的调度主要受资源组的控制，`HIGH_PRIORITY` 将不再生效。建议在支持资源管控的版本优先使用资源管控功能。 ## 示例 diff --git a/statistics.md b/statistics.md index 7ad3e745cb4b..f8015a092688 100644 --- a/statistics.md +++ b/statistics.md @@ -320,13 +320,17 @@ SHOW COLUMN_STATS_USAGE WHERE db_name = 'test' AND table_name = 't' AND last_ana ## 统计信息版本 +> **警告：** +> +> 从 v8.5.6 开始，统计信息版本 1 (`tidb_analyze_version = 1`) 已废弃，并将在未来的版本中移除。建议你使用统计信息版本 2 (`tidb_analyze_version = 2`)，并[将目前已有统计信息版本 1 的对象迁移至版本 2](#切换统计信息版本)。 + 系统变量 [`tidb_analyze_version`](/system-variables.md#tidb_analyze_version-从-v510-版本开始引入) 用于控制 TiDB 收集统计信息的行为。目前 TiDB 支持两个版本的统计信息，即 `tidb_analyze_version = 1` 和 `tidb_analyze_version = 2`。 - 从 v5.3.0 开始，变量 `tidb_analyze_version` 的默认值从 `1` 变为了 `2`。 - 如果从 v5.3.0 之前版本的集群升级至 v5.3.0 或之后的版本，该变量的默认值不会发生变化。 -更推荐选择 Version 2。Version 2 将继续增强，并最终完全取代 Version 1。与 Version 1 相比，Version 2 提高了大数据量场景下多项统计信息收集的准确性。此外，Version 2 在进行谓词选择率估算时不再需要收集 Count-Min Sketch 统计信息，并支持仅对选定列进行自动收集（参见[收集部分列的统计信息](#收集部分列的统计信息)），从而提高了收集性能。 +推荐使用统计信息版本 2 。与版本 1 相比，版本 2 提高了大数据量场景下多项统计信息的准确性。此外，版本 2 在进行谓词选择率估算时不再需要收集 Count-Min Sketch 统计信息，从而提高了收集性能。 以下表格列出了两个统计信息版本为优化器估算收集的信息： @@ -341,11 +345,11 @@ SHOW COLUMN_STATS_USAGE WHERE db_name = 'test' AND table_name = 't' AND last_ana ### 切换统计信息版本 -建议确保所有表、索引（和分区）使用相同版本的统计信息收集功能。推荐使用 Version 2，但不建议在没有正当理由（例如使用中的版本出现问题）的情况下切换版本。版本之间的切换可能需要一段时间，在此期间可能没有统计信息，直到所有表都使用了新版本进行统计。如果没有统计信息，可能会影响优化器的计划选择。 +建议所有表、索引和分区使用相同的统计信息版本。如果你的集群仍在使用统计信息版本 1，请尽快迁移至统计信息版本 2。在为某个对象（例如表、索引或分区）收集到 Version 2 的统计信息之前，TiDB 会继续使用该对象现有的 Version 1 统计信息。 -切换版本的正当理由可能包括：使用 Version 1 在收集 Count-Min Sketch 统计信息时，由于哈希冲突导致等值查询或 `IN` 查询谓词估算不准确。此时，你可以参考 [Count-Min Sketch](#count-min-sketch) 小节中描述的解决方案，或者设置 `tidb_analyze_version = 2` 并对所有对象重新运行 `ANALYZE`。在 Version 2 的早期阶段，执行 `ANALYZE` 后有内存溢出的风险，现在这个问题已经解决，但最初的解决方案是设置 `tidb_analyze_version = 1` 并对所有对象重新运行 `ANALYZE`。 +迁移的一个主要原因是，版本 1 可能对等值/IN 谓词产生不准确的估算，因为 Count-Min Sketch 可能存在哈希冲突。更多信息，请参阅 [Count-Min Sketch](#count-min-sketch)。为避免此问题，请设置 `tidb_analyze_version = 2` 并对所有对象重新运行 `ANALYZE`。 -要为切换统计信息版本做好 `ANALYZE` 准备，请根据情况进行以下操作： +要为从统计信息版本 1 迁移到统计信息版本 2 做好 `ANALYZE` 准备，请根据情况进行以下操作： - 如果 `ANALYZE` 语句是手动执行的，请手动统计每张需要统计的表： @@ -353,17 +357,10 @@ SHOW COLUMN_STATS_USAGE WHERE db_name = 'test' AND table_name = 't' AND last_ana SELECT DISTINCT(CONCAT('ANALYZE TABLE ', table_schema, '.', table_name, ';')) FROM information_schema.tables JOIN mysql.stats_histograms ON table_id = tidb_table_id - WHERE stats_ver = 2; + WHERE stats_ver = 1; ``` -- 如果 `ANALYZE` 语句是由 TiDB 自动执行的（当开启自动更新统计信息时），请执行以下语句生成 [`DROP STATS`](/sql-statements/sql-statement-drop-stats.md) 语句： - - ```sql - SELECT DISTINCT(CONCAT('DROP STATS ', table_schema, '.', table_name, ';')) - FROM information_schema.tables JOIN mysql.stats_histograms - ON table_id = tidb_table_id - WHERE stats_ver = 2; - ``` +- 如果 `ANALYZE` 语句是由 TiDB 自动执行的（当开启自动更新统计信息时），在你设置 `tidb_analyze_version = 2` 后，TiDB 会通过后续的 Auto Analyze 逐步将统计信息刷新至版本 2。在为某个对象收集到版本 2 的统计信息之前，TiDB 可以继续使用其现有的版本 1 统计信息。若要加速重要对象的迁移，请手动对其运行 `ANALYZE`。 - 如果上一条语句的返回结果太长，不方便复制粘贴，可以将结果导出到临时文件后，再执行： diff --git a/sync-diff-inspector/sync-diff-inspector-overview.md b/sync-diff-inspector/sync-diff-inspector-overview.md index b1326cccc5ba..ee6a4978f415 100644 --- a/sync-diff-inspector/sync-diff-inspector-overview.md +++ b/sync-diff-inspector/sync-diff-inspector-overview.md @@ -5,9 +5,11 @@ summary: sync-diff-inspector 是一个用于校验 MySQL/TiDB 中数据一致性 # sync-diff-inspector 用户文档 -[sync-diff-inspector](https://github.com/pingcap/tidb-tools/tree/master/sync_diff_inspector) 是一个用于校验 MySQL／TiDB 中两份数据是否一致的工具。该工具提供了修复数据的功能（适用于修复少量不一致的数据）。 +[sync-diff-inspector](https://github.com/pingcap/tiflow/tree/master/sync_diff_inspector) 是一个用于校验 MySQL／TiDB 中两份数据是否一致的工具。该工具提供了修复数据的功能（适用于修复少量不一致的数据）。 -主要功能： +本文介绍 sync-diff-inspector 的主要功能，并说明如何配置以及使用该工具。 + +## 主要功能 * 对比表结构和数据 * 如果数据不一致，则生成用于修复数据的 SQL 语句 @@ -16,12 +18,31 @@ summary: sync-diff-inspector 是一个用于校验 MySQL/TiDB 中数据一致性 * 支持 [TiDB 主从集群的数据校验](/ticdc/ticdc-upstream-downstream-check.md) * 支持[从 TiDB DM 拉取配置的数据校验](/sync-diff-inspector/dm-diff.md) -你可通过以下方式下载 sync-diff-inspector： +## 安装 sync-diff-inspector + +sync-diff-inspector 的安装方法取决于 TiDB 版本。 + +对于 TiDB v8.5.6 及以上版本，你可通过以下方式下载 sync-diff-inspector： + ++ 使用 TiUP 安装： + + ```shell + tiup install sync-diff-inspector + ``` + ++ 下载 Binary 包。sync-diff-inspector 的安装包位于 TiDB 离线工具包中。下载方式，请参考 [TiDB 工具下载](/download-ecosystem-tools.md)。 + ++ 使用 Docker 镜像。执行以下命令进行下载： + + ```shell + docker pull pingcap/sync-diff-inspector:latest + ``` + +对于 TiDB v8.5.6 之前版本，你可通过以下方式下载 sync-diff-inspector： -+ Binary 包。sync-diff-inspector 的安装包位于 TiDB 离线工具包中。下载方式，请参考 [TiDB 工具下载](/download-ecosystem-tools.md)。 -+ Docker 镜像。执行以下命令进行下载： ++ 下载来自 [`tidb-tools`](https://github.com/pingcap/tidb-tools) 仓库的 Binary 包。sync-diff-inspector 的安装包位于 TiDB 离线工具包中。下载方式，请参考 [TiDB 工具下载](/download-ecosystem-tools.md)。 - {{< copyable "shell-regular" >}} ++ 使用 Docker 镜像。执行以下命令进行下载： ```shell docker pull pingcap/tidb-tools:latest @@ -279,7 +300,7 @@ Average Speed: 113.277149MB/s - 下游数据库冗余行，则是 DELETE 语句 - 下游数据库行部分数据不一致，则是 REPLACE 语句，但会在 SQL 文件中通过注释的方法标明不同的列 -```SQL +```sql -- table: sbtest.sbtest99 -- range in sequence: (3690708) < (id) <= (3720581) /* diff --git a/system-variables.md b/system-variables.md index 6bf02400f2a0..65949969b558 100644 --- a/system-variables.md +++ b/system-variables.md @@ -544,6 +544,10 @@ mysql> SELECT * FROM t1; - 单位：秒 - 悲观事务语句等锁时间。 +### `InPacketBytes` 从 v8.5.6 版本开始引入 + +- 这个变量只做内部统计使用，对用户不可见。 + ### `interactive_timeout` - 作用域：SESSION | GLOBAL @@ -691,6 +695,10 @@ mysql> SHOW GLOBAL VARIABLES LIKE 'max_prepared_stmt_count'; - `1`：从 v6.6.0 版本开始引入，用于开启 TiFlash 带压缩的数据交换，详情参见 [MPP Version 和 Exchange 数据压缩](/explain-mpp.md#mpp-version-和-exchange-数据压缩)。 - `2`：从 v7.3.0 版本开始引入，用于确保在 TiFlash 执行出错的情况下，获取到准确的报错信息。 +### `OutPacketBytes` 从 v8.5.6 版本开始引入 + +- 这个变量只做内部统计使用，对用户不可见。 + ### `password_history` 从 v6.5.0 版本开始引入 - 作用域：GLOBAL @@ -987,6 +995,10 @@ MPP 是 TiFlash 引擎提供的分布式计算框架，允许节点之间的数 ### `tidb_analyze_version` 从 v5.1.0 版本开始引入 +> **警告：** +> +> 从 v8.5.6 开始，统计信息版本 1 (`tidb_analyze_version = 1`) 已废弃，并将在未来的版本中移除。建议使用 `tidb_analyze_version = 2`。 + - 作用域：SESSION | GLOBAL - 是否持久化到集群：是 - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 @@ -2683,6 +2695,15 @@ v5.0 后，用户仍可以单独修改以上系统变量（会有废弃警告） > > TiDB 从 v6.6.0 版本开始支持[使用资源管控 (Resource Control) 实现资源组限制和流控](/tidb-resource-control-ru-groups.md)功能。该功能可以将不同优先级的语句放在不同的资源组中执行，并为这些资源组分配不同的配额和优先级，可以达到更好的资源管控效果。在开启资源管控功能后，语句的调度主要受资源组的控制，`PRIORITY` 将不再生效。建议在支持资源管控的版本优先使用资源管控功能。 +### `tidb_foreign_key_check_in_shared_lock` 从 v8.5.6 版本开始引入 + +- 作用域：SESSION | GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 +- 类型：布尔型 +- 默认值：`OFF` +- 该变量用于控制在悲观事务中，外键约束检查对父表中的行加锁时是否使用共享锁（而非排他锁）。开启后，多个并发事务可以同时对同一父表行执行外键检查而不互相阻塞，从而降低锁冲突并提升子表并发写入性能。 + ### `tidb_gc_concurrency` 从 v5.0 版本开始引入 - 作用域：GLOBAL @@ -2954,11 +2975,11 @@ v5.0 后，用户仍可以单独修改以上系统变量（会有废弃警告） - 是否持久化到集群：是 - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 - 类型：布尔型 -- 默认值：`OFF` +- 默认值：`ON`。在 v8.5.6 之前，默认值为 `OFF`。 - 这个变量用来控制 TiDB 在生成执行计划摘要 (Plan Digest) 时，是否忽略不同查询中 `IN` 列表的元素差异。 - - 当为默认值 `OFF` 时，TiDB 在生成执行计划摘要时，不会忽略 `IN` 列表中的元素差异（包括元素数量差异）。`IN` 列表的元素差异将导致生成的执行计划摘要不同。 - - 当设置为 `ON` 时，TiDB 会忽略 `IN` 列表中的元素差异（包括元素数量差异），在执行计划摘要中使用 `...` 代替 `IN` 列表中的元素。此时，相同类型的 `IN` 查询会生成相同的执行计划摘要。 + - 当为默认值 `ON` 时，TiDB 在生成执行计划摘要时，会忽略 `IN` 列表中的元素差异（包括元素数量的差异），并使用 `...` 代替 `IN` 列表中的元素。此时，相同类型的 `IN` 查询会生成相同的执行计划摘要。 + - 当设置为 `OFF` 时，TiDB 在生成执行计划摘要时，不会忽略 `IN` 列表中的元素差异（包括元素数量的差异）。`IN` 列表中的元素差异会导致生成的执行计划摘要不同。 ### `tidb_ignore_prepared_cache_close_stmt` 从 v6.0.0 版本开始引入 @@ -3305,6 +3326,22 @@ v5.0 后，用户仍可以单独修改以上系统变量（会有废弃警告） - 范围：`[100, 16384]` - 这个变量用来设置缓存 schema 版本信息（对应版本修改的相关 table IDs）的个数限制，可设置的范围 100 - 16384。此变量在 2.1.18 及之后版本支持。 +### `tidb_max_dist_task_nodes` 从 v8.5.6 版本开始引入 + +- 作用域：SESSION | GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 +- 类型：整数型 +- 默认值：`-1` +- 范围：`-1` 或 `[1, 128]` +- 该变量用于定义分布式框架任务可使用的 TiDB 节点数上限。默认值为 `-1`，表示启用自动模式。在自动模式下，TiDB 将按照 `min(3, tikv_nodes / 3)` 动态地计算该值，其中 `tikv_nodes` 表示集群中 TiKV 节点的数量。 + +> **注意：** +> +> 如果部分 TiDB 节点显式设置了 [`tidb_service_scope`](#tidb_service_scope-从-v740-版本开始引入)，则分布式执行框架仅会将任务调度到这些节点中执行。此时，即使 `tidb_max_dist_task_nodes` 设置了更大的值，实际使用的 TiDB 节点数也不会超过显式设置了 `tidb_service_scope` 的 TiDB 节点数。 +> +> 例如，集群有 10 个 TiDB 节点，其中 4 个节点均设置了 `tidb_service_scope = group1`。此时即使设置 `tidb_max_dist_task_nodes = 5`，实际参与任务执行的节点数仍为 4。 + ### `tidb_max_paging_size` 从 v6.3.0 版本开始引入 - 作用域：SESSION | GLOBAL @@ -3831,6 +3868,17 @@ mysql> desc select count(distinct a) from test.t; - 这个变量用来控制 TiDB Join Reorder 算法的选择。当参与 Join Reorder 的节点个数大于该阈值时，TiDB 选择贪心算法，小于该阈值时 TiDB 选择动态规划 (dynamic programming) 算法。 - 目前对于 OLTP 的查询，推荐保持默认值。对于 OLAP 的查询，推荐将变量值设为 10~15 来获得 AP 场景下更好的连接顺序。 +### `tidb_opt_join_reorder_through_sel` 从 v8.5.6 版本开始引入 + +- 作用域：SESSION | GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：是 +- 类型：布尔型 +- 默认值：`OFF` +- 该变量用于提升部分多表 JOIN 查询的连接顺序优化 (Join Reorder) 效果。当该变量值为 `ON` 时，在满足安全条件的前提下，优化器会将多个连续 JOIN 之间的过滤条件 (`Selection`) 一并纳入连接顺序优化的候选范围。在重建 JOIN 树时，优化器会将这些条件下推至更合适的位置，从而使更多表参与连接顺序优化。 +- 如果开启后出现性能回退或执行计划不稳定，建议将该变量设置为 `OFF` 以关闭此功能。 +- 对于包含非确定性函数或具有副作用的过滤条件（例如 `RAND()`），即使开启该变量，优化器也不会执行条件下推操作，以保证表达式的求值语义不变。 + ### `tidb_opt_limit_push_down_threshold` - 作用域：SESSION | GLOBAL @@ -4028,6 +4076,73 @@ mysql> desc select count(distinct a) from test.t; +----------------------------------+---------+-----------+----------------------+-------------------------------------+ ``` +### `tidb_opt_partial_ordered_index_for_topn` 从 v8.5.6 版本开始引入 + +- 作用域：SESSION | GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：是 +- 类型：枚举型 +- 默认值：`DISABLE` +- 可选值：`DISABLE`、`COST` +- 用于控制当查询包含 `ORDER BY ... LIMIT` 时，优化器是否可以利用索引的部分有序性 (partial order) 来优化 TopN 计算过程。当排序列与索引顺序一致时（例如排序列本身是索引列，或该列使用了前缀索引），通过索引扫描得到的数据在该列上已经具有一定的顺序（即“部分有序”）。在这种情况下，优化器可以在扫描过程中逐步构建 TopN 结果，并在满足 `LIMIT` 后提前停止扫描，从而减少排序计算开销。 +- 适用场景：`ORDER BY ... LIMIT` 的排序列为较长字符串且仅建立了前缀索引时，如需减少 TopN 排序开销时，可以通过将该变量设置为 `COST` 并在查询中指定 `USE INDEX` 或 `FORCE INDEX` Hint 以应用 partial order TopN 优化。 + + - 该变量默认值为 `DISABLE`，代表关闭 partial order TopN 优化。此时，优化器将直接使用常规的全局排序 TopN 方式。 + - 如需强制应用 partial order TopN 优化，请将该变量设置为 `COST` 并在查询中通过 `USE INDEX` 或 `FORCE INDEX` Hint 指定满足条件的索引。如果指定的索引不满足该优化的前置条件（例如 `ORDER BY` 与索引前缀不匹配，或者查询中存在不支持的排序形式），即使该变量设置为 `COST` 也可能无法应用该优化，执行计划会退化为常规的 TopN 方式。 + + > **注意：** + > + > 目前优化器尚不支持根据 cost model 动态选择是否应用 partial order TopN 优化。如果只将该变量设置为 `COST` 而不指定 `USE INDEX` 或 `FORCE INDEX` Hint，优化器可能不会应用 partial order TopN 优化。如需强制应用该优化，请结合 `USE INDEX` 或 `FORCE INDEX` Hint 一起使用。 + +
+查看 partial order TopN 优化示例 + +创建表 `t_varchar`，并在字符串列 `name` 上定义了前缀索引 `idx_name_prefix(name(10))`： + +```sql +CREATE TABLE t_varchar ( + id INT PRIMARY KEY, + name VARCHAR(255), + INDEX idx_name_prefix(name(10)) +); +``` + +- 强制应用 partial order TopN 优化（`COST` + `USE INDEX`）： + + ```sql + > SET SESSION tidb_opt_partial_ordered_index_for_topn = 'COST'; + + > EXPLAIN FORMAT='brief' SELECT /*+ use_index(t_varchar, idx_name_prefix) */ * + FROM t_varchar ORDER BY name LIMIT 5; + +-------------------------------------------+---------+-----------+------------------------------+----------------------------------------------------------------------------------------------+ + | id | estRows | task | access object | operator info | + +-------------------------------------------+---------+-----------+------------------------------+----------------------------------------------------------------------------------------------+ + | TopN | 5.00 | root | | planner__core__partial_order_topn.t_varchar.name, offset:0, count:5, prefix_col:planner__core__partial_order_topn.t_varchar.name, prefix_len:10 | + | └─IndexLookUp | 5.00 | root | | | + | ├─Limit(Build) | 5.00 | cop[tikv] | | offset:0, count:5, prefix_col:planner__core__partial_order_topn.t_varchar.name, prefix_len:10 | + | │ └─IndexFullScan | 10000.00| cop[tikv] | table:t_varchar, index:idx_name_prefix(name) | keep order:true, stats:pseudo | + | └─TableRowIDScan(Probe) | 5.00 | cop[tikv] | table:t_varchar | keep order:false, stats:pseudo | + +-------------------------------------------+---------+-----------+------------------------------+----------------------------------------------------------------------------------------------+ + ``` + +- 关闭 partial order TopN 优化（`DISABLE`）： + + ```sql + > SET SESSION tidb_opt_partial_ordered_index_for_topn = 'DISABLE'; + + > EXPLAIN FORMAT='brief' SELECT * FROM t_varchar ORDER BY name LIMIT 5; + +---------------------------+---------+-----------+---------------------+----------------------------------------------------+ + | id | estRows | task | access object | operator info | + +---------------------------+---------+-----------+---------------------+----------------------------------------------------+ + | TopN | 5.00 | root | | planner__core__partial_order_topn.t_varchar.name, offset:0, count:5 | + | └─TableReader | 5.00 | root | data:TopN | | + | └─TopN | 5.00 | cop[tikv] | | planner__core__partial_order_topn.t_varchar.name, offset:0, count:5 | + | └─TableFullScan | 10000.00| cop[tikv] | table:t_varchar | keep order:false, stats:pseudo | + +---------------------------+---------+-----------+---------------------+----------------------------------------------------+ + ``` + +
+ ### `tidb_opt_prefer_range_scan` 从 v5.0 版本开始引入 > **注意：** @@ -4956,7 +5071,7 @@ EXPLAIN FORMAT='brief' SELECT COUNT(1) FROM t WHERE a = 1 AND b IS NOT NULL; - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 - 类型：字符串 - 默认值："" -- 可选值：长度小于或等于 64 的字符串，可用合法字符包括数字 `0-9`、字母 `a-zA-Z`、下划线 `_` 和连字符 `-` +- 可选值：长度小于或等于 64 的字符串，可用合法字符包括数字 `0-9`、字母 `a-zA-Z`、下划线 `_` 和连字符 `-`。从 v8.5.6 开始，该变量的取值大小写不敏感，TiDB 会将输入值转换为小写形式进行存储和比较。 - 该变量是一个实例级别的变量，用于控制 [TiDB 分布式执行框架](/tidb-distributed-execution-framework.md)下各 TiDB 节点的服务范围。分布式执行框架会根据该变量的值决定将分布式任务调度到哪些 TiDB 节点上执行，具体规则请参考[任务调度](/tidb-distributed-execution-framework.md#任务调度)。 ### `tidb_session_alias` 从 v7.4.0 版本开始引入 @@ -5063,6 +5178,34 @@ Query OK, 0 rows affected, 1 warning (0.00 sec) > > 跳过字符检查可能会使 TiDB 检测不到应用写入的非法 UTF-8 字符，进一步导致执行 `ANALYZE` 时解码错误，以及引入其他未知的编码问题。如果应用不能保证写入字符串的合法性，不建议跳过该检查。 +### `tidb_slow_log_max_per_sec` 从 v8.5.6 版本开始引入 + +- 作用域：GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 +- 默认值：`0` +- 类型：整数型 +- 范围：`[0, 1000000]` +- 控制每个 TiDB 节点每秒打印的慢查询日志的数量上限。 + - 当值为 `0` （默认值）时，表示不限制每秒打印的慢查询日志数量。 + - 当值大于 `0` 时，TiDB 每秒最多打印指定数量的慢查询日志，超过部分将被丢弃，不会写入慢查询日志文件。 +- 该变量常与 [`tidb_slow_log_rules`](#tidb_slow_log_rules-从-v856-版本开始引入) 结合使用，以防止在高负载情况下产生过多的慢查询日志。 + +### `tidb_slow_log_rules` 从 v8.5.6 版本开始引入 + +- 作用域：SESSION | GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 +- 默认值："" +- 类型：字符串 +- 用于定义慢查询日志的触发规则，支持基于多维度指标的组合条件，实现更加灵活和精细化的日志记录控制。 +- 关于该系统变量的详细使用方法，请参考 [`tidb_slow_log_rules` 使用方法](/identify-slow-queries.md#tidb_slow_log_rules-使用方法)。 + +> **Tip:** +> +> - 在生产环境启用 `tidb_slow_log_rules` 时，建议同时配置 [`tidb_slow_log_max_per_sec`](#tidb_slow_log_max_per_sec-从-v856-版本开始引入)，避免慢查询日志打印过于频繁。 +> - 规则建议先从较严格条件开始，再按排障需求逐步放宽。更多性能影响介绍，请参考[使用建议](/identify-slow-queries.md#使用建议)。 + ### `tidb_slow_log_threshold` - 作用域：GLOBAL diff --git a/ticdc/ticdc-architecture.md b/ticdc/ticdc-architecture.md index 3793ed23230a..eee5f47388f3 100644 --- a/ticdc/ticdc-architecture.md +++ b/ticdc/ticdc-architecture.md @@ -64,7 +64,17 @@ TiCDC 新架构通过将整体架构拆分成有状态和无状态的两部分 > **注意：** > -> 针对 MySQL Sink 的 Changefeed，除了满足上述任一条件，表还需要满足**有且仅有一个主键或非空唯一键**，才可以被 TiCDC 拆分并分发，以保证拆表模式下数据同步的正确性。 +> 针对 MySQL Sink 的 Changefeed，除了满足上述任一条件，表还需要满足**有且仅有一个主键或非空唯一键**，才可以被 TiCDC 拆分并分发，以保证表级任务拆分模式下数据同步的正确性。 + +### 表级任务拆分配置建议 + +切换至 TiCDC 新架构后，不建议继续使用老架构中的拆表相关配置。在绝大多数场景下，建议先采用新架构的默认配置。仅在存在同步性能瓶颈或调度不均的特殊场景下，再基于默认值进行小幅调整。 + +在拆表模式下，建议重点关注以下配置项： + +- [`scheduler.region-threshold`](/ticdc/ticdc-changefeed-config.md#region-threshold)：默认值为 `10000`。当表的 Region 数量超过该阈值时，TiCDC 会对该表执行拆分。对于 Region 数量较少但表整体写入流量较高的场景，可以适当降低该值。该参数必须大于或等于 `scheduler.region-count-per-span`，否则可能导致任务频繁调度，并增加同步延迟。 +- [`scheduler.region-count-per-span`](/ticdc/ticdc-changefeed-config.md#region-count-per-span-从-v854-版本开始引入)：默认值为 `100`。在 Changefeed 初始化阶段，满足拆分条件的表会按照该参数进行拆分。拆分后，每个子表最多包含 `region-count-per-span` 个 Region。 +- [`scheduler.write-key-threshold`](/ticdc/ticdc-changefeed-config.md#write-key-threshold)：默认值为 `0`（表示关闭）。当表的 Sink 写入流量超过该阈值时，TiCDC 会触发拆分。建议保持默认值 `0`。 ## 兼容性说明 diff --git a/ticdc/ticdc-changefeed-config.md b/ticdc/ticdc-changefeed-config.md index 9311c19c306b..073c84b5025c 100644 --- a/ticdc/ticdc-changefeed-config.md +++ b/ticdc/ticdc-changefeed-config.md @@ -161,6 +161,11 @@ Info: {"upstream_id":7178706266519722477,"namespace":"default","id":"simple-repl - 默认为 `false`。设置为 `true` 以打开该功能。 - 默认值：`false` +#### `region-count-per-span` 从 v8.5.4 版本开始引入 + +- 在 [TiCDC 新架构](/ticdc/ticdc-architecture.md)中引入。在 Changefeed 初始化阶段，满足拆分条件的表会按照该参数进行拆分。拆分后，每个子表最多包含 `region-count-per-span` 个 Region。 +- 默认值：`100`。 + #### `region-threshold` - 默认值：对于 [TiCDC 新架构](/ticdc/ticdc-architecture.md)，默认值为 `10000`；对于 [TiCDC 老架构](/ticdc/ticdc-classic-architecture.md)，默认值为 `100000`。 diff --git a/ticdc/ticdc-csv.md b/ticdc/ticdc-csv.md index fcb578cf41ee..d6d3006b2a74 100644 --- a/ticdc/ticdc-csv.md +++ b/ticdc/ticdc-csv.md @@ -29,6 +29,7 @@ null = '\N' include-commit-ts = true binary-encoding-method = 'base64' output-old-value = false +output-field-header = false # 从 v8.5.6 开始引入，仅适用于 TiCDC 新架构 ``` ## 数据保存的事务性约束 @@ -52,6 +53,12 @@ CSV 文件中，单行的每一列定义如下： - 第五列：`is-update`，该列仅在 `output-old-value` 为 true 时存在，用于标识该行变更来自 Update 事件（值为 true），还是来自 Insert/Delete 事件（值为 false）。 - 第六列至最后一列：变更数据的列，可为一列或多列。 +对于 [TiCDC 新架构](/ticdc/ticdc-architecture.md)，当配置中 `output-field-header = true` 时，CSV 文件将包含一个表头行，表头行的列名如下： + +| 第一列 | 第二列 | 第三列 | 第四列（可选） | 第五列（可选） | 第六列 | ... | 最后一列 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `ticdc-meta$operation` | `ticdc-meta$table` | `ticdc-meta$schema` | `ticdc-meta$commit-ts` | `ticdc-meta$is-update` | 涉及数据变更的第一列的列名 | ... | 涉及数据变更的最后一列的列名 | + 假设某张表 `hr.employee` 的定义如下： ```sql @@ -86,6 +93,19 @@ CREATE TABLE `employee` ( "I","employee","hr",433305438660591630,true,102,"Alex","Alice","2018-06-15","Beijing" ``` +当配置中 `include-commit-ts = true` 且 `output-old-value = true` 且 `output-field-header = true` 时，该表上的 DML 事件以 CSV 格式存储后如下所示： + +```csv +ticdc-meta$operation,ticdc-meta$table,ticdc-meta$schema,ticdc-meta$commit-ts,ticdc-meta$is-update,Id,LastName,FirstName,HireDate,OfficeLocation +"I","employee","hr",433305438660591626,false,101,"Smith","Bob","2014-06-04","New York" +"D","employee","hr",433305438660591627,true,101,"Smith","Bob","2015-10-08","Shanghai" +"I","employee","hr",433305438660591627,true,101,"Smith","Bob","2015-10-08","Los Angeles" +"D","employee","hr",433305438660591629,false,101,"Smith","Bob","2017-03-13","Dallas" +"I","employee","hr",433305438660591630,false,102,"Alex","Alice","2017-03-14","Shanghai" +"D","employee","hr",433305438660591630,true,102,"Alex","Alice","2017-03-14","Beijing" +"I","employee","hr",433305438660591630,true,102,"Alex","Alice","2018-06-15","Beijing" +``` + ## 数据类型映射 | MySQL 类型 | CSV 类型 | 示例 | 描述 | diff --git a/tidb-resource-control-background-tasks.md b/tidb-resource-control-background-tasks.md index 7d7dae163573..c5c128c2cc83 100644 --- a/tidb-resource-control-background-tasks.md +++ b/tidb-resource-control-background-tasks.md @@ -4,15 +4,14 @@ summary: 介绍如何通过资源管控 (Resource Control) 控制后台任务。 --- # 使用资源管控 (Resource Control) 管理后台任务 -> **警告：** -> -> - 该功能目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请[提交 issue](/support.md) 反馈。 -> - 资源管控的后台任务管理是基于 TiKV 的 CPU/IO 的资源利用率动态调整资源配额的，因此它依赖各个实例可用资源上限 (Quota)。如果在单个服务器混合部署多个组件或实例，需要通过 `cgroup` 为各个实例设置合适的资源上限 (Quota)。TiUP Playground 等共享资源的配置很难表现出预期效果。 - 后台任务是指那些优先级不高但是需要消耗大量资源的任务，如数据备份和自动统计信息收集等。这些任务通常定期或不定期触发，在执行的时候会消耗大量资源，从而影响在线的高优先级任务的性能。 自 v7.4.0 开始，[TiDB 资源管控](/tidb-resource-control-ru-groups.md)引入了对后台任务的管理。当一种任务被标记为后台任务时，TiKV 会动态地限制该任务的资源使用，以尽量避免此类任务在执行时对其他前台任务的性能产生影响。TiKV 通过实时地监测所有前台任务所消耗的 CPU 和 IO 等资源，并根据实例总的资源上限计算出后台任务可使用的资源阈值，所有后台任务在执行时会受此阈值的限制。 +> *注意：** +> +> 资源管控的后台任务管理是基于 TiKV 的 CPU/IO 的资源利用率动态调整资源配额的，因此它依赖各个实例可用资源上限 (Quota)。如果在单个服务器混合部署多个组件或实例，需要通过 `cgroup` 为各个实例设置合适的资源上限 (Quota)。TiUP Playground 等共享资源的配置很难表现出预期效果。 + ## `BACKGROUND` 参数说明 - `TASK_TYPES`：设置需要作为后台任务管理的任务类型，多个任务类型以 `,` 分隔。 @@ -20,7 +19,7 @@ summary: 介绍如何通过资源管控 (Resource Control) 控制后台任务。 目前 TiDB 支持如下几种后台任务的类型： -- `lightning`：使用 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 或 [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) 执行导入任务。同时支持 TiDB Lightning 的物理和逻辑导入模式。 +- `import`：使用 [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md) 或 [`IMPORT INTO`](/sql-statements/sql-statement-import-into.md) 执行导入任务。同时支持 TiDB Lightning 的物理和逻辑导入模式。 - `br`：使用 [BR](/br/backup-and-restore-overview.md) 执行数据备份和恢复。目前不支持 PITR。 - `ddl`：对于 Reorg DDL，控制批量数据回写阶段的资源使用。 - `stats`：对应手动执行或系统自动触发的[收集统计信息](/statistics.md#收集统计信息)任务。 diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 319f3bfe8726..04944ed258ea 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -2347,6 +2347,23 @@ Raft Engine 相关的配置项。 + 控制是否强制对 RocksDB 最底层文件进行 compaction。 + 默认值：`true` +### `mvcc-read-aware-enabled` 从 v8.5.6 版本开始引入 + ++ 控制是否启用 MVCC-read-aware compaction。启用后，TiKV 会跟踪读取请求期间扫描的 MVCC 版本数量，并利用这些信息优先对 MVCC 读取放大率高的 Region 进行 compaction。这可以降低在扫描期间遇到大量过期版本的热点 Region 的读延迟。 ++ 默认值：`false` + +### `mvcc-scan-threshold` 从 v8.5.6 版本开始引入 + ++ 将 Region 标记为 compaction 候选所需的每个读请求扫描的最小 MVCC 版本数量。此配置项仅在 [`mvcc-read-aware-enabled`](#mvcc-read-aware-enabled-从-v856-版本开始引入) 设置为 `true` 时生效。 ++ 默认值：`1000` ++ 最小值：`0` + +### `mvcc-read-weight` 从 v8.5.6 版本开始引入 + ++ 计算 Region 的 compaction 优先级得分时，应用于 MVCC 读取活动的权重倍数。较高的数值会提高 MVCC 读放大在整体评估中的权重，相对于其他 compaction 触发因素（例如 tombstone 密度）占比更大。该配置项仅在 [`mvcc-read-aware-enabled`](#mvcc-read-aware-enabled-从-v856-版本开始引入) 设置为 `true` 时生效。 ++ 默认值：`3.0` ++ 最小值：`0.0` + ## backup 用于 BR 备份相关的配置项。 @@ -2647,6 +2664,24 @@ Raft Engine 相关的配置项。 + 在默认的一个 TSO 物理时钟更新周期内 (50ms)，PD 最多提供 262144 个 TSO，超过这个数量后 PD 会暂缓 TSO 请求的处理。这个配置用于避免 PD 的 TSO 消耗殆尽、影响其他业务的使用。如果增大这个参数，建议同时减小 PD 的 [`tso-update-physical-interval`](/pd-configuration-file.md#tso-update-physical-interval) 参数，以获得足够的 TSO。 + 默认值：8192 +## resource-metering + +资源计量 (Resource Metering) 相关的配置项。 + +### `enable-network-io-collection` 从 v8.5.6 版本开始引入 + ++ 是否在 [Top SQL](/dashboard/top-sql.md) 中除了采集 CPU 数据外，还额外采集 TiKV 的网络流量和逻辑 I/O 信息。 ++ 开启后，TiKV 在处理请求时会额外记录这些指标：网络入站字节数、网络出站字节数、逻辑读字节数和逻辑写字节数。 ++ 上报资源消耗时，TiKV 会基于 CPU 时间、网络流量和逻辑 I/O 来筛选 Top N 记录，并额外按 Region 维度上报这些统计结果，便于更细粒度地分析热点请求或资源消耗来源。 ++ 默认值：false + +> **注意：** +> +> 逻辑 I/O 与物理 I/O 含义不同，两者不能直接对应： +> +> - 逻辑 I/O 指 TiKV 存储层处理请求时涉及的逻辑数据量，例如读取过程中扫描或处理的数据量，以及写请求自身的逻辑写入字节数。 +> - 物理 I/O 指底层存储设备实际发生的磁盘读写流量，会受到 block cache、compaction、flush 等因素的影响。 + ## resource-control 资源控制 (Resource Control) 在 TiKV 存储层相关的配置项。 diff --git a/upgrade-tidb-using-tiup.md b/upgrade-tidb-using-tiup.md index c60ad59b6cae..a9b8d8e6c2e1 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -70,6 +70,7 @@ summary: TiUP 可用于 TiDB 升级。升级过程中需注意不支持 TiFlash - TiDB v8.5.3 [兼容性变更](/releases/release-8.5.3.md#兼容性变更) - TiDB v8.5.4 [兼容性变更](/releases/release-8.5.4.md#兼容性变更) - TiDB v8.5.5 [兼容性变更](/releases/release-8.5.5.md#兼容性变更) +- TiDB v8.5.6 [兼容性变更](https://docs.pingcap.com/zh/tidb/stable/release-8.5.6/#兼容性变更) ### 2.2 升级 TiUP 或更新 TiUP 离线镜像 diff --git a/variables.json b/variables.json index a1b25b8aa78e..5403115ffd15 100644 --- a/variables.json +++ b/variables.json @@ -1,8 +1,8 @@ { "tidb": "TiDB", - "tidb-version": "8.5.5", + "tidb-version": "8.5.6", "tidb-operator-version": "v1.6.4", - "tidb-release-date": "2026-01-15", + "tidb-release-date": "2026-04-14", "starter": "TiDB Cloud Starter", "essential": "TiDB Cloud Essential", "dedicated": "TiDB Cloud Dedicated",