mysql-debug（MySQL 调试）

MySQL 数据库查询调试技能

概述

本技能用于在 Bug 排查过程中直接查询 MySQL 数据库，验证数据状态。配合日志分析定位问题根因。

核心能力：

1. 智能判断 Bug 是否需要查库（明显代码错误跳过）
2. 从日志自动提取数据库名（租户 ID = 数据库名）
3. 只读查询，安全排查

连接信息获取（三级降级，自动查找）

当本技能被激活时，按以下优先级获取数据库连接信息：

优先级 1：用户对话中指定（最高优先级）

用户直接给出连接信息，或指定环境名：

• "连 dev 环境查一下" → 使用 .claude/mysql-config.json 中 dev 环境的配置
• 直接给出 host/port/user/password → 直接使用

优先级 2：.claude/mysql-config.json（显式配置，可选）

如果文件存在且当前环境的 password 不是占位符 YOUR_PASSWORD，使用该配置。 此文件为可选，主要用于连接非本地环境（dev/prod 远程数据库）。

优先级 3：工程配置文件（零配置，本地开发默认）

从项目的 bootstrap-dev.yml 中自动提取连接信息：

搜索路径：

**/bootstrap-dev.yml
**/bootstrap*.yml（降级）

解析位置：spring.dataset.system.master 节点

解析规则：

# 从以下字段提取：
jdbcUrl: jdbc:mysql://127.0.0.1:3306/system_xxx
username: root
password: xxx

提取结果：

• host = 127.0.0.1（从 jdbcUrl 解析）
• port = 3306（从 jdbcUrl 解析）
• user = root（username 字段）
• password = xxx（password 字段）
• 注意：jdbcUrl 中的数据库名（system_xxx）为系统库，不作为查询目标数据库。查询目标数据库 = 租户ID（从日志提取或用户指定）

mysql CLI 查找（跨平台，优先缓存）

优先级 1：配置文件指定路径（推荐，一次配置永久生效）

在 .claude/mysql-config.json（或 .cursor/mysql-config.json）中配置 mysqlPath：

{
  "mysqlPath": "/opt/homebrew/opt/mysql-client/bin/mysql",
  "environments": { ... }
}

Windows 示例：

{
  "mysqlPath": "C:\\Program Files\\MySQL\\MySQL Server 8.0\\bin\\mysql.exe",
  "environments": { ... }
}

如果 mysqlPath 已配置且文件存在，直接使用，跳过下方所有搜索步骤。

优先级 2：系统 PATH 查找（一条命令，不遍历磁盘）

优先级 3：常见安装路径（仅尝试已知固定路径，禁止遍历磁盘）

macOS：

ls /opt/homebrew/opt/mysql-client/bin/mysql \
  || ls /opt/homebrew/bin/mysql \
  || ls /usr/local/mysql/bin/mysql

Windows（直接检查这几个路径，禁止遍历 C:\、D:\ 等盘符）：

where /R "C:\Program Files\MySQL" mysql.exe 2>nul
if not exist ... (
  where /R "C:\Program Files (x86)\MySQL" mysql.exe 2>nul
)

Linux：

ls /usr/bin/mysql || ls /usr/local/bin/mysql

优先级 4：找不到时的引导提示

⚠️ 未找到 mysql 客户端。请选择一种方式解决：

方式 1（推荐）：在配置文件中指定路径
  在 .claude/mysql-config.json（Cursor 用 .cursor/mysql-config.json）中添加：
  { "mysqlPath": "你的mysql可执行文件完整路径" }

方式 2：安装 mysql 客户端
  macOS:   brew install mysql-client
  Windows: 下载 https://dev.mysql.com/downloads/shell/ 或 scoop install mysql
  Linux:   apt install mysql-client / yum install mysql

关键规则：禁止使用 find / 或遍历磁盘盘符来搜索 mysql。 只用上述固定路径检查。

引导提示（仅当连接信息和 mysql CLI 都无法获取时）

⚠️ 数据库查询功能需要先完成配置：

