https://docs.pingcap.com/zh/tidb/stable/tikv-control

TiKV Control（以下简称 tikv-ctl）是 TiKV 的命令行工具，用于管理 TiKV 集群。它的安装目录如下：

• 如果是使用 TiUP 部署的集群，在 ~/.tiup/components/ctl/{VERSION}/ 目录下。

通过 TiUP 使用 TiKV Control

tikv-ctl 也集成在了 tiup 命令中。执行以下命令，即可调用 tikv-ctl 工具：

你可以在 tiup ctl:v<CLUSTER_VERSION> tikv 后面再接上相应的参数与子命令。

通用参数

tikv-ctl 提供以下两种运行模式：

• 远程模式。通过 --host 选项接受 TiKV 的服务地址作为参数。在此模式下，如果 TiKV 启用了 SSL，则 tikv-ctl 也需要指定相关的证书文件，例如：

  tikv-ctl --ca-path ca.pem --cert-path client.pem --key-path client-key.pem --host 127.0.0.1:20160 <subcommands>

  某些情况下，tikv-ctl 与 PD 进行通信，而不与 TiKV 通信。此时你需要使用 --pd 选项而非 --host 选项，例如：

  tikv-ctl --pd 127.0.0.1:2379 compact-cluster
  store:"127.0.0.1:20160" compact db:KV cf:default range:([], []) success!

• 本地模式：

  • 通过 --data-dir 选项来指定本地 TiKV 数据的目录路径。
  • 通过 --config 选项来指定本地 TiKV 配置文件到路径。

  在此模式下，需要停止正在运行的 TiKV 实例。

以下如无特殊说明，所有命令都同时支持这两种模式。

除此之外，tikv-ctl 还有两个简单的命令 --to-hex 和 --to-escaped，用于对 key 的形式作简单的变换。一般使用 escaped 形式，示例如下：

各项子命令及部分参数、选项

下面逐一对 tikv-ctl 支持的子命令进行举例说明。有的子命令支持很多可选参数，要查看全部细节，可运行 tikv-ctl --help <subcommand>。

查看 Raft 状态机的信息

raft 子命令可以查看 Raft 状态机在某一时刻的状态。状态信息包括 RegionLocalState、RaftLocalState 和 RegionApplyState 三个结构体，及某一条 log 对应的 Entries。

可以使用 region 和 log 两个子命令分别查询以上信息。两条子命令都同时支持远程模式和本地模式。

对于 region 子命令：

• 要查看指定的 Region，可在命令中使用 -r 参数，多个 Region 以 , 分隔。也可以使用 --all-regions 参数来返回所有 Region（-r 与 --all-regions 不能同时使用）
• 要限制输出的 Region 的数量，可在命令中使用 --limit 参数（默认为 16）
• 要查询某个 key 范围中包含哪些 Region，可在命令中使用 --start 和 --end 参数（默认不限范围，采用 Hex 格式）

需要输出 ID 为 1239 的 Region 时，用法及输出内容如下所示：

需要查询某个 key 范围中包含哪些 Region 时，用法及输出内容如下所示：

• 当 key 范围包含在某个 Region 中时，将会输出该 Region 信息。
• 当 key 范围精准到某个 Region 的范围时，以上述 Region 1239 为例：当给定的 key 范围为 Region 1239 的范围时，由于 Region 范围为左闭右开区间，并且 Region 1009 以 Region 1239 的 end_key 作为 start_key，因此会同时输出 Region 1009 和 Region 1239 的信息。

查看 Region 的大小

使用 size 命令可以查看 Region 的大小：

扫描查看给定范围的 MVCC

scan 命令的 --from 和 --to 参数接受两个 escaped 形式的 raw key，并用 --show-cf 参数指定只需要查看哪些列族。

查看给定 key 的 MVCC

与 scan 命令类似，mvcc 命令可以查看给定 key 的 MVCC：

扫描 raw key

使用 raw-scan 命令，TiKV 可直接在 RocksDB 中扫描 raw key。

• 要指定扫描范围，可在 raw-scan 命令中使用 --from 和 --to 参数（默认不限范围）
• 要限制能够打印出的 key 的数量（默认为 30），可在命令中使用 --limit 参数
• 要指定扫描的 CF，可在命令中使用 --cf 参数（可选值为 default，write，lock）

打印某个 key 的值

打印某个 key 的值需要用到 print 命令。示例从略。

打印 Region 的 properties 信息

