Quick start

Collect your first PostgreSQL metrics

Install PG Exporter, create a monitoring user, and connect it to PostgreSQL. Then add its metrics endpoint to Prometheus.

You need Linux amd64, PostgreSQL 10 or later on the same host, sudo access, and database administrator access.

Other installation methods

Step 01

Install

Download and install the binary and its collector configuration.

VERSION=1.6.0
ARCHIVE="pg_exporter-${VERSION}.linux-amd64.tar.gz"
curl -fLO "https://github.com/pgsty/pg_exporter/releases/download/v${VERSION}/$ARCHIVE" &&
curl -fLO "https://github.com/pgsty/pg_exporter/releases/download/v${VERSION}/checksums.txt" &&
grep "  $ARCHIVE$" checksums.txt | sha256sum -c - &&
mkdir -p "pg_exporter-${VERSION}" &&
tar -xzf "$ARCHIVE" -C "pg_exporter-${VERSION}" &&
sudo install -m 0755 "pg_exporter-${VERSION}/pg_exporter" /usr/local/bin/pg_exporter &&
sudo install -m 0644 "pg_exporter-${VERSION}/pg_exporter.yml" /etc/pg_exporter.yml &&
pg_exporter --version

The checksum result is OK. The installed version is v1.6.0.

Other platforms and package installation commands are on the download page.

Step 02

Create a monitoring user

Connect to PostgreSQL as its administrator:

sudo -u postgres psql -d postgres

Replace change-me with a password. Then create the monitoring role:

CREATE USER monitor WITH PASSWORD 'change-me';
GRANT pg_monitor TO monitor;

On PostgreSQL 10–13, also run this in the main connection database (postgres in this guide):

GRANT SELECT (oid) ON pg_catalog.pg_subscription TO monitor;

PostgreSQL 14+ needs no extra grant under the standard catalog ACLs. This grant does not expose subscription passwords.

Type \q to return to the shell. Use the same password in the connection URL below.

Step 03

Run and verify

Start the exporter in the foreground. It listens on this host only.

In the URL, percent-encode reserved characters in the password (for example, # becomes %23).

export PG_EXPORTER_URL='postgres://monitor:[email protected]:5432/postgres?sslmode=disable'
pg_exporter --config=/etc/pg_exporter.yml --web.listen-address=127.0.0.1:9630

Run this command in another terminal:

curl -fsS http://127.0.0.1:9630/metrics | grep -E '^pg_(up|version|in_recovery) '

For remote databases, TLS, or password files, see production deployment.

Example output

pg_up 1 reports a main database scrape without a fatal error. This example shows a PostgreSQL 17 primary.

PostgreSQL availability, version, and recovery metrics

pg_up 1
pg_version 170000
pg_in_recovery 0

Step 04

Add the Prometheus target

Add this target to prometheus.yml. This example uses Prometheus on the same host.

scrape_configs:
  - job_name: 'postgresql'
    scrape_interval: 15s
    static_configs:
      - targets: ['127.0.0.1:9630']

Reload Prometheus. Open its Targets page and check that the target is UP. If Prometheus runs elsewhere, configure a reachable listener and target address as shown in production deployment.

Use Pigsty dashboards to view the metrics, or explore the live demo.

Troubleshooting

Check the result

Use the logs for connection errors, /explain for selected queries, and /stat for query statistics.

Why is pg_up 0?

Read the exporter log. Check the host, port, database, credentials, and pg_hba.conf. A fatal collector error can also set pg_up to 0.

Troubleshooting guide

Why are some metrics missing?

Read /explain to see the collectors selected for the main database. Compare their version limits, tags, and SQL with your target. Read /stat for error counts and metric counts. Check the exporter logs for error details.

Troubleshooting guide

Then what