KechuAI

sql-tap：架在应用与数据库之间的实时 SQL 流量监视器

数据库
PostgreSQL
MySQL
可观测性
开源
Go
2026/9/29
·

阅读时间: 大约 7 分钟

sql-tap：架在应用与数据库之间的实时 SQL 流量监视器

sql-tap 的终端 UI：按时间列出每条查询、操作类型、耗时与事务

调试数据库性能时，开发者通常在三条路里选：开数据库慢查询日志（事后、粗糙）、接 APM（重、要埋点）、或者直接在应用日志里翻 SQL。sql-tap 走的是第四条路——把一个代理守护进程插在应用和数据库中间，像抓包一样把每条查询实时摊在你眼前。它由 mickamy 用 Go 编写、MIT 协议开源，支持 PostgreSQL、MySQL 与 TiDB。本文基于其 GitHub README 的一手内容做分析。

一、它解决什么问题

N+1 查询、慢查询、事务里混了几条语句、某条 SQL 实际跑了多久——这些问题在「应用日志 + 慢日志」的组合下定位起来很割裂：日志里看不到数据库真实耗时，慢日志又只记录超过阈值的那部分，事务边界更是要自己拼。

sql-tap 的思路是中间人代理：应用连到 sql-tap 监听的端口（如 :5433），由它转发到真正的数据库（:5432）。因为它讲数据库原生线协议，应用端一行代码都不用改，只要把连接串的端口换掉。捕获到的查询通过 gRPC（默认 :9091）推给前端，前端有 TUI（终端）和 Web UI（--http :8080）两种形态。

二、怎么跑起来

官方 Quick Start 三步：

# 1. 起代理：监听 :5433，转发到本机 :5432
DATABASE_URL="postgres://user:pass@localhost:5432/db?sslmode=disable" \
  sql-tapd --driver=postgres --listen=:5433 --upstream=localhost:5432

# 2. 把应用连到 :5433（而不是 :5432），无需改代码

# 3. 起 TUI 看实时流量
sql-tap localhost:9091

MySQL（:3307→:3306）与 TiDB（:4001→:4000）同理，换 --driver 即可。安装方式覆盖 Homebrew、go install、Nix flake、Docker 旁车（sidecar）部署。

三、关键能力与默认参数

sql-tap 的 Web UI：50 条查询实时流，按事务 ID 分组，可一键 EXPLAIN / EXPLAIN ANALYZE

从截图能看到它的核心视图：每条查询一行，列是时间、操作（Begin/Execute/Commit/Rollback）、SQL、耗时（微秒级）、错误标记；底部面板选中一条后显示参数（Args）、事务 ID（Tx），并提供 EXPLAIN、EXPLAIN ANALYZE、复制 SQL 等按钮——EXPLAIN 用的是 --dsn-env 指定的那个真实 DSN 去数据库上执行。

N+1 检测是它的卖点之一，README 暴露了三个可调旋钮（这也是最该读懂的口径）：

参数默认值含义
--nplus1-threshold5同一查询模板触发多少次才判为 N+1（0 关闭）
--nplus1-window1s统计时间窗口
--nplus1-cooldown10s每个查询模板告警后的静默期

慢查询阈值 --slow-threshold 也可配。

四、官方口径之外：必须自己评估的风险

README 把功能讲得很顺，但有几个边界需要读者自己补全：

  1. 生产环境多了一个网络跳点。代理在中间转发，意味着引入了一个额外的延迟来源与故障点。Koala 点评的建议是对的：先在开发/测试环境用，不要一上来把生产流量切到 sql-tapd 后面。一旦代理崩了，应用连库就断——它不是无旁路的 tap，而是 in-path 代理。

  2. N+1 阈值是「调出来」的，不是「设好」的。默认 5 次/1 秒窗口，对一个批处理脚本可能正好，对一个本就循环查 4 次的合理逻辑就会误报；cooldown 10s 又可能让连续爆发被合并。官方没有给出「推荐阈值 = 你的 QPS」这类映射，需要按自己应用的查询形态调。

  3. 项目非常早期。Docker 示例里版本号仍是 0.0.1，提交约「2 个月前」。这意味着协议稳定性、性能 overhead、边缘 case（大结果集、预处理语句、复制协议）都还需要自己实测——README 没有给出代理引入的额外延迟基准（「官方称零侵入」是架构描述，不是延迟测量）。

  4. EXPLAIN 是真实打到你的数据库上。方便是方便，但要注意它会在你的库上执行分析型查询，量大时自身也有成本。

五、适用与不适用场景

适合： 开发与测试环境本地起服务时实时观察 ORM 到底发了什么 SQL（尤其排查 N+1）；演示/教学时把事务的 Begin→多条执行→Commit/Rollback 过程可视化；不想接重型 APM 又需要比慢日志更实时的视图。

不适合： 直接放进生产流量路径当常驻监控（故障域 + 跳点风险）；需要长期归档、聚合、按天报表的场景（它是实时查看器，不是时序仓库）；需要评估代理自身开销的生产 SLO 场景——没有公开基准。

六、客观分析：优势与意义

优势： 原生线协议代理、零应用改动，接入成本极低；TUI/Web 双形态，终端党和浏览器党都照顾到；N+1 检测、事务追踪、一键 EXPLAIN 把「看流量」和「查计划」连了起来；Go 单二进制分发，部署轻。

局限： in-path 代理的可靠性负担；项目早期、版本 0.0.1、缺公开性能基准；N+1 规则需要自行调参；只覆盖 Postgres/MySQL/TiDB 三家。

sql-tap 这类工具的价值，在于把「数据库里到底发生了什么」从一个需要事后拼凑的问题，变成了开发时一眼可见的东西。它不替代 APM，也不该直接上生产，但作为开发者本机的 SQL 调试镜，方向是对的——前提是你接受「多一跳」这个代价。

参考来源