From dd5197a32788157af58f36e9f95affb8b6a73f60 Mon Sep 17 00:00:00 2001 From: Lingyu Song Date: Mon, 13 Jul 2020 16:40:18 +0800 Subject: [PATCH 1/3] cherry pick #3048 to release-2.1 Signed-off-by: ti-srebot --- tidb-control.md | 205 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 201 insertions(+), 4 deletions(-) diff --git a/tidb-control.md b/tidb-control.md index 96588372d2439..3d16449dca2ae 100644 --- a/tidb-control.md +++ b/tidb-control.md @@ -7,11 +7,19 @@ aliases: ['/docs/v2.1/tidb-control/','/docs/v2.1/reference/tools/tidb-control/'] # 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. @@ -31,20 +39,53 @@ 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`. +<<<<<<< HEAD ``` tidb-ctl -H/--host {TiDB service address} -P/--port {TiDB service port} ``` +======= +- `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) +- `--pdhost`: PD Service address (default 127.0.0.1) +- `--pdport`: PD Service port (default 2379) +- `--ca`: The CA file path used for the TLS connection +- `--ssl-key`: The key file path used for the TLS connection +- `--ssl-cert`: The certificate file path used for the TLS connection + +`--pdhost` and `--pdport` are mainly used in the `etcd` subcommand. For example, `tidb-ctl etcd ddlinfo`. If you do not specify the address and the port, the following default value is used: +>>>>>>> 64044c7... update document of tidb-ctl (#3048) If you do not add an address or a port, the default value is used. The default address is `127.0.0.1` (service address must be the IP address); the default port is `10080`. Connection options are top-level options and apply to all of the following commands. +<<<<<<< HEAD Currently, TiDB Control can obtain four categories of information using the following four commands: - `tidb-ctl mvcc`: MVCC information @@ -66,6 +107,13 @@ Use `tidb-ctl schema -h` to get the help information of the subcommands. `schema You can also use `tidb-ctl schema in -h/--help` to get the help information of the `in` subcommand. ##### Basic usage +======= +### The `schema` command + +#### The `in` subcommand + +`in` is used to obtain the table schema of all tables in the database through the database name. +>>>>>>> 64044c7... update document of tidb-ctl (#3048) ``` tidb-ctl schema in {database name} @@ -107,7 +155,156 @@ The result is long and displayed in JSON. The above result is a truncated one. } ``` +<<<<<<< HEAD The above result is a truncated one, too. +======= + (The above output is also 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 `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. + +```shell +tidb-ctl base64decode [base64_data] +tidb-ctl base64decode [db_name.table_name] [base64_data] +tidb-ctl base64decode [table_id] [base64_data] +``` + +1. Execute the following SQL statement to prepare the environment: + + ```sql + use test; + create table t (a int, b varchar(20),c datetime default current_timestamp , d timestamp default current_timestamp, unique index(a)); + insert into t (a,b,c) values(1,"哈哈 hello",NULL); + alter table t add column e varchar(20); + ``` + +2. Obtian MVCC data using the HTTP API interface: + + ```shell + $ curl "http://$IP:10080/mvcc/index/test/t/a/1?a=1" + { + "info": { + "writes": [ + { + "start_ts": 407306449994645510, + "commit_ts": 407306449994645513, + "short_value": "AAAAAAAAAAE=" # The unique index a stores the handle id of the corresponding row. + } + ] + } + }% + + $ curl "http://$IP:10080/mvcc/key/test/t/1" + { + "info": { + "writes": [ + { + "start_ts": 407306588892692486, + "commit_ts": 407306588892692489, + "short_value": "CAIIAggEAhjlk4jlk4ggaGVsbG8IBgAICAmAgIDwjYuu0Rk=" # Row data that handle id is 1. + } + ] + } + }% + ``` + +3. Decode ```handle id (uint64) using `base64decode` ```. + + ```shell + $ tidb-ctl base64decode AAAAAAAAAAE= + hex: 0000000000000001 + uint64: 1 + ``` + +4. Decode row data using `base64decode`. + + ```shell + $ ./tidb-ctl base64decode test.t CAIIAggEAhjlk4jlk4ggaGVsbG8IBgAICAmAgIDwjYuu0Rk= + a: 1 + b: 哈哈 hello + c is NULL + d: 2019-03-28 05:35:30 + e not found in data + + # if the table id of test.t is 60, you can also use below command to do the same thing. + $ ./tidb-ctl base64decode 60 CAIIAggEAhjlk4jlk4ggaGVsbG8IBgAICAmAgIDwjYuu0Rk= + a: 1 + b: 哈哈 hello + c is NULL + d: 2019-03-28 05:35:30 + e not found in data + ``` + +### The `decoder` command + +- The following example shows how to decode the row key, similar to decoding the index key. + + ```shell + $ ./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 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` 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). + + ```shell + tidb-ctl etcd putkey "foo" "bar" + ``` + + In fact, a key-value pair is added to the etcd whose KEY is `/tidb/ddl/all_schema_versions/foo` and VALUE is `bar`. + +- `tidb-ctl etcd delkey` deletes the KEY in etcd. Only those KEYs with the `/tidb/ddl/fg/owner/` or `/tidb/ddl/all_schema_versions/` prefix can be deleted. + + ```shell + tidb-ctl etcd delkey "/tidb/ddl/fg/owner/foo" + tidb-ctl etcd delkey "/tidb/ddl/all_schema_versions/bar" + ``` + +### 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` command + +The `keyrange` subcommand is used to query the global or table-related key range information, which is output in the hexadecimal form. +>>>>>>> 64044c7... update document of tidb-ctl (#3048) - If you want to specify the server address, use the `-H -P` option. From dfc3c72bfaffc8d383845052d7a3156b6bf5ba5d Mon Sep 17 00:00:00 2001 From: imtbkcat Date: Mon, 13 Jul 2020 22:17:06 +0800 Subject: [PATCH 2/3] fix conflict --- tidb-control.md | 106 +++++++++++++++++++++++++++--------------------- 1 file changed, 60 insertions(+), 46 deletions(-) diff --git a/tidb-control.md b/tidb-control.md index 3d16449dca2ae..2b3d408f3b54e 100644 --- a/tidb-control.md +++ b/tidb-control.md @@ -2,7 +2,7 @@ title: TiDB Control User Guide summary: Use TiDB Control to obtain TiDB status information for debugging. category: reference -aliases: ['/docs/v2.1/tidb-control/','/docs/v2.1/reference/tools/tidb-control/'] +aliases: ['/docs/dev/tidb-control/','/docs/dev/reference/tools/tidb-control/'] --- # TiDB Control User Guide @@ -25,16 +25,17 @@ After installing TiUP, you can use `tiup ctl tidb` command to get and execute Ti ## Usage introduction -The usage of `tidb-ctl` consists of command (including subcommand), option, and flag. +This section describes how to use commands, subcommands, options, and flags in `tidb-ctl`. - command: characters without `-` or `--` +- subcommand: characters without `-` or `--` that follow a command - option: characters with `-` or `--` -- flag: characters exactly following the command or option, passing value to the command or option +- flag: characters exactly following a command/subcommand or option, passing value to the command/subcommand or option Usage example: `tidb-ctl schema in mysql -n db` - `schema`: the command -- `in`: the subcommand of schema +- `in`: the subcommand of `schema` - `mysql`: the flag of `in` - `-n`: the option - `db`: the flag of `-n` @@ -60,11 +61,6 @@ 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`. -<<<<<<< HEAD -``` -tidb-ctl -H/--host {TiDB service address} -P/--port {TiDB service port} -``` -======= - `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. @@ -81,45 +77,22 @@ tidb-ctl -H/--host {TiDB service address} -P/--port {TiDB service port} - `--ssl-cert`: The certificate file path used for the TLS connection `--pdhost` and `--pdport` are mainly used in the `etcd` subcommand. For example, `tidb-ctl etcd ddlinfo`. If you do not specify the address and the port, the following default value is used: ->>>>>>> 64044c7... update document of tidb-ctl (#3048) - -If you do not add an address or a port, the default value is used. The default address is `127.0.0.1` (service address must be the IP address); the default port is `10080`. Connection options are top-level options and apply to all of the following commands. - -<<<<<<< HEAD -Currently, TiDB Control can obtain four categories of information using the following four commands: - -- `tidb-ctl mvcc`: MVCC information -- `tidb-ctl region`: Region information -- `tidb-ctl schema`: Schema information -- `tidb-ctl table`: Table information - -### Examples - -The following example shows how to obtain the schema information: - -Use `tidb-ctl schema -h` to get the help information of the subcommands. `schema` 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 through the unique `table_id` in the whole database. - -#### The `in` command - -You can also use `tidb-ctl schema in -h/--help` to get the help information of the `in` subcommand. +- The default service address of TiDB and PD: `127.0.0.1`. The service address must be an IP address. +- The default service port of TiDB: `10080`. +- The default service port of PD: `2379`. -##### Basic usage -======= ### The `schema` command #### The `in` subcommand `in` is used to obtain the table schema of all tables in the database through the database name. ->>>>>>> 64044c7... update document of tidb-ctl (#3048) -``` -tidb-ctl schema in {database name} +```bash +tidb-ctl schema in ``` -For example, `tidb-ctl schema in mysql` returns the following result: +For example, running `tidb-ctl schema in mysql` returns the following result: ```json [ @@ -137,9 +110,9 @@ For example, `tidb-ctl schema in mysql` returns the following result: ] ``` -The result is long and displayed in JSON. The above result is a truncated one. +The result is displayed in the JSON format. (The above output is truncated.) -- If you want to specify the table name, use `tidb-ctl schema in {database} -n {table name}` to filter. +- If you want to specify the table name, use `tidb-ctl schema in -n ` to filter. For example, `tidb-ctl schema in mysql -n db` returns the table schema of the `db` table in the `mysql` database: @@ -155,9 +128,6 @@ The result is long and displayed in JSON. The above result is a truncated one. } ``` -<<<<<<< HEAD - The above result is a truncated one, too. -======= (The above output is also 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`. @@ -304,8 +274,52 @@ The stack information for the TiDB error log is in one line format. You could us ### 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. ->>>>>>> 64044c7... update document of tidb-ctl (#3048) -- If you want to specify the server address, use the `-H -P` option. +* Execute the `tidb-ctl keyrange` command to check the global key range information: + + {{< copyable "shell-regular" >}} - For example, `tidb-ctl -H 127.0.0.1 -P 10080 schema in mysql -n db`. + ```shell + tidb-ctl keyrange + ``` + + ``` + global ranges: + meta: (6d, 6e) + table: (74, 75) + ``` + +* Add the `--encode` option to display encoded keys (in the same format as in TiKV and PD): + + {{< copyable "shell-regular" >}} + + ```shell + tidb-ctl keyrange --encode + ``` + + ``` + global ranges: + meta: (6d00000000000000f8, 6e00000000000000f8) + table: (7400000000000000f8, 7500000000000000f8) + ``` + +* Execute the `tidb-ctl keyrange --database={db} --table={tbl}` command to check the global and table-related key range information: + + {{< copyable "shell-regular" >}} + + ```shell + tidb-ctl keyrange --database test --table ttt + ``` + + ``` + global ranges: + meta: (6d, 6e) + table: (74, 75) + table ttt ranges: (NOTE: key range might be changed after DDL) + table: (74800000000000002f, 748000000000000030) + table indexes: (74800000000000002f5f69, 74800000000000002f5f72) + index c2: (74800000000000002f5f698000000000000001, 74800000000000002f5f698000000000000002) + index c3: (74800000000000002f5f698000000000000002, 74800000000000002f5f698000000000000003) + index c4: (74800000000000002f5f698000000000000003, 74800000000000002f5f698000000000000004) + table rows: (74800000000000002f5f72, 748000000000000030) + ``` From 1eaecd736a08daa3ff2600f4d70fac9c589b0ae3 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Tue, 14 Jul 2020 13:35:10 +0800 Subject: [PATCH 3/3] Update tidb-control.md --- tidb-control.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-control.md b/tidb-control.md index 2b3d408f3b54e..b0be6fcfcf8bf 100644 --- a/tidb-control.md +++ b/tidb-control.md @@ -2,7 +2,7 @@ title: TiDB Control User Guide summary: Use TiDB Control to obtain TiDB status information for debugging. category: reference -aliases: ['/docs/dev/tidb-control/','/docs/dev/reference/tools/tidb-control/'] +aliases: ['/docs/v2.1/tidb-control/','/docs/v2.1/reference/tools/tidb-control/'] --- # TiDB Control User Guide