MYSQL QUERY

核心用法

db-query 是一款面向开发运维场景的数据库查询技能，核心解决远程数据库安全访问与配置管理标准化两大痛点。通过集中式 JSON 配置文件管理多数据库连接，支持自动 SSH 隧道建立与销毁，用户只需指定数据库描述名即可执行 SQL 查询。

工作流程：
1. 读取 ~/.config/clawdbot/db-config.json 匹配数据库描述
2. 若配置 SSH 隧道，自动建立本地端口转发
3. 通过环境变量注入密码，执行 MySQL 查询
4. 查询完成后自动关闭 SSH 隧道，避免连接残留

显著优点

• 安全设计优先：密码通过 MYSQL_PWD/SSHPASS 环境变量传递，进程列表中不可见；推荐将敏感信息外置到环境变量而非配置文件
• 零运维负担：SSH 隧道的生命周期完全自动化，无需手动 ssh -L 或担心忘记关闭
• 多环境友好：单配置文件支持多个数据库，通过描述名区分，支持大小写不敏感的部分匹配
• 配置即代码：JSON 配置易于版本控制（脱敏后），环境变量命名规范清晰

潜在缺点与局限性

• 仅支持 MySQL：当前实现依赖 mysql 客户端，不支持 PostgreSQL、MongoDB 等
• Python 3.6+ 依赖：目标环境需预装 Python，且脚本路径硬编码于 node_modules 下，移植性受限
• 单查询单连接：每次查询独立建立连接，高频短查询场景开销较大
• SSH 密码依赖 sshpass：若使用 SSH 密码认证需额外安装 sshpass，密钥认证场景未明确说明
• 错误处理透明度：自动隧道关闭虽便利，但连接失败时的调试信息可能分散在多个层

适合人群

• 需要频繁访问跳板机后数据库的开发者、DBA
• 追求配置标准化、避免本地 SSH 隧道手动管理的团队
• 已将 MySQL 作为主力数据库的技术栈

常规风险

• 环境变量在 shell history 中可能残留（建议配合 HISTCONTROL 或使用专用 secret 管理工具）
• 配置文件权限若设置不当（如 644），数据库描述等元数据可能泄露
• 本地端口冲突：多数据库共用同一 local_port 会导致隧道建立失败

核心用法

db-query 是一款面向开发和运维场景的数据库查询工具，核心能力在于自动化的 SSH 隧道生命周期管理。用户通过 JSON 配置文件定义数据库连接信息，工具在执行查询前自动建立 SSH 隧道，查询完成后自动清理关闭，无需手动管理连接状态。

典型工作流：
1. 配置 ~/.config/clawdbot/db-config.json 文件，定义数据库名、主机、端口及可选的 SSH 隧道参数
2. 通过环境变量注入敏感凭据（推荐），避免密码落盘
3. 执行查询命令，工具自动匹配配置、建立隧道、执行 SQL、返回结果并清理资源

环境变量命名规范：

• 数据库密码：DB_PASSWORD_<DATABASE_NAME>（空格转下划线、大写）
• SSH 密码：SSH_PASSWORD_<DATABASE_NAME>

显著优点

• 安全凭据管理：完全依赖 MYSQL_PWD 和 SSHPASS 环境变量传递密码，进程列表中绝不暴露敏感信息，从根本上杜绝 ps aux 泄露风险
• 零第三方依赖：仅使用 Python 标准库（288 行代码/3 个文件），供应链攻击面极小，依赖审计得分 95 分
• 自动资源清理：通过 atexit 注册钩子确保 SSH 隧道在使用后可靠关闭，避免连接残留导致的端口占用或安全隐患
• 灵活配置驱动：支持多数据库配置，通过描述性名称模糊匹配，支持自定义配置文件路径
• 传输层加密：SSH 隧道 + MySQL SSL/TLS 双重保障，符合 GDPR、CCPA 等合规要求

潜在缺点与局限性

• 模糊匹配风险：数据库描述采用大小写不敏感的部分匹配，若配置中存在相似名称可能意外命中非预期数据库
• 外部命令依赖：依赖系统预装的 mysql-client 和 ssh，版本差异可能导致兼容性问题
• 配置文件权限：虽推荐环境变量存密码，但配置文件的权限管理仍依赖用户自觉，默认未强制 600 权限
• 主机密钥策略：使用 StrictHostKeyChecking=accept-new，首次连接自动接受新主机指纹，存在中间人攻击理论风险
• 无 SQL 注入内置检测：虽通过 mysql 客户端执行具备天然隔离，但工具层未对 --query 参数做危险关键字校验

适合人群

• 运维工程师：需要安全访问跳板机后的内网数据库，厌倦手动管理 SSH 隧道
• 全栈开发者：本地开发需频繁切换多套环境（开发/测试/生产）的数据库连接
• 安全敏感团队：对凭据泄露高度警惕，要求密码零落盘、零进程暴露
• 合规要求严格的组织：需满足数据最小化、传输加密、用户知情权等 GDPR/CCPA 条款

常规风险

| 风险类别 | 说明 | 缓解措施 |

|---------|------|---------|

| 配置文件泄露 | 配置文件中可能残留密码 | 强制使用环境变量；设置 `chmod 600` 权限 |

| SSH 主机伪造 | 自动接受新主机指纹 | 预连接目标主机并手动验证指纹 |

| 查询误匹配 | 模糊匹配导致连接错误数据库 | 配置命名保持唯一性，避免相似前缀 |

| 进程注入 | subprocess 执行外部命令的理论风险 | 确保 mysql/ssh 客户端来自可信源 |