印刻数据库

外观

TiDB 控制工具 tidb-ctl 使用指南 ​

核心功能 ​

功能描述
状态查看查看 TiDB 服务器的运行状态
配置管理查看和修改 TiDB 配置
日志管理查看和管理 TiDB 日志
会话管理查看和管理 TiDB 会话
事务管理查看和管理 TiDB 事务
性能诊断诊断 TiDB 性能问题
系统信息查看 TiDB 系统信息

tidb-ctl 安装与配置 ​

安装方式 ​

通过 TiUP 安装 ​

bash
# 安装 tidb-ctl
tiup install tidb-ctl

# 查看版本
tiup tidb-ctl --version

从源码编译 ​

bash
# 克隆源码
git clone https://github.com/pingcap/tidb.git
cd tidb

# 编译 tidb-ctl
make build_ctl

# 查看版本
./bin/tidb-ctl --version

基本配置 ​

bash
# 设置环境变量（可选）
export TIDB_HOST=127.0.0.1
export TIDB_PORT=10080

# 验证连接
tiup tidb-ctl status

常用命令 ​

状态查看 ​

bash
# 查看 TiDB 状态
tiup tidb-ctl status --host tidb-host --port tidb-port

# 查看 TiDB 版本
tiup tidb-ctl status --version

# 查看 TiDB 启动时间
tiup tidb-ctl status --uptime

配置管理 ​

bash
# 查看所有配置
tiup tidb-ctl config --host tidb-host --port tidb-port

# 查看指定配置
tiup tidb-ctl config --host tidb-host --port tidb-port --key tidb_txn_timeout

# 查看配置文件路径
tiup tidb-ctl config --host tidb-host --port tidb-port --file

日志管理 ​

bash
# 查看日志级别
tiup tidb-ctl log --host tidb-host --port tidb-port --level

# 设置日志级别
tiup tidb-ctl log --host tidb-host --port tidb-port --set-level debug

# 查看日志文件路径
tiup tidb-ctl log --host tidb-host --port tidb-port --file

会话管理 ​

bash
# 查看当前会话
tiup tidb-ctl session --host tidb-host --port tidb-port

# 查看指定会话
tiup tidb-ctl session --host tidb-host --port tidb-port --id session-id

# 终止指定会话
tiup tidb-ctl session --host tidb-host --port tidb-port --kill session-id

# 查看会话统计信息
tiup tidb-ctl session --host tidb-host --port tidb-port --stats

事务管理 ​

bash
# 查看当前事务
tiup tidb-ctl txn --host tidb-host --port tidb-port

# 查看指定事务
tiup tidb-ctl txn --host tidb-host --port tidb-port --id <txn-id>

# 回滚指定事务
tiup tidb-ctl txn --host tidb-host --port tidb-port --rollback <txn-id>

# 查看事务统计信息
tiup tidb-ctl txn --host tidb-host --port tidb-port --stats

性能诊断 ​

bash
# 查看慢查询
tiup tidb-ctl slow --host tidb-host --port tidb-port

# 查看慢查询统计
tiup tidb-ctl slow --host tidb-host --port tidb-port --stats

# 查看最近的慢查询
tiup tidb-ctl slow --host tidb-host --port tidb-port --latest 10

# 查看查询执行计划
tiup tidb-ctl plan --host tidb-host --port tidb-port --sql "SELECT * FROM test.t1"

系统信息 ​

bash
# 查看系统信息
tiup tidb-ctl info --host tidb-host --port tidb-port

# 查看 CPU 信息
tiup tidb-ctl info --host tidb-host --port tidb-port --cpu

# 查看内存信息
tiup tidb-ctl info --host tidb-host --port tidb-port --mem

# 查看磁盘信息
tiup tidb-ctl info --host tidb-host --port tidb-port --disk

高级功能 ​

配置热加载 ​

bash
# 查看支持热加载的配置项
tiup tidb-ctl config --host tidb-host --port tidb-port --dynamic

# 动态修改配置
tiup tidb-ctl config --host tidb-host --port tidb-port --set tidb_txn_timeout=600

