How do I set up sql-tap with Docker Compose?

Run sql-tap as a sidecar container using the Docker example from the README, which proxies ports like :5433 for PostgreSQL. You'll need to adjust your app's database connection to point to the proxy port instead of the direct database.

sql-tap vs pgBadger for PostgreSQL monitoring?

sql-tap provides real-time, interactive monitoring with a TUI/web UI and requires no log parsing, while pgBadger analyzes PostgreSQL log files for historical reports. sql-tap is better for live debugging, whereas pgBadger suits post-mortem analysis.

Does sql-tap work with cloud databases like Amazon RDS?

Yes, as long as the database uses PostgreSQL, MySQL, or TiDB wire protocols. Point sql-tapd's upstream flag to the RDS endpoint, but note that network latency and security groups might require additional configuration.

How to disable N+1 detection in sql-tap?

Set the '--nplus1-threshold' flag to 0 when starting sql-tapd, as mentioned in the configuration section. This disables server-side detection entirely for all connected clients.

Can sql-tap handle encrypted connections (SSL/TLS)?

The README shows DSN examples with 'sslmode=disable' for PostgreSQL, but it doesn't specify native SSL/TLS support in the proxy. You may need to ensure the proxy handles encryption or run it in trusted networks only.

What's the performance overhead of running sql-tap?

As a proxy, it adds minimal latency from parsing and streaming queries, but the impact depends on query volume and system resources. It's designed for development/CI, not production, where overhead could affect high-load applications.

How to export queries from sql-tap for further analysis?

In the TUI, press 'w' to export queries to JSON or Markdown files, as listed in the keybindings. This allows offline review or integration with other tools, though the web UI doesn't mention export features.

Open-Awesome

sql-tap

MITGov0.3.2

A real-time SQL traffic viewer that proxies database connections to capture and inspect queries via TUI or web UI.

GitHub

1.6k stars49 forks0 contributors

What is sql-tap?

sql-tap is a real-time SQL traffic monitoring tool that acts as a transparent proxy between applications and databases. It captures every query, transaction, and error, displaying them in an interactive terminal or web interface. It solves the problem of debugging and optimizing database interactions without instrumenting application code.

Target Audience

Developers and database administrators who need to debug, profile, or optimize SQL queries in applications using PostgreSQL, MySQL, or TiDB.

Value Proposition

Developers choose sql-tap because it requires no code changes, supports multiple databases natively, offers both TUI and web interfaces, and provides advanced features like N+1 detection, EXPLAIN integration, and CI-friendly reporting.

Overview

Watch SQL traffic in real-time with a TUI

Use Cases

Best For

Debugging N+1 query problems in real-time
Profiling SQL performance during application testing
Monitoring database traffic in development environments
Analyzing query execution plans without database client tools
Integrating SQL observability into CI/CD pipelines
Learning how an application interacts with its database

Not Ideal For

High-throughput production systems where every millisecond of latency is critical
Teams needing monitoring for databases beyond PostgreSQL, MySQL, or TiDB (e.g., SQLite, Oracle)
Environments where deploying and managing a separate proxy daemon adds unacceptable operational overhead
Projects requiring long-term historical analytics or aggregated reporting without real-time focus

Pros & Cons

Pros

Zero-Code Instrumentation

Captures every SQL query in real-time by acting as a transparent proxy, requiring no changes to application code, as emphasized in the philosophy and quick start.

Interactive Dual UIs

Offers both a terminal UI (TUI) with keybindings and a web UI with SSE streaming, providing flexible interfaces for query inspection and visualization, shown in the GIF and screenshot.

Advanced Debugging Features

Supports EXPLAIN, EXPLAIN ANALYZE, N+1 detection with configurable thresholds, and slow query alerts, enabling deep performance analysis directly from the UI.

CI Pipeline Integration

Includes a CI mode that runs during test suites to detect query problems and exit with error codes, making it easy to automate SQL quality checks in development workflows.

Cons

Input Parsing Quirks

Due to a Bubble Tea v1 limitation, arrow key input in search/filter mode can display garbage text, and strings like '[A' cannot be typed, as admitted in the known limitations section.

EXPLAIN Configuration Dependency

Requires setting the DATABASE_URL environment variable for EXPLAIN functionality; without it, query capture works but execution plan analysis is disabled, adding setup friction.

Proxy-Induced Complexity

Introduces an extra network hop and daemon management, which can complicate deployment (e.g., port mapping, sidecar containers) and may add latency unsuitable for performance-critical environments.

Frequently Asked Questions

Related Projects

Prometheus.io

The Prometheus monitoring system and time series database.

Stars65,277

Forks10,678

Last commit11 hours ago

MySQLTuner-perl

MySQLTuner is a script written in Perl that will assist you with your MySQL configuration and make recommendations for increased performance and stability.

Stars9,470

Forks1,291

Last commit2 days ago

innodb-ruby

A parser for InnoDB file formats, in Ruby

Stars1,796

Forks324

Last commit2 months ago

Anemometer

Box SQL Slow Query Monitor

Stars1,393

Forks307

Last commit4 years ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub