mickamy/sql-tap

sql-tap

Real-time SQL traffic viewer — proxy daemon + TUI / Web client.

sql-tap sits between your application and your database (PostgreSQL, MySQL, or TiDB), capturing every query and displaying it in an interactive terminal UI. Inspect queries, view transactions, and run EXPLAIN — all without changing your application code.

Installation

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

Build from source

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

Nix

Using the flake directly

nix profile install github:mickamy/sql-tap

In a devenv.sh project

Add sql-tap as a flake input in devenv.yaml:

inputs:
  sql-tap:
    url: github:mickamy/sql-tap

Then reference it in devenv.nix:

{ inputs, pkgs, ... }:
{
  packages = [
    inputs.sql-tap.packages.${pkgs.system}.default
  ];
}

Docker

FROM alpine:3
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"]

Run as a sidecar alongside your database:

# PostgreSQL
docker run --rm --network=host sql-tap \
  --driver=postgres --listen=:5433 --upstream=localhost:5432 --grpc=:9091

# MySQL
docker run --rm --network=host sql-tap \
  --driver=mysql --listen=:3307 --upstream=localhost:3306 --grpc=:9091

Quick start

1. Start the proxy daemon

# PostgreSQL: proxy listens on :5433, forwards to PostgreSQL on :5432
DATABASE_URL="postgres://user:pass@localhost:5432/db?sslmode=disable" \
  sql-tapd --driver=postgres --listen=:5433 --upstream=localhost:5432

# MySQL: proxy listens on :3307, forwards to MySQL on :3306
DATABASE_URL="user:pass@tcp(localhost:3306)/db" \
  sql-tapd --driver=mysql --listen=:3307 --upstream=localhost:3306

# TiDB: proxy listens on :4001, forwards to TiDB on :4000
DATABASE_URL="user:pass@tcp(localhost:4000)/db" \
  sql-tapd --driver=tidb --listen=:4001 --upstream=localhost:4000

2. Point your application at the proxy

Connect your app to the proxy port instead of the database port. No code changes needed — sql-tapd speaks the native wire protocol.

3. Launch the TUI

sql-tap localhost:9091

All queries flowing through the proxy appear in real-time.

Usage

sql-tapd

sql-tapd — SQL proxy daemon for sql-tap

Usage:
  sql-tapd [flags]

Flags:
  -config    path to config file (default: .sql-tap.yaml if exists)
  -driver    database driver: postgres, mysql, tidb (required)
  -listen    client listen address (required)
  -upstream  upstream database address (required)
  -grpc      gRPC server address for TUI (default: ":9091")
  -http      HTTP server address for web UI (e.g. ":8080")
  -dsn-env   env var holding DSN for EXPLAIN (default: "DATABASE_URL")
  -nplus1-threshold  N+1 detection threshold (default: 5, 0 to disable)
  -nplus1-window     N+1 detection time window (default: 1s)
  -nplus1-cooldown   N+1 alert cooldown per query template (default: 10s)
  -slow-threshold    slow query threshold (default: 100ms, 0 to disable)
  -version   show version and exit

Set DATABASE_URL (or the env var specified by -dsn-env) to enable EXPLAIN support. Without it, the proxy still captures queries but EXPLAIN is disabled.

Config file

Instead of passing flags on every invocation, you can create a .sql-tap.yaml in your project directory:

driver: postgres
listen: ":5433"
upstream: "localhost:5432"
grpc: ":9091"
http: ":8080"
dsn_env: DATABASE_URL
slow_threshold: 100ms
nplus1:
  threshold: 5
  window: 1s
  cooldown: 10s

sql-tapd automatically loads .sql-tap.yaml from the current directory. Use -config to specify a different path. CLI flags override config file values.

Web UI

Add --http=:8080 to serve a browser-based viewer:

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

Open http://localhost:8080 in your browser to view queries in real-time. The web UI supports:

• Real-time query stream via SSE
• Click to inspect query details
• EXPLAIN / EXPLAIN ANALYZE
• Text filter
• Copy query (with or without bound args)
• N+1 detection (toast + row highlight)
• Timeline view (Gantt-chart style query visualization)

