Installation - PostgreSQL Server Exporter

System Requirements

Before installing, verify your system meets these requirements:

PostgreSQL Version

PostgreSQL 13-18 (recommended)PostgreSQL 9.1+ supported with reduced functionality

Operating System

Linux (amd64, arm64, armv7, ppc64le)Windows and macOS supported for development

Network

Port 9187 (exporter metrics endpoint)Access to PostgreSQL port 5432 (or custom port)

Permissions

PostgreSQL user with pg_monitor role (PostgreSQL 10+)Or custom monitoring functions (PostgreSQL 9.x)

Installation Methods

Docker
Binary
From Source
Kubernetes

Docker Installation

The fastest way to deploy postgres_exporter is using the official Docker image.

Pull the Image

docker pull quay.io/prometheuscommunity/postgres-exporter:latest

Images are published to both Quay.io (primary) and Docker Hub. Use prometheuscommunity/postgres-exporter for Docker Hub.

Basic Deployment

docker run -d \
  --name postgres-exporter \
  -p 9187:9187 \
  -e DATA_SOURCE_URI="postgres-host:5432/postgres?sslmode=require" \
  -e DATA_SOURCE_USER="postgres_exporter" \
  -e DATA_SOURCE_PASS="your-password" \
  quay.io/prometheuscommunity/postgres-exporter:latest

Production Deployment with Secrets

Use file-based secrets for production:

# Create password file
echo "your-secure-password" > postgres-password.txt
chmod 400 postgres-password.txt

docker run -d \
  --name postgres-exporter \
  -p 9187:9187 \
  -v $(pwd)/postgres-password.txt:/secrets/password:ro \
  -e DATA_SOURCE_URI="postgres-host:5432/postgres?sslmode=require" \
  -e DATA_SOURCE_USER="postgres_exporter" \
  -e DATA_SOURCE_PASS_FILE="/secrets/password" \
  quay.io/prometheuscommunity/postgres-exporter:latest

The container runs as uid/gid 65534 (user nobody). Ensure mounted files have appropriate permissions:

chown 65534:65534 postgres-password.txt
chmod 400 postgres-password.txt

Enable Optional Collectors

Pass command-line flags to enable additional collectors:

docker run -d \
  --name postgres-exporter \
  -p 9187:9187 \
  -e DATA_SOURCE_URI="postgres-host:5432/postgres?sslmode=require" \
  -e DATA_SOURCE_USER="postgres_exporter" \
  -e DATA_SOURCE_PASS_FILE="/secrets/password" \
  -v $(pwd)/postgres-password.txt:/secrets/password:ro \
  quay.io/prometheuscommunity/postgres-exporter:latest \
  --collector.stat_statements \
  --collector.long_running_transactions \
  --collector.database_wraparound

Docker Compose

docker-compose.yml

version: '3.8'
services:
  postgres-exporter:
    image: quay.io/prometheuscommunity/postgres-exporter:latest
    container_name: postgres-exporter
    ports:
      - "9187:9187"
    environment:
      DATA_SOURCE_URI: "postgres:5432/mydb?sslmode=require"
      DATA_SOURCE_USER: "postgres_exporter"
      DATA_SOURCE_PASS_FILE: "/secrets/password"
      PG_EXPORTER_COLLECTION_TIMEOUT: "2m"
    volumes:
      - ./postgres-password.txt:/secrets/password:ro
      - ./postgres-exporter.yml:/etc/postgres-exporter.yml:ro
    command:
      - --config.file=/etc/postgres-exporter.yml
      - --collector.stat_statements
    restart: unless-stopped
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge

Verify Installation

# Check container logs
docker logs postgres-exporter

# Test metrics endpoint
curl http://localhost:9187/metrics | grep pg_up

Binary Installation

Download pre-compiled binaries for Linux, Windows, or macOS.

Download Binary

Visit the GitHub Releases page and download the latest release for your platform:

# Linux amd64 example
VERSION="0.15.0"
wget https://github.com/prometheus-community/postgres_exporter/releases/download/v${VERSION}/postgres_exporter-${VERSION}.linux-amd64.tar.gz

# Extract
tar xvf postgres_exporter-${VERSION}.linux-amd64.tar.gz
cd postgres_exporter-${VERSION}.linux-amd64

Run Directly

