pgpulse

Real-time PostgreSQL monitoring in the terminal — like top / htop, for your database.

Built with Node.js, pg, and neo-blessed. Polls system views on an interval, tracks pg_stat_statements deltas in a short ring buffer for a rolling “last ~10s” window.

What it shows

Live sessions — pg_stat_activity (duration, state, truncated query, waits)
Top statements — pg_stat_statements when the extension is installed
Locks / blocking — blocked vs blocking backends
Tables & indexes — high sequential scans; unused index candidates
Table analysis — press t for per-table heap/cache stats and index list
Footer — PostgreSQL-side buffer cache hit ratio, sessions vs max_connections, key memory settings, checkpoint hint (PG17 uses pg_stat_checkpointer)

TUI layout (ASCII)

┌─ live queries (pg_stat_activity) ─┐┌─ top queries ─────────────────────┐
│ pid user duration state query …     ││ calls / total / mean / query …    │
└─────────────────────────────────────┘└───────────────────────────────────┘
┌─ locks / blocking ──────────────────────────────────────────────────────────┐
│ blocked_pid ← blocking_pid  wait …                                          │
└─────────────────────────────────────────────────────────────────────────────┘
┌─ tables / indexes (summary strip) ────────────────────────────────────────┘
footer: shortcuts + pg server metrics (cache hit %, conns, shared_buffers, …)

Requirements & install

Node.js 18+ and PostgreSQL 10+ — see PostgreSQL version compatibility for per-version SQL behavior.

Install globally so pgpulse is on your PATH:

npm i -g pgpulse
pgpulse

From a clone: npm install then npm start (see README).

Optional: better-sqlite3 for --sqlite snapshot history (native build).

PostgreSQL version compatibility

Supported: PostgreSQL 10+ (earlier releases untested). On connect, pgpulse reads server_version_num and chooses SQL accordingly.

Area	Behavior
`pg_stat_activity.backend_type`	Included on PG 10+ only; omitted on older servers.
`pg_stat_statements`	PG 13+: `total_exec_time` / `mean_exec_time`. PG 12 and older: `total_time` / `mean_time` (shown in the UI with the same labels). Extension must be installed.
Footer checkpoint hint	PG 16 and older: `pg_stat_bgwriter`. PG 17+: `pg_stat_checkpointer`.

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Run on the target database for the Top queries panel.

Connection

Precedence: DATABASE_URL → --connection-string → PG* env + CLI flags.

DATABASE_URL=postgres://user:pass@localhost:5432/db pgpulse
pgpulse --host localhost --port 5432 --user postgres --database app

CLI options

Flag	Description
`--interval <ms>`	Poll interval (default 2000)
`--long-threshold <s>`	Highlight “long” queries (default 5)
`--export <file>`	Default path for JSON export (`e`)
`--sqlite <file>`	Optional local snapshot DB
`-h`, `--help`	Help

Keyboard

Key	Action
`q`	Quit
`Tab`	Focus panels
`r`	Reset delta / 10s window
`s`	Cycle sort (statements)
`d`	Cumulative vs Δ10s window
`/`	Filter (Enter apply, Esc cancel)
`l` / `i`	Locked backends / idle in transaction only
`t`	Table analysis browser + detail
`x` / `k`	EXPLAIN / terminate backend (with confirm)
`e`	Export JSON

Footer: PostgreSQL metrics

The second footer line is built from SQL-visible stats: buffer cache hit ratio from pg_stat_database, session count vs max_connections, shared_buffers / work_mem from pg_settings, deadlocks, temp files, and checkpoint pressure. This is not the host OS CPU% or total RAM of the database machine — only what PostgreSQL exposes through catalogs.

PostgreSQL 17+ uses pg_stat_checkpointer instead of pg_stat_bgwriter.

Architecture

src/
  collectors/     activity, statements, locks, tables, indexes, pgServerStats
  engine/         snapshot.js, delta.js (statement deltas + 10s ring)
  ui/             layout.js, panels/
  utils/          sql.js, format.js, version.js, pgServerMetrics.js
  index.js        CLI entry

See the repository README.md for development (Vitest) and security notes.