Elephantshark is a lightweight tool for monitoring, analyzing, and debugging PostgreSQL network traffic. It helps developers and administrators understand how clients, drivers, and ORMs interact with PostgreSQL servers, proxies, and connection pools.
It can also track traffic between standby and primary servers, as well as between subscribers and publishers in replication systems.
GitHub: neondatabase-labs/elephantshark
Features
Elephantshark was designed as a “listening” and analysis tool for Postgres traffic without needing to modify the database or applications. It allows you to:
- Monitor client activity - see which queries are executed, how often, and with what latency.
- Understand driver and ORM behavior - how they open connections, what parameters they use, and what commands they send.
- Troubleshoot connection and pool issues - for example, slow or dropped connections.
- Analyze replication - traffic between primary/standby and publisher/subscriber servers.
- Work non-invasively - the tool doesn’t require any PostgreSQL configuration changes.
Elephantshark can be used as a diagnostic tool when setting up infrastructure, performing migrations, or debugging unstable connections.
Installation
To install Elephantshark, clone the repository and build the binary from source:
git clone https://github.com/neondatabase-labs/elephantshark.git cd elephantshark cargo build --releaseThe compiled binary will be located at
target/release/elephantshark. You can also download prebuilt releases (if available) from GitHub Releases.
Usage examples
Start analyzing traffic on a specific interface or port:
sudo elephantshark --interface eth0 --port 5432Or read a previously saved .pcap file:
elephantshark --file traffic.pcap- Elephantshark automatically recognizes PostgreSQL packets and displays decoded commands, queries, and responses. This allows detailed analysis of how your application communicates with the database.
Why try Elephantshark
- Built specifically for PostgreSQL. Understands the internal Postgres protocol, including extended commands and handshake processes.
- Non-intrusive. Works as a passive sniffer without affecting performance.
- Great for debugging. Helps quickly identify problematic queries, timeouts, or pool connection issues.
- Ideal for DevOps and DBAs. Essential when setting up high-performance and fault-tolerant PostgreSQL systems.
Conclusion
Elephantshark is a “network microscope” for PostgreSQL. It helps you see how your application communicates with the database, find weak points, and improve overall stability. If you manage infrastructure, build database drivers, or simply want to understand PostgreSQL networking more deeply - Elephantshark is an excellent tool to have in your toolkit.
Frequently Asked Questions (FAQ)
- Can I use Elephantshark in production? Yes, but it’s recommended to run it in passive monitoring mode or on traffic copies to avoid impacting active connections.
- Does it require database access? No. Elephantshark only analyzes network traffic and doesn’t require PostgreSQL login credentials.
- What is the performance overhead? Minimal - the tool only listens to packets and doesn’t interfere with transmission.
- Does Elephantshark support SSL connections? No, it can’t decrypt SSL-encrypted traffic, but it works perfectly with unencrypted connections (for example, within a local network).
- Can it be used with pgbouncer or other pools? Yes, Elephantshark recognizes traffic between clients, proxies, pools, and PostgreSQL servers.