1. 连接信息获取失败：
   - 未找到 bootstrap-dev.yml 工程配置文件
   - 未找到 .claude/mysql-config.json 配置文件
   → 请创建 .claude/mysql-config.json 或确保项目中存在 bootstrap-dev.yml

2. 安装 MySQL 客户端：
   brew install mysql-client

完成后重新触发即可使用数据库查询辅助排查。

引导提示输出后，Bug 排查仍可继续（走 bug-detective 纯代码分析路径），只是跳过数据库查询环节。

多环境支持

配置文件结构

.claude/mysql-config.json 支持多环境配置：

{
  "environments": {
    "local": { "host": "127.0.0.1", "port": 3306, "user": "root", "password": "xxx" },
    "dev":   { "host": "dev-db.example.com", "port": 3306, "user": "dev_user", "password": "xxx" },
    "prod":  { "host": "prod-db.example.com", "port": 3306, "user": "readonly", "password": "xxx" }
  },
  "default": "local"
}

环境选择规则

环境关键词映射

用户说的话 → 对应环境名：

连接示例

# 用户说"连 dev 环境查一下 order_info"
# → 读取 environments.dev 的连接信息 + 日志提取的数据库名
mysql -h dev-db.example.com -P 3306 -u dev_user -p'xxx' 546198574447230976 -e "SELECT ..."

核心流程：是否需要查库？

决策树（Bug 修复时必须先评估）

用户报告 Bug / 提供日志
  │
  ├─ 明显的代码错误？ ──→ ✅ 不需要查库，直接修复
  │   - NPE 且代码中未做空判断
  │   - 语法错误、拼写错误
  │   - 类型转换错误（ClassCastException）
  │   - 缺少 import、注解遗漏
  │   - 方法签名不匹配
  │
  ├─ 数据相关的问题？ ──→ 🔍 需要查库
  │   - "查不到数据"、"数据为空"
  │   - "数量不对"、"金额不对"
  │   - SQL 相关异常（DataIntegrityViolation、DuplicateKey）
  │   - 关联查询结果异常
  │   - 状态流转异常（订单状态不对等）
  │
  ├─ 不确定是代码还是数据？ ──→ 🔍 需要查库确认
  │   - 逻辑正确但结果错误
  │   - 特定租户/特定数据才出现的 Bug
  │   - 生产有问题但本地无法复现
  │
  └─ 配置/环境问题？ ──→ ✅ 不需要查库
      - 启动失败、Bean 创建异常
      - 配置文件错误
      - 依赖版本冲突

评估输出格式

在 Bug 修复响应中，先输出评估结论：

📊 数据库查询评估：需要查库
理由：日志显示 order_info 查询返回空，需要确认数据是否存在
数据库：546198574447230976（从日志提取）

或：

📊 数据库查询评估：不需要查库
理由：明显的 NPE，代码中 getUserInfo() 返回值未做空判断

从日志提取数据库名

日志格式说明

本项目的日志格式：

2026-03-04 10:21:40.902,-,546198574447230976,, DEBUG 94396 --- [  XNIO-1 task-3] n.x.f.c.request.RequestLoggingFilter : 47  : >>> GET /api/v2/web/xxx

各字段含义：

时间戳                    ,-,租户ID（=数据库名）,, 日志级别 PID --- [线程名] 类名 : 行号 : 日志内容

提取规则

1. 自动提取：从日志行中匹配 ,-,(\d{15,19}),, 模式，提取的数字即为数据库名
2. 手动指定：用户直接说"查 546198574447230976 库"或"数据库名是 xxx"
3. 优先级：手动指定 > 日志提取 > 配置文件 default

提取示例

日志：2026-03-04 10:21:40.902,-,546198574447230976,, DEBUG ...
                                ↑
                          数据库名 = 546198574447230976

连接时使用：

mysql -h 127.0.0.1 -P 3306 -u root -p'password' 546198574447230976 -e "SELECT ..."

查询执行

连接方式

按"连接信息获取"章节的优先级获取 host/port/user/password，数据库名从日志提取或用户指定：

# mysql 路径：优先用 mysqlPath 配置，否则用 which/where 查找结果
MYSQL_BIN={mysqlPath 或 which/where 找到的路径}

