diff --git a/TOC.md b/TOC.md index 79adf0d7ef7f..6c3a88160563 100644 --- a/TOC.md +++ b/TOC.md @@ -241,6 +241,7 @@ - [使用概述](/br/br-use-overview.md) - [快照备份与恢复](/br/br-snapshot-guide.md) - [日志备份与 PITR](/br/br-pitr-guide.md) + - [压缩日志备份](/br/br-compact-log-backup.md) - [实践示例](/br/backup-and-restore-use-cases.md) - [备份存储](/br/backup-and-restore-storages.md) - br cli 命令手册 @@ -882,6 +883,7 @@ - [`SET ROLE`](/sql-statements/sql-statement-set-role.md) - [`SET TRANSACTION`](/sql-statements/sql-statement-set-transaction.md) - [`SET `](/sql-statements/sql-statement-set-variable.md) + - [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) - [`SHOW [BACKUPS|RESTORES]`](/sql-statements/sql-statement-show-backups.md) - [`SHOW ANALYZE STATUS`](/sql-statements/sql-statement-show-analyze-status.md) - [`SHOW BINDINGS`](/sql-statements/sql-statement-show-bindings.md) @@ -999,6 +1001,7 @@ - [临时表](/temporary-tables.md) - [缓存表](/cached-tables.md) - [外键约束](/foreign-key.md) + - [表级数据亲和性](/table-affinity.md) - 字符集和排序规则 - [概述](/character-set-and-collation.md) - [GBK](/character-set-gbk.md) diff --git a/best-practices/pd-scheduling-best-practices.md b/best-practices/pd-scheduling-best-practices.md index 963d308f2f16..9a8f0e82e50d 100644 --- a/best-practices/pd-scheduling-best-practices.md +++ b/best-practices/pd-scheduling-best-practices.md @@ -296,7 +296,9 @@ Region Merge 速度慢也很有可能是受到 limit 配置的限制（`merge-sc 实践中，如果能确定这个节点的故障是不可恢复的，可以立即做下线处理，这样 PD 能尽快补齐副本，降低数据丢失的风险。与之相对，如果确定这个节点是能恢复的，但可能半小时之内来不及，则可以把 `max-store-down-time` 临时调整为比较大的值，这样能避免超时之后产生不必要的副本补充，造成资源浪费。 -自 v5.2.0 起，TiKV 引入了慢节点检测机制。通过对 TiKV 中的请求进行采样，计算出一个范围在 1~100 的分数。当分数大于等于 80 时，该 TiKV 节点会被设置为 slow 状态。可以通过添加 [`evict-slow-store-scheduler`](/pd-control.md#scheduler-show--add--remove--pause--resume--config--describe) 来针对慢节点进行对应的检测和调度。当检测到有且只有一个 TiKV 节点为慢节点，并且该 TiKV 的 slow score 到达限定值（默认 80）时，将节点上的 Leader 驱逐（其作用类似于 `evict-leader-scheduler`）。 +自 v5.2.0 起，TiKV 引入了磁盘的慢节点检测机制。通过对 TiKV 中的请求进行采样，计算出一个范围在 1~100 的分数。当分数大于等于 80 时，该 TiKV 节点会被设置为 slow 状态。可以通过添加 [`evict-slow-store-scheduler`](/pd-control.md#scheduler-show--add--remove--pause--resume--config--describe) 来针对慢节点进行对应的调度。当检测到有且只有一个 TiKV 节点为慢节点，并且该 TiKV 的 slow score 到达限定值（默认 80）时，将节点上的 Leader 驱逐（其作用类似于 `evict-leader-scheduler`）。 + +自 v8.5.5 起，TiKV 引入了网络的慢节点检测机制。与磁盘慢节点检测类似，该机制通过在 TiKV 节点之间进行网络延时探测并计算分数，来判断节点的网络是否出现异常。可以通过 [`enable-network-slow-store`](/pd-control.md#scheduler-config-evict-slow-store-scheduler) 来开启该机制。 > **注意：** > diff --git a/br/backup-and-restore-overview.md b/br/backup-and-restore-overview.md index f26adbf76d1b..8eec37deae2a 100644 --- a/br/backup-and-restore-overview.md +++ b/br/backup-and-restore-overview.md @@ -21,7 +21,6 @@ TiDB 备份恢复功能可以用于满足以下业务的需求： ### 使用限制 - PITR 仅支持恢复到**全新的空集群**。 -- PITR 仅支持集群粒度的恢复，不支持对单个 database 或 table 的恢复。 - PITR 不支持恢复系统表中用户表和权限表的数据。 - 不支持在一个集群上**同时**运行多个数据备份任务。 - 不建议备份正在恢复的表，这样备份的数据可能存在异常。 diff --git a/br/backup-and-restore-storages.md b/br/backup-and-restore-storages.md index 7185831ad7a4..db456a6db067 100644 --- a/br/backup-and-restore-storages.md +++ b/br/backup-and-restore-storages.md @@ -202,6 +202,66 @@ tiup br restore db --db test -u "${PD_IP}:2379" \ --storage "azure://external/backup-20220915?account-name=${account-name}" ``` +- 方式四：使用 Azure 托管标识 (Managed Identity) + + 从 v8.5.5 起，如果你的 TiDB 集群和 br 命令行工具运行在 Azure 虚拟机 (VM) 或 Azure Kubernetes Service (AKS) 环境中，并且已为节点分配了 Azure 托管标识，则可以使用 Azure 托管标识进行鉴权。 + + 使用此方式前，请确保已在 [Azure Portal](https://azure.microsoft.com/) 中为对应的托管标识授予目标存储账户的访问权限（如 `Storage Blob Data Contributor`）。 + + - **系统分配的托管标识 (System-assigned)**： + + 使用系统分配的托管标识时，无需配置任何 Azure 相关环境变量，直接运行 br 备份命令即可。 + + ```shell + tiup br backup full -u "${PD_IP}:2379" \ + --storage "azure://external/backup-20220915?account-name=${account-name}" + ``` + + > **注意：** + > + > 请确保运行环境中**不存在** `AZURE_CLIENT_ID`、`AZURE_TENANT_ID` 或 `AZURE_CLIENT_SECRET` 环境变量，否则 Azure SDK 可能会优先使用其他认证方式，导致托管标识未生效。 + + - **用户分配的托管标识 (User-assigned)**： + + 使用用户分配的托管标识时，需要在 TiKV 运行环境和 br 命令行工具运行环境中配置环境变量 `AZURE_CLIENT_ID` （其值为该托管标识的 Client ID），然后再执行 br 备份命令。具体步骤如下： + + 1. 使用 TiUP 启动时为 TiKV 配置 Client ID： + + 以下步骤以 TiKV 端口 `24000`、systemd 服务名 `tikv-24000` 为例： + + 1. 执行以下命令进入服务配置编辑界面： + + ```shell + systemctl edit tikv-24000 + ``` + + 2. 配置 `AZURE_CLIENT_ID` 环境变量： + + ```ini + [Service] + Environment="AZURE_CLIENT_ID=" + ``` + + 3. 重新加载 systemd 配置并重启 TiKV： + + ```shell + systemctl daemon-reload + systemctl restart tikv-24000 + ``` + + 2. 为 br 命令行工具配置 `AZURE_CLIENT_ID` 环境变量： + + ```shell + export AZURE_CLIENT_ID="" + ``` + + 3. 使用 br 命令行工具将数据备份至 Azure Blob Storage： + + ```shell + tiup br backup full -u "${PD_IP}:2379" \ + --storage "azure://external/backup-20220915?account-name=${account-name}" + ``` + diff --git a/br/backup-and-restore-use-cases.md b/br/backup-and-restore-use-cases.md index a46c08a8731e..5112ce4c7050 100644 --- a/br/backup-and-restore-use-cases.md +++ b/br/backup-and-restore-use-cases.md @@ -140,7 +140,9 @@ tiup br restore point --pd="${PD_IP}:2379" \ --full-backup-storage='s3://tidb-pitr-bucket/backup-data/snapshot-20220514000000' \ --restored-ts '2022-05-15 18:00:00+0800' -Full Restore <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Split&Scatter Region <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Download&Ingest SST <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Restore Pipeline <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% [2022/05/29 18:15:39.132 +08:00] [INFO] [collector.go:69] ["Full Restore success summary"] [total-ranges=12] [ranges-succeed=xxx] [ranges-failed=0] [split-region=xxx.xxxµs] [restore-ranges=xxx] [total-take=xxx.xxxs] [restore-data-size(after-compressed)=xxx.xxx] [Size=xxxx] [BackupTS={TS}] [total-kv=xxx] [total-kv-size=xxx] [average-speed=xxx] Restore Meta Files <--------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% Restore KV Files <----------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% diff --git a/br/br-checkpoint-restore.md b/br/br-checkpoint-restore.md index 8bca50bb64d9..40427d85216b 100644 --- a/br/br-checkpoint-restore.md +++ b/br/br-checkpoint-restore.md @@ -15,7 +15,7 @@ summary: 了解断点恢复功能，包括它的使用场景、实现原理以 ## 实现原理 -断点恢复的实现原理分为快照恢复和日志恢复两部分。具体实现细节请参考[实现细节](#实现细节)。 +断点恢复的实现原理分为快照恢复和日志恢复两部分。具体实现细节请参考[实现细节：将断点数据存储在下游集群](#实现细节将断点数据存储在下游集群)和[实现细节：将断点数据存储在外部存储](#实现细节将断点数据存储在外部存储)。 ### 快照恢复 @@ -65,7 +65,11 @@ br 工具暂停 GC 的原理是通过执行 `SET config tikv gc.ratio-threshold 不建议进行跨大版本的断点恢复操作。对于使用 v8.5.0 之前长期支持 (Long-Term Support, LTS) 版本 br 恢复失败的集群，无法通过 v8.5.0 或更新的 LTS 版本 br 继续恢复，反之亦然。 -## 实现细节 +## 实现细节：将断点数据存储在下游集群 + +> **注意：** +> +> 从 v8.5.5 开始，默认将断点数据存储在下游集群。你可以通过参数 `--checkpoint-storage` 来指定断点数据存储的外部存储。 断点恢复的具体操作细节分为快照恢复和 PITR 恢复两部分。 @@ -81,8 +85,78 @@ br 工具暂停 GC 的原理是通过执行 `SET config tikv gc.ratio-threshold [PITR (Point-in-time recovery)](/br/br-pitr-guide.md) 恢复分为快照恢复和日志恢复两个阶段。 -在第一次执行恢复时，br 工具首先进入快照恢复阶段。该阶段与上述只进行[快照恢复](#快照恢复-1)操作相同，断点数据，以及备份数据的上游集群的 ID 和备份数据的 BackupTS（即日志恢复的起始时间点 `start-ts`）会被记录到 `__TiDB_BR_Temporary_Snapshot_Restore_Checkpoint` 数据库中。如果在此阶段恢复失败，尝试继续断点恢复时无法再调整日志恢复的起始时间点 `start-ts`。 +在第一次执行恢复时，br 工具首先进入快照恢复阶段。断点数据、备份数据的上游集群的 ID、备份数据的 BackupTS（即日志恢复的起始时间点 `start-ts`）和 PITR 恢复的 `restored-ts` 会被记录到 `__TiDB_BR_Temporary_Snapshot_Restore_Checkpoint` 数据库中。如果在此阶段恢复失败，尝试继续断点恢复时无法再调整日志恢复的起始时间点 `start-ts` 和 `restored-ts`。 在第一次执行恢复并且进入日志恢复阶段时，br 工具会在恢复集群中创建 `__TiDB_BR_Temporary_Log_Restore_Checkpoint` 数据库，用于记录断点数据，以及这次恢复的上游集群 ID 和恢复的时间范围 `start-ts` 与 `restored-ts`。如果在此阶段恢复失败，重新执行恢复命令时，你需要指定与断点记录相同的 `start-ts` 和 `restored-ts` 参数，否则 br 工具会报错，并提示上游集群 ID 或恢复的时间范围与断点记录不同。如果恢复集群已被清理，你可以手动删除 `__TiDB_BR_Temporary_Log_Restore_Checkpoint` 数据库，然后使用其他备份重试。 -在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到系统表 `mysql.tidb_pitr_id_map` 中，以避免库表 ID 被重复分配。如果删除 `mysql.tidb_pitr_id_map` 中的数据，可能会导致 PITR 恢复数据不一致。 +注意在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到系统表 `mysql.tidb_pitr_id_map` 中，以避免库表 ID 被重复分配。**如果随意删除 `mysql.tidb_pitr_id_map` 中的数据，可能会导致 PITR 恢复数据不一致。** + +> **注意：** +> +> 为了兼容旧版本集群，从 v8.5.5 开始，当恢复集群不存在系统表 `mysql.tidb_pitr_id_map` 时，`pitr_id_map` 数据会写到日志备份目录下，文件名为 `pitr_id_maps/pitr_id_map.cluster_id:{downstream-cluster-ID}.restored_ts:{restored-ts}`。 + +## 实现细节：将断点数据存储在外部存储 + +> **注意：** +> +> 从 v8.5.5 开始，默认将断点数据存储在下游集群。你可以通过参数 `--checkpoint-storage` 来指定断点数据存储的外部存储。例如： +> +> ```shell +> ./br restore full -s "s3://backup-bucket/backup-prefix" --checkpoint-storage "s3://temp-bucket/checkpoints" +> ``` + +在外部存储中，断点数据的目录结构如下： + +- 主路径 `restore-{downstream-cluster-ID}` 中的下游集群 ID `{downstream-cluster-ID}` 用于区分不同的恢复集群 +- 路径 `restore-{downstream-cluster-ID}/log` 存储日志恢复阶段的日志文件断点数据 +- 路径 `restore-{downstream-cluster-ID}/sst` 存储日志恢复阶段中未被日志备份覆盖的 SST 文件的断点数据 +- 路径 `restore-{downstream-cluster-ID}/snapshot` 存储快照恢复阶段的断点数据 + +``` +. +`-- restore-{downstream-cluster-ID} + |-- log + | |-- checkpoint.meta + | |-- data + | | |-- {uuid}.cpt + | | |-- {uuid}.cpt + | | `-- {uuid}.cpt + | |-- ingest_index.meta + | `-- progress.meta + |-- snapshot + | |-- checkpoint.meta + | |-- checksum + | | |-- {uuid}.cpt + | | |-- {uuid}.cpt + | | `-- {uuid}.cpt + | `-- data + | |-- {uuid}.cpt + | |-- {uuid}.cpt + | `-- {uuid}.cpt + `-- sst + `-- checkpoint.meta +``` + +断点恢复的具体操作细节分为快照恢复和 PITR 恢复两部分。 + +### 快照恢复 + +在第一次执行恢复时，br 工具会在恢复集群中创建路径 `restore-{downstream-cluster-ID}/snapshot`，用于记录断点数据，以及这次恢复的上游集群 ID 和备份的 BackupTS。 + +如果恢复执行失败，你可以使用相同的命令再次执行恢复，br 工具会从指定的存储断点数据的外部存储中读取断点信息，并从上次中断的位置继续恢复。 + +当恢复执行失败后，如果你尝试将与断点记录不同的备份数据恢复到同一集群，br 工具会报错，并提示上游集群 ID 或 BackupTS 与断点记录不同。如果恢复集群已被清理，你可以手动删除存储在外部存储的断点数据或更换指定的断点数据存储路径，然后使用其他备份重试。 + +### PITR 恢复 + +[PITR (Point-in-time recovery)](/br/br-pitr-guide.md) 恢复分为快照恢复和日志恢复两个阶段。 + +在第一次执行恢复时，br 工具首先进入快照恢复阶段。断点数据，以及备份数据的上游集群的 ID、备份数据的 BackupTS（即日志恢复的起始时间点 `start-ts`）和 PITR 恢复的 `restored-ts` 会被记录到路径 `restore-{downstream-cluster-ID}/snapshot` 中。如果在此阶段恢复失败，尝试继续断点恢复时无法再调整日志恢复的起始时间点 `start-ts` 和 `restored-ts`。 + +在第一次执行恢复并且进入日志恢复阶段时，br 工具会在恢复集群中创建路径 `restore-{downstream-cluster-ID}/log`，用于记录断点数据，以及这次恢复的上游集群 ID 和恢复的时间范围 `start-ts` 与 `restored-ts`。如果在此阶段恢复失败，重新执行恢复命令时，你需要指定与断点记录相同的 `start-ts` 和 `restored-ts` 参数，否则 br 工具会报错，并提示上游集群 ID 或恢复的时间范围与断点记录不同。如果恢复集群已被清理，你可以手动删除 存储在外部存储的断点数据或更换指定的断点数据存储路径，然后使用其他备份重试。 + +注意在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到存放断点数据的外部存储中（文件名为 `pitr_id_maps/pitr_id_map.cluster_id:{downstream-cluster-ID}.restored_ts:{restored-ts}`），以避免库表 ID 被重复分配。**如果随意删除 `pitr_id_maps` 目录中的文件，可能会导致 PITR 恢复数据不一致。** + +> **注意：** +> +> 为了兼容旧版本集群，从 v8.5.5 开始，当恢复集群不存在系统表 `mysql.tidb_pitr_id_map` 且未指定参数 `--checkpoint-storage` 时，`pitr_id_map` 数据会写到日志备份目录下，文件名为 `pitr_id_maps/pitr_id_map.cluster_id:{downstream-cluster-ID}.restored_ts:{restored-ts}`。 diff --git a/br/br-compact-log-backup.md b/br/br-compact-log-backup.md new file mode 100644 index 000000000000..3f6f2efe02c3 --- /dev/null +++ b/br/br-compact-log-backup.md @@ -0,0 +1,85 @@ +--- +title: 压缩日志备份 +summary: 了解如何通过压缩日志备份为 SST 格式来提升按时间点恢复 (Point-in-time recovery, PITR) 的效率。 +--- + +# 压缩日志备份 + +本文介绍如何通过压缩日志备份 (Compact Log Backup) 为 [SST](/glossary.md#static-sorted-table--sorted-string-table-sst) 格式来提升按时间点恢复 (Point-in-time recovery, [PITR](/glossary.md#point-in-time-recovery-pitr)) 的效率。 + +## 功能概述 + +传统日志备份以一种高度非结构化的方式存储写入操作，可能导致以下问题： + +- 恢复性能下降：无序数据需通过 Raft 协议逐条写入集群。 +- 写放大：所有写入必须从 LSM Tree 的 L0 开始被逐级别 compact 到底层。 +- 全量备份依赖：需频繁执行全量备份以控制恢复数据量，对业务有一定影响。 + +从 v8.5.5 开始，压缩日志备份功能提供了离线压缩能力，可将日志备份的非结构化数据转换为结构化的 SST 文件，从而实现以下改进： + +- SST 可以被快速导入集群，从而提升恢复性能。 +- 压缩过程中消除重复记录，从而减少空间消耗。 +- 在确保 RTO (Recovery Time Objective) 的前提下允许用户设置更长的全量备份间隔，从而降低对业务的影响。 + +## 使用限制 + +- 压缩日志备份并不是全量备份的替代方案，需与定期全量备份配合使用。为了保证能进行 PITR，日志备份的压缩过程会保留所有 MVCC 版本，长期不进行全量备份将导致存储膨胀并且可能在未来恢复时遇到问题。 +- 目前不支持压缩启用了 Local Encryption 的备份。 + +## 使用方法 + +目前仅支持手动压缩日志备份，流程较为复杂。**建议在生产中使用后续发布的 TiDB Operator 方案来压缩日志备份**。 + +### 手动压缩 + +本节介绍手动压缩日志备份的操作步骤。 + +#### 前提条件 + +手动压缩日志备份需要两个工具：`tikv-ctl` 和 `br`。 + +#### 第 1 步：将存储编码为 Base64 + +执行以下编码命令： + +```shell +br operator base64ify --storage "s3://your/log/backup/storage/here" --load-creds +``` + +> **注意：** +> +> - 如果执行以上命令时带了 `--load-cerds` 这个选项，编码出来的 Base64 中会包含从 BR 当前环境中加载的密钥信息，请注意安全保护和权限管控。 +> - 此处的 `--storage` 值应该和日志备份任务的 `log status` 命令输出的 storage 相同。 + +#### 第 2 步：执行日志压缩 + +有了存储的 Base64 之后，你可以执行以下命令通过 `tikv-ctl` 发起压缩，注意 `tikv-ctl` 默认日志等级为 `warning`，启用 `--log-level info` 来获得更多信息： + +```shell +tikv-ctl --log-level info compact-log-backup \ + --from "" --until "" \ + -s 'bAsE64==' -N 8 +``` + +参数解释如下： + +- `-s`：已获得的存储的 Base64。 +- `-N`：最大并发压缩日志任务的数量。 +- `--from`：压缩开始的时间戳。 +- `--until`：压缩结束的时间戳。 + +`--from` 和 `--until` 这对参数指定了压缩操作的时间范围。压缩操作将处理所有包含指定时间范围内任意写入的日志文件，因此最终生成的 SST 文件可能包含该范围外的写入数据。 + +要获取某个特定时间点的时间戳，请执行以下命令： + +```shell +echo $(( $(date --date '2004-05-06 15:02:01Z' +%s%3N) << 18 )) +``` + +> **注意：** +> +> 如果你是 macOS 用户，需要先使用 Homebrew 安装 `coreutils`，并且使用 `gdate` 而非 `date`。 +> +> ```shell +> echo $(( $(gdate --date '2004-05-06 15:02:01Z' +%s%3N) << 18 )) +> ``` diff --git a/br/br-pitr-guide.md b/br/br-pitr-guide.md index 7c7483467b33..cf978f35845d 100644 --- a/br/br-pitr-guide.md +++ b/br/br-pitr-guide.md @@ -93,13 +93,17 @@ tiup br restore point --pd "${PD_IP}:2379" \ 恢复期间，可通过终端中的进度条查看进度，如下。恢复分为两个阶段：全量恢复 (Full Restore) 和日志恢复（Restore Meta Files 和 Restore KV Files）。每个阶段完成恢复后，br 命令行工具都会输出恢复耗时和恢复数据大小等信息。 ```shell -Full Restore <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Split&Scatter Region <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Download&Ingest SST <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Restore Pipeline <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% *** ["Full Restore success summary"] ****** [total-take=xxx.xxxs] [restore-data-size(after-compressed)=xxx.xxx] [Size=xxxx] [BackupTS={TS}] [total-kv=xxx] [total-kv-size=xxx] [average-speed=xxx] Restore Meta Files <--------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% Restore KV Files <----------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% *** ["restore log success summary"] [total-take=xxx.xx] [restore-from={TS}] [restore-to={TS}] [total-kv-count=xxx] [total-size=xxx] ``` +在数据恢复期间，目标表的 Table Mode 会自动设置为 `restore`，处于 `restore` 模式的表禁止用户执行任何读写操作。当数据恢复完成后，Table Mode 会自动切换为 `normal` 状态，用户可以正常读写该表，从而确保数据恢复期间的任务稳定性和数据一致性。 + ## 清理过期的日志备份数据 如[使用指南概览](/br/br-use-overview.md)所述： diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index a03f2e85b248..091e6e90d5e4 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -458,7 +458,9 @@ tiup br restore point --pd="${PD_IP}:2379" --storage='s3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}' --full-backup-storage='s3://backup-101/snapshot-202205120000?access-key=${access-key}&secret-access-key=${secret-access-key}' -Full Restore <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Split&Scatter Region <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Download&Ingest SST <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% +Restore Pipeline <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% *** ***["Full Restore success summary"] ****** [total-take=3.112928252s] [restore-data-size(after-compressed)=5.056kB] [Size=5056] [BackupTS=434693927394607136] [total-kv=4] [total-kv-size=290B] [average-speed=93.16B/s] Restore Meta Files <--------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% Restore KV Files <----------------------------------------------------------------------------------------------------------------------------------------------------> 100.00% @@ -497,4 +499,157 @@ tiup br restore point --pd="${PD_IP}:2379" --crypter.key 0123456789abcdef0123456789abcdef --master-key-crypter-method aes128-ctr --master-key "local:///path/to/master.key" -``` \ No newline at end of file +``` + +### 使用过滤器恢复 + +从 TiDB v8.5.5 开始，在按时间点恢复 (PITR) 过程中，你可以使用过滤器恢复特定的数据库或表，从而更精细地控制要恢复的数据。 + +过滤器采用与其他 BR 操作相同的[表库过滤语法](/table-filter.md)： + +- `'*.*'`：匹配所有数据库和表。 +- `'db1.*'`：匹配数据库 `db1` 中的所有表。 +- `'db1.table1'`：匹配数据库 `db1` 中的特定表 `table1`。 +- `'db*.tbl*'`：匹配以 `db` 开头的数据库和以 `tbl` 开头的表。 +- `'!mysql.*'`：排除 `mysql` 数据库中的所有表。 + +使用示例： + +```shell +# 恢复特定数据库 +tiup br restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--start-ts "2025-06-02 00:00:00+0800" \ +--restored-ts "2025-06-03 18:00:00+0800" \ +--filter 'db1.*' --filter 'db2.*' + +# 恢复特定表 +tiup br restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--start-ts "2025-06-02 00:00:00+0800" \ +--restored-ts "2025-06-03 18:00:00+0800" \ +--filter 'db1.users' --filter 'db1.orders' + +# 使用模式匹配恢复 +tiup br restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--start-ts "2025-06-02 00:00:00+0800" \ +--restored-ts "2025-06-03 18:00:00+0800" \ +--filter 'db*.tbl*' +``` + +> **注意：** +> +> - 使用过滤器恢复前，请确保目标集群中不存在与过滤器匹配的数据库或表，否则恢复将失败并报错。 +> - 过滤器选项适用于快照备份和日志备份的恢复阶段。 +> - 可以指定多个 `--filter` 选项来包含或排除不同的模式。 +> - PITR 过滤暂不支持系统表。如果需要恢复特定的系统表，请使用 `br restore full` 命令并配合过滤器，注意该命令仅恢复快照备份数据（而非日志备份数据）。 +> - 恢复任务中的正则表达式匹配的是 `restored-ts` 时刻的表名，有以下三种情况： +> - 表 A (table id = 1) 在 `restored-ts` 时刻及之前，表名始终匹配 `--filter` 正则表达式，则 PITR 会恢复这张表。 +> - 表 B (table id = 2) 在 `restored-ts` 前的某个时刻，表名不匹配 `--filter` 正则表达式，但在 `restored-ts` 时刻匹配，则 PITR 会恢复这张表。 +> - 表 C (table id = 3) 在 `restored-ts` 前的某个时刻，表名匹配 `--filter` 正则表达式，但在 `restored-ts` 时刻**不**匹配，则 PITR **不会**恢复这张表。 +> - 你可以使用库表过滤功能在线恢复部分数据。在线恢复过程中，不要创建与恢复对象同名的库表，否则恢复任务会因冲突而失败。在该恢复过程中，由 PITR 创建的表都不可读写，直至恢复完成后，这些表才可正常读写。 + +### 并发恢复操作 + +从 TiDB v8.5.5 开始，你可以同时执行多个 PITR 恢复任务。该功能允许你并行恢复不同的数据集，从而提升大规模恢复场景下的效率。 + +并发恢复的使用示例： + +```shell +# 终端 1 - 恢复数据库 db1 +tiup br restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--start-ts "2025-06-02 00:00:00+0800" \ +--restored-ts "2025-06-03 18:00:00+0800" \ +--filter 'db1.*' + +# 终端 2 - 恢复数据库 db2（可同时运行） +tiup br restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--start-ts "2025-06-02 00:00:00+0800" \ +--restored-ts "2025-06-03 18:00:00+0800" \ +--filter 'db2.*' +``` + +> **注意：** +> +> - 每个并发恢复操作必须作用于不同的数据库或不重叠的表集合。尝试并发恢复重叠数据集将导致错误。 +> - 多个恢复任务会占用大量系统资源。仅在 CPU 和 I/O 资源充足时，才建议并行执行恢复任务。 + +### 进行中的日志备份与快照恢复的兼容性 + +从 v8.5.5 开始，当存在日志备份任务时，如果**同时满足**以下条件，则可以正常进行快照恢复 (`br restore [full|database|table]`)，并且恢复的数据可以被进行中的日志备份（下称“日志备份”）正常记录： + +- 执行备份恢复操作的节点需要同时具备以下权限： + - 对备份来源外部存储的读取权限，用于执行快照恢复 + - 对日志备份目标外部存储的写入权限 +- 日志备份的目标外部存储类型是 Amazon S3 (`s3://`)、Google Cloud Storage (`gcs://`) 或 Azure Blob Storage (`azblob://`)。 +- 待恢复的数据与日志备份的目标存储拥有相同的外部存储类型。 +- 待恢复的数据和日志备份均未开启本地加密，参考[日志备份加密](#加密日志备份数据)和[快照备份加密](/br/br-snapshot-manual.md#备份数据加密)。 + +如果不能同时满足上述条件，你可以通过以下步骤完成数据恢复： + +1. [停止日志备份任务](#停止日志备份任务)。 +2. 进行数据恢复。 +3. 恢复完成后，重新进行快照备份。 +4. [重新启动备份任务](#重新启动备份任务)。 + +> **注意：** +> +> 当恢复记录了快照（全量）恢复数据的日志备份时，需要使用 v8.5.5 及之后版本的 BR，否则可能导致记录下来的全量恢复数据无法被恢复。 + +### 进行中的日志备份与 PITR 操作的兼容性 + +从 TiDB v8.5.5 开始，默认情况下，你可以在日志备份任务运行期间执行 PITR 操作。系统会自动处理这些操作之间的兼容性。 + +#### 进行中的日志备份与 PITR 的重要限制 + +当在运行日志备份的同时执行 PITR 操作时，恢复的数据也会被记录到日志备份中。但是，在恢复操作的时间窗口内，由于日志恢复操作的特性，可能存在数据不一致的风险。系统会将元数据写入外部存储，以标记无法保证一致性的时间范围和数据范围。 + +如果在时间范围 `[t1, t2)` 期间发生此类不一致，你无法直接恢复该时间段的数据，需选择以下替代方案： + +- 恢复到 `t1` 时间点（获取不一致时期之前的数据） +- 或在 `t2` 时间点后执行新的快照备份，并基于此备份进行后续 PITR 操作 + +### 中止恢复操作 + +当恢复操作失败时，你可以使用 `tiup br abort` 命令来清理注册表条目和检查点数据。该命令会根据提供的原始恢复参数自动找到并删除相关的元数据，包括 `mysql.tidb_restore_registry` 表中的条目以及检查点数据（无论存储在本地数据库还是外部存储中）。 + +> **注意：** +> +> `abort` 命令仅清理元数据，任何实际恢复的数据需要手动从集群中删除。 + +使用与原始恢复命令相同的参数来中止恢复操作的示例如下： + +```shell +# 中止 PITR 操作 +tiup br abort restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' + +# 中止带过滤器的 PITR 操作 +tiup br abort restore point --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--filter 'db1.*' + +# 中止全量恢复 +tiup br abort restore full --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' + +# 中止数据库恢复 +tiup br abort restore db --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--db database_name + +# 中止表恢复 +tiup br abort restore table --pd="${PD_IP}:2379" \ +--storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ +--db database_name --table table_name +``` diff --git a/br/br-snapshot-guide.md b/br/br-snapshot-guide.md index 67f906159dbd..85c0bb0b3c0d 100644 --- a/br/br-snapshot-guide.md +++ b/br/br-snapshot-guide.md @@ -34,12 +34,19 @@ tiup br backup full --pd "${PD_IP}:2379" \ - `--backupts`：快照对应的物理时间点，格式可以是 [TSO](/tso.md) 或者时间戳，例如 `400036290571534337` 或者 `2018-05-11 01:42:23 +08:00`。如果该快照的数据被垃圾回收 (GC) 了，那么 `tiup br backup` 命令会报错并退出。使用日期方式备份时，建议同时指定时区，否则 br 默认使用本地时间构造时间戳，可能导致备份时间点错误。如果你没有指定该参数，那么 br 会选取备份开始的时间点所对应的快照。 - `--storage`：数据备份到的存储地址。快照备份支持以 Amazon S3、Google Cloud Storage、Azure Blob Storage 为备份存储，以上命令以 Amazon S3 为示例。详细存储地址格式请参考[外部存储服务的 URI 格式](/external-storage-uri.md)。 -在快照备份过程中，终端会显示备份进度条。在备份完成后，会输出备份耗时、速度、备份数据大小等信息。 +在快照备份过程中，终端会显示备份进度条。在备份完成后，会输出备份耗时、速度、备份数据大小等信息。其中： + +- `total-ranges`：备份的文件总数量 +- `ranges-succeed`：备份成功的文件数量 +- `ranges-failed`：备份失败的文件数量 +- `backup-total-ranges`：备份的表（包括分区表）与索引的数量 +- `write-CF-files`：备份文件中含有 `write CF` 数据的 SST 文件数量 +- `default-CF-files`：备份文件中含有 `default CF` 数据的 SST 文件数量 ```shell Full Backup <-------------------------------------------------------------------------------> 100.00% Checksum <----------------------------------------------------------------------------------> 100.00% -*** ["Full Backup success summary"] *** [backup-checksum=3.597416ms] [backup-fast-checksum=2.36975ms] *** [total-take=4.715509333s] [BackupTS=435844546560000000] [total-kv=1131] [total-kv-size=250kB] [average-speed=53.02kB/s] [backup-data-size(after-compressed)=71.33kB] [Size=71330] +*** ["Full Backup success summary"] *** [total-ranges=20] [ranges-succeed=20] [ranges-failed=0] [backup-checksum=3.597416ms] [backup-fast-checksum=2.36975ms] [backup-total-ranges=11] [backup-total-regions=10] [write-CF-files=14] [default-CF-files=6] [total-take=4.715509333s] [BackupTS=435844546560000000] [total-kv=1131] [total-kv-size=250kB] [average-speed=53.02kB/s] [backup-data-size(after-compressed)=71.33kB] [Size=71330] ``` ## 查询快照备份的时间点信息 @@ -76,13 +83,27 @@ tiup br restore full --pd "${PD_IP}:2379" \ --storage "s3://backup-101/snapshot-202209081330?access-key=${access-key}&secret-access-key=${secret-access-key}" ``` -在恢复快照备份数据过程中，终端会显示恢复进度条。在完成恢复后，会输出恢复耗时、速度、恢复数据大小等信息。 +在恢复快照备份数据过程中，终端会显示恢复进度条。在完成恢复后，会输出恢复耗时、速度、恢复数据大小等信息。其中： + +- `total-ranges`：恢复的文件总数量 +- `ranges-succeed`：恢复成功的文件数量 +- `ranges-failed`：恢复失败的文件数量 +- `merge-ranges`：合并数据范围的耗时 +- `split-region`：切分和打散 Region 的耗时 +- `restore-files`： TiKV 恢复 SST 文件的耗时 +- `write-CF-files`：恢复文件中含有 `write CF` 数据的 SST 文件数量 +- `default-CF-files`：恢复文件中含有 `default CF` 数据的 SST 文件数量 +- `split-keys`：生成的用于切分 Region 的 key 数量 ```shell -Full Restore <------------------------------------------------------------------------------> 100.00% -*** ["Full Restore success summary"] *** [total-take=4.344617542s] [total-kv=5] [total-kv-size=327B] [average-speed=75.27B/s] [restore-data-size(after-compressed)=4.813kB] [Size=4813] [BackupTS=435844901803917314] +Split&Scatter Region <--------------------------------------------------------------------> 100.00% +Download&Ingest SST <---------------------------------------------------------------------> 100.00% +Restore Pipeline <------------------------------------------------------------------------> 100.00% +*** ["Full Restore success summary"] [total-ranges=20] [ranges-succeed=20] [ranges-failed=0] [merge-ranges=7.546971ms] [split-region=343.594072ms] [restore-files=1.57662s] [default-CF-files=6] [write-CF-files=14] [split-keys=9] [total-take=4.344617542s] [total-kv=5] [total-kv-size=327B] [average-speed=75.27B/s] [restore-data-size(after-compressed)=4.813kB] [Size=4813] [BackupTS=435844901803917314] ``` +在数据恢复期间，目标表的 Table Mode 会自动设置为 `restore`，处于 `restore` 模式的表禁止用户执行任何读写操作。当数据恢复完成后，Table Mode 会自动切换为 `normal` 状态，用户可以正常读写该表，从而确保数据恢复期间的任务稳定性和数据一致性。 + ### 恢复备份数据中指定库表的数据 br 命令行工具支持只恢复备份数据中指定库、表的部分数据，该功能用于在恢复过程中过滤不需要的数据。 @@ -129,6 +150,7 @@ tiup br restore full \ - `br` v5.1.0 开始，快照备份时默认自动备份 **mysql schema 下的系统表数据**，但恢复数据时默认不恢复系统表数据。 - `br` v6.2.0 开始，增加恢复参数 `--with-sys-table` 支持恢复数据的同时恢复**部分系统表相关数据**。 - `br` v7.6.0 开始，恢复参数 `--with-sys-table` 默认开启，即默认支持恢复数据的同时恢复**部分系统表相关数据**。 +- `br` v8.5.5 开始，增加恢复参数 `--fast-load-sys-tables` 支持物理恢复系统表，该参数默认开启。通过 `RENAME TABLE` DDL 将 `__TiDB_BR_Temporary_mysql` 下的系统表和 `mysql` 库下的系统表进行原子交换。与通过 `REPLACE INTO` SQL 写入的逻辑恢复系统表方式不同，物理恢复系统表将会完全覆盖系统表中原有的数据。 **可恢复的部分系统表**： diff --git a/br/br-snapshot-manual.md b/br/br-snapshot-manual.md index 04a09f511e24..ea398e15982d 100644 --- a/br/br-snapshot-manual.md +++ b/br/br-snapshot-manual.md @@ -127,8 +127,19 @@ tiup br restore full \ --storage local:///br_data/ --pd "${PD_IP}:2379" --log-file restore.log ``` +> **注意：** +> +> 从 v8.5.5 开始，当参数 `--load-stats` 设置为 `false` 时，br 不再向 `mysql.stats_meta` 表写入恢复表的统计信息。你可以在恢复完成后手动执行 [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md)，以更新相关统计信息。 + 备份恢复功能在备份时，将统计信息通过 JSON 格式存储在 `backupmeta` 文件中。在恢复时，将 JSON 格式的统计信息导入到集群中。详情请参考 [LOAD STATS](/sql-statements/sql-statement-load-stats.md)。 +从 v8.5.5 开始，BR 引入参数 `--fast-load-sys-tables`，该参数默认开启。在使用 br 命令行工具将数据恢复到一个全新集群，且上下游的表和分区 ID 能够复用的前提下（否则会自动回退为逻辑导入统计信息），开启 `--fast-load-sys-tables` 后，br 会先将统计信息相关表恢复至临时系统库 `__TiDB_BR_Temporary_mysql` 中，再通过 `RENAME TABLE` 语句将这些表与 `mysql` 库下的原有表进行原子性替换。使用示例如下： + +```shell +tiup br restore full \ +--storage local:///br_data/ --pd "${PD_IP}:2379" --log-file restore.log --load-stats --fast-load-sys-tables +``` + ## 备份数据加密 br 命令行工具支持在备份端，或备份到 Amazon S3 的时候在[存储服务端进行备份数据加密](/br/backup-and-restore-storages.md#amazon-s3-存储服务端加密备份数据)，你可以根据自己情况选择其中一种使用。 @@ -176,9 +187,27 @@ tiup br restore full \ 恢复期间终端会显示进度条，效果如下。当进度条达到 100% 时，表示恢复完成。在完成恢复后，br 工具为了确保数据安全性，还会校验恢复数据。 ```shell -Full Restore <---------/...............................................> 17.12%. +Split&Scatter Region <--------------------------------------------------------------------> 100.00% +Download&Ingest SST <---------------------------------------------------------------------> 100.00% +Restore Pipeline <-------------------------/...............................................> 17.12% ``` +从 TiDB v8.5.5 开始，你可以通过指定参数 `--fast-load-sys-tables` 在全新的集群上进行物理恢复系统表： + +```shell +tiup br restore full \ + --pd "${PD_IP}:2379" \ + --with-sys-table \ + --fast-load-sys-tables \ + --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \ + --ratelimit 128 \ + --log-file restorefull.log +``` + +> **注意：** +> +> 与通过 `REPLACE INTO` SQL 语句执行的逻辑恢复系统表方式不同，物理恢复系统表会完全覆盖系统表中的原有数据。 + ## 恢复备份数据中指定库表的数据 br 命令行工具支持只恢复备份数据中指定库/表的局部数据。该功能在恢复过程中过滤掉不需要的数据，可以用于往 TiDB 集群上恢复指定库/表的数据。 diff --git a/configure-store-limit.md b/configure-store-limit.md index 6d99eeae4610..b49ad596c2b5 100644 --- a/configure-store-limit.md +++ b/configure-store-limit.md @@ -53,6 +53,13 @@ tiup ctl:v pd store limit all 5 add-peer // 设置所 tiup ctl:v pd store limit all 5 remove-peer // 设置所有 store 删除 peer 的速度上限为每分钟 5 个。 ``` +从 v8.5.5 起，PD 支持按存储引擎类型为所有 store 设置删除 peer 的 limit，示例如下： + +```bash +tiup ctl:v pd store limit all engine tikv 5 remove-peer // 设置所有 TiKV store 删除 peer 的速度上限为每分钟 5 个 +tiup ctl:v pd store limit all engine tiflash 5 remove-peer // 设置所有 TiFlash store 删除 peer 的速度上限为每分钟 5 个 +``` + ### 设置单个 store 的 limit 设置单个 store 的 limit 示例如下： diff --git a/faq/backup-and-restore-faq.md b/faq/backup-and-restore-faq.md index b09cfcaf02bf..b9005b158a96 100644 --- a/faq/backup-and-restore-faq.md +++ b/faq/backup-and-restore-faq.md @@ -107,6 +107,14 @@ Error: failed to check gc safePoint, checkpoint ts 433177834291200000: GC safepo 此场景的处理办法是：先执行 `br log stop` 命令来删除当前的任务，然后执行 `br log start` 重新创建新的日志备份任务，同时做一个全量备份，便于后续做 PITR 恢复操作。 +### 执行 PITR table filter 时报 `[ddl:8204]invalid ddl job type: none` 错误，该如何处理？ + +```shell +failed to refresh meta for database with schemaID=124, dbName=pitr_test: [ddl:8204]invalid ddl job type: none +``` + +该错误是由于 DDL Owner 所在的 TiDB 节点版本过低，无法识别 Refresh Meta DDL 导致的。请将集群升级至 v8.5.5 或更高版本，再使用 PITR 的 [table filter](/table-filter.md) 功能。 + ## 功能兼容性问题 ### 为什么 BR 恢复的数据无法同步到 TiCDC 的上游集群？ diff --git a/identify-slow-queries.md b/identify-slow-queries.md index 4a584888c1f7..4eb582daf8eb 100644 --- a/identify-slow-queries.md +++ b/identify-slow-queries.md @@ -167,6 +167,11 @@ Slow Query 基础信息： * `Request_unit_write`：执行语句消耗的总写 RU。 * `Time_queued_by_rc`：执行语句过程中等待可用资源的总耗时。 +和存储引擎相关的字段： + +- `Storage_from_kv`：从 v8.5.5 开始引入，表示该语句是否从 TiKV 读取数据。 +- `Storage_from_mpp`：从 v8.5.5 开始引入，表示该语句是否从 TiFlash 读取数据。 + ## 相关系统变量 * [tidb_slow_log_threshold](/system-variables.md#tidb_slow_log_threshold)：设置慢日志的阈值，执行时间超过阈值的 SQL 语句将被记录到慢日志中。默认值是 300 ms。 diff --git a/information-schema/information-schema-partitions.md b/information-schema/information-schema-partitions.md index 007113f7b1b1..3c5235f15309 100644 --- a/information-schema/information-schema-partitions.md +++ b/information-schema/information-schema-partitions.md @@ -45,8 +45,9 @@ DESC PARTITIONS; | TABLESPACE_NAME | varchar(64) | YES | | NULL | | | TIDB_PARTITION_ID | bigint(21) | YES | | NULL | | | TIDB_PLACEMENT_POLICY_NAME | varchar(64) | YES | | NULL | | +| TIDB_AFFINITY | varchar(128) | YES | | NULL | | +-------------------------------+--------------+------+------+---------+-------+ -27 rows in set (0.00 sec) +28 rows in set (0.00 sec) ``` ```sql @@ -85,6 +86,7 @@ SUBPARTITION_ORDINAL_POSITION: NULL TABLESPACE_NAME: NULL TIDB_PARTITION_ID: 89 TIDB_PLACEMENT_POLICY_NAME: NULL + TIDB_AFFINITY: NULL *************************** 2. row *************************** TABLE_CATALOG: def TABLE_SCHEMA: test @@ -113,6 +115,7 @@ SUBPARTITION_ORDINAL_POSITION: NULL TABLESPACE_NAME: NULL TIDB_PARTITION_ID: 90 TIDB_PLACEMENT_POLICY_NAME: NULL + TIDB_AFFINITY: NULL 2 rows in set (0.00 sec) ``` diff --git a/information-schema/information-schema-tables.md b/information-schema/information-schema-tables.md index ff7ac01c5887..a1b38ae3294a 100644 --- a/information-schema/information-schema-tables.md +++ b/information-schema/information-schema-tables.md @@ -41,8 +41,12 @@ DESC tables; | TABLE_COMMENT | varchar(2048) | YES | | NULL | | | TIDB_TABLE_ID | bigint(21) | YES | | NULL | | | TIDB_ROW_ID_SHARDING_INFO | varchar(255) | YES | | NULL | | +| TIDB_PK_TYPE | varchar(64) | YES | | NULL | | +| TIDB_PLACEMENT_POLICY_NAME | varchar(64) | YES | | NULL | | +| TIDB_TABLE_MODE | varchar(16) | YES | | NULL | | +| TIDB_AFFINITY | varchar(128) | YES | | NULL | | +---------------------------+---------------+------+------+----------+-------+ -23 rows in set (0.00 sec) +27 rows in set (0.00 sec) ``` {{< copyable "sql" >}} @@ -76,6 +80,10 @@ SELECT * FROM tables WHERE table_schema='mysql' AND table_name='user'\G TABLE_COMMENT: TIDB_TABLE_ID: 5 TIDB_ROW_ID_SHARDING_INFO: NULL + TIDB_PK_TYPE: CLUSTERED +TIDB_PLACEMENT_POLICY_NAME: NULL + TIDB_TABLE_MODE: Normal + TIDB_AFFINITY: NULL 1 row in set (0.00 sec) ``` @@ -115,7 +123,7 @@ SHOW TABLES * `CREATE_OPTIONS`：创建选项。 * `TABLE_COMMENT`：表的注释、备注。 -表中的信息大部分定义自 MySQL，只有两列是 TiDB 新增的： +表中的大部分列都和 MySQL 相同，除了以下列是 TiDB 新增的： * `TIDB_TABLE_ID`：标识表的内部 ID，该 ID 在一个 TiDB 集群内部唯一。 * `TIDB_ROW_ID_SHARDING_INFO`：标识表的 Sharding 类型，可能的值为： @@ -123,4 +131,8 @@ SHOW TABLES - `"NOT_SHARDED(PK_IS_HANDLE)"`：一个定义了整型主键的表未被 Shard。 - `"PK_AUTO_RANDOM_BITS={bit_number}"`：一个定义了整型主键的表由于定义了 `AUTO_RANDOM` 而被 Shard。 - `"SHARD_BITS={bit_number}"`：表使用 `SHARD_ROW_ID_BITS={bit_number}` 进行了 Shard。 - - NULL：表属于系统表或 View，无法被 Shard。 + - `NULL`：表属于系统表或 View，无法被 Shard。 +* `TIDB_PK_TYPE`：表的主键类型，可能的值包括 `CLUSTERED`（聚簇主键）和 `NONCLUSTERED`（非聚簇主键）。 +* `TIDB_PLACEMENT_POLICY_NAME`：应用于该表的放置策略 (placement policy) 名称。 +* `TIDB_TABLE_MODE`：表的模式，例如 `Normal`、`Import` 或 `Restore`。 +* `TIDB_AFFINITY`：表的亲和性等级，非分区表为 `table`，分区表为 `partition`，未开启亲和性时为 `NULL`。 diff --git a/optimizer-hints.md b/optimizer-hints.md index 7fffc9da259e..2b2595c171e5 100644 --- a/optimizer-hints.md +++ b/optimizer-hints.md @@ -476,6 +476,60 @@ EXPLAIN SELECT /*+ NO_ORDER_INDEX(t, a) */ a FROM t ORDER BY a LIMIT 10; 和 `ORDER_INDEX` Hint 的示例相同，优化器对该查询会生成两类计划：`Limit + IndexScan(keep order: true)` 和 `TopN + IndexScan(keep order: false)`，当使用了 `NO_ORDER_INDEX` Hint，优化器会选择后一种不按照顺序读取索引的计划。 +### INDEX_LOOKUP_PUSHDOWN(t1_name, idx1_name [, idx2_name ...]) 从 v8.5.5 版本开始引入 + +`INDEX_LOOKUP_PUSHDOWN(t1_name, idx1_name [, idx2_name ...])` 提示优化器仅使用指定的索引访问指定的表，并将 `IndexLookUp` 算子下推到 TiKV 执行。 + +以下示例展示了使用该 Hint 后生成的执行计划： + +```sql +CREATE TABLE t1(a INT, b INT, KEY(a)); +EXPLAIN SELECT /*+ INDEX_LOOKUP_PUSHDOWN(t1, a) */ a, b FROM t1; +``` + +```sql ++-----------------------------+----------+-----------+----------------------+--------------------------------+ +| id | estRows | task | access object | operator info | ++-----------------------------+----------+-----------+----------------------+--------------------------------+ +| IndexLookUp_7 | 10000.00 | root | | | +| ├─LocalIndexLookUp(Build) | 10000.00 | cop[tikv] | | index handle offsets:[1] | +| │ ├─IndexFullScan_5(Build) | 10000.00 | cop[tikv] | table:t1, index:a(a) | keep order:false, stats:pseudo | +| │ └─TableRowIDScan_8(Probe) | 10000.00 | cop[tikv] | table:t1 | keep order:false, stats:pseudo | +| └─TableRowIDScan_6(Probe) | 0.00 | cop[tikv] | table:t1 | keep order:false, stats:pseudo | ++-----------------------------+----------+-----------+----------------------+--------------------------------+ +``` + +使用 `INDEX_LOOKUP_PUSHDOWN` Hint 后，执行计划中原本位于 TiDB 侧的最外层 Build 算子会被替换为 `LocalIndexLookUp`，并下推到 TiKV 执行。TiKV 在扫描索引的同时，会尝试在本地回表读取行数据。由于索引和行数据可能分布在不同的 Region，下推到 TiKV 的请求可能无法覆盖所有目标行。因此，执行计划中仍会保留 TiDB 侧的 `TableRowIDScan` 算子，用于补齐未在 TiKV 侧命中的行数据。 + +`INDEX_LOOKUP_PUSHDOWN` Hint 目前存在以下限制： + +- 不支持缓存表 (cached table) 和临时表。 +- 暂不支持使用[全局索引](/global-indexes.md)的查询。 +- 暂不支持使用[多值索引](/choose-index.md#使用多值索引)的查询。 +- 暂不支持除 `REPEATABLE-READ` 之外的其他隔离级别。 +- 暂不支持 [Follower Read](/follower-read.md)。 +- 暂不支持 [Stale Read](/stale-read.md) 或[使用 `tidb_snapshot` 来读取历史数据](/read-historical-data.md)。 +- 下推的 `LocalIndexLookUp` 算子暂不支持 `keep order`。如果执行计划包含基于索引列的 `ORDER BY`，查询将回退为普通的 `IndexLookUp`。 +- 下推的 `LocalIndexLookUp` 算子暂不支持以分页 (paging) 方式发送 Coprocessor 请求。 +- 下推的 `LocalIndexLookUp` 算子暂不支持[下推计算结果缓存](/coprocessor-cache.md)。 + +### NO_INDEX_LOOKUP_PUSHDOWN(t1_name) 从 v8.5.5 版本开始引入 + +`NO_INDEX_LOOKUP_PUSHDOWN(t1_name)` 用于显式禁止对指定表执行 `IndexLookUp` 下推。该 Hint 通常与系统变量 [`tidb_index_lookup_pushdown_policy`](/system-variables.md#tidb_index_lookup_pushdown_policy-从-v855-版本开始引入) 配合使用。当该变量的值为 `force` 或 `affinity-force` 时，你可以使用此 Hint 阻止特定表下推 `IndexLookUp`。 + +以下示例将 `tidb_index_lookup_pushdown_policy` 变量设置为 `force`，使当前会话中的所有 `IndexLookUp` 算子自动下推。如果在查询中指定了 `NO_INDEX_LOOKUP_PUSHDOWN` Hint，则对应表不会下推 `IndexLookUp`： + +```sql +SET @@tidb_index_lookup_pushdown_policy = 'force'; + +-- 不会下推 IndexLookUp 算子 +SELECT /*+ NO_INDEX_LOOKUP_PUSHDOWN(t) */ * FROM t WHERE a > 1; +``` + +> **注意：** +> +> `NO_INDEX_LOOKUP_PUSHDOWN` 的优先级高于 [`INDEX_LOOKUP_PUSHDOWN`](#index_lookup_pushdownt1_name-idx1_name--idx2_name--从-v855-版本开始引入)。当同一个查询中同时指定这两个 Hint 时，`NO_INDEX_LOOKUP_PUSHDOWN` 生效。 + ### AGG_TO_COP() `AGG_TO_COP()` 提示优化器将指定查询块中的聚合函数下推到 coprocessor。如果优化器没有下推某些适合下推的聚合函数，建议尝试使用。例如： diff --git a/pd-configuration-file.md b/pd-configuration-file.md index 27baea8258f2..910e075d8f69 100644 --- a/pd-configuration-file.md +++ b/pd-configuration-file.md @@ -287,6 +287,13 @@ pd-server 相关配置项。 + 控制 Region Merge 的 key 上限，当 Region key 大于指定值时 PD 不会将其与相邻的 Region 合并。 + 默认：540000。在 v8.4.0 之前，默认值为 200000；从 v8.4.0 开始，默认值为 540000。 +### `max-affinity-merge-region-size` 从 v8.5.5 版本开始引入 + ++ 控制属于同一[亲和性](/table-affinity.md)分组中相邻的小 Region 自动合并的阈值。当 Region 属于某个亲和性分组，且其大小小于该配置值时，PD 会尝试将该 Region 与同一亲和性分组中相邻的其它小 Region 进行合并，以减少 Region 数量并保持亲和性效果。 ++ 设置为 `0` 表示关闭亲和性分组中相邻小 Region 的自动合并。 ++ 默认值：256 ++ 单位：MiB + ### `patrol-region-interval` + 控制 checker 检查 Region 健康状态的运行频率，越短则运行越快，通常状况不需要调整 @@ -362,6 +369,11 @@ pd-server 相关配置项。 + 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。 + 默认值：8 +### `affinity-schedule-limit` 从 v8.5.5 版本开始引入 + ++ 控制同时进行的[亲和性](/table-affinity.md)调度任务数量。设置为 `0` 表示禁用亲和性调度。 ++ 默认值：0 + ### `high-space-ratio` + 设置 store 空间充裕的阈值。当节点的空间占用比例小于该阈值时，PD 调度时会忽略节点的剩余空间，主要根据实际数据量进行均衡。此配置仅在 `region-score-formula-version = v1` 时生效。 diff --git a/pd-control.md b/pd-control.md index 510020d3f394..5c024ec172aa 100644 --- a/pd-control.md +++ b/pd-control.md @@ -1157,7 +1157,7 @@ pd-ctl resource-manager config controller set ltb-max-wait-duration 30m >> scheduler config evict-leader-scheduler // v4.0.0 起，展示该调度器具体在哪些 store 上 >> scheduler config evict-leader-scheduler add-store 2 // 为 store 2 添加 leader 驱逐调度 >> scheduler config evict-leader-scheduler delete-store 2 // 为 store 2 移除 leader 驱逐调度 ->> scheduler add evict-slow-store-scheduler // 当有且仅有一个 slow store 时将该 store 上的所有 Region 的 leader 驱逐出去 +>> scheduler add evict-slow-store-scheduler // 自动检测磁盘或网络慢节点，并在满足条件时将该 store 上的所有 Region leader 驱逐出去 >> scheduler remove grant-leader-scheduler-1 // 把对应的调度器删掉，`-1` 对应 store ID >> scheduler pause balance-region-scheduler 10 // 暂停运行 balance-region 调度器 10 秒 >> scheduler pause all 10 // 暂停运行所有的调度器 10 秒 @@ -1181,6 +1181,44 @@ pd-ctl resource-manager config controller set ltb-max-wait-duration 30m - `pending`：表示当前调度器无法产生调度。`pending` 状态的调度器，会返回一个概览信息，来帮助用户诊断。概览信息包含了 store 的一些状态信息，解释了它们为什么不能被选中进行调度。 - `normal`：表示当前调度器无需进行调度。 +### `scheduler config evict-slow-store-scheduler` + +`evict-slow-store-scheduler` 用于在 TiKV 节点出现磁盘 I/O 或网络抖动时，限制 PD 向异常节点调度 Leader，并在必要时主动驱逐 Leader，以降低慢节点对集群的影响。 + +#### 磁盘慢节点 + +从 v6.2.0 开始，TiKV 会在 store 心跳中向 PD 上报 `SlowScore`，该分值基于磁盘 I/O 情况计算得出。分值范围为 1～100，数值越大表示该节点越可能存在磁盘性能异常。 + +对于磁盘慢节点，TiKV 侧的探测以及 PD 侧基于 `evict-slow-store-scheduler` 的调度处理默认开启，无需额外配置。 + +#### 网络慢节点 + +从 v8.5.5 起，TiKV 支持在 store 心跳中上报 `NetworkSlowScore`，该分值基于网络探测结果计算得出，用于识别网络抖动导致的慢节点。分值范围为 1～100，数值越大表示网络异常的可能性越高。 + +出于兼容性和资源消耗的考虑，网络慢节点的探测与调度默认关闭。如需启用，你需要同时完成以下配置： + +1. 在 PD 侧开启调度器对网络慢节点的处理： + + ```bash + scheduler config evict-slow-store-scheduler set enable-network-slow-store true + ``` + +2. 在 TiKV 侧将 [`raftstore.inspect-network-interval`](/tikv-configuration-file.md#inspect-network-interval-从-v855-版本开始引入) 配置项设置为大于 `0` 的值，以启用网络探测。 + +#### 恢复时间控制 + +你可以通过 `recovery-duration` 参数控制慢节点在被判定为恢复正常前需要保持稳定状态的时间。 + +示例如下： + +```bash +>> scheduler config evict-slow-store-scheduler +{ + "recovery-duration": "1800" // 30 分钟 +} +>> scheduler config evict-slow-store-scheduler set recovery-duration 600 +``` + ### `scheduler config balance-leader-scheduler` 用于查看和控制 `balance-leader-scheduler` 策略。 @@ -1452,15 +1490,17 @@ store weight 1 5 10 通过 `store-limit`，你可以设置 store 的调度速度。关于 `store limit` 的原理和使用方法，请参考 [`store limit`](/configure-store-limit.md)。 ```bash ->> store limit // 显示所有 store 添加和删除 peer 的速度上限 ->> store limit add-peer // 显示所有 store 添加 peer 的速度上限 ->> store limit remove-peer // 显示所有 store 删除 peer 的速度上限 ->> store limit all 5 // 设置所有 store 添加和删除 peer 的速度上限为每分钟 5 个 ->> store limit 1 5 // 设置 store 1 添加和删除 peer 的速度上限为每分钟 5 个 ->> store limit all 5 add-peer // 设置所有 store 添加 peer 的速度上限为每分钟 5 个 ->> store limit 1 5 add-peer // 设置 store 1 添加 peer 的速度上限为每分钟 5 个 ->> store limit 1 5 remove-peer // 设置 store 1 删除 peer 的速度上限为每分钟 5 个 ->> store limit all 5 remove-peer // 设置所有 store 删除 peer 的速度上限为每分钟 5 个 +>> store limit // 显示所有 store 添加和删除 peer 的速度上限 +>> store limit add-peer // 显示所有 store 添加 peer 的速度上限 +>> store limit remove-peer // 显示所有 store 删除 peer 的速度上限 +>> store limit all 5 // 设置所有 store 添加和删除 peer 的速度上限为每分钟 5 个 +>> store limit 1 5 // 设置 store 1 添加和删除 peer 的速度上限为每分钟 5 个 +>> store limit all 5 add-peer // 设置所有 store 添加 peer 的速度上限为每分钟 5 个 +>> store limit 1 5 add-peer // 设置 store 1 添加 peer 的速度上限为每分钟 5 个 +>> store limit 1 5 remove-peer // 设置 store 1 删除 peer 的速度上限为每分钟 5 个 +>> store limit all 5 remove-peer // 设置所有 store 删除 peer 的速度上限为每分钟 5 个 +>> store limit all engine tikv 5 remove-peer // 从 v8.5.5 起，支持设置所有 TiKV store 删除 peer 的速度上限，该示例将所有 TiKV store 删除 peer 的速度上限设置为每分钟 5 个 +>> store limit all engine tiflash 5 remove-peer // 从 v8.5.5 起，支持设置所有 TiFlash store 删除 peer 的速度上限，该示例将所有 TiFlash store 删除 peer 的速度上限设置为每分钟 5 个 ``` > **注意：** diff --git a/sql-statements/sql-statement-alter-table.md b/sql-statements/sql-statement-alter-table.md index 91701dbda670..5fc6ee3761f6 100644 --- a/sql-statements/sql-statement-alter-table.md +++ b/sql-statements/sql-statement-alter-table.md @@ -54,6 +54,7 @@ AlterTableSpec ::= | TTLEnable EqOpt ( 'ON' | 'OFF' ) | TTLJobInterval EqOpt stringLit ) +| 'AFFINITY' EqOpt stringLit | PlacementPolicyOption PlacementPolicyOption ::= @@ -172,6 +173,7 @@ TiDB 中的 `ALTER TABLE` 语法主要存在以下限制： - 不支持分区表上的列类型变更。 - 不支持生成列上的列类型变更。 - 不支持部分数据类型（例如，部分时间类型、Bit、Set、Enum、JSON 等）的变更，因为 TiDB 中的 `CAST` 函数与 MySQL 的行为存在兼容性问题。 +- `AFFINITY` 选项为 TiDB 扩展语法。开启 `AFFINITY` 后，不支持变更该表的分区方案（如添加、删除、重组或交换分区），需要先移除 `AFFINITY`。 - 不支持空间数据类型。 - `ALTER TABLE t CACHE | NOCACHE` 不是 MySQL 标准语法，而是 TiDB 扩展功能，参见[缓存表](/cached-tables.md)。 diff --git a/sql-statements/sql-statement-create-table.md b/sql-statements/sql-statement-create-table.md index 7b4fdd224fc3..2c571491dad6 100644 --- a/sql-statements/sql-statement-create-table.md +++ b/sql-statements/sql-statement-create-table.md @@ -117,6 +117,7 @@ TableOption ::= | 'UNION' EqOpt '(' TableNameListOpt ')' | 'ENCRYPTION' EqOpt EncryptionOpt | 'TTL' EqOpt TimeColumnName '+' 'INTERVAL' Expression TimeUnit (TTLEnable EqOpt ( 'ON' | 'OFF' ))? (TTLJobInterval EqOpt stringLit)? +| 'AFFINITY' EqOpt StringName | PlacementPolicyOption OnCommitOpt ::= @@ -170,10 +171,12 @@ TiDB 支持以下 `table_option`。TiDB 会解析并忽略其他 `table_option` |`CHARACTER SET` |指定该表所使用的[字符集](/character-set-and-collation.md) | `CHARACTER SET` = 'utf8mb4'| |`COLLATE` |指定该表所使用的字符集排序规则 | `COLLATE` = 'utf8mb4_bin'| |`COMMENT` |注释信息 | `COMMENT` = 'comment info'| +|`AFFINITY` |为表或分区开启亲和性调度。非分区表可设置为 `'table'`，分区表可设置为 `'partition'`。设置为 `'none'` 或留空可关闭亲和性调度 |`AFFINITY` = 'table'| > **注意：** > -> 在 TiDB 配置文件中，`split-table` 默认开启。当该配置项开启时，建表操作会为每个表建立单独的 Region，详情参见 [TiDB 配置文件描述](/tidb-configuration-file.md)。 +> - 在 TiDB 配置文件中，`split-table` 默认开启。当该配置项开启时，建表操作会为每个表建立单独的 Region，详情参见 [TiDB 配置文件描述](/tidb-configuration-file.md)。 +> - 使用 `AFFINITY` 时，当前不支持对该表进行分区方案变更（如添加、删除、重组或交换分区），也不支持在临时表或视图上设置该选项。 ## 示例 diff --git a/sql-statements/sql-statement-show-affinity.md b/sql-statements/sql-statement-show-affinity.md new file mode 100644 index 000000000000..500d16fbd2c1 --- /dev/null +++ b/sql-statements/sql-statement-show-affinity.md @@ -0,0 +1,61 @@ +--- +title: SHOW AFFINITY +summary: 介绍 TiDB 数据库中 SHOW AFFINITY 的使用概况。 +--- + +# SHOW AFFINITY 从 v8.5.5 开始引入 + +`SHOW AFFINITY` 语句用于查看配置了 `AFFINITY` 选项的表的[亲和性](/table-affinity.md)调度信息，以及 PD 当前记录的目标副本分布。 + +## 语法图 + +```ebnf+diagram +ShowAffinityStmt ::= + "SHOW" "AFFINITY" ShowLikeOrWhereOpt +``` + +`SHOW AFFINITY` 支持使用 `LIKE` 或 `WHERE` 子句过滤表名。 + +## 示例 + +以下示例创建两个启用了亲和性调度的表，并查看其调度信息： + +```sql +CREATE TABLE t1 (a INT) AFFINITY = 'table'; +CREATE TABLE tp1 (a INT) AFFINITY = 'partition' PARTITION BY HASH(a) PARTITIONS 2; + +SHOW AFFINITY; +``` + +输出结果示例如下： + +```sql ++---------+------------+----------------+-----------------+------------------+----------+--------------+----------------------+ +| Db_name | Table_name | Partition_name | Leader_store_id | Voter_store_ids | Status | Region_count | Affinity_region_count| ++---------+------------+----------------+-----------------+------------------+----------+--------------+----------------------+ +| test | t1 | NULL | 1 | 1,2,3 | Stable | 8 | 8 | +| test | tp1 | p0 | 4 | 4,5,6 | Preparing| 4 | 2 | +| test | tp1 | p1 | 4 | 4,5,6 | Preparing| 3 | 2 | ++---------+------------+----------------+-----------------+------------------+----------+--------------+----------------------+ +``` + +各列含义如下： + +- `Leader_store_id`、`Voter_store_ids`：PD 为该表或分区记录的目标 Leader 副本和 Voter 副本所在的 TiKV Store ID。如果亲和性分组尚未确定目标副本位置或 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-版本开始引入) 为 `0`，则显示为 `NULL`。 +- `Status`：表示当前亲和性调度的状态。可能的取值如下： + - `Pending`：PD 尚未对该表或分区进行亲和性调度（比如未确定 Leader 或 Voter 时）。 + - `Preparing`：PD 正在调度 Region 以满足亲和性要求。 + - `Stable`：所有 Region 已达到目标分布。 +- `Region_count`：当前在该亲和性组中的 Region 数量。 +- `Affinity_region_count`：当前已满足亲和性副本分布要求的 Region 数量。 + - 当 `Affinity_region_count` 小于 `Region_count` 时，表示仍有部分 Region 尚未完成基于亲和性的副本调度。 + - 当 `Affinity_region_count` 等于 `Region_count` 时，表示基于亲和性的 Region 副本迁移调度已完成，也就意味着所有 Region 的分布已经满足亲和性要求，但并不代表相关 Region 的合并操作已完成。 + +## MySQL 兼容性 + +该语句是 TiDB 对 MySQL 语法的扩展。 + +## 另请参阅 + +- [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md) +- [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index ac0b98811040..34432d0e71d3 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -373,6 +373,11 @@ SQL 的基础信息： - `MAX_QUEUED_RC_TIME`：执行 SQL 语句等待可用 RU 的最大耗时 - `RESOURCE_GROUP`：执行 SQL 语句绑定的资源组 +和存储引擎相关的字段： + +- `STORAGE_KV`：从 v8.5.5 开始引入，表示该类 SQL 语句上一次执行是否从 TiKV 读取了数据。 +- `STORAGE_MPP`：从 v8.5.5 开始引入，表示该类 SQL 语句上一次执行是否从 TiFlash 读取了数据。 + ### `statements_summary_evicted` 字段介绍 - `BEGIN_TIME`: 记录的开始时间； diff --git a/system-variables.md b/system-variables.md index b087d1d036c6..fc15c18a6539 100644 --- a/system-variables.md +++ b/system-variables.md @@ -877,6 +877,16 @@ mysql> SHOW GLOBAL VARIABLES LIKE 'max_prepared_stmt_count'; - 单位：字节 - 这个变量用于控制当 [`replica-read`](#tidb_replica_read-从-v40-版本开始引入) 设置为 `closest-adaptive` 时，优先将读请求发送至 TiDB server 所在区域副本的阈值。当读请求预估的返回结果的大小超过此阈值时，TiDB 会将读请求优先发送至同一可用区的副本，否则会发送至 leader 副本。 +### `tidb_advancer_check_point_lag_limit` 从 v8.5.5 版本开始引入 + +- 作用域：GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 +- 类型：Duration +- 默认值：`48h0m0s` +- 范围：`[1s, 8760h0m0s]` +- 该变量用于控制日志备份任务 Checkpoint 的滞后时间限制。如果日志备份任务 Checkpoint 的滞后时间超过了限制，TiDB Advancer 会暂停该任务。 + ### `tidb_allow_tiflash_cop` 从 v7.3.0 版本开始引入 - 作用域：SESSION | GLOBAL @@ -1245,6 +1255,15 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - 这个变量用于控制是否开启[自动捕获绑定](/sql-plan-management.md#自动捕获绑定-baseline-capturing)功能。该功能依赖 Statement Summary，因此在使用自动绑定之前需打开 Statement Summary 开关。 - 开启该功能后会定期遍历一次 Statement Summary 中的历史 SQL 语句，并为至少出现两次的 SQL 语句自动创建绑定。 +### `tidb_cb_pd_metadata_error_rate_threshold_ratio` 从 v8.5.5 版本开始引入 + +- 作用域：GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 +- 默认值：`0` +- 取值范围：`[0, 1]` +- 该变量用于控制 TiDB 何时触发熔断器。设置为 `0`（默认值）表示禁用熔断器。设置为 `0.01` 到 `1` 之间的值时，表示启用熔断器，当发送到 PD 的特定请求的错误率达到或超过该阈值时，熔断器会被触发。 + ### `tidb_cdc_write_source` 从 v6.5.0 版本开始引入 - 作用域：SESSION @@ -3003,6 +3022,19 @@ v5.0 后，用户仍可以单独修改以上系统变量（会有废弃警告） - 这个变量用来设置 index lookup join 算法的并发度。 - 默认值 `-1` 表示使用 `tidb_executor_concurrency` 的值。 +### `tidb_index_lookup_pushdown_policy` 从 v8.5.5 版本开始引入 + +- 作用域：SESSION | GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：是 +- 类型：枚举型 +- 默认值：`hint-only` +- 可选值：`hint-only`，`affinity-force`，`force` +- 该变量用于控制 TiDB 是否以及在什么条件下将 `IndexLookUp` 算子下推到 TiKV。可选值的含义如下： + - `hint-only`（默认值）：仅在 SQL 中显式指定 [`INDEX_LOOKUP_PUSHDOWN`](/optimizer-hints.md#index_lookup_pushdownt1_name-idx1_name--idx2_name--从-v855-版本开始引入) Hint 时，才将 `IndexLookUp` 算子下推到 TiKV。 + - `affinity-force`：仅对配置了 `AFFINITY` 选项的表自动启用下推。 + - `force`：对所有表开启 `IndexLookUp` 算子下推。 + ### `tidb_index_merge_intersection_concurrency` 从 v6.5.0 版本开始引入 - 作用域：SESSION | GLOBAL diff --git a/table-affinity.md b/table-affinity.md new file mode 100644 index 000000000000..f0a818fd0667 --- /dev/null +++ b/table-affinity.md @@ -0,0 +1,109 @@ +--- +title: 表级数据亲和性 +summary: 通过为表或分区配置亲和性约束，控制 Region 副本的分布并查看调度状态。 +--- + +# 表级数据亲和性 从 v8.5.5 开始引入 + +> **警告：** +> +> 该功能为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。 + +表级数据亲和性是 PD 在表级别上的数据分布调度机制，用于控制同一个表或分区中 Region 的 Leader 和 Voter 副本在 TiKV 集群中的分布。 + +开启 PD 数据亲和性调度，并将表的 `AFFINITY` 选项设置为 `table` 或 `partition` 后，PD 会将同一张表或同一个分区的 Region 归入同一个亲和性分组，并在调度过程中优先将这些 Region 的 Leader 和 Voter 副本放置到相同的少数 TiKV 节点上，从而减少查询过程中跨节点访问带来的网络延迟，提升查询性能。 + +## 使用限制 + +使用表级数据亲和性前，请注意以下限制： + +- 在 [PD 微服务模式](/pd-microservices.md)下，该功能不会生效。 +- [临时表](/temporary-tables.md)和[视图](/views.md)不支持配置数据亲和性。 +- 为[分区表](/partitioned-table.md)配置数据亲和性后，**不支持修改该表的分区方案**，包括新增、删除、重组或交换分区。如需调整分区配置，请先移除该表的亲和性设置。 +- **数据量较大时需提前评估磁盘容量**：开启数据亲和性后，PD 会优先将表或分区的 Region 调度到相同的少数 TiKV 节点上。对于数据量较大的表或分区，可能导致这些节点的磁盘使用率显著升高。建议提前评估磁盘容量并做好监控。 +- 数据亲和性调度仅影响 Leader 和 Voter 副本的分布。如果表有 Learner 副本（如 TiFlash），Learner 副本的分布不受亲和性配置影响。 + +## 前提条件 + +PD 亲和性调度特性默认关闭。在设置表或分区的亲和性前，请开启并配置该特性。 + +1. 将 PD 配置项 [`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-版本开始引入) 设置为大于 `0` 的值，以开启 PD 的亲和性调度。 + + 例如，执行以下命令将该配置项设置为 `4`，表示允许 PD 最多同时执行 4 个亲和性调度任务： + + ```bash + pd-ctl config set schedule.affinity-schedule-limit 4 + ``` + +2. （可选）根据需要设置 PD 配置项 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-版本开始引入)（默认值为 `256`，单位为 MiB），用于控制属于同一亲和性分组中相邻的小 Region 自动合并的阈值。设置为 `0` 表示关闭亲和性分组中相邻的小 Region 的自动合并。 + +## 使用方法 + +本节介绍如何配置表或分区的亲和性，以及如何查看亲和性调度状态。 + +### 配置表或分区的亲和性 + +你可以通过 `CREATE TABLE` 或 `ALTER TABLE` 语句中的 `AFFINITY` 选项配置表或分区的亲和性。 + +| 亲和性等级 | 适用范围 | 效果 | +|---|---|---| +| `AFFINITY='table'` | 非分区表 | 开启该表的亲和性，PD 会为此表的所有 Region 创建一个亲和性分组。 | +| `AFFINITY='partition'` | 分区表 | 开启该表中每个分区的亲和性，PD 会为此表的**每个分区**对应的 Region 分别创建独立的亲和性分组。例如，当表包含 4 个分区时，PD 将为该表创建 4 个相互独立的亲和性分组。 | +| `AFFINITY=''` 或 `AFFINITY='none'` | 已设置 `AFFINITY='table'` 或 `AFFINITY='partition'` 的表 | 关闭该表或分区的亲和性。设置后，PD 会删除对应表或分区的亲和性分组，表或分区的 Region 将不再受到亲和性调度约束。TiKV 上 Region 的自动分裂将在最长 10 分钟内恢复为默认状态。 | + +**示例**： + +创建非分区表时开启该表的亲和性： + +```sql +CREATE TABLE t1 (a INT) AFFINITY = 'table'; +``` + +创建分区表时开启该表中每个分区的亲和性： + +```sql +CREATE TABLE tp1 (a INT) + AFFINITY = 'partition' + PARTITION BY HASH(a) PARTITIONS 4; +``` + +为现有非分区表开启亲和性： + +```sql +CREATE TABLE t2 (a INT); +ALTER TABLE t2 AFFINITY = 'table'; +``` + +关闭表的亲和性： + +```sql +ALTER TABLE t1 AFFINITY = ''; +``` + +### 查看亲和性 + +可以通过以下方式查看表或分区的亲和性信息： + +- 执行 [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) 语句，在 `Status` 列查看已开启亲和性的表或分区及其调度状态。`Status` 列的值含义如下： + + - `Pending`：PD 尚未对该表或分区进行亲和性调度，比如未确定 Leader 或 Voter 时。 + - `Preparing`：PD 正在调度 Region 以满足亲和性要求。 + - `Stable`：所有 Region 已达到目标分布。 + +- 查询 [`INFORMATION_SCHEMA.TABLES`](/information-schema/information-schema-tables.md) 表的 `TIDB_AFFINITY` 列查看表的亲和性等级。 +- 查询 [`INFORMATION_SCHEMA.PARTITIONS`](/information-schema/information-schema-partitions.md) 表的 `TIDB_AFFINITY` 列查看分区的亲和性等级。 + +## 注意事项 + +- **Region 的自动分裂**：当 Region 属于某个亲和性分组且亲和性生效时，Region 默认不会自动分裂，以避免产生过多 Region 影响亲和性效果。只有当 Region 大小超过 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-版本开始引入) 值的四倍时，才会触发自动分裂。需要注意的是，非 TiKV 或 PD 自动触发的 Region 分裂（例如手动执行的 [`SPLIT TABLE`](/sql-statements/sql-statement-split-region.md)）不受此限制。 + +- **降级与过期机制**：如果亲和性分组中目标 Leader 或 Voter 所在的 TiKV 节点处于不可用状态（例如节点宕机或磁盘空间不足）、Leader 被驱逐，或与现有放置规则发生冲突时，PD 会将该亲和性分组标记为降级状态。在降级期间，对应表或分区的亲和性调度将暂停。 + + - 若相关节点在 10 分钟内恢复正常，PD 会继续按照原有亲和性设置进行调度。 + - 若超过 10 分钟仍未恢复，该亲和性分组将被标记为过期。此时 PD 会先恢复常规调度行为（[`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) 的状态会回到 `Pending`），然后自动更新亲和性分组中的 Leader 和 Voter，以重新启用亲和性调度。 + +## 相关语句与配置 + +- [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md) 和 [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) 的 `AFFINITY` 选项 +- [`SHOW AFFINITY`](/sql-statements/sql-statement-show-affinity.md) +- PD 配置项：[`schedule.affinity-schedule-limit`](/pd-configuration-file.md#affinity-schedule-limit-从-v855-版本开始引入) 和 [`schedule.max-affinity-merge-region-size`](/pd-configuration-file.md#max-affinity-merge-region-size-从-v855-版本开始引入) \ No newline at end of file diff --git a/tidb-configuration-file.md b/tidb-configuration-file.md index 20ca0f7fccb0..b6a88159ba33 100644 --- a/tidb-configuration-file.md +++ b/tidb-configuration-file.md @@ -637,6 +637,11 @@ TiDB 配置文件比命令行参数支持更多的选项。你可以在 [config/ + 当 `force-init-stats` 为 `true` 时，TiDB 启动时会等到统计信息初始化完成后再对外提供服务。需要注意的是，在表和分区数量较多且 [`lite-init-stats`](/tidb-configuration-file.md#lite-init-stats-从-v710-版本开始引入) 为 `false` 的情况下，`force-init-stats` 为 `true` 可能会导致 TiDB 从启动到开始对外提供服务的时间变长。 + 当 `force-init-stats` 为 `false` 时，TiDB 在统计信息初始化未完成时即可对外提供服务，但由于统计信息初始化未完成，优化器会用 pseudo 统计信息进行决策，可能会产生不合理的执行计划。 +### `enable-async-batch-get` 从 v8.5.5 版本开始引入 + ++ 用于控制 TiDB 是否使用异步方式执行 Batch Get 算子。使用异步方式能够降低 goroutine 开销，提供更优的性能。通常无需调整该配置项。 ++ 默认值：`false` + ## opentracing opentracing 的相关的设置。 diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md index 16ea7bf90057..1b2b11554740 100644 --- a/tikv-configuration-file.md +++ b/tikv-configuration-file.md @@ -208,6 +208,14 @@ TiKV 配置文件比命令行参数支持更多的选项。你可以在 [etc/con + 默认值：3s + 最小值：1s +### `graceful-shutdown-timeout` 从 v8.5.5 版本开始引入 + ++ TiKV 优雅关闭 (graceful shutdown) 的超时时长。 + + 当该值大于 `0s` 时，如果关闭 TiKV 节点，TiKV 在该超时时间内会尽量将其上的 leader 副本转移到其他 TiKV 节点，然后再关闭。若达到该超时时间后仍有 leader 未完成转移，TiKV 将跳过剩余 leader 的转移，直接进入关闭流程。 + + 当该值为 `0s` 时，表示不启用 TiKV 的 graceful shutdown 功能。 ++ 默认值：20s ++ 最小值：0s + ### `concurrent-send-snap-limit` + 同时发送 snapshot 的最大个数。 @@ -291,6 +299,13 @@ TiKV 配置文件比命令行参数支持更多的选项。你可以在 [etc/con + 设置服务与转发请求的连接池大小。设置过小会影响请求的延迟和负载均衡。 + 默认值：4 +### `inspect-network-interval` 从 v8.5.5 版本开始引入 + ++ 控制 TiKV HealthChecker 主动向 PD 以及其他 TiKV 节点发起网络探测的周期，用于计算 `NetworkSlowScore` 并向 PD 上报慢节点的网络状态。 ++ 设置为 `0` 表示关闭网络探测。数值越小，探测频率越高，有助于更快发现网络抖动，但也会消耗更多网络与 CPU 资源。 ++ 默认值：100ms ++ 取值范围：0 或 `[10ms, +∞)` + ## readpool.unified 统一处理读请求的线程池相关的配置项。该线程池自 4.0 版本起取代原有的 storage 和 coprocessor 线程池。 @@ -330,6 +345,17 @@ TiKV 配置文件比命令行参数支持更多的选项。你可以在 [etc/con + 是否开启自动调整线程池的大小。开启此配置可以基于当前的 CPU 使用情况，自动调整统一处理读请求的线程池 (UnifyReadPool) 的大小，优化 TiKV 的读性能。目前线程池自动调整的范围为：`[max-thread-count, MAX(4, CPU)]`(上限与 [`max-thread-count`](#max-thread-count) 可设置的最大值相同)。 + 默认值：false +### `cpu-threshold` 从 v8.5.5 版本开始引入 + ++ 限制统一处理读请求的线程池 (UnifyReadPool) 可使用的最大 CPU 资源比例。例如，当该值为 `0.8` 时，该线程池最多可使用 80% 的 CPU。 + + 默认情况下（该值为 `0.0` 时），表示不限制 UnifyReadPool 的 CPU 资源比例，该线程池的规模完全由繁忙线程伸缩算法决定，该算法会根据当前处理任务的线程数量动态调整。 + + 当设置该值大于 `0.0` 时，TiKV 会在原有的繁忙线程伸缩算法基础上，引入以下 CPU 使用率阈值约束，以更严格地控制 CPU 资源使用： + + 强制缩减：当 UnifyReadPool 的CPU 使用率超过该配置项值加上 10% 的缓冲时，TiKV 会强制缩小 UnifyReadPool 的规模。 + + 阻止扩增：当扩大 UnifyReadPool 规模可能导致 CPU 使用率超过配置阈值减去 10% 的缓冲时，TiKV 会阻止 UnifyReadPool 继续扩大规模。 ++ 仅当 [`readpool.unified.auto-adjust-pool-size`](#auto-adjust-pool-size-从-v630-版本开始引入) 设置为 `true` 时生效。 ++ 默认值：`0.0` ++ 可调整范围：`[0.0, 1.0]` + ## readpool.storage 存储线程池相关的配置项。 @@ -1260,7 +1286,7 @@ RocksDB 相关的配置项。 ### `max-manifest-file-size` + RocksDB Manifest 文件最大大小。 -+ 默认值：256MiB。在 v8.5.3 及之前的 v8.5.x 版本中，默认值为 `128MiB`。 ++ 默认值：128MiB + 最小值：0 + 单位：B|KiB|MiB|GiB diff --git a/upgrade-tidb-using-tiup.md b/upgrade-tidb-using-tiup.md index 31c76ed5fa5e..10ca0dd402e0 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -68,6 +68,7 @@ summary: TiUP 可用于 TiDB 升级。升级过程中需注意不支持 TiFlash - TiDB v8.5.2 [Release Notes](/releases/release-8.5.2.md) - TiDB v8.5.3 [兼容性变更](/releases/release-8.5.3.md#兼容性变更) - TiDB v8.5.4 [兼容性变更](/releases/release-8.5.4.md#兼容性变更) +- TiDB v8.5.5 [兼容性变更](https://docs.pingcap.com/zh/tidb/v8.5/release-8.5.5/#兼容性变更) ### 2.2 升级 TiUP 或更新 TiUP 离线镜像 diff --git a/variables.json b/variables.json index c103ddef8b9f..603b3e81d30a 100644 --- a/variables.json +++ b/variables.json @@ -1,7 +1,7 @@ { "tidb": "TiDB", - "tidb-version": "8.5.4", - "tidb-release-date": "2025-11-27", + "tidb-version": "8.5.5", + "tidb-release-date": "2026-01-15", "starter": "TiDB Cloud Starter", "essential": "TiDB Cloud Essential", "dedicated": "TiDB Cloud Dedicated",