sql‑tap: Real‑Time SQL Watching with TUI and Web UI

In modern applications, database interactions are the heartbeat of the system, yet they are rarely visible in a readable form. sql‑tap fills that gap by sitting as a transparent proxy between your app and the database, capturing every query and exposing it through an interactive terminal UI (TUI) or a browser‑based dashboard.

Author’s note: sql‑tap was created in Go, licensed under MIT, and has >900 GitHub stars. It supports PostgreSQL, MySQL, and TiDB, making it ideal for multi‑vendor environments.

Why sql‑tap?

• Zero code changes – Your application talks to the proxy instead of the database.
• Real‑time visibility – Every statement, transaction, and error floods your screen.
• Built‑in analytics – N+1 detection, EXPLAIN, query filtering, and export functions.
• Developer‑friendly UI – Keyboard‑driven TUI powered by Bubble Tea and a lightweight SSE‑based web UI.
• Extensible – Written in Go; add new drivers or integrations via a simple plugin architecture.

Features at a Glance

Feature	TUI	Web UI
Real‑time query stream	✔︎	✔︎
Query filtering & search	✔︎	✔︎
Highlight slow queries	✔︎	✔︎
N+1 detection (toast & marker)	✔︎	✔︎
EXPLAIN / EXPLAIN ANALYZE	✔︎	✔︎
Copy query or explain	✔︎	✔︎
Export to JSON / Markdown	✔︎	✔︎
Transaction inspection	✔︎	✔︎
Analytics view	✔︎	⬜️

Installation Options

Homebrew (macOS & Linux)

brew install --cask mickamy/tap/sql-tap

Go install

go install github.com/mickamy/sql-tap@latest
go install github.com/mickamy/sql-tap/cmd/sql-tapd@latest

Docker (PostgreSQL / MySQL / TiDB)

# PostgreSQL example
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"]

Replace postgres with mysql or tidb and adjust ports accordingly.

Build from Source

git clone https://github.com/mickamy/sql-tap.git
cd sql-tap
make install

Running the Proxy

The core component is sql‑tapd, the proxy daemon. Here is a quick example for PostgreSQL:

DATABASE_URL="postgres://user:pass@localhost:5432/db?sslmode=disable" \
sql-tapd --driver=postgres --listen=:5433 --upstream=localhost:5432

For MySQL:

DATABASE_URL="user:pass@tcp(localhost:3306)/db" \
sql-tapd --driver=mysql --listen=:3307 --upstream=localhost:3306

Connecting Your App

Point your database client or ORM to the listen port (5433, 3307, etc.). No code changes are required because the proxy speaks the native wire protocol.

TUI Client (sql-tap)

Open a new terminal and run:

sql-tap localhost:9091

This launches a keyboard‑driven interface. Keybindings are documented in the repo and include:

Key	Action
j/k	Move cursor
/	Incremental text search
f	Structured filter (e.g. d>100ms)
x	EXPLAIN
q	Quit

The interface shows query, duration, status, and rows affected. Press Enter to dive into a query, run x for an EXPLAIN, or c to copy.

Web Dashboard

If you wish to see queries in a browser, add --http=:8080 when starting sql-tapd:

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

Open http://localhost:8080 to view real‑time logs, filter, toggle N+1 detection, and analyze explain plans. The UI uses Server‑Sent Events (SSE) for streaming.

N+1 Query Detection

Many applications inadvertently issue N+1 selects. sql‑tap monitors templates (parameterized queries) and flags any template executed more than 5 times in 1 s by default.

sql-tapd --nplus1-threshold=5 --nplus1-window=1s

The TUI overlays a toast on first detection and highlights subsequent queries. The web UI shows a toast and yellow row background, with an N+1 marker in the Status column.

You can disable detection by setting the threshold to 0:

sql-tapd --nplus1-threshold=0

Advanced Usage

• EXPLAIN Support – Set the DATABASE_URL environment variable (or the var defined by -dsn-env) to enable explain plans. Without it, the proxy still captures queries but disables EXPLAIN.
• Exporting – Press w (TUI) or click the Export button to save the query log to JSON or Markdown.
• Extending Drivers – The Go codebase is modular; you can add support for new database drivers following the existing patterns.

Why sql‑tap is a Game‑Changer

• Rapid Diagnosis – Spot slow queries or transaction issues instantly.
• Non‑Intrusive – No instrumentation or logging changes.
• Cross‑Database – Works consistently across PostgreSQL, MySQL, and TiDB.
• Developer‑Friendly – Keyboard‑driven TUI plus a clear web UI.
• Open Source – MIT license, community‑supported, and actively maintained.

Getting Started

1. Install sql-tapd via Homebrew, Go, Docker, or source.
2. Run the proxy with your database credentials.
3. Point your application to the proxy port.
4. Launch sql-tap or open the web UI.
5. Use filters, N+1 detection, or EXPLAIN to dig into problematic queries.

Conclusion

sql‑tap merges simplicity with powerful functionality, turning your database traffic into a live, navigable stream. Whether you’re debugging a perplexing performance bottleneck, verifying transaction isolation, or just curious about the SQL your app emits, sql‑tap gives you the visibility you need. Give it a try—your database and team will thank you.

Happy monitoring!