MySQL 数据库查询调试技能

概述

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

核心能力：

• 智能判断 Bug 是否需要查库（明显代码错误跳过）

• 从日志自动提取数据库名（租户 ID = 数据库名）

• 只读查询，安全排查

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

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

优先级 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 查找（多路径）

按顺序查找 mysql 客户端：

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

找到任一即可使用。如果全部不存在，输出安装提示：

brew install mysql-client

引导提示（仅当连接信息和 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" }

环境选择规则

优先级 来源 示例

1（最高） 用户对话中指定 "连 dev 环境查一下"、"用生产库看看"

2 配置文件 default 字段 "default": "local"

环境关键词映射

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

用户说法 环境

"本地"、"local"、"本地环境" local

"开发"、"dev"、"测试环境"、"开发环境" dev

"生产"、"prod"、"线上"、"正式环境" prod

连接示例

用户说"连 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 --- [线程名] 类名 : 行号 : 日志内容

提取规则

• 自动提取：从日志行中匹配 ,-,(\d{15,19}),, 模式，提取的数字即为数据库名

• 手动指定：用户直接说"查 546198574447230976 库"或"数据库名是 xxx"

• 优先级：手动指定 > 日志提取 > 配置文件 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-config.json > bootstrap-dev.yml 自动提取

数据库名来源：用户指定 > 日志提取的租户ID

mysql -h {host} -P {port} -u {user} -p'{password}' {database_from_log_or_user} -e "{SQL}"

mysql 路径：如果 which mysql 失败，尝试绝对路径

/opt/homebrew/opt/mysql-client/bin/mysql -h {host} ...

常用排查查询模板

查看表结构

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，改为输出分析结果并询问用户：

风险类型 检测规则 处理方式

无 WHERE 全表扫描 SELECT * FROM xxx 无 WHERE 子句 提醒用户加条件，或自动加 LIMIT 10

大范围查询 WHERE 条件覆盖范围过大（如 del_flag = 2 ） 提醒加更精确条件，强制 LIMIT 50

多表 JOIN 无条件 JOIN 无 ON 条件（笛卡尔积） 拒绝执行，提示补充 JOIN 条件

子查询嵌套过深 超过 3 层嵌套子查询 输出 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：

步骤 bug-detective mysql-debug

1 分析日志、定位异常层 评估是否需要查库

2 识别涉及的表和查询 从日志提取数据库名

3 推断可能原因 执行 SQL 验证数据

4 给出修复方案 用数据证实/排除假设

典型联合使用：

用户："订单查询接口返回空数据，日志如下..." 日志：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