为了记录 Region 的状态信息，TiKV 将一些数据写入 Region 的 SST 文件中。你可以用子命令 region-properties 运行 tikv-ctl 来查看这些 properties 信息。例如：

这些 properties 信息可以用于检查某个 Region 是否健康或者修复不健康的 Region。例如，使用 middle_key_approximate_size 可以手动分裂 Region。

手动 compact 单个 TiKV 的数据

compact 命令可以对单个 TiKV 进行手动 compact。

• --from 和 --to 选项以 escaped raw key 形式指定 compact 的范围。如果没有设置，表示 compact 整个 TiKV。

• --region 选项指定 compact Region 的范围。如果设置，则 --from 和 --to 选项会被忽略。

• --db 选项可以指定要 compact 的 RocksDB，可选值为 kv 和 raft。

• --threads 选项可以指定 compact 的并发数，默认值是 8。一般来说，并发数越大，compact 的速度越快，但是也会对服务造成影响，所以需要根据情况选择合适的并发数。

• --bottommost 选项可以指定 compact 是否包括最下层的文件。可选值为 default、skip 和 force，默认为 default。

  • default 表示只有开启了 Compaction Filter 时 compact 才会包括最下层文件。
  • skip 表示 compact 不包括最下层文件。
  • force 表示 compact 总是包括最下层文件。

• 在本地模式 compact data，执行如下命令：

  tikv-ctl --data-dir /path/to/tikv compact --db kv

• 在远程模式 compact data，执行如下命令：

  tikv-ctl --host ip:port compact --db kv

手动 compact 整个 TiKV 集群的数据

compact-cluster 命令可以对整个 TiKV 集群进行手动 compact。该命令参数的含义和使用与 compact 命令一样。

设置一个 Region 副本为 tombstone 状态

tombstone 命令常用于没有开启 sync-log，因为机器掉电导致 Raft 状态机丢失部分写入的情况。它可以在一个 TiKV 实例上将一些 Region 的副本设置为 Tombstone 状态，从而在重启时跳过这些 Region，避免因为这些 Region 的副本的 Raft 状态机损坏而无法启动服务。这些 Region 应该在其他 TiKV 上有足够多的健康的副本以便能够继续通过 Raft 机制进行读写。

一般情况下，可以先在 PD 上将 Region 的副本通过 remove-peer 命令删除掉：

然后再用 tikv-ctl 在那个 TiKV 实例上将 Region 的副本标记为 tombstone 以便跳过启动时对他的健康检查：

但是有些情况下，当不能方便地从 PD 上移除这个副本时，可以指定 tikv-ctl 的 --force 选项来强制设置它为 tombstone：

向 TiKV 发出 consistency-check 请求

consistency-check 命令用于在某个 Region 对应的 Raft 副本之间进行一致性检查。如果检查失败，TiKV 自身会 panic。如果 --host 指定的 TiKV 不是这个 Region 的 Leader，则会报告错误。

Dump snapshot 元文件

这条子命令可以用于解析指定路径下的 Snapshot 元文件并打印结果。

打印 Raft 状态机出错的 Region

前面 tombstone 命令可以将 Raft 状态机出错的 Region 设置为 Tombstone 状态，避免 TiKV 启动时对它们进行检查。在运行 tombstone 命令之前，可使用 bad-regions 命令找到出错的 Region，以便将多个工具组合起来进行自动化的处理。

命令执行成功后会打印以上信息，否则会打印出有错误的 Region 列表。目前可以检出的错误包括 last index、commit index 和 apply index 之间的不匹配，以及 Raft log 的丢失。其他一些情况，比如 Snapshot 文件损坏等仍然需要后续的支持。

查看 Region 属性

• 本地查看部署在 /path/to/tikv 的 TiKV 上面 Region 2 的 properties 信息：

  tikv-ctl --data-dir /path/to/tikv/data region-properties -r 2

• 在线查看运行在 127.0.0.1:20160 的 TiKV 上面 Region 2 的 properties 信息：

  tikv-ctl --host 127.0.0.1:20160 region-properties -r 2

动态修改 TiKV 的配置

使用 modify-tikv-config 命令可以动态修改配置参数。目前可动态修改的 TiKV 配置与具体的修改行为与 SQL 动态修改配置功能相同，可参考在线修改 TiKV 配置。

• -n 用于指定完整的配置名。支持动态修改的配置名可以参考在线修改 TiKV 配置中支持的配置项列表。
• -v 用于指定配置值。

设置 shared block cache 的大小：

当禁用 shared block cache 时，为 write CF 设置 block cache size：

