PG Exporter 1.6.1 Documentation

• 1: Getting Started
• 2: Installation
• 3: Configuration
• 4: API Reference
• 5: Deployment
• 6: Release Notes

docker run -d --name pg_exporter -p 9630:9630 -e PG_EXPORTER_URL="postgres://user:pass@host:5432/postgres" pgsty/pg_exporter:1.6.1

# RPM-based systems
sudo tee /etc/yum.repos.d/pigsty-infra.repo > /dev/null <<-'EOF'
[pigsty-infra]
name=Pigsty Infra for $basearch
baseurl=https://repo.pigsty.io/yum/infra/$basearch
enabled = 1
gpgcheck = 0
module_hotfixes=1
EOF

sudo yum makecache;
sudo yum install -y pg-exporter

sudo tee /etc/apt/sources.list.d/pigsty-infra.list > /dev/null <<EOF
deb [trusted=yes] https://repo.pigsty.io/apt/infra generic main
EOF

sudo apt update;
sudo apt install -y pg-exporter

VERSION=$(curl -fsSL https://api.github.com/repos/pgsty/pg_exporter/releases/latest | sed -n 's/.*"tag_name": "v\([^"]*\)".*/\1/p')
wget "https://github.com/pgsty/pg_exporter/releases/download/v${VERSION}/pg_exporter-${VERSION}.linux-amd64.tar.gz"
mkdir -p "pg_exporter-${VERSION}.linux-amd64"
tar -xf "pg_exporter-${VERSION}.linux-amd64.tar.gz" -C "pg_exporter-${VERSION}.linux-amd64"
sudo install "pg_exporter-${VERSION}.linux-amd64/pg_exporter" /usr/bin/
sudo install "pg_exporter-${VERSION}.linux-amd64/pg_exporter.yml" /etc/pg_exporter.yml

# Build from source
git clone https://github.com/pgsty/pg_exporter.git
cd pg_exporter
make build

# Minimal startup with the local-first default URL
pg_exporter

# Or point to a specific target
PG_EXPORTER_URL='postgres://user:pass@localhost:5432/postgres' pg_exporter

# Access metrics
curl http://localhost:9630/metrics

# Reload configuration online (POST recommended)
curl -X POST http://localhost:9630/reload

1 - Getting Started

Follow these steps to install pg_exporter, connect to PostgreSQL, check metrics, and configure Prometheus.

You need a reachable PostgreSQL 10-19+ or pgBouncer 1.8+ instance and permission to create a user in it. For PostgreSQL 9.1-9.6, see Compatibility.

Step 1: Install

On Linux amd64, download the binary directly. For other platforms and RPM/DEB/Docker options, see the Installation guide.

VERSION=$(curl -fsSL https://api.github.com/repos/pgsty/pg_exporter/releases/latest | sed -n 's/.*"tag_name": "v\([^"]*\)".*/\1/p')
wget "https://github.com/pgsty/pg_exporter/releases/download/v${VERSION}/pg_exporter-${VERSION}.linux-amd64.tar.gz"
mkdir -p "pg_exporter-${VERSION}.linux-amd64"
tar -xf "pg_exporter-${VERSION}.linux-amd64.tar.gz" -C "pg_exporter-${VERSION}.linux-amd64"
sudo install "pg_exporter-${VERSION}.linux-amd64/pg_exporter" /usr/bin/
sudo install "pg_exporter-${VERSION}.linux-amd64/pg_exporter.yml" /etc/pg_exporter.yml

Confirm the installation:

pg_exporter --version
# pg_exporter v1.6.1 (built with go1.27.4 on linux/amd64)

Step 2: Create a Monitoring User

Create a dedicated monitoring user on the target PostgreSQL instance. Start with the built-in pg_monitor role in PostgreSQL 10+:

CREATE USER monitor WITH PASSWORD 'S3cret';
GRANT pg_monitor TO monitor;

On PostgreSQL 10–13, an administrator must also run the following grant in the exporter’s main connection database to read subscription OIDs. Granting it only in the database owning the subscription is insufficient. This does not expose the password-bearing subconninfo column. PostgreSQL 14+ needs no extra grant under standard catalog ACLs.

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

For a local test with a superuser such as postgres, you can skip this step.

Step 3: Run and Verify

Use --dry-run to check that the configuration parses correctly. Then start the exporter:

export PG_EXPORTER_URL='postgres://monitor:S3cret@localhost:5432/postgres'

pg_exporter --dry-run     # print parsed collector config, then exit
pg_exporter               # start for real, listening on :9630 by default

If you do not specify a URL, pg_exporter uses postgresql:///?sslmode=disable to connect on the same host. The URL source order is --url > PG_EXPORTER_URL > PGURL > PG_EXPORTER_URL_FILE > default. See the Deployment guide for details.

Get the metrics from another terminal:

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

You should see the three core built-in metrics:

pg_up 1              # 1 when the main target is reachable and has no fatal collector error
pg_version 170000    # version in server_version_num format
pg_in_recovery 0     # 1 on replicas, 0 on primaries

pg_up 1 indicates that the main target was reachable and had no fatal collector error during the last valid scrape. The pg_exporter.yml bundle defines 460 distinct metric names (pg_db_*, pg_table_*, pg_wal_*, and others), and outputs the metrics that apply to the server version, role, and database objects. If pg_up is 0, run pg_exporter --log.level=debug to inspect connection and fatal query errors; an interrupted initial precheck can also leave pg_up at 0 temporarily. For the difference between HTTP health checks and scrape metrics, see the API Reference.

Step 4: Hook into Prometheus

Add a scrape target in prometheus.yml:

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

Collectors cache results for their ttl. Most realtime collectors use ttl: 10. If the TTL is less than the scrape interval, each scrape gets fresh data. The cache also prevents high-frequency scrapes from overloading the database. Do not set scrape_interval below the common collector TTLs.

For Grafana, use the PostgreSQL dashboards from Pigsty, or view the live demo.

Troubleshooting

/stat, /explain, and /reload are management endpoints. In production, protect them with --web.config.file for TLS/auth, or keep them on a trusted network. See the API Reference.

Next Steps

• Monitor pgBouncer, enable auto-discovery, deploy with systemd / Docker / Kubernetes: Deployment guide
• Understand and customize collectors (GAUGE/COUNTER/HISTOGRAM, TTL, tags, version gates): Configuration reference
• Health check and primary/replica traffic routing endpoints (/up, /primary, /replica): API Reference

2 - Installation

Install pg_exporter with Pigsty, YUM/APT repositories, GitHub release packages (RPM/DEB/Tarball), or Docker images. You can also build it from source.

Repository installation uses the current package in the repository, which can lag the GitHub release. Use the versioned release artifacts below when you need v1.6.1.

Pigsty

Use Pigsty for the simplest installation. Pigsty is a complete PostgreSQL distribution with monitoring based on pg_exporter, VictoriaMetrics (Prometheus-compatible metric scraping and querying), and Grafana. It configures the metrics, alert rules, and dashboard panels for you. You do not need to configure pg_exporter separately.

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty;

Release

Download a pg_exporter package (RPM/DEB/Tarball) from the Latest GitHub Release Page:

v1.6.1 Release Files:

Install the package with your OS package manager (rpm/dpkg), or put the binary in your $PATH. Current tarballs also include pg_exporter.yml, package/pg_exporter.default, package/pg_exporter.service, and LICENSE for manual deployments.

The release page contains full SHA256 checksums in checksums.txt. The release notes also contain checksums for each version.

Repository

The pigsty-infra repository also contains the pg_exporter package. Add the repository to your system. Then install the package with your OS package manager:

YUM

For EL distributions such as RHEL, Rocky Linux, CentOS, AlmaLinux, and Oracle Linux:

sudo tee /etc/yum.repos.d/pigsty-infra.repo > /dev/null <<-'EOF'
[pigsty-infra]
name=Pigsty Infra for $basearch
baseurl=https://repo.pigsty.io/yum/infra/$basearch
enabled = 1
gpgcheck = 0
module_hotfixes=1
EOF

sudo yum makecache;
sudo yum install -y pg-exporter

APT

For Debian, Ubuntu and compatible Linux Distributions:

sudo tee /etc/apt/sources.list.d/pigsty-infra.list > /dev/null <<EOF
deb [trusted=yes] https://repo.pigsty.io/apt/infra generic main
EOF

sudo apt update;
sudo apt install -y pg-exporter

Docker

Docker Hub provides prebuilt images for the amd64 and arm64 architectures: pgsty/pg_exporter.

# Basic usage
docker run -d \
  --name pg_exporter \
  -p 9630:9630 \
  -e PG_EXPORTER_URL="postgres://user:password@host:5432/postgres" \
  pgsty/pg_exporter:1.6.1

# With custom configuration
docker run -d \
  --name pg_exporter \
  -p 9630:9630 \
  -v /path/to/pg_exporter.yml:/etc/pg_exporter.yml:ro \
  -e PG_EXPORTER_CONFIG="/etc/pg_exporter.yml" \
  -e PG_EXPORTER_URL="postgres://user:password@host:5432/postgres" \
  pgsty/pg_exporter:1.6.1

# With auto-discovery enabled
docker run -d \
  --name pg_exporter \
  -p 9630:9630 \
  -e PG_EXPORTER_URL="postgres://user:password@host:5432/postgres" \
  -e PG_EXPORTER_AUTO_DISCOVERY="true" \
  -e PG_EXPORTER_EXCLUDE_DATABASE="template0,template1" \
  pgsty/pg_exporter:1.6.1

Compatibility

The default configuration supports PostgreSQL 10-19+. For end-of-life PostgreSQL versions, use the legacy configuration bundle maintained separately on main. It is not included in binary tarballs or RPM/DEB packages; download it separately.

Legacy config example:

curl -fSL https://raw.githubusercontent.com/pgsty/pg_exporter/v1.6.1/legacy/pg_exporter.yml -o pg_exporter-legacy.yml
PG_EXPORTER_CONFIG=pg_exporter-legacy.yml pg_exporter

For PostgreSQL 9.1, use configuration from the v1.6.1 tag or main at 282e19d or later. This fixes OID 0 errors on tables without TOAST relations that caused all table-size metrics to disappear. Legacy configuration is still not bundled in binary archives or RPM/DEB packages and must be downloaded separately.

The built-in pgBouncer collectors support pgBouncer 1.8+; the SHOW STATS fields they read are available starting in 1.8.

3 - Configuration

Each business metric in pg_exporter comes from a YAML collector definition. A collector contains one SQL query and its execution conditions: version, role, tags, and predicates. It also controls caching and timeout. This page describes all collector settings.

Use one YAML file, such as the default pg_exporter.yml, or a directory of YAML files. The official default bundle combines 58 YAML files from config/ in lexicographic order: 57 collector files and one configuration reference. It defines 96 branches, 59 namespaces, and 460 distinct metric names, including disabled collectors and two unexpanded histogram definitions.

Configuration Loading

PG Exporter searches for configuration in the following order:

1. Command-line argument: --config=/path/to/config
2. Environment variable: PG_EXPORTER_CONFIG=/path/to/config
3. Current directory: ./pg_exporter.yml
4. System config file: /etc/pg_exporter.yml
5. System config directory: /etc/pg_exporter/

Directory mode details:

• The exporter loads only .yml / .yaml files in the specified directory. It does not read subdirectories.
• It merges files in lexicographic order. A later file overrides an earlier collector definition with the same top-level name.
• If the directory contains YAML files but none can be parsed, the exporter returns an error.
• If only some files fail, the exporter logs their errors and loads the valid files. Directory loading is not all-or-nothing.
• An empty individual YAML file is a valid empty configuration; reloading it clears the collectors. A reload that fails parsing preserves the previous plan and caches.

Collector Structure

Define each collector as a top-level YAML object with a unique name and the required properties:

collector_branch_name:           # Unique identifier for this collector
  name: metric_namespace         # Metric prefix (defaults to branch name)
  desc: "Collector description"  # Human-readable description
  query: |                       # SQL query to execute
    SELECT column1, column2
    FROM table

  # Execution Control
  ttl: 10                        # Cache time-to-live in seconds
  timeout: 0.1                   # Query timeout in seconds
  fatal: false                   # If true, failure fails entire scrape
  skip: false                    # If true, collector is disabled

  # Version Compatibility
  min_version: 100000            # Minimum PostgreSQL version (inclusive)
  max_version: 999999            # Maximum PostgreSQL version (exclusive)

  # Execution Tags
  tags: [cluster, primary]       # Conditions for execution

  # Predicate Queries (optional)
  predicate_queries:
    - name: "check_function"
      predicate_query: |
        SELECT EXISTS (...)

  # Metric Definitions
  metrics:
    - column_name:
        usage: GAUGE             # GAUGE, COUNTER, HISTOGRAM, LABEL, or DISCARD
        rename: metric_name      # Optional: rename the metric
        description: "Help text" # Metric description
        default: 0               # Default value if NULL
        scale: 1000              # Scale factor for the value
        bucket: [1, 10, 100]     # Bucket upper bounds for HISTOGRAM columns (strictly increasing, +Inf appended)

Validation rules:

• Each entry in metrics must define exactly one column mapping.
• Each collector must expose at least one GAUGE, COUNTER, or HISTOGRAM column.
• usage accepts only GAUGE, COUNTER, HISTOGRAM, LABEL, or DISCARD.
• A HISTOGRAM column must define bucket with finite upper bounds in strictly increasing order. The exporter appends the +Inf bucket.
• Explicit scale and default values must be finite; since v1.6.1, NaN and infinity are rejected
• Scalar queries (GAUGE / COUNTER) must return one row per label set. Since v1.6.1, duplicate scalar label sets fail that collector for the current scrape and discard its results, isolating the error from the whole scrape. Histogram-only collectors still combine multiple observations with the same labels.
• Metric and label names must follow Prometheus naming rules. The exporter checks them during loading and rejects invalid configurations immediately.
• Constant labels cannot conflict with query labels or built-in dynamic labels such as datname and query. The exporter checks this during loading. If any collector uses HISTOGRAM, le is reserved and cannot be a constant label.
• The SQL result must include every LABEL column. From v1.4.1, a missing label column fails the entire collector scrape. The collector does not emit an empty label or keep stale results. Other non-fatal collectors continue.
• In one-line inline metrics definitions, enclose description values in double quotes to prevent YAML ambiguity.

Core Configuration Elements

Collector Branch Name

The top-level key uniquely identifies a collector across the entire configuration:

pg_stat_database:  # Must be unique
  name: pg_db      # Actual metric namespace

Query Definition

The SQL query that retrieves metrics:

query: |
  SELECT 
    datname,
    numbackends,
    xact_commit,
    xact_rollback,
    blks_read,
    blks_hit
  FROM pg_stat_database
  WHERE datname NOT IN ('template0', 'template1')

Metric Types

Each column in the query result must be mapped to a metric type:

Histogram Columns (HISTOGRAM)

Version v1.4.0 adds the HISTOGRAM column type. Each query result row is one observation. The exporter groups observations by label to produce a classic Prometheus histogram snapshot. It generates three series families: <name>_bucket, <name>_count, and <name>_sum. The bucket series includes the le label and the +Inf bucket:

pg_xact_age:
  name: pg_xact_age
  desc: "Open transaction age distribution histogram"
  query: |
    SELECT datname,
           greatest(0, extract(epoch FROM now() - xact_start)) AS seconds
    FROM pg_stat_activity
    WHERE pid <> pg_backend_pid() AND backend_type = 'client backend'
      AND datname IS NOT NULL AND xact_start IS NOT NULL;
  ttl: 10
  tags: [cluster]
  metrics:
    - datname: {usage: LABEL, description: "Database name"}
    - seconds:
        usage: HISTOGRAM
        bucket: [1, 3, 10, 30, 100, 300, 1000, 3000, 10000, 30000, 100000]
        description: "Open transaction age snapshot in seconds"

Usage notes:

• This is a snapshot histogram. Each scrape rebuilds the full distribution. Bucket counts can increase or decrease, as gauges do. Use histogram_quantile() directly. Do not use rate() / increase() on _count / _sum; these operations have no meaning for a snapshot.
• By default, the exporter ignores SQL NULL observations. If you set default, it counts them with that value.
• The exporter applies scale before it assigns a bucket. As with scalar columns, scale does not apply to timestamps or booleans.
• For a reference implementation, see the default pg_xact_age collector.

Cache Control (TTL)

The ttl parameter controls result caching:

# Fast queries - minimal caching
pg_stat_activity:
  ttl: 1  # Cache for 1 second

# Expensive queries - longer caching
pg_table_bloat:
  ttl: 3600  # Cache for 1 hour

Best practices:

• Set TTL less than your scrape interval
• Use longer TTL for expensive queries
• TTL of 0 disables caching
• Collector and predicate TTLs must be finite, nonnegative, and fit in Go time.Duration. v1.5.0 rejects NaN, infinities, and excessively large values.

Timeout Control

Prevent queries from running too long:

timeout: 0.1   # 100ms default
timeout: 1.0   # 1 second for complex queries
timeout: -1    # Disable timeout (not recommended)

Omitting timeout or setting it to 0 selects the 100ms default; a finite negative value disables the query deadline. v1.5.0 rejects NaN, infinities, and positive timeouts that would overflow. The timeout covers the predicates and main query together.

Request Lifetime

Since v1.6.0, at most two metrics requests are admitted across collection, waiting, and response writing. Scrapes still run serially; one request can wait within its remaining budget, and further concurrent requests receive HTTP 503. The budget defaults to 30 seconds and is shortened by a valid, finite, positive X-Prometheus-Scrape-Timeout-Seconds header. A request canceled while waiting does not start SQL work.

After request cancellation, the exporter does not start the next collector or database. A collector already started with a positive timeout keeps its shared predicate-and-query deadline and caches a successful refresh. A negative timeout disables that deadline, so the query cancels with the request. An interrupted scrape returns 503 if the connection still accepts a response. Driver and network blocking mean these deadlines are not hard wall-clock caps; configure connect_timeout in the DSN to bound connection handshakes.

Interrupted rounds do not increment pg_exporter_scrape_error_count or pg_exporter_server_scrape_error_count, and log INFO interrupted; query error counters and fatal-query ERROR logs remain active. A real failure that overlaps request cancellation can therefore be omitted from those two round counters. Without request cancellation, connection/precheck failures and fatal query failures (including their own timeouts) still count as errors; non-fatal failures remain visible in query-level counters.

Failed refreshes keep the existing failure TTL. In particular, a fatal collector with a negative timeout caches a fatal failure when canceled; later active scrapes can count that cached failure and report pg_up 0 until a refresh succeeds. Keep positive timeouts on fatal collectors. See Scrape Lifetime for rationale.

Version Compatibility

Control which PostgreSQL versions can run this collector:

min_version: 100000  # PostgreSQL 10.0+
max_version: 140000  # Below PostgreSQL 14.0

Version numbers follow PostgreSQL server_version_num rules:

• 100000 = 10.0
• 130002 = 13.2
• 160001 = 16.1
• 190000 = 19.0
• 90600 = 9.6, relevant when using the legacy config bundle

Execution Model

Use the execution model to find why a metric is missing:

1. Planning runs on the first scrape, configuration reload, or metadata change. It checks each branch’s target type (PostgreSQL / pgBouncer), min_version / max_version, tags, and skip setting. Tags must match the server role and exporter tags. A branch that fails any check is not installed on the target. Use curl localhost:9630/explain to see each decision.
2. Scraping runs on each /metrics request. An installed collector returns cached results while they are within ttl. Otherwise, it first runs predicate_queries. A false result skips the collector for this round and increments pg_exporter_query_scrape_predicate_skip_count. If all predicates pass, the main query runs with timeout. The exporter converts the results to metrics and caches them.
3. Failure semantics: a normal collector failure affects only that collector. It increments pg_exporter_query_scrape_error_count and omits its metric group for this round. A failed collector with fatal: true fails the entire server scrape.

In v1.5.0, a successful precheck compares the username, schemas, and extensions. A change triggers replanning; adding or removing a schema or extension does not require a manual reload. Unchanged sets preserve plans and caches; replanning resets query caches and statistics.

Tag System

Tags control when and where collectors execute:

Built-in Tags

Prefixed Tags

Custom Tags

Pass custom tags to the exporter:

pg_exporter --tag="production,critical"

Then use the tags in the configuration:

expensive_metrics:
  tags: [critical]  # Only runs with 'critical' tag

Predicate Queries

Run conditional checks before the main query:

predicate_queries:
  - name: "Check pg_stat_statements"
    predicate_query: |
      SELECT EXISTS (
        SELECT 1 FROM pg_extension 
        WHERE extname = 'pg_stat_statements'
      )

The main query only executes if all predicates return true.

Metric Definition

Basic Definition

metrics:
  - numbackends:
      usage: GAUGE
      description: "Number of backends connected"

Advanced Options

metrics:
  - checkpoint_write_time:
      usage: COUNTER
      rename: write_time        # Rename metric
      scale: 0.001              # Convert ms to seconds
      default: 0                # Use 0 if NULL
      description: "Checkpoint write time in seconds"

Collector Organization

PG Exporter ships with pre-organized collectors:

Real-World Examples

Simple Gauge Collector

pg_connections:
  desc: "Current database connections"
  query: |
    SELECT 
      count(*) as total,
      count(*) FILTER (WHERE state = 'active') as active,
      count(*) FILTER (WHERE state = 'idle') as idle,
      count(*) FILTER (WHERE state = 'idle in transaction') as idle_in_transaction
    FROM pg_stat_activity
    WHERE pid != pg_backend_pid()
  ttl: 1
  metrics:
    - total: {usage: GAUGE, description: "Total connections"}
    - active: {usage: GAUGE, description: "Active connections"}
    - idle: {usage: GAUGE, description: "Idle connections"}
    - idle_in_transaction: {usage: GAUGE, description: "Idle in transaction"}

Counter with Labels

pg_table_stats:
  desc: "Table statistics"
  query: |
    SELECT 
      schemaname,
      relname AS tablename,
      n_tup_ins,
      n_tup_upd,
      n_tup_del,
      n_live_tup,
      n_dead_tup
    FROM pg_stat_user_tables
  ttl: 10
  metrics:
    - schemaname: {usage: LABEL}
    - tablename: {usage: LABEL}
    - n_tup_ins: {usage: COUNTER, description: "Tuples inserted"}
    - n_tup_upd: {usage: COUNTER, description: "Tuples updated"}
    - n_tup_del: {usage: COUNTER, description: "Tuples deleted"}
    - n_live_tup: {usage: GAUGE, description: "Live tuples"}
    - n_dead_tup: {usage: GAUGE, description: "Dead tuples"}

Version-Specific Collector

pg_wal_stats:
  desc: "WAL statistics (PG 14–17)"
  min_version: 140000
  max_version: 180000
  query: |
    SELECT 
      wal_records,
      wal_bytes,
      wal_buffers_full,
      wal_write_time,
      wal_sync_time
    FROM pg_stat_wal
  ttl: 10
  tags: [cluster]
  metrics:
    - wal_records: {usage: COUNTER}
    - wal_bytes: {usage: COUNTER}
    - wal_buffers_full: {usage: COUNTER}
    - wal_write_time: {usage: COUNTER, scale: 0.001}
    - wal_sync_time: {usage: COUNTER, scale: 0.001}

Extension-Dependent Collector

pg_stat_statements_metrics:
  desc: "Query performance statistics"
  tags: [extension:pg_stat_statements]
  query: |
    SELECT 
      sum(calls) as total_calls,
      sum(total_exec_time) as total_time,
      sum(mean_exec_time * calls) / sum(calls) as mean_time
    FROM pg_stat_statements
  ttl: 60
  metrics:
    - total_calls: {usage: COUNTER}
    - total_time: {usage: COUNTER, scale: 0.001}
    - mean_time: {usage: GAUGE, scale: 0.001}

Custom Collectors

Creating Your Own Metrics

1. Create a new YAML file in your config directory:

# /etc/pg_exporter/custom_metrics.yml
app_metrics:
  desc: "Application-specific metrics"
  query: |
    SELECT 
      (SELECT count(*) FROM users WHERE active = true) as active_users,
      (SELECT count(*) FROM orders WHERE created_at > NOW() - '1 hour'::interval) as recent_orders,
      (SELECT avg(processing_time) FROM jobs WHERE completed_at > NOW() - '5 minutes'::interval) as avg_job_time
  ttl: 30
  metrics:
    - active_users: {usage: GAUGE, description: "Currently active users"}
    - recent_orders: {usage: GAUGE, description: "Orders in last hour"}
    - avg_job_time: {usage: GAUGE, description: "Average job processing time"}

2. Test your collector:

pg_exporter --explain --config=/etc/pg_exporter/

Conditional Metrics

Use predicate queries for conditional metrics:

partition_metrics:
  desc: "Partitioned table metrics"
  predicate_queries:
    - name: "Check if partitioning is used"
      predicate_query: |
        SELECT EXISTS (
          SELECT 1 FROM pg_class 
          WHERE relkind = 'p' LIMIT 1
        )
  query: |
    SELECT 
      parent.relname as parent_table,
      count(*) as partition_count,
      sum(pg_relation_size(child.oid)) as total_size
    FROM pg_inherits
    JOIN pg_class parent ON parent.oid = pg_inherits.inhparent
    JOIN pg_class child ON child.oid = pg_inherits.inhrelid
    WHERE parent.relkind = 'p'
    GROUP BY parent.relname
  ttl: 300
  metrics:
    - parent_table: {usage: LABEL}
    - partition_count: {usage: GAUGE}
    - total_size: {usage: GAUGE}

Performance Optimization

Query Optimization Tips

1. Use appropriate TTL values:

   • Fast queries: 1-10 seconds
   • Medium queries: 10-60 seconds
   • Expensive queries: 300-3600 seconds

2. Set realistic timeouts:

   • Default: 100ms
   • Complex queries: 500ms-1s
   • Never disable timeout in production

3. Use cluster-level tags:

   tags: [cluster]  # Run once per cluster, not per database

4. Disable expensive collectors:

   pg_table_bloat:
     skip: true  # Disable if not needed

Monitoring Collector Performance

Check collector execution statistics:

# View collector statistics (hit / error / skip counters and durations)
curl http://localhost:9630/stat

# Per-collector duration and error counters, by datname/query
curl -s http://localhost:9630/metrics | grep -E 'pg_exporter_query_scrape_(duration|error_count)'

Metric and Alert Upgrade Checks

When upgrading the exporter, merge and deploy the matching collector YAML. Replacing only the binary does not apply SQL, label, or state-code corrections. For instances managed by Pigsty, also verify that the deployed configuration contains these definitions. After a PostgreSQL major-version upgrade, check the newly selected collector branches.

• Exporter v1.6.0 → v1.6.1: built-in SQL metric names, label keys, types, buckets, and routes are unchanged. pg_table emits age = 0 for relfrozenxid = 0 (such as partitioned parents), and zero-fills missing index/table estimates to avoid losing valid statistics or producing NaN. pg_table_size excludes pg_temp* and pg_toast*. Duplicate label rows in custom scalar queries fail only that collector, and scale / default must be finite.
• Exporter v1.5.0 → v1.6.0: bundled SQL metric names, label keys, types, and units stay unchanged. Cross-database progress metrics now emit the numeric OID as relname for user relations in other databases while still resolving names for the current database and shared catalogs; dashboards retain datname and pid. Interrupted rounds no longer increment target error counters, and HTTP health is determined separately from scrape success.
• Exporter v1.4.1 → v1.5.0: bundled SQL metric names, types, and units stay unchanged, but pg_sub_* adds datname and pg_recv_state corrects its state codes. Review joins/aggregations for subscriptions with the same name in different databases, and Grafana value mappings.
• PG18 → PG19: existing metrics are not removed or renamed, but pg_sub_sync_error_count broadens to table plus sequence synchronization errors, and pg_subrel_count includes sequences. pg_sub_has_worker distinguishes a subscription row from a running apply worker; the presence of pg_sub_id alone is insufficient.
• Crossing PG17 / PG18: some pg_bgwriter_* metrics need to move to pg_checkpointer_* or backend-filtered I/O metrics. From PG18 onward, pg_wal_write, pg_wal_sync, pg_wal_write_time, and pg_wal_sync_time need to move to pg_io_*{object="wal"}, with corresponding label aggregation changes. See the metric-by-metric migration table.

See v1.6.1 release notes, v1.6.0 release notes, and the PG19 metrics matrix. PG19 support first shipped in v1.3.0; acceptance evidence covers 19 RC1. These notes do not imply runtime acceptance of every dashboard.

Before and after deployment, inspect /metrics, /explain, /stat, pg_exporter_query_scrape_error_count, and the logs. Evaluate the actual dashboard, recording-rule, and alert expressions, checking returned series, labels, units, and state mappings. Use promtool check rules for syntax and promtool test rules for both normal and missing-series input. HTTP 200, up == 1, or pg_up == 1 does not prove that every expected metric exists; an empty vector is not a healthy zero.

For PG19 targets expected to expose the bundled WAL collector, use this per-target missing-metric check with for: 5m in the alert rule:

(pg_up{job="pg19"} == 1)
unless on (job, instance)
pg_wal_bytes{job="pg19"}

job="pg19" is an example: replace it with the actual target selector and include any additional identity labels in matching. Monitor up and pg_up failures separately. Scope absence checks by version, primary/replica role, and expected objects; for example, a primary should not require pg_recovery_state_*. Do not mask missing input with an unconditional or vector(0). Fleet-wide absent(metric) also misses one target’s disappearance while other targets still emit data. See the complete missing-metric rule.

Troubleshooting Configuration

Validate Configuration

# Dry run - shows parsed configuration
pg_exporter --dry-run

# Explain - shows planned queries
pg_exporter --explain

Common Issues

Debug Logging

Enable debug logging to troubleshoot:

pg_exporter --log.level=debug

4 - API Reference

pg_exporter provides four types of HTTP endpoints: metrics, health checks, traffic routing, and operational management. The default listen port is :9630. The following table lists all endpoints:

Health and routing endpoints return the cached state from background probes: primary, replica, down, starting, or unknown. They do not query the database for each HTTP request. In v1.5.0, each response reads one atomic state snapshot, so its HTTP status and body always describe the same state. The cached state can still lag behind the database. A successful PgBouncer probe maps to primary; it does not describe the role of its PostgreSQL backend.

Metrics Endpoint

GET /metrics

This endpoint returns all collected metrics in Prometheus format.

Request

curl http://localhost:9630/metrics

Response

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

# HELP pg_version server version number
# TYPE pg_version gauge
pg_version 140000

# HELP pg_in_recovery server is in recovery mode? 1 for yes 0 for no
# TYPE pg_in_recovery gauge
pg_in_recovery 0

# HELP pg_exporter_build_info A metric with a constant '1' value labeled with version, revision, branch, goversion, builddate, goos, and goarch from which pg_exporter was built.
# TYPE pg_exporter_build_info gauge
pg_exporter_build_info{version="v1.6.1",branch="main",revision="<git-sha>",builddate="<build-date>",goversion="go1.27.4",goos="linux",goarch="amd64"} 1

# ... additional metrics

Response Format

Metrics follow the Prometheus exposition format:

# HELP <metric_name> <description>
# TYPE <metric_name> <type>
<metric_name>{<label_name>="<label_value>",...} <value> <timestamp>

Since v1.6.0, at most two metrics requests are admitted across collection, waiting, and response writing. Scrapes still run serially; one request can wait within its remaining budget, and further concurrent requests receive HTTP 503. The budget defaults to 30 seconds and is shortened by a valid, finite, positive X-Prometheus-Scrape-Timeout-Seconds header. A request canceled while waiting does not start SQL work.

After request cancellation, the exporter does not start the next collector or database. A collector already started with a positive timeout keeps its shared predicate-and-query deadline and caches a successful refresh. A negative timeout disables that deadline, so the query cancels with the request. An interrupted scrape returns 503 if the connection still accepts a response. Driver and network blocking mean these deadlines are not hard wall-clock caps; configure connect_timeout in the DSN to bound connection handshakes.

Interrupted rounds do not increment pg_exporter_scrape_error_count or pg_exporter_server_scrape_error_count, and log INFO interrupted; query error counters and fatal-query ERROR logs remain active. A real failure that overlaps request cancellation can therefore be omitted from those two round counters. Without request cancellation, connection/precheck failures and fatal query failures (including their own timeouts) still count as errors; non-fatal failures remain visible in query-level counters.

Failed refreshes keep the existing failure TTL. In particular, a fatal collector with a negative timeout caches a fatal failure when canceled; later active scrapes can count that cached failure and report pg_up 0 until a refresh succeeds. Keep positive timeouts on fatal collectors. See Scrape Lifetime for rationale.

Self-Monitoring Metrics

Built-in PostgreSQL metrics default to the pg prefix; PgBouncer uses pgbouncer. --namespace changes these prefixes, and invalid namespaces are rejected at startup. It does not rename metrics defined in YAML.

These series also receive configured constant labels. On pg_exporter_build_info, build values for version, revision, branch, builddate, goversion, goos, and goarch take precedence over user labels. Invalid labels on built-in database/query samples cause a warning and that sample is skipped to avoid a panic. Cumulative database/collector counters are exposed as Gauges. Replanning a server resets collector statistics; configuration reload also triggers replanning. Recreating a database connection object resets that database’s statistics.

--disable-intro suppresses all built-in metrics in this table, including pg_up. YAML metrics, Go/process metrics, and HTTP health endpoints remain available.

On interruption, pg_up preserves the primary target’s previous availability state, or stays 1 if the current precheck already succeeded. If the first precheck is interrupted before succeeding, it remains 0 and recovers on a later successful scrape. Interrupted child databases follow the same per-database rule without incrementing primary-target error counters.

Health Checks

Health endpoints provide multiple ways to monitor PG Exporter and the target database state.

GET /up

After initialization, HTTP health state is updated only by the once-per-second background probe. Slow scrapes do not hold the probe lock or overwrite newer probe results. HTTP health requests read the snapshot without running SQL. pg_up and pg_in_recovery remain scrape metrics: a fatal collector failure can set pg_up to 0 while /up still returns 200 if the database is reachable. Connection pool limits are three for the PostgreSQL main target, two for PgBouncer, and one per discovered database.

Response Codes

Example

# Check whether the service is healthy
curl -I http://localhost:9630/up

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

GET /health

Alias of /up with identical behavior.

curl http://localhost:9630/health

GET /liveness and GET /readiness

These aliases use the same handler and behavior as /up. Use them for Kubernetes probes:

livenessProbe:
  httpGet: { path: /liveness, port: 9630 }
  initialDelaySeconds: 30
  periodSeconds: 10
readinessProbe:
  httpGet: { path: /readiness, port: 9630 }
  initialDelaySeconds: 5
  periodSeconds: 5

Both endpoints return 503 when the target database is unreachable. To prevent a database failure from restarting the exporter Pod, use a TCP liveness probe on the listen port.

Traffic Routing

Load balancers and proxies use these endpoints to route traffic by server role.

GET /primary

Check whether the server is a primary instance.

Response Codes

Aliases

• /leader
• /master
• /read-write
• /rw

Example

# Check whether the server is primary
curl -I http://localhost:9630/primary

# Use in HAProxy
backend pg_primary
  option httpchk GET /primary
  server pg1 10.0.0.1:5432 check port 9630
  server pg2 10.0.0.2:5432 check port 9630

GET /replica

Check whether the server is a replica instance.

Response Codes

Aliases

• /standby
• /read-only
• /ro

/slave remains compatible, but /replica is the preferred name.

Example

# Check whether the server is a replica
curl -I http://localhost:9630/replica

# Use in a load balancer
backend pg_replicas
  option httpchk GET /replica
  server pg2 10.0.0.2:5432 check port 9630
  server pg3 10.0.0.3:5432 check port 9630

GET /read

Check whether the server can handle read traffic. Both primaries and replicas may return success.

Response Codes

Example

# Check whether the server can serve reads
curl -I http://localhost:9630/read

# Route reads to any healthy server
backend pg_read
  option httpchk GET /read
  server pg1 10.0.0.1:5432 check port 9630
  server pg2 10.0.0.2:5432 check port 9630
  server pg3 10.0.0.3:5432 check port 9630

Operational Endpoints

GET /reload / POST /reload

Reload configuration without restarting the exporter.

Request

# POST is recommended
curl -X POST http://localhost:9630/reload

# GET remains supported for compatibility
curl http://localhost:9630/reload

Response

server reloaded

Response Codes

Use Cases

• Update collector definitions
• Change query parameters
• Modify cache TTL values
• Add or remove collectors

GET /explain

Display the collectors selected in the primary target’s current plan. Predicates run during refresh and are not evaluated by this endpoint.

Request

curl http://localhost:9630/explain

Response

##
# SYNOPSIS
#       pg.pg_primary_only_*
#
# DESCRIPTION
#       PostgreSQL basic information (on primary)
#
# OPTIONS
#       Tags       [cluster, primary]
#       TTL        1
#       Priority   110
#       Timeout    100ms
#       Fatal      true
#       Version    100000 ~ higher
#       Source     pg_exporter.yml

...

GET /stat

Show runtime statistics, including collector execution times and success/error counters.

Request

curl http://localhost:9630/stat

Response

name                     total      hit        error      skip       metric     ttl/s  duration/ms
pg                       12         0          0          0          15         1      4.231000
pg_db                    12         11         0          0          28         10     0.153000
pg_activity              12         0          1          0          8          0      7.842000
...

Use this endpoint to identify slow or failed collectors.

Using with Load Balancers

HAProxy Example

# Primary backend for write traffic
backend pg_primary
  mode tcp
  option httpchk GET /primary
  http-check expect status 200
  server pg1 10.0.0.1:5432 check port 9630 inter 3000 fall 2 rise 2
  server pg2 10.0.0.2:5432 check port 9630 inter 3000 fall 2 rise 2 backup

# Replica backend for read traffic
backend pg_replicas
  mode tcp
  balance roundrobin
  option httpchk GET /replica
  http-check expect status 200
  server pg2 10.0.0.2:5432 check port 9630 inter 3000 fall 2 rise 2
  server pg3 10.0.0.3:5432 check port 9630 inter 3000 fall 2 rise 2

# Read backend for any server that can handle reads
backend pg_read
  mode tcp
  balance leastconn
  option httpchk GET /read
  http-check expect status 200
  server pg1 10.0.0.1:5432 check port 9630 inter 3000 fall 2 rise 2
  server pg2 10.0.0.2:5432 check port 9630 inter 3000 fall 2 rise 2
  server pg3 10.0.0.3:5432 check port 9630 inter 3000 fall 2 rise 2

A Note on Nginx

Open-source Nginx does not support active HTTP health checks outside the traffic connection. The health_check directive requires NGINX Plus. PostgreSQL traffic also requires the stream module instead of http proxying. To route PostgreSQL traffic by role, use HAProxy as shown above, or a solution such as Patroni + vip-manager.

5 - Deployment

Use this page to deploy pg_exporter in production. It describes process arguments, environment variables, monitoring users, credentials, and deployment with systemd, Docker, or Kubernetes. It also describes pgBouncer monitoring, auto-discovery, Prometheus scrapes, and alerts.

The exporter reads process configuration from two sources. Command-line arguments take precedence:

1. Command-line arguments (--url, --config, …)
2. Environment variables (every flag has a corresponding PG_EXPORTER_* variable)

YAML collector definitions control metric collection. The default file is /etc/pg_exporter.yml. You can also use a configuration directory. See the Configuration reference.

Command-Line Arguments

pg_exporter \
  --url="postgres://monitor:S3cret@localhost:5432/postgres" \
  --config="/etc/pg_exporter.yml" \
  --web.listen-address=":9630" \
  --auto-discovery \
  --log.level="info"

The full flag list from pg_exporter --help:

Flags:
  -h, --[no-]help                Show context-sensitive help (also try --help-long and --help-man).
  -u, --url=URL                  postgres target url
  -c, --config=CONFIG            path to config dir or file
      --web.listen-address=:9630 ...
                                 Addresses on which to expose metrics and web interface. Repeatable for multiple addresses. Examples: `:9100` or `[::1]:9100` for http, `vsock://:9100` for vsock
      --web.config.file=""       Path to configuration file that can enable TLS or authentication. See: https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md
  -l, --label=""                 constant labels: comma separated list of label=value pair ($PG_EXPORTER_LABEL)
  -t, --tag=""                   tags, comma separated list of server tag ($PG_EXPORTER_TAG)
  -C, --[no-]disable-cache       force not using cache ($PG_EXPORTER_DISABLE_CACHE)
  -m, --[no-]disable-intro       disable internal/exporter self-monitoring metrics (only expose query metrics) ($PG_EXPORTER_DISABLE_INTRO)
  -a, --[no-]auto-discovery      automatically scrape all databases on the target server ($PG_EXPORTER_AUTO_DISCOVERY)
  -x, --exclude-database="template0,template1,postgres"
                                 excluded databases when auto-discovery is enabled ($PG_EXPORTER_EXCLUDE_DATABASE)
  -i, --include-database=""      included databases when auto-discovery is enabled ($PG_EXPORTER_INCLUDE_DATABASE)
  -n, --namespace=""             prefix of built-in metrics, (pg|pgbouncer) by default ($PG_EXPORTER_NAMESPACE)
  -f, --[no-]fail-fast           fail fast instead of waiting during start-up ($PG_EXPORTER_FAIL_FAST)
  -T, --connect-timeout=100      connect timeout in ms, 100 by default ($PG_EXPORTER_CONNECT_TIMEOUT)
  -P, --web.telemetry-path="/metrics"
                                 URL path under which to expose metrics ($PG_EXPORTER_TELEMETRY_PATH)
  -D, --[no-]dry-run             dry run and print raw configs
  -E, --[no-]explain             explain server planned queries
      --log.level="info"         log level: debug|info|warn|error
      --log.format="logfmt"      log format: logfmt|json
      --[no-]version             Show application version.

These behaviors affect deployment:

• Startup policy: startup is non-blocking by default. If the database is unreachable, HTTP endpoints still start. A background probe retries until recovery. To fail when the database is unreachable, set --fail-fast. For example, use this option when systemd or an orchestrator controls restarts.
• Telemetry path validation: --web.telemetry-path rejects empty paths, conflicts with built-in endpoints, and non-canonical paths such as //metrics. v1.5.0 also verifies that the active HTTP mux selects the metrics handler, preventing escaped paths from returning the landing page or a redirect. Prefer an unescaped path such as /metrics.

Connection URL Sources

The exporter checks these sources in order, skipping empty command-line and environment values:

1. --url / -u command-line argument
2. PG_EXPORTER_URL environment variable
3. PGURL environment variable
4. Content of the file pointed to by PG_EXPORTER_URL_FILE (fits container Secret mounts)
5. Default postgresql:///?sslmode=disable (local-first, fits same-host deployment)

Once PG_EXPORTER_URL_FILE is selected, an unreadable, empty, or whitespace-only file prevents startup; it does not fall back to the local default.

v1.5.0 validates URLs, percent escapes, and query parameter names strictly. Names cannot be empty or contain whitespace or =, and URLs cannot contain unescaped #. Invalid input stops startup with fixed diagnostics that omit the original connection string, preventing password disclosure or silent loss of TLS settings. Logs redact userinfo passwords and password= / sslpassword= values in valid URLs. Hostless URLs such as postgresql://?host=/var/run/postgresql retain // during normalization.

If the URL omits sslmode, the exporter appends sslmode=disable. At startup, it also clears libpq service-file environment variables, such as PGSERVICE / PGSERVICEFILE, and logs this action. Service files can override an explicit connection target. Clearing these variables ensures that the exporter connects to the URL shown in the log.

Monitoring User and Credentials

Create the Monitoring User

CREATE ROLE monitor WITH LOGIN PASSWORD 'S3cret' CONNECTION LIMIT 5;
GRANT pg_monitor TO monitor;   -- built-in monitoring role (PostgreSQL 10+)

On PostgreSQL 10–13, an administrator must also run the following grant in the exporter’s main connection database to read subscription OIDs. Granting it only in the database owning the subscription is insufficient. This does not expose the password-bearing subconninfo column. PostgreSQL 14+ needs no extra grant under standard catalog ACLs.

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

Size CONNECTION LIMIT for the number of discovered databases. A limit that is too low can prevent connections to additional databases. Keep a connection limit to prevent connection exhaustion if the configuration is incorrect. The exporter normally uses one to a few connections. With auto-discovery, it uses one connection per database.

Manage Passwords with .pgpass

Remove the password from the URL. Use libpq’s .pgpass file to supply it:

# Create as the OS user that runs the exporter
echo "localhost:5432:*:monitor:S3cret" > ~/.pgpass
chmod 600 ~/.pgpass

# URL without password
PG_EXPORTER_URL='postgres://monitor@localhost:5432/postgres'

TLS for the Database Connection

PG_EXPORTER_URL='postgres://monitor:[email protected]:5432/postgres?sslmode=verify-full&sslrootcert=/etc/pki/ca.crt'

Protecting the HTTP Port

The HTTP port provides /metrics and the management endpoints /reload, /explain, and /stat. Anyone with access to the port can read configuration and runtime state, or start a reload. On a shared network, enable TLS / Basic Auth with --web.config.file (exporter-toolkit web configuration). You can also restrict access through a firewall or reverse proxy.

Systemd Deployment (RPM/DEB packages)

RPM/DEB packages include a service unit and an environment file. After installation, edit the environment file and start the service:

# /usr/lib/systemd/system/pg_exporter.service
[Unit]
Description=Prometheus exporter for PostgreSQL/Pgbouncer server metrics
Documentation=https://pigsty.io/docs/pg_exporter
After=network.target

[Service]
EnvironmentFile=-/etc/default/pg_exporter
User=prometheus
ExecStart=/usr/bin/pg_exporter $PG_EXPORTER_OPTS
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure

[Install]
WantedBy=multi-user.target

Environment file /etc/default/pg_exporter (package defaults):

PG_EXPORTER_URL='postgres://:5432/postgres?sslmode=disable'
PG_EXPORTER_CONFIG=/etc/pg_exporter.yml
PG_EXPORTER_LABEL=""
PG_EXPORTER_TAG=""
PG_EXPORTER_DISABLE_CACHE=false
PG_EXPORTER_AUTO_DISCOVERY=true
PG_EXPORTER_EXCLUDE_DATABASE="template0,template1,postgres"
PG_EXPORTER_INCLUDE_DATABASE=""
PG_EXPORTER_NAMESPACE="pg"
PG_EXPORTER_FAIL_FAST=false
PG_EXPORTER_CONNECT_TIMEOUT=100
PG_EXPORTER_TELEMETRY_PATH="/metrics"
PG_EXPORTER_OPTS='--log.level=info'

Each command-line flag has an environment variable. Add the variables you need, such as PG_EXPORTER_DISABLE_INTRO. The file uses the noreplace package option. Upgrades do not overwrite your changes.

Common operations:

sudo systemctl daemon-reload               # refresh systemd after upgrading the unit
sudo systemctl enable --now pg_exporter    # start and enable at boot
sudo systemctl status pg_exporter          # check status
sudo systemctl reload pg_exporter          # reload collector configuration through SIGHUP without restarting
journalctl -u pg_exporter -f               # follow logs
curl -X POST localhost:9630/reload         # reload collector configuration over HTTP

Docker Deployment

docker run -d \
  --name pg_exporter \
  --restart unless-stopped \
  -p 9630:9630 \
  -e PG_EXPORTER_URL="postgres://monitor:S3cret@host:5432/postgres" \
  pgsty/pg_exporter:1.6.1

Docker Compose:

services:
  pg_exporter:
    image: pgsty/pg_exporter:1.6.1
    container_name: pg_exporter
    restart: unless-stopped
    ports:
      - "9630:9630"
    environment:
      - PG_EXPORTER_URL=postgres://monitor:S3cret@postgres:5432/postgres
    volumes:
      - ./pg_exporter.yml:/etc/pg_exporter.yml:ro   # optional: custom collector config
    depends_on:
      - postgres

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: pg-exporter
  labels: { app: pg-exporter }
spec:
  replicas: 1
  selector:
    matchLabels: { app: pg-exporter }
  template:
    metadata:
      labels: { app: pg-exporter }
    spec:
      containers:
      - name: pg-exporter
        image: pgsty/pg_exporter:1.6.1
        ports:
        - containerPort: 9630
        env:
        - name: PG_EXPORTER_URL
          valueFrom:
            secretKeyRef:
              name: pg-credentials
              key: connection-url
        livenessProbe:
          httpGet: { path: /liveness, port: 9630 }
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet: { path: /readiness, port: 9630 }
          initialDelaySeconds: 5
          periodSeconds: 5
        resources:
          requests: { cpu: 100m, memory: 128Mi }
          limits: { cpu: 200m, memory: 256Mi }
---
apiVersion: v1
kind: Service
metadata:
  name: pg-exporter
  labels: { app: pg-exporter }
spec:
  ports:
  - { port: 9630, targetPort: 9630, name: metrics }
  selector: { app: pg-exporter }

To keep the connection string out of environment variables, set PG_EXPORTER_URL_FILE to a Secret-mounted file.

Auto-Discovery

Auto-discovery is enabled by default. It lets one exporter instance monitor every database in the target PostgreSQL instance:

pg_exporter --auto-discovery \
  --exclude-database="template0,template1,postgres" \
  --include-database=""
# The exclusion list above is the default; set --include-database for allowlist mode.

Behavior:

• Cluster-level collectors (tags: [cluster]) run once on the primary connection
• Database-level collectors run on every discovered database, with metrics distinguished by the datname label
• Newly created or dropped databases are added or removed during subsequent prechecks
• v1.5.0 uses lib/pq to resolve the actual database identity. When replacing a database name, it removes conflicting dbname / database query parameters, and v1.6.1 also removes conflicting service=. It preserves special characters to prevent discovered connections from converging on the same database. Removing or replacing child targets waits for active collection before closing old pools.
• Database scrapes remain sequential. Allow enough scrape timeout for prechecks and queries across all databases; in v1.6.0, a canceled request does not start subsequent databases or collectors
• The PostgreSQL main connection pool uses up to three connections, and each discovered database uses one connection. The PgBouncer connection pool uses up to two connections to separate serial scrapes from the independent health probe

Monitoring pgBouncer

Set the database name in the URL to pgbouncer. This name activates pgBouncer mode:

PG_EXPORTER_URL='postgres://stats_user:S3cret@localhost:6432/pgbouncer' pg_exporter

In pgBouncer mode, the exporter uses the pgbouncer metric prefix. It runs only pgBouncer collectors, such as SHOW STATS / SHOW POOLS. Usually, you run one exporter for PostgreSQL and another for pgBouncer. Give each exporter a different port.

Prometheus Scraping and Alerting

Scrape Configuration

scrape_configs:
  - job_name: 'postgresql'
    scrape_interval: 15s
    static_configs:
      - targets: ['pg-1:9630', 'pg-2:9630', 'pg-3:9630']

Kubernetes service discovery:

scrape_configs:
  - job_name: 'postgresql'
    kubernetes_sd_configs:
      - role: pod
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_label_app]
        regex: pg-exporter
        action: keep
      - source_labels: [__meta_kubernetes_pod_ip]
        target_label: __address__
        replacement: ${1}:9630

Set the scrape interval equal to or greater than the common collector ttl. Most collectors in the default bundle use 10 seconds. More frequent scrapes return cached results until the TTL expires.

Alert Rules

The following rules use available metrics:

groups:
  - name: pg_exporter
    rules:
      # Exporter process unreachable
      - alert: PgExporterDown
        expr: up{job="postgresql"} == 0
        for: 1m
        labels: { severity: critical }
        annotations:
          summary: "pg_exporter down ({{ $labels.instance }})"

      # Exporter alive but cannot reach the database
      - alert: PostgreSQLDown
        expr: pg_up == 0
        for: 1m
        labels: { severity: critical }
        annotations:
          summary: "PostgreSQL connection failed ({{ $labels.instance }})"

      # Overall scrape duration abnormal (unit: seconds)
      - alert: PgExporterSlowScrape
        expr: pg_exporter_scrape_duration > 10
        for: 5m
        labels: { severity: warning }
        annotations:
          summary: "pg_exporter slow scrape ({{ $labels.instance }})"

      # A specific collector keeps failing (locate by datname/query)
      - alert: PgExporterQueryError
        expr: increase(pg_exporter_query_scrape_error_count[10m]) > 0
        for: 10m
        labels: { severity: warning }
        annotations:
          summary: "Collector {{ $labels.query }} keeps failing on {{ $labels.datname }}"

Role-Based Traffic Routing

Use /primary, /replica, and /read as health probes for HAProxy or similar load balancers. These endpoints support primary/replica routing to separate read and write traffic. For endpoint behavior and a complete HAProxy example, see the API Reference.

Open-source Nginx does not support active HTTP health checks outside the traffic connection. The health_check directive requires NGINX Plus. To route PostgreSQL traffic by role, use HAProxy or a solution such as Patroni + vip-manager.

6 - Release Notes

The latest stable pg_exporter release is v1.6.1.

v1.6.1

Released on 2026-11-11.

PG Exporter v1.6.1 is a maintenance release that corrects table statistics, isolates collector errors that could break a whole scrape, and fixes connection edge cases. The build toolchain moves to Go 1.27.4, while the PostgreSQL driver remains lib/pq 1.12.3. Built-in SQL metric names, label keys, types, buckets, CLI flags, and HTTP routes are unchanged.

Fixes and Improvements

• Isolate duplicate scalar rows: if a GAUGE or COUNTER query returns multiple rows with the same labels, mark that collector as failed and discard its output before Prometheus gathers it. Other collectors continue after nonfatal failures; fatal: true retains its semantics. Histogram-only collectors still merge same-label observations into one snapshot distribution. Cross-collector metric conflicts still require configuration fixes.
• Correct partitioned and unindexed table statistics: all four pg_table version branches emit age = 0 for relfrozenxid = 0, including partitioned parents, instead of 2147483647. tbl_scan, tup_read, and n_tup_mod individually coalesce nulls before addition, so missing index counts no longer suppress valid sequential-scan statistics. Null live/dead/modified row estimates become zero rather than NaN.
• Avoid temporary-table size failures: pg_table_size excludes pg_temp* and pg_toast*, avoiding reads of other sessions’ temporary tables and separate TOAST accounting. The source tag also fixes OID 0 errors in PostgreSQL 9.1 legacy configuration for tables without TOAST, preventing loss of the entire table-size metric set. Download legacy configuration separately.
• Correct activity durations and TimescaleDB identifiers: pg_activity clamps negative durations to zero when state, transaction, or session timestamps exceed the query time reference. Disabled-by-default pg_tsdb_hypertable correctly quotes schema/table names containing uppercase or special characters. HELP text is aligned for transaction/session start, index build stages, checkpoint counts, and table main-fork sizes.
• Fix connection URLs and log redaction: hostless URLs such as postgresql://?host=/var/run/postgresql retain // during normalization so lib/pq recognizes them. Auto-discovery removes conflicting service= when selecting a child database. Logs also redact sslpassword=.
• Improve connection-pool cleanup: after removing or replacing child targets, auto-discovery waits for active collection before closing old pools. Closing clears pool references and safely handles uninitialized or already-closed pools. Reload still reuses existing pools and clears collection plans rather than recreating all child connections.
• Strengthen validation and built-in metric handling: configuration rejects nonfinite scale / default, and startup rejects invalid --namespace. Invalid built-in labels, such as non-UTF-8 database names, produce warnings and skip samples instead of panicking. Constant user labels cannot override reserved build fields such as version and revision.
• Fix diagnostics and direct-call edge cases: HTML explain pages display predicate cache TTL correctly. Direct collector calls execute queries for cold caches or zero TTL even without a server scrape timestamp. Explicit Server.Plan(...) preserves same-name versioned queries by branch key.
• Update builds and service management: packaged systemd units add ExecReload for systemctl reload pg_exporter. Standalone Docker builds accept version, branch, revision, and build-date arguments; make docker-build supplies them. Ordinary builds without arguments retain HEAD / unknown revision/date values. The toolchain moves to Go 1.27.4 with routine dependency updates.

Upgrade Notes

1. Upgrade the binary and merge collector YAML. Packages preserve locally modified /etc/pg_exporter.yml and /etc/default/pg_exporter. Deploy the new SQL to obtain table statistics, activity duration, and TimescaleDB fixes. Default configuration still has 58 YAML files, 96 branches, 59 namespaces, and 460 deduplicated metric definitions.
2. Review custom collectors. Scalar queries need one row per label set; scale and default must be finite. Histogram-only queries can still return multiple observations per label set. Partitioned-parent freeze age is now zero, and unindexed table totals or previously NaN row estimates may change.
3. Update service units and restart after upgrading the binary. Run sudo systemctl daemon-reload after installing the new unit, then sudo systemctl restart pg_exporter for a new binary or process arguments. Later YAML-only changes can use sudo systemctl reload pg_exporter or POST /reload.
4. Download legacy YAML separately for PostgreSQL 9.1–9.6. Use configuration from v1.6.1 or main at 282e19d or later. Binary archives and RPM/DEB packages still bundle only PostgreSQL 10+ defaults.

When upgrading from v1.5.0 or earlier, also review v1.6.0 health probes, scrape budgets, and cross-database progress labels, plus v1.5.0 subscription labels, receiver states, and PostgreSQL 10–13 privileges. See the full metric compatibility matrix.

Verification Scope

The v1.6.1 tag points to d0dead1. CI and Release workflows passed module/generated-config checks, the full race suite, Go 1.21 HTTP mux compatibility, go vet, six-target cross-compilation, container checks, and package/checksum checks. Regressions cover duplicate scalar isolation, direct cold-cache/zero-TTL collection, namespaces/build labels, hostless URLs, service= removal, sslpassword redaction, predicate HTML rendering, finite configuration values, and SQL invariants.

Release acceptance covers 12 public artifacts and checksums, amd64/arm64 Docker images, ARM64 DEB installation on Debian 12, ARM64 RPM installation on Rocky Linux 9, and real non-superuser scrapes against PostgreSQL 10–18 and 19 RC1 primaries, PostgreSQL 18 and 19 RC1 streaming replicas, PgBouncer 1.26.1, and PostgreSQL 9.1–9.6 with separate legacy configuration. Scenarios include discovery/database removal, HTTP/SIGHUP reload, pg_stat_statements, unindexed/partitioned/temporary tables, and active transactions. Legacy acceptance does not imply backporting modern pg_temp* filtering or COALESCE fixes. Windows, Linux ppc64le, and Intel macOS were covered only by builds/checksums; package container checks do not prove real systemd startup. PostgreSQL 19 evidence is limited to RC1, not all later builds or production workloads. Experimental snort is not included in v1.6.1.

SHA-256 Checksums

SHA256 checksums

GitHub release · SHA256 checksums · Full changes · Collector documentation

v1.6.0

Release date: 2026-11-09.

PG Exporter v1.6.0 decouples health probing from metrics scrapes, bounds overlapping scrapes and waits, preserves completed bounded refreshes when a client disconnects, and fixes cross-database progress labels. It also adds container trust roots and refreshes dependencies. The release builds with Go 1.27.3 and lib/pq 1.12.3.

Fixes and Improvements

• Independent health probe: slow metrics scrapes no longer block the background probe, and finishing scrapes no longer overwrite newer reachability or role observations. After initialization, HTTP health state is written only by the probe; pg_up and pg_in_recovery still reflect scrape outcomes. /up can return HTTP 200 while a fatal collector sets pg_up to 0 if the database remains reachable.
• Bounded scrape admission: at most two metrics requests are admitted across collection, waiting, and response writing. Scrapes still run serially; one request can wait and reuse warm cache, and further requests receive HTTP 503. Waiting is cancelable and starts no SQL work. Request budgets default to 30 seconds and honor a valid, finite, positive Prometheus scrape-timeout header when shorter.
• Collector-boundary cancellation: after request cancellation, no further collector or database starts. An already started collector with a positive timeout keeps its shared predicate-and-query deadline and caches a successful refresh instead of poisoning shared cache for later scrapers. A negative timeout disables the collector deadline, so SQL cancels with the request.
• Separate interruption from target errors: interrupted rounds log INFO interrupted and do not increment exporter or server scrape error counters. Availability retains its prior value, or becomes true after the current precheck succeeds. Uncanceled connection failures and fatal collector failures still count as errors. Query-level error counters and fatal-query ERROR logs keep their existing behavior.
• Accurate progress labels: pg_vacuuming, pg_indexing, and pg_clustering remain cluster-wide and keep three queries per refresh. Relations in the connected database and shared catalogs resolve to names; user relations in other databases emit the numeric OID as relname while keeping datname and pid, preventing accidental local OID name collisions. Auto-discovery filters or missing CONNECT privilege do not hide rows visible in the progress views.
• Container trust bundle: both scratch image build paths include the system CA bundle and license, allowing public-CA TLS verification out of the box. Private CAs still require a mounted certificate and sslrootcert; default TLS mode is unchanged.
• Dependencies and release checks: move YAML from v3 to v4 while keeping existing collector configuration syntax, and update Prometheus common/procfs, golang.org/x/net, and related dependencies. CI validates container file/TLS behavior and all three DEB architectures in addition to RPM compatibility and checksums.
• Aligned metric help text: clarify I/O byte vs operation counts, completed checkpoints, VACUUM dead-tuple memory, and CLUSTER progress. SQL metric names, label keys, types, and units are unchanged on the same PostgreSQL version.

Upgrade Notes

1. Upgrade configuration and binary together. Merge the updated pg_exporter.yml or split YAML files; package upgrades keep local config files. Replacing only the binary does not apply the progress SQL fix. The default bundle remains 58 YAML files, 96 branches, 59 namespaces, and 460 distinct metric definitions, including disabled collectors and two unexpanded histograms.
2. Review progress-label consumers. Cross-database relname values can change from an incorrect local name to a numeric OID, creating new time series; keep datname and pid in panels. Current-database and shared-catalog relation names remain readable.
3. Choose the right health signal. /up and role endpoints reflect the latest health probe; pg_up reflects primary-target scrapes, including fatal collector failures. Inspect query and server metrics for non-fatal and child-database errors. --disable-intro suppresses all built-in metrics, including pg_up, while keeping HTTP health checks active.
4. Account for the PgBouncer probe connection. The PgBouncer pool limit increases from one connection to two. PostgreSQL remains three on the main target and one per discovered database.
5. Keep positive timeouts on fatal collectors. Canceling a negative-timeout fatal query caches a failure under the normal TTL. Later active scrapes can count that cached failure and report pg_up 0 until a refresh succeeds. Zero TTL or --disable-cache still forces refresh on every scrape.
6. Review concurrency and budgets. Excess concurrent scrapes or interrupted scrapes can return 503. An already started bounded collector can overrun the request budget by roughly its own timeout; network stalls can extend longer, and neither deadline is a hard wall-clock cap. Configure a sensible connect_timeout in the DSN for connection handshakes.

A real failure that overlaps request cancellation can be omitted from the two round error counters because classification checks both scrape error and request context; query-level failure counters remain visible. If the first scrape is interrupted before precheck succeeds, pg_up stays 0 until a later scrape recovers. Failure TTL, reload, and immediate SIGTERM exit semantics are unchanged; this release adds no background refresh or graceful shutdown.

When upgrading from v1.4.1 or earlier, also apply the v1.5.0 migration notes, including subscription labels, receiver state mappings, and the PostgreSQL 10–13 monitoring grant. For the full runtime contract, see Compatibility, HTTP API, and Scrape Lifetime.

Verification Scope

Release verification covered the full race test suite, both HTTP mux modes, module and generated-config consistency, static analysis, six-platform builds, container TLS/file checks, and package validation. Three cancellation regressions also passed 200 consecutive race-enabled iterations; a negative control with the interruption fix removed failed earlier. On PostgreSQL 18.6, a client disconnecting during a 0.8s bounded fatal query left both round error counters at 0, and the next scrape returned pg_up 1 with cached metrics without re-running SQL.

Local acceptance against the release artifacts also covered PostgreSQL 9.2–9.6 (legacy config), 10–18 and 19 RC1 (default config), and PgBouncer 1.26.1. Linux amd64/arm64/ppc64le tarballs and RPM/DEB packages passed runtime and install checks; ARM64 package upgrades from 1.5.0 preserved local configuration. Docker Hub 1.6.0 and latest point to the same amd64/arm64 multi-arch manifest; pulled public images passed CA, file, and TLS checks, and their binaries matched the corresponding release tarballs byte-for-byte. All 24 functional test groups passed on Darwin ARM64, including HTTPS auth, reload overlap, standby promotion, and disconnect recovery. Windows and Intel macOS received static binary checks only; container package tests did not exercise real systemd service startup.

Progress SQL branches were verified with the monitoring role on PostgreSQL 12, 17, and 18, with supplementary shared-catalog cases and a live cross-database VACUUM checked on 18.6. These are bounded acceptance results, not a complete re-audit of every PostgreSQL version, extension, dashboard, or production workload. Composite, Patroni, pgBackRest, and PostgreSQL-log components remain on the separate snort line and are not part of v1.6.0.

SHA-256 Checksums

SHA256 checksums

GitHub release · SHA256 checksums · Full changelog · Complete collector reference

v1.5.0

Release date: 2026-10-23. This release improves connection security, collection accuracy, and runtime state consistency, and upgrades the build toolchain to Go 1.27.3.

Fixes and Improvements

• Validate PostgreSQL URLs and query parameters strictly. Reject malformed escapes and parameter names containing whitespace or =. Safe diagnostics prevent malformed connection strings from leaking passwords into logs or silently discarding explicit TLS settings. An empty or whitespace-only file selected through PG_EXPORTER_URL_FILE now prevents startup.
• Resolve database identities with lib/pq. Auto-discovery removes conflicting dbname / database query parameters when replacing a database name and preserves special characters, fixing duplicate collection and HTTP 500 responses caused by duplicate metrics.
• Generate each health response’s HTTP status and body from one atomic state snapshot, fixing contradictory responses during concurrent state transitions. Health checks still use background cached state.
• Replan after a successful precheck detects changes to the username, schemas, or extensions. Unchanged metadata preserves plans and caches. Adding or removing a schema or extension no longer requires manual reload.
• Reject NaN, infinities, and overflowing TTLs or positive timeouts during configuration loading. Preserve the existing meanings of zero TTL (disable caching), zero timeout (use the default), and finite negative timeout (disable the deadline).
• Verify at startup that the active HTTP mux routes the metrics path to the metrics handler. Reject escaped paths that would return the landing page or a redirect under the legacy mux.
• Add the owning database’s datname label to pg_sub_*, preventing collisions between identically named subscriptions in different databases. Correct pg_recv_state codes in the current and legacy bundles, and fix receiver address extraction on PostgreSQL 9.6.
• Clarify pg_origin permissions, the table scope of pg_pubrel_count, synchronization states and PostgreSQL 19 sequence semantics in pg_subrel_count, and the pg_backend description.

Metric and dashboard compatibility

Compared with v1.4.1 on the same PostgreSQL version, v1.5.0 does not add, remove, or rename bundled SQL metric names. Types and units remain unchanged, but labels and state mappings do change. PostgreSQL 19 support first shipped in v1.3.0; upgrading the database can also change the selected SQL branch and a metric’s meaning.

Users upgrading from PG17 or earlier must also migrate older names: checkpoint metrics left pg_bgwriter_* in PG17, and pg_wal_write, pg_wal_sync, pg_wal_write_time, and pg_wal_sync_time are absent from PG18 onward. The full compatibility guide lists each replacement, label/aggregation differences, and mixed-version PromQL.

Before rollout, evaluate the actual dashboard and alert expressions and test missing-series input. A successful scrape does not ensure every expected metric exists; an empty alert expression can silently stop firing. The missing-metric checks include a per-target rule and explain when absence is expected. The full PG19 metric table links to the tagged collector definitions; PostgreSQL validation remains scoped to 19 RC1.

Upgrade Notes

• On PostgreSQL 10–13, an administrator must run GRANT SELECT (oid) ON pg_catalog.pg_subscription TO monitor; in the exporter’s main connection database, substituting the actual monitoring role. This does not expose subconninfo. PostgreSQL 14+ needs no extra grant under standard catalog ACLs.
• The new datname label on pg_sub_* creates new time series. Review PromQL joins, aggregations, and alerts that match these labels. The pg_sub_id gauge is retained.
• pg_recv_state uses the following codes; 1–3 remain reserved. No receiver row means no sample. PostgreSQL 9.6 still hides receiver details from ordinary monitoring roles, resulting in an unknown state; the exporter does not expand database privileges.

• Upgrade both the binary and collector configuration. Packages preserve local configuration changes: merge the new pg_exporter.yml, then check query error counters in /metrics. HTTP 200 alone does not establish a successful scrape.
• Reloading empty YAML still clears collectors, and directory loading still permits valid files to load when others fail. SIGTERM retains immediate process termination; it does not wait for active scrapes to complete.

Toolchain and Validation

Retain lib/pq 1.12.3 and upgrade Prometheus client_golang to 1.25.0, common to 0.72.1, and exporter-toolkit to 0.20.0. YAML uses go.yaml.in/yaml/v3 3.0.5. The PostgreSQL driver remains lib/pq.

The default bundle still contains 58 YAML files, 96 branches, 59 namespaces, and 460 distinct metric definitions, including two unexpanded histograms. Validation covered non-superuser collection on PostgreSQL 9.1–9.6, 10–18, 19 RC1, and PgBouncer 1.26.1; physical standby promotion, reloads, disconnect recovery, races, both HTTP mux modes, six-platform builds, ARM64 RPM/DEB installation, and Docker images. PostgreSQL 19 testing used RC1; this does not cover every extension or production workload.

Go and Dependency Security Updates

Go 1.27.3 adds a blocklist for untrusted intermediate certificates in crypto/x509, addressing CVE-2026-111943. It also includes security fixes accumulated since the previous Go 1.26.5 build, including TLS issues CVE-2026-56862 and CVE-2026-97031, HTTP issues CVE-2026-56853 and CVE-2026-94439, and template, ASN.1, and multipart fixes. See the complete upstream scope in the Go 1.26.6, Go 1.27.2, and Go 1.27.3 announcements.

golang.org/x/net moves from 0.57.0 to 0.61.0, including five HTTP/2 fixes introduced in 0.60.0:

x/crypto 0.58.0 also crosses the fixes for SSH issues CVE-2026-56854, CVE-2026-56855, and CVE-2026-78662. x/text 0.43.0 includes the precis fix CVE-2026-56851. The exporter does not import these SSH/precis packages; these are dependency-version updates, not confirmed exporter runtime vulnerabilities.

Comparative govulncheck runs on 2026-10-23 found no known symbol-level or imported-package-level vulnerabilities in the new candidate for Darwin, Linux, or Windows. The unimported OpenPGP package retains a module-level advisory, GO-2026-5932. Static symbol matches are not exploit reproductions, and including upstream fixes does not establish that every issue was exploitable in the exporter. Other dependency upgrades are maintenance updates. Install the rebuilt release binary; upgrading Go on the host does not change an existing binary.

For the full CVE table, first fixed versions, and scan levels, see the security update verification.

SHA-256 Checksums

SHA256 checksums

GitHub release · SHA256 checksums · Full changelog · Complete collector reference

v1.4.1

v1.4.1 is a maintenance release focused on metric accuracy and RPM upgrade compatibility.

Highlights:

• Fix pg_subrel_count overcounting with parallel logical replication apply workers. Deduplicate pg_stat_subscription by subscription ID and name before aggregating subscription relation states.
• If a query result omits a configured LABEL column, fail the entire collector scrape. Do not emit an empty label or keep stale results. Other non-fatal collectors continue normally.
• Rename the official RPM package and artifact prefix from pg_exporter to pg-exporter. The new package provides and obsoletes the legacy name to support direct upgrades.
• Update version and standalone package metadata. Add regression tests for missing labels. Validate RPM configuration, artifact names, and compatibility metadata in CI.

Upgrade Notes:

• Custom collector SQL must return every LABEL column. The result schema must be complete even if the query returns zero rows.
• If automation matches GitHub RPM file names directly, change pg_exporter-*.rpm to pg-exporter-*.rpm.

Checksums

https://github.com/pgsty/pg_exporter/releases/download/v1.4.1/checksums.txt

https://github.com/pgsty/pg_exporter/releases/tag/v1.4.1

v1.4.0

v1.4.0 adds Snapshot Histogram metrics and the pg_xact_age transaction age collector. It also improves HTTP routing, packaging, and the build toolchain.

New Features:

• Add the HISTOGRAM column type. It aggregates SQL snapshots by label group into classic Prometheus histograms with _bucket / _count / _sum series. Configuration loading validates finite bucket bounds in strictly increasing order and appends +Inf automatically. The le label is reserved. Hot reload is supported.
• Add the pg_xact_age collector. It returns open transaction age (pg_xact_age_seconds) and idle-in-transaction age (pg_xact_age_idle_seconds) as histograms. It collects cluster-level data from client backends only, with a 10s TTL.
• Increase the default bundle from 57 to 58 definition files. Assign pg_xact_age to slot 0450. Renumber pg_lock / pg_lock_stat / pg_query to 0460 / 0470 / 0480 without content changes.

Fixes & Improvements:

• Register HTTP routes in a private ServeMux instead of the global DefaultServeMux. This prevents accidental exposure of endpoints from third-party libraries.
• Validate --web.telemetry-path at startup. Reject empty paths, paths without a leading /, paths with ? # { }, and conflicts with built-in endpoints. Also reject non-canonical paths such as //metrics, which cannot match requests. Each failure returns a clear error immediately.
• Escape the telemetry path in the landing page HTML.
• Close the primary connection pool if the --fail-fast pre-check fails.
• Fix RPM / DEB packaging (#105). Set the prometheus user’s HOME to /var/lib/prometheus, where libpq looks for ~/.pgpass. Add /postgres to the packaged default URL. This prevents libpq from using a database named after the OS user.
• Use the v version prefix consistently. Official release binaries report v1.4.0 in --version, /version, and pg_exporter_build_info{version=...}. GoReleaser artifacts previously reported 1.3.0 without the prefix. Artifact file names, package versions, and Docker image tag conventions do not change.
• Apply the same value conversion rules to histograms and scalar columns. Exclude timestamps and booleans from scale.
• Correct GoReleaser package metadata to show support for PostgreSQL 9.x - 19+ and pgBouncer 1.8 - 1.25+.
• Restore GOPROXY / GOSUMDB build-argument passthrough in make docker.

Engineering & Build:

• Update the build toolchain to Go 1.26.5, exporter-toolkit v0.17.1, and prometheus/common v0.70.0.
• Add regular CI checks for module tidy, generated configuration, race tests, and six-platform cross-builds. The make conf output must match config/*.yml.
• Remove the docker/ scripts and make docker-release. Use GoReleaser to build multi-architecture release images.
• Remove assumptions about specific collectors from configuration coverage tests. This makes smaller custom bundles easier to maintain.

Upgrade Notes:

• A non-canonical telemetry path, such as //metrics, now prevents startup. Previously, the process started but the metrics endpoint was unreachable.
• Update automation that parses the version label of pg_exporter_build_info or the --version output to accept the v prefix.
• If any collector uses HISTOGRAM, do not use le as a constant label.

Checksums

https://github.com/pgsty/pg_exporter/releases/tag/v1.4.0

v1.3.0

v1.3.0 adds PostgreSQL 19 support. It also updates the default collectors, build toolchain, and configuration coverage tests.

Highlights:

• Default support range extended from PostgreSQL 10-18+ to 10-19+
• Default config bundle includes 57 config/*.yml definition files
• Build dependencies updated to Go 1.26.4, lib/pq v1.12.3, Prometheus client v1.23.2, and exporter-toolkit v0.16.0
• pg_recovery_state: collect pg_stat_recovery on recovery nodes, exposing promotion trigger status, replay LSN, timeline, recovery transaction time, and pause state
• pg_lock_stat: collect PG19 pg_stat_lock, exposing waits, wait time, and fast-path overflow counts by locktype
• pg_vacuum_score: collect the current-database summary from pg_stat_autovacuum_scores, exposing max autovacuum score and candidate table count
• pg_wal_19: expose wal_fpi_bytes on PG19 as pg_wal_fpi_bytes
• pg_sub_19: adapt sequence sync and logical replication conflict stats from pg_stat_subscription_stats, while keeping sync_error_count for legacy dashboards
• pg_recv: recognize the PG13+ WAL receiver connecting state on PG19
• pg_slot: recognize the PG19 replication slot invalidation reason idle_timeout
• pg_db_confl: switch to an explicit column list to avoid accidentally exporting future view columns
• pg_backup, pg_vacuuming, and pg_clustering continue reusing stable existing branches instead of changing the metric surface for low-value PG19 fields

Checksums

https://github.com/pgsty/pg_exporter/releases/tag/v1.3.0

v1.2.2

v1.2.2 updates the release toolchain to Go 1.26.2. This maintenance release has no changes to collectors, configuration behavior, or runtime behavior.

Highlights

• Refresh the release toolchain: bump release builds to Go 1.26.2
• No functional changes: collector behavior, default configs, metric definitions, and runtime semantics remain unchanged

Checksums

https://github.com/pgsty/pg_exporter/releases/tag/v1.2.2

v1.2.1

v1.2.1 is a maintenance release for release engineering, configuration package consistency, documentation, and metadata. It has no changes to collector or runtime behavior.

Highlights

• Refresh the build toolchain: bump both release workflows and Docker build images to Go 1.26.1
• Standardize config style: switch inline description values in both current and legacy configs to double-quoted form, and regenerate merged pg_exporter.yml / legacy/pg_exporter.yml
• Add config consistency tests: verify split and merged configs remain equivalent, and check inline metric description style to reduce configuration drift
• Refresh packaging metadata: update RPM / DEB support descriptions to PostgreSQL 9.x - 18+ and pgBouncer 1.8 - 1.25+, and refresh Pigsty documentation links

Checksums

https://github.com/pgsty/pg_exporter/releases/tag/v1.2.1

v1.2.0

v1.2.0 improves stability and compatibility for startup, hot reload, health probes, configuration validation, and legacy support.

New Features:

• Improve hot reload. Support platform-specific signals (SIGHUP / SIGUSR1) and improve POST /reload to update configuration and query plans without a restart.
• Use non-blocking startup. HTTP endpoints start even if the target precheck fails. This improves recovery and monitoring integration.
• Add a legacy configuration bundle for PostgreSQL 9.1-9.6. Use legacy/ and the make conf9 target to configure monitoring for EOL versions.
• Use cached health snapshots with periodic probes. This improves consistency for role-based health endpoints and reloads.
• Add go test and go vet to release workflows. Update the build toolchain to Go 1.26.0.

Bug Fixes:

• Fix configuration parsing cases. Reject malformed metric entries, return explicit errors if a configuration directory has no valid YAML, and improve runtime fallbacks.
• Fix CLI boolean parsing for arguments such as --flag=false.
• Fix /explain output with corrected content types and safer template rendering.
• Improve predicate queries and PG URL handling. Improve BOOL/BOOLEAN support, row resource handling, and dbname query-parameter parsing and redaction.
• Close connections asynchronously when auto-discovery removes a target.
• Fix metric and label validation. Check constant-label conflicts, scaled default values, and Prometheus naming rules.

Checksums

https://github.com/pgsty/pg_exporter/releases/tag/v1.2.0

v1.1.2

This minor release fixes the pg_timeline configuration and builds with the latest Go dependencies.

Checksums

https://github.com/pgsty/pg_exporter/releases/tag/v1.1.2

v1.1.1

Minor release with new collectors and bug fixes.

New Features:

• New pg_timeline collector for timeline monitoring
• New pg_sub_16 collector branch to exclude parallel operations in subscriptions (PostgreSQL 16+ compatibility)

Bug Fixes:

• Fix: Add coalesce for slotname in pg_recv collector to handle NULL values

Checksums

https://github.com/pgsty/pg_exporter/releases/tag/v1.1.1

v1.1.0

Build with Go 1.25.5 and latest dependencies, collector updates:

Collector Changes:

• pg_setting: update PG10-18 compatibility and add missing_ok support.
  • Add 13 new metrics: max_parallel_workers, max_parallel_workers_per_gather, max_parallel_maintenance_workers, shared_buffers, maintenance_work_mem, effective_cache_size, fsync, full_page_writes, autovacuum, autovacuum_max_workers, checkpoint_timeout, checkpoint_completion_target, hot_standby, synchronous_commit, io_method.
  • Rename work_memory_size to work_mem.
  • Change min_version from 9.6 to 10. Use explicit ::int type conversion.
• pg_size: fix log directory size detection. Check logging_collector instead of matching path patterns.
• pg_table: replace LATERAL subqueries with JOIN to improve performance. Change tuples and frozenxid from COUNTER to GAUGE. Increase the timeout from 1s to 2s.
• pg_vacuuming: add a PG17 branch with indexes_total, indexes_processed, and dead_tuple_bytes to track index vacuum progress.
• pg_query: increase the timeout from 1s to 2s for high-load conditions.
• pg_io: correct the reuses description from “in reused” to “is reused”.
• pg_checkpointer: correct the pg_checkpointer_10 description from “9.4+” to “9.4-17”.
• pg_db_confl: correct the pg_db_confl_15 description from “9.1 - 16” to “9.1 - 15”.
• Correct format alignment for pg_db, pg_indexing, pg_clustering, and pg_backup.

Other Changes:

• Fix release year by @anayrat

Checksums

https://github.com/pgsty/pg_exporter/releases/tag/v1.1.0

v1.0.3

• Build with Go 1.25.4 and latest dependencies
• Fix #80 Conflict with libpq env variables
• Change default value of auto-discovery to true by @kadaffy

Checksums