██████╗  ██████╗     ██████╗ ██╗     ██╗███╗   ███╗██████╗ ███████╗███████╗
        ██╔══██╗██╔════╝    ██╔════╝ ██║     ██║████╗ ████║██╔══██╗██╔════╝██╔════╝
        ██████╔╝██║  ███╗   ██║  ███╗██║     ██║██╔████╔██║██████╔╝███████╗█████╗
        ██╔═══╝ ██║   ██║   ██║   ██║██║     ██║██║╚██╔╝██║██╔═══╝ ╚════██║██╔══╝
        ██║     ╚██████╔╝   ╚██████╔╝███████╗██║██║ ╚═╝ ██║██║     ███████║███████╗
        ╚═╝      ╚═════╝     ╚═════╝ ╚══════╝╚═╝╚═╝     ╚═╝╚═╝     ╚══════╝╚══════╝

                        Real-time PostgreSQL monitoring in your terminal

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.

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