如果 compaction 的流量控制导致待 compact 数据量 (compaction pending bytes) 堆积，可以禁用 rate-limiter-auto-tuned 配置项或调高 compaction 相关的流量阈值。示例如下：

强制 Region 从多副本失败状态恢复服务（弃用）

unsafe-recover remove-fail-stores 命令可以将故障机器从指定 Region 的 peer 列表中移除。运行命令之前，需要目标 TiKV 先停掉服务以便释放文件锁。

-s 选项接受多个以逗号分隔的 store_id，并使用 -r 参数来指定包含的 Region。如果要对某一个 store 上的全部 Region 都执行这个操作，可简单指定 --all-regions。

之后启动 TiKV，这些 Region 便可以使用剩下的健康副本继续提供服务了。此命令常用于多个 TiKV store 损坏或被删除的情况。

恢复损坏的 MVCC 数据

recover-mvcc 命令用于 MVCC 数据损坏导致 TiKV 无法正常运行的情况。为了从不同种类的不一致情况中恢复，该命令会交叉检查 3 个 CF ("default", "write", "lock")。

• -r 选项可以通过 region_id 指定包含的 Region。
• -p 选项可以指定 PD 的 endpoints。

Ldb 命令

ldb 命令行工具提供多种数据访问以及数据库管理命令。下方列出了一些示例用法。详细信息请在运行 tikv-ctl ldb 命令时查看帮助消息或查阅 RocksDB 文档。

数据访问序列的示例如下：

用 HEX 格式 dump 现有 RocksDB 数据：

Dump 现有 RocksDB 的声明：

您可以通过 --column_family=<string> 指定查询的目标列族。

通过 --try_load_options 命令加载数据库选项文件以打开数据库。在数据库运行时，建议您保持该命令为开启的状态。如果您使用默认配置打开数据库，LSM-tree 存储组织可能会出现混乱，且无法自动恢复。

打印加密元数据

encryption-meta 命令用于打印加密元数据。该子命令可以打印两种加密元数据：数据文件的加密信息，以及所有的数据加密密钥。

使用 encryption-meta dump-file 子命令打印数据文件的加密信息。你需要创建一个 TiKV 配置文件用以指定 TiKV 的数据目录：

--path 选项可以指定数据文件的绝对或者相对路径。如果指定的文件是明文存储的，本命令有可能没有输出。如果不指定 --path 选项，本命令打印所有数据文件的加密信息。

使用 encryption-meta dump-key 打印数据加密密钥。使用本命令的时候，除了在 TiKV 配置文件中指定 TiKV 的数据目录以外，还需要指定当前的主加密密钥。请参阅静态加密文档关于配置 TiKV 主加密密钥的说明。使用本命令时 security.encryption.previous-master-key 配置项不生效，即使配置文件中使用了该配置，本命令也不会触发更换主加密密钥。

注意如果使用了 AWS KMS 作为主加密密钥，使用本命令时 tikv-ctl 需要该 KMS 密钥的访问权限。KMS 访问权限可以通过环境变量、AWS 默认配置文件或 IAM 的方式传递给 tikv-ctl。详情请参阅相关 AWS 文档。

--ids 选项可以指定以逗号分隔的数据加密密钥 id 列表。如果不指定 --ids 选项，本命令打印所有的数据加密密钥，以及最新的数据加密密钥的 id。

本命令会输出一个警告，提示本命令会泄漏敏感数据。根据提示输入 "I consent" 即可。

打印损坏的 SST 文件信息

TiKV 中损坏的 SST 文件会导致 TiKV 进程崩溃。在 TiDB v6.1.0 之前，损坏的 SST 文件会导致 TiKV 进程立即崩溃。从 TiDB v6.1.0 起，TiKV 进程会在 SST 文件损坏 1 小时后崩溃。

为了方便清理掉这些 SST 文件，你可以先使用 bad-ssts 命令打印出损坏的 SST 文件信息。

通过上面的输出，你可以看到损坏的 SST 文件和损坏原因等信息先被打印出，然后是相关的元信息。

• 在 sst meta 输出部分，14 表示 SST 文件号，552997 表示文件大小，紧随其后的是最小和最大的序列号 (seq) 等其它元信息。
• overlap region 部分为损坏 SST 文件所在 Region 的信息。该信息是从 PD 组件获取的。
• suggested operations 部分为你清理损坏的 SST 文件提供建议操作。你可以参考这些建议的命令，清理文件，并重新启动该 TiKV 实例。