# 验证配置修改
tiup tidb-ctl config --host tidb-host --port tidb-port --key tidb_txn_timeout

日志动态调整 ​

bash
# 动态调整日志级别
tiup tidb-ctl log --host tidb-host --port tidb-port --set-level info

# 动态调整日志文件大小
tiup tidb-ctl log --host tidb-host --port tidb-port --set-max-size 1GB

# 动态调整日志保留天数
tiup tidb-ctl log --host tidb-host --port tidb-port --set-max-days 7

性能采样 ​

bash
# 启动性能采样
tiup tidb-ctl profile --host tidb-host --port tidb-port --start

# 查看性能采样状态
tiup tidb-ctl profile --host tidb-host --port tidb-port --status

# 停止性能采样并获取报告
tiup tidb-ctl profile --host tidb-host --port tidb-port --stop --output profile.txt

系统变量管理 ​

bash
# 查看所有系统变量
tiup tidb-ctl variable --host tidb-host --port tidb-port

# 查看指定系统变量
tiup tidb-ctl variable --host tidb-host --port tidb-port --name tidb_version

# 设置系统变量
tiup tidb-ctl variable --host tidb-host --port tidb-port --set tidb_enable_noop_functions=ON

最佳实践 ​

日常巡检 ​

bash
# 编写巡检脚本
cat > tidb_check.sh << 'EOF'
#!/bin/bash

host="tidb-host"
port="tidb-port"

# 检查 TiDB 状态
echo "=== TiDB Status ==="
tiup tidb-ctl status --host $host --port $port

# 检查 TiDB 配置
echo "\n=== TiDB Config ==="
tiup tidb-ctl config --host $host --port $port | grep -E "tidb_txn_timeout|tidb_retry_limit|tidb_mem_quota_query"

# 检查慢查询
echo "\n=== Slow Queries ==="
tiup tidb-ctl slow --host $host --port $port --latest 5

# 检查会话数
echo "\n=== Session Count ==="
tiup tidb-ctl session --host $host --port $port --stats

# 检查事务数
echo "\n=== Transaction Count ==="
tiup tidb-ctl txn --host $host --port $port --stats
EOF

# 赋予执行权限
chmod +x tidb_check.sh

# 执行巡检脚本
./tidb_check.sh

5.2 性能诊断 ​

bash
# 1. 查看 TiDB 状态
tiup tidb-ctl status --host tidb-host --port tidb-port

# 2. 查看慢查询
tiup tidb-ctl slow --host tidb-host --port tidb-port --stats

# 3. 查看会话状态
tiup tidb-ctl session --host tidb-host --port tidb-port

# 4. 查看事务状态
tiup tidb-ctl txn --host tidb-host --port tidb-port

# 5. 启动性能采样
tiup tidb-ctl profile --host tidb-host --port tidb-port --start
# 等待一段时间...
tiup tidb-ctl profile --host tidb-host --port tidb-port --stop --output performance_profile.txt

# 6. 分析性能报告
cat performance_profile.txt | head -50

5.3 故障处理 ​

  1. 会话阻塞处理
bash
   # 查看阻塞会话
tiup tidb-ctl session --host tidb-host --port tidb-port --blocked

# 终止阻塞会话
tiup tidb-ctl session --host tidb-host --port tidb-port --kill blocking-session-id
  1. 长时间事务处理
bash
   # 查看长时间运行的事务
tiup tidb-ctl txn --host tidb-host --port tidb-port --long-running

# 回滚长时间运行的事务
tiup tidb-ctl txn --host tidb-host --port tidb-port --rollback long-txn-id
  1. 高内存使用处理
bash
   # 查看高内存使用的会话
tiup tidb-ctl session --host tidb-host --port tidb-port --high-mem

# 终止高内存使用的会话
tiup tidb-ctl session --host tidb-host --port tidb-port --kill high-mem-session-id

5.4 配置优化 ​

bash
# 查看当前配置
tiup tidb-ctl config --host tidb-host --port tidb-port > current_config.txt

# 分析配置差异
diff -u baseline_config.txt current_config.txt

