Skip to content

update document of tidb-ctl #3189

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
May 25, 2020
Merged

update document of tidb-ctl #3189

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
fdfcb11
update document of tidb-ctl
May 21, 2020
d7ce8f7
fix lint
May 21, 2020
0b67e7a
address comment
May 22, 2020
00fcc68
address comment
May 22, 2020
4b0f526
address comment
May 22, 2020
a425e5d
Update tidb-control.md
May 25, 2020
4c4d10a
Merge branch 'docs-special-week' into update_tidb_ctl
yikeke May 25, 2020
4b0effb
Merge branch 'docs-special-week' into update_tidb_ctl
May 25, 2020
5f84af9
Merge branch 'docs-special-week' into update_tidb_ctl
sre-bot May 25, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 67 additions & 34 deletions tidb-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,19 @@ aliases: ['/docs-cn/dev/reference/tools/tidb-control/','/docs-cn/tools/tidb-cont

# TiDB Control 使用说明

TiDB Control 是 TiDB 的命令行工具，用于获取 TiDB 状态信息，多用于调试。
TiDB Control 是 TiDB 的命令行工具，用于获取 TiDB 状态信息，多用于调试。本文介绍了 TiDB Control 的主要功能和各个功能的使用方法。

## 源码编译
## 获取 TiDB Control

编译环境要求：[Go](https://golang.org/) Version 1.7 以上
本节提供了两种方式获取 TiDB Control 工具。

### 通过 TiUP 安装

在安装 TiUP 之后， 可以使用 `tiup ctl tidb` 命令来获取 TiDB Control 的二进制程序以及运行 TiDB Control。

### 从源代码编译安装

编译环境要求：[Go](https://golang.org/) Version 1.13 以上

编译步骤：在 [TiDB Control 项目](https://github.com/pingcap/tidb-ctl)根目录，使用 `make` 命令进行编译，生成 tidb-ctl。

Expand All @@ -28,13 +36,28 @@ TiDB Control 是 TiDB 的命令行工具，用于获取 TiDB 状态信息，多
* -n: 选项
* db: -n 的参数

目前，TiDB Control 包含以下子命令。

* `tidb-ctl base64decode` 用于 BASE64 解码
* `tidb-ctl decoder` 用于 KEY 解码
* `tidb-ctl etcd` 用于操作 etcd
* `tidb-ctl log` 用于格式化日志文件，将单行的堆栈信息展开
* `tidb-ctl mvcc` 用于获取 MVCC 信息
* `tidb-ctl region` 用于获取 Region 信息
* `tidb-ctl schema` 用于获取 Schema 信息
* `tidb-ctl table` 用于获取 Table 信息

### 获取帮助

`tidb-ctl -h/--help` 用于获取帮助信息。tidb-ctl 由多层命令组成，tidb-ctl 及其所有子命令都可以通过 `-h/--help` 来获取使用帮助。

### 连接
以获取 Schema 信息为例：

通过 `tidb-ctl schema -h` 可以获取这个子命令的使用帮助。schema 有两个子命令——in 和 tid。in 用来通过数据库名获取数据库中所有表的表结构，tid 用来通过全数据库唯一的 table_id 获取表的表结构。

`tidb-ctl` 与连接相关的参数有 4 个，分别为：
### 全局参数

`tidb-ctl` 有 4 个与连接相关的全局参数，分别为：

- `--host` TiDB 服务地址
- `--port` TiDB 服务端口
Expand All @@ -46,28 +69,11 @@ TiDB Control 是 TiDB 的命令行工具，用于获取 TiDB 状态信息，多

其中 `--pdhost` 和 `--pdport` 主要是用于 `etcd` 子命令，例如：`tidb-ctl etcd ddlinfo`。如不添加地址和端口将使用默认值，TiDB/PD 服务默认的地址是 127.0.0.1 (服务地址只能使用 IP 地址)，TiDB 服务端口默认的端口是 10080，PD 服务端口默认的端口是 2379 **连接选项是全局选项，适用于以下所有命令。**

目前，TiDB Control 包含以下子命令，各个子命令的具体用法可以使用 `tidb-ctl SUBCOMMAND --help` 获取使用帮助：
### schema 命令

* `tidb-ctl base64decode` BASE64 解码
* `tidb-ctl decoder` 用于 KEY 解码
* `tidb-ctl etcd` 用于操作 etcd
* `tidb-ctl log` 格式化日志文件，将单行的堆栈信息展开
* `tidb-ctl mvcc` - MVCC 信息
* `tidb-ctl region` - Region 信息
* `tidb-ctl schema` - Schema 信息
* `tidb-ctl table` - Table 信息

### 使用举例
#### in 子命令

以获取 Schema 信息为例：

通过 `tidb-ctl schema -h` 可以获取这个子命令的使用帮助。schema 有两个子命令，in 和 tid。in 用来通过数据库名获取数据库中所有表的表结构，tid 用来通过全数据库唯一的 table_id 获取表的表结构。

#### in 命令

同样可以通过 `tidb-ctl schema in -h` 或 `tidb-ctl schema in --help` 来获取子命令 in 的使用帮助。

##### 基本用法
in 子命令用来通过数据库名获取数据库中所有表的表结构。

`tidb-ctl schema in {数据库名}`

Expand Down Expand Up @@ -111,10 +117,35 @@ TiDB Control 是 TiDB 的命令行工具，用于获取 TiDB 状态信息，多

如使用的 TiDB 地址不为默认地址和端口，可以使用命令行参数 `--host`, `--port` 选项，如：`tidb-ctl --host 172.16.55.88 --port 8898 schema in mysql -n db`。

#### base64decode 子命令
#### tid 子命令

tid 子命令用来通过表的 id 获取数据库中表的表结构。

通过使用 in 子命令查询到数据库中表的 id，之后可以通过 tid 子命令查看表的详细信息。

例如，查询到 `mysql.stat_meta` 表的 id 是 21，可以通过 `tidb-ctl schema tid -i 21` 查看表的详细信息。

```json
{
"id": 21,
"name": {
"O": "stats_meta",
"L": "stats_meta"
},
"charset": "utf8mb4",
"collate": "utf8mb4_bin",
...
}
```

同 in 子命令一样，如果使用的 TiDB 地址不是默认的地址和端口，需要通过 `--host` 和 `--port` 参数指定 TiDB 的地址和端口。

### base64decode 命令

`base64decode` 用来解码 base64 数据。

基本用法：

```shell
tidb-ctl base64decode [base64_data]
tidb-ctl base64decode [db_name.table_name] [base64_data]
Expand Down Expand Up @@ -219,17 +250,18 @@ tidb-ctl base64decode [table_id] [base64_data]
e not found in data
```

#### decoder 子命令
### decoder 命令

* 以下示例解码 row key，index key 类似。

{{< copyable "shell-regular" >}}

```shell
./tidb-ctl decoder -f table_row -k "t\x00\x00\x00\x00\x00\x00\x00\x1c_r\x00\x00\x00\x00\x00\x00\x00\xfa"
./tidb-ctl decoder "t\x00\x00\x00\x00\x00\x00\x00\x1c_r\x00\x00\x00\x00\x00\x00\x00\xfa"
```

```
format: table_row
table_id: -9223372036854775780
row_id: -9223372036854775558
```
Expand All @@ -239,15 +271,16 @@ tidb-ctl base64decode [table_id] [base64_data]
{{< copyable "shell-regular" >}}

```shell
./tidb-ctl decoder -f value -k AhZoZWxsbyB3b3JsZAiAEA==
./tidb-ctl decoder AhZoZWxsbyB3b3JsZAiAEA==
```

```
type: bytes, value: hello world
type: bigint, value: 1024
format: index_value
index_value[0]: {type: bytes, value: hello world}
index_value[1]: {type: bigint, value: 1024}
```

#### etcd 子命令
### etcd 命令

* `tidb-ctl etcd ddlinfo` 获取 DDL 信息。
* `tidb-ctl etcd putkey KEY VALUE` 添加 KEY VALUE 到 etcd (所有的 KEY 会添加到 `/tidb/ddl/all_schema_versions/` 之下)。
Expand All @@ -269,11 +302,11 @@ tidb-ctl base64decode [table_id] [base64_data]
tidb-ctl etcd delkey "/tidb/ddl/all_schema_versions/bar"
```

#### log 子命令
### log 命令

TiDB 错误日志的堆栈信息是一行的格式，可以使用 `tidb-ctl log` 将堆栈信息格式化成多行形式。

#### keyrange 子命令
### keyrange 命令

`keyrange` 子命令用于查询全局或表相关的关键 key range 信息，以十六进制形式输出。

Expand Down