兼容性

按运行主机选择安装包，按数据库版本选择采集配置，再安装所需的视图或扩展。本页说明 v1.5.0 随附配置的兼容范围。

数据库目标

PostgreSQL 19 分支覆盖恢复、锁、自动清理评分、WAL、订阅、接收器与复制槽。采集器按服务器版本号选择分支；首次抓取后，检查 /stat，确认查询与实际服务器构建匹配。

内置 PgBouncer 采集器要求 1.8 或更高版本。1.8 调整了查询所用的 SHOW STATS 字段。最新配置分支未设版本上限；升级 PgBouncer 后，结合上游变更日志检查采集结果。

发布验证

v1.5.0 候选已以非超级用户通过 PostgreSQL 9.1–9.6、10–18、19 RC1 的默认主库采集，以及 PgBouncer 1.26.1 实测。PG10–13 使用文档要求的订阅 OID 授权；另验证了物理备库晋升、断连恢复及并发采集／健康检查／重载。PG19 证据对应 RC1，不等于覆盖所有正式版构建、扩展与生产负载。

指标、仪表盘与告警兼容性

升级 Exporter 和升级 PostgreSQL 大版本，可能改变指标契约的不同部分。以下对照以 v1.4.1 与 v1.5.0 标签中的内置 SQL 采集器为准，包含各列的 rename 映射；列出的是实际导出的指标名，不只是 PostgreSQL 视图列名或 YAML 文件名。自定义采集器与业务告警规则仍需单独检查。

Exporter v1.4.1 → v1.5.0

保持 PostgreSQL 版本不变时，内置 SQL 指标没有新增、删除或改名，指标类型和单位也不变。不过，以下变化仍需检查仪表盘与告警：

这些修正需要同时部署新版 YAML 和二进制。PG10–13 的订阅采集器还需要订阅 OID 授权，否则查询失败，指标会缺失。兼容性决策详见复制采集器设计记录。

使用 v1.5.0 配置，PostgreSQL 18 → 19

从 PG18 分支切换到 PG19 分支，不会删除或改名 PG18 分支已有的指标。 PostgreSQL 19 采集器支持最早随 Exporter v1.3.0 发布，以下行为由 v1.5.0 继承，与上面的标签和接收器修正属于不同变化。PostgreSQL 验收证据对应 19 RC1。

精确定义见发布标签中的订阅、订阅关系、WAL、锁、恢复与自动清理采集器。

对于使用 v1.5.0 配置的 PG15–19 混合环境，以下表达式保持 只统计表同步错误 的速率口径。PG19 指标存在时优先使用左侧；两侧标签和目标选择条件须一致：

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

从 PG17 或更早版本升级

直接升到 PG19 还会跨越较早 PostgreSQL 版本的指标变化。下列旧名在 v1.5.0 配置采集 PG19 时已不存在，但它们的消失 并非 Exporter v1.5.0 或 PostgreSQL 19 新引入。

v1.5.0 配置在 PG10–16 上也通过旧 SQL 列的别名提供上述 pg_checkpointer_* 指标，混合版本仪表盘可优先使用这些名称。PG18+ 还提供表示已完成检查点的 pg_checkpointer_done；timed、req 统计计划／请求量，不应当作已完成总量。PG17+ 的检查点统计按各指标定义包含 restartpoint 活动。

WAL I/O 转到带有 type、object、context 维度的视图，不能只替换名字。例如，PG18+ 按目标汇总的 WAL 写操作速率为：

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

按实际环境保留额外的集群／目标标签，核对后端范围与计时开关后再比较历史值。PG18+ 还新增 pg_io_read_bytes、pg_io_write_bytes、pg_io_extend_bytes；计算字节吞吐量时应使用这些指标，不再假定每次操作对应固定字节数。参见发布标签中的 I/O、后台写进程、检查点进程定义与 PostgreSQL 18 迁移说明。

避免指标缺失让告警静默

Prometheus 告警表达式返回空向量时，不会产生告警实例。HTTP 200、Prometheus up == 1 或 pg_up == 1，都不能证明每个采集器和告警表达式仍然正常。参见 Prometheus 告警求值规则。

1. 合并并部署配套 YAML，保留本地定制。对每种版本与角色选择代表性目标，抓取 /metrics，检查 /explain、/stat、pg_exporter_query_scrape_error_count 和日志中的查询错误。
2. 执行实际仪表盘、记录规则和告警表达式，检查名称、标签连接、单位、状态映射与返回时序，并等待 rate() 窗口积累足够样本。空结果不等于健康的零值。
3. 分别用正常数据和缺失时序测试告警规则（promtool check rules 检查语法，promtool test rules 可检查行为）。Exporter 测试通过不等于下游仪表盘已经验证。
4. 按目标检查预期存在的关键指标，同时限定服务器版本、角色与已配置对象。不要用无条件 or vector(0) 掩盖输入缺失。

例如，假设 job="pg19" 只包含预期启用内置 WAL 采集器的 PG19 目标，以下规则可逐个发现数据库健康但缺少 pg_wal_bytes 的目标：

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"

按实际目标身份调整选择器与匹配标签，并分别监控 up 和 pg_up 故障。已知的单个目标也可使用 absent_over_time()。仅对整个集群执行 absent(metric)，无法发现其他目标仍有数据时的单目标缺失。同理，pg_recv_state != 0 无法发现已经消失的接收器行；预期持续流复制的备库还需要单独检查接收器是否存在。

v1.5.0 发布产物

发布压缩包包含二进制、合并后的默认配置、许可证、默认环境文件与 systemd 单元。PostgreSQL 9.x 配置需要从对应源码标签获取，不在这些二进制压缩包中。macOS 与 Windows 产物适合开发或连接远端目标；软件包提供的服务集成只适用于 Linux。

容器约束

官方镜像基于 scratch 构建，只包含静态 exporter 二进制、/etc/pg_exporter.yml 与许可证；镜像内没有 Shell，也没有操作系统 CA 证书包。使用 sslmode=verify-ca 或 verify-full 时，需要显式挂载 CA 证书。

采集器级前置条件

采集器还会按目标数据库的实际条件选择：

• primary / replica 标签按恢复角色限制执行。
• dbname:、extension:、schema: 与 username: 标签要求对应事实匹配。
• 谓词查询可以执行额外的运行时检查。
• 默认关闭的采集器（skip: true）必须显式启用。
• 表/索引膨胀等辅助视图采集器需要相应视图与权限。

先抓取一次 /metrics，再通过 /explain 查看当前采集计划，通过 /stat 检查查询结果。每个文件的前置条件参见内置采集器。