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/dm/dm-compatibility-catalog.md b/dm/dm-compatibility-catalog.md index 1ea5b6a1c797..23b6291ada8f 100644 --- a/dm/dm-compatibility-catalog.md +++ b/dm/dm-compatibility-catalog.md @@ -19,9 +19,9 @@ 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 | 实验支持 | | 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/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/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..278867472f43 100644 --- a/system-variables.md +++ b/system-variables.md @@ -987,6 +987,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) 控制：否 @@ -3305,6 +3309,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 +3851,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 @@ -4956,7 +4987,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 +5094,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/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..2e07eb22aa48 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 备份相关的配置项。