Environment Variables

The PostgreSQL Server Exporter can be configured using environment variables, which is especially useful for containerized deployments.

Environment variables starting with PG_EXPORTER_ will be overwritten by the corresponding CLI flag if given.

Data Source Variables

These variables configure the PostgreSQL connection. See Data Source Configuration for detailed examples.

DATA_SOURCE_NAME

string

Complete connection string including credentials. Supports both URI format (postgresql://user:pass@host/db) and key=value format (host=localhost user=postgres). Takes precedence over all other data source variables.Example: postgresql://postgres:password@localhost:5432/postgres?sslmode=disable

DATA_SOURCE_URI

string

Database hostname and connection parameters without credentials. Format: hostname:port/database?optionsExample: localhost:5432/postgres?sslmode=disable

DATA_SOURCE_URI_FILE

string

Path to a file containing the DATA_SOURCE_URI value. Whitespace is trimmed.Example: /run/secrets/db_uri

DATA_SOURCE_USER

string

Database username. Used with DATA_SOURCE_URI to construct the full connection string.Example: postgres_exporter

DATA_SOURCE_USER_FILE

string

Path to a file containing the username. Whitespace is trimmed. Takes precedence over DATA_SOURCE_USER.Example: /run/secrets/db_user

DATA_SOURCE_PASS

string

Database password. Used with DATA_SOURCE_URI to construct the full connection string.Example: secure_password

DATA_SOURCE_PASS_FILE

string

Path to a file containing the password. Whitespace is trimmed. Takes precedence over DATA_SOURCE_PASS. Recommended for security.Example: /run/secrets/db_password

Exporter Behavior Variables

These variables control how the exporter operates and what metrics it collects.

PG_EXPORTER_WEB_TELEMETRY_PATH

string

default:"/metrics"

HTTP path where metrics are exposed.CLI Flag: --web.telemetry-path

PG_EXPORTER_DISABLE_DEFAULT_METRICS

boolean

default:"false"

When true, only metrics from custom queries are exported (requires PG_EXPORTER_EXTEND_QUERY_PATH). Built-in collector metrics are disabled.CLI Flag: --disable-default-metricsValues: true, false

PG_EXPORTER_DISABLE_SETTINGS_METRICS

boolean

default:"false"

When true, disables scraping of pg_settings metrics.CLI Flag: --disable-settings-metricsValues: true, false

PG_EXPORTER_COLLECTION_TIMEOUT

duration

default:"1m"

Timeout for collecting statistics from PostgreSQL. When reached, the database connection is dropped to prevent connection pool exhaustion. Must be greater than 1ms.CLI Flag: --collection-timeoutExample: 30s, 2m, 500ms

PG_EXPORTER_METRIC_PREFIX

string

default:"pg"

Prefix for all exported metrics. Change this to avoid metric name conflicts.CLI Flag: --metric-prefixExample: postgres, pgsql

Deprecated Variables

The following variables are deprecated and will be removed in a future release.

PG_EXPORTER_AUTO_DISCOVER_DATABASES

boolean

default:"false"

DEPRECATED: Automatically discover and monitor all databases on the server.CLI Flag: --auto-discover-databasesDeprecation Note: Use service discovery in Prometheus instead of database auto-discovery in the exporter.

PG_EXPORTER_EXCLUDE_DATABASES

string

default:""

DEPRECATED: Comma-separated list of database names to exclude when PG_EXPORTER_AUTO_DISCOVER_DATABASES is enabled.CLI Flag: --exclude-databasesExample: template0,template1,postgres

PG_EXPORTER_INCLUDE_DATABASES

string

default:""

DEPRECATED: Comma-separated list of database names to exclusively include when PG_EXPORTER_AUTO_DISCOVER_DATABASES is enabled. Empty means all (minus excludes).CLI Flag: --include-databasesExample: app_db,analytics_db

PG_EXPORTER_EXTEND_QUERY_PATH

string

default:""

DEPRECATED: Path to YAML file with custom queries. Use built-in collectors instead, or see sql_exporter for generic SQL monitoring.CLI Flag: --extend.query-pathExample: /etc/postgres_exporter/queries.yaml

PG_EXPORTER_CONSTANT_LABELS

string

default:""

DEPRECATED: Comma-separated list of label=value pairs to add to all metrics.CLI Flag: --constantLabelsExample: environment=production,region=us-east-1

Configuration Examples

Docker Compose
Kubernetes
systemd
Shell Script

docker-compose.yml

version: '3.8'
services:
  postgres-exporter:
    image: quay.io/prometheuscommunity/postgres-exporter:latest
    environment:
      DATA_SOURCE_URI: "postgres:5432/mydb?sslmode=disable"
      DATA_SOURCE_USER: "postgres_exporter"
      DATA_SOURCE_PASS: "secure_password"
      PG_EXPORTER_WEB_TELEMETRY_PATH: "/metrics"
      PG_EXPORTER_DISABLE_SETTINGS_METRICS: "false"
      PG_EXPORTER_METRIC_PREFIX: "pg"
    ports:
      - "9187:9187"
    networks:
      - monitoring
  
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secure_password
      POSTGRES_DB: mydb
    networks:
      - monitoring

networks:
  monitoring:

apiVersion: v1
kind: ConfigMap
metadata:
  name: postgres-exporter-config
data:
  DATA_SOURCE_URI: "postgres.default.svc.cluster.local:5432/postgres?sslmode=require"
  PG_EXPORTER_COLLECTION_TIMEOUT: "30s"
  PG_EXPORTER_METRIC_PREFIX: "pg"
---
apiVersion: v1
kind: Secret
metadata:
  name: postgres-exporter-secret
type: Opaque
stringData:
  username: postgres_exporter
  password: secure_password
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: 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
        env:
        - name: DATA_SOURCE_USER
          valueFrom:
            secretKeyRef:
              name: postgres-exporter-secret
              key: username
        - name: DATA_SOURCE_PASS
          valueFrom:
            secretKeyRef:
              name: postgres-exporter-secret
              key: password
        envFrom:
        - configMapRef:
            name: postgres-exporter-config

/etc/systemd/system/postgres-exporter.service

[Unit]
Description=PostgreSQL Prometheus Exporter
After=network.target postgresql.service

[Service]
Type=simple
User=postgres_exporter
Group=postgres_exporter

Environment="DATA_SOURCE_URI=localhost:5432/postgres?sslmode=disable"
Environment="DATA_SOURCE_USER_FILE=/etc/postgres_exporter/secrets/user"
Environment="DATA_SOURCE_PASS_FILE=/etc/postgres_exporter/secrets/password"
Environment="PG_EXPORTER_WEB_TELEMETRY_PATH=/metrics"
Environment="PG_EXPORTER_COLLECTION_TIMEOUT=1m"

ExecStart=/usr/local/bin/postgres_exporter
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Create the secret files:

sudo mkdir -p /etc/postgres_exporter/secrets
echo "postgres_exporter" | sudo tee /etc/postgres_exporter/secrets/user
echo "secure_password" | sudo tee /etc/postgres_exporter/secrets/password
sudo chmod 600 /etc/postgres_exporter/secrets/*
sudo chown postgres_exporter:postgres_exporter /etc/postgres_exporter/secrets/*

run_exporter.sh

#!/bin/bash

# Data source configuration
export DATA_SOURCE_URI="localhost:5432/postgres?sslmode=disable"
export DATA_SOURCE_USER="postgres_exporter"
export DATA_SOURCE_PASS="secure_password"

# Or use file-based secrets
# export DATA_SOURCE_USER_FILE="/run/secrets/db_user"
# export DATA_SOURCE_PASS_FILE="/run/secrets/db_password"

# Exporter configuration
export PG_EXPORTER_WEB_TELEMETRY_PATH="/metrics"
export PG_EXPORTER_DISABLE_DEFAULT_METRICS="false"
export PG_EXPORTER_DISABLE_SETTINGS_METRICS="false"
export PG_EXPORTER_COLLECTION_TIMEOUT="1m"
export PG_EXPORTER_METRIC_PREFIX="pg"

# Start the exporter
exec ./postgres_exporter \
  --web.listen-address=":9187" \
  --log.level=info

Precedence with CLI Flags

When both environment variables and CLI flags are set:

# Environment variable sets base value
export PG_EXPORTER_WEB_TELEMETRY_PATH="/metrics"

# CLI flag overrides it
./postgres_exporter --web.telemetry-path="/custom/metrics"

# Result: metrics served at /custom/metrics

CLI flags always take precedence over environment variables.

Validation

Verify your environment variables are set correctly:

# Show all PG_EXPORTER variables
env | grep PG_EXPORTER

# Check DATA_SOURCE variables (careful with passwords!)
env | grep DATA_SOURCE | grep -v PASS

Get Started

Configuration

Deployment

Collectors

Advanced

Data Source Variables

Exporter Behavior Variables

Deprecated Variables

Configuration Examples

Precedence with CLI Flags

Validation

Next Steps

Command-Line Flags

Data Source Configuration

Build docs developers (and LLMs) love

Get Started

Configuration

Deployment

Collectors

Advanced

​Data Source Variables

​Exporter Behavior Variables

​Deprecated Variables

​Configuration Examples

​Precedence with CLI Flags

​Validation

​Next Steps

Command-Line Flags

Data Source Configuration

Build docs developers (and LLMs) love

Data Source Variables

Exporter Behavior Variables

Deprecated Variables

Configuration Examples

Precedence with CLI Flags

Validation

Next Steps