当前位置：首页 > news >正文

【赵渝强老师】TiDB提供的命令行工具

news 来源：原创 2025/4/21 14:38:45

在这里插入图片描述

TiDB数据库提供了以下几款命令行工具，用于操作和管理TiDB集群中的节点。这几款工具主要包括：

TiDB的命令行工具：tidb-ctl
TiKV的命令行工具：tikv-ctl
PD的命令行工具：pd-ctl
集群管理工具：TiUP

视频讲解如下
【赵渝强老师】TiDB提供的命令行工具

下面分别进行介绍

一、 TiDB的命令行工具：tidb-ctl

TiDB Control（简称tidb-ctl）是TiDB的命令行工具，用于获取TiDB状态信息，多用于调试。tidb-ctl工具位于中控机的.tiup/components/ctl/v8.5.1目录下。下面通过几个示例来演示该工具的使用方法。

（1）查看scott数据库中所有表的结构信息。

# ./tidb-ctl schema --host 192.168.79.11 in scott
输出的信息如下：
[{"id": 121,"name": {"O": "dept","L": "dept"},"charset": "utf8mb4","collate": "utf8mb4_bin","cols": [{"id": 1,"name": {"O": "deptno","L": "deptno"},"offset": 0,"origin_default": null,"origin_default_bit": null,"default": null,......"comment": "","hidden": false,"change_state_info": null,"version": 2},{"id": 2,"name": {"O": "dname","L": "dname"},......},{"id": 3,"name": {"O": "loc","L": "loc"},......}],......},{"id": 123,"name": {"O": "emp","L": "emp"},.....}
]

（2）查看scott数据库中部门表dept的结构信息。

# ./tidb-ctl schema --host 192.168.79.11 in scott -n dept

（3）查看scott数据库中员工表emp的Region信息。

# ./tidb-ctl table regions --host 192.168.79.11 -d scott -t emp
输出的信息如下：
{"name": "emp","id": 123,"record_regions": [{"region_id": 3760,"leader": {"id": 3763,"store_id": 5},"peers": [{"id": 3761,"store_id": 1},{"id": 3762,"store_id": 4},{"id": 3763,"store_id": 5}],"region_epoch": {"conf_ver": 5,"version": 77}}],"indices": [{"name": "fk_1","id": 1,"regions": [{"region_id": 3760,"leader": {"id": 3763,"store_id": 5},"peers": [{"id": 3761,"store_id": 1},{"id": 3762,"store_id": 4},{"id": 3763,"store_id": 5}],"region_epoch": {"conf_ver": 5,"version": 77}}]}]
}提示：通过下面的方式也可以查看表的Region信息。
tidb> show table emp regions \G;
*************************** 1. row ***************************REGION_ID: 3760START_KEY: t_113_END_KEY: 78000000LEADER_ID: 3763LEADER_STORE_ID: 5PEERS: 3761, 3762, 3763SCATTERING: 0WRITTEN_BYTES: 0READ_BYTES: 7080APPROXIMATE_SIZE(MB): 2APPROXIMATE_KEYS: 4208
SCHEDULING_CONSTRAINTS: SCHEDULING_STATE: 
1 row in set (0.011 sec)

二、 TiKV的命令行工具：tikv-ctl

TiKVControl（以下简称tikv-ctl）是TiKV的命令行工具，用于管理TiKV集群。如果是使用TiUP部署的集群。该命令行工具在中控机的~/.tiup/components/ctl/{VERSION}/目录下。因此首先在中控机上将tikv-ctl复制到TiKV的节点上。

# cd /root/.tiup/components/ctl/v8.5.1
# scp tikv-ctl root@192.168.79.11:/usr/bin提示：tikv-ctl也可以通过指定--host参数运行在远程模式下。

下面通过具体的示例来演示如何使用tikv-ctl。
（1）在中控机上查看集群的TiKV节点的数据存储目录信息。

# tiup cluster display mytidb-cluster -R tikv
输出的信息如下：
Cluster type:       tidb
Cluster name:       mytidb-cluster
Cluster version:    v8.5.1
Deploy user:        tidb
SSH type:           builtin
ID                   Role  ...  Data Dir               ...
--                   ----  ...  --------               ...
192.168.79.11:20160  tikv  ...  /tidb-data/tikv-20160  ...
192.168.79.12:20160  tikv  ...  /tidb-data/tikv-20160  ...
192.168.79.13:20160  tikv  ...  /tidb-data/tikv-20160  ...
Total nodes: 3

（2）在TiKV节点上检查Regions是否健康

# tikv-ctl --data-dir=/tidb-data/tikv-20160 bad-regions
将出现下面的错误信息：
Failed to lock file: Resource temporarily unavailable (os error 11), 
maybe another instance is using this directory.提示：该检查命令是一个脱机命令，因此需要通过下面的命令停止TiDB集群。
# tiup cluster stop mytidb-cluster重新执行上面的命令将输出下面的结果：
all regions are healthy

（3）查看TiKV上所有的键值对

