Skip to content

README.md

Latest commit

 

History

History
331 lines (251 loc) · 11.9 KB

README.md

File metadata and controls

331 lines (251 loc) · 11.9 KB
        ██████╗  ██████╗     ██████╗ ██╗     ██╗███╗   ███╗██████╗ ███████╗███████╗
        ██╔══██╗██╔════╝    ██╔════╝ ██║     ██║████╗ ████║██╔══██╗██╔════╝██╔════╝
        ██████╔╝██║  ███╗   ██║  ███╗██║     ██║██╔████╔██║██████╔╝███████╗█████╗
        ██╔═══╝ ██║   ██║   ██║   ██║██║     ██║██║╚██╔╝██║██╔═══╝ ╚════██║██╔══╝
        ██║     ╚██████╔╝   ╚██████╔╝███████╗██║██║ ╚═╝ ██║██║     ███████║███████╗
        ╚═╝      ╚═════╝     ╚═════╝ ╚══════╝╚═╝╚═╝     ╚═╝╚═╝     ╚══════╝╚══════╝

                        Real-time PostgreSQL monitoring in your terminal

CI Coverage Quality Gate Security Crates.io Downloads License Rust

Install • Features • Usage • Keys • Replay

Note: This project is under active development. You may encounter bugs or unexpected behavior. If you find any issues, please open an issue.

A blazing-fast TUI for PostgreSQL. Monitor active queries, connections, locks, cache performance, replication lag, vacuum progress, and more — all from your terminal. Built with Rust and ratatui.

pg_glimpse demo

Install

Homebrew (macOS/Linux):

brew install dlt/tap/pg_glimpse

Scoop (Windows):

scoop bucket add dlt https://github.com/dlt/scoop-bucket
scoop install pg_glimpse

Cargo (any platform with Rust 1.74+):

cargo install pg_glimpse

Binary: grab a prebuilt binary from Releases.

Features

Panels

Key Panel What you see
— Queries Active queries with PID, user, state, duration, wait events
Tab Blocking Lock blocking chains — who's waiting on whom
w Wait Events What backends are waiting on
t Table Stats Dead tuples, bloat, sizes, last vacuum
R Replication Streaming replica lag (write/flush/replay)
v Vacuum Live vacuum progress with phase
x Wraparound XID age and wraparound risk
I Indexes Scan counts, tuple reads, sizes
S Statements pg_stat_statements metrics
A WAL & I/O WAL rate, checkpoints, archiver stats (PG14+)

Live Graphs

Sparkline graphs tracking:

  • Connections
  • Average query time
  • Cache hit ratio
  • Active queries
  • Lock count
  • TPS (transactions per second)
  • WAL write rate

Stats Overview

Server version, uptime, database size, connection usage, cache hit ratio, dead tuples, wraparound status, replication lag, checkpoint stats, TPS, WAL rate, blocks read/sec, oldest transaction age, autovacuum workers.

More

  • Inspect overlay — press Enter to see full query details, index definitions, or statement stats
  • Fuzzy filter — press / to filter with match highlighting
  • Clipboard — press y to yank SQL to clipboard
  • SQL highlighting — syntax-highlighted queries everywhere
  • Themes — Tokyo Night, Dracula, Nord, Solarized, Catppuccin
  • Recordings browser — press L to browse and replay past sessions
  • Zen mode — press z to collapse graphs and maximize panel space

Usage

# Connect with parameters
pg_glimpse -H localhost -p 5432 -d mydb -U postgres

# Connection string
pg_glimpse -c "host=localhost port=5432 dbname=mydb user=postgres"

# PostgreSQL URI
pg_glimpse -c "postgresql://user:pass@host:5432/dbname"

# Use service file (~/.pg_service.conf)
pg_glimpse --service=production

# Custom refresh interval
pg_glimpse -r 1 --history-length 240

Options

Flag Description Default
--service PostgreSQL service name from ~/.pg_service.conf —
-c, --connection Connection string (overrides service) —
-H, --host PostgreSQL host localhost
-p, --port PostgreSQL port 5432
-d, --dbname Database name postgres
-U, --user Database user postgres
-W, --password Database password —
-r, --refresh Refresh interval (seconds) 2
--history-length Sparkline data points 120
--ssl Enable SSL/TLS connection —
--ssl-insecure SSL without cert verification (RDS/Aurora) —
--ssl-cert Client certificate file for mutual TLS —
--ssl-key Client private key file for mutual TLS —
--ssl-root-cert CA root certificate for server verification —
--replay Replay a recorded session —

Environment Variables

PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD, PGSERVICE, PG_GLIMPSE_CONNECTION, PGSSLCERT, PGSSLKEY, PGSSLROOTCERT

PostgreSQL Service File

Store connection parameters in ~/.pg_service.conf to avoid passing credentials on the command line:

[production]
host=prod.db.example.com
port=5432
dbname=myapp
user=readonly
password=secretpassword

