sql-tap CI模式实战:让测试套件自动检测N+1与慢查询并阻断构建

原创2026-10-11 11:46:571,356 阅读

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-tap 实时SQL流量嗅探终端界面演示

关键设计:检测在代理侧完成。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。

sql-tap Web界面实时SQL查询流与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 问题。

实战小贴士 💡

  1. CI 走代理端口,本地走真实端口:DATABASE_URL 只是 :5433 与 :5432 的差别,用环境变量切换即可,互不干扰。
  2. 报告按模板聚合并计数:问题次数最多的查询排最前(按 count 降序),修复时优先处理它。
  3. CI 模式专供一次性测试运行:它会收集到收到信号为止,日常开发想实时看 SQL,直接用 TUI(sql-tap localhost:9091)或 Web UI(--http=:8080)更合适。
  4. 想立刻体验? 仓库 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 是一个零侵入的完整方案。

登录后查看全文
sql-tap