TiDB HTTP API

TiDBIP is the ip of the TiDB server. 10080 is the default status port, and you can edit it in tidb.toml when starting the TiDB server.

Get the current status of TiDB, including the connections, version and git_hash

curl http://{TiDBIP}:10080/status

$curl http://127.0.0.1:10080/status
{
    "connections": 0,
    "git_hash": "f572e33854e1c0f942f031e9656d0004f99995c6",
    "version": "5.7.25-TiDB-v2.1.0-rc.3-355-gf572e3385-dirty"
}

Get all metrics of TiDB
```
curl http://{TiDBIP}:10080/metrics
```

Get the metadata of all regions

curl http://{TiDBIP}:10080/regions/meta

$curl http://127.0.0.1:10080/regions/meta
[
    {
        "leader": {
            "id": 5,
            "store_id": 1
        },
        "peers": [
            {
                "id": 5,
                "store_id": 1
            }
        ],
        "region_epoch": {
            "conf_ver": 1,
            "version": 2
        },
        "region_id": 4
    }
]

Get the table/index of hot regions

curl http://{TiDBIP}:10080/regions/hot

$curl http://127.0.0.1:10080/regions/hot
{
  "read": [

  ],
  "write": [
    {
      "db_name": "sbtest1",
      "table_name": "sbtest13",
      "index_name": "",
      "flow_bytes": 220718,
      "max_hot_degree": 12,
      "region_count": 1
    }
  ]
}

Get the information of a specific region by ID

curl http://{TiDBIP}:10080/regions/{regionID}

$curl http://127.0.0.1:10080/regions/4001
{
    "end_key": "dIAAAAAAAAEk",
    "frames": [
        {
            "db_name": "test",
            "is_record": true,
            "table_id": 286,
            "table_name": "t1"
        }
    ],
    "region_id": 4001,
    "start_key": "dIAAAAAAAAEe"
}

Get regions Information from db.table

curl http://{TiDBIP}:10080/tables/{db}/{table}/regions

$curl http://127.0.0.1:10080/tables/test/t1/regions
{
    "id": 286,
    "indices": [],
    "name": "t1",
    "record_regions": [
        {
            "leader": {
                "id": 4002,
                "store_id": 1
            },
            "peers": [
                {
                    "id": 4002,
                    "store_id": 1
                }
            ],
            "region_epoch": {
                "conf_ver": 1,
                "version": 83
            },
            "region_id": 4001
        }
    ]
}

Get schema Information about all db

curl http://{TiDBIP}:10080/schema

$curl http://127.0.0.1:10080/schema
[
    {
        "charset": "utf8mb4",
        "collate": "utf8mb4_bin",
        "db_name": {
            "L": "test",
            "O": "test"
        },
        "id": 266,
        "state": 5
    },
    .
    .
    .
]

Get schema Information about db
```
curl http://{TiDBIP}:10080/schema/{db}
```
Get schema Information about db.table, and you can get schema info by tableID (tableID is the unique identifier of table in TiDB)
```
curl http://{TiDBIP}:10080/schema/{db}/{table}

curl http://{TiDBIP}:10080/schema?table_id={tableID}
```
Get database information, table information and tidb info schema version by tableID.
```
curl http://{TiDBIP}:10080/db-table/{tableID}
```

Get MVCC Information of the key with a specified handle ID

curl http://{TiDBIP}:10080/mvcc/key/{db}/{table}/{handle}

$curl http://127.0.0.1:10080/mvcc/key/test/t1/1
{
    "info": {
        "writes": [
            {
                "commit_ts": 405179368526053380,
                "short_value": "CAICAkE=",
                "start_ts": 405179368526053377
            }
        ]
    }
}

Get MVCC Information of the first key in the table with a specified start ts

curl http://{TiDBIP}:10080/mvcc/txn/{startTS}/{db}/{table}

$curl http://127.0.0.1:10080/mvcc/txn/405179368526053377/test/t1
{
    "info": {
        "writes": [
            {
                "commit_ts": 405179368526053380,
                "short_value": "CAICAkE=",
                "start_ts": 405179368526053377
            }
        ]
    },
    "key": "dIAAAAAAAAEzX3KAAAAAAAAAAQ=="
}

Get MVCC Information by a hex value

curl http://{TiDBIP}:10080/mvcc/hex/{hexKey}

Get MVCC Information of a specified index key, argument example: column_name_1=column_value_1&column_name_2=column_value2...

curl http://{TiDBIP}:10080/mvcc/index/{db}/{table}/{index}/{handle}?${c1}={v1}&${c2}=${v2}

Hint: For the index column which column type is timezone dependent, e.g. timestamp, convert its value to UTC timezone.

$curl http://127.0.0.1:10080/mvcc/index/test/t1/idx/1\?a\=A
{
    "info": {
        "writes": [
            {
                "commit_ts": 405179523374252037,
                "short_value": "MA==",
                "start_ts": 405179523374252036
            }
        ]
    }
}

Hint: On a partitioned table, use the table(partition) pattern as the table name, test(p1) for example:

$curl http://127.0.0.1:10080/mvcc/index/test(p1)/t1/idx/1\?a\=A

Scatter regions of the specified table, add a scatter-range scheduler for the PD and the range is same as the table range.
```
curl http://{TiDBIP}:10080/tables/{db}/{table}/scatter
```
Hint: On a partitioned table, use the table(partition) pattern as the table name, test(p1) for example.

