sql‑tap : Surveillance SQL en temps réel avec TUI et interface Web

Dans les applications modernes, les interactions avec la base de données constituent le cœur du système, mais sont rarement visibles sous forme lisible. sql‑tap comble ce vide en agissant comme un proxy transparent entre votre application et la base de données, capturant chaque requête et l’exposant via une interface terminal interactive (TUI) ou un tableau de bord basé sur le navigateur.

Remarque de l’auteur : sql‑tap a été créé en Go, sous licence MIT, et compte plus de 900 étoiles GitHub. Il prend en charge PostgreSQL, MySQL et TiDB, ce qui le rend idéal pour les environnements multi‑vendeurs.

Pourquoi sql‑tap ?

• Aucun changement de code : votre application communique avec le proxy au lieu de la base de données.
• Visibilité en temps réel : chaque instruction, transaction et erreur afflue sur votre écran.
• Analyses intégrées : détection N+1, EXPLAIN, filtrage des requêtes et fonctions d’exportation.
• Interface conviviale pour les développeurs : TUI pilotée par le clavier alimentée par Bubble Tea et une interface web légère basée sur SSE.
• Extensible : écrite en Go ; ajoutez de nouveaux pilotes ou intégrations via une architecture de plug‑in simple.

Fonctionnalités en un coup d’œil

Options d’installation

Homebrew (macOS & Linux)

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

Installation Go

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

Docker (PostgreSQL / MySQL / TiDB)

# Exemple 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"]

Remplacez postgres par mysql ou tidb et ajustez les ports en conséquence.

Construire à partir du code source

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

Lancement du proxy

Le composant principal est sql‑tapd, le démon proxy. Voici un exemple rapide pour PostgreSQL :

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

Pour MySQL :

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

Connecter votre application

Pointez votre client de base de données ou ORM vers le port d'écoute (5433, 3307, etc.). Aucun changement de code n'est requis car le proxy parle le protocole natif.

Client TUI (sql-tap)

Ouvrez un nouveau terminal et exécutez :

sql-tap localhost:9091

Ceci lance une interface pilotée par le clavier. Les raccourcis clavier sont documentés dans le dépôt et incluent :

L'interface affiche requête, durée, statut, et lignes affectées. Appuyez sur Entrée pour approfondir une requête, exécutez x pour un EXPLAIN ou c pour copier.

Tableau de bord Web

Si vous souhaitez voir les requêtes dans un navigateur, ajoutez --http=:8080 lors du lancement de sql-tapd :

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

Ouvrez http://localhost:8080 pour visualiser les journaux en temps réel, filtrer, activer/désactiver la détection N+1 et analyser les plans EXPLAIN. L’interface utilise les événements envoyés par le serveur (SSE) pour le streaming.

Détection de requêtes N+1

De nombreuses applications produisent accidentellement des requêtes N+1. sql‑tap surveille les modèles (requêtes paramétrées) et signale tout modèle exécuté plus de 5 fois en 1 s par défaut.

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

Le TUI affiche une notification toast dès la première détection et souligne les requêtes suivantes. L’interface web affiche une notification toast et un fond jaune sur la ligne, ainsi qu’un indicateur N+1 dans la colonne Statut.

Vous pouvez désactiver la détection en fixant le seuil à 0 :

sql-tapd --nplus1-threshold=0

Utilisation avancée

• Support EXPLAIN : définissez la variable d’environnement DATABASE_URL (ou la variable définie par -dsn-env) pour activer les plans EXPLAIN. Sans cela, le proxy continue à capturer les requêtes mais désactive EXPLAIN.
• Exportation : appuyez sur w (TUI) ou cliquez sur le bouton Export pour enregistrer le journal des requêtes en JSON ou Markdown.
• Extension des pilotes : le code Go est modulaire ; vous pouvez ajouter la prise en charge de nouveaux pilotes de base de données en suivant les modèles existants.

Pourquoi sql‑tap est un véritable changement de jeu

• Diagnostic rapide : repérez immédiatement les requêtes lentes ou les problèmes de transaction.
• Non‑intrusif : aucune instrumentation ni changement de journalisation.
• Cross‑Base de données : fonctionne de façon cohérente sur PostgreSQL, MySQL et TiDB.
• Convivialité pour les développeurs : TUI pilotée par clavier ainsi qu’une interface web claire.
• Open Source : licence MIT, support communautaire, et maintenance active.

Commencer

1. Installez sql-tapd via Homebrew, Go, Docker ou source.
2. Lancez le proxy avec vos identifiants de base de données.
3. Orientez votre application vers le port du proxy.
4. Lancez sql-tap ou ouvrez l’interface web.
5. Utilisez les filtres, la détection N+1 ou EXPLAIN pour approfondir les requêtes problématiques.

Conclusion

sql‑tap combine simplicité et puissance, transformant le trafic de votre base de données en un flux en direct, navigable. Que vous soyez en train de déboguer un goulet d’étranglement de performance, de vérifier l’isolement des transactions, ou simplement curieux de connaître le SQL que votre application émet, sql‑tap vous donne la visibilité dont vous avez besoin. Essayez‑le — votre base de données et votre équipe vous remercieront.

Bonne surveillance !