PG Exporter v1.6.1

VonngAuthor of PG Exporter and Pigsty, working on PostgreSQL infrastructure and monitoring.

PG Exporter v1.6.1 was released on November 11, 2026. This maintenance release fixes incorrect table statistics, collector failures that could disrupt a scrape, and connection-handling edge cases. It uses Go 1.27.4 and retains lib/pq 1.12.3. Built-in SQL metric names, label keys, types, buckets, CLI flags, and HTTP routes are unchanged.

Changes

• Keep duplicate scalar rows from breaking the whole scrape. A query returning two rows with the same labels for a GAUGE or COUNTER now fails that collector and discards its result before Prometheus gathers the samples. Other collectors continue when the failing collector is non-fatal; fatal: true retains its normal failure semantics. A collector containing only HISTOGRAM metrics still combines repeated label sets into one snapshot distribution. Collisions between separate collectors still require a configuration fix.
• Correct partitioned and indexless table statistics. Across all four pg_table branches, relations with relfrozenxid = 0, including partitioned parents, report age = 0 instead of 2147483647. Nullable index counters no longer erase valid sequential-scan totals: each operand of tbl_scan, tup_read, and n_tup_mod defaults to zero before addition. Nullable live/dead/modified-row estimates also default to zero instead of NaN.
• Avoid table-size failures on temporary relations. pg_table_size excludes pg_temp* and pg_toast* schemas, so it does not attempt to size another session’s temporary tables or report TOAST tables separately. The source tag also includes the legacy PostgreSQL 9.1 fix for tables without TOAST: OID 0 no longer fails the entire table-size collector. The legacy bundle remains a separate download.
• Fix activity durations and TimescaleDB identifiers. pg_activity clamps negative state, transaction, and session durations to zero when timestamps fall after the query’s time reference. The optional, default-disabled pg_tsdb_hypertable collector correctly quotes schema and table names containing uppercase letters or special characters. HELP text now describes transaction/session start times, indexing phases, checkpoint counters, and table data-fork size more accurately.
• Fix connection URLs and credential redaction. Hostless URLs such as postgresql://?host=/var/run/postgresql keep the authority separator during normalization and remain valid for lib/pq. Auto-discovery removes conflicting service= parameters when assigning a child database. Logs also mask sslpassword= values.
• Make connection-pool cleanup safe. Removed or replaced discovered targets close their old pools after active collection finishes. Closing a server clears its pool reference under synchronization and safely handles an uninitialized or already-closed pool. Configuration reload continues to reuse live pools and invalidate collector plans; it does not rebuild every child connection.
• Reject invalid metric configuration and protect self-metrics. Non-finite scale and default values are rejected during configuration loading, and invalid --namespace values fail startup. Invalid internal metric labels, such as a non-UTF-8 database name, produce a warning and skip that sample instead of panicking. User constant labels cannot overwrite reserved build-info fields such as version and revision.
• Repair diagnostic and direct-call edge cases. The HTML explain page correctly renders predicate cache TTLs. Direct collector calls execute on a cold cache or with TTL zero even without a server scrape timestamp. Explicit Server.Plan(...) calls preserve same-name version branches by their branch keys.
• Update builds and service management. The packaged systemd unit adds ExecReload for systemctl reload pg_exporter. Standalone Docker builds accept version, branch, revision, and build-date arguments; make docker-build supplies them. Plain Docker builds retain HEAD / unknown placeholders unless those arguments are provided. The build toolchain moves to Go 1.27.4, with routine dependency updates.

Upgrade notes

1. Upgrade the binary and merge the collector YAML. Package upgrades preserve locally modified /etc/pg_exporter.yml and /etc/default/pg_exporter. Deploy the updated SQL to receive the table, activity, and TimescaleDB fixes. The default bundle still contains 58 YAML files, 96 branches, 59 namespaces, and 460 distinct metric definitions.
2. Review custom collectors. Scalar queries must return one row per label tuple. Use finite scale and default values. Histogram-only queries may still return multiple observations per label tuple. Partitioned-parent freeze-age alerts now see 0; indexless-table totals and formerly NaN row estimates may also change.
3. Refresh the unit and restart after a binary upgrade. After installing the new systemd unit, run sudo systemctl daemon-reload, then sudo systemctl restart pg_exporter to use the new binary or process settings. For subsequent collector-YAML-only changes, use sudo systemctl reload pg_exporter or POST /reload.
4. Download legacy YAML separately for PostgreSQL 9.1–9.6. Use legacy/pg_exporter.yml from tag v1.6.1 or main at 282e19d or later. Binary archives and RPM/DEB packages contain only the regular PostgreSQL 10+ configuration.

When upgrading from v1.5.0 or earlier, also review the v1.6.0 release notes for health probes, scrape budgets, and cross-database progress labels, and the v1.5.0 migration notes for subscription labels, receiver states, and PostgreSQL 10–13 grants. See compatibility for the migration table.

Verification scope

Tag v1.6.1 points to d0dead1. Its CI run and Release run passed module and generated-config checks, the full race suite, Go 1.21 HTTP mux compatibility tests, go vet, six-target cross-builds, container checks, and package/checksum checks. Added regressions cover duplicate scalar-row isolation, cold/zero-TTL direct collection, namespace and build-info validation, hostless URLs, service= removal, sslpassword masking, predicate HTML rendering, finite numeric options, and collector SQL invariants.

The release acceptance record covers the 12 published artifacts and checksums, amd64/arm64 Docker images, ARM64 DEB installation on Debian 12 and RPM installation on Rocky Linux 9, and non-superuser live scrapes on PostgreSQL 10–18 and 19 RC1 primaries, PostgreSQL 18 and 19 RC1 streaming standbys, PgBouncer 1.26.1, and PostgreSQL 9.1–9.6 with the separate legacy bundle. Scenarios included auto-discovery and database removal, HTTP/SIGHUP reload, pg_stat_statements, indexless and partitioned tables, temporary tables, and open transactions. Legacy acceptance does not imply that the modern pg_temp* and COALESCE refinements were backported. Windows, Linux ppc64le, and Intel macOS received build/checksum checks rather than runtime acceptance; package-container checks do not establish a real systemd boot. PostgreSQL 19 evidence is for RC1, not every later build or production workload. The experimental snort components are not part of v1.6.1.

Checksums

SHA256 checksums