核心用法
SQLFormat 是一款基于 Bash 的本地命令行工具，通过 sqlformat <command> [args] 语法调用。它提供 12 类核心操作指令（check、validate、generate、format、lint、explain、convert、template、diff、preview、fix、report），以及 stats、export、search、recent 等辅助指令。每个指令会将用户输入按 YYYY-MM-DD HH:MM|<input> 格式写入对应的 .log 文件，同时记录到统一的 history.log 中。
关键使用模式：
- 无参调用：查看该指令最近 20 条记录（如
sqlformat format显示 format.log 末 20 行） - 带参调用：将新条目追加写入对应日志文件
- 数据导出：支持通过
export json|csv|txt导出全部历史记录 - 跨日志检索：
search <term>可全库搜索关键词
显著优点
1. 零依赖部署：纯 Bash 4.0+ 实现，仅依赖标准 Unix 工具（date、grep、sed 等），无需 npm/pip/docker，兼容 Linux/macOS 全平台
2. 极简供应链风险：无外部依赖库，彻底消除供应链攻击面，适合安全敏感环境
3. 完整操作审计：自动为每条 SQL 操作打时间戳，形成可追溯的工作流历史，便于复盘和合规审查
4. 灵活数据导出：原生支持 JSON/CSV/TXT 三种格式导出，方便与其他工具链集成
5. 模板化沉淀：template 指令支持存储可复用的 SQL 片段，积累团队知识资产
潜在缺点与局限性
1. 功能-文档严重背离：SKILL.md 声称提供 "format、lint、validate、dialect conversion" 等能力，实际代码仅执行原始输入的日志记录，不具备任何实际的 SQL 解析、格式化或语法验证能力。用户若误信文档，可能提交未经格式化的代码。
2. 敏感数据明文存储：所有输入（可能包含生产库查询、表结构、业务逻辑甚至隐私数据）以纯文本形式持久化存储在 ~/.local/share/sqlformat/，无加密、无脱敏、无自动清理机制。共享设备或备份场景下泄露风险显著。
3. 无 SQL 处理能力：缺乏词法分析、语法树构建、方言差异解析等核心能力，convert 指令仅记录用户手写的转换说明字符串，而非自动转换。
4. 输入无验证：对用户输入无长度限制、无特殊字符转义，极端情况下可能导致日志注入或文件系统异常。
适合的目标群体
- 个人开发者：需要 lightweight、零配置的 SQL 操作历史追踪，用于本地复盘或习惯养成
- 小型敏捷团队：希望快速建立 SQL 变更的审计轨迹，无复杂合规要求的场景
- 离线/隔离环境：无法安装外部依赖（如 sqlparse、sqlfluff）的受限网络环境
- Bash 生态偏好者：习惯命令行工作流、倾向于文本化数据管理的开发者
不适用场景：需要真实 SQL 格式化、语法检查、方言转换的生产环境；处理敏感生产数据的合规敏感场景；追求 IDE 级 SQL 智能提示的大型团队。
使用风险
| 风险类别 | 具体表现 | 缓解建议 |
|---------|---------|---------|
| 功能误导风险 | 误信文档能力，提交未格式化的 SQL | 明确认知其为"记录器"而非"处理器"，生产环境配合真实格式化工具使用 |
| 敏感数据泄露 | 明文日志包含业务 SQL，设备共享/备份时暴露 | 设置 `SQLFORMAT_DIR` 指向加密卷；定期手动清理；避免输入含密码/PII 的查询 |
| 日志膨胀风险 | 高频使用导致 `~/.local/share/` 磁盘占用增长 | 定期执行 `stats` 监控，手动归档或删除旧日志 |
| T3 来源风险 | 个人开发者维护，长期支持不确定性 | 关注 GitHub 仓库活跃度；关键场景 fork 后自维护 |
| 无版本控制 | 单文件日志易损坏，无内置备份机制 | 自行配置目录级备份策略 |
总结
SQLFormat 本质上是一款基于时间戳的 SQL 活动审计日志工具，其价值在于轻量、零依赖、完整的历史追溯能力，而非文档宣称的 SQL 处理能力。适合明确认知其定位、能接受明文本地存储风险的开发者个人使用。若需真实的 SQL 格式化、linting 或跨方言转换，应选择 sqlfluff、pgFormatter、sqlparse 等专业工具，或将 SQLFormat 仅作为辅助审计层使用。