pgbouncer-insights

A CLI observability dashboard for PgBouncer. Most PgBouncer tooling is a thin Prometheus exporter and not much else — this gives you both scriptable one-shot output and a live, auto-refreshing terminal dashboard for pool saturation, client/server connections, transaction rate, and query/wait times, without standing up a metrics stack.

Connection credentials are cached locally after the first pgbi connect, so you don't have to re-enter them on every run.

Features

• Live terminal dashboard (pgbi dashboard) — a full-screen, auto-refreshing view built on blessed-contrib: a pools table, a transactions/sec sparkline, gauges for average query and wait time, and a per-database clients/servers summary. Reconnects automatically if the connection drops.
• Scriptable one-shot output (pgbi show <resource>) — any PgBouncer SHOW command as a colored table or raw JSON, for piping into jq, cron jobs, or other scripts.
• Cached connection profiles — save host/port/user/database once, reuse by name. Passwords are never written to disk in plaintext.
• Multiple named profiles — e.g. default, staging, prod, switchable with --profile or a persistent default via pgbi profiles use.

How it works

PgBouncer exposes an admin console as a virtual Postgres database (conventionally named pgbouncer) on the same host and port it listens on for regular traffic. This tool connects to that virtual database with a normal Postgres client and issues SHOW POOLS, SHOW CLIENTS, SHOW SERVERS, SHOW STATS, SHOW DATABASES, SHOW LISTS, and SHOW CONFIG — the same commands you'd run by hand with psql. No extensions, agents, or exporters need to be installed on the PgBouncer host; you only need admin-console credentials (a user listed in PgBouncer's admin_users or stats_users).

Requirements

• Node.js 18 or later
• Network access to a running PgBouncer instance and admin-console credentials for it
• An OS credential store for cached passwords: Windows Credential Manager, macOS Keychain, or a Linux Secret Service provider (e.g. gnome-keyring, kwallet) — most desktop Linux distros have one; headless Linux servers may need one installed

Install

npm install -g pgbouncer-insights

Or run from a local checkout:

npm install
npm run build
npm link

This exposes the pgbi binary on your PATH.

Usage

Connecting and caching credentials

pgbi connect                  # prompts for host, port, admin user, password, admin db
pgbi connect --name staging   # cache a second, named profile
pgbi connect --name staging   # re-run against an existing name to update it

You'll be prompted for:

| Prompt | Default | Notes | | --- | --- | --- | | PgBouncer host | 127.0.0.1 | | | PgBouncer port | 6432 | | | Admin user | pgbouncer | must be listed in PgBouncer's admin_users or stats_users | | Password | — | not echoed to the terminal | | Admin database | pgbouncer | PgBouncer's built-in virtual admin database | | Use TLS? | No | |

The connection is tested (SHOW VERSION) before anything is saved — a bad host, port, or credential fails loudly instead of silently caching junk.

Where things are stored:

• Host/port/user/database/TLS flag → a JSON file in your OS config directory (via the conf package — e.g. %APPDATA%\pgbouncer-insights-nodejs\Config\config.json on Windows, ~/.config/pgbouncer-insights-nodejs/config.json on Linux/macOS).
• Password → your OS credential store (Windows Credential Manager / macOS Keychain / Linux Secret Service), via @napi-rs/keyring. It is never written to the JSON config file or logged.

Managing profiles

pgbi profiles list            # show all saved profiles, marking the default
pgbi profiles use staging     # make "staging" the default profile
pgbi profiles remove staging  # delete the profile and its cached password

Every other command accepts --profile <name> / -p <name>; when omitted, the default profile is used (the first profile you save becomes the default automatically, or set one explicitly with profiles use).

One-shot, scriptable output

pgbi show pools
pgbi show clients --profile staging
pgbi show stats --json | jq '.[0].avg_query_time'

Supported resources: pools, clients, servers, stats, databases, lists, config — these map directly to PgBouncer's SHOW POOLS / SHOW CLIENTS / etc. Add --json for raw JSON instead of a table (numeric fields are coerced from PgBouncer's text output into actual numbers).

Live dashboard

pgbi dashboard
pgbi dashboard --profile staging --interval 5   # poll every 5s instead of the default 2s

Press q or Ctrl+C to exit; the terminal is restored cleanly on exit.

Local development

A docker-compose.yml is included for testing against a real PgBouncer + Postgres stack, with AUTH_TYPE: trust so any password is accepted for the admin user:

docker compose up -d
npm run build && npm link
pgbi connect        # host 127.0.0.1, port 6432, user "app", any password, db "pgbouncer"
pgbi show pools --json
pgbi dashboard

Other scripts:

npm run dev          # run src/cli.ts directly via tsx, no build step
npm run build         # compile TypeScript to dist/
npm run typecheck     # tsc --noEmit
npm run test           # run the vitest suite once
npm run test:watch     # vitest in watch mode

See CLAUDE.md for an architecture overview of the codebase (module layout, how credential caching is split between the profile store and the OS keyring, how the dashboard's polling loop works, etc.).

License

GPL-3.0 — see LICENSE.