-- 分页显示键值对
# tikv-ctl --data-dir=/tidb-data/tikv-20160 raw-scan | more-- 将TiKV上所有的键值对转向输出到文件
# tikv-ctl --data-dir=/tidb-data/tikv-20160 raw-scan > /root/kv.txt
输出内容如下所示：
key: "\001\001", value: "\010\346\221\216\351\204\312\337\340g\020\004"
key: "zmDB:1\000\000\000\377\000\373\000\000\000\000\000\000\377\000hTable:\37710\377\000\000\000\000\000\377\
000\000\000\367\000\000\000\000\373\371\252\320\252\025w\377\366", value: "{\"id\":10,\"name\":{\"O\":\"db\",\
"L\":\"db\"},\"charset\":\"utf8mb4\",\"collate\":\"utf8mb4_bin\",\"cols\":[{\"id\":1,\"name\":{\"O\":\"Host\",
\"L\":\"host\"},\"offset\":0,\"origin_default\":null,\"origin_default_bit
......

（4）通过Key查看Value的值。

# tikv-ctl --data-dir=/tidb-data/tikv-20160 print -k "\001\001"输出的信息如下：
value: \010\346\221\216\351\204\312\337\340g\020\004

（5）查看TiKV上的Region大小。

-- 查看所有Region的大小
# tikv-ctl --data-dir=/tidb-data/tikv-20160 size
输出的信息如下：
......
region id: 3760
cf default region size: 1.606MiB
cf write region size: 32626B
cf lock region size: 0B
region id: 8874
cf default region size: 0B
cf write region size: 3404B
cf lock region size: 0B
......-- 查看Region ID为8874的大小
# tikv-ctl --data-dir=/tidb-data/tikv-20160 size -r 8874
输出的信息如下：
region id: 8874
cf default region size: 0B
cf write region size: 3404B
cf lock region size: 0B

《TiDB数据库从零开始》

三、 PD的命令行工具：pd-ctl

PD Control（简称：pd-ctl）是PD的命令行工具，用于获取集群状态信息和调整集群。tidb-ctl工具位于中控机的.tiup/components/ctl/v8.5.1目录下。下面通过几个简单的示例来演示其用法。
（1）获取TiDB集群的状态信息。

# ./pd-ctl cluster status --pd http://192.168.79.11:2379输出的信息如下：
{"raft_bootstrap_time": "2025-02-28T17:13:53.332180613+08:00","is_initialized": true,"replication_status": ""
}

（2）获取TiDB集群中的Store信息，即：TiKV节点和TIFlash节点。

# ./pd-ctl store check up --pd http://192.168.79.11:2379
输出的信息如下：
{"count": 6,"stores": [{"store": {"id": 1,"address": "192.168.79.13:20160","labels": [{"key": "host","value": "Chongqing"}],"version": "8.5.1","peer_address": "192.168.79.13:20160","status_address": "192.168.79.13:20180",......"state_name": "Up"},"status": {"capacity": "45.02GiB","available": "34.36GiB","used_size": "1.286GiB","leader_count": 3,"leader_weight": 1,"leader_score": 3,"leader_size": 3,"region_count": 7,......}},{"store": {"id": 4,"address": "192.168.79.11:20160","labels": [{"key": "host","value": "Beijing"}],......},"status": {......}},{"store": {"id": 5,"address": "192.168.79.12:20160","labels": [{"key": "host","value": "Shanghai"}],......},"status": {......}},{"store": {"id": 277,"address": "192.168.79.11:3930","labels": [{"key": "engine","value": "tiflash"},{"key": "zone","value": "beijing"}],......},"status": {......}},{"store": {"id": 278,"address": "192.168.79.12:3930","labels": [{"key": "engine","value": "tiflash"},{"key": "zone","value": "shanghai"}],......},"status": {......}},{"store": {"id": 279,"address": "192.168.79.13:3930","labels": [{"key": "engine","value": "tiflash"},{"key": "zone","value": "chongqing"}],......},"status": {......}}]
}

四、集群管理工具：TiUP

从TiDB v4.0起，提供了包管理工具TiUP，负责管理TiDB、PD、TiKV等组件。只需通过TiUP命令即可运行这些组件，显著降低了管理难度。下面展示了TIUP的帮助信息。

# tiup --help
输出信息如下：
......
Usage:tiup [flags] <command> [args...]tiup [flags] <component> [args...]tiup [command]
......
Available Commands:install     Install a specific version of a componentlist        List the available TiDB components or versionsuninstall   Uninstall components or versions of a componentupdate      Update tiup components to the latest versionstatus      List the status of instantiated componentsclean       Clean the data of instantiated componentsmirror      Manage a repository mirror for TiUP componentstelemetry   Controls things about telemetryenv         Show the list of system environment variable that related to TiUPhistory     Display the historical execution record of TiUP, 
displays 100 lines by defaultlink        Link component binary to $TIUP_HOME/bin/unlink      Unlink component binary to $TIUP_HOME/bin/help        Help about any commandcompletion  Generate the autocompletion script for the specified shell
......提示：TIUP的具体使用方法将在后续进行详细介绍。