PostgreSQL + PgBouncer → Prometheus

PG Exporter

PostgreSQL observability, expressed in SQL. Define metrics in YAML and SQL; let one exporter select the right collector for each target version, role, and extension set.

600+ metrics · PostgreSQL 10–19+ · PgBouncer 1.8–1.25+

Download Read the docs

Start with one database in five minutes

Shipped surface

Useful defaults, backed by inspectable definitions

Product coverage rather than adoption counters; every number maps to the current source tree or release archive.

600+Metricsin the merged default configInspect
58Collector filesversioned YAML + SQL definitionsInspect
10–19+PostgreSQLcovered by the default bundleInspect
35Documented tagsv0.0.1 through v1.4.1Inspect

Why PG Exporter

Put metric logic where database engineers can inspect it

Collector behavior is data. The runtime handles target discovery, planning, execution, caching, failure isolation, and Prometheus encoding.

01 / DECLARE

Define metrics with YAML + SQL

◇ Change the collector, not the binary

  • Map query columns to GAUGE, COUNTER, HISTOGRAM, and LABEL semantics.
  • Set per-collector TTL, timeout, skip, and fatal behavior explicitly.
  • Keep custom collectors beside the shipped definitions and review them as configuration.

The metric contract stays readable to the people who understand the database.

collector.yml
pg_example:
  query: SELECT value FROM view
  min_version: 100000
  tags: [cluster, primary]
  ttl: 10
  timeout: 0.1

02 / PLAN

Select the right query for each target

◇ One binary, target-aware execution

  • Match PostgreSQL or PgBouncer version, recovery role, database, user, schema, and extension facts.
  • Use multiple query branches instead of freezing a collector at the oldest common denominator.
  • Ask /explain why every branch was selected, skipped, or rejected.

Compatibility decisions are explicit at runtime instead of buried in release notes.

GET /explain
✓ pg_wal / primary / PG17
✓ pg_stat_statements / 1.11
– pg_replica / role mismatch
– pgbouncer / target mismatch

03 / OPERATE

Observe and control the exporter itself

◇ Scrapes are only one part of the runtime

  • Inspect per-collector duration, errors, cache state, and output through /stat.
  • Reload configuration without a process restart and keep independent collector failures isolated.
  • Use health and primary/replica endpoints for probes and traffic decisions.

The exporter exposes the evidence needed to operate it, not just the database metrics it emits.

Production fit

A small binary with clear operational boundaries

01

Batteries included

Start with broad PostgreSQL and PgBouncer coverage, then replace only the definitions you need to own.

02

Precise control

Version gates, predicates, timeouts, cache TTLs, failure policy, and constant labels are all explicit.

03

Deploy your way

Use RPM/DEB packages, release archives, containers, Pigsty automation, or a source build.

Download and deploy

Choose the path that matches your environment

Every route runs the same PG Exporter binary and declarative collector model. The difference is lifecycle ownership.

Recommended for services

Linux packages

Install pg-exporter from the Pigsty APT/YUM repository or a versioned RPM/DEB; get systemd integration and /etc/default/pg_exporter.

Compare methods

Linux · macOS · Windows

Release archives

Download a pinned binary, merged config, service examples, license, and checksums from the GitHub release.

Compare methods

amd64 · arm64

Container image

Run the multi-architecture pgsty/pg_exporter image and mount only the configuration or CA material you need.

Compare methods

Integrated or custom

Pigsty or source

Let Pigsty deliver the complete monitoring stack, or build the tagged source with its declared Go toolchain.

Compare methods

Go from download to pg_up 1.Pick an artifact, configure one connection URL, then verify the exporter before adding the Prometheus scrape.

Download PG ExporterFive-minute quick start