diff --git a/tidb-control.md b/tidb-control.md index d8db9e85d99a2..330b176432436 100644 --- a/tidb-control.md +++ b/tidb-control.md @@ -7,11 +7,19 @@ aliases: ['/docs/stable/tidb-control/','/docs/v4.0/tidb-control/','/docs/stable/ # TiDB Control User Guide -TiDB Control is a command line tool of TiDB, usually used to obtain the status information of TiDB for debugging. +TiDB Control is a command-line tool of TiDB, usually used to obtain the status information of TiDB for debugging. This document introduces the features of TiDB Control and how to use these features. -## Compile from source code +## Get TiDB Control -- Compilation environment requirement: [Go](https://golang.org/) Version 1.7 or later +You can get TiDB Control by installing it using TiUP or by compiling it from source code. + +### Install TiDB Control using TiUP + +After installing TiUP, you can use `tiup ctl tidb` command to get and execute TiDB Control. + +### Compile from source code + +- Compilation environment requirement: [Go](https://golang.org/) Version 1.13 or later - Compilation procedures: Go to the root directory of the [TiDB Control project](https://github.com/pingcap/tidb-ctl), use the `make` command to compile, and generate `tidb-ctl`. - Compilation documentation: you can find the help files in the `doc` directory; if the help files are lost or you want to update them, use the `make doc` command to generate the help files. @@ -32,15 +40,33 @@ Usage example: `tidb-ctl schema in mysql -n db` - `-n`: the option - `db`: the flag of `-n` +Currently, TiDB Control has the following subcommands: + +- `tidb-ctl base64decode`: used for `BASE64` decoding +- `tidb-ctl decoder`: used for `KEY` decoding +- `tidb-ctl etcd`: used for operating etcd +- `tidb-ctl log`: used to format the log file to expand the single-line stack information +- `tidb-ctl mvcc`: used to get the MVCC information +- `tidb-ctl region`: used to get the Region information +- `tidb-ctl schema`: used to get the schema information +- `tidb-ctl table`: used to get the table information + ### Get help Use `tidb-ctl -h/--help` to get usage information. TiDB Control consists of multiple layers of commands. You can use `-h/--help` after each command/subcommand to get its respective usage information. -### Connect +The following example shows how to obtain the schema information: + +Use `tidb-ctl schema -h` to get usage details. The `schema` command itself has two subcommands: `in` and `tid`. -`tidb-ctl` has 4 connection related options: +- `in` is used to obtain the table schema of all tables in the database through the database name. +- `tid` is used to obtain the table schema by using the unique `table_id` in the whole database. + +### Global options + +`tidb-ctl` has the following connection-related global options: - `--host`: TiDB Service address (default 127.0.0.1) - `--port`: TiDB Service port (default 10080) @@ -56,33 +82,11 @@ TiDB Control consists of multiple layers of commands. You can use `-h/--help` af - The default service port of TiDB: `10080`. - The default service port of PD: `2379`. -**Connection options are global options that apply to all the following commands:** - -- `tidb-ctl base64decode`: BASE64 decode -- `tidb-ctl decoder`: for KEY decode -- `tidb-ctl etcd`: for operating etcd -- `tidb-ctl log`: format the log file to expand the single-line stack information -- `tidb-ctl mvcc`: MVCC information -- `tidb-ctl region`: Region information -- `tidb-ctl schema`: Schema information -- `tidb-ctl table`: Table information +### The `schema` command -For details about how to use the above `tidb-ctl` commands, use `tidb-ctl SUBCOMMAND --help` to get the help information. +#### The `in` subcommand -### Usage examples - -The following example shows how to obtain the schema information: - -Use `tidb-ctl schema -h` to get usage details. The `schema` command itself has two subcommands: `in` and `tid`. - -- `in` is used to obtain the table schema of all tables in the database through the database name. -- `tid` is used to obtain the table schema by using the unique `table_id` in the whole database. - -#### The `in` command - -You can use `tidb-ctl schema in -h/--help` to get the help information of the `in` subcommand. - -##### Basic usage +`in` is used to obtain the table schema of all tables in the database through the database name. ```bash tidb-ctl schema in @@ -128,7 +132,28 @@ The result is displayed in the JSON format. (The above output is truncated.) If you do not want to use the default TiDB service address and port, use the `--host` and `--port` options to configure. For example, `tidb-ctl --host 172.16.55.88 --port 8898 schema in mysql -n db`. -#### The `base64decode` subcommand +#### The `tid` subcommand + +`tid` is used to obtain the table schema by using the unique `table_id` in the whole database. You can use the `in` subcommand to get all table IDs of certain schema and use the `tid` subcommand to get the detailed table information. + +For example, the table ID of `mysql.stat_meta` is `21`. You can use `tidb-ctl schema tid -i 21` to obtain the detail of `mysql.stat_meta`. + +```json +{ + "id": 21, + "name": { + "O": "stats_meta", + "L": "stats_meta" + }, + "charset": "utf8mb4", + "collate": "utf8mb4_bin", + ... +} +``` + +Like the `in` subcommand, if you do not want to use the default TiDB service address and port, use the `--host` and `--port` options to specify the host and port. + +#### The `base64decode` command `base64decode` is used to decode `base64` data. @@ -204,25 +229,27 @@ tidb-ctl base64decode [table_id] [base64_data] e not found in data ``` -#### The `decoder` subcommand +### The `decoder` command - The following example shows how to decode the row key, similar to decoding the index key. ```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" - table_id: -9223372036854775780 - row_id: -9223372036854775558 + $ ./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 table_id: -9223372036854775780 + row_id: -9223372036854775558 row_id: -9223372036854775558 ``` - The following example shows how to decode `value`. ```shell - $ ./tidb-ctl decoder -f value -k AhZoZWxsbyB3b3JsZAiAEA== - type: bytes, value: hello world - type: bigint, value: 1024 + $ ./tidb-ctl decoder AhZoZWxsbyB3b3JsZAiAEA== + format: index_value + type: bigint, value: 1024 index_value[0]: {type: bytes, value: hello world} + index_value[1]: {type: bigint, value: 1024} ``` -#### The `etcd` subcommand +### The `etcd` command - `tidb-ctl etcd ddlinfo` is used to obtain DDL information. - `tidb-ctl etcd putkey KEY VALUE` is used to add KEY VALUE to etcd (All the KEYs are added to the `/tidb/ddl/all_schema_versions/` directory). @@ -240,11 +267,11 @@ tidb-ctl base64decode [table_id] [base64_data] tidb-ctl etcd delkey "/tidb/ddl/all_schema_versions/bar" ``` -#### The `log` subcommand +### The `log` command The stack information for the TiDB error log is in one line format. You could use `tidb-ctl log` to change its format to multiple lines. -#### The `keyrange` subcommand +### The `keyrange` command The `keyrange` subcommand is used to query the global or table-related key range information, which is output in the hexadecimal form.