sql‑tap: Vigilancia SQL en tiempo real con TUI y Web UI

En aplicaciones modernas, las interacciones con la base de datos son el latido del sistema, pero rara vez son visibles de forma legible. sql‑tap llena ese vacío al ubicarse como un proxy transparente entre su aplicación y la base de datos, capturando cada consulta y exponiéndola a través de una interfaz de terminal interactiva (TUI) o un panel basado en navegador.

Nota del autor: sql‑tap fue creado en Go, con licencia MIT, y cuenta con más de 900 estrellas en GitHub. Soporta PostgreSQL, MySQL y TiDB, lo que lo hace ideal para entornos con múltiples proveedores.

Por qué sql‑tap?

• Sin cambios de código – Su aplicación habla con el proxy en lugar de la base de datos.
• Visibilidad en tiempo real – Cada sentencia, transacción y error aparece en su pantalla.
• Análisis incorporado – Detección N+1, EXPLAIN, filtrado de consultas y funciones de exportación.
• UI amigable para desarrolladores – TUI impulsado por Bubble Tea y una ligera UI web basada en SSE.
• Extensible – Escrito en Go; agregue nuevos controladores o integraciones a través de una arquitectura de plugins sencilla.

Características en un vistazo

Opciones de instalación

Homebrew (macOS & Linux)

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

Instalar con Go

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

Docker (PostgreSQL / MySQL / TiDB)

# Ejemplo con 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"]

Reemplace postgres por mysql o tidb y ajuste los puertos en consecuencia.

Compilar desde el código fuente

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

Ejecutar el Proxy

El componente principal es sql‑tapd, el demonio proxy. Así es un ejemplo rápido para PostgreSQL:

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

Para MySQL:

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

Conectar su aplicación

Redireccione su cliente de base de datos u ORM al puerto de escucha (5433, 3307, etc.). No se requieren cambios de código porque el proxy habla el protocolo nativo.

Cliente TUI (sql-tap)

Abra un nuevo terminal y ejecute:

sql-tap localhost:9091

La interfaz muestra consulta, duración, estado y filas afectadas. Presione Enter para profundizar en una consulta, ejecute x para un EXPLAIN, o c para copiar.

Panel Web

Si desea ver las consultas en un navegador, añada --http=:8080 al iniciar sql-tapd:

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

Detección de N+1

Muchas aplicaciones emiten inadvertidamente N+1 selects. sql‑tap monitorea plantillas (consultas parametrizadas) y señala cualquier plantilla ejecutada más de 5 veces en 1 s por defecto.

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

El TUI muestra un mensaje emergente en la primera detección y resalta las consultas posteriores. La UI web muestra un mensaje emergente y el fondo amarillo de la fila, con un marcador N+1 en la columna Estado.

Puede desactivar la detección estableciendo el umbral a 0:

sql-tapd --nplus1-threshold=0

Uso avanzado

• Soporte EXPLAIN – Establezca la variable de entorno DATABASE_URL (o la definida por -dsn-env) para habilitar planes de explicación. Sin ella, el proxy sigue capturando consultas pero desactiva EXPLAIN.
• Exportar – Presione w (TUI) o haga clic en el botón Exportar para guardar el registro de consultas en JSON o Markdown.
• Extender controladores – La base de código Go es modular; puede agregar soporte para nuevos controladores de bases de datos siguiendo los patrones existentes.

Por qué sql‑tap es un cambio de juego

• Diagnóstico rápido – Identifique consultas lentas o problemas de transacción instantáneamente.
• No intrusivo – Sin instrumentación ni cambios en el registro.
• Cross‑Database – Funciona de forma consistente entre PostgreSQL, MySQL y TiDB.
• UI amigable – TUI impulsado por teclado + una UI web clara.
• Código abierto – Licencia MIT, soporte comunitario y mantenimiento activo.

Empezar

1. Instale sql‑tapd vía Homebrew, Go, Docker o fuente.
2. Ejecute el proxy con sus credenciales de base de datos.
3. Redireccione su aplicación al puerto del proxy.
4. Inicie sql-tap o abra la UI web.
5. Use filtros, detección N+1 o EXPLAIN para indagar las consultas problemáticas.

Conclusión

sql‑tap combina la simplicidad con funcionalidades potentes, convirtiendo el tráfico de su base de datos en un flujo en vivo navegable. Ya sea que esté depurando un cuello de botella de rendimiento, verificando la aislación de transacciones o simplemente curioso acerca del SQL que emite su aplicación, sql‑tap le brinda la visibilidad que necesita. Pruébelo—su base de datos y su equipo le lo agradecerán.

¡Feliz monitoreo!