pga

A tiny CLI over the pganalyze GraphQL API for quick Postgres investigations: slow queries, index advisor findings, unused indexes, active issues/alerts.

Ships with a Claude Code skill in .claude/skills/pganalyze/ that teaches Claude when and how to reach for this tool during DB-perf investigations.

Unofficial. Not affiliated with pganalyze. Uses only their documented public API (getServers, getIssues, getQueryStats).

Install

curl -LsSf https://raw.githubusercontent.com/drewag/pg-analyze/main/install.sh | bash

Installs the pga CLI to ~/.local/bin/pga and the Claude Code skill to ~/.claude/skills/pganalyze/. Needs uv (brew install uv) and curl.

Then:

pga setup

Interactively captures your API key, org, and default server/database. Grab a key from https://app.pganalyze.com. That's it — run any command below.

Install details

• Run ./install.sh from a local clone instead of piping from curl.
• Override install locations with PGA_BIN_DIR / PGA_SKILL_DIR.
• Skill at ~/.claude/skills/pganalyze/ is auto-picked up by Claude Code in every project.

Config details

• Config file: ~/.config/pga/config.toml (chmod 600, includes the API key).
• pga config show — review current values.
• pga config set <key> <value> — change individual fields (organization_slug, server_id, database_id).
• pga config set-key / pga config clear-key — manage just the API key.
• PGANALYZE_API_KEY env var, if set, overrides the config file.

Usage

pga queries top --by pct-total --limit 10      # top 10 by % of total runtime
pga queries top --by avg-time --limit 10       # top 10 by avg ms per call
pga queries show <query-id>                    # SQL + stats + related issues

pga indexes missing                            # index advisor: missing
pga indexes unused                             # index advisor: unused

pga issues list --severity critical            # all active issues
pga issues show <issue-id>

pga alerts list                                # critical issues
pga alerts show <alert-id>

Add --json to any command for machine-readable output.

What's not here

• Alert acknowledgment. pganalyze's public API exposes only one mutation (addServer). There's no documented way to acknowledge an issue/alert. Use the UI URL shown in references[].url.
• Historical windows. queries top uses pganalyze's default (last 24h). Extend the CLI if you need custom windows.
• Anything beyond getServers, getIssues, getQueryStats. Everything else pganalyze exposes is undocumented/private and can break without notice.

Claude Code skill

The installer drops SKILL.md into ~/.claude/skills/pganalyze/ so it's auto-picked up by Claude Code in every project. Inside this repo it also lives at .claude/skills/pganalyze/SKILL.md. It documents trigger phrases, playbook recipes, and how to interpret the metrics.

Contributing

Small PRs welcome — especially:

• New subcommands that stay within pganalyze's documented public API.
• Tuning the _matches_kind heuristic in pga.py for index/alert partitioning against real API responses.
• Additional Claude Code skill recipes.

Please keep the CLI to a single pga.py file (no build step).

License

MIT — see LICENSE.