sql-tap 是一個即時 SQL 流量檢視器，包含代理伺服器後端與 TUI / 網頁用戶端。
sql-tap 部署於您的應用程式與資料庫（PostgreSQL、MySQL 或 TiDB）之間，擷取所有查詢並在互動式終端機使用者介面（TUI）中顯示。您無需更改應用程式程式碼，即可檢查查詢、檢視交易並執行 EXPLAIN。
將 sql-tap 加入 devenv.yaml 的 flake 輸入：
將其作為 sidecar 與您的資料庫一同執行：
2. 將您的應用程式指向代理伺服器
將應用程式連接到代理伺服器的連接埠，而非資料庫的連接埠。無需程式碼變更 — sql-tapd 可理解原生線路協定。
所有通過代理伺服器的查詢都會即時顯示。
設定 DATABASE_URL（或由 -dsn-env 指定的環境變數）以啟用 EXPLAIN 支援。若未設定，代理伺服器仍會擷取查詢，但 EXPLAIN 功能將被禁用。
您可以建立專案目錄中的 .sql-tap.yaml 檔案，而非每次呼叫時都傳遞旗標：
sql-tapd 會自動從目前目錄載入 .sql-tap.yaml。使用 -config 指定不同路徑。CLI 旗標會覆蓋組態檔的值。
加入 --http=:8080 以啟動基於瀏覽器的檢視器：
在瀏覽器中開啟 http://localhost:8080 以即時檢視查詢。網頁 UI 支援：
<addr> 是 sql-tapd 的 gRPC 位址（例如 localhost:9091）。
執行 sql-tap -ci 以在您的測試套件中偵測 N+1 和慢速查詢。它會連接到正在運行的 sql-tapd（參見快速入門設定），收集事件，並在發現任何問題時以代碼 1 退出。
在列表檢視中按下 f 進入篩選模式。篩選器支援結構化條件，超越簡單的文字搜尋。
多個 token 以空格分隔並以 AND 邏輯組合：
這僅顯示執行時間超過 100ms 的 SELECT 查詢。
/（文字搜尋）和 f（篩選）可以同時啟用 — 篩選器會先套用，然後文字搜尋進一步縮小結果範圍。
sql-tap 會自動偵測 N+1 查詢模式 — 當在短時間窗口內執行相同的 SELECT 模板多次時。
偵測預設啟用，並在伺服器端運行，因此 TUI 和 Web UI 都能受益：
僅監控 SELECT 查詢。INSERT、UPDATE、DELETE 和交易生命週期命令（BEGIN、COMMIT 等）被排除。元數據查詢 — 沒有 FROM 子句的 SELECT 語句，例如 SELECT database()、SELECT @@version 或 SELECT 1 — 也被排除，因為它們通常是驅動程式健康檢查或系統內省調用，而非應用程式資料查詢。
一旦超過閾值，同一模板在該窗口內的後續所有執行都會被標記。冷卻期僅影響通知頻率 — Status 欄位的標記始終出現。
由於 Bubble Tea v1 使用的終端機輸入解析器存在限制，多位元組跳脫序列（例如方向鍵：ESC [ A/B/C/D）有時會在作業系統層級的 read() 調用之間分割。發生這種情況時，剩餘的位元組（[A、[B、[C、[D、[F、[H）會以垃圾文字的形式出現在輸入欄位中。
sql-tap 包含一個解決方案，可偵測並捨棄這些分割的序列。作為副作用，字面上的兩個字元字串 [A、[B、[C、[D、[F 和 [H 無法在搜尋或篩選輸入中鍵入。這不太可能影響實際使用，因為這些模式很少出現在 SQL 查詢中。
sql-tapd 會解析資料庫線路協定（PostgreSQL、MySQL 或 TiDB）以透明地攔截查詢。它會追蹤準備好的語句、參數綁定、交易、執行時間、受影響的行數和錯誤。事件透過 gRPC 串流傳輸到連接的 TUI 用戶端。
使用 TUI 即時監控 SQL 流量