Integrations & developer tooling

The same engine powers the web tool, a Go module, a CLI, and a GitHub Action. Pick whichever fits your workflow — none of them require a connection to your database.

GitHub Action — analyze in CI

Drop captured plans into your repo and let CI fail on regressions. The action installs the CLI, analyzes each plan, and writes a summary into the workflow.

# .github/workflows/explain-checks.yml
name: explain checks
on: pull_request
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cybertec-postgresql/pgconfigurator_v2/.github/actions/analyze@main
        with:
          plans: 'ci/plans/*.txt'
          fail-on: error

Inputs: plans (glob), fail-on (error|warn|info), cli-version (default latest — pin for reproducibility). Outputs: errors / warnings / infos.

CLI — pgconfigurator

The same binary powers the action; install it locally with Go and you can analyze and generate from scripts.

# install
go install github.com/cybertec-postgresql/pgconfigurator_v2/cmd/pgconfigurator@latest

# analyze a plan file (or stdin)
pgconfigurator analyze my-plan.txt
psql -d mydb -c 'EXPLAIN (ANALYZE) ...' | pgconfigurator analyze

# generate postgresql.conf for a profile
pgconfigurator generate --workload OLTP --pg 18 --ram 32 --cpu 8 --storage NVMe

On the plan side, findings are printed to stderr and the full Analysis JSON to stdout — so you can pipe it into jq.

psql one-liner — pgca

A small shell wrapper that runs an EXPLAIN against your database and pipes the output through pgconfigurator analyze. The repository is public, so you can read it on GitHub (scripts/psql/pgca) or download it directly:

# fetch it onto your $PATH in one line:
curl -fsSL https://raw.githubusercontent.com/cybertec-postgresql/pgconfigurator_v2/main/scripts/psql/pgca \
  -o ~/.local/bin/pgca && chmod +x ~/.local/bin/pgca

# then:
pgca mydb "EXPLAIN (ANALYZE, BUFFERS) SELECT ... FROM ..."

# remote DB:
pgca -h db.example -U app  prod  "EXPLAIN (ANALYZE) SELECT ..."

Findings to stderr, the JSON plan to stdout — pipe to jq for filtering, or pipe stdout to /dev/null to keep only the findings.

Or inline, without the wrapper

psql -d mydb -X -q -A -t \
  -c "EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM big WHERE ..." \
  | pgconfigurator analyze

Browser bookmarklet

Highlight an EXPLAIN plan in your tool of choice (pgAdmin, DataGrip, a notebook, an issue ticket), click your bookmark, and it opens /explain with the plan pre-filled. The plan travels in the URL fragment — nothing is sent to the server.

Install: create a new bookmark — drag any page to your bookmarks bar, then edit it — and paste the line below as its address (URL), replacing whatever is there. Name it anything you like.

We deliberately don't hand you a ready-made draggable link: a bookmarklet is a javascript: URL, and browsers and ad-blockers flag (or quietly strip) script-bearing links on a page as a security precaution. Pasting it into a bookmark yourself is the safe, warning-free way in.

Bookmark address

javascript:(function(){var t=(window.getSelection&&window.getSelection().toString())||'';if(!t){alert('Select an EXPLAIN plan first, then click the bookmarklet.');return;}var b=btoa(unescape(encodeURIComponent(t))).replace(/=+$/,'');window.open(location.origin.indexOf('pgconfigurator')!==-1?location.origin+'/explain#plan='+b:'https://pgconfigurator.cybertec.at/explain#plan='+b,'_blank');})();

It runs entirely in your browser: it base64-encodes your selected text and opens it in /explain— no network call. Limit: very long plans may exceed the browser's URL length cap (~32 KB), so for huge plans, copy-paste into /explain instead.

Public HTTP API

If you want to script the analyzer or generator from any language, see the API reference for endpoint shapes and curl examples.