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 编写；可通过插件架构添加新驱动或集成。

功能一览

安装方式

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

界面展示 查询、耗时、状态 与 影响行数。按 Enter 查看详细查询，按 x 查看 EXPLAIN，按 c 复制。

Web 仪表板

如想在浏览器查看查询，启动 sql-tapd 时加上 --http=:8080：

sql-tapd --driver=postgres --listen=:5433 --upstream=localhost:5432 --http=:8080

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 许可证，社区支持，持续维护。

开始使用

1. 通过 Homebrew、Go、Docker 或源码安装 sql‑tapd。
2. 用数据库凭据启动代理。
3. 将应用指向代理端口。
4. 启动 sql-tap 或打开 Web UI。
5. 使用过滤器、N+1 检测或 EXPLAIN 深入排查问题。

结语

sql‑tap 将简洁与强大功能结合，将数据库流量转换为可实时浏览的流。无论你是在调试棘手的性能瓶颈、验证事务隔离，还是好奇应用输出什么 SQL，sql‑tap 都能为你提供必要的可见性。试一试——你和团队都会称赞。

祝监控愉快！