How to Monitor PostgreSQL with Prometheus Exporter and Docker

Introduction

PostgreSQL is a popular open‑source relational database widely used in enterprises. This guide shows how to monitor PostgreSQL with Prometheus using the postgres_exporter project.

1. Install the Exporter (single‑node)

The Prometheus community provides postgres_exporter (GitHub: https://github.com/prometheus-community/postgres_exporter). It can be run as a Docker container. Example command:

docker run -d \
  --name postgres-exporter \
  --net=host \
  --restart=always \
  -e DATA_SOURCE_URI="localhost:5432/postgres?sslmode=disable" \
  -e DATA_SOURCE_USER=postgres \
  -e DATA_SOURCE_PASS=password \
  quay.io/prometheuscommunity/postgres_exporter

The exporter listens on port 9187. Add the following scrape job to Prometheus:

scrape_configs:
  - job_name: postgres
    static_configs:
      - targets: ["127.0.0.1:9187"]

2. Multi‑node Monitoring

postgres_exporter

can monitor multiple PostgreSQL instances from a single exporter.

2.1 Create a configuration file

# postgres_exporter.yml
auth_modules:
  psql:  # custom auth module name
    type: userpass
    userpass:
      username: postgres
      password: password
    options:
      sslmode: disable

2.2 Start the exporter container with the config

docker run -d \
  --name postgres-exporter \
  --net=host \
  --restart=always \
  -v $(pwd)/postgres_exporter.yml:/postgres-exporter/config/postgres_exporter.yml \
  quay.io/prometheuscommunity/postgres_exporter \
  --config.file=/postgres-exporter/config/postgres_exporter.yml

2.3 Configure Prometheus for multiple targets

scrape_configs:
  - job_name: 'postgres'
    static_configs:
      - targets:
        - postgresql-1:5432  # first instance
        - postgresql-2:5432  # second instance
    metrics_path: /probe
    params:
      auth_module: [psql]
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9187  # exporter address