# 优化配置
tiup tidb-ctl config --host tidb-host --port tidb-port --set tidb_txn_timeout=300
tiup tidb-ctl config --host tidb-host --port tidb-port --set tidb_retry_limit=10
tiup tidb-ctl config --host tidb-host --port tidb-port --set tidb_mem_quota_query=1GB

与其他工具的配合使用 ​

与 TiDB Dashboard 配合 ​

  1. 使用 TiDB Dashboard 可视化查看 TiDB 状态
  2. 在 TiDB Dashboard 中找到问题会话或事务的 ID
  3. 使用 tidb-ctl 进行详细分析和处理

与 Prometheus + Grafana 配合 ​

  1. 在 Grafana 中监控 TiDB 性能指标
  2. 发现异常指标时，使用 tidb-ctl 进行深入诊断
  3. 根据诊断结果调整配置或处理问题

与 pd-ctl 和 tikv-ctl 配合 ​

bash
# 使用 pd-ctl 查看 PD 状态
tiup pd-ctl -u http://pd-host:2379 cluster

# 使用 tikv-ctl 查看 TiKV 状态
tiup tikv-ctl --host tikv-host:20160 status

# 使用 tidb-ctl 查看 TiDB 状态
tiup tidb-ctl status --host tidb-host --port tidb-port

常见问题（FAQ） ​

Q1: tidb-ctl 连接 TiDB 失败，提示 "connection refused"，怎么办？ ​

A1: 请检查以下内容：

  1. TiDB 服务器是否正在运行
  2. TiDB 服务器的主机地址和端口是否正确
  3. 防火墙是否允许访问 TiDB 端口
  4. TiDB 配置中的 status.port 是否与实际监听端口一致

Q2: tidb-ctl 执行某些命令时提示权限不足，怎么办？ ​

A2: 请确保：

  1. 你有足够的权限访问 TiDB 服务器
  2. TiDB 配置中的 status.auth-enabled 是否设置为 true，如果是，需要提供用户名和密码
  3. 使用 --user 和 --password 参数指定用户名和密码

Q3: 如何查看 tidb-ctl 支持的所有命令？ ​

A3: 使用以下命令查看帮助信息：

bash
tiup tidb-ctl --help

Q4: 如何查看 tidb-ctl 某个命令的详细用法？ ​

A4: 使用以下命令查看特定命令的帮助：

bash
tiup tidb-ctl command --help

Q5: tidb-ctl 可以远程管理 TiDB 服务器吗？ ​

A5: 是的，tidb-ctl 可以远程管理 TiDB 服务器，只需要指定正确的主机地址和端口即可：

bash
tiup tidb-ctl status --host remote-host --port remote-port

Q6: 如何使用 tidb-ctl 修改 TiDB 配置？ ​

A6: 可以使用以下命令修改配置：

bash
# 修改动态配置
tiup tidb-ctl config --host tidb-host --port tidb-port --set key=value

# 修改静态配置需要编辑配置文件后重启 TiDB

Q7: 如何使用 tidb-ctl 查看 TiDB 日志？ ​

A7: 可以使用以下命令查看 TiDB 日志：

bash
tiup tidb-ctl log --host tidb-host --port tidb-port

# 查看指定级别的日志
tiup tidb-ctl log --host tidb-host --port tidb-port --level error

Q8: 如何使用 tidb-ctl 管理 TiDB 会话？ ​

A8: 可以使用以下命令管理会话：

bash
# 查看所有会话
tiup tidb-ctl session --host tidb-host --port tidb-port

# 终止指定会话
tiup tidb-ctl session --host tidb-host --port tidb-port --kill session-id

命令参考 ​

全局选项 ​

选项描述
--hostTiDB 服务器主机地址
--portTiDB 状态端口
--user用户名（如果启用了认证）
--password密码（如果启用了认证）
--help显示帮助信息
--version显示版本信息

主要命令 ​

命令描述
status查看 TiDB 状态
config查看和修改 TiDB 配置
log查看和管理 TiDB 日志
session查看和管理 TiDB 会话
txn查看和管理 TiDB 事务
slow查看和管理慢查询
plan查看查询执行计划
info查看系统信息
profile性能采样和分析
variable查看和修改系统变量