sql‑tap: TUI と Web UIでリアルタイム SQL 監視

現在のアプリケーションでは、データベースとのやり取りがシステムの鼓動となりますが、読める形式で可視化されることはほとんどありません。sql‑tapは、アプリとデータベースの間に透明なプロキシとして位置し、すべてのクエリを捕捉してインタラクティブなターミナル UI（TUI）またはブラウザベースのダッシュボードで表示することで、このギャップを埋めます。

著者のノート: sql-tap は Go で作られ、MIT ライセンスで公開され、900件を超える GitHub のスターを獲得しています。PostgreSQL、MySQL、TiDB をサポートし、複数ベンダー環境に最適です。

Why sql‑tap?

• コードの変更は不要 – アプリケーションはデータベースではなくプロキシと通信します。
• リアルタイム可視化 – すべてのステートメント、トランザクション、エラーが画面に映ります。
• 組み込み解析機能 – N+1検出、EXPLAIN、クエリフィルタリング、およびエクスポート機能。
• 開発者フレンドリーUI – Bubble Teaで動くキーボード駆動 TUI と軽量SSEベースの Web UI。
• 拡張可能 – Go で実装され、シンプルなプラグインアーキテクチャで新しいドライバや統合を追加できます。

Features at a Glance

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 の例
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 に置き換えて、ポートを調整してください。

Build from Source

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

Running the Proxy

プロキシデーモン 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

Connecting Your App

データベースクライアントまたはORMをプロキシの listen ポート（例：5433、3307）に向けます。プロキシはネイティブプロトコルで通信するため、コード変更は不要です。

TUI Client (sql-tap)

新しいターミナルを開き、実行してください:

sql-tap localhost:9091

インターフェイスは クエリ、duration、status、rows affected を表示します。Enter を押すとクエリの詳細に進み、x を実行してEXPLAINを表示、c でコピーできます。

Web Dashboard

ブラウザでクエリを確認したい場合は、sql-tapd の起動時に --http=:8080 を付与します:

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

N+1 Query Detection

多くのアプリケーションは意図せず N+1 選択を発行します。sql‑tap はテンプレート（パラメータ化クエリ）を監視し、デフォルトで 5 回以上 1 s 内に実行されたテンプレートをフラグします。

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

TUI では最初の検出時にトーストを表示し、以降のクエリをハイライトします。Web UI ではトーストと黄背景、Status 列に N+1 マーカーを表示します。

検出を無効にしたい場合は閾値を 0 に設定します:

sql-tapd --nplus1-threshold=0

Advanced Usage

• EXPLAIN Support – DATABASE_URL 環境変数（または -dsn-env で定義された変数）を設定してエグゼプランを有効にします。設定しないとプロキシはクエリを取得しつつも EXPLAIN を無効化します。
• Exporting – TUI で w を押すか Export ボタンをクリックしてクエリログを JSON か Markdown で保存します。
• Extending Drivers – Go コードベースはモジュラー設計で、新しいデータベースドライバを既存のパターンに従って追加できます。

Why sql‑tap is a Game‑Changer

• 迅速な診断 – 遅延クエリやトランザクション問題を即座に検出します。
• 非侵襲的 – 設備化やログ変更は不要です。
• クロスデータベース – PostgreSQL、MySQL、TiDB で一貫して動作します。
• 開発者フレンドリー – キーボード駆動 TUI と明快な Web UI を備えています。
• オープンソース – MIT ライセンス、コミュニティサポート、積極的に保守されています。

Getting Started

1. Homebrew、Go、Docker、またはソースから sql-tapd をインストールします。
2. データベース認証情報でプロキシを実行します。
3. アプリケーションをプロキシのポートに向けます。
4. sql-tap を起動するか Web UI を開きます。
5. フィルタ、N+1 検出、または EXPLAIN を使って問題のあるクエリを掘り下げます。

Conclusion

sql‑tap はシンプルさと強力な機能を融合し、データベーストラフィックをライブでナビゲート可能なストリームに変換します。パフォーマンスボトルネックのデバッグ、トランザクション分離の検証、あるいはアプリが発行する SQL を単に知りたいだけでも、sql‑tap は必要な可視化を提供します。ぜひお試しください—データベースとチームから感謝を受けることでしょう。

モニタリングをお楽しみください！