# 连接信息来源：用户指定 > mysql-config.json > bootstrap-dev.yml 自动提取
# 数据库名来源：用户指定 > 日志提取的租户ID
$MYSQL_BIN -h {host} -P {port} -u {user} -p'{password}' {database_from_log_or_user} -e "{SQL}"

常用排查查询模板

查看表结构

DESCRIBE table_name;
SHOW CREATE TABLE table_name;

按 ID 查记录

SELECT * FROM table_name WHERE id = {id} AND del_flag = 2;

查看最近修改的数据

SELECT * FROM table_name
WHERE uptime >= '{log_timestamp}'
ORDER BY uptime DESC
LIMIT 20;

检查关联数据一致性

SELECT a.id, b.id AS related_id
FROM table_a a
LEFT JOIN table_b b ON a.related_id = b.id
WHERE a.id = {id} AND b.id IS NULL;

统计数据分布

SELECT status, COUNT(*) as cnt
FROM table_name
WHERE del_flag = 2
GROUP BY status;

查看某时间段的操作记录

SELECT * FROM table_name
WHERE crtime BETWEEN '{start}' AND '{end}'
ORDER BY crtime DESC
LIMIT 50;

安全规范（强制执行，违反即终止）

允许执行的 SQL（白名单）

只允许以下语句类型：

• SELECT — 查询数据
• DESCRIBE / DESC — 查看表结构
• SHOW — 查看建表语句、索引、状态等
• EXPLAIN — 分析执行计划

禁止执行的 SQL（黑名单）

DDL 操作 — 全部禁止：

• CREATE TABLE / VIEW / INDEX / DATABASE
• ALTER TABLE / COLUMN
• DROP TABLE / VIEW / INDEX / DATABASE
• TRUNCATE TABLE
• RENAME TABLE

DML 写操作 — 全部禁止：

• INSERT — 禁止插入数据
• UPDATE — 禁止更新数据
• DELETE — 禁止删除数据
• REPLACE — 禁止替换数据

权限/管理操作 — 全部禁止：

• GRANT / REVOKE
• SET GLOBAL
• FLUSH

敏感 SQL 拦截（执行前必须分析）

在执行任何 SQL 之前，必须进行安全分析。遇到以下情况时，不执行 SQL，改为输出分析结果并询问用户：

执行前检查流程

收到/构造 SQL
  │
  ├─ 是否在白名单内？ ──→ 否 → 拒绝执行，输出原因
  │
  ├─ 是否命中敏感规则？ ──→ 是 → 输出风险分析，询问用户
  │
  ├─ 是否包含 LIMIT？ ──→ 否 → 自动追加 LIMIT 50
  │
  └─ 通过所有检查 → 执行 SQL

查询结果安全

• 查询必须加 LIMIT（默认 LIMIT 50）防止返回过多数据
• 不在输出中暴露密码、手机号（phone）、身份证（id_card）等敏感字段
• 查询结果中的敏感字段用 *** 脱敏展示
• 如需修改数据，只输出 SQL 语句让用户手动执行，不代为执行

配置文件安全

• .claude/mysql-config.json 已加入 .gitignore，禁止提交到版本库

与 bug-detective 配合

本技能是 bug-detective 的数据层扩展。当 bug-detective 被触发时，会自动评估是否需要同时激活 mysql-debug：

典型联合使用：

用户："订单查询接口返回空数据，日志如下..."
日志：2026-03-04 10:21:40.902,-,546198574447230976,, ERROR ...

→ 评估：需要查库（数据返回空，需确认数据是否存在）
→ 提取数据库：546198574447230976
→ 执行：SELECT * FROM order_info WHERE id = xxx AND del_flag = 2
→ 发现：del_flag = 1（已删除），用户操作了删除但不知情
→ 修复方案：恢复数据 / 检查前端删除按钮权限

注意

• 本技能专注于查询数据库辅助排查，不涉及建表、迁移等操作（请使用 database-ops）
• 如果是纯代码错误（NPE、语法错误等）不需要查库，请使用 bug-detective
• 如果是 SQL 性能问题（慢查询），请使用 performance-doctor