MyntDev_
Iniciar Proyecto

sql-tap: Visualización de tráfico SQL en tiempo real - Análisis completo

16/2/2026 9 min de lectura Por Nicolas - MyntDev Actualizado: 16/2/2026

Descubre sql-tap: la herramienta revolucionaria que intercepta y visualiza consultas SQL en tiempo real mediante TUI. Arquitectura, características, casos de uso y comparación con alternativas tradicionales.

Interfaz TUI de sql-tap mostrando consultas SQL en tiempo real con panel de analytics y explain plan
  • Base de datos
  • PostgreSQL
  • MySQL
  • Herramientas de desarrollo
  • Go
  • Open Source
Índice de contenido

El problema: debugging de bases de datos en tiempo real

El 14 de febrero de 2026, Tetsuro Mikami (mickamy) liberó sql-tap en GitHub. En menos de 48 horas, el proyecto alcanzó 768 estrellas. ¿Por qué? Porque resolvía un problema que todo desarrollador de backend enfrenta pero nadie había resuelto bien: ¿cómo ver exactamente qué queries está ejecutando tu aplicación en tiempo real, sin modificar código ni configurar logging complejo?

Las soluciones tradicionales tenían tradeoffs significativos:

  • Slow query log: útil pero reactivo, solo muestra queries que ya terminaron
  • Logging en aplicación: requiere modificar código, agregar dependencias, y genera spam en logs
  • pg_stat_statements: excelente para agregación, pero no muestra queries en tiempo real ni contexto de transacción
  • Tcpdump/Wireshark: técnico, difícil de filtrar, no entiende el protocolo SQL

sql-tap tomó un enfoque diferente: un proxy transparente con una interfaz TUI hermosa y práctica.

Arquitectura: Proxy + Wire Protocol Parsing

sql-tap consta de dos componentes:

sql-tapd: El proxy daemon

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

El daemon se posiciona entre tu aplicación y la base de datos:

# PostgreSQL: proxy en :5433 → database en :5432
DATABASE_URL="postgres://user:pass@localhost:5432/db?sslmode=disable" \
  sql-tapd --driver=postgres --listen=:5433 --upstream=localhost:5432

# MySQL: proxy en :3307 → database en :3306
DATABASE_URL="user:pass@tcp(localhost:3306)/db" \
  sql-tapd --driver=mysql --listen=:3307 --upstream=localhost:3306

Lo clave: habla el wire protocol nativo. Tu aplicación cree que está hablando directamente con PostgreSQL o MySQL. No hay traducción ni modificación de queries.

Captura de información

El proxy parsea el wire protocol para extraer:

  • Queries completas: incluyendo prepared statements y parameter bindings
  • Transacciones: agrupa queries por transacción automáticamente
  • Métricas: tiempo de ejecución, filas afectadas, errores
  • Contexto: stack trace de la aplicación (cuando está disponible)

Los eventos se transmiten en tiempo real vía gRPC a clientes conectados (puedes tener múltiples TUI conectadas al mismo proxy).

Cliente TUI: Interfaz práctica y poderosa

Una vez iniciado el proxy, conectas la TUI:

sql-tap localhost:9091

La interfaz tiene cuatro vistas principales:

Lista de queries (List View)

Muestra todas las queries en tiempo real con atajos:

  • j/k o ↓/↑: navegación
  • /: búsqueda incremental
  • s: toggle sort cronológico/duración
  • Enter: inspeccionar query
  • Space: expandir/colapsar transacción
  • x: EXPLAIN
  • X: EXPLAIN ANALYZE
  • e/E: editar query antes de EXPLAIN
  • a: analytics view
  • c/C: copiar query (con o sin bound args)

Inspector de query

Detalles completos de una query específica:

  • SQL completo con syntax highlighting
  • Parámetros bindeados
  • Tiempo de ejecución
  • Filas afectadas
  • Contexto de error (si falló)
  • Plan de ejecución (si ejecutaste EXPLAIN)

Analytics view

Agregaciones estadísticas:

  • Queries más frecuentes
  • Queries más lentas
  • Distribución de tiempos
  • Sorteable por total/count/average

Explain view

Visualización de planes de ejecución con scroll horizontal y vertical, soporte para EXPLAIN y EXPLAIN ANALYZE.

Características únicas

1. Transparencia total

A diferencia de soluciones que requieren instrumentación (ORM logging, middleware), sql-tap no sabe ni le importa tu stack. Node.js, Python, Ruby, Java, Go — funciona con cualquier lenguaje que use el driver estándar de PostgreSQL o MySQL.

2. Soporte para prepared statements

Las herramientas de logging tradicionales suelen mostrar SELECT * FROM users WHERE id = $1 sin los valores. sql-tap captura tanto el statement preparado como los parámetros bindeados, mostrando la query completa y reproducible.

3. Agrupación por transacción

Las queries dentro de una transacción se agrupan visualmente. Puedes expandir/colapsar transacciones con Space para ver el contexto completo. Esto es crítico para debugging de race conditions o deadlocks.