# Set connection parameters
export DATA_SOURCE_NAME="postgresql://postgres_exporter:password@localhost:5432/postgres?sslmode=disable"

# Run exporter
./postgres_exporter

Or using separate environment variables:

export DATA_SOURCE_URI="localhost:5432/postgres?sslmode=disable"
export DATA_SOURCE_USER="postgres_exporter"
export DATA_SOURCE_PASS="password"

./postgres_exporter --collector.stat_statements

Create Systemd Service

For production deployments, run as a systemd service:

# Copy binary to system path
sudo cp postgres_exporter /usr/local/bin/
sudo chmod +x /usr/local/bin/postgres_exporter

# Create service user
sudo useradd --no-create-home --shell /bin/false postgres_exporter

Create service file /etc/systemd/system/postgres-exporter.service:

[Unit]
Description=PostgreSQL Exporter
After=network.target

[Service]
Type=simple
User=postgres_exporter
Group=postgres_exporter
ExecStart=/usr/local/bin/postgres_exporter \
  --config.file=/etc/postgres-exporter.yml \
  --collector.stat_statements \
  --collector.long_running_transactions

# Environment file with DATA_SOURCE_* variables
EnvironmentFile=/etc/postgres-exporter.env

Restart=always
RestartSec=10

# Security hardening
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/lib/postgres-exporter

[Install]
WantedBy=multi-user.target

Create environment file /etc/postgres-exporter.env:

DATA_SOURCE_URI=localhost:5432/postgres?sslmode=require
DATA_SOURCE_USER=postgres_exporter
DATA_SOURCE_PASS_FILE=/etc/postgres-exporter-password.txt
PG_EXPORTER_COLLECTION_TIMEOUT=2m

Secure the password file:

echo "your-password" | sudo tee /etc/postgres-exporter-password.txt
sudo chown postgres_exporter:postgres_exporter /etc/postgres-exporter-password.txt
sudo chmod 400 /etc/postgres-exporter-password.txt

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable postgres-exporter
sudo systemctl start postgres-exporter

# Check status
sudo systemctl status postgres-exporter

# View logs
sudo journalctl -u postgres-exporter -f

Build From Source

Build the latest version from source for development or custom modifications.

Prerequisites

Go 1.21 or later
Git
Make (optional, for convenience)

Clone and Build

# Clone repository
git clone https://github.com/prometheus-community/postgres_exporter.git
cd postgres_exporter

# Build using Make
make build

# Or build directly with Go
go build -o postgres_exporter ./cmd/postgres_exporter

Run Tests

# Unit tests
make test

# Integration tests (requires PostgreSQL)
docker run -d \
  --name postgres-test \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=test \
  postgres:16

DATA_SOURCE_NAME='postgresql://postgres:test@localhost:5432/postgres?sslmode=disable' \
  GOOPTS='-v -tags integration' \
  make test

Build Docker Image

# Install promu build tool
make promu

# Cross-compile for multiple architectures
promu crossbuild -p linux/amd64 -p linux/armv7 -p linux/arm64 -p linux/ppc64le

# Build Docker image
make docker

This creates a Docker image tagged as prometheuscommunity/postgres_exporter:<branch>.

Run Development Build

export DATA_SOURCE_NAME="postgresql://postgres:password@localhost:5432/postgres?sslmode=disable"
./postgres_exporter --log.level=debug

Kubernetes Deployment

Deploy postgres_exporter as a sidecar or standalone service in Kubernetes.

Sidecar Deployment

Add exporter as a sidecar to your PostgreSQL StatefulSet:

postgres-statefulset.yaml

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
spec:
  serviceName: postgres
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "9187"
    spec:
      containers:
      - name: postgres
        image: postgres:16
        ports:
        - containerPort: 5432
        env:
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: postgres-secret
              key: password
      
      # Postgres Exporter Sidecar
      - name: postgres-exporter
        image: quay.io/prometheuscommunity/postgres-exporter:latest
        ports:
        - containerPort: 9187
          name: metrics
        env:
        - name: DATA_SOURCE_URI
          value: "localhost:5432/postgres?sslmode=disable"
        - name: DATA_SOURCE_USER
          value: "postgres"
        - name: DATA_SOURCE_PASS
          valueFrom:
            secretKeyRef:
              name: postgres-secret
              key: password
        - name: PG_EXPORTER_COLLECTION_TIMEOUT
          value: "2m"
        args:
        - --collector.stat_statements
        - --collector.database_wraparound
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 512Mi

