sql‑tap: 实时 SQL 监控，支持 TUI 与 Web UI
Discover sql‑tap, a lightweight Go‑based proxy that lets you monitor PostgreSQL, MySQL and TiDB traffic in real time without touching your application code. Learn how to install it via Homebrew, Go, Docker or source, launch the terminal UI or web dashboard, and use built‑in N+1 query detection, EXPLAIN support, and query analytics. Perfect for developers and DBAs looking to spot slow queries, debug transactions and improve performance. Get a step‑by‑step guide and best‑practice tips in this comprehensive walkthrough.
sql‑tap: 实时 SQL 监控，支持 TUI 与 Web UI
在现代应用中，数据库交互是系统的心跳，但它们很少以可读形式呈现。sql‑tap 通过在你的应用与数据库之间挂上一层透明代理，捕获每一次查询，并通过交互式终端 UI（TUI）或浏览器仪表板展示。
作者说明：sql‑tap 采用 Go 编写，MIT 许可，GitHub 关注度>900。它支持 PostgreSQL、MySQL 与 TiDB，适合多厂商环境。
为什么选 sql‑tap？
- 零代码改动 – 你的应用与代理通信，而非直接与数据库。
- 实时可见 – 每条语句、事务与错误都即时弹现。
- 内置分析 – N+1 检测、EXPLAIN、查询过滤与导出功能。
- 开发者友好 UI – 基于 Bubble Tea 的键盘驱动 TUI，轻量级 SSE‑based Web UI。
- 可扩展 – 用 Go 编写；可通过插件架构添加新驱动或集成。
功能一览
| 功能 | TUI | Web UI |
|---|---|---|
| 实时查询流 | ✔︎ | ✔︎ |
| 查询过滤 & 搜索 | ✔︎ | ✔︎ |
| 高亮慢查询 | ✔︎ | ✔︎ |
| N+1 检测（toast 与标记） | ✔︎ | ✔︎ |
| EXPLAIN / EXPLAIN ANALYZE | ✔︎ | ✔︎ |
| 复制查询或 EXPLAIN | ✔︎ | ✔︎ |
| 导出到 JSON / Markdown | ✔︎ | ✔︎ |
| 事务检查 | ✔︎ | ✔︎ |
| 分析视图 | ✔︎ | ⬜️ |
安装方式
Homebrew (macOS & Linux)
brew install --cask mickamy/tap/sql-tap
Go 安装
go install github.com/mickamy/sql-tap@latest
go install github.com/mickamy/sql-tap/cmd/sql-tapd@latest
Docker (PostgreSQL / MySQL / TiDB)
# PostgreSQL 示例
FROM postgres:18-alpine
ARG SQL_TAP_VERSION=0.0.1
ARG TARGETARCH
ADD https://github.com/mickamy/sql-tap/releases/download/v${SQL_TAP_VERSION}/sql-tap_${SQL_TAP_VERSION}_linux_${TARGETARCH}.tar.gz /tmp/sql-tap.tar.gz
RUN tar -xzf /tmp/sql-tap.tar.gz -C /usr/local/bin sql-tapd && rm /tmp/sql-tap.tar.gz
ENTRYPOINT ["sql-tapd", "--driver=postgres", "--listen=:5433", "--upstream=localhost:5432", "--grpc=:9091"]
将 postgres 换成 mysql 或 tidb 并按需调整端口。
源码构建
git clone https://github.com/mickamy/sql-tap.git
cd sql-tap
make install
启动代理
核心组件是 sql‑tapd，即代理守护进程。以下是 PostgreSQL 的快速示例：
DATABASE_URL="postgres://user:pass@localhost:5432/db?sslmode=disable" \
sql-tapd --driver=postgres --listen=:5433 --upstream=localhost:5432
MySQL 版本：
DATABASE_URL="user:pass@tcp(localhost:3306)/db" \
sql-tapd --driver=mysql --listen=:3307 --upstream=localhost:3306
连接你的应用
将数据库客户端或 ORM 指向 监听 端口（如 5433、3307 等）。无需改动代码，因为代理使用原生协议。
TUI 客户端（sql-tap）
打开新终端并运行：
sql-tap localhost:9091
这会启动键盘驱动界面。按键绑定见仓库文档，主要包括：
| 键 | 操作 |
|---|---|
j/k |
移动光标 |
/ |
渐进式文本搜索 |
f |
结构化过滤（例如 d>100ms） |
x |
EXPLAIN |
q |
退出 |
界面展示 查询、耗时、状态 与 影响行数。按 Enter 查看详细查询，按 x 查看 EXPLAIN，按 c 复制。
Web 仪表板
如想在浏览器查看查询，启动 sql-tapd 时加上 --http=:8080：
sql-tapd --driver=postgres --listen=:5433 --upstream=localhost:5432 --http=:8080
打开 http://localhost:8080 即可查看实时日志、过滤、切换 N+1 检测并分析 EXPLAIN 计划。UI 采用 SSE 进行流式传输。
N+1 查询检测
许多应用在无意中执行了 N+1 查询。sql‑tap 监视模板（参数化查询），并在默认条件下，若同一模板在 1 s 内执行超过 5 次，则标记。
sql-tapd --nplus1-threshold=5 --nplus1-window=1s
TUI 在首次检测时弹出 toast，并高亮后续查询。Web UI 则显示 toast、黄色行背景，并在 状态 列加 N+1 标记。
若想禁用检测，将阈值设为 0：
sql-tapd --nplus1-threshold=0
高级使用
- EXPLAIN 支持 – 设置
DATABASE_URL环境变量（或-dsn-env定义的变量）即可启用 EXPLAIN 计划。未设置时，代理仍捕获查询，但会禁用 EXPLAIN。 - 导出 – 在 TUI 按
w或点击 导出 按钮，将查询日志保存为 JSON 或 Markdown。 - 扩展驱动 – Go 代码结构模块化；可按现有模式新增数据库驱动支持。
为什么 sql‑tap 成为革新者
- 快速诊断 – 立即发现慢查询或事务问题。
- 非侵入性 – 无需任何注入或日志改动。
- 跨数据库 – 在 PostgreSQL、MySQL 与 TiDB 之间表现一致。
- 开发者友好 – 键盘驱动 TUI 与直观 Web UI。
- 开源 – MIT 许可证，社区支持，持续维护。
开始使用
- 通过 Homebrew、Go、Docker 或源码安装
sql‑tapd。 - 用数据库凭据启动代理。
- 将应用指向代理端口。
- 启动
sql-tap或打开 Web UI。 - 使用过滤器、N+1 检测或 EXPLAIN 深入排查问题。
结语
sql‑tap 将简洁与强大功能结合，将数据库流量转换为可实时浏览的流。无论你是在调试棘手的性能瓶颈、验证事务隔离，还是好奇应用输出什么 SQL，sql‑tap 都能为你提供必要的可见性。试一试——你和团队都会称赞。
祝监控愉快！