Note: The scatter-range scheduler may conflict with the global scheduler, do not use it for long periods on the larger table.
Stop scatter the regions, disable the scatter-range scheduler for the specified table.
```
curl http://{TiDBIP}:10080/tables/{db}/{table}/stop-scatter
```
Hint: On a partitioned table, use the table(partition) pattern as the table name, test(p1) for example.
Get TiDB server settings
```
curl http://{TiDBIP}:10080/settings
```

Get TiDB server information.

curl http://{TiDBIP}:10080/info

$curl http://127.0.0.1:10080/info
{
    "ddl_id": "f7e73ed5-63b4-4cb4-ba7c-42b32dc74e77",
    "git_hash": "f572e33854e1c0f942f031e9656d0004f99995c6",
    "ip": "",
    "is_owner": true,
    "lease": "45s",
    "listening_port": 4000,
    "status_port": 10080,
    "version": "5.7.25-TiDB-v2.1.0-rc.3-355-gf572e3385-dirty"
}

Get TiDB cluster all servers information.

curl http://{TiDBIP}:10080/info/all

$curl http://127.0.0.1:10080/info/all
{
    "servers_num": 2,
    "owner_id": "29a65ec0-d931-4f9e-a212-338eaeffab96",
    "is_all_server_version_consistent": true,
    "all_servers_info": {
        "29a65ec0-d931-4f9e-a212-338eaeffab96": {
            "version": "5.7.25-TiDB-v4.0.0-alpha-669-g8f2a09a52-dirty",
            "git_hash": "8f2a09a52fdcaf9d9bfd775d2c6023f363dc121e",
            "ddl_id": "29a65ec0-d931-4f9e-a212-338eaeffab96",
            "ip": "",
            "listening_port": 4000,
            "status_port": 10080,
            "lease": "45s",
            "binlog_status": "Off"
        },
        "cd13c9eb-c3ee-4887-af9b-e64f3162d92c": {
            "version": "5.7.25-TiDB-v4.0.0-alpha-669-g8f2a09a52-dirty",
            "git_hash": "8f2a09a52fdcaf9d9bfd775d2c6023f363dc121e",
            "ddl_id": "cd13c9eb-c3ee-4887-af9b-e64f3162d92c",
            "ip": "",
            "listening_port": 4001,
            "status_port": 10081,
            "lease": "45s",
            "binlog_status": "Off"
        }
    }
}

Enable/Disable TiDB server general log

curl -X POST -d "tidb_general_log=1" http://{TiDBIP}:10080/settings
curl -X POST -d "tidb_general_log=0" http://{TiDBIP}:10080/settings

Change TiDB server log level

curl -X POST -d "log_level=debug" http://{TiDBIP}:10080/settings
curl -X POST -d "log_level=info" http://{TiDBIP}:10080/settings

Change TiDB DDL slow log threshold

The unit is millisecond.

curl -X POST -d "ddl_slow_threshold=300" http://{TiDBIP}:10080/settings

Get the column value by an encoded row and some information that can be obtained from a column of the table schema information.

Argument example: rowBin=base64_encoded_row_value
```
curl http://{TiDBIP}:10080/tables/{colID}/{colFlag}/{colLen}?rowBin={val}
```
Hint: For the column which field type is timezone dependent, e.g. timestamp, convert its value to UTC timezone.
Resign the ddl owner, let tidb start a new ddl owner election.
```
curl -X POST http://{TiDBIP}:10080/ddl/owner/resign
```
Get all TiDB DDL job history information.
```
curl http://{TiDBIP}:10080/ddl/history
```
Get count {number} TiDB DDL job history information.
```
curl http://{TiDBIP}:10080/ddl/history?limit={number}
```
Note: If you request a tidb that is not ddl owner, the response will be This node is not a ddl owner, can't be resigned.
Download TiDB debug info
```
curl http://{TiDBIP}:10080/debug/zip?seconds=60 --output debug.zip
```
zip file will include:
- Go heap pprof(after GC)
- Go cpu pprof(10s)
- Go mutex pprof
- Full goroutine
- TiDB config and version
Param:
- seconds: profile time(s), default is 10s.

Get statistics data of specified table.

curl http://{TiDBIP}:10080/stats/dump/{db}/{table}

Get statistics data of specific table and timestamp.

curl http://{TiDBIP}:10080/stats/dump/{db}/{table}/{yyyyMMddHHmmss}

curl http://{TiDBIP}:10080/stats/dump/{db}/{table}/{yyyy-MM-dd HH:mm:ss}

Resume the binlog writing when Pump is recovered.
```
curl http://{TiDBIP}:10080/binlog/recover
```
Return value:
- timeout, return status code: 400, message: timeout
- If it returns normally, status code: 200, message example:
```
{
  "Skipped": false,
  "SkippedCommitterCounter": 0
}
```
  Skipped: false indicates that the current binlog is not in the skipped state, otherwise, it is in the skipped state SkippedCommitterCounter: Represents how many transactions are currently being committed in the skipped state. By default, the API will return after waiting until all skipped-binlog transactions are committed. If this value is greater than 0, it means that you need to wait until them are committed .
Param:
- op=nowait: return after binlog status is recoverd, do not wait until the skipped-binlog transactions are committed.
- op=reset: reset SkippedCommitterCounter to 0 to avoid the problem that SkippedCommitterCounter is not cleared due to some unusual cases.
- op=status: Get the current status of binlog recovery.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

tidb_http_api.md

tidb_http_api.md

TiDB HTTP API

Files

tidb_http_api.md

Latest commit

History

tidb_http_api.md

File metadata and controls

TiDB HTTP API