Standalone Deployment

Deploy exporter as a separate Deployment for multi-target monitoring:

postgres-exporter-deployment.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: postgres-exporter-config
data:
  postgres_exporter.yml: |
    auth_modules:
      production:
        type: userpass
        userpass:
          username: postgres_exporter
          password: ${POSTGRES_PASSWORD}
        options:
          sslmode: require
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres-exporter
  labels:
    app: postgres-exporter
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres-exporter
  template:
    metadata:
      labels:
        app: postgres-exporter
    spec:
      containers:
      - name: postgres-exporter
        image: quay.io/prometheuscommunity/postgres-exporter:latest
        ports:
        - containerPort: 9187
          name: metrics
        args:
        - --config.file=/etc/postgres-exporter.yml
        volumeMounts:
        - name: config
          mountPath: /etc/postgres-exporter.yml
          subPath: postgres_exporter.yml
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 512Mi
      volumes:
      - name: config
        configMap:
          name: postgres-exporter-config
---
apiVersion: v1
kind: Service
metadata:
  name: postgres-exporter
  labels:
    app: postgres-exporter
spec:
  selector:
    app: postgres-exporter
  ports:
  - port: 9187
    targetPort: 9187
    name: metrics

ServiceMonitor for Prometheus Operator

servicemonitor.yaml

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: postgres-exporter
  labels:
    app: postgres-exporter
spec:
  selector:
    matchLabels:
      app: postgres-exporter
  endpoints:
  - port: metrics
    interval: 30s
    path: /metrics

Helm Chart (Community)

Use the community Helm chart for quick deployment:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

helm install postgres-exporter prometheus-community/prometheus-postgres-exporter \
  --set config.datasource.host=postgres.default.svc.cluster.local \
  --set config.datasource.user=postgres_exporter \
  --set config.datasource.passwordSecret.name=postgres-secret \
  --set config.datasource.passwordSecret.key=password

Configuration File

The exporter supports a YAML configuration file for advanced settings, particularly for multi-target monitoring.

Create Configuration File

Create postgres_exporter.yml:

postgres_exporter.yml

auth_modules:
  production:
    type: userpass
    userpass:
      username: postgres_exporter
      password: prod-password
    options:
      sslmode: require
      connect_timeout: 10

  staging:
    type: userpass
    userpass:
      username: postgres_exporter
      password: staging-password
    options:
      sslmode: disable

  readonly:
    type: userpass
    userpass:
      username: readonly_user
      password: readonly-password
    options:
      sslmode: require
      application_name: postgres_exporter

Use Configuration File

# With binary
./postgres_exporter --config.file=/etc/postgres-exporter.yml

# With Docker
docker run -d \
  -v $(pwd)/postgres_exporter.yml:/config.yml:ro \
  -p 9187:9187 \
  quay.io/prometheuscommunity/postgres-exporter:latest \
  --config.file=/config.yml