4. EXPLAIN interactivo

Presiona x para ejecutar EXPLAIN en la base de datos upstream directamente desde la TUI. Presiona X para EXPLAIN ANALYZE (ejecuta realmente la query y muestra métricas). Presiona e para editar la query antes de explicarla útil para probar variantes.

Para que funcione, configura DATABASE_URL con credenciales válidas:

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

5. Multiplataforma

Binarios disponibles para:

  • macOS (amd64, arm64)
  • Linux (amd64, arm64)
  • Windows (vía Go install)

También disponible vía Homebrew y Docker.

Casos de uso prácticos

Debugging de N+1 queries

El problema clásico: tu aplicación hace 1 query para traer 100 usuarios, y luego 100 queries más para traer sus profiles. Con sql-tap:

  1. Inicia el proxy
  2. Ejecuta la operación problemática
  3. Presiona a para analytics view
  4. Ordena por count
  5. Las queries repetidas aparecen inmediatamente

Análisis de queries lentas

En desarrollo local:

  1. Conecta la TUI
  2. Ejecuta la página que está lenta
  3. Presiona s para ordenar por duración
  4. Presiona X en la query más lenta para EXPLAIN ANALYZE
  5. Identifica missing indexes o joins ineficientes

Debugging de prepared statements

Las herramientas tradicionales muestran:

SELECT * FROM users WHERE email = $1

sql-tap muestra:

SELECT * FROM users WHERE email = '[email protected]'

Crítico para reproducir problemas específicos.

Understanding queries en legacy code

Tomaste un proyecto heredado y no entiendes qué hace. Con sql-tap:

  1. Inicia el proxy
  2. Navega la aplicación
  3. Observa las queries que se ejecutan
  4. Entiende el comportamiento sin leer 10,000 líneas de código

Especificaciones técnicas

Stack tecnológico

  • Lenguaje: Go (131,478 líneas de código Go)
  • Licencia: MIT
  • Versión actual: v0.0.9 (15 de febrero de 2026)
  • Autor: Tetsuro Mikami (mickamy)
  • Comunidad: 768 GitHub stars, 17 forks

Bases de datos soportadas

  • PostgreSQL: versión 18-alpine en Docker, versiones recientes en bare metal
  • MySQL: versión 8+, soporte para MySQL 9.x con fixes para CLIENT_QUERY_ATTRIBUTES
  • TiDB: soportado desde v0.0.9 con --driver=tidb

Protocolos soportados

  • PostgreSQL wire protocol: parse completo de messages, including Parse, Bind, Execute, Sync
  • MySQL wire protocol: parse de COM_QUERY, con soporte para attributes de MySQL 9
  • Compression: soporte para zlib y zstd (stripeado en handshake para prevenir broken connections)

Comunicación

  • gRPC: comunicación entre proxy y TUI
  • Default port: 9091 (configurable con --grpc)

Instalación

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

Build from source

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

Docker

PostgreSQL

FROM postgres:18-alpine
ARG SQL_TAP_VERSION=0.0.9
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"]

MySQL

FROM mysql:8
ARG SQL_TAP_VERSION=0.0.9
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=mysql", "--listen=:3307", "--upstream=localhost:3306", "--grpc=:9091"]

Limitaciones y consideraciones

Latencia

El proxy añade latencia. En development/desconecta el proxy y conecta directamente a la base de datos.

Uso de recursos

El proxy consume CPU y memoria para parsear el wire protocol. En alta carga, puede ser significativo. Monitorea el uso de recursos del daemon sql-tapd.

Compatibilidad con protocolos comprimidos

La versión 0.0.9 corrigió soporte para protocolo comprimido (zlib/zstd) en MySQL, pero requiere testing extensivo en producción. El fix (commit d64140d5, 15 de febrero de 2026) stripea las capacidades de compresión en el handshake para prevenir conexiones rotas.

UTF-8 encoding

El commit 49cfb91b (15 de febrero de 2026) añadió sanitización de UTF-8 inválido en respuestas gRPC, previniendo crashes cuando el database retorna datos no-UTF-8 válidos (binarios, encoding incorrecto).

EXPLAIN requiere credenciales

Sin DATABASE_URL configurada, el proxy captura queries pero EXPLAIN está deshabilitado. Necesitas credenciales válidas para usar esta funcionalidad.

Roadmap y desarrollo activo

El proyecto es extremadamente activo. Creado el 14 de febrero de 2026, en 48 horas tuvo:

  • 4 issues cerradas: incluyendo bugs críticos para MySQL 9 y compresión
  • 9 releases: desde v0.0.1 hasta v0.0.9
  • 67 commits: todos por mickamy (proyecto solitario actualmente)

Fixes recientes

  1. v0.0.9 (15 de febrero): sanitización de UTF-8, fix para MySQL 9 CLIENT_QUERY_ATTRIBUTES, soporte para TiDB
  2. v0.0.8: fix para protocolo comprimido en MySQL
  3. v0.0.7: mejoras en analytics view