sql-tap

sql-tap — Watch SQL traffic in real-time

Usage:
  sql-tap [flags] <addr>

Flags:
  -ci       run in CI mode: collect events until SIGTERM/SIGINT or stream ends, then report and exit
  -version  Show version and exit

<addr> is the gRPC address of sql-tapd (e.g. localhost:9091).

CI mode

Run sql-tap -ci to detect N+1 and slow queries in your test suite. It connects to a running sql-tapd (see Quick start for setup), collects events, and exits with code 1 if any problems are found.

# Start sql-tap in CI mode (background)
sql-tap -ci localhost:9091 &
CI_PID=$!

# Run your tests through the proxy
DATABASE_URL="postgres://user:pass@localhost:5433/db?sslmode=disable" go test ./...

# Stop sql-tap — prints report and exits 0 (clean) or 1 (problems found)
kill "$CI_PID" 2>/dev/null || true
wait "$CI_PID" 2>/dev/null || true

Example output:

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)

Keybindings

List view

Inspector view

Analytics view

Timeline view

Explain view

Filter syntax

Press f in the list view to enter filter mode. Filters support structured conditions that go beyond simple text search.

Multiple tokens are separated by spaces and combined with AND logic:

op:select d>100ms

This shows only SELECT queries that took longer than 100ms.

Both / (text search) and f (filter) can be active simultaneously — the filter is applied first, then the text search narrows the results further.

N+1 query detection

sql-tap automatically detects N+1 query patterns — when the same SELECT template is executed many times in a short time window.

Detection is enabled by default and runs server-side, so both TUI and Web UI benefit:

• TUI: alert overlay on first detection + N+1 marker in the Status column for every flagged query
• Web UI: toast notification on first detection + yellow row highlight + N+1 in the Status column

Configuration

Only SELECT queries are monitored. INSERT, UPDATE, DELETE, and transaction lifecycle commands (BEGIN, COMMIT, etc.) are excluded. Metadata queries — SELECT statements without a FROM clause, such as SELECT database(), SELECT @@version, or SELECT 1 — are also excluded, as they are typically driver health checks or system introspection calls rather than application data queries.

Once the threshold is crossed, all subsequent executions of the same template within the window are flagged. The cooldown only affects the notification frequency — the Status column marker always appears.

To disable detection entirely:

sql-tapd --nplus1-threshold=0 ...

Known limitations

Arrow key input in search / filter mode

Due to a limitation in the terminal input parser used by Bubble Tea v1, multi-byte escape sequences (such as arrow keys: ESC [ A/B/C/D) can occasionally be split across OS-level read() calls. When this happens, the remaining bytes ([A, [B, [C, [D, [F, [H) would appear as garbage text in the input field.

sql-tap includes a workaround that detects and discards these split sequences. As a side effect, the literal two-character strings [A, [B, [C, [D, [F, and [H cannot be typed in search or filter input. This is unlikely to affect real-world usage since these patterns rarely appear in SQL queries.

How it works

┌─────────────┐      ┌───────────────────────┐      ┌───────────────────────────┐
│ Application │─────▶│  sql-tapd (proxy)     │─────▶│ PostgreSQL / MySQL / TiDB │
└─────────────┘      │                       │      └───────────────────────────┘
                     │  captures queries     │
                     │  via wire protocol    │
                     └───────────┬───────────┘
                                 │ gRPC stream / SSE
                     ┌───────────▼───────────┐
                     │  sql-tap (TUI)        │
                     │  Browser  (Web UI)    │
                     └───────────────────────┘

sql-tapd parses the database wire protocol (PostgreSQL, MySQL, or TiDB) to intercept queries transparently. It tracks prepared statements, parameter bindings, transactions, execution time, rows affected, and errors. Events are streamed to connected TUI clients via gRPC.

See also

• grpc-tap — Same concept for gRPC. Transparent HTTP/2 reverse proxy that captures every gRPC / gRPC-Web / Connect call with TUI + Web UI.

License

MIT