See [Multi-Target Setup(../multi-target) for complete configuration examples.

Database User Setup

Create a dedicated monitoring user with minimal required permissions.

PostgreSQL 10 and Later

-- Create user
CREATE USER postgres_exporter WITH PASSWORD 'secure-password' LOGIN;

-- Grant monitoring role (provides read access to all stats views)
GRANT pg_monitor TO postgres_exporter;

-- Grant connection to databases you want to monitor
GRANT CONNECT ON DATABASE postgres TO postgres_exporter;
GRANT CONNECT ON DATABASE myapp TO postgres_exporter;

-- Optional: Enable pg_stat_statements monitoring
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
GRANT SELECT ON pg_stat_statements TO postgres_exporter;

PostgreSQL 9.x

Older versions require creating helper functions:

-- Create user
CREATE USER postgres_exporter WITH PASSWORD 'secure-password' LOGIN;

-- Create schema
CREATE SCHEMA IF NOT EXISTS postgres_exporter;
GRANT USAGE ON SCHEMA postgres_exporter TO postgres_exporter;
ALTER USER postgres_exporter SET SEARCH_PATH TO postgres_exporter, pg_catalog;

-- Helper function for pg_stat_activity
CREATE OR REPLACE FUNCTION postgres_exporter.get_pg_stat_activity() 
RETURNS SETOF pg_stat_activity AS
$$ SELECT * FROM pg_catalog.pg_stat_activity; $$
LANGUAGE sql VOLATILE SECURITY DEFINER;

CREATE OR REPLACE VIEW postgres_exporter.pg_stat_activity AS
  SELECT * FROM postgres_exporter.get_pg_stat_activity();

GRANT SELECT ON postgres_exporter.pg_stat_activity TO postgres_exporter;

-- Helper function for pg_stat_replication
CREATE OR REPLACE FUNCTION postgres_exporter.get_pg_stat_replication() 
RETURNS SETOF pg_stat_replication AS
$$ SELECT * FROM pg_catalog.pg_stat_replication; $$
LANGUAGE sql VOLATILE SECURITY DEFINER;

CREATE OR REPLACE VIEW postgres_exporter.pg_stat_replication AS
  SELECT * FROM postgres_exporter.get_pg_stat_replication();

GRANT SELECT ON postgres_exporter.pg_stat_replication TO postgres_exporter;

-- Grant database connection
GRANT CONNECT ON DATABASE postgres TO postgres_exporter;

AWS RDS / Aurora

RDS restricts superuser functions. Use the master user or grant the monitoring user to master:

CREATE USER postgres_exporter WITH PASSWORD 'secure-password' LOGIN;
GRANT pg_monitor TO postgres_exporter;
GRANT postgres_exporter TO <RDS_MASTER_USER>;

Verify Installation

Run these commands to verify the exporter is working correctly:

Check Process is Running

# For systemd
systemctl status postgres-exporter

# For Docker
docker ps | grep postgres-exporter

# For Kubernetes
kubectl get pods -l app=postgres-exporter

Test Metrics Endpoint

curl http://localhost:9187/metrics | head -20

Expected output includes:

# HELP pg_up Whether the last scrape was able to connect to the server (1 for yes, 0 for no)
# TYPE pg_up gauge
pg_up 1

Check for Errors

# Binary/systemd
journalctl -u postgres-exporter -n 50

# Docker
docker logs postgres-exporter

# Kubernetes
kubectl logs -l app=postgres-exporter

Verify Key Metrics

curl -s http://localhost:9187/metrics | grep -E "(pg_up|pg_stat_database_numbackends|pg_exporter_last_scrape_error)"

All three should be present:

pg_up 1 = Connected successfully
pg_stat_database_numbackends = Database metrics collected
pg_exporter_last_scrape_error 0 = No collection errors

Next Steps

Configuration Reference

Complete guide to collectors, flags, and environment variables

Multi-Target Monitoring

Configure centralized monitoring for multiple PostgreSQL servers

Prometheus Integration

Set up scrape configs and alerting rules

Security Best Practices

Secure your exporter deployment

Get Started

Configuration

Deployment

Collectors

Advanced

​System Requirements

PostgreSQL Version

Operating System

Network

Permissions

​Installation Methods

​Docker Installation

​Pull the Image

​Basic Deployment

​Production Deployment with Secrets

​Enable Optional Collectors

​Docker Compose

​Verify Installation

​Binary Installation

​Download Binary

​Run Directly

​Create Systemd Service

​Build From Source

​Prerequisites

​Clone and Build

​Run Tests

​Build Docker Image

​Run Development Build

​Kubernetes Deployment

​Sidecar Deployment

​Standalone Deployment

​ServiceMonitor for Prometheus Operator

​Helm Chart (Community)

​Configuration File

​Create Configuration File

​Use Configuration File

​Database User Setup

​PostgreSQL 10 and Later

​PostgreSQL 9.x

​AWS RDS / Aurora

​Verify Installation

​Next Steps

Configuration Reference

Multi-Target Monitoring

Prometheus Integration

Security Best Practices

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Docker Installation

Pull the Image

Basic Deployment

Production Deployment with Secrets

Enable Optional Collectors

Docker Compose

Verify Installation

Binary Installation

Download Binary

Run Directly

Create Systemd Service

Build From Source

Prerequisites

Clone and Build

Run Tests

Build Docker Image

Run Development Build

Kubernetes Deployment

Sidecar Deployment

Standalone Deployment

ServiceMonitor for Prometheus Operator

Helm Chart (Community)

Configuration File

Create Configuration File

Use Configuration File

Database User Setup

PostgreSQL 10 and Later

PostgreSQL 9.x

AWS RDS / Aurora

Verify Installation

Next Steps