Compatibility

Choose an artifact for the exporter host and a collector configuration for the database version. Then install any views or extensions required by the collectors you enable. This page describes the configuration shipped with v1.5.0.

Database Targets

PostgreSQL 19 branches cover recovery, locks, autovacuum scores, WAL, subscriptions, receivers, and replication slots. Version selection uses the server version number; check /stat after the first scrape to find queries that need adjustment for your server build.

The bundled PgBouncer collectors require 1.8 or later. That version changed the SHOW STATS fields used by these queries. The latest configured branches have no upper version bound. When you upgrade PgBouncer, check collector results against the upstream changelog.

Release Validation

The v1.5.0 candidate passed default primary collection as a non-superuser on PostgreSQL 9.1–9.6, 10–18, and 19 RC1, plus PgBouncer 1.26.1. PostgreSQL 10–13 used the documented subscription OID grant. Physical standby promotion, reconnect recovery, and concurrent scrape/health/reload requests were also tested. PostgreSQL 19 evidence refers to RC1, not an exhaustive check of every final-release build, extension, or production workload.

Metric and Dashboard Compatibility

An exporter upgrade and a PostgreSQL major-version upgrade can change different parts of the metric contract. The comparisons below use the bundled SQL collectors at tags v1.4.1 and v1.5.0, including each column’s rename setting. They describe exported metric names, not just PostgreSQL view columns or YAML filenames. Custom collectors and application-specific alert rules need their own review.

Exporter v1.4.1 → v1.5.0

With the same PostgreSQL version, no bundled SQL metric names are added, removed, or renamed, and metric types and units remain unchanged. The following changes still require dashboard and alert review:

These corrections require deploying the updated YAML as well as the binary. On PG10–13, the subscription collector also needs the subscription OID grant; otherwise its metrics disappear because the query fails. See the replication design record for the compatibility decisions.

PostgreSQL 18 → 19 with the v1.5.0 configuration

No metric names from the PG18 branches are removed or renamed by switching to the PG19 branches. PostgreSQL 19 collector support first shipped in Exporter v1.3.0; the behavior below is inherited by v1.5.0. It is separate from the label and receiver corrections above. PostgreSQL acceptance evidence is for 19 RC1.

Exact definitions are in the tagged subscription, subscription relation, WAL, lock, recovery, and autovacuum collectors.

For a mixed PG15–19 fleet using the v1.5.0 configuration, this expression preserves table-only synchronization-error rates. The left side takes precedence where the PG19 metric exists; labels and target selectors must agree:

rate(pg_sub_sync_table_error_count[5m])
or
rate(pg_sub_sync_error_count[5m])

Upgrading from PG17 or earlier

An upgrade straight to PG19 also crosses earlier PostgreSQL metric boundaries. The following names are absent on PG19 with the v1.5.0 bundle; their disappearance is not new in Exporter v1.5.0 or PostgreSQL 19.

The pg_checkpointer_* names above are already provided by the v1.5.0 configuration on PG10–16, using aliases for the old SQL columns. Prefer those names for a mixed-version dashboard. PG18+ also exposes pg_checkpointer_done for completed checkpoints; timed and req count scheduled/requested checkpoints and should not be treated as a completed-work total. Checkpointer statistics on PG17+ include restartpoint activity where documented.

WAL I/O moves to a view with type, object, and context dimensions, so replacing a name alone is insufficient. For example, a per-target WAL write rate on PG18+ is:

sum by (job, instance) (rate(pg_io_writes{object="wal"}[5m]))

Keep any additional cluster/target labels required by your setup, review the chosen backend scope, and check timing settings before comparing historical values. PG18+ also adds pg_io_read_bytes, pg_io_write_bytes, and pg_io_extend_bytes; use these for byte throughput rather than assuming a fixed byte count per operation. See the tagged I/O, background-writer, and checkpointer definitions and PostgreSQL 18 migration notes.

Detect missing metrics before alerts go silent

A Prometheus alert whose expression returns an empty vector has no active alert instances. HTTP 200, Prometheus up == 1, or pg_up == 1 does not establish that every collector or alert expression still works. See Prometheus alert evaluation.

1. Merge and deploy the matching YAML, preserving local customizations. On a representative target of each version and role, scrape /metrics, inspect /explain and /stat, and check pg_exporter_query_scrape_error_count and the logs for collector failures.
2. Evaluate the actual dashboard, recording-rule, and alert expressions. Check names, label joins, units, state mappings, and returned series; wait for enough samples to fill rate() windows. An empty result is not a healthy zero.
3. Test alert rules with both expected data and missing-series input (promtool check rules checks syntax; promtool test rules can check behavior). A successful exporter test does not validate downstream dashboards.
4. Add per-target missing-metric checks only where that metric is expected for the server version, role, and configured objects. Do not hide missing input with a blanket or vector(0).

For example, if job="pg19" contains only PG19 targets expected to expose the bundled WAL collector, this rule detects a missing pg_wal_bytes on each otherwise healthy target:

groups:
  - name: pg-exporter-compatibility
    rules:
      - alert: PgWalMetricMissing
        expr: (pg_up{job="pg19"} == 1) unless on (job, instance) pg_wal_bytes{job="pg19"}
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Expected WAL metric is missing from a healthy PostgreSQL target"

Adapt the selector and matching labels to your target identity; monitor up and pg_up failures separately. For a known individual target, absent_over_time() is another option. A fleet-wide absent(metric) alone cannot detect one missing target while others still emit the metric. Likewise, pg_recv_state != 0 cannot detect a receiver row that has disappeared; streaming-standby monitoring needs a separate expected-receiver presence check.

v1.5.0 Release Artifacts

Release archives include the binary, merged default config, license, default environment file, and systemd unit. Get the PostgreSQL 9.x configuration from the matching source tag; it is not included in these binary archives. macOS and Windows artifacts are useful for development and remote targets; the packaged service integration is Linux-specific.

Container Constraints

The official image is built from scratch. It contains the static exporter binary, /etc/pg_exporter.yml, and the license, but no shell and no operating-system CA bundle. Mount required CA certificates explicitly when using sslmode=verify-ca or verify-full.

Collector-Level Requirements

Collector selection also depends on the target database:

• primary / replica tags restrict execution by recovery role.
• dbname:, extension:, schema:, and username: tags require matching facts.
• Predicate queries can perform additional runtime checks.
• Disabled-by-default collectors (skip: true) must be intentionally enabled.
• Auxiliary-view collectors such as table/index bloat require their views and privileges.

Scrape /metrics once, then use /explain to inspect the current plan and /stat to check query results. Bundled Collectors lists the prerequisites for each file.