Issues cerrados recientes

  • Issue #4: Error gRPC con UTF-8 inválido — cerrado en v0.0.9
  • Issue #3: EXPLAIN falla con MySQL 9.6.0 debido a CLIENT_QUERY_ATTRIBUTES — cerrado en v0.0.9
  • Issue #2: Soporte para protocolo comprimido — cerrado en v0.0.8
  • Issue #1: Primer feature request — cerrado

Comparación con alternativas

vs. Slow query log

Slow query log:

  • ✅ Nativo, sin dependencias
  • ✅ Configurable por threshold
  • ❌ Solo queries lentas, no todas
  • ❌ Reactivo, no en tiempo real
  • ❌ No agrupa por transacción

sql-tap:

  • ✅ Todas las queries en tiempo real
  • ✅ Agrupa por transacción
  • ✅ UI interactiva
  • ❌ Requiere proxy adicional
  • ❌ Latencia añadida

Veredicto: Complementarios. Usa slow query log en producción, sql-tap en desarrollo.

vs. pg_stat_statements

pg_stat_statements:

  • ✅ Nativo de PostgreSQL
  • ✅ Agregaciones estadísticas potentes
  • ✅ Overhead mínimo
  • ❌ No muestra queries en tiempo real
  • ❌ No muestra contexto de aplicación
  • ❌ Solo PostgreSQL

sql-tap:

  • ✅ Tiempo real
  • ✅ Contexto completo
  • ✅ Multi-database (PostgreSQL, MySQL, TiDB)
  • ❌ Overhead de proxy
  • ❌ No agrupaciones estadísticas (aunque analytics view ayuda)

Veredicto: pg_stat_statements para tendencias a largo plazo, sql-tap para debugging interactivo.

vs. Logging en aplicación

ORM/driver logging:

  • ✅ Sin infra adicional
  • ✅ Contexto de aplicación incluido
  • ❌ Contamina logs
  • ❌ Requiere modificar código
  • ❌ Diffícil de filtrar/buscar

sql-tap:

  • ✅ Sin modificación de código
  • ✅ UI dedicada con filtros
  • ✅ No contamina logs
  • ❌ Infraestructura adicional
  • ❌ Overhead de proxy

Veredicto: sql-tap es superior para debugging temporal. Logging es mejor para tracing permanente.

vs. Tcpdump/Wireshark

Tcpdump/Wireshark:

  • ✅ Captura todo el tráfico
  • ✅ Sin modificación de infra
  • ❌ Muy técnico
  • ❌ No entiende protocolo SQL
  • ❌ Diffícil de filtrar queries específicas

sql-tap:

  • ✕ Entiende wire protocol SQL
  • ✕ UI especializada
  • ✕ Filtros por transacción, duración, etc.
  • ❌ Solo tráfico SQL
  • ❌ Requiere proxy

Veredicto: sql-tap es tcpdump especializado para SQL con UX amigable.

Cuándo usar sql-tap

Ideal para:

  • Development local: debugging interactivo de queries
  • Staging: análisis de rendimiento antes de producción
  • Debugging de issues específicos: reproducir queries problemáticas
  • Onboarding a nuevos desarrolladores: entender el comportamiento de queries en legacy code
  • Optimización de queries: identificar N+1, missing indexes, joins ineficientes

No ideal para:

  • Producción de alta carga: el overhead de proxy puede ser significativo
  • Monitoring permanente: herramientas especializadas (Datadog, New Relic) son más apropiadas
  • Ambientes sin acceso a TTY: requiere terminal interactiva
  • Queries extremadamente sensibles: el proxy tiene acceso a todo el tráfico SQL

Conclusión

sql-tap llena un gap importante en el toolkit de desarrolladores backend: una herramienta moderna, interactiva y práctica para debugging de bases de datos en tiempo real. No reemplaza herramientas de monitoring ni logging tradicional, pero complementa el ecosistema de forma única.

El proyecto es joven (creado en febrero de 2026) pero extremadamente activo, con bugs siendo corregidos rápidamente y features siendo añadidas en base a feedback de la comunidad. Con 768 estrellas en 48 horas, es claro que resonó con un dolor real de desarrolladores.

Mi recomendación: agrégalo a tu toolkit de development. Úsalo cuando necesites entender qué está haciendo tu aplicación con la base de datos, debugging de queries lentas, u onboarding a código heredado. Desconéctalo en producción y usa herramientas especializadas para monitoring.

La combinación de arquitectura de proxy transparente + wire protocol parsing + TUI interactiva hace de sql-tap una herramienta que, una vez que la usas, te preguntas cómo vivías sin ella.

Recursos

Preguntas frecuentes

¿Necesitas un equipo de desarrollo para tu empresa?

En Mynt trabajamos como equipo independiente para arquitectura, implementacion y escalado de productos digitales en distintos contextos.

Ingenieria de software Equipo de desarrollo