[staging]
host=staging.db.example.com
port=5432
dbname=myapp
user=app_user
password=another_secret

Then connect with:

pg_glimpse --service=production

Individual CLI parameters override service file values if both are provided.

Client Certificate Authentication (Mutual TLS)

PostgreSQL supports client certificate authentication for enhanced security. To use mutual TLS:

# Specify certificate files explicitly
pg_glimpse -H myserver.example.com -d mydb -U user -W password \
  --ssl \
  --ssl-cert ~/.postgresql/postgresql.crt \
  --ssl-key ~/.postgresql/postgresql.key \
  --ssl-root-cert ~/.postgresql/root.crt

# Or use environment variables
export PGSSLCERT=~/.postgresql/postgresql.crt
export PGSSLKEY=~/.postgresql/postgresql.key
export PGSSLROOTCERT=~/.postgresql/root.crt
pg_glimpse --ssl -H myserver.example.com -d mydb -U user -W password

Service file with certificates:

[secure-prod]
host=prod.db.example.com
port=5432
dbname=myapp
user=app_user
password=secretpassword
sslcert=/path/to/client.crt
sslkey=/path/to/client.key
sslrootcert=/path/to/ca.crt

Default paths: If certificates exist in ~/.postgresql/ directory, they'll be auto-detected:

  • ~/.postgresql/postgresql.crt (client certificate)
  • ~/.postgresql/postgresql.key (client private key)
  • ~/.postgresql/root.crt (CA certificate)

Important notes:

  • Client certificate authentication requires both password AND certificate
  • Private key files should have mode 0600 (readable only by owner)
  • Use --ssl for verified TLS or --ssl-insecure for self-signed server certificates

Keyboard Reference

Global

Key Action
q / Ctrl+C Quit
Esc Back to Queries / Quit
p Pause / resume
r Force refresh
? Help
, Configuration
z Zen mode (collapse graphs)
L Recordings browser
y Yank to clipboard
/ Fuzzy filter

Navigation

Key Action
↑ / k Previous row
↓ / j Next row
Enter Inspect
s Cycle sort column
b Refresh bloat estimates
X Reset pg_stat_statements
C Cancel query (batch if filtered)
K Terminate backend (batch if filtered)

Recording & Replay

Every live session is automatically recorded to ~/.local/share/pg_glimpse/recordings/ (configurable). This is useful for:

  • Incident investigation — review what happened during an outage
  • Sharing with teammates — send a recording file for async debugging
  • Post-mortem analysis — step through events at your own pace

How it works

  • Recordings are saved as JSONL files named host_port_YYYYMMDD_HHMMSS.jsonl
  • Each snapshot (every refresh interval) is captured with all panel data
  • Old recordings are automatically cleaned up based on retention setting (default: 1 hour)

Browse recordings

Press L during a live session to open the recordings browser. Navigate with ↑/↓, press Enter to replay, or d to delete a recording.

Replay a session

From the browser, or via command line:

pg_glimpse --replay ~/.local/share/pg_glimpse/recordings/localhost_5432_20260205_143022.jsonl

Recordings auto-play when opened. All panels, sorting, filtering, and inspection work identically in replay mode. Actions that modify the database (Cancel/Kill) are disabled. Press q to exit replay and return to live monitoring.

Replay controls

Key Action
Space Play / pause
← / h Step back one snapshot
→ / l Step forward one snapshot
< / > Adjust playback speed (0.25x – 8x)
g / G Jump to start / end

Configuration

Press , to open settings. Saved to ~/.config/pg_glimpse/config.toml.

Setting Options
Graph Marker Braille / HalfBlock / Block
Color Theme Tokyo Night / Dracula / Nord / Solarized / Catppuccin
Refresh Interval 1–60s
Warn Duration 0.1s+
Danger Duration warn threshold – 300s
Recording Retention 10m – 24h
Recordings Dir Custom path (default: ~/.local/share/pg_glimpse/recordings/)

Extension Support

Automatically detects and integrates with:

  • pg_stat_statements — query-level stats (powers the Statements panel)

Detected (shown as indicators in stats panel):

  • pg_buffercache — buffer cache inspection
  • pg_stat_kcache — OS-level CPU/disk stats
  • pg_wait_sampling — wait event profiling

Troubleshooting

Password with special characters

If your password contains special characters (!, $, ", etc.), the shell may interpret them before pg_glimpse receives them. Use the PGPASSWORD environment variable with single quotes:

PGPASSWORD='my!pass$word' pg_glimpse -H myhost -d mydb -U myuser

SSL connection to RDS/Aurora

Cloud-hosted PostgreSQL typically requires SSL but uses certificates not in your system trust store. Use --ssl-insecure:

pg_glimpse --ssl-insecure -H myinstance.rds.amazonaws.com -d mydb -U myuser

FAQ

Did you build it or did Claude?

Yes.

License

MIT