sql-tap CI模式实战:让测试套件自动检测N+1与慢查询并阻断构建
sql-tap CI模式实战:让测试套件自动检测N+1与慢查询并阻断构建
sql-tap 是一个开源的实时 SQL 流量嗅探工具,而它的 CI 模式(sql-tap -ci)可以把整个测试套件"包"进嗅探代理:跑完测试后自动汇总所有 N+1 查询 与 慢查询,输出报告并以退出码 1 直接阻断构建。全程无需修改业务代码、无需 ORM 插件、无需解析数据库日志,对 PostgreSQL、MySQL、TiDB 开箱即用。
CI模式工作原理:代理嗅探 + 客户端汇总
架构非常简单:代理守护进程 sql-tapd 插在你的应用(或测试套件)与数据库之间,解析数据库 wire 协议透明转发每一条 SQL,同时记录执行时长、行数、错误等信息;客户端 sql-tap -ci 则通过 gRPC 流收集这些事件,收到终止信号(SIGTERM/SIGINT)或流结束后输出报告并退出。
关键设计:检测在代理侧完成。sql-tapd 会给每条查询事件打上 NPlus1 / SlowQuery 标记(见 proxy/proxy.go 的 Event 结构体),CI 收集端只负责聚合统计,逻辑干净利落。
三步接入:从安装到阻断构建
第一步:安装 sql-tap 客户端与代理守护进程
- Homebrew:
brew install mickamy/tap/sql-tap - Go:
go install github.com/mickamy/sql-tap@latest与go install github.com/mickamy/sql-tap/cmd/sql-tapd@latest - 源码构建:参考 Makefile 的
install目标
注意 CI 模式需要两个二进制:代理 sql-tapd 和客户端 sql-tap。项目附带 Dockerfile,也可以把 sql-tapd 作为 sidecar 部署在测试数据库旁边。
第二步:启动 SQL 嗅探代理
以 PostgreSQL 为例,代理监听 :5433,转发到真实数据库的 :5432:
DATABASE_URL="postgres://user:pass@localhost:5432/db?sslmode=disable" \
sql-tapd --driver=postgres --listen=:5433 --upstream=localhost:5432
MySQL 则换成 --driver=mysql --listen=:3307 --upstream=localhost:3306;完整参数说明见 README.md。
第三步:测试流量走代理,用退出码阻断流水线
唯一要改的地方,是让测试套件的 DSN 指向代理端口:
# 1. 后台启动 sql-tap CI 模式
sql-tap -ci localhost:9091 &
CI_PID=$!
# 2. 运行测试套件,SQL 全部经过 :5433 代理
DATABASE_URL="postgres://user:pass@localhost:5433/db?sslmode=disable" go test ./...
# 3. 终止收集端 —— 打印报告,退出码 0(通过)或 1(发现问题)
kill "$CI_PID" 2>/dev/null || true
wait "$CI_PID" 2>/dev/null
让 CI 平台(GitHub Actions / GitLab CI 等)依据 wait 的退出码决定是否阻断流水线即可。发现问题时,输出类似:
sql-tap CI Report
=================
Captured: 142 queries
Problems found:
[N+1] SELECT * FROM comments WHERE post_id = $1 (detected 12 times)
[SLOW] SELECT * FROM users JOIN ... (avg 523ms, 3 occurrences)
Exit: 1 (2 problems found)
报告与退出码的实现很直观:ci/ci.go 按"归一化后的查询模板"聚合事件,main.go 在有问题的情况下返回退出码 1。
N+1 与慢查询检测参数速查表 📊
两条检测规则完全跑在代理侧(N+1 检测器实现在 detect/detect.go,慢查询判断在 cmd/sql-tapd/main.go),常用参数如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
--nplus1-threshold |
5 |
同一模板在窗口内执行次数达到该值即标记 N+1(0 禁用) |
--nplus1-window |
1s |
滑动计数窗口 |
--nplus1-cooldown |
10s |
同一模板的告警冷却间隔 |
--slow-threshold |
100ms |
单条查询超过此时长计为慢查询(0 禁用) |
三个值得注意的细节:
- N+1 只监测 SELECT:INSERT/UPDATE/DELETE 与事务命令自动忽略;没有 FROM 子句的元数据查询(如
SELECT 1、SELECT @@version)也会被排除,驱动层的健康检查不会误报。 - 查询归一化是聚合的关键:query/normalize.go 会把 SQL 中的字面量替换成
?占位符,让 100 条只有 ID 不同的查询归并为同一模板。 - Web UI 同样受益:首次检出时弹 toast 通知 + 黄色高亮行 + Status 列显示
N+1。
用配置文件微调检测阈值
不必在 CI 脚本里堆参数——在项目根目录放一个 .sql-tap.yaml,sql-tapd 会自动加载(见 config/config.go):
driver: postgres
listen: ":5433"
upstream: "localhost:5432"
grpc: ":9091"
dsn_env: DATABASE_URL
slow_threshold: 200ms
nplus1:
threshold: 3
window: 2s
cooldown: 10s
命令行参数会覆盖配置文件中的同名项。CI 场景下建议适当收紧阈值:测试数据集小,slow_threshold 可以降到 50~100ms;threshold 降到 3 能更快暴露 N+1 问题。
实战小贴士 💡
- CI 走代理端口,本地走真实端口:
DATABASE_URL只是:5433与:5432的差别,用环境变量切换即可,互不干扰。 - 报告按模板聚合并计数:问题次数最多的查询排最前(按 count 降序),修复时优先处理它。
- CI 模式专供一次性测试运行:它会收集到收到信号为止,日常开发想实时看 SQL,直接用 TUI(
sql-tap localhost:9091)或 Web UI(--http=:8080)更合适。 - 想立刻体验? 仓库 example/ 目录自带会制造 N+1 与慢查询的演示程序(如 example/postgres/main.go),配合 example/compose.yaml 一条命令起齐数据库 + 代理环境。
总结
sql-tap CI 模式本质上是把"SQL 嗅探工具"变成了一道静态检查门禁:
- ✅ 零代码改动:wire 协议层透明嗅探
- ✅ N+1 + 慢查询双检测,按归一化模板聚合
- ✅ 退出码 1 阻断构建,任何 CI 平台即插即用
- ✅ 支持 PostgreSQL / MySQL / TiDB 三种数据库
下次想在流水线里加上"数据库健康检查"这一环,sql-tap -ci 是一个零侵入的完整方案。

