Skip to main content
Deploy the PostgreSQL Server Exporter as a standalone binary on Linux, macOS, or BSD systems.

​
Download

Download the latest release from the GitHub releases page. Available architectures:
  • linux-amd64
  • linux-arm64
  • linux-armv7
  • linux-ppc64le
  • darwin-amd64
  • darwin-arm64
  • freebsd-amd64
1

Download the binary

wget https://github.com/prometheus-community/postgres_exporter/releases/download/v0.15.0/postgres_exporter-0.15.0.linux-amd64.tar.gz
Replace v0.15.0 with the latest version and adjust the architecture as needed.
2

Extract the archive

tar xvfz postgres_exporter-0.15.0.linux-amd64.tar.gz
cd postgres_exporter-0.15.0.linux-amd64
3

Move the binary to system path

sudo mv postgres_exporter /usr/local/bin/
sudo chmod +x /usr/local/bin/postgres_exporter
4

Verify installation

postgres_exporter --version

​
Building from Source

To build the latest version from source:
1

Clone the repository

git clone https://github.com/prometheus-community/postgres_exporter.git
cd postgres_exporter
2

Build the binary

make build
This requires Go 1.21 or later.
3

Install the binary

sudo mv postgres_exporter /usr/local/bin/

​
Running the Exporter

​
Using Environment Variables

1

Set the data source name

export DATA_SOURCE_NAME="postgresql://postgres_exporter:password@localhost:5432/postgres?sslmode=disable"
Or use the split format:
export DATA_SOURCE_URI="localhost:5432/postgres?sslmode=disable"
export DATA_SOURCE_USER="postgres_exporter"
export DATA_SOURCE_PASS="password"
2

Start the exporter

postgres_exporter
The exporter will start on port 9187 by default.
3

Verify metrics

curl http://localhost:9187/metrics
Store database passwords in files with restricted permissions instead of environment variables.
1

Create a password file

sudo mkdir -p /etc/postgres_exporter
echo "your_password" | sudo tee /etc/postgres_exporter/password.txt
sudo chmod 600 /etc/postgres_exporter/password.txt
2

Set file ownership

sudo chown postgres_exporter:postgres_exporter /etc/postgres_exporter/password.txt
3

Run with password file

export DATA_SOURCE_URI="localhost:5432/postgres?sslmode=require"
export DATA_SOURCE_USER="postgres_exporter"
export DATA_SOURCE_PASS_FILE="/etc/postgres_exporter/password.txt"
postgres_exporter

​
Using Configuration File

For multi-target deployments:
1

Create a configuration file

Create /etc/postgres_exporter/postgres_exporter.yml:
auth_modules:
  primary:
    type: userpass
    userpass:
      username: postgres_exporter
      password: primary_password
    options:
      sslmode: require
  replica:
    type: userpass
    userpass:
      username: postgres_exporter
      password: replica_password
    options:
      sslmode: require
2

Set file permissions

Configuration files may contain sensitive credentials. Protect them with appropriate permissions.
sudo chmod 600 /etc/postgres_exporter/postgres_exporter.yml
sudo chown postgres_exporter:postgres_exporter /etc/postgres_exporter/postgres_exporter.yml
3

Run with configuration file

postgres_exporter --config.file=/etc/postgres_exporter/postgres_exporter.yml

​
Command-Line Flags

Common flags: 
postgres_exporter \
  --web.listen-address=":9187" \
  --web.telemetry-path="/metrics" \
  --config.file="/etc/postgres_exporter/postgres_exporter.yml" \
  --log.level="info" \
  --log.format="logfmt"

​
Available Flags

FlagDefaultDescription
--web.listen-address:9187Address to listen on
--web.telemetry-path/metricsPath for metrics endpoint
--config.filepostgres_exporter.ymlConfiguration file path
--log.levelinfoLog level (debug, info, warn, error)
--log.formatlogfmtLog format (logfmt, json)
--disable-default-metricsfalseDisable built-in metrics
--disable-settings-metricsfalseDisable pg_settings metrics
--extend.query-path-Path to custom queries YAML
See all available flags: 
postgres_exporter --help

​
Running as Non-Root User

1

Create a dedicated user

sudo useradd --system --no-create-home --shell /bin/false postgres_exporter
2

Create directories

sudo mkdir -p /etc/postgres_exporter
sudo mkdir -p /var/log/postgres_exporter
sudo chown postgres_exporter:postgres_exporter /etc/postgres_exporter
sudo chown postgres_exporter:postgres_exporter /var/log/postgres_exporter
3

Run as the dedicated user

sudo -u postgres_exporter DATA_SOURCE_URI="localhost:5432/postgres?sslmode=disable" \
  DATA_SOURCE_USER="postgres_exporter" \
  DATA_SOURCE_PASS_FILE="/etc/postgres_exporter/password.txt" \
  postgres_exporter

​
Local Socket Connection

For local PostgreSQL installations using Unix sockets: 
sudo -u postgres DATA_SOURCE_NAME="user=postgres host=/var/run/postgresql/ sslmode=disable" \
  postgres_exporter
This is the recommended approach for local deployments on Debian/Ubuntu systems.

​
Multiple Databases

To scrape multiple databases from a single exporter instance: 
export DATA_SOURCE_NAME="port=5432,port=6432"
postgres_exporter
Or use multi-target mode with a configuration file (see Multi-Target Support).

​
Custom Queries

To add custom metrics:
1

Create a queries file

Create /etc/postgres_exporter/queries.yaml with your custom queries.
2

Run with custom queries

postgres_exporter --extend.query-path=/etc/postgres_exporter/queries.yaml

​
Security Considerations

  • Never run as root in production
  • Use password files instead of environment variables
  • Set file permissions to 600 for password and config files
  • Use SSL/TLS connections to PostgreSQL (sslmode=require)
  • Limit network access to the metrics endpoint (port 9187)
  • Create a dedicated database user with minimal privileges
  • Consider using systemd for process management (see systemd deployment)

​
Verifying the Deployment

Check that metrics are being collected: 
curl -s http://localhost:9187/metrics | grep pg_up
You should see: 
pg_up 1
Check for errors in the logs: 
postgres_exporter --log.level=debug

Build docs developers (and LLMs) love

Get started for freeTalk to us