pgweather

A terminal-based PostgreSQL monitoring tool where database health is visualized as weather over a persistent landscape.

Database load, lock contention, and query performance are mapped to weather conditions (sunny through hurricane), with live animated scenes rendered directly in your terminal.

Quick Start

go build -o pgweather .
./pgweather "postgresql://user:pass@localhost:5432/mydb"

Run without a database:

./pgweather --demo

Requirements

• Go 1.26+
• Terminal with true-color (24-bit) support
• Minimum terminal size: 40x15

Weather Map

Condition	Meaning
Sunny	All systems healthy
Cloudy	Elevated load
Overcast	Sustained pressure
Rain	Active issues
Storm	Major incident
Fog	High dead tuple ratio
Hurricane	Catastrophic failure

Key Bindings

Key	Action
n	Next weather condition
p	Previous weather condition
q / Ctrl+C	Quit

Metrics Tracked

• Cache hit rate (from pg_statio_user_tables)
• Active connections vs max connections
• Lock waits
• Dead tuple ratio
• Longest running query duration

Building & Testing

make build    # build binary
make test     # run tests
make vet      # run go vet

Architecture

main.go                 Entry point, CLI args
internal/db/            PostgreSQL connection + metric queries
internal/metrics/       Metric struct + thresholds
internal/weather/       Metrics-to-condition mapping
internal/ui/            BubbleTea event loop
internal/render/        Scene rendering, palettes, transitions

The rendering engine uses a fixed-width ASCII art landscape (120 columns) with procedural tree generation, animated cloud drift, rain, lightning, fog bands, and condition-reactive cabin and lake elements.