跳转到主要内容

这是本节的多页打印视图。 .

返回本页常规视图.

模块：PGSQL

使用 Pigsty v4.5 声明、部署、接入、监控、备份与管理 PostgreSQL 集群。

PGSQL 是 Pigsty 的核心模块：通过 Ansible 清单声明 PostgreSQL 集群，以 Patroni 与 etcd 提供高可用编排，以 pgBackRest 提供备份/PITR，并通过 HAProxy、VIP、DNS、PgBouncer 与完整可观测性栈提供数据库服务。

本页按 Pigsty v4.5.0 源码组织入口。具体默认值只在 参数参考 中维护，避免在模块首页复制一份会漂移的参数快照。

建模与配置

  • 集群模型：集群、实例、身份与角色。
  • 架构：Patroni、etcd、服务接入与可观测性关系。
  • 集群配置：主库、副本、离线实例、同步提交、备份集群、延迟集群与 Citus。
  • 内核：PostgreSQL 大版本、发行版与软件包选择。
  • 用户、数据库、HBA 与 ACL：业务对象与访问控制。
  • 服务接入：读写/只读服务、HAProxy、VIP、DNS 与连接池。
  • 扩展目录：当前打包的 575 个扩展及平台覆盖。

部署与管理

任务 入口
初始化集群或添加实例 集群管理 · pgsql.yml
创建或变更用户 用户管理 · pgsql-user.yml
创建或变更数据库 数据库管理 · pgsql-db.yml
HBA 与参数变更 HBA 管理 · 组件管理
Patroni 切换、维护与故障处理 Patroni 管理
扩展安装、创建、升级与移除 扩展管理
外部实例监控接入 pgsql-monitor.yml
迁移准备 迁移 · pgsql-migration.yml
移除实例或集群 安全移除流程 · pgsql-rm.yml

pgsql.yml、pgsql-user.yml、pgsql-db.yml 等真实执行会修改目标环境；pgsql-rm.yml 默认可能删除数据与备份。执行前先核对精确集群/节点与近期备份；移除操作还必须由操作者输入并确认精确目标。

备份与恢复

  • 备份与恢复总览：恢复能力、边界与入口。
  • 机制 与 策略：基础备份、WAL、恢复窗口与保留策略。
  • 仓库：本地、S3/Silo 与其他 pgBackRest 仓库。
  • 日常管理：备份状态、检查、调度与清理。
  • 恢复操作：集群级 pgsql-pitr.yml、单节点 pig pitr 和低层 pig pb restore。
  • 手工演练：在可丢弃沙箱中分阶段验证 PITR。

恢复是破坏性操作；生产环境必须保留独立、近期且验证过的备份，并把停服、恢复、数据验证、时间线提升、DCS 重建、副本重建和新全量备份当作不同关卡。

监控

当前源码 files/grafana/pgsql 包含 29 个 PostgreSQL/PGCAT 仪表盘，覆盖全局、集群、实例、数据库、表、查询、会话、事务、复制、服务、PgBouncer、PITR 与告警。

参数组

PGSQL 参数参考 是 v4.5.0 默认值与语义的唯一文档入口：

  • PG_ID：集群/实例身份。
  • PG_BUSINESS：用户、数据库、服务等业务对象。
  • PG_INSTALL：内核、软件包与扩展。
  • PG_BOOTSTRAP：Patroni 引导、复制与数据库初始化。
  • PG_PROVISION：库内对象与权限置备。
  • PG_BACKUP：pgBackRest 与备份仓库。
  • PG_ACCESS：PgBouncer、服务、VIP 与 DNS。
  • PG_MONITOR：exporter、监控注册与指标采集。
  • PG_REMOVE：移除保险与清理范围。

延伸阅读

1 - 集群配置

根据需求场景选择合适的实例与集群类型，配置出满足需求的 PostgreSQL 数据库集群。

Pigsty 是一个“配置驱动”的 PostgreSQL 平台：所有行为都来自 ~/pigsty/conf/*.yml 清单与 PGSQL 参数 的组合。

只要写好配置，你就能在几分钟内复刻出一套包含实例、用户、数据库、访问控制、扩展与调优策略的定制集群。

配置入口

  1. 准备清单：复制 pigsty/conf/*.yml 模板或从零开始编写 Ansible Inventory，将集群分组（all.children.<cls>.hosts）与全局变量（all.vars）写入同一个文件。
  2. 定义参数：在 vars 区块中覆盖需要的 PGSQL 参数。全局 → 集群 → 主机的覆盖顺序决定了最终值。
  3. 应用配置：运行 ./configure -c <conf> 或 bin/pgsql-add <cls> 等剧本让配置落地。Pigsty 会根据参数生成 Patroni/pgbouncer/pgbackrest 等服务所需的配置文件。

Pigsty 默认的 Demo 清单 conf/pgsql.yml 就是一份最小化示例：一个 pg-meta 集群、全局 pg_version: 18、少量业务用户与数据库定义。你可以在此基础上扩展更多集群。

关注点与文档索引

Pigsty 的 PostgreSQL 配置可以从以下几个维度组合，后续文档会逐一展开“如何配置”：

  • 集群实例：通过 pg_cluster / pg_role / pg_seq / pg_upstream 定义实例拓扑（单机、主从、备份集群、延迟集群、Citus 等）。
  • 内核版本：使用 pg_version、pg_mode、pg_packages、pg_extensions、pg_conf 等参数挑选核心版本、风味和调优模板。
  • 用户/角色：在 pg_default_roles 与 pg_users 中声明系统角色、业务账号、密码策略以及连接池属性。
  • 数据库对象：借助 pg_databases、baseline、schemas、extensions、pool_* 字段按需创建数据库并自动接入 pgbouncer/Grafana。
  • 访问控制 (HBA)：利用 pg_default_hba_rules 与 pg_hba_rules 维护主机级认证策略，保证不同角色/网络的访问边界。
  • 权限模型 (ACL)：通过 pg_default_privileges、pg_default_roles、pg_revoke_public 等参数收敛对象权限，开箱即用地提供分层角色体系。

理解这些参数之后，你就可以针对任意业务需求写出“配置即基础设施”的声明式清单，Pigsty 会负责执行并确保幂等。

一个典型示例

下面的片段展示了如何在同一个配置文件中同时控制实例拓扑、内核版本、扩展、用户以及数据库：

all:
  children:
    pg-analytics:
      hosts:
        10.10.10.11: { pg_seq: 1, pg_role: primary }
        10.10.10.12: { pg_seq: 2, pg_role: replica, pg_offline_query: true }
      vars:
        pg_cluster: pg-analytics
        pg_conf: olap.yml
        pg_extensions: [ postgis, timescaledb, pgvector ]
        pg_databases:
          - { name: bi, owner: dbuser_bi, schemas: [mart], extensions: [timescaledb], pool_mode: session }
        pg_users:
          - { name: dbuser_bi, password: DBUser.BI, roles: [dbrole_admin], pgbouncer: true }
  vars:
    pg_version: 18
    pg_packages: [ pgsql-main, pgsql-common ]
    pg_hba_rules:
      - { user: dbuser_bi, db: bi, addr: intra, auth: ssl, title: 'BI 只允许内网 SSL 访问' }
  • pg-analytics 集群包含一个主库和一个离线副本。
  • 全局指定 pg_version: 18 与一套扩展示例，并加载 olap.yml 调优。
  • 在 pg_databases 与 pg_users 中声明业务对象，自动生成 schema/extension 与连接池条目。
  • 附加的 pg_hba_rules 限制了访问来源与认证方式。

修改并应用这份清单即可得到一套定制化的 PostgreSQL 集群，而无需手工逐项配置。

1.1 - 集群实例

根据需求场景选择合适的实例与集群类型，配置出满足需求的 PostgreSQL 数据库集群。

根据需求场景选择合适的实例与集群类型，配置出满足需求的 PostgreSQL 数据库集群。

您可以定义不同类型的实例和集群，下面是 Pigsty 中常见的几种 PostgreSQL 实例/集群类型：

读写主库

我们从最简单的情况开始：由一个主库（Primary）组成的单实例集群：

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-test

这段配置言简意赅，自我描述，仅由 身份参数 构成。为方便使用 -l pg-test 限定目标， 通常仍建议让 Ansible Group 分组名与 pg_cluster 一致，但这不是成员发现的硬约束； 当前源码会按各主机的 pg_cluster 身份计算实际成员，因此同一 PostgreSQL 集群可以跨越多个清单分组。

使用以下命令创建该集群：

bin/pgsql-add pg-test

Demo 展示，开发测试，承载临时需求，进行无关紧要的计算分析任务时，使用单一数据库实例可能并没有太大问题。但这样的单机集群没有 高可用，当出现硬件故障时，您需要使用 PITR 或其他恢复手段来确保集群的 RTO / RPO。为此，您可以考虑为集群添加若干个 只读从库

只读从库

要添加一台只读从库（Replica）实例，您可以在 pg-test 中添加一个新节点，并将其 pg_role 设置为 replica。

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }  # <--- 新添加的从库
  vars:
    pg_cluster: pg-test

如果整个集群不存在，您可以直接 创建 这个完整的集群。 如果集群主库已经初始化好了，那么您可以向现有集群 添加 一个从库：

bin/pgsql-add pg-test               # 一次性初始化整个集群
bin/pgsql-add pg-test 10.10.10.12   # 添加从库到现有的集群

当集群主库出现故障时，只读实例（Replica）可以在高可用系统的帮助下接管主库的工作。除此之外，只读实例还可以用于执行只读查询：许多业务的读请求要比写请求多很多，而大部分只读查询负载都可以由从库实例承担。

离线从库

离线实例（Offline）是专门用于服务慢查询、ETL、OLAP 流量和交互式查询等的专用只读从库。慢查询/长事务对在线业务的性能与稳定性有不利影响，因此最好将它们与在线业务隔离开来。

要添加离线实例，请为其分配一个新实例，并将 pg_role 设置为 offline。

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
    10.10.10.13: { pg_seq: 3, pg_role: offline }  # <--- 新添加的离线从库
  vars:
    pg_cluster: pg-test

专用离线实例的工作方式与常见的从库实例类似，但它在 pg-test-replica 服务中用作备份服务器。 也就是说，只有当所有 replica 实例都宕机时，离线和主实例才会提供此项只读服务。

许多情况下，数据库资源有限，单独使用一台服务器作为离线实例是不经济的做法。作为折中，您可以选择一台现有的从库实例，打上 pg_offline_query 标记，将其标记为一台可以承载"离线查询"的实例。在这种情况下，这台只读从库会同时承担在线只读请求与离线类查询。您可以使用 pg_default_hba_rules 和 pg_hba_rules 对离线实例进行额外的访问控制。

同步备库

当启用同步备库（Sync Standby）时，PostgreSQL 将选择一个从库作为 同步备库，其他所有从库作为 候选者。 主数据库会等待备库实例刷新到磁盘，然后才确认提交，备库实例始终拥有最新的数据，没有复制延迟，主从切换至同步备库不会有数据丢失。

PostgreSQL 默认使用异步流复制，主库故障时可能丢失尚未复制的 WAL。pg_rpo 配置的是 Patroni 候选副本的采样落后阈值，并非实际丢失量硬上限；实际窗口还取决于写入速率、复制状态与 Patroni 采样时机。

但在某些关键场景中（例如，金融交易），数据丢失是完全不可接受的，或者，读取复制延迟是不可接受的。在这种情况下，您可以使用同步提交来解决这个问题。 要启用同步备库模式，您可以简单地使用 pg_conf 中的 crit.yml 模板。

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
    10.10.10.13: { pg_seq: 3, pg_role: replica }
  vars:
    pg_cluster: pg-test
    pg_conf: crit.yml   # <--- 使用 crit 模板

要在现有集群上启用同步备库，请 配置集群 并启用 synchronous_mode：

$ pg edit-config pg-test    # 在管理员节点以管理员用户身份运行
+++
-synchronous_mode: false    # <--- 旧值
+synchronous_mode: true     # <--- 新值
 synchronous_mode_strict: false

应用这些更改？[y/N]: y

在这种情况下，PostgreSQL 配置项 synchronous_standby_names 由 Patroni 自动管理。 一台从库将被选拔为同步从库，它的 application_name 将被写入 PostgreSQL 主库配置文件中并应用生效。

法定人数提交

法定人数提交（Quorum Commit）提供了比同步备库更强大的控制能力：特别是当您有多个从库时，您可以设定提交成功的标准，实现更高/更低的一致性级别（以及可用性之间的权衡）。

如果想要 最少两个从 库来确认提交，可以通过 Patroni 配置集群，调整参数 synchronous_node_count 并应用生效

synchronous_mode: true          # 确保同步提交已经启用
synchronous_node_count: 2       # 指定“至少”有多少个从库提交成功，才算提交成功

如果你想要使用更多的同步从库，修改 synchronous_node_count 的取值即可。当集群的规模发生变化时，您应当确保这里的配置仍然是有效的，以避免服务不可用。

在这种情况下，PostgreSQL 配置项 synchronous_standby_names 由 Patroni 自动管理。

synchronous_standby_names = '2 ("pg-test-3","pg-test-2")'
示例：使用多个同步从库
$ pg edit-config pg-test
---
+synchronous_node_count: 2

Apply these changes? [y/N]: y

应用配置后，出现两个同步备库。

+ Cluster: pg-test (7080814403632534854) +---------+----+-----------+-----------------+
| Member    | Host        | Role         | State   | TL | Lag in MB | Tags            |
+-----------+-------------+--------------+---------+----+-----------+-----------------+
| pg-test-1 | 10.10.10.10 | Leader       | running |  1 |           | clonefrom: true |
| pg-test-2 | 10.10.10.11 | Sync Standby | running |  1 |         0 | clonefrom: true |
| pg-test-3 | 10.10.10.12 | Sync Standby | running |  1 |         0 | clonefrom: true |
+-----------+-------------+--------------+---------+----+-----------+-----------------+

另一种情景是，使用 任意 n 个 从库来确认提交。在这种情况下，配置的方式略有不同，例如，假设我们只需要任意一个从库确认提交：

synchronous_mode: quorum        # 使用法定人数提交
postgresql:
  parameters:                   # 修改 PostgreSQL 的配置参数 synchronous_standby_names ，使用 `ANY n ()` 语法
    synchronous_standby_names: 'ANY 1 (*)'  # 你可以指定具体的从库列表，或直接使用 * 通配所有从库。
示例：启用 ANY 法定人数提交
$ pg edit-config pg-test

+    synchronous_standby_names: 'ANY 1 (*)' # 在 ANY 模式下，需要使用此参数
- synchronous_node_count: 2  # 在 ANY 模式下， 不需要使用此参数

Apply these changes? [y/N]: y

应用后，配置生效，所有备库在 Patroni 中变为普通的 replica。但是在 pg_stat_replication 中可以看到 sync_state 会变为 quorum。

备份集群

您可以克隆现有的集群，并创建一个备份集群（Standby Cluster），用于数据迁移、水平拆分、多区域部署，或灾难恢复。

在正常情况下，备份集群将追随上游集群并保持内容同步，您可以将备份集群提升，作为真正地独立集群。

备份集群的定义方式与正常集群的定义基本相同，除了在主库上额外定义了 pg_upstream 参数，备份集群的主库被称为 备份集群领导者 （Standby Leader）。

例如，下面定义了一个 pg-test 集群，以及其备份集群 pg-test2，其配置清单可能如下所示：

# pg-test 是原始集群
pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
  vars: { pg_cluster: pg-test }

# pg-test2 是 pg-test 的备份集群
pg-test2:
  hosts:
    10.10.10.12: { pg_seq: 1, pg_role: primary , pg_upstream: 10.10.10.11 } # <--- pg_upstream 在这里定义
    10.10.10.13: { pg_seq: 2, pg_role: replica }
  vars: { pg_cluster: pg-test2 }

而 pg-test2 集群的主节点 pg-test2-1 将是 pg-test 的下游从库，并在 pg-test2 集群中充当备份集群领导者（Standby Leader）。

只需确保备份集群的主节点上配置了 pg_upstream 参数，以便自动从原始上游拉取备份。

bin/pgsql-add pg-test     # 创建原始集群
bin/pgsql-add pg-test2    # 创建备份集群
示例：更改复制上游

如有必要（例如，上游发生主从切换/故障转移），您可以通过 配置集群 更改备份集群的复制上游。

要这样做，只需将 standby_cluster.host 更改为新的上游 IP 地址并应用。

$ pg edit-config pg-test2

 standby_cluster:
   create_replica_methods:
   - basebackup
-  host: 10.10.10.13     # <--- 旧的上游
+  host: 10.10.10.12     # <--- 新的上游
   port: 5432

 Apply these changes? [y/N]: y
示例：提升备份集群

你可以随时将备份集群提升为独立集群，这样该集群就可以独立承载写入请求，并与原集群分叉。

为此，你必须 配置 该集群并完全擦除 standby_cluster 部分，然后应用。

$ pg edit-config pg-test2
-standby_cluster:
-  create_replica_methods:
-  - basebackup
-  host: 10.10.10.11
-  port: 5432

Apply these changes? [y/N]: y
示例：级联复制

如果您在一台从库上指定了 pg_upstream，而不是主库。那么可以配置集群的 级联复制（Cascade Replication）

在配置级联复制时，您必须使用集群中某一个实例的 IP 地址作为参数的值，否则初始化会报错。该从库从特定的实例进行流复制，而不是主库。

这台充当 WAL 中继器的实例被称为 桥接实例（Bridge Instance）。使用桥接实例可以分担主库发送 WAL 的负担，当您有几十台从库时，使用桥接实例级联复制是一个不错的注意。

pg-test:
 hosts: # pg-test-1 ---> pg-test-2 ---> pg-test-3
   10.10.10.11: { pg_seq: 1, pg_role: primary }
   10.10.10.12: { pg_seq: 2, pg_role: replica } # <--- 桥接实例
   10.10.10.13: { pg_seq: 3, pg_role: replica, pg_upstream: 10.10.10.12 }
   # ^--- 从 pg-test-2 (桥接)复制，而不是从 pg-test-1 (主节点) 
 vars: { pg_cluster: pg-test }

延迟集群

延迟集群（Delayed Cluster）是一种特殊类型的 备份集群，用于尽快恢复"意外删除"的数据。

例如，如果你希望有一个名为 pg-testdelay 的集群，其数据内容与一小时前的 pg-test 集群相同：

# pg-test 是原始集群
pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
  vars: { pg_cluster: pg-test }

# pg-testdelay 是 pg-test 的延迟集群
pg-testdelay:
  hosts:
    10.10.10.12: { pg_seq: 1, pg_role: primary , pg_upstream: 10.10.10.11, pg_delay: 1d }
    10.10.10.13: { pg_seq: 2, pg_role: replica }
  vars: { pg_cluster: pg-testdelay }

你还可以在现有的 备份集群 上 配置 一个"复制延迟"。

$ pg edit-config pg-testdelay
 standby_cluster:
   create_replica_methods:
   - basebackup
   host: 10.10.10.11
   port: 5432
+  recovery_min_apply_delay: 1h    # <--- 在此处添加延迟时长，例如1小时

Apply these changes? [y/N]: y

当某些元组和表格被意外删除时，你可以通过修改此参数的方式，将此延迟集群推进到适当的时间点，并从中读取数据，快速修复原始集群。

延迟集群需要额外的资源，但比起 PITR 要快得多，并且对系统的影响也小得多，对于非常关键的集群，可以考虑搭建延迟集群。

Citus集群

Pigsty 原生支持 Citus。可以参考 conf/ha/citus.yml 作为完整样例。

要定义一个 citus 集群，您需要指定以下参数：

  • pg_mode 必须设置为 citus，而不是默认的 pgsql
  • 在每个分片集群上都必须定义分片名 pg_shard 和分片号 pg_group
  • 必须定义 pg_primary_db 来指定由 Patroni 管理的 Citus 数据库。
  • 如果您想使用 pg_dbsu 的 postgres 而不是默认的 pg_admin_username 来执行管理命令，那么 pg_dbsu_password 必须设置为非空的纯文本密码

此外，还需要额外的 hba 规则，允许从本地和其他数据节点进行 SSL 访问。如下所示：

all:
  children:
    pg-citus0: # citus 0号分片
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus0 , pg_group: 0 }
    pg-citus1: # citus 1号分片
      hosts: { 10.10.10.11: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus1 , pg_group: 1 }
    pg-citus2: # citus 2号分片
      hosts: { 10.10.10.12: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus2 , pg_group: 2 }
    pg-citus3: # citus 3号分片
      hosts:
        10.10.10.13: { pg_seq: 1, pg_role: primary }
        10.10.10.14: { pg_seq: 2, pg_role: replica }
      vars: { pg_cluster: pg-citus3 , pg_group: 3 }
  vars:                               # 所有 Citus 集群的全局参数
    pg_mode: citus                    # pgsql 集群模式需要设置为： citus
    pg_shard: pg-citus                # citus 水平分片名称： pg-citus
    pg_primary_db: meta               # citus 数据库名称：meta
    pg_dbsu_password: DBUser.Postgres # 如果使用 dbsu ，那么需要为其配置一个密码
    pg_users: [ { name: dbuser_meta ,password: DBUser.Meta ,pgbouncer: true ,roles: [ dbrole_admin ] } ]
    pg_databases: [ { name: meta ,extensions: [ { name: citus }, { name: postgis }, { name: timescaledb } ] } ]
    pg_hba_rules:
      - { user: 'all' ,db: all  ,addr: 127.0.0.1/32 ,auth: ssl ,title: 'all user ssl access from localhost' }
      - { user: 'all' ,db: all  ,addr: intra        ,auth: ssl ,title: 'all user ssl access from intranet'  }

在协调者节点上，您可以创建分布式表和引用表，并从任何数据节点查询它们。从 11.2 开始，任何 Citus 数据库节点都可以扮演协调者的角色了。

SELECT create_distributed_table('pgbench_accounts', 'aid'); SELECT truncate_local_data_after_distributing_table($$public.pgbench_accounts$$);
SELECT create_reference_table('pgbench_branches')         ; SELECT truncate_local_data_after_distributing_table($$public.pgbench_branches$$);
SELECT create_reference_table('pgbench_history')          ; SELECT truncate_local_data_after_distributing_table($$public.pgbench_history$$);
SELECT create_reference_table('pgbench_tellers')          ; SELECT truncate_local_data_after_distributing_table($$public.pgbench_tellers$$);

1.2 - 内核版本

如何选择合适的 PostgreSQL 内核与大版本。

在 Pigsty 中选择"内核"意味着确定 PostgreSQL 大版本、模式/发行版、需要安装的包以及要加载的调优模板。

Pigsty v4.5 当前源码支持 PostgreSQL 14 - 18，默认使用 18。下方内容展示如何通过配置文件完成这些选择。

大版本与软件包

  • pg_version：指定 PostgreSQL 主版本（默认 18）。Pigsty 会根据版本自动映射到正确的包名前缀。
  • pg_packages：定义需要安装的核心包集合，支持使用 包别名（默认 pgsql-main pgsql-common，包含内核 + patroni/pgbouncer/pgbackrest 等常用工具）。
  • pg_extensions：额外需要安装的扩展包列表，同样支持别名；缺省为空表示只装核心依赖。
all:
  vars:
    pg_version: 18
    pg_packages: [ pgsql-main, pgsql-common ]
    pg_extensions: [ postgis, timescaledb, pgvector, pgml ]

效果：Ansible 在安装阶段会拉取与 pg_version=18 对应的包，将扩展预装到系统中，随后数据库初始化脚本即可直接 CREATE EXTENSION。

Pigsty 的离线仓库中不同版本的扩展支持范围不同：14 可用扩展相对较少，17/18 覆盖最广。若某扩展未预打包，可通过 repo_extra_packages 追加。

内核模式（pg_mode）

pg_mode 控制要部署的内核“风味”，默认 pgsql 表示标准 PostgreSQL。Pigsty 目前支持以下模式：

模式 场景
pgsql 标准 PostgreSQL，高可用 + 复制
citus Citus 分布式集群，需要额外的 pg_shard / pg_group
gpsql Cloudberry / Greenplum / MatrixDB
mssql Babelfish
mysql OpenGauss/HaloDB 兼容 MySQL 协议
polar 阿里 PolarDB（基于 pg polar 发行）
ivory IvorySQL（Oracle 兼容语法）
pgtde Percona PostgreSQL + pg_tde，使用 /usr/pgtde-$v
oriole OrioleDB 存储引擎
agens AgensGraph 图数据库内核
pgedge pgEdge 分布式复制内核

pg_mode 决定二进制路径、Patroni 集成方式及部分内核特定逻辑；它本身不会自动替你补齐所有软件包、扩展与业务数据库。实际部署时应使用匹配的 conf/*.yml 配置模板，或显式配置 pg_packages、pg_extensions、pg_libs 与 pg_databases。以下是一个精简的 Citus 示例：

all:
  children:
    pg-citus1:
      hosts: { 10.10.10.11: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus1, pg_group: 0 }
    pg-citus2:
      hosts: { 10.10.10.12: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus2, pg_group: 1 }
  vars:
    pg_mode: citus
    pg_shard: pg-citus
    pg_primary_db: citus
    pg_extensions: [ citus ]
    pg_libs: 'citus, pg_stat_statements'
    pg_databases:
      - { name: citus, extensions: [ citus ] }

conf/ha/citus.yml 提供了当前完整样例；上面的精简配置显式安装 Citus 包，并在 citus 数据库中创建扩展。

扩展与预置对象

除了系统包，你还可以通过以下参数控制数据库启动后自动加载的组件：

  • pg_libs：写入 shared_preload_libraries 的列表。例如 pg_libs: 'timescaledb, pg_stat_statements, auto_explain'。
  • pg_default_extensions / pg_default_schemas：控制初始化脚本对 template1 与 postgres 预创建的 schema、扩展。
  • pg_parameters：由 Pigsty 在配置阶段渲染进 postgresql.auto.conf；不要再手工执行 ALTER SYSTEM 管理同一批参数。

示例：启用 TimescaleDB、pgvector 并自定义一些系统参数。

pg-analytics:
  vars:
    pg_cluster: pg-analytics
    pg_libs: 'timescaledb, pg_stat_statements, auto_explain'
    pg_default_extensions:
      - { name: timescaledb }
      - { name: vector }
    pg_parameters:
      timescaledb.max_background_workers: 8

效果：初始化时 template1 与 postgres 会创建默认扩展；新建且使用 template1 的业务库会继承这些对象。pg_parameters 则直接写入 postgresql.auto.conf。

调优模板 (pg_conf)

pg_conf 指向 roles/pgsql/templates/*.yml 中的 Patroni 模板。Pigsty 内置四套通用模板：

模板 适用场景
oltp.yml 默认模板，面向 4–128 核的 TP 负载
olap.yml 针对分析场景优化
crit.yml 强调同步提交/最小延迟，适合金融等零丢失场景
tiny.yml 轻量机 / 边缘场景 / 资源受限环境

你可以直接替换模板或自定义一个 YAML 文件放在 templates/ 下，然后在集群 vars 里指定。

pg-ledger:
  hosts: { 10.10.10.21: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-ledger
    pg_conf: crit.yml
    pg_parameters:
      synchronous_commit: 'remote_apply'
      max_wal_senders: 16
      wal_keep_size: '2GB'

效果：拷贝 crit.yml 作为 Patroni 配置，叠加 pg_parameters 写入 postgresql.auto.conf，使实例立即以同步提交模式运行。

组合实例：一个完整示例 

pg-rag:
  hosts:
    10.10.10.31: { pg_seq: 1, pg_role: primary }
    10.10.10.32: { pg_seq: 2, pg_role: replica }
  vars:
    pg_cluster: pg-rag
    pg_version: 18
    pg_mode: pgsql
    pg_conf: olap.yml
    pg_packages: [ pgsql-main, pgsql-common ]
    pg_extensions: [ pgvector, pgml, postgis ]
    pg_libs: 'pg_stat_statements, auto_explain'
    pg_parameters:
      max_parallel_workers: 8
      shared_buffers: '32GB'
  • 第一台主库 + 一台 replica，使用 olap.yml 调优。
  • 安装 PG18 + RAG 常用扩展；只有需要预加载的库才应写入 pg_libs。
  • Patroni/pgbouncer/pgbackrest 由 Pigsty 生成，无需手工干预。

根据业务需要替换上述参数即可完成内核层的全部定制。

1.3 - 别名翻译

Pigsty 提供软件包别名翻译机制，可以屏蔽底层操作系统的二进制包细节差异，让安装更简易。

PostgreSQL 在不同操作系统上的软件包命名规则存在显著差异：

  • EL 系统（RHEL/Rocky/Alma/…）使用 pgvector_18，postgis36_18* 这样的格式
  • Debian/Ubuntu 系统 使用 postgresql-18-pgvector，postgresql-18-postgis-3 这样的格式

这种差异给用户带来了额外的认知负担：您需要记住不同系统的包名规则，还要处理 PostgreSQL 版本号嵌入的问题。

软件包别名

Pigsty 通过 软件包别名（Package Alias） 机制解决了这个问题：您只需使用统一的别名，Pigsty 会处理好所有细节：

# 使用别名 —— 简单、统一、跨平台
pg_extensions: [ postgis, pgvector, timescaledb ]

# 等效于 EL9 + PG18 上的实际包名
pg_extensions: [ postgis36_18*, pgvector_18*, timescaledb-tsl_18* ]

# 等效于 Ubuntu 24 + PG18 上的实际包名
pg_extensions: [ postgresql-18-postgis-3, postgresql-18-pgvector, postgresql-18-timescaledb-tsl ]

别名翻译

别名还可以将一组软件包归类为一个整体，例如 Pigsty 默认安装的软件包 —— pg_packages 的默认值是：

pg_packages:                      # pg packages to be installed, alias can be used
  - pgsql-main pgsql-common

Pigsty 将查询当前的操作系统别名清单（假设为 el10.x86_64），将其翻译为 PGSQL 内核，扩展，以及工具包：

pgsql-main:    "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl postgresql$v-llvmjit pg_repack_$v* wal2json_$v* pgvector_$v*"
pgsql-common:  "patroni patroni-etcd pgbouncer pgbackrest pg_exporter pgbackrest_exporter vip-manager"

接下来，Pigsty 又进一步通过当前指定的 PG 大版本（假设 pg_version = 18），将 pgsql-main 翻译为：

pg18-main:   "postgresql18 postgresql18-server postgresql18-libs postgresql18-contrib postgresql18-plperl postgresql18-plpython3 postgresql18-pltcl postgresql18-llvmjit pg_repack_18* wal2json_18* pgvector_18*"

通过这种方式，Pigsty 屏蔽了软件包的复杂性，让用户可以简单的指定自己想要的功能组件。

哪些变量可以使用别名？

您可以在以下四个参数中使用包别名，别名会根据翻译流程自动转换为实际的软件包名称：

别名列表

你可以在 Pigsty 项目源代码的 roles/node_id/vars/ 目录下，找到各操作系统与架构对应的别名映射文件：

工作原理

别名翻译流程 

用户配置别名 --> 检测操作系统 -->  查找别名映射表 ---> 替换$v占位符 ---> 安装实际软件包
     ↓              ↓               ↓                               ↓
  postgis      el9.x86_64      postgis36_$v*                postgis36_18*
  postgis      u24.x86_64      postgresql-$v-postgis-3      postgresql-18-postgis-3

版本占位符

Pigsty 的别名系统使用 $v 作为 PostgreSQL 版本号的占位符。当您使用 pg_version 指定了 PostgreSQL 版本后，所有别名中的 $v 都会被替换为实际版本号。

例如，当 pg_version: 18 时：

别名定义 (EL) 展开结果
postgresql$v* postgresql18*
pgvector_$v* pgvector_18*
timescaledb-tsl_$v* timescaledb-tsl_18*
别名定义 (Debian/Ubuntu) 展开结果
postgresql-$v postgresql-18
postgresql-$v-pgvector postgresql-18-pgvector
postgresql-$v-timescaledb-tsl postgresql-18-timescaledb-tsl

通配符匹配

在 EL 系统上，许多别名使用 * 通配符来匹配相关的子包。例如：

  • postgis36_18* 会匹配 postgis36_18、postgis36_18-client、postgis36_18-utils 等
  • postgresql18* 会匹配 postgresql18、postgresql18-server、postgresql18-libs、postgresql18-contrib 等

这种设计确保您无需逐一列出每个子包，一个别名即可安装完整的扩展。

1.4 - 用户/角色

如何通过配置来定制所需 PostgreSQL 用户与角色？

在本文中，“用户”（User） 指的是使用 SQL 命令 CREATE USER/ROLE 创建的，数据库集簇内的逻辑对象。

在 PostgreSQL 中，用户直接隶属于数据库集簇而非某个具体的数据库。因此在创建业务数据库和业务用户时，应当遵循"先用户，后数据库"的原则。

Pigsty 通过两个配置参数定义数据库集群中的角色与用户：

  • pg_default_roles：定义全局统一使用的角色和用户
  • pg_users：在数据库集群层面定义业务用户和角色

前者用于定义整套环境中共用的角色与用户，后者定义单个集群中特有的业务角色与用户。二者形式相同，均为用户定义对象的数组。 用户/角色按数组顺序逐一创建，因此后定义的用户可以属于先定义的角色。

默认情况下，所有带有 pgbouncer: true 标记的用户都会被添加到 Pgbouncer 连接池用户列表中。

定义用户

下面是 Pigsty 演示环境中默认集群 pg-meta 中的业务用户定义：

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_users:
      - {name: dbuser_meta     ,password: DBUser.Meta     ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: pigsty admin user }
      - {name: dbuser_view     ,password: DBUser.Viewer   ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer for meta database }
      - {name: dbuser_grafana  ,password: DBUser.Grafana  ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for grafana database    }
      - {name: dbuser_bytebase ,password: DBUser.Bytebase ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for bytebase database   }
      - {name: dbuser_kong     ,password: DBUser.Kong     ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for kong api gateway    }
      - {name: dbuser_gitea    ,password: DBUser.Gitea    ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for gitea service       }
      - {name: dbuser_wiki     ,password: DBUser.Wiki     ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for wiki.js service     }
      - {name: dbuser_noco     ,password: DBUser.Noco     ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for nocodb service      }
      - {name: dbuser_remove   ,state: absent }  # 使用 state: absent 删除用户

每个用户/角色定义都是一个复杂对象，可能包括以下字段，除了 name 字段外，其他字段均为可选字段：

- name: dbuser_meta               # 必选，`name` 是用户定义的唯一必选字段
  state: create                   # 可选，用户状态：create（创建，默认）、absent（删除）
  password: DBUser.Meta           # 可选，密码，可以是 scram-sha-256 哈希字符串或明文
  login: true                     # 可选，默认为 true，是否可以登录
  superuser: false                # 可选，默认为 false，是否是超级用户
  createdb: false                 # 可选，默认为 false，是否可以创建数据库
  createrole: false               # 可选，默认为 false，是否可以创建角色
  inherit: true                   # 可选，默认为 true，是否自动继承所属角色权限
  replication: false              # 可选，默认为 false，是否可以发起流复制连接
  bypassrls: false                # 可选，默认为 false，是否可以绕过行级安全
  connlimit: -1                   # 可选，用户连接数限制，默认 -1 不限制
  expire_in: 3650                 # 可选，从创建时起 N 天后过期（优先级比 expire_at 高）
  expire_at: '2030-12-31'         # 可选，过期日期，使用 YYYY-MM-DD 格式（优先级没 expire_in 高）
  comment: pigsty admin user      # 可选，用户备注信息
  roles: [dbrole_admin]           # 可选，所属角色数组
  parameters:                     # 可选，角色级配置参数
    search_path: public
  pgbouncer: true                 # 可选，是否加入连接池用户列表，默认 false
  pool_mode: transaction          # 可选，用户级别的池化模式，默认 transaction
  pool_connlimit: 100             # 可选，用户级别的连接池最大连接数；省略时继承全局默认 100

用户级连接池限额字段统一使用 pool_connlimit（对应 Pgbouncer max_user_connections）。

参数总览

所有参数中唯一 必选 的字段是 name，它应该是当前 PostgreSQL 集群中有效且唯一的用户名，其他参数都有合理的默认值，均为可选项。

字段 分类 类型 属性 说明
name 基本 string 必选 用户名，必须是有效且唯一的标识符
state 基本 enum 可选 用户状态：create（默认）、absent
password 基本 string 可变 用户密码，明文或哈希
comment 基本 string 可变 用户备注信息
login 权限 bool 可变 是否允许登录，默认 true
superuser 权限 bool 可变 是否为超级用户，默认 false
createdb 权限 bool 可变 是否可创建数据库，默认 false
createrole 权限 bool 可变 是否可创建角色，默认 false
inherit 权限 bool 可变 是否继承所属角色权限，默认 true
replication 权限 bool 可变 是否可进行复制，默认 false
bypassrls 权限 bool 可变 是否可绕过行级安全，默认 false
connlimit 权限 int 可变 连接数限制，-1 表示不限制
expire_in 有效期 int 可变 从当前日期起 N 天后过期（优先级高于 expire_at）
expire_at 有效期 string 可变 过期日期，YYYY-MM-DD 格式
roles 角色 array 增量 所属角色数组，支持字符串或对象格式
parameters 参数 object 可变 角色级参数
pgbouncer 连接池 bool 可变 是否加入连接池，默认 false
pool_mode 连接池 enum 可变 池化模式：transaction（默认）
pool_connlimit 连接池 int 可变 连接池用户最大连接数

参数详情

name

字符串，必选参数，表示用户的名称，在一个数据库集群内必须唯一。

用户名必须是有效的 PostgreSQL 标识符，必须匹配正则表达式 ^[a-z_][a-z0-9_]{0,62}$： 以小写字母或下划线开头，只能包含小写字母、数字、下划线，最长 63 个字符。

- name: dbuser_app         # 标准命名
- name: app_readonly       # 下划线分隔
- name: _internal          # 下划线开头（用于内部角色）

state

枚举值，用于指定要对用户执行的操作，可以是 create 或 absent，默认值为 create。

状态 说明
create 默认，创建用户，如果已存在则更新属性
absent 删除用户，使用 DROP ROLE 
- name: dbuser_app             # state 默认为 create
- name: dbuser_old
  state: absent                # 删除用户

以下系统用户无法通过 state: absent 删除，这是为了防止误删关键系统用户导致集群故障：

password

字符串，可变参数，用于设置用户密码，不指定则用户无法使用密码登录。

密码可以是以下格式之一：

格式 示例 说明
明文密码 DBUser.Meta 不推荐，会被记录到配置文件和日志
SCRAM-SHA-256 SCRAM-SHA-256$4096:xxx$yyy:zzz 推荐，PostgreSQL 10+ 默认认证方式
MD5 哈希 md5... 兼容旧版本，不推荐新项目使用 
# 明文密码（不推荐，会被记录到配置和日志中）
- name: dbuser_app
  password: MySecretPassword

# SCRAM-SHA-256 哈希（推荐）
- name: dbuser_app
  password: 'SCRAM-SHA-256$4096:xxx$yyy:zzz'

设置密码时，Pigsty 会临时屏蔽当前会话的日志记录以避免密码泄露：

SET log_statement TO 'none';
ALTER USER "dbuser_app" PASSWORD 'xxx';
SET log_statement TO DEFAULT;

如果你不希望在配置文件中记录明文密码，可以使用 SCRAM-SHA-256 哈希字符串代替明文密码。生成 SCRAM-SHA-256 哈希的方法：

# 使用 PostgreSQL 生成（需要先连接到数据库，数据库有 pgcrypto 扩展）
psql -c "SELECT encode(digest('password' || 'username', 'sha256'), 'hex')"

comment

字符串，可变参数，用于设置用户的备注信息，如果不指定，默认值为 business user {name}。

用户备注信息通过 COMMENT ON ROLE 语句设置，支持中文和特殊字符（Pigsty 会自动转义单引号）。

- name: dbuser_app
  comment: '业务应用主账号'
COMMENT ON ROLE "dbuser_app" IS '业务应用主账号';

login

布尔值，可变参数，用于控制用户是否可以登录，默认值为 true。

设置为 false 则创建的是无法登陆的 角色（Role）而非用户（User），通常用于权限分组。

在 PostgreSQL 中，CREATE USER 等价于 CREATE ROLE ... LOGIN。

# 创建可登录用户
- name: dbuser_app
  login: true

# 创建角色（不可登录，用于权限分组）
- name: dbrole_custom
  login: false
  comment: 自定义权限角色
CREATE USER "dbuser_app" LOGIN;
CREATE USER "dbrole_custom" NOLOGIN;

superuser

布尔值，可变参数，用于指定用户是否为超级用户，默认值为 false。

超级用户拥有数据库的全部权限，可以绕过所有权限检查。

- name: dbuser_admin
  superuser: true            # 危险：拥有全部权限
ALTER USER "dbuser_admin" SUPERUSER;

Pigsty 已经提供了默认的超级用户 pg_admin_username （dbuser_dba） 除非绝对必要，否则不应创建额外的超级用户。

createdb

布尔值，可变参数，用于指定用户是否可以创建数据库，默认值为 false。

- name: dbuser_dev
  createdb: true             # 允许创建数据库
ALTER USER "dbuser_dev" CREATEDB;

一些应用软件可能会要求自己创建数据库，例如 Gitea，Odoo 等，因此您可能需要为这些应用的管理员用户启用 CREATEDB 权限。

createrole

布尔值，可变参数，用于指定用户是否可以创建其他角色，默认值为 false。

拥有 CREATEROLE 权限的用户可以创建、修改、删除其他非超级用户角色。

- name: dbuser_admin
  createrole: true           # 允许管理其他角色
ALTER USER "dbuser_admin" CREATEROLE;

inherit

布尔值，可变参数，用于控制用户是否自动继承所属角色的权限，默认值为 true。

设置为 false 时，用户需要通过 SET ROLE 显式切换角色才能使用所属角色的权限。

# 自动继承角色权限（默认）
- name: dbuser_app
  inherit: true
  roles: [dbrole_readwrite]

# 需要显式切换角色
- name: dbuser_special
  inherit: false
  roles: [dbrole_admin]
ALTER USER "dbuser_special" NOINHERIT;
-- 用户需要执行 SET ROLE dbrole_admin 才能获得该角色权限（必要但不充分）

replication

布尔值，可变参数，用于指定用户是否可以发起流复制连接，默认值为 false。

通常只有复制用户（如 replicator）需要此权限。普通业务用户不应该拥有此权限，除非这是一个逻辑解码订阅者。

- name: replicator
  replication: true          # 允许流复制连接
  roles: [pg_monitor, dbrole_readonly]
ALTER USER "replicator" REPLICATION;

bypassrls

布尔值，可变参数，用于指定用户是否可以绕过行级安全（RLS）策略，默认值为 false。

启用此权限后，用户可以访问所有行，即使表上定义了行级安全策略。此权限通常只授予管理员用户。

- name: dbuser_myappadmin
  bypassrls: true            # 绕过行级安全策略
ALTER USER "dbuser_myappadmin" BYPASSRLS;

connlimit

整数，可变参数，用于限制用户的最大并发连接数，默认值为 -1，表示不限制。

设置为正整数时，会限制该用户同时建立的最大数据库连接数。此限制不影响超级用户。

- name: dbuser_app
  connlimit: 100             # 最多 100 个并发连接

- name: dbuser_batch
  connlimit: 10              # 批处理用户限制连接数
ALTER USER "dbuser_app" CONNECTION LIMIT 100;

expire_in

整数，可变参数，用于指定用户从当前日期起多少天后过期。

此参数优先级高于 expire_at，如果同时指定两者，只有 expire_in 生效。

每次执行剧本时会根据当前日期重新计算过期时间，适合用于临时用户或需要定期续期的场景。

- name: temp_user
  expire_in: 30              # 30 天后过期

- name: contractor_user
  expire_in: 90              # 90 天后过期

执行时会计算实际过期日期并生成对应的 SQL：

-- expire_in: 30, 假设当前日期为 2025-01-01
ALTER USER "temp_user" VALID UNTIL '2025-01-31';

expire_at

字符串，可变参数，用于指定用户的过期日期，格式为 YYYY-MM-DD 或特殊值 infinity。

此参数优先级低于 expire_in。使用 infinity 表示用户永不过期。

- name: contractor_user
  expire_at: '2024-12-31'    # 指定日期过期

- name: permanent_user
  expire_at: 'infinity'      # 永不过期
ALTER USER "contractor_user" VALID UNTIL '2024-12-31';
ALTER USER "permanent_user" VALID UNTIL 'infinity';

roles

数组，增量参数，用于定义用户所属的角色。数组元素可以是字符串或对象。

简单格式使用字符串直接指定角色名：

- name: dbuser_app
  roles:
    - dbrole_readwrite
    - pg_read_all_data
GRANT "dbrole_readwrite" TO "dbuser_app";
GRANT "pg_read_all_data" TO "dbuser_app";

完整格式使用对象定义，支持更精细的角色成员关系控制：

- name: dbuser_app
  roles:
    - dbrole_readwrite                            # 简单字符串：GRANT 角色
    - { name: dbrole_admin, admin: true }         # 带 ADMIN OPTION
    - { name: pg_monitor, set: false }            # PG16+: 不允许 SET ROLE
    - { name: pg_signal_backend, inherit: false } # PG16+: 不自动继承权限
    - { name: old_role, state: absent }           # 撤销角色成员关系

对象格式参数说明：

参数 类型 说明
name string 角色名称（必选）
state enum grant（默认）或 absent/revoke：控制授予或撤销
admin bool true：WITH ADMIN OPTION，false：REVOKE ADMIN
set bool PG16+：true：WITH SET TRUE，false：REVOKE SET
inherit bool PG16+：true：WITH INHERIT TRUE，false：REVOKE INHERIT

PostgreSQL 16+ 新特性：

PostgreSQL 16 引入了更细粒度的角色成员关系控制：

  • ADMIN OPTION：允许将角色授予其他用户
  • SET OPTION：允许使用 SET ROLE 切换到该角色
  • INHERIT OPTION：是否自动继承该角色的权限
# PostgreSQL 16+ 完整示例
- name: dbuser_app
  roles:
    # 普通成员关系
    - dbrole_readwrite

    # 可以将 dbrole_admin 授予其他用户
    - { name: dbrole_admin, admin: true }

    # 不能 SET ROLE 到 pg_monitor（只能通过继承使用权限）
    - { name: pg_monitor, set: false }

    # 不自动继承 pg_execute_server_program 的权限（需要显式 SET ROLE）
    - { name: pg_execute_server_program, inherit: false }

    # 撤销 old_role 的成员关系
    - { name: old_role, state: absent }

set 和 inherit 选项仅在 PostgreSQL 16+ 中有效，在早期版本会被忽略并在生成的 SQL 中添加警告注释。

parameters

对象，可变参数，用于设置角色级别的配置参数。参数通过 ALTER ROLE ... SET 设置，会对该用户的所有会话生效。

- name: dbuser_analyst
  parameters:
    work_mem: '256MB'
    statement_timeout: '5min'
    search_path: 'analytics,public'
    log_statement: 'all'
ALTER USER "dbuser_analyst" SET "work_mem" = '256MB';
ALTER USER "dbuser_analyst" SET "statement_timeout" = '5min';
ALTER USER "dbuser_analyst" SET "search_path" = 'analytics,public';
ALTER USER "dbuser_analyst" SET "log_statement" = 'all';

使用特殊值 DEFAULT（大小写不敏感）可以将参数重置为 PostgreSQL 默认值：

- name: dbuser_app
  parameters:
    work_mem: DEFAULT          # 重置为默认值
    statement_timeout: '30s'   # 设置新值
ALTER USER "dbuser_app" SET "work_mem" = DEFAULT;
ALTER USER "dbuser_app" SET "statement_timeout" = '30s';

常用角色级参数：

参数 说明 示例值
work_mem 查询工作内存 '64MB'
statement_timeout 语句超时时间 '30s'
lock_timeout 锁等待超时 '10s'
idle_in_transaction_session_timeout 空闲事务超时 '10min'
search_path Schema 搜索路径 'app,public'
log_statement 日志记录级别 'ddl'
temp_file_limit 临时文件大小限制 '10GB'

您可以从数据库的 pg_db_role_setting 系统视图查询用户级别的参数设置。

pgbouncer

布尔值，可变参数，用于控制是否将用户添加到 Pgbouncer 连接池用户列表，默认值为 false。

对于需要通过连接池访问数据库的生产用户，必须显式设置 pgbouncer: true。 默认为 false 是为了避免意外将内部用户暴露给连接池。

# 生产用户：需要连接池
- name: dbuser_app
  password: DBUser.App
  pgbouncer: true

# 内部用户：不需要连接池
- name: dbuser_internal
  password: DBUser.Internal
  pgbouncer: false           # 默认值，可省略

设置 pgbouncer: true 的用户会被添加到 /etc/pgbouncer/userlist.txt 文件中。

pool_mode

枚举值，可变参数，用于设置用户级别的池化模式，可选值为 transaction、session 或 statement，默认值为 transaction。

模式 说明 适用场景
transaction 事务结束后归还连接 大多数 OLTP 应用，默认推荐
session 会话结束后归还连接 需要会话状态的应用（如 SET 命令）
statement 每条语句后归还连接 简单无状态查询，极致复用 
# DBA 用户使用 session 模式（可能需要 SET 命令等会话状态）
- name: dbuser_dba
  pgbouncer: true
  pool_mode: session

# 普通业务用户使用 transaction 模式
- name: dbuser_app
  pgbouncer: true
  pool_mode: transaction

用户级别的连接池参数通过 /etc/pgbouncer/useropts.txt 文件配置：

dbuser_dba      = pool_mode=session max_user_connections=16
dbuser_monitor  = pool_mode=session max_user_connections=8

pool_connlimit

整数，可变参数，用于设置用户级别的连接池最大连接数。省略时不生成用户级覆盖项，继承 Pigsty 在 pgbouncer.ini 中设置的全局默认值 100；PgBouncer 使用 0 表示不限制。

- name: dbuser_app
  pgbouncer: true
  pool_connlimit: 50         # 此用户最多使用 50 个连接池连接

ACL 系统

Pigsty 提供一套内置的访问控制 / ACL 模型，可以将以下默认业务角色分配给用户：

角色 权限说明 典型使用场景
dbrole_readwrite 全局读写访问 主属业务的生产账号
dbrole_readonly 全局只读访问 其他业务的只读访问
dbrole_admin 拥有 DDL 权限 业务管理员，需要建表的场景
dbrole_offline 独立只读访问；实例范围由 HBA 控制 个人用户，ETL/分析任务 
# 典型业务用户配置
pg_users:
  - name: dbuser_app
    password: DBUser.App
    pgbouncer: true
    roles: [dbrole_readwrite]    # 生产账号，读写权限

  - name: dbuser_readonly
    password: DBUser.Readonly
    pgbouncer: true
    roles: [dbrole_readonly]     # 只读账号

  - name: dbuser_admin
    password: DBUser.Admin
    pgbouncer: true
    roles: [dbrole_admin]        # 管理员，可执行 DDL

  - name: dbuser_etl
    password: DBUser.ETL
    roles: [dbrole_offline]      # 分析账号；另用 HBA 限制实例范围

dbrole_offline 本身不会把用户限制到离线实例。若需要该边界，应为对应 HBA 规则设置 role: offline；详见 离线角色与实例隔离。

如果您希望重新设计您自己的 ACL 系统，可以考虑定制以下参数和模板：

Pgbouncer 用户

默认情况下启用 Pgbouncer 作为连接池中间件。Pigsty 默认将 pg_users 中显式带有 pgbouncer: true 标志的所有用户添加到 Pgbouncer 用户列表中。

Pgbouncer 连接池中的用户在 /etc/pgbouncer/userlist.txt 中列出：

"postgres" ""
"dbuser_wiki" "SCRAM-SHA-256$4096:+77dyhrPeFDT/TptHs7/7Q==$KeatuohpKIYzHPCt/tqBu85vI11o9mar/by0hHYM2W8=:X9gig4JtjoS8Y/o1vQsIX/gY1Fns8ynTXkbWOjUfbRQ="
"dbuser_view" "SCRAM-SHA-256$4096:DFoZHU/DXsHL8MJ8regdEw==$gx9sUGgpVpdSM4o6A2R9PKAUkAsRPLhLoBDLBUYtKS0=:MujSgKe6rxcIUMv4GnyXJmV0YNbf39uFRZv724+X1FE="
"dbuser_monitor" "SCRAM-SHA-256$4096:fwU97ZMO/KR0ScHO5+UuBg==$CrNsmGrx1DkIGrtrD1Wjexb/aygzqQdirTO1oBZROPY=:L8+dJ+fqlMQh7y4PmVR/gbAOvYWOr+KINjeMZ8LlFww="
"dbuser_meta" "SCRAM-SHA-256$4096:leB2RQPcw1OIiRnPnOMUEg==$eyC+NIMKeoTxshJu314+BmbMFpCcspzI3UFZ1RYfNyU=:fJgXcykVPvOfro2MWNkl5q38oz21nSl1dTtM65uYR1Q="

用户级别的连接池参数使用另一个单独的文件 /etc/pgbouncer/useropts.txt 进行维护：

dbuser_dba      = pool_mode=session max_user_connections=16
dbuser_monitor  = pool_mode=session max_user_connections=8

当您 创建用户 时，Pgbouncer 的用户列表定义文件将会被刷新，并通过在线重载配置的方式生效，不会影响现有的连接。

Pgbouncer 使用和 PostgreSQL 相同的 dbsu 运行，默认为 postgres 操作系统用户。您可以使用 pgb 别名，使用 dbsu 访问 Pgbouncer 管理功能。

pgbouncer_auth_query 参数允许您使用动态查询来完成连接池用户认证，当您不想手动管理连接池中的用户时，这是一种便捷的方案。

相关资源

关于用户管理操作，请参考 用户管理 一节。

关于用户的访问权限，请参考 访问控制：角色体系。

1.5 - 数据库

如何通过配置来定制所需 PostgreSQL 数据库？

在本文中，“数据库”（Database） 指的是使用 SQL 命令 CREATE DATABASE 创建的，数据库集簇内的逻辑对象。

一组 PostgreSQL 服务器可以同时服务于多个 数据库 （Database）。在 Pigsty 中，你可以在集群配置中 定义 好所需的数据库。

Pigsty 会对默认模板数据库 template1 进行修改与定制，创建默认模式，安装默认扩展，配置默认权限，新创建的数据库默认会从 template1 继承这些设置。 您也可以通过 template 参数指定其他模板数据库，实现瞬间 数据库克隆。

默认情况下，所有业务数据库都会被 1:1 添加到 Pgbouncer 连接池 中；pg_exporter 默认会通过 自动发现 机制查找所有业务数据库并进行库内对象监控。 所有数据库也会添加到所有 INFRA节点 上的 Grafana 中， 注册为 PostgreSQL 数据源供 PGCAT 监控面板使用。

定义数据库

业务数据库定义在数据库集群参数 pg_databases 中，这是一个数据库定义构成的对象数组。 在集群初始化时，数组内的数据库按照 定义顺序 依次创建，因此后面定义的数据库可以使用先前定义的数据库作为 模板。

下面是 Pigsty 演示环境中默认集群 pg-meta 中的数据库定义：

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_databases:
      - { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [{name: postgis, schema: public}, {name: timescaledb}]}
      - { name: grafana  ,owner: dbuser_grafana  ,revokeconn: true ,comment: grafana primary database }
      - { name: bytebase ,owner: dbuser_bytebase ,revokeconn: true ,comment: bytebase primary database }
      - { name: kong     ,owner: dbuser_kong     ,revokeconn: true ,comment: kong the api gateway database }
      - { name: gitea    ,owner: dbuser_gitea    ,revokeconn: true ,comment: gitea meta database }
      - { name: wiki     ,owner: dbuser_wiki     ,revokeconn: true ,comment: wiki meta database }
      - { name: noco     ,owner: dbuser_noco     ,revokeconn: true ,comment: nocodb database }

每个数据库定义都是一个复杂对象，可能包括以下字段，除了 name 字段外，其他字段均为可选字段：

- name: meta                      # 必选，`name` 是数据库定义的唯一必选字段
  state: create                   # 可选，数据库状态：create（创建，默认）、absent（删除）、recreate（重建）
  baseline: cmdb.sql              # 可选，数据库 sql 的基线定义文件路径（ansible 搜索路径中的相对路径，如 files/）
  pgbouncer: true                 # 可选，是否将此数据库添加到 pgbouncer 数据库列表？默认为 true
  schemas: [pigsty]               # 可选，要创建的附加模式，由模式名称字符串组成的数组
  extensions:                     # 可选，要安装的附加扩展： 扩展对象的数组
    - { name: postgis , schema: public }  # 可以指定将扩展安装到某个模式中，也可以不指定（不指定则安装到 search_path 首位模式中）
    - { name: timescaledb }               # 例如有的扩展会创建并使用固定的模式，就不需要指定模式。
  comment: pigsty meta database   # 可选，数据库的说明与备注信息
  owner: postgres                 # 可选，数据库所有者，不指定则为当前用户
  template: template1             # 可选，要使用的模板，默认为 template1，目标必须是一个模板数据库
  strategy: FILE_COPY             # 可选，克隆策略：FILE_COPY 或 WAL_LOG（PG15+），不指定使用 PG 默认
  encoding: UTF8                  # 可选，不指定则继承模板/集群配置（UTF8）
  locale: C                       # 可选，不指定则继承模板/集群配置（C）
  lc_collate: C                   # 可选，不指定则继承模板/集群配置（C）
  lc_ctype: C                     # 可选，不指定则继承模板/集群配置（C）
  locale_provider: libc           # 可选，本地化提供者：libc、icu、builtin（PG15+）
  icu_locale: en-US               # 可选，ICU 本地化规则（PG15+）
  icu_rules: ''                   # 可选，ICU 排序规则（PG16+）
  builtin_locale: C.UTF-8         # 可选，内置本地化提供者规则（PG17+）
  tablespace: pg_default          # 可选，默认表空间，默认为 'pg_default'
  is_template: false              # 可选，是否标记为模板数据库，允许任何有 CREATEDB 权限的用户克隆
  allowconn: true                 # 可选，是否允许连接，默认为 true。显式设置 false 将完全禁止连接到此数据库
  revokeconn: false               # 可选，撤销公共连接权限。设为 true 时仅为属主、管理员、监控与复制用户保留 CONNECT
  register_datasource: true       # 可选，是否将此数据库注册到 grafana 数据源？默认为 true，显式设置为 false 会跳过注册
  connlimit: -1                   # 可选，数据库连接限制，默认为 -1 ，不限制，设置为正整数则会限制连接数。
  parameters:                     # 可选，数据库级参数，通过 ALTER DATABASE SET 设置
    work_mem: '64MB'
    statement_timeout: '30s'
  pool_auth_user: dbuser_meta     # 可选，连接到此 pgbouncer 数据库的所有连接都将使用此用户进行验证（启用 pgbouncer_auth_query 才有用）
  pool_mode: transaction          # 可选，数据库级别的 pgbouncer 池化模式，默认为 transaction
  pool_size: 50                   # 可选，数据库级别的 pgbouncer 默认池子大小，默认为 50
  pool_reserve: 30                # 可选，数据库级别的 pgbouncer 池子保留空间，默认为 30，当默认池子不够用时，最多再申请这么多条突发连接。
  pool_size_min: 0                # 可选，数据库级别的 pgbouncer 池的最小大小，默认为 0
  pool_connlimit: 100             # 可选，数据库级别的最大数据库连接数，默认为 100

自 Pigsty v4.1.0 起，数据库连接池参数统一使用 pool_reserve 与 pool_connlimit，旧别名 pool_size_reserve / pool_max_db_conn 已收敛。

参数总览

所有参数中唯一 必选 的字段是 name，它应该是当前 PostgreSQL 集群中有效且唯一的数据库名称，其他参数都有合理的默认值，均为可选项。 带有 “不可变” 标记的参数仅在数据库创建时生效，创建后无法修改，若需更改则必须删除并重建数据库。

字段 分类 类型 属性 说明
name 基本 string 必选 数据库名称，必须是有效且唯一的标识符
state 基本 enum 可选 数据库状态：create（默认）、absent、recreate
owner 基本 string 可变 数据库属主，不指定则为 postgres
comment 基本 string 可变 数据库备注信息
template 模板 string 不可变 创建时使用的模板数据库，默认 template1
strategy 模板 enum 不可变 克隆策略：FILE_COPY 或 WAL_LOG（PG15+）
encoding 编码 string 不可变 字符编码，默认继承模板（UTF8）
locale 编码 string 不可变 本地化规则，默认继承模板（C）
lc_collate 编码 string 不可变 排序规则，默认继承模板（C）
lc_ctype 编码 string 不可变 字符分类，默认继承模板（C）
locale_provider 编码 enum 不可变 本地化提供者：libc、icu、builtin（PG15+）
icu_locale 编码 string 不可变 ICU 本地化规则（PG15+）
icu_rules 编码 string 不可变 ICU 排序定制规则（PG16+）
builtin_locale 编码 string 不可变 内置本地化规则（PG17+）
tablespace 存储 string 可变 默认表空间，修改会触发数据迁移
is_template 权限 bool 可变 是否标记为模板数据库
allowconn 权限 bool 可变 是否允许连接，默认 true
revokeconn 权限 bool 可变 是否回收 PUBLIC 的 CONNECT 权限
connlimit 权限 int 可变 连接数限制，-1 表示不限制
baseline 初始化 string 可变 SQL 基线文件路径，每次置备该数据库时执行
schemas 初始化 (string|object)[] 可变 要创建的模式定义数组
extensions 初始化 (string|object)[] 可变 要安装的扩展定义数组
parameters 初始化 object 可变 数据库级参数
pgbouncer 连接池 bool 可变 是否加入连接池，默认 true
pool_mode 连接池 enum 可变 池化模式：transaction（默认）
pool_size 连接池 int 可变 默认池大小，默认 50
pool_size_min 连接池 int 可变 最小池大小，默认 0
pool_reserve 连接池 int 可变 保留池大小，默认 30
pool_connlimit 连接池 int 可变 最大数据库连接数，默认 100
pool_auth_user 连接池 string 可变 认证查询用户
register_datasource 监控 bool 可变 是否注册到 Grafana 数据源，默认 true

参数详情

name

字符串，必选参数，表示数据库的名称，在一个数据库集群内必须唯一。

当前角色没有对数据库名称实施这一正则校验，SQL 中也会用双引号引用名称；但名称同时参与临时文件路径与 Shell/SQL 命令拼接。为保证整条自动化链路安全可用，建议限制为 63 字节以内，并遵循 ^[A-Za-z_][A-Za-z0-9_$]{0,62}$，不要使用空格、引号、斜杠或其他特殊字符。

- name: myapp              # 简单命名
- name: my_application     # 下划线分隔
- name: app_v2             # 包含版本号

state

枚举值，用于指定要对数据库执行的操作，可以是 create、absent 或 recreate，默认值为 create。

状态 说明
create 默认，创建或修改数据库，如果已经存在，则将可变参数调整到描述的状态
absent 删除数据库，使用 DROP DATABASE WITH (FORCE)
recreate 先删除再创建，用于重置数据库 
- name: myapp                # state 默认为 create
- name: olddb
  state: absent              # 删除数据库
- name: testdb
  state: recreate            # 重建数据库

owner

字符串，指定数据库的属主用户，默认不指定，不指定则为数据库 pg_dbsu，即 postgres 用户。

要指定数据库的 owner，被指定的用户必须已存在。修改 owner 会执行：旧 Owner 在数据库上的权限不会被撤回。

数据库属主具有对数据库的完全控制权限，包括创建模式、表、扩展等对象的权限，对于多租户场景尤为有用。

ALTER DATABASE "myapp" OWNER TO "new_owner";
GRANT ALL PRIVILEGES ON DATABASE "myapp" TO "new_owner";

comment

字符串，用于设置数据库的备注信息，如果不指定，默认值为 business database {name}。

数据库备注信息通过 COMMENT ON DATABASE 语句设置，支持中文和特殊字符（Pigsty 会自动转义单引号）。 备注信息会存储在共享对象注释目录 pg_shdescription 中，可以通过 \l+ 命令查看。

COMMENT ON DATABASE "myapp" IS '我的应用主数据库';
- name: myapp
  comment: 我的应用主数据库

template

字符串，不可变参数，用于指定创建数据库时使用的模板数据库，默认值为 template1。

PostgreSQL 的 CREATE DATABASE 本质上是对模板数据库进行复制，新数据库会继承模板中的所有对象、扩展、模式、权限设置等。 Pigsty 会在集群初始化阶段对 template1 进行定制配置，因此新建数据库默认会继承这些设置。

模板 说明
template1 默认模板，包含 Pigsty 预配置的扩展、模式和权限设置
template0 干净模板，使用不同于集群默认的本地化提供者时，必须使用此模板
自定义数据库 可以使用已有数据库作为模板进行克隆

使用 icu 或 builtin 本地化提供者时，必须指定 template: template0，因为 template1 已有本地化设置无法覆盖。 使用其他

- name: myapp_icu
  template: template0        # 使用 ICU 时必须指定 template0
  locale_provider: icu
  icu_locale: zh-Hans

使用 template0 时，监控所需的扩展与 Schema，以及角色的默认权限都不再自动创建，这允许你从一个完全干净的模板开始定制数据库。

strategy

枚举值，不可变参数，用于指定从模板克隆数据库的策略，可选值为 FILE_COPY 或 WAL_LOG，此参数在 PostgreSQL 15 及以上版本可用。

策略 说明 适用场景
FILE_COPY 直接复制数据文件，并在前后执行检查点 大模板、希望减少 WAL 量
WAL_LOG 逐块复制并写入 WAL，PG15+ 默认 小模板、不阻塞模板上的连接

WAL_LOG 策略的优势是复制过程中不会阻塞模板数据库上的连接，但对于较大的模板效率不如 FILE_COPY。 在 PostgreSQL 14 及更早版本中，此参数会被忽略。

- name: cloned_db
  template: source_db
  strategy: WAL_LOG          # 使用 WAL 日志方式克隆

encoding

字符串，不可变参数，用于指定数据库的字符编码，如果不指定则继承模板数据库的编码设置，通常为 UTF8。

如果没有特殊原因，强烈建议使用 UTF8 编码。字符编码在数据库创建后无法修改，如需更改必须重建数据库。

- name: legacy_db
  template: template0        # 指定非默认编码时使用 template0
  encoding: LATIN1

locale

字符串，不可变参数，用于指定数据库的本地化规则，相当于同时设置 lc_collate 和 lc_ctype，如果不指定则继承模板数据库的设置，通常为 C。

本地化规则决定了字符串的排序顺序和字符分类行为。使用 C 或 POSIX 可获得最佳性能和跨平台一致性， 使用特定语言的本地化规则（如 zh_CN.UTF-8）可以获得符合该语言习惯的排序结果。

- name: chinese_db
  template: template0
  locale: zh_CN.UTF-8        # 中文本地化
  encoding: UTF8

lc_collate

字符串，不可变参数，用于指定字符串的排序规则，如果不指定则继承模板数据库的设置，通常为 C。

排序规则决定了 ORDER BY 和比较操作的结果。常用值包括：C（字节序，最快）、C.UTF-8、en_US.UTF-8、zh_CN.UTF-8。 此参数在数据库创建后无法修改。

- name: myapp
  template: template0
  lc_collate: en_US.UTF-8    # 英文排序规则
  lc_ctype: en_US.UTF-8

lc_ctype

字符串，不可变参数，用于指定字符分类规则，决定字符的大小写、数字、字母等分类，如果不指定则继承模板数据库的设置，通常为 C。

字符分类规则影响 upper()、lower()、正则表达式中的 \w 等函数的行为。此参数在数据库创建后无法修改。

locale_provider

枚举值，不可变参数，用于指定本地化的实现提供者，可选值为 libc、icu 或 builtin，此参数在 PostgreSQL 15 及以上版本可用，默认值为 libc。

提供者 版本 说明
libc - 使用操作系统 C 库，传统默认方式，行为因系统而异
icu PG15+ 使用 ICU 库，跨平台一致，支持更多语言
builtin PG17+ PostgreSQL 内置实现，最高效，仅支持 C/C.UTF-8

使用 icu 或 builtin 提供者时，必须指定 template: template0，并配合相应的 icu_locale 或 builtin_locale 参数。

- name: fast_db
  template: template0
  locale_provider: builtin   # 使用内置提供者，最高效
  builtin_locale: C.UTF-8

icu_locale

字符串，不可变参数，用于指定 ICU 本地化规则标识符，此参数在 PostgreSQL 15 及以上版本、且 locale_provider 为 icu 时可用。

ICU 本地化标识符遵循 BCP 47 标准，常用值包括：

值 说明
en-US 美式英语
en-GB 英式英语
zh-Hans 简体中文
zh-Hant 繁体中文
ja-JP 日语
ko-KR 韩语 
- name: chinese_app
  template: template0
  locale_provider: icu
  icu_locale: zh-Hans        # 简体中文 ICU 排序
  encoding: UTF8

icu_rules

字符串，不可变参数，用于自定义 ICU 排序规则，此参数在 PostgreSQL 16 及以上版本可用。

ICU 规则允许对默认排序行为进行微调，使用 ICU 排序规则语法。

- name: custom_sort_db
  template: template0
  locale_provider: icu
  icu_locale: en-US
  icu_rules: '&V << w <<< W'  # 自定义 V/W 排序顺序

builtin_locale

字符串，不可变参数，用于指定内置本地化提供者的规则，此参数在 PostgreSQL 17 及以上版本、且 locale_provider 为 builtin 时可用，可选值为 C 或 C.UTF-8。

builtin 提供者是 PostgreSQL 17 新增的内置本地化实现，比 libc 更快，且行为跨平台完全一致。 适合只需要 C 或 C.UTF-8 排序规则的场景。

- name: fast_db
  template: template0
  locale_provider: builtin
  builtin_locale: C.UTF-8    # 内置 UTF-8 支持
  encoding: UTF8

tablespace

字符串，可变参数，用于指定数据库的默认表空间，默认值为 pg_default。

修改现有数据库的表空间会触发数据物理迁移，PostgreSQL 会将数据库中的所有对象移动到新表空间，对于大数据库可能需要较长时间，慎用。

- name: archive_db
  tablespace: slow_hdd       # 归档数据使用慢速存储
ALTER DATABASE "archive_db" SET TABLESPACE "slow_hdd";

is_template

布尔值，可变参数，用于指定是否将数据库标记为模板数据库，默认值为 false。

设置为 true 后，任何拥有 CREATEDB 权限的用户都可以使用此数据库作为模板克隆新数据库。 模板数据库通常用于预装标准模式、扩展和数据，方便快速创建具有相同配置的新数据库。

- name: app_template
  is_template: true          # 标记为模板，允许普通用户克隆
  schemas: [core, api]
  extensions: [postgis, pg_trgm]

删除标记为 is_template: true 的数据库时，Pigsty 会先执行 ALTER DATABASE ... IS_TEMPLATE false 取消模板标记，然后再删除。

allowconn

布尔值，可变参数，用于控制是否允许连接到此数据库，默认值为 true。

设置为 false 会在数据库层面完全禁止连接，任何用户（包括超级用户）都无法连接到此数据库。 此参数通常用于维护或归档用途。

- name: archive_db
  allowconn: false           # 禁止任何连接
ALTER DATABASE "archive_db" ALLOW_CONNECTIONS false;

revokeconn

布尔值，可变参数，用于控制是否回收 PUBLIC 角色的 CONNECT 权限，默认值为 false。

设置为 true 时，Pigsty 会执行以下权限变更：

  • 回收 PUBLIC 的 CONNECT 权限，普通用户将无法连接
  • 授予复制用户（replicator）和监控用户（dbuser_monitor）连接权限
  • 授予管理员用户（dbuser_dba）和数据库属主连接权限，并附带 WITH GRANT OPTION

设置为 false 时，会恢复 PUBLIC 的 CONNECT 权限。

- name: secure_db
  owner: dbuser_secure
  revokeconn: true           # 回收公共连接权限，只有指定用户可连接

connlimit

整数，可变参数，用于限制数据库的最大并发连接数，默认值为 -1，表示不限制。

设置为正整数时，会限制同时连接到此数据库的最大会话数。此限制不影响超级用户。

- name: limited_db
  connlimit: 50              # 最多允许 50 个并发连接
ALTER DATABASE "limited_db" CONNECTION LIMIT 50;

baseline

字符串，用于指定数据库置备时要执行的 SQL 基线文件路径。

基线文件通常包含表结构定义、初始数据、存储过程等，用于初始化新数据库。 路径是相对于 Ansible 搜索路径的相对路径，通常放在 files/ 目录下。

只要定义了 baseline，当前角色在每次为该数据库执行置备任务时都会运行该文件，即使数据库已经存在；state: recreate 时也会重新执行。因此基线 SQL 应设计为幂等脚本，或避免在现有数据库上重复执行。

- name: myapp
  baseline: myapp_schema.sql  # 会查找 files/myapp_schema.sql

schemas

数组，可变参数（支持增删），用于定义要在数据库中创建或删除的模式。数组元素可以是字符串或对象。

简单格式使用字符串直接指定模式名，仅支持创建操作：

schemas:
  - app
  - api
  - core

完整格式使用对象定义，支持指定模式属主和删除操作：

schemas:
  - name: app                # 模式名（必选）
    owner: dbuser_app        # 模式属主（可选），生成 AUTHORIZATION 子句
  - name: deprecated
    state: absent            # 删除模式（使用 CASCADE）

创建模式时使用 IF NOT EXISTS，已存在则跳过；删除模式时使用 CASCADE，会同时删除模式内的所有对象。

CREATE SCHEMA IF NOT EXISTS "app" AUTHORIZATION "dbuser_app";
DROP SCHEMA IF EXISTS "deprecated" CASCADE;

extensions

数组，可变参数（支持增删），用于定义要在数据库中安装或卸载的扩展。数组元素可以是字符串或对象。

简单格式使用字符串直接指定扩展名，仅支持安装操作：

extensions:
  - postgis
  - pg_trgm
  - vector

完整格式使用对象定义，支持指定安装模式、版本和卸载操作：

extensions:
  - name: vector             # 扩展名（必选）
    schema: public           # 安装到指定模式（可选）
    version: '0.5.1'         # 指定版本（可选）
  - name: old_extension
    state: absent            # 卸载扩展（使用 CASCADE）

安装扩展时使用 IF NOT EXISTS ... CASCADE；如果扩展已存在，PostgreSQL 会给出 NOTICE 并跳过，同时可自动安装依赖扩展。卸载扩展时使用 CASCADE，会同时删除依赖此扩展的对象。

CREATE EXTENSION IF NOT EXISTS "vector" WITH SCHEMA "public" VERSION '0.5.1' CASCADE;
DROP EXTENSION IF EXISTS "old_extension" CASCADE;

parameters

对象，可变参数，用于设置数据库级别的配置参数。参数通过 ALTER DATABASE ... SET 设置，会对连接到此数据库的所有会话生效。

- name: analytics
  parameters:
    work_mem: '256MB'
    maintenance_work_mem: '512MB'
    statement_timeout: '5min'
    search_path: 'analytics,public'

使用特殊值 DEFAULT（大小写不敏感）可以将参数重置为 PostgreSQL 默认值：

parameters:
  work_mem: DEFAULT          # 重置为默认值
  statement_timeout: '30s'   # 设置新值
ALTER DATABASE "myapp" SET "work_mem" = DEFAULT;
ALTER DATABASE "myapp" SET "statement_timeout" = '30s';

pgbouncer

布尔值，可变参数，用于控制是否将数据库添加到 Pgbouncer 连接池列表，默认值为 true。

设置为 false 时，数据库不会出现在 Pgbouncer 的数据库列表中，客户端无法通过连接池访问此数据库。 适用于内部管理数据库或需要直连的特殊场景。

- name: internal_db
  pgbouncer: false           # 不通过连接池访问

pool_mode

枚举值，可变参数，用于设置此数据库在 Pgbouncer 中的池化模式，可选值为 transaction、session 或 statement，默认值为 transaction。

模式 说明 适用场景
transaction 事务结束后归还连接 大多数 OLTP 应用，默认推荐
session 会话结束后归还连接 需要会话级状态的应用
statement 每条语句后归还连接 简单无状态查询，极致复用 
- name: session_app
  pool_mode: session         # 使用会话级池化

pool_size

整数，可变参数，用于设置此数据库在 Pgbouncer 中的默认连接池大小，默认值为 50。

连接池大小决定了此数据库连接池允许使用的常规后端连接上限；预热连接数由 pool_size_min 控制。请根据应用负载调整。

- name: high_load_db
  pool_size: 128             # 高负载应用使用更大的池

pool_size_min

整数，可变参数，用于设置此数据库在 Pgbouncer 中的最小连接池大小，默认值为 0。

设置大于 0 的值会让 Pgbouncer 预先创建指定数量的后端连接，用于连接预热，减少首次请求的延迟。

- name: latency_sensitive
  pool_size_min: 10          # 预热 10 个连接

pool_reserve

整数，可变参数，用于设置此数据库在 Pgbouncer 中的保留连接数，默认值为 30。

当默认池不够用时，Pgbouncer 最多可以额外申请 pool_reserve 个连接来处理突发流量。

- name: bursty_db
  pool_size: 50
  pool_reserve: 30           # 常规池用尽后最多再增加 30 个连接

pool_connlimit

整数，可变参数，用于设置通过 Pgbouncer 连接池访问此数据库的最大连接数，默认值为 100。

此限制是 Pgbouncer 层面的限制，与数据库本身的 connlimit 参数独立。

- name: limited_pool_db
  pool_connlimit: 50         # 连接池最多 50 个连接

pool_auth_user

字符串，可变参数，用于指定 Pgbouncer 认证查询使用的用户。

此参数需要配合 pgbouncer_auth_query 参数启用才生效。 设置后，所有通过 Pgbouncer 连接到此数据库的请求都会使用指定用户执行认证查询来验证密码。

- name: myapp
  pool_auth_user: dbuser_monitor  # 使用监控用户执行认证查询

register_datasource

布尔值，可变参数，用于控制是否将此数据库注册到 Grafana 作为 PostgreSQL 数据源，默认值为 true。

设置为 false 可以跳过 Grafana 数据源注册。适用于临时数据库、测试数据库，或不希望在监控系统中出现的内部数据库。

- name: temp_db
  register_datasource: false  # 不注册到 Grafana

模板继承

许多参数如果不显式指定，会从模板数据库继承。默认模板是 template1，其编码设置由集群初始化参数决定：

集群参数 默认值 说明
pg_encoding UTF8 集群默认字符编码
pg_locale C / C-UTF-8 (如果支持) 集群默认本地化
pg_lc_collate C / C-UTF-8 (如果支持) 集群默认排序规则
pg_lc_ctype C / C-UTF-8 (如果支持) 集群默认字符分类

新创建的数据库默认会从 template1 数据库 Fork 出来，这个模版数据库会在 PG_PROVISION 阶段进行定制修改： 配置好扩展、模式以及默认权限，因此新创建的数据库也会继承这些配置，除非您显式使用一个其他的数据库作为模板。

深度定制

Pigsty 提供了丰富的定制参数与配置旋钮，如果你想定制模板数据库，请参考以下资源：

如果上面这些配置仍然无法满足您的需求，您可以使用 pg_init 指定自定义的集群初始化脚本进行定制：

本地化提供者

PostgreSQL 15+ 引入了 locale_provider 参数，支持不同的本地化实现。这些属性只能在数据库创建时指定，之后无法修改。

Pigsty 在 configure 配置向导中会根据 PG 与操作系统版本，优先使用 PG 内置的 C.UTF-8/C 本地化提供者。 数据库在默认情况下继承集群的本地化设置。如果您要为数据库指定一个不同于集群默认的本地化提供者，则必须使用 template0 作为模板数据库。

使用 ICU 提供者（PG15+）：

- name: myapp_icu
  template: template0        # ICU 必须使用 template0
  locale_provider: icu
  icu_locale: en-US          # ICU 本地化规则
  encoding: UTF8

使用内置提供者（PG17+）：

- name: myapp_builtin
  template: template0
  locale_provider: builtin
  builtin_locale: C.UTF-8    # 内置本地化规则
  encoding: UTF8

提供者对比：libc（传统方式，依赖操作系统）、icu（PG15+，跨平台一致，功能丰富）、builtin（PG17+，最高效的 C/C.UTF-8 排序）。

连接池

Pgbouncer 连接池可以优化短连接性能，降低并发征用，以避免过高的连接数冲垮数据库，并在数据库迁移时提供额外的灵活处理空间。

Pigsty 会默认为 PostgreSQL 实例 1:1 配置启用一个连接池， 使用和 PostgreSQL 同样的 pg_dbsu 运行，默认为 postgres 操作系统用户。 连接池与数据库使用 /var/run/postgresql Unix Socket 通信。

Pigsty 默认将 pg_databases 中的所有数据库都添加到 pgbouncer 的数据库列表中。 您可以通过在数据库定义中显式设置 pgbouncer: false 来禁用特定数据库的 pgbouncer 连接池支持。 pgbouncer 数据库列表与其配置参数在 /etc/pgbouncer/database.txt 中定义。

meta                        = host=/var/run/postgresql mode=session
grafana                     = host=/var/run/postgresql mode=transaction
bytebase                    = host=/var/run/postgresql auth_user=dbuser_meta
kong                        = host=/var/run/postgresql pool_size=32 reserve_pool=64
gitea                       = host=/var/run/postgresql min_pool_size=10
wiki                        = host=/var/run/postgresql
noco                        = host=/var/run/postgresql
mongo                       = host=/var/run/postgresql

当您 创建数据库 时，Pgbouncer 的数据库列表定义文件将会被刷新，并通过在线重载配置的方式生效，正常不会影响现有的连接。

1.6 - HBA 规则

Pigsty 中 PostgreSQL 与 PgBouncer 的 HBA（Host-Based Authentication）规则配置参考。

概述

HBA（Host-Based Authentication）控制“谁可以从哪里、以什么方式连接到数据库”。认证模型和默认规则说明见 身份认证。 Pigsty 通过 pg_default_hba_rules 与 pg_hba_rules 让 HBA 规则也能以声明式配置形式管理。

Pigsty 在集群初始化或 HBA 刷新时渲染以下配置文件：

配置文件 路径 说明
PostgreSQL HBA /pg/data/pg_hba.conf PostgreSQL 服务器的 HBA 规则
PgBouncer HBA /etc/pgbouncer/pgb_hba.conf 连接池 PgBouncer 的 HBA 规则

HBA 规则由以下参数控制：

参数 层级 说明
pg_default_hba_rules G PostgreSQL 全局默认 HBA 规则
pg_hba_rules G/C/I PostgreSQL 集群/实例级追加规则
pgb_default_hba_rules G PgBouncer 全局默认 HBA 规则
pgb_hba_rules G/C/I PgBouncer 集群/实例级追加规则

规则支持以下特性：

  • 按角色过滤：规则支持 role 字段，根据实例的 pg_role 自动筛选生效
  • 按顺序排序：规则支持 order 字段，控制规则在最终配置文件中的位置
  • 两种写法：支持别名形式（简化语法）和原始形式（直接 HBA 文本）

刷新 HBA

修改配置后，需要重新渲染配置文件并让服务重载：

bin/pgsql-hba <cls>                   # 刷新整个集群的 HBA 规则（推荐）
bin/pgsql-hba <cls> <ip>...           # 刷新集群中指定实例的 HBA 规则

脚本内部执行以下剧本命令：

./pgsql.yml -l <cls> -t pg_hba,pg_reload,pgbouncer_hba,pgbouncer_reload -e pg_reload=true

仅刷新 PostgreSQL：./pgsql.yml -l <cls> -t pg_hba,pg_reload -e pg_reload=true

仅刷新 Pgbouncer：./pgsql.yml -l <cls> -t pgbouncer_hba,pgbouncer_reload

不要直接编辑配置文件

不要直接编辑 /pg/data/pg_hba.conf 或 /etc/pgbouncer/pgb_hba.conf，下次执行 playbook 时会被覆盖。 所有变更应在 pigsty.yml 中进行，然后执行 bin/pgsql-hba 刷新。

参数详解

pg_default_hba_rules

PostgreSQL 全局默认 HBA 规则列表，通常定义在 all.vars 中，为所有 PostgreSQL 集群提供基础访问控制。

  • 类型：rule[]，层级：全局 (G)
pg_default_hba_rules:
  - {user: '${dbsu}'    ,db: all         ,addr: local     ,auth: ident ,title: 'dbsu access via local os user ident'  ,order: 100}
  - {user: '${dbsu}'    ,db: replication ,addr: local     ,auth: ident ,title: 'dbsu replication from local os ident' ,order: 150}
  - {user: '${repl}'    ,db: replication ,addr: localhost ,auth: pwd   ,title: 'replicator replication from localhost',order: 200}
  - {user: '${repl}'    ,db: replication ,addr: intra     ,auth: pwd   ,title: 'replicator replication from intranet' ,order: 250}
  - {user: '${repl}'    ,db: postgres    ,addr: intra     ,auth: pwd   ,title: 'replicator postgres db from intranet' ,order: 300}
  - {user: '${monitor}' ,db: all         ,addr: localhost ,auth: pwd   ,title: 'monitor from localhost with password' ,order: 350}
  - {user: '${monitor}' ,db: all         ,addr: infra     ,auth: pwd   ,title: 'monitor from infra host with password',order: 400}
  - {user: '${admin}'   ,db: all         ,addr: infra     ,auth: ssl   ,title: 'admin @ infra nodes with pwd & ssl'   ,order: 450}
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: ssl   ,title: 'admin @ everywhere with ssl & pwd'    ,order: 500}
  - {user: '+dbrole_readonly',db: all    ,addr: localhost ,auth: pwd   ,title: 'pgbouncer read/write via local socket',order: 550}
  - {user: '+dbrole_readonly',db: all    ,addr: intra     ,auth: pwd   ,title: 'read/write biz user via password'     ,order: 600}
  - {user: '+dbrole_offline' ,db: all    ,addr: intra     ,auth: pwd   ,title: 'allow etl offline tasks from intranet',order: 650}

pg_hba_rules

PostgreSQL 集群/实例级 HBA 追加规则，可在集群或实例级别覆盖，与默认规则合并后按 order 排序。

  • 类型：rule[]，层级：全局/集群/实例 (G/C/I)，默认值：[]
pg_hba_rules:
  - {user: app_user, db: app_db, addr: intra, auth: pwd, title: 'app user access'}

pgb_default_hba_rules

Pgbouncer 全局默认 HBA 规则列表，通常定义在 all.vars 中。

  • 类型：rule[]，层级：全局 (G)
pgb_default_hba_rules:
  - {user: '${dbsu}'    ,db: pgbouncer   ,addr: local     ,auth: peer  ,title: 'dbsu local admin access with os ident',order: 100}
  - {user: 'all'        ,db: all         ,addr: localhost ,auth: pwd   ,title: 'allow all user local access with pwd' ,order: 150}
  - {user: '${monitor}' ,db: pgbouncer   ,addr: intra     ,auth: pwd   ,title: 'monitor access via intranet with pwd' ,order: 200}
  - {user: '${monitor}' ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other monitor access addr' ,order: 250}
  - {user: '${admin}'   ,db: all         ,addr: intra     ,auth: pwd   ,title: 'admin access via intranet with pwd'   ,order: 300}
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other admin access addr'   ,order: 350}
  - {user: 'all'        ,db: all         ,addr: intra     ,auth: pwd   ,title: 'allow all user intra access with pwd' ,order: 400}

pgb_hba_rules

Pgbouncer 集群/实例级 HBA 追加规则。

  • 类型：rule[]，层级：全局/集群/实例 (G/C/I)，默认值：[]

注意：Pgbouncer HBA 不支持 db: replication。

规则字段

每条 HBA 规则是一个 YAML 字典，支持以下字段：

字段 类型 必需 默认值 说明
user string 否 all 用户名，支持 all、变量占位符、+rolename 等
db string 否 all 数据库名，支持 all、replication、具体库名
addr string 是* - 地址别名或 CIDR，见 地址别名
auth string 否 pwd 认证方式别名，见 认证方式
title string 否 - 规则说明/注释，会渲染为配置文件中的注释
role string 否 common 实例角色过滤，见 角色过滤
order int 否 1000 排序权重，数字小的排前面，见 排序机制
rules list 是* - 原始 HBA 文本行列表，与 addr 二选一

addr 和 rules 必须指定其一。使用 rules 时可以直接写原始 HBA 格式。

地址别名

Pigsty 提供地址别名，简化 HBA 规则编写：

别名 展开为 说明
local Unix socket 本地 Unix 套接字连接
localhost Unix socket + 127.0.0.1/32 + ::1/128 本地回环地址
admin ${admin_ip}/32 管理员 IP 地址
infra 所有 infra 组节点 IP 基础设施节点列表
cluster 当前集群所有成员 IP 同一集群内的所有实例
intra / intranet 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 内网 CIDR 网段
world / all 0.0.0.0/0 + ::/0 任意地址（IPv4 + IPv6）
<CIDR> 直接使用 如 192.168.1.0/24、10.1.1.100/32

内网 CIDR 可通过 node_firewall_intranet 参数自定义：

node_firewall_intranet:
  - 10.0.0.0/8
  - 172.16.0.0/12
  - 192.168.0.0/16

认证方式

Pigsty 提供认证方式别名，简化配置：

别名 实际方式 连接类型 说明
pwd scram-sha-256 或 md5 host 根据 pg_pwd_enc 自动选择
ssl scram-sha-256 或 md5 hostssl 强制 SSL + 密码
ssl-sha scram-sha-256 hostssl 强制 SSL + SCRAM-SHA-256
ssl-md5 md5 hostssl 强制 SSL + MD5
cert cert hostssl 客户端证书认证
trust trust host 无条件信任（危险）
deny / reject reject host 拒绝连接
ident ident host OS 用户映射（PostgreSQL）
peer peer local OS 用户映射（Pgbouncer/本地）

pg_pwd_enc 默认为 scram-sha-256，可设为 md5 以兼容老客户端。

用户变量

HBA 规则支持以下用户占位符，渲染时自动替换为实际用户名：

占位符 默认值 对应参数
${dbsu} postgres pg_dbsu
${repl} replicator pg_replication_username
${monitor} dbuser_monitor pg_monitor_username
${admin} dbuser_dba pg_admin_username

角色过滤

HBA 规则的 role 字段控制规则在哪些实例上生效：

角色 说明
common 默认值，所有实例都生效
primary 仅主库实例生效
replica 仅从库实例生效
offline 仅离线实例生效（pg_role: offline 或 pg_offline_query: true）
standby 备库实例
delayed 延迟从库实例

角色过滤基于实例的 pg_role 变量进行匹配，不匹配的规则会被注释掉（以 # 开头）。

pg_hba_rules:
  # 仅在主库生效：写入用户只能连主库
  - {user: writer, db: all, addr: intra, auth: pwd, role: primary, title: 'writer only on primary'}

  # 仅在离线实例生效：ETL 任务专用网络
  - {user: '+dbrole_offline', db: all, addr: '172.20.0.0/16', auth: ssl, role: offline, title: 'offline dedicated'}

排序机制

PostgreSQL HBA 是 首条匹配生效，规则顺序至关重要。Pigsty 通过 order 字段控制规则渲染顺序。

Order 区间约定

区间 用途
0 - 99 用户高优先规则（在所有默认规则之前）
100 - 650 默认规则区（间隔 50，便于插入）
1000+ 用户规则默认值（不填 order 时追加到最后）

PostgreSQL 默认规则 Order 分配

Order 规则说明
100 dbsu local ident
150 dbsu replication local
200 replicator localhost
250 replicator intra replication
300 replicator intra postgres
350 monitor localhost
400 monitor infra
450 admin infra ssl
500 admin world ssl
550 dbrole_readonly localhost
600 dbrole_readonly intra
650 dbrole_offline intra

Pgbouncer 默认规则 Order 分配

Order 规则说明
100 dbsu local peer
150 all localhost pwd
200 monitor pgbouncer intra
250 monitor world deny
300 admin intra pwd
350 admin world deny
400 all intra pwd

写法示例

别名形式：使用 Pigsty 提供的简化语法

pg_hba_rules:
  - title: allow grafana view access
    role: primary
    user: dbuser_view
    db: meta
    addr: infra
    auth: ssl

渲染结果：

# allow grafana view access [primary]
hostssl  meta               dbuser_view        10.10.10.10/32     scram-sha-256

原始形式：直接使用 PostgreSQL HBA 语法

pg_hba_rules:
  - title: allow intranet password access
    role: common
    rules:
      - host all all 10.0.0.0/8 scram-sha-256
      - host all all 172.16.0.0/12 scram-sha-256
      - host all all 192.168.0.0/16 scram-sha-256

渲染结果：

# allow intranet password access [common]
host all all 10.0.0.0/8 scram-sha-256
host all all 172.16.0.0/12 scram-sha-256
host all all 192.168.0.0/16 scram-sha-256

常见配置场景

黑名单 IP：使用 order: 0 确保最先匹配

pg_hba_rules:
  - {user: all, db: all, addr: '10.1.1.100/32', auth: deny, order: 0, title: 'block bad ip'}

白名单应用服务器：高优先级允许特定 IP

pg_hba_rules:
  - {user: app_user, db: app_db, addr: '192.168.1.10/32', auth: ssl, order: 50, title: 'app server'}

管理员强制证书：覆盖默认的 SSL 密码认证

pg_hba_rules:
  - {user: '${admin}', db: all, addr: world, auth: cert, order: 10, title: 'admin cert only'}

离线实例专用网络：仅在 offline 实例生效

pg_hba_rules:
  - {user: '+dbrole_offline', db: all, addr: '172.20.0.0/16', auth: ssl-sha, role: offline, title: 'etl network'}

按数据库限制访问：敏感库仅允许特定网段

pg_hba_rules:
  - {user: fin_user, db: finance_db, addr: '10.20.0.0/16', auth: ssl, title: 'finance only'}
  - {user: hr_user, db: hr_db, addr: '10.30.0.0/16', auth: ssl, title: 'hr only'}

Pgbouncer 专用规则：注意不支持 db: replication

pgb_hba_rules:
  - {user: '+dbrole_readwrite', db: all, addr: world, auth: ssl, title: 'app via pgbouncer'}

完整集群示例 

pg-prod:
  hosts:
    10.10.10.11: {pg_seq: 1, pg_role: primary}
    10.10.10.12: {pg_seq: 2, pg_role: replica}
    10.10.10.13: {pg_seq: 3, pg_role: offline}
  vars:
    pg_cluster: pg-prod

    pg_hba_rules:
      # 黑名单：已知恶意 IP（最高优先级）
      - {user: all, db: all, addr: '10.1.1.100/32', auth: deny, order: 0, title: 'blacklist'}

      # 应用服务器白名单（高优先级）
      - {user: app_user, db: app_db, addr: '192.168.1.0/24', auth: ssl, order: 50, title: 'app servers'}

      # ETL 任务：仅离线实例
      - {user: etl_user, db: all, addr: '172.20.0.0/16', auth: pwd, role: offline, title: 'etl tasks'}

      # 集群内监控访问
      - {user: '${monitor}', db: all, addr: cluster, auth: pwd, order: 380, title: 'cluster monitor'}

    pgb_hba_rules:
      # 应用通过连接池
      - {user: '+dbrole_readwrite', db: all, addr: '192.168.1.0/24', auth: ssl, title: 'app via pgbouncer'}

验证与排查

查看当前 HBA 规则

psql -c "TABLE pg_hba_file_rules"         # 通过 SQL 查看（推荐）
cat /pg/data/pg_hba.conf                  # 查看 PostgreSQL HBA 文件
cat /etc/pgbouncer/pgb_hba.conf           # 查看 Pgbouncer HBA 文件
grep '^#' /pg/data/pg_hba.conf | head -20 # 查看规则标题（验证 order）

测试连接认证

psql -h <host> -p 5432 -U <user> -d <db> -c "SELECT 1"

常见问题排查

错误信息 可能原因 解决方案
no pg_hba.conf entry for host... 没有匹配的 HBA 规则 添加对应规则并刷新
password authentication failed 密码错误或加密方式不兼容 检查密码和 pg_pwd_enc
规则不生效 未刷新或 order 被覆盖 执行 bin/pgsql-hba 并检查顺序

注意事项

  1. 顺序敏感：PostgreSQL HBA 首条匹配生效，善用 order 字段
  2. 角色匹配：确保 role 字段与目标实例的 pg_role 一致
  3. 地址格式：CIDR 必须正确，如 10.0.0.0/8 而非 10.0.0.0/255.0.0.0
  4. PgBouncer 限制：不支持 db: replication
  5. TLS 前提：ssl、cert 要求服务端 TLS；客户端仍需使用 verify-full 验证服务端身份
  6. 测试优先：修改 HBA 前建议先在测试环境验证
  7. 扩缩容刷新：使用 addr: cluster 的规则在集群成员变化后需要刷新

相关文档

1.7 - 参数配置

如何配置集群、实例、用户和数据库级别的 PostgreSQL 参数

PostgreSQL 参数可以在多个层级进行配置，不同层级的参数设置具有不同的作用范围和优先级。 Pigsty 支持在四个层级配置 PostgreSQL 参数，从全局到局部依次为：

层级 作用范围 配置方式 存储位置
集群级 整个集群所有实例 Patroni DCS / 调优模板 etcd + postgresql.conf
实例级 单个 PostgreSQL 实例 pg_parameters / ALTER SYSTEM postgresql.auto.conf
数据库级 特定数据库的所有会话 pg_databases[].parameters pg_db_role_setting
用户级 特定用户的所有会话 pg_users[].parameters pg_db_role_setting

参数优先级从低到高：集群级 < 实例级 < 数据库级 < 用户级 < 会话级（SET 命令）。 高优先级的设置会覆盖低优先级的设置。

关于 PostgreSQL 参数的完整说明，请参阅 PostgreSQL 官方文档：服务器配置。

集群级参数

集群级参数是整个 PostgreSQL 集群共享的配置，所有实例（主库和从库）都会使用相同的参数值。 在 Pigsty 中，集群级参数通过 Patroni 管理，存储在分布式配置存储（DCS，默认为 etcd）中。

Pigsty 提供了四种预置的 Patroni 参数优化模板，针对不同的使用场景进行了优化，通过 pg_conf 参数指定：

模板 适用场景 特点
oltp.yml 在线事务处理 低延迟、高并发，默认推荐
olap.yml 在线分析处理 大查询、高吞吐，适合数仓
crit.yml 核心金融业务 最大持久性，牺牲部分性能换取安全
tiny.yml 微型实例 资源受限环境，适合开发测试

调优模板文件位于 Pigsty 安装目录的 roles/pgsql/templates/ 目录下，包含了根据硬件规格自动计算的参数值。 这些模板会在集群初始化时渲染为 Patroni 配置文件 /etc/patroni/patroni.yml。更多详情请参阅 场景模板。

在集群创建前，您可以通过调整这些 Patroni 配置模板来修改集群的 初始化参数。 一旦集群初始化完成，后续的参数修改应通过 Patroni 的 配置管理 机制进行。

Patroni DCS 配置

Patroni 将集群配置存储在 DCS（分布式配置存储，默认为 etcd）中，确保集群所有成员使用一致的配置。

配置存储结构：

/pigsty/                          # 命名空间（patroni_namespace）
  └── pg-meta/                    # 集群名称（pg_cluster）
      ├── config                  # 集群配置（所有成员共享）
      ├── leader                  # 当前主库信息
      ├── members/                # 成员注册信息
      │   ├── pg-meta-1
      │   └── pg-meta-2
      └── ...

配置渲染流程：

  1. 初始化阶段：调优模板（如 oltp.yml）通过 Jinja2 渲染为 /etc/patroni/patroni.yml
  2. 启动阶段：Patroni 读取本地配置，将 PostgreSQL 参数写入 DCS
  3. 运行阶段：Patroni 定期从 DCS 同步配置到本地 PostgreSQL

本地缓存机制：

每个 Patroni 实例会在本地缓存 DCS 配置，位于 /pg/conf/<instance>.yml：

  • 启动时：从 DCS 加载配置，缓存到本地
  • 运行时：定期同步 DCS 配置到本地缓存
  • DCS 不可用时：使用本地缓存继续运行（但无法进行主从切换）

配置文件层次

Patroni 会将 DCS 中的配置渲染到本地 PostgreSQL 配置文件，形成以下层次结构：

/pg/data/
├── postgresql.conf          # 主配置文件（由 Patroni 动态管理）
├── postgresql.base.conf     # 基础配置（通过 include 指令加载）
├── postgresql.auto.conf     # 实例级覆盖配置（ALTER SYSTEM 写入）
├── pg_hba.conf              # 客户端认证配置
└── pg_ident.conf            # 用户映射配置

配置加载顺序（优先级从低到高）：

  1. postgresql.conf：Patroni 动态生成，包含 DCS 中的集群参数
  2. postgresql.base.conf：通过 include 指令加载，包含静态基础配置
  3. postgresql.auto.conf：PostgreSQL 自动加载，用于实例级参数覆盖

由于 postgresql.auto.conf 最后加载，其中的参数会覆盖前面文件中的同名参数。

实例级参数

实例级参数仅对单个 PostgreSQL 实例生效，用于覆盖集群级配置或设置实例特定的参数。 实例级参数会写入 postgresql.auto.conf 文件，由于该文件最后加载，可以覆盖集群级的任何参数。

这是一项非常有用的技术：您可以为特定实例设置不同于集群的参数值，例如：

  • 为从库设置 hot_standby_feedback = on
  • 为特定实例调整 work_mem 或 maintenance_work_mem
  • 为延迟从库设置 recovery_min_apply_delay

使用 pg_parameters

在 Pigsty 配置中，使用 pg_parameters 参数定义实例级配置：

pg-meta:
  hosts:
    10.10.10.10:
      pg_seq: 1
      pg_role: primary
      pg_parameters:                              # 实例级参数
        log_statement: all                        # 仅此实例记录所有 SQL
  vars:
    pg_cluster: pg-meta
    pg_parameters:                                # 集群默认的实例参数
      log_timezone: Asia/Shanghai
      log_min_duration_statement: 1000

使用 ./pgsql.yml -l <cls> -t pg_param 子任务，可以将参数配置应用生效，这些参数会被渲染到 postgresql.auto.conf 文件中。

参数覆盖层次

pg_parameters 可以在 Ansible 配置的不同层次定义，优先级从低到高：

all:
  vars:
    pg_parameters:                    # 全局默认
      log_statement: none

  children:
    pg-meta:
      vars:
        pg_parameters:                # 集群级覆盖
          log_statement: ddl
      hosts:
        10.10.10.10:
          pg_parameters:              # 实例级覆盖（最高优先级）
            log_statement: all

使用 ALTER SYSTEM

除了通过配置文件，还可以在运行时使用 SQL 命令 ALTER SYSTEM 修改实例级参数：

-- 设置参数
ALTER SYSTEM SET work_mem = '256MB';
ALTER SYSTEM SET log_min_duration_statement = 1000;

-- 重置为默认值
ALTER SYSTEM RESET work_mem;
ALTER SYSTEM RESET ALL;  -- 重置所有 ALTER SYSTEM 设置

-- 重新加载配置使其生效
SELECT pg_reload_conf();

ALTER SYSTEM 会将参数写入 postgresql.auto.conf 文件。

注意：在 Pigsty 管理的集群中，postgresql.auto.conf 由 Ansible 通过 pg_parameters 管理。 手动使用 ALTER SYSTEM 修改的参数可能会在下次执行 playbook 时被覆盖。 建议通过修改 pigsty.yml 中的 pg_parameters 来管理实例级参数。

列表类型参数

PostgreSQL 中有一类特殊的参数接受逗号分隔的列表值。在 YAML 配置文件中配置这类参数时， 整个值必须用引号包裹，否则 YAML 解析器会将其解释为数组而导致错误：

# ✓ 正确：用引号包裹整个值
pg_parameters:
  shared_preload_libraries: 'timescaledb, pg_stat_statements'
  search_path: '"$user", public, app'

# ✗ 错误：不加引号会导致 YAML 解析错误
pg_parameters:
  shared_preload_libraries: timescaledb, pg_stat_statements   # YAML 会解析为数组！

Pigsty 会自动识别以下列表类型参数，在渲染到配置文件时 不添加外层引号：

参数 说明 示例值
shared_preload_libraries 预加载共享库 'timescaledb, pg_stat_statements'
search_path Schema 搜索路径 '"$user", public, app'
local_preload_libraries 本地预加载库 'auto_explain'
session_preload_libraries 会话预加载库 'pg_hint_plan'
log_destination 日志输出目标 'csvlog, stderr'
unix_socket_directories Unix Socket 目录 '/var/run/postgresql, /tmp'
temp_tablespaces 临时表空间 'ssd_space, hdd_space'
debug_io_direct 直接 I/O 模式（PG16+） 'data, wal'

渲染示例：

# pigsty.yml 配置（YAML 中需要引号）
pg_parameters:
  shared_preload_libraries: 'timescaledb, pg_stat_statements'
  search_path: '"$user", public, app'
  work_mem: 64MB
# 渲染后的 postgresql.auto.conf（列表参数无外层引号）
shared_preload_libraries = timescaledb, pg_stat_statements
search_path = "$user", public, app
work_mem = '64MB'

数据库级参数

数据库级参数针对特定数据库生效，连接到该数据库的所有会话都会应用这些参数设置。 通过 ALTER DATABASE ... SET 实现，存储在系统表 pg_db_role_setting 中。

配置方式

在 pg_databases 中使用 parameters 字段定义：

pg_databases:
  - name: analytics
    owner: dbuser_analyst
    parameters:
      work_mem: 256MB                              # 分析库需要更多内存
      maintenance_work_mem: 1GB                    # 大表维护操作
      statement_timeout: 10min                     # 允许长查询
      search_path: '"$user", public, mart'         # 列表参数需要引号

与实例级参数相同，列表类型参数值在 YAML 中需要用引号包裹。

参数渲染规则

数据库级参数通过 ALTER DATABASE ... SET 语句设置。Pigsty 会根据参数类型自动选择正确的语法：

列表类型参数（search_path、temp_tablespaces、local_preload_libraries、session_preload_libraries、log_destination）不加外层引号：

ALTER DATABASE "analytics" SET "search_path" = "$user", public, mart;

标量参数 使用引号包裹值：

ALTER DATABASE "analytics" SET "work_mem" = '256MB';
ALTER DATABASE "analytics" SET "statement_timeout" = '10min';

注意：虽然 log_destination 在数据库级参数白名单中，但由于其 context 为 sighup， 实际上无法在数据库级别生效。此参数应在实例级（pg_parameters）配置。

查看数据库参数 

-- 查看特定数据库的参数设置
SELECT datname, unnest(setconfig) AS setting
FROM pg_db_role_setting drs
JOIN pg_database d ON d.oid = drs.setdatabase
WHERE drs.setrole = 0 AND datname = 'analytics';

手动管理 

-- 设置参数
ALTER DATABASE analytics SET work_mem = '256MB';
ALTER DATABASE analytics SET search_path = "$user", public, myschema;

-- 重置参数
ALTER DATABASE analytics RESET work_mem;
ALTER DATABASE analytics RESET ALL;

用户级参数

用户级参数针对特定数据库用户生效，该用户的所有会话都会应用这些参数设置。 通过 ALTER USER ... SET 实现，同样存储在系统表 pg_db_role_setting 中。

配置方式

在 pg_users 或 pg_default_roles 中使用 parameters 字段定义：

pg_users:
  - name: dbuser_analyst
    password: DBUser.Analyst
    parameters:
      work_mem: 256MB                              # 分析查询需要更多内存
      statement_timeout: 5min                      # 允许较长的查询时间
      search_path: '"$user", public, analytics'    # 列表参数需要引号
      log_statement: all                           # 记录所有 SQL

参数渲染规则

用户级参数的渲染规则与数据库级参数相同：

列表类型参数（search_path、temp_tablespaces、local_preload_libraries、session_preload_libraries）不加外层引号：

ALTER USER "dbuser_analyst" SET "search_path" = "$user", public, analytics;

标量参数 使用引号包裹：

ALTER USER "dbuser_analyst" SET "work_mem" = '256MB';
ALTER USER "dbuser_analyst" SET "statement_timeout" = '5min';

特殊值 DEFAULT

使用 DEFAULT（大小写不敏感）可以将参数重置为 PostgreSQL 默认值：

parameters:
  work_mem: DEFAULT          # 重置为默认值
  statement_timeout: 30s     # 设置具体值
ALTER USER "dbuser_app" SET "work_mem" = DEFAULT;
ALTER USER "dbuser_app" SET "statement_timeout" = '30s';

查看用户参数 

-- 查看特定用户的参数设置
SELECT rolname, unnest(setconfig) AS setting
FROM pg_db_role_setting drs
JOIN pg_roles r ON r.oid = drs.setrole
WHERE rolname = 'dbuser_analyst';

手动管理 

-- 设置参数
ALTER USER dbuser_app SET work_mem = '128MB';
ALTER USER dbuser_app SET search_path = "$user", public, myschema;

-- 重置参数
ALTER USER dbuser_app RESET work_mem;
ALTER USER dbuser_app RESET ALL;

参数优先级

当同一参数在多个层级设置时，PostgreSQL 按以下优先级应用（从低到高）：

postgresql.conf           ← 集群级参数（Patroni DCS）
       ↓
postgresql.auto.conf      ← 实例级参数（pg_parameters / ALTER SYSTEM）
       ↓
数据库级                    ← ALTER DATABASE SET
       ↓
用户级                      ← ALTER USER SET
       ↓
会话级                      ← SET 命令

关于数据库级与用户级的优先级：

当用户连接到特定数据库时，如果同一参数在数据库级和用户级都有设置， PostgreSQL 会使用 用户级参数，因为用户级优先级更高。

示例场景：

# 数据库级：analytics 数据库 work_mem = 256MB
pg_databases:
  - name: analytics
    parameters:
      work_mem: 256MB

# 用户级：analyst 用户 work_mem = 512MB
pg_users:
  - name: analyst
    parameters:
      work_mem: 512MB
  • 当 analyst 用户连接到 analytics 数据库时：work_mem = 512MB（用户级优先）
  • 当其他用户连接到 analytics 数据库时：work_mem = 256MB（数据库级生效）
  • 当 analyst 用户连接到其他数据库时：work_mem = 512MB（用户级生效）

1.8 - 访问控制

Pigsty 内置角色、用户、默认权限与数据库 ACL 的配置参考。

访问控制由角色、对象权限、数据库 ACL 与 HBA 共同决定。本节聚焦配置参数；设计与边界见 访问控制概念。

Pigsty 预置了一套精简的 ACL 模型，通过以下参数描述：

  • pg_default_roles：系统角色与系统用户。
  • pg_users：业务用户与角色。
  • pg_default_privileges：管理员/属主新建对象时的默认权限。
  • pg_revoke_public、pg_default_schemas、pg_default_extensions：控制 template1 的默认行为。

这些参数应与 HBA 和数据库定义一起管理，形成可复现的访问控制配置。

默认角色体系（pg_default_roles）

默认包含 4 个业务角色 + 4 个系统用户：

名称 类型 说明
dbrole_readonly NOLOGIN 所有业务共用，拥有 SELECT/USAGE
dbrole_readwrite NOLOGIN 继承只读角色，并拥有 INSERT/UPDATE/DELETE
dbrole_admin NOLOGIN 继承 pg_monitor + 读写角色，可建对象和触发器
dbrole_offline NOLOGIN 独立只读角色；实例范围需要通过 HBA 显式限制
postgres 用户 系统超级用户，与 pg_dbsu 同名
replicator 用户 用于流复制与备份，继承监控与只读权限
dbuser_dba 用户 主要管理员账号，同时同步到 pgbouncer
dbuser_monitor 用户 监控账号，具备 pg_monitor 权限，默认记录慢 SQL

这些定义位于 pg_default_roles。该参数是完整列表；自定义时应复制并保留所需的默认角色和系统用户，再按依赖顺序添加新角色。更改角色名称后，还必须同步更新 HBA、默认权限和脚本中的引用。

默认用户与凭据参数

系统用户的用户名/密码由以下参数控制：

参数 默认值 作用
pg_dbsu postgres 数据库/系统超级用户
pg_dbsu_password 空字符串 dbsu 密码（默认不启用）
pg_replication_username replicator 复制用户名称
pg_replication_password DBUser.Replicator 复制用户密码
pg_admin_username dbuser_dba 管理员用户名
pg_admin_password DBUser.DBA 管理员密码
pg_monitor_username dbuser_monitor 监控用户
pg_monitor_password DBUser.Monitor 监控用户密码

修改这些参数后，应同步更新 pg_default_roles 中对应用户的定义，避免用户名和角色属性不一致。

业务角色与授权（pg_users）

业务用户通过 pg_users 声明（详细字段见 用户配置），其中 roles 字段控制授予的业务角色。

示例：创建只读/读写用户各一名：

pg_users:
  - { name: app_reader,  password: DBUser.Reader,  roles: [dbrole_readonly],  pgbouncer: true }
  - { name: app_writer,  password: DBUser.Writer,  roles: [dbrole_readwrite], pgbouncer: true }

业务用户通过继承 dbrole_* 获得默认对象权限；数据库 CONNECT 权限和 pg_hba_rules 继续控制可连接的数据库和来源。

需要更细粒度的 ACL 时，可在 baseline SQL 或后续剧本中使用标准 GRANT / REVOKE，并将额外授权纳入审查。

默认权限模板（pg_default_privileges）

pg_default_privileges 会应用到 pg_dbsu、pg_admin_username、dbrole_admin，并应用到每个已声明的数据库属主。默认模板如下：

pg_default_privileges:
  - GRANT USAGE      ON SCHEMAS   TO dbrole_readonly
  - GRANT SELECT     ON TABLES    TO dbrole_readonly
  - GRANT SELECT     ON SEQUENCES TO dbrole_readonly
  - GRANT EXECUTE    ON FUNCTIONS TO dbrole_readonly
  - GRANT USAGE      ON SCHEMAS   TO dbrole_offline
  - GRANT SELECT     ON TABLES    TO dbrole_offline
  - GRANT SELECT     ON SEQUENCES TO dbrole_offline
  - GRANT EXECUTE    ON FUNCTIONS TO dbrole_offline
  - GRANT INSERT     ON TABLES    TO dbrole_readwrite
  - GRANT UPDATE     ON TABLES    TO dbrole_readwrite
  - GRANT DELETE     ON TABLES    TO dbrole_readwrite
  - GRANT USAGE      ON SEQUENCES TO dbrole_readwrite
  - GRANT UPDATE     ON SEQUENCES TO dbrole_readwrite
  - GRANT TRUNCATE   ON TABLES    TO dbrole_admin
  - GRANT REFERENCES ON TABLES    TO dbrole_admin
  - GRANT TRIGGER    ON TABLES    TO dbrole_admin
  - GRANT CREATE     ON SCHEMAS   TO dbrole_admin

由上述身份创建的对象会自动应用对应权限。其他对象创建者需要单独配置 ALTER DEFAULT PRIVILEGES。

额外提示：

  • pg_revoke_public 默认为 true，意味着自动撤销 PUBLIC 在数据库和 public schema 上的 CREATE 权限。
  • pg_default_schemas 和 pg_default_extensions 控制在 template1/postgres 中预创建的 schema/扩展，通常用于监控对象（monitor schema、pg_stat_statements 等）。

常见配置场景

为合作方提供只读账号 

pg_users:
  - name: partner_ro
    password: Partner.Read
    roles: [dbrole_readonly]
pg_hba_rules:
  - { user: partner_ro, db: analytics, addr: 203.0.113.0/24, auth: ssl }

该配置为合作方增加一条从指定网段通过 TLS 访问 analytics 的 HBA 规则。pg_hba_rules 不会删除范围更宽的默认规则；若要求该账号只能访问此数据库，还应收敛默认 HBA，并配置数据库 CONNECT 权限。

为业务管理员赋予 DDL 能力 

pg_users:
  - name: app_admin
    password: DBUser.AppAdmin
    roles: [dbrole_admin]

app_admin 可以继承 dbrole_admin 的 DDL 权限。要让新对象应用 dbrole_admin 的默认权限，应先执行 SET ROLE dbrole_admin；如果 app_admin 是已声明的数据库属主，也可以直接以属主身份创建对象。

自定义默认权限 

pg_default_privileges:
  - GRANT INSERT,UPDATE,DELETE ON TABLES TO dbrole_admin
  - GRANT SELECT,UPDATE ON SEQUENCES TO dbrole_admin
  - GRANT SELECT ON TABLES TO reporting_group

该参数会替换完整的默认权限列表。引用的角色必须先创建；变更只影响之后创建的对象，已有对象需要另行授权。

与其他组件的协同

  • HBA 规则：使用 pg_hba_rules 绑定角色、数据库和来源。要限制 dbrole_offline，应为其规则设置 role: offline。
  • PgBouncer：pgbouncer: true 的用户会被写入 userlist.txt，pool_mode/pool_connlimit 可以控制连接池层面的配额。
  • 数据库监控：dbuser_monitor 的权限来自 pg_default_roles。新增监控用户时，应授予 pg_monitor，并检查 monitor schema 的访问权限。

这些参数可以与配置清单一起版本化；实际权限仍应通过数据库系统目录定期核对。

相关文档

2 - 服务/接入

分离读写操作，正确路由流量，稳定可靠地交付 PostgreSQL 集群提供的能力。

分离读写操作，正确路由流量，稳定可靠地交付 PostgreSQL 集群提供的能力。

服务 是一种抽象：它是数据库集群对外提供能力的形式，并封装了底层集群的细节。

服务对于生产环境中的 稳定接入 至关重要，在 高可用 集群自动故障时方显其价值，单机用户 通常不需要操心这个概念。

单机用户

“服务” 的概念是给生产环境用的，个人用户/单机集群可以不折腾，直接拿实例名/IP 地址访问数据库。

例如，Pigsty 默认的单节点 pg-meta.meta 数据库，就可以直接用下面三个不同的用户连接上去。

psql postgres://dbuser_dba:[email protected]/meta     # 直接用 DBA 超级用户连上去
psql postgres://dbuser_meta:[email protected]/meta   # 用默认的业务管理员用户连上去
psql postgres://dbuser_view:DBUser.Viewer@pg-meta/meta     # 用默认的只读用户走实例域名连上去

服务概述

在真实世界生产环境中，我们会使用基于复制的主从数据库集群。集群中有且仅有一个实例作为领导者（主库）可以接受写入。 而其他实例（从库）则会从持续从集群领导者获取变更日志，与领导者保持一致。同时，从库还可以承载只读请求，在读多写少的场景下可以显著分担主库的负担， 因此对集群的写入请求与只读请求进行区分，是一种十分常见的实践。

此外对于高频短连接的生产环境，我们还会通过连接池中间件（Pgbouncer）对请求进行池化，减少连接与后端进程的创建开销。但对于 ETL 与变更执行等场景，我们又需要绕过连接池，直接访问数据库。 同时，高可用集群在故障时会出现故障切换（Failover），故障切换会导致集群的领导者出现变更。因此高可用的数据库方案要求写入流量可以自动适配集群的领导者变化。 这些不同的访问需求（读写分离，池化与直连，故障切换自动适配）最终抽象出 服务 （Service）的概念。

通常来说，数据库集群都必须提供这种最基础的服务：

  • 读写服务（primary）：可以读写数据库

对于生产数据库集群，至少应当提供这两种服务：

  • 读写服务（primary）：写入数据：只能由主库所承载。
  • 只读服务（replica）：读取数据：可以由从库承载，没有从库时也可由主库承载

此外，根据具体的业务场景，可能还会有其他的服务，例如：

  • 默认直连服务（default）：允许（管理）用户，绕过连接池直接访问数据库的服务
  • 离线从库服务（offline）：不承接线上只读流量的专用从库，用于 ETL 与分析查询
  • 同步从库服务（standby）：没有复制延迟的只读服务，由 同步备库/主库处理只读查询
  • 延迟从库服务（delayed）：访问同一个集群在一段时间之前的旧数据，由 延迟从库 来处理

默认服务

Pigsty 默认为每个 PostgreSQL 数据库集群提供四种不同的服务，以下是默认服务及其定义：

服务 端口 描述
primary 5433 生产读写，连接到主库连接池（6432）
replica 5434 生产只读，连接到备库连接池（6432）
default 5436 管理，ETL 写入，直接访问主库（5432）
offline 5438 OLAP、ETL、个人用户、交互式查询

以默认的 pg-meta 集群为例，它提供四种默认服务：

psql postgres://dbuser_meta:DBUser.Meta@pg-meta:5433/meta   # pg-meta-primary : 通过主要的 pgbouncer(6432) 进行生产读写
psql postgres://dbuser_meta:DBUser.Meta@pg-meta:5434/meta   # pg-meta-replica : 通过备份的 pgbouncer(6432) 进行生产只读
psql postgres://dbuser_dba:DBUser.DBA@pg-meta:5436/meta     # pg-meta-default : 通过主要的 postgres(5432) 直接连接
psql postgres://dbuser_stats:DBUser.Stats@pg-meta:5438/meta # pg-meta-offline : 通过离线的 postgres(5432) 直接连接

从示例集群 架构图 上可以看出这四种服务的工作方式：

pigsty-ha.png

这里 pg-meta 的实际 DNS 目标由 pg_dns_target 决定：默认 auto 在启用 L2 VIP 时指向 VIP，否则指向清单中的主实例 IP。默认配置并不启用 VIP，详见 服务接入。

服务实现

在 Pigsty 中，服务使用 节点 上的 haproxy 来实现，通过主机节点上的不同端口进行区分。

Pigsty 所纳管的每个节点上都默认启用了 Haproxy 以对外暴露服务，而数据库节点也不例外。 集群中的节点尽管从数据库的视角来看有主从之分，但从服务的视角来看，每个节点都是相同的： 这意味着即使您访问的是从库节点，只要使用正确的服务端口，就依然可以使用到主库读写的服务。 这样的设计可以屏蔽复杂度：所以您只要可以访问 PostgreSQL 集群上的任意一个实例，就可以完整的访问到所有服务。

这样的设计类似于 Kubernetes 中的 NodePort 服务，同样在 Pigsty 中，每一个服务都包括以下两个核心要素：

  1. 通过 NodePort 暴露的访问端点（端口号，从哪访问？）
  2. 通过 Selectors 选择的目标实例（实例列表，谁来承载？）

Pigsty 的服务交付边界止步于集群的 HAProxy，用户可以用各种手段访问这些负载均衡器，请参考 接入服务。

所有的服务都通过配置文件进行声明，例如，PostgreSQL 默认服务就是由 pg_default_services 参数所定义的：

pg_default_services:
- { name: primary ,port: 5433 ,dest: default  ,check: /primary   ,selector: "[]" }
- { name: replica ,port: 5434 ,dest: default  ,check: /read-only ,selector: "[]" , backup: "[? pg_role == `primary` || pg_role == `offline` ]" }
- { name: default ,port: 5436 ,dest: postgres ,check: /primary   ,selector: "[]" }
- { name: offline ,port: 5438 ,dest: postgres ,check: /replica   ,selector: "[? pg_role == `offline` || pg_offline_query ]" , backup: "[? pg_role == `replica` && !pg_offline_query]"}

您也可以在 pg_services 中定义额外的服务，参数 pg_default_services 与 pg_services 都是由 服务定义 对象组成的数组。

定义服务

Pigsty 允许您定义自己的服务：

  • pg_default_services：所有 PostgreSQL 集群统一对外暴露的服务，默认有四个。
  • pg_services：额外的 PostgreSQL 服务，可以视需求在全局或集群级别定义。
  • haproxy_services：直接定制 HAProxy 服务内容，可以用于其他组件的接入

对于 PostgreSQL 集群来说，通常只需要关注前两者即可。 每一条服务定义都会在所有相关 HAProxy 实例的配置目录下生成一个新的配置文件：/etc/haproxy/conf.d/<pg_cluster>-<service>.cfg 下面是一个自定义的服务样例 standby：当您想要对外提供没有复制延迟的只读服务时，就可以在 pg_services 新增这条记录：

- name: standby                   # 必选，服务名称，最终的 svc 名称会使用 `pg_cluster` 作为前缀，例如：pg-meta-standby
  port: 5435                      # 必选，暴露的服务端口（作为 kubernetes 服务节点端口模式）
  ip: "*"                         # 可选，服务绑定的 IP 地址，默认情况下为所有 IP 地址
  selector: "[]"                  # 必选，服务成员选择器，使用 JMESPath 来筛选配置清单
  backup: "[? pg_role == `primary`]"  # 可选，服务成员选择器（备份），也就是当默认选择器选中的实例都宕机后，服务才会由这里选中的实例成员来承载
  dest: default                   # 可选，目标端口，default|postgres|pgbouncer|<port_number>，默认为 'default'，即由 pg_default_service_dest 决定
  check: /sync                    # 可选，健康检查 URL 路径，默认为 /，这里使用 Patroni API：/sync ，只有同步备库和主库才会返回 200 健康状态码 
  maxconn: 5000                   # 可选，允许的前端连接最大数，默认为5000
  balance: roundrobin             # 可选，haproxy 负载均衡算法（默认为 roundrobin，其他选项：leastconn）
  options: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'

而上面的服务定义，在样例的三节点 pg-test 上将会被转换为 HAProxy 配置文件 /etc/haproxy/conf.d/pg-test-standby.cfg：

#---------------------------------------------------------------------
# service: pg-test-standby @ 10.10.10.11:5435
#---------------------------------------------------------------------
# service instances 10.10.10.11, 10.10.10.13, 10.10.10.12
# service backups   10.10.10.11
listen pg-test-standby
    bind *:5435            # <--- 绑定了所有IP地址上的 5435 端口
    mode tcp               # <--- 负载均衡器工作在 TCP 协议上
    maxconn 5000           # <--- 最大连接数为 5000，可按需调大
    balance roundrobin     # <--- 负载均衡算法为 rr 轮询，还可以使用 leastconn 
    option httpchk         # <--- 启用 HTTP 健康检查
    option http-keep-alive # <--- 保持HTTP连接
    http-check send meth OPTIONS uri /sync   # <---- 这里使用 /sync ，Patroni 健康检查 API ，只有同步备库和主库才会返回 200 健康状态码。 
    http-check expect status 200             # <---- 健康检查返回代码 200 代表正常
    default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
    # servers： # pg-test 集群全部三个实例都被 selector: "[]" 圈中，成为 pg-test-standby 服务的后端；/sync 健康检查只放行主库和同步备库。
    server pg-test-1 10.10.10.11:6432 check port 8008 weight 100 backup  # <----- 唯独主库满足条件 pg_role == `primary`， 被 backup selector 选中。
    server pg-test-3 10.10.10.13:6432 check port 8008 weight 100         #        因此作为服务的兜底实例：平时不承载请求，其他从库全部宕机后，才会承载只读请求，从而最大避免了读写服务受到只读服务的影响
    server pg-test-2 10.10.10.12:6432 check port 8008 weight 100         #

在这里，pg-test 集群全部三个实例都被 selector: "[]" 给圈中了，渲染进入 pg-test-standby 服务的后端服务器列表中。但是因为还有 /sync 健康检查，Patroni Rest API 只有在主库和 同步备库 上才会返回代表健康的 HTTP 200 状态码，因此只有主库和同步备库才能真正承载请求。 此外，主库因为满足条件 pg_role == primary， 被 backup selector 选中，被标记为了备份服务器，只有当没有其他实例（也就是同步备库）可以满足需求时，才会顶上。

Primary服务

Primary 服务可能是生产环境中最关键的服务，它在 5433 端口提供对数据库集群的读写能力，服务定义如下：

- { name: primary ,port: 5433 ,dest: default  ,check: /primary   ,selector: "[]" }
  • 选择器参数 selector: "[]" 意味着所有集群成员都将被包括在 Primary 服务中
  • 但只有主库能够通过健康检查（check: /primary），实际承载 Primary 服务的流量。
  • 目的地参数 dest: default 意味着 Primary 服务的目的地受到 pg_default_service_dest 参数的影响
  • dest 默认值 default 会被替换为 pg_default_service_dest 的值，默认为 pgbouncer。
  • 默认情况下 Primary 服务的目的地默认是主库上的连接池，也就是由 pgbouncer_port 指定的端口，默认为 6432

如果 pg_default_service_dest 的值为 postgres，那么 primary 服务的目的地就会绕过连接池，直接使用 PostgreSQL 数据库的端口（pg_port，默认值 5432），对于一些不希望使用连接池的场景，这个参数非常实用。

示例：pg-test-primary 的 haproxy 配置
listen pg-test-primary
    bind *:5433         # <--- primary 服务默认使用 5433 端口
    mode tcp
    maxconn 5000
    balance roundrobin
    option httpchk
    option http-keep-alive
    http-check send meth OPTIONS uri /primary # <--- primary 服务默认使用 Patroni RestAPI /primary 健康检查
    http-check expect status 200
    default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
    # servers
    server pg-test-1 10.10.10.11:6432 check port 8008 weight 100
    server pg-test-3 10.10.10.13:6432 check port 8008 weight 100
    server pg-test-2 10.10.10.12:6432 check port 8008 weight 100

Patroni 的 高可用 机制确保任何时候最多只会有一个实例的 /primary 健康检查为真，因此 Primary 服务将始终将流量路由到主实例。

使用 Primary 服务而不是直连数据库的一个好处是，如果集群因为某种情况出现了双主（比如在没有 watchdog 的情况下 kill -9杀死主库 Patroni），Haproxy 在这种情况下仍然可以避免脑裂，因为它只会在 Patroni 存活且返回主库状态时才会分发流量。

Replica服务

Replica 服务在生产环境中的重要性仅次于 Primary 服务，它在 5434 端口提供对数据库集群的只读能力，服务定义如下：

- { name: replica ,port: 5434 ,dest: default  ,check: /read-only ,selector: "[]" , backup: "[? pg_role == `primary` || pg_role == `offline` ]" }
  • 选择器参数 selector: "[]" 意味着所有集群成员都将被包括在 Replica 服务中
  • 所有实例都能够通过健康检查（check: /read-only），承载 Replica 服务的流量。
  • 备份选择器：[? pg_role == 'primary' || pg_role == 'offline' ] 将主库和 离线从库 标注为备份服务器。
  • 只有当所有 普通从库 都宕机后，Replica 服务才会由主库或离线从库来承载。
  • 目的地参数 dest: default 意味着 Replica 服务的目的地也受到 pg_default_service_dest 参数的影响
  • dest 默认值 default 会被替换为 pg_default_service_dest 的值，默认为 pgbouncer，这一点和 Primary服务 相同
  • 默认情况下 Replica 服务的目的地默认是从库上的连接池，也就是由 pgbouncer_port 指定的端口，默认为 6432
示例：pg-test-replica 的 haproxy 配置
listen pg-test-replica
    bind *:5434
    mode tcp
    maxconn 5000
    balance roundrobin
    option httpchk
    option http-keep-alive
    http-check send meth OPTIONS uri /read-only
    http-check expect status 200
    default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
    # servers
    server pg-test-1 10.10.10.11:6432 check port 8008 weight 100 backup
    server pg-test-3 10.10.10.13:6432 check port 8008 weight 100
    server pg-test-2 10.10.10.12:6432 check port 8008 weight 100

Replica 服务非常灵活：如果有存活的专用 Replica 实例，那么它会优先使用这些实例来承载只读请求，只有当从库实例全部宕机后，才会由主库来兜底只读请求。对于常见的一主一从双节点集群就是：只要从库活着就用从库，从库挂了再用主库。

此外，除非专用只读实例全部宕机，Replica 服务也不会使用专用 Offline 实例，这样就避免了在线快查询与离线慢查询混在一起，相互影响。

Default服务

Default 服务在 5436 端口上提供服务，它是 Primary 服务的变体。

Default 服务总是绕过连接池直接连到主库上的 PostgreSQL，这对于管理连接、ETL 写入、CDC 数据变更捕获等都很有用。

- { name: default ,port: 5436 ,dest: postgres ,check: /primary   ,selector: "[]" }

如果 pg_default_service_dest 被修改为 postgres，那么可以说 Default 服务除了端口和名称内容之外，与 Primary 服务是完全等价的。在这种情况下，您可以考虑将 Default 从默认服务中剔除。

示例：pg-test-default 的 haproxy 配置
listen pg-test-default
    bind *:5436         # <--- 除了监听端口/目标端口和服务名，其他配置和 primary 服务一模一样
    mode tcp
    maxconn 5000
    balance roundrobin
    option httpchk
    option http-keep-alive
    http-check send meth OPTIONS uri /primary
    http-check expect status 200
    default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
    # servers
    server pg-test-1 10.10.10.11:5432 check port 8008 weight 100
    server pg-test-3 10.10.10.13:5432 check port 8008 weight 100
    server pg-test-2 10.10.10.12:5432 check port 8008 weight 100

Offline服务

Offline 服务在 5438 端口上提供服务，它绕开连接池直接访问 PostgreSQL 数据库，通常用于慢查询/分析查询/ETL 读取/个人用户交互式查询，其服务定义如下：

- { name: offline ,port: 5438 ,dest: postgres ,check: /replica   ,selector: "[? pg_role == `offline` || pg_offline_query ]" , backup: "[? pg_role == `replica` && !pg_offline_query]"}

Offline 服务将流量直接路由到专用的 离线从库 上，或者带有 pg_offline_query 标记的普通 只读实例。

  • 选择器参数从集群中筛选出了两种实例：pg_role = offline 的离线从库，或是带有 pg_offline_query = true 标记的普通 只读实例
  • 专用离线从库和打标记的普通从库主要的区别在于：前者默认不承载 Replica服务 的请求，避免快慢请求混在一起，而后者默认会承载。
  • 备份选择器参数从集群中筛选出了一种实例：不带 offline 标记的普通从库，这意味着如果离线实例或者带 Offline 标记的普通从库挂了之后，其他普通的从库可以用来承载 Offline 服务。
  • 健康检查 /replica 只会针对从库返回 200， 主库会返回错误，因此 Offline 服务 永远不会将流量分发到主库实例上去，哪怕集群中只剩这一台主库。
  • 同时，主库实例既不会被选择器圈中，也不会被备份选择器圈中，因此它永远不会承载 Offline 服务。因此 Offline 服务总是可以避免用户访问主库，从而避免对主库的影响。
示例：pg-test-offline 的 haproxy 配置
listen pg-test-offline
    bind *:5438
    mode tcp
    maxconn 5000
    balance roundrobin
    option httpchk
    option http-keep-alive
    http-check send meth OPTIONS uri /replica
    http-check expect status 200
    default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
    # servers
    server pg-test-3 10.10.10.13:5432 check port 8008 weight 100
    server pg-test-2 10.10.10.12:5432 check port 8008 weight 100 backup

Offline 服务提供受限的只读服务，通常用于两类查询：交互式查询（个人用户），慢查询长事务（分析/ETL）。

Offline 服务需要额外的维护照顾：HAProxy 的 /replica 健康检查会在主从切换后自动拒绝新主库，但 selector 使用的是配置清单中的静态 pg_role / pg_offline_query 标签。对于一主一从、仅从库承载 Offline 查询的精简集群，切换后可能暂时没有合格后端。 仅重载未修改的清单并不会把原主库加入 Offline 后端。需要先按新的规划调整清单标签（或 pg_offline_query）再 重载服务，或者将主库切回原节点。

如果您的业务模型较为简单，您可以考虑剔除 Default 服务与 Offline 服务，使用 Primary 服务与 Replica 服务直连数据库。

重载服务

当集群成员发生变化（添加/删除副本）、服务定义或静态选择标签变化、相对权重调整时，需要 重载服务。Primary/Replica 服务的正常主备切换由 Patroni 健康检查自动接管，不需要为此单独重载。

bin/pgsql-svc <cls> [ip...]         # 为 lb 集群或 lb 实例重载服务
# ./pgsql.yml -t pg_service         # 重载服务的实际 ansible 任务

接入服务

Pigsty 的服务交付边界止步于集群的 HAProxy，用户可以用各种手段访问这些负载均衡器。

典型的做法是使用 DNS 或 VIP 接入，将其绑定在集群所有或任意数量的负载均衡器上。

pigsty-access.jpg

你可以使用不同的 主机 & 端口 组合，它们以不同的方式提供 PostgreSQL 服务。

主机

类型 样例 描述
集群域名 pg-test 通过集群域名访问（由 dnsmasq @ infra 节点解析）
集群 VIP 地址 10.10.10.3 通过由 vip-manager 管理的 L2 VIP 地址访问，绑定到主节点
实例主机名 pg-test-1 通过任何实例主机名访问（由 dnsmasq @ infra 节点解析）
实例 IP 地址 10.10.10.11 访问任何实例的 IP 地址

端口

Pigsty 使用不同的 端口 来区分 pg services

端口 服务 类型 描述
5432 postgres 数据库 直接访问 postgres 服务器
6432 pgbouncer 中间件 访问 postgres 前先通过连接池中间件
5433 primary 服务 访问主 pgbouncer (或 postgres)
5434 replica 服务 访问备份 pgbouncer (或 postgres)
5436 default 服务 访问主 postgres
5438 offline 服务 访问离线 postgres

组合

# 通过集群域名访问（以下示例假定已启用 L2 VIP；未启用时默认指向清单主实例 IP）
postgres://test@pg-test:5432/test # DNS -> L2 VIP -> 主直接连接
postgres://test@pg-test:6432/test # DNS -> L2 VIP -> 主连接池 -> 主
postgres://test@pg-test:5433/test # DNS -> L2 VIP -> HAProxy -> 主连接池 -> 主
postgres://test@pg-test:5434/test # DNS -> L2 VIP -> HAProxy -> 备份连接池 -> 备份
postgres://dbuser_dba@pg-test:5436/test # DNS -> L2 VIP -> HAProxy -> 主直接连接 (用于管理员)
postgres://dbuser_stats@pg-test:5438/test # DNS -> L2 VIP -> HAProxy -> 离线直接连接 (用于 ETL/个人查询)

# 通过集群 VIP 直接访问
postgres://[email protected]:5432/test # L2 VIP -> 主直接访问
postgres://[email protected]:6432/test # L2 VIP -> 主连接池 -> 主
postgres://[email protected]:5433/test # L2 VIP -> HAProxy -> 主连接池 -> 主
postgres://[email protected]:5434/test # L2 VIP -> HAProxy -> 备份连接池 -> 备份
postgres://[email protected]:5436/test # L2 VIP -> HAProxy -> 主直接连接 (用于管理员)
postgres://[email protected]:5438/test # L2 VIP -> HAProxy -> 离线直接连接 (用于 ETL/个人查询)

# 直接指定任何集群实例名
postgres://test@pg-test-1:5432/test # DNS -> 数据库实例直接连接 (单例访问)
postgres://test@pg-test-1:6432/test # DNS -> 连接池 -> 数据库
postgres://test@pg-test-1:5433/test # DNS -> HAProxy -> 连接池 -> 数据库读/写
postgres://test@pg-test-1:5434/test # DNS -> HAProxy -> 连接池 -> 数据库只读
postgres://dbuser_dba@pg-test-1:5436/test # DNS -> HAProxy -> 数据库直接连接
postgres://dbuser_stats@pg-test-1:5438/test # DNS -> HAProxy -> 数据库离线读/写

# 直接指定任何集群实例 IP 访问
postgres://[email protected]:5432/test # 数据库实例直接连接 (直接指定实例, 没有自动流量分配)
postgres://[email protected]:6432/test # 连接池 -> 数据库
postgres://[email protected]:5433/test # HAProxy -> 连接池 -> 数据库读/写
postgres://[email protected]:5434/test # HAProxy -> 连接池 -> 数据库只读
postgres://[email protected]:5436/test # HAProxy -> 数据库直接连接
postgres://[email protected]:5438/test # HAProxy -> 数据库离线读/写

# 智能客户端：自动进行读写分离
postgres://[email protected]:6432,10.10.10.12:6432,10.10.10.13:6432/test?target_session_attrs=primary
postgres://[email protected]:6432,10.10.10.12:6432,10.10.10.13:6432/test?target_session_attrs=prefer-standby

覆盖服务

你可以通过多种方式覆盖默认的服务配置，一种常见的需求是让 Primary服务 与 Replica服务 绕过 Pgbouncer 连接池，直接访问 PostgreSQL 数据库。

为了实现这一点，你可以将 pg_default_service_dest 更改为 postgres，这样所有服务定义中 svc.dest='default' 的服务都会使用 postgres 而不是默认的 pgbouncer 作为目标。

如果您已经将 Primary服务 指向了 PostgreSQL，那么 default服务 就会比较多余，可以考虑移除。

如果您不需要区分个人交互式查询，分析/ETL 慢查询，可以考虑从默认服务列表 pg_default_services 中移除 Offline服务。

如果您不需要只读从库来分担在线只读流量，也可以从默认服务列表中移除 Replica服务。

委托服务

Pigsty 通过节点上的 haproxy 暴露 PostgreSQL 服务。整个集群中的所有 haproxy 实例都使用相同的 服务定义 进行配置。

但是，你可以将 pg 服务委托给特定的节点分组（例如，专门的 haproxy 负载均衡器集群），而不是 PostgreSQL 集群成员上的 haproxy。

为此，你需要使用 pg_default_services 覆盖默认的服务定义，并将 pg_service_provider 设置为代理组名称。

例如，此配置将在端口 10013 的 proxy haproxy 节点组上公开 pg 集群的主服务。

pg_service_provider: proxy       # 使用端口 10013 上的 `proxy` 组的负载均衡器
pg_default_services:  [{ name: primary ,port: 10013 ,dest: postgres  ,check: /primary   ,selector: "[]" }]

用户需要确保每个委托服务的端口，在代理集群中都是 唯一 的。

在 20 节点生产环境仿真 沙箱 中提供了一个使用专用负载均衡器集群的例子：conf/ha/simu.yml

3 - PostgreSQL 安全

PostgreSQL 身份认证、访问控制、加密通信、数据保护与安全运维入口。

PostgreSQL 安全由身份认证、权限控制、网络边界、加密通信、数据保护和运维流程共同构成。Pigsty 提供这些机制的配置入口，但部署方仍需根据环境完成加固、验证和持续审计。

概念与边界

主题 内容
安全与合规 默认状态、能力边界与加固路径
身份认证 HBA、SCRAM、证书认证与凭据管理
访问控制 内置角色、默认权限、数据库 ACL 与实例访问边界
加密通信 CA、TLS、服务端身份验证与证书轮换
数据安全 页校验和、复制、备份、PITR、审计与日志
合规实践 上线检查、控制映射与证据要求

配置参考

  • HBA 配置：声明 PostgreSQL 与 PgBouncer 的认证规则。
  • 访问控制配置：配置默认角色、业务用户、对象权限与数据库 ACL。
  • 用户配置：定义用户属性、角色成员关系和连接池选项。
  • CRIT 参数模板：同步复制、校验和、日志与 watchdog 等关键参数。

管理与验证

  • 用户管理：创建、更新和删除用户。
  • HBA 管理：刷新规则、检查生效配置并排查认证问题。
  • 安全考量：生产部署的加固与验收清单。
  • 安全建议：安装前最基本的密码、网络和文件检查。

配置清单描述期望状态。验收时还应检查运行节点上的 HBA、证书、监听端口和敏感文件，并通过 PostgreSQL 系统目录核对实际角色与权限。

4 - 日常管理

数据库日常管理任务标准操作指南（SOP）

4.1 - 管理 PostgreSQL 数据库集群

创建/销毁 PostgreSQL 集群，以及对现有集群进行扩容，缩容，克隆集群。

速查手册

操作 快捷命令 说明
创建集群 bin/pgsql-add <cls> 创建新的 PostgreSQL 集群
扩容集群 bin/pgsql-add <cls> <ip...> 为现有集群添加从库副本
缩容集群 bin/pgsql-rm <cls> <ip...> 从集群中移除指定实例
销毁集群 bin/pgsql-rm <cls> 销毁整个 PostgreSQL 集群
刷新服务 bin/pgsql-svc <cls> [ip...] 重载集群的负载均衡配置
刷新HBA bin/pgsql-hba <cls> [ip...] 重载集群的 HBA 访问规则
克隆集群 - 通过备份集群或 PITR 克隆

其他管理任务，请参考：高可用管理，管理用户，管理数据库。

创建集群

要创建一个新的 PostgreSQL 集群，请首先在 配置清单 中 定义集群，然后 纳管节点 并进行初始化：

脚本
bin/node-add  <cls>     # 添加分组 <cls> 下的节点
剧本
./node.yml  -l <cls>    # 直接使用 Ansible 剧本添加分组 <cls> 下的节点
示例
bin/node-add pg-test    # 例子，添加 pg-test 分组下的节点，实际执行 ./node.yml -l pg-test

在被纳管的节点上，可以使用以下命令创建集群：（针对 <cls> 分组执行 pgsql.yml 剧本）

脚本
bin/pgsql-add <cls>     # 创建 PostgreSQL 集群 <cls>
剧本
./pgsql.yml -l <cls>    # 直接使用 Ansible 剧本创建 PostgreSQL 集群 <cls>
示例
bin/pgsql-add pg-test   # 例子，创建 pg-test 集群

示例：创建三节点 PG 集群 pg-test

demo/pgsql.cast
针对已经存在的集群重新执行创建存在风险

如果您在已经存在的集群上重新执行创建操作，Pigsty 不会移除已有的数据文件，但现有服务配置会被覆盖，集群会发生 重启！ 此外，如果你在 数据库定义 中指定了 baseline SQL，它也会重新执行，如果里面包含删除/覆盖逻辑，可能会导致 数据丢失。

扩容集群

若要将新从库添加到 现有的 PostgreSQL 集群 中，您需要将 实例定义 添加到 配置清单：all.children.<cls>.hosts 中。

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary } # 已存在的成员
    10.10.10.12: { pg_seq: 2, pg_role: replica } # 已存在的成员
    10.10.10.13: { pg_seq: 3, pg_role: replica } # <--- 新成员
  vars: { pg_cluster: pg-test }

扩容集群的操作与 创建集群 非常类似，首先需要将扩容的节点纳入 Pigsty 管理：添加节点：

脚本
bin/node-add <ip>       # 添加 IP 地址为 <ip> 的节点
剧本
./node.yml -l <ip>      # 直接使用 Ansible 剧本添加 <ip> 对应的节点
示例
bin/node-add 10.10.10.13    # 例子，添加 IP 为 10.10.10.13 的节点，实际执行 ./node.yml -l 10.10.10.13

然后在新节点上运行以下命令以扩容集群（针对新节点安装 PGSQL 模块，使用与现有集群相同的 pg_cluster）

脚本
bin/pgsql-add <cls> <ip>  # 添加 IP 地址为 <ip> 的节点
剧本
./pgsql.yml -l <ip>       # 核心逻辑：使用 Ansible 剧本在 <ip> 节点上安装 PGSQL 模块
示例
bin/pgsql-add pg-test 10.10.10.13   # 示例，为 pg-test 集群扩容 IP 为 10.10.10.13 的节点

扩容完成后，您应当 刷新服务 以将新成员添加至负载均衡器中以实际承载流量。

示例：为两节点集群 pg-test 扩容一个新从库 10.10.10.13

demo/pgsql-append.cast

缩容集群

若要从 现有的 PostgreSQL 集群 中移除副本，您需要从 配置清单 的 all.children.<cls>.hosts 中移除对应的 实例定义。

缩容会停止实例并默认删除其数据目录。操作前先执行 pig pg list <cls> 与 pig pb info，确认目标不是主库、存在近期可恢复备份， 并让操作者输入精确的 <ip>，确认后方可实际执行。

缩容集群首先需要卸载目标节点上的 PGSQL 模块（针对 <ip> 执行 pgsql-rm.yml 剧本）：

脚本
bin/pgsql-rm <cls> <ip>   # 从集群 <cls> 中移除 <ip> 节点上的 PostgreSQL 实例
剧本
./pgsql-rm.yml -l <ip>    # 直接使用 Ansible 剧本移除 <ip> 节点上的 PostgreSQL 实例
示例
bin/pgsql-rm pg-test 10.10.10.13  # 例子，从 pg-test 集群移除 10.10.10.13 节点

移除 PGSQL 模块后，您可以选择将节点从 Pigsty 管理中移除：移除节点（可选）：

脚本
bin/node-rm <ip>          # 从 Pigsty 管理中移除 <ip> 节点
剧本
./node-rm.yml -l <ip>     # 直接使用 Ansible 剧本从 Pigsty 管理中移除 <ip> 节点
示例
bin/node-rm 10.10.10.13   # 例子，从 Pigsty 管理中移除 10.10.10.13 节点

缩容完成后，您应当从 配置清单 中移除该实例的定义，然后 刷新服务 以将它从负载均衡器中踢除。

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
    10.10.10.13: { pg_seq: 3, pg_role: replica } # <--- 执行后移除此行
  vars: { pg_cluster: pg-test }

示例：从三节点集群 pg-test 中缩容一个从库 10.10.10.13

demo/pgsql-shrink.cast

销毁集群

销毁集群需要在集群的所有节点上卸载 PGSQL 模块（针对 <cls> 执行 pgsql-rm.yml 剧本）：

这是不可逆的数据删除：先用 pig pg list <cls> 与 pig pb info 核对状态和近期备份，决定是否保留独立备份副本， 并要求操作者输入精确集群名。下面命令会直接执行相应的销毁操作。

脚本
bin/pgsql-rm <cls>        # 销毁整个 PostgreSQL 集群 <cls>
剧本
./pgsql-rm.yml -l <cls>   # 直接使用 Ansible 剧本销毁整个 PostgreSQL 集群 <cls>
示例
bin/pgsql-rm pg-test      # 例子，销毁 pg-test 集群

销毁 PGSQL 模块后，您可以选择将节点一并从 Pigsty 管理中移除：移除节点（可选，如果还有其他服务可以保留）：

脚本
bin/node-rm <cls>         # 从 Pigsty 管理中移除 <cls> 分组下的所有节点
剧本
./node-rm.yml -l <cls>    # 直接使用 Ansible 剧本从 Pigsty 管理中移除 <cls> 分组下的所有节点
示例
bin/node-rm pg-test       # 例子，从 Pigsty 管理中移除 pg-test 分组下的所有节点

销毁结束后，建议及时从 配置清单 中移除整个 集群定义。

pg-test: # 清理这个集群定义分组
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
    10.10.10.13: { pg_seq: 3, pg_role: replica }
  vars: { pg_cluster: pg-test }

示例：销毁三节点 PG 集群 pg-test

demo/pgsql-rm.cast

注意：如果为这个集群配置了 pg_safeguard（或全局设置为 true），pgsql-rm.yml 将中止执行，以避免意外销毁集群。 您可以使用剧本命令行参数明确地覆盖它，以强制执行销毁。 此外默认情况下，集群的备份仓库将同集群一并删除。如果你希望保留备份（例如在使用集中式备份仓库时），可以设置 pg_rm_backup=false 参数：

./pgsql-rm.yml -l pg-meta -e pg_safeguard=false    # 强制销毁受保护的 pg 集群 pg-meta
./pgsql-rm.yml -l pg-meta -e pg_rm_backup=false    # 在销毁集群过程中保留其备份仓库

刷新服务

PostgreSQL 集群通过主机节点上的 HAProxy 对外提供 服务。 当服务定义变化、实例权重变化，或者集群成员发生变化时（例如集群 扩容 / 缩容），您需要刷新服务以更新负载均衡器的静态成员配置。默认 Primary/Replica 服务通过 Patroni REST API 健康检查识别当前角色，正常的主从切换或故障转移会自动改道，不要求重新生成 HAProxy 配置。

要在整个集群或特定实例上刷新服务配置（针对 <cls> 或 <ip> 执行 pgsql.yml 的 pg_service 子任务）：

脚本
bin/pgsql-svc <cls>           # 刷新整个集群 <cls> 的服务配置
bin/pgsql-svc <cls> <ip...>   # 刷新集群 <cls> 中指定实例的服务配置
剧本
./pgsql.yml -l <cls> -t pg_service -e pg_reload=true        # 刷新整个集群的服务配置
./pgsql.yml -l <ip>  -t pg_service -e pg_reload=true        # 刷新指定实例的服务配置
示例
bin/pgsql-svc pg-test                 # 例子，刷新 pg-test 集群的服务配置
bin/pgsql-svc pg-test 10.10.10.13     # 例子，刷新 pg-test 集群中 10.10.10.13 实例的服务配置

备注：如果您使用集中式的专用负载均衡集群（pg_service_provider），那么只有刷新集群主库时才会更新负载均衡配置。

示例：刷新集群 pg-test 的服务配置

demo/pgsql-svc.cast
示例：重载 PG 服务以踢除一个实例

asciicast

刷新HBA

当您修改了 HBA 相关配置后，需要刷新 HBA 规则以应用更改。（pg_hba_rules / pgb_hba_rules） 如果您有任何特定于清单角色的 HBA 规则，或者在 IP 地址段中引用了集群成员的别名，那么修改 pg_role 标签或集群扩缩容后也可能需要刷新 HBA。这里的角色筛选使用静态清单变量，不会随 Patroni 主从切换自动改变。

要在整个集群或特定实例上刷新 PG 和 Pgbouncer 的 HBA 规则（针对 <cls> 或 <ip> 执行 pgsql.yml 的 HBA 相关子任务）：

脚本
bin/pgsql-hba <cls>           # 刷新整个集群 <cls> 的 HBA 规则
bin/pgsql-hba <cls> <ip...>   # 刷新集群 <cls> 中指定实例的 HBA 规则
剧本
./pgsql.yml -l <cls> -t pg_hba,pg_reload,pgbouncer_hba,pgbouncer_reload -e pg_reload=true   # 刷新整个集群
./pgsql.yml -l <ip>  -t pg_hba,pg_reload,pgbouncer_hba,pgbouncer_reload -e pg_reload=true   # 刷新指定实例
示例
bin/pgsql-hba pg-test                 # 例子，刷新 pg-test 集群的 HBA 规则
bin/pgsql-hba pg-test 10.10.10.13     # 例子，刷新 pg-test 集群中 10.10.10.13 实例的 HBA 规则

示例：刷新集群 pg-test 的 HBA 规则

demo/pgsql-hba.cast

配置集群

PostgreSQL 的配置参数由 Patroni 管理，初始参数由 Patroni 配置模板 指定。 集群初始化之后，配置存储在 Etcd 中，并由 Patroni 进行动态管理，并在集群中同步与共享。 Patroni 本身的 配置参数 大部分可以通过 patronictl 命令行工具修改。 其余参数（例如，etcd DCS 配置，日志/RestAPI 等配置）则可以通过下面的子任务进行更新。例如，当 etcd 集群成员发生变动时，你可以刷新 Patroni 配置：

./pgsql.yml -l pg-test -t pg_conf                   # 更新 Patroni 配置文件
ansible pg-test -b -a 'systemctl reload patroni'    # 重载 Patroni 服务

您可以在不同层次上覆盖 Patroni 集中管理的默认，例如单独 为实例指定配置参数； 单独为 为用户指定配置参数，或者 为数据库指定配置参数。

克隆集群

有两种克隆集群的方式：使用 备份集群 功能，或者使用 时间点恢复 功能。 前者配置简单，无需备份仓库，但需要可达的复制上游，只能克隆指定集群的最新状态；后者依赖集中式的 备份仓库（例如 Silo），可以克隆到恢复窗口内的任意时间点。

方式 优点 缺点 适用场景
备份集群 无需备份仓库 需要可达上游，只能克隆最新状态 灾备，读写分离，迁移
PITR 可恢复到窗口内任意时点 依赖集中式备份仓库 误操作恢复，数据审计

使用备份集群克隆

备份集群（Standby Cluster）通过流复制从上游集群持续同步数据，是克隆集群最简单的方式。 只需在新集群主库上指定 pg_upstream 参数，即可自动从上游集群拉取数据。

# pg-test 是原始集群
pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
  vars: { pg_cluster: pg-test }

# pg-test2 是 pg-test 的备份集群（克隆）
pg-test2:
  hosts:
    10.10.10.12: { pg_seq: 1, pg_role: primary, pg_upstream: 10.10.10.11 }  # 指定上游
    10.10.10.13: { pg_seq: 2, pg_role: replica }
  vars: { pg_cluster: pg-test2 }

使用以下命令创建备份集群：

脚本
bin/pgsql-add pg-test2    # 创建备份集群，自动从上游 pg-test 克隆数据
剧本
./pgsql.yml -l pg-test2   # 直接使用 Ansible 剧本创建备份集群

备份集群会持续追随上游集群，保持数据同步。您可以随时将其 提升 为独立集群：

示例：提升备份集群为独立集群

通过 配置集群 擦除 standby_cluster 配置段，即可将备份集群提升为独立集群：

$ pg edit-config pg-test2
-standby_cluster:
-  create_replica_methods:
-  - basebackup
-  host: 10.10.10.11
-  port: 5432

Apply these changes? [y/N]: y

提升后，pg-test2 将成为可以独立承载写入请求的独立集群，与原集群 pg-test 分叉。

示例：更改复制上游

如果上游集群发生主从切换，您可以通过 配置集群 更改备份集群的复制上游：

$ pg edit-config pg-test2

 standby_cluster:
   create_replica_methods:
   - basebackup
-  host: 10.10.10.11     # <--- 旧的上游
+  host: 10.10.10.14     # <--- 新的上游
   port: 5432

Apply these changes? [y/N]: y

使用 PITR 克隆

时间点恢复（PITR）允许您将集群恢复到恢复窗口内的任意时间点。 此方式依赖集中式的 备份仓库（如 Silo/S3），但功能更加强大。

要使用 PITR 克隆集群，在配置中添加 pg_pitr 参数指定恢复目标：

# 从 pg-meta 集群的备份克隆一个新集群 pg-meta2
pg-meta2:
  hosts: { 10.10.10.12: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta2
    pg_pitr:
      cluster: pg-meta                    # 从 pg-meta 的备份恢复
      time: '2025-01-10 10:00:00+00'      # 恢复到指定时间点
      archive: false                       # 独立恢复阶段禁用归档
      action: promote                      # 完成重放后提升并启动集群

使用 pgsql-pitr.yml 剧本执行克隆：

剧本
./pgsql-pitr.yml -l pg-meta2    # 使用上面显式声明的 action: promote
命令行
# 也可以通过命令行参数指定 PITR 选项
./pgsql-pitr.yml -l pg-meta2 -e '{"pg_pitr": {"cluster": "pg-meta", "time": "2025-01-10 10:00:00+00", "archive": false, "action": "promote"}}'

PITR 支持多种恢复目标类型：

目标类型 参数示例 说明
时间点 time: "2025-01-10 10:00:00+00" 恢复到指定时间戳
事务 ID xid: "250000" 恢复到指定事务之前/之后
恢复点 name: "before_migration" 恢复到命名恢复点
LSN lsn: "0/4001C80" 恢复到指定 WAL 位置
最新 pg_pitr: {} 恢复到 WAL 归档末尾
PITR 恢复后处理

跨集群恢复完成后，按 克隆善后 处理归档与 stanza。

更多 PITR 的详细用法，请参考 恢复操作；跨集群恢复后的归档与 stanza 处理见 克隆数据库集群。

4.2 - 管理 PostgreSQL 业务用户

用户管理：创建、修改、删除用户，管理角色成员关系，连接池用户配置

快速上手

Pigsty 使用声明式管理方式，首先在 配置清单 中 定义用户，然后使用 bin/pgsql-user <cls> <username> 创建或修改用户。

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_users: [{ name: dbuser_app, password: 'DBUser.App', pgbouncer: true }]  # <--- 在这里定义用户列表！
脚本
bin/pgsql-user <cls> <username>    # 在 <cls> 集群上创建/修改 <username> 用户
剧本
./pgsql-user.yml -l pg-meta -e username=dbuser_app    # 直接使用剧本在 <cls> 集群上创建/修改 <username> 用户
示例
bin/pgsql-user pg-meta dbuser_app    # 在 pg-meta 集群上创建/修改 dbuser_app 用户

关于用户定义参数的完整参考，请查阅 用户配置。角色与权限模型参见 访问控制，认证与凭据管理参见 身份认证。

name 是 pgsql-user.yml 查找用户定义的键，剧本不会执行角色重命名。需要更名时，应先创建新角色，迁移所有权、成员关系与客户端凭据，完成切换和验证后再删除旧角色；不要把“删除后重建”当作无损的重命名操作。

操作 快捷命令 说明
创建用户 bin/pgsql-user <cls> <user> 创建新的业务用户或角色
修改用户 bin/pgsql-user <cls> <user> 修改已存在用户的属性
删除用户 bin/pgsql-user <cls> <user> 依赖感知的破坏性删除（需设置 state: absent）
demo/pgsql-user.cast

创建用户

定义在 pg_users 里面的用户会在 PostgreSQL 集群创建 的时候在 pg_user 任务中自动创建。

要在现有的 PostgreSQL 集群上创建新的业务用户，请将 用户定义 添加到 all.children.<cls>.pg_users，然后执行：

脚本
bin/pgsql-user <cls> <username>   # 创建用户 <username>
剧本
./pgsql-user.yml -l <cls> -e username=<username>   # 直接使用 Ansible 剧本创建用户
示例
bin/pgsql-user pg-meta dbuser_app    # 例子，在 pg-meta 集群中创建 dbuser_app 用户

示例配置：创建名为 dbuser_app 的业务用户

#all.children.pg-meta.vars.pg_users: # 省略上级缩进
  - name: dbuser_app
    password: DBUser.App
    pgbouncer: true
    roles: [dbrole_readwrite]
    comment: application user for myapp

执行效果：在主库上创建用户 dbuser_app，设置密码，授予 dbrole_readwrite 角色权限， 将用户添加到 Pgbouncer 连接池，在每个实例上重载 Pgbouncer 配置使其立即生效。

建议使用剧本创建用户

如果您需要手工创建用户，那么需要自行确保 Pgbouncer 连接池用户列表同步。

修改用户

修改用户与创建用户使用相同的命令，剧本是幂等的。当目标用户已存在时，Pigsty 会修改目标用户的属性使其符合配置。

脚本
bin/pgsql-user <cls> <user>   # 修改用户 <user> 的属性
剧本
./pgsql-user.yml -l <cls> -e username=<user>   # 幂等操作，可重复执行
示例
bin/pgsql-user pg-meta dbuser_app    # 修改 dbuser_app 用户的属性使其符合配置

不可直接修改的属性：用户的 name 是声明式定义的身份键，剧本不会把一个现有角色重命名为另一个角色。应按“创建新角色 → 迁移所有权/权限与客户端 → 验证 → 删除旧角色”的顺序完成更名。

其他属性均可修改，以下是一些常见的修改示例：

修改密码：更新配置中的 password 字段后执行剧本。密码修改时会临时禁用日志记录，避免密码泄露到日志中。

- name: dbuser_app
  password: NewSecretPassword     # 修改密码

修改权限属性：通过配置相应的布尔标志来修改用户权限。

- name: dbuser_app
  superuser: false           # 超级用户（谨慎使用！）
  createdb: true             # 允许创建数据库
  createrole: false          # 允许创建角色
  inherit: true              # 自动继承角色权限
  replication: false         # 允许流复制连接
  bypassrls: false           # 绕过行级安全策略
  connlimit: 50              # 限制连接数，-1 不限制

修改用户有效期：使用 expire_in 设置相对过期时间（N 天后过期），或 expire_at 设置绝对过期日期。expire_in 优先级更高，每次执行剧本时会重新计算，适合需要定期续期的临时用户。

- name: temp_user
  expire_in: 30                   # 30 天后过期（相对时间）

- name: contractor_user
  expire_at: '2024-12-31'         # 指定日期过期（绝对时间）

- name: permanent_user
  expire_at: 'infinity'           # 永不过期

修改角色成员关系：通过 roles 数组配置角色成员关系，支持简单格式和扩展格式。角色成员关系是增量操作，不会移除未声明的现有角色。使用 state: absent 可以显式撤销角色。

- name: dbuser_app
  roles:
    - dbrole_readwrite                      # 简单形式：授予角色
    - { name: dbrole_admin, admin: true }   # 带 ADMIN OPTION（可以将此角色授予其他用户）
    - { name: pg_monitor, set: false }      # PG16+: 不允许 SET ROLE
    - { name: old_role, state: absent }     # 撤销角色成员关系

管理用户参数：通过 parameters 字典配置用户级参数，会生成 ALTER USER ... SET 语句。使用特殊值 DEFAULT 可将参数重置为 PostgreSQL 默认值。

- name: dbuser_analyst
  parameters:
    work_mem: '256MB'
    statement_timeout: '5min'
    search_path: 'analytics,public'
    log_statement: DEFAULT        # 重置为默认值

连接池配置：设置 pgbouncer: true 将用户添加到连接池，可选配置 pool_mode（池化模式：transaction/session/statement）和 pool_connlimit（用户最大连接数）。

- name: dbuser_app
  pgbouncer: true                 # 添加到连接池
  pool_mode: transaction          # 池化模式
  pool_connlimit: 50              # 用户最大连接数

删除用户

删除用户会终止连接、转移对象所有权、撤销授权并执行 DROP ROLE，属于不可逆操作。先确认精确的集群名、用户名、继任所有者与近期备份，再将目标用户的 state 设置为 absent 并执行实际变更。

脚本
bin/pgsql-user <cls> <user>   # 确认后实际删除；配置中必须为 state: absent
剧本
./pgsql-user.yml -l <cls> -e username=<user>   # 直接使用 Ansible 剧本删除用户
示例
bin/pgsql-user pg-meta dbuser_old    # 删除 dbuser_old 用户（配置中已设置 state: absent）

配置示例：

pg_users:
  - name: dbuser_old
    state: absent

删除操作会：在主库调用 pg-drop-role <user> postgres --force，先禁用登录并终止活跃连接，将数据库、表空间以及每个可连接数据库中的对象所有权转移给 postgres，执行 DROP OWNED 清理授权，撤销角色成员关系，最后执行 DROP ROLE。脚本在 /tmp/pg_drop_role_<user>_<timestamp>.log 保存执行前的审计快照。

保护机制：Ansible 任务会跳过 postgres 以及清单中配置的复制、管理和监控用户。直接运行 pg-drop-role 时，脚本只硬编码保护默认名称 postgres、replicator、dbuser_dba、dbuser_monitor；如果改过系统用户名，直接脚本不会自动识别它们，必须额外谨慎。

依赖感知，但不是事务性删除

pg-drop-role 会在 REASSIGN OWNED 失败时跳过对应数据库的 DROP OWNED，但整个跨数据库流程不是一个事务；中途失败可能留下 NOLOGIN、已转移的部分对象或残余依赖。v4.5 的 Ansible 删除任务还使用 ignore_errors，因此剧本最终状态不能代替核验。执行后必须确认角色已消失、继任所有权正确、应用已切换，并检查审计日志。

v4.5 的 pgsql-user.yml 会重载 Pgbouncer，但不会可靠地从 /etc/pgbouncer/userlist.txt 清除已删除角色。删除后应在每个集群实例检查：

sudo -iu postgres psql -AXtwc "SELECT 1 FROM pg_roles WHERE rolname = 'dbuser_old';"
grep -n '^"dbuser_old"[[:space:]]' /etc/pgbouncer/userlist.txt

若仍有精确匹配的 Pgbouncer 条目，应在受控变更中移除该行、重载 Pgbouncer 并验证应用连接；不要用模糊匹配批量删除。

手工删除用户

如果需要手动删除用户，可以直接使用 pg-drop-role 脚本：

# 检查依赖关系（只读操作）
pg-drop-role dbuser_old --check

# 预览删除操作（不实际执行）
pg-drop-role dbuser_old --dry-run -v

# 确认近期备份、精确用户名与继任所有者后，才执行实际删除
pg-drop-role dbuser_old dbuser_new

# 仅当已明确同意终止连接时使用 --force
pg-drop-role dbuser_old dbuser_new --force

常见用例

下面是一些常见的用户配置示例：

创建基本业务用户

- name: dbuser_app
  password: DBUser.App
  pgbouncer: true
  roles: [dbrole_readwrite]
  comment: application user

创建只读用户

- name: dbuser_readonly
  password: DBUser.Readonly
  pgbouncer: true
  roles: [dbrole_readonly]

创建管理员用户（可执行 DDL）

- name: dbuser_admin
  password: DBUser.Admin
  pgbouncer: true
  pool_mode: session
  roles: [dbrole_admin]
  parameters:
    log_statement: 'all'

创建临时用户（30天后过期）

- name: temp_contractor
  password: TempPassword
  expire_in: 30
  roles: [dbrole_readonly]

创建角色（不可登录，用于权限分组）

- name: custom_role
  login: false
  comment: custom role for special permissions

创建带高级角色选项的用户（PG16+）

- name: dbuser_special
  password: DBUser.Special
  pgbouncer: true
  roles:
    - dbrole_readwrite
    - { name: dbrole_admin, admin: true }
    - { name: pg_monitor, set: false }
    - { name: pg_execute_server_program, inherit: false }

查询用户

以下是一些常用的 SQL 查询，用于查看用户信息：

查看所有用户

SELECT rolname, rolsuper, rolinherit, rolcreaterole, rolcreatedb,
       rolcanlogin, rolreplication, rolbypassrls, rolconnlimit, rolvaliduntil
FROM pg_roles WHERE rolname NOT LIKE 'pg_%' ORDER BY rolname;

查看用户的角色成员关系

SELECT r.rolname AS member, g.rolname AS role, m.admin_option, m.set_option, m.inherit_option
FROM pg_auth_members m
JOIN pg_roles r ON r.oid = m.member
JOIN pg_roles g ON g.oid = m.roleid
WHERE r.rolname = 'dbuser_app';

查看用户级参数设置

SELECT rolname, setconfig FROM pg_db_role_setting s
JOIN pg_roles r ON r.oid = s.setrole WHERE s.setdatabase = 0;

查看即将过期的用户

SELECT rolname, rolvaliduntil, rolvaliduntil - CURRENT_TIMESTAMP AS time_remaining
FROM pg_roles WHERE rolvaliduntil IS NOT NULL
  AND rolvaliduntil < CURRENT_TIMESTAMP + INTERVAL '30 days'
ORDER BY rolvaliduntil;

连接池管理

在用户定义中配置的 连接池参数 会在创建/修改用户时应用到 Pgbouncer 连接池中。

设置 pgbouncer: true 的用户会被添加到 /etc/pgbouncer/userlist.txt 文件中。用户级别的连接池参数（pool_mode、pool_connlimit）通过 /etc/pgbouncer/useropts.txt 文件配置。

您可以使用 postgres 操作系统用户，使用 pgb 别名访问 Pgbouncer 管理数据库。更多连接池管理操作，请参考 Pgbouncer 管理。

管理默认用户密码

要修改普通用户的密码， 按照上面 修改用户 的说明，更新配置中的 password 字段并执行剧本即可。 不过修改 默认用户 的密码会稍微复杂一些，因为它们的密码还在多个地方被其他服务引用。

参数 默认值 对应用户 用途
pg_admin_password DBUser.DBA dbuser_dba 管理员用户密码
pg_monitor_password DBUser.Monitor dbuser_monitor 监控用户密码
pg_replication_password DBUser.Replicator replicator 复制用户密码

这三个账号属于 pg_default_roles，不在 pg_users 中。pgsql-user.yml 只查找 pg_users，因此不应通过命令行临时覆盖 pg_users 来轮换默认密码：这既会改变本次剧本看到的业务用户列表，也会把明文密码留在 shell 历史中。

使用以下通用顺序一次轮换一个账号：

  1. 在 pigsty.yml（或实际使用的清单）中持久化新的密码参数，不要把明文密码写进命令行。
  2. 在当前主库上以超级用户打开交互式 psql，使用 \password <username> 修改数据库角色密码；该元命令会交互读取密码。
  3. 使用下面对应的刷新剧本，并核对 -l 限定的集群/节点。
  4. 保留当前管理会话，验证 PostgreSQL 直连、Pgbouncer、复制、Exporter 和 Grafana 数据源，再轮换下一个账号。
# 在目标集群当前主库上，交互修改数据库角色密码
sudo -iu postgres psql -d postgres
\password dbuser_dba       # 或 dbuser_monitor / replicator

随后按账号刷新所有消费者；下列命令中的 <cls> 与 infra 必须替换/限定为实际目标：

# 管理员 dbuser_dba：PG 节点 .pgpass、Pgbouncer、Infra 管理端与 pgAdmin 文件
./pgsql.yml -l <cls> -t pg_pass,pgbouncer_user,pgbouncer_reload -e pg_reload=true
./infra.yml -l infra -t env_pgpass,env_pgscv,env_pgadmin

# 监控用户 dbuser_monitor：PG 节点 .pgpass、Pgbouncer、两个 Exporter 与 Grafana 数据源
./pgsql.yml -l <cls> -t pg_pass,pgbouncer_user,pgbouncer_reload,pg_exporter,pgbouncer_exporter,add_ds -e pg_reload=true
./infra.yml -l infra -t env_pgpass

# 复制用户 replicator：Patroni 配置、PG 节点 .pgpass 与 Infra .pgpass
./pgsql.yml -l <cls> -t pg_conf,pg_pass,patroni_reload -e pg_reload=true
./infra.yml -l infra -t env_pgpass

复制密码在数据库角色与所有 Patroni 节点之间不一致时，新建复制连接会失败，因此应安排维护窗口并快速完成验证。若部署了 VIBE 等会把管理员连接串写入工作区上下文的模块，还应按模块文档重新渲染对应文件。

检查 Infra .pgpass 重复项

v4.5 的 env_pgpass 使用 lineinfile 添加新记录，不会按用户名自动删除旧密码；libpq 又采用第一条匹配记录。刷新后应在每个目标 Infra 节点检查每个系统用户名是否只有一条匹配记录，并通过受控编辑删掉旧项（不要把密码打印到终端或日志）：

awk -F: '$4=="dbuser_dba" || $4=="dbuser_monitor" || $4=="replicator" {print NR, $4}' ~/.pgpass

Patroni REST API 的 patroni_password 不是 PostgreSQL 角色密码。修改清单后，应分别刷新目标 PostgreSQL 集群和 Infra 管理端：

./pgsql.yml -l <cls> -t pg_conf,patroni_reload -e pg_reload=true
./infra.yml -l infra -t env_patroni

执行后用 patronictl 或 pig pg list <cls> 验证认证与集群状态。

4.3 - 管理 PostgreSQL 业务数据库

数据库管理：创建、修改、删除、重建数据库，使用模板克隆数据库

快速上手

Pigsty 使用声明式管理方式，首先在 配置清单 中 定义数据库，然后使用 bin/pgsql-db <cls> <dbname> 创建或修改数据库。

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_databases: [{ name: some_db }]  # <--- 在这里定义数据库列表！
脚本
bin/pgsql-db <cls> <dbname>    # 在 <cls> 集群上创建/修改 <dbname> 数据库
剧本
./pgsql-db.yml -l pg-meta -e dbname=some_db    # 直接使用剧本在 <cls> 集群上创建/修改 <dbname> 数据库
示例
bin/pgsql-db pg-meta some_db    # 在 pg-meta 集群上创建/修改 some_db 数据库

关于数据库定义参数的完整参考，请查阅 数据库配置。数据库访问权限见 访问控制：数据库隔离。

请注意，部分数据库参数仅能在 创建时 指定。修改这些参数需要先删除再创建数据库（使用 state: recreate 重建数据库）。

操作 快捷命令 说明
创建数据库 bin/pgsql-db <cls> <db> 创建新的业务数据库
修改数据库 bin/pgsql-db <cls> <db> 修改已存在数据库的属性
删除数据库 bin/pgsql-db <cls> <db> 删除数据库（需设置 state: absent）
重建数据库 bin/pgsql-db <cls> <db> 先删再建（需设置 state: recreate）
克隆数据库 bin/pgsql-db <cls> <db> 使用模板克隆数据库
demo/pgsql-db.cast

创建数据库

定义在 pg_databases 里面的数据库会在 PostgreSQL 集群创建 的时候在 pg_db 任务中自动创建。

要在现有的 PostgreSQL 集群上创建新的业务数据库，请将 数据库定义 添加到 all.children.<cls>.pg_databases，然后执行：

脚本
bin/pgsql-db <cls> <dbname>   # 创建数据库 <dbname>
剧本
./pgsql-db.yml -l <cls> -e dbname=<dbname>   # 直接使用 Ansible 剧本创建数据库
示例
bin/pgsql-db pg-meta myapp    # 例子，在 pg-meta 集群中创建 myapp 数据库

示例配置：创建名为 myapp 的业务数据库

#all.children.pg-meta.vars.pg_databases: # 省略上级缩进
  - name: myapp
    owner: dbuser_myapp
    schemas: [app]
    extensions:
      - { name: pg_trgm }
      - { name: btree_gin }
    comment: my application database

执行效果：在主库上创建数据库 myapp，设置数据库所有者为 dbuser_myapp，创建 schema app， 启用扩展 pg_trgm 和 btree_gin，数据库将默认添加到 Pgbouncer 连接池，并注册为 Grafana PG 数据源。

建议使用剧本创建数据库

如果您需要手工创建数据库，那么需要自行确保 pgbouncer 连接池 / grafana 数据源同步。

修改数据库

修改数据库与创建数据库使用相同的命令，在没有定义 baseline SQL 的情况下剧本是幂等的。

当目标数据库已存在时，Pigsty 会修改目标数据库的属性使其符合配置。然而，一些属性只能在数据库创建时设置。

脚本
bin/pgsql-db <cls> <db>   # 修改数据库 <db> 的属性
剧本
./pgsql-db.yml -l <cls> -e dbname=<db>   # 幂等操作，可重复执行
示例
bin/pgsql-db pg-meta myapp    # 修改 myapp 数据库的属性使其符合配置

不可修改的属性：以下属性在数据库创建后无法修改，需要使用 state: recreate 重建数据库：

  • name（数据库名称）、template（模板数据库）、strategy（克隆策略）。
  • encoding（字符编码）、locale/lc_collate/lc_ctype（本地化设置）、locale_provider/icu_locale/icu_rules/builtin_locale（本地化提供者设置）

其他属性均可修改，以下是一些常见的修改示例：

修改属主：更新配置中的 owner 字段后执行剧本，会执行 ALTER DATABASE ... OWNER TO 并授予相应权限。

- name: myapp
  owner: dbuser_new_owner     # 修改为新属主

修改连接限制：通过 connlimit 限制数据库的最大连接数。

- name: myapp
  connlimit: 100              # 限制最大 100 个连接

回收公共连接权限：设置 revokeconn: true 会回收 PUBLIC 的 CONNECT 权限，仅允许属主、DBA、监控用户和复制用户连接。

- name: myapp
  owner: dbuser_myapp
  revokeconn: true            # 回收 PUBLIC 的 CONNECT 权限

管理数据库参数：通过 parameters 字典配置数据库级参数，会生成 ALTER DATABASE ... SET 语句。使用特殊值 DEFAULT 可将参数重置为默认值。

- name: myapp
  parameters:
    work_mem: '256MB'
    maintenance_work_mem: '512MB'
    statement_timeout: '30s'
    search_path: DEFAULT      # 重置为默认值

管理模式（Schema）：通过 schemas 数组配置模式，支持简单格式和指定属主的完整格式。使用 state: absent 删除模式（CASCADE）。

- name: myapp
  schemas:
    - app                                   # 简单形式
    - { name: core, owner: dbuser_myapp }   # 指定属主
    - { name: deprecated, state: absent }   # 删除模式

管理扩展（Extension）：通过 extensions 数组配置扩展，支持简单格式和指定 schema/版本的完整格式。使用 state: absent 卸载扩展（CASCADE）。

- name: myapp
  extensions:
    - postgis                                 # 简单形式
    - { name: vector, schema: public }        # 指定 schema
    - { name: pg_trgm, state: absent }        # 卸载扩展
CASCADE 警告

删除模式或卸载扩展使用 CASCADE 选项，会同时删除依赖该模式/扩展的所有对象。请确保理解影响范围后再执行删除操作。

连接池配置：默认情况下所有业务数据库都会添加到 Pgbouncer 连接池。可配置 pgbouncer（是否加入连接池）、pool_mode（池化模式）、pool_size（默认池大小）、pool_reserve（保留连接数）、pool_size_min（最小池大小）、pool_connlimit（最大数据库连接）、pool_auth_user（认证查询用户）等参数。

- name: myapp
  pgbouncer: true              # 是否加入连接池（默认 true）
  pool_mode: transaction       # 池化模式：transaction/session/statement
  pool_size: 50                # 默认池大小
  pool_reserve: 30             # 保留池大小
  pool_size_min: 0             # 最小池大小
  pool_connlimit: 100          # 最大数据库连接
  pool_auth_user: dbuser_meta  # 认证查询使用用户（配合 pgbouncer_auth_query）

自 Pigsty v4.1.0 起，数据库连接池参数统一使用 pool_reserve 与 pool_connlimit，旧别名 pool_size_reserve / pool_max_db_conn 已收敛。

删除数据库

要删除数据库，将其 state 设置为 absent 并执行剧本：

脚本
bin/pgsql-db <cls> <db>   # 删除数据库 <db>（需在配置中设置 state: absent）
剧本
./pgsql-db.yml -l <cls> -e dbname=<db>   # 直接使用 Ansible 剧本删除数据库
示例
bin/pgsql-db pg-meta olddb    # 删除 olddb 数据库（配置中已设置 state: absent）

配置示例：

pg_databases:
  - name: olddb
    state: absent

删除操作会：如果数据库标记为 is_template: true，先执行 ALTER DATABASE ... IS_TEMPLATE false；使用 DROP DATABASE ... WITH (FORCE) 强制删除数据库（PG13+）并终止所有活动连接；从 Pgbouncer 连接池中移除该数据库；从 Grafana 数据源中取消注册。

保护机制：系统数据库 postgres、template0、template1 无法删除。删除操作仅在主库上执行，流复制会自动同步到从库。

危险操作警告

删除数据库是 不可逆 操作，会永久删除该数据库中的所有数据。执行前请确保：已有最新的数据库备份、已确认没有业务在使用该数据库、已通知相关干系人。 Pigsty 不对任何因删除数据库导致的数据丢失承担责任，使用需自担风险。

重建数据库

recreate 状态用于重建数据库，等效于先删除再创建：

脚本
bin/pgsql-db <cls> <db>   # 重建数据库 <db>（需在配置中设置 state: recreate）
剧本
./pgsql-db.yml -l <cls> -e dbname=<db>   # 直接使用 Ansible 剧本重建数据库
示例
bin/pgsql-db pg-meta testdb    # 重建 testdb 数据库（配置中已设置 state: recreate）

配置示例：

pg_databases:
  - name: testdb
    state: recreate
    owner: dbuser_test
    baseline: test_init.sql    # 重建后执行初始化

适用场景：测试环境重置、清空开发数据库、修改不可变属性（编码、本地化等）、恢复数据库到初始状态。

与手动 DROP + CREATE 的区别：单条命令完成，无需两次操作；自动保留 Pgbouncer 和 Grafana 配置；执行后自动加载 baseline 初始化脚本。

克隆数据库

你可以通过 PG 的 template 机制复制一个 PostgreSQL 数据库，在克隆期间，不允许有任何连接到模版数据库的活动连接。

脚本
bin/pgsql-db <cls> <db>   # 克隆数据库 <db>（需在配置中指定 template）
剧本
./pgsql-db.yml -l <cls> -e dbname=<db>   # 直接使用 Ansible 剧本克隆数据库
示例
bin/pgsql-db pg-meta meta_dev    # 克隆创建 meta_dev 数据库（配置中已指定 template: meta）

配置示例：

pg_databases:
  - name: meta                   # 源数据库

  - name: meta_dev
    template: meta               # 以 meta 作为模板
    strategy: FILE_COPY          # PG15+ 克隆策略，PG18 瞬间生效

瞬间克隆（PG18+）：如果使用 PostgreSQL 18 以上版本，Pigsty 默认设置了 file_copy_method，配合 strategy: FILE_COPY 可以在约 200ms 内完成数据库克隆，而不需要复制数据文件。例如克隆一个 30 GB 的数据库，普通克隆用时 18 秒，瞬间克隆仅需 200 毫秒。

手动克隆：确保清理掉所有连接到模版数据库的连接后执行：

SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'meta';
CREATE DATABASE meta_dev TEMPLATE meta STRATEGY FILE_COPY;

局限性与注意事项：瞬间克隆仅在支持的文件系统上可用（xfs，btrfs，zfs，apfs）；不要使用 postgres 数据库作为模版数据库进行克隆；在高并发环境中使用瞬间克隆需要谨慎，需在克隆窗口（200ms）内清理掉所有连接到模版数据库的连接。

连接池管理

在数据库定义中配置的 连接池参数 会在创建/修改数据库时应用到 Pgbouncer 连接池中。

默认情况下所有业务数据库都会添加到 Pgbouncer 连接池（pgbouncer: true）。数据库会被添加到 /etc/pgbouncer/database.txt 文件中，数据库级别的连接池参数（pool_auth_user、pool_mode、pool_size、pool_reserve、pool_size_min、pool_connlimit）通过此文件配置。

您可以使用 postgres 操作系统用户，使用 pgb 别名访问 Pgbouncer 管理数据库。更多连接池管理操作，请参考 Pgbouncer 管理。

4.4 - 管理 Patroni 高可用

使用 Patroni 管理 PG 集群高可用，包括，修改参数，查看状态，主从切换，重启，重做从库等操作。

概览

Pigsty 使用 Patroni 管理 PostgreSQL 集群，它可以用来修改集群配置，查看集群状态，执行主从切换，重启集群，重做从库等操作。

要使用 Patroni 进行管理，您需要有以下两种身份之一：

Patroni 提供了 patronictl 命令行工具用于管理，Pigsty 提供了封装的快捷命令 pg 来简化其操作。

通过 pg 别名使用 patronictl
pg ()
{
    local patroni_conf="/infra/conf/patronictl.yml";
    if [ ! -r ${patroni_conf} ]; then
        patroni_conf="/etc/patroni/patroni.yml";
        if [ ! -r ${patroni_conf} ]; then
            echo "error: patronictl config not found";
            return 1;
        fi;
    fi;
    patronictl -c ${patroni_conf} "$@"
}

可用命令

命令 功能 说明
edit-config 修改配置 交互式修改集群的 Patroni/PostgreSQL 配置
list 查看状态 列出集群成员及其状态
switchover 主动切换 将主库角色切换到指定从库（计划内维护）
failover 故障切换 强制故障转移到指定从库（紧急情况）
restart 重启实例 重启 PostgreSQL 实例以应用需要重启的参数
reload 重载配置 重载 Patroni 配置（无需重启）
reinit 重做从库 重新初始化从库（擦除数据并重新复制）
pause 暂停自动切换 暂停 Patroni 的自动故障转移功能
resume 恢复自动切换 恢复 Patroni 的自动故障转移功能
history 查看历史 显示集群的故障转移历史记录
show-config 显示配置 显示集群当前的配置（只读）
query 执行查询 在集群成员上执行 SQL 查询
topology 查看拓扑 显示集群的复制拓扑结构
version 查看版本 显示 Patroni 版本信息
remove 移除成员 从 DCS 中移除集群成员（危险操作）

修改配置

使用 edit-config 子命令可以交互式修改集群的 Patroni 与 PostgreSQL 配置。该命令会打开一个编辑器，让您修改存储在 DCS（分布式配置存储）中的集群配置，修改后会自动应用到所有集群成员。您可以更改 Patroni 本身的参数（如 ttl、loop_wait、synchronous_mode 等），以及 postgresql.parameters 中的 PostgreSQL 参数。

pg edit-config <cls>                  # 交互式编辑集群配置
pg edit-config <cls> --force          # 跳过确认提示直接应用
pg edit-config <cls> -p <k>=<v>       # 修改 PostgreSQL 参数（--pg 简写）
pg edit-config <cls> -s <k>=<v>       # 修改 Patroni 参数（--set 简写）
demo/pgsql-config.cast

以下是一些常见的配置修改示例：

# 修改 PostgreSQL 参数：慢查询阈值（会询问是否应用）
pg edit-config pg-test -p log_min_duration_statement=1000

# 修改 PostgreSQL 参数并跳过确认
pg edit-config pg-test -p log_min_duration_statement=1000 --force

# 修改多个 PostgreSQL 参数
pg edit-config pg-test -p work_mem=256MB -p maintenance_work_mem=1GB --force

# 修改 Patroni 参数：增大故障检测时间窗口（增大 RTO）
pg edit-config pg-test -s loop_wait=15 -s ttl=60 --force

# 修改 Patroni 参数：启用同步复制模式
pg edit-config pg-test -s synchronous_mode=true --force

# 修改 Patroni 参数：启用严格同步模式（至少一个同步从库才允许写入）
pg edit-config pg-test -s synchronous_mode_strict=true --force

# 修改需要重启的参数（修改后需执行 pg restart）
pg edit-config pg-test -p shared_buffers=4GB --force
pg edit-config pg-test -p shared_preload_libraries='timescaledb, pg_stat_statements' --force
pg edit-config pg-test -p max_connections=200 --force

部分参数修改后需要重启 PostgreSQL 才能生效，您可以使用 pg list 检查集群状态，带 * 标记的实例表示需要重启。然后使用 pg restart 命令重启集群使配置生效。 您也可以使用 curl 或编写程序直接调用 Patroni 提供的 REST API 来修改配置：

# 查看当前配置
curl -s 10.10.10.11:8008/config | jq .

# 通过 API 修改参数（需要认证）
curl -u 'postgres:Patroni.API' \
     -d '{"postgresql":{"parameters": {"log_min_duration_statement":200}}}' \
     -s -X PATCH http://10.10.10.11:8008/config | jq .

查看状态

使用 list 子命令可以查看集群成员及其状态。输出结果会显示每个实例的名称、主机地址、角色、运行状态、时间线和复制延迟等信息。这是日常运维中最常用的命令之一，用于快速了解集群的健康状况。

pg list <cls>                         # 查看指定集群的状态
pg list                               # 列出所有集群（需要在管理节点上执行）
pg list <cls> -e                      # 显示扩展信息（--extended）
pg list <cls> -t                      # 显示时间戳（--timestamp）
pg list <cls> -f json                 # 以 JSON 格式输出（--format）
pg list <cls> -W 5                    # 每 5 秒刷新一次（--watch）

输出示例：

+ Cluster: pg-test (7322261897169354773) -----+----+--------------+
| Member    | Host        | Role    | State   | TL | Lag in MB    |
+-----------+-------------+---------+---------+----+--------------+
| pg-test-1 | 10.10.10.11 | Leader  | running |  1 |              |
| pg-test-2 | 10.10.10.12 | Replica | running |  1 |            0 |
| pg-test-3 | 10.10.10.13 | Replica | running |  1 |            0 |
+-----------+-------------+---------+---------+----+--------------+

输出列说明：Member 是实例名称，由 pg_cluster-pg_seq 组成；Host 是实例所在主机的 IP 地址；Role 表示角色，包括 Leader（主库）、Replica（从库）、Sync Standby（同步从库）、Standby Leader（级联复制的级联主库）等；State 表示运行状态，常见值包括 running（正常运行）、streaming（流复制中）、in archive recovery（归档恢复中）、starting（启动中）、stopped（已停止）等；TL 是时间线编号（Timeline），每次主从切换后会递增；Lag in MB 是复制延迟，以 MB 为单位，主库不显示此值。

如果某个实例需要重启才能应用配置更改，实例名称后会显示 * 标记：

+ Cluster: pg-test (7322261897169354773) -------+----+--------------+
| Member      | Host        | Role    | State   | TL | Lag in MB    |
+-------------+-------------+---------+---------+----+--------------+
| pg-test-1 * | 10.10.10.11 | Leader  | running |  1 |              |
| pg-test-2 * | 10.10.10.12 | Replica | running |  1 |            0 |
+-------------+-------------+---------+---------+----+--------------+

主动切换

使用 switchover 子命令可以执行计划内的主从切换。Switchover 是一种优雅的切换方式：Patroni 会先确保从库完全同步，然后让主库降级为从库，最后提升目标从库为新主库。这个过程通常只需要几秒钟，期间会有短暂的写入不可用。适用于主库所在主机需要维护、升级、或者需要将主库迁移到性能更好的节点等场景。

pg switchover <cls>                   # 交互式切换，会提示选择目标从库
pg switchover <cls> --leader <old>    # 指定当前主库名称
pg switchover <cls> --candidate <new> # 指定目标从库名称
pg switchover <cls> --scheduled <time> # 定时切换，格式如 2024-12-01T03:00
pg switchover <cls> --force           # 跳过确认提示

执行切换前请确保所有从库复制状态正常（状态为 running 或 streaming），复制延迟在可接受范围内，并已通知相关业务方。

# 交互式切换（推荐，会显示当前拓扑并提示选择）
$ pg switchover pg-test
Current cluster topology
+ Cluster: pg-test (7322261897169354773) -----+----+--------------+
| Member    | Host        | Role    | State   | TL | Lag in MB    |
+-----------+-------------+---------+---------+----+--------------+
| pg-test-1 | 10.10.10.11 | Leader  | running |  1 |              |
| pg-test-2 | 10.10.10.12 | Replica | running |  1 |            0 |
| pg-test-3 | 10.10.10.13 | Replica | running |  1 |            0 |
+-----------+-------------+---------+---------+----+--------------+
Primary [pg-test-1]:
Candidate ['pg-test-2', 'pg-test-3'] []: pg-test-2
When should the switchover take place (e.g. 2024-01-01T12:00) [now]:
Are you sure you want to switchover cluster pg-test, demoting current leader pg-test-1? [y/N]: y

# 非交互式切换（指定主库和候选从库）
pg switchover pg-test --leader pg-test-1 --candidate pg-test-2 --force

# 定时切换（在凌晨 3 点执行，适合维护窗口）
pg switchover pg-test --leader pg-test-1 --candidate pg-test-2 --scheduled "2024-12-01T03:00"

切换完成后，请使用 pg list 确认新的集群拓扑。

故障切换

使用 failover 子命令可以执行紧急故障切换。与 switchover 不同，failover 用于主库已经不可用的紧急情况。它会直接提升一个从库为新主库，而不等待原主库的确认。由于从库可能尚未完全同步所有数据，使用 failover 可能会导致少量数据丢失。因此，在非紧急情况下请优先使用 switchover。

pg failover <cls>                     # 交互式故障切换
pg failover <cls> --candidate <new>   # 指定要提升的从库
pg failover <cls> --force             # 跳过确认提示

故障切换示例：

# 交互式故障切换
$ pg failover pg-test
Candidate ['pg-test-2', 'pg-test-3'] []: pg-test-2
Are you sure you want to failover cluster pg-test? [y/N]: y
Successfully failed over to "pg-test-2"

# 非交互式故障切换（紧急情况快速执行）
pg failover pg-test --candidate pg-test-2 --force

Switchover 与 Failover 的区别：Switchover 用于计划内维护，要求原主库在线，执行前会确保数据完全同步，不会丢失数据；Failover 用于紧急故障恢复，原主库可以离线，会直接提升从库，可能丢失未同步的数据。日常维护、升级请使用 Switchover；只有在主库彻底故障无法恢复时才使用 Failover。

当前内置 Patroni 的 failover 子命令没有 --leader 选项；需要校验或指定原主库时应使用计划内的 switchover --leader ...，故障切换只指定候选从库。

重启实例

使用 restart 子命令可以重启 PostgreSQL 实例，通常用于应用需要重启才能生效的参数更改。直接对整个集群执行时，patronictl 会逐个提交所选成员，但不保证“从库优先、主库最后”的顺序。若需要明确的 leader-last 顺序，应先按角色重启从库，再单独重启主库。

pg restart <cls>                      # 重启整个集群的所有实例
pg restart <cls> <member>             # 重启指定实例
pg restart <cls> --role leader        # 仅重启主库
pg restart <cls> --role replica       # 仅重启所有从库
pg restart <cls> --pending            # 仅重启标记为需要重启的实例
pg restart <cls> --scheduled <time>   # 定时重启
pg restart <cls> --timeout <sec>      # 设置重启超时时间（秒）
pg restart <cls> --force              # 跳过确认提示

当您修改了需要重启才能生效的参数（如 shared_buffers、shared_preload_libraries、max_connections、max_worker_processes 等）后，需要使用此命令重启实例。

# 查看哪些实例需要重启（名称后带 * 标记）
$ pg list pg-test
+ Cluster: pg-test (7322261897169354773) -------+----+--------------+
| Member      | Host        | Role    | State   | TL | Lag in MB    |
+-------------+-------------+---------+---------+----+--------------+
| pg-test-1 * | 10.10.10.11 | Leader  | running |  1 |              |
| pg-test-2 * | 10.10.10.12 | Replica | running |  1 |            0 |
+-------------+-------------+---------+---------+----+--------------+

# 重启单个从库实例
pg restart pg-test pg-test-2

# 重启整个集群的所有成员（不承诺 leader-last 顺序）
pg restart pg-test --force

# 仅重启需要重启的实例
pg restart pg-test --pending --force

# 显式按“从库优先、主库最后”执行
pg restart pg-test --role replica --force
pg restart pg-test --role leader --force

# 定时重启（在维护窗口执行）
pg restart pg-test --scheduled "2024-12-01T03:00"

# 设置重启超时时间为 300 秒
pg restart pg-test --timeout 300 --force

重载配置

使用 reload 子命令可以重载 Patroni 配置，无需重启 PostgreSQL。该命令会让 Patroni 重新读取配置文件，并将不需要重启的参数变更应用到 PostgreSQL（通过 pg_reload_conf()）。相比 restart，reload 更加轻量，不会中断数据库连接和正在执行的查询。

pg reload <cls>                       # 重载整个集群的配置
pg reload <cls> <member>              # 重载指定实例的配置
pg reload <cls> --role leader         # 仅重载主库
pg reload <cls> --role replica        # 仅重载所有从库
pg reload <cls> --force               # 跳过确认提示

大多数 PostgreSQL 参数可以通过 reload 生效，只有少数参数（位于 postmaster 上下文的参数，例如 shared_buffers、max_connections、shared_preload_libraries，archive_mode 等）需要重启 PostgreSQL 才能生效。

# 重载整个集群
pg reload pg-test

# 重载单个实例
pg reload pg-test pg-test-1

# 强制重载，跳过确认
pg reload pg-test --force

重做从库

使用 reinit 子命令可以重新初始化从库。该操作会删除从库上的所有数据，再按 Patroni 的 create_replica_methods 顺序重建：Pigsty 默认先尝试 basebackup（即 pg_basebackup）；启用远程 pgBackRest 仓库时还会配置 pgbackrest 作为后备方法。适用于从库数据损坏无法修复、从库落后太多导致 WAL 已被清理无法追赶、或从库配置错误需要重置等场景。

pg reinit <cls> <member>              # 重新初始化指定从库
pg reinit <cls> <member> --force      # 跳过确认提示
pg reinit <cls> <member> --wait       # 等待重建完成后再返回

⚠️ 警告：此操作会删除目标实例的所有数据！只能对从库执行，不能对主库执行。

# 重新初始化从库（会提示确认）
$ pg reinit pg-test pg-test-2
Are you sure you want to reinitialize members pg-test-2? [y/N]: y
Success: reinitialize for member pg-test-2

# 强制重新初始化，跳过确认
pg reinit pg-test pg-test-2 --force

# 重新初始化并等待完成
pg reinit pg-test pg-test-2 --force --wait

重建过程中，可以使用 pg list 查看进度。从库状态会显示为 creating replica：

+ Cluster: pg-test (7322261897169354773) --------------+----+------+
| Member    | Host        | Role    | State            | TL | Lag  |
+-----------+-------------+---------+------------------+----+------+
| pg-test-1 | 10.10.10.11 | Leader  | running          |  2 |      |
| pg-test-2 | 10.10.10.12 | Replica | creating replica |    |    ? |
+-----------+-------------+---------+------------------+----+------+

暂停自动切换

使用 pause 子命令可以暂停 Patroni 的自动故障转移功能。暂停后，即使主库故障，Patroni 也不会自动提升从库为新主库。适用于计划内维护窗口（避免维护操作误触发切换）、调试问题时防止集群状态变化、或需要手动控制切换时机等场景。

pg pause <cls>                        # 暂停自动故障转移
pg pause <cls> --wait                 # 暂停并等待所有成员确认

⚠️ 警告：暂停期间如果主库故障，集群将不会自动恢复！请确保在维护完成后及时使用 resume 恢复。

# 暂停自动切换
$ pg pause pg-test
Success: cluster management is paused

# 查看集群状态（底部会显示 Maintenance mode: on）
$ pg list pg-test
+ Cluster: pg-test (7322261897169354773) -----+----+--------------+
| Member    | Host        | Role    | State   | TL | Lag in MB    |
+-----------+-------------+---------+---------+----+--------------+
| pg-test-1 | 10.10.10.11 | Leader  | running |  1 |              |
| pg-test-2 | 10.10.10.12 | Replica | running |  1 |            0 |
+-----------+-------------+---------+---------+----+--------------+
 Maintenance mode: on

恢复自动切换

使用 resume 子命令可以恢复 Patroni 的自动故障转移功能。维护完成后应立即执行此命令，以确保集群在主库故障时能够自动恢复。

pg resume <cls>                       # 恢复自动故障转移
pg resume <cls> --wait                # 恢复并等待所有成员确认
# 恢复自动切换
$ pg resume pg-test
Success: cluster management is resumed

# 确认已恢复（Maintenance mode 提示消失）
$ pg list pg-test

查看历史

使用 history 子命令可以查看集群的故障转移历史记录。每次主从切换（无论是自动故障转移还是手动切换）都会生成一条新的时间线记录。

pg history <cls>                      # 显示故障转移历史
pg history <cls> -f json              # 以 JSON 格式输出
pg history <cls> -f yaml              # 以 YAML 格式输出
$ pg history pg-test
+----+-----------+------------------------------+---------------------------+
| TL |       LSN | Reason                       | Timestamp                 |
+----+-----------+------------------------------+---------------------------+
|  1 | 0/5000060 | no recovery target specified | 2024-01-15T10:30:00+08:00 |
|  2 | 0/6000000 | switchover to pg-test-2      | 2024-01-20T14:00:00+08:00 |
|  3 | 0/7000028 | failover to pg-test-1        | 2024-01-25T09:15:00+08:00 |
+----+-----------+------------------------------+---------------------------+

输出列说明：TL 是时间线编号（Timeline），每次切换后递增，用于区分不同的主库历史；LSN 是切换时的日志序列号（Log Sequence Number），标识切换发生时的 WAL 位置；Reason 是切换原因，可能是 switchover to xxx（手动切换）、failover to xxx（故障转移）或 no recovery target specified（初始化）；Timestamp 是切换发生的时间戳。

显示配置

使用 show-config 子命令可以查看集群当前存储在 DCS 中的配置。这是一个只读操作，如需修改配置请使用 edit-config 命令。

pg show-config <cls>                  # 显示集群配置
$ pg show-config pg-test
loop_wait: 10
maximum_lag_on_failover: 1048576
postgresql:
  parameters:
    archive_command: pgbackrest --stanza=pg-test archive-push %p
    max_connections: 100
    shared_buffers: 256MB
    log_min_duration_statement: 1000
  use_pg_rewind: true
  use_slots: true
retry_timeout: 10
ttl: 30
synchronous_mode: false

执行查询

使用 query 子命令可以在集群成员上快速执行 SQL 查询。这是一个方便的调试工具，适合快速检查集群状态或执行简单查询。生产环境中的复杂查询建议使用 psql 或应用程序连接。

pg query <cls> -c "<sql>"             # 在主库上执行查询
pg query <cls> -c "<sql>" -m <member> # 在指定实例上执行（--member）
pg query <cls> -c "<sql>" -r leader   # 在主库上执行（--role）
pg query <cls> -c "<sql>" -r replica  # 在所有从库上执行
pg query <cls> -f <file>              # 从文件读取 SQL 执行
pg query <cls> -c "<sql>" -U <user>   # 指定用户名（--username）
pg query <cls> -c "<sql>" -d <db>     # 指定数据库（--dbname）
pg query <cls> -c "<sql>" --format json  # 以 JSON 格式输出
# 查看主库当前连接数
pg query pg-test -c "SELECT count(*) FROM pg_stat_activity"

# 查看 PostgreSQL 版本
pg query pg-test -c "SELECT version()"

# 在所有从库上查看复制状态
pg query pg-test -c "SELECT pg_is_in_recovery(), pg_last_wal_replay_lsn()" -r replica

# 在指定实例上执行
pg query pg-test -c "SELECT pg_is_in_recovery()" -m pg-test-2

# 使用指定用户和数据库
pg query pg-test -c "SELECT current_user, current_database()" -U postgres -d postgres

# 以 JSON 格式输出结果
pg query pg-test -c "SELECT * FROM pg_stat_replication" --format json

查看拓扑

使用 topology 子命令可以以树形结构查看集群的复制拓扑。与 list 相比，topology 更直观地展示了主从复制关系，特别适合级联复制（Cascading Replication）场景。

pg topology <cls>                     # 显示复制拓扑
$ pg topology pg-test
+ Cluster: pg-test (7322261897169354773) -------+----+--------------+
| Member      | Host        | Role    | State   | TL | Lag in MB    |
+-------------+-------------+---------+---------+----+--------------+
| pg-test-1   | 10.10.10.11 | Leader  | running |  1 |              |
| + pg-test-2 | 10.10.10.12 | Replica | running |  1 |            0 |
| + pg-test-3 | 10.10.10.13 | Replica | running |  1 |            0 |
+-------------+-------------+---------+---------+----+--------------+

在级联复制场景中，拓扑图会清晰展示复制链路层级，例如 pg-test-3 从 pg-test-2 复制，而 pg-test-2 从主库 pg-test-1 复制。

查看版本

使用 version 子命令可以查看 patronictl 的版本信息。

pg version                            # 显示 patronictl 版本
$ pg version
patronictl version 4.1.0

移除成员

使用 remove 子命令可以从 DCS（分布式配置存储）中移除集群或成员的元数据。这是一个危险操作，仅移除 DCS 中的元数据，不会停止 PostgreSQL 服务或删除数据文件。错误使用可能导致集群状态不一致。

pg remove <cls>                       # 从 DCS 中移除整个集群的元数据

通常情况下您不需要使用此命令。如需正确移除集群或实例，请使用 Pigsty 提供的 bin/pgsql-rm 脚本或 pgsql-rm.yml 剧本。 只有在以下特殊情况下才考虑使用 remove：DCS 中存在孤立的元数据需要清理（例如节点已物理移除但元数据残留），或集群已通过其他方式销毁需要清理残留信息。

# 移除整个集群的元数据（需要多次确认）
$ pg remove pg-test
Please confirm the cluster name to remove: pg-test
You are about to remove all information in DCS for pg-test, please type: "Yes I am aware": Yes I am aware

4.5 - 管理 PostgreSQL HBA 认证规则

HBA 管理：刷新规则、验证配置、故障排查、PgBouncer HBA

快速上手

Pigsty 使用声明式管理方式，首先在 配置清单 中 定义 HBA 规则，然后使用 bin/pgsql-hba <cls> 刷新规则。

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_hba_rules:                            # <--- 在这里定义 HBA 规则列表！
      - {user: dbuser_app, db: app, addr: intra, auth: pwd, title: 'app access'}
      - {user: dbuser_api, db: all, addr: world, auth: ssl, title: 'api ssl access'}
脚本
bin/pgsql-hba <cls>              # 刷新集群的 PostgreSQL 和 Pgbouncer HBA 规则
bin/pgsql-hba <cls> <ip>...      # 刷新集群中特定实例的 HBA 规则
剧本
./pgsql.yml -l <cls> -t pg_hba,pg_reload                 # 仅刷新 PostgreSQL HBA
./pgsql.yml -l <cls> -t pgbouncer_hba,pgbouncer_reload   # 仅刷新 Pgbouncer HBA
./pgsql.yml -l <cls> -t pg_hba,pg_reload,pgbouncer_hba,pgbouncer_reload  # 同时刷新两者
示例
bin/pgsql-hba pg-meta                      # 刷新 pg-meta 集群的 HBA 规则
bin/pgsql-hba pg-meta 10.10.10.10          # 仅刷新特定实例
bin/pgsql-hba pg-meta 10.10.10.11 10.10.10.12  # 刷新多个实例

关于规则语法，请查阅 HBA 配置；关于认证方法、默认边界与凭据管理，请参考 身份认证。

操作 说明 风险
刷新 HBA 规则 重新渲染配置文件并重载服务 低
验证 HBA 规则 查看当前生效规则，测试连接认证 只读
常见管理场景 添加规则、封禁 IP、角色区分、扩容刷新 低
故障排查 连接被拒绝、认证失败、规则未生效 -
Pgbouncer HBA Pgbouncer 连接池的 HBA 管理 低
demo/pgsql-hba.cast

刷新 HBA 规则

修改 pigsty.yml 中的 HBA 规则后，需要重新渲染配置文件并让服务重载。

脚本
bin/pgsql-hba <cls>              # 刷新整个集群的 HBA 规则（PostgreSQL + Pgbouncer）
bin/pgsql-hba <cls> <ip>...      # 刷新特定实例（多个 IP 空格分隔）
剧本
./pgsql.yml -l <cls> -t pg_hba,pg_reload                 # 仅刷新 PostgreSQL HBA
./pgsql.yml -l <cls> -t pgbouncer_hba,pgbouncer_reload   # 仅刷新 Pgbouncer HBA
./pgsql.yml -l <cls> -t pg_hba,pg_reload,pgbouncer_hba,pgbouncer_reload  # 同时刷新两者
示例
bin/pgsql-hba pg-meta                      # 刷新 pg-meta 集群
bin/pgsql-hba pg-meta 10.10.10.10          # 仅刷新 10.10.10.10 实例

执行效果：根据配置清单中的 HBA 规则定义，渲染 PostgreSQL 和 Pgbouncer 的 HBA 配置文件，然后重载服务使配置生效。

配置文件位置

服务 配置文件路径 模板文件
PostgreSQL /pg/data/pg_hba.conf roles/pgsql/templates/pg_hba.conf
Pgbouncer /etc/pgbouncer/pgb_hba.conf roles/pgsql/templates/pgbouncer.hba
不要直接编辑配置文件

直接编辑 /pg/data/pg_hba.conf 或 /etc/pgbouncer/pgb_hba.conf 虽然可以临时生效，但下次执行 Ansible 剧本时会被覆盖。所有 HBA 规则变更应在 pigsty.yml 中进行，然后执行 bin/pgsql-hba 刷新。

相关 Tags

Tag 说明
pg_hba 渲染 PostgreSQL HBA 配置文件
pg_reload 重载 PostgreSQL 配置（需配合 pg_reload=true）
pgbouncer_hba 渲染 Pgbouncer HBA 配置文件
pgbouncer_reload 重载 Pgbouncer 配置

验证 HBA 规则

刷新 HBA 规则后，可以通过以下方式验证配置是否正确生效。

查看当前生效的 HBA 规则

SQL
-- 查看 PostgreSQL HBA 规则（推荐）
TABLE pg_hba_file_rules;

-- 查看特定数据库的匹配规则
SELECT * FROM pg_hba_file_rules WHERE database @> ARRAY['mydb']::text[];
Bash
# 查看 PostgreSQL HBA 配置文件
cat /pg/data/pg_hba.conf

# 查看 Pgbouncer HBA 配置文件
cat /etc/pgbouncer/pgb_hba.conf

# 查看配置文件头部（确认是否更新）
head -20 /pg/data/pg_hba.conf
测试连接
# 测试特定用户从特定地址的连接
psql -h <host> -p 5432 -U <user> -d <database> -c "SELECT 1"

# 测试通过 Pgbouncer 连接
psql -h <host> -p 6432 -U <user> -d <database> -c "SELECT 1"

检查 HBA 配置语法

# 重载配置（会验证语法）
psql -c "SELECT pg_reload_conf()"

# 如果有语法错误，查看日志
tail -f /pg/log/postgresql-*.log

常见管理场景

添加新的 HBA 规则

在集群配置的 pg_hba_rules 中添加规则，然后执行刷新：

pg-meta:
  vars:
    pg_hba_rules:
      - {user: new_user, db: new_db, addr: '192.168.1.0/24', auth: pwd, title: 'new app access'}
bin/pgsql-hba pg-meta

紧急封禁 IP

当发现恶意 IP 时，可以添加高优先级（order: 0）的拒绝规则：

pg_hba_rules:
  - {user: all, db: all, addr: '10.1.1.100/32', auth: deny, order: 0, title: 'emergency block'}
bin/pgsql-hba pg-meta    # 立即刷新生效

按角色区分规则

为主库和从库配置不同的 HBA 规则，使用 role 参数：

pg_hba_rules:
  # 仅主库允许写入用户
  - {user: writer, db: all, addr: intra, auth: pwd, role: primary, title: 'writer on primary'}
  # 从库允许只读用户
  - {user: reader, db: all, addr: world, auth: ssl, role: replica, title: 'reader on replica'}

执行刷新后，规则会根据实例的 pg_role 自动启用或禁用。

集群扩容后刷新 HBA

当集群新增实例后，使用 addr: cluster 的规则需要刷新才能包含新成员：

./pgsql.yml -l 10.10.10.14       # 扩容新实例
bin/pgsql-hba pg-meta            # 刷新所有实例的 HBA（包含新成员 IP）

主从切换后刷新 HBA

Patroni 故障转移后，实例的 pg_role 可能与配置不一致。如果 HBA 规则使用了 role 过滤，需要更新配置并刷新：

# 更新 pigsty.yml 中的角色定义后刷新
bin/pgsql-hba pg-meta

故障排查

连接被拒绝

症状：FATAL: no pg_hba.conf entry for host "x.x.x.x", user "xxx", database "xxx"

排查步骤：

  1. 检查当前 HBA 规则，确认是否有匹配的规则：
psql -c "TABLE pg_hba_file_rules"

  1. 确认客户端 IP、用户名、数据库是否匹配任何规则

  2. 检查规则顺序（HBA 是首条匹配生效）

  3. 在配置清单中添加对应规则并刷新：

bin/pgsql-hba <cls>

认证失败

症状：FATAL: password authentication failed for user "xxx"

排查步骤：

  1. 确认密码正确
  2. 检查密码加密方式（pg_pwd_enc）与客户端兼容性
  3. 检查用户是否存在：
SELECT * FROM pg_roles WHERE rolname = 'xxx';

HBA 规则未生效

排查步骤：

  1. 确认已执行刷新命令
  2. 检查 Ansible 执行是否成功
  3. 确认 PostgreSQL 已重载：
psql -c "SELECT pg_reload_conf()"
  1. 检查配置文件是否更新：
head -20 /pg/data/pg_hba.conf

规则顺序问题

HBA 是首条匹配生效，如果规则未按预期工作：

  1. 检查规则定义中的 order 值
  2. 使用 psql -c "TABLE pg_hba_file_rules" 查看实际顺序
  3. 调整 order 值（数字越小优先级越高）

Pgbouncer HBA

Pgbouncer 的 HBA 管理与 PostgreSQL 类似，但有一些差异。

配置差异

差异点 PostgreSQL Pgbouncer
配置文件 /pg/data/pg_hba.conf /etc/pgbouncer/pgb_hba.conf
复制连接 支持 db: replication 不支持
本地认证 使用 ident 使用 peer

刷新 Pgbouncer HBA

脚本
bin/pgsql-hba <cls>    # 同时刷新 PostgreSQL 和 Pgbouncer
剧本
./pgsql.yml -l <cls> -t pgbouncer_hba,pgbouncer_reload   # 仅刷新 Pgbouncer HBA
查看
cat /etc/pgbouncer/pgb_hba.conf    # 查看 Pgbouncer HBA 规则

最佳实践

  1. 始终在配置文件中管理：不要直接编辑 pg_hba.conf，所有变更通过 pigsty.yml
  2. 测试环境先验证：HBA 变更可能导致连接问题，先在测试环境验证
  3. 使用 order 控制优先级：黑名单规则使用 order: 0，确保优先匹配
  4. 及时刷新：添加/删除实例、主从切换后及时刷新 HBA
  5. 最小权限原则：只开放必要的访问，避免使用 addr: world + auth: trust
  6. 监控认证失败：关注 pg_stat_activity 中的认证失败记录
  7. 备份配置：重要变更前备份 pigsty.yml

相关文档

4.6 - Pgbouncer 连接池管理

使用 Pgbouncer 管理连接池，包括暂停、恢复、禁用、启用、重连、终止、重载等操作。

概览

Pigsty 使用 Pgbouncer 作为 PostgreSQL 的连接池中间件，默认监听 6432 端口，代理访问本机 5432 端口上的 PostgreSQL 实例。

这是一个 可选组件，如果您并没有海量连接，也不需要事务池化与查询监控指标，可以关闭连接池，直连数据库，或者保留但不使用。

用户与数据库管理

Pgbouncer 中的用户和数据库由 Pigsty 自动管理，并在 创建数据库 与 创建用户 时自动应用 数据库配置 与 用户配置。

数据库管理：在 pg_databases 中定义的数据库，默认会自动添加到 Pgbouncer。设置 pgbouncer: false 可以排除特定数据库。

pg_databases:
  - name: mydb                # 默认加入连接池
    pool_auth_user: dbuser_meta # 可选，认证查询用户（配合 pgbouncer_auth_query）
    pool_mode: transaction    # 数据库级池化模式
    pool_size: 50             # 默认池大小
    pool_reserve: 30          # 保留池大小
    pool_size_min: 0          # 最小池大小
    pool_connlimit: 100       # 最大数据库连接数
  - name: internal
    pgbouncer: false          # 不加入连接池

用户管理：在 pg_users 中定义的用户，需要显式设置 pgbouncer: true 才会加入连接池用户列表。

pg_users:
  - name: dbuser_app
    password: DBUser.App
    pgbouncer: true           # 加入连接池用户列表
    pool_mode: transaction    # 用户级池化模式
    pool_connlimit: 50        # 用户级最大连接数

自 Pigsty v4.1.0 起，数据库连接池参数统一使用 pool_reserve 与 pool_connlimit，旧别名 pool_size_reserve / pool_max_db_conn 已收敛。

服务管理

在 Pigsty 中，PostgreSQL 集群的 Primary 服务 与 Replica 服务默认指向 Pgbouncer 6432 端口， 如果您想要让这两个服务绕过连接池直接访问 PostgreSQL 实例，可以定制 pg_services，或将 pg_default_service_dest 设置为 postgres。

配置管理

Pgbouncer 的配置文件位于 /etc/pgbouncer/ 目录，由 Pigsty 统一生成与管理：

文件 说明
pgbouncer.ini 主配置文件，连接池级别参数
database.txt 数据库列表，数据库级别参数
userlist.txt 用户密码列表
useropts.txt 用户级别的连接池参数
pgb_hba.conf HBA 访问控制规则

Pigsty 会自动管理 database.txt 和 userlist.txt，在 创建数据库 或 创建用户 时自动更新这些文件。

您也可以手动编辑配置文件后执行 RELOAD 使其生效：

# 编辑配置
$ vim /etc/pgbouncer/pgbouncer.ini

# 重载生效：通过 systemctl
$ sudo systemctl reload pgbouncer

# 重载生效，本身是 pg_dbsu / postgres 用户
$ pgb -c "RELOAD;"

连接池管理

Pgbouncer 使用和 PostgreSQL 相同的 dbsu 运行，默认为 postgres 操作系统用户。Pigsty 提供了快捷命令 pgb 来简化管理操作：

alias pgb='psql -p6432 -dpgbouncer'

您可以在数据库节点上使用 pgb 命令连接到 Pgbouncer 管理控制台，执行管理命令和监控查询。

$ pgb
pgbouncer=# SHOW POOLS;
pgbouncer=# SHOW CLIENTS;
pgbouncer=# SHOW SERVERS;
命令 功能 说明
PAUSE 暂停 暂停数据库连接，等待事务完成后断开服务端连接
RESUME 恢复 恢复被 PAUSE/KILL/SUSPEND 暂停的数据库
DISABLE 禁用 拒绝指定数据库的新客户端连接
ENABLE 启用 允许指定数据库的新客户端连接
RECONNECT 重连 优雅地关闭并重建服务端连接
KILL 终止 立即断开指定数据库的所有客户端和服务端连接
KILL_CLIENT 杀客户端 终止指定的客户端连接
SUSPEND 挂起 刷新缓冲区并停止监听，用于在线重启
SHUTDOWN 关闭 关闭 Pgbouncer 进程
RELOAD 重载 重新加载配置文件
WAIT_CLOSE 等待关闭 等待 RECONNECT/RELOAD 后的服务端连接释放
监控命令 监控 查看连接池状态、客户端、服务端等信息

PAUSE

使用 PAUSE 命令暂停数据库连接。Pgbouncer 会根据池化模式等待活动事务/会话完成后断开服务端连接。新的客户端请求会被阻塞直到执行 RESUME。

PAUSE [db];           -- 暂停指定数据库，不指定则暂停所有数据库

典型使用场景：

  • 在线切换后端数据库（如主从切换后更新连接目标）
  • 执行需要断开所有连接的维护操作
  • 配合 SUSPEND 实现 Pgbouncer 在线重启
$ pgb -c "PAUSE mydb;"        # 暂停 mydb 数据库
$ pgb -c "PAUSE;"             # 暂停所有数据库

暂停后，SHOW DATABASES 会显示 paused 状态：

pgbouncer=# SHOW DATABASES;
   name   |   host    | port | database | ... | paused | disabled
----------+-----------+------+----------+-----+--------+----------
 mydb     | /var/run  | 5432 | mydb     | ... |      1 |        0

RESUME

使用 RESUME 命令恢复被 PAUSE、KILL 或 SUSPEND 暂停的数据库，允许新的连接请求并恢复正常服务。

RESUME [db];          -- 恢复指定数据库，不指定则恢复所有数据库
$ pgb -c "RESUME mydb;"       # 恢复 mydb 数据库
$ pgb -c "RESUME;"            # 恢复所有数据库

DISABLE

使用 DISABLE 命令禁用指定数据库，拒绝所有新的客户端连接请求。已存在的连接不受影响。

DISABLE db;           -- 禁用指定数据库（必须指定数据库名）

典型使用场景：

  • 临时下线某个数据库进行维护
  • 阻止新连接以便安全地进行数据库迁移
  • 逐步下线即将删除的数据库
$ pgb -c "DISABLE mydb;"      # 禁用 mydb，新连接被拒绝

ENABLE

使用 ENABLE 命令启用之前被 DISABLE 禁用的数据库，重新接受新的客户端连接。

ENABLE db;            -- 启用指定数据库（必须指定数据库名）
$ pgb -c "ENABLE mydb;"       # 启用 mydb，允许新连接

RECONNECT

使用 RECONNECT 命令优雅地重建服务端连接。Pgbouncer 会在连接释放回池后关闭它们，并在需要时建立新连接。

RECONNECT [db];       -- 重建指定数据库的服务端连接，不指定则重建所有

典型使用场景：

  • 后端数据库 IP 地址变更后刷新连接
  • 主从切换后重新路由流量
  • DNS 更新后重建连接
$ pgb -c "RECONNECT mydb;"    # 重建 mydb 的服务端连接
$ pgb -c "RECONNECT;"         # 重建所有服务端连接

执行 RECONNECT 后，可以使用 WAIT_CLOSE 等待旧连接完全释放。

KILL

使用 KILL 命令立即断开指定数据库的所有客户端和服务端连接。与 PAUSE 不同，KILL 不等待事务完成，直接强制断开。

KILL [db];            -- 终止指定数据库的所有连接，不指定则终止所有（admin 除外）
$ pgb -c "KILL mydb;"         # 强制断开 mydb 的所有连接
$ pgb -c "KILL;"              # 强制断开所有数据库的连接（admin 除外）

执行 KILL 后，新连接会被阻塞直到执行 RESUME。

KILL_CLIENT

使用 KILL_CLIENT 命令终止指定的客户端连接。客户端 ID 可以从 SHOW CLIENTS 输出中获取。

KILL_CLIENT id;       -- 终止指定 ID 的客户端连接
# 查看客户端连接
$ pgb -c "SHOW CLIENTS;"

# 终止特定客户端（假设 ptr 列显示的 ID 为 0x1234567890）
$ pgb -c "KILL_CLIENT 0x1234567890;"

SUSPEND

使用 SUSPEND 命令挂起 Pgbouncer。Pgbouncer 会刷新所有 socket 缓冲区并停止监听数据，直到执行 RESUME。

SUSPEND;              -- 挂起 Pgbouncer

SUSPEND 主要用于实现 Pgbouncer 的在线重启（零停机升级）：

# 1. 挂起当前 Pgbouncer
$ pgb -c "SUSPEND;"

# 2. 启动新的 Pgbouncer 进程（使用 -R 选项接管 socket）
$ pgbouncer -R /etc/pgbouncer/pgbouncer.ini

# 3. 新进程接管后，旧进程自动退出

SHUTDOWN

使用 SHUTDOWN 命令关闭 Pgbouncer 进程。支持多种关闭模式：

SHUTDOWN;                      -- 立即关闭
SHUTDOWN WAIT_FOR_SERVERS;     -- 等待服务端连接释放后关闭
SHUTDOWN WAIT_FOR_CLIENTS;     -- 等待客户端断开后关闭（零停机滚动重启）
模式 说明
SHUTDOWN 立即关闭 Pgbouncer 进程
WAIT_FOR_SERVERS 停止接受新连接，等待服务端连接释放后退出
WAIT_FOR_CLIENTS 停止接受新连接，等待所有客户端断开后退出，适用于滚动重启 
$ pgb -c "SHUTDOWN WAIT_FOR_CLIENTS;"   # 优雅关闭，等待客户端断开

RELOAD

使用 RELOAD 命令重新加载 Pgbouncer 配置文件。可以动态更新大部分配置参数，无需重启进程。

RELOAD;               -- 重载配置文件
$ pgb -c "RELOAD;"              # 通过管理控制台重载
$ systemctl reload pgbouncer    # 通过 systemd 重载
$ kill -SIGHUP $(cat /run/postgresql/pgbouncer.pid)  # 通过信号重载

Pigsty 提供了重载 Pgbouncer 配置的剧本任务：

./pgsql.yml -l <cls> -t pgbouncer_reload    # 重载集群的 Pgbouncer 配置

WAIT_CLOSE

使用 WAIT_CLOSE 命令等待服务端连接完成关闭。通常在 RECONNECT 或 RELOAD 后使用，确保旧连接已全部释放。

WAIT_CLOSE [db];      -- 等待指定数据库的服务端连接关闭，不指定则等待所有
# 完整的连接重建流程
$ pgb -c "RECONNECT mydb;"
$ pgb -c "WAIT_CLOSE mydb;"    # 等待旧连接释放

监控命令

Pgbouncer 提供了丰富的 SHOW 命令用于监控连接池状态：

命令 说明
SHOW HELP 显示可用命令帮助
SHOW DATABASES 显示数据库配置和状态
SHOW POOLS 显示连接池统计信息
SHOW CLIENTS 显示客户端连接列表
SHOW SERVERS 显示服务端连接列表
SHOW USERS 显示用户配置
SHOW STATS 显示统计信息（请求数、字节数等）
SHOW STATS_TOTALS 显示累计统计信息
SHOW STATS_AVERAGES 显示平均统计信息
SHOW CONFIG 显示当前配置参数
SHOW MEM 显示内存使用情况
SHOW DNS_HOSTS 显示 DNS 缓存的主机名
SHOW DNS_ZONES 显示 DNS 缓存的区域
SHOW SOCKETS 显示打开的 socket 信息
SHOW ACTIVE_SOCKETS 显示活动的 socket
SHOW LISTS 显示内部列表计数
SHOW FDS 显示文件描述符使用情况
SHOW STATE 显示 Pgbouncer 运行状态
SHOW VERSION 显示 Pgbouncer 版本

常用监控示例：

# 查看连接池状态
$ pgb -c "SHOW POOLS;"

# 查看客户端连接
$ pgb -c "SHOW CLIENTS;"

# 查看服务端连接
$ pgb -c "SHOW SERVERS;"

# 查看统计信息
$ pgb -c "SHOW STATS;"

# 查看数据库状态
$ pgb -c "SHOW DATABASES;"

更多监控命令的详细说明，请参考 Pgbouncer 官方文档。

Unix 信号

Pgbouncer 支持通过 Unix 信号进行控制，这在无法连接管理控制台时非常有用：

信号 等效命令 说明
SIGHUP RELOAD 重载配置文件
SIGTERM SHUTDOWN WAIT_FOR_CLIENTS 优雅关闭，等待客户端断开
SIGINT SHUTDOWN WAIT_FOR_SERVERS 优雅关闭，等待服务端释放
SIGQUIT SHUTDOWN 立即关闭
SIGUSR1 PAUSE 暂停所有数据库
SIGUSR2 RESUME 恢复所有数据库 
# 通过信号重载配置
$ kill -SIGHUP $(cat /run/postgresql/pgbouncer.pid)

# 通过信号优雅关闭
$ kill -SIGTERM $(cat /run/postgresql/pgbouncer.pid)

# 通过信号暂停
$ kill -SIGUSR1 $(cat /run/postgresql/pgbouncer.pid)

# 通过信号恢复
$ kill -SIGUSR2 $(cat /run/postgresql/pgbouncer.pid)

流量切换

Pigsty 管理的数据库路由位于 /etc/pgbouncer/database.txt。要将某个数据库的 Pgbouncer 流量切换到其他节点，需要修改该文件、重载配置，再让已有服务端连接排空并重建：

# 1. 仅把 mydb 的后端目标改为 10.10.10.12
$ sed -i -E '/^mydb[[:space:]]*=/ s#host=[^[:space:]]+#host=10.10.10.12#' /etc/pgbouncer/database.txt

# 2. 重载配置
$ pgb -c "RELOAD;"

# 3. 重建该数据库的连接并等待旧连接释放
$ pgb -c "RECONNECT mydb;"
$ pgb -c "WAIT_CLOSE mydb;"

当前源码附带的 pgb-route 函数只修改 /etc/pgbouncer/pgbouncer.ini；该文件仅 include database.txt，并不包含 Pigsty 生成的逐库 host= 路由。因此它不会改变托管数据库的后端目标，请不要用它替代上述操作。

4.7 - 管理 PostgreSQL 组件服务

使用 systemctl 管理 PostgreSQL 集群中的各个组件服务：启动、停止、重启、重载与状态检查。

概述

Pigsty 的 PGSQL 模块由多个组件构成，每个组件都以 systemd 服务的形式运行在节点上。（pgbackrest 除外）

了解这些组件及其管理方式，对于维护生产环境中的 PostgreSQL 集群非常重要。

组件 端口 服务名 说明
Patroni 8008 patroni 高可用管理器，负责 PostgreSQL 的生命周期管理
PostgreSQL 5432 postgres 占位服务，默认不使用，应急使用
Pgbouncer 6432 pgbouncer 连接池中间件，业务流量入口
PgBackRest - - pgBackRest 没有守护服务
HAProxy 543x haproxy 负载均衡器，暴露数据库服务
pg_exporter 9630 pg_exporter PostgreSQL 监控指标导出器
pgbouncer_exporter 9631 pgbouncer_exporter Pgbouncer 监控指标导出器
vip-manager - vip-manager 可选，管理 L2 VIP 地址漂移
重要提示

不要直接使用 systemctl 管理 PostgreSQL 服务。PostgreSQL 由 Patroni 托管，应通过 patronictl 命令进行管理。 直接操作 PostgreSQL 可能导致 Patroni 状态不一致，触发意外的故障转移。postgres 服务是 Patroni 服务失效时的应急逃生窗口。

命令速查

操作 命令
启动服务 systemctl start <service>
停止服务 systemctl stop <service>
重启服务 systemctl restart <service>
重载配置 systemctl reload <service>
查看状态 systemctl status <service>
查看日志 journalctl -u <service> -f
开机启动 systemctl enable <service>
禁用启动 systemctl disable <service>

常用组件服务名：patroni、pgbouncer、haproxy、pg_exporter、pgbouncer_exporter、vip-manager

Patroni

Patroni 是 PostgreSQL 的高可用管理器，负责 PostgreSQL 的启动、停止、故障检测与自动故障转移。 它是 PGSQL 模块的核心组件，PostgreSQL 进程由 Patroni 托管，不应直接通过 systemctl 管理 postgres 服务。

启动 Patroni

systemctl start patroni     # 启动 Patroni（同时启动 PostgreSQL）

启动 Patroni 后，它会自动拉起 PostgreSQL 进程。首次启动时，Patroni 会根据角色决定行为：

  • 主库：初始化或恢复数据目录
  • 从库：从主库克隆数据并建立复制

停止 Patroni

systemctl stop patroni      # 停止 Patroni（同时停止 PostgreSQL）

停止 Patroni 时，它会优雅地关闭 PostgreSQL 进程。注意：如果这是主库，且未暂停自动切换，可能触发故障转移。

重启 Patroni

systemctl restart patroni   # 重启 Patroni（同时重启 PostgreSQL）

重启会导致短暂的服务中断。对于生产环境，建议使用 pg restart 命令进行滚动重启。

重载 Patroni

systemctl reload patroni    # 重载 Patroni 配置

重载会让 Patroni 重新读取配置文件，并将可热加载的参数应用到 PostgreSQL。

查看状态与日志

systemctl status patroni    # 查看 Patroni 服务状态
journalctl -u patroni -f    # 实时查看 Patroni 日志
journalctl -u patroni -n 100 --no-pager  # 查看最近 100 行日志

配置文件位置：/etc/patroni/patroni.yml

最佳实践：使用 patronictl 而非 systemctl 管理 PostgreSQL 集群。

Pgbouncer

Pgbouncer 是轻量级的 PostgreSQL 连接池中间件。 业务流量通常通过 Pgbouncer（6432 端口）而非直接连接 PostgreSQL（5432 端口），以实现连接复用和保护数据库。

启动 Pgbouncer

systemctl start pgbouncer

停止 Pgbouncer

systemctl stop pgbouncer

注意：停止 Pgbouncer 会中断所有通过连接池的业务连接。

重启 Pgbouncer

systemctl restart pgbouncer

重启会断开所有现有连接。如果只是配置变更，建议使用 reload。

重载 Pgbouncer

systemctl reload pgbouncer

重载会重新读取配置文件（用户列表、连接池参数等），不会断开现有连接。

查看状态与日志

systemctl status pgbouncer
journalctl -u pgbouncer -f

配置文件位置：

  • 主配置：/etc/pgbouncer/pgbouncer.ini
  • HBA 规则：/etc/pgbouncer/pgb_hba.conf
  • 用户列表：/etc/pgbouncer/userlist.txt
  • 数据库列表：/etc/pgbouncer/database.txt

管理控制台

psql -p 6432 -U postgres -d pgbouncer  # 连接到 Pgbouncer 管理控制台

常用管理命令：

SHOW POOLS;      -- 查看连接池状态
SHOW CLIENTS;    -- 查看客户端连接
SHOW SERVERS;    -- 查看后端服务器连接
SHOW STATS;      -- 查看统计信息
RELOAD;          -- 重载配置
PAUSE;           -- 暂停所有连接池
RESUME;          -- 恢复所有连接池

HAProxy

HAProxy 是高性能的负载均衡器，负责将流量分发到正确的 PostgreSQL 实例。 Pigsty 使用 HAProxy 暴露 服务，根据角色（主库/从库）和健康状态进行流量调度。

启动 HAProxy

systemctl start haproxy

停止 HAProxy

systemctl stop haproxy

注意：停止 HAProxy 会中断所有通过负载均衡器的连接。

重启 HAProxy

systemctl restart haproxy

重载 HAProxy

systemctl reload haproxy

HAProxy 支持优雅重载，不会断开现有连接。配置变更后推荐使用 reload。

查看状态与日志

systemctl status haproxy
journalctl -u haproxy -f

配置文件位置：主配置为 /etc/haproxy/haproxy.cfg，Pigsty 生成的服务片段位于 /etc/haproxy/conf.d/。

管理界面

HAProxy 提供 Web 管理界面，默认监听在 9101 端口：

http://<node_ip>:9101/haproxy

默认认证：用户名 admin，密码由 haproxy_admin_password 配置。

pg_exporter

pg_exporter 是 PostgreSQL 的 Prometheus 监控指标导出器，负责采集数据库性能指标。

启动 pg_exporter

systemctl start pg_exporter

停止 pg_exporter

systemctl stop pg_exporter

停止后，Prometheus 将无法采集该实例的 PostgreSQL 监控指标。

重启 pg_exporter

systemctl restart pg_exporter

查看状态与日志

systemctl status pg_exporter
journalctl -u pg_exporter -f

配置文件位置：/etc/pg_exporter.yml

验证指标采集

curl -s localhost:9630/metrics | head -20

pgbouncer_exporter

pgbouncer_exporter 是 Pgbouncer 的 Prometheus 监控指标导出器。

启动/停止/重启

systemctl start pgbouncer_exporter
systemctl stop pgbouncer_exporter
systemctl restart pgbouncer_exporter

查看状态与日志

systemctl status pgbouncer_exporter
journalctl -u pgbouncer_exporter -f

验证指标采集

curl -s localhost:9631/metrics | head -20

vip-manager

vip-manager 是可选组件，用于管理 L2 VIP 地址漂移。 当启用 pg_vip_enabled 时，vip-manager 会将 VIP 绑定到当前主库节点。

启动 vip-manager

systemctl start vip-manager

停止 vip-manager

systemctl stop vip-manager

停止后，VIP 地址会从当前节点释放。

重启 vip-manager

systemctl restart vip-manager

查看状态与日志

systemctl status vip-manager
journalctl -u vip-manager -f

配置文件位置：/etc/default/vip-manager

验证 VIP 绑定

ip addr show           # 查看网络接口，检查 VIP 是否绑定
pg list <cls>          # 确认主库位置

启动顺序与依赖

PGSQL 模块组件的推荐启动顺序：

1. patroni          # 首先启动 Patroni（会自动启动 PostgreSQL）
2. pgbouncer        # 然后启动连接池
3. haproxy          # 启动负载均衡器
4. pg_exporter      # 启动监控导出器
5. pgbouncer_exporter
6. vip-manager      # 最后启动 VIP 管理器（如果启用）

停止顺序应相反。Pigsty 剧本会自动处理这些依赖关系。

批量启动所有服务

systemctl start patroni pgbouncer haproxy pg_exporter pgbouncer_exporter

批量停止所有服务

systemctl stop pgbouncer_exporter pg_exporter haproxy pgbouncer patroni

常见故障排查

服务启动失败

systemctl status <service>        # 查看服务状态
journalctl -u <service> -n 50     # 查看最近日志
journalctl -u <service> --since "5 min ago"  # 查看最近 5 分钟日志

Patroni 无法启动

现象 可能原因 解决方案
无法连接 etcd etcd 集群不可用 检查 etcd 服务状态
数据目录权限错误 文件所有权不是 postgres chown -R postgres:postgres /pg/data
端口被占用 PostgreSQL 残留进程 pg_ctl stop -D /pg/data 或 kill

Pgbouncer 无法启动

现象 可能原因 解决方案
配置文件语法错误 INI 格式错误 检查 /etc/pgbouncer/pgbouncer.ini
端口被占用 6432 端口已被使用 lsof -i :6432
userlist.txt 权限 文件权限不正确 chmod 600 /etc/pgbouncer/userlist.txt

HAProxy 无法启动

现象 可能原因 解决方案
配置文件语法错误 主配置或服务片段格式错误 haproxy -Ws -f /etc/haproxy/haproxy.cfg -f /etc/haproxy/conf.d -c -q
端口被占用 服务端口冲突 lsof -i :5433

相关文档

4.8 - 管理 PostgreSQL 定时任务

配置 Crontab 定期调度 PostgreSQL 备份任务，执行备份 / Vacuum Freeze / Analyze 任务，以及处理表膨胀

Pigsty 使用 crontab 来管理定时任务，用于执行例行备份，冻结老化事务，重整膨胀表索引等维护工作。

速查手册

操作 快捷命令 说明
配置定时任务 ./pgsql.yml -t pg_crontab -l <cls> 应用 pg_crontab 配置
查看定时任务 crontab -l 以 postgres 用户查看
物理备份 pg-backup [full|diff|incr] 使用 pgBackRest 执行备份
事务冻结 pg-vacuum [database...] 冻结老化事务，预防 XID 回卷
膨胀治理 pg-repack [database...] 在线重整膨胀的表与索引

其他管理任务，请参考：备份管理，监控系统，高可用管理。

配置定时任务

使用 pg_crontab 参数配置 PostgreSQL 数据库超级用户（pg_dbsu，默认 postgres）的定时任务。

下面 pg-meta 集群配置了每天凌晨1点进行全量备份的定时任务，pg-test 配置了每周一全量备份，其余日期增量备份的定时任务。

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_crontab:
      - '00 01 * * * /pg/bin/pg-backup'
pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
  vars:
    pg_cluster: pg-test
    pg_crontab:
      - '00 01 * * 1            /pg/bin/pg-backup full'
      - '00 01 * * 2,3,4,5,6,7  /pg/bin/pg-backup'

推荐的维护计划

pg_crontab:
  - '00 01 * * * /pg/bin/pg-backup full'    # 每天凌晨1点全量备份
  - '00 03 * * 0 /pg/bin/pg-vacuum'         # 每周日凌晨3点执行 vacuum freeze
  - '00 04 * * 1 /pg/bin/pg-repack'         # 每周一凌晨4点执行 repack
任务 频率 时机 说明
pg-backup 每天 凌晨 全量或增量备份，视业务需求而定
pg-vacuum 每周一次 周日凌晨 冻结老化事务，预防 XID 回卷
pg-repack 每周/每月 业务低峰期 重整膨胀表索引，回收空间
仅在主库执行

pg-backup、pg-vacuum、pg-repack 脚本会自动检测当前节点角色，只有主库才会实际执行，从库会直接退出。

因此可以安全地在所有节点配置相同的定时任务，故障切换后新主库会自动继续执行维护任务。

应用定时任务

定时任务会在 pgsql.yml 剧本执行时（pg_crontab 任务）自动写入对应操作系统发行版的默认位置：

  • EL（RHEL/Rocky/Alma）：/var/spool/cron/postgres
  • Debian/Ubuntu：/var/spool/cron/crontabs/postgres
剧本
./pgsql.yml -l pg-meta -t pg_crontab     # 应用 pg_crontab 配置到指定集群
./pgsql.yml -l 10.10.10.10 -t pg_crontab # 仅针对特定主机
手工
# 以 postgres 用户编辑定时任务
sudo -u postgres crontab -e

# 或直接编辑 crontab 文件
sudo vi /var/spool/cron/postgres           # EL 系列
sudo vi /var/spool/cron/crontabs/postgres  # Debian/Ubuntu

每次执行剧本都会 全量覆盖刷新 定时任务配置。

查看定时任务

使用 pg_dbsu 操作系统用户执行以下命令查看定时任务：

crontab -l

# Pigsty Managed Crontab for postgres
SHELL=/bin/bash
PATH=/usr/pgsql/bin:/pg/bin:/usr/local/bin:/usr/bin:/usr/sbin:/bin:/sbin
MAILTO=""
00 01 * * * /pg/bin/pg-backup

如果您不熟悉 Crontab 的语法，可以参考 Crontab Guru 的解释。

pg-backup

pg-backup 是 Pigsty 提供的物理备份脚本，基于 pgBackRest 实现，支持全量、差异、增量三种备份模式。

基本用法

pg-backup                # 执行增量备份（默认），如果没有全量备份则自动执行全量备份
pg-backup full           # 执行全量备份
pg-backup diff           # 执行差异备份（基于最近的全量备份）
pg-backup incr           # 执行增量备份（基于最近的任意备份）

备份类型说明

类型 参数 说明
全量备份 full 完整备份所有数据，恢复时只需要该备份
差异备份 diff 备份自上次全量备份以来的变更，恢复时需要全量+差异
增量备份 incr 备份自上次任意备份以来的变更，恢复时需要完整链路

执行条件

  • 脚本必须在 主库 上以 postgres 用户身份运行
  • 脚本会自动检测当前节点角色，从库执行时会直接退出（exit 1）
  • 从 /etc/pgbackrest/pgbackrest.conf 中自动获取 stanza 名称

常用定时任务配置

每日全量
pg_crontab:
  - '00 01 * * * /pg/bin/pg-backup full'    # 每天凌晨1点全量备份
周全量+日增量
pg_crontab:
  - '00 01 * * 1            /pg/bin/pg-backup full'  # 周一全量备份
  - '00 01 * * 2,3,4,5,6,7  /pg/bin/pg-backup'       # 其他日期增量备份
周全量+日差异
pg_crontab:
  - '00 01 * * 1            /pg/bin/pg-backup full'  # 周一全量备份
  - '00 01 * * 2,3,4,5,6,7  /pg/bin/pg-backup diff'  # 其他日期差异备份

更多备份恢复操作，请参考 备份管理 章节。

pg-vacuum

pg-vacuum 是 Pigsty 提供的事务冻结脚本，用于执行 VACUUM FREEZE 操作，防止事务 ID（XID）回卷导致数据库停机。

基本用法

基本
pg-vacuum                    # 冻结所有数据库中的老化表
pg-vacuum mydb               # 仅处理指定数据库
选项
pg-vacuum -n mydb            # 空跑模式，只显示不执行
pg-vacuum -a 80000000 mydb   # 使用自定义年龄阈值（默认1亿）
pg-vacuum -r 50 mydb         # 使用自定义老化比例阈值（默认40%）
手工SQL
-- 对整个数据库执行 VACUUM FREEZE
VACUUM FREEZE;

-- 对特定表执行 VACUUM FREEZE
VACUUM FREEZE schema.table_name;

命令选项

选项 说明 默认值
-h, --help 显示帮助信息 -
-n, --dry-run 空跑模式，只显示不执行 false
-a, --age 年龄阈值，超过此值的表需要冻结 100000000
-r, --ratio 老化比例阈值，超过则全库冻结（%） 40

工作逻辑

  1. 检查数据库的 datfrozenxid 年龄，如果低于阈值则跳过该库
  2. 计算老化页面比例（超过年龄阈值的表页面占总页面的百分比）
  3. 如果老化比例 > 40%，执行全库 VACUUM FREEZE ANALYZE
  4. 否则，仅对超过年龄阈值的表执行 VACUUM FREEZE ANALYZE

脚本会设置 vacuum_cost_limit = 10000 和 vacuum_cost_delay = 1ms 以控制 I/O 影响。

执行条件

  • 脚本必须在 主库 上以 pg_dbsu postgres 用户身份运行
  • 使用文件锁 /tmp/pg-vacuum.lock 防止并发执行
  • 自动跳过 template0、template1、postgres 系统数据库

常用定时任务配置

建议将 vacuum 任务与备份/Repack 任务分开执行，避免冲突。

pg_crontab:
  - '00 03 * * 0 /pg/bin/pg-vacuum'     # 每周日凌晨3点执行

pg-repack

pg-repack 是 Pigsty 提供的膨胀治理脚本，基于 pg_repack 扩展实现，用于在线重整膨胀的表与索引。

基本用法

基本
pg-repack                    # 重整所有数据库中的膨胀表与索引
pg-repack mydb               # 仅重整指定数据库
pg-repack mydb1 mydb2        # 重整多个数据库
选项
pg-repack -n mydb            # 空跑模式，只显示不执行
pg-repack -t mydb            # 仅重整表
pg-repack -i mydb            # 仅重整索引
pg-repack -T 30 -j 4 mydb    # 自定义锁超时(秒)和并行度
手工
# 直接使用 pg_repack 命令重整特定表
pg_repack dbname -t schema.table

# 直接使用 pg_repack 命令重整特定索引
pg_repack dbname -i schema.index

命令选项

选项 说明 默认值
-h, --help 显示帮助信息 -
-n, --dry-run 空跑模式，只显示不执行 false
-t, --table 仅重整表 false
-i, --index 仅重整索引 false
-T, --timeout 锁等待超时时间（秒） 10
-j, --jobs 并行作业数 2

自动选择阈值

脚本会根据表和索引的大小与膨胀率，自动选择需要重整的对象：

表膨胀阈值

大小范围 膨胀率阈值 最大数量
< 256MB > 40% 64
256MB - 2GB > 30% 16
2GB - 8GB > 20% 4
8GB - 64GB > 15% 1

索引膨胀阈值

大小范围 膨胀率阈值 最大数量
< 128MB > 40% 64
128MB - 1GB > 35% 16
1GB - 8GB > 30% 4
8GB - 64GB > 20% 1

超过 64GB 的巨型表/索引会被跳过并给出提示，需要手动处理。

执行条件

  • 脚本必须在 主库 上以 postgres 用户身份运行
  • 需要安装 pg_repack 扩展（Pigsty 默认安装）
  • 需要 monitor schema 中的 pg_table_bloat 和 pg_index_bloat 视图
  • 使用文件锁 /tmp/pg-repack.lock 防止并发执行
  • 自动跳过 template0、template1、postgres 系统数据库
锁等待

重整期间不会影响正常读写，但重整完毕的 切换瞬间 需要获取表上的 AccessExclusive 锁阻塞一切访问。对于高吞吐量业务，建议在业务低峰期或维护窗口进行。

常用定时任务配置

pg_crontab:
  - '00 04 * * 1 /pg/bin/pg-repack'     # 每周一凌晨4点执行

您可以通过 Pigsty 的 PGCAT Database - Table Bloat 面板确认数据库中的膨胀情况，并选择膨胀率较高的表与索引进行重整。

更多细节请参考：关系膨胀的治理

移除定时任务

当使用 pgsql-rm.yml 剧本移除 PostgreSQL 集群时，会自动删除 postgres 用户的 crontab 文件。

./pgsql-rm.yml -l <cls> -t pg_crontab    # 仅移除定时任务
./pgsql-rm.yml -l <cls>                  # 移除整个集群（包含定时任务）

相关文档

4.9 - 升级 PostgreSQL 大小版本

版本升级：小版本滚动升级、大版本迁移、扩展升级

快速上手

PostgreSQL 版本升级分为两种类型：小版本升级 和 大版本升级，两者的风险和复杂度差异很大。

类型 示例 停机时间 数据兼容性 风险等级
小版本升级 17.2 → 17.3 秒级（滚动重启） 完全兼容 低
大版本升级 17 → 18 分钟级 需要升级数据目录 中
小版本
# 滚动升级：先从库后主库
ansible <cls> -b -a 'yum upgrade -y postgresql17*'
pg restart --role replica --force <cls>
pg switchover <cls>
pg restart <cls> <old-primary> --force
大版本
# 推荐：逻辑复制迁移
bin/pgsql-add pg-new              # 创建新版本集群
# 配置逻辑复制同步数据...
# 切换流量到新集群
扩展
ansible <cls> -b -a 'yum upgrade -y postgis36_17*'
psql -c 'ALTER EXTENSION postgis UPDATE;'

关于在线迁移的详细流程，请参考 在线迁移 文档。

操作 说明 风险
小版本升级 更新软件包，滚动重启 低
小版本降级 回退到之前的小版本 低
大版本升级 逻辑复制或 pg_upgrade 中
扩展升级 升级扩展软件包和扩展对象 低

小版本升级

小版本升级（如 17.2 → 17.3）是最常见的升级场景，通常用于应用安全补丁和 Bug 修复。数据目录完全兼容，通过滚动重启即可完成。

升级策略：推荐采用 滚动升级 方式：先升级从库，再通过主从切换升级原主库，最小化服务中断。

1. 更新软件仓库 → 2. 升级从库软件包 → 3. 重启从库
4. 主从切换 → 5. 升级原主库软件包 → 6. 重启原主库

步骤一：准备软件包

确保本地软件仓库中有最新版本的 PostgreSQL 包，并刷新节点缓存：

仓库
cd ~/pigsty
./infra.yml -t repo_upstream      # 添加上游仓库（需要互联网）
./infra.yml -t repo_build         # 重建本地仓库
EL
ansible <cls> -b -a 'yum clean all'
ansible <cls> -b -a 'yum makecache'
Debian
ansible <cls> -b -a 'apt clean'
ansible <cls> -b -a 'apt update'

步骤二：升级从库

在所有从库上升级软件包并验证版本：

EL
ansible <cls> -b -a 'yum upgrade -y postgresql17*'
ansible <cls> -b -a '/usr/pgsql/bin/pg_ctl --version'
Debian
ansible <cls> -b -a 'apt install -y postgresql-17'
ansible <cls> -b -a '/usr/lib/postgresql/17/bin/pg_ctl --version'

重启所有从库以应用新版本：

pg restart --role replica --force <cls>

步骤三：切换主库

执行主从切换，将主库角色转移到已升级的从库：

pg switchover <cls>
# 或非交互式：
pg switchover --leader <old-primary> --candidate <new-primary> --scheduled=now --force <cls>

步骤四：升级原主库

原主库现在已降级为从库，升级软件包并重启：

EL
ansible <old-primary-ip> -b -a 'yum upgrade -y postgresql17*'
Debian
ansible <old-primary-ip> -b -a 'apt install -y postgresql-17'
pg restart <cls> <old-primary-name> --force

步骤五：验证

确认所有实例版本一致：

pg list <cls>
pg query <cls> -c "SELECT version()"

小版本降级

在极少数情况下（如新版本引入 Bug），可能需要将 PostgreSQL 降级到之前的版本。

步骤一：获取旧版本包

EL
cd ~/pigsty; ./infra.yml -t repo_upstream     # 添加上游仓库
cd /www/pigsty; repotrack postgresql17-*-17.1 # 下载指定版本的包
cd ~/pigsty; ./infra.yml -t repo_create       # 重建仓库元数据
刷新缓存
ansible <cls> -b -a 'yum clean all'
ansible <cls> -b -a 'yum makecache'

步骤二：执行降级

EL
ansible <cls> -b -a 'yum downgrade -y postgresql17*'
Debian
ansible <cls> -b -a 'apt install -y postgresql-17=17.1*'

步骤三：重启集群

pg restart --force <cls>

大版本升级

大版本升级（如 17 → 18）涉及数据格式变更，需要使用专用工具进行数据迁移。

方式 停机时间 复杂度 适用场景
逻辑复制迁移 秒级切换 高 生产环境，要求最小停机
pg_upgrade 原地升级 分钟~小时 中 测试环境，数据量较小
推荐方案

对于生产环境，推荐使用 逻辑复制迁移 方式：创建新版本集群，通过逻辑复制同步数据，然后进行蓝绿切换。这种方式停机时间最短，且可以随时回滚。详见 在线迁移。

逻辑复制迁移

逻辑复制迁移是生产环境大版本升级的推荐方式，核心步骤：

1. 创建新版本目标集群 → 2. 配置逻辑复制同步数据 → 3. 验证数据一致性
4. 切换应用流量到新集群 → 5. 下线旧集群

步骤一：创建新版本集群

pg-meta-new:
  hosts:
    10.10.10.12: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-meta-new
    pg_version: 18                    # 新版本
bin/pgsql-add pg-meta-new

步骤二：配置逻辑复制

-- 源集群（旧版本）主库：创建发布
CREATE PUBLICATION upgrade_pub FOR ALL TABLES;

-- 目标集群（新版本）主库：创建订阅
CREATE SUBSCRIPTION upgrade_sub
  CONNECTION 'host=10.10.10.11 port=5432 dbname=mydb user=replicator password=xxx'
  PUBLICATION upgrade_pub;

步骤三：等待同步完成

-- 目标集群：检查订阅状态
SELECT * FROM pg_stat_subscription;

-- 源集群：检查复制槽 LSN
SELECT slot_name, confirmed_flush_lsn FROM pg_replication_slots;

步骤四：切换流量

确认数据同步完成后：停止应用写入源集群 → 等待最后的数据同步 → 切换应用连接到新集群 → 删除订阅，下线源集群。

-- 目标集群：删除订阅
DROP SUBSCRIPTION upgrade_sub;

详细的迁移流程请参考 在线迁移 文档。

pg_upgrade 原地升级

pg_upgrade 是 PostgreSQL 官方提供的大版本升级工具，适用于测试环境或可接受较长停机时间的场景。

重要警告

原地升级会导致较长的停机时间，且回滚困难。生产环境请优先考虑逻辑复制迁移方式。

步骤一：安装新版本软件包

./pgsql.yml -l <cls> -t pg_pkg -e pg_version=18

步骤二：停止 Patroni

pg pause <cls>                        # 暂停自动故障转移
systemctl stop patroni                # 停止 Patroni（会停止 PostgreSQL）

步骤三：运行 pg_upgrade

sudo su - postgres
mkdir -p /data/postgres/pg-meta-18/data

# 预检（-c 参数只检查不执行）
/usr/pgsql-18/bin/pg_upgrade \
  -b /usr/pgsql-17/bin -B /usr/pgsql-18/bin \
  -d /data/postgres/pg-meta-17/data \
  -D /data/postgres/pg-meta-18/data \
  -v -c

# 执行升级
/usr/pgsql-18/bin/pg_upgrade \
  -b /usr/pgsql-17/bin -B /usr/pgsql-18/bin \
  -d /data/postgres/pg-meta-17/data \
  -D /data/postgres/pg-meta-18/data \
  --link -j 8 -v

步骤四：更新链接并启动

rm -rf /usr/pgsql && ln -s /usr/pgsql-18 /usr/pgsql
rm -rf /pg && ln -s /data/postgres/pg-meta-18 /pg
# 编辑 /etc/patroni/patroni.yml 更新路径
systemctl start patroni
pg resume <cls>

步骤五：后处理

/usr/pgsql-18/bin/vacuumdb --all --analyze-in-stages
./delete_old_cluster.sh   # pg_upgrade 生成的清理脚本

扩展升级

升级 PostgreSQL 版本时，通常也需要升级相关扩展插件。

升级扩展软件包

EL
ansible <cls> -b -a 'yum upgrade -y postgis36_17 timescaledb-2-postgresql-17* pgvector_17*'
Debian
ansible <cls> -b -a 'apt install -y postgresql-17-postgis-3 postgresql-17-pgvector'

升级扩展版本

软件包升级后，在数据库中执行扩展升级：

-- 查看可升级的扩展
SELECT name, installed_version, default_version FROM pg_available_extensions
WHERE installed_version IS NOT NULL AND installed_version <> default_version;

-- 升级扩展
ALTER EXTENSION postgis UPDATE;
ALTER EXTENSION timescaledb UPDATE;
ALTER EXTENSION vector UPDATE;

-- 检查扩展版本
SELECT extname, extversion FROM pg_extension;
扩展兼容性

大版本升级前，请确认所有使用的扩展都支持目标 PostgreSQL 版本。某些扩展可能需要先卸载再重新安装，请查阅扩展文档。

注意事项

  1. 备份优先：任何升级操作前都应进行完整备份
  2. 测试验证：先在测试环境验证升级流程
  3. 扩展兼容：确认所有扩展支持目标版本
  4. 回滚预案：准备好回滚方案，特别是大版本升级
  5. 监控观察：升级后密切监控数据库性能和错误日志
  6. 文档记录：记录升级过程中的所有操作和问题

相关文档

4.10 - 管理 PostgreSQL 扩展插件

扩展管理：下载、安装、配置、启用、更新、卸载扩展

快速上手

Pigsty 提供 575 扩展，使用扩展涉及四个步骤：下载、安装、配置、启用。

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_extensions: [ postgis, timescaledb, pgvector ]           # <--- 安装扩展软件包
    pg_libs: 'timescaledb, pg_stat_statements, auto_explain'    # <--- 配置预加载扩展
    pg_databases:
      - name: meta
        extensions: [ postgis, timescaledb, vector ]            # <--- 在数据库中启用
脚本
bin/pgsql-ext <cls>           # 在 <cls> 集群上安装配置中定义的扩展
bin/pgsql-ext <cls> [ext...]  # 在 <cls> 集群上安装命令行参数给出的扩展
剧本
./pgsql.yml -l pg-meta -t pg_ext    # 使用剧本安装扩展
示例
bin/pgsql-ext pg-meta                         # 在 pg-meta 集群上安装定义的扩展
bin/pgsql-ext pg-meta pg_duckdb pg_mooncake   # 安装指定扩展

关于扩展的完整参考，请查阅 扩展插件 章节。关于可用扩展列表，请参考 扩展目录。

操作 快捷命令 说明
下载扩展 ./infra.yml -t repo_build 将扩展下载到本地仓库
安装扩展 bin/pgsql-ext <cls> 在集群节点上安装扩展软件包
配置扩展 pg edit-config <cls> -p 将扩展添加到预加载库（需重启）
启用扩展 psql -c 'CREATE EXT ...' 在数据库中创建扩展对象
更新扩展 ALTER EXTENSION UPDATE 更新扩展软件包与扩展对象
移除扩展 DROP EXTENSION 删除扩展对象，卸载软件包
demo/pgsql-ext.cast

安装扩展

定义在 pg_extensions 里面的扩展会在 PostgreSQL 集群创建 的时候在 pg_extension 任务中自动安装。

要在现有的 PostgreSQL 集群上安装扩展，请将扩展添加到 all.children.<cls>.pg_extensions，然后执行：

脚本
bin/pgsql-ext <cls>   # 在 <cls> 集群上安装扩展
剧本
./pgsql.yml -l <cls> -t pg_extension   # 直接使用 Ansible 剧本安装扩展
示例
bin/pgsql-ext pg-meta    # 在 pg-meta 集群上安装配置中定义的扩展

示例配置：在集群上安装 PostGIS、TimescaleDB 和 PGVector

#all.children.pg-meta.vars: # 省略上级缩进
pg_extensions: [ postgis, timescaledb, pgvector ]

执行效果：在集群所有节点上安装扩展软件包。Pigsty 会自动将 包别名 翻译为对应操作系统和 PostgreSQL 版本的实际包名。

安装前，确保软件源可用

安装扩展前请确保节点已配置正确的软件源 —— 扩展已经在本地仓库中 下载好，或者已经 配置扩展仓库。

手工安装

如果您不想使用 Pigsty 配置来管理 PostgreSQL 扩展，可以在命令行中直接传递要安装的扩展列表：

脚本
bin/pgsql-ext pg-meta pg_duckdb pg_mooncake   # 在 pg-meta 集群上安装指定扩展
剧本
./pgsql.yml -l pg-meta -t pg_ext -e '{"pg_extensions": ["pg_duckdb", "pg_mooncake"]}'

您也可以使用 pig 包管理器命令行工具在单个节点上安装扩展，同样会自动进行 包别名 解析。

pig install postgis timescaledb       # 安装多个扩展
pig install pgvector -v 18            # 针对特定 PG 大版本安装

ansible pg-test -b -a 'pig install pg_duckdb'   # 使用 Ansible 在集群上批量安装

您也可以 直接使用操作系统包管理器 (apt/dnf) 进行安装，但您必须知道具体操作系统/PG 下的 RPM/DEB 包名：

# EL 系统（RHEL、Rocky、Alma、Oracle Linux）
sudo yum install -y pgvector_18*

# Debian / Ubuntu 系统
sudo apt install -y postgresql-18-pgvector

下载扩展

要想安装扩展，您需要确保节点上配置的 扩展仓库 包含待安装的扩展：

  • 单机安装 时无需操心，上游仓库已经直接添加到节点上。
  • 离线安装 时无需操心，绝大部分扩展都已经包含在离线安装包里，个别扩展需要在线安装。
  • 使用本地仓库的 生产多节点部署，要看情况，如果在本地仓库创建的时候 repo_packages / repo_extra_packages 中包含了扩展包， 则意味着已经下载到了本地，可以直接安装，否则需要先下载扩展包到本地仓库。或者直接为节点 配置上游仓库 在线安装。

Pigsty 的默认配置在安装过程中会自动下载主流扩展到本地仓库。如需额外扩展，添加到 repo_extra_packages 后重建仓库：

repo_extra_packages: [ pgvector, postgis, timescaledb ]
脚本
make repo         # 快捷方式 = repo-build + node-repo
make repo-build   # 快捷方式，重建 Infra 上的软件仓库（下载软件包与依赖）
make node-repo    # 快捷方式，刷新节点上的软件源缓存，更新对 Infra 软件仓库的引用
剧本
./deploy.yml -t repo_build,node_repo  # 一次性执行两个任务
./infra.yml -t repo_build     # 重新下载软件包到本地仓库
./node.yml  -t node_repo      # 刷新节点软件源缓存

配置仓库

您也可以选择直接让所有节点都使用上游仓库（生产环境不推荐），跳过下载步骤，直接从互联网 上游扩展仓库 安装

./node.yml -t node_repo -e node_repo_modules=node,pgsql   # 添加 PGDG 与 Pigsty 上游仓库

配置扩展

部分扩展需要预加载到 shared_preload_libraries 才能使用，修改后需要 重启数据库 生效。

您可以用 pg_libs 参数作为它的默认值，在配置预加载的扩展，但是这个参数只在集群初始化时生效，后面修改就无效了。

pg-meta:
  vars:
    pg_cluster: pg-meta
    pg_libs: 'timescaledb, pg_stat_statements, auto_explain'   # 预加载扩展
    pg_extensions: [ timescaledb, postgis, pgvector ]          # 安装扩展包

对于已有集群，您可以参考 修改配置 的介绍，修改 shared_preload_libraries 参数：

pg edit-config pg-meta --force -p shared_preload_libraries='timescaledb, pg_stat_statements, auto_explain'
pg restart pg-meta   # 修改 pg-meta 集群的参数，并重启集群使配置生效

请确保扩展软件包已正确安装后再添加预加载配置，如果 shared_preload_libraries 中的扩展不存在或加载失败，PostgreSQL 将 无法启动。 此外，请通过 Patroni 管理集群的配置变更，避免使用 ALTER SYSTEM 或者 pg_parameters 单独修改实例配置。 如果主库和从库配置不一致，可能导致启动失败或复制中断。

启用扩展

安装扩展软件包后，需要在数据库中执行 CREATE EXTENSION 才能使用扩展提供的功能。

集群初始化时启用

在 数据库定义 中通过 extensions 数组声明要启用的扩展：

pg_databases:
  - name: meta
    extensions:
      - vector                             # 简单形式
      - { name: postgis, schema: public }  # 指定 Schema

手动启用

SQL
CREATE EXTENSION vector;                      -- 创建扩展
CREATE EXTENSION postgis SCHEMA public;       -- 指定 Schema
CREATE EXTENSION IF NOT EXISTS vector;        -- 幂等创建
CREATE EXTENSION postgis_topology CASCADE;    -- 自动安装依赖
psql
psql -d meta -c 'CREATE EXTENSION vector;'                  # 在 meta 数据库创建扩展
psql -d meta -c 'CREATE EXTENSION postgis SCHEMA public;'   # 指定 Schema
剧本
# 修改数据库定义后使用剧本启用扩展
bin/pgsql-db pg-meta meta    # 创建/修改数据库会自动启用定义的扩展

执行效果：在数据库中创建扩展对象（函数、类型、操作符、索引方法等），之后即可使用扩展提供的功能。

更新扩展

扩展更新涉及两个层面：软件包更新 和 扩展对象更新。

更新软件包

pig
pig update pgvector                           # 使用 pig 更新扩展
yum
sudo yum update pgvector_18 # EL
apt
sudo apt upgrade postgresql-18-pgvector  # Debian/Ubuntu

更新扩展对象

-- 查看可升级的扩展
SELECT name, installed_version, default_version FROM pg_available_extensions
WHERE installed_version IS NOT NULL AND installed_version <> default_version;

-- 更新扩展到最新版本
ALTER EXTENSION vector UPDATE;

-- 更新到指定版本
ALTER EXTENSION vector UPDATE TO '0.8.1';
更新注意事项

更新扩展前建议备份数据库。预加载扩展更新后可能需要重启 PostgreSQL。某些扩展版本升级可能不兼容，请查阅扩展文档。

移除扩展

移除扩展涉及两个层面：删除扩展对象 和 卸载软件包。

删除扩展对象

DROP EXTENSION vector;              -- 删除扩展
DROP EXTENSION vector CASCADE;      -- 级联删除（删除依赖对象）

移除预加载

如果是预加载扩展，需从 shared_preload_libraries 中移除并重启：

pg edit-config pg-meta --force -p shared_preload_libraries='pg_stat_statements, auto_explain'
pg restart pg-meta   # 重启使配置生效

卸载软件包（可选）

pig
pig remove pgvector                           # 使用 pig 卸载
yum
sudo yum remove pgvector_18*                  # EL 系统
apt
sudo apt remove postgresql-18-pgvector        # Debian/Ubuntu
CASCADE 警告

使用 CASCADE 删除扩展会同时删除所有依赖该扩展的对象（表、索引、视图等）。请先检查依赖关系再执行删除。

查询扩展

以下是一些常用的 SQL 查询，用于查看扩展信息：

查看已启用的扩展

SELECT extname, extversion, nspname AS schema
FROM pg_extension e JOIN pg_namespace n ON e.extnamespace = n.oid
ORDER BY extname;

查看可用扩展

SELECT name, default_version, installed_version, comment
FROM pg_available_extensions
WHERE installed_version IS NOT NULL   -- 仅显示已安装的
ORDER BY name;

检查扩展是否可用

SELECT * FROM pg_available_extensions WHERE name = 'vector';

查看扩展依赖关系

SELECT e.extname, d.refobjid::regclass AS depends_on
FROM pg_extension e
JOIN pg_depend d ON d.objid = e.oid
WHERE d.deptype = 'e' AND e.extname = 'postgis_topology';

查看扩展对象

SELECT classid::regclass, objid, deptype
FROM pg_depend
WHERE refobjid = (SELECT oid FROM pg_extension WHERE extname = 'vector');

psql 快捷命令

\dx                    # 列出已启用的扩展
\dx+ vector            # 显示扩展详情

添加仓库

如需直接从上游安装扩展，可手动添加软件仓库。

使用 Pigsty 剧本添加

./node.yml -t node_repo -e node_repo_modules=node,pgsql        # 添加 PGDG 与 Pigsty 仓库
./node.yml -t node_repo -e node_repo_modules=node,pgsql,local  # 包括本地仓库

YUM 仓库（EL 系统）

# Pigsty 仓库
curl -fsSL https://repo.pigsty.io/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
curl -fsSL https://repo.pigsty.io/yum/repo | sudo tee /etc/yum.repos.d/pigsty.repo >/dev/null

# 中国大陆镜像
curl -fsSL https://repo.pigsty.cc/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
curl -fsSL https://repo.pigsty.cc/yum/repo | sudo tee /etc/yum.repos.d/pigsty.repo >/dev/null

APT 仓库（Debian/Ubuntu）

curl -fsSL https://repo.pigsty.io/key | sudo gpg --dearmor -o /etc/apt/keyrings/pigsty.gpg
sudo tee /etc/apt/sources.list.d/pigsty.list > /dev/null <<EOF
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.io/apt/infra generic main
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.io/apt/pgsql $(lsb_release -cs) main
EOF
sudo apt update

# 中国大陆镜像：将 repo.pigsty.io 替换为 repo.pigsty.cc

常见问题

扩展名与包名的区别

名称 说明 示例
扩展名 CREATE EXTENSION 使用的名称 vector
包别名 Pigsty 配置中使用的标准化名称 pgvector
包名 操作系统实际的包名 pgvector_18* 或 postgresql-18-pgvector

预加载扩展无法启动

如果 shared_preload_libraries 中的扩展不存在或加载失败，PostgreSQL 将无法启动。解决方法：

  1. 确保扩展软件包已正确安装
  2. 或从 shared_preload_libraries 中移除该扩展（编辑 /pg/data/postgresql.conf）

扩展依赖问题

某些扩展依赖于其他扩展，需按顺序创建或使用 CASCADE：

CREATE EXTENSION postgis;                    -- 先创建基础扩展
CREATE EXTENSION postgis_topology;           -- 再创建依赖扩展
-- 或
CREATE EXTENSION postgis_topology CASCADE;   -- 自动创建依赖

扩展版本不兼容

查看当前 PostgreSQL 版本支持的扩展版本：

SELECT * FROM pg_available_extension_versions WHERE name = 'vector';

相关资源

5 - 备份恢复

配置备份策略与备份仓库，管理备份，执行时间点恢复：pgBackRest 引擎与 Pigsty 封装层的完整实操手册。

Pigsty 使用 pgBackRest 管理 PostgreSQL 备份 —— 这可能是 PostgreSQL 生态中最强大的开源备份工具， 支持增量备份、并行处理、加密、Silo/S3 对象存储等众多特性。 每个 PGSQL 集群默认都预配置了备份与 WAL 归档，开箱即用。

本章是备份恢复的 实操手册：配置方法、管理命令、恢复操作与演练教程。 设计理念与心智模型（为什么、如何权衡）请参阅概念层文档 时间点恢复。

所有的备份恢复操作，最终都会落实为 pgBackRest 命令。Pigsty 在它之上提供了三层封装，按需选用：

层次 接口 形态 适用场景
集群编排 pg_pitr 参数 + pgsql-pitr.yml 剧本 Ansible 剧本 生产集群恢复：编排 HA、etcd 与多节点
实例编排 pig pitr 命令行工具 单节点恢复：在数据库节点上直接编排执行
命令原语 pig pb / pb 别名 / pg-backup 脚本 pgBackRest 封装 备份、查询、清理，以及非托管实例的裸恢复
底层引擎 pgbackrest 原生命令 一切封装的最终执行者
章节 内容
机制 pgBackRest 核心概念（stanza / 仓库 / 保留 / 时间线）与 Pigsty 的封装映射
策略 设计备份策略：调度计划、恢复窗口与磁盘空间规划
仓库 配置备份仓库：本地、Silo、外部 S3，加密、版本控制与锁定
管理 备份管理命令手册：启停、手动备份、查看、清理、Stanza 管理
恢复 执行时间点恢复：恢复目标、分步执行、参数参考
克隆 用 PITR 克隆数据库集群：找回数据、恢复演练
示例 沙箱教程：使用 pgBackRest 原语手工执行恢复
免责声明

Pigsty 尽最大努力提供可靠的 PITR 解决方案，但我们不对 PITR 操作导致的数据丢失承担任何责任，使用需自担风险。如需专业支持，请考虑我们的 专业服务。

恢复操作会覆盖目标数据

执行 PITR 前必须先核对 pig pg list <目标集群> 与 pig pb info，确认近期可用备份和恢复窗口， 由操作者复述精确的目标集群与恢复点，再执行目标限定的 ./pgsql-pitr.yml -l <目标集群> ...。 pgsql-pitr.yml 只打印计划，不会暂停等待确认；生产恢复还需要维护窗口和独立验证过的备份。

快速上手

  1. 设计备份策略：用 pg_crontab 声明定时备份计划，用 pgbackrest_repo 选择备份仓库
  2. 管理备份：用 pg-backup 手动备份，用 pb info 查看备份状态
  3. 执行恢复：用 pg_pitr 参数声明恢复目标，运行 pgsql-pitr.yml 剧本
pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ]
./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": { "time": "2025-07-13 10:00:00+00", "action": "promote" }}'

5.1 - 备份机制

pgBackRest 的概念体系（stanza、仓库、备份链、保留策略、时间线）与 Pigsty 封装层的参数映射：理解每条命令背后发生了什么。

Pigsty 的备份恢复功能，最终都会落实为 pgBackRest 命令的执行。 所以要真正掌握这套系统，需要理解两件事：pgBackRest 本身的概念体系（stanza、仓库、备份链、保留、时间线）， 以及 Pigsty 各层封装如何映射到它（参数如何变成命令行选项）。本页依次讲清这两部分。

pgBackRest 核心概念

Stanza：集群的备份身份

Stanza（节）是 pgBackRest 中一套 PostgreSQL 集群备份配置的名称，也是仓库内隔离不同集群的命名空间。 Pigsty 将 stanza 直接映射为集群名 pg_cluster： 集群 pg-meta 的备份就存储在仓库的 backup/pg-meta/ 与 archive/pg-meta/ 目录下， 多套集群可以安全共享同一个仓库。

Stanza 记录着源集群的 system-id 与主版本号，写入备份前会核对身份 —— 这正是 克隆集群 后需要 stanza-upgrade 善后的原因。 Stanza 由 stanza-create 创建（Pigsty 在集群初始化时自动完成）， 版本升级后用 stanza-upgrade 更新。

仓库：备份存放在哪里

仓库（Repository）是备份与 WAL 归档的存储后端，在配置中以 repo1-* 系列选项定义： repo1-type 决定类型（POSIX 文件系统、S3、Azure、GCS、SFTP），repo1-path 决定路径， repo1-cipher-* 决定加密，repo1-retention-* 决定保留策略。 Pigsty 通过 pgbackrest_repo 参数生成这些配置，详见 备份仓库。

备份链与备份标签

pgBackRest 支持三种备份类型，后两种依赖前面的备份构成 备份链：

类型 内容 标签后缀
全量备份（full） 完整复制数据库集群 F
差异备份（diff） 相对最近一次 全量 的变化 D
增量备份（incr） 相对最近一次 任意备份 的变化 I

每个备份都有唯一的 备份标签（label），命名规则本身就描述了备份链： 20250715-013657F 是一个全量备份，20250715-013657F_20250715-013724D 是基于它的差异备份， 20250715-013657F_20250715-013730I 是增量备份 —— 下划线前的部分标识它所依附的全量备份。 恢复时用 --set 指定从哪个备份集开始还原，默认自动选择目标时间点前最近的一个。

保留策略：仓库如何不被撑爆

保留策略（Retention）决定旧备份何时被清除。repo1-retention-full 配合 repo1-retention-full-type（count 按份数 / time 按天数）控制全量备份的保留； 全量备份过期时，依附它的差异/增量备份与对应的 WAL 归档一并清除。 Pigsty 默认启用 expire-auto，每次备份完成后自动执行过期清理，也可用 expire 命令手动触发。

time 表示 最短时间窗口，不是“只保留最近 N 天内的全量备份”。只有在仓库中还存在另一份年龄达到 N 天的全量备份时， 更老的全量备份才会过期。因此 retention_full: 14 配合每周全备，稳态会保留三条全量备份链，恢复窗口约为 14～21 天。

WAL 归档：保留下来的历史

PostgreSQL 的 archive_command 在每个 WAL 段写满（或 archive_timeout 超时）后触发， Pigsty 将其配置为 archive-push，把 WAL 推入仓库； 恢复时则由 restore_command 调用 archive-get 按需拉取。 Pigsty 启用了异步归档（archive-async=y），经由 /pg/spool 假脱机目录批量推送，避免归档拖慢主库。

时间线：分叉的历史

每次恢复提升（或故障切换）都会开启一条新的 时间线（Timeline），旧时间线的 WAL 仍保留在仓库中。 恢复时可用 --target-timeline 指定沿哪条时间线重放（默认 latest）， 这使得"恢复错了再恢复一次"成为可能。完整心智模型见概念层 工作原理。

恢复机制：restore 命令做了什么

理解 restore 命令的行为，就理解了 PITR 的执行过程。它做两件事：

  1. 重建数据目录：从备份集还原数据文件。带 --delta 选项（Pigsty 默认启用）时执行增量还原 —— 校验现有文件，只重写与备份不一致的部分，大幅缩短大库的还原时间。
  2. 写入恢复配置：生成 recovery.signal 标记与恢复参数（restore_command、recovery_target_*）， 使 PostgreSQL 下次启动时进入恢复模式，从仓库拉取 WAL 重放至目标点。

因此 restore 命令返回成功只是完成了一半：真正的恢复发生在 PostgreSQL 启动之后的 WAL 重放阶段。 重放到达目标后的行为由 --target-action 决定：pause 暂停等待检查、promote 提升开启新时间线、shutdown 停机。

恢复目标的参数组合是固定句式：--type 指定目标类型，--target 给出目标值， 可选的 --target-exclusive 控制边界、--target-timeline 选择时间线、--set 指定起点备份：

pgbackrest --stanza=pg-meta restore                                        # 恢复到 WAL 归档末尾
pgbackrest --stanza=pg-meta --type=immediate restore                       # 恢复到最近一致点
pgbackrest --stanza=pg-meta --type=time --target='2025-07-13 10:00:00+00' restore
pgbackrest --stanza=pg-meta --type=xid  --target='250000' --target-exclusive restore
pgbackrest --stanza=pg-meta --type=name --target='my-restore-point' restore
pgbackrest --stanza=pg-meta --type=lsn  --target='0/4001C80' --target-action=promote restore

实际观察

您可以使用 pg_dbsu 用户（默认 postgres）直接执行 pgbackrest 命令， 观察上述概念的实际形态 —— 注意备份标签的命名、备份大小的差异，以及 info 输出中的备份链引用关系：

备份命令

full
$ pgbackrest --stanza=pg-meta --type=full backup
2025-07-15 01:36:57.007 P00   INFO: backup command begin 2.54.2: --annotation=pg_cluster=pg-meta ...
2025-07-15 01:36:57.030 P00   INFO: execute non-exclusive backup start: backup begins after the requested immediate checkpoint completes
2025-07-15 01:36:57.105 P00   INFO: backup start archive = 000000010000000000000006, lsn = 0/6000028
2025-07-15 01:36:58.540 P00   INFO: new backup label = 20250715-013657F
2025-07-15 01:36:58.588 P00   INFO: full backup size = 44.5MB, file total = 1437
2025-07-15 01:36:58.589 P00   INFO: backup command end: completed successfully (1584ms)
diff
$ pgbackrest --stanza=pg-meta --type=diff backup
2025-07-15 01:37:24.952 P00   INFO: backup command begin 2.54.2: ...
2025-07-15 01:37:24.985 P00   INFO: last backup label = 20250715-013657F, version = 2.54.2
2025-07-15 01:37:26.337 P00   INFO: new backup label = 20250715-013657F_20250715-013724D
2025-07-15 01:37:26.381 P00   INFO: diff backup size = 424.3KB, file total = 1437
2025-07-15 01:37:26.381 P00   INFO: backup command end: completed successfully (1431ms)
incr
$ pgbackrest --stanza=pg-meta --type=incr backup
2025-07-15 01:37:30.305 P00   INFO: backup command begin 2.54.2: ...
2025-07-15 01:37:30.337 P00   INFO: last backup label = 20250715-013657F_20250715-013724D, version = 2.54.2
2025-07-15 01:37:31.356 P00   INFO: new backup label = 20250715-013657F_20250715-013730I
2025-07-15 01:37:31.403 P00   INFO: incr backup size = 8.3KB, file total = 1437
2025-07-15 01:37:31.403 P00   INFO: backup command end: completed successfully (1099ms)
info
$ pgbackrest --stanza=pg-meta info
stanza: pg-meta
    status: ok
    cipher: aes-256-cbc

    db (current)
        wal archive min/max (17): 000000010000000000000001/00000001000000000000000A

        full backup: 20250715-013657F
            timestamp start/stop: 2025-07-15 01:36:57+00 / 2025-07-15 01:36:58+00
            wal start/stop: 000000010000000000000006 / 000000010000000000000006
            database size: 44.5MB, database backup size: 44.5MB
            repo1: backup size: 8.7MB

        diff backup: 20250715-013657F_20250715-013724D
            timestamp start/stop: 2025-07-15 01:37:24+00 / 2025-07-15 01:37:26+00
            database size: 44.5MB, database backup size: 424.3KB
            repo1: backup size: 94KB
            backup reference total: 1 full

        incr backup: 20250715-013657F_20250715-013730I
            timestamp start/stop: 2025-07-15 01:37:30+00 / 2025-07-15 01:37:31+00
            database size: 44.5MB, database backup size: 8.3KB
            repo1: backup size: 504B
            backup reference total: 1 full, 1 diff

Pigsty 的封装层次

在原生命令之上，Pigsty 提供了逐层升高的封装，每一层都只是对下一层的参数化调用，没有黑魔法：

层次 接口 它实际做什么
集群编排 pg_pitr + pgsql-pitr.yml 编排整个集群的恢复：暂停 HA → 停库 → 渲染配置并调用 pgbackrest restore → 输出控制信息 → 清理 etcd → 拉起 HA
实例编排 pig pitr 单节点编排：预检 → 停 Patroni/PG → 调用 pgbackrest restore → 可选启动 PG，Patroni 保持停止
命令原语 pig pb / pb 别名 / pg-backup 自动填充 --stanza 与 DBSU 身份，转发给 pgbackrest 对应子命令
底层引擎 pgbackrest 读取 /etc/pgbackrest/pgbackrest.conf，实际执行备份/归档/恢复

命令原语层

pb 是登录 shell 内置的别名函数：从配置文件解析出 stanza 后转发，让您少敲一个参数：

pb() (
    stanza=$(grep -o '\[[^][]*]' /etc/pgbackrest/pgbackrest.conf | head -n1 | sed 's/.*\[\([^]]*\)].*/\1/')
    pgbackrest --stanza="${stanza}" "$@"
)
pb info     # = pgbackrest --stanza=pg-meta info
pb backup   # = pgbackrest --stanza=pg-meta backup

pg-backup 脚本在此基础上增加了 角色检查（只在主库执行，从库直接退出），供 crontab 安全调用：

pg-backup full   # = pgbackrest --stanza=pg-meta --type=full backup（仅主库执行）
pg-backup diff   # = pgbackrest --stanza=pg-meta --type=diff backup
pg-backup incr   # = pgbackrest --stanza=pg-meta --type=incr backup（默认，无全量时自动升级为全量）

pig pb 提供了更完善的封装：自动检测 stanza、自动以 DBSU 身份执行（root 下 su、普通用户 sudo）、 备份前检查主库角色、恢复前显示执行计划并要求确认。完整子命令表见 管理命令。

参数如何映射

Pigsty 恢复接口的每个参数，都对应一个 pgbackrest 选项 —— 三层接口共用同一套语义：

pg_pitr 字段 pig pitr 选项 pgbackrest 选项 含义
cluster --stanza --stanza 从哪个集群的备份恢复（源 stanza）
type + time/xid/lsn/name --time/--xid/--lsn/--name --type + --target 恢复目标
（type: default） --default 不传 --type/--target 重放到 WAL 归档末尾
（type: immediate） --immediate --type=immediate 恢复到最近一致点
exclusive --exclusive / -X --target-exclusive 停在目标之前（排除目标点）
action --target-action --target-action 到达目标后：pause / promote / shutdown
timeline --target-timeline / -T --target-timeline 目标时间线，默认 latest
set --set / -b --set 从哪个备份集开始还原
db_include / db_exclude — --db-include / --db-exclude 选择性恢复部分数据库
link_map — --link-map 表空间/目录软链接映射
process — process-max 恢复并行进程数
data --data / -D --pg1-path 恢复到哪个数据目录
repo — repo1-*（渲染临时配置） 覆盖备份仓库定义；pig pitr --repo 仅选择现有配置中的仓库编号

选择性恢复仍是物理恢复：未包含或被排除的数据库会以稀疏清零文件还原，以便 PostgreSQL 完成恢复，但这些数据库本身不可访问， 恢复后需要显式删除。它不是 pg_dump 那样的逻辑子集恢复。

配置如何渲染

pgbackrest_repo 中被 pgbackrest_method 选中的仓库定义，会按简单规则渲染进 /etc/pgbackrest/pgbackrest.conf： 键名的下划线替换为连字符，加上 repo1- 前缀 —— 因此 pgBackRest 支持的仓库级配置项 可以直接写入参数：

pgbackrest_repo:
  minio:
    type: s3                  # ----> repo1-type=s3
    s3_endpoint: sss.pigsty   # ----> repo1-s3-endpoint=sss.pigsty
    cipher_type: aes-256-cbc  # ----> repo1-cipher-type=aes-256-cbc
    retention_full: 14        # ----> repo1-retention-full=14

执行 pgsql-pitr.yml 时，Pigsty 会另行渲染一份临时配置 /pg/conf/pitr.conf（避免污染常规配置）， 该剧本启动恢复期间的 PostgreSQL 日志写入 /pg/tmp/recovery.log。

定时备份

Pigsty 使用 Linux crontab 调度备份任务：pg_crontab 参数中的条目 会写入 postgres 用户的 crontab。因为 pg-backup 自带角色检查，同一份 crontab 可以下发到集群所有节点 —— 故障切换后，新主库会自动接续后续定时备份。

pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ]
pg_crontab:
  - '00 01 * * 1 /pg/bin/pg-backup full'
  - '00 01 * * 2,3,4,5,6,7 /pg/bin/pg-backup'

修改后用剧本应用变更：

./pgsql.yml -t pg_crontab -l pg-meta    # 更新 pg-meta 集群的 crontab

如何选择备份频率与保留策略，请参阅 备份策略。

部署细节

pgBackRest 组件在 pgsql.yml 剧本中完成安装与配置：

  • 随 pg_packages 中的 pgsql-common 组安装，二进制位于 /usr/bin/pgbackrest
  • pg_backup 子任务负责渲染配置、创建 stanza；由 pgbackrest_enabled 控制（默认启用）
  • 集群初始化后默认尝试执行一次 初始全量备份，且只在备份成功后留下 /etc/pgbackrest/initial.done 标记防止重复； 由 pgbackrest_init_backup 控制

文件层次

路径 用途
/usr/bin/pgbackrest 二进制，来自 PGDG 仓库的 pgbackrest 包
/etc/pgbackrest/pgbackrest.conf 主配置文件（stanza + 仓库定义）
/pg/backup 本地仓库数据目录（local 仓库时使用）
/pg/spool 异步归档的假脱机目录
/pg/log/pgbackrest/ 备份/归档/恢复日志，pgbackrest_log_dir
/pg/conf/pitr.conf PITR 过程中的临时 pgbackrest 配置
/pg/tmp/recovery.log PITR 过程中的 PostgreSQL 恢复日志

监控

每个节点运行 pgbackrest_exporter 服务（端口 pgbackrest_exporter_port：9854）， 将备份状态导出为监控指标（参见 pgBackRest 监控指标）。 可通过 pgbackrest_exporter_options 定制， 或将 pgbackrest_exporter_enabled 设为 false 禁用。

5.2 - 备份策略

设计并配置备份策略：备份频率决定恢复速度，保留策略决定恢复窗口与空间占用，两张推演图帮您做出量化决策。

备份策略要回答三个问题：何时 备份（调度计划）、何处 存放（备份仓库）、 保留多久（保留策略）。本页给出两套久经考验的预设策略及其量化推演 —— 背后的权衡逻辑请参阅概念层文档 策略权衡。

备份频率与恢复速度直接相关：恢复时需要从最近的基础备份开始重放 WAL 日志到目标时间点， 备份越频繁，需要重放的 WAL 越少，恢复越快；而保留策略与仓库空间直接相关：窗口越长，占用空间越大。

每日全量备份

对于生产数据库，建议从最简单的每日全量备份策略开始。Pigsty 随附的标准 pigsty.yml 集群示例采用这一策略， 配合默认的 local 本地仓库（保留最近 2 个全量备份）使用：

pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ]
pgbackrest_method: local          # 选择备份仓库方法：`local`、`minio` 或其他自定义仓库
pgbackrest_repo:                  # pgbackrest 仓库配置: https://pgbackrest.org/configuration.html#section-repository
  local:                          # 使用本地 POSIX 文件系统的默认 pgbackrest 仓库
    path: /pg/backup              # 本地备份目录，默认为 `/pg/backup`
    retention_full_type: count    # 按数量保留全量备份
    retention_full: 2             # 使用本地文件系统仓库时，保留2个，最多3个全量备份

假设您的数据库大小为 100GB，每天写入 10GB 数据，备份耗时 1 小时。 下图将「恢复窗口」与「存储空间占用」合并到同一时间轴（0~108h）上推演该策略的稳态行为： 恢复窗口在 24～48 小时 之间循环，备份占用约为 2 个全量备份加上 1～2 天的 WAL 归档。 在实践中，您需要准备至少 3～5 倍 数据库大小的备份磁盘，才能从容使用该默认策略。

tooltip: { trigger: axis, formatter: $fn:tipMerged, axisPointer: { type: line, snap: true, label: { show: false } } }
axisPointer: { link: [ { xAxisIndex: [0, 1] } ] }
legend: { show: false, bottom: 10, itemGap: 18, data: ["首要备份", "次要备份", "WAL归档", "瞬时备份"] }
grid:
  - { left: 82, right: "10%", top: 42, height: 218, containLabel: false }
  - { left: 82, right: "10%", top: 286, height: 218, containLabel: false }
xAxis:
  - type: category
    gridIndex: 0
    position: bottom
    boundaryGap: false
    data: [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108]
    name: 时间 h
    nameLocation: end
    nameGap: 10
    nameTextStyle: { align: left, verticalAlign: top, padding: [8, 0, 0, 0] }
    axisLabel: { interval: 11, formatter: $fn:fmtHour }
    axisLine: { show: true, symbol: [none, arrow], symbolSize: [10, 14], lineStyle: { width: 1.6, color: "#4b5563" } }
    axisTick: { show: true, length: 6 }
    splitLine: { show: true, lineStyle: { type: dashed, width: 1, opacity: 0.28, color: "#9ca3af" } }
    minorTick: { show: true, splitNumber: 12, length: 3 }
    minorSplitLine: { show: true, lineStyle: { type: dotted, width: 1, opacity: 0.14, color: "#9ca3af" } }
  - type: category
    gridIndex: 1
    position: top
    boundaryGap: true
    data: [0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108]
    axisLabel: { show: false }
    axisLine: { show: true, lineStyle: { width: 1.6, color: "#4b5563" } }
    axisTick: { show: true, length: 6 }
    splitLine: { show: true, lineStyle: { type: dashed, width: 1, opacity: 0.22, color: "#9ca3af" } }
yAxis:
  - type: value
    gridIndex: 0
    min: 0
    max: 52
    interval: 5
    name: 恢复窗口 h
    nameLocation: end
    nameRotate: 0
    nameGap: 8
    nameTextStyle: { align: left, verticalAlign: bottom, padding: [0, 0, 8, 4] }
    axisLabel: { formatter: $fn:fmtWin }
    axisLine: { show: true, symbol: [none, arrow], symbolSize: [10, 14], lineStyle: { width: 1.6, color: "#4b5563" } }
    axisTick: { show: true, length: 6 }
    splitLine: { show: true, lineStyle: { type: dashed, width: 1, opacity: 0.35, color: "#9ca3af" } }
    minorTick: { show: true, splitNumber: 5, length: 3 }
    minorSplitLine: { show: true, lineStyle: { type: dotted, width: 1, opacity: 0.18, color: "#9ca3af" } }
  - type: value
    gridIndex: 1
    min: 0
    max: 350
    interval: 50
    inverse: true
    name: 存储空间 GB
    nameLocation: end
    nameRotate: 0
    nameGap: 8
    nameTextStyle: { align: left, verticalAlign: top, padding: [10, 0, 0, 4] }
    axisLabel: { formatter: $fn:fmtGbTick }
    axisLine: { show: true, symbol: [arrow, none], symbolSize: [10, 14], lineStyle: { width: 1.6, color: "#4b5563" } }
    axisTick: { show: true, length: 6 }
    splitLine: { show: true, lineStyle: { type: dashed, width: 1, opacity: 0.32, color: "#9ca3af" } }
series: [ { name: 恢复窗口, type: line, smooth: false, symbol: none, showSymbol: false, xAxisIndex: 0, yAxisIndex: 0, lineStyle: { width: 3, color: "#f2a000" }, itemStyle: { color: "#f2a000" }, data: [[0,0],[1,0],[2,1],[3,2],[4,3],[5,4],[6,5],[7,6],[8,7],[9,8],[10,9],[11,10],[12,11],[13,12],[14,13],[15,14],[16,15],[17,16],[18,17],[19,18],[20,19],[21,20],[22,21],[23,22],[24,23],[25,24],[26,25],[27,26],[28,27],[29,28],[30,29],[31,30],[32,31],[33,32],[34,33],[35,34],[36,35],[37,36],[38,37],[39,38],[40,39],[41,40],[42,41],[43,42],[44,43],[45,44],[46,45],[47,46],[48,47],[49,48],[49,24],[50,25],[51,26],[52,27],[53,28],[54,29],[55,30],[56,31],[57,32],[58,33],[59,34],[60,35],[61,36],[62,37],[63,38],[64,39],[65,40],[66,41],[67,42],[68,43],[69,44],[70,45],[71,46],[72,47],[73,48],[73,24],[74,25],[75,26],[76,27],[77,28],[78,29],[79,30],[80,31],[81,32],[82,33],[83,34],[84,35],[85,36],[86,37],[87,38],[88,39],[89,40],[90,41],[91,42],[92,43],[93,44],[94,45],[95,46],[96,47],[97,48],[97,24],[98,25],[99,26],[100,27],[101,28],[102,29],[103,30],[104,31],[105,32],[106,33],[107,34],[108,35]], markLine: { symbol: none, label: { show: false }, data: [ { xAxis: 0, lineStyle: { color: "#59a14f", type: "solid", width: 1.4, opacity: 0.75 } }, { xAxis: 24, lineStyle: { color: "#59a14f", type: "solid", width: 1.4, opacity: 0.75 } }, { xAxis: 48, lineStyle: { color: "#59a14f", type: "solid", width: 1.4, opacity: 0.75 } }, { xAxis: 72, lineStyle: { color: "#59a14f", type: "solid", width: 1.4, opacity: 0.75 } }, { xAxis: 96, lineStyle: { color: "#59a14f", type: "solid", width: 1.4, opacity: 0.75 } }, { xAxis: 1, lineStyle: { color: "#336791", type: "solid", width: 1.4, opacity: 0.8 } }, { xAxis: 25, lineStyle: { color: "#336791", type: "solid", width: 1.4, opacity: 0.8 } }, { xAxis: 49, lineStyle: { color: "#336791", type: "solid", width: 1.4, opacity: 0.8 } }, { xAxis: 73, lineStyle: { color: "#336791", type: "solid", width: 1.4, opacity: 0.8 } }, { xAxis: 97, lineStyle: { color: "#336791", type: "solid", width: 1.4, opacity: 0.8 } }, { yAxis: 24, label: { show: true, formatter: "稳态下限 24h", position: "end", distance: 12, color: "#2563eb" }, lineStyle: { color: "#2563eb", type: "dashdot", width: 1.4, opacity: 0.75 } }, { yAxis: 48, label: { show: true, formatter: "窗口峰值 48h", position: "end", distance: 12, color: "#7c3aed" }, lineStyle: { color: "#7c3aed", type: "dashdot", width: 1.4, opacity: 0.75 } } ] } }, { name: 首要备份, type: bar, stack: used, xAxisIndex: 1, yAxisIndex: 1, barWidth: 5, itemStyle: { color: "#59a14f" }, data: [0,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100] }, { name: 次要备份, type: bar, stack: used, xAxisIndex: 1, yAxisIndex: 1, barWidth: 5, itemStyle: { color: "#4e79a7" }, data: [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100] }, { name: WAL归档, type: bar, stack: used, xAxisIndex: 1, yAxisIndex: 1, barWidth: 5, itemStyle: { color: "#edc949" }, data: [0,0.42,0.83,1.25,1.67,2.08,2.5,2.92,3.33,3.75,4.17,4.58,5,5.42,5.83,6.25,6.67,7.08,7.5,7.92,8.33,8.75,9.17,9.58,10,10.42,10.83,11.25,11.67,12.08,12.5,12.92,13.33,13.75,14.17,14.58,15,15.42,15.83,16.25,16.67,17.08,17.5,17.92,18.33,18.75,19.17,19.58,20,10.42,10.83,11.25,11.67,12.08,12.5,12.92,13.33,13.75,14.17,14.58,15,15.42,15.83,16.25,16.67,17.08,17.5,17.92,18.33,18.75,19.17,19.58,20,10.42,10.83,11.25,11.67,12.08,12.5,12.92,13.33,13.75,14.17,14.58,15,15.42,15.83,16.25,16.67,17.08,17.5,17.92,18.33,18.75,19.17,19.58,20,10.42,10.83,11.25,11.67,12.08,12.5,12.92,13.33,13.75,14.17,14.58,15] }, { name: 瞬时备份, type: bar, stack: used, xAxisIndex: 1, yAxisIndex: 1, barWidth: 5, itemStyle: { color: "#9ca3af", opacity: 0.75 }, data: [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,100,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,100,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,100,0,0,0,0,0,0,0,0,0,0,0,0] } ]

全量 + 增量备份

如果使用 Silo / S3 作为集中式备份仓库，存储空间不再受本地磁盘限制， 此时可以用「周全量 + 每日增量」配合两周保留策略，换取更长的恢复窗口：

pg_crontab:  # 周一凌晨1点全量备份，其余每日增量备份
  - '00 01 * * 1           /pg/bin/pg-backup full'
  - '00 01 * * 2,3,4,5,6,7 /pg/bin/pg-backup'
pgbackrest_method: minio
pgbackrest_repo:                  # pgbackrest 仓库配置: https://pgbackrest.org/configuration.html#section-repository
  minio:                          # 可选的 minio 仓库
    type: s3                      # minio 兼容 S3 协议
    s3_endpoint: sss.pigsty       # minio 端点域名，默认为 `sss.pigsty`
    s3_region: us-east-1          # minio 区域，默认 us-east-1，对 minio 无实际意义
    s3_bucket: pgsql              # minio 桶名，默认为 `pgsql`
    s3_key: pgbackrest            # pgbackrest 的 minio 用户访问密钥
    s3_key_secret: S3User.Backup  # 对象存储用户密钥
    s3_uri_style: path            # minio 使用路径风格 URI 而非主机风格
    path: /pgbackrest             # minio 备份路径，默认为 `/pgbackrest`
    storage_port: 9000            # minio 端口，默认 9000
    storage_ca_file: /etc/pki/ca.crt  # minio CA 证书路径，默认 `/etc/pki/ca.crt`
    block: y                      # 启用块级增量备份
    bundle: y                     # 将小文件打包成单个文件
    bundle_limit: 20MiB           # 文件包大小限制，对象存储建议 20MiB
    bundle_size: 128MiB           # 文件包目标大小，对象存储建议 128MiB
    cipher_type: aes-256-cbc      # 为远程备份仓库启用 AES 加密
    cipher_pass: pgBackRest       # 仓库加密密码
    retention_full_type: time     # 按时间保留全量备份
    retention_full: 14            # 按时间保留 14 天

同样假设数据库 100GB、每日增量与 WAL 均按 10GB 粗估，下图推演 30 天内恢复窗口与存储占用的变化： retention_full_type: time 会确保至少留下一份年龄达到 14 天的全量备份，周全备时恢复窗口在 14～21 天 之间循环。 按这组未压缩假设，稳态占用约为 560～690GB，新全量完成、旧链过期前的瞬时峰值约为 790GB； 实际占用取决于 WAL 量、块级增量命中率与 zstd 压缩率。

tooltip: { trigger: axis, formatter: $fn:tipMerged30, axisPointer: { type: line, snap: true, label: { show: false } } }
axisPointer: { link: [ { xAxisIndex: [0, 1] } ] }
legend: { show: false, bottom: 10, itemGap: 18, data: ["基础全量", "追加全量", "增量备份", "WAL归档"] }
grid:
  - { left: 82, right: "10%", top: 42, height: 218, containLabel: false }
  - { left: 82, right: "10%", top: 302, height: 218, containLabel: false }
xAxis:
  - type: value
    gridIndex: 0
    position: bottom
    boundaryGap: false
    min: 0
    max: 31
    interval: 1
    name: 时间
    nameLocation: end
    nameGap: 10
    nameTextStyle: { align: left, verticalAlign: top, padding: [8, 0, 0, 0] }
    axisLabel: { formatter: $fn:fmtDay30 }
    axisLine: { show: true, symbol: [none, arrow], symbolSize: [10, 14], lineStyle: { width: 1.6, color: "#4b5563" } }
    axisTick: { show: true, length: 6 }
    splitLine: { show: true, lineStyle: { type: dashed, width: 1, opacity: 0.28, color: "#9ca3af" } }
    minorTick: { show: true, splitNumber: 4, length: 3 }
    minorSplitLine: { show: true, lineStyle: { type: dotted, width: 1, opacity: 0.14, color: "#9ca3af" } }
  - type: category
    gridIndex: 1
    position: top
    boundaryGap: true
    z: 10
    data: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30]
    axisLabel: { show: false }
    axisLine: { show: true, lineStyle: { width: 1.6, color: "#4b5563" } }
    axisTick: { show: true, alignWithLabel: true, length: 6 }
    splitLine: { show: true, lineStyle: { type: dashed, width: 1, opacity: 0.22, color: "#9ca3af" } }
yAxis:
  - type: value
    gridIndex: 0
    min: 0
    max: 576
    interval: 72
    name: 恢复窗口 h
    nameLocation: end
    nameRotate: 0
    nameGap: 8
    nameTextStyle: { align: left, verticalAlign: bottom, padding: [0, 0, 8, 4] }
    axisLabel: { formatter: $fn:fmtWin30 }
    axisLine: { show: true, symbol: [none, arrow], symbolSize: [10, 14], lineStyle: { width: 1.6, color: "#4b5563" } }
    axisTick: { show: true, length: 6 }
    splitLine: { show: true, lineStyle: { type: dashed, width: 1, opacity: 0.35, color: "#9ca3af" } }
    minorTick: { show: true, splitNumber: 4, length: 3 }
    minorSplitLine: { show: true, lineStyle: { type: dotted, width: 1, opacity: 0.18, color: "#9ca3af" } }
  - type: value
    gridIndex: 1
    min: 0
    max: 800
    interval: 100
    inverse: true
    z: 10
    name: 存储空间 GB
    nameLocation: end
    nameRotate: 0
    nameGap: 8
    nameTextStyle: { align: left, verticalAlign: top, padding: [10, 0, 0, 4] }
    axisLabel: { formatter: $fn:fmtGbTick30 }
    axisLine: { show: true, symbol: [arrow, none], symbolSize: [10, 14], lineStyle: { width: 1.6, color: "#4b5563" } }
    axisTick: { show: true, length: 6 }
    splitLine: { show: true, lineStyle: { type: dashed, width: 1, opacity: 0.32, color: "#9ca3af" } }
series:
  - { name: 恢复窗口, type: line, smooth: false, symbol: none, showSymbol: false, xAxisIndex: 0, yAxisIndex: 0, lineStyle: { width: 3, color: "#f28e2c" }, itemStyle: { color: "#f28e2c" }, data: [[1,0],[2,24],[3,48],[4,72],[5,96],[6,120],[7,144],[8,168],[9,192],[10,216],[11,240],[12,264],[13,288],[14,312],[15,336],[16,360],[17,384],[18,408],[19,432],[20,456],[21,480],[22,504],[22,336],[23,360],[24,384],[25,408],[26,432],[27,456],[28,480],[29,504],[29,336],[30,360]], markLine: { symbol: none, label: { show: false }, data: [ { xAxis: 1, lineStyle: { color: "#336791", type: "solid", width: 1.4, opacity: 0.65 } }, { xAxis: 8, lineStyle: { color: "#336791", type: "solid", width: 1.4, opacity: 0.65 } }, { xAxis: 15, lineStyle: { color: "#336791", type: "solid", width: 1.4, opacity: 0.65 } }, { xAxis: 22, lineStyle: { color: "#336791", type: "solid", width: 1.4, opacity: 0.65 } }, { xAxis: 29, lineStyle: { color: "#336791", type: "solid", width: 1.4, opacity: 0.65 } }, { yAxis: 336, label: { show: true, formatter: "窗口下限 14d", position: "end", distance: 12, color: "#2563eb" }, lineStyle: { color: "#2563eb", type: "dashdot", width: 1.4, opacity: 0.72 } }, { yAxis: 504, label: { show: true, formatter: "窗口上限 21d", position: "end", distance: 12, color: "#7c3aed" }, lineStyle: { color: "#7c3aed", type: "dashdot", width: 1.4, opacity: 0.72 } } ] } }
  - { name: 基础全量, type: bar, stack: used, xAxisIndex: 1, yAxisIndex: 1, barWidth: 16, itemStyle: { color: "#59a14f" }, data: [100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100,100] }
  - { name: 追加全量, type: bar, stack: used, xAxisIndex: 1, yAxisIndex: 1, barWidth: 16, itemStyle: { color: "#4e79a7" }, data: [0,0,0,0,0,0,0,100,100,100,100,100,100,100,200,200,200,200,200,200,200,200,200,200,200,200,200,200,200,200] }
  - { name: 增量备份, type: bar, stack: used, xAxisIndex: 1, yAxisIndex: 1, barWidth: 16, itemStyle: { color: "#76b7b2" }, data: [0,10,20,30,40,50,60,60,70,80,90,100,110,120,120,130,140,150,160,170,180,120,130,140,150,160,170,180,120,130] }
  - { name: WAL归档, type: bar, stack: used, xAxisIndex: 1, yAxisIndex: 1, barWidth: 16, itemStyle: { color: "#edc949" }, data: [0,10,20,30,40,50,60,70,80,90,100,110,120,130,140,150,160,170,180,190,200,140,150,160,170,180,190,200,140,150] }

空间规划

两套策略的空间需求可以按以下经验公式粗估（实际占用受压缩与块级增量影响，通常更低）：

策略 恢复窗口 空间粗估 建议预留
每日全量，保留 2 份（local） 24～48 小时 2 × 全量 + 1～2 天 WAL 数据库大小的 3～5 倍
周全量 + 日增量，按时间保留 14 天（minio） 14～21 天 3 × 全量 + 12～18 份增量 + 14～21 天 WAL 按实测压缩率与 WAL 量规划

注意 瞬时峰值：新的全量备份成功完成后，旧备份才会参与过期计算，因此仓库会短暂多出一份全量备份， 同时保留尚未清理的旧备份链与 WAL。空间规划必须覆盖这个峰值而非只看清理后的稳态。

WAL 归档的增长与写入负载成正比。批量导数、VACUUM FULL、大规模 UPDATE 都会瞬间产生大量 WAL， 如果备份仓库空间紧张，请在此类操作前后关注仓库水位（监控指标 开箱即用）。

应用策略变更

备份策略的三类变更，分别用对应的剧本任务应用：

./pgsql.yml -t pg_crontab -l pg-meta    # 变更调度计划（pg_crontab）后：更新 crontab
./pgsql.yml -t pg_backup  -l pg-meta    # 变更仓库定义（pgbackrest_repo / pgbackrest_method）后：重新渲染配置并初始化 stanza
pg-backup full                          # 切换仓库后：立即执行一次全量备份，建立新仓库中的恢复起点

注意：切换 pgbackrest_method 到新仓库后，旧仓库中的备份不会自动迁移； 在新仓库完成首次全量备份之前，恢复窗口存在缺口。

5.3 - 备份仓库

配置备份存储仓库：本地磁盘、Silo 与外部 S3 对象存储，保留策略、加密、版本控制与对象锁定。

备份存储在哪里，由两个参数决定：pgbackrest_repo 定义所有候选仓库， pgbackrest_method 选择实际使用哪一个。 仓库定义中的键值会 按固定规则 渲染为 pgbackrest 的 repo1-* 配置项， 因此 pgBackRest 支持的任何仓库选项 都可以直接写入。 v4.5.0 每次只把 pgbackrest_method 选中的一个字典项渲染为 repo1；候选项同时存在并不等于多仓备份。

默认仓库

Pigsty 预置了两个仓库定义：local 与 minio。

  • local：默认选项，使用本地 /pg/backup 目录（软链接指向 pg_fs_backup：/data/backups）
  • minio：使用 MINIO 模块部署的 Silo 或任意 S3 兼容对象存储（Pigsty 支持，默认不启用）
pgbackrest_method: local          # 选择备份仓库方法：`local`、`minio` 或其他自定义仓库
pgbackrest_repo:                  # pgbackrest 仓库配置: https://pgbackrest.org/configuration.html#section-repository
  local:                          # 使用本地 POSIX 文件系统的默认 pgbackrest 仓库
    path: /pg/backup              # 本地备份目录，默认为 `/pg/backup`
    retention_full_type: count    # 按数量保留全量备份
    retention_full: 2             # 使用本地文件系统仓库时，保留2个，最多3个全量备份
  minio:                          # 可选的 minio 仓库
    type: s3                      # minio 兼容 S3 协议
    s3_endpoint: sss.pigsty       # minio 端点域名，默认为 `sss.pigsty`
    s3_region: us-east-1          # minio 区域，默认 us-east-1，对 minio 无实际意义
    s3_bucket: pgsql              # minio 桶名，默认为 `pgsql`
    s3_key: pgbackrest            # pgbackrest 的 minio 用户访问密钥
    s3_key_secret: S3User.Backup  # pgbackrest 的 minio 用户密钥
    s3_uri_style: path            # minio 使用路径风格 URI 而非主机风格
    path: /pgbackrest             # minio 备份路径，默认为 `/pgbackrest`
    storage_port: 9000            # minio 端口，默认 9000
    storage_ca_file: /etc/pki/ca.crt  # minio CA 证书路径，默认 `/etc/pki/ca.crt`
    block: y                      # 启用块级增量备份
    bundle: y                     # 将小文件打包成单个文件
    bundle_limit: 20MiB           # 文件包大小限制，对象存储建议 20MiB
    bundle_size: 128MiB           # 文件包目标大小，对象存储建议 128MiB
    cipher_type: aes-256-cbc      # 为远程备份仓库启用 AES 加密
    cipher_pass: pgBackRest       # AES 加密密码，默认为 'pgBackRest'
    retention_full_type: time     # 按时间保留全量备份
    retention_full: 14            # 按时间保留 14 天

两套仓库的预置策略有意不同：local 不加密、不打包、按份数保留，追求简单与恢复速度； minio 加密（AES-256-CBC）、打包（bundle）、块级增量（block）、按时间保留两周，面向生产容灾。

生产环境请修改默认密码

使用远程仓库时，请务必修改默认的 cipher_pass 加密密码与 s3_key_secret 访问密钥。 示例中的 pgBackRest 与 S3User.Backup 是公开默认值，不能直接用于生产环境。 加密密码一旦遗失，仓库中的备份将无法解密恢复 —— 请与备份分开妥善保管，具体要求参阅 部署安全。

保留策略

如果只备份不清理，仓库迟早被撑爆。保留策略在仓库定义中声明，由 pgBackRest 在每次备份后自动执行清理 （全量备份过期时，依附它的差异/增量备份与对应 WAL 归档一并清除）：

  • retention_full_type: count + retention_full: 2：按份数保留 —— 保留最近 2 个全量备份（新备份完成前短暂存在第 3 个）
  • retention_full_type: time + retention_full: 14：按时间保留 —— 至少留下一份年龄达到 14 天的全量备份后，才会删除更老的备份

保留策略与恢复窗口、空间占用的量化关系，请参阅 备份策略； 手动清理过期备份的方法，请参阅 管理命令。

使用 Silo 仓库

MINIO 模块 当前部署 Silo S3 兼容对象存储。 只有把对象存储部署在数据库主机或站点的故障域之外时，它才提供独立的容灾副本。部署对象存储集群后，将备份方法切换为 minio：

all:
  vars:
    pgbackrest_method: minio      # 使用 minio 作为默认备份仓库
  children:                       # 定义一个单节点 minio SNSD 集群
    minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio, minio_type: silo }}

Pigsty 的 minio 仓库预设通过域名（默认 sss.pigsty）和 HTTPS 端点访问对象存储， 并使用自签名 CA（/etc/pki/ca.crt）验证这条链路。 默认的 pgsql 桶与 pgbackrest 访问用户在 MINIO 模块初始化时自动创建。

对于严肃的生产部署，建议使用经过验证的多节点对象存储集群（MNMD，纠删码容错），参阅 MINIO 配置。

pgbackrest_method: minio 是 Pigsty 的 S3 兼容仓库预设名，并不要求服务端必须由 MINIO 模块管理。独立部署和管理的 MinIO、RustFS 或其他 S3 兼容服务也可以使用该预设，但其安装、升级、证书和数据生命周期不在当前 MINIO 角色的支持范围内。

使用 S3 / 云对象存储

如果您只有一个节点，最有意义的备份策略就是使用云厂商的对象存储服务（AWS S3、阿里云 OSS 等）， 以极低的成本获得异地容灾能力。定义一个新仓库并切换过去即可：

pgbackrest_method: s3             # 使用 'pgbackrest_repo.s3' 作为备份仓库
pgbackrest_repo:                  # pgbackrest 仓库配置: https://pgbackrest.org/configuration.html#section-repository

  s3:                             # 阿里云 OSS（S3 兼容）对象存储服务示例
    type: s3                      # oss 兼容 S3 协议
    s3_endpoint: oss-cn-beijing-internal.aliyuncs.com
    s3_region: oss-cn-beijing
    s3_bucket: <your_bucket_name>
    s3_key: <your_access_key>
    s3_key_secret: <your_secret_key>
    s3_uri_style: host            # 云厂商对象存储通常使用主机风格 URI
    path: /pgbackrest
    bundle: y                     # 将小文件打包成单个文件
    bundle_limit: 20MiB           # 文件包大小限制，对象存储建议 20MiB
    bundle_size: 128MiB           # 文件包目标大小，对象存储建议 128MiB
    cipher_type: aes-256-cbc      # 为远程备份仓库启用 AES 加密
    cipher_pass: pgBackRest       # AES 加密密码
    retention_full_type: time     # 按时间保留全量备份
    retention_full: 14            # 按时间保留 14 天

  local:                          # 保留默认本地仓库定义，便于随时切换
    path: /pg/backup
    retention_full_type: count
    retention_full: 2

除 S3 兼容存储外，pgBackRest 还支持以下后端，配置方式参阅官方用户指南：

多集群共享仓库

一个集中式仓库可以同时服务多套 PostgreSQL 集群：pgBackRest 用 stanza （即 pg_cluster）隔离各集群的备份与归档，互不干扰。 这也是 克隆集群 的基础 —— 新集群可以直接从共享仓库中读取源集群的备份进行恢复。

因此，请确保同一仓库下的集群名称 全局唯一，即使它们分属不同的部署环境。

仓库版本控制

对象存储的 版本控制（Versioning）为仓库提供同一存储系统内的版本保护：即使备份文件被覆盖或删除，历史版本仍有机会找回。 它与当前仓库共享同一故障域和管理平面，不能替代独立的异地或离线副本。 您可以在 minio_buckets 中为桶添加 versioning 标志启用：

minio_buckets:
  - { name: pgsql ,versioning: true }
  - { name: meta  ,versioning: true }
  - { name: data }

配合 pgBackRest 的 repo-target-time 选项， 甚至可以把整个仓库"回滚"到过去某一时刻的状态读取 —— 相当于对备份系统本身做时间点恢复。

仓库锁定

部分对象存储（Silo、MinIO、S3 等）支持 对象锁定（Object Lock / WORM）：对对象版本配置保留模式与期限后， 锁定版本在保留期内不可修改、不可永久删除。这是对抗勒索攻击的重要防线，但普通删除仍可能写入 Delete Marker， 暂时隐藏当前对象；恢复时需要保留版本与版本管理能力。

在 minio_buckets 中添加 lock 标志，只会在创建桶时启用对象锁定能力与版本控制：

minio_buckets:
  - { name: pgsql ,lock: true }
  - { name: meta  ,versioning: true }
  - { name: data }

这一步还没有给新对象设置 WORM 保留期。您还需要在 Silo / MinIO 中使用 mcli retention set 或控制台配置默认的 GOVERNANCE / COMPLIANCE 模式与期限，并用 mcli retention info 验证。GOVERNANCE 可以被拥有 bypass 权限的主体绕过； COMPLIANCE 在期限内连 root 用户也不能解除。

锁定会改变 过期清理 与 移除集群备份 的行为：pgBackRest 可以让对象在逻辑上过期，但被锁定的历史版本仍会占用空间，直到保留期结束。上线前应在测试桶中验证 备份、expire、删除标记清理和版本恢复的完整流程。

切换仓库

变更仓库定义或切换 pgbackrest_method 后，需要重新渲染配置、初始化 stanza，并尽快建立新仓库中的恢复起点：

./pgsql.yml -t pg_backup -l pg-meta           # 重新配置并创建 stanza
sudo -iu postgres pg-backup full              # 在当前主库执行全量备份，建立新仓库中的第一个恢复点

旧仓库中的备份不会自动迁移，但在其保留期内仍可作为恢复来源使用（通过 pg_pitr.repo 指定）。

5.4 - 管理命令

备份管理命令手册：启用与移除备份，手动备份，查看与清理，Stanza 管理，日志排查，以及替代备份工具。

备份管理命令应以数据库超级用户（pg_dbsu，默认 postgres）身份在数据库节点上执行。 您可以按习惯选择三种等价的入口：

  • pig pb：pig 命令行工具 的封装 —— 自动检测 stanza、自动切换 DBSU 身份、带安全检查，推荐使用
  • pb：登录 shell 的别名函数，自动填充 --stanza 后转发给 pgbackrest
  • pgbackrest：原生命令，完整选项参阅 pgBackRest 命令参考

命令一览

pig 命令 别名 对应 pgbackrest 命令 说明
pig pb info i info 查看备份与归档状态
pig pb list ls — 列出仓库中的 stanza 与备份
pig pb backup [full/diff/incr] b backup 执行备份（自动检查主库角色）
pig pb restore r restore 恢复（显示计划并确认，详见 恢复操作）
pig pb expire e expire 按保留策略清理过期备份（--plan 预览）
pig pb create c stanza-create 创建 stanza
pig pb upgrade u stanza-upgrade 升级 stanza（版本升级或克隆善后）
pig pb delete d stanza-delete 删除 stanza 及其全部备份
pig pb check ck check 校验备份配置与归档链路
pig pb start up start 恢复 pgbackrest 操作
pig pb stop dw stop 暂停 pgbackrest 操作
pig pb log [list/show/tail] l — 查看 pgbackrest 日志

启用备份

如果集群创建时 pgbackrest_enabled 为 true（默认），备份已自动启用。 若创建时禁用了备份，或修改了仓库配置，可用 pg_backup 子任务补充配置：

./pgsql.yml -t pg_backup -l pg-meta   # 配置 pgbackrest，创建 stanza

集群初始化后 Pigsty 会自动尝试执行一次初始全量备份；只有备份命令成功后才写入 /etc/pgbackrest/initial.done，失败会被剧本忽略且不会留下标记。该文件只防止初始化任务重复执行，最终仍应使用 pig pb info（或 pgbackrest info）核对仓库中的实际备份状态。 定时备份计划通过 pg_crontab 声明，详见 备份策略。

移除备份

pig pb delete 是只删除备份 stanza 的首选入口。它会在实际执行前交互确认；多 stanza 配置还要求显式给出目标。核对目标后执行：

pig pb info -s pg-meta           # 核对当前备份链与恢复窗口
pig pb delete -s pg-meta         # 输入精确 stanza 名确认后才执行

移除主实例（pg_role = primary）时，pgsql-rm.yml 默认也会尝试删除该集群的备份 stanza。以下命令会直接修改或删除状态：

./pgsql-rm.yml -l pg-meta                          # 移除集群及其备份
./pgsql-rm.yml -l pg-meta -e pg_rm_backup=false    # 移除集群但保留备份
./pgsql-rm.yml -l pg-meta -t pg_backup             # 仅删除备份相关状态

执行前应确认近期备份可用、记录恢复需求，并由操作者再次输入精确的集群/stanza 名。使用 pg_rm_backup（设为 false）可以在移除集群时保留备份。

pgsql-rm.yml -t pg_backup 会在主库上强制执行 pgbackrest stanza-delete，删除本地仓库目录（仅 local 模式），并移除 pgBackRest 配置与初始备份标记；该任务会忽略部分删除错误。因此执行后必须再次检查仓库，不能把剧本“成功”当成备份已物理清空的证明。只需要删除 stanza 时，优先使用上面的 pig pb delete，它提供计划与确认保护。

如果备份仓库为对象版本配置了 对象锁定保留期， 删除可能只写入 Delete Marker，被锁定的历史版本会继续占用空间，直到保留期结束。

备份删除

删除备份可能造成永久数据丢失。执行前必须确认目标集群/stanza、核对近期备份与替代恢复副本，并保留 pig pb info/删除计划的审计记录。

手动备份

crontab 之外，随时可以手动触发备份。pg-backup 脚本与 pig pb backup 都带主库角色检查，在从库上执行会直接退出，不会产生错误的备份：

pg-backup            # 增量备份（仓库中无全量备份时自动升级为全量）
pg-backup full       # 全量备份
pg-backup diff       # 差异备份（相对最近一次全量）
pg-backup incr       # 增量备份（相对最近一次任意备份）

pig pb backup full   # 等价：pig 封装，自动检测 stanza 与 DBSU

备份期间会显著占用磁盘 I/O 与网络带宽（并行度已限制在 2～4 进程），建议安排在业务低峰执行。

查看备份

pb info 列出仓库中当前 stanza 的备份与 WAL 归档状态：

pb info          # = pgbackrest --stanza=pg-meta info
pig pb info      # 等价
pig pb list      # 列出仓库中所有 stanza

输出解读的关键是 备份标签： 20250715-013657F 为全量备份（F），..._20250715-013724D 为差异备份（D），..._20250715-013730I 为增量备份（I）—— 下划线前的部分标识备份链所依附的全量备份。wal archive min/max 显示 WAL 归档范围， 它与最早的全量备份共同描述 恢复窗口。

监控系统同样提供备份状态的持续观测：pgbackrest_exporter（端口 9854）导出的 指标 覆盖最近备份时间、类型、大小与错误状态，可直接用于告警。

清理过期备份

保留策略默认在每次备份后自动执行（expire-auto）。手动触发或预览清理计划：

pig pb expire --plan    # 预览将被清理的备份（dry-run，不实际删除）
pig pb expire           # 按保留策略执行清理

Stanza 管理

Stanza 记录集群的备份身份（system-id 与主版本）， 以下场景需要手动管理：

pig pb create             # 创建 stanza：新仓库初始化（Pigsty 集群初始化时自动执行）
pig pb upgrade            # 升级 stanza：PostgreSQL 大版本升级后，或克隆恢复出新集群后
pig pb delete -s pg-meta  # 交互确认后删除全部备份与归档，危险操作！

最常见的手动场景是 克隆集群的善后： 从其他集群的备份恢复出新集群后，stanza 中记录的 system-id 与新集群不符， 必须执行 stanza-upgrade 之后，新集群的备份才能写入仓库。

检查与启停 

pig pb check     # 端到端校验：配置、归档推送、仓库可达性
pig pb stop      # 暂停 pgbackrest 操作（维护窗口，阻止新备份/归档启动）
pig pb start     # 恢复 pgbackrest 操作

check 命令会实际推送一个 WAL 段并确认其到达仓库，是排查"归档不工作"问题的第一步。

查看日志 

pig pb log           # 列出日志文件
pig pb log tail      # 跟踪最新日志
ls /pg/log/pgbackrest/   # 日志目录：备份、归档、恢复各有独立日志文件

使用 pgsql-pitr.yml 时，PostgreSQL 的恢复日志位于 /pg/tmp/recovery.log。

替代备份工具

pg-basebackup

Pigsty 另备有不依赖 pgbackrest 的独立备份脚本 /pg/bin/pg-basebackup， 它使用原生 pg_basebackup 生成单文件物理备份（lz4 压缩 tarball），默认写入 /pg/backup。 适合在不便使用备份仓库时快速留存一份物理副本：

pg-basebackup                        # 生成 /pg/backup/backup_<tag>_<date>.tar.lz4
pg-basebackup --dst /tmp --file backup.tar.lz4   # 指定输出位置与文件名

mkdir -p /tmp/data                   # 解压提取
cat /pg/backup/backup_pg-meta_20250713.tar.lz4 | unlz4 -d -c | tar -xC /tmp/data
加密选项为遗留实现

pg-basebackup -e 使用 OpenSSL RC4 加密 —— 这是一个已被淘汰的弱加密算法，仅作混淆用途， 不应作为机密性保障。需要加密备份时，请使用 pgbackrest 仓库的 AES-256 加密（cipher_type: aes-256-cbc）。

逻辑备份

pg_dump 生成的逻辑备份 不能 用于 PITR，但它是跨大版本迁移、导出部分数据、长期归档快照的正确工具。 物理备份与逻辑备份互为补充，严肃的生产环境通常两者兼备。这是 PostgreSQL 自带的工具，请参阅 官方文档

5.5 - 恢复操作

执行时间点恢复：pgsql-pitr.yml 剧本、pig pitr 命令与 pig pb restore 原语，恢复目标、分步执行与完整参数参考。

Pigsty 提供三个层次的恢复入口，共用 同一套参数语义，按场景选用：

入口 适用场景 特点
pgsql-pitr.yml 剧本 生产集群恢复 编排整个集群：HA 暂停、多节点、etcd 清理、恢复控制信息输出
pig pitr 命令 单节点集群 / 节点本机操作 无需管理节点，在数据库节点上直接编排执行
pig pb restore 原语 非 Patroni 托管的实例 pgbackrest restore 的直接封装，最精细的控制

手把手的沙箱演练教程请参阅 手工恢复； 用恢复克隆出新集群（不影响生产的推荐姿势）请参阅 克隆数据库集群。

PITR 会覆盖目标集群

pgsql-pitr.yml 会暂停 HA、停止 Patroni/PostgreSQL、以 pgbackrest --force restore 覆盖目标数据目录， 随后删除目标集群的 etcd 前缀并重建 HA；它只打印计划，不会等待人工确认。 执行任何实质恢复前，必须先用 pig pg list <目标集群> 核对当前拓扑、用 pig pb info 核对近期备份与恢复窗口， 由操作者复述并确认精确的目标集群与恢复点。生产恢复仍应安排维护窗口并保留独立、已验证的备份。

快速上手

要将 pg-meta 集群回滚到之前的时间点，声明 pg_pitr 参数并运行剧本：

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_pitr: { time: '2025-07-13 10:00:00+00', action: promote }   # 一步执行：到达目标后显式提升
pig pg list pg-meta
pig pb info
./pgsql-pitr.yml -l pg-meta

参数也可以通过命令行临时传入，两种方式等价：

./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": { "time": "2025-07-13 10:00:00+00", "action": "promote" }}'
命令行传参请使用合法 JSON

-e 传入的参数必须是合法 JSON：键与字符串值都要加双引号，例如 {"pg_pitr": {"time": "...", "archive": true}}。 布尔值不加引号，字符串必须加 —— 引号缺失会导致参数解析失败或静默取错值。

剧本会依次执行：暂停 Patroni 高可用 → 停止集群进程 → 执行 pgbackrest 增量还原 → 启动 PostgreSQL 并等待进入一致恢复状态 → 用 pg_controldata 打印控制信息 → 清理 etcd 元数据 → 重新拉起集群与高可用。 执行过程的第一步会打印完整的恢复计划（源集群、目标、还原命令），但不会暂停等待确认；上面的一步式示例因此显式声明了 action: promote。 如果需要在目标点检查数据，请使用下文的 分步执行，并显式选择 action: pause。

恢复目标

pg_pitr 支持 六类恢复目标，其中四类目标值互斥，只能指定一个：

恢复目标类型

default/latest
pg_pitr: { }  # 恢复到最新状态（WAL 归档流末尾）
time
pg_pitr: { time: "2025-07-13 10:00:00+00" }
lsn
pg_pitr: { lsn: "0/4001C80" }
xid
pg_pitr: { xid: "250000" }
name
pg_pitr: { name: "some_restore_point" }
immediate
pg_pitr: { type: "immediate" }

未指定任何目标时，重放全部 WAL 归档恢复到最新状态（内部类型 default）； immediate 类型在到达第一个一致点后立即停止，用于最快恢复出可用实例（例如验证备份）。

按时间恢复

最常用的目标。时间应为合法的 PostgreSQL TIMESTAMP 格式，建议带时区：YYYY-MM-DD HH:MM:SS+TZ：

./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": { "time": "2025-07-13 10:00:00+00", "action": "promote" }}'

按名称恢复

在高危变更前用 pg_create_restore_point 打点，恢复时便有了无歧义的目标：

SELECT pg_create_restore_point('before_migration');
./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": { "name": "before_migration", "action": "promote" }}'

按事务 ID 恢复

如果误删数据的事务号已知（从监控仪表盘或 CSVLOG 的 TXID 字段获取）， 配合 exclusive 精确停在该事务 之前，一条数据都不多丢：

./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": { "xid": "250000", "exclusive": true, "action": "promote" }}'

按 LSN 恢复

LSN（日志序列号）标识 WAL 流中的精确位置， 可从 Pigsty 仪表盘的 PG LSN 面板获取；需要时可以用 timeline 指定目标时间线（默认 latest）：

./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": { "lsn": "0/4001C80", "timeline": "1", "action": "promote" }}'
包含与排除

恢复目标默认是"包含"（inclusive）的：目标点上的事务会被重放。 exclusive: true 排除目标点本身 —— 例如 xid: 250000, exclusive: true 时，最后被重放的是 249999 号之前已提交的事务。 仅适用于 time、xid、lsn 目标，对应 PostgreSQL 的 recovery_target_inclusive。

恢复来源

默认从本集群自己的备份恢复，三个字段可以改变恢复来源：

  • cluster：源 stanza —— 使用共享仓库中 其他集群 的备份恢复（克隆集群 的基础）
  • repo：临时指定备份仓库定义（格式同 pgbackrest_repo 的仓库条目），例如从旧仓库或异地仓库恢复
  • set：从指定的 备份标签 开始还原（默认自动选择目标点前最近的备份集，用 pb info 查看可用标签）
./pgsql-pitr.yml -l pg-meta2 -e '{"pg_pitr": { "cluster": "pg-meta", "archive": false, "action": "promote" }}'           # 用 pg-meta 的备份恢复 pg-meta2
./pgsql-pitr.yml -l pg-meta2 -e '{"pg_pitr": { "cluster": "pg-meta", "time": "2025-07-14 08:00:00+00", "archive": false, "action": "promote" }}' # 并指定时间点

分步执行

一步到位固然方便，但在生产事故中，您可能希望亲手控制每个阶段。剧本的任务树支持用 tags 三步走：

# 确认备份、恢复点和精确目标 pg-meta 后，按顺序执行；不要跳过阶段间检查
./pgsql-pitr.yml -l pg-meta -t down     # 第一步：暂停 HA，停止 patroni 与 postgres
./pgsql-pitr.yml -l pg-meta -t pitr     # 第二步：执行还原与重放，打印恢复控制信息
./pgsql-pitr.yml -l pg-meta -t up       # 第三步：清理 etcd，拉起集群，恢复 HA
# down                 : # 停止高可用并关闭 patroni 和 postgres
#   - pause            : # 暂停 patroni 自动故障切换
#   - stop             : # 停止 patroni 和 postgres 服务
#     - stop_patroni   : # 停止 patroni 服务
#     - stop_postgres  : # 停止 postgres 服务
# pitr                 : # 执行 PITR 过程
#   - config           : # 生成 pgbackrest 配置和恢复脚本
#   - restore          : # 运行 pgbackrest 恢复命令
#   - recovery         : # 启动 postgres 并完成恢复
#   - verify           : # 验证恢复后的集群控制数据
# up:                  : # 启动 postgres / patroni 并恢复高可用
#   - etcd             : # 启动前清理 etcd 元数据
#   - start            : # 启动 patroni 和 postgres 服务
#     - start_postgres : # 启动 postgres 服务
#     - start_patroni  : # 启动 patroni 服务
#   - resume           : # 恢复 patroni 自动故障切换

每步之间您可以检查状态：down 之后确认进程已停；pitr 阶段返回后，先查看 /pg/tmp/recovery.log， 并用 pg_is_in_recovery()、pg_is_wal_replay_paused()、pg_last_wal_replay_lsn() 与 pg_last_xact_replay_timestamp() 确认是否已经到达目标，再结合业务查询抽查数据。pg_controldata /pg/data 提供的是检查点与时间线摘要，不能单独证明时间、XID 或 LSN 目标已经命中。 使用 action: pause 时，确认无误后先提升实例，再执行 up；如果恢复目标选错了，可在 up 之前调整 pg_pitr 重跑 pitr 阶段。 pause / shutdown 需要配合这种分阶段流程才能形成明确的人工门；一步式执行应显式使用 action: promote。

SELECT pg_is_in_recovery(), pg_is_wal_replay_paused(),
       pg_last_wal_replay_lsn(), pg_last_xact_replay_timestamp();
pg_ctl -D /pg/data promote              # action: pause 验证通过后执行
./pgsql-pitr.yml -l pg-meta -t up       # 清理 etcd，拉起 Patroni，恢复 HA
重跑 pitr 阶段

backup: true 会把当前数据目录搬到 /pg/data-backup，而再次运行时会先删除已有的 /pg/data-backup。 因此剧本支持分阶段执行，但不能把带 backup: true 的恢复笼统视为幂等操作。

PITR 参数定义

pg_pitr 的完整字段如下。恢复目标、目标动作与原数据保留方式都建议显式声明：

pg_pitr:                         # 定义 PITR 恢复任务
  cluster: pg-meta               # 恢复来源集群（源 stanza），默认为本集群 pg_cluster
  type: default                  # 目标类型：default | time | xid | name | lsn | immediate
  time: "2025-07-13 10:00:00+00" # 恢复目标：时间点（与 xid / name / lsn 互斥）
  name: "some_restore_point"     # 恢复目标：命名恢复点（与 time / xid / lsn 互斥）
  xid: "250000"                  # 恢复目标：事务 ID（与 time / name / lsn 互斥）
  lsn: "0/4001C80"               # 恢复目标：日志序列号（与 time / xid / name 互斥）
  exclusive: false               # 排除目标点本身，默认包含（仅 time / xid / lsn 有效）
  timeline: latest               # 目标时间线，可为整数，默认 latest
  set: latest                    # 从哪个备份标签开始还原，默认自动选择
  action: pause                  # 到达目标后动作：pause / promote / shutdown
                                 # 指定恢复目标时未声明 action，实际默认 pause
  archive: true                  # 保留原归档配置；探索性恢复设为 false（archive-mode=off）
  backup: false                  # 恢复前将原数据目录搬到 /pg/data-backup；重跑会覆盖已有备份目录
  db_exclude: []                 # 排除的数据库（选择性恢复）
  db_include: []                 # 只恢复指定数据库（选择性恢复）
  link_map:                      # 目录软链接映射（表空间 / WAL 分盘）
    pg_wal: '/data/wal'
    pg_xact: '/data/pg_xact'
  process: 4                     # 恢复并行进程数，默认为节点 CPU 核数
  repo: {}                       # 临时指定恢复来源仓库（格式同 pgbackrest_repo 条目）
  data: /pg/data                 # 恢复到的数据目录
  port: 5432                     # 恢复实例的监听端口

每个字段与 pgbackrest 选项的对应关系，见 参数映射表。

单实例：pig pitr

在数据库节点上，pig pitr 无需 Ansible 环境即可执行单节点恢复编排： 预检（校验目标、stanza 与备份存在性）→ 停止 Patroni 与 PostgreSQL → 执行还原 → 按参数决定是否启动 PostgreSQL → 恢复后指引。

pig pitr -t "2025-07-13 10:00:00+00"    # 恢复到时间点
pig pitr --xid 250000 -X                # 恢复到事务 250000 之前（-X = --exclusive）
pig pitr --name before_migration        # 恢复到命名还原点
pig pitr -d                             # 恢复到 WAL 归档末尾（--default）
pig pitr -I --no-restart                # 只还原并准备 immediate 恢复，PostgreSQL 保持停止
pig pitr -t "..." --plan                # 只显示执行计划，不实际执行

常用选项：-b/--set 指定备份集，-T/--target-timeline 指定时间线，--target-action 指定到达目标后的动作， -D/--data 恢复到其他数据目录（此时必须配合 --no-restart）。 默认只用安全的 fast 模式停库，失败即中止 —— 除非显式给出 --force-stop，才允许升级为强制停库。 对于 Patroni 托管的数据目录，命令恢复后会让 Patroni 保持停止；验证数据后再执行 pig pt start。 pig pitr 不清理 etcd、不重建副本，也不会自动把实例重新加入 HA 集群。 完整选项参阅 pig pitr 命令手册。

原语：pig pb restore

对于 不由 Patroni 托管 的实例（或已明确停管的场景），可以使用最底层的恢复原语 —— 它是 pgbackrest restore 的直接封装，自动处理 stanza、DBSU 与时间格式， 执行前显示恢复计划并要求确认：

pig pb restore --time "2025-07-13 10:00"     # 时间可省略时区与秒，自动按本地时区规范化
pig pb restore --set 20250715-013657F        # 从指定备份集恢复
pig pb restore -d                            # 恢复到归档末尾

两道内置的安全边界值得了解：

  • Patroni 托管实例会被硬拒绝：若 Patroni 服务活跃且目标是其托管的数据目录，pig pb restore 直接报错退出 —— 因为 Patroni 会立刻把恢复到一半的实例重新拉起。托管实例请使用 pig pitr 或 pgsql-pitr.yml。
  • PostgreSQL 必须已停止：实例仍在运行时拒绝执行。

-- 之后可透传原生 pgbackrest 选项（如 --tablespace-map、--link-all）， 但恢复目标、stanza、仓库等关键选项已被封装接管，不允许透传覆盖。详见 pig pb 命令手册。

恢复后处理

恢复完成后，剧本会打印控制信息并重建高可用，但仍有三件事需要确认：

  1. 核对数据：按 分步执行 中的方法检查恢复目标与业务数据。

  2. 重建备份：如果是从其他集群克隆恢复，需要执行 stanza 善后； 无论何种恢复，都建议尽快执行一次全量备份，在新时间线上重建恢复起点：

    pg-backup full

  3. 恢复归档：探索性恢复若设置了 archive: false，归档已被关闭，验证完成后必须恢复 （archive_mode 是 postmaster 参数，需要重启生效）。先确认维护窗口、当前主库和复制状态，再由操作者明确批准重启：

    psql -c 'ALTER SYSTEM RESET archive_mode;'
pg restart pg-meta   # 重启集群使归档配置生效
pg-backup full       # 执行新的全量备份

5.6 - 克隆数据库集群

用 PITR 把一个集群的历史状态恢复到另一个集群：找回误删数据、执行恢复演练，以及必不可少的 Stanza 善后。

克隆是恢复能力最有价值的用法：不动生产集群，把它的历史状态恢复到另一套集群上。 误删数据后从克隆库中导回、定期演练验证备份可用性、审计取证查看历史状态、把测试环境重置为生产某刻的快照 —— 这些场景的操作方式完全相同，本页给出完整流程。

目标集群需要能访问源集群的备份仓库、允许被覆盖，并使用兼容的 PostgreSQL 主版本。使用集中式仓库（Silo / S3）时， 仓库中以 stanza 隔离的各集群备份，对持有相应凭据的目标集群可见。

克隆会覆盖目标集群

先用 pig pg list <目标集群> 核对目标拓扑、用 pig pb info 核对源 stanza 的近期备份与恢复窗口， 并由操作者确认精确的源集群、目标集群和恢复点后实施恢复。 目标集群上原有的数据会被覆盖；生产操作仍需维护窗口和独立、已验证的备份。

克隆现有集群

假设四节点沙箱中有 pg-meta 与 pg-test 两套集群，共享 Silo 备份仓库。 要把 pg-test 重置为 pg-meta 的 最新状态，只需在 pg_pitr 中把恢复来源指向 pg-meta 的 stanza：

pig pg list pg-test
pig pb info
./pgsql-pitr.yml -l pg-test -e '{"pg_pitr": { "cluster": "pg-meta", "archive": false, "action": "promote" }}'

配合恢复目标，可以克隆到恢复窗口内的 任意时间点 —— 例如把 pg-test 重置为 pg-meta 在 2025 年 12 月 26 日 15:30 的状态：

./pgsql-pitr.yml -l pg-test -e '{"pg_pitr": { "cluster": "pg-meta", "time": "2025-12-26 15:30:00+08", "archive": false, "action": "promote" }}'

跨集群克隆显式设置 archive: false，在独立恢复阶段关闭归档；Patroni 接管后按下面的步骤处理目标 stanza 与归档。

目标集群也可以是全新创建的空集群：先用标准流程 创建集群（如 pg-meta2）， 再对它执行跨集群 PITR，即完成了"从备份仓库引导新集群"。

pgBackRest 的还原是增量的（delta）：只重写与备份不一致的文件。 因此对反复执行的演练、或已通过 备份集群（Standby Cluster） 物理复制拉齐过数据的目标集群，克隆速度会显著快于首次全量还原。

误删数据的典型找回流程到这里只剩最后一步：在克隆集群中验证数据无误后， 用 pg_dump 导出受影响的表/库，导回生产集群。全库原地回滚是最后手段，而不是第一反应。

克隆善后

克隆出的新集群带着 源集群的数据，但备份仓库中它自己的 stanza 仍记录着 原来的身份（system-id）。 pgBackRest 写入备份前会核对身份，不一致即拒绝 —— 这个保护机制防止新集群的备份污染源集群的备份历史。

因此，确认克隆结果符合预期后，必须执行三步善后，新集群的备份链路才能恢复正常。 其中集群重启是服务变更：先核对主库、复制状态和维护窗口，并获得明确批准：

pb stanza-upgrade                          # 1. 升级 stanza，接纳新集群的 system-id（仅跨集群克隆需要）
psql -c 'ALTER SYSTEM RESET archive_mode;' # 2. 恢复归档（本文跨集群示例显式设置了 archive: false）
pg restart pg-test                         #    archive_mode 为 postmaster 参数，重启生效
pg-backup full                             # 3. 全量备份，让新集群从此刻起拥有自己的备份历史

跳过善后的后果是可预期的：下一次例行备份会因身份核对失败而报错， 在此期间新集群 没有备份保护（如果关闭了归档，也不会产生新的 WAL 归档）：

postgres@pg-test-1:~$ pb backup
INFO: backup command begin 2.57.0: --annotation=pg_cluster=pg-test ... --stanza=pg-test --start-fast
ERROR: [051]: PostgreSQL version 18, system-id 7588470953413201282 do not match stanza version 18, system-id 7588470974940466058
       HINT: is this the correct stanza?
INFO: backup command end: aborted with exception [051]

重建备份身份

stanza-upgrade 让新集群沿用原 stanza 继续写备份。如果您希望新集群拥有 全新的备份历史 （例如克隆出的集群将长期独立演化），也可以选择彻底重建其备份配置 —— 声明式方式：

pig pb info -s pg-test           # 核对现有备份与恢复窗口
pig pb delete -s pg-test         # 输入精确 stanza 名确认后执行
./pgsql.yml -t pg_backup -l pg-test          # 创建全新 stanza
pg-backup full                               # 建立第一个恢复点

或者用 pgbackrest 原语 手动完成同样的事情：

pig pb stop                       # 暂停 pgbackrest 操作
pig pb delete -s pg-test          # 确认精确目标后删除
pig pb start                      # 恢复 pgbackrest 操作
pig pb create -s pg-test          # 以当前集群身份重建 stanza
pig pb backup full -s pg-test     # 建立第一个恢复点
重建会永久丢弃旧恢复历史

只有在已经核对近期备份、保留了需要的独立恢复副本，并由操作者确认精确的 pg-test stanza 后，才可执行删除。对象锁定仓库中的历史版本可能继续保留并占用空间；删除命令成功不等于底层版本已经物理清空。

在线副本：备份集群

克隆得到的是 静态的时间点快照。如果需要的是持续跟随源集群的 在线副本， 应使用 备份集群（Standby Cluster，基于流复制）； 需要"一直落后一小时"的快速反悔窗口，则使用 延迟集群。

三者互为补充：备份集群提供实时副本，延迟集群提供固定延迟的反悔窗口， PITR 克隆提供恢复窗口内的历史快照 —— 且不需要提前准备在线副本。

恢复演练

克隆是 不触碰生产集群的恢复演练：目标集群会被覆盖，但它能端到端验证备份系统的每个环节。 建议将以下演练纳入例行运维（每季度，或每次重大变更后）：

  1. 选定演练目标：生产集群恢复窗口内的某个时间点；
  2. 向演练集群执行跨集群 PITR，记录耗时 —— 这就是实测的 PITR RTO；
  3. 验证数据完整性：行数抽查、关键业务表校验、应用连通测试；
  4. 执行 克隆善后，确认演练集群自身备份恢复正常（验证善后流程本身也是演练的一部分）；
  5. 记录结果：恢复耗时、发现的问题、文档与实际操作的出入。

沙箱环境中使用 pgbackrest 原语手工执行恢复的完整教程，参阅 手工恢复； 在同一台机器上用 XFS 快照快速 Fork 实例的进阶技巧，参阅 Fork 实例。

6 - 数据迁移

如何将现有的 PostgreSQL 集群以最小的停机时间迁移至新的、由 Pigsty 管理的 PostgreSQL 集群？

Pigsty 内置了一个剧本 pgsql-migration.yml，基于逻辑复制来实现在线数据库迁移。

通过预生成的自动化脚本，应用停机时间可以缩减到几秒内。但请注意，逻辑复制需要 PostgreSQL 10 以上的版本才能工作。

当然如果您有充足的停机时间预算，那么总是可以使用 pg_dump | psql 的方式进行停机迁移。

定义迁移任务

想要使用 Pigsty 提供的在线迁移剧本，您需要创建一个定义文件，来描述迁移任务的细节。

请查看任务定义文件示例作为参考： files/migration/pg-meta.yml。

这个迁移任务要将 pg-meta.meta 在线迁移到 pg-test.test，前者称为 源集群（SRC）， 后者称为 宿集群（DST）。

pg-meta-1	10.10.10.10  --> pg-test-1	10.10.10.11 (10.10.10.12,10.10.10.13)

基于逻辑复制的迁移以数据库为单位，您需要指定需要迁移的数据库名称，以及数据库源宿集群主节点的 IP 地址，以及超级用户的连接信息。

---
#-----------------------------------------------------------------
# PG_MIGRATION
#-----------------------------------------------------------------
context_dir: ~/migration  # 迁移手册 & 脚本的放置目录
#-----------------------------------------------------------------
# SRC Cluster (旧集群)
#-----------------------------------------------------------------
src_cls: pg-meta      # 源集群名称                  <必填>
src_db: meta          # 源数据库名称                <必填>
src_ip: 10.10.10.10   # 源集群主 IP                <必填>
#src_pg: ''            # 如果定义，使用此作为源 dbsu pgurl 代替：
#                      # postgres://{{ pg_admin_username }}@{{ src_ip }}/{{ src_db }}
#                      # 例如: 'postgres://dbuser_dba:[email protected]:5432/meta'
#sub_conn: ''          # 如果定义，使用此作为订阅连接字符串代替：
#                      # host={{ src_ip }} dbname={{ src_db }} user={{ pg_replication_username }}'
#                      # 例如: 'host=10.10.10.10 dbname=meta user=replicator password=DBUser.Replicator'
#-----------------------------------------------------------------
# DST Cluster (新集群)
#-----------------------------------------------------------------
dst_cls: pg-test      # 宿集群名称                  <必填>
dst_db: test          # 宿数据库名称                 <必填>
dst_ip: 10.10.10.11   # 宿集群主 IP                <必填>
#dst_pg: ''            # 如果定义，使用此作为目标 dbsu pgurl 代替：
#                      # postgres://{{ pg_admin_username }}@{{ dst_ip }}/{{ dst_db }}
#                      # 例如: 'postgres://dbuser_dba:[email protected]:5432/test'
#-----------------------------------------------------------------
# PGSQL
#-----------------------------------------------------------------
pg_dbsu: postgres
pg_replication_username: replicator
pg_replication_password: DBUser.Replicator
pg_admin_username: dbuser_dba
pg_admin_password: DBUser.DBA
pg_monitor_username: dbuser_monitor
pg_monitor_password: DBUser.Monitor
#-----------------------------------------------------------------
...

默认情况下，源宿集群两侧的超级用户连接串会使用全局的管理员用户和各自主库的 IP 地址拼接而成，但您总是可以通过 src_pg 和 dst_pg 参数来覆盖这些默认值。 同理，您也可以通过 sub_conn 参数来覆盖订阅连接串的默认值。

生成迁移计划

此剧本不会主动完成集群的迁移工作，但它会生成迁移所需的操作手册与自动化脚本。

默认情况下，你会在 ~/migration/pg-meta.meta 下找到迁移上下文目录。 按照 README.md 的说明，依次执行这些脚本，你就可以完成数据库迁移了！

# 激活迁移上下文：启用相关环境变量
. ~/migration/pg-meta.meta/activate

# 这些脚本用于检查 src 集群状态，并帮助在 pigsty 中生成新的集群定义
./check-user     # 检查 src 用户
./check-db       # 检查 src 数据库
./check-hba      # 检查 src hba 规则
./check-repl     # 检查 src 复制身份
./check-misc     # 检查 src 特殊对象

# 这些脚本用于在现有的 src 集群和由 pigsty 管理的 dst 集群之间建立逻辑复制，除序列外的数据将实时同步
./copy-schema    # 将模式复制到目标
./create-pub     # 在 src 上创建发布
./create-sub     # 在 dst 上创建订阅
./copy-progress  # 打印逻辑复制进度
./copy-diff      # 通过计数表快速比较 src 和 dst 的差异

# 这些脚本将在线迁移中运行，该迁移将停止 src 集群，复制序列号（逻辑复制不复制序列号！）
./copy-seq [n]   # 同步序列号，如果给出了 n，则会应用额外的偏移

# 你必须根据你的访问方式（dns,vip,haproxy,pgbouncer等），将应用流量切换至新的集群！
#./disable-src   # 将 src 集群访问限制为管理节点和新集群（你的实现）
#./re-routing    # 从 SRC 到 DST 重新路由应用流量！（你的实现）

# 然后进行清理以删除订阅和发布
./drop-sub       # 迁移后在 dst 上删除订阅
./drop-pub       # 迁移后在 src 上删除发布

注意事项

如果担心拷贝序列号时出现主键冲突，您可以在拷贝时将所有序列号向前推进一段距离，例如 +1000，你可以使用 ./copy-seq 加一个参数 1000 来实现这一点。

你必须实现自己的 ./re-routing 脚本，以将你的应用流量从 src 路由到 dst。 因为我们不知道你的流量是如何路由的（例如 dns, VIP, haproxy 或 pgbouncer）。 当然，您也可以手动完成这项操作…

你可以实现一个 ./disable-src 脚本来限制应用对 src 集群的访问，这是可选的：如果你能确保所有应用流量都在 ./re-routing 中干净利落地切完，其实不用这一步。

但如果您有未知来源的各种访问无法梳理干净，那么最好使用更为彻底的方式：更改 HBA 规则并重新加载来实现（推荐），或者只是简单粗暴地关停源主库上的 postgres、pgbouncer 或 haproxy 进程。

7 - 任务教程

如何去完成单个任务。每个任务页面是一般通过给出若干步骤展示如何执行完成某事。

7.1 - 故障排查

常见故障与分析排查思路

本文档列举了 PostgreSQL 和 Pigsty 中可能出现的故障，以及定位、处理、分析问题的 SOP。

磁盘空间写满

磁盘空间写满是最常见的故障类型。

现象

当数据库所在磁盘空间耗尽时，PostgreSQL 将无法正常工作，可能出现以下现象：数据库日志反复报错"no space left on device"（磁盘空间不足）， 新数据无法写入，甚至 PostgreSQL 可能触发 PANIC 强制关闭。

Pigsty 带有 NodeFsSpaceFull 告警规则，当文件系统可用空间不足 10% 时触发告警。 使用监控系统 NODE Instance 面板查阅 FS 指标面板定位问题。

诊断

您也可以登录数据库节点，使用 df -h 查看各挂载盘符使用率，确定哪个分区被写满。 对于数据库节点，重点检查以下目录及其大小，以判断是哪个类别的文件占满了空间：

  • 数据目录（/pg/data/base）：存放表和索引的数据文件，大量写入与临时文件需要关注
  • WAL 目录（如 pg/data/pg_wal）：存放 PG WAL，WAL 堆积/复制槽保留是常见的磁盘写满原因。
  • 数据库日志目录（如 pg/log）：如果 PG 日志未及时轮转写大量报错写入，也可能占用大量空间。
  • 本地备份目录（如 data/backups）：使用 pgBackRest 等在本机保存备份时，也有可能撑满磁盘。

如果问题出在 Pigsty 管理节点或监控节点，还需考虑：

  • 监控数据：VictoriaMetrics 的时序指标和 VictoriaLogs 日志存储都会占用磁盘，可检查保留策略。
  • 对象存储数据：Pigsty 集成的 Silo 对象存储可能会被用于 PG 备份保存。

明确占用空间最大的目录后，可进一步使用 du -sh <目录> 深入查找特定大型文件或子目录。

处理

磁盘写满属于紧急问题，需立即采取措施释放空间并保证数据库继续运行。 当数据盘并未与系统盘区分时，写满磁盘可能导致 Shell 命令无法执行。这种情况下，可以删除 /pg/dummy 占位文件，释放少量应急空间以便 shell 命令恢复正常。 如果数据库由于 pg_wal 写满已经宕机，清理空间后需要重启数据库服务并仔细检查数据完整性。

事务号回卷

PostgreSQL 循环使用 32 位事务 ID (XID)，耗尽时会出现"事务号回卷"故障（XID Wraparound）。

现象

第一阶段的典型征兆是 PGSQL Persist - Age Usage 面板年龄饱和度进入警告区域。 数据库日志开始出现：WARNING: database "postgres" must be vacuumed within xxxxxxxx transactions 字样的信息。

若问题持续恶化，PostgreSQL 会进入保护模式：当剩余事务 ID 不到约100万时数据库切换为只读模式；达到上限约21亿（2^31）时则拒绝任何新事务并迫使服务器停机以避免数据错误。

诊断

PostgreSQL 与 Pigsty 默认启用自动垃圾回收（AutoVacuum），因此此类故障出现通常有更深层次的根因。 常见的原因包括：超长事务（SAGE），Autovacuum 配置失当，复制槽阻塞，资源不足，存储引擎/扩展 BUG，磁盘坏块。

首先定位年龄最大的数据库，然后可通过 Pigsty PGCAT Database - Tables 面板来确认表的年龄分布。 同时查阅数据库错误日志，通常可以找到定位根因的线索。

处理

  1. 立即冻结老事务：如果数据库尚未进入只读保护状态，立刻对受影响的库执行一次手动 VACUUM FREEZE。可以从老化最严重的表开始逐个冻结，而不是整库一起做，以加快效果。使用超级用户连接数据库，针对识别出的 relfrozenxid 最大的表运行 VACUUM FREEZE 表名;，优先冻结那些 XID 年龄最大的表元组。这样可以迅速回收大量事务 ID 空间。
  2. 单用户模式救援：如果数据库已经拒绝写入或宕机保护，此时需要启动数据库到单用户模式执行冻结操作。在单用户模式下运行 VACUUM FREEZE database_name; 对整个数据库进行冻结清理。完成后再以多用户模式重启数据库。这样做可以解除回卷锁定，让数据库重新可写。需要注意在单用户模式下操作要非常谨慎，并确保有足够的事务 ID 余量完成冻结。
  3. 备用节点接管：在某些复杂场景（例如遭遇硬件问题导致 vacuum 无法完成），可考虑提升集群中的只读备节点为主，以获取一个相对干净的环境来处理冻结。例如主库因坏块导致无法 vacuum，此时可以手动 Failover 提升备库为新的主库，再对其进行紧急 vacuum freeze。确保新主库已冻结老事务后，再将负载切回来。

连接耗尽

PostgreSQL 有一个最大连接数配置 (max_connections)，当客户端连接数超过此上限时，新的连接请求将被拒绝。典型现象是在应用端看到数据库无法连接，并报出类似 FATAL: remaining connection slots are reserved for non-replication superuser connections 或 too many clients already 的错误。 这表示普通连接数已用完，仅剩下保留给超管或复制的槽位

诊断

连接耗尽通常由客户端大量并发请求引起。您可以通过 PGCAT Instance / PGCAT Database / PGCAT Locks 直接查阅数据库当前的活跃会话。 并判断是什么样的查询填满了系统，并进行进一步的处理。特别需要关注是否存在大量 Idle in Transaction 状态的连接以及长时间运行的事务（以及慢查询）。

处理

杀查询：对于已经耗尽导致业务受阻的情况，通常立即使用 pg_terminate_backend(pid) 进行紧急降压。 对于使用连接池的情况，则可以调整连接池大小参数，并执行 reload 重载的方式减少数据库层面的连接数量。

您也可以修改 max_connections 参数为更大的值，但本参数需要重启数据库后才能生效。

etcd 配额写满

etcd 配额写满将导致 PG 高可用控制面失效，无法进行配置变更。

诊断

Pigsty 在实现高可用时使用 etcd 作为分布式配置存储(DCS)，etcd 自身有一个存储配额（默认约为2GB）。 当 etcd 存储用量达到配额上限时，etcd 将拒绝写入操作，报错 “etcdserver: mvcc: database space exceeded"。在这种情况下，Patroni 无法向 etcd 写入心跳或更新配置，从而导致集群管理功能失效。

解决

在 Pigsty v2.0.0 - v2.5.1 之间的版本默认受此问题影响。Pigsty v2.6.0 为部署的 etcd 新增了自动压实的配置项，如果您仅将其用于 PG 高可用租约，则常规用例下不会再有此问题。

有缺陷的存储引擎

目前，TimescaleDB 的试验性存储引擎 Hypercore 被证实存在缺陷，已经出现 VACUUM 无法回收出现 XID 回卷故障的案例。 请使用该功能的用户及时迁移至 PostgreSQL 原生表或者 TimescaleDB 默认引擎

详细介绍：《PG新存储引擎故障案例》

7.2 - 误删处理

处理误删数据，误删表，误删数据库

误删数据

如果是小批量 DELETE 误操作，可以考虑使用 pg_surgery 或者 pg_dirtyread 扩展进行原地手术恢复。

-- 立即关闭此表上的 Auto Vacuum 并中止 Auto Vacuum 本表的 worker 进程
ALTER TABLE public.some_table SET (autovacuum_enabled = off, toast.autovacuum_enabled = off);

CREATE EXTENSION pg_dirtyread;
SELECT * FROM pg_dirtyread('tablename') AS t(col1 type1, col2 type2, ...);

如果被删除的数据已经被 VACUUM 回收，那么使用通用的误删处理流程。

误删对象

当出现 DROP/DELETE 类误操作，通常按照以下流程决定恢复方案。

  1. 确认此数据是否可以通过业务系统或其他数据系统找回，如果可以，直接从业务侧修复。
  2. 确认是否有延迟从库，如果有，推进延迟从库至误删时间点，查询出来恢复。
  3. 如果数据已经确认删除，确认备份信息，恢复范围是否覆盖误删时间点，如果覆盖，开始 PITR
  4. 确认是整集群原地 PITR 回滚，还是先 克隆新集群 验证数据，还是用从库来重放，并执行恢复策略

误删集群

如果出现整个数据库集群通过 Pigsty 管理命令被误删的情况，例如错误的执行 pgsql-rm.yml 剧本或 bin/pgsql-rm 命令。 除非您指定了 pg_rm_backup 参数为 false，否则备份会与数据库集群一起被删除。

警告：在这种情况，您的数据将无法找回！请务必三思而后行！

建议：对于生产环境，您可以在配置清单中全局配置此参数为 false，在移除集群时保留备份。

7.3 - 手工 PITR 演练

在隔离沙箱中分阶段执行、验证并收尾 PostgreSQL 时间点恢复。

本教程在 Pigsty v4.5.0 的四节点沙箱中演练 PostgreSQL 时间点恢复。核心路径使用 pgsql-pitr.yml 的 down → pitr → up 三阶段，让操作者在覆盖数据、提升时间线和重建 HA 之前分别停下来验证。

如果只恢复当前节点，可使用 pig pitr；如果需要直接控制 pgBackRest，可参考 pg-pitr 低层工具。

只在可丢弃沙箱中照做

恢复会停止 Patroni/PostgreSQL，并以 pgbackrest --force restore 覆盖目标 PGDATA；up 阶段还会删除目标集群的 etcd 前缀并重建 Patroni 状态。剧本会打印计划，但 没有交互确认。生产操作前必须由操作者明确说出并确认精确集群名与恢复点，核对近期可用且独立验证过的备份，使用完全相同的 -l、变量与标签先运行 --check，并安排维护窗口。本教程不授权在任何生产环境执行这些命令。

准备隔离沙箱

使用 Vagrant 或其他可丢弃的四节点实验环境，并选用自带 Silo 备份仓库的 ha/full 模板：

curl -fsSL https://repo.pigsty.io/get | bash
cd ~/pigsty
./configure -c ha/full
./deploy.yml

ha/full 定义单节点 pg-meta、三节点 pg-test 与 Silo/pgBackRest 仓库。本教程以下使用精确目标 pg-meta，避免把示例选择器复制到其他环境。

初始部署和备份都会改变沙箱状态；生产环境必须另行履行部署与备份审批流程。

建立恢复证据

先只读检查拓扑、备份链与 WAL 范围：

pig pg list pg-meta
sudo -iu postgres pig pb info
sudo -iu postgres pig pb check

info 中至少应有 status: ok 的可用备份，并且归档 WAL 覆盖目标时间。check 能检查当前 stanza 与归档链路，但不能替代真实恢复演练或独立副本验证。

在沙箱中，可以运行 Pigsty 心跳脚本生成易验证的时间序列：

sudo -iu postgres /pg/bin/pg-heartbeat

记录以下信息，随后停止负载：

  • 准备恢复到的带时区时间戳；
  • 该时刻前后的心跳、LSN 与事务边界；
  • 当前主库、时间线和备份标签；
  • 目标集群名 pg-meta 与目标节点。

对真实业务表的检查需要单独授权；本教程只使用沙箱心跳数据。

声明恢复任务

在沙箱清单的 pg-meta.vars 中声明恢复目标：

pg_pitr:
  cluster: pg-meta
  time: "2026-08-13 10:00:00+08"
  action: pause
  archive: true
  backup: false
  • cluster 是备份源 stanza；缺省为目标 pg_cluster。
  • action: pause 让 PostgreSQL 到达目标后暂停，给人工验证留下闸门。
  • archive: true 保留归档设置。
  • backup: true 不是安全备份替代品：它会先删除已有的 <pg_data>-backup，再移动当前 PGDATA，因此这里保持 false。

也可以用 -e 临时传入同一对象，但三个阶段与预检必须逐字复用同一份有效 JSON，避免变量漂移。

完整预检

在任何停服或写入动作前，对完整工作流执行同目标预检：

./pgsql-pitr.yml -l pg-meta --check

检查 Ansible 解析出的唯一目标确实是 pg-meta，并核对输出中的：

  • 源 stanza、恢复类型、时间、时间线与动作；
  • 目标 pg_data、端口和仓库；
  • 表空间/软链接映射；
  • archive 与 backup 行为。

--check 只验证清单、变量和任务选择，不能证明 pgBackRest 备份能够恢复。目标、备份或变量一旦变化，就必须重新预检。

阶段一：停服

只有在操作者再次确认精确目标 pg-meta、恢复点与维护窗口后，才执行：

./pgsql-pitr.yml -l pg-meta -t down

down 会尝试暂停 Patroni 自动故障转移，停止所有目标成员的 Patroni，并在 PostgreSQL 仍运行时执行 immediate shutdown。随后在每个目标节点确认服务确实停止；不要只相信剧本返回码：

sudo systemctl is-active patroni
sudo -iu postgres pg_ctl -D /pg/data status

预期分别为 inactive 和“server is not running”。如果任何成员仍在运行，停止流程并排障，不要进入恢复阶段。

阶段二：恢复并验证

再次核对 pg_pitr 与目标节点后执行破坏性的恢复阶段：

./pgsql-pitr.yml -l pg-meta -t pitr

该阶段会：

  1. 生成 /pg/conf/pitr.conf 与 /pg/bin/pg-restore；
  2. 根据 backup 决定是否移动原 PGDATA；
  3. 创建目标目录并运行带 --force、delta=y 的 pgBackRest restore；
  4. 直接启动 PostgreSQL并等待日志出现 consistent recovery state；
  5. 打印 pg_controldata 摘要。

控制信息只能证明数据目录具有可读的控制状态，不能证明指定时间、XID 或业务状态正确。使用 action: pause 时，确认 WAL 已到达并暂停在目标附近：

sudo -iu postgres psql -p 5432 -Atqc \
  'SELECT pg_is_in_recovery(), pg_is_wal_replay_paused(), pg_last_wal_replay_lsn(), pg_last_xact_replay_timestamp()'

然后只检查获授权的最小数据范围；在沙箱中可检查心跳记录。若目标不对：

  1. 保持所有 Patroni 停止；
  2. 停止手工启动的 PostgreSQL；
  3. 修改恢复目标并重新运行完整 --check；
  4. 再执行 pitr 阶段。

不要运行 up，也不要让旧时间线上的副本重新接入。

提升与阶段三：重建 HA

只有操作者确认恢复结果正确且接受创建新时间线后，才提升恢复实例：

sudo -iu postgres pg_ctl -D /pg/data promote
sudo -iu postgres psql -p 5432 -Atqc 'SELECT pg_is_in_recovery()'

预期结果为 f。提升不是只读验证，也不能无损撤销。

在所有 Patroni 成员仍停止、精确目标仍为 pg-meta 的前提下，再执行：

./pgsql-pitr.yml -l pg-meta -t up

up 会在主库节点对应的 etcd 中删除 /pg/pg-meta/ 前缀（实际前缀还受 pg_namespace/Citus 配置影响），停止手工 PostgreSQL，启动主库 Patroni，再逐个启动副本并恢复 HA。etcd 删除任务设置了错误容忍，因此成功返回也不能证明旧 DCS 状态已正确清除。

恢复后验收

逐项验证，不要把“服务启动”当成恢复完成：

pig pg list pg-meta
sudo -iu postgres psql -Atqc \
  "SELECT pg_is_in_recovery(), pg_current_wal_lsn(), current_setting('archive_mode')"
sudo -iu postgres pig pb check

还应确认：

  • 只有预期成员成为主库，副本来自新时间线且复制正常；
  • HAProxy/VIP/DNS 和应用流量只指向已验收的实例；
  • 恢复点附近的数据与事件边界正确；
  • archive_mode、archive_command 和新 WAL 归档正常；
  • 监控、告警与备份仓库没有旧集群残留。

确认新时间线稳定后，按审批流程执行新的全量备份并再次核验：

sudo -iu postgres pg-backup full
sudo -iu postgres pig pb info

如果本次恢复显式使用了 archive: false，它会写入 archive-mode=off。只有在验证恢复结果并确认维护窗口后，才重置该覆盖项并通过受控重启使 archive_mode 生效；默认 archive: true 不需要这一步。

多节点与跨集群恢复

  • 多节点恢复后，旧时间线副本不能未经验证直接重新加入；up 会逐个启动副本并等待克隆/恢复，必须监控完成状态。
  • 从另一 stanza 恢复时，pg_pitr.cluster 是源，-l 仍是被覆盖的目标。把两者分别写进变更单并逐一复述。
  • 跨集群恢复通常应使用 archive: false，避免测试目标向源 stanza 写入 WAL；验收并完成 stanza 善后 后再启用自己的归档。
  • link_map、data、port 与临时 repo 会改变真正的数据与存储目标，必须纳入 --check 和人工复核。

相关文档

7.4 - 克隆与旁路恢复 PostgreSQL 实例

使用 pg-fork 创建本机物理副本，并以 pg-pitr 对停止的数据目录执行低层恢复。

Pigsty v4.5.0 提供两个本机 Shell 工具：

  • pg-fork：复制一个 PostgreSQL 数据目录，并为副本设置独立端口。
  • pg-pitr：调用 pgBackRest，将一个 已停止 的数据目录恢复到指定目标。

它们适合沙箱演练、旁路取证和临时测试，不是完整的 Patroni 集群恢复编排器。托管实例优先使用 pig pitr；多节点集群优先使用分阶段的 pgsql-pitr.yml。

先确认路径、备份和停机状态

pg-fork 会递归删除已存在的目标目录；pg-pitr 会用备份覆盖目标目录。两者在非交互环境都可能不经确认直接执行。真实运行前必须核对源与目标的绝对路径、端口、表空间、精确集群/实例身份，并确认有独立、近期且经过验证的备份。不要把刚创建的 CoW 克隆当作独立备份。

pg-fork

pg-fork 在当前节点上复制 PostgreSQL 数据目录。以数据库操作系统用户（通常为 postgres，至少属于 postgres 组）执行：

pg-fork 1                         # /pg/data -> /pg/data1，目标端口 15432
pg-fork 2 -d /pg/data1            # /pg/data1 -> /pg/data2，目标端口 25432
pg-fork 3 -D /srv/pg-clone -P 55432

参数 

pg-fork <FORK_ID> [options]
参数 含义 默认值
<FORK_ID> 单个数字 1–9，用于推导默认目录和端口 必填
-d, --data <path> 源数据目录 $PG_DATA 或 /pg/data
-D, --dst <path> 目标数据目录 /pg/data<FORK_ID>
-p, --port <port> 源实例端口 $PG_PORT 或 5432
-P, --dst-port <port> 目标实例端口 <FORK_ID>5432
-s, --skip 跳过在线备份 API，强制冷拷贝 否
-y, --yes 跳过交互确认 否

脚本会拒绝相同的规范化源/目标路径，但不会判断自定义目标目录是否属于其他重要数据。目标目录存在时，它会在复制前执行递归删除。

热备份与冷拷贝

默认情况下，脚本用目标端口连接源实例，在同一个 psql 会话中执行：

  1. CHECKPOINT；
  2. pg_backup_start()；
  3. rm -rf <目标> 与 cp -a --reflink=auto；
  4. pg_backup_stop(wait_for_archive => false)。

如果无法通过指定端口连接源实例，脚本会 自动降级为冷拷贝，而不是中止。-s 也会强制冷拷贝。只有确认源实例已经完全停止时，冷拷贝才是安全的；postmaster.pid 只能作为警告线索，不能证明进程状态。

同一文件系统上，脚本会将以下文件系统识别为快速 CoW 模式：启用 reflink 的 XFS、Btrfs、Bcachefs 和 OCFS2。其他文件系统或跨文件系统目标仍执行 cp --reflink=auto，但可能退化为完整复制。脚本帮助中的 ZFS 描述比当前探测逻辑更宽；v4.5.0 实现不会把 ZFS 标记为已确认的快速 CoW 模式。

副本配置

复制成功后，pg-fork 会：

  • 删除目标中的 postmaster.pid、postmaster.opts 与 standby.signal；
  • 清空目标中的物理复制槽目录；
  • 在目标 postgresql.auto.conf 中设置独立 port、archive_mode=off 与本地 log_directory；
  • 删除 primary_conninfo、primary_slot_name 与旧的 recovery_target* 覆盖项。

脚本不会检查目标端口是否空闲，也不会调整内存参数。启动副本前，至少核对：

postgres -D /pg/data1 -C port
postgres -D /pg/data1 -C archive_mode
postgres -D /pg/data1 -C shared_buffers
pg_ctl -D /pg/data1 status
外部表空间不会被隔离

cp -a 会保留 pg_tblspc 中的符号链接；pg-fork 不会复制或重映射 PGDATA 之外的表空间。直接启动这样的副本可能访问甚至修改源实例的表空间。存在外部表空间时，必须先独立复制并重映射所有表空间，或不要使用此脚本创建可写副本。

交互边界

只有标准输入是终端且没有 -y 时，脚本才询问 Proceed with fork? [y/N]。管道、CI、cron 等非交互调用不会出现该确认。因此自动化必须在调用前自行完成严格的绝对路径白名单与目标存在性检查；不要为了方便默认添加 -y。

pg-pitr

pg-pitr 是低层 pgBackRest restore 包装器。它不暂停或启动 Patroni，不停止或启动 PostgreSQL，不清理 DCS，也不重建副本。

恢复目标

实际执行至少要明确理解一个恢复目标。无参数调用只显示帮助：

参数 pgBackRest 语义
-d, --default 不设置停止目标，重放到可用 WAL 末尾
-i, --immediate 到达所选备份的一致性点后停止
-t, --time <timestamp> 恢复到指定时间
-n, --name <restore-point> 恢复到命名还原点
-l, --lsn <lsn> 恢复到指定 LSN
-x, --xid <xid> 恢复到指定事务 ID

-S/--set（兼容别名 -b/--backup）只选择 从哪个备份集开始恢复，不是停止目标。例如，-S 20251225-120000F -d 仍会继续重放到 WAL 末尾；若要在该备份一致后立即停止，应组合 -S ... -i。

针对 time、name、lsn、xid 与 immediate，pgBackRest 的有效默认动作是抵达目标后暂停；-P/--promote 改为自动提升。-X/--exclusive 只应与 time、lsn 或 xid 这类明确边界配合使用。

其他选项

参数 含义
-D, --data <path> 目标数据目录，必须是绝对路径；默认 /pg/data
-s, --stanza <name> pgBackRest stanza；默认从配置取第一个非 global stanza
-T, --timeline <value> latest、current 或正整数时间线
-P, --promote 对有停止目标的恢复设置自动提升
-v, --verbose 启用 pgBackRest info 级控制台日志
-c, --check, --dry-run 只打印将执行的命令
-y, --yes 跳过五秒倒计时
-- <args> 将额外参数原样传给 pgBackRest

-c 是命令渲染检查，不会证明备份/WAL 可用，也不会检查 PostgreSQL 或 Patroni 已停止。额外 pgBackRest 参数也没有由包装器做冲突过滤；传递仓库、表空间或链接映射参数时必须单独审查最终命令。

安全执行顺序

以下示例只展示单个已隔离目标目录的低层流程；生产集群恢复应使用完整 runbook：

# 1. 只读核验备份与恢复窗口
pig pb info

# 2. 核对目标实例已经停止；Patroni 托管实例还要先停止 Patroni
pg_ctl -D /pg/data1 status

# 3. 打印并人工审查准确命令，不写数据
pg-pitr -D /pg/data1 -t "2026-08-13 10:00:00+08" -c

# 4. 只有在操作者再次确认绝对目标、备份与停机状态后，才去掉 -c
pg-pitr -D /pg/data1 -t "2026-08-13 10:00:00+08"

实际执行拒绝 root，并在发现目标目录中存在 postmaster.pid 时中止；即使 PID 已失效，也要求人工确认后清理。它没有 y/N 问答：交互终端只有五秒可中断倒计时，非交互环境没有倒计时并直接进入 restore。

恢复后由操作者启动实例并验证：

pg_ctl -D /pg/data1 start
psql -p 15432 -Atqc \
  'SELECT pg_is_in_recovery(), pg_is_wal_replay_paused(), pg_last_xact_replay_timestamp()'

只有恢复目标、允许访问的业务数据、时间线和归档设置全部验证无误后，才决定是否提升。提升会创建新时间线，不是可撤销的“查看”动作。pg-pitr 本身不会关闭归档；不要机械执行脚本结尾的通用“enable archive_mode”提示，应先查看有效值，只纠正本次恢复明确造成的覆盖项。

旁路恢复的额外风险

向 /pg/data1 之类的自定义目录恢复时，pgBackRest 可能从备份恢复 postgresql.auto.conf，覆盖 pg-fork 写入的独立端口。启动前重新检查 port、archive_mode、socket、日志与内存设置。

备份中若包含外部表空间或链接，旁路恢复还可能使用原路径。需要隔离时，应在 -- 后提供经过审查的 pgBackRest --tablespace-map、--link-map 等参数，并检查打印出的完整命令；否则不要在与生产实例相同的主机上启动恢复副本。

推荐的克隆验证流程

  1. 核对源实例、目标绝对路径、目标端口、表空间与独立备份。
  2. 在交互终端运行 pg-fork <id>，确认脚本显示的是热备份而非意外降级的冷拷贝。
  3. 不启动副本，先用 pg-pitr -D <clone> ... -c 检查恢复命令。
  4. 明确确认目标后执行恢复；随后重新检查副本端口和所有外部路径。
  5. 启动副本，在隔离端口上验证恢复状态和经授权的数据。
  6. 只有需要形成新主库时才提升；否则停止副本并按经过验证的精确路径清理。

这种旁路验证可以降低对当前 PGDATA 的直接影响，但仍会读取同一个备份仓库、占用主机资源，并可能触及外部表空间；它不是无风险沙箱。

相关文档

7.5 - 为 PostgreSQL 集群启用 HugePage

为 PostgreSQL 集群启用大页，减少大内存实例的页表开销并提高性能

使用 node_hugepage_count 和 node_hugepage_ratio 或 /pg/bin/pg-tune-hugepage

如果你计划启用大页（HugePage），请考虑使用 node_hugepage_count 和 node_hugepage_ratio，并配合 ./node.yml -t node_tune 进行应用。

大页对于数据库来说有利有弊，利是内存是专门管理的，不用担心被挪用，降低数据库 OOM 风险。缺点是某些场景下可能对性能由负面影响。

在 PostgreSQL 启动前，您需要分配 足够多的 大页，浪费的部分可以使用 pg-tune-hugepage 脚本对其进行回收，不过此脚本仅 PostgreSQL 15+ 可用。

如果你的 PostgreSQL 已经在运行，你可以使用下面的办法启动大页（仅 PG15+ 可用）：

sync; echo 3 > /proc/sys/vm/drop_caches   # 刷盘，释放系统缓存（请做好数据库性能受到冲击的准备）
sudo /pg/bin/pg-tune-hugepage             # 将 nr_hugepages 写入 /etc/sysctl.d/hugepage.conf
pg restart <cls>                          # 重启 postgres 以使用 hugepage

7.6 - 3坏2应急处理

高可用典型场景处理预案：三节点坏了两个节点，高可用不生效了，怎么从紧急状态中恢复？

如果经典3节点高可用部署同时出现两台（多数主体）故障，系统通常无法自动完成故障切换，需要人工介入：

首先判断另外两台服务器的情况，如果短时间内可以拉起，优先选择拉起另外两台服务。否则进入 紧急止血流程

紧急止血流程假设您的管理节点故障，只有单台普通数据库节点存活，在这种情况下，最快的恢复操作流程为：

  • 调整 HAProxy 配置，将流量指向主库。
  • 关闭 Patroni，手动提升 PostgreSQL 从库为主库。

调整HAProxy配置

如果你通过其他方式绕开 HAProxy 访问集群，那么可以跳过这一步。 如果你通过 HAProxy 方式访问数据库集群，那么你需要调整负载均衡配置，将读写流量手工指向主库。

  • 编辑 /etc/haproxy/conf.d/<pg_cluster>-primary.cfg 配置文件，其中 <pg_cluster> 为你的 PostgreSQL 集群名称，例如 pg-meta。
  • 将健康检查配置选项注释，停止进行健康检查。
  • 将服务器列表中，其他两台故障的机器注释掉，只保留当前主库服务器。
listen pg-meta-primary
    bind *:5433
    mode tcp
    maxconn 5000
    balance roundrobin

    # 注释掉以下四行健康检查配置
    #option httpchk                               # <---- remove this
    #option http-keep-alive                       # <---- remove this
    #http-check send meth OPTIONS uri /primary    # <---- remove this
    #http-check expect status 200                 # <---- remove this

    default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
    server pg-meta-1 10.10.10.10:6432 check port 8008 weight 100

    # 注释掉其他两台故障的机器
    #server pg-meta-2 10.10.10.11:6432 check port 8008 weight 100 <---- comment this
    #server pg-meta-3 10.10.10.12:6432 check port 8008 weight 100 <---- comment this

配置调整完成后，先不着急执行 systemctl reload haproxy 重载生效，等待后续主库提升后一起执行。 以上配置的效果是，HAProxy 将不再进行主库健康检查（默认使用 Patroni），而是直接将写入流量指向当前主库

手工提升备库

登陆目标服务器，切换至 dbsu 用户，执行 CHECKPOINT 刷盘后，关闭 Patroni，重启 PostgreSQL 并执行 Promote。

sudo su - postgres                     # 切换到数据库 dbsu 用户
psql -c 'checkpoint; checkpoint;'      # 两次 Checkpoint 刷脏页，避免PG后重启耗时过久
sudo systemctl stop patroni            # 关闭 Patroni
pg-restart                             # 重新拉起 PostgreSQL
pg-promote                             # 将 PostgreSQL 从库提升为主库
psql -c 'SELECT pg_is_in_recovery();'  # 如果结果为 f，表示已经提升为主库

如果你上面调整了 HAProxy 配置，那么现在可以执行 systemctl reload haproxy 重载 HAProxy 配置，将流量指向新的主库。

systemctl reload haproxy                # 重载 HAProxy 配置，将写入流量指向当前实例

避免脑裂

紧急止血后，第二优先级问题为：避免脑裂。用户应当防止另外两台服务器重新上线后，与当前主库形成脑裂，导致数据不一致。

简单的做法是：

  • 将另外两台服务器直接 断电/断网，确保它们不会在不受控的情况下再次上线。
  • 调整应用使用的数据库连接串，将其 HOST 直接指向唯一幸存服务器上的主库。

然后应当根据具体情况，决定下一步的操作：

  • A：这两台服务器是临时故障（比如断网断电），可以原地修复后继续服务
  • B：这两台故障服务器是永久故障（比如硬件损坏），将移除并下线。

临时故障后的复原

如果另外两台服务器是临时故障，可以修复后继续服务，那么可以按照以下步骤进行修复与重建：

  • 每次处理一台故障服务器，优先处理 管理节点 / INFRA 管理节点
  • 启动故障服务器，并在启动后关停 Patroni

ETCD 集群在法定人数恢复后，将恢复工作，此时可以启动幸存服务器（当前主库）上的 Patroni，接管现有 PostgreSQL，并重新获取集群领导者身份。 Patroni 启动后进入维护模式。

sudo systemctl restart patroni
pg pause <pg_cluster>

在另外两台实例上以 postgres 用户身份创建 touch /pg/data/standby.signal 标记文件将其标记为从库，然后拉起 Patroni：

sudo -iu postgres touch /pg/data/standby.signal
sudo systemctl restart patroni

确认 Patroni 集群身份/角色正常后，退出维护模式：

pg resume <pg_cluster>

永久故障后的复原

出现永久故障后，首先需要恢复管理节点上的 ~/pigsty 目录，主要是需要 pigsty.yml 与 files/pki/ca/ca.key 两个核心文件。

如果您无法取回或没有备份这两个文件，您可以选择部署一套新的 Pigsty，并通过 备份集群 的方式将现有集群迁移至新部署中。

请定期备份 pigsty 目录（例如使用 Git 进行版本管理）。建议吸取教训，下次不要犯这样的错误。

配置修复

您可以将幸存的节点作为新的管理节点，将 ~/pigsty 目录拷贝到新的管理节点上，然后开始调整配置。 例如，将原本默认的管理节点 10.10.10.10 替换为幸存节点 10.10.10.12

all:
  vars:
    admin_ip: 10.10.10.12               # 使用新的管理节点地址
    node_etc_hosts: [10.10.10.12 h.pigsty a.pigsty p.pigsty g.pigsty sss.pigsty]
    infra_portal: {}                    # 一并修改其他引用旧管理节点 IP (10.10.10.10) 的配置

  children:

    infra:                              # 调整 Infra 集群
      hosts:
        # 10.10.10.10: { infra_seq: 1 } # 老的 Infra 节点
        10.10.10.12: { infra_seq: 3 }   # 新增 Infra 节点

    etcd:                               # 调整 ETCD 集群
      hosts:
        #10.10.10.10: { etcd_seq: 1 }   # 注释掉此故障节点
        #10.10.10.11: { etcd_seq: 2 }   # 注释掉此故障节点
        10.10.10.12: { etcd_seq: 3 }    # 保留幸存节点
      vars:
        etcd_cluster: etcd

    pg-meta:                            # 调整 PGSQL 集群配置
      hosts:
        #10.10.10.10: { pg_seq: 1, pg_role: primary }
        #10.10.10.11: { pg_seq: 2, pg_role: replica }
        #10.10.10.12: { pg_seq: 3, pg_role: replica , pg_offline_query: true }
        10.10.10.12: { pg_seq: 3, pg_role: primary , pg_offline_query: true }
      vars:
        pg_cluster: pg-meta

ETCD修复

然后执行以下命令，将 ETCD 重置为单节点集群：

./etcd.yml -e etcd_safeguard=false -e etcd_clean=true

根据 ETCD重载配置 的说明，调整对 ETCD Endpoint 的引用。

INFRA修复

如果幸存节点上没有 INFRA 模块，请在当前节点上配置新的 INFRA 模块并安装。执行以下命令，将 INFRA 模块部署到幸存节点上：

./infra.yml -l 10.10.10.12

修复当前节点的监控

./node.yml -t monitor

PGSQL修复 

./pgsql.yml -t pg_conf                            # 重新生成 PG 配置文件
systemctl reload patroni                          # 在幸存节点上重载 Patroni 配置

各模块修复后，您可以参考标准扩容流程，将新的节点加入集群，恢复集群的高可用性。

7.7 - 使用 VIP-Manager 为 PostgreSQL 集群配置二层 VIP

您可以在 PostgreSQL 集群上绑定一个可选的 L2 VIP —— 前提条件是：集群中的所有节点都在一个二层网络中。

这个 L2 VIP 强制使用 Master - Backup 模式，Master 始终指向在数据库集群主库实例所在的节点。

这个 VIP 由 VIP-Manager 组件管理，它会从 DCS （etcd） 中直接读取由 Patroni 写入的 Leader Key，从而判断自己是否是 Master。

启用VIP

在 PostgreSQL 集群上定义 pg_vip_enabled 参数为 true，即可在集群上启用 VIP 组件。当然您也可以在全局配置中启用此配置项。

# pgsql 3 node ha cluster: pg-test
pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }   # primary instance, leader of cluster
    10.10.10.12: { pg_seq: 2, pg_role: replica }   # replica instance, follower of leader
    10.10.10.13: { pg_seq: 3, pg_role: replica, pg_offline_query: true } # replica with offline access
  vars:
    pg_cluster: pg-test           # define pgsql cluster name
    pg_users:  [{ name: test , password: test , pgbouncer: true , roles: [ dbrole_admin ] }]
    pg_databases: [{ name: test }]

    # 启用 L2 VIP
    pg_vip_enabled: true
    pg_vip_address: 10.10.10.3/24
    #pg_vip_interface: auto

请注意，pg_vip_address 必须是一个合法的 IP 地址，带有网段，且在当前二层网络中可用。

pg_vip_interface 默认为 auto， 此时 Pigsty 会根据 inventory 中的 IPv4 地址自动探测各实例使用的网卡。 如果自动探测不适用于非标准路由或策略路由环境，可以为每个实例显式指定合法的网卡名称，例如：

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary , pg_vip_interface: eth0  }
    10.10.10.12: { pg_seq: 2, pg_role: replica , pg_vip_interface: eth1  }
    10.10.10.13: { pg_seq: 3, pg_role: replica , pg_vip_interface: ens33 }
  vars:
    pg_cluster: pg-test           # define pgsql cluster name
    pg_users:  [{ name: test , password: test , pgbouncer: true , roles: [ dbrole_admin ] }]
    pg_databases: [{ name: test }]

    # 启用 L2 VIP
    pg_vip_enabled: true
    pg_vip_address: 10.10.10.3/24

使用以下命令，刷新 PG 的 vip-manager 配置并重启生效：

./pgsql.yml -t pg_vip

7.8 - Citus 集群部署

如何部署 Citus 高可用分布式集群？

Citus 是一个 PostgreSQL 扩展，可以将 PostgreSQL 原地转换为一个分布式数据库，并实现在多个节点上水平扩展，以处理大量数据和大量查询。

Patroni 在 v3.0 后，提供了对 Citus 原生高可用的支持，简化了 Citus 集群的搭建，Pigsty 也对此提供了原生支持。

说明

Citus 13.x 支持 PostgreSQL 18、17、16、15、14 五个大版本。Pigsty 扩展仓库提供了 Citus ARM64 软件包。

Citus集群

Pigsty 原生支持 Citus。当前完整配置模板见 conf/ha/citus.yml。

下面先使用一个简化的四节点拓扑说明关键参数：一个两节点协调者集群 pg-citus0，以及两个单节点 Worker 集群 pg-citus1、pg-citus2。它不是当前完整模板的逐行摘录。

pg-citus:
  hosts:
    10.10.10.10: { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.2/24 ,pg_seq: 1, pg_role: primary }
    10.10.10.11: { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.2/24 ,pg_seq: 2, pg_role: replica }
    10.10.10.12: { pg_group: 1, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.3/24 ,pg_seq: 1, pg_role: primary }
    10.10.10.13: { pg_group: 2, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.4/24 ,pg_seq: 1, pg_role: primary }
  vars:
    pg_mode: citus                            # pgsql cluster mode: citus
    pg_version: 18                            # citus 13.x supports PG 14-18
    pg_shard: pg-citus                        # citus shard name: pg-citus
    pg_primary_db: citus                      # primary database used by citus
    pg_vip_enabled: true                      # enable vip for citus cluster
    pg_vip_interface: auto                    # auto detect vip interface for every member
    pg_dbsu_password: DBUser.Postgres         # all dbsu password access for citus cluster
    pg_extensions: [ citus, postgis, pgvector, topn, pg_cron, hll ]  # install these extensions
    pg_libs: 'citus, pg_cron, pg_stat_statements' # 显式预加载 citus，且置于首位
    pg_users: [{ name: dbuser_citus ,password: DBUser.Citus ,pgbouncer: true ,roles: [ dbrole_admin ]    }]
    pg_databases: [{ name: citus ,owner: dbuser_citus ,extensions: [ citus, vector, topn, pg_cron, hll ] }]
    pg_parameters:
      cron.database_name: citus
      citus.node_conninfo: 'sslrootcert=/pg/cert/ca.crt sslmode=verify-full'
    pg_hba_rules:
      - { user: 'all' ,db: all  ,addr: 127.0.0.1/32  ,auth: ssl   ,title: 'all user ssl access from localhost' }
      - { user: 'all' ,db: all  ,addr: intra         ,auth: ssl   ,title: 'all user ssl access from intranet'  }

相比标准 PostgreSQL 集群，Citus 集群的配置有一些特殊之处，首先，你需要确保 Citus 扩展被下载，安装，加载并启用，这涉及到以下四个参数

  • repo_packages：必须包含 citus 扩展，或者你需要使用带有 Citus 扩展的 PostgreSQL 离线安装包。
  • pg_extensions：必须包含 citus 扩展，即你必须在每个节点上安装 citus 扩展。
  • pg_libs：必须显式包含 citus，并将其置于首位；当前 Patroni 模板直接使用该参数生成 shared_preload_libraries。
  • pg_databases： 这里要定义一个首要数据库，该数据库必须安装 citus 扩展。

其次，你需要确保 Citus 集群的配置正确：

  • pg_mode： 必须设置为 citus，从而告知 Patroni 使用 Citus 模式。
  • pg_primary_db：必须指定一个首要数据库的名称，该数据库必须安装 citus 扩展，这里名为 citus。
  • pg_shard：必须指定一个统一的名称，字符串，作为所有水平分片 PG 集群的集群名称前缀，这里为 pg-citus。
  • pg_group：必须指定一个分片号，从零开始依次分配的整数，0 号固定代表协调者集群，其他为 Worker 集群。
  • pg_cluster 必须在每个物理 PostgreSQL 集群间唯一。通常采用 pg_shard 加序号的命名约定，但当前角色不强制它与 pg_group 按字符串拼接结果相等。
  • pg_dbsu_password：必须设置为非空的纯文本密码，否则 Citus 无法正常工作。
  • pg_parameters：建议设置 citus.node_conninfo 参数，强制要求 SSL 访问并要求节点间验证客户端证书。

配置完成后，您可以像创建普通 PostgreSQL 集群一样，使用 pgsql.yml 部署 Citus 集群。

管理Citus集群

定义好 Citus 集群后，部署 Citus 集群同样使用的剧本 pgsql.yml：

./pgsql.yml -l pg-citus    # 部署 Citus 集群 pg-citus

使用任意成员的 DBSU（postgres）用户，都能通过 patronictl （alias: pg） 列出 Citus 集群的状态：

$ pg list
+ Citus cluster: pg-citus ----------+---------+-----------+----+-----------+--------------------+
| Group | Member      | Host        | Role    | State     | TL | Lag in MB | Tags               |
+-------+-------------+-------------+---------+-----------+----+-----------+--------------------+
|     0 | pg-citus0-1 | 10.10.10.10 | Leader  | running   |  1 |           | clonefrom: true    |
|       |             |             |         |           |    |           | conf: tiny.yml     |
|       |             |             |         |           |    |           | spec: 20C.40G.125G |
|       |             |             |         |           |    |           | version: '16'      |
+-------+-------------+-------------+---------+-----------+----+-----------+--------------------+
|     1 | pg-citus1-1 | 10.10.10.11 | Leader  | running   |  1 |           | clonefrom: true    |
|       |             |             |         |           |    |           | conf: tiny.yml     |
|       |             |             |         |           |    |           | spec: 10C.20G.125G |
|       |             |             |         |           |    |           | version: '16'      |
+-------+-------------+-------------+---------+-----------+----+-----------+--------------------+
|     2 | pg-citus2-1 | 10.10.10.12 | Leader  | running   |  1 |           | clonefrom: true    |
|       |             |             |         |           |    |           | conf: tiny.yml     |
|       |             |             |         |           |    |           | spec: 10C.20G.125G |
|       |             |             |         |           |    |           | version: '16'      |
+-------+-------------+-------------+---------+-----------+----+-----------+--------------------+
|     2 | pg-citus2-2 | 10.10.10.13 | Replica | streaming |  1 |         0 | clonefrom: true    |
|       |             |             |         |           |    |           | conf: tiny.yml     |
|       |             |             |         |           |    |           | spec: 10C.20G.125G |
|       |             |             |         |           |    |           | version: '16'      |
+-------+-------------+-------------+---------+-----------+----+-----------+--------------------+

您可以将每个水平分片集群视为一个独立的 PGSQL 集群，使用 pg (patronictl) 命令管理它们。 但是务必注意，当你使用 pg 命令管理 Citus 集群时，需要额外使用 --group 参数指定集群分片号

pg list pg-citus --group 0   # 需要使用 --group 0 指定集群分片号

Citus 中有一个名为 pg_dist_node 的系统表，用于记录 Citus 集群的节点信息，Patroni 会自动维护该表。

PGURL=postgres://postgres:[email protected]/citus

psql $PGURL -c 'SELECT * FROM pg_dist_node;'       # 查看节点信息
 nodeid | groupid |  nodename   | nodeport | noderack | hasmetadata | isactive | noderole  | nodecluster | metadatasynced | shouldhaveshards
--------+---------+-------------+----------+----------+-------------+----------+-----------+-------------+----------------+------------------
      1 |       0 | 10.10.10.10 |     5432 | default  | t           | t        | primary   | default     | t              | f
      4 |       1 | 10.10.10.12 |     5432 | default  | t           | t        | primary   | default     | t              | t
      5 |       2 | 10.10.10.13 |     5432 | default  | t           | t        | primary   | default     | t              | t
      6 |       0 | 10.10.10.11 |     5432 | default  | t           | t        | secondary | default     | t              | f

此外，你还可以查看用户认证信息（仅限超级用户访问）：

$ psql $PGURL -c 'SELECT * FROM pg_dist_authinfo;'   # 查看节点认证信息（仅限超级用户访问）

然后，你可以使用普通业务用户（例如，具有 DDL 权限的 dbuser_citus）来访问 Citus 集群：

psql postgres://dbuser_citus:[email protected]/citus -c 'SELECT * FROM pg_dist_node;'

使用Citus集群

在使用 Citus 集群时，我们强烈建议您先阅读 Citus 官方文档，了解其架构设计与核心概念。

其中核心是了解 Citus 中的五种表，以及其特点与应用场景：

  • 分布式表（Distributed Table）
  • 参考表（Reference Table）
  • 本地表（Local Table）
  • 本地管理表（Local Management Table）
  • 架构表（Schema Table）

在协调者节点上，您可以创建分布式表和引用表，并从任何数据节点查询它们。从 11.2 开始，任何 Citus 数据库节点都可以扮演协调者的角色了。

我们可以使用 pgbench 来创建一些表，并将其中的主表（pgbench_accounts）分布到各个节点上，然后将其他小表作为引用表：

PGURL=postgres://dbuser_citus:[email protected]/citus
pgbench -i $PGURL

psql $PGURL <<-EOF
SELECT create_distributed_table('pgbench_accounts', 'aid'); SELECT truncate_local_data_after_distributing_table('public.pgbench_accounts');
SELECT create_reference_table('pgbench_branches')         ; SELECT truncate_local_data_after_distributing_table('public.pgbench_branches');
SELECT create_reference_table('pgbench_history')          ; SELECT truncate_local_data_after_distributing_table('public.pgbench_history');
SELECT create_reference_table('pgbench_tellers')          ; SELECT truncate_local_data_after_distributing_table('public.pgbench_tellers');
EOF

执行读写测试：

pgbench -nv -P1 -c10 -T500 postgres://dbuser_citus:[email protected]/citus      # 直连协调者 5432 端口
pgbench -nv -P1 -c10 -T500 postgres://dbuser_citus:[email protected]:6432/citus # 通过连接池，减少客户端连接数压力，可以有效提高整体吞吐。
pgbench -nv -P1 -c10 -T500 postgres://dbuser_citus:[email protected]/citus      # 任意 primary 节点都可以作为 coordinator
pgbench --select-only -nv -P1 -c10 -T500 postgres://dbuser_citus:[email protected]/citus # 可以发起只读查询

更严肃的生产部署

要将 Citus 用于生产环境，您通常需要为 Coordinator 和每个 Worker 集群设置流复制物理副本。

当前 conf/ha/citus.yml 在 13 台主机上定义了 1 个 pg-meta 实例，以及 12 个 Citus 实例（6 个双节点物理集群，pg_group 为 0–5）。下面的 10 节点片段是另一种独立的生产拓扑示例，并非当前模板内容。

pg-citus: # citus group
  hosts:
    10.10.10.50: { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.60/24 ,pg_seq: 0, pg_role: primary }
    10.10.10.51: { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.60/24 ,pg_seq: 1, pg_role: replica }
    10.10.10.52: { pg_group: 1, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.61/24 ,pg_seq: 0, pg_role: primary }
    10.10.10.53: { pg_group: 1, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.61/24 ,pg_seq: 1, pg_role: replica }
    10.10.10.54: { pg_group: 2, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.62/24 ,pg_seq: 0, pg_role: primary }
    10.10.10.55: { pg_group: 2, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.62/24 ,pg_seq: 1, pg_role: replica }
    10.10.10.56: { pg_group: 3, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.63/24 ,pg_seq: 0, pg_role: primary }
    10.10.10.57: { pg_group: 3, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.63/24 ,pg_seq: 1, pg_role: replica }
    10.10.10.58: { pg_group: 4, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.64/24 ,pg_seq: 0, pg_role: primary }
    10.10.10.59: { pg_group: 4, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.64/24 ,pg_seq: 1, pg_role: replica }
  vars:
    pg_mode: citus                            # pgsql cluster mode: citus
    pg_version: 18                            # citus 13.x supports PG 14-18
    pg_shard: pg-citus                        # citus shard name: pg-citus
    pg_primary_db: citus                      # primary database used by citus
    pg_vip_enabled: true                      # enable vip for citus cluster
    pg_vip_interface: auto                    # auto detect vip interface for every member
    pg_dbsu_password: DBUser.Postgres         # enable dbsu password access for citus
    pg_extensions: [ citus, postgis, pgvector, topn, pg_cron, hll ]  # install these extensions
    pg_libs: 'citus, pg_cron, pg_stat_statements' # citus will be added by patroni automatically
    pg_users: [{ name: dbuser_citus ,password: DBUser.Citus ,pgbouncer: true ,roles: [ dbrole_admin ]    }]
    pg_databases: [{ name: citus ,owner: dbuser_citus ,extensions: [ citus, vector, topn, pg_cron, hll ] }]
    pg_parameters:
      cron.database_name: citus
      citus.node_conninfo: 'sslrootcert=/pg/cert/ca.crt sslmode=verify-full'
    pg_hba_rules:
      - { user: 'all' ,db: all  ,addr: 127.0.0.1/32  ,auth: ssl   ,title: 'all user ssl access from localhost' }
      - { user: 'all' ,db: all  ,addr: intra         ,auth: ssl   ,title: 'all user ssl access from intranet'  }

我们将在后续教程中覆盖一系列关于 Citus 的高级主题

  • 读写分离
  • 故障处理
  • 一致性备份与恢复
  • 高级监控与问题诊断
  • 连接池

8 - 监控系统

Pigsty 监控系统架构概览，以及如何监控现存的 PostgreSQL 实例？

本文介绍了 Pigsty 的监控系统架构，包括监控指标，日志，与目标管理的方式。以及如何 监控现有PG集群 与远程 RDS服务。

监控概览

Pigsty 使用现代的可观测技术栈对 PostgreSQL 进行监控：

  • 使用 Grafana 进行指标可视化和 PostgreSQL 数据源。
  • 使用 VictoriaMetrics 来采集 PostgreSQL / Pgbouncer / Patroni / HAProxy / Node 的指标
  • 使用 VictoriaLogs 来记录 PostgreSQL / Pgbouncer / Patroni / pgBackRest 以及主机组件的日志
  • Pigsty 提供了开箱即用的 Grafana 仪表盘，展示与 PostgreSQL 有关的方方面面。

监控指标

PostgreSQL 本身的监控指标完全由 pg_exporter 配置文件所定义：roles/pg_monitor/templates/pg_exporter.yml。 它们会进一步由 VictoriaMetrics/vmalert 兼容的记录与告警规则加工处理：files/victoria/rules/pgsql.yml。

Pigsty 使用三个身份标签：cls、ins、ip，它们将附加到所有指标和日志上。此外，Pgbouncer 的监控指标，主机节点 NODE，与负载均衡器的监控指标也会被 Pigsty 所使用，并尽可能地使用相同的标签以便于关联分析。

- { cls: pg-meta, ins: pg-meta-1, ip: 10.10.10.10 }
- { cls: pg-test, ins: pg-test-1, ip: 10.10.10.11 }
- { cls: pg-test, ins: pg-test-2, ip: 10.10.10.12 }
- { cls: pg-test, ins: pg-test-3, ip: 10.10.10.13 }

日志

与 PostgreSQL 有关的日志由 vector 负责收集，并发送至 infra 节点上的 VictoriaLogs 日志存储/查询服务。

目标管理

VictoriaMetrics 的监控目标在 /infra/targets/pgsql/ 下的静态文件中定义，每个实例都有一个相应的文件。以 pg-meta-1 为例：

# pg-meta-1 [primary] @ 10.10.10.10
- labels: { cls: pg-meta, ins: pg-meta-1, ip: 10.10.10.10 }
  targets:
    - 10.10.10.10:9630    # <--- pg_exporter 用于PostgreSQL指标
    - 10.10.10.10:9631    # <--- pgbouncer_exporter 用于 Pgbouncer 指标
    - 10.10.10.10:8008    # <--- patroni指标（未启用 API SSL 时）
    - 10.10.10.10:9854    # <--- pgbackrest_exporter 用于备份指标

当全局标志 patroni_ssl_enabled 被设置时，Patroni 目标会单独写入 /infra/targets/patroni/<ins>.yml，因为此时使用 HTTPS 抓取端点。当您 监控RDS 实例时，监控目标会放在 /infra/targets/pgrds/ 目录下，并以 集群 为单位进行管理。

当使用 bin/pgsql-rm 或 pgsql-rm.yml 移除集群时，相应监控目标会被移除。您也可以使用：

bin/pgmon-rm <cls|ins>    # 从所有 infra 节点中移除监控目标

远程 RDS 监控目标会被放置于 /infra/targets/pgrds/<cls>.yml，它们由 pgsql-monitor.yml 剧本或 bin/pgmon-add 脚本创建。

监控模式

Pigsty 提供三种监控模式，以适应不同的监控需求。

事项\等级 L1 L2 L3
名称 基础部署 托管部署 标准部署
英文 RDS MANAGED FULL
场景 只有连接串，例如 RDS DB 已存在，节点可管理 实例由 Pigsty 创建
PGCAT 功能 ✅ 完整可用 ✅ 完整可用 ✅ 完整可用
PGSQL 功能 ✅ 限 PG 指标 ✅ 限 PG 与节点指标 ✅ 完整功能
连接池指标 ❌ 不可用 ⚠️ 选装 ✅ 预装项
负载均衡器指标 ❌ 不可用 ⚠️ 选装 ✅ 预装项
PGLOG 功能 ❌ 不可用 ⚠️ 选装 ✅ 预装项
PG Exporter ⚠️ 部署于 Infra 节点 ✅ 部署于 DB 节点 ✅ 部署于 DB 节点
Node Exporter ❌ 不部署 ✅ 部署于 DB 节点 ✅ 部署于 DB 节点
侵入 DB 节点 ✅ 无侵入 ⚠️ 安装 Exporter ⚠️ 完全由 Pigsty 管理
监控现有实例 ✅ 可支持 ✅ 可支持 ❌ 仅用于 Pigsty 托管实例
监控用户与视图 人工创建 人工创建 Pigsty 自动创建
部署使用剧本 bin/pgmon-add <cls> 部分执行 pgsql.yml/node.yml pgsql.yml
所需权限 Infra 节点可达的 PGURL DB 节点 ssh 与 sudo 权限 DB 节点 ssh 与 sudo 权限
功能概述 PGCAT + PGRDS 大部分功能 完整功能

由 Pigsty 完全管理的数据库会自动纳入监控，并拥有最好的监控支持，通常不需要任何配置。对于现有的 PostgreSQL 集群或者 RDS 服务，如果目标 DB 节点 可以被 Pigsty 所管理（ssh 可达，sudo 可用），那么您可以考虑 托管部署，实现与 Pigsty 基本类似的监控管理体验。如果您 只能通过 PGURL（数据库连接串）的方式访问目标数据库，例如远程的 RDS 服务，则可以考虑使用 精简模式 监控目标数据库。

监控现有集群

如果目标 DB 节点可以被 Pigsty 所管理（ssh 可达且 sudo 可用），那么您可以使用 pgsql.yml 剧本中的 pg_exporter 任务， 使用与标准部署相同的方式，在目标节点上部署监控组件：PG Exporter。您也可以使用该剧本的 pgbouncer，pgbouncer_exporter 任务在已有实例节点上部署连接池及其监控。此外，您也可以使用 node.yml 中的 node_exporter， haproxy， vector 部署主机监控，负载均衡，日志收集组件。从而获得与原生 Pigsty 数据库实例完全一致的使用体验。

现有集群的定义方式与 Pigsty 所管理的集群定义方式完全相同，您只是选择性执行 pgsql.yml 剧本中的部分任务，而不是执行整个剧本。

./node.yml  -l <cls> -t node_repo,node_pkg           # 在主机节点上添加 INFRA节点的 YUM 源并安装软件包。
./node.yml  -l <cls> -t node_exporter,node_register  # 配置主机监控，并加入 VictoriaMetrics
./node.yml  -l <cls> -t vector                       # 配置主机日志采集，并发送至 VictoriaLogs
./pgsql.yml -l <cls> -t pg_exporter,pg_register      # 配置 PostgreSQL 监控，并注册至 Victoria/Grafana

因为目标数据库集群已存在，所以您需要手工在目标数据库集群上 创建监控用户、模式与扩展。

监控RDS

如果您 只能通过 PGURL（数据库连接串）的方式访问目标数据库，那么可以参照这里的说明进行配置。在这种模式下，Pigsty 在 INFRA节点 上部署对应的 PG Exporter，抓取远端数据库指标信息。如下图所示：

------ infra ------
|                 |
| victoria-metrics|            v---- pg-foo-1 ----v
|       ^         |  metrics   |         ^        |
|   pg_exporter <-|------------|----  postgres    |
|   (port: 20001) |            | 10.10.10.10:5432 |
|       ^         |            ^------------------^
|       ^         |                      ^
|       ^         |            v---- pg-foo-2 ----v
|       ^         |  metrics   |         ^        |
|   pg_exporter <-|------------|----  postgres    |
|   (port: 20002) |            | 10.10.10.11:5433 |
-------------------            ^------------------^

在这种模式下，监控系统不会有主机，连接池，负载均衡器，高可用组件的相关指标，但数据库本身，以及数据目录（Catalog）中的实时状态信息仍然可用。Pigsty 提供了两个专用的监控面板，专注于 PostgreSQL 本身的监控指标： PGRDS Cluster 与 PGRDS Instance，总览与数据库内监控则复用现有监控面板。因为 Pigsty 不能管理您的 RDS，所以用户需要在目标数据库上提前 配置好监控对象。

监控外部 Postgres 实例时的局限性
  • PgBouncer 连接池指标不可用
  • Patroni 高可用组件指标不可用
  • 主机节点监控指标不可用，以及节点 HAProxy，Keepalived 指标亦不可用。
  • 日志收集与日志衍生指标不可用

下面我们使用沙箱环境作为示例：现在我们假设 pg-meta 集群是一个有待监控的 RDS 实例 pg-foo-1，而 pg-test 集群则是一个有待监控的 RDS 集群 pg-bar：

  1. 在目标上创建监控模式、用户和权限。详情请参考 监控对象配置

  2. 在配置清单中声明集群。例如，假设我们想要监控“远端”的 pg-meta & pg-test 集群：

    infra:            # 代理、监控、警报等的infra集群..
  hosts: { 10.10.10.10: { infra_seq: 1 } }
  vars:           # 在组'infra'上为远程postgres RDS安装pg_exporter
    pg_exporters: # 在此列出所有远程实例，为k分配一个唯一的未使用的本地端口
      20001: { pg_cluster: pg-foo, pg_seq: 1, pg_host: 10.10.10.10 , pg_databases: [{ name: meta }] } # 注册 meta 数据库为 Grafana 数据源

      20002: { pg_cluster: pg-bar, pg_seq: 1, pg_host: 10.10.10.11 , pg_port: 5432 } # 几种不同的连接串拼接方法
      20003: { pg_cluster: pg-bar, pg_seq: 2, pg_host: 10.10.10.12 , pg_exporter_url: 'postgres://dbuser_monitor:[email protected]:5432/postgres?sslmode=disable'}
      20004: { pg_cluster: pg-bar, pg_seq: 3, pg_host: 10.10.10.13 , pg_monitor_username: dbuser_monitor, pg_monitor_password: DBUser.Monitor }

    其中， pg_databases 字段中所列出的数据库，将会被注册至 Grafana 中，成为一个 PostgreSQL 数据源，为 PGCAT 监控面板提供数据支持。如果您不想使用 PGCAT，将注册数据库到 Grafana 中，只需要将 pg_databases 设置为空数组或直接留空即可。

    pigsty-monitor.jpg

  3. 执行添加监控命令：bin/pgmon-add <clsname>

    bin/pgmon-add pg-foo  # 将 pg-foo 集群纳入监控
bin/pgmon-add pg-bar  # 将 pg-bar 集群纳入监控

  4. 要删除远程集群的监控目标，可以使用 bin/pgmon-rm <clsname>

    bin/pgmon-rm pg-foo  # 将 pg-foo 从 Pigsty 监控中移除
bin/pgmon-rm pg-bar  # 将 pg-bar 从 Pigsty 监控中移除

您可以使用更多的参数来覆盖默认 pg_exporter 的选项，下面是一个使用 Pigsty 监控阿里云 RDS 与 PolarDB 的配置样例：

示例：监控阿里云 RDS for PostgreSQL 与 PolarDB

详情请参考：remote.yml

infra:            # 代理、监控、警报等的infra集群..
  hosts: { 10.10.10.10: { infra_seq: 1 } }
  vars:
    pg_exporters:   # 在此列出所有待监控的远程 RDS PG 实例

      20001:        # 分配一个唯一的未使用的本地端口，供本地监控 Agent 使用，这里是一个 PolarDB 的主库
        pg_cluster: pg-polar                  # RDS 集群名 （身份参数，手工指定分配监控系统内名称）
        pg_seq: 1                             # RDS 实例号 （身份参数，手工指定分配监控系统内名称）
        pg_host: pc-2ze379wb1d4irc18x.polardbpg.rds.aliyuncs.com # RDS 主机地址
        pg_port: 1921                         # RDS 端口（从控制台连接信息获取）
        pg_exporter_auto_discovery: true      # 启用新数据库自动发现功能
        pg_exporter_include_database: 'test'  # 仅监控这个列表中的数据库（多个数据库用逗号分隔）
        pg_monitor_username: dbuser_monitor   # 监控用的用户名，覆盖全局配置
        pg_monitor_password: DBUser_Monitor   # 监控用的密码，覆盖全局配置
        pg_databases: [{ name: test }]        # 希望启用PGCAT的数据库列表，只要name字段即可，register_datasource设置为false则不注册。

      20002:       # 这是一个 PolarDB  从库
        pg_cluster: pg-polar                  # RDS 集群名 （身份参数，手工指定分配监控系统内名称）
        pg_seq: 2                             # RDS 实例号 （身份参数，手工指定分配监控系统内名称）
        pg_host: pe-2ze7tg620e317ufj4.polarpgmxs.rds.aliyuncs.com # RDS 主机地址
        pg_port: 1521                         # RDS 端口（从控制台连接信息获取）
        pg_exporter_auto_discovery: true      # 启用新数据库自动发现功能
        pg_exporter_include_database: 'test,postgres'  # 仅监控这个列表中的数据库（多个数据库用逗号分隔）
        pg_monitor_username: dbuser_monitor   # 监控用的用户名
        pg_monitor_password: DBUser_Monitor   # 监控用的密码
        pg_databases: [ { name: test } ]        # 希望启用PGCAT的数据库列表，只要name字段即可，register_datasource设置为false则不注册。

      20004: # 这是一个基础版的单节点 RDS for PostgreSQL 实例
        pg_cluster: pg-rds                    # RDS 集群名 （身份参数，手工指定分配监控系统内名称）
        pg_seq: 1                             # RDS 实例号 （身份参数，手工指定分配监控系统内名称）
        pg_host: pgm-2zern3d323fe9ewk.pg.rds.aliyuncs.com  # RDS 主机地址
        pg_port: 5432                         # RDS 端口（从控制台连接信息获取）
        pg_exporter_auto_discovery: true      # 启用新数据库自动发现功能
        pg_exporter_include_database: 'rds'   # 仅监控这个列表中的数据库（多个数据库用逗号分隔）
        pg_monitor_username: dbuser_monitor   # 监控用的用户名
        pg_monitor_password: DBUser_Monitor   # 监控用的密码
        pg_databases: [ { name: rds } ]       # 希望启用PGCAT的数据库列表，只要name字段即可，register_datasource设置为false则不注册。

      20005: # 这是一个高可用版的 RDS for PostgreSQL 集群主库
        pg_cluster: pg-rdsha                  # RDS 集群名 （身份参数，手工指定分配监控系统内名称）
        pg_seq: 1                             # RDS 实例号 （身份参数，手工指定分配监控系统内名称）
        pg_host: pgm-2ze3d35d27bq08wu.pg.rds.aliyuncs.com  # RDS 主机地址
        pg_port: 5432                         # RDS 端口（从控制台连接信息获取）
        pg_exporter_include_database: 'rds'   # 仅监控这个列表中的数据库（多个数据库用逗号分隔）
        pg_databases: [ { name: rds }, {name : test} ]  # 将这两个数据库纳入 PGCAT 管理，注册为 Grafana 数据源

      20006: # 这是一个高可用版的 RDS for PostgreSQL 集群只读实例（从库）
        pg_cluster: pg-rdsha                  # RDS 集群名 （身份参数，手工指定分配监控系统内名称）
        pg_seq: 2                             # RDS 实例号 （身份参数，手工指定分配监控系统内名称）
        pg_host: pgr-2zexqxalk7d37edt.pg.rds.aliyuncs.com  # RDS 主机地址
        pg_port: 5432                         # RDS 端口（从控制台连接信息获取）
        pg_exporter_include_database: 'rds'   # 仅监控这个列表中的数据库（多个数据库用逗号分隔）
        pg_databases: [ { name: rds }, {name : test} ]  # 将这两个数据库纳入 PGCAT 管理，注册为 Grafana 数据源

监控对象配置

当您想要监控现有实例时，不论是 RDS，还是自建的 PostgreSQL 实例，您都需要在目标数据库上进行一些配置，以便 Pigsty 可以访问它们。

为了将外部现存 PostgreSQL 实例纳入监控，您需要有一个可用于访问该实例/集群的连接串。任何可达连接串（业务用户，超级用户）均可使用，但我们建议使用一个专用监控用户以避免权限泄漏。

  • 监控用户：默认使用的用户名为 dbuser_monitor， 该用户属于 pg_monitor 角色组，或确保具有相关视图访问权限。
  • 监控认证：默认使用密码访问，您需要确保 HBA 策略允许监控用户从管理机或 DB 节点本地访问数据库。
  • 监控模式：固定使用名称 monitor，用于安装额外的 监控视图 与扩展插件，非必选，但建议创建。
  • 监控扩展：强烈建议 启用 PG 自带的监控扩展 pg_stat_statements。
  • 监控视图：监控视图是可选项，可以提供更多的监控指标支持。

监控用户

以 Pigsty 默认使用的监控用户 dbuser_monitor 为例，在目标数据库集群创建以下用户。

CREATE USER dbuser_monitor;                                       -- 创建监控用户
COMMENT ON ROLE dbuser_monitor IS 'system monitor user';          -- 监控用户备注
GRANT pg_monitor TO dbuser_monitor;                               -- 授予监控用户 pg_monitor 权限，否则一些指标将无法采集

ALTER USER dbuser_monitor PASSWORD 'DBUser.Monitor';              -- 按需修改监控用户密码（强烈建议修改！但请与Pigsty配置一致）
ALTER USER dbuser_monitor SET log_min_duration_statement = 1000;  -- 建议设置此参数，避免日志塞满监控慢查询
ALTER USER dbuser_monitor SET search_path = monitor,public;       -- 建议设置此参数，避免 pg_stat_statements 扩展无法生效

请注意，这里创建的监控用户与密码需要与 pg_monitor_username 与 pg_monitor_password 保持一致。

监控认证

配置数据库 pg_hba.conf 文件，添加以下规则以允许监控用户从本地，以及管理机使用密码访问所有数据库。

# allow local role monitor with password
local   all  dbuser_monitor                    md5
host    all  dbuser_monitor  127.0.0.1/32      md5
host    all  dbuser_monitor  <管理机器IP地址>/32 md5

如果您的 RDS 不支持定义 HBA，那么把安装 Pigsty 机器的内网 IP 地址开白即可。

监控模式

监控模式 可选项，即使没有，Pigsty 监控系统的主体也可以正常工作，但我们强烈建议设置此模式。

CREATE SCHEMA IF NOT EXISTS monitor;               -- 创建监控专用模式
GRANT USAGE ON SCHEMA monitor TO dbuser_monitor;   -- 允许监控用户使用

监控扩展

监控扩展是可选项，但我们强烈建议启用 pg_stat_statements 扩展该扩展提供了关于查询性能的重要数据。

注意：该扩展必须列入数据库参数 shared_preload_libraries 中方可生效，而修改该参数需要重启数据库。

CREATE EXTENSION IF NOT EXISTS "pg_stat_statements" WITH SCHEMA "monitor";

请注意，您应当在默认的管理数据库 postgres 中安装此扩展。有些时候，RDS 不允许您在 postgres 数据库中创建监控模式， 在这种情况下，您可以将 pg_stat_statements 插件安装到默认的 public 下，只要确保监控用户的 search_path 按照上面的配置，能够找到 pg_stat_statements 视图即可。

CREATE EXTENSION IF NOT EXISTS "pg_stat_statements";
ALTER USER dbuser_monitor SET search_path = monitor,public; -- 建议设置此参数，避免 pg_stat_statements 扩展无法生效

监控视图

监控视图提供了若干常用的预处理结果，并对某些需要高权限的监控指标进行权限封装（例如共享内存分配），便于查询与使用。强烈建议在所有需要监控的数据库中创建

监控模式与监控视图定义

下列 SQL 便于理解监控对象；当前 Pigsty 实际渲染的完整定义以 roles/pgsql/templates/pg-init-template.sql 为准，当前模板还包含对安全搜索路径与权限边界的额外加固。

----------------------------------------------------------------------
-- Table bloat estimate : monitor.pg_table_bloat
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor.pg_table_bloat CASCADE;
CREATE OR REPLACE VIEW monitor.pg_table_bloat AS
SELECT CURRENT_CATALOG AS datname, nspname, relname , tblid , bs * tblpages AS size,
       CASE WHEN tblpages - est_tblpages_ff > 0 THEN (tblpages - est_tblpages_ff)/tblpages::FLOAT ELSE 0 END AS ratio
FROM (
         SELECT ceil( reltuples / ( (bs-page_hdr)*fillfactor/(tpl_size*100) ) ) + ceil( toasttuples / 4 ) AS est_tblpages_ff,
                tblpages, fillfactor, bs, tblid, nspname, relname, is_na
         FROM (
                  SELECT
                      ( 4 + tpl_hdr_size + tpl_data_size + (2 * ma)
                          - CASE WHEN tpl_hdr_size % ma = 0 THEN ma ELSE tpl_hdr_size % ma END
                          - CASE WHEN ceil(tpl_data_size)::INT % ma = 0 THEN ma ELSE ceil(tpl_data_size)::INT % ma END
                          ) AS tpl_size, (heappages + toastpages) AS tblpages, heappages,
                      toastpages, reltuples, toasttuples, bs, page_hdr, tblid, nspname, relname, fillfactor, is_na
                  FROM (
                           SELECT
                               tbl.oid AS tblid, ns.nspname , tbl.relname, tbl.reltuples,
                               tbl.relpages AS heappages, coalesce(toast.relpages, 0) AS toastpages,
                               coalesce(toast.reltuples, 0) AS toasttuples,
                               coalesce(substring(array_to_string(tbl.reloptions, ' ') FROM 'fillfactor=([0-9]+)')::smallint, 100) AS fillfactor,
                               current_setting('block_size')::numeric AS bs,
                               CASE WHEN version()~'mingw32' OR version()~'64-bit|x86_64|ppc64|ia64|amd64' THEN 8 ELSE 4 END AS ma,
                               24 AS page_hdr,
                               23 + CASE WHEN MAX(coalesce(s.null_frac,0)) > 0 THEN ( 7 + count(s.attname) ) / 8 ELSE 0::int END
                                   + CASE WHEN bool_or(att.attname = 'oid' and att.attnum < 0) THEN 4 ELSE 0 END AS tpl_hdr_size,
                               sum( (1-coalesce(s.null_frac, 0)) * coalesce(s.avg_width, 0) ) AS tpl_data_size,
                               bool_or(att.atttypid = 'pg_catalog.name'::regtype)
                                   OR sum(CASE WHEN att.attnum > 0 THEN 1 ELSE 0 END) <> count(s.attname) AS is_na
                           FROM pg_attribute AS att
                                    JOIN pg_class AS tbl ON att.attrelid = tbl.oid
                                    JOIN pg_namespace AS ns ON ns.oid = tbl.relnamespace
                                    LEFT JOIN pg_stats AS s ON s.schemaname=ns.nspname AND s.tablename = tbl.relname AND s.inherited=false AND s.attname=att.attname
                                    LEFT JOIN pg_class AS toast ON tbl.reltoastrelid = toast.oid
                           WHERE NOT att.attisdropped AND tbl.relkind = 'r' AND nspname NOT IN ('pg_catalog','information_schema')
                           GROUP BY 1,2,3,4,5,6,7,8,9,10
                       ) AS s
              ) AS s2
     ) AS s3
WHERE NOT is_na;
COMMENT ON VIEW monitor.pg_table_bloat IS 'postgres table bloat estimate';

GRANT SELECT ON monitor.pg_table_bloat TO pg_monitor;

----------------------------------------------------------------------
-- Index bloat estimate : monitor.pg_index_bloat
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor.pg_index_bloat CASCADE;
CREATE OR REPLACE VIEW monitor.pg_index_bloat AS
SELECT CURRENT_CATALOG AS datname, nspname, idxname AS relname, tblid, idxid, relpages::BIGINT * bs AS size,
       COALESCE((relpages - ( reltuples * (6 + ma - (CASE WHEN index_tuple_hdr % ma = 0 THEN ma ELSE index_tuple_hdr % ma END)
                                               + nulldatawidth + ma - (CASE WHEN nulldatawidth % ma = 0 THEN ma ELSE nulldatawidth % ma END))
                                  / (bs - pagehdr)::FLOAT  + 1 )), 0) / relpages::FLOAT AS ratio
FROM (
         SELECT nspname,idxname,indrelid AS tblid,indexrelid AS idxid,
                reltuples,relpages,
                current_setting('block_size')::INTEGER                                                               AS bs,
                (CASE WHEN version() ~ 'mingw32' OR version() ~ '64-bit|x86_64|ppc64|ia64|amd64' THEN 8 ELSE 4 END)  AS ma,
                24                                                                                                   AS pagehdr,
                (CASE WHEN max(COALESCE(pg_stats.null_frac, 0)) = 0 THEN 2 ELSE 6 END)                               AS index_tuple_hdr,
                sum((1.0 - COALESCE(pg_stats.null_frac, 0.0)) *
                    COALESCE(pg_stats.avg_width, 1024))::INTEGER                                                     AS nulldatawidth
         FROM pg_attribute
                  JOIN (
             SELECT pg_namespace.nspname,
                    ic.relname                                                   AS idxname,
                    ic.reltuples,
                    ic.relpages,
                    pg_index.indrelid,
                    pg_index.indexrelid,
                    tc.relname                                                   AS tablename,
                    regexp_split_to_table(pg_index.indkey::TEXT, ' ') :: INTEGER AS attnum,
                    pg_index.indexrelid                                          AS index_oid
             FROM pg_index
                      JOIN pg_class ic ON pg_index.indexrelid = ic.oid
                      JOIN pg_class tc ON pg_index.indrelid = tc.oid
                      JOIN pg_namespace ON pg_namespace.oid = ic.relnamespace
                      JOIN pg_am ON ic.relam = pg_am.oid
             WHERE pg_am.amname = 'btree' AND ic.relpages > 0 AND nspname NOT IN ('pg_catalog', 'information_schema')
         ) ind_atts ON pg_attribute.attrelid = ind_atts.indexrelid AND pg_attribute.attnum = ind_atts.attnum
                  JOIN pg_stats ON pg_stats.schemaname = ind_atts.nspname
             AND ((pg_stats.tablename = ind_atts.tablename AND pg_stats.attname = pg_get_indexdef(pg_attribute.attrelid, pg_attribute.attnum, TRUE))
                 OR (pg_stats.tablename = ind_atts.idxname AND pg_stats.attname = pg_attribute.attname))
         WHERE pg_attribute.attnum > 0
         GROUP BY 1, 2, 3, 4, 5, 6
     ) est;
COMMENT ON VIEW monitor.pg_index_bloat IS 'postgres index bloat estimate (btree-only)';

GRANT SELECT ON monitor.pg_index_bloat TO pg_monitor;

----------------------------------------------------------------------
-- Relation Bloat : monitor.pg_bloat
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor.pg_bloat CASCADE;
CREATE OR REPLACE VIEW monitor.pg_bloat AS
SELECT coalesce(ib.datname, tb.datname)                                                   AS datname,
       coalesce(ib.nspname, tb.nspname)                                                   AS nspname,
       coalesce(ib.tblid, tb.tblid)                                                       AS tblid,
       coalesce(tb.nspname || '.' || tb.relname, ib.nspname || '.' || ib.tblid::RegClass) AS tblname,
       tb.size                                                                            AS tbl_size,
       CASE WHEN tb.ratio < 0 THEN 0 ELSE round(tb.ratio::NUMERIC, 6) END                 AS tbl_ratio,
       (tb.size * (CASE WHEN tb.ratio < 0 THEN 0 ELSE tb.ratio::NUMERIC END)) ::BIGINT    AS tbl_wasted,
       ib.idxid,
       ib.nspname || '.' || ib.relname                                                    AS idxname,
       ib.size                                                                            AS idx_size,
       CASE WHEN ib.ratio < 0 THEN 0 ELSE round(ib.ratio::NUMERIC, 5) END                 AS idx_ratio,
       (ib.size * (CASE WHEN ib.ratio < 0 THEN 0 ELSE ib.ratio::NUMERIC END)) ::BIGINT    AS idx_wasted
FROM monitor.pg_index_bloat ib
         FULL OUTER JOIN monitor.pg_table_bloat tb ON ib.tblid = tb.tblid;

COMMENT ON VIEW monitor.pg_bloat IS 'postgres relation bloat detail';
GRANT SELECT ON monitor.pg_bloat TO pg_monitor;

----------------------------------------------------------------------
-- monitor.pg_index_bloat_human
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor.pg_index_bloat_human CASCADE;
CREATE OR REPLACE VIEW monitor.pg_index_bloat_human AS
SELECT idxname                            AS name,
       tblname,
       idx_wasted                         AS wasted,
       pg_size_pretty(idx_size)           AS idx_size,
       round(100 * idx_ratio::NUMERIC, 2) AS idx_ratio,
       pg_size_pretty(idx_wasted)         AS idx_wasted,
       pg_size_pretty(tbl_size)           AS tbl_size,
       round(100 * tbl_ratio::NUMERIC, 2) AS tbl_ratio,
       pg_size_pretty(tbl_wasted)         AS tbl_wasted
FROM monitor.pg_bloat
WHERE idxname IS NOT NULL;
COMMENT ON VIEW monitor.pg_index_bloat_human IS 'postgres index bloat info in human-readable format';
GRANT SELECT ON monitor.pg_index_bloat_human TO pg_monitor;


----------------------------------------------------------------------
-- monitor.pg_table_bloat_human
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor.pg_table_bloat_human CASCADE;
CREATE OR REPLACE VIEW monitor.pg_table_bloat_human AS
SELECT tblname                                          AS name,
       idx_wasted + tbl_wasted                          AS wasted,
       pg_size_pretty(idx_wasted + tbl_wasted)          AS all_wasted,
       pg_size_pretty(tbl_wasted)                       AS tbl_wasted,
       pg_size_pretty(tbl_size)                         AS tbl_size,
       tbl_ratio,
       pg_size_pretty(idx_wasted)                       AS idx_wasted,
       pg_size_pretty(idx_size)                         AS idx_size,
       round(idx_wasted::NUMERIC * 100.0 / idx_size, 2) AS idx_ratio
FROM (SELECT datname,
             nspname,
             tblname,
             coalesce(max(tbl_wasted), 0)                         AS tbl_wasted,
             coalesce(max(tbl_size), 1)                           AS tbl_size,
             round(100 * coalesce(max(tbl_ratio), 0)::NUMERIC, 2) AS tbl_ratio,
             coalesce(sum(idx_wasted), 0)                         AS idx_wasted,
             coalesce(sum(idx_size), 1)                           AS idx_size
      FROM monitor.pg_bloat
      WHERE tblname IS NOT NULL
      GROUP BY 1, 2, 3
     ) d;
COMMENT ON VIEW monitor.pg_table_bloat_human IS 'postgres table bloat info in human-readable format';
GRANT SELECT ON monitor.pg_table_bloat_human TO pg_monitor;


----------------------------------------------------------------------
-- Activity Overview: monitor.pg_session
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor.pg_session CASCADE;
CREATE OR REPLACE VIEW monitor.pg_session AS
SELECT coalesce(datname, 'all') AS datname, numbackends, active, idle, ixact, max_duration, max_tx_duration, max_conn_duration
FROM (
         SELECT datname,
                count(*)                                         AS numbackends,
                count(*) FILTER ( WHERE state = 'active' )       AS active,
                count(*) FILTER ( WHERE state = 'idle' )         AS idle,
                count(*) FILTER ( WHERE state = 'idle in transaction'
                    OR state = 'idle in transaction (aborted)' ) AS ixact,
                max(extract(epoch from now() - state_change))
                FILTER ( WHERE state = 'active' )                AS max_duration,
                max(extract(epoch from now() - xact_start))      AS max_tx_duration,
                max(extract(epoch from now() - backend_start))   AS max_conn_duration
         FROM pg_stat_activity
         WHERE backend_type = 'client backend'
           AND pid <> pg_backend_pid()
         GROUP BY ROLLUP (1)
         ORDER BY 1 NULLS FIRST
     ) t;
COMMENT ON VIEW monitor.pg_session IS 'postgres activity group by session';
GRANT SELECT ON monitor.pg_session TO pg_monitor;


----------------------------------------------------------------------
-- Sequential Scan: monitor.pg_seq_scan
----------------------------------------------------------------------
DROP VIEW IF EXISTS monitor.pg_seq_scan CASCADE;
CREATE OR REPLACE VIEW monitor.pg_seq_scan AS
SELECT schemaname                                                        AS nspname,
       relname,
       seq_scan,
       seq_tup_read,
       seq_tup_read / seq_scan                                           AS seq_tup_avg,
       idx_scan,
       n_live_tup + n_dead_tup                                           AS tuples,
       round(n_live_tup * 100.0::NUMERIC / (n_live_tup + n_dead_tup), 2) AS live_ratio
FROM pg_stat_user_tables
WHERE seq_scan > 0
  and (n_live_tup + n_dead_tup) > 0
ORDER BY seq_scan DESC;
COMMENT ON VIEW monitor.pg_seq_scan IS 'table that have seq scan';
GRANT SELECT ON monitor.pg_seq_scan TO pg_monitor;
查看共享内存分配的函数（PG13 以上可用）
DROP FUNCTION IF EXISTS monitor.pg_shmem() CASCADE;
CREATE OR REPLACE FUNCTION monitor.pg_shmem() RETURNS SETOF
    pg_shmem_allocations SET search_path = '' AS $$ SELECT * FROM pg_shmem_allocations;$$ LANGUAGE SQL SECURITY DEFINER;
COMMENT ON FUNCTION monitor.pg_shmem() IS 'security wrapper for system view pg_shmem';
REVOKE ALL ON FUNCTION monitor.pg_shmem() FROM PUBLIC;
REVOKE ALL ON FUNCTION monitor.pg_shmem() FROM dbrole_readonly;
REVOKE ALL ON FUNCTION monitor.pg_shmem() FROM dbrole_offline;
GRANT EXECUTE ON FUNCTION monitor.pg_shmem() TO pg_monitor;

9 - 监控面板

Pigsty 为 PostgreSQL 提供了诸多开箱即用的 Grafana 监控仪表盘

Pigsty 为 PostgreSQL 提供了诸多开箱即用的 Grafana 监控仪表盘： Demo & Gallery。

当前源码共提供 31 个 PostgreSQL 相关面板：files/grafana/pgsql 中有 29 个 PostgreSQL / PGCAT 面板，files/grafana/app 中另有 2 个 PGLOG 面板。它们按层次分为总览、集群、实例、数据库四大类，按数据来源分为 PGSQL、PGCAT、PGLOG 三类。

pigsty-dashboard.jpg

总览

总览 集群 实例 数据库
PGSQL Overview PGSQL Cluster PGSQL Instance PGSQL Database
PGSQL Alert PGRDS Cluster PGRDS Instance PGCAT Database
PGSQL Shard PGSQL Activity PGCAT Instance PGSQL Tables
PGSQL Replication PGSQL Persist PGSQL Table
PGSQL Service PGSQL Proxy PGCAT Table
PGSQL Databases PGSQL Pgbouncer PGSQL Query
PGSQL Patroni PGSQL Session PGCAT Query
PGSQL PITR PGSQL Xacts PGCAT Locks
PGSQL Exporter PGCAT Schema

概览

  • pgsql-overview：PGSQL 模块的主仪表板
  • pgsql-alert：PGSQL 的全局关键指标和警报事件
  • pgsql-shard：关于水平分片的 PGSQL 集群的概览，例如 citus / gpsql 集群

集群

  • pgsql-cluster：一个 PGSQL 集群的主仪表板
  • pgrds-cluster：PGSQL Cluster 的 RDS 版本，专注于所有 PostgreSQL 本身的指标
  • pgsql-activity：关注 PGSQL 集群的会话/负载/QPS/TPS/锁定情况
  • pgsql-replication：关注 PGSQL 集群复制、插槽和发布/订阅
  • pgsql-service：关注 PGSQL 集群服务、代理、路由和负载均衡
  • pgsql-databases：关注所有实例的数据库 CRUD、慢查询和表统计信息
  • pgsql-patroni：关注集群高可用状态，Patroni 组件状态
  • pgsql-pitr：关注集群 PITR 过程的上下文，用于辅助时间点恢复

实例

  • pgsql-instance：单个 PGSQL 实例的主仪表板
  • pgrds-instance：PGSQL Instance 的 RDS 版本，专注于所有 PostgreSQL 本身的指标
  • pgcat-instance：直接从数据库目录获取的实例信息
  • pgsql-proxy：单个 haproxy 负载均衡器的详细指标
  • pgsql-pgbouncer：单个 Pgbouncer 连接池实例中的指标总览
  • pgsql-persist：持久性指标：WAL、XID、检查点、存档、IO
  • pgsql-session：单个实例中的会话和活动/空闲时间的指标
  • pgsql-xacts：关于事务、锁、TPS/QPS 相关的指标
  • pgsql-exporter：Postgres 与 Pgbouncer 监控组件自我监控指标

数据库

  • pgsql-database：单个 PGSQL 数据库的主仪表板
  • pgcat-database：直接从数据库目录获取的数据库信息
  • pgsql-tables：单个数据库内的表/索引访问指标
  • pgsql-table：单个表的详细信息（QPS/RT/索引/序列…）
  • pgcat-table：直接从数据库目录获取的单个表的详细信息（统计/膨胀…）
  • pgsql-query：单个查询的详细信息（QPS/RT）
  • pgcat-query：直接从数据库目录获取的单个查询的详细信息（SQL/统计）
  • pgcat-schema：直接从数据库目录获取关于模式的信息（表/索引/序列…）
  • pgcat-locks：直接从数据库目录获取的关于活动与锁等待的信息

总览

PGSQL Overview：PGSQL 模块的主仪表板

PGSQL Overview

pgsql-overview.jpg

PGSQL Alert：PGSQL 全局核心指标总览与告警事件一览

PGSQL Alert

pgsql-alert.jpg

PGSQL Shard：展示一个 PGSQL 水平分片集群内的横向指标对比：例如 CITUS / GPSQL 集群。

PGSQL Shard

pgsql-shard.jpg

集群

PGSQL Cluster：一个 PGSQL 集群的主仪表板

PGSQL Cluster

pgsql-cluster.jpg

PGRDS Cluster：PGSQL Cluster 的 RDS 版本，专注于所有 PostgreSQL 本身的指标

PGRDS Cluster

pgrds-cluster.jpg

PGSQL Service：关注 PGSQL 集群服务、代理、路由和负载均衡。

PGSQL Service

pgsql-service.jpg

PGSQL Activity：关注 PGSQL 集群的会话/负载/QPS/TPS/锁定情况

PGSQL Activity

pgsql-activity.jpg

PGSQL Replication：关注 PGSQL 集群复制、插槽和发布/订阅。

PGSQL Replication

pgsql-replication.jpg

PGSQL Databases：关注所有实例的数据库 CRUD、慢查询和表统计信息。

PGSQL Databases

pgsql-databases.jpg

PGSQL Patroni：关注集群高可用状态，Patroni 组件状态

PGSQL Patroni

pgsql-patroni.jpg

PGSQL PITR：关注集群 PITR 过程的上下文，用于辅助时间点恢复

PGSQL PITR

pgsql-patroni.jpg

实例

PGSQL Instance：单个 PGSQL 实例的主仪表板

PGSQL Instance

pgsql-instance.jpg

PGRDS Instance：PGSQL Instance 的 RDS 版本，专注于所有 PostgreSQL 本身的指标

PGRDS Instance

pgrds-instance.jpg

PGSQL Proxy：单个 haproxy 负载均衡器的详细指标

PGSQL Proxy

pgsql-proxy.jpg

PGSQL Pgbouncer：单个 Pgbouncer 连接池实例中的指标总览

PGSQL Pgbouncer

pgsql-pgbouncer.jpg

PGSQL Persist：持久性指标：WAL、XID、检查点、存档、IO

PGSQL Persist

pgsql-persist.jpg

PGSQL Xacts：关于事务、锁、TPS/QPS 相关的指标

PGSQL Xacts

pgsql-xacts.jpg

PGSQL Session：单个实例中的会话和活动/空闲时间的指标

PGSQL Session

pgsql-session.jpg

PGSQL Exporter：Postgres/Pgbouncer 监控组件自我监控指标

PGSQL Exporter

pgsql-exporter.jpg

数据库

PGSQL Database：单个 PGSQL 数据库的主仪表板

PGSQL Database

pgsql-database.jpg

PGSQL Tables：单个数据库内的表/索引访问指标

PGSQL Tables

pgsql-tables.jpg

PGSQL Table：单个表的详细信息（QPS/RT/索引/序列…）

PGSQL Table

pgsql-table.jpg

PGSQL Query：单类查询的详细信息（QPS/RT）

PGSQL Query

pgsql-query.jpg

PGCAT

PGCAT Instance：直接从数据库目录获取的实例信息

PGCAT Instance

pgcat-instance.jpg

PGCAT Database：直接从数据库目录获取的数据库信息

PGCAT Database

pgcat-database.jpg

PGCAT Schema：直接从数据库目录获取关于模式的信息（表/索引/序列…）

PGCAT Schema

pgcat-schema.jpg

PGCAT Table：直接从数据库目录获取的单个表的详细信息（统计/膨胀…）

PGCAT Table

pgcat-table.jpg

PGCAT Query：直接从数据库目录获取的单类查询的详细信息（SQL/统计）

PGCAT Query

pgcat-query.jpg

PGCAT Locks：直接从数据库目录获取的关于活动与锁等待的信息

PGCAT Locks

pgcat-locks.jpg

PGLOG

PGLOG Overview：总览 Pigsty CMDB 中的 CSV 日志样本

PGLOG Overview

pglog-overview.jpg

PGLOG Overview：Pigsty CMDB 中的 CSV 日志样本中某一条会话的日志详情

PGLOG Session

pglog-session.jpg

画廊

详情请参考 pigsty/wiki/gallery。

PGSQL Overview

pgsql-overview.jpg

PGSQL Shard

pgsql-shard.jpg

PGSQL Cluster

pgsql-cluster.jpg

PGSQL Service

pgsql-service.jpg

PGSQL Activity

pgsql-activity.jpg

PGSQL Replication

pgsql-replication.jpg

PGSQL Databases

pgsql-databases.jpg

PGSQL Instance

pgsql-instance.jpg

PGSQL Proxy

pgsql-proxy.jpg

PGSQL Pgbouncer

pgsql-pgbouncer.jpg

PGSQL Session

pgsql-session.jpg

PGSQL Xacts

pgsql-xacts.jpg

PGSQL Persist

pgsql-persist.jpg

PGSQL Database

pgsql-database.jpg

PGSQL Tables

pgsql-tables.jpg

PGSQL Table

pgsql-table.jpg

PGSQL Query

pgsql-query.jpg

PGCAT Instance

pgcat-instance.jpg

PGCAT Database

pgcat-database.jpg

PGCAT Schema

pgcat-schema.jpg

PGCAT Table

pgcat-table.jpg

PGCAT Lock

pgcat-locks.jpg

PGCAT Query

pgcat-query.jpg

PGLOG Overview

pglog-overview.jpg

PGLOG Session

pglog-session.jpg

9.1 - 总览面板

PostgreSQL 模块全局总览类监控面板

PostgreSQL 模块全局总览类监控面板，包括：

9.1.1 - PGSQL Overview

PGSQL 模块的主仪表板

PGSQL 模块的主仪表板：Demo

PGSQL Overview 是 PostgreSQL 模块的主仪表板，提供整个 PGSQL 模块的全局概览视图。

pgsql-overview

9.1.2 - PGSQL Alert

PGSQL 的全局关键指标和警报事件

PGSQL 的全局关键指标和警报事件：Demo

PGSQL Alert 仪表板展示 PGSQL 全局核心指标总览与告警事件一览。

pgsql-alert

9.1.3 - PGSQL Shard

关于水平分片的 PGSQL 集群的概览

关于水平分片的 PGSQL 集群的概览：Demo

PGSQL Shard 仪表板展示一个 PGSQL 水平分片集群内的横向指标对比，例如 Citus / GPSQL 集群。

pgsql-shard

9.2 - 集群面板

PostgreSQL 集群级别监控面板

PostgreSQL 集群级别监控面板，包括：

  • PGSQL Cluster：一个 PGSQL 集群的主仪表板
  • PGRDS Cluster：PGSQL Cluster 的 RDS 版本，专注于 PostgreSQL 本身的指标
  • PGSQL Activity：关注 PGSQL 集群的会话/负载/QPS/TPS/锁定情况
  • PGSQL Replication：关注 PGSQL 集群复制、插槽和发布/订阅
  • PGSQL Service：关注 PGSQL 集群服务、代理、路由和负载均衡
  • PGSQL Databases：关注所有实例的数据库 CRUD、慢查询和表统计信息
  • PGSQL Patroni：关注集群高可用状态，Patroni 组件状态
  • PGSQL PITR：关注集群 PITR 过程的上下文，用于辅助时间点恢复

9.2.1 - PGSQL Cluster

一个 PGSQL 集群的主仪表板

一个 PGSQL 集群的主仪表板：Demo

PGSQL Cluster 是单个 PostgreSQL 集群的主仪表板，提供集群级别的核心指标概览。

pgsql-cluster

9.2.2 - PGRDS Cluster

PGSQL Cluster 的 RDS 版本，专注于 PostgreSQL 本身的指标

PGSQL Cluster 的 RDS 版本：Demo

PGRDS Cluster 是 PGSQL Cluster 的 RDS 版本，专注于所有 PostgreSQL 本身的指标，适用于云数据库 RDS 监控场景。

pgrds-cluster

9.2.3 - PGSQL Activity

关注 PGSQL 集群的会话/负载/QPS/TPS/锁定情况

关注 PGSQL 集群的会话/负载/QPS/TPS/锁定情况：Demo

PGSQL Activity 仪表板关注 PGSQL 集群的会话、负载、QPS、TPS 以及锁定情况。

pgsql-activity

9.2.4 - PGSQL Replication

关注 PGSQL 集群复制、插槽和发布/订阅

关注 PGSQL 集群复制、插槽和发布/订阅：Demo

PGSQL Replication 仪表板关注 PGSQL 集群的复制状态、复制插槽和发布/订阅信息。

pgsql-replication

9.2.5 - PGSQL Service

关注 PGSQL 集群服务、代理、路由和负载均衡

关注 PGSQL 集群服务、代理、路由和负载均衡：Demo

PGSQL Service 仪表板关注 PGSQL 集群的服务、代理、路由和负载均衡状态。

pgsql-service

9.2.6 - PGSQL Databases

关注所有实例的数据库 CRUD、慢查询和表统计信息

关注所有实例的数据库 CRUD、慢查询和表统计信息：Demo

PGSQL Databases 仪表板关注集群中所有实例的数据库 CRUD、慢查询和表统计信息。

pgsql-databases

9.2.7 - PGSQL Patroni

关注集群高可用状态，Patroni 组件状态

关注集群高可用状态，Patroni 组件状态：Demo

PGSQL Patroni 仪表板关注集群的高可用状态以及 Patroni 组件的运行状态。

pgsql-patroni

9.2.8 - PGSQL PITR

关注集群 PITR 过程的上下文，用于辅助时间点恢复

关注集群 PITR 过程的上下文：Demo

PGSQL PITR 仪表板关注集群 PITR 过程的上下文，用于辅助时间点恢复操作。

pgsql-pitr

9.3 - 实例面板

PostgreSQL 实例级别监控面板

PostgreSQL 实例级别监控面板，包括：

  • PGSQL Instance：单个 PGSQL 实例的主仪表板
  • PGRDS Instance：PGSQL Instance 的 RDS 版本，专注于 PostgreSQL 本身的指标
  • PGCAT Instance：直接从数据库目录获取的实例信息
  • PGSQL Persist：持久性指标：WAL、XID、检查点、存档、IO
  • PGSQL Proxy：单个 HAProxy 负载均衡器的详细指标
  • PGSQL Pgbouncer：单个 Pgbouncer 连接池实例中的指标总览
  • PGSQL Session：单个实例中的会话和活动/空闲时间的指标
  • PGSQL Xacts：关于事务、锁、TPS/QPS 相关的指标
  • PGSQL Exporter：Postgres 与 Pgbouncer 监控组件自我监控指标

9.3.1 - PGSQL Instance

单个 PGSQL 实例的主仪表板

单个 PGSQL 实例的主仪表板：Demo

PGSQL Instance 是单个 PostgreSQL 实例的主仪表板，提供实例级别的核心指标概览。

pgsql-instance

9.3.2 - PGRDS Instance

PGSQL Instance 的 RDS 版本，专注于 PostgreSQL 本身的指标

PGSQL Instance 的 RDS 版本：Demo

PGRDS Instance 是 PGSQL Instance 的 RDS 版本，专注于所有 PostgreSQL 本身的指标，适用于云数据库 RDS 监控场景。

pgrds-instance

9.3.3 - PGCAT Instance

直接从数据库目录获取的实例信息

直接从数据库目录获取的实例信息：Demo

PGCAT Instance 仪表板展示直接从数据库系统目录获取的实例信息。

pgcat-instance

9.3.4 - PGSQL Persist

持久性指标：WAL、XID、检查点、存档、IO

持久性指标：WAL、XID、检查点、存档、IO：Demo

PGSQL Persist 仪表板关注持久性相关指标：WAL、XID、检查点、存档和 IO。

pgsql-persist

9.3.5 - PGSQL Proxy

单个 HAProxy 负载均衡器的详细指标

单个 HAProxy 负载均衡器的详细指标：Demo

PGSQL Proxy 仪表板展示单个 HAProxy 负载均衡器的详细指标。

pgsql-proxy

9.3.6 - PGSQL Pgbouncer

单个 Pgbouncer 连接池实例中的指标总览

单个 Pgbouncer 连接池实例中的指标总览：Demo

PGSQL Pgbouncer 仪表板展示单个 Pgbouncer 连接池实例中的指标总览。

pgsql-pgbouncer

9.3.7 - PGSQL Session

单个实例中的会话和活动/空闲时间的指标

单个实例中的会话和活动/空闲时间的指标：Demo

PGSQL Session 仪表板展示单个实例中的会话和活动/空闲时间的指标。

pgsql-session

9.3.8 - PGSQL Xacts

关于事务、锁、TPS/QPS 相关的指标

关于事务、锁、TPS/QPS 相关的指标：Demo

PGSQL Xacts 仪表板关注事务、锁、TPS/QPS 相关的指标。

pgsql-xacts

9.3.9 - PGSQL Exporter

Postgres 与 Pgbouncer 监控组件自我监控指标

Postgres 与 Pgbouncer 监控组件自我监控指标：Demo

PGSQL Exporter 仪表板展示 Postgres 与 Pgbouncer 监控组件的自我监控指标。

pgsql-exporter

9.4 - 数据库面板

PostgreSQL 数据库级别监控面板

PostgreSQL 数据库级别监控面板，包括：

  • PGSQL Database：单个 PGSQL 数据库的主仪表板
  • PGCAT Database：直接从数据库目录获取的数据库信息
  • PGSQL Tables：单个数据库内的表/索引访问指标
  • PGSQL Table：单个表的详细信息（QPS/RT/索引/序列……）
  • PGCAT Table：直接从数据库目录获取的单个表的详细信息
  • PGSQL Query：单类查询的详细信息（QPS/RT）
  • PGCAT Query：直接从数据库目录获取的单类查询的详细信息
  • PGCAT Locks：直接从数据库目录获取的关于活动与锁等待的信息
  • PGCAT Schema：直接从数据库目录获取关于模式的信息

9.4.1 - PGSQL Database

单个 PGSQL 数据库的主仪表板

单个 PGSQL 数据库的主仪表板：Demo

PGSQL Database 是单个 PostgreSQL 数据库的主仪表板，提供数据库级别的核心指标概览。

pgsql-database

9.4.2 - PGCAT Database

直接从数据库目录获取的数据库信息

直接从数据库目录获取的数据库信息：Demo

PGCAT Database 仪表板展示直接从数据库系统目录获取的数据库信息。

pgcat-database

9.4.3 - PGSQL Tables

单个数据库内的表/索引访问指标

单个数据库内的表/索引访问指标：Demo

PGSQL Tables 仪表板展示单个数据库内的表和索引访问指标。

pgsql-tables

9.4.4 - PGSQL Table

单个表的详细信息（QPS/RT/索引/序列……）

单个表的详细信息：Demo

PGSQL Table 仪表板展示单个表的详细信息，包括 QPS、RT、索引、序列等指标。

pgsql-table

9.4.5 - PGCAT Table

直接从数据库目录获取的单个表的详细信息

直接从数据库目录获取的单个表的详细信息：Demo

PGCAT Table 仪表板展示直接从数据库系统目录获取的单个表的详细信息，包括统计和膨胀信息。

pgcat-table

9.4.6 - PGSQL Query

单类查询的详细信息（QPS/RT）

单类查询的详细信息：Demo

PGSQL Query 仪表板展示单类查询的详细信息，包括 QPS 和 RT 指标。

pgsql-query

9.4.7 - PGCAT Query

直接从数据库目录获取的单类查询的详细信息

直接从数据库目录获取的单类查询的详细信息：Demo

PGCAT Query 仪表板展示直接从数据库系统目录获取的单类查询的详细信息，包括 SQL 和统计信息。

pgcat-query

9.4.8 - PGCAT Locks

直接从数据库目录获取的关于活动与锁等待的信息

直接从数据库目录获取的关于活动与锁等待的信息：Demo

PGCAT Locks 仪表板展示直接从数据库系统目录获取的关于活动与锁等待的信息。

pgcat-locks

9.4.9 - PGCAT Schema

直接从数据库目录获取关于模式的信息

直接从数据库目录获取关于模式的信息：Demo

PGCAT Schema 仪表板展示直接从数据库系统目录获取的关于模式的信息，包括表、索引、序列等。

pgcat-schema

10 - 指标列表

Pigsty PGSQL 模块提供的完整监控指标列表与释义

PGSQL 模块包含有 638 类可用监控指标。

Metric Name Type Labels Description
ALERTS Unknown category, job, level, ins, severity, ip, alertname, alertstate, instance, cls N/A
ALERTS_FOR_STATE Unknown category, job, level, ins, severity, ip, alertname, instance, cls N/A
cls:pressure1 Unknown job, cls N/A
cls:pressure15 Unknown job, cls N/A
cls:pressure5 Unknown job, cls N/A
go_gc_duration_seconds summary job, ins, ip, instance, quantile, cls A summary of the pause duration of garbage collection cycles.
go_gc_duration_seconds_count Unknown job, ins, ip, instance, cls N/A
go_gc_duration_seconds_sum Unknown job, ins, ip, instance, cls N/A
go_goroutines gauge job, ins, ip, instance, cls Number of goroutines that currently exist.
go_info gauge version, job, ins, ip, instance, cls Information about the Go environment.
go_memstats_alloc_bytes gauge job, ins, ip, instance, cls Number of bytes allocated and still in use.
go_memstats_alloc_bytes_total counter job, ins, ip, instance, cls Total number of bytes allocated, even if freed.
go_memstats_buck_hash_sys_bytes gauge job, ins, ip, instance, cls Number of bytes used by the profiling bucket hash table.
go_memstats_frees_total counter job, ins, ip, instance, cls Total number of frees.
go_memstats_gc_sys_bytes gauge job, ins, ip, instance, cls Number of bytes used for garbage collection system metadata.
go_memstats_heap_alloc_bytes gauge job, ins, ip, instance, cls Number of heap bytes allocated and still in use.
go_memstats_heap_idle_bytes gauge job, ins, ip, instance, cls Number of heap bytes waiting to be used.
go_memstats_heap_inuse_bytes gauge job, ins, ip, instance, cls Number of heap bytes that are in use.
go_memstats_heap_objects gauge job, ins, ip, instance, cls Number of allocated objects.
go_memstats_heap_released_bytes gauge job, ins, ip, instance, cls Number of heap bytes released to OS.
go_memstats_heap_sys_bytes gauge job, ins, ip, instance, cls Number of heap bytes obtained from system.
go_memstats_last_gc_time_seconds gauge job, ins, ip, instance, cls Number of seconds since 1970 of last garbage collection.
go_memstats_lookups_total counter job, ins, ip, instance, cls Total number of pointer lookups.
go_memstats_mallocs_total counter job, ins, ip, instance, cls Total number of mallocs.
go_memstats_mcache_inuse_bytes gauge job, ins, ip, instance, cls Number of bytes in use by mcache structures.
go_memstats_mcache_sys_bytes gauge job, ins, ip, instance, cls Number of bytes used for mcache structures obtained from system.
go_memstats_mspan_inuse_bytes gauge job, ins, ip, instance, cls Number of bytes in use by mspan structures.
go_memstats_mspan_sys_bytes gauge job, ins, ip, instance, cls Number of bytes used for mspan structures obtained from system.
go_memstats_next_gc_bytes gauge job, ins, ip, instance, cls Number of heap bytes when next garbage collection will take place.
go_memstats_other_sys_bytes gauge job, ins, ip, instance, cls Number of bytes used for other system allocations.
go_memstats_stack_inuse_bytes gauge job, ins, ip, instance, cls Number of bytes in use by the stack allocator.
go_memstats_stack_sys_bytes gauge job, ins, ip, instance, cls Number of bytes obtained from system for stack allocator.
go_memstats_sys_bytes gauge job, ins, ip, instance, cls Number of bytes obtained from system.
go_threads gauge job, ins, ip, instance, cls Number of OS threads created.
ins:pressure1 Unknown job, ins, ip, cls N/A
ins:pressure15 Unknown job, ins, ip, cls N/A
ins:pressure5 Unknown job, ins, ip, cls N/A
patroni_cluster_unlocked gauge job, ins, ip, instance, cls, scope Value is 1 if the cluster is unlocked, 0 if locked.
patroni_dcs_last_seen gauge job, ins, ip, instance, cls, scope Epoch timestamp when DCS was last contacted successfully by Patroni.
patroni_failsafe_mode_is_active gauge job, ins, ip, instance, cls, scope Value is 1 if failsafe mode is active, 0 if inactive.
patroni_is_paused gauge job, ins, ip, instance, cls, scope Value is 1 if auto failover is disabled, 0 otherwise.
patroni_master gauge job, ins, ip, instance, cls, scope Value is 1 if this node is the leader, 0 otherwise.
patroni_pending_restart gauge job, ins, ip, instance, cls, scope Value is 1 if the node needs a restart, 0 otherwise.
patroni_postgres_in_archive_recovery gauge job, ins, ip, instance, cls, scope Value is 1 if Postgres is replicating from archive, 0 otherwise.
patroni_postgres_running gauge job, ins, ip, instance, cls, scope Value is 1 if Postgres is running, 0 otherwise.
patroni_postgres_server_version gauge job, ins, ip, instance, cls, scope Version of Postgres (if running), 0 otherwise.
patroni_postgres_streaming gauge job, ins, ip, instance, cls, scope Value is 1 if Postgres is streaming, 0 otherwise.
patroni_postgres_timeline counter job, ins, ip, instance, cls, scope Postgres timeline of this node (if running), 0 otherwise.
patroni_postmaster_start_time gauge job, ins, ip, instance, cls, scope Epoch seconds since Postgres started.
patroni_primary gauge job, ins, ip, instance, cls, scope Value is 1 if this node is the leader, 0 otherwise.
patroni_replica gauge job, ins, ip, instance, cls, scope Value is 1 if this node is a replica, 0 otherwise.
patroni_standby_leader gauge job, ins, ip, instance, cls, scope Value is 1 if this node is the standby_leader, 0 otherwise.
patroni_sync_standby gauge job, ins, ip, instance, cls, scope Value is 1 if this node is a sync standby replica, 0 otherwise.
patroni_up Unknown job, ins, ip, instance, cls N/A
patroni_version gauge job, ins, ip, instance, cls, scope Patroni semver without periods.
patroni_xlog_location counter job, ins, ip, instance, cls, scope Current location of the Postgres transaction log, 0 if this node is not the leader.
patroni_xlog_paused gauge job, ins, ip, instance, cls, scope Value is 1 if the Postgres xlog is paused, 0 otherwise.
patroni_xlog_received_location counter job, ins, ip, instance, cls, scope Current location of the received Postgres transaction log, 0 if this node is not a replica.
patroni_xlog_replayed_location counter job, ins, ip, instance, cls, scope Current location of the replayed Postgres transaction log, 0 if this node is not a replica.
patroni_xlog_replayed_timestamp gauge job, ins, ip, instance, cls, scope Current timestamp of the replayed Postgres transaction log, 0 if null.
pg:cls:active_backends Unknown job, cls N/A
pg:cls:active_time_rate15m Unknown job, cls N/A
pg:cls:active_time_rate1m Unknown job, cls N/A
pg:cls:active_time_rate5m Unknown job, cls N/A
pg:cls:age Unknown job, cls N/A
pg:cls:buf_alloc_rate1m Unknown job, cls N/A
pg:cls:buf_clean_rate1m Unknown job, cls N/A
pg:cls:buf_flush_backend_rate1m Unknown job, cls N/A
pg:cls:buf_flush_checkpoint_rate1m Unknown job, cls N/A
pg:cls:cpu_count Unknown job, cls N/A
pg:cls:cpu_usage Unknown job, cls N/A
pg:cls:cpu_usage_15m Unknown job, cls N/A
pg:cls:cpu_usage_1m Unknown job, cls N/A
pg:cls:cpu_usage_5m Unknown job, cls N/A
pg:cls:db_size Unknown job, cls N/A
pg:cls:file_size Unknown job, cls N/A
pg:cls:ixact_backends Unknown job, cls N/A
pg:cls:ixact_time_rate1m Unknown job, cls N/A
pg:cls:lag_bytes Unknown job, cls N/A
pg:cls:lag_seconds Unknown job, cls N/A
pg:cls:leader Unknown job, ins, ip, instance, cls N/A
pg:cls:load1 Unknown job, cls N/A
pg:cls:load15 Unknown job, cls N/A
pg:cls:load5 Unknown job, cls N/A
pg:cls:lock_count Unknown job, cls N/A
pg:cls:locks Unknown job, cls, mode N/A
pg:cls:log_size Unknown job, cls N/A
pg:cls:lsn_rate1m Unknown job, cls N/A
pg:cls:members Unknown job, ins, ip, cls N/A
pg:cls:num_backends Unknown job, cls N/A
pg:cls:partition Unknown job, cls N/A
pg:cls:receiver Unknown state, slot_name, job, appname, ip, cls, sender_host, sender_port N/A
pg:cls:rlock_count Unknown job, cls N/A
pg:cls:saturation1 Unknown job, cls N/A
pg:cls:saturation15 Unknown job, cls N/A
pg:cls:saturation5 Unknown job, cls N/A
pg:cls:sender Unknown pid, usename, address, job, ins, appname, ip, cls N/A
pg:cls:session_time_rate1m Unknown job, cls N/A
pg:cls:size Unknown job, cls N/A
pg:cls:slot_count Unknown job, cls N/A
pg:cls:slot_retained_bytes Unknown job, cls N/A
pg:cls:standby_count Unknown job, cls N/A
pg:cls:sync_state Unknown job, cls N/A
pg:cls:timeline Unknown job, cls N/A
pg:cls:tup_deleted_rate1m Unknown job, cls N/A
pg:cls:tup_fetched_rate1m Unknown job, cls N/A
pg:cls:tup_inserted_rate1m Unknown job, cls N/A
pg:cls:tup_modified_rate1m Unknown job, cls N/A
pg:cls:tup_returned_rate1m Unknown job, cls N/A
pg:cls:wal_size Unknown job, cls N/A
pg:cls:xact_commit_rate15m Unknown job, cls N/A
pg:cls:xact_commit_rate1m Unknown job, cls N/A
pg:cls:xact_commit_rate5m Unknown job, cls N/A
pg:cls:xact_rollback_rate15m Unknown job, cls N/A
pg:cls:xact_rollback_rate1m Unknown job, cls N/A
pg:cls:xact_rollback_rate5m Unknown job, cls N/A
pg:cls:xact_total_rate15m Unknown job, cls N/A
pg:cls:xact_total_rate1m Unknown job, cls N/A
pg:cls:xact_total_sigma15m Unknown job, cls N/A
pg:cls:xlock_count Unknown job, cls N/A
pg:db:active_backends Unknown datname, job, ins, ip, instance, cls N/A
pg:db:active_time_rate15m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:active_time_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:active_time_rate5m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:age Unknown datname, job, ins, ip, instance, cls N/A
pg:db:age_deriv1h Unknown datname, job, ins, ip, instance, cls N/A
pg:db:age_exhaust Unknown datname, job, ins, ip, instance, cls N/A
pg:db:blk_io_time_seconds_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:blk_read_time_seconds_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:blk_write_time_seconds_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:blks_access_1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:blks_hit_1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:blks_hit_ratio1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:blks_read_1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:conn_limit Unknown datname, job, ins, ip, instance, cls N/A
pg:db:conn_usage Unknown datname, job, ins, ip, instance, cls N/A
pg:db:db_size Unknown datname, job, ins, ip, instance, cls N/A
pg:db:ixact_backends Unknown datname, job, ins, ip, instance, cls N/A
pg:db:ixact_time_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:lock_count Unknown datname, job, ins, ip, instance, cls N/A
pg:db:num_backends Unknown datname, job, ins, ip, instance, cls N/A
pg:db:rlock_count Unknown datname, job, ins, ip, instance, cls N/A
pg:db:session_time_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:temp_bytes_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:temp_files_1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:tup_deleted_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:tup_fetched_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:tup_inserted_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:tup_modified_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:tup_returned_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:wlock_count Unknown datname, job, ins, ip, instance, cls N/A
pg:db:xact_commit_rate15m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:xact_commit_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:xact_commit_rate5m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:xact_rollback_rate15m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:xact_rollback_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:xact_rollback_rate5m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:xact_total_rate15m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:xact_total_rate1m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:xact_total_rate5m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:xact_total_sigma15m Unknown datname, job, ins, ip, instance, cls N/A
pg:db:xlock_count Unknown datname, job, ins, ip, instance, cls N/A
pg:env:active_backends Unknown job N/A
pg:env:active_time_rate15m Unknown job N/A
pg:env:active_time_rate1m Unknown job N/A
pg:env:active_time_rate5m Unknown job N/A
pg:env:age Unknown job N/A
pg:env:cpu_count Unknown job N/A
pg:env:cpu_usage Unknown job N/A
pg:env:cpu_usage_15m Unknown job N/A
pg:env:cpu_usage_1m Unknown job N/A
pg:env:cpu_usage_5m Unknown job N/A
pg:env:ixact_backends Unknown job N/A
pg:env:ixact_time_rate1m Unknown job N/A
pg:env:lag_bytes Unknown job N/A
pg:env:lag_seconds Unknown job N/A
pg:env:lsn_rate1m Unknown job N/A
pg:env:session_time_rate1m Unknown job N/A
pg:env:tup_deleted_rate1m Unknown job N/A
pg:env:tup_fetched_rate1m Unknown job N/A
pg:env:tup_inserted_rate1m Unknown job N/A
pg:env:tup_modified_rate1m Unknown job N/A
pg:env:tup_returned_rate1m Unknown job N/A
pg:env:xact_commit_rate15m Unknown job N/A
pg:env:xact_commit_rate1m Unknown job N/A
pg:env:xact_commit_rate5m Unknown job N/A
pg:env:xact_rollback_rate15m Unknown job N/A
pg:env:xact_rollback_rate1m Unknown job N/A
pg:env:xact_rollback_rate5m Unknown job N/A
pg:env:xact_total_rate15m Unknown job N/A
pg:env:xact_total_rate1m Unknown job N/A
pg:env:xact_total_sigma15m Unknown job N/A
pg:ins:active_backends Unknown job, ins, ip, instance, cls N/A
pg:ins:active_time_rate15m Unknown job, ins, ip, instance, cls N/A
pg:ins:active_time_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:active_time_rate5m Unknown job, ins, ip, instance, cls N/A
pg:ins:age Unknown job, ins, ip, instance, cls N/A
pg:ins:blks_hit_ratio1m Unknown job, ins, ip, instance, cls N/A
pg:ins:buf_alloc_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:buf_clean_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:buf_flush_backend_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:buf_flush_checkpoint_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:ckpt_1h Unknown job, ins, ip, instance, cls N/A
pg:ins:ckpt_req_1m Unknown job, ins, ip, instance, cls N/A
pg:ins:ckpt_timed_1m Unknown job, ins, ip, instance, cls N/A
pg:ins:conn_limit Unknown job, ins, ip, instance, cls N/A
pg:ins:conn_usage Unknown job, ins, ip, instance, cls N/A
pg:ins:cpu_count Unknown job, ins, ip, instance, cls N/A
pg:ins:cpu_usage Unknown job, ins, ip, instance, cls N/A
pg:ins:cpu_usage_15m Unknown job, ins, ip, instance, cls N/A
pg:ins:cpu_usage_1m Unknown job, ins, ip, instance, cls N/A
pg:ins:cpu_usage_5m Unknown job, ins, ip, instance, cls N/A
pg:ins:db_size Unknown job, ins, ip, instance, cls N/A
pg:ins:file_size Unknown job, ins, ip, instance, cls N/A
pg:ins:fs_size Unknown job, ins, ip, instance, cls N/A
pg:ins:is_leader Unknown job, ins, ip, instance, cls N/A
pg:ins:ixact_backends Unknown job, ins, ip, instance, cls N/A
pg:ins:ixact_time_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:lag_bytes Unknown job, ins, ip, instance, cls N/A
pg:ins:lag_seconds Unknown job, ins, ip, instance, cls N/A
pg:ins:load1 Unknown job, ins, ip, instance, cls N/A
pg:ins:load15 Unknown job, ins, ip, instance, cls N/A
pg:ins:load5 Unknown job, ins, ip, instance, cls N/A
pg:ins:lock_count Unknown job, ins, ip, instance, cls N/A
pg:ins:locks Unknown job, ins, ip, mode, instance, cls N/A
pg:ins:log_size Unknown job, ins, ip, instance, cls N/A
pg:ins:lsn_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:mem_size Unknown job, ins, ip, instance, cls N/A
pg:ins:num_backends Unknown job, ins, ip, instance, cls N/A
pg:ins:rlock_count Unknown job, ins, ip, instance, cls N/A
pg:ins:saturation1 Unknown job, ins, ip, cls N/A
pg:ins:saturation15 Unknown job, ins, ip, cls N/A
pg:ins:saturation5 Unknown job, ins, ip, cls N/A
pg:ins:session_time_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:slot_retained_bytes Unknown job, ins, ip, instance, cls N/A
pg:ins:space_usage Unknown job, ins, ip, instance, cls N/A
pg:ins:status Unknown job, ins, ip, instance, cls N/A
pg:ins:sync_state Unknown job, ins, instance, cls N/A
pg:ins:target_count Unknown job, cls, ins N/A
pg:ins:timeline Unknown job, ins, ip, instance, cls N/A
pg:ins:tup_deleted_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:tup_fetched_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:tup_inserted_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:tup_modified_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:tup_returned_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:wal_size Unknown job, ins, ip, instance, cls N/A
pg:ins:wlock_count Unknown job, ins, ip, instance, cls N/A
pg:ins:xact_commit_rate15m Unknown job, ins, ip, instance, cls N/A
pg:ins:xact_commit_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:xact_commit_rate5m Unknown job, ins, ip, instance, cls N/A
pg:ins:xact_rollback_rate15m Unknown job, ins, ip, instance, cls N/A
pg:ins:xact_rollback_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:xact_rollback_rate5m Unknown job, ins, ip, instance, cls N/A
pg:ins:xact_total_rate15m Unknown job, ins, ip, instance, cls N/A
pg:ins:xact_total_rate1m Unknown job, ins, ip, instance, cls N/A
pg:ins:xact_total_rate5m Unknown job, ins, ip, instance, cls N/A
pg:ins:xact_total_sigma15m Unknown job, ins, ip, instance, cls N/A
pg:ins:xlock_count Unknown job, ins, ip, instance, cls N/A
pg:query:call_rate1m Unknown datname, query, job, ins, ip, instance, cls N/A
pg:query:rt_1m Unknown datname, query, job, ins, ip, instance, cls N/A
pg:table:scan_rate1m Unknown datname, relname, job, ins, ip, instance, cls N/A
pg_activity_count gauge datname, state, job, ins, ip, instance, cls Count of connection among (datname,state)
pg_activity_max_conn_duration gauge datname, state, job, ins, ip, instance, cls Max backend session duration since state change among (datname, state)
pg_activity_max_duration gauge datname, state, job, ins, ip, instance, cls Max duration since last state change among (datname, state)
pg_activity_max_tx_duration gauge datname, state, job, ins, ip, instance, cls Max transaction duration since state change among (datname, state)
pg_archiver_failed_count counter job, ins, ip, instance, cls Number of failed attempts for archiving WAL files
pg_archiver_finish_count counter job, ins, ip, instance, cls Number of WAL files that have been successfully archived
pg_archiver_last_failed_time counter job, ins, ip, instance, cls Time of the last failed archival operation
pg_archiver_last_finish_time counter job, ins, ip, instance, cls Time of the last successful archive operation
pg_archiver_reset_time gauge job, ins, ip, instance, cls Time at which archive statistics were last reset
pg_backend_count gauge type, job, ins, ip, instance, cls Database backend process count by backend_type
pg_bgwriter_buffers_alloc counter job, ins, ip, instance, cls Number of buffers allocated
pg_bgwriter_buffers_backend counter job, ins, ip, instance, cls Number of buffers written directly by a backend
pg_bgwriter_buffers_backend_fsync counter job, ins, ip, instance, cls Number of times a backend had to execute its own fsync call
pg_bgwriter_buffers_checkpoint counter job, ins, ip, instance, cls Number of buffers written during checkpoints
pg_bgwriter_buffers_clean counter job, ins, ip, instance, cls Number of buffers written by the background writer
pg_bgwriter_checkpoint_sync_time counter job, ins, ip, instance, cls Total amount of time that has been spent in the portion of checkpoint processing where files are synchronized to disk, in seconds
pg_bgwriter_checkpoint_write_time counter job, ins, ip, instance, cls Total amount of time that has been spent in the portion of checkpoint processing where files are written to disk, in seconds
pg_bgwriter_checkpoints_req counter job, ins, ip, instance, cls Number of requested checkpoints that have been performed
pg_bgwriter_checkpoints_timed counter job, ins, ip, instance, cls Number of scheduled checkpoints that have been performed
pg_bgwriter_maxwritten_clean counter job, ins, ip, instance, cls Number of times the background writer stopped a cleaning scan because it had written too many buffers
pg_bgwriter_reset_time counter job, ins, ip, instance, cls Time at which bgwriter statistics were last reset
pg_boot_time gauge job, ins, ip, instance, cls unix timestamp when postmaster boot
pg_checkpoint_checkpoint_lsn counter job, ins, ip, instance, cls Latest checkpoint location
pg_checkpoint_elapse gauge job, ins, ip, instance, cls Seconds elapsed since latest checkpoint in seconds
pg_checkpoint_full_page_writes gauge job, ins, ip, instance, cls Latest checkpoint’s full_page_writes enabled
pg_checkpoint_newest_commit_ts_xid counter job, ins, ip, instance, cls Latest checkpoint’s newestCommitTsXid
pg_checkpoint_next_multi_offset counter job, ins, ip, instance, cls Latest checkpoint’s NextMultiOffset
pg_checkpoint_next_multixact_id counter job, ins, ip, instance, cls Latest checkpoint’s NextMultiXactId
pg_checkpoint_next_oid counter job, ins, ip, instance, cls Latest checkpoint’s NextOID
pg_checkpoint_next_xid counter job, ins, ip, instance, cls Latest checkpoint’s NextXID xid
pg_checkpoint_next_xid_epoch counter job, ins, ip, instance, cls Latest checkpoint’s NextXID epoch
pg_checkpoint_oldest_active_xid counter job, ins, ip, instance, cls Latest checkpoint’s oldestActiveXID
pg_checkpoint_oldest_commit_ts_xid counter job, ins, ip, instance, cls Latest checkpoint’s oldestCommitTsXid
pg_checkpoint_oldest_multi_dbid gauge job, ins, ip, instance, cls Latest checkpoint’s oldestMulti’s DB OID
pg_checkpoint_oldest_multi_xid counter job, ins, ip, instance, cls Latest checkpoint’s oldestMultiXid
pg_checkpoint_oldest_xid counter job, ins, ip, instance, cls Latest checkpoint’s oldestXID
pg_checkpoint_oldest_xid_dbid gauge job, ins, ip, instance, cls Latest checkpoint’s oldestXID’s DB OID
pg_checkpoint_prev_tli counter job, ins, ip, instance, cls Latest checkpoint’s PrevTimeLineID
pg_checkpoint_redo_lsn counter job, ins, ip, instance, cls Latest checkpoint’s REDO location
pg_checkpoint_time counter job, ins, ip, instance, cls Time of latest checkpoint
pg_checkpoint_tli counter job, ins, ip, instance, cls Latest checkpoint’s TimeLineID
pg_conf_reload_time gauge job, ins, ip, instance, cls seconds since last configuration reload
pg_db_active_time counter datname, job, ins, ip, instance, cls Time spent executing SQL statements in this database, in seconds
pg_db_age gauge datname, job, ins, ip, instance, cls Age of database calculated from datfrozenxid
pg_db_allow_conn gauge datname, job, ins, ip, instance, cls If false(0) then no one can connect to this database.
pg_db_blk_read_time counter datname, job, ins, ip, instance, cls Time spent reading data file blocks by backends in this database, in seconds
pg_db_blk_write_time counter datname, job, ins, ip, instance, cls Time spent writing data file blocks by backends in this database, in seconds
pg_db_blks_access counter datname, job, ins, ip, instance, cls Number of times disk blocks that accessed read+hit
pg_db_blks_hit counter datname, job, ins, ip, instance, cls Number of times disk blocks were found already in the buffer cache
pg_db_blks_read counter datname, job, ins, ip, instance, cls Number of disk blocks read in this database
pg_db_cks_fail_time gauge datname, job, ins, ip, instance, cls Time at which the last data page checksum failure was detected in this database
pg_db_cks_fails counter datname, job, ins, ip, instance, cls Number of data page checksum failures detected in this database, -1 for not enabled
pg_db_confl_confl_bufferpin counter datname, job, ins, ip, instance, cls Number of queries in this database that have been canceled due to pinned buffers
pg_db_confl_confl_deadlock counter datname, job, ins, ip, instance, cls Number of queries in this database that have been canceled due to deadlocks
pg_db_confl_confl_lock counter datname, job, ins, ip, instance, cls Number of queries in this database that have been canceled due to lock timeouts
pg_db_confl_confl_snapshot counter datname, job, ins, ip, instance, cls Number of queries in this database that have been canceled due to old snapshots
pg_db_confl_confl_tablespace counter datname, job, ins, ip, instance, cls Number of queries in this database that have been canceled due to dropped tablespaces
pg_db_conflicts counter datname, job, ins, ip, instance, cls Number of queries canceled due to conflicts with recovery in this database
pg_db_conn_limit gauge datname, job, ins, ip, instance, cls Sets maximum number of concurrent connections that can be made to this database. -1 means no limit.
pg_db_datid gauge datname, job, ins, ip, instance, cls OID of the database
pg_db_deadlocks counter datname, job, ins, ip, instance, cls Number of deadlocks detected in this database
pg_db_frozen_xid gauge datname, job, ins, ip, instance, cls All transaction IDs before this one have been frozened
pg_db_is_template gauge datname, job, ins, ip, instance, cls If true(1), then this database can be cloned by any user with CREATEDB privileges
pg_db_ixact_time counter datname, job, ins, ip, instance, cls Time spent idling while in a transaction in this database, in seconds
pg_db_numbackends gauge datname, job, ins, ip, instance, cls Number of backends currently connected to this database
pg_db_reset_time counter datname, job, ins, ip, instance, cls Time at which database statistics were last reset
pg_db_session_time counter datname, job, ins, ip, instance, cls Time spent by database sessions in this database, in seconds
pg_db_sessions counter datname, job, ins, ip, instance, cls Total number of sessions established to this database
pg_db_sessions_abandoned counter datname, job, ins, ip, instance, cls Number of database sessions to this database that were terminated because connection to the client was lost
pg_db_sessions_fatal counter datname, job, ins, ip, instance, cls Number of database sessions to this database that were terminated by fatal errors
pg_db_sessions_killed counter datname, job, ins, ip, instance, cls Number of database sessions to this database that were terminated by operator intervention
pg_db_temp_bytes counter datname, job, ins, ip, instance, cls Total amount of data written to temporary files by queries in this database.
pg_db_temp_files counter datname, job, ins, ip, instance, cls Number of temporary files created by queries in this database
pg_db_tup_deleted counter datname, job, ins, ip, instance, cls Number of rows deleted by queries in this database
pg_db_tup_fetched counter datname, job, ins, ip, instance, cls Number of rows fetched by queries in this database
pg_db_tup_inserted counter datname, job, ins, ip, instance, cls Number of rows inserted by queries in this database
pg_db_tup_modified counter datname, job, ins, ip, instance, cls Number of rows modified by queries in this database
pg_db_tup_returned counter datname, job, ins, ip, instance, cls Number of rows returned by queries in this database
pg_db_tup_updated counter datname, job, ins, ip, instance, cls Number of rows updated by queries in this database
pg_db_xact_commit counter datname, job, ins, ip, instance, cls Number of transactions in this database that have been committed
pg_db_xact_rollback counter datname, job, ins, ip, instance, cls Number of transactions in this database that have been rolled back
pg_db_xact_total counter datname, job, ins, ip, instance, cls Number of transactions in this database
pg_downstream_count gauge state, job, ins, ip, instance, cls Count of corresponding state
pg_exporter_agent_up Unknown job, ins, ip, instance, cls N/A
pg_exporter_last_scrape_time gauge job, ins, ip, instance, cls seconds exporter spending on scrapping
pg_exporter_query_cache_ttl gauge datname, query, job, ins, ip, instance, cls times to live of query cache
pg_exporter_query_scrape_duration gauge datname, query, job, ins, ip, instance, cls seconds query spending on scrapping
pg_exporter_query_scrape_error_count gauge datname, query, job, ins, ip, instance, cls times the query failed
pg_exporter_query_scrape_hit_count gauge datname, query, job, ins, ip, instance, cls numbers been scrapped from this query
pg_exporter_query_scrape_metric_count gauge datname, query, job, ins, ip, instance, cls numbers of metrics been scrapped from this query
pg_exporter_query_scrape_total_count gauge datname, query, job, ins, ip, instance, cls times exporter server was scraped for metrics
pg_exporter_scrape_duration gauge job, ins, ip, instance, cls seconds exporter spending on scrapping
pg_exporter_scrape_error_count counter job, ins, ip, instance, cls times exporter was scraped for metrics and failed
pg_exporter_scrape_total_count counter job, ins, ip, instance, cls times exporter was scraped for metrics
pg_exporter_server_scrape_duration gauge datname, job, ins, ip, instance, cls seconds exporter server spending on scrapping
pg_exporter_server_scrape_error_count Unknown datname, job, ins, ip, instance, cls N/A
pg_exporter_server_scrape_total_count gauge datname, job, ins, ip, instance, cls times exporter server was scraped for metrics
pg_exporter_server_scrape_total_seconds gauge datname, job, ins, ip, instance, cls seconds exporter server spending on scrapping
pg_exporter_up gauge job, ins, ip, instance, cls always be 1 if your could retrieve metrics
pg_exporter_uptime gauge job, ins, ip, instance, cls seconds since exporter primary server inited
pg_flush_lsn counter job, ins, ip, instance, cls primary only, location of current wal syncing
pg_func_calls counter datname, funcname, job, ins, ip, instance, cls Number of times this function has been called
pg_func_self_time counter datname, funcname, job, ins, ip, instance, cls Total time spent in this function itself, not including other functions called by it, in ms
pg_func_total_time counter datname, funcname, job, ins, ip, instance, cls Total time spent in this function and all other functions called by it, in ms
pg_in_recovery gauge job, ins, ip, instance, cls server is in recovery mode? 1 for yes 0 for no
pg_index_idx_blks_hit counter datname, relname, job, ins, relid, ip, instance, cls, idxname Number of buffer hits in this index
pg_index_idx_blks_read counter datname, relname, job, ins, relid, ip, instance, cls, idxname Number of disk blocks read from this index
pg_index_idx_scan counter datname, relname, job, ins, relid, ip, instance, cls, idxname Number of index scans initiated on this index
pg_index_idx_tup_fetch counter datname, relname, job, ins, relid, ip, instance, cls, idxname Number of live table rows fetched by simple index scans using this index
pg_index_idx_tup_read counter datname, relname, job, ins, relid, ip, instance, cls, idxname Number of index entries returned by scans on this index
pg_index_relpages gauge datname, relname, job, ins, relid, ip, instance, cls, idxname Size of the on-disk representation of this index in pages
pg_index_reltuples gauge datname, relname, job, ins, relid, ip, instance, cls, idxname Estimate relation tuples
pg_insert_lsn counter job, ins, ip, instance, cls primary only, location of current wal inserting
pg_io_evictions counter type, job, ins, object, ip, context, instance, cls Number of times a block has been written out from a shared or local buffer
pg_io_extend_time counter type, job, ins, object, ip, context, instance, cls Time spent in extend operations in seconds
pg_io_extends counter type, job, ins, object, ip, context, instance, cls Number of relation extend operations, each of the size specified in op_bytes.
pg_io_fsync_time counter type, job, ins, object, ip, context, instance, cls Time spent in fsync operations in seconds
pg_io_fsyncs counter type, job, ins, object, ip, context, instance, cls Number of fsync calls. These are only tracked in context normal
pg_io_hits counter type, job, ins, object, ip, context, instance, cls The number of times a desired block was found in a shared buffer.
pg_io_op_bytes gauge type, job, ins, object, ip, context, instance, cls The number of bytes per unit of I/O read, written, or extended. 8192 by default
pg_io_read_time counter type, job, ins, object, ip, context, instance, cls Time spent in read operations in seconds
pg_io_reads counter type, job, ins, object, ip, context, instance, cls Number of read operations, each of the size specified in op_bytes.
pg_io_reset_time gauge type, job, ins, object, ip, context, instance, cls Timestamp at which these statistics were last reset
pg_io_reuses counter type, job, ins, object, ip, context, instance, cls The number of times an existing buffer in reused
pg_io_write_time counter type, job, ins, object, ip, context, instance, cls Time spent in write operations in seconds
pg_io_writeback_time counter type, job, ins, object, ip, context, instance, cls Time spent in writeback operations in seconds
pg_io_writebacks counter type, job, ins, object, ip, context, instance, cls Number of units of size op_bytes which the process requested the kernel write out to permanent storage.
pg_io_writes counter type, job, ins, object, ip, context, instance, cls Number of write operations, each of the size specified in op_bytes.
pg_is_in_recovery gauge job, ins, ip, instance, cls 1 if in recovery mode
pg_is_wal_replay_paused gauge job, ins, ip, instance, cls 1 if wal play paused
pg_lag gauge job, ins, ip, instance, cls replica only, replication lag in seconds
pg_last_replay_time gauge job, ins, ip, instance, cls time when last transaction been replayed
pg_lock_count gauge datname, job, ins, ip, mode, instance, cls Number of locks of corresponding mode and database
pg_lsn counter job, ins, ip, instance, cls log sequence number, current write location
pg_meta_info gauge cls, extensions, version, job, ins, primary_conninfo, conf_path, hba_path, ip, cluster_id, instance, listen_port, wal_level, ver_num, cluster_name, data_dir constant 1
pg_query_calls counter datname, query, job, ins, ip, instance, cls Number of times the statement was executed
pg_query_exec_time counter datname, query, job, ins, ip, instance, cls Total time spent executing the statement, in seconds
pg_query_io_time counter datname, query, job, ins, ip, instance, cls Total time the statement spent reading and writing blocks, in seconds
pg_query_rows counter datname, query, job, ins, ip, instance, cls Total number of rows retrieved or affected by the statement
pg_query_sblk_dirtied counter datname, query, job, ins, ip, instance, cls Total number of shared blocks dirtied by the statement
pg_query_sblk_hit counter datname, query, job, ins, ip, instance, cls Total number of shared block cache hits by the statement
pg_query_sblk_read counter datname, query, job, ins, ip, instance, cls Total number of shared blocks read by the statement
pg_query_sblk_written counter datname, query, job, ins, ip, instance, cls Total number of shared blocks written by the statement
pg_query_wal_bytes counter datname, query, job, ins, ip, instance, cls Total amount of WAL bytes generated by the statement
pg_receive_lsn counter job, ins, ip, instance, cls replica only, location of wal synced to disk
pg_recovery_backup_end_lsn counter job, ins, ip, instance, cls Backup end location
pg_recovery_backup_start_lsn counter job, ins, ip, instance, cls Backup start location
pg_recovery_min_lsn counter job, ins, ip, instance, cls Minimum recovery ending location
pg_recovery_min_timeline counter job, ins, ip, instance, cls Min recovery ending loc’s timeline
pg_recovery_prefetch_block_distance gauge job, ins, ip, instance, cls How many blocks ahead the prefetcher is looking
pg_recovery_prefetch_hit counter job, ins, ip, instance, cls Number of blocks not prefetched because they were already in the buffer pool
pg_recovery_prefetch_io_depth gauge job, ins, ip, instance, cls How many prefetches have been initiated but are not yet known to have completed
pg_recovery_prefetch_prefetch counter job, ins, ip, instance, cls Number of blocks prefetched because they were not in the buffer pool
pg_recovery_prefetch_reset_time counter job, ins, ip, instance, cls Time at which these recovery prefetch statistics were last reset
pg_recovery_prefetch_skip_fpw gauge job, ins, ip, instance, cls Number of blocks not prefetched because a full page image was included in the WAL
pg_recovery_prefetch_skip_init counter job, ins, ip, instance, cls Number of blocks not prefetched because they would be zero-initialized
pg_recovery_prefetch_skip_new counter job, ins, ip, instance, cls Number of blocks not prefetched because they didn’t exist yet
pg_recovery_prefetch_skip_rep counter job, ins, ip, instance, cls Number of blocks not prefetched because they were already recently prefetched
pg_recovery_prefetch_wal_distance gauge job, ins, ip, instance, cls How many bytes ahead the prefetcher is looking
pg_recovery_require_record gauge job, ins, ip, instance, cls End-of-backup record required
pg_recv_flush_lsn counter state, slot_name, job, ins, ip, instance, cls, sender_host, sender_port Last write-ahead log location already received and flushed to disk
pg_recv_flush_tli counter state, slot_name, job, ins, ip, instance, cls, sender_host, sender_port Timeline number of last write-ahead log location received and flushed to disk
pg_recv_init_lsn counter state, slot_name, job, ins, ip, instance, cls, sender_host, sender_port First write-ahead log location used when WAL receiver is started
pg_recv_init_tli counter state, slot_name, job, ins, ip, instance, cls, sender_host, sender_port First timeline number used when WAL receiver is started
pg_recv_msg_recv_time gauge state, slot_name, job, ins, ip, instance, cls, sender_host, sender_port Receipt time of last message received from origin WAL sender
pg_recv_msg_send_time gauge state, slot_name, job, ins, ip, instance, cls, sender_host, sender_port Send time of last message received from origin WAL sender
pg_recv_pid gauge state, slot_name, job, ins, ip, instance, cls, sender_host, sender_port Process ID of the WAL receiver process
pg_recv_reported_lsn counter state, slot_name, job, ins, ip, instance, cls, sender_host, sender_port Last write-ahead log location reported to origin WAL sender
pg_recv_reported_time gauge state, slot_name, job, ins, ip, instance, cls, sender_host, sender_port Time of last write-ahead log location reported to origin WAL sender
pg_recv_time gauge state, slot_name, job, ins, ip, instance, cls, sender_host, sender_port Time of current snapshot
pg_recv_write_lsn counter state, slot_name, job, ins, ip, instance, cls, sender_host, sender_port Last write-ahead log location already received and written to disk, but not flushed.
pg_relkind_count gauge datname, job, ins, ip, instance, cls, relkind Number of relations of corresponding relkind
pg_repl_backend_xmin counter pid, usename, address, job, ins, appname, ip, instance, cls This standby’s xmin horizon reported by hot_standby_feedback.
pg_repl_client_port gauge pid, usename, address, job, ins, appname, ip, instance, cls TCP port number that the client is using for communication with this WAL sender, or -1 if a Unix socket is used
pg_repl_flush_diff gauge pid, usename, address, job, ins, appname, ip, instance, cls Last log position flushed to disk by this standby server diff with current lsn
pg_repl_flush_lag gauge pid, usename, address, job, ins, appname, ip, instance, cls Time elapsed between flushing recent WAL locally and receiving notification that this standby server has written and flushed it
pg_repl_flush_lsn counter pid, usename, address, job, ins, appname, ip, instance, cls Last write-ahead log location flushed to disk by this standby server
pg_repl_launch_time counter pid, usename, address, job, ins, appname, ip, instance, cls Time when this process was started, i.e., when the client connected to this WAL sender
pg_repl_lsn counter pid, usename, address, job, ins, appname, ip, instance, cls Current log position on this server
pg_repl_replay_diff gauge pid, usename, address, job, ins, appname, ip, instance, cls Last log position replayed into the database on this standby server diff with current lsn
pg_repl_replay_lag gauge pid, usename, address, job, ins, appname, ip, instance, cls Time elapsed between flushing recent WAL locally and receiving notification that this standby server has written, flushed and applied it
pg_repl_replay_lsn counter pid, usename, address, job, ins, appname, ip, instance, cls Last write-ahead log location replayed into the database on this standby server
pg_repl_reply_time gauge pid, usename, address, job, ins, appname, ip, instance, cls Send time of last reply message received from standby server
pg_repl_sent_diff gauge pid, usename, address, job, ins, appname, ip, instance, cls Last log position sent to this standby server diff with current lsn
pg_repl_sent_lsn counter pid, usename, address, job, ins, appname, ip, instance, cls Last write-ahead log location sent on this connection
pg_repl_state gauge pid, usename, address, job, ins, appname, ip, instance, cls Current WAL sender encoded state 0-4 for streaming startup catchup backup stopping
pg_repl_sync_priority gauge pid, usename, address, job, ins, appname, ip, instance, cls Priority of this standby server for being chosen as the synchronous standby
pg_repl_sync_state gauge pid, usename, address, job, ins, appname, ip, instance, cls Encoded synchronous state of this standby server, 0-3 for async potential sync quorum
pg_repl_time counter pid, usename, address, job, ins, appname, ip, instance, cls Current timestamp in unix epoch
pg_repl_write_diff gauge pid, usename, address, job, ins, appname, ip, instance, cls Last log position written to disk by this standby server diff with current lsn
pg_repl_write_lag gauge pid, usename, address, job, ins, appname, ip, instance, cls Time elapsed between flushing recent WAL locally and receiving notification that this standby server has written it
pg_repl_write_lsn counter pid, usename, address, job, ins, appname, ip, instance, cls Last write-ahead log location written to disk by this standby server
pg_replay_lsn counter job, ins, ip, instance, cls replica only, location of wal applied
pg_seq_blks_hit counter datname, job, ins, ip, instance, cls, seqname Number of buffer hits in this sequence
pg_seq_blks_read counter datname, job, ins, ip, instance, cls, seqname Number of disk blocks read from this sequence
pg_seq_last_value counter datname, job, ins, ip, instance, cls, seqname The last sequence value written to disk
pg_setting_block_size gauge job, ins, ip, instance, cls pg page block size, 8192 by default
pg_setting_data_checksums gauge job, ins, ip, instance, cls whether data checksum is enabled, 1 enabled 0 disabled
pg_setting_max_connections gauge job, ins, ip, instance, cls number of concurrent connections to the database server
pg_setting_max_locks_per_transaction gauge job, ins, ip, instance, cls no more than this many distinct objects can be locked at any one time
pg_setting_max_prepared_transactions gauge job, ins, ip, instance, cls maximum number of transactions that can be in the prepared state simultaneously
pg_setting_max_replication_slots gauge job, ins, ip, instance, cls maximum number of replication slots
pg_setting_max_wal_senders gauge job, ins, ip, instance, cls maximum number of concurrent connections from standby servers
pg_setting_max_worker_processes gauge job, ins, ip, instance, cls maximum number of background processes that the system can support
pg_setting_wal_log_hints gauge job, ins, ip, instance, cls whether wal_log_hints is enabled, 1 enabled 0 disabled
pg_size_bytes gauge datname, job, ins, ip, instance, cls File size in bytes
pg_slot_active gauge slot_name, job, ins, ip, instance, cls True(1) if this slot is currently actively being used
pg_slot_catalog_xmin counter slot_name, job, ins, ip, instance, cls The oldest transaction affecting the system catalogs that this slot needs the database to retain.
pg_slot_confirm_lsn counter slot_name, job, ins, ip, instance, cls The address (LSN) up to which the logical slot’s consumer has confirmed receiving data.
pg_slot_reset_time counter slot_name, job, ins, ip, instance, cls When statistics were last reset
pg_slot_restart_lsn counter slot_name, job, ins, ip, instance, cls The address (LSN) of oldest WAL which still might be required by the consumer of this slot
pg_slot_retained_bytes gauge slot_name, job, ins, ip, instance, cls Size of bytes that retained for this slot
pg_slot_safe_wal_size gauge slot_name, job, ins, ip, instance, cls bytes that can be written to WAL which will not make slot into lost
pg_slot_spill_bytes counter slot_name, job, ins, ip, instance, cls Bytes that spilled to disk due to logical decode mem exceeding
pg_slot_spill_count counter slot_name, job, ins, ip, instance, cls Xacts that spilled to disk due to logical decode mem exceeding (a xact can be spilled multiple times)
pg_slot_spill_txns counter slot_name, job, ins, ip, instance, cls Xacts that spilled to disk due to logical decode mem exceeding (subtrans included)
pg_slot_stream_bytes counter slot_name, job, ins, ip, instance, cls Bytes that streamed to decoding output plugin after mem exceed
pg_slot_stream_count counter slot_name, job, ins, ip, instance, cls Xacts that streamed to decoding output plugin after mem exceed (a xact can be streamed multiple times)
pg_slot_stream_txns counter slot_name, job, ins, ip, instance, cls Xacts that streamed to decoding output plugin after mem exceed
pg_slot_temporary gauge slot_name, job, ins, ip, instance, cls True(1) if this is a temporary replication slot.
pg_slot_total_bytes counter slot_name, job, ins, ip, instance, cls Number of decoded bytes sent to the decoding output plugin for this slot
pg_slot_total_txns counter slot_name, job, ins, ip, instance, cls Number of decoded xacts sent to the decoding output plugin for this slot
pg_slot_wal_status gauge slot_name, job, ins, ip, instance, cls WAL reserve status 0-3 means reserved,extended,unreserved,lost, -1 means other
pg_slot_xmin counter slot_name, job, ins, ip, instance, cls The oldest transaction that this slot needs the database to retain.
pg_slru_blks_exists counter job, ins, ip, instance, cls Number of blocks checked for existence for this SLRU
pg_slru_blks_hit counter job, ins, ip, instance, cls Number of times disk blocks were found already in the SLRU, so that a read was not necessary
pg_slru_blks_read counter job, ins, ip, instance, cls Number of disk blocks read for this SLRU
pg_slru_blks_written counter job, ins, ip, instance, cls Number of disk blocks written for this SLRU
pg_slru_blks_zeroed counter job, ins, ip, instance, cls Number of blocks zeroed during initializations
pg_slru_flushes counter job, ins, ip, instance, cls Number of flushes of dirty data for this SLRU
pg_slru_reset_time counter job, ins, ip, instance, cls Time at which these statistics were last reset
pg_slru_truncates counter job, ins, ip, instance, cls Number of truncates for this SLRU
pg_ssl_disabled gauge job, ins, ip, instance, cls Number of client connection that does not use ssl
pg_ssl_enabled gauge job, ins, ip, instance, cls Number of client connection that use ssl
pg_sync_standby_enabled gauge job, ins, ip, names, instance, cls Synchronous commit enabled, 1 if enabled, 0 if disabled
pg_table_age gauge datname, relname, job, ins, ip, instance, cls Age of this table in vacuum cycles
pg_table_analyze_count counter datname, relname, job, ins, ip, instance, cls Number of times this table has been manually analyzed
pg_table_autoanalyze_count counter datname, relname, job, ins, ip, instance, cls Number of times this table has been analyzed by the autovacuum daemon
pg_table_autovacuum_count counter datname, relname, job, ins, ip, instance, cls Number of times this table has been vacuumed by the autovacuum daemon
pg_table_frozenxid counter datname, relname, job, ins, ip, instance, cls All txid before this have been frozen on this table
pg_table_heap_blks_hit counter datname, relname, job, ins, ip, instance, cls Number of buffer hits in this table
pg_table_heap_blks_read counter datname, relname, job, ins, ip, instance, cls Number of disk blocks read from this table
pg_table_idx_blks_hit counter datname, relname, job, ins, ip, instance, cls Number of buffer hits in all indexes on this table
pg_table_idx_blks_read counter datname, relname, job, ins, ip, instance, cls Number of disk blocks read from all indexes on this table
pg_table_idx_scan counter datname, relname, job, ins, ip, instance, cls Number of index scans initiated on this table
pg_table_idx_tup_fetch counter datname, relname, job, ins, ip, instance, cls Number of live rows fetched by index scans
pg_table_kind gauge datname, relname, job, ins, ip, instance, cls Relation kind r/table/114
pg_table_n_dead_tup gauge datname, relname, job, ins, ip, instance, cls Estimated number of dead rows
pg_table_n_ins_since_vacuum gauge datname, relname, job, ins, ip, instance, cls Estimated number of rows inserted since this table was last vacuumed
pg_table_n_live_tup gauge datname, relname, job, ins, ip, instance, cls Estimated number of live rows
pg_table_n_mod_since_analyze gauge datname, relname, job, ins, ip, instance, cls Estimated number of rows modified since this table was last analyzed
pg_table_n_tup_del counter datname, relname, job, ins, ip, instance, cls Number of rows deleted
pg_table_n_tup_hot_upd counter datname, relname, job, ins, ip, instance, cls Number of rows HOT updated (i.e with no separate index update required)
pg_table_n_tup_ins counter datname, relname, job, ins, ip, instance, cls Number of rows inserted
pg_table_n_tup_mod counter datname, relname, job, ins, ip, instance, cls Number of rows modified (insert + update + delete)
pg_table_n_tup_newpage_upd counter datname, relname, job, ins, ip, instance, cls Number of rows updated where the successor version goes onto a new heap page
pg_table_n_tup_upd counter datname, relname, job, ins, ip, instance, cls Number of rows updated (includes HOT updated rows)
pg_table_ncols gauge datname, relname, job, ins, ip, instance, cls Number of columns in the table
pg_table_pages gauge datname, relname, job, ins, ip, instance, cls Size of the on-disk representation of this table in pages
pg_table_relid gauge datname, relname, job, ins, ip, instance, cls Relation oid of this table
pg_table_seq_scan counter datname, relname, job, ins, ip, instance, cls Number of sequential scans initiated on this table
pg_table_seq_tup_read counter datname, relname, job, ins, ip, instance, cls Number of live rows fetched by sequential scans
pg_table_size_bytes gauge datname, relname, job, ins, ip, instance, cls Total bytes of this table (including toast, index, toast index)
pg_table_size_indexsize gauge datname, relname, job, ins, ip, instance, cls Bytes of all related indexes of this table
pg_table_size_relsize gauge datname, relname, job, ins, ip, instance, cls Bytes of this table itself (main, vm, fsm)
pg_table_size_toastsize gauge datname, relname, job, ins, ip, instance, cls Bytes of toast tables of this table
pg_table_tbl_scan counter datname, relname, job, ins, ip, instance, cls Number of scans initiated on this table
pg_table_tup_read counter datname, relname, job, ins, ip, instance, cls Number of live rows fetched by scans
pg_table_tuples counter datname, relname, job, ins, ip, instance, cls All txid before this have been frozen on this table
pg_table_vacuum_count counter datname, relname, job, ins, ip, instance, cls Number of times this table has been manually vacuumed (not counting VACUUM FULL)
pg_timestamp gauge job, ins, ip, instance, cls database current timestamp
pg_up gauge job, ins, ip, instance, cls last scrape was able to connect to the server: 1 for yes, 0 for no
pg_uptime gauge job, ins, ip, instance, cls seconds since postmaster start
pg_version gauge job, ins, ip, instance, cls server version number
pg_wait_count gauge datname, job, ins, event, ip, instance, cls Count of WaitEvent on target database
pg_wal_buffers_full counter job, ins, ip, instance, cls Number of times WAL data was written to disk because WAL buffers became full
pg_wal_bytes counter job, ins, ip, instance, cls Total amount of WAL generated in bytes
pg_wal_fpi counter job, ins, ip, instance, cls Total number of WAL full page images generated
pg_wal_records counter job, ins, ip, instance, cls Total number of WAL records generated
pg_wal_reset_time counter job, ins, ip, instance, cls When statistics were last reset
pg_wal_sync counter job, ins, ip, instance, cls Number of times WAL files were synced to disk via issue_xlog_fsync request
pg_wal_sync_time counter job, ins, ip, instance, cls Total amount of time spent syncing WAL files to disk via issue_xlog_fsync request, in seconds
pg_wal_write counter job, ins, ip, instance, cls Number of times WAL buffers were written out to disk via XLogWrite request.
pg_wal_write_time counter job, ins, ip, instance, cls Total amount of time spent writing WAL buffers to disk via XLogWrite request in seconds
pg_write_lsn counter job, ins, ip, instance, cls primary only, location of current wal writing
pg_xact_xmax counter job, ins, ip, instance, cls First as-yet-unassigned txid. txid >= this are invisible.
pg_xact_xmin counter job, ins, ip, instance, cls Earliest txid that is still active
pg_xact_xnum gauge job, ins, ip, instance, cls Current active transaction count
pgbouncer:cls:load1 Unknown job, cls N/A
pgbouncer:cls:load15 Unknown job, cls N/A
pgbouncer:cls:load5 Unknown job, cls N/A
pgbouncer:db:conn_usage Unknown datname, job, ins, ip, instance, host, cls, real_datname, port N/A
pgbouncer:db:conn_usage_reserve Unknown datname, job, ins, ip, instance, host, cls, real_datname, port N/A
pgbouncer:db:pool_current_conn Unknown datname, job, ins, ip, instance, host, cls, real_datname, port N/A
pgbouncer:db:pool_disabled Unknown datname, job, ins, ip, instance, host, cls, real_datname, port N/A
pgbouncer:db:pool_max_conn Unknown datname, job, ins, ip, instance, host, cls, real_datname, port N/A
pgbouncer:db:pool_paused Unknown datname, job, ins, ip, instance, host, cls, real_datname, port N/A
pgbouncer:db:pool_reserve_size Unknown datname, job, ins, ip, instance, host, cls, real_datname, port N/A
pgbouncer:db:pool_size Unknown datname, job, ins, ip, instance, host, cls, real_datname, port N/A
pgbouncer:ins:free_clients Unknown job, ins, ip, instance, cls N/A
pgbouncer:ins:free_servers Unknown job, ins, ip, instance, cls N/A
pgbouncer:ins:load1 Unknown job, ins, ip, instance, cls N/A
pgbouncer:ins:load15 Unknown job, ins, ip, instance, cls N/A
pgbouncer:ins:load5 Unknown job, ins, ip, instance, cls N/A
pgbouncer:ins:login_clients Unknown job, ins, ip, instance, cls N/A
pgbouncer:ins:pool_databases Unknown job, ins, ip, instance, cls N/A
pgbouncer:ins:pool_users Unknown job, ins, ip, instance, cls N/A
pgbouncer:ins:pools Unknown job, ins, ip, instance, cls N/A
pgbouncer:ins:used_clients Unknown job, ins, ip, instance, cls N/A
pgbouncer_database_current_connections gauge datname, job, ins, ip, instance, host, cls, real_datname, port Current number of connections for this database
pgbouncer_database_disabled gauge datname, job, ins, ip, instance, host, cls, real_datname, port True(1) if this database is currently disabled, else 0
pgbouncer_database_max_connections gauge datname, job, ins, ip, instance, host, cls, real_datname, port Maximum number of allowed connections for this database
pgbouncer_database_min_pool_size gauge datname, job, ins, ip, instance, host, cls, real_datname, port Minimum number of server connections
pgbouncer_database_paused gauge datname, job, ins, ip, instance, host, cls, real_datname, port True(1) if this database is currently paused, else 0
pgbouncer_database_pool_size gauge datname, job, ins, ip, instance, host, cls, real_datname, port Maximum number of server connections
pgbouncer_database_reserve_pool gauge datname, job, ins, ip, instance, host, cls, real_datname, port Maximum number of additional connections for this database
pgbouncer_exporter_agent_up Unknown job, ins, ip, instance, cls N/A
pgbouncer_exporter_last_scrape_time gauge job, ins, ip, instance, cls seconds exporter spending on scrapping
pgbouncer_exporter_query_cache_ttl gauge datname, query, job, ins, ip, instance, cls times to live of query cache
pgbouncer_exporter_query_scrape_duration gauge datname, query, job, ins, ip, instance, cls seconds query spending on scrapping
pgbouncer_exporter_query_scrape_error_count gauge datname, query, job, ins, ip, instance, cls times the query failed
pgbouncer_exporter_query_scrape_hit_count gauge datname, query, job, ins, ip, instance, cls numbers been scrapped from this query
pgbouncer_exporter_query_scrape_metric_count gauge datname, query, job, ins, ip, instance, cls numbers of metrics been scrapped from this query
pgbouncer_exporter_query_scrape_total_count gauge datname, query, job, ins, ip, instance, cls times exporter server was scraped for metrics
pgbouncer_exporter_scrape_duration gauge job, ins, ip, instance, cls seconds exporter spending on scrapping
pgbouncer_exporter_scrape_error_count counter job, ins, ip, instance, cls times exporter was scraped for metrics and failed
pgbouncer_exporter_scrape_total_count counter job, ins, ip, instance, cls times exporter was scraped for metrics
pgbouncer_exporter_server_scrape_duration gauge datname, job, ins, ip, instance, cls seconds exporter server spending on scrapping
pgbouncer_exporter_server_scrape_total_count gauge datname, job, ins, ip, instance, cls times exporter server was scraped for metrics
pgbouncer_exporter_server_scrape_total_seconds gauge datname, job, ins, ip, instance, cls seconds exporter server spending on scrapping
pgbouncer_exporter_up gauge job, ins, ip, instance, cls always be 1 if your could retrieve metrics
pgbouncer_exporter_uptime gauge job, ins, ip, instance, cls seconds since exporter primary server inited
pgbouncer_in_recovery gauge job, ins, ip, instance, cls server is in recovery mode? 1 for yes 0 for no
pgbouncer_list_items gauge job, ins, ip, instance, list, cls Number of corresponding pgbouncer object
pgbouncer_pool_active_cancel_clients gauge datname, job, ins, ip, instance, user, cls, pool_mode Client connections that have forwarded query cancellations to the server and are waiting for the server response.
pgbouncer_pool_active_cancel_servers gauge datname, job, ins, ip, instance, user, cls, pool_mode Server connections that are currently forwarding a cancel request
pgbouncer_pool_active_clients gauge datname, job, ins, ip, instance, user, cls, pool_mode Client connections that are linked to server connection and can process queries
pgbouncer_pool_active_servers gauge datname, job, ins, ip, instance, user, cls, pool_mode Server connections that are linked to a client
pgbouncer_pool_cancel_clients gauge datname, job, ins, ip, instance, user, cls, pool_mode Client connections that have not forwarded query cancellations to the server yet.
pgbouncer_pool_cancel_servers gauge datname, job, ins, ip, instance, user, cls, pool_mode cancel requests have completed that were sent to cancel a query on this server
pgbouncer_pool_idle_servers gauge datname, job, ins, ip, instance, user, cls, pool_mode Server connections that are unused and immediately usable for client queries
pgbouncer_pool_login_servers gauge datname, job, ins, ip, instance, user, cls, pool_mode Server connections currently in the process of logging in
pgbouncer_pool_maxwait gauge datname, job, ins, ip, instance, user, cls, pool_mode How long the first(oldest) client in the queue has waited, in seconds, key metric
pgbouncer_pool_maxwait_us gauge datname, job, ins, ip, instance, user, cls, pool_mode Microsecond part of the maximum waiting time.
pgbouncer_pool_tested_servers gauge datname, job, ins, ip, instance, user, cls, pool_mode Server connections that are currently running reset or check query
pgbouncer_pool_used_servers gauge datname, job, ins, ip, instance, user, cls, pool_mode Server connections that have been idle for more than server_check_delay (means have to run check query)
pgbouncer_pool_waiting_clients gauge datname, job, ins, ip, instance, user, cls, pool_mode Client connections that have sent queries but have not yet got a server connection
pgbouncer_stat_avg_query_count gauge datname, job, ins, ip, instance, cls Average queries per second in last stat period
pgbouncer_stat_avg_query_time gauge datname, job, ins, ip, instance, cls Average query duration, in seconds
pgbouncer_stat_avg_recv gauge datname, job, ins, ip, instance, cls Average received (from clients) bytes per second
pgbouncer_stat_avg_sent gauge datname, job, ins, ip, instance, cls Average sent (to clients) bytes per second
pgbouncer_stat_avg_wait_time gauge datname, job, ins, ip, instance, cls Time spent by clients waiting for a server, in seconds (average per second).
pgbouncer_stat_avg_xact_count gauge datname, job, ins, ip, instance, cls Average transactions per second in last stat period
pgbouncer_stat_avg_xact_time gauge datname, job, ins, ip, instance, cls Average transaction duration, in seconds
pgbouncer_stat_total_query_count gauge datname, job, ins, ip, instance, cls Total number of SQL queries pooled by pgbouncer
pgbouncer_stat_total_query_time counter datname, job, ins, ip, instance, cls Total number of seconds spent when executing queries
pgbouncer_stat_total_received counter datname, job, ins, ip, instance, cls Total volume in bytes of network traffic received by pgbouncer
pgbouncer_stat_total_sent counter datname, job, ins, ip, instance, cls Total volume in bytes of network traffic sent by pgbouncer
pgbouncer_stat_total_wait_time counter datname, job, ins, ip, instance, cls Time spent by clients waiting for a server, in seconds
pgbouncer_stat_total_xact_count gauge datname, job, ins, ip, instance, cls Total number of SQL transactions pooled by pgbouncer
pgbouncer_stat_total_xact_time counter datname, job, ins, ip, instance, cls Total number of seconds spent when in a transaction
pgbouncer_up gauge job, ins, ip, instance, cls last scrape was able to connect to the server: 1 for yes, 0 for no
pgbouncer_version gauge job, ins, ip, instance, cls server version number
process_cpu_seconds_total counter job, ins, ip, instance, cls Total user and system CPU time spent in seconds.
process_max_fds gauge job, ins, ip, instance, cls Maximum number of open file descriptors.
process_open_fds gauge job, ins, ip, instance, cls Number of open file descriptors.
process_resident_memory_bytes gauge job, ins, ip, instance, cls Resident memory size in bytes.
process_start_time_seconds gauge job, ins, ip, instance, cls Start time of the process since unix epoch in seconds.
process_virtual_memory_bytes gauge job, ins, ip, instance, cls Virtual memory size in bytes.
process_virtual_memory_max_bytes gauge job, ins, ip, instance, cls Maximum amount of virtual memory available in bytes.
promhttp_metric_handler_requests_in_flight gauge job, ins, ip, instance, cls Current number of scrapes being served.
promhttp_metric_handler_requests_total counter code, job, ins, ip, instance, cls Total number of scrapes by HTTP status code.
scrape_duration_seconds Unknown job, ins, ip, instance, cls N/A
scrape_samples_post_metric_relabeling Unknown job, ins, ip, instance, cls N/A
scrape_samples_scraped Unknown job, ins, ip, instance, cls N/A
scrape_series_added Unknown job, ins, ip, instance, cls N/A
up Unknown job, ins, ip, instance, cls N/A

11 - 参数列表

PGSQL 模块提供的 PostgreSQL 相关配置参数详解

PGSQL 模块需要在 Pigsty 管理的节点上安装（即节点已经配置了 NODE 模块），同时还要求您的部署中有一套可用的 ETCD 集群来存储集群元数据。

在单个节点上安装 PGSQL 模块将创建一个独立的 PGSQL 服务器/实例，即 主实例。 在额外节点上安装将创建 只读副本，可以作为备用实例，并用于承载分担只读请求。 您还可以创建用于 ETL/OLAP/交互式查询的 离线 实例， 使用 同步备库 和 法定人数提交 来提高数据一致性， 甚至搭建 备份集群 和 延迟集群 以快速应对人为失误与软件缺陷导致的数据损失。

您可以定义多个 PGSQL 集群并进一步组建一个水平分片集群： Pigsty 支持原生的 citus 集群组，可以将您的标准 PGSQL 集群原地升级为一个分布式的数据库集群。

参数组 功能说明
PG_ID PostgreSQL 集群与实例的身份标识参数
PG_BUSINESS 业务用户、数据库、服务与访问控制规则定义
PG_INSTALL PostgreSQL 安装相关：版本、路径、软件包
PG_BOOTSTRAP PostgreSQL 集群初始化引导：Patroni 高可用
PG_PROVISION PostgreSQL 集群模板置备：角色、权限、扩展
PG_BACKUP pgBackRest 备份与恢复配置
PG_ACCESS 服务暴露、连接池、VIP、DNS 等客户端访问配置
PG_MONITOR PostgreSQL 监控 Exporter 配置
PG_REMOVE PostgreSQL 实例清理与卸载配置

参数概览

PG_ID 参数组用于定义 PostgreSQL 集群与实例的身份标识，包括集群名称、实例序号、角色、分片等核心身份参数。

参数 类型 级别 说明
pg_mode enum C pgsql 集群模式：pgsql,citus,mssql,mysql,ivory,pgtde,polar,gpsql,agens,oriole,pgedge
pg_cluster string C pgsql 集群名称，必选身份参数
pg_seq int I pgsql 实例号，必选身份参数
pg_role enum I pgsql 实例角色，必选身份参数，可为 primary、replica、standby、offline、delayed
pg_instances dict I 在一个节点上定义多个 pg 实例，使用 {port:ins_vars} 格式
pg_upstream ip I 级联从库或备份集群的复制上游节点 IP 地址
pg_shard string C pgsql 分片名；水平分片集群建议显式指定
pg_group int C pgsql 分片号，可使用非负整数；水平分片集群建议显式指定
gp_role enum C 这个集群的 greenplum 角色，可以是 master 或 segment
pg_exporters dict C 在该节点上设置额外的 pg_exporters 用于监控远程 postgres 实例
pg_offline_query bool I 设置为 true 将此只读实例标记为特殊的离线从库，承载 Offline 服务，允许离线查询

PG_BUSINESS 参数组用于定义业务用户、数据库、服务与访问控制规则，以及默认的系统用户凭据。

参数 类型 级别 说明
pg_users user[] C postgres 业务用户
pg_databases database[] C postgres 业务数据库
pg_services service[] C postgres 业务服务
pg_hba_rules hba[] C postgres 的业务 hba 规则
pgb_hba_rules hba[] C pgbouncer 的业务 hba 规则
pg_crontab string[] C postgres dbsu 的定时任务
pg_replication_username username G postgres 复制用户名，默认为 replicator
pg_replication_password password G postgres 复制密码，默认为 DBUser.Replicator
pg_admin_username username G postgres 管理员用户名，默认为 dbuser_dba
pg_admin_password password G postgres 管理员明文密码，默认为 DBUser.DBA
pg_monitor_username username G postgres 监控用户名，默认为 dbuser_monitor
pg_monitor_password password G postgres 监控密码，默认为 DBUser.Monitor
pg_dbsu_password password G/C dbsu 密码，默认为空字符串意味着不设置 dbsu 密码，最好不要设置。

PG_INSTALL 参数组用于配置 PostgreSQL 安装相关选项，包括版本、路径、软件包与扩展插件。

参数 类型 级别 说明
pg_dbsu username C 操作系统 dbsu 名称，默认为 postgres，最好不要更改
pg_dbsu_uid int C 操作系统 dbsu uid 和 gid，对于默认的 postgres 用户和组为 26
pg_dbsu_sudo enum C dbsu sudo 权限，none,limit,all,nopass，默认为 limit
pg_dbsu_home path C postgresql 主目录，默认为 /var/lib/pgsql
pg_dbsu_ssh_exchange bool C 在 pgsql 集群之间交换 postgres dbsu ssh 密钥
pg_version enum C 要安装的 postgres 主版本，默认为 18
pg_bin_dir path C postgres 二进制目录，默认为 /usr/pgsql/bin
pg_log_dir path C postgres 日志目录，默认为 /pg/log/postgres
pg_packages string[] C 要安装的 pg 包，${pg_version} 将被替换为实际主版本号
pg_extensions string[] C 要安装的 pg 扩展，${pg_version} 将被替换为实际主版本号

PG_BOOTSTRAP 参数组用于配置 PostgreSQL 集群初始化引导，包括 Patroni 高可用、存储路径、连接、编码等核心设置。

参数 类型 级别 说明
pg_data path C PostgreSQL 数据目录，默认为 /pg/data
pg_fs_main path C postgres 主数据的挂载点/路径，默认为 /data/postgres
pg_fs_backup path C pg 备份数据的挂载点/路径，默认为 /data/backups
pg_storage_type enum C pg 主数据的存储类型，SSD、HDD，默认为 SSD，影响自动优化的参数。
pg_dummy_filesize size C /pg/dummy 的大小，默认保留 64MB 磁盘空间用于紧急抢修
pg_listen ip(s) C/I postgres/pgbouncer 的监听地址，用逗号分隔的 IP 列表，默认为 0.0.0.0
pg_port port C postgres 监听端口，默认为 5432
pg_localhost path C postgres 的 Unix 套接字目录，用于本地连接
pg_namespace path C 在 etcd 中的顶级键命名空间，被 patroni & vip 用于高可用管理
patroni_enabled bool C 如果禁用，初始化期间不会创建 postgres 集群
patroni_mode enum C patroni 工作模式：default,pause,remove
patroni_port port C patroni 监听端口，默认为 8008
patroni_log_dir path C patroni 日志目录，默认为 /pg/log/patroni
patroni_ssl_enabled bool G 使用 SSL 保护 patroni RestAPI 通信？
patroni_watchdog_mode enum C patroni 看门狗模式：automatic,required,off，默认为 off
patroni_username username C patroni restapi 用户名，默认为 postgres
patroni_password password C patroni restapi 密码，默认为 Patroni.API
pg_primary_db string C 指定集群中首要使用的数据库名，Citus 等模式会用到，默认为 postgres
pg_parameters dict C 覆盖 postgresql.auto.conf 中的 PostgreSQL 参数
pg_files path[] C 拷贝至 PGDATA 目录中的额外文件列表 (例如许可证文件)
pg_conf enum C 配置模板：oltp,olap,crit,tiny，默认为 oltp.yml
pg_max_conn int C postgres 最大连接数，auto 将使用推荐值
pg_shared_buffer_ratio float C postgres 共享缓冲区内存比率，默认为 0.25，范围 0.1~0.4
pg_rto enum C RTO 模式：fast,norm,safe,wide，默认 norm
pg_rto_plan dict G RTO 预设配置，定义 Patroni HA 与 HAProxy 健康检查的超时参数
pg_rpo int C Patroni 故障切换候选从库的采样落后阈值，默认为 1MiB
pg_libs string C 预加载的库，默认为 pg_stat_statements,auto_explain
pg_delay interval I 备份集群主库的 WAL 重放应用延迟，用于制备延迟从库
pg_checksum bool C 为 postgres 集群启用数据校验和？
pg_pwd_enc enum C 密码加密算法：固定为 scram-sha-256
pg_encoding enum C 数据库集群编码，默认为 UTF8
pg_locale enum C 数据库集群本地化设置，默认为 C
pg_lc_collate enum C 数据库集群排序，默认为 C
pg_lc_ctype enum C 数据库字符类型，默认为 C
pg_io_method enum C PostgreSQL IO 方法：auto, sync, worker, io_uring
pg_etcd_password password C 此 PostgreSQL 集群在 etcd 中使用的密码，默认使用集群名
pgsodium_key string C pgsodium 加密主密钥，64 位十六进制数字，默认使用 sha256(pg_cluster)
pgsodium_getkey_script path C pgsodium 获取密钥脚本路径，默认使用模板中的 pgsodium_getkey

PG_PROVISION 参数组用于配置 PostgreSQL 集群模板置备，包括默认角色、权限、模式、扩展与 HBA 规则。

参数 类型 级别 说明
pg_provision bool C 在引导后置备 postgres 集群内部的业务对象？
pg_init string G/C 为集群模板提供初始化脚本，默认为 pg-init
pg_default_roles role[] G/C postgres 集群中的默认预定义角色和系统用户
pg_default_privileges string[] G/C 由管理员用户创建数据库内对象时的默认权限
pg_default_schemas string[] G/C 要创建的默认模式列表
pg_default_extensions extension[] G/C 要创建的默认扩展列表
pg_reload bool A 更改 HBA 后，是否立即重载 postgres 配置
pg_default_hba_rules hba[] G/C postgres 基于主机的认证规则，全局 PG 默认 HBA
pgb_default_hba_rules hba[] G/C pgbouncer 默认的基于主机的认证规则，全局 PGB 默认 HBA

PG_BACKUP 参数组用于配置 pgBackRest 备份与恢复，包括仓库类型、路径、保留策略等。

参数 类型 级别 说明
pgbackrest_enabled bool C 在 pgsql 主机上启用 pgbackrest？
pgbackrest_log_dir path C pgbackrest 日志目录，默认为 /pg/log/pgbackrest
pgbackrest_method enum C pgbackrest 使用的仓库：local,minio,等…
pgbackrest_init_backup bool C pgbackrest 初始化完成后是否立即执行全量备份？默认为 true
pgbackrest_repo dict G/C pgbackrest 仓库定义

PG_ACCESS 参数组用于配置服务暴露、连接池、VIP、DNS 等客户端访问相关选项。

参数 类型 级别 说明
pgbouncer_enabled bool C 如果禁用，则不会配置 pgbouncer 连接池
pgbouncer_port port C pgbouncer 监听端口，默认为 6432
pgbouncer_log_dir path C pgbouncer 日志目录，默认为 /pg/log/pgbouncer
pgbouncer_auth_query bool C 使用 AuthQuery 来从 postgres 获取未列出的业务用户？
pgbouncer_poolmode enum C 池化模式：transaction,session,statement，默认为 transaction
pgbouncer_sslmode enum C pgbouncer 客户端 SSL 模式，默认为禁用
pgbouncer_ignore_param string[] C pgbouncer 忽略的启动参数列表
pg_weight int I 在服务中的相对负载均衡权重，默认为 100，范围 0-255
pg_service_provider string G/C 专用的 haproxy 节点组名称，或默认空字符，使用本地节点上的 haproxy
pg_default_service_dest enum G/C 如果 svc.dest=‘default’，默认服务指向哪里？postgres 或 pgbouncer
pg_default_services service[] G/C postgres 默认服务定义列表，全局共用。
pg_vip_enabled bool C 是否为 pgsql 主节点启用 L2 VIP？默认不启用
pg_vip_address cidr4 C vip 地址的格式为 <ipv4>/<mask>，启用 vip 时为必选参数
pg_vip_interface string C/I 监听的 vip 网络接口，默认为 auto
pg_dns_suffix string C pgsql dns 后缀，默认为空
pg_dns_target enum C PG DNS 解析到哪里？auto、primary、vip、none 或者特定的 IP 地址

PG_MONITOR 参数组用于配置 PostgreSQL 监控 Exporter，包括 pg_exporter、pgbouncer_exporter 和 pgbackrest_exporter。

参数 类型 级别 说明
pg_exporter_enabled bool C 在 pgsql 主机上启用 pg_exporter 吗？
pg_exporter_config string C pg_exporter 配置文件/模板名称
pg_exporter_cache_ttls string C pg_exporter 收集器阶梯 TTL 配置，默认为 ‘1,10,60,300’
pg_exporter_port port C pg_exporter 监听端口，默认为 9630
pg_exporter_params string C pg_exporter dsn 中传入的额外 URL 参数
pg_exporter_url pgurl C 如果指定，则覆盖自动生成的 postgres DSN 连接串
pg_exporter_auto_discovery bool C 监控是否启用自动数据库发现？默认启用
pg_exporter_exclude_database string C 启用自动发现时，排除在外的数据库名称列表，用逗号分隔
pg_exporter_include_database string C 启用自动发现时，只监控这个列表中的数据库，名称用逗号分隔
pg_exporter_connect_timeout int C pg_exporter 连接超时，单位毫秒，默认为 200
pg_exporter_options arg C pg_exporter 的额外命令行参数选项
pgbouncer_exporter_enabled bool C 在 pgsql 主机上启用 pgbouncer_exporter 吗？
pgbouncer_exporter_port port C pgbouncer_exporter 监听端口，默认为 9631
pgbouncer_exporter_url pgurl C 如果指定，则覆盖自动生成的 pgbouncer dsn 连接串
pgbouncer_exporter_options arg C pgbouncer_exporter 的额外命令行参数选项
pgbackrest_exporter_enabled bool C 在 pgsql 主机上启用 pgbackrest_exporter 吗？
pgbackrest_exporter_port port C pgbackrest_exporter 监听端口，默认为 9854
pgbackrest_exporter_options arg C pgbackrest_exporter 的额外命令行参数选项

PG_REMOVE 参数组用于配置 PostgreSQL 实例清理与卸载行为，包括数据目录、备份、软件包的删除控制。

参数 类型 级别 说明
pg_rm_data bool G/C/A 删除 pgsql 实例时是否清理 postgres 数据目录？
pg_rm_backup bool G/C/A 删除主库时是否一并清理 pgbackrest 备份？
pg_rm_pkg bool G/C/A 删除 pgsql 实例时是否卸载相关软件包？
pg_safeguard bool G/C/A 防误删保险，阻止误执行 pgsql 清理操作？默认为 false

PG_ID

以下是一些常用的参数，用于标识 PGSQL 模块中的 实体：集群、实例、服务等…

# pg_cluster:           #CLUSTER  # pgsql 集群名称，必需的标识参数
# pg_seq: 0             #INSTANCE # pgsql 实例序列号，必需的标识参数
# pg_role: replica      #INSTANCE # pgsql 角色，必需的，可以是 primary,replica,offline
# pg_instances: {}      #INSTANCE # 在节点上定义多个 pg 实例，使用 `{port:ins_vars}` 格式
# pg_upstream:          #INSTANCE # 备用集群或级联副本的 repl 上游 ip 地址
# pg_shard:             #CLUSTER  # pgsql 分片名称，分片集群的可选标识
# pg_group: 0           #CLUSTER  # pgsql 分片索引号，分片集群的可选标识
# gp_role: master       #CLUSTER  # 此集群的 greenplum 角色，可以是 master 或 segment
pg_offline_query: false #INSTANCE # 设置为 true 以在此实例上启用离线查询

您必须显式指定这些 身份参数，它们没有默认值：

名称 类型 级别 扩展说明
pg_cluster string C PG 数据库集群名称
pg_seq number I PG 数据库实例 ID
pg_role enum I PG 数据库实例角色
pg_shard string C 数据库分片名称
pg_group number C 数据库分片序号
  • pg_cluster：它标识集群的名称，该名称在集群级别配置。
  • pg_role：在实例级别配置，标识 ins 的角色。只有 primary 角色会特别处理。如果不填写，默认为 replica 角色和特殊的 delayed 和 offline 角色。
  • pg_seq：用于在集群内标识 ins，通常是从 0 或 1 递增的整数，一旦分配就不会更改。
  • {{ pg_cluster }}-{{ pg_seq }} 用于唯一标识 ins，即 pg_instance。
  • {{ pg_cluster }}-{{ pg_role }} 用于标识集群内的服务，即 pg_service。
  • pg_shard 和 pg_group 用于水平分片集群，仅用于 citus、greenplum 和 matrixdb。

pg_cluster、pg_role、pg_seq 是核心 标识参数，对于任何 Postgres 集群都是 必选 的，并且必须显式指定。以下是一个示例：

pg-test:
  hosts:
    10.10.10.11: {pg_seq: 1, pg_role: replica}
    10.10.10.12: {pg_seq: 2, pg_role: primary}
    10.10.10.13: {pg_seq: 3, pg_role: replica}
  vars:
    pg_cluster: pg-test

所有其他参数都可以从全局配置或默认配置继承，但标识参数必须 明确指定 和 手动分配。

pg_mode

参数名称： pg_mode， 类型： enum， 层次：C

PostgreSQL 集群模式，默认值为 pgsql，即标准的 PostgreSQL 集群。

可用的模式选项包括：

  • pgsql：标准的 PostgreSQL 集群
  • citus：Citus 分布式数据库集群
  • mssql：Babelfish MSSQL 线缆协议兼容内核
  • mysql：OpenHalo/HaloDB MySQL 线协议兼容内核
  • ivory：IvorySQL Oracle 兼容内核
  • pgtde：带 pg_tde 的 Percona PostgreSQL 内核
  • polar：PolarDB for PostgreSQL 内核
  • gpsql：Greenplum 并行数据库集群（监控）
  • agens：AgensGraph 图数据库内核
  • oriole：OrioleDB 存储引擎内核
  • pgedge：pgEdge 分布式复制内核

pg_shard 与 pg_group 分别有 pg_cluster 和 0 作为默认值；当 pg_mode 设置为 citus 或 gpsql 并包含多个物理集群时，应显式设置这两个参数来定义水平分片集群的身份。

在这两种情况下，每一个 PostgreSQL 集群都是一组更大的业务单元的一部分。

pg_cluster

参数名称： pg_cluster， 类型： string， 层次：C

PostgreSQL 集群名称，必选的身份标识参数，没有默认值

集群名将用作资源的命名空间。

当前角色校验要求集群名匹配 ^[A-Za-z0-9-]+$，且不能命名为 root。为保持 DNS、服务名与运维脚本中的命名一致，仍建议采用小写字母开头、仅含小写字母、数字与连字符的名称。

pg_seq

参数名称： pg_seq， 类型： int， 层次：I

PostgreSQL 实例序列号，必选的身份标识参数，无默认值。

此实例的序号，在其 集群 内是唯一分配的，通常使用自然数，从0或1开始分配，通常不会回收重用。

pg_role

参数名称： pg_role， 类型： enum， 层次：I

PostgreSQL 实例角色，必选的身份标识参数，无默认值。当前校验接受：primary、replica、standby、offline、delayed。

常用的服务成员标签如下：

  • primary：主实例，在集群中有且仅有一个。
  • replica：用于承载在线只读流量的副本，高负载下可能会有轻微复制延迟（10ms~100ms, 100KB）。
  • offline：用于处理离线只读流量的离线副本，如统计分析/ETL/个人查询等。

standby 与 delayed 也是合法的清单角色值，但当前角色逻辑不会仅凭这两个字符串自动创建备份集群或延迟复制；相应拓扑仍需通过 pg_upstream 与 pg_delay 配置。按角色筛选的 HBA 规则会直接使用这些清单标签。

pg_instances

参数名称： pg_instances， 类型： dict， 层次：I

使用 {port:ins_vars} 的形式在一台主机上定义多个 PostgreSQL 实例。

此参数是为在单个节点上的多实例部署保留的参数，Pigsty 尚未实现此功能，并强烈建议独占节点部署。

pg_upstream

参数名称： pg_upstream， 类型： ip， 层次：I

备份集群 或级联从库的上游实例 IP 地址。

在集群的 primary 实例上设置 pg_upstream，表示此集群是一个 备份集群，该实例将作为 standby leader，从上游集群接收并应用更改。

对非 primary 实例设置 pg_upstream 参数将指定一个具体实例作为物理复制的上游，如果与主实例 ip 地址不同，此实例将成为 级联副本。确保上游 IP 地址是同一集群中的另一个实例是用户的责任。

pg_shard

参数名称： pg_shard， 类型： string， 层次：C

PostgreSQL 水平分片名称，默认值为 pg_cluster。对于包含多个物理集群的水平分片集群（例如 Citus 集群），建议显式指定。

当多个标准的 PostgreSQL 集群一起以水平分片方式为同一业务提供服务时，Pigsty 将此组集群标记为 水平分片集群。

pg_shard 是分片组名称。它通常是 pg_cluster 的前缀。

例如，如果我们有一个分片组 pg-citus，并且其中有4个集群，它们的标识参数将是：

cls pg_shard: pg-citus
cls pg_group = 0:   pg-citus0
cls pg_group = 1:   pg-citus1
cls pg_group = 2:   pg-citus2
cls pg_group = 3:   pg-citus3

pg_group

参数名称： pg_group， 类型： int， 层次：C

PostgreSQL 水平分片集群的分片索引号，默认值为 0。对于包含多个物理集群的水平分片集群（例如 Citus 集群），建议显式指定。

此参数与 pg_shard 配对使用，通常可以使用非负整数作为索引号。

gp_role

参数名称： gp_role， 类型： enum， 层次：C

PostgreSQL 集群的 Greenplum/Matrixdb 角色，可以是 master 或 segment。

  • master：标记 postgres 集群为 greenplum 主实例（协调节点），这是默认值。
  • segment 标记 postgres 集群为 greenplum 段集群（数据节点）。

此参数仅用于 Greenplum/MatrixDB 数据库 （pg_mode 为 gpsql），对于普通的 PostgreSQL 集群没有意义。

pg_exporters

参数名称： pg_exporters， 类型： dict， 层次：C

额外用于 监控 远程 PostgreSQL 实例的 Exporter 定义，默认值：{}

如果您希望监控远程 PostgreSQL 实例，请在监控系统所在节点（Infra 节点）集群上的 pg_exporters 参数中定义它们，并使用 pgsql-monitor.yml 剧本来完成部署。

pg_exporters: # list all remote instances here, alloc a unique unused local port as k
    20001: { pg_cluster: pg-foo, pg_seq: 1, pg_host: 10.10.10.10 }
    20004: { pg_cluster: pg-foo, pg_seq: 2, pg_host: 10.10.10.11 }
    20002: { pg_cluster: pg-bar, pg_seq: 1, pg_host: 10.10.10.12 }
    20003: { pg_cluster: pg-bar, pg_seq: 1, pg_host: 10.10.10.13 }

pg_offline_query

参数名称： pg_offline_query， 类型： bool， 层次：I

设置为 true，将此实例标记为可承载离线查询，默认为 false。

该标记会使实例进入默认 offline 服务的候选集合，并使 role: offline 的 HBA 规则在该实例上生效。它本身不会授予连接权限；用户能否连接仍取决于生成的 HBA 规则、数据库 CONNECT 权限和角色属性。

带有此标记的实例在效果上类似于为实例设置 pg_role = offline，唯一的区别在于 offline 实例默认不会承载 replica 服务的请求，是作为专用的离线/分析从库实例而存在的。

没有专用离线实例时，可以在普通从库的实例层配置中启用该参数。若要将 dbrole_offline 限制到这些实例，还需为对应 HBA 规则显式设置 role: offline。

PG_BUSINESS

定制集群模板：用户，数据库，服务，权限规则。

用户需 重点关注 此部分参数，因为这里是业务声明自己所需数据库对象的地方。

默认 的数据库用户及其凭据，生产环境必须修改这些用户的密码。

# postgres business object definition, overwrite in group vars
pg_users: []                      # postgres business users
pg_databases: []                  # postgres business databases
pg_services: []                   # postgres business services
pg_hba_rules: []                  # business hba rules for postgres
pgb_hba_rules: []                 # business hba rules for pgbouncer
pg_crontab: []                    # crontab entries for postgres dbsu
# global credentials, overwrite in global vars
pg_dbsu_password: ''              # dbsu password, empty string means no dbsu password by default
pg_replication_username: replicator
pg_replication_password: DBUser.Replicator
pg_admin_username: dbuser_dba
pg_admin_password: DBUser.DBA
pg_monitor_username: dbuser_monitor
pg_monitor_password: DBUser.Monitor

pg_users

参数名称： pg_users， 类型： user[]， 层次：C

PostgreSQL 业务用户列表，需要在 PG 集群层面进行定义。默认值为：[] 空列表。

每一个数组元素都是一个 用户/角色 定义，例如：

- name: dbuser_meta               # 必选，`name` 是用户定义的唯一必选字段
  state: create                   # 可选，用户状态：create（创建，默认）、absent（删除）
  password: DBUser.Meta           # 可选，密码，可以是 scram-sha-256 哈希字符串或明文
  login: true                     # 可选，默认为 true，是否可以登录
  superuser: false                # 可选，默认为 false，是否是超级用户
  createdb: false                 # 可选，默认为 false，是否可以创建数据库
  createrole: false               # 可选，默认为 false，是否可以创建角色
  inherit: true                   # 可选，默认为 true，是否自动继承所属角色权限
  replication: false              # 可选，默认为 false，是否可以发起流复制连接
  bypassrls: false                # 可选，默认为 false，是否可以绕过行级安全
  connlimit: -1                   # 可选，用户连接数限制，默认 -1 不限制
  expire_in: 3650                 # 可选，从创建时起 N 天后过期（优先级比 expire_at 高）
  expire_at: '2030-12-31'         # 可选，过期日期，使用 YYYY-MM-DD 格式（优先级没 expire_in 高）
  comment: pigsty admin user      # 可选，用户备注信息
  roles: [dbrole_admin]           # 可选，所属角色数组
  parameters:                     # 可选，角色级配置参数
    search_path: public
  pgbouncer: true                 # 可选，是否加入连接池用户列表，默认 false
  pool_mode: transaction          # 可选，用户级别的池化模式，默认 transaction
  pool_connlimit: 100             # 可选，用户级连接池最大连接数；省略时继承 Pigsty 全局默认 100

用户级连接池限额字段统一使用 pool_connlimit（对应 Pgbouncer max_user_connections）。

pg_databases

参数名称： pg_databases， 类型： database[]， 层次：C

PostgreSQL 业务数据库列表，需要在 PG 集群层面进行定义。默认值为：[] 空列表。

每一个数组元素都是一个 业务数据库 定义，例如：

- name: meta                      # 必选，`name` 是数据库定义的唯一必选字段
  state: create                   # 可选，数据库状态：create（创建，默认）、absent（删除）、recreate（重建）
  baseline: cmdb.sql              # 可选，数据库 sql 的基线定义文件路径（ansible 搜索路径中的相对路径，如 files/）
  pgbouncer: true                 # 可选，是否将此数据库添加到 pgbouncer 数据库列表？默认为 true
  schemas: [pigsty]               # 可选，要创建的附加模式，由模式名称字符串组成的数组
  extensions:                     # 可选，要安装的附加扩展：扩展对象的数组
    - { name: postgis , schema: public }  # 可以指定将扩展安装到某个模式中，也可以不指定（不指定则安装到 search_path 首位模式中）
    - { name: timescaledb }               # 例如有的扩展会创建并使用固定的模式，就不需要指定模式。
  comment: pigsty meta database   # 可选，数据库的说明与备注信息
  owner: postgres                 # 可选，数据库所有者，不指定则为当前用户
  template: template1             # 可选，要使用的模板，默认为 template1，目标必须是一个模板数据库
  strategy: FILE_COPY             # 可选，克隆策略：FILE_COPY 或 WAL_LOG（PG15+），不指定使用 PG 默认
  encoding: UTF8                  # 可选，不指定则继承模板/集群配置（UTF8）
  locale: C                       # 可选，不指定则继承模板/集群配置（C）
  lc_collate: C                   # 可选，不指定则继承模板/集群配置（C）
  lc_ctype: C                     # 可选，不指定则继承模板/集群配置（C）
  locale_provider: libc           # 可选，本地化提供者：libc、icu、builtin（PG15+）
  icu_locale: en-US               # 可选，ICU 本地化规则（PG15+）
  icu_rules: ''                   # 可选，ICU 排序规则（PG16+）
  builtin_locale: C.UTF-8         # 可选，内置本地化提供者规则（PG17+）
  tablespace: pg_default          # 可选，默认表空间，默认为 'pg_default'
  is_template: false              # 可选，是否标记为模板数据库，允许任何有 CREATEDB 权限的用户克隆
  allowconn: true                 # 可选，是否允许连接，默认为 true。显式设置 false 将完全禁止连接到此数据库
  revokeconn: false               # 可选，撤销公共连接权限。默认为 false，设置为 true 时，属主和管理员之外用户的 CONNECT 权限会被回收
  register_datasource: true       # 可选，是否将此数据库注册到 grafana 数据源？默认为 true，显式设置为 false 会跳过注册
  connlimit: -1                   # 可选，数据库连接限制，默认为 -1 ，不限制，设置为正整数则会限制连接数
  parameters:                     # 可选，数据库级参数，通过 ALTER DATABASE SET 设置
    work_mem: '64MB'
    statement_timeout: '30s'
  pool_auth_user: dbuser_meta     # 可选，连接到此 pgbouncer 数据库的所有连接都将使用此用户进行验证（启用 pgbouncer_auth_query 才有用）
  pool_mode: transaction          # 可选，数据库级别的 pgbouncer 池化模式，默认为 transaction
  pool_size: 50                   # 可选，数据库级别的 pgbouncer 默认池子大小，默认为 50
  pool_reserve: 30                # 可选，数据库级别的 pgbouncer 池子保留空间，默认为 30，当默认池子不够用时，最多再申请这么多条突发连接
  pool_size_min: 0                # 可选，数据库级别的 pgbouncer 池的最小大小，默认为 0
  pool_connlimit: 100             # 可选，数据库级别的最大数据库连接数，默认为 100

自 Pigsty v4.1.0 起，数据库连接池参数统一使用 pool_reserve 与 pool_connlimit，旧别名 pool_size_reserve / pool_max_db_conn 已收敛。

在每个数据库定义对象中，只有 name 是必选字段，其他的字段都是可选项。

pg_services

参数名称： pg_services， 类型： service[]， 层次：C

PostgreSQL 服务列表，需要在 PG 集群层面进行定义。默认值为：[]，空列表。

用于在数据库集群层面定义额外的服务，数组中的每一个对象定义了一个 服务，一个完整的服务定义样例如下：

- name: standby                   # 必选，服务名称，最终的 svc 名称会使用 `pg_cluster` 作为前缀，例如：pg-meta-standby
  port: 5435                      # 必选，暴露的服务端口（作为 kubernetes 服务节点端口模式）
  ip: "*"                         # 可选，服务绑定的 IP 地址，默认情况下为所有 IP 地址
  selector: "[]"                  # 必选，服务成员选择器，使用 JMESPath 来筛选配置清单
  backup: "[? pg_role == `primary`]"  # 可选，服务成员选择器（备份），也就是当默认选择器选中的实例都宕机后，服务才会由这里选中的实例成员来承载
  dest: default                   # 可选，目标端口，default|postgres|pgbouncer|<port_number>，默认为 'default'，Default的意思就是使用 pg_default_service_dest 的取值来最终决定
  check: /sync                    # 可选，健康检查 URL 路径，默认为 /，这里使用 Patroni API：/sync ，只有同步备库和主库才会返回 200 健康状态码
  maxconn: 5000                   # 可选，允许的前端连接最大数，默认为5000
  balance: roundrobin             # 可选，haproxy 负载均衡算法（默认为 roundrobin，其他选项：leastconn）
  #options: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'
  # 注意：健康检查相关参数（inter, fastinter, downinter, rise, fall）现在由 pg_rto_plan 统一控制
  # 默认 norm 模式参数：inter 2s fastinter 1s downinter 2s rise 3 fall 3

请注意，本参数用于在集群层面添加额外的服务。如果您想在全局定义所有 PostgreSQL 数据库都要提供的服务，可以使用 pg_default_services 参数。

pg_hba_rules

参数名称： pg_hba_rules， 类型： hba[]， 层次：C

数据库集群/实例的客户端 IP 黑白名单规则。默认为：[] 空列表。

对象数组，每一个对象都代表一条规则， hba 规则对象的定义形式如下：

- title: allow intranet password access
  role: common
  rules:
    - host   all  all  10.0.0.0/8      md5
    - host   all  all  172.16.0.0/12   md5
    - host   all  all  192.168.0.0/16  md5
  • title： 规则的标题名称，会被渲染为 HBA 文件中的注释。
  • rules：规则数组，每个元素是一条标准的 HBA 规则字符串。
  • role：规则的应用范围，哪些实例角色会启用这条规则？
    • common：对于所有实例生效
    • primary, replica,offline： 只针对特定的角色 pg_role 实例生效。
    • 特例：role: 'offline' 的规则除了会应用在 pg_role : offline 的实例上，对于带有 pg_offline_query 标记的实例也生效。

除了上面这种原生 HBA 规则定义形式，Pigsty 还提供了另外一种更为简便的别名形式：

- addr: 'intra'    # world|intra|infra|admin|local|localhost|cluster|<cidr>
  auth: 'pwd'      # trust|pwd|ssl|cert|deny|<official auth method>
  user: 'all'      # all|${dbsu}|${repl}|${admin}|${monitor}|<user>|<group>
  db: 'all'        # all|replication|....
  rules: []        # raw hba string precedence over above all
  title: allow intranet password access

pg_default_hba_rules 与本参数基本类似，但它是用于定义全局的 HBA 规则，而本参数通常用于定制某个集群/实例的 HBA 规则。

pgb_hba_rules

参数名称： pgb_hba_rules， 类型： hba[]， 层次：C

Pgbouncer 业务 HBA 规则，默认值为： []， 空数组。

此参数与 pg_hba_rules 基本类似，都是 hba 规则对象的数组，区别在于本参数是为 Pgbouncer 准备的。

pgb_default_hba_rules 与本参数基本类似，但它是用于定义全局连接池 HBA 规则，而本参数通常用于定制某个连接池集群/实例的 HBA 规则。

pg_crontab

参数名称： pg_crontab， 类型： string[]， 层次：C

PostgreSQL 数据库超级用户（dbsu，默认 postgres）的定时任务列表，默认值为：[] 空数组。

每个数组元素是一行 crontab 条目，使用标准的用户 crontab 格式：分 时 日 月 周 命令（无需指定用户名）。

pg_crontab:
  - '00 01 * * * /pg/bin/pg-backup full'      # 每天凌晨 1 点全量备份
  - '00 13 * * * /pg/bin/pg-backup'           # 每天下午 1 点增量备份

此参数会将定时任务写入 postgres 用户的个人 crontab 文件：

  • EL 系统：/var/spool/cron/postgres
  • Debian 系统：/var/spool/cron/crontabs/postgres

注意：此参数用于取代在 node_crontab 中配置 postgres 用户任务的旧做法。 因为 node_crontab 在 NODE 初始化阶段写入 /etc/crontab，此时 postgres 用户可能尚未创建，会导致 cron 报错。

移除集群时，此 crontab 文件会被一并删除。

pg_replication_username

参数名称： pg_replication_username， 类型： username， 层次：G

PostgreSQL 物理复制用户名，默认使用 replicator，不建议修改此参数。

pg_replication_password

参数名称： pg_replication_password， 类型： password， 层次：G

PostgreSQL 物理复制用户密码，默认值为：DBUser.Replicator。

警告

请在生产环境中修改此密码！

pg_admin_username

参数名称： pg_admin_username， 类型： username， 层次：G

PostgreSQL / Pgbouncer 管理员名称，默认为：dbuser_dba。

这是全局使用的数据库管理员，具有数据库的 Superuser 权限与连接池的流量管理权限，请务必控制使用范围。

pg_admin_password

参数名称： pg_admin_password， 类型： password， 层次：G

PostgreSQL / Pgbouncer 管理员密码，默认为： DBUser.DBA。

警告

请在生产环境中修改此密码！

pg_monitor_username

参数名称： pg_monitor_username， 类型： username， 层次：G

PostgreSQL/Pgbouncer 监控用户名，默认为：dbuser_monitor。

这是一个用于监控的数据库/连接池用户，不建议修改此用户名。

但如果您的现有数据库使用了不同的监控用户，可以在指定监控目标时使用此参数传入使用的监控用户名。

pg_monitor_password

参数名称： pg_monitor_password， 类型： password， 层次：G

PostgreSQL/Pgbouncer 监控用户使用的密码，默认为：DBUser.Monitor。

请尽可能不要在密码中使用 @:/ 这些容易与 URL 分隔符混淆的字符，减少不必要的麻烦。

警告

请在生产环境中修改此密码！

pg_dbsu_password

参数名称： pg_dbsu_password， 类型： password， 层次：G/C

PostgreSQL pg_dbsu 超级用户密码，默认是空字符串，即不为其设置密码。

我们不建议为 dbsu 配置密码登陆，这会增大攻击面。例外情况是：pg_mode = citus，这时候需要为每个分片集群的 dbsu 配置密码，以便在分片集群内部进行连接。

PG_INSTALL

本节负责安装 PostgreSQL 及其扩展。如果您希望安装不同大版本与扩展插件，修改 pg_version 与 pg_extensions 即可，不过请注意，并不是所有扩展都在所有大版本可用。

pg_dbsu: postgres                 # os 数据库超级用户名称，默认为 postgres，最好不要更改
pg_dbsu_uid: 26                   # os 数据库超级用户 uid 和 gid，默认为 26，适用于默认的 postgres 用户和组
pg_dbsu_sudo: limit               # 数据库超级用户 sudo 权限，可选 none,limit,all,nopass。默认为 limit
pg_dbsu_home: /var/lib/pgsql      # postgresql 主目录，默认为 `/var/lib/pgsql`
pg_dbsu_ssh_exchange: true        # 是否在相同的 pgsql 集群中交换 postgres 数据库超级用户的 ssh 密钥
pg_version: 18                    # 要安装的 postgres 主版本，默认为 18
pg_bin_dir: /usr/pgsql/bin        # postgres 二进制目录，默认为 `/usr/pgsql/bin`
pg_log_dir: /pg/log/postgres      # postgres 日志目录，默认为 `/pg/log/postgres`
pg_packages:                      # pg packages to be installed, alias can be used
  - pgsql-main pgsql-common
pg_extensions: []                 # pg extensions to be installed, alias can be used

pg_dbsu

参数名称： pg_dbsu， 类型： username， 层次：C

PostgreSQL 使用的操作系统 dbsu 用户名， 默认为 postgres，改这个用户名是不太明智的。

不过在特定情况下，您可能会使用到不同于 postgres 的用户名，例如在安装配置 Greenplum / MatrixDB 时，需要使用 gpadmin / mxadmin 作为相应的操作系统超级用户。

pg_dbsu_uid

参数名称： pg_dbsu_uid， 类型： int， 层次：C

操作系统数据库超级用户的 uid 和 gid，26 是 PGDG RPM 默认的 postgres 用户 UID/GID。

对于 Debian/Ubuntu 系统，没有默认值，且 26 号用户经常被占用。因此 Pigsty 在检测到安装环境为 Debian 系，且 uid 为 26 时，会自动使用替换的 pg_dbsu_uid = 543。

pg_dbsu_sudo

参数名称： pg_dbsu_sudo， 类型： enum， 层次：C

数据库超级用户的 sudo 权限，可以是 none、limit、all 或 nopass。默认为 limit

  • none：无 Sudo 权限

  • limit：有限的 sudo 权限，用于执行与数据库相关的组件的 systemctl 命令（默认选项）。

  • all：完全的 sudo 权限，需要密码。

  • nopass：不需要密码的完全 sudo 权限（不推荐）。

  • 默认值为 limit，只允许执行 sudo systemctl <start|stop|reload> <postgres|patroni|pgbouncer|...>。

pg_dbsu_home

参数名称： pg_dbsu_home， 类型： path， 层次：C

postgresql 主目录，默认为 /var/lib/pgsql，与官方的 pgdg RPM 保持一致。

pg_dbsu_ssh_exchange

参数名称： pg_dbsu_ssh_exchange， 类型： bool， 层次：C

是否在同一 PostgreSQL 集群中交换操作系统 dbsu 的 ssh 密钥？

默认值为 true，意味着同一集群中的数据库超级用户可以互相 ssh 访问。

交换范围由当前清单中实际匹配同一 pg_cluster 的 pg_cluster_members 决定，不依赖存在一个与集群同名的 Ansible Group。执行时的 -l 仍会限制本次剧本目标，请确保限域覆盖需要配置的成员。

pg_version

参数名称： pg_version， 类型： enum， 层次：C

要安装的 postgres 主版本，默认为 18。

请注意，PostgreSQL 的物理流复制不能跨主要版本，因此最好不要在实例级别上配置此项。

您可以使用 pg_packages 和 pg_extensions 中的参数来为特定的 PG 大版本安装不同的软件包与扩展。

pg_bin_dir

参数名称： pg_bin_dir， 类型： path， 层次：C

PostgreSQL 二进制程序目录，默认为 /usr/pgsql/bin。

默认值是在安装过程中手动创建的软链接，指向安装的特定的 Postgres 版本目录。

例如 /usr/pgsql -> /usr/pgsql-15。在 Ubuntu/Debian 上则指向 /usr/lib/postgresql/15/bin。

更多详细信息，请查看 PGSQL 文件结构。

pg_log_dir

参数名称： pg_log_dir， 类型： path， 层次：C

PostgreSQL 日志目录，默认为：/pg/log/postgres，Vector 日志代理会使用此变量收集 PostgreSQL 日志。

请注意，如果日志目录 pg_log_dir 以数据库目录 pg_data 作为前缀，则不会显式创建（数据库目录初始化时自动创建）。

pg_packages

参数名称： pg_packages， 类型： string[]， 层次：C

要安装的 PostgreSQL 软件包（RPM/DEB），这是一个包名数组，元素可以是空格或逗号分隔的包别名。

Pigsty v4 将默认值收敛为两个别名：

pg_packages:
  - pgsql-main pgsql-common
  • pgsql-main：映射到当前平台上的 PostgreSQL 内核、客户端、PL 语言以及 pg_repack、wal2json、pgvector 等核心扩展。
  • pgsql-common：映射到运行数据库必需的配套组件，例如 Patroni、Pgbouncer、pgBackRest、pg_exporter、vip-manager 等守护进程。

别名的具体定义可以在 roles/node_id/vars/ 中的 pg_package_map 查到，Pigsty 会先根据操作系统和架构解析别名，再将 $v/${pg_version} 替换为实际主版本 pg_version，最后安装真实的软件包。这样可以屏蔽不同发行版之间的包名差异。

如果需要额外的软件包（例如特定 FDW 或扩展），可以直接在 pg_packages 中追加别名或真实包名。但请记得保留 pgsql-main pgsql-common，否则会缺失核心组件。

pg_extensions

参数名称： pg_extensions， 类型： string[]， 层次：G/C

要安装的 PostgreSQL 扩展包（RPM/DEB），这是一个由扩展包名或别名组成的数组。

从 v4 开始默认值为空列表 []，Pigsty 不再强制安装大体量扩展，用户可以按需选择，避免占用额外的磁盘与依赖。

如果需要安装扩展，请像下面这样填充：

pg_extensions:
  - postgis timescaledb pgvector
  - pgsql-fdw     # 使用别名一次性安装常用 FDW

pg_package_map 中提供了大量别名，方便在不同发行版之间屏蔽包名差异。下面给出当前 v4.5 EL9 映射中的单扩展别名与分类包组示例；其他平台及 PostgreSQL 大版本的实际可用范围可能不同：

pg_extensions: # extensions to be installed on this cluster
  - timescaledb postgis pgvector pg_search pg_duckdb pg_repack wal2json
  # 也可以按分类安装当前平台映射中的整组软件包；通常只选择确实需要的组
  # - pgsql-time pgsql-gis pgsql-rag pgsql-fts pgsql-olap
  # - pgsql-feat pgsql-lang pgsql-type pgsql-util pgsql-func
  # - pgsql-admin pgsql-stat pgsql-sec pgsql-fdw pgsql-sim pgsql-etl

完整映射请以目标平台的 roles/node_id/vars/<os>.<arch>.yml 与当前 扩展目录 为准。pg_analytics 与 spat 已从 v4.5 目录及当前主流平台映射中移除；不要沿用旧版示例安装它们。

PG_BOOTSTRAP

使用 Patroni 引导拉起 PostgreSQL 集群，并设置 1:1 对应的 Pgbouncer 连接池。

它还会使用 PG_PROVISION 中定义的默认角色、用户、权限、模式、扩展来初始化数据库集群

以下为 PGSQL 引导阶段的可配置参数。内部变量 pg_data 固定表示 /pg/data 软链，不应在配置清单中覆盖；需要调整实际主数据目录位置时，请配置 pg_fs_main。

pg_fs_main: /data/postgres        # postgres main data directory, `/data/postgres` by default
pg_fs_backup: /data/backups       # postgres backup data directory, `/data/backups` by default
pg_storage_type: SSD              # storage type for pg main data, SSD,HDD, SSD by default
pg_dummy_filesize: 64MiB          # size of `/pg/dummy`, hold 64MB disk space for emergency use
pg_listen: '0.0.0.0'              # postgres/pgbouncer listen addresses, comma separated list
pg_port: 5432                     # postgres listen port, 5432 by default
pg_localhost: /var/run/postgresql # postgres unix socket dir for localhost connection
patroni_enabled: true             # if disabled, no postgres cluster will be created during init
patroni_mode: default             # patroni working mode: default,pause,remove
pg_namespace: /pg                 # top level key namespace in etcd, used by patroni & vip
patroni_port: 8008                # patroni listen port, 8008 by default
patroni_log_dir: /pg/log/patroni  # patroni log dir, `/pg/log/patroni` by default
patroni_ssl_enabled: false        # secure patroni RestAPI communications with SSL?
patroni_watchdog_mode: off        # patroni watchdog mode: automatic,required,off. off by default
patroni_username: postgres        # patroni restapi username, `postgres` by default
patroni_password: Patroni.API     # patroni restapi password, `Patroni.API` by default
pg_etcd_password: ''              # etcd password for this pg cluster, '' to use pg_cluster
pg_primary_db: postgres           # primary database name, used by citus,etc... ,postgres by default
pg_parameters: {}                 # extra parameters in postgresql.auto.conf
pg_files: []                      # extra files to be copied to postgres data directory (e.g. license)
pg_conf: oltp.yml                 # config template: oltp,olap,crit,tiny. `oltp.yml` by default
pg_max_conn: auto                 # postgres max connections, `auto` will use recommended value
pg_shared_buffer_ratio: 0.25      # postgres shared buffers ratio, 0.25 by default, 0.1~0.4
pg_io_method: worker              # io method for postgres, auto,sync,worker,io_uring, worker by default
pg_rto: norm                      # shared rto mode: fast,norm,safe,wide
pg_rpo: 1048576                   # recovery point objective in bytes, `1MiB` at most by default
pg_libs: 'pg_stat_statements, auto_explain'  # preloaded libraries, `pg_stat_statements,auto_explain` by default
pg_delay: 0                       # replication apply delay for standby cluster leader
pg_checksum: true                 # enable data checksum for postgres cluster?
pg_pwd_enc: scram-sha-256         # passwords encryption algorithm: fixed to scram-sha-256
pg_encoding: UTF8                 # database cluster encoding, `UTF8` by default
pg_locale: C                      # database cluster local, `C` by default
pg_lc_collate: C                  # database cluster collate, `C` by default
pg_lc_ctype: C                    # database character type, `C` by default
#pgsodium_key: ""                 # pgsodium key, 64 hex digit, default to sha256(pg_cluster)
#pgsodium_getkey_script: ""       # pgsodium getkey script path, pgsodium_getkey by default

pg_data

内部变量名称： pg_data， 类型： path

pg_data 是 Pigsty 内部变量，不是用户配置参数。它固定表示 Postgres 数据目录软链 /pg/data。

该软链指向底层实际数据目录，在 Patroni 模板、维护脚本与清理流程中被多处引用，请不要在 pigsty.yml 中覆盖或修改它。需要调整实际主数据目录位置时，请配置 pg_fs_main。参阅 PGSQL文件结构 获取详细信息。

pg_fs_main

参数名称： pg_fs_main， 类型： path， 层次：C

PostgreSQL 主数据盘的挂载点/文件系统路径，默认为 /data/postgres。

默认值：/data/postgres，它将直接用作 PostgreSQL 主数据目录的父目录。

建议使用 NVME SSD 作为 PostgreSQL 主数据存储，Pigsty 默认为 SSD 存储进行了优化，但是也支持 HDD。

您可以更改 pg_storage_type 为 HDD 以针对 HDD 存储进行优化。

pg_fs_backup

参数名称： pg_fs_backup， 类型： path， 层次：C

PostgreSQL 备份数据盘的挂载点/文件系统路径，默认为 /data/backups。

如果您使用的是默认的 pgbackrest_method = local，建议为备份存储使用一个单独的磁盘。

备份磁盘应足够大，以容纳所有的备份，至少足以容纳3个基础备份+2天的 WAL 归档。 通常容量不是什么大问题，因为您可以使用便宜且大的机械硬盘作为备份盘。

建议为备份存储使用一个单独的磁盘，否则 Pigsty 将回退到主数据磁盘，并占用主数据盘的容量与 IO。

pg_storage_type

参数名称： pg_storage_type， 类型： enum， 层次：C

PostgreSQL 数据存储介质的类型：SSD 或 HDD，默认为 SSD。

默认值：SSD，它会影响一些调优参数，如 random_page_cost 和 effective_io_concurrency。

pg_dummy_filesize

参数名称： pg_dummy_filesize， 类型： size， 层次：C

/pg/dummy 的大小，默认值为 64MiB，用于紧急使用的64MB 磁盘空间。

当磁盘已满时，删除占位符文件可以为紧急使用释放一些空间，建议生产使用至少 8GiB。

pg_listen

参数名称： pg_listen， 类型： ip， 层次：C

PostgreSQL / Pgbouncer 的监听地址，默认为 0.0.0.0（所有 ipv4 地址）。

您可以在此变量中使用占位符，例如：'${ip},${lo}' 或 '${ip},${vip},${lo}'：

  • ${ip}：转换为 inventory_hostname，它是配置清单中定义的首要内网 IP 地址。
  • ${vip}：如果启用了 pg_vip_enabled，将使用 pg_vip_address 的主机部分。
  • ${lo}：将替换为 127.0.0.1

对于高安全性要求的生产环境，建议限制监听的 IP 地址。

pg_port

参数名称： pg_port， 类型： port， 层次：C

PostgreSQL 服务器监听的端口，默认为 5432。

pg_localhost

参数名称： pg_localhost， 类型： path， 层次：C

本地主机连接 PostgreSQL 使用的 Unix 套接字目录，默认值为 /var/run/postgresql。

PostgreSQL 和 Pgbouncer 本地连接的 Unix 套接字目录，pg_exporter 和 patroni 都会优先使用 Unix 套接字访问 PostgreSQL。

pg_namespace

参数名称： pg_namespace， 类型： path， 层次：C

在 etcd 中使用的顶级命名空间，由 patroni 和 vip-manager 使用，默认值是：/pg，不建议更改。

patroni_enabled

参数名称： patroni_enabled， 类型： bool， 层次：C

是否启用 Patroni？默认值为：true。

如果禁用，则在初始化期间不会创建 Postgres 集群。Pigsty 将跳过拉起 patroni 的任务，当试图向现有的 postgres 实例添加一些组件时，可以使用此参数。

patroni_mode

参数名称： patroni_mode， 类型： enum， 层次：C

Patroni 工作模式：default，pause，remove。默认值：default。

  • default：正常使用 Patroni 引导 PostgreSQL 集群
  • pause：与 default 相似，但在引导后进入维护模式
  • remove：使用 Patroni 初始化集群，然后删除 Patroni 并使用原始 PostgreSQL。

patroni_port

参数名称： patroni_port， 类型： port， 层次：C

patroni 监听端口，默认为 8008，不建议更改。

Patroni API 服务器在此端口上监听健康检查和 API 请求。

patroni_log_dir

参数名称： patroni_log_dir， 类型： path， 层次：C

patroni 日志目录，默认为 /pg/log/patroni，由 Vector 日志代理收集。

patroni_ssl_enabled

参数名称： patroni_ssl_enabled， 类型： bool， 层次：G

使用 SSL 保护 patroni RestAPI 通信吗？默认值为 false。

此参数是一个全局标志，只能在部署之前预先设置。因为如果为 patroni 启用了 SSL，您将必须使用 HTTPS 而不是 HTTP 执行健康检查、获取指标，调用 API。

patroni_watchdog_mode

参数名称： patroni_watchdog_mode， 类型： string， 层次：C

patroni 看门狗模式：automatic，required，off，默认值为 off。

在主库故障的情况下，Patroni 可以使用 看门狗 来强制关机旧主库节点以避免脑裂。

  • off：不使用 看门狗。完全不进行 Fencing （默认行为）
  • automatic：如果内核启用了 softdog 模块并且看门狗属于 dbsu，则启用 watchdog。
  • required：强制启用 watchdog，如果 softdog 不可用则拒绝启动 Patroni/PostgreSQL。

默认值为 off，您不应该在 Infra 节点 启用看门狗，数据一致性优先于可用性的关键系统，特别是与钱有关的业务集群可以考虑打开此选项。

注意：当使用 pg_conf = crit 配置模板时，off 会被自动提升为 automatic，以确保关键业务系统的数据一致性。

请注意，如果您的所有访问流量都使用 HAproxy 健康检查 服务接入，正常是不存在脑裂风险的。

patroni_username

参数名称： patroni_username， 类型： username， 层次：C

Patroni REST API 用户名，默认为 postgres，与 patroni_password 配对使用。

Patroni 的危险 REST API （比如重启集群）由额外的用户名/密码保护，查看 配置集群 和 Patroni RESTAPI 以获取详细信息。

patroni_password

参数名称： patroni_password， 类型： password， 层次：C

Patroni REST API 密码，默认为 Patroni.API。

警告

务必在生产环境中修改此参数！

pg_primary_db

参数名称： pg_primary_db， 类型： string， 层次：C

指定集群中的主数据库名称，用于 citus 等业务数据库，默认为 postgres。

例如，在使用 Patroni 管理高可用的 Citus 集群时，您必须选择一个 “主数据库”。

此外，在这里指定的数据库名称，将在 PGSQL 模块安装完成后，显示在打印的连接串中。

pg_parameters

参数名称： pg_parameters， 类型： dict， 层次：G/C/I

可用于指定并管理 postgresql.auto.conf 中的配置参数。

当集群所有实例完成初始化后，pg_param 任务将会把本字典中的 key / value 键值对依次覆盖写入 /pg/data/postgresql.auto.conf 中。

说明

请不要手工修改该配置文件，或通过 ALTER SYSTEM 修改集群配置参数；这些修改会在下一次配置同步时被覆盖。

该变量的优先级大于 Patroni / DCS 中的集群配置（即优先级高于集群配置，由 Patroni edit-config 编辑的配置），因此通常可以在实例级别覆盖集群默认参数。

当您的集群成员有着不同的规格（不推荐的行为！）时，您可以通过本参数对每个实例的配置进行精细化管理。

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary , pg_parameters: { shared_buffers: '5GB' } }
    10.10.10.12: { pg_seq: 2, pg_role: replica , pg_parameters: { shared_buffers: '4GB' } }
    10.10.10.13: { pg_seq: 3, pg_role: replica , pg_parameters: { shared_buffers: '3GB' } }

请注意，一些 重要的集群参数（对主从库参数值有要求）是 Patroni 直接通过命令行参数管理的，具有最高优先级，无法通过此方式覆盖，对于这些参数，您必须使用 Patroni edit-config 进行管理与配置。

在主从上必须保持一致的 PostgreSQL 参数（不一致会导致从库无法启动！）：

  • wal_level
  • max_connections
  • max_locks_per_transaction
  • max_worker_processes
  • max_prepared_transactions
  • track_commit_timestamp

在主从上最好保持一致的参数（考虑到主从切换的可能性）：

  • listen_addresses
  • port
  • cluster_name
  • hot_standby
  • wal_log_hints
  • max_wal_senders
  • max_replication_slots
  • wal_keep_segments
  • wal_keep_size

您可以设置不存在的参数（例如来自扩展的 GUC，从而配置 ALTER SYSTEM 无法修改的“尚未存在”的参数），但将现有配置修改为非法值可能会导致 PostgreSQL 无法启动，请谨慎配置！

pg_files

参数名称： pg_files， 类型： path[]， 层次：C

用于指定需要拷贝至 PGDATA 目录的文件列表，默认为空数组：[]

在本参数中指定的文件将会被拷贝至 {{ pg_data }} 目录下，这主要用于下发特殊商业版本 PostgreSQL 内核要求的 License 文件。

目前仅有 PolarDB （Oracle 兼容）内核需要许可证文件，例如，您可以将 license.lic 文件放置在 files/ 目录下，并在 pg_files 中指定：

pg_files: [ license.lic ]

pg_conf

参数名称： pg_conf， 类型： enum， 层次：C

配置模板：{oltp,olap,crit,tiny}.yml，默认为 oltp.yml。

  • tiny.yml：为小节点、虚拟机、小型演示优化（1-8核，1-16GB）
  • oltp.yml：为 OLTP 工作负载和延迟敏感应用优化（4C8GB+）（默认模板）
  • olap.yml：为 OLAP 工作负载和吞吐量优化（4C8G+）
  • crit.yml：为数据一致性和关键应用优化（4C8G+）

默认值：oltp.yml，但是 配置 程序将在当前节点为小节点时将此值设置为 tiny.yml。

您可以拥有自己的模板，只需将其放在templates/<mode>.yml下，并将此值设置为模板名称即可使用。

pg_max_conn

参数名称： pg_max_conn， 类型： int， 层次：C

PostgreSQL 服务器最大连接数。你可以选择一个介于 50 到 5000 之间的值，或使用 auto 选择推荐值。

默认值为 auto，会根据 pg_conf 和 pg_default_service_dest 来设定最大连接数。

  • tiny: 100
  • olap: 200
  • oltp: 200 (pgbouncer) / 1000 (postgres)
    • pg_default_service_dest = pgbouncer : 200
    • pg_default_service_dest = postgres : 1000
  • crit: 200 (pgbouncer) / 1000 (postgres)
    • pg_default_service_dest = pgbouncer : 200
    • pg_default_service_dest = postgres : 1000

不建议将此值设定为超过 5000，否则你还需要手动增加 haproxy 服务的连接限制。

Pgbouncer 的事务池可以缓解过多的 OLTP 连接问题，因此默认情况下不建议设置很大的连接数。

对于 OLAP 场景， pg_default_service_dest 修改为 postgres 可以绕过连接池。

pg_shared_buffer_ratio

参数名称： pg_shared_buffer_ratio， 类型： float， 层次：C

Postgres 共享缓冲区内存比例，默认为 0.25，正常范围在 0.1~0.4 之间。

默认值：0.25，意味着节点内存的 25% 将被用作 PostgreSQL 的分片缓冲区。如果您想为 PostgreSQL 启用大页，那么此参数值应当适当小于 node_hugepage_ratio。

将此值设定为大于 0.4（40%）通常不是好主意，但在极端情况下可能有用。

注意，共享缓冲区只是 PostgreSQL 中共享内存的一部分，要计算总共享内存，使用 show shared_memory_size_in_huge_pages;。

pg_rto

参数名称： pg_rto， 类型： enum， 层次：C

恢复时间目标（RTO）模式，用于控制 Patroni 与 HAProxy 的超时参数，默认为 norm。

Pigsty 提供四种预设的 RTO 模式，分别针对不同的网络条件与部署场景进行了优化：

模式 适用场景 网络条件 源码目标 RTO Patroni TTL 误切风险
fast 同机柜/同交换机 < 1ms，极稳定 < 30s 20s 较高
norm 同机房（默认） 1-5ms，正常 < 45s 30s 中等
safe 同省跨机房 10-50ms，跨机房 < 90s 60s 较低
wide 跨地域/跨洲 100-200ms，公网 < 150s 120s 极低

减小 RTO 可以加快故障恢复速度，但会增加误切风险（网络抖动被误判为故障）。您需要根据实际网络条件选择合适的模式。 更多详情请参阅 RTO 利弊权衡 文档。

当前模板只识别这四个字符串键；其他值（包括数字）不会按秒数映射，而会回退到 norm。如需自定义时间组合，请修改 pg_rto_plan 并用新增的键名作为 pg_rto。

pg_rto: norm   # 默认模式，适合同机房部署
pg_rto: safe   # 跨机房部署推荐
# pg_rto: 30   # 非法键；当前模板会回退到 norm，请勿用数字表达秒数

pg_rto_plan

参数名称： pg_rto_plan， 类型： dict， 层次：G

RTO 预设配置字典，定义了 Patroni 高可用与 HAProxy 健康检查的具体超时参数，默认值包含四种预设模式：

pg_rto_plan:  # [ttl, loop, retry, start, margin, inter, fastinter, downinter, rise, fall]
  fast: [ 20  ,5  ,5  ,15 ,5  ,'1s' ,'0.5s' ,'1s' ,3 ,3 ]  # rto < 30s
  norm: [ 30  ,5  ,10 ,25 ,5  ,'2s' ,'1s'   ,'2s' ,3 ,3 ]  # rto < 45s
  safe: [ 60  ,10 ,20 ,45 ,10 ,'3s' ,'1.5s' ,'3s' ,3 ,3 ]  # rto < 90s
  wide: [ 120 ,20 ,30 ,95 ,15 ,'4s' ,'2s'   ,'4s' ,3 ,3 ]  # rto < 150s

每个模式是一个包含 10 个参数的数组，用于同时控制 Patroni 和 HAProxy 的超时行为：

索引 参数名 组件 说明
0 ttl Patroni 主库锁 TTL（秒）
1 loop_wait Patroni 主循环休眠间隔（秒）
2 retry_timeout Patroni DCS/PostgreSQL 重试超时
3 primary_start_timeout Patroni 主库恢复等待时间
4 safety_margin Patroni Watchdog 安全边界
5 inter HAProxy 健康检查间隔
6 fastinter HAProxy 状态变化时的快速检查间隔
7 downinter HAProxy 服务器宕机时的检查间隔
8 rise HAProxy 标记为 UP 所需的连续成功检查次数
9 fall HAProxy 标记为 DOWN 所需的连续失败检查次数

此参数允许用户通过覆盖默认值来自定义 RTO 行为，或添加新的 RTO 模式。例如，如果您需要一个更激进的 RTO 配置：

pg_rto_plan:
  ultra: [ 10, 2, 3, 8, 2, '0.5s', '0.25s', '0.5s', 2, 2 ]  # 极速模式，仅限低延迟环境

注意：修改此参数需要谨慎，不恰当的超时配置可能导致集群不稳定或频繁误切换。

pg_rpo

参数名称： pg_rpo， 类型： int， 层次：C

以字节为单位的候选从库落后阈值，默认值：1048576（1MiB）。该值写入 Patroni 的 maximum_lag_on_failover，用于判断从库是否有资格参与故障切换；它不是实际数据丢失量的硬上限。 异步复制下，实际最坏丢失还取决于写入速率以及 Patroni 对主库 WAL 位置的采样时机。

当主节点宕机并且所有副本都滞后时，你必须做出一个艰难的选择，在可用性和一致性之间进行权衡：

  • 提升一个落后副本成为新的主库，并尽快恢复服务，但接受可能的数据丢失。
  • 等待主库重新上线（可能永远不会），或人工干预以避免任何数据丢失。

你可以使用 crit.yml conf 模板来确保在故障转移期间没有数据丢失，但这会牺牲一些性能。

pg_libs

参数名称： pg_libs， 类型： string， 层次：C

预加载的动态共享库，默认为 pg_stat_statements,auto_explain，这是两个 PostgreSQL 自带的扩展，强烈建议启用。

对于现有集群，您可以直接 配置集群 的 shared_preload_libraries 参数并应用生效。

如果您想使用 TimescaleDB 或 Citus 扩展，您需要将 timescaledb 或 citus 添加到此列表中。timescaledb 和 citus 应当放在这个列表的最前面，例如：

citus,timescaledb,pg_stat_statements,auto_explain

其他需要动态加载的扩展也可以添加到这个列表中，例如 pg_cron， pgml 等，通常 citus 和 timescaledb 有着最高的优先级，应该添加到列表的最前面。

pg_delay

参数名称： pg_delay， 类型： interval， 层次：I

延迟备库复制延迟，默认值：0。

如果此值被设置为一个正值，备用集群主库在应用 WAL 变更之前将被延迟这个时间。设置为 1h 意味着该集群中的数据将始终滞后原集群一个小时。

查看 延迟备用集群 以获取详细信息。

pg_checksum

参数名称： pg_checksum， 类型： bool， 层次：C

为 PostgreSQL 集群启用数据校验和吗？默认值是 true，启用。

这个参数只能在 PGSQL 部署之前设置（但你可以稍后手动启用它）。

数据校验和可以帮助检测磁盘损坏和硬件故障，从 Pigsty v3.5 开始默认启用此功能以确保数据完整性。

pg_pwd_enc

参数名称： pg_pwd_enc， 类型： enum， 层次：C

密码加密算法，Pigsty v4 以后固定为 scram-sha-256。

所有新建用户都会使用 SCRAM 凭据。md5 已被淘汰，如需兼容旧客户端，请在业务连接池或客户端驱动中升级至 SCRAM。

pg_encoding

参数名称： pg_encoding， 类型： enum， 层次：C

数据库集群编码，默认为 UTF8。

不建议使用其他非 UTF8 系编码。

pg_locale

参数名称： pg_locale， 类型： enum， 层次：C

数据库集群本地化规则集 (Locale)，默认为 C。

此参数控制数据库的默认 Locale 设置，影响排序规则、字符分类等行为。使用 C 或 POSIX 可以获得最佳的性能和可预测的排序行为。

如果您需要特定语言的本地化支持，可以设置为相应的 Locale，例如 en_US.UTF-8 或 zh_CN.UTF-8。请注意，Locale 设置会影响索引的排序顺序，因此在集群初始化后无法更改。

pg_lc_collate

参数名称： pg_lc_collate， 类型： enum， 层次：C

数据库集群本地化排序规则，默认为 C。

除非您知道自己在做什么，否则不建议修改集群级别的本地排序规则设置。

pg_lc_ctype

参数名称： pg_lc_ctype， 类型： enum， 层次：C

数据库字符集 CTYPE，默认为 C。

从 Pigsty v3.5 开始，为了与 pg_lc_collate 保持一致，默认值改为 C。

pg_io_method

参数名称： pg_io_method， 类型： enum， 层次：C

PostgreSQL 的 IO 方法，默认为 worker。可选值包括：

  • auto：根据操作系统自动选择，在 Debian 系列或 EL 10+ 上使用 io_uring，否则使用 worker
  • sync：使用传统的同步 IO 方式
  • worker：使用后台工作进程处理 IO（默认选项）
  • io_uring：使用 Linux 的 io_uring 异步 IO 接口

此参数只会由当前调优模板写入 PostgreSQL 18 及以上版本的配置，用于选择异步 I/O 执行方式。

  • PostgreSQL 18 提供 worker、io_uring、sync 三个实际 GUC 枚举值；auto 是 Pigsty 模板的选择逻辑，并不是 PostgreSQL 自身的枚举值。
  • PostgreSQL 18 默认使用 worker，通过后台工作进程执行异步 I/O。
  • 如果您使用 Debian 12/Ubuntu 22+ 或 EL 10+ 系统，并希望获得最佳 IO 性能，可以考虑设置为 io_uring。

请注意，在不支持 io_uring 的系统上设置此值可能导致 PostgreSQL 启动失败，因此 auto 或 worker 是更安全的选择。

pg_etcd_password

参数名称： pg_etcd_password， 类型： password， 层次：C

此 PostgreSQL 集群在 etcd 中使用的密码，默认为空字符串 ''。

如果设置为空字符串，则会使用 pg_cluster 参数值作为密码（对于 Citus 集群则使用 pg_shard 参数值）。

此密码用于 Patroni 连接 etcd 以及 vip-manager 访问 etcd 时的认证。

pgsodium_key

参数名称： pgsodium_key， 类型： string， 层次：C

用于 pgsodium 扩展的加密主密钥，由 64 位十六进制数字组成。

默认不设置此参数，如果未指定，Pigsty 会使用 sha256(pg_cluster) 的值自动生成一个确定性的密钥。

pgsodium 是一个基于 libsodium 的 PostgreSQL 扩展，提供加密函数和透明列加密功能。 如果您需要使用 pgsodium 的加密功能，建议显式指定一个安全的随机密钥，并妥善保管。

生成随机密钥的命令示例：

openssl rand -hex 32   # 生成 64 位十六进制密钥

pgsodium_getkey_script

参数名称： pgsodium_getkey_script， 类型： path， 层次：C

pgsodium 获取密钥脚本的路径，默认使用 Pigsty 模板中的 pgsodium_getkey 脚本。

此脚本用于在 PostgreSQL 启动时获取 pgsodium 的主密钥。默认脚本会从环境变量或配置文件中读取密钥。

如果您有自定义的密钥管理需求（如使用 HashiCorp Vault、AWS KMS 等），可以提供自定义脚本路径。

PG_PROVISION

如果说 PG_BOOTSTRAP 是创建一个新的集群，那么 PG_PROVISION 就是在集群中创建默认的对象，包括：

pg_provision: true                # 在引导后提供postgres集群
pg_init: pg-init                  # 集群模板的初始化脚本，默认为`pg-init`
pg_default_roles:                 # postgres集群中的默认角色和用户
  - { name: dbrole_readonly  ,login: false ,comment: role for global read-only access     }
  - { name: dbrole_offline   ,login: false ,comment: role for restricted read-only access }
  - { name: dbrole_readwrite ,login: false ,roles: [dbrole_readonly] ,comment: role for global read-write access }
  - { name: dbrole_admin     ,login: false ,roles: [pg_monitor, dbrole_readwrite] ,comment: role for object creation }
  - { name: postgres     ,superuser: true  ,comment: system superuser }
  - { name: replicator ,replication: true  ,roles: [pg_monitor, dbrole_readonly] ,comment: system replicator }
  - { name: dbuser_dba   ,superuser: true  ,roles: [dbrole_admin]  ,pgbouncer: true ,pool_mode: session, pool_connlimit: 16 ,comment: pgsql admin user }
  - { name: dbuser_monitor ,roles: [pg_monitor, dbrole_readonly] ,pgbouncer: true ,parameters: {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment: pgsql monitor user }
pg_default_privileges:            # 管理员用户创建时的默认权限
  - GRANT USAGE      ON SCHEMAS   TO dbrole_readonly
  - GRANT SELECT     ON TABLES    TO dbrole_readonly
  - GRANT SELECT     ON SEQUENCES TO dbrole_readonly
  - GRANT EXECUTE    ON FUNCTIONS TO dbrole_readonly
  - GRANT USAGE      ON SCHEMAS   TO dbrole_offline
  - GRANT SELECT     ON TABLES    TO dbrole_offline
  - GRANT SELECT     ON SEQUENCES TO dbrole_offline
  - GRANT EXECUTE    ON FUNCTIONS TO dbrole_offline
  - GRANT INSERT     ON TABLES    TO dbrole_readwrite
  - GRANT UPDATE     ON TABLES    TO dbrole_readwrite
  - GRANT DELETE     ON TABLES    TO dbrole_readwrite
  - GRANT USAGE      ON SEQUENCES TO dbrole_readwrite
  - GRANT UPDATE     ON SEQUENCES TO dbrole_readwrite
  - GRANT TRUNCATE   ON TABLES    TO dbrole_admin
  - GRANT REFERENCES ON TABLES    TO dbrole_admin
  - GRANT TRIGGER    ON TABLES    TO dbrole_admin
  - GRANT CREATE     ON SCHEMAS   TO dbrole_admin
pg_default_schemas: [ monitor ]   # 默认模式
pg_default_extensions:            # 默认扩展
  - { name: pg_stat_statements ,schema: monitor }
  - { name: pgstattuple        ,schema: monitor }
  - { name: pg_buffercache     ,schema: monitor }
  - { name: pageinspect        ,schema: monitor }
  - { name: pg_prewarm         ,schema: monitor }
  - { name: pg_visibility      ,schema: monitor }
  - { name: pg_freespacemap    ,schema: monitor }
  - { name: postgres_fdw       ,schema: public  }
  - { name: file_fdw           ,schema: public  }
  - { name: btree_gist         ,schema: public  }
  - { name: btree_gin          ,schema: public  }
  - { name: pg_trgm            ,schema: public  }
  - { name: intagg             ,schema: public  }
  - { name: intarray           ,schema: public  }
  - { name: pg_repack }
pg_reload: true                   # HBA变化后是否重载配置？
pg_default_hba_rules:             # postgres 默认 HBA 规则集，按 order 排序
  - {user: '${dbsu}'    ,db: all         ,addr: local     ,auth: ident ,title: 'dbsu access via local os user ident'  ,order: 100}
  - {user: '${dbsu}'    ,db: replication ,addr: local     ,auth: ident ,title: 'dbsu replication from local os ident' ,order: 150}
  - {user: '${repl}'    ,db: replication ,addr: localhost ,auth: pwd   ,title: 'replicator replication from localhost',order: 200}
  - {user: '${repl}'    ,db: replication ,addr: intra     ,auth: pwd   ,title: 'replicator replication from intranet' ,order: 250}
  - {user: '${repl}'    ,db: postgres    ,addr: intra     ,auth: pwd   ,title: 'replicator postgres db from intranet' ,order: 300}
  - {user: '${monitor}' ,db: all         ,addr: localhost ,auth: pwd   ,title: 'monitor from localhost with password' ,order: 350}
  - {user: '${monitor}' ,db: all         ,addr: infra     ,auth: pwd   ,title: 'monitor from infra host with password',order: 400}
  - {user: '${admin}'   ,db: all         ,addr: infra     ,auth: ssl   ,title: 'admin @ infra nodes with pwd & ssl'   ,order: 450}
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: ssl   ,title: 'admin @ everywhere with ssl & pwd'    ,order: 500}
  - {user: '+dbrole_readonly',db: all    ,addr: localhost ,auth: pwd   ,title: 'pgbouncer read/write via local socket',order: 550}
  - {user: '+dbrole_readonly',db: all    ,addr: intra     ,auth: pwd   ,title: 'read/write biz user via password'     ,order: 600}
  - {user: '+dbrole_offline' ,db: all    ,addr: intra     ,auth: pwd   ,title: 'allow etl offline tasks from intranet',order: 650}
pgb_default_hba_rules:            # pgbouncer 默认 HBA 规则集，按 order 排序
  - {user: '${dbsu}'    ,db: pgbouncer   ,addr: local     ,auth: peer  ,title: 'dbsu local admin access with os ident',order: 100}
  - {user: 'all'        ,db: all         ,addr: localhost ,auth: pwd   ,title: 'allow all user local access with pwd' ,order: 150}
  - {user: '${monitor}' ,db: pgbouncer   ,addr: intra     ,auth: pwd   ,title: 'monitor access via intranet with pwd' ,order: 200}
  - {user: '${monitor}' ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other monitor access addr' ,order: 250}
  - {user: '${admin}'   ,db: all         ,addr: intra     ,auth: pwd   ,title: 'admin access via intranet with pwd'   ,order: 300}
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other admin access addr'   ,order: 350}
  - {user: 'all'        ,db: all         ,addr: intra     ,auth: pwd   ,title: 'allow all user intra access with pwd' ,order: 400}

pg_provision

参数名称： pg_provision， 类型： bool， 层次：C

在集群拉起后，完整本节定义的 PostgreSQL 集群置备工作。默认值为 true。

如果禁用，不会置备 PostgreSQL 集群。对于一些特殊的 “PostgreSQL” 集群，比如 Greenplum，可以关闭此选项跳过置备阶段。

pg_init

参数名称： pg_init， 类型： string， 层次：G/C

用于初始化数据库模板的 Shell 脚本位置，默认为 pg-init，该脚本会被拷贝至 /pg/bin/pg-init 后执行。

该脚本位于 roles/pgsql/templates/pg-init

你可以在该脚本中添加自己的逻辑，或者提供一个新的脚本放置在 templates/ 目录下，并将 pg_init 设置为新的脚本名称。使用自定义脚本时请保留现有的初始化逻辑。

pg_default_roles

参数名称： pg_default_roles， 类型： role[]， 层次：G/C

Postgres 集群中的默认角色和用户。

Pigsty 有一个内置的角色系统，请查看 PGSQL 访问控制：角色体系 了解详情。

pg_default_roles:                 # postgres集群中的默认角色和用户
  - { name: dbrole_readonly  ,login: false ,comment: role for global read-only access     }
  - { name: dbrole_offline   ,login: false ,comment: role for restricted read-only access }
  - { name: dbrole_readwrite ,login: false ,roles: [dbrole_readonly]               ,comment: role for global read-write access }
  - { name: dbrole_admin     ,login: false ,roles: [pg_monitor, dbrole_readwrite]  ,comment: role for object creation }
  - { name: postgres     ,superuser: true                                          ,comment: system superuser }
  - { name: replicator ,replication: true  ,roles: [pg_monitor, dbrole_readonly]   ,comment: system replicator }
  - { name: dbuser_dba   ,superuser: true  ,roles: [dbrole_admin]  ,pgbouncer: true ,pool_mode: session, pool_connlimit: 16 , comment: pgsql admin user }
  - { name: dbuser_monitor   ,roles: [pg_monitor, dbrole_readonly] ,pgbouncer: true ,parameters: {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment: pgsql monitor user }

pg_default_privileges

参数名称： pg_default_privileges， 类型： string[]， 层次：G/C

每个数据库中的默认权限（DEFAULT PRIVILEGE）设置：

pg_default_privileges:            # 管理员用户创建时的默认权限
  - GRANT USAGE      ON SCHEMAS   TO dbrole_readonly
  - GRANT SELECT     ON TABLES    TO dbrole_readonly
  - GRANT SELECT     ON SEQUENCES TO dbrole_readonly
  - GRANT EXECUTE    ON FUNCTIONS TO dbrole_readonly
  - GRANT USAGE      ON SCHEMAS   TO dbrole_offline
  - GRANT SELECT     ON TABLES    TO dbrole_offline
  - GRANT SELECT     ON SEQUENCES TO dbrole_offline
  - GRANT EXECUTE    ON FUNCTIONS TO dbrole_offline
  - GRANT INSERT     ON TABLES    TO dbrole_readwrite
  - GRANT UPDATE     ON TABLES    TO dbrole_readwrite
  - GRANT DELETE     ON TABLES    TO dbrole_readwrite
  - GRANT USAGE      ON SEQUENCES TO dbrole_readwrite
  - GRANT UPDATE     ON SEQUENCES TO dbrole_readwrite
  - GRANT TRUNCATE   ON TABLES    TO dbrole_admin
  - GRANT REFERENCES ON TABLES    TO dbrole_admin
  - GRANT TRIGGER    ON TABLES    TO dbrole_admin
  - GRANT CREATE     ON SCHEMAS   TO dbrole_admin

Pigsty 基于默认角色系统提供相应的默认权限设置，请查看 PGSQL 访问控制：默认权限 了解详情。

pg_default_schemas

参数名称： pg_default_schemas， 类型： string[]， 层次：G/C

要创建的默认模式，默认值为：[ monitor ]，这将在所有数据库上创建一个 monitor 模式，用于放置各种监控扩展、表、视图、函数。

pg_default_extensions

参数名称： pg_default_extensions， 类型： extension[]， 层次：G/C

要在所有数据库中默认创建启用的扩展列表，默认值：

pg_default_extensions: # default extensions to be created
  - { name: pg_stat_statements ,schema: monitor }
  - { name: pgstattuple        ,schema: monitor }
  - { name: pg_buffercache     ,schema: monitor }
  - { name: pageinspect        ,schema: monitor }
  - { name: pg_prewarm         ,schema: monitor }
  - { name: pg_visibility      ,schema: monitor }
  - { name: pg_freespacemap    ,schema: monitor }
  - { name: postgres_fdw       ,schema: public  }
  - { name: file_fdw           ,schema: public  }
  - { name: btree_gist         ,schema: public  }
  - { name: btree_gin          ,schema: public  }
  - { name: pg_trgm            ,schema: public  }
  - { name: intagg             ,schema: public  }
  - { name: intarray           ,schema: public  }
  - { name: pg_repack }

唯一的三方扩展是 pg_repack，这对于数据库维护很重要，所有其他扩展都是内置的 PostgreSQL Contrib 扩展插件。

监控相关的扩展默认安装在 monitor 模式中，该模式由 pg_default_schemas 创建。

pg_reload

参数名称： pg_reload， 类型： bool， 层次：A

在 hba 更改后重新加载 PostgreSQL，默认值为 true

当您想在应用 HBA 更改之前进行检查时，将其设置为 false 以禁用自动重新加载配置。

pg_default_hba_rules

参数名称： pg_default_hba_rules， 类型： hba[]， 层次：G/C

PostgreSQL 基于主机的认证规则，全局默认规则定义。默认值为：

pg_default_hba_rules:             # postgres default host-based authentication rules, order by `order`
  - {user: '${dbsu}'    ,db: all         ,addr: local     ,auth: ident ,title: 'dbsu access via local os user ident'  ,order: 100}
  - {user: '${dbsu}'    ,db: replication ,addr: local     ,auth: ident ,title: 'dbsu replication from local os ident' ,order: 150}
  - {user: '${repl}'    ,db: replication ,addr: localhost ,auth: pwd   ,title: 'replicator replication from localhost',order: 200}
  - {user: '${repl}'    ,db: replication ,addr: intra     ,auth: pwd   ,title: 'replicator replication from intranet' ,order: 250}
  - {user: '${repl}'    ,db: postgres    ,addr: intra     ,auth: pwd   ,title: 'replicator postgres db from intranet' ,order: 300}
  - {user: '${monitor}' ,db: all         ,addr: localhost ,auth: pwd   ,title: 'monitor from localhost with password' ,order: 350}
  - {user: '${monitor}' ,db: all         ,addr: infra     ,auth: pwd   ,title: 'monitor from infra host with password',order: 400}
  - {user: '${admin}'   ,db: all         ,addr: infra     ,auth: ssl   ,title: 'admin @ infra nodes with pwd & ssl'   ,order: 450}
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: ssl   ,title: 'admin @ everywhere with ssl & pwd'    ,order: 500}
  - {user: '+dbrole_readonly',db: all    ,addr: localhost ,auth: pwd   ,title: 'pgbouncer read/write via local socket',order: 550}
  - {user: '+dbrole_readonly',db: all    ,addr: intra     ,auth: pwd   ,title: 'read/write biz user via password'     ,order: 600}
  - {user: '+dbrole_offline' ,db: all    ,addr: intra     ,auth: pwd   ,title: 'allow etl offline tasks from intranet',order: 650}

默认规则面向受信内网中的常规部署，并非公网或合规场景的加固基线。默认的 +dbrole_offline 规则没有 role 字段，因此会应用到所有实例；若需实例隔离，应复制完整默认列表，并将该规则设为 role: offline。详见 身份认证 与 访问控制。

本参数为 HBA 规则对象组成的数组，在形式上与 pg_hba_rules 完全一致。 建议在全局配置统一的 pg_default_hba_rules，针对特定集群使用 pg_hba_rules 进行额外定制。两个参数中的规则都会依次应用，后者优先级更高。

pgb_default_hba_rules

参数名称： pgb_default_hba_rules， 类型： hba[]， 层次：G/C

pgbouncer default host-based authentication rules, array or hba rule object.

default value provides a fair enough security level for common scenarios, check PGSQL Authentication for details.

pgb_default_hba_rules:            # pgbouncer default host-based authentication rules, order by `order`
  - {user: '${dbsu}'    ,db: pgbouncer   ,addr: local     ,auth: peer  ,title: 'dbsu local admin access with os ident',order: 100}
  - {user: 'all'        ,db: all         ,addr: localhost ,auth: pwd   ,title: 'allow all user local access with pwd' ,order: 150}
  - {user: '${monitor}' ,db: pgbouncer   ,addr: intra     ,auth: pwd   ,title: 'monitor access via intranet with pwd' ,order: 200}
  - {user: '${monitor}' ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other monitor access addr' ,order: 250}
  - {user: '${admin}'   ,db: all         ,addr: intra     ,auth: pwd   ,title: 'admin access via intranet with pwd'   ,order: 300}
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other admin access addr'   ,order: 350}
  - {user: 'all'        ,db: all         ,addr: intra     ,auth: pwd   ,title: 'allow all user intra access with pwd' ,order: 400}

默认的 Pgbouncer HBA 规则很简单：

  1. 允许从 本地 使用密码登陆
  2. 允许从内网网断使用密码登陆

用户可以按照自己的需求进行定制。

本参数在形式上与 pgb_hba_rules 完全一致，建议在全局配置统一的 pgb_default_hba_rules，针对特定集群使用 pgb_hba_rules 进行额外定制。两个参数中的规则都会依次应用，后者优先级更高。

PG_BACKUP

本节定义了用于 pgBackRest 的变量，它被用于 PGSQL 时间点恢复 PITR。

查看 PGSQL 备份 & PITR 以获取详细信息；手工演练见 PITR 教程。

pgbackrest_enabled: true          # 在 pgsql 主机上启用 pgBackRest 吗？
pgbackrest_log_dir: /pg/log/pgbackrest # pgbackrest 日志目录，默认为 `/pg/log/pgbackrest`
pgbackrest_method: local          # pgbackrest 仓库方法：local, minio, [用户定义...]
pgbackrest_init_backup: true      # pgbackrest 初始化完成后是否立即执行全量备份？
pgbackrest_repo:                  # pgbackrest 仓库：https://pgbackrest.org/configuration.html#section-repository
  local:                          # 默认使用本地 posix 文件系统的 pgbackrest 仓库
    path: /pg/backup              # 本地备份目录，默认为 `/pg/backup`
    retention_full_type: count    # 按计数保留完整备份
    retention_full: 2             # 使用本地文件系统仓库时，最多保留 3 个完整备份，至少保留 2 个
  minio:                          # pgbackrest 的可选 minio 仓库
    type: s3                      # minio 是与 s3 兼容的，所以使用 s3
    s3_endpoint: sss.pigsty       # minio 端点域名，默认为 `sss.pigsty`
    s3_region: us-east-1          # minio 区域，默认为 us-east-1，对 minio 无效
    s3_bucket: pgsql              # minio 桶名称，默认为 `pgsql`
    s3_key: pgbackrest            # pgbackrest 的 minio 用户访问密钥
    s3_key_secret: S3User.Backup  # pgbackrest 的 minio 用户秘密密钥
    s3_uri_style: path            # 对 minio 使用路径风格的 uri，而不是主机风格
    path: /pgbackrest             # minio 备份路径，默认为 `/pgbackrest`
    storage_port: 9000            # minio 端口，默认为 9000
    storage_ca_file: /etc/pki/ca.crt  # minio ca 文件路径，默认为 `/etc/pki/ca.crt`
    block: y                      # 启用块级增量备份（pgBackRest 2.46+）
    bundle: y                     # 将小文件打包成一个文件
    bundle_limit: 20MiB           # 对象存储文件打包阈值，默认 20MiB
    bundle_size: 128MiB           # 对象存储文件打包目标大小，默认 128MiB
    cipher_type: aes-256-cbc      # 为远程备份仓库启用 AES 加密
    cipher_pass: pgBackRest       # AES 加密密码，默认为 'pgBackRest'
    retention_full_type: time     # 在 minio 仓库上按时间保留完整备份
    retention_full: 14            # 保留过去 14 天的完整备份

pgbackrest_enabled

参数名称： pgbackrest_enabled， 类型： bool， 层次：C

是否在 PGSQL 节点上启用 pgBackRest？默认值为： true

启用后，各节点都会获得 pgBackRest 配置；使用本地文件系统仓库（local）时，每个成员都会创建各自的本地 stanza。 初始与定时备份只由当前主库执行，从库上的 pg-backup 会因角色检查而退出。非本地仓库只在未定义 pg_upstream 的主库上初始化共享 stanza。

pgbackrest_log_dir

参数名称： pgbackrest_log_dir， 类型： path， 层次：C

pgBackRest 日志目录，默认为 /pg/log/pgbackrest，Vector 日志代理会引用此参数收集日志。

pgbackrest_method

参数名称： pgbackrest_method， 类型： enum， 层次：C

pgBackRest 仓库方法：默认可选项为：local、minio 或其他用户定义的方法，默认为 local。

此参数用于确定用于 pgBackRest 的仓库，所有可用的仓库方法都在 pgbackrest_repo 中定义。

Pigsty 默认使用 local 备份仓库，这将在主实例的 /pg/backup 目录上创建一个备份仓库。底层存储路径由 pg_fs_backup 指定。

pgbackrest_init_backup

参数名称： pgbackrest_init_backup， 类型： bool， 层次：C

在 pgBackRest 初始化完成后是否立即执行一次全量备份？默认为 true。

此任务仅在集群主库（primary）且未定义 pg_upstream 时尝试执行。任务对备份错误使用 ignore_errors， 因此启用此参数不等于保证已经存在基础备份；只有命令成功后才会写入 /etc/pgbackrest/initial.done。 部署后必须用 pig pb info（或 pb info）核验实际备份。

pgbackrest_repo

参数名称： pgbackrest_repo， 类型： dict， 层次：G/C

pgBackRest 仓库文档：https://pgbackrest.org/configuration.html#section-repository

默认值包括 local 与 minio 两个候选仓库，定义如下。pgbackrest_method 只选择其中一个， v4.5.0 模板只将被选项渲染为 pgBackRest 的 repo1；同时列出两个字典项不表示双仓同时备份：

pgbackrest_repo:                  # pgbackrest 仓库：https://pgbackrest.org/configuration.html#section-repository
  local:                          # 默认使用本地 posix 文件系统的 pgbackrest 仓库
    path: /pg/backup              # 本地备份目录，默认为 `/pg/backup`
    retention_full_type: count    # 按计数保留完整备份
    retention_full: 2             # 使用本地文件系统仓库时，最多保留 3 个完整备份，至少保留 2 个
  minio:                          # pgbackrest 的可选 minio 仓库
    type: s3                      # minio 是与 s3 兼容的，所以使用 s3
    s3_endpoint: sss.pigsty       # minio 端点域名，默认为 `sss.pigsty`
    s3_region: us-east-1          # minio 区域，默认为 us-east-1，对 minio 无效
    s3_bucket: pgsql              # minio 桶名称，默认为 `pgsql`
    s3_key: pgbackrest            # pgbackrest 的 minio 用户访问密钥
    s3_key_secret: S3User.Backup  # pgbackrest 的 minio 用户秘密密钥
    s3_uri_style: path            # 对 minio 使用路径风格的 uri，而不是主机风格
    path: /pgbackrest             # minio 备份路径，默认为 `/pgbackrest`
    storage_port: 9000            # minio 端口，默认为 9000
    storage_ca_file: /etc/pki/ca.crt  # minio ca 文件路径，默认为 `/etc/pki/ca.crt`
    block: y                      # 启用块级增量备份（pgBackRest 2.46+）
    bundle: y                     # 将小文件打包成一个文件
    bundle_limit: 20MiB           # 对象存储文件打包阈值，默认 20MiB
    bundle_size: 128MiB           # 对象存储文件打包目标大小，默认 128MiB
    cipher_type: aes-256-cbc      # 为远程备份仓库启用 AES 加密
    cipher_pass: pgBackRest       # AES 加密密码，默认为 'pgBackRest'
    retention_full_type: time     # 在 minio 仓库上按时间保留完整备份
    retention_full: 14            # 保留过去 14 天的完整备份

您可以定义新的备份仓库，例如使用 AWS S3，GCP 或其他云供应商的 S3 兼容存储服务。

块级增量备份 (Block Incremental Backup)：从 pgBackRest 2.46 版本开始支持 block: y 选项，可以实现块级增量备份。 这意味着在增量备份时，pgBackRest 只会备份发生变化的数据块，而不是整个变化的文件，从而大幅减少备份数据量和备份时间。 此功能对于大型数据库特别有用，建议在对象存储仓库上启用此选项。

PG_ACCESS

本节负责数据库访问路径，包括：

  • 在每个 PGSQL 节点上部署 Pgbouncer 连接池并设定默认行为
  • 通过本地或专用 haproxy 节点发布服务端口
  • 绑定可选的 L2 VIP、注册 DNS 记录
pgbouncer_enabled: true           # if disabled, pgbouncer will not be launched on pgsql host
pgbouncer_port: 6432              # pgbouncer listen port, 6432 by default
pgbouncer_log_dir: /pg/log/pgbouncer  # pgbouncer log dir, `/pg/log/pgbouncer` by default
pgbouncer_auth_query: false       # query postgres to retrieve unlisted business users?
pgbouncer_poolmode: transaction   # pooling mode: transaction,session,statement, transaction by default
pgbouncer_sslmode: disable        # pgbouncer client ssl mode, disable by default
pgbouncer_ignore_param: [ extra_float_digits, application_name, TimeZone, DateStyle, IntervalStyle, search_path ]
pg_weight: 100          #INSTANCE # relative load balance weight in service, 100 by default, 0-255
pg_service_provider: ''           # dedicate haproxy node group name, or empty string for local nodes by default
pg_default_service_dest: pgbouncer # default service destination if svc.dest='default'
pg_default_services:              # postgres default service definitions
  - { name: primary ,port: 5433 ,dest: default  ,check: /primary   ,selector: "[]" }
  - { name: replica ,port: 5434 ,dest: default  ,check: /read-only ,selector: "[]" , backup: "[? pg_role == `primary` || pg_role == `offline` ]" }
  - { name: default ,port: 5436 ,dest: postgres ,check: /primary   ,selector: "[]" }
  - { name: offline ,port: 5438 ,dest: postgres ,check: /replica   ,selector: "[? pg_role == `offline` || pg_offline_query ]" , backup: "[? pg_role == `replica` && !pg_offline_query]"}
pg_vip_enabled: false             # enable a l2 vip for pgsql primary? false by default
pg_vip_address: 127.0.0.1/24      # vip address in `<ipv4>/<mask>` format, require if vip is enabled
pg_vip_interface: auto            # vip network interface to listen, auto by default
pg_dns_suffix: ''                 # pgsql dns suffix, '' by default
pg_dns_target: auto               # auto, primary, vip, none, or ad hoc ip

pgbouncer_enabled

参数名称： pgbouncer_enabled， 类型： bool， 层次：C

默认值为 true，如果禁用，将不会在 PGSQL节点 上配置连接池 Pgbouncer。

pgbouncer_port

参数名称： pgbouncer_port， 类型： port， 层次：C

Pgbouncer 监听端口，默认为 6432。

pgbouncer_log_dir

参数名称： pgbouncer_log_dir， 类型： path， 层次：C

Pgbouncer 日志目录，默认为 /pg/log/pgbouncer，Vector 日志代理会根据此参数收集 Pgbouncer 日志。

pgbouncer_auth_query

参数名称： pgbouncer_auth_query， 类型： bool， 层次：C

是否允许 Pgbouncer 查询 PostgreSQL，以允许未显式列出的用户通过连接池访问 PostgreSQL？默认值是 false。

如果启用，pgbouncer 用户将使用 SELECT username, password FROM monitor.pgbouncer_auth($1) 对 postgres 数据库进行身份验证，否则，只有带有 pgbouncer: true 的业务用户才被允许连接到 Pgbouncer 连接池。

pgbouncer_poolmode

参数名称： pgbouncer_poolmode， 类型： enum， 层次：C

Pgbouncer 连接池池化模式：transaction,session,statement，默认为 transaction。

  • session：会话级池化，具有最佳的功能兼容性。
  • transaction：事务级池化，具有更好的性能（许多小连接），可能会破坏某些会话级特性，如 NOTIFY/LISTEN 等…
  • statements：语句级池化，用于简单的只读查询。

如果您的应用出现功能兼容性问题，可以考虑修改此参数为 session。

pgbouncer_sslmode

参数名称： pgbouncer_sslmode， 类型： enum， 层次：C

Pgbouncer 客户端 ssl 模式，默认为 disable。

注意，启用 SSL 可能会对你的 pgbouncer 产生巨大的性能影响。

  • disable：如果客户端请求 TLS 则忽略（默认）
  • allow：如果客户端请求 TLS 则使用。如果没有则使用纯 TCP。不验证客户端证书。
  • prefer：与 allow 相同。
  • require：客户端必须使用 TLS。如果没有则拒绝客户端连接。不验证客户端证书。
  • verify-ca：客户端必须使用有效的客户端证书的 TLS。
  • verify-full：与 verify-ca 相同。

pgbouncer_ignore_param

参数名称： pgbouncer_ignore_param， 类型： string[]， 层次：C

PgBouncer 忽略的启动参数列表，默认值为：

[ extra_float_digits, application_name, TimeZone, DateStyle, IntervalStyle, search_path ]

这些参数会被配置到 PgBouncer 配置文件中的 ignore_startup_parameters 选项。当客户端连接时设置这些参数时，PgBouncer 不会因为连接池中的连接参数不匹配而创建新的连接。

这允许不同的客户端使用相同的连接池，即使它们设置了不同的这些参数值。此参数在 Pigsty v3.5 中新增。

pg_weight

参数名称： pg_weight， 类型： int， 层次：I

服务中的相对负载均衡权重，默认为100，范围0-255。

默认值： 100。您必须在实例变量中定义它，并 重载服务 以生效。

pg_service_provider

参数名称： pg_service_provider， 类型： string， 层次：G/C

专用的 haproxy 节点组名，或默认为本地节点的空字符串。

如果指定，PostgreSQL 服务将注册到专用的 haproxy 节点组，而不是当下的 PGSQL 集群节点。

请记住为每个服务在专用的 haproxy 节点上分配 唯一 的端口！

例如，如果我们在3节点的 pg-test 集群上定义以下参数：

pg_service_provider: infra       # use load balancer on group `infra`
pg_default_services:             # alloc port 10001 and 10002 for pg-test primary/replica service  
  - { name: primary ,port: 10001 ,dest: postgres  ,check: /primary   ,selector: "[]" }
  - { name: replica ,port: 10002 ,dest: postgres  ,check: /read-only ,selector: "[]" , backup: "[? pg_role == `primary` || pg_role == `offline` ]" }

pg_default_service_dest

参数名称： pg_default_service_dest， 类型： enum， 层次：G/C

当定义一个 服务 时，如果 svc.dest='default'，此参数将用作默认值。

默认值： pgbouncer，意味着5433主服务和5434副本服务将默认将流量路由到 pgbouncer。

如果您不想使用 pgbouncer，将其设置为 postgres。流量将直接路由到 postgres。

pg_default_services

参数名称： pg_default_services， 类型： service[]， 层次：G/C

postgres 默认服务定义

默认值是四个默认服务定义，如 PGSQL Service 所述

pg_default_services:               # postgres default service definitions
  - { name: primary ,port: 5433 ,dest: default  ,check: /primary   ,selector: "[]" }
  - { name: replica ,port: 5434 ,dest: default  ,check: /read-only ,selector: "[]" , backup: "[? pg_role == `primary` || pg_role == `offline` ]" }
  - { name: default ,port: 5436 ,dest: postgres ,check: /primary   ,selector: "[]" }
  - { name: offline ,port: 5438 ,dest: postgres ,check: /replica   ,selector: "[? pg_role == `offline` || pg_offline_query ]" , backup: "[? pg_role == `replica` && !pg_offline_query]"}

pg_vip_enabled

参数名称： pg_vip_enabled， 类型： bool， 层次：C

为 PGSQL 集群启用 L2 VIP 吗？默认值是 false，表示不创建 L2 VIP。

启用 L2 VIP 后，会有一个 VIP 绑定在集群主实例节点上，由 vip-manager 管理，根据 etcd 中的数据进行判断。

L2 VIP 只能在相同的 L2 网络中使用，这可能会对您的网络拓扑产生额外的限制。

pg_vip_address

参数名称： pg_vip_address， 类型： cidr4， 层次：C

如果启用 vip，则需要<ipv4>/<mask>格式的 vip 地址。

默认值： 127.0.0.1/24。这个值由两部分组成：ipv4 和 mask，用 / 分隔。

pg_vip_interface

参数名称： pg_vip_interface， 类型： string， 层次：C/I

vip network interface to listen, auto by default.

L2 VIP 监听的网卡接口，默认为 auto。Pigsty 会根据 inventory 中的实例 IP 自动探测对应网卡。

它应该是您节点的首要网卡名，即您在配置清单中使用的 IP 地址。

自动探测不适用于非标准路由、策略路由等特殊网络环境时，您可以在实例变量上显式覆盖：

pg-test:
    hosts:
        10.10.10.11: {pg_seq: 1, pg_role: replica ,pg_vip_interface: eth0 }
        10.10.10.12: {pg_seq: 2, pg_role: primary ,pg_vip_interface: eth1 }
        10.10.10.13: {pg_seq: 3, pg_role: replica ,pg_vip_interface: eth2 }
    vars:
      pg_vip_enabled: true          # 为这个集群启用L2 VIP，默认绑定到主实例
      pg_vip_address: 10.10.10.3/24 # L2网络CIDR: 10.10.10.0/24, vip地址: 10.10.10.3
      # pg_vip_interface: eth1      # 如果您的节点有统一的接口，您可以在这里定义它

pg_dns_suffix

参数名称： pg_dns_suffix， 类型： string， 层次：C

PostgreSQL DNS 名称后缀，默认为空字符串。

在默认情况下，PostgreQL 集群名会作为 DNS 域名注册到 Infra 节点的 dnsmasq 中对外提供解析。

您可以通过本参数指定一个域名后缀，这样会使用 {{ pg_cluster }}{{ pg_dns_suffix }} 作为集群 DNS 名称。

例如，如果您将 pg_dns_suffix 设置为 .db.vip.company.tld，那么 pg-test 的集群 DNS 名称将是 pg-test.db.vip.company.tld

pg_dns_target

参数名称： pg_dns_target， 类型： enum， 层次：C

Could be: auto, primary, vip, none, or an ad hoc ip address, which will be the target IP address of cluster DNS record.

default values: auto , which will bind to pg_vip_address if pg_vip_enabled, or fallback to cluster primary instance ip address.

  • vip：bind to pg_vip_address
  • primary：resolve to cluster primary instance ip address
  • auto：resolve to pg_vip_address if pg_vip_enabled, or fallback to cluster primary instance ip address.
  • none：do not bind to any ip address
  • <ipv4>：bind to the given IP address

可以是：auto、primary、vip、none 或一个特定的 IP 地址，它将是集群 DNS 记录的解析目标 IP 地址。

默认值： auto，如果 pg_vip_enabled，将绑定到 pg_vip_address，否则会回退到集群主实例的 IP 地址。

  • vip：绑定到 pg_vip_address
  • primary：解析为集群主实例 IP 地址
  • auto：如果 pg_vip_enabled，解析为 pg_vip_address，或回退到集群主实例 ip 地址。
  • none：不绑定到任何 ip 地址
  • <ipv4>：绑定到指定的 IP 地址

PG_MONITOR

PG_MONITOR 组的参数用于监控 PostgreSQL 数据库、Pgbouncer 连接池与 pgBackRest 备份系统的状态。

此参数组定义了三个 Exporter 的配置：pg_exporter 用于监控 PostgreSQL，pgbouncer_exporter 用于监控连接池，pgbackrest_exporter 用于监控备份状态。

pg_exporter_enabled: true              # 在 pgsql 主机上启用 pg_exporter 吗？
pg_exporter_config: pg_exporter.yml    # pg_exporter 配置文件名
pg_exporter_cache_ttls: '1,10,60,300'  # pg_exporter 收集器 ttl 阶段（秒），默认为 '1,10,60,300'
pg_exporter_port: 9630                 # pg_exporter 监听端口，默认为 9630
pg_exporter_params: 'sslmode=disable'  # pg_exporter dsn 的额外 url 参数
pg_exporter_url: ''                    # 如果指定，将覆盖自动生成的 pg dsn
pg_exporter_auto_discovery: true       # 启用自动数据库发现？默认启用
pg_exporter_exclude_database: 'template0,template1,postgres' # 在自动发现过程中不会被监控的数据库的 csv 列表
pg_exporter_include_database: ''       # 在自动发现过程中将被监控的数据库的 csv 列表
pg_exporter_connect_timeout: 200       # pg_exporter 连接超时（毫秒），默认为 200
pg_exporter_options: ''                # 覆盖 pg_exporter 的额外选项
pgbouncer_exporter_enabled: true       # 在 pgsql 主机上启用 pgbouncer_exporter 吗？
pgbouncer_exporter_port: 9631          # pgbouncer_exporter 监听端口，默认为 9631
pgbouncer_exporter_url: ''             # 如果指定，将覆盖自动生成的 pgbouncer dsn
pgbouncer_exporter_options: ''         # 覆盖 pgbouncer_exporter 的额外选项
pgbackrest_exporter_enabled: true      # 在 pgsql 主机上启用 pgbackrest_exporter 吗？
pgbackrest_exporter_port: 9854         # pgbackrest_exporter 监听端口，默认为 9854
pgbackrest_exporter_options: >-        # 覆盖 pgbackrest_exporter 的额外选项
  --collect.interval=120
  --log.level=info

pg_exporter_enabled

参数名称： pg_exporter_enabled， 类型： bool， 层次：C

是否在 PGSQL 节点上启用 pg_exporter？默认值为：true。

PG Exporter 用于监控 PostgreSQL 数据库实例，如果不想安装 pg_exporter 可以设置为 false。

pg_exporter_config

参数名称： pg_exporter_config， 类型： string， 层次：C

pg_exporter 的收集器配置文件名，默认值：pg_exporter.yml。Pgbouncer Exporter 使用独立且固定的 pgbouncer_exporter.yml 模板，不受此参数影响。

默认模板位于 roles/pg_monitor/templates/pg_exporter.yml。若要使用自定义文件，需要将其放在 Ansible 的模板搜索路径中，并在这里填写对应模板名。

pg_exporter_cache_ttls

参数名称： pg_exporter_cache_ttls， 类型： string， 层次：C

pg_exporter 收集器 TTL 阶梯（秒），默认为 ‘1,10,60,300’

默认值：1,10,60,300，它将为不同的度量收集器使用不同的 TTL 值： 1s, 10s, 60s, 300s。

PG Exporter 内置了缓存机制，避免多个 Prometheus 重复抓取对数据库产生不当影响，所有指标收集器按 TTL 分为四类：

ttl_fast: "{{ pg_exporter_cache_ttls.split(',')[0]|int }}"         # critical queries
ttl_norm: "{{ pg_exporter_cache_ttls.split(',')[1]|int }}"         # common queries
ttl_slow: "{{ pg_exporter_cache_ttls.split(',')[2]|int }}"         # slow queries (e.g table size)
ttl_slowest: "{{ pg_exporter_cache_ttls.split(',')[3]|int }}"      # ver slow queries (e.g bloat)

例如，在默认配置下，存活类指标默认最多缓存 1s，大部分普通指标会缓存 10s（应当与监控抓取间隔 vmetrics_scrape_interval 相同）。 少量变化缓慢的查询会有 60s 的 TTL，极个别大开销监控查询会有 300s 的 TTL。

pg_exporter_port

参数名称： pg_exporter_port， 类型： port， 层次：C

pg_exporter 监听端口号，默认值为：9630

pg_exporter_params

参数名称： pg_exporter_params， 类型： string， 层次：C

pg_exporter 所使用 DSN 中额外的 URL PATH 参数。

默认值：sslmode=disable，它将禁用用于监控连接的 SSL（因为默认使用本地 unix 套接字）。

pg_exporter_url

参数名称： pg_exporter_url， 类型： pgurl， 层次：C

如果指定了本参数，将会覆盖自动生成的 PostgreSQL DSN，使用指定的 DSN 连接 PostgreSQL。默认值为空字符串。

如果没有指定此参数，PG Exporter 默认会使用以下的连接串访问 PostgreSQL：

postgres://{{ pg_monitor_username }}:{{ pg_monitor_password }}@{{ pg_host }}:{{ pg_port }}/postgres{% if pg_exporter_params != '' %}?{{ pg_exporter_params }}{% endif %}

当您想监控一个远程的 PostgreSQL 实例时，或者需要使用不同的监控用户/密码，配置选项时，可以使用这个参数。

pg_exporter_auto_discovery

参数名称： pg_exporter_auto_discovery， 类型： bool， 层次：C

启用自动数据库发现吗？ 默认启用：true。

PG Exporter 默认会连接到 DSN 中指定的数据库 （默认为管理数据库 postgres） 收集全局指标，如果您希望收集所有业务数据库的指标，可以开启此选项。 PG Exporter 会自动发现目标 PostgreSQL 实例中的所有数据库，并在这些数据库中收集 库级监控指标。

pg_exporter_exclude_database

参数名称： pg_exporter_exclude_database， 类型： string， 层次：C

如果启用了数据库自动发现（默认启用），在这个参数指定的列表中的数据库将不会被监控。 默认值为： template0,template1,postgres，即管理数据库 postgres 与模板数据库会被排除在自动监控的数据库之外。

作为例外，DSN 中指定的数据库不受此参数影响，例如，PG Exporter 如果连接的是 postgres 数据库，那么即使 postgres 在此列表中，也会被监控。

pg_exporter_include_database

参数名称： pg_exporter_include_database， 类型： string， 层次：C

如果启用了数据库自动发现（默认启用），在这个参数指定的列表中的数据库才会被监控。默认值为空字符串，即不启用此功能。

参数的形式是由逗号分隔的数据库名称列表，例如：db1,db2,db3。

此参数相对于 [pg_exporter_exclude_database] 有更高的优先级，相当于白名单模式。如果您只希望监控特定的数据库，可以使用此参数。

pg_exporter_connect_timeout

参数名称： pg_exporter_connect_timeout， 类型： int， 层次：C

pg_exporter 连接超时（毫秒），默认为 200 （单位毫秒）

当 PG Exporter 尝试连接到 PostgreSQL 数据库时，最多会等待多长时间？超过这个时间，PG Exporter 将会放弃连接并报错。

默认值 200毫秒 对于绝大多数场景（例如：同可用区监控）都是足够的，但是如果您监控的远程 PostgreSQL 位于另一个大洲，您可能需要增加此值以避免连接超时。

pg_exporter_options

参数名称： pg_exporter_options， 类型： arg， 层次：C

传给 PG Exporter 的命令行参数，默认值为："" 空字符串。

当使用空字符串时，会使用默认的命令参数：

{% if pg_exporter_options != '' %}
PG_EXPORTER_OPTS='--web.listen-address=:{{ pg_exporter_port }} {{ pg_exporter_options }}'
{% else %}
PG_EXPORTER_OPTS='--web.listen-address=:{{ pg_exporter_port }} --log.level=info'
{% endif %}

注意，请不要在本参数中覆盖 pg_exporter_port 的端口配置。

pgbouncer_exporter_enabled

参数名称： pgbouncer_exporter_enabled， 类型： bool， 层次：C

在 PGSQL 节点上，是否启用 pgbouncer_exporter？默认值为：true。

pgbouncer_exporter_port

参数名称： pgbouncer_exporter_port， 类型： port， 层次：C

pgbouncer_exporter 监听端口号，默认值为：9631

pgbouncer_exporter_url

参数名称： pgbouncer_exporter_url， 类型： pgurl， 层次：C

如果指定了本参数，将会覆盖自动生成的 pgbouncer DSN，使用指定的 DSN 连接 pgbouncer。默认值为空字符串。

如果没有指定此参数，Pgbouncer Exporter 默认会使用以下的连接串访问 Pgbouncer：

postgres://{{ pg_monitor_username }}:{{ pg_monitor_password }}@:{{ pgbouncer_port }}/pgbouncer?host={{ pg_localhost }}&sslmode=disable

当您想监控一个远程的 Pgbouncer 实例时，或者需要使用不同的监控用户/密码，配置选项时，可以使用这个参数。

pgbouncer_exporter_options

参数名称： pgbouncer_exporter_options， 类型： arg， 层次：C

传给 Pgbouncer Exporter 的命令行参数，默认值为："" 空字符串。

当使用空字符串时，会使用默认的命令参数：

{% if pgbouncer_exporter_options != '' %}
PG_EXPORTER_OPTS='--web.listen-address=:{{ pgbouncer_exporter_port }} {{ pgbouncer_exporter_options }}'
{% else %}
PG_EXPORTER_OPTS='--web.listen-address=:{{ pgbouncer_exporter_port }} --log.level=info'
{% endif %}

注意，请不要在本参数中覆盖 pgbouncer_exporter_port 的端口配置。

pgbackrest_exporter_enabled

参数名称： pgbackrest_exporter_enabled， 类型： bool， 层次：C

是否在 PGSQL 节点上启用 pgbackrest_exporter？默认值为：true。

pgbackrest_exporter 用于监控 pgBackRest 备份系统的状态，包括备份的大小、时间、类型、持续时长等关键指标。

pgbackrest_exporter_port

参数名称： pgbackrest_exporter_port， 类型： port， 层次：C

pgbackrest_exporter 监听端口号，默认值为：9854。

此端口会注册到 VictoriaMetrics 兼容的抓取目标中，用于采集备份相关指标。

pgbackrest_exporter_options

参数名称： pgbackrest_exporter_options， 类型： arg， 层次：C

传给 pgbackrest_exporter 的命令行参数，默认值为：

pgbackrest_exporter_options: >-
  --collect.interval=120
  --log.level=info

即每 120 秒采集一次，日志级别为 info。设置此参数会整体覆盖默认参数。

PG_REMOVE

pgsql-rm.yml 会调用 pg_remove 角色来安全地移除 PostgreSQL 实例。本节参数用于控制清理行为，避免误删。

pg_rm_data: true                  # remove postgres data during remove? true by default
pg_rm_backup: true                # remove pgbackrest backup during primary remove? true by default
pg_rm_pkg: true                   # uninstall postgres packages during remove? true by default
pg_safeguard: false               # stop pg_remove running if pg_safeguard is enabled, false by default

pg_rm_data

参数名称： pg_rm_data， 类型： bool， 层次：G/C/A

删除 PGSQL 实例时是否清理 pg_data 以及软链，默认值 true。

该开关既影响 pgsql-rm.yml，也影响其他触发 pg_remove 的场景。设为 false 可以保留数据目录，便于手动检查或重新挂载。

pg_rm_backup

参数名称： pg_rm_backup， 类型： bool， 层次：G/C/A

删除主库时是否一并清理 pgBackRest 仓库与配置，默认值 true。

该参数仅对 pg_role=primary 的主实例生效：pg_remove 会先停止 pgBackRest、删除当前集群的 stanza，并在 pgbackrest_method == 'local' 时移除 pg_fs_backup 中的数据。备用集群或上游备份不会受到影响。

pg_rm_pkg

参数名称： pg_rm_pkg， 类型： bool， 层次：G/C/A

在清理 PGSQL 实例时是否卸载 pg_packages 安装的所有软件包，默认值 true。

如果只想暂时停机并保留二进制文件，可将其设为 false，否则 pg_remove 会调用系统包管理器彻底卸载 PostgreSQL 相关组件。

pg_safeguard

参数名称： pg_safeguard， 类型： bool， 层次：G/C/A

防误删保险，默认值为 false。当显式设置为 true 时，pg_remove 会立即终止并提示，必须使用 -e pg_safeguard=false 或在变量中关闭后才会继续。

建议在生产环境批量清理前先开启此开关，确认命令与目标节点无误后再解除，以避免误操作导致实例被删除。

12 - 预置剧本

如何使用 ansible 剧本来管理 PostgreSQL 集群

Pigsty 提供了一系列剧本，用于集群上下线扩缩容，用户/数据库管理，监控、备份恢复或迁移已有实例。

剧本 功能
pgsql.yml 初始化 PostgreSQL 集群或添加新的从库
pgsql-rm.yml 移除 PostgreSQL 集群，或移除某个实例
pgsql-user.yml 在现有的 PostgreSQL 集群中添加新的业务用户
pgsql-db.yml 在现有的 PostgreSQL 集群中添加新的业务数据库
pgsql-monitor.yml 将远程 PostgreSQL 实例纳入监控中
pgsql-migration.yml 为现有的 PostgreSQL 集群生成迁移手册和脚本
pgsql-pitr.yml 执行 PostgreSQL 时间点恢复 (PITR)

保护机制

使用 PGSQL 剧本时需要 特别注意，剧本 pgsql.yml 与 pgsql-rm.yml 使用不当会有误删数据库的风险！

  • 在执行时添加 -l 参数，限制命令执行的对象范围，并确保自己在正确的目标上执行正确的任务。
  • 限制范围通常以一个数据库集群为宜，使用不带参数的 pgsql.yml 在生产环境中是一个高危操作，务必三思而后行。
  • 移除前核对 pig pg list <cluster> 与 pig pb info，确认近期备份，并让操作者输入精确目标。

出于防止误删的目的，Pigsty 的 PGSQL 模块提供了防误删保险，由 pg_safeguard 参数控制。 当 pg_safeguard 设置为 true 时，pgsql-rm.yml 剧本会立即中止执行，防止误删数据库集群。

# 将会中止执行，保护数据安全
./pgsql-rm.yml -l pg-test -e pg_safeguard=true

# 通过命令行参数强制覆盖保护开关
./pgsql-rm.yml -l pg-test -e pg_safeguard=false

除了 pg_safeguard 外，pgsql-rm.yml 还提供了更细粒度的控制参数：

参数 默认值 说明
pg_safeguard false 防误删保险，设为 true 时剧本会中止执行
pg_rm_data true 是否移除 PostgreSQL 数据目录
pg_rm_backup true 是否移除 pgBackRest 备份数据（仅主库移除时生效）
pg_rm_pkg true 是否卸载 PostgreSQL 软件包

这些参数允许你根据实际需求精确控制移除行为：

# 移除实例的服务、监控、DCS 注册等组件，但保留数据目录
./pgsql-rm.yml -l pg-test -e pg_rm_data=false

# 移除集群但保留备份数据
./pgsql-rm.yml -l pg-test -e pg_rm_backup=false

# 移除集群并卸载软件包
./pgsql-rm.yml -l pg-test -e pg_rm_pkg=true

pgsql.yml

剧本 pgsql.yml 用于初始化 PostgreSQL 集群或添加新的从库。

下面是使用此剧本初始化沙箱环境中 PostgreSQL 集群的过程：

asciicast

基本用法

./pgsql.yml -l pg-meta            # 初始化集群 pg-meta
./pgsql.yml -l 10.10.10.13        # 初始化/添加实例 10.10.10.13
./pgsql.yml -l pg-test -t pg_service  # 刷新集群 pg-test 的服务
./pgsql.yml -l pg-test -t pg_hba,pgbouncer_hba,pgbouncer_reload -e pg_reload=true  # 重载HBA规则

包装脚本

Pigsty 提供了便捷的包装脚本简化常见操作：

bin/pgsql-add pg-meta             # 初始化 pgsql 集群 pg-meta
bin/pgsql-add 10.10.10.10         # 初始化 pgsql 实例 10.10.10.10
bin/pgsql-add pg-test 10.10.10.13 # 添加 10.10.10.13 到集群 pg-test（自动刷新服务）
bin/pgsql-svc pg-test             # 刷新 pg-test 的 haproxy 服务（成员变更时使用）
bin/pgsql-hba pg-test             # 重载 pg-test 的 pg/pgb HBA 规则

任务列表

本剧本包含以下子任务：

# pg_install              : 安装 postgres 软件包与扩展
#   - pg_dbsu             : 设置 postgres 超级用户
#     - pg_dbsu_create    : 创建 dbsu 用户
#     - pg_dbsu_sudo      : 配置 dbsu sudo 权限
#     - pg_ssh            : 交换 dbsu SSH 密钥
#   - pg_pkg              : 安装 postgres 软件包
#     - pg_pre            : 安装前置任务
#     - pg_ext            : 安装 postgres 扩展包
#     - pg_post           : 安装后置任务
#   - pg_link             : 将 pgsql 版本 bin 链接到 /usr/pgsql
#   - pg_path             : 将 pgsql bin 添加到系统路径
#   - pg_dir              : 创建 postgres 目录并设置 FHS
#   - pg_bin              : 同步 /pg/bin 脚本
#   - pg_alias            : 配置 pgsql/psql 别名
#   - pg_dummy            : 创建 dummy 占位文件
#
# pg_bootstrap            : 引导 postgres 集群
#   - pg_config           : 生成 postgres 配置
#     - pg_conf           : 生成 patroni 配置
#     - pg_key            : 生成 pgsodium 密钥
#   - pg_cert             : 为 postgres 签发证书
#     - pg_cert_private   : 检查 pg 私钥是否存在
#     - pg_cert_issue     : 签发 pg 服务端证书
#     - pg_cert_copy      : 复制密钥与证书到 pg 节点
#   - pg_launch           : 启动 patroni 主库与从库
#     - pg_watchdog       : 授予 postgres watchdog 权限
#     - pg_primary        : 启动 patroni/postgres 主库
#     - pg_init           : 使用角色/模板初始化 pg 集群
#     - pg_pass           : 将 .pgpass 文件写入 pg 主目录
#     - pg_replica        : 启动 patroni/postgres 从库
#     - pg_hba            : 生成 pg HBA 规则
#     - patroni_reload    : 重新加载 patroni 配置
#     - pg_patroni        : 必要时暂停或移除 patroni
#
# pg_provision            : 创建 postgres 业务用户与数据库
#   - pg_user             : 创建 postgres 业务用户
#     - pg_user_config    : 渲染创建用户的 sql
#     - pg_user_create    : 在 postgres 上创建用户
#   - pg_db               : 创建 postgres 业务数据库
#     - pg_db_drop        : 删除数据库（state=absent/recreate时）
#     - pg_db_config      : 渲染创建数据库的 sql
#     - pg_db_create      : 在 postgres 上创建数据库
#
# pg_backup               : 初始化 postgres PITR 备份
#   - pgbackrest          : 配置 pgbackrest 备份
#     - pgbackrest_config : 生成 pgbackrest 配置
#     - pgbackrest_init   : 初始化 pgbackrest 仓库
#     - pgbackrest_backup : 引导后进行初始备份
#
# pg_crontab              : 配置 postgres dbsu 定时任务
#
# pg_access               : 初始化 postgres 服务访问层
#   - pgbouncer           : 部署 pgbouncer 连接池
#     - pgbouncer_dir     : 创建 pgbouncer 目录
#     - pgbouncer_config  : 生成 pgbouncer 配置
#       - pgbouncer_hba   : 生成 pgbouncer hba 配置
#       - pgbouncer_user  : 生成 pgbouncer 用户列表
#     - pgbouncer_launch  : 启动 pgbouncer 服务
#     - pgbouncer_reload  : 重载 pgbouncer 配置
#   - pg_vip              : 使用 vip-manager 绑定 VIP 到主库
#     - pg_vip_config     : 生成 vip-manager 配置
#     - pg_vip_launch     : 启动 vip-manager 绑定 vip
#   - pg_dns              : 将 DNS 名称注册到基础设施 dnsmasq
#     - pg_dns_ins        : 注册 pg 实例名称
#     - pg_dns_cls        : 注册 pg 集群名称
#   - pg_service          : 使用 haproxy 暴露 pgsql 服务
#     - pg_service_config : 为 pg 服务生成本地 haproxy 配置
#     - pg_service_reload : 使用 haproxy 暴露 postgres 服务
#
# pg_monitor              : 设置 pgsql 监控并注册到基础设施
#   - pg_exporter         : 配置并启动 pg_exporter
#   - pgbouncer_exporter  : 配置并启动 pgbouncer_exporter
#   - pgbackrest_exporter : 配置并启动 pgbackrest_exporter
#   - pg_register         : 将 pgsql 注册到监控/日志/数据源
#     - add_metrics       : 将 pg 注册为 victoria 监控目标
#     - add_logs          : 将 pg 注册为 vector 日志来源
#     - add_ds            : 将 pg 数据库注册为 grafana 数据源

以下管理任务使用到了此剧本

注意事项

  • 单独针对某一集群从库执行此剧本时，用户应当确保 集群主库已经完成初始化！
  • 扩容完成后，您需要 重载服务 与 重载HBA，包装脚本 bin/pgsql-add 会自动完成这些任务。

集群扩容时，如果 Patroni 拉起从库的时间过长，Ansible 剧本可能会因为超时而中止：

  • 典型错误信息为：wait for postgres/patroni replica 任务执行很长时间后中止
  • 但制作从库的进程会继续，例如制作从库需超过1天的场景，后续处理请参考 FAQ：制作从库失败。

pgsql-rm.yml

剧本 pgsql-rm.yml 用于移除 PostgreSQL 集群，或移除某个实例。

下面是使用此剧本移除沙箱环境中 PostgreSQL 集群的过程：

asciicast

基本用法

./pgsql-rm.yml -l pg-test          # 移除集群 pg-test
./pgsql-rm.yml -l 10.10.10.13      # 移除实例 10.10.10.13

命令行参数

本剧本可以使用以下命令行参数控制其行为：

./pgsql-rm.yml -l pg-test          # 移除集群 pg-test
    -e pg_safeguard=false          # 防误删保险，默认关闭，开启时需强制覆盖
    -e pg_rm_data=true             # 是否一并移除 PostgreSQL 数据目录，默认移除
    -e pg_rm_backup=true           # 是否一并移除 pgBackRest 备份（仅主库），默认移除
    -e pg_rm_pkg=true              # 是否卸载 PostgreSQL 软件包，默认卸载

包装脚本

bin/pgsql-rm pg-meta               # 移除 pgsql 集群 pg-meta
bin/pgsql-rm pg-test 10.10.10.13   # 从集群 pg-test 移除实例 10.10.10.13

任务列表

本剧本包含以下子任务：

# pg_safeguard           : 如果 pg_safeguard 启用则中止执行
#
# pg_monitor             : 从监控系统移除注册
#   - pg_deregister      : 从基础设施移除 pg 监控目标
#     - rm_metrics       : 从 VictoriaMetrics 目标目录移除监控目标
#     - rm_ds            : 从 grafana 移除数据源
#     - rm_logs          : 从 vector 移除日志目标
#   - pg_exporter        : 移除 pg_exporter
#   - pgbouncer_exporter : 移除 pgbouncer_exporter
#   - pgbackrest_exporter: 移除 pgbackrest_exporter
#
# pg_access              : 移除 pg 服务访问层
#   - dns                : 移除 pg DNS 记录
#   - vip                : 移除 vip-manager
#   - pg_service         : 从 haproxy 移除 pg 服务
#   - pgbouncer          : 移除 pgbouncer 连接中间件
#
# pg_crontab             : 移除 postgres dbsu 定时任务
#
# postgres               : 移除 postgres 实例
#   - pg_replica         : 移除所有从库
#   - pg_primary         : 移除主库
#   - pg_meta            : 从 etcd 移除元数据
#
# pg_backup              : 移除备份仓库（使用 pg_rm_backup=false 禁用）
# pg_data                : 移除 postgres 数据（使用 pg_rm_data=false 禁用）
# pg_pkg                 : 卸载 pg 软件包（默认启用；使用 pg_rm_pkg=false 禁用）
#   - pg_ext             : 单独卸载 postgres 扩展

以下管理任务使用到了此剧本

注意事项

  • 请不要直接对还有从库的集群主库单独执行此剧本，否则抹除主库后，其余从库会自动触发高可用自动故障切换。总是先下线所有从库后，再下线主库，当一次性下线整个集群时不需要操心此问题。
  • 实例下线后请刷新集群服务，当您从集群中下线掉某一个从库实例时，它仍然存留于在负载均衡器的配置文件中。因为健康检查无法通过，所以下线后的实例不会对集群产生影响。但您应当在恰当的时间点 重载服务，确保生产环境与配置清单的一致性。

pgsql-user.yml

剧本 pgsql-user.yml 用于在现有的 PostgreSQL 集群中添加新的业务用户。

基本用法

./pgsql-user.yml -l pg-meta -e username=dbuser_meta

包装脚本

bin/pgsql-user pg-meta dbuser_meta  # 在集群 pg-meta 上创建用户 dbuser_meta

工作流程

  1. 在配置清单中定义用户: all.children.<pg_cluster>.vars.pg_users[i]
  2. 执行剧本时指定集群和用户名: pgsql-user.yml -l <pg_cluster> -e username=<name>

剧本会：

  1. 在 /pg/tmp/pg-user-{{ user.name }}.sql 生成用户创建 SQL
  2. 在集群主库上执行用户创建/更新 SQL
  3. 若启用 pgbouncer_enabled: true，更新 /etc/pgbouncer/userlist.txt 与 useropts.txt
  4. 重载 pgbouncer 使配置生效

用户定义示例

pg_users:
  - name: dbuser_meta               # 必填，用户名是唯一必须的字段
    password: DBUser.Meta           # 可选，密码可以是 scram-sha-256 哈希或明文
    login: true                     # 可选，是否可登录，默认 true
    superuser: false                # 可选，是否超级用户，默认 false
    createdb: false                 # 可选，是否可创建数据库，默认 false
    createrole: false               # 可选，是否可创建角色，默认 false
    inherit: true                   # 可选，是否继承权限，默认 true
    replication: false              # 可选，是否可复制，默认 false
    bypassrls: false                # 可选，是否绕过 RLS，默认 false
    pgbouncer: true                 # 可选，是否添加到 pgbouncer 用户列表，默认 false
    connlimit: -1                   # 可选，连接数限制，-1 表示无限制
    expire_in: 3650                 # 可选，N 天后过期（覆盖 expire_at）
    expire_at: '2030-12-31'         # 可选，指定过期日期
    comment: pigsty admin user      # 可选，用户注释
    roles: [dbrole_admin]           # 可选，所属角色
    parameters: {}                  # 可选，角色级参数
    pool_mode: transaction          # 可选，pgbouncer 用户级连接池模式
    pool_connlimit: 100             # 可选，用户级最大连接数；省略时继承全局默认 100

详情请参考：管理SOP：创建用户

pgsql-db.yml

剧本 pgsql-db.yml 用于在现有的 PostgreSQL 集群中添加新的业务数据库。

基本用法

./pgsql-db.yml -l pg-meta -e dbname=meta

包装脚本

bin/pgsql-db pg-meta meta  # 在集群 pg-meta 上创建数据库 meta

工作流程

  1. 在配置清单中定义数据库: all.children.<pg_cluster>.vars.pg_databases[i]
  2. 执行剧本时指定集群和数据库名: pgsql-db.yml -l <pg_cluster> -e dbname=<name>

剧本会：

  1. 在 /pg/tmp/pg-db-{{ database.name }}.sql 生成数据库创建 SQL
  2. 在集群主库上执行数据库创建/更新 SQL
  3. 如果 db.register_datasource 为 true，将数据库注册为 grafana 数据源
  4. 更新 /etc/pgbouncer/database.txt 并重载 pgbouncer

数据库定义示例

pg_databases:
  - name: meta                      # 必填，数据库名是唯一必须的字段
    baseline: cmdb.sql              # 可选，数据库初始化 SQL 文件路径
    pgbouncer: true                 # 可选，是否添加到 pgbouncer，默认 true
    schemas: [pigsty]               # 可选，额外创建的 schema
    extensions:                     # 可选，要安装的扩展
      - { name: postgis, schema: public }
      - { name: timescaledb }
    comment: pigsty meta database   # 可选，数据库注释
    owner: postgres                 # 可选，数据库所有者
    template: template1             # 可选，模板数据库
    encoding: UTF8                  # 可选，字符编码
    locale: C                       # 可选，区域设置
    tablespace: pg_default          # 可选，默认表空间
    allowconn: true                 # 可选，是否允许连接
    revokeconn: false               # 可选，是否回收 public 连接权限
    register_datasource: true       # 可选，是否注册到 grafana 数据源
    connlimit: -1                   # 可选，连接数限制
    pool_auth_user: dbuser_meta     # 可选，认证查询使用的用户（配合 pgbouncer_auth_query）
    pool_mode: transaction          # 可选，pgbouncer 连接池模式
    pool_size: 50                   # 可选，pgbouncer 默认池大小
    pool_reserve: 30                # 可选，pgbouncer 保留池大小
    pool_size_min: 0                # 可选，pgbouncer 最小池大小
    pool_connlimit: 100             # 可选，pgbouncer 最大数据库连接数

详情请参考：管理SOP：创建数据库

pgsql-monitor.yml

剧本 pgsql-monitor.yml 用于将远程 PostgreSQL 实例纳入 Pigsty 监控体系。

基本用法

./pgsql-monitor.yml -e clsname=pg-foo  # 监控远程集群 pg-foo

包装脚本

bin/pgmon-add pg-foo              # 监控一个远程 pgsql 集群 pg-foo
bin/pgmon-add pg-foo pg-bar       # 同时监控多个集群

配置方式

首先需要在 infra 组变量中定义 pg_exporters：

infra:
  hosts:
    10.10.10.10:
      pg_exporters:  # 列出所有远程实例，分配唯一的未使用本地端口
        20001: { pg_cluster: pg-foo, pg_seq: 1, pg_host: 10.10.10.10 }
        20002: { pg_cluster: pg-foo, pg_seq: 2, pg_host: 10.10.10.11 }

架构示意

     ------ infra ------
     |                 |
     | victoria-metrics|            v---- pg-foo-1 ----v
     |       ^         |  metrics   |         ^        |
     |   pg_exporter <-|------------|----  postgres    |
     |   (port: 20001) |            | 10.10.10.10:5432 |
     |       ^         |            ^------------------^
     |       ^         |                      ^
     |       ^         |            v---- pg-foo-2 ----v
     |       ^         |  metrics   |         ^        |
     |   pg_exporter <-|------------|----  postgres    |
     |   (port: 20002) |            | 10.10.10.11:5433 |
     -------------------            ^------------------^

可配置参数

pg_exporter_config: pg_exporter.yml    # pg_exporter 配置文件名
pg_exporter_cache_ttls: '1,10,60,300'  # pg_exporter 采集器 TTL 阶段
pg_exporter_port: 9630                 # pg_exporter 监听端口
pg_exporter_params: 'sslmode=disable'  # DSN 额外 URL 参数
pg_exporter_url: ''                    # 直接覆盖自动生成的 DSN
pg_exporter_auto_discovery: true       # 是否启用自动数据库发现
pg_exporter_exclude_database: 'template0,template1,postgres'  # 排除的数据库
pg_exporter_include_database: ''       # 仅包含的数据库
pg_exporter_connect_timeout: 200       # 连接超时（毫秒）
pg_monitor_username: dbuser_monitor    # 监控用户名
pg_monitor_password: DBUser.Monitor    # 监控密码

远程数据库配置

远程 PostgreSQL 实例需要创建监控用户：

CREATE USER dbuser_monitor;
COMMENT ON ROLE dbuser_monitor IS 'system monitor user';
ALTER USER dbuser_monitor PASSWORD 'DBUser.Monitor';
GRANT pg_monitor TO dbuser_monitor;
CREATE EXTENSION IF NOT EXISTS "pg_stat_statements" WITH SCHEMA "monitor";

限制

  • 仅 postgres 指标可用
  • node、pgbouncer、patroni、haproxy 指标不可用

详情请参考：管理SOP：监控现有PG

pgsql-migration.yml

剧本 pgsql-migration.yml 用于为现有的 PostgreSQL 集群生成基于逻辑复制的零停机迁移手册和脚本。

基本用法

./pgsql-migration.yml -e@files/migration/pg-meta.yml

工作流程

  1. 定义迁移任务配置文件（如 files/migration/pg-meta.yml）
  2. 执行剧本生成迁移手册与脚本
  3. 按照手册逐步执行脚本完成迁移

迁移任务定义示例

# files/migration/pg-meta.yml
context_dir: ~/migration           # 迁移手册与脚本输出目录
src_cls: pg-meta                   # 源集群名称（必填）
src_db: meta                       # 源数据库名称（必填）
src_ip: 10.10.10.10                # 源集群主库 IP（必填）
dst_cls: pg-test                   # 目标集群名称（必填）
dst_db: test                       # 目标数据库名称（必填）
dst_ip: 10.10.10.11                # 目标集群主库 IP（必填）

# 可选参数
pg_dbsu: postgres
pg_replication_username: replicator
pg_replication_password: DBUser.Replicator
pg_admin_username: dbuser_dba
pg_admin_password: DBUser.DBA
pg_monitor_username: dbuser_monitor
pg_monitor_password: DBUser.Monitor

详情请参考：管理SOP：迁移数据库集群

pgsql-pitr.yml

剧本 pgsql-pitr.yml 用于执行 PostgreSQL 时间点恢复 (Point-In-Time Recovery)。

基本用法

# 恢复到最新状态（WAL 归档流末端）
./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": {}}'

# 恢复到指定时间点
./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": {"time": "2025-07-13 10:00:00+00"}}'

# 恢复到指定 LSN
./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": {"lsn": "0/4001C80"}}'

# 恢复到指定事务 ID
./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": {"xid": "250000"}}'

# 恢复到命名还原点
./pgsql-pitr.yml -l pg-meta -e '{"pg_pitr": {"name": "some_restore_point"}}'

# 从其他集群备份恢复
./pgsql-pitr.yml -l pg-test -e '{"pg_pitr": {"cluster": "pg-meta"}}'

PITR 任务参数

pg_pitr:                           # 定义 PITR 任务
  cluster: "pg-meta"               # 源集群名称（恢复其他集群的备份时使用）
  type: default                    # 恢复目标类型: default, time, xid, name, lsn, immediate
  time: "2025-01-01 10:00:00+00"   # 恢复目标：时间点
  name: "some_restore_point"       # 恢复目标：命名还原点
  xid: "100000"                    # 恢复目标：事务 ID
  lsn: "0/3000000"                 # 恢复目标：日志序列号
  set: latest                      # 从哪个备份集恢复，默认 latest
  timeline: latest                 # 目标时间线，可以是整数，默认 latest
  exclusive: false                 # 是否排除目标点，默认 false
  action: pause                    # 恢复后动作: pause, promote, shutdown
  archive: true                    # 是否保留归档设置，默认 true；探索性恢复可设为 false
  backup: false                    # 恢复前是否备份现有数据到 /pg/data-backup？默认 false
  db_include: []                   # 仅包含这些数据库
  db_exclude: []                   # 排除这些数据库
  link_map: {}                     # 表空间链接映射
  process: 4                       # 并行恢复进程数，默认使用 node_cpu
  repo: {}                         # 恢复源仓库配置
  data: /pg/data                   # 恢复数据目录
  port: 5432                       # 恢复实例监听端口

任务列表

本剧本包含以下子任务：

# down                 : 停止 HA 并关闭 patroni 和 postgres
#   - pause            : 暂停 patroni 自动故障转移
#   - stop             : 停止 patroni 和 postgres 服务
#     - stop_patroni   : 停止 patroni 服务
#     - stop_postgres  : 停止 postgres 服务
#
# pitr                 : 执行 PITR 恢复过程
#   - config           : 生成 pgbackrest 配置和恢复脚本
#   - backup           : 执行可选的原始数据备份
#   - restore          : 运行 pgbackrest restore 命令
#   - recovery         : 启动 postgres 并完成恢复
#   - verify           : 验证恢复的集群控制数据
#
# up                   : 启动 postgres/patroni 并恢复 HA
#   - etcd             : 启动前清理 etcd 元数据
#   - start            : 启动 patroni 和 postgres 服务
#     - start_postgres : 启动 postgres 服务
#     - start_patroni  : 启动 patroni 服务
#   - resume           : 恢复 patroni 自动故障转移

恢复目标类型说明

类型 说明 示例
default 恢复到 WAL 归档流末端（最新状态） {"pg_pitr": {}}
time 恢复到指定时间点 {"pg_pitr": {"time": "2025-07-13 10:00:00"}}
xid 恢复到指定事务 ID {"pg_pitr": {"xid": "250000"}}
name 恢复到命名还原点 {"pg_pitr": {"name": "before_ddl"}}
lsn 恢复到指定 LSN {"pg_pitr": {"lsn": "0/4001C80"}}
immediate 恢复到一致性状态后立即停止 {"pg_pitr": {"type": "immediate"}}

详情请参考：备份恢复教程

13 - 扩展插件

利用 PostgreSQL 扩展的协同超能力

Pigsty 提供 575 个已打包扩展，覆盖时序、地理、向量、全文检索、分析、特性增强等 16 大类别，开箱即用。

在 Pigsty 中使用扩展涉及四个核心步骤：下载、安装、配置/加载 与 启用。

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_databases:
      - name: meta
        extensions: [ postgis, timescaledb, vector ]   # 启用：在数据库中创建扩展
    pg_libs: 'timescaledb, pg_stat_statements, auto_explain' # 配置：预加载扩展库
    pg_extensions: [ postgis, timescaledb, pgvector ]  # 安装：安装扩展软件包
Pigsty PostgreSQL 扩展生态

13.1 - 快速开始

使用扩展的四步流程速览

在 Pigsty 中使用扩展需要四个步骤：下载、安装、配置、启用。

  1. 下载：将扩展软件包下载到本地仓库（默认本地仓库只保证基础内核与 pgsql-main 包集）
  2. 安装：在集群节点上安装扩展软件包
  3. 配置：部分扩展需要预加载或配置参数
  4. 启用：在数据库中执行 CREATE EXTENSION 创建扩展

声明式配置

在 Pigsty 配置清单中声明扩展，集群初始化时自动完成安装与启用：

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_databases:
      - name: meta
        extensions: [ postgis, timescaledb, vector ]   # 在数据库中启用扩展
    pg_libs: 'timescaledb, pg_stat_statements, auto_explain' # 预加载扩展库
    pg_extensions: [ postgis, timescaledb, pgvector ]  # 安装扩展软件包

执行 ./pgsql.yml 初始化集群后，postgis、timescaledb、vector 三个扩展即在 meta 数据库中可用。

命令式操作

对于已有集群，可以使用命令行方式添加扩展：

# 1. 安装扩展软件包
./pgsql.yml -l pg-meta -t pg_extension -e '{"pg_extensions":["pgvector"]}'

# 2. 预加载扩展（如需要，修改后需重启）
pg edit-config pg-meta --force -p shared_preload_libraries='timescaledb, pg_stat_statements, auto_explain'

# 3. 在数据库中启用扩展
psql -d meta -c 'CREATE EXTENSION vector;'

也可以使用 pig 包管理器安装扩展包，然后在数据库内执行 CREATE EXTENSION：

pig install pgvector                         # 安装扩展包
psql -d meta -c 'CREATE EXTENSION vector;'   # 在数据库中启用

流程速查

步骤 参数/命令 说明
下载 repo_extra_packages 指定下载到本地仓库的扩展包
安装 pg_extensions 指定集群要安装的扩展包
配置 pg_libs 预加载扩展到 shared_preload_libraries
启用 pg_databases.extensions 在数据库中自动执行 CREATE EXTENSION

详细说明请参阅各子章节：下载、安装、配置、启用

13.2 - 扩展简介

PostgreSQL 扩展的核心概念与 Pigsty 扩展生态

扩展是 PostgreSQL 的灵魂所在。Pigsty 收录了 575 个预编译、开箱即用的扩展插件，充分释放 PostgreSQL 的潜能。

扩展是什么

PostgreSQL 扩展（Extension）是一种模块化机制，允许在不修改核心代码的情况下增强数据库功能。 一个扩展通常包含三部分：

  • 控制文件（.control）：必需，包含扩展元数据
  • SQL 脚本（.sql）：可选，定义函数、类型、操作符等数据库对象
  • 动态库（.so）：可选，提供 C 语言实现的高性能功能

扩展可以为 PostgreSQL 添加：新数据类型、索引方法、函数与操作符、外部数据访问、过程语言、性能监控、安全审计等能力。

核心扩展

Pigsty 收录的扩展中，以下是最具代表性的：

扩展 说明
PostGIS 地理空间数据类型与索引，GIS 事实标准
TimescaleDB 时序数据库，支持持续聚合、列存储、自动压缩
PGVector 向量数据类型与 HNSW/IVFFlat 索引，AI 应用必备
Citus 分布式数据库，水平分片扩展能力
pg_duckdb 嵌入 DuckDB 分析引擎，OLAP 加速
pg_search ParadeDB 搜索扩展，提供 BM25 与全文检索能力
Apache AGE 图数据库，支持 OpenCypher 查询语言
pg_graphql 原生 GraphQL 查询支持

绝大多数扩展可以并存甚至组合使用，产生 1+1 远大于 2 的协同效应。

扩展类别

Pigsty 将扩展划分为 16 个类别：

类别 别名 说明 典型扩展
时序 time 时序数据处理 timescaledb, pg_cron, periods
地理 gis 地理空间数据 postgis, h3, pgrouting
向量 rag 向量检索与 AI pgvector, vchord, pg_vectorize
搜索 fts 全文检索 pgroonga, zhparser, pg_bigm
分析 olap OLAP 与分析 pg_duckdb, pg_mooncake, citus
特性 feat 功能增强 age, pg_graphql, hll, rum
语言 lang 过程语言 plpython3u, pljava, plv8
类型 type 数据类型 hstore, ltree, ip4r
工具 util 实用工具 http, pg_net, pgjwt
函数 func 函数库 pg_uuidv7, topn, tdigest
管理 admin 运维管理 pg_repack, pg_squeeze, pgagent
统计 stat 监控统计 pg_stat_statements, pg_qualstats, auto_explain
安全 sec 安全审计 pgaudit, pgsodium, pg_tde
外联 fdw 外部数据访问 postgres_fdw, mysql_fdw, oracle_fdw
兼容 sim 数据库兼容 orafce, babelfish
同步 etl 数据同步 pglogical, wal2json, decoderbufs

使用类别别名可以批量安装整个类别的扩展，例如 pg_extensions: [ pgsql-gis, pgsql-rag ]。

预定义扩展集

Pigsty 提供了若干预定义的扩展集（Stack），方便按场景选用：

扩展集 包含扩展
gis-stack postgis, pgrouting, pointcloud, h3, q3c, ogr_fdw
rag-stack pgvector, vchord, pgvectorscale, pg_similarity, pg_tiktoken
fts-stack pgroonga, pg_bigm, zhparser, hunspell
olap-stack pg_duckdb, pg_mooncake, timescaledb, pg_partman, plproxy
feat-stack age, hll, rum, pg_graphql, pg_jsonschema, jsquery
stat-stack pg_show_plans, pg_stat_kcache, pg_qualstats, pg_wait_sampling
supa-stack pg_graphql, pg_jsonschema, wrappers, pgvector, pgsodium, vault

在 pg_extensions 中直接使用这些名称即可安装整套扩展。

扩展资源

13.3 - 软件包

扩展包别名与类别命名规则

Pigsty 使用 包别名 机制简化扩展的安装与管理。

包别名机制

管理扩展涉及多个层面的名称映射：

层面 示例 pgvector 示例 postgis
扩展名 vector postgis, postgis_topology, …
包别名 pgvector postgis
RPM 包名 pgvector_18 postgis36_18*
DEB 包名 postgresql-18-pgvector postgresql-18-postgis-3*

Pigsty 提供 包别名 抽象层，让用户无需关心具体的 RPM/DEB 包名：

pg_extensions: [ pgvector, postgis, timescaledb ]  # 使用包别名

Pigsty 会根据操作系统和 PostgreSQL 版本自动翻译为正确的包名。

说明

CREATE EXTENSION 使用的是 扩展名（如 vector），而非包别名（pgvector）。

类别别名

所有扩展被划分为 16 个类别，可使用类别别名批量安装：

# 使用通用类别别名（自动适配当前 PG 版本）
pg_extensions: [ pgsql-gis, pgsql-rag, pgsql-fts ]

# 或使用版本特定的类别别名
pg_extensions: [ pg18-gis, pg18-rag, pg18-fts ]

除 olap 类别外，所有类别的扩展都可以同时安装。olap 类别中存在互斥：pg_duckdb 与 pg_mooncake 冲突。

类别列表

类别 说明 典型扩展
time 时序类 timescaledb, pg_cron, periods
gis 地理类 postgis, h3, pgrouting
rag 向量类 pgvector, pgml, vchord
fts 搜索类 pg_trgm, zhparser, pgroonga
olap 分析类 citus, pg_duckdb, pg_mooncake
feat 特性类 age, pg_graphql, rum
lang 语言类 plpython3u, pljava, plv8
type 类型类 hstore, ltree, citext
util 工具类 http, pg_net, pgjwt
func 函数类 pgcrypto, uuid-ossp, pg_uuidv7
admin 管理类 pg_repack, pgagent, pg_squeeze
stat 统计类 pg_stat_statements, pg_qualstats, auto_explain
sec 安全类 pgaudit, pgcrypto, pgsodium
fdw 外部类 postgres_fdw, mysql_fdw, oracle_fdw
sim 兼容类 orafce, babelfishpg_tds
etl 数据类 pglogical, wal2json, decoderbufs

查阅扩展目录

您可以在 Pigsty 扩展目录 网站上查阅所有可用扩展的详细信息，包括：

  • 扩展名称、描述、版本
  • 支持的 PostgreSQL 版本
  • 支持的操作系统发行版
  • 安装方式、预加载需求
  • 许可证、来源仓库

13.4 - 下载扩展

从软件仓库下载扩展包到本地

在安装扩展前，需要确保扩展软件包已下载到本地仓库或可从上游获取。

默认行为

Pigsty 默认会把基础 PostgreSQL 18 内核包下载到本地软件仓库。默认额外下载集为 repo_extra_packages_default: [ pgsql-main ]，包含 PostgreSQL 内核、客户端、过程语言，以及 pg_repack、wal2json、pgvector 等基础扩展包。

如果需要 575 个扩展目录中的其他扩展，请显式加入 repo_extra_packages；Pigsty 不会在默认安装时把全部扩展都下载到本地。

使用本地仓库的优势：

  • 加速安装，避免重复下载
  • 减少网络流量消耗
  • 提高交付可靠性
  • 确保版本一致性

下载新扩展

要下载额外的扩展，将其添加到 repo_extra_packages 并重建仓库：

all:
  vars:
    repo_extra_packages: [ pgvector, postgis, timescaledb, pg_duckdb ]
# 重新下载软件包到本地仓库
./infra.yml -t repo_build

# 刷新所有节点的软件源缓存
./node.yml -t node_repo

使用上游仓库

也可以直接从互联网上游仓库安装，无需预先下载：

# 在节点上添加上游软件源
./node.yml -t node_repo -e node_repo_modules=node,pgsql

这种方式适合：

  • 快速测试最新版本
  • 安装冷门扩展
  • 网络条件良好的环境

但可能面临：

  • 网络不稳定影响安装
  • 版本不一致风险

扩展来源

扩展软件包来自两个主要源：

仓库 说明
PGDG PostgreSQL 官方仓库，提供核心扩展
Pigsty Pigsty 补充仓库，提供额外扩展

Pigsty 仓库只收录 PGDG 仓库中不存在的扩展。一旦某扩展进入 PGDG 仓库，Pigsty 仓库会移除或与其保持一致。

仓库地址：

详细的仓库配置请参阅 扩展仓库。

13.5 - 安装扩展

在集群节点上安装扩展软件包

Pigsty 使用操作系统的包管理器（yum/apt）安装扩展软件包。

相关参数

两个参数用于指定要安装的扩展：

参数 用途 默认行为
pg_packages 全局通用软件包 确保存在（不升级）
pg_extensions 集群特定扩展 安装最新版本

pg_packages 通常用于指定所有集群都需要的基础组件（PostgreSQL 内核、Patroni、pgBouncer 等）和必选扩展。

pg_extensions 用于指定特定集群需要的扩展。

pg_packages:                           # 全局基础包
  - pgsql-main pgsql-common
pg_extensions:                         # 集群扩展
  - postgis timescaledb pgvector

集群初始化时安装

在集群配置中声明扩展，初始化时自动安装：

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_extensions: [ postgis, timescaledb, pgvector, pg_duckdb ]

执行 ./pgsql.yml 初始化集群时，扩展会自动安装。

已有集群安装扩展

对于已初始化的集群，有多种方式安装扩展：

使用 Pigsty 剧本 

# 修改配置后使用剧本安装
./pgsql.yml -l pg-meta -t pg_extension

# 或直接在命令行指定扩展
./pgsql.yml -l pg-meta -t pg_extension -e '{"pg_extensions":["pg_duckdb"]}'

使用 pig 包管理器 

# 使用 pig 安装扩展
pig install pg_duckdb

# 批量安装
ansible pg-meta -b -a 'pig install pg_duckdb pgvector'

直接使用包管理器 

# EL 系统
sudo yum install -y pg_duckdb_18*

# Debian/Ubuntu 系统
sudo apt install -y postgresql-18-pg-duckdb

使用包别名

Pigsty 支持使用标准化的包别名，自动翻译为对应 PG 版本的包名：

pg_extensions:
  - pgvector           # 自动翻译为 pgvector_18* (EL) 或 postgresql-18-pgvector (Debian)
  - postgis            # 自动翻译为 postgis36_18* (EL) 或 postgresql-18-postgis-3* (Debian)
  - pgsql-gis          # 类别别名，安装整个 GIS 类别的扩展

也可以直接使用原始包名：

pg_extensions:
  - pgvector_18*                    # EL 系统的原始包名
  - postgresql-18-pgvector          # Debian 系统的原始包名

包别名定义参见：

验证安装

安装后可在数据库中验证：

-- 查看已安装的扩展
SELECT * FROM pg_available_extensions WHERE name = 'vector';

-- 查看扩展文件是否存在
\dx

13.6 - 配置扩展

预加载扩展库与配置扩展参数

部分扩展需要预加载动态库或配置参数后才能使用，本节介绍如何配置扩展。

预加载扩展

大多数扩展安装后可直接使用 CREATE EXTENSION 启用，但部分使用 PostgreSQL Hook 机制的扩展需要 预加载。

预加载通过 shared_preload_libraries 参数指定，修改后需 重启数据库 生效。

需要预加载的扩展

以下是常见的需要预加载的扩展：

扩展 说明
timescaledb 时序数据库扩展，必须放在最前面
citus 分布式数据库扩展，必须放在最前面
pg_stat_statements SQL 语句统计，Pigsty 默认启用
auto_explain 自动记录慢查询执行计划，Pigsty 默认启用
pg_cron 定时任务调度
pg_net 异步 HTTP 请求
pg_tle 可信语言扩展
pgaudit 审计日志
pg_stat_kcache 内核统计信息
pg_squeeze 在线表空间回收
pgml PostgresML 机器学习

完整列表请参阅 扩展目录（带 LOAD 标记）。

预加载顺序

shared_preload_libraries 中扩展的加载顺序很重要：

  • timescaledb 和 citus 必须放在 最前面
  • 如果同时使用，citus 应在 timescaledb 之前
  • 统计类扩展应在 pg_stat_statements 之后，以使用相同的 query_id
pg_libs: 'citus, timescaledb, pg_stat_statements, auto_explain'

集群初始化时配置

在创建新集群时，使用 pg_libs 参数指定预加载的扩展：

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_libs: 'timescaledb, pg_stat_statements, auto_explain'
    pg_extensions: [ timescaledb, postgis, pgvector ]

pg_libs 的值将在集群初始化时写入 shared_preload_libraries。

默认值

pg_libs 的默认值是 pg_stat_statements, auto_explain，这两个 Contrib 扩展提供基本的可观测性：

  • pg_stat_statements：跟踪所有 SQL 语句的执行统计
  • auto_explain：自动记录慢查询的执行计划

已有集群修改配置

对于已初始化的集群，使用 patronictl 修改 shared_preload_libraries：

# 添加 timescaledb 到预加载库
pg edit-config pg-meta --force -p shared_preload_libraries='timescaledb, pg_stat_statements, auto_explain'

# 重启集群使配置生效
pg restart pg-meta

也可以直接修改 postgresql.conf 或使用 ALTER SYSTEM：

ALTER SYSTEM SET shared_preload_libraries = 'timescaledb, pg_stat_statements, auto_explain';

修改后需重启 PostgreSQL 服务生效。

扩展参数配置

许多扩展有可配置的参数，可以在以下位置设置：

集群初始化时

使用 pg_parameters 参数指定：

pg-meta:
  vars:
    pg_cluster: pg-meta
    pg_libs: 'pg_cron, pg_stat_statements, auto_explain'
    pg_parameters:
      cron.database_name: postgres           # pg_cron 使用的数据库
      pg_stat_statements.track: all          # 跟踪所有语句
      auto_explain.log_min_duration: 1000    # 记录超过 1 秒的查询

运行时修改

使用 ALTER SYSTEM 或 patronictl：

-- 修改参数
ALTER SYSTEM SET pg_stat_statements.track = 'all';

-- 重新加载配置
SELECT pg_reload_conf();
# 使用 patronictl 修改
pg edit-config pg-meta --force -p 'pg_stat_statements.track=all'

注意事项

  1. 预加载错误会阻止启动：如果 shared_preload_libraries 中的扩展不存在或加载失败，PostgreSQL 将无法启动。确保扩展已正确安装后再添加预加载。

  2. 修改需重启：shared_preload_libraries 的修改需要重启 PostgreSQL 服务才能生效。

  3. 部分功能可用：某些扩展在不预加载的情况下可以部分使用，但完整功能需要预加载。

  4. 查看当前配置：使用以下命令查看当前的预加载库：

SHOW shared_preload_libraries;

13.7 - 启用扩展

在数据库中创建和启用扩展

安装扩展软件包后，需要在数据库中执行 CREATE EXTENSION 才能使用扩展功能。

查看可用扩展

安装扩展软件包后，可以查看可用的扩展：

-- 查看所有可用扩展
SELECT * FROM pg_available_extensions;

-- 查看特定扩展
SELECT * FROM pg_available_extensions WHERE name = 'vector';

-- 查看已启用的扩展
SELECT * FROM pg_extension;

创建扩展

使用 CREATE EXTENSION 在数据库中启用扩展：

-- 创建扩展
CREATE EXTENSION vector;

-- 创建扩展到指定 Schema
CREATE EXTENSION postgis SCHEMA public;

-- 自动安装依赖的扩展
CREATE EXTENSION postgis_topology CASCADE;

-- 如果不存在则创建
CREATE EXTENSION IF NOT EXISTS vector;
说明

CREATE EXTENSION 使用的是 扩展名（如 vector），而非包别名（pgvector）。

集群初始化时启用

在 pg_databases 中声明扩展，集群初始化时自动创建：

pg-meta:
  vars:
    pg_cluster: pg-meta
    pg_databases:
      - name: meta
        extensions:
          - { name: vector }                         # 使用默认 Schema
          - { name: postgis, schema: public }        # 指定 Schema
          - { name: pg_stat_statements, schema: monitor }

Pigsty 会在数据库创建后自动执行 CREATE EXTENSION。

需要预加载的扩展

部分扩展需要先添加到 shared_preload_libraries 并重启后才能创建：

pg-meta:
  vars:
    pg_cluster: pg-meta
    pg_libs: 'timescaledb, pg_stat_statements, auto_explain'
    pg_databases:
      - name: meta
        extensions:
          - { name: timescaledb }  # 需要预加载

如果未预加载就尝试创建，会收到错误信息。

需要预加载的常见扩展：timescaledb, citus, pg_cron, pg_net, pgaudit 等。详见 配置扩展。

扩展依赖

某些扩展依赖于其他扩展，需要按顺序创建：

-- postgis_topology 依赖 postgis
CREATE EXTENSION postgis;
CREATE EXTENSION postgis_topology;

-- 或使用 CASCADE 自动安装依赖
CREATE EXTENSION postgis_topology CASCADE;

不需要创建的扩展

少数扩展不通过 SQL 接口对外服务，无需执行 CREATE EXTENSION：

扩展 说明
wal2json 逻辑解码插件，直接在复制槽中使用
decoderbufs 逻辑解码插件
decoder_raw 逻辑解码插件

这些扩展安装后即可使用，例如：

-- 使用 wal2json 创建逻辑复制槽
SELECT * FROM pg_create_logical_replication_slot('test_slot', 'wal2json');

查看扩展信息 

-- 查看扩展详情
\dx+ vector

-- 查看扩展包含的对象
SELECT * FROM pg_extension_config_dump('vector');

-- 查看扩展版本
SELECT extversion FROM pg_extension WHERE extname = 'vector';

13.8 - 更新扩展

升级 PostgreSQL 扩展版本

扩展更新涉及两个层面：软件包更新（操作系统层面）和 扩展对象更新（数据库层面）。

更新软件包

使用包管理器更新扩展的软件包：

# EL 系统
sudo yum update pgvector_18*

# Debian/Ubuntu 系统
sudo apt update && sudo apt upgrade postgresql-18-pgvector

使用 Pigsty 批量更新：

# 更新指定集群的扩展包
./pgsql.yml -l pg-meta -t pg_extension -e '{"pg_extensions":["pgvector"]}'

# 使用 pig 包管理器
pig update pgvector

更新扩展对象

软件包更新后，数据库中的扩展对象可能需要同步更新。

查看可更新的扩展 

-- 查看已安装扩展及其版本
SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE installed_version IS NOT NULL;

-- 查看可升级的扩展
SELECT name, installed_version, default_version
FROM pg_available_extensions
WHERE installed_version IS NOT NULL
  AND installed_version <> default_version;

执行扩展更新 

-- 更新到最新版本
ALTER EXTENSION pgvector UPDATE;

-- 更新到指定版本
ALTER EXTENSION pgvector UPDATE TO '0.8.0';

查看更新路径 

-- 查看扩展的可用升级路径
SELECT * FROM pg_extension_update_paths('pgvector');

注意事项

  1. 备份优先：更新扩展前建议先备份数据库，特别是涉及数据类型变更的扩展。

  2. 检查兼容性：某些扩展的大版本升级可能不兼容，需查阅扩展的升级文档。

  3. 预加载扩展：如果更新的是需要预加载的扩展（如 timescaledb），更新后可能需要重启数据库。

  4. 依赖关系：如果其他扩展依赖于被更新的扩展，需要按依赖顺序更新。

  5. 复制环境：在主从复制环境中，应先在从库测试更新，确认无误后再更新主库。

常见问题

更新失败

如果 ALTER EXTENSION UPDATE 失败，可能是因为：

  • 没有可用的升级路径
  • 扩展正在被使用
  • 权限不足
-- 查看扩展依赖
SELECT * FROM pg_depend WHERE refobjid = (SELECT oid FROM pg_extension WHERE extname = 'pgvector');

回滚更新

PostgreSQL 扩展通常不支持直接回滚。如需回滚：

  1. 从备份恢复
  2. 或者：卸载新版本扩展，安装旧版本软件包，重新创建扩展

13.9 - 移除扩展

卸载 PostgreSQL 扩展

移除扩展涉及两个层面：删除扩展对象（数据库层面）和 卸载软件包（操作系统层面）。

删除扩展对象

使用 DROP EXTENSION 从数据库中删除扩展：

-- 删除扩展
DROP EXTENSION pgvector;

-- 如果有依赖对象，需要级联删除
DROP EXTENSION pgvector CASCADE;

警告：CASCADE 会删除所有依赖于该扩展的对象（表、函数、视图等），请谨慎使用。

查看扩展依赖

删除前建议先检查依赖关系：

-- 查看依赖于某扩展的对象
SELECT
    classid::regclass,
    objid,
    deptype
FROM pg_depend
WHERE refobjid = (SELECT oid FROM pg_extension WHERE extname = 'pgvector');

-- 查看使用了扩展类型的表
SELECT
    c.relname AS table_name,
    a.attname AS column_name,
    t.typname AS type_name
FROM pg_attribute a
JOIN pg_class c ON a.attrelid = c.oid
JOIN pg_type t ON a.atttypid = t.oid
WHERE t.typname = 'vector';

移除预加载

如果扩展在 shared_preload_libraries 中，删除后需要从预加载列表移除：

# 修改 shared_preload_libraries，移除扩展
pg edit-config pg-meta --force -p shared_preload_libraries='pg_stat_statements, auto_explain'

# 重启使配置生效
pg restart pg-meta

卸载软件包

从数据库中删除扩展后，可以选择卸载软件包：

# EL 系统
sudo yum remove pgvector_18*

# Debian/Ubuntu 系统
sudo apt remove postgresql-18-pgvector

# 使用 pig 包管理器
pig remove pgvector

通常保留软件包不会有问题，仅在需要释放磁盘空间或解决冲突时才需要卸载。

注意事项

  1. 数据丢失风险：使用 CASCADE 会删除依赖对象，可能导致数据丢失。

  2. 应用兼容性：删除扩展前确保应用程序不再使用该扩展的功能。

  3. 预加载顺序：如果删除的是预加载扩展，务必同时从 shared_preload_libraries 中移除，否则数据库可能无法启动。

  4. 主从环境：在主从复制环境中，DROP EXTENSION 会自动复制到从库。

操作顺序

完整的扩展移除流程：

# 1. 检查依赖关系
psql -d mydb -c "SELECT * FROM pg_depend WHERE refobjid = (SELECT oid FROM pg_extension WHERE extname = 'pgvector');"

# 2. 删除数据库中的扩展
psql -d mydb -c "DROP EXTENSION pgvector;"

# 3. 如果是预加载扩展，从 shared_preload_libraries 移除
pg edit-config pg-meta --force -p shared_preload_libraries='pg_stat_statements, auto_explain'

# 4. 重启数据库（如果修改了预加载配置）
pg restart pg-meta

# 5. 可选：卸载软件包
sudo yum remove pgvector_18*

13.10 - 默认扩展

Pigsty 默认安装的 PostgreSQL 扩展

Pigsty 在初始化 PostgreSQL 集群时，会默认安装和启用一些核心扩展。

默认安装的扩展

通过 pg_packages 默认安装的扩展：

扩展 说明
pg_repack 在线处理表膨胀，重要的维护工具
wal2json 逻辑解码输出 JSON 格式变更，CDC 场景常用
pgvector 向量数据类型与索引，默认随 pgsql-main 安装

pg_extensions 的默认值为空数组 []。如需安装其他扩展，可以按需声明，例如：

扩展 说明
postgis 地理空间数据库扩展
timescaledb 时序数据库扩展
pgvector 向量数据类型与索引

默认启用的扩展

通过 pg_default_extensions 在所有数据库中默认启用的扩展：

扩展 Schema 说明
pg_stat_statements monitor SQL 语句执行统计
pgstattuple monitor 元组级统计信息
pg_buffercache monitor 缓冲区缓存检查
pageinspect monitor 页面级检查
pg_prewarm monitor 关系预热
pg_visibility monitor 可见性映射检查
pg_freespacemap monitor 空闲空间映射检查
postgres_fdw public PostgreSQL 外部数据包装器
file_fdw public 文件外部数据包装器
btree_gist public B-tree GiST 操作符类
btree_gin public B-tree GIN 操作符类
pg_trgm public 三元组匹配
intagg public 整数聚合器
intarray public 整数数组函数
pg_repack repack 在线重组表

这些扩展提供基础的监控、运维和功能增强能力。

默认预加载的扩展

通过 pg_libs 默认预加载到 shared_preload_libraries 的扩展：

扩展 说明
pg_stat_statements 跟踪所有 SQL 语句的执行统计
auto_explain 自动记录慢查询的执行计划

这两个扩展提供基本的可观测性，强烈建议保留。

自定义默认扩展

可以通过修改配置参数来自定义默认安装和启用的扩展：

all:
  vars:
    # 修改默认安装的扩展包
    pg_packages:
      - pgsql-main pgsql-common
      - pg_repack_$v* wal2json_$v*

    # 修改默认安装的扩展
    pg_extensions: [ postgis, timescaledb, pgvector ]

    # 修改默认预加载的扩展
    pg_libs: 'timescaledb, pg_stat_statements, auto_explain'

    # 修改默认启用的扩展
    pg_default_extensions:
      - { name: pg_stat_statements, schema: monitor }
      - { name: pg_repack }
      # ... 添加更多

详细的扩展使用方法请参阅：

13.11 - 扩展仓库

Pigsty 扩展软件仓库配置

Pigsty 提供补充扩展仓库，在 PGDG 官方仓库基础上提供额外的扩展包。

YUM 仓库

适用于 EL 8/9/10 及其兼容系统（RHEL、Rocky、AlmaLinux、CentOS 等）。

添加仓库 

# 添加 GPG 公钥
curl -fsSL https://repo.pigsty.io/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null

# 添加仓库配置
curl -fsSL https://repo.pigsty.io/yum/repo | sudo tee /etc/yum.repos.d/pigsty.repo >/dev/null

# 刷新缓存
sudo yum makecache

中国大陆镜像 

curl -fsSL https://repo.pigsty.cc/key | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-pigsty >/dev/null
curl -fsSL https://repo.pigsty.cc/yum/repo | sudo tee /etc/yum.repos.d/pigsty.repo >/dev/null

仓库地址

APT 仓库

适用于 Debian 12/13 和 Ubuntu 22.04/24.04/26.04 及其兼容系统。

添加仓库 

# 添加 GPG 公钥
curl -fsSL https://repo.pigsty.io/key | sudo gpg --dearmor -o /etc/apt/keyrings/pigsty.gpg

# 获取发行版代号并添加仓库
distro_codename=$(lsb_release -cs)
sudo tee /etc/apt/sources.list.d/pigsty.list > /dev/null <<EOF
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.io/apt/infra generic main
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.io/apt/pgsql/${distro_codename} ${distro_codename} main
EOF

# 刷新缓存
sudo apt update

中国大陆镜像 

curl -fsSL https://repo.pigsty.cc/key | sudo gpg --dearmor -o /etc/apt/keyrings/pigsty.gpg

distro_codename=$(lsb_release -cs)
sudo tee /etc/apt/sources.list.d/pigsty.list > /dev/null <<EOF
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.cc/apt/infra generic main
deb [signed-by=/etc/apt/keyrings/pigsty.gpg] https://repo.pigsty.cc/apt/pgsql/${distro_codename} ${distro_codename} main
EOF

仓库地址

GPG 签名

所有软件包均使用 GPG 签名：

  • 指纹: 9592A7BC7A682E7333376E09E7935D8DB9BD8B20
  • 短 ID: B9BD8B20

仓库策略

Pigsty 仓库遵循以下原则：

  1. 补充性：只收录 PGDG 仓库中不存在的扩展
  2. 一致性：扩展进入 PGDG 仓库后，Pigsty 仓库会移除或保持一致
  3. 兼容性：支持 PostgreSQL 14-18 多个大版本
  4. 多平台：支持 x86_64 和 aarch64 架构

相关资源

14 - 内核分支

如何在 Pigsty 中使用其他 PostgreSQL 内核分支？例如 Citus，Babelfish，IvorySQL，PolarDB 等

在 Pigsty 中，您可以使用不同 “风味” 的 PostgreSQL 分支替换 “原生 PG 内核”，实现特殊的功能与效果。

Pigsty 支持多种 PostgreSQL 内核和兼容分支，让您能够在同一套运维体系中获得兼容性、多主复制、图查询、MPP 数仓、透明加密等不同能力。

需要注意的是，不同内核在 Pigsty 中的交付深度并不完全一致： 像 PostgreSQL、Citus、Babelfish、IvorySQL、PolarDB、AgensGraph、pgEdge 已经有较明确的模板与配置方式； 像 Cloudberry / Greenplum 则更多通过 gpsql 模式统一纳管，MPP 初始化与扩缩容仍建议使用上游工具链。

内核 关键特性 描述
PostgreSQL 原生内核，扩展齐备 原版 PostgreSQL，配备 575 扩展
Supabase 后端即服务 基于 PostgreSQL 的 BaaS，Firebase 替代方案
Citus 水平分布式扩展，多租户 通过原生扩展实现分布式 PostgreSQL
Babelfish SQL Server 兼容 SQL Server 线协议兼容（PG17/18）
IvorySQL Oracle 兼容 Oracle 语法和 PL/SQL 兼容
OpenHalo MySQL 兼容 MySQL 线协议兼容
Percona 透明数据加密 带有 pg_tde 的 Percona 发行版
DocumentDB MongoDB 迁移 DocumentDB + FerretDB，兼容 MongoDB 线协议
OrioleDB OLTP 优化 Zheap，无膨胀，S3 存储
PolarDB Aurora 风格 RAC RAC，中国国产合规
Cloudberry 开源 MPP 数仓 以 gpsql 模式接入的 Cloudberry 分支
AgensGraph 属性图 + Cypher 在 PostgreSQL 体系内提供图查询能力
pgEdge Spock 多主复制 面向边缘场景的分布式 PostgreSQL 发行版
PostgreSQL 分支与兼容内核

版本

内核 Debian / Ubuntu EL
PostgreSQL / Citus PostgreSQL 18.6 (Ubuntu 18.6-1.pgdg26.04+1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 15.2.0-16ubuntu1) 15.2.0, 64-bit PostgreSQL 18.6 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.3.1 20251022 (Red Hat 14.3.1-4), 64-bit
IvorySQL PostgreSQL 18.4 (IvorySQL 5.4) on x86_64-pc-linux-gnu, compiled by gcc (GCC) 9.5.0, 64-bit PostgreSQL 18.4 (IvorySQL 5.4) on x86_64-pc-linux-gnu, compiled by gcc (GCC) 9.5.0, 64-bit
Babelfish Babelfish 17.7 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 15.2.0-16ubuntu1) 15.2.0, 64-bit Babelfish 17.7 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.3.1 20251022 (Red Hat 14.3.1-4), 64-bit
PolarDB PostgreSQL 17.10 (PolarDB 17.10.1.0 build accf02e2) on x86_64-linux-gnu PostgreSQL 17.10 (PolarDB 17.10.1.0 build accf02e2) on x86_64-linux-gnu
Percona PostgreSQL 18.4 - Percona Server for PostgreSQL 18.4.1 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 15.2.0-16ubuntu1) 15.2.0, 64-bit PostgreSQL 18.4 - Percona Server for PostgreSQL 18.4.1 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.3.1 20250617 (Red Hat 14.3.1-2), 64-bit
OrioleDB OrioleDB 18.4 (OrioleDB 1.8-beta16) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 15.2.0-16ubuntu1) 15.2.0, 64-bit OrioleDB 18.4 (OrioleDB 1.8-beta16) on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.3.1 20251022 (Red Hat 14.3.1-4), 64-bit
OpenHalo openHalo 14.18 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 15.2.0-16ubuntu1) 15.2.0, 64-bit openHalo 14.18 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.3.1 20251022 (Red Hat 14.3.1-4), 64-bit
DocumentDB PostgreSQL 18.6 (Ubuntu 18.6-1.pgdg26.04+1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 15.2.0-16ubuntu1) 15.2.0, 64-bit PostgreSQL 18.6 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.3.1 20251022 (Red Hat 14.3.1-4), 64-bit
AgensGraph PostgreSQL 17.10 (AgensGraph 2.17.0) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 15.2.0-16ubuntu1) 15.2.0, 64-bit PostgreSQL 17.10 (AgensGraph 2.17.0) on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.3.1 20251022 (Red Hat 14.3.1-4), 64-bit
pgEdge PostgreSQL 18.4 (pgEdge 5.0.10) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 15.2.0-16ubuntu1) 15.2.0, 64-bit PostgreSQL 18.4 (pgEdge 5.0.10) on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.3.1 20251022 (Red Hat 14.3.1-4), 64-bit
Cloudberry PostgreSQL 14.4 (Apache Cloudberry 2.0.0-incubating build 1) on aarch64-unknown-linux-gnu, compiled by gcc (GCC) 11.5.0 20240719 (Red Hat 11.5.0-11), 64-bit

14.1 - PostgreSQL

带有 575 个扩展的原版 PostgreSQL 内核

PostgreSQL 是世界上最先进和最受欢迎的开源数据库。

默认安装 PostgreSQL 18，支持 PostgreSQL 14 ~ 18，并提供 575 个 PG 扩展。

快速开始

使用 pgsql 配置模板 安装 Pigsty。

./configure -c pgsql     # 使用 postgres 内核
./deploy.yml             # 部署 Pigsty 核心链路与原生 PostgreSQL

大多数 配置模板 默认使用 PostgreSQL 内核，例如：

  • meta : 默认，带有核心扩展（vector、postgis、timescale）的 postgres
  • rich：安装了所有扩展的 postgres
  • slim：仅 postgres，无监控基础设施
  • ha/full：用于 HA 演示的 4 节点沙盒
  • pgsql：最小的 postgres 内核配置示例

配置

原版 PostgreSQL 内核不需要特殊调整：

pg-meta:
  hosts:
    10.10.10.10: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-meta
    pg_users:
      - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
      - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer  }
    pg_databases:
      - { name: meta, baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [ vector ]}
    pg_hba_rules:
      - { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes' }
    pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ] # 每天凌晨 1 点进行全量备份
    pg_packages: [ pgsql-main, pgsql-common ]   # pg 内核和通用工具
    #pg_extensions: [ pg18-time ,pg18-gis ,pg18-rag ,pg18-fts ,pg18-olap ,pg18-feat ,pg18-lang ,pg18-type ,pg18-util ,pg18-func ,pg18-admin ,pg18-stat ,pg18-sec ,pg18-fdw ,pg18-sim ,pg18-etl]

版本选择

要使用不同的 PostgreSQL 主版本，您可以使用 -v 参数进行配置：

./configure -c pgsql            # 默认就是 postgresql 18，无需显式指定
./configure -c pgsql -v 18      # 显式指定 postgresql 18
./configure -c pgsql -v 17      # 使用 postgresql 17
./configure -c pgsql -v 16      # 使用 postgresql 16
./configure -c pgsql -v 15      # 使用 postgresql 15
./configure -c pgsql -v 14      # 使用 postgresql 14

如果 PostgreSQL 集群已经安装，您需要在安装新版本之前卸载它：

./pgsql-rm.yml -l pg-meta # 卸载 pg-meta 集群

扩展生态

Pigsty 为 PostgreSQL 提供了丰富的扩展生态，详情请参考 扩展目录。

14.2 - Supabase

如何使用 Pigsty 自建 Supabase，一键拉起开源 Firebase 替代，后端全栈全家桶。

Supabase —— Build in a weekend, Scale to millions

Supabase 是一个开源的 Firebase 替代，对 PostgreSQL 进行了封装，并提供了认证，开箱即用的 API，边缘函数，实时订阅，对象存储，向量嵌入能力。 这是一个低代码的一站式后端平台，能让你几乎告别大部分后端开发的工作，只需要懂数据库设计与前端即可快速出活！

Supabase 的口号是：“花个周末写写，随便扩容至百万”。诚然，在小微规模（4c8g）内的 Supabase 极有性价比，堪称赛博菩萨。 —— 但当你真的增长到百万用户时 —— 确实应该认真考虑托管自建 Supabase 了 —— 无论是出于功能，性能，还是成本上的考虑。

Pigsty 为您提供完整的 Supabase 一键自建方案。自建的 Supabase 可以享受完整的 PostgreSQL 监控，IaC，PITR 与高可用， 而且相比 Supabase 云服务，提供了多达 575 个开箱即用的 PostgreSQL 扩展，并能够更充分地利用现代硬件的性能与成本优势。

完整自建教程，请参考：《Supabase自建手册》

Supabase

快速上手

Pigsty 默认提供的 supabase.yml 配置模板定义了一套单节点 Supabase。

首先，使用 Pigsty 标准安装流程 安装 Supabase 所需的 Silo 与 PostgreSQL 实例：

 curl -fsSL https://repo.pigsty.io/get | bash
./bootstrap          # 环境检查，安装依赖
./configure -c supabase  # 重要：请在配置文件中修改密码等关键信息！
./deploy.yml         # 安装 Pigsty，拉起 PGSQL 与 MINIO！

请在部署 Supabase 前，根据您的实际情况，修改 pigsty.yml 配置文件中 关于 Supabase 的参数（主要是密码！）

然后使用当前仓库根目录的 docker.yml 与 app.yml 完成剩余工作，安装容器运行时并拉起 conf/supabase.yml 中定义的 Supabase 应用：

./docker.yml       # 安装 Docker 模块
./app.yml          # 拉起 Supabase 无状态部分！

中国区域用户注意，请您配置合适的 Docker 镜像站点或代理服务器绕过 GFW 以拉取 DockerHub 镜像。 对于 专业订阅，我们提供在没有互联网访问的情况下，离线安装 Pigsty 与 Supabase 的能力。

Pigsty 默认通过管理节点/INFRA 节点上的 Nginx 对外暴露 Web 服务，您可以在本地添加 supa.pigsty 的 DNS 解析指向该节点， 然后通过浏览器访问 https://supa.pigsty 即可进入 Supabase Studio 管理界面。

默认用户名与密码：supabase / pigsty

demo/supabase.cast

配置细节

./configure -c supabase 会生成 ~/pigsty/pigsty.yml。在执行 ./deploy.yml 之前，请至少检查并修改其中的密码、密钥、域名等敏感配置。

更完整的配置说明请参阅：《Supabase自建手册》。

14.3 - Citus

使用 Pigsty 部署原生高可用的 Citus 水平分片集群，将 PostgreSQL 无缝伸缩到多套分片并加速 OLTP/OLAP 查询。

Pigsty 原生支持 Citus。这是一个基于原生 PostgreSQL 内核的分布式水平扩展插件。

Citus

安装

Citus 是一个 PostgreSQL 扩展插件，可以按照标准插件安装的流程，在原生 PostgreSQL 集群上加装启用。

./pgsql.yml -t pg_extension -e '{"pg_extensions":["citus"]}'

配置

要定义一个 citus 集群，您需要指定以下参数：

  • pg_mode 必须设置为 citus，而不是默认的 pgsql
  • 在每个分片集群上都必须定义分片名 pg_shard 和分片号 pg_group
  • 必须定义 pg_primary_db 来指定由 Patroni 管理的 Citus 数据库。
  • 如果您想使用 pg_dbsu 的 postgres 而不是默认的 pg_admin_username 来执行管理命令，那么 pg_dbsu_password 必须设置为非空的纯文本密码

此外，还需要额外的 hba 规则，允许从本地和其他数据节点进行 SSL 访问。

您可以将每个 Citus 集群分别定义为独立的分组，像标准的 PostgreSQL 集群一样；当前完整模板见 conf/ha/citus.yml：

all:
  children:
    pg-citus0: # citus 0号分片
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus0 , pg_group: 0 }
    pg-citus1: # citus 1号分片
      hosts: { 10.10.10.11: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus1 , pg_group: 1 }
    pg-citus2: # citus 2号分片
      hosts: { 10.10.10.12: { pg_seq: 1, pg_role: primary } }
      vars: { pg_cluster: pg-citus2 , pg_group: 2 }
    pg-citus3: # citus 3号分片
      hosts:
        10.10.10.13: { pg_seq: 1, pg_role: primary }
        10.10.10.14: { pg_seq: 2, pg_role: replica }
      vars: { pg_cluster: pg-citus3 , pg_group: 3 }
  vars:                               # 所有 Citus 集群的全局参数
    pg_mode: citus                    # pgsql 集群模式需要设置为： citus
    pg_shard: pg-citus                # citus 水平分片名称： pg-citus
    pg_primary_db: meta               # citus 数据库名称：meta
    pg_dbsu_password: DBUser.Postgres # 如果使用 dbsu ，那么需要为其配置一个密码
    pg_users: [ { name: dbuser_meta ,password: DBUser.Meta ,pgbouncer: true ,roles: [ dbrole_admin ] } ]
    pg_databases: [ { name: meta ,extensions: [ { name: citus }, { name: postgis }, { name: timescaledb } ] } ]
    pg_hba_rules:
      - { user: 'all' ,db: all  ,addr: 127.0.0.1/32 ,auth: ssl ,title: 'all user ssl access from localhost' }
      - { user: 'all' ,db: all  ,addr: intra        ,auth: ssl ,title: 'all user ssl access from intranet'  }

您也可以在一个分组内指定所有 Citus 集群成员的身份参数，如 conf/ha/citus.yml 所示：

#==========================================================#
# pg-citus: 10 node citus cluster (5 x primary-replica pair)
#==========================================================#
pg-citus: # citus group
  hosts:
    10.10.10.50: { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.60/24 ,pg_seq: 0, pg_role: primary }
    10.10.10.51: { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.60/24 ,pg_seq: 1, pg_role: replica }
    10.10.10.52: { pg_group: 1, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.61/24 ,pg_seq: 0, pg_role: primary }
    10.10.10.53: { pg_group: 1, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.61/24 ,pg_seq: 1, pg_role: replica }
    10.10.10.54: { pg_group: 2, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.62/24 ,pg_seq: 0, pg_role: primary }
    10.10.10.55: { pg_group: 2, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.62/24 ,pg_seq: 1, pg_role: replica }
    10.10.10.56: { pg_group: 3, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.63/24 ,pg_seq: 0, pg_role: primary }
    10.10.10.57: { pg_group: 3, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.63/24 ,pg_seq: 1, pg_role: replica }
    10.10.10.58: { pg_group: 4, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.64/24 ,pg_seq: 0, pg_role: primary }
    10.10.10.59: { pg_group: 4, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.64/24 ,pg_seq: 1, pg_role: replica }
  vars:
    pg_mode: citus                    # pgsql cluster mode: citus
    pg_shard: pg-citus                # citus shard name: pg-citus
    pg_primary_db: test               # primary database used by citus
    pg_dbsu_password: DBUser.Postgres # all dbsu password access for citus cluster
    pg_vip_enabled: true
    pg_vip_interface: auto
    pg_extensions: [ 'citus postgis timescaledb pgvector' ]
    pg_libs: 'citus, timescaledb, pg_stat_statements, auto_explain' # citus will be added by patroni automatically
    pg_users: [ { name: test ,password: test ,pgbouncer: true ,roles: [ dbrole_admin ] } ]
    pg_databases: [ { name: test ,owner: test ,extensions: [ { name: citus }, { name: postgis } ] } ]
    pg_hba_rules:
      - { user: 'all' ,db: all  ,addr: 10.10.10.0/24 ,auth: trust ,title: 'trust citus cluster members'        }
      - { user: 'all' ,db: all  ,addr: 127.0.0.1/32  ,auth: ssl   ,title: 'all user ssl access from localhost' }
      - { user: 'all' ,db: all  ,addr: intra         ,auth: ssl   ,title: 'all user ssl access from intranet'  }

使用

您可以像访问普通集群一样，访问任意节点：

pgbench -i postgres://test:test@pg-citus0/test
pgbench -nv -P1 -T1000 -c 2 postgres://test:test@pg-citus0/test

默认情况下，您对某一个 Shard 进行的变更，都只发生在这套集群上，而不会同步到其他 Shard。

如果你希望将写入分布到所有 Shard，可以使用 Citus 提供的 API 函数，将表标记为：

  • 水平分片表（自动分区，需要指定分区键）
  • 引用表（全量复制：不需要指定分区键）：

从 Citus 11.2 开始，任何 Citus 数据库节点都可以扮演协调者的角色，即，任意一个主节点都可以写入：

psql -h pg-citus0 -d test -c "SELECT create_distributed_table('pgbench_accounts', 'aid'); SELECT truncate_local_data_after_distributing_table('public.pgbench_accounts');"
psql -h pg-citus0 -d test -c "SELECT create_reference_table('pgbench_branches')         ; SELECT truncate_local_data_after_distributing_table('public.pgbench_branches');"
psql -h pg-citus0 -d test -c "SELECT create_reference_table('pgbench_history')          ; SELECT truncate_local_data_after_distributing_table('public.pgbench_history');"
psql -h pg-citus0 -d test -c "SELECT create_reference_table('pgbench_tellers')          ; SELECT truncate_local_data_after_distributing_table('public.pgbench_tellers');"

将表分布出去后，你可以在其他节点上也访问到：

psql -h pg-citus1 -d test -c '\dt+'

例如，全表扫描可以发现执行计划已经变为分布式计划

vagrant@meta-1:~$ psql -h pg-citus3 -d test -c 'explain select * from pgbench_accounts'
                                               QUERY PLAN
---------------------------------------------------------------------------------------------------------
 Custom Scan (Citus Adaptive)  (cost=0.00..0.00 rows=100000 width=352)
   Task Count: 32
   Tasks Shown: One of 32
   ->  Task
         Node: host=10.10.10.52 port=5432 dbname=test
         ->  Seq Scan on pgbench_accounts_102008 pgbench_accounts  (cost=0.00..81.66 rows=3066 width=97)
(6 rows)

你可以从几个不同的主节点发起写入：

pgbench -nv -P1 -T1000 -c 2 postgres://test:test@pg-citus1/test
pgbench -nv -P1 -T1000 -c 2 postgres://test:test@pg-citus2/test
pgbench -nv -P1 -T1000 -c 2 postgres://test:test@pg-citus3/test
pgbench -nv -P1 -T1000 -c 2 postgres://test:test@pg-citus4/test

当某个节点出现故障时，Patroni 提供的原生高可用支持会将备用节点提升并自动顶上。

test=# select * from  pg_dist_node;
 nodeid | groupid |  nodename   | nodeport | noderack | hasmetadata | isactive | noderole | nodecluster | metadatasynced | shouldhaveshards
--------+---------+-------------+----------+----------+-------------+----------+----------+-------------+----------------+------------------
      1 |       0 | 10.10.10.51 |     5432 | default  | t           | t        | primary  | default     | t              | f
      2 |       2 | 10.10.10.54 |     5432 | default  | t           | t        | primary  | default     | t              | t
      5 |       1 | 10.10.10.52 |     5432 | default  | t           | t        | primary  | default     | t              | t
      3 |       4 | 10.10.10.58 |     5432 | default  | t           | t        | primary  | default     | t              | t
      4 |       3 | 10.10.10.56 |     5432 | default  | t           | t        | primary  | default     | t              | t

14.4 - Babelfish

在 Pigsty 中使用 Babelfish（PG17/18）提供 SQL Server 协议/T-SQL 兼容能力

Babelfish 是一个提供 MS SQL Server 线缆协议兼容性的内核分支 + 扩展，由 AWS 开源。

概览

Pigsty 允许您使用 mssql 模式部署 Babelfish 内核，在 PostgreSQL 上提供：

  • SQL Server 线缆协议兼容（TDS 协议，1433 端口）
  • T-SQL 语法兼容
  • 与 Pigsty 现有能力（高可用、备份、监控、IaC）统一集成

在 Pigsty v4 中，Babelfish 支持 PostgreSQL 17/18，默认模板使用 pg_version: 17，并已经纳入 Pigsty 标准交付链路。支持所有 Linux 平台。

快速开始

使用 Pigsty 内置模板：

./configure -c mssql [-v 17/18]
./deploy.yml

部署完成后可直接使用 SQL Server 客户端连接：

sqlcmd -S <ip>,1433 -U dbuser_mssql -P DBUser.MSSQL -d mssql

关键配置

mssql 模板中的核心参数如下：

pg_mode: mssql
pg_version: 17  # optional: 18
pg_packages: [ babelfish, pgsql-common, sqlcmd ]
pg_libs: 'babelfishpg_tds, pg_stat_statements, auto_explain'

pg_databases:
  - name: mssql
    baseline: mssql.sql
    extensions:
      - { name: uuid-ossp }
      - { name: babelfishpg_common }
      - { name: babelfishpg_tsql }
      - { name: babelfishpg_tds }
      - { name: babelfishpg_money }
      - { name: pg_hint_plan }
      - { name: system_stats }
      - { name: tds_fdw }
    parameters: { 'babelfishpg_tsql.migration_mode': 'multi-db' }

pg_hba_rules:
  - { user: dbuser_mssql, db: mssql, addr: intra, auth: md5, order: 525 }

pg_default_services:
  - { name: primary, port: 5433, dest: 1433 }
  - { name: replica, port: 5434, dest: 1433 }

连接与端口

Babelfish 集群会同时提供两类访问：

  • PostgreSQL 协议：5432
  • SQL Server 协议（TDS）：1433

通过 Pigsty 服务抽象，还可使用：

  • 5433 固定路由到主库 1433
  • 5434 路由到可读节点 1433
# 主库写入
sqlcmd -S <任意节点IP>,5433 -U dbuser_mssql -P DBUser.MSSQL

# 读库查询
sqlcmd -S <任意节点IP>,5434 -U dbuser_mssql -P DBUser.MSSQL

注意事项

  • Babelfish 认证规则需使用 md5，而不是默认 scram-sha-256。
  • 默认迁移模式为 multi-db，如需 single-db 可修改 babelfishpg_tsql.migration_mode。
  • 并非所有原生 PostgreSQL 扩展都可直接在 Babelfish 内核使用；请以包可用性与兼容性测试为准。
  • 生产环境请收紧 HBA 与网络暴露策略，不要沿用演示级开放配置。

相关文档

可用扩展

Babelfish 内核共有 55 个可用扩展，去除 PG Contrib 自带扩展之后，还有以下额外扩展：

扩展名 版本号 说明
babelfishpg_common 5.4.0 Transact SQL Datatype Support
babelfishpg_money 1.1.0 babelfishpg_money
babelfishpg_tds 1.0.0 TDS protocol extension
babelfishpg_tsql 5.4.0 Transact SQL compatibility

14.5 - IvorySQL

使用瀚高开源的 IvorySQL 内核，基于 PostgreSQL 集群实现 Oracle 语法/PLSQL 兼容性。

IvorySQL 是一个开源的，旨在基于 PG 提供 “Oracle 兼容性” 的 PostgreSQL 内核分支。

概览

Pigsty PGSQL 仓库直接提供 IvorySQL 5.4 软件包，兼容 PostgreSQL 18.4，并覆盖当前支持的 EL、Debian、Ubuntu 与双架构平台。 在线安装使用 Pigsty 的 pgsql 仓库；商业版同时提供对应平台的离线交付方案。

IvorySQL

当前 Pigsty 的 ivorysql 包别名指向 IvorySQL 5，兼容 PostgreSQL 18。不同发行版的真实包名由 roles/node_id/vars/ 中的平台变量映射，例如 EL 使用 ivorysql5，Debian/Ubuntu 使用 ivorysql-5。

最后一个支持 EL7 的 IvorySQL 版本为 3.3，对应 PostgreSQL 16.3；最后一个基于 PostgreSQL 17 的版本为 IvorySQL 4.4

安装

使用 Pigsty 内置的 ivory 配置模板安装：

./configure -c ivory
./deploy.yml

配置

以下参数需要针对 IvorySQL 数据库集群进行配置：

#----------------------------------#
# Ivory SQL Configuration
#----------------------------------#
node_repo_modules: node,infra,pgsql       # use Pigsty node/infra/pgsql repos
pg_mode: ivory                    # IvorySQL Oracle Compatible Mode
pg_packages: [ ivorysql, pgsql-common ]
pg_libs: 'liboracle_parser, pg_stat_statements, auto_explain'
pg_extensions: [ ]                # do not install any vanilla postgresql extensions

使用 Oracle 兼容性模式时，需要动态加载 liboracle_parser 扩展插件。

客户端访问

IvorySQL 5 等效于 PostgreSQL 18，任何兼容 PostgreSQL 线缆协议的客户端工具都可以访问 IvorySQL 集群。

可用扩展

IvorySQL 内核共有 95 个可用扩展，去除 PG Contrib 自带扩展之后，还有以下额外扩展：

扩展名 版本号 说明
address_standardizer 3.5.4 Used to parse an address into constituent elements. Generally used to support geocoding address normalization step.
address_standardizer_data_us 3.5.4 Address Standardizer US dataset example
age 1.7.0 AGE database extension
ddlx 0.31 DDL eXtractor functions
gb18030_2022 1.0 support gb18030 2022 with extension
http 1.7 HTTP client for PostgreSQL, allows web page retrieval inside the database.
ivorysql_ora 1.0 Oracle Compatible extenison on Postgres Database
ora_btree_gin 1.0 support for indexing oracle datatypes in GIN
ora_btree_gist 1.0 support for oracle indexing common datatypes in GiST
pg_bigm 1.2 text similarity measurement and index searching based on bigrams
pg_cron 1.6 Job scheduler for PostgreSQL
pg_curl 2.4 PostgreSQL cURL allows most curl actions, including data transfer with URL syntax via HTTP, HTTPS, FTP, FTPS, GOPHER, TFTP, SCP, SFTP, SMB, TELNET, DICT, LDAP, LDAPS, FILE, IMAP, SMTP, POP3, RTSP and RTMP
pg_get_functiondef 1.0 Get function’s definition
pg_hint_plan 1.8.0 optimizer hints for PostgreSQL
pg_jieba 1.1.1 a parser for full-text search of Chinese
pg_partman 5.3.1 Extension to manage partitioned tables by time or ID
pg_show_plans 2.1 show query plans of all currently running SQL statements
pg_stat_monitor 2.3 The pg_stat_monitor is a PostgreSQL Query Performance Monitoring tool, based on PostgreSQL contrib module pg_stat_statements. pg_stat_monitor provides aggregated statistics, client information, plan details including plan, and histogram information.
pg_textsearch 0.1.0 Full-text search with BM25 ranking
pgagent 4.2 A PostgreSQL job scheduler
pgaudit 18.0 provides auditing functionality
pgroonga 4.0.4 Super fast and all languages supported full text search index based on Groonga
pgroonga_database 4.0.4 PGroonga database management module
pgrouting 3.8.0 pgRouting Extension
plisql 1.0 PL/iSQL procedural language
plpgsql_check 2.8 extended check for plpgsql functions
postgis 3.5.4 PostGIS geometry and geography spatial types and functions
postgis_raster 3.5.4 PostGIS raster types and functions
postgis_sfcgal 3.5.4 PostGIS SFCGAL functions
postgis_tiger_geocoder 3.5.4 PostGIS tiger geocoder and reverse geocoder
postgis_topology 3.5.4 PostGIS topology spatial types and functions
redis_fdw 1.0 Foreign data wrapper for querying a Redis server
system_stats 3.0 EnterpriseDB system statistics for PostgreSQL
vector 0.8.1 vector data type and ivfflat and hnsw access methods
zhparser 2.3 a parser for full-text search of Chinese

请注意，Pigsty 不对使用 IvorySQL 内核承担任何质保责任，使用此内核遇到的任何问题与需求请联系原厂解决。

14.6 - PolarDB PG

使用阿里云开源的 PolarDB for PostgreSQL 内核提供国产信创资质支持，与类似 Oracle RAC 的使用体验。

概览

Pigsty 允许使用 PolarDB 创建带有 “国产化信创资质” 的 PostgreSQL 集群！

PolarDB for PostgreSQL 当前以 PostgreSQL 17 为基线，Pigsty 中的 polar 模板、默认路径与扩展说明也已经同步到 PG17。任何兼容 PostgreSQL 线缆协议的客户端工具都可以访问 PolarDB 集群。

Pigsty 的 PGSQL 仓库中提供了 PolarDB PG 开源版安装包，但不会在 Pigsty 安装时下载到本地软件仓库。

PolarDB for PostgreSQL

安装

使用 Pigsty 内置模板：

./configure -c polar
./deploy.yml

变更摘要

从 Pigsty v4.4 开始，PolarDB PG 内核将直接使用 pigsty 构建打包的版本，主要变化如下：

项目 旧文档 / 旧默认值 当前值
内核基线 PostgreSQL 15 PostgreSQL 17
默认 PolarDB 路径 /u01/polardb_pg /usr/polar-17
支持架构 x86_64 x86_64, aarch64
可用扩展数 旧文档正文写为 61 pg_available_extensions 查询结果为 93，过滤 contrib 后为 34
复制用户要求 replicator 需要 SUPERUSER 保持不变

配置

以下参数需要针对 PolarDB 数据库集群进行特殊配置：

#----------------------------------#
# PGSQL & PolarDB
#----------------------------------#
pg_version: 17
pg_mode: polar
pg_packages: [ polardb, pgsql-common ]
pg_exporter_exclude_database: 'template0,template1,postgres,polardb_admin'
pg_default_roles:
  - { name: dbrole_readonly  ,login: false ,comment: role for global read-only access     }
  - { name: dbrole_offline   ,login: false ,comment: role for restricted read-only access }
  - { name: dbrole_readwrite ,login: false ,roles: [dbrole_readonly] ,comment: role for global read-write access }
  - { name: dbrole_admin     ,login: false ,roles: [pg_monitor, dbrole_readwrite] ,comment: role for object creation }
  - { name: postgres     ,superuser: true  ,comment: system superuser }
  - { name: replicator   ,superuser: true  ,replication: true ,roles: [pg_monitor, dbrole_readonly] ,comment: system replicator } # <- superuser is required for replication
  - { name: dbuser_dba   ,superuser: true  ,roles: [dbrole_admin]  ,pgbouncer: true ,pool_mode: session, pool_connlimit: 16 ,comment: pgsql admin user }
  - { name: dbuser_monitor ,roles: [pg_monitor] ,pgbouncer: true ,parameters: {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment: pgsql monitor user }

默认 polar 内核安装目录已调整为 /usr/polar-17。这里特别注意，PolarDB PG 要求 replicator 复制用户为 SUPERUSER，与原生 PG 不同。

扩展列表

PolarDB PG 内核共有 93 个可用扩展，去除 PG Contrib 自带扩展之后，还有以下额外扩展：

扩展名 版本号 说明
hll 2.18 type for storing hyperloglog data
ip4r 2.4
log_fdw 1.4 foreign-data wrapper for Postgres log file access
pase 0.0.1 ant ai similarity search
pg_bigm 1.2 text similarity measurement and index searching based on bigrams
pg_cron 1.5 Job scheduler for PostgreSQL
pg_cron_preload 1.0 polardb pg extend catalog
pg_hint_plan 1.7.0 optimizer hints for PostgreSQL
pg_jieba 1.1.0 a parser for full-text search of Chinese
pg_partman 5.2.4 Extension to manage partitioned tables by time or ID
pg_profile 4.10 PostgreSQL load profile repository and report builder
pg_repack 1.5.1-1 Reorganize tables in PostgreSQL databases with minimal locks
pg_similarity 1.0 support similarity queries
pg_squeeze 1.9 A tool to remove unused space from a relation.
pg_stat_kcache 2.3.0 Kernel statistics gathering
pgaudit 17.1 provides auditing functionality
pgtap 1.3.3 Unit testing for PostgreSQL
pldbgapi 1.1 server-side support for debugging PL/pgSQL functions
polar_advisor 1.1 polar_advisor
polar_feature_utils 1.0 PolarDB feature utilization
polar_io_stat 1.0 polar io stat in multi dimension
polar_monitor 1.3 monitor functions for PolarDB
polar_monitor_preload 1.0 examine the polardb information
polar_parameter_manager 1.2 Extension to select parameters for manger.
polar_proxy_utils 1.0 Extension to provide operations about proxy.
polar_resource_manager 1.0 a background process that forcibly frees user session process memory
polar_smgrperf 1.0 smgr perf test extension
polar_tde_utils 1.0 Internal extension for TDE
polar_vfs 1.0 polar virtual file system for different storage
polar_worker 1.1 polar_worker
prefix 1.2.0 Prefix Range module for PostgreSQL
roaringbitmap 0.5 support for Roaring Bitmaps
sequential_uuids 1.0.3 generator of sequential UUIDs
varbitx 1.1 varbit functions pack

14.7 - PolarDB Oracle

使用阿里云商业版本的 PolarDB for Oracle 内核（闭源，PG14，仅在特殊企业版定制中可用）

Pigsty 允许使用 PolarDB 创建带有 “国产化信创资质” 的 PolarDB for Oracle 集群！

根据 【安全可靠测评结果公告（2023年第1号）】，附表三、集中式数据库。PolarDB v2.0 属于自主可控，安全可靠的国产信创数据库。

PolarDB for Oracle 是基于 PolarDB for PostgreSQL 进行二次开发的 Oracle 兼容版本，两者共用同一套内核，通过 --compatibility-mode 参数进行区分。

我们与阿里云内核团队合作，提供基于 PolarDB v2.0 内核与 Pigsty 的完整数据库解决方案，请联系销售咨询，或在阿里云市场自行采购。

PolarDB for Oracle 内核目前仅在 EL7 (CentOS 7) 系统中可用。

PolarDB for Oracle

扩展

目前 PolarDB 2.0 (Oracle 兼容) 内核自带了以下 188 个扩展插件：

name default_version comment
cube 1.5 data type for multidimensional cubes
ip4r 2.4 NULL
adminpack 2.1 administrative functions for PostgreSQL
dict_xsyn 1.0 text search dictionary template for extended synonym processing
amcheck 1.4 functions for verifying relation integrity
autoinc 1.0 functions for autoincrementing fields
hstore 1.8 data type for storing sets of (key, value) pairs
bloom 1.0 bloom access method - signature file based index
earthdistance 1.1 calculate great-circle distances on the surface of the Earth
hstore_plperl 1.0 transform between hstore and plperl
bool_plperl 1.0 transform between bool and plperl
file_fdw 1.0 foreign-data wrapper for flat file access
bool_plperlu 1.0 transform between bool and plperlu
fuzzystrmatch 1.1 determine similarities and distance between strings
hstore_plperlu 1.0 transform between hstore and plperlu
btree_gin 1.3 support for indexing common datatypes in GIN
hstore_plpython2u 1.0 transform between hstore and plpython2u
btree_gist 1.6 support for indexing common datatypes in GiST
hll 2.17 type for storing hyperloglog data
hstore_plpython3u 1.0 transform between hstore and plpython3u
citext 1.6 data type for case-insensitive character strings
hstore_plpythonu 1.0 transform between hstore and plpythonu
hypopg 1.3.1 Hypothetical indexes for PostgreSQL
insert_username 1.0 functions for tracking who changed a table
dblink 1.2 connect to other PostgreSQL databases from within a database
decoderbufs 0.1.0 Logical decoding plugin that delivers WAL stream changes using a Protocol Buffer format
intagg 1.1 integer aggregator and enumerator (obsolete)
dict_int 1.0 text search dictionary template for integers
intarray 1.5 functions, operators, and index support for 1-D arrays of integers
isn 1.2 data types for international product numbering standards
jsonb_plperl 1.0 transform between jsonb and plperl
jsonb_plperlu 1.0 transform between jsonb and plperlu
jsonb_plpython2u 1.0 transform between jsonb and plpython2u
jsonb_plpython3u 1.0 transform between jsonb and plpython3u
jsonb_plpythonu 1.0 transform between jsonb and plpythonu
lo 1.1 Large Object maintenance
log_fdw 1.0 foreign-data wrapper for csvlog
ltree 1.2 data type for hierarchical tree-like structures
ltree_plpython2u 1.0 transform between ltree and plpython2u
ltree_plpython3u 1.0 transform between ltree and plpython3u
ltree_plpythonu 1.0 transform between ltree and plpythonu
moddatetime 1.0 functions for tracking last modification time
old_snapshot 1.0 utilities in support of old_snapshot_threshold
oracle_fdw 1.2 foreign data wrapper for Oracle access
oss_fdw 1.1 foreign-data wrapper for OSS access
pageinspect 2.1 inspect the contents of database pages at a low level
pase 0.0.1 ant ai similarity search
pg_bigm 1.2 text similarity measurement and index searching based on bigrams
pg_freespacemap 1.2 examine the free space map (FSM)
pg_hint_plan 1.4 controls execution plan with hinting phrases in comment of special form
pg_buffercache 1.5 examine the shared buffer cache
pg_prewarm 1.2 prewarm relation data
pg_repack 1.4.8-1 Reorganize tables in PostgreSQL databases with minimal locks
pg_sphere 1.0 spherical objects with useful functions, operators and index support
pg_cron 1.5 Job scheduler for PostgreSQL
pg_jieba 1.1.0 a parser for full-text search of Chinese
pg_stat_kcache 2.2.1 Kernel statistics gathering
pg_stat_statements 1.9 track planning and execution statistics of all SQL statements executed
pg_surgery 1.0 extension to perform surgery on a damaged relation
pg_trgm 1.6 text similarity measurement and index searching based on trigrams
pg_visibility 1.2 examine the visibility map (VM) and page-level visibility info
pg_wait_sampling 1.1 sampling based statistics of wait events
pgaudit 1.6.2 provides auditing functionality
pgcrypto 1.3 cryptographic functions
pgrowlocks 1.2 show row-level locking information
pgstattuple 1.5 show tuple-level statistics
pgtap 1.2.0 Unit testing for PostgreSQL
pldbgapi 1.1 server-side support for debugging PL/pgSQL functions
plperl 1.0 PL/Perl procedural language
plperlu 1.0 PL/PerlU untrusted procedural language
plpgsql 1.0 PL/pgSQL procedural language
plpython2u 1.0 PL/Python2U untrusted procedural language
plpythonu 1.0 PL/PythonU untrusted procedural language
plsql 1.0 Oracle compatible PL/SQL procedural language
pltcl 1.0 PL/Tcl procedural language
pltclu 1.0 PL/TclU untrusted procedural language
polar_bfile 1.0 The BFILE data type enables access to binary file LOBs that are stored in file systems outside Database
polar_bpe 1.0 polar_bpe
polar_builtin_cast 1.1 Internal extension for builtin casts
polar_builtin_funcs 2.0 implement polar builtin functions
polar_builtin_type 1.5 polar_builtin_type for PolarDB
polar_builtin_view 1.5 polar_builtin_view
polar_catalog 1.2 polardb pg extend catalog
polar_channel 1.0 polar_channel
polar_constraint 1.0 polar_constraint
polar_csn 1.0 polar_csn
polar_dba_views 1.0 polar_dba_views
polar_dbms_alert 1.2 implement polar_dbms_alert - supports asynchronous notification of database events.
polar_dbms_application_info 1.0 implement polar_dbms_application_info - record names of executing modules or transactions in the database.
polar_dbms_pipe 1.1 implements polar_dbms_pipe - package lets two or more sessions in the same instance communicate.
polar_dbms_aq 1.2 implement dbms_aq - provides an interface to Advanced Queuing.
polar_dbms_lob 1.3 implement dbms_lob - provides subprograms to operate on BLOBs, CLOBs, and NCLOBs.
polar_dbms_output 1.2 implement polar_dbms_output - enables you to send messages from stored procedures.
polar_dbms_lock 1.0 implement polar_dbms_lock - provides an interface to Oracle Lock Management services.
polar_dbms_aqadm 1.3 polar_dbms_aqadm - procedures to manage Advanced Queuing configuration and administration information.
polar_dbms_assert 1.0 implement polar_dbms_assert - provide an interface to validate properties of the input value.
polar_dbms_metadata 1.0 implement polar_dbms_metadata - provides a way for you to retrieve metadata from the database dictionary.
polar_dbms_random 1.0 implement polar_dbms_random - a built-in random number generator, not intended for cryptography
polar_dbms_crypto 1.1 implement dbms_crypto - provides an interface to encrypt and decrypt stored data.
polar_dbms_redact 1.0 implement polar_dbms_redact - provides an interface to mask data from queries by an application.
polar_dbms_debug 1.1 server-side support for debugging PL/SQL functions
polar_dbms_job 1.0 polar_dbms_job
polar_dbms_mview 1.1 implement polar_dbms_mview - enables to refresh materialized views.
polar_dbms_job_preload 1.0 polar_dbms_job_preload
polar_dbms_obfuscation_toolkit 1.1 implement polar_dbms_obfuscation_toolkit - enables an application to get data md5.
polar_dbms_rls 1.1 implement polar_dbms_rls - a fine-grained access control administrative built-in package
polar_multi_toast_utils 1.0 polar_multi_toast_utils
polar_dbms_session 1.2 implement polar_dbms_session - support to set preferences and security levels.
polar_odciconst 1.0 implement ODCIConst - Provide some built-in constants in Oracle.
polar_dbms_sql 1.2 implement polar_dbms_sql - provides an interface to execute dynamic SQL.
polar_osfs_toolkit 1.0 osfs library tools and functions extension
polar_dbms_stats 14.0 stabilize plans by fixing statistics
polar_monitor 1.5 monitor functions for PolarDB
polar_osfs_utils 1.0 osfs library utils extension
polar_dbms_utility 1.3 implement polar_dbms_utility - provides various utility subprograms.
polar_parameter_check 1.0 kernel extension for parameter validation
polar_dbms_xmldom 1.0 implement dbms_xmldom and dbms_xmlparser - support standard DOM interface and xml parser object
polar_parameter_manager 1.1 Extension to select parameters for manger.
polar_faults 1.0.0 simulate some database faults for end user or testing system.
polar_monitor_preload 1.1 examine the polardb information
polar_proxy_utils 1.0 Extension to provide operations about proxy.
polar_feature_utils 1.2 PolarDB feature utilization
polar_global_awr 1.0 PolarDB Global AWR Report
polar_publication 1.0 support polardb pg logical replication
polar_global_cache 1.0 polar_global_cache
polar_px 1.0 Parallel Execution extension
polar_serverless 1.0 polar serverless extension
polar_resource_manager 1.0 a background process that forcibly frees user session process memory
polar_sys_context 1.1 implement polar_sys_context - returns the value of parameter associated with the context namespace at the current instant.
polar_gpc 1.3 polar_gpc
polar_tde_utils 1.0 Internal extension for TDE
polar_gtt 1.1 polar_gtt
polar_utl_encode 1.2 implement polar_utl_encode - provides functions that encode RAW data into a standard encoded format
polar_htap 1.1 extension for PolarDB HTAP
polar_htap_db 1.0 extension for PolarDB HTAP database level operation
polar_io_stat 1.0 polar io stat in multi dimension
polar_utl_file 1.0 implement utl_file - support PL/SQL programs can read and write operating system text files
polar_ivm 1.0 polar_ivm
polar_sql_mapping 1.2 Record error sqls and mapping them to correct one
polar_stat_sql 1.0 Kernel statistics gathering, and sql plan nodes information gathering
tds_fdw 2.0.2 Foreign data wrapper for querying a TDS database (Sybase or Microsoft SQL Server)
xml2 1.1 XPath querying and XSLT
polar_upgrade_catalogs 1.1 Upgrade catalogs for old version instance
polar_utl_i18n 1.1 polar_utl_i18n
polar_utl_raw 1.0 implement utl_raw - provides SQL functions for manipulating RAW datatypes.
timescaledb 2.9.2 Enables scalable inserts and complex queries for time-series data
polar_vfs 1.0 polar virtual file system for different storage
polar_worker 1.0 polar_worker
postgres_fdw 1.1 foreign-data wrapper for remote PostgreSQL servers
refint 1.0 functions for implementing referential integrity (obsolete)
roaringbitmap 0.5 support for Roaring Bitmaps
tsm_system_time 1.0 TABLESAMPLE method which accepts time in milliseconds as a limit
vector 0.5.0 vector data type and ivfflat and hnsw access methods
rum 1.3 RUM index access method
unaccent 1.1 text search dictionary that removes accents
seg 1.4 data type for representing line segments or floating-point intervals
sequential_uuids 1.0.2 generator of sequential UUIDs
uuid-ossp 1.1 generate universally unique identifiers (UUIDs)
smlar 1.0 compute similary of any one-dimensional arrays
varbitx 1.1 varbit functions pack
sslinfo 1.2 information about SSL certificates
tablefunc 1.0 functions that manipulate whole tables, including crosstab
tcn 1.0 Triggered change notifications
zhparser 1.0 a parser for full-text search of Chinese
address_standardizer 3.3.2 Ganos PostGIS address standardizer
address_standardizer_data_us 3.3.2 Ganos PostGIS address standardizer data us
ganos_fdw 6.0 Ganos Spatial FDW extension for POLARDB
ganos_geometry 6.0 Ganos geometry lite extension for POLARDB
ganos_geometry_pyramid 6.0 Ganos Geometry Pyramid extension for POLARDB
ganos_geometry_sfcgal 6.0 Ganos geometry lite sfcgal extension for POLARDB
ganos_geomgrid 6.0 Ganos geometry grid extension for POLARDB
ganos_importer 6.0 Ganos Spatial importer extension for POLARDB
ganos_networking 6.0 Ganos networking
ganos_pointcloud 6.0 Ganos pointcloud extension For POLARDB
ganos_pointcloud_geometry 6.0 Ganos_pointcloud LIDAR data and ganos_geometry data for POLARDB
ganos_raster 6.0 Ganos raster extension for POLARDB
ganos_scene 6.0 Ganos scene extension for POLARDB
ganos_sfmesh 6.0 Ganos surface mesh extension for POLARDB
ganos_spatialref 6.0 Ganos spatial reference extension for POLARDB
ganos_trajectory 6.0 Ganos trajectory extension for POLARDB
ganos_vomesh 6.0 Ganos volumn mesh extension for POLARDB
postgis_tiger_geocoder 3.3.2 Ganos PostGIS tiger geocoder
postgis_topology 3.3.2 Ganos PostGIS topology

14.8 - Percona

支持 TDE 透明加密的 Percona Postgres 发行版

Percona Postgres 是一个带有 pg_tde（透明数据加密）扩展的补丁 Postgres 内核。

Pigsty 从 v4.4.0 起将 Percona PostgreSQL 打包到私有前缀 /usr/pgtde-$v，v4.5.0 延续这一布局 （PostgreSQL 18 对应 /usr/pgtde-18）。pgtde 包别名会同时安装内核包 与 contrib 包，其中包含 pg_tde、PostGIS、pgvector、wal2json、pg_repack、 pgaudit、pg_stat_monitor 等常用组件。

快速开始

使用 Pigsty 标准安装流程，配合 pgtde 配置模板。

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty;
./configure -c pgtde     # 使用 percona postgres 内核
./deploy.yml             # 部署 Pigsty 核心链路与 Percona PostgreSQL

配置

需要调整以下参数来部署 Percona 集群：

pg-meta:
  hosts:
    10.10.10.10: { pg_seq: 1, pg_role: primary }
  vars:
    pg_mode: pgtde
    pg_cluster: pg-meta
    pg_users:
      - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
      - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer  }
    pg_databases:
      - name: meta
        baseline: cmdb.sql
        comment: pigsty tde database
        schemas: [pigsty]
        extensions: [ vector, postgis, pg_tde ,pgaudit, { name: pg_stat_monitor, schema: monitor } ]
    pg_hba_rules:
      - { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes' }
    pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ] # 每天凌晨 1 点进行全量备份

    # Percona PostgreSQL TDE 内核设置
    pg_packages: [ pgtde, pgsql-common ]
    pg_libs: 'pg_tde, pgaudit, pg_stat_statements, pg_stat_monitor, auto_explain'

pgtde 软件包由 Pigsty 的 pgsql 仓库模块提供，此模板不再依赖旧的 percona 仓库模块。

可用扩展

Percona Postgres 内核共有 73 个可用扩展，去除 PG Contrib 自带扩展之后，还有以下额外扩展：

扩展名 版本号 说明
address_standardizer 3.5.7 Used to parse an address into constituent elements. Generally used to support geocoding address normalization step.
address_standardizer_data_us 3.5.7 Address Standardizer US dataset example
pg_repack 1.5.3 Reorganize tables in PostgreSQL databases with minimal locks
pg_stat_monitor 2.3.2 The pg_stat_monitor is a PostgreSQL Query Performance Monitoring tool, based on PostgreSQL contrib module pg_stat_statements. pg_stat_monitor provides aggregated statistics, client information, plan details including plan, and histogram information.
pg_tde 2.2.1 pg_tde access method
pgaudit 18.0 provides auditing functionality
postgis 3.5.7 PostGIS geometry and geography spatial types and functions
postgis_raster 3.5.7 PostGIS raster types and functions
postgis_sfcgal 3.5.7 PostGIS SFCGAL functions
postgis_tiger_geocoder 3.5.7 PostGIS tiger geocoder and reverse geocoder
postgis_topology 3.5.7 PostGIS topology spatial types and functions
set_user 4.2.0 similar to SET ROLE but with added logging
vector 0.8.3 vector data type and ivfflat and hnsw access methods

关键特性

  • 透明数据加密：使用 pg_tde 扩展提供静态数据加密
  • PostgreSQL 18 兼容：基于 Percona PostgreSQL 18 包集
  • 企业级扩展：包含 pgaudit、pg_stat_monitor 等企业级功能
  • 完整生态：支持 pgvector、PostGIS 等流行扩展

注意：目前处于稳定阶段 - 在生产使用前请彻底评估。

14.9 - PostgresML

如何使用 Pigsty 部署 PostgresML，在数据库内进行机器学习、模型训练、推理、Embedding 与 RAG。

PostgresML 是一个 PostgreSQL 扩展，支持最新的大语言模型（LLM）、向量操作、经典机器学习以及传统的 Postgres 应用负载。

PostgresML (pgml) 是一个用 Rust 编写的 PostgreSQL 扩展。您可以运行独立的 Docker 镜像，但本文档不是 docker-compose 模板介绍，仅供参考。

PostgresML 官方支持 Ubuntu 22.04，但我们也为 EL 8/9 维护了 RPM 版本，如果您不需要 CUDA 和 NVIDIA 相关功能的话。

您需要在数据库节点上能够访问互联网，以便从 PyPI 下载 Python 依赖，并从 HuggingFace 下载模型。

警告

pgml 上游项目已经不再维护

配置

PostgresML 是一个用 Rust 编写的扩展。Pigsty 在 EL8/EL9 以及 Debian/Ubuntu 平台维护了 PG14-17 的预编译包。

创建新集群

PostgresML 2.10.0 可用于 PostgreSQL 14-17。下面示例使用 PG17；如果使用 PG14-16，只需把 pg_version 改为对应主版本。

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_users:
      - {name: dbuser_meta     ,password: DBUser.Meta     ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: pigsty admin user }
      - {name: dbuser_view     ,password: DBUser.Viewer   ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer for meta database }
    pg_databases:
      - { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [{name: postgis, schema: public}, {name: timescaledb}]}
    pg_hba_rules:
      - {user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes'}
    pg_version: 17
    pg_libs: 'pgml, pg_stat_statements, auto_explain'
    pg_extensions: [ pgml, pgvector, wal2json, pg_repack ]

Pigsty 会把 pgml 包别名解析为平台真实包名：EL 为 pgml_$v，Debian/Ubuntu 为 postgresql-$v-pgml。同时需要将 pgml 添加到 pg_libs 中。

在现有集群上启用

要在现有集群上启用 pgml，可以使用 Ansible 的 package 模块安装：

ansible pg-meta -m package -b -a 'name=pgml_17'
# ansible el8,el9 -m package -b -a 'name=pgml_17'              # EL 8/9
# ansible u22,u24 -m package -b -a 'name=postgresql-17-pgml'   # Debian/Ubuntu

Python 依赖

您还需要在集群节点上安装 PostgresML 的 Python 依赖。官方教程：安装指南

安装 Python 和 PIP

确保已安装 python3、pip 和 venv：

# Ubuntu 22.04 (python3.10)，需要使用 apt 安装 pip 和 venv
sudo apt install -y python3 python3-pip python3-venv

对于 EL 8 / EL9 及兼容发行版，可以使用 python3.11：

# EL 8/9，可以升级默认的 pip 和 virtualenv
sudo yum install -y python3.11 python3.11-pip       # 安装最新的 python3.11
python3.11 -m pip install --upgrade pip virtualenv  # 在 EL8 / EL9 上使用 python3.11
使用 PyPI 镜像

对于中国大陆用户，建议使用清华大学 PyPI 镜像。

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple    # 设置全局镜像（推荐）
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple some-package        # 单次安装时使用

安装依赖包

创建 Python 虚拟环境，并使用 pip 从 requirements.txt 和 requirements-xformers.txt 安装依赖。

如果您使用的是 EL 8/9，需要将以下命令中的 python3 替换为 python3.11。

su - postgres;                          # 使用数据库超级用户创建虚拟环境
mkdir -p /data/pgml; cd /data/pgml;     # 创建虚拟环境目录
python3    -m venv /data/pgml           # 创建虚拟环境目录（Ubuntu 22.04）
source /data/pgml/bin/activate          # 激活虚拟环境

# 写入 Python 依赖并使用 pip 安装
cat > /data/pgml/requirments.txt <<EOF
accelerate==0.22.0
auto-gptq==0.4.2
bitsandbytes==0.41.1
catboost==1.2
ctransformers==0.2.27
datasets==2.14.5
deepspeed==0.10.3
huggingface-hub==0.17.1
InstructorEmbedding==1.0.1
lightgbm==4.1.0
orjson==3.9.7
pandas==2.1.0
rich==13.5.2
rouge==1.0.1
sacrebleu==2.3.1
sacremoses==0.0.53
scikit-learn==1.3.0
sentencepiece==0.1.99
sentence-transformers==2.2.2
tokenizers==0.13.3
torch==2.0.1
torchaudio==2.0.2
torchvision==0.15.2
tqdm==4.66.1
transformers==4.33.1
xgboost==2.0.0
langchain==0.0.287
einops==0.6.1
pynvml==11.5.0
EOF

# 在虚拟环境中使用 pip 安装依赖
python3 -m pip install -r /data/pgml/requirments.txt
python3 -m pip install xformers==0.0.21 --no-dependencies

# 此外，有 3 个 Python 包需要使用 sudo 全局安装！
sudo python3 -m pip install xgboost lightgbm scikit-learn

启用 PostgresML

在所有集群节点上安装 pgml 扩展和 Python 依赖后，就可以在 PostgreSQL 集群上启用 pgml 了。

使用 patronictl 命令 配置集群，将 pgml 添加到 shared_preload_libraries，并在 pgml.venv 中指定您的虚拟环境目录：

shared_preload_libraries: pgml, timescaledb, pg_stat_statements, auto_explain
pgml.venv: '/data/pgml'

然后重启数据库集群，并使用 SQL 命令创建扩展：

CREATE EXTENSION vector;        -- 建议同时安装 pgvector！
CREATE EXTENSION pgml;          -- 在当前数据库中创建 PostgresML
SELECT pgml.version();          -- 打印 PostgresML 版本信息

如果一切正常，您应该会看到类似以下输出：

# create extension pgml;
INFO:  Python version: 3.11.2 (main, Oct  5 2023, 16:06:03) [GCC 8.5.0 20210514 (Red Hat 8.5.0-18)]
INFO:  Scikit-learn 1.3.0, XGBoost 2.0.0, LightGBM 4.1.0, NumPy 1.26.1
CREATE EXTENSION

# SELECT pgml.version(); -- 打印 PostgresML 版本信息
 version
---------
 2.7.8

大功告成！更多详情请参阅 PostgresML 官方文档：https://postgresml.org/docs/guides/use-cases/

14.10 - openHalo

MySQL 兼容的 Postgres 14 分支

OpenHalo 是一个开源的 PostgreSQL 内核，提供 MySQL 线协议兼容性。

openHalo 基于 PostgreSQL 14.18 内核版本，提供与 MySQL 5.7.32-log / 8.0 版本的线协议兼容性。Pigsty 通过 pg_mode: mysql 与 openhalo 包别名交付。

Pigsty 在所有支持的 Linux 平台上为 OpenHalo 提供部署支持。

快速开始

使用 Pigsty 的 标准安装流程 和 mysql 配置模板。

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty;
./configure -c mysql    # 使用 MySQL（openHalo）配置模板
./deploy.yml            # 安装，生产部署请先在 pigsty.yml 中修改密码

对于生产部署，请确保在运行安装剧本之前修改 pigsty.yml 配置文件中的密码参数。

配置 

pg-meta:
  hosts:
    10.10.10.10: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-meta
    pg_users:
      - {name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: pigsty admin user }
      - {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer for meta database }
    pg_databases:
      - {name: postgres, extensions: [ aux_mysql ]} # mysql 兼容数据库
      - {name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty]}
    pg_hba_rules:
      - {user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes'}
    pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ] # 每天凌晨 1 点进行全量备份

    # OpenHalo 临时设置
    pg_mode: mysql                    # HaloDB 的 MySQL 兼容模式
    pg_version: 14                    # 当前 HaloDB 兼容 PG 主版本 14
    pg_packages: [ openhalo, pgsql-common ]    # 安装 openHalo 而不是 PostgreSQL 原生内核

OpenHalo 提供了一个独有的扩展 aux_mysql，它包含了 MySQL 兼容性所需的函数和类型。请确保在 pg_databases 配置中为 postgres 数据库启用此扩展，以获得完整的 MySQL 兼容功能。

使用

访问 MySQL 时，实际连接使用的是 postgres 数据库。请注意，MySQL 中的"数据库"概念实际上对应于 PostgreSQL 中的"Schema"。 因此，use mysql 实际上使用的是 postgres 数据库内的 mysql Schema。

用于 MySQL 的用户名和密码与 PostgreSQL 中的相同。您可以使用标准的 PostgreSQL 方法管理用户和权限。

客户端访问

OpenHalo 提供 MySQL 线协议兼容性，默认监听端口 3306，允许 MySQL 客户端和驱动程序直接连接。

Pigsty 的 conf/mysql 配置默认安装 mysql 客户端工具。

您可以使用以下命令访问 MySQL：

mysql -h 127.0.0.1 -u dbuser_dba

目前，OpenHalo 官方确保 Navicat 可以正常访问此 MySQL 端口，但 Intellij IDEA 的 DataGrip 访问会导致错误。

配置

Pigsty 默认配置了 database_compat_mode 值为 mysql，启用 MySQL 兼容性模式。您可以进一步调整以下参数来调整 MySQL 兼容性设置：

mysql.listener_on = true	                    # (enable MySQL listener; change requires restart)
mysql.port = 3306                              # (second_port is for MySQL mode; change requires restart)
mysql.halo_mysql_version = '5.7.32-log'        # (change requires restart)
mysql.ci_collation = true                      # (change requires restart)
mysql.explicit_defaults_for_timestamp = false  # (change requires restart)
mysql.auto_rollback_tx_on_error = false        # (change requires restart)

修改说明

Pigsty 安装的 OpenHalo 内核基于 HaloTech-Co-Ltd/openHalo 内核进行了少量修改：

  • 将默认数据库名称从 halo0root 改回 postgres
  • 从默认版本号中删除 1.0. 前缀，恢复为 14.18（否则 Patroni 会报错）
  • 修改默认配置文件以启用 MySQL 兼容性并默认监听端口 3306

请注意，Pigsty 不为使用 OpenHalo 内核提供任何保证。使用此内核时遇到的任何问题或需求应与原始供应商联系。

警告：目前该内核处于 beta1 阶段 - 在生产使用前请自行评估风险。

可用扩展

OpenHalo 内核共有 59 个可用扩展，去除 PG Contrib 自带扩展之后，还有以下额外扩展：

扩展名 版本号 说明
aux_mysql 1.5 MySQL Supplementary Extension
hstore_plpython2u 1.0 transform between hstore and plpython2u
hstore_plpythonu 1.0 transform between hstore and plpythonu
jsonb_plpython2u 1.0 transform between jsonb and plpython2u
jsonb_plpythonu 1.0 transform between jsonb and plpythonu
ltree_plpython2u 1.0 transform between ltree and plpython2u
ltree_plpythonu 1.0 transform between ltree and plpythonu

14.11 - Greenplum

使用 Pigsty 部署/监控 Greenplum 集群，构建大规模并行处理（MPP）的 PostgreSQL 数据仓库集群！

Pigsty 支持部署 Greenplum 集群，及其衍生发行版 YMatrixDB，并提供了将现有 Greenplum 部署纳入 Pigsty 监控的能力。

概览

Greenplum / YMatrix 集群部署能力仅在专业版本/企业版本中提供，目前不对外开源。

安装

Pigsty 提供了 Greenplum 6 (@el7) 与 Greenplum 7 (@el8) 的安装包，开源版本用户可以自行安装配置。

# EL 7 Only (Greenplum6)
./node.yml -t node_install  -e '{"node_repo_modules":"pgsql","node_packages":["open-source-greenplum-db-6"]}'

# EL 8 Only (Greenplum7)
./node.yml -t node_install  -e '{"node_repo_modules":"pgsql","node_packages":["open-source-greenplum-db-7"]}'

配置

要定义 Greenplum 集群，需要用到 pg_mode = gpsql，并使用额外的身份参数 pg_shard 与 gp_role。

#================================================================#
#                        GPSQL Clusters                          #
#================================================================#

#----------------------------------#
# cluster: mx-mdw (gp master)
#----------------------------------#
mx-mdw:
  hosts:
    10.10.10.10: { pg_seq: 1, pg_role: primary , nodename: mx-mdw-1 }
  vars:
    gp_role: master          # this cluster is used as greenplum master
    pg_shard: mx             # pgsql sharding name & gpsql deployment name
    pg_cluster: mx-mdw       # this master cluster name is mx-mdw
    pg_databases:
      - { name: matrixmgr , extensions: [ { name: matrixdbts } ] }
      - { name: meta }
    pg_users:
      - { name: meta , password: DBUser.Meta , pgbouncer: true }
      - { name: dbuser_monitor , password: DBUser.Monitor , roles: [ dbrole_readonly ], superuser: true }

    pgbouncer_enabled: true                # enable pgbouncer for greenplum master
    pgbouncer_exporter_enabled: false      # enable pgbouncer_exporter for greenplum master
    pg_exporter_params: 'host=127.0.0.1&sslmode=disable'  # use 127.0.0.1 as local monitor host

#----------------------------------#
# cluster: mx-sdw (gp master)
#----------------------------------#
mx-sdw:
  hosts:
    10.10.10.11:
      nodename: mx-sdw-1        # greenplum segment node
      pg_instances:             # greenplum segment instances
        6000: { pg_cluster: mx-seg1, pg_seq: 1, pg_role: primary , pg_exporter_port: 9633 }
        6001: { pg_cluster: mx-seg2, pg_seq: 2, pg_role: replica , pg_exporter_port: 9634 }
    10.10.10.12:
      nodename: mx-sdw-2
      pg_instances:
        6000: { pg_cluster: mx-seg2, pg_seq: 1, pg_role: primary , pg_exporter_port: 9633  }
        6001: { pg_cluster: mx-seg3, pg_seq: 2, pg_role: replica , pg_exporter_port: 9634  }
    10.10.10.13:
      nodename: mx-sdw-3
      pg_instances:
        6000: { pg_cluster: mx-seg3, pg_seq: 1, pg_role: primary , pg_exporter_port: 9633 }
        6001: { pg_cluster: mx-seg1, pg_seq: 2, pg_role: replica , pg_exporter_port: 9634 }
  vars:
    gp_role: segment               # these are nodes for gp segments
    pg_shard: mx                   # pgsql sharding name & gpsql deployment name
    pg_cluster: mx-sdw             # these segment clusters name is mx-sdw
    pg_preflight_skip: true        # skip preflight check (since pg_seq & pg_role & pg_cluster not exists)
    pg_exporter_config: pg_exporter_basic.yml                             # use basic config to avoid segment server crash
    pg_exporter_params: 'options=-c%20gp_role%3Dutility&sslmode=disable'  # use gp_role = utility to connect to segments

此外，PG Exporter 需要额外的连接参数，才能连接到 Greenplum Segment 实例上采集监控指标。

14.12 - OrioleDB

PostgreSQL 的下一代 OLTP 引擎

OrioleDB 是一个 PostgreSQL 存储引擎扩展，声称能够提供 4 倍 OLTP 性能，没有 xid 环绕和表膨胀问题，并具有"云原生"（数据存储在 S3）能力。

OrioleDB 当前在 Pigsty 中支持 PostgreSQL 16、17、18 三个兼容系，当前基线版本为 OrioleDB 1.8 beta16。

您可以使用 Pigsty 将 OrioleDB 作为 RDS 运行。pg_mode 仍使用 oriole 选择 /usr/oriole-$v 安装路径， orioledb 包别名会按 pg_version 解析为版本化内核包，例如 orioledb-16、orioledb-17、orioledb-18。

快速开始

按照 Pigsty 标准安装 流程，使用 oriole 配置模板。

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty;
./configure -c oriole    # 使用 OrioleDB 配置模板
./deploy.yml             # 使用 OrioleDB 安装 Pigsty

对于生产部署，请确保在运行 install 剧本之前修改 pigsty.yml 配置中的密码参数。

配置 

pg-meta:
  hosts:
    10.10.10.10: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-meta
    pg_users:
      - {name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: pigsty admin user }
      - {name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer for meta database }
    pg_databases:
      - {name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty], extensions: [orioledb]}
    pg_hba_rules:
      - {user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes'}
    pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ] # 每天凌晨 1 点进行全量备份

    # OrioleDB 临时设置
    pg_mode: oriole                                         # oriole 兼容模式
    pg_version: 18                                          # OrioleDB 支持 PG 16、17、18
    pg_packages: [ orioledb, pgsql-common ]                 # 安装 OrioleDB 内核
    pg_libs: 'orioledb, pg_stat_statements, auto_explain'   # 加载 OrioleDB 扩展

使用

要使用 OrioleDB，请安装 orioledb 包别名；Pigsty 会按平台与 pg_version 解析为对应的 PG16、PG17 或 PG18 内核包。

使用 pgbench 初始化类似 TPC-B 的表，包含 100 个仓库：

pgbench -is 100 meta
pgbench -nv -P1 -c10 -S -T1000 meta
pgbench -nv -P1 -c50 -S -T1000 meta
pgbench -nv -P1 -c10    -T1000 meta
pgbench -nv -P1 -c50    -T1000 meta

接下来，您可以使用 orioledb 存储引擎重建这些表并观察性能差异：

-- 创建 OrioleDB 表
CREATE TABLE pgbench_accounts_o (LIKE pgbench_accounts INCLUDING ALL) USING orioledb;
CREATE TABLE pgbench_branches_o (LIKE pgbench_branches INCLUDING ALL) USING orioledb;
CREATE TABLE pgbench_history_o (LIKE pgbench_history INCLUDING ALL) USING orioledb;
CREATE TABLE pgbench_tellers_o (LIKE pgbench_tellers INCLUDING ALL) USING orioledb;

-- 从常规表复制数据到 OrioleDB 表
INSERT INTO pgbench_accounts_o SELECT * FROM pgbench_accounts;
INSERT INTO pgbench_branches_o SELECT * FROM pgbench_branches;
INSERT INTO pgbench_history_o SELECT  * FROM pgbench_history;
INSERT INTO pgbench_tellers_o SELECT * FROM pgbench_tellers;

-- 删除原始表并重命名 OrioleDB 表
DROP TABLE pgbench_accounts, pgbench_branches, pgbench_history, pgbench_tellers;
ALTER TABLE pgbench_accounts_o RENAME TO pgbench_accounts;
ALTER TABLE pgbench_branches_o RENAME TO pgbench_branches;
ALTER TABLE pgbench_history_o RENAME TO pgbench_history;
ALTER TABLE pgbench_tellers_o RENAME TO pgbench_tellers;

关键特性

  • 无 XID 回绕：消除事务 ID 回绕维护
  • 无表膨胀：高级存储管理防止表膨胀
  • 云存储：对 S3 兼容对象存储的原生支持
  • OLTP 优化：专为事务工作负载设计
  • 改进性能：更好的空间利用率和查询性能

注意：OrioleDB 仍处于快速迭代阶段，生产使用前请按目标版本单独评估。

可用扩展

OrioleDB 内核共有 53 个可用扩展，去除 PG Contrib 自带扩展之后，还有以下额外扩展：

扩展名 版本号 说明
orioledb 1.8 OrioleDB – the next generation transactional engine

14.13 - Cloudberry

在 Pigsty 中使用 Cloudberry 开源 MPP 数仓内核，通过 gpsql 模式统一纳管节点、监控与配置。

Cloudberry 是一个源自 Greenplum 社区的开源 MPP 数据仓库内核，适合大规模并行分析场景。

概览

在 Pigsty 中，Cloudberry 沿用 gpsql 模式接入，与 Greenplum / MatrixDB 共享一套身份模型、监控逻辑与目录约定。

  • 内核包名：cloudberry
  • 模式标识：pg_mode: gpsql
  • 角色标识：gp_role: master | segment
  • 当前仓库版本：Cloudberry 2.1.0
  • 当前主包版本：DEB 2.1.0-2PIGSTY，RPM 2.1.0-3PIGSTY
  • 默认二进制目录：/usr/cloudberry

需要特别说明的是，Pigsty 当前对 Cloudberry 的支持重点在于：软件包交付、节点管理、监控纳管、访问控制与配置编排。 对于 MPP 集群初始化、扩容、重平衡和上游专有运维动作，仍建议使用 Cloudberry 官方工具链完成。

当前 Pigsty 仓库同时提供 DEB 与 RPM 的 cloudberry、cloudberry-backup、cloudberry-pxf 包。

安装

当前版本暂未提供独立的 cloudberry 一键模板。更常见的使用方式是：

  1. 将目标节点纳入 Pigsty 管理。
  2. 安装 cloudberry 内核包。
  3. 通过 gpsql 模式描述 coordinator / segment 拓扑。
  4. 使用 Pigsty 统一接入监控、账号、访问控制与备份体系。

如果只是为节点安装内核包，可直接执行：

./node.yml -t node_repo    -e '{"node_repo_modules":"local,node,pgsql"}'
./node.yml -t node_install -e '{"node_packages":["cloudberry"]}'

如果是已有 Cloudberry 集群纳管，建议先保留原有初始化方式，再逐步补齐 Pigsty inventory 与监控配置。

配置

Cloudberry 使用 gpsql 模式，而不是单独的 cloudberry 模式。与原生 PostgreSQL 相比，至少需要额外关注 pg_shard 与 gp_role 两个身份参数；如需显式标注分片组，也可以补充 pg_group。

下面是一个最小可读的拓扑示例：

all:
  children:
    cb-mdw:
      hosts:
        10.10.10.10: { pg_seq: 1, pg_role: primary }
      vars:
        pg_cluster: cb-mdw
        pg_mode: gpsql
        pg_shard: cb
        gp_role: master
        pg_packages: [ cloudberry, pgsql-common ]

    cb-sdw:
      hosts:
        10.10.10.11:
          nodename: cb-sdw-1
          pg_instances:
            6000: { pg_cluster: cb-seg1, pg_seq: 1, pg_role: primary, pg_exporter_port: 9633 }
        10.10.10.12:
          nodename: cb-sdw-2
          pg_instances:
            6000: { pg_cluster: cb-seg2, pg_seq: 1, pg_role: primary, pg_exporter_port: 9633 }
      vars:
        pg_cluster: cb-sdw
        pg_mode: gpsql
        pg_shard: cb
        gp_role: segment
        pg_preflight_skip: true
        pg_packages: [ cloudberry, pgsql-common ]
        pg_exporter_config: pg_exporter_basic.yml
        pg_exporter_params: 'options=-c%20gp_role%3Dutility&sslmode=disable'

其中有两点最容易忽略：

  • gp_role: master 用于 coordinator / master 节点，业务访问通常落在这里。
  • gp_role: segment 节点采集监控时，通常需要让 pg_exporter 以 utility 模式连接。

客户端访问

对业务侧来说，Cloudberry 仍然暴露 PostgreSQL 线缆协议，绝大多数兼容 PostgreSQL 的客户端、驱动与 BI 工具都可以接入。

但需要注意：

  • 应用与分析查询应连接到 master / coordinator，而不是直接访问 segment 节点。
  • segment 节点更适合承载数据与计算分片，以及被 Pigsty 纳入监控采集。
  • 如果需要统一接入地址，可以继续使用 Pigsty 的 HAProxy / PgBouncer / DNS 服务抽象。

扩展与生态

Cloudberry 虽然源自 PostgreSQL 生态，但它不是“原生 PostgreSQL + 若干扩展”那么简单。 对于 Pigsty 主仓库中现成的扩展包，需要分两类看待：

  • 纯 SQL 或与内核 ABI 耦合较弱的对象，通常更容易适配。
  • 依赖 PGXS / 内核 C ABI 的扩展，往往需要针对 Cloudberry 的版本和编译链重新验证甚至重编译。

如果你的业务依赖 postgis、向量、FDW、审计或自定义 C 扩展，请先在目标 Cloudberry 版本上单独做兼容性验证，不要直接照搬原生 PostgreSQL 的扩展清单。

注意事项

  • Cloudberry 当前没有单独的 Pigsty 配置模板，使用时应以 gpsql 模式手工描述拓扑。
  • 当前仓库交付重点是包、配置与监控，并不替代 Cloudberry 官方的 MPP 初始化与扩缩容工具。
  • 由于这是 MPP 分布式内核，Patroni / PgBouncer / PgBackRest 的原生 PostgreSQL 经验并不能无条件套用到所有节点角色。
  • 如果你只需要 PostgreSQL 水平扩展而不是完整 MPP 数仓，通常应优先考虑 Citus。

相关文档

14.14 - Neon

使用 Neon 开源的 Serverless 版本 PostgreSQL 内核，自建灵活伸缩，Scale To Zero，灵活分叉的 PG 服务。

Neon 采用了存储与计算分离架构，提供了丝滑的自动扩缩容，Scale to Zero，以及数据库版本分叉等独家能力。

Neon 官网：https://neon.tech/

Neon 编译后的二进制产物过于庞大，目前不对开源版用户提供，目前处于试点阶段，有需求请联系 Pigsty 销售。

14.15 - AgensGraph

在 Pigsty 中使用 AgensGraph（PG17）图数据库内核，在 PostgreSQL 体系内获得属性图与 Cypher/SQL 混合查询能力。

AgensGraph 是基于 PostgreSQL 的属性图数据库内核，支持 openCypher 查询，并允许 Cypher 与 SQL 混合使用。

概览

Pigsty 通过 pg_mode: agens 接入 AgensGraph，并保留标准 PostgreSQL 集群的大部分运维体验。

  • 内核包：agensgraph
  • 模式标识：pg_mode: agens
  • 当前模板版本：AgensGraph 2.17.0
  • 当前版本字符串：PostgreSQL 17.10 (AgensGraph 2.17.0)
  • 当前内置模板：agens
  • 适用场景：关系数据之上叠加图关系分析、路径查询、知识图谱、风控关联

对客户端来说，AgensGraph 仍然暴露 PostgreSQL 线缆协议，常规 PG 客户端、驱动与连接池都可以直接接入。 和原生 PostgreSQL 的主要区别不在“如何连接”，而在“库内多了图模型对象、Cypher 语法与 agtype 数据类型”。

安装

使用 Pigsty 内置模板：

./configure -c agens
./deploy.yml

agens 模板会自动启用 pg_mode: agens 并安装 agensgraph 内核包。部署完成后可直接核对内核版本：

psql -d meta -c "SELECT version();"

配置

AgensGraph 在 Pigsty 中的关键配置如下：

all:
  vars:
    node_repo_modules: node,infra,pgsql
    pg_version: 17

  children:
    pg-meta:
      vars:
        pg_mode: agens
        pg_packages: [ agensgraph, pgsql-common ]

AgensGraph 不需要像 pgEdge / Babelfish 那样额外预加载一组专有库，因此大多数 Pigsty 的标准 HA、备份、监控、访问控制与 IaC 用法都保持不变。 如果你的负载以图遍历和复杂路径查询为主，通常应重点关注 work_mem、shared_buffers 与代价参数，而不是简单沿用默认 OLTP 习惯。

使用

连接到数据库后，通常先创建图并设置 graph_path：

CREATE GRAPH g;
SET graph_path = g;

创建标签、顶点和边：

CREATE VLABEL person;
CREATE ELABEL knows;

CREATE (:person {name: 'Jack'});
CREATE (:person {name: 'Emily'})-[:knows]->(:person {name: 'Tom'});

执行图查询与更新：

MATCH (:person {name: 'Emily'})-[:knows]->(v:person)
RETURN v.name;

MATCH (v:person {name: 'Jack'})
SET v.age = '24';

如需在 SQL 中混合调用 Cypher，可使用 cypher()：

SELECT *
FROM cypher('g', $$ MATCH (v:person) RETURN v.name $$) AS (name agtype);

在实际项目里，更常见的做法是把“关系表 + 图标签 + Cypher 查询”混合使用： 普通事务、权限与备份仍沿用 PostgreSQL 的工作流，而图分析逻辑放在 AgensGraph 提供的图对象与 cypher() 接口中完成。

注意事项

  • AgensGraph 当前固定在 PG17 兼容系，规划扩展生态时不要按 PG18 的可用性来假定。
  • agens 默认模板为单节点快速启用，生产环境建议按需扩展为高可用拓扑。
  • 并非所有 PostgreSQL 三方扩展都保证可直接用于 AgensGraph 内核，建议先做兼容性验证。
  • 图对象与关系对象可以共存于同一数据库中，但生产上通常更建议规划清晰的数据库或命名约定，避免图模型与普通业务对象互相污染。
  • 请结合业务图模型规模调优内存与代价参数，避免直接沿用默认值。
  • 使用 AgensGraph 内核遇到兼容或语义问题时，建议优先对照官方手册与上游 Issue 排查。

相关文档

可用扩展

AgensGraph 内核共有 60 个可用扩展，去除 PG Contrib 自带扩展之后，还有以下额外扩展：

扩展名 版本号 说明
meta 1.0 Utility functions for agensgraph

14.16 - pgEdge

在 Pigsty 中使用 pgEdge（PG15~18）内核，借助 Spock 多主逻辑复制构建面向边缘场景的分布式 PostgreSQL。

pgEdge 是面向边缘场景的分布式 PostgreSQL 发行版，核心能力建立在 Spock 多主逻辑复制之上。

概览

Pigsty 通过 pg_mode: pgedge 接入 pgEdge，并用标准 PG 集群编排流程交付其核心组件：

  • pgedge：PG15、PG16、PG17、PG18 兼容内核，模板默认使用 PG18
  • spock：多主（active-active）逻辑复制
  • snowflake：分布式唯一序列
  • lolor：大对象逻辑复制兼容层

当前 Pigsty 仓库中提供 pgedge-15、pgedge-16、pgedge-17、pgedge-18 四个版本化内核包，模板默认使用 pg_version: 18。 spock、snowflake 与 lolor 的控制文件、SQL 文件和动态库随 pgedge-$v 内核包一起交付，不再作为独立 pg_extensions 包安装项。 对客户端来说，pgEdge 仍然是 PostgreSQL 线缆协议，psql、JDBC/ODBC、DBeaver 等工具都可以直接接入。

Pigsty 提供的是“先验证单节点内核，再扩展到多节点复制拓扑”的交付路径： 模板会开箱即用地完成内核、扩展、监控、备份与访问控制，但真正的多主拓扑编排仍需要你根据业务一致性和冲突策略来设计。

安装

使用 Pigsty 内置模板：

./configure -c pgedge
./deploy.yml

模板默认在 meta 数据库预装 spock、snowflake、lolor。部署完成后可用以下命令核对版本和扩展：

psql -d meta -c "SELECT version();"
psql -d meta -c "SELECT extname, extversion FROM pg_extension WHERE extname IN ('spock','snowflake','lolor') ORDER BY 1;"

模板与完整参数见：pgedge 配置模板。

配置

pgedge 模板的关键参数如下（与 conf/pgedge.yml 一致）：

pg_mode: pgedge
pg_version: 18
pg_packages: [ pgedge, pgsql-common ]
pg_libs: 'spock, lolor, pg_stat_statements, auto_explain'
pg_databases:
  - { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [spock, snowflake, lolor] }

如果计划扩展为多节点多主，建议额外显式配置逻辑复制容量和 snowflake.node：

pg_parameters:
  wal_level: logical
  max_replication_slots: 16
  max_wal_senders: 16
  'snowflake.node': 1

其中 snowflake.node 必须在每个写节点上保持唯一，否则分布式 ID 会冲突。

使用

在 Pigsty 中，常见使用路径是“先单节点验证内核，再扩展为多节点 Spock 复制拓扑”。

如果你在业务数据库中也需要这些能力，请先创建扩展：

CREATE EXTENSION IF NOT EXISTS spock;
CREATE EXTENSION IF NOT EXISTS snowflake;
CREATE EXTENSION IF NOT EXISTS lolor;

随后再使用 Spock SQL API 或 pgEdge CLI 建立节点、复制集和订阅关系。 对于已有使用 serial / identity 的业务表，建议在多主写入前先完成 snowflake 序列规划，否则跨节点写入很容易出现主键冲突。

注意事项

  • pgEdge 的复制是“按数据库”组织的，不是一次性把整个实例自动变成全库多主。
  • 参与复制的表应具备 PRIMARY KEY 或合适的 REPLICA IDENTITY。
  • UNLOGGED 与 TEMPORARY 表不会进入 Spock 逻辑复制。
  • Spock 的配置与运维通常需要超级用户权限，生产环境应明确权限边界。
  • 如果业务依赖 large object 复制，应显式使用 lolor，不要假定原生 large object 会自动正确同步。
  • 跨地域多主不是“开关一开即可用”的功能，网络时延、冲突解决策略与写入模型都要先评估。

相关文档

可用扩展

pgEdge 内核共有 63 个可用扩展，去除 PG Contrib 自带扩展之后，还有以下额外扩展：

扩展名 版本号 说明
lolor 1.2.2 Large Objects support for logical replication
snowflake 2.5.0 Snowflake style IDs for PostgreSQL
spock 5.0.10 PostgreSQL Logical Replication

14.17 - DocumentDB

DocumentDB + FerretDB 组合提供 MongoDB 线协议兼容能力

DocumentDB 是微软开源维护的 PostgreSQL 文档数据库扩展，FerretDB 是构建在其上的无状态协议转换代理。 两者组合，让标准 PostgreSQL 内核对外提供 MongoDB 线协议兼容端点——使用 MongoDB 驱动的应用程序可以直接对接，请求被转换为对 PostgreSQL 的操作。

与其他内核分支不同，这不是一个独立的 PostgreSQL 分叉：数据层运行原生 PostgreSQL 16 - 18 内核，由标准 PGSQL 模块管理， 持久化、事务、高可用、备份、监控与访问控制均由 PostgreSQL 侧负责；FerretDB 以 Pigsty Docker APP 的形式部署，只承担协议转换。

Pigsty 是 FerretDB 社区的合作伙伴，提供 FerretDB 与 DocumentDB 扩展的二进制打包， 并通过 mongo 配置模板开箱即用地交付整套组合。

快速开始

使用 Pigsty 的 标准安装流程 和 mongo 配置模板：

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty;
./configure -c mongo    # 使用 Mongo（DocumentDB + FerretDB）配置模板
./deploy.yml            # 安装，生产部署请先在 pigsty.yml 中修改密码
./docker.yml -l pg-meta # 在 pg-meta 节点上安装 Docker
./app.yml -l pg-meta    # 部署 FerretDB Docker APP

FerretDB 默认监听本机回环地址的 27017 端口，使用 mongosh 或任意 MongoDB 兼容客户端即可访问：

mongosh 'mongodb://mongod:[email protected]:27017/'

配置

源文件：pigsty/conf/mongo.yml，完整模板说明见 Mongo 配置模板 文档。

PostgreSQL 侧的关键配置是 documentdb 扩展及其预加载库，以及供 FerretDB 使用的后端超级用户：

pg-meta:
  hosts:
    10.10.10.10: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-meta
    pg_users:
      - { name: mongod ,password: DBUser.Mongo ,superuser: true ,comment: FerretDB backend user }
    pg_databases:
      - { name: postgres, extensions: [ documentdb, postgis, vector, pg_cron, rum ]}
    pg_extensions: [ documentdb, postgis, pgvector, pg_cron, rum ]
    pg_libs: 'pg_documentdb, pg_documentdb_core, pg_documentdb_extended_rum, pg_cron, pg_stat_statements, auto_explain'

FerretDB 作为 Docker APP 部署，参数是 apps.ferretdb.conf 下的普通覆盖项， 容器通过 host.docker.internal 连接本机 5436 主库直连服务：

docker_enabled: true
app: ferretdb
apps:
  ferretdb:
    conf:
      FERRETDB_IMAGE: ghcr.io/ferretdb/ferretdb:2.7.0
      FERRETDB_POSTGRESQL_URL: 'postgres://mongod:[email protected]:5436/postgres?pool_min_conns=1&pool_max_conns=20'
      FERRETDB_BIND_ADDR: 127.0.0.1
      FERRETDB_PORT: 27017
      FERRETDB_AUTH: true
      FERRETDB_TELEMETRY: disabled

高可用

因为 FerretDB 完全无状态，高可用拓扑与标准 PostgreSQL 集群一致：模板中保留了注释状态的三节点 pg-mongo 示例， 每个节点各跑一个 FerretDB 容器（绑定本机 27018），由 HAProxy 汇聚为浮动端点 10.10.10.4:27017（mongo.pigsty）对外服务。

PostgreSQL 侧的故障转移仍由 Patroni 与 etcd 负责，Mongo 端点在主库切换后自动恢复可用。

注意事项

  • FerretDB 默认启用认证（FERRETDB_AUTH: true），但尚未实现 MongoDB 授权角色体系，真正的安全边界仍是 PostgreSQL 的用户与 HBA 规则。
  • 默认未启用客户端 MongoDB TLS，Mongo 端点也不会暴露到网络；确有远程访问需求时才应修改 FERRETDB_BIND_ADDR。
  • 后端集群统一使用标准 PostgreSQL 参数、剧本与仪表盘，不存在独立的 FERRET 模块或 mongo_* 参数组。
  • FerretDB 或 DocumentDB 升级后，建议重新执行一次带认证的 CRUD 冒烟测试。

15 - 场景模板

使用 Pigsty 预置的四种场景化 Patroni 模版，或者基于这些模板自定义您的配置模板

Pigsty 提供四种预置的 Patroni/PostgreSQL 配置模板，针对不同的使用场景进行了参数优化：

模板 CPU 核心 适用场景 特点
/docs/pgsql/template/oltp.yml 4-128C OLTP 事务处理 高并发、低延迟、高吞吐
/docs/pgsql/template/olap.yml 4-128C OLAP 分析处理 大查询、高并行、长事务
/docs/pgsql/template/crit.yml 4-128C 一致性优先业务 一致性优先、详细审计
/docs/pgsql/template/tiny.yml 1-3C 微型实例 资源受限、低配环境

您可以通过 pg_conf 参数来选择使用哪个配置模板，默认为 /docs/pgsql/template/oltp.yml。

通常，数据库调优模板 pg_conf 应当与机器调优模板 node_tune 配套使用。

四套标准模板都将 wal_level 设为 logical。从 PostgreSQL 18.6 起，服务端新增 output_plugin_libraries 安全白名单；Pigsty 默认允许内置的 pgoutput、test_decoding 与默认随 pgsql-main 安装的 wal2json。如果要使用其他逻辑解码输出插件，应在评审其代码与权限边界后，将准确的库名加入 pg_parameters；Patroni 会在不支持该参数的旧 PostgreSQL 版本上过滤模板项。

使用模板

要使用特定的配置模板，只需在集群定义中设置 pg_conf 参数。 建议同时设置 node_tune 参数，使操作系统级别的调优与数据库调优保持一致：

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
  vars:
    pg_cluster: pg-test
    pg_conf: oltp.yml    # PostgreSQL 配置模板（默认值）
    node_tune: oltp      # 操作系统调优模板（默认值）

对于核心金融业务场景，您可以使用 /docs/pgsql/template/crit.yml 模板：

pg-finance:
  hosts:
    10.10.10.21: { pg_seq: 1, pg_role: primary }
    10.10.10.22: { pg_seq: 2, pg_role: replica }
    10.10.10.23: { pg_seq: 3, pg_role: replica }
  vars:
    pg_cluster: pg-finance
    pg_conf: crit.yml    # PostgreSQL 关键业务模板
    node_tune: crit      # 操作系统关键业务调优

对于低配虚拟机或开发环境，可以使用 /docs/pgsql/template/tiny.yml 模板：

pg-dev:
  hosts:
    10.10.10.31: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-dev
    pg_conf: tiny.yml    # PostgreSQL 微型实例模板
    node_tune: tiny      # 操作系统微型实例调优

模板对比

四种模板在关键参数上有显著差异，以适应不同的业务场景。以下是主要差异对比：

连接与内存

参数 OLTP OLAP CRIT TINY
max_connections 500/1000 500 500/1000 250
work_mem 范围 64MB-1GB 64MB-8GB 64MB-1GB 16MB-256MB
maintenance_work_mem 25% 共享缓冲区 50% 共享缓冲区 25% 共享缓冲区 25% 共享缓冲区
max_locks_per_transaction 1-2x maxconn 2-4x maxconn 1-2x maxconn 1-2x maxconn

并行查询

参数 OLTP OLAP CRIT TINY
max_worker_processes max(cpu+16, 24) max(cpu+20, 28) max(cpu+16, 24) max(cpu+12, 20)
max_parallel_workers 50% cpu 80% cpu 50% cpu 50% cpu
max_parallel_workers_per_gather 20% cpu (max 8) 50% cpu 0（禁用） 0（禁用）
parallel_setup_cost 2000 1000 2000 1000
parallel_tuple_cost 0.2 0.1 0.2 0.1

同步复制

参数 OLTP OLAP CRIT TINY
synchronous_mode 取决于 pg_rpo 取决于 pg_rpo 强制开启 取决于 pg_rpo
data_checksums 可选 可选 强制开启 可选

Vacuum 配置

参数 OLTP OLAP CRIT TINY
vacuum_cost_delay 20ms 10ms 20ms 20ms
vacuum_cost_limit 2000 10000 2000 2000
autovacuum_max_workers 3 3 3 2

超时与安全

参数 OLTP OLAP CRIT TINY
idle_in_transaction_session_timeout 10min 禁用 1min 10min
log_min_duration_statement 100ms 1000ms 100ms 100ms
default_statistics_target 400 1000 400 200
track_activity_query_size 8KB 8KB 32KB 8KB
log_connections 仅授权 仅授权 全部阶段 默认

IO 配置（PG18）

参数 OLTP OLAP CRIT TINY
io_workers 25% cpu (4-16) 50% cpu (4-32) 25% cpu (4-8) 3
temp_file_limit 1/20 磁盘，上限 100GB 1/5 磁盘，上限 400GB 1/20 磁盘，上限 100GB 1/20 磁盘，上限 100GB

选择建议

  • OLTP 模板：适用于大多数在线事务处理场景，是默认选择。适合电商、社交、游戏等高并发低延迟应用。

  • OLAP 模板：适用于数据仓库、BI 报表、ETL 等分析型负载。特点是允许大查询、高并行度、宽松的超时设置。

  • CRIT 模板：适用于金融交易、核心账务等对数据一致性和安全性有极高要求的场景。强制同步复制、数据校验和、完整审计日志。

  • TINY 模板：适用于开发测试环境、资源受限的虚拟机、树莓派等场景。最小化资源占用，禁用并行查询。

自定义模板

您可以基于现有模板创建自定义配置模板。模板文件位于 Pigsty 安装目录的 roles/pgsql/templates/ 下：

roles/pgsql/templates/
├── oltp.yml    # OLTP 事务处理模板（默认）
├── olap.yml    # OLAP 分析处理模板
├── crit.yml    # CRIT 关键业务模板
└── tiny.yml    # TINY 微型实例模板

创建自定义模板的步骤：

  1. 复制一个现有模板作为基础
  2. 根据需要修改参数
  3. 将模板放置在 roles/pgsql/templates/ 目录
  4. 在集群定义中通过 pg_conf 引用新模板

例如，创建一个名为 myapp.yml 的自定义模板：

cp roles/pgsql/templates/oltp.yml roles/pgsql/templates/myapp.yml
# 编辑 myapp.yml 进行自定义

然后在集群中使用：

pg-myapp:
  vars:
    pg_conf: myapp.yml

请注意，模板文件使用 Jinja2 模板语法，参数值会根据节点的实际资源（CPU、内存、磁盘）动态计算。

参数优化策略

了解更多关于模板参数优化的技术细节，请参阅 参数优化策略，其中详细介绍了：

  • 内存参数调整（共享缓冲区、工作内存、最大连接数）
  • CPU 参数调整（并行查询工作进程配置）
  • 存储空间参数（WAL 大小、临时文件限制）
  • 手工调整参数的方法

相关参数

  • pg_conf：指定使用的 PostgreSQL 配置模板
  • node_tune：指定使用的操作系统调优模板，应与 pg_conf 配套
  • pg_rto：恢复时间目标，影响故障切换超时
  • pg_rpo：候选副本落后阈值；设为 0 时通用模板启用同步复制
  • pg_max_conn：覆盖模板的最大连接数
  • pg_shared_buffer_ratio：共享缓冲区占内存比例
  • pg_storage_type：存储类型，影响 IO 相关参数

15.1 - 默认配置模板的参数优化策略说明

了解在 Pigsty 中，预置的四种 Patroni 场景化模板所采用的不同参数优化策略

Pigsty 默认提供了四套场景化参数模板，可以通过 pg_conf 参数指定并使用。

  • tiny.yml：为小节点、虚拟机、小型演示优化（模板标注为 1-3 核）
  • oltp.yml：为 OLTP 工作负载和延迟敏感应用优化（4C8GB+）（默认模板）
  • olap.yml：为 OLAP 工作负载和吞吐量优化（4C8G+）
  • crit.yml：为数据一致性和关键应用优化（4C8G+）

Pigsty 会针对这四种默认场景，采取不同的参数优化策略，如下所示：

内存参数调整

Pigsty 默认会检测系统的内存大小，并以此为依据设定最大连接数量与内存相关参数。

默认情况下，Pigsty 使用 25% 的内存作为 PostgreSQL 共享缓冲区；其余内存还会被连接、work_mem、后台进程及操作系统缓存共同使用。

默认情况下，如果用户没有设置一个 pg_max_conn 最大连接数，Pigsty 会根据以下规则使用默认值：

  • oltp: 500 (pgbouncer) / 1000 (postgres)
  • crit: 500 (pgbouncer) / 1000 (postgres)
  • tiny: 250
  • olap: 500

其中对于 OLTP 与 CRIT 模版来说，如果服务没有指向 pgbouncer 连接池，而是直接连接 postgres 数据库，最大连接会翻倍至 1000 条。

决定最大连接数后，work_mem 会根据共享内存数量 / 最大连接数计算得到，并限定在 64MB ~ 1GB 的范围内。

{% raw %}
{% if pg_max_conn != 'auto' and pg_max_conn|int >= 20 %}{% set pg_max_connections = pg_max_conn|int %}{% else %}{% if pg_default_service_dest|default('postgres') == 'pgbouncer' %}{% set pg_max_connections = 500 %}{% else %}{% set pg_max_connections = 1000 %}{% endif %}{% endif %}
{% set pg_max_prepared_transactions = pg_max_connections if 'citus' in pg_libs else 0 %}
{% set pg_max_locks_per_transaction = (2 * pg_max_connections)|int if 'citus' in pg_libs or 'timescaledb' in pg_libs else pg_max_connections %}
{% set pg_shared_buffers = (node_mem_mb|int * pg_shared_buffer_ratio|float) | round(0, 'ceil') | int %}
{% set pg_maintenance_mem = (pg_shared_buffers|int * 0.25)|round(0, 'ceil')|int %}
{% set pg_effective_cache_size = node_mem_mb|int - pg_shared_buffers|int  %}
{% set pg_workmem =  ([ ([ (pg_shared_buffers / pg_max_connections)|round(0,'floor')|int , 64 ])|max|int , 1024])|min|int %}
{% endraw %}

CPU参数调整

在 PostgreSQL 中，有 4 个与并行查询相关的重要参数，Pigsty 会自动根据当前系统的 CPU 核数进行参数优化。 模板先计算并行/扩展 worker 预算，然后在写入 max_worker_processes 时再额外增加 8 个保留槽。因此最终 GUC 比模板顶部的中间变量多 8。

OLTP 设置逻辑 范围限制
max_worker_processes max(CPU + 8, 16) + 8 即 max(CPU + 16, 24)
max_parallel_workers max(ceil(50% CPU), 2) 1/2 CPU 上取整，最少两个
max_parallel_maintenance_workers max(ceil(33% CPU), 2) 1/3 CPU 上取整，最少两个
max_parallel_workers_per_gather min(max(ceil(20% CPU), 2),8) 1/5 CPU 下取整，最少两个，最多 8 个
OLAP 设置逻辑 范围限制
max_worker_processes max(CPU + 12, 20) + 8 即 max(CPU + 20, 28)
max_parallel_workers max(ceil(80% CPU, 2)) 4/5 CPU 上取整，最少两个
max_parallel_maintenance_workers max(ceil(33% CPU), 2) 1/3 CPU 上取整，最少两个
max_parallel_workers_per_gather max(floor(50% CPU), 2) 1/2 CPU 上取整，最少两个
CRIT 设置逻辑 范围限制
max_worker_processes max(CPU + 8, 16) + 8 即 max(CPU + 16, 24)
max_parallel_workers max(ceil(50% CPU), 2) 1/2 CPU 上取整，最少两个
max_parallel_maintenance_workers max(ceil(33% CPU), 2) 1/3 CPU 上取整，最少两个
max_parallel_workers_per_gather 0, 按需启用
TINY 设置逻辑 范围限制
max_worker_processes max(CPU + 4, 12) + 8 即 max(CPU + 12, 20)
max_parallel_workers max(floor(50% CPU), 1) 50% CPU 下取整，最少 1 个
max_parallel_maintenance_workers max(floor(33% CPU), 1) 33% CPU 下取整，最少 1 个
max_parallel_workers_per_gather 0，按需启用 禁用单个查询的并行 gather

请注意，CRIT 和 TINY 模板直接通过设置 max_parallel_workers_per_gather = 0 关闭了并行查询。 用户可以按需在需要时设置此参数以启用并行查询。

OLTP 和 CRIT 模板都额外设置了以下参数，将并行查询的 Cost x 2，以降低使用并行查询的倾向。

parallel_setup_cost: 2000           # double from 100 to increase parallel cost
parallel_tuple_cost: 0.2            # double from 0.1 to increase parallel cost
min_parallel_table_scan_size: 32MB  # 4x default 8MB, prefer non-parallel scan
min_parallel_index_scan_size: 2MB   # 4x default 512kB, prefer non-parallel scan

请注意 max_worker_processes 参数的调整必须在重启后才能生效。此外，当从库的本参数配置值高于主库时，从库将无法启动。 此参数必须通过 patroni 配置管理进行调整，该参数由 Patroni 管理，用于确保主从配置一致，避免在故障切换时新从库无法启动。

存储空间参数

Pigsty 默认检测 /data/postgres 主数据目录所在磁盘的总空间，并以此作为依据指定下列参数：

{% raw %}
{% set pg_size_twentieth = ([([(node_fs_bytes|int / 21474836480)|round(0, 'ceil')|int, 1])|max, 100])|min %}
min_wal_size: {{ ([pg_size_twentieth, 200])|min }}GB                  # 1/20 disk size, max 200GB
max_wal_size: {{ ([pg_size_twentieth * 4, 2000])|min }}GB             # 2/10 disk size, max 2000GB
max_slot_wal_keep_size: {{ ([pg_size_twentieth * 6, 3000])|min }}GB   # 3/10 disk size, max 3000GB
temp_file_limit: {{ ([pg_size_twentieth, 200])|min }}GB               # 1/20 of disk size, max 200GB
{% endraw %}
  • pg_size_twentieth 先按磁盘容量的 1/20 向上取整，并限制在 1～100GB。
  • 因此前三种标准模板中，temp_file_limit 与 min_wal_size 的 实际有效上限是 100GB。
  • max_wal_size 的实际有效上限是 400GB。
  • max_slot_wal_keep_size 的实际有效上限是 600GB。

OLAP 模板将 temp_file_limit 设为 pg_size_twentieth × 4，实际有效上限是 400GB。模板行尾现有的 200GB/2TB/3TB 注释没有计入 pg_size_twentieth 自身的 100GB 上限，应以渲染表达式为准。

手工调整参数

除了使用 Pigsty 自动配置的参数外，您还可以手工调整 PostgreSQL 参数。

使用 pg edit-config <cluster> 命令可以交互式编辑集群配置：

pg edit-config pg-meta

或者使用 -p 参数直接设置参数：

pg edit-config -p log_min_duration_statement=1000 pg-meta
pg edit-config --force -p shared_preload_libraries='timescaledb, pg_cron, pg_stat_statements, auto_explain' pg-meta

您也可以使用 Patroni REST API 来修改配置：

curl -u 'postgres:Patroni.API' \
    -d '{"postgresql":{"parameters": {"log_min_duration_statement":200}}}' \
    -s -X PATCH http://10.10.10.10:8008/config | jq .

15.2 - OLTP 模板

针对在线事务处理负载优化的 PostgreSQL 配置模板

oltp.yml 是 Pigsty 的默认配置模板，针对 在线事务处理（OLTP）负载进行了优化。适用于 4-128 核 CPU 的服务器，特点是高并发连接、低延迟响应、高事务吞吐量。

建议同时使用 node_tune = oltp 进行操作系统级别的配套调优。

适用场景

OLTP 模板适用于以下场景：

  • 电商系统：订单处理、库存管理、用户交易
  • 社交应用：用户动态、消息推送、关注关系
  • 游戏后端：玩家数据、排行榜、游戏状态
  • SaaS 应用：多租户业务系统
  • Web 应用：常规的 CRUD 操作密集型应用

特征负载：

  • 大量短事务（毫秒级）
  • 高并发连接（数百到数千）
  • 读写比例通常在 7:3 到 9:1
  • 对延迟敏感，要求快速响应
  • 数据一致性要求高

使用方法

oltp.yml 是默认模板，无需显式指定：

pg-oltp:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
  vars:
    pg_cluster: pg-oltp
    # pg_conf: oltp.yml  # PostgreSQL 配置模板（默认值）
    # node_tune: oltp    # 操作系统调优模板（默认值）

或显式指定：

pg-oltp:
  vars:
    pg_conf: oltp.yml    # PostgreSQL 配置模板
    node_tune: oltp      # 操作系统调优模板

参数详解

连接管理 

max_connections: 500/1000   # 取决于是否使用 pgbouncer
superuser_reserved_connections: 10
  • 当 pg_default_service_dest 为 pgbouncer 时，max_connections 设为 500
  • 当流量直连 PostgreSQL 时，max_connections 设为 1000
  • 可通过 pg_max_conn 参数覆盖

内存配置

OLTP 模板的内存分配策略：

参数 计算公式 说明
shared_buffers 内存 × pg_shared_buffer_ratio 默认比例 0.25
maintenance_work_mem shared_buffers × 25% 用于 VACUUM、CREATE INDEX
work_mem 64MB - 1GB 根据 shared_buffers/max_connections 计算
effective_cache_size 总内存 - shared_buffers 可用于缓存的预估内存

work_mem 计算逻辑：

work_mem = min(max(shared_buffers / max_connections, 64MB), 1GB)

这确保每个连接有足够的排序/哈希内存，但不会过度分配。

并行查询

OLTP 模板对并行查询做了适度限制，以避免并行查询抢占过多资源影响其他事务：

max_worker_processes: max(cpu + 16, 24)
max_parallel_workers: 50% × cpu (最小2)
max_parallel_workers_per_gather: 20% × cpu (2-8)
max_parallel_maintenance_workers: 33% × cpu (最小2)

同时提高了并行查询的成本估算，让优化器倾向于串行执行：

parallel_setup_cost: 2000      # 默认值 1000 的两倍
parallel_tuple_cost: 0.2       # 默认值 0.1 的两倍
min_parallel_table_scan_size: 32MB   # 默认值 8MB 的四倍，倾向于不使用并行扫描
min_parallel_index_scan_size: 2MB    # 默认值 512kB 的四倍，倾向于不使用并行扫描

WAL 配置 

min_wal_size: 磁盘/20 (实际最大100GB)
max_wal_size: 磁盘/5 (实际最大400GB)
max_slot_wal_keep_size: 磁盘×3/10 (实际最大600GB)
wal_buffers: 16MB
wal_writer_delay: 20ms
wal_writer_flush_after: 1MB
commit_delay: 20
commit_siblings: 10
checkpoint_timeout: 15min
checkpoint_completion_target: 0.80

这些设置平衡了数据安全性和写入性能。

Vacuum 配置 

vacuum_cost_delay: 20ms         # 每轮 vacuum 后休眠
vacuum_cost_limit: 2000         # 每轮 vacuum 的代价上限
autovacuum_max_workers: 3
autovacuum_naptime: 1min
autovacuum_vacuum_scale_factor: 0.08    # 8% 表变化触发 vacuum
autovacuum_analyze_scale_factor: 0.04   # 4% 表变化触发 analyze
autovacuum_freeze_max_age: 1000000000

OLTP 模板使用保守的 vacuum 设置，避免 vacuum 操作影响在线事务性能。

查询优化 

random_page_cost: 1.1           # SSD 优化
effective_io_concurrency: 200   # SSD 并发 IO
default_statistics_target: 400  # 统计信息精度

这些设置让优化器能够生成更好的查询计划。

日志与监控 

log_min_duration_statement: 100         # 记录超过 100ms 的慢查询
log_statement: ddl                      # 记录 DDL 语句
log_checkpoints: on
log_lock_waits: on
log_temp_files: 1024                    # 记录超过 1MB 的临时文件
log_autovacuum_min_duration: 1s
track_io_timing: on
track_functions: all
track_activity_query_size: 8192

客户端超时 

deadlock_timeout: 50ms
idle_in_transaction_session_timeout: 10min

10 分钟的空闲事务超时可以防止长时间持有锁的僵尸事务。

扩展配置 

shared_preload_libraries: 'pg_stat_statements, auto_explain'

# auto_explain
auto_explain.log_min_duration: 1s
auto_explain.log_analyze: on
auto_explain.log_verbose: on
auto_explain.log_timing: on
auto_explain.log_nested_statements: true

# pg_stat_statements
pg_stat_statements.max: 10000
pg_stat_statements.track: all
pg_stat_statements.track_utility: off
pg_stat_statements.track_planning: off

与其他模板的对比

特性 OLTP OLAP CRIT
max_connections 500-1000 500 500-1000
work_mem 64MB-1GB 64MB-8GB 64MB-1GB
并行查询 适度限制 激进启用 禁用
vacuum 激进度 保守 激进 保守
事务超时 10min 禁用 1min
慢查询阈值 100ms 1000ms 100ms

为什么选择 OLTP 而非 OLAP？

  • 您的查询大多数是简单的点查和范围查询
  • 事务响应时间要求在毫秒级
  • 有大量并发连接
  • 不需要执行复杂的分析查询

为什么选择 OLTP 而非 CRIT？

  • 可以接受极小概率的数据丢失（异步复制）
  • 不需要完整的审计日志
  • 希望获得更好的写入性能

性能调优建议

连接池

对于高并发场景，强烈建议使用 PgBouncer 连接池：

pg-oltp:
  vars:
    pg_default_service_dest: pgbouncer  # 默认值
    pgbouncer_poolmode: transaction     # 事务级池化

只读分离

使用只读从库分担读取负载：

pg-oltp:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
    10.10.10.13: { pg_seq: 3, pg_role: replica }

监控指标

关注以下监控指标：

  • 连接数：活跃连接数、等待连接数
  • 事务率：TPS、提交/回滚比例
  • 响应时间：查询延迟百分位（p50/p95/p99）
  • 锁等待：锁等待时间、死锁次数
  • 复制延迟：从库延迟时间和字节数

参考资料

15.3 - OLAP 模板

针对在线分析处理负载优化的 PostgreSQL 配置模板

olap.yml 是针对 在线分析处理（OLAP）负载优化的配置模板。适用于 4-128 核 CPU 的服务器，特点是支持大查询、高并行度、宽松的超时设置和激进的 Vacuum 策略。

建议同时使用 node_tune = olap 进行操作系统级别的配套调优。

适用场景

OLAP 模板适用于以下场景：

  • 数据仓库：历史数据存储、多维分析
  • BI 报表：复杂报表查询、仪表盘数据源
  • ETL 处理：数据抽取、转换、加载
  • 数据分析：Ad-hoc 查询、数据探索
  • HTAP 混合负载：分析型从库

特征负载：

  • 复杂查询（秒级到分钟级）
  • 低并发连接（数十到数百）
  • 读密集型，写入通常是批量操作
  • 对吞吐量敏感，可以容忍较高延迟
  • 需要扫描大量数据

使用方法

在集群定义中指定 pg_conf = olap.yml：

pg-olap:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
  vars:
    pg_cluster: pg-olap
    pg_conf: olap.yml    # PostgreSQL 分析处理模板
    node_tune: olap      # 操作系统分析处理调优

也可以将 olap.yml 模板用于专用的离线从库：

pg-mixed:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
    10.10.10.13: { pg_seq: 3, pg_role: offline, pg_conf: olap.yml }  # 离线分析从库
  vars:
    pg_cluster: pg-mixed
    pg_conf: oltp.yml    # 主库和在线从库使用 OLTP 模板
    node_tune: oltp      # 操作系统 OLTP 调优

参数详解

连接管理 

max_connections: 500
superuser_reserved_connections: 10

OLAP 场景通常不需要大量连接，500 个连接足以应对大多数分析负载。

内存配置

OLAP 模板的内存分配策略更为激进：

参数 计算公式 说明
shared_buffers 内存 × pg_shared_buffer_ratio 默认比例 0.25
maintenance_work_mem shared_buffers × 50% 加速索引创建和 VACUUM
work_mem 64MB - 8GB 更大的排序/哈希内存
effective_cache_size 总内存 - shared_buffers 可用于缓存的预估内存

work_mem 计算逻辑（与 OLTP 不同）：

work_mem = min(max(shared_buffers / max_connections, 64MB), 8GB)

更大的 work_mem 允许更大的排序和哈希操作在内存中完成，避免磁盘溢出。

锁与事务 

max_locks_per_transaction: 2-4x maxconn   # OLTP 是 1-2x

OLAP 查询可能涉及更多表（分区表、大量 JOIN），因此需要更多的锁槽。

并行查询

OLAP 模板激进启用并行查询：

max_worker_processes: max(cpu + 20, 28)      # OLTP: max(cpu + 16, 24)
max_parallel_workers: 80% × cpu (最小2)      # OLTP: 50%
max_parallel_workers_per_gather: 50% × cpu   # OLTP: 20% (最大8)
max_parallel_maintenance_workers: 33% × cpu

并行查询成本保持默认值，让优化器更倾向于选择并行计划：

# parallel_setup_cost: 1000    # 默认值，不加倍
# parallel_tuple_cost: 0.1     # 默认值，不加倍

同时启用分区智能优化：

enable_partitionwise_join: on       # 分区表智能 JOIN
enable_partitionwise_aggregate: on  # 分区表智能聚合

IO 配置（PG18） 

io_workers: 50% × cpu (4-32)    # OLTP: 25% (4-16)

更多的 IO 工作线程支持并行扫描大表。

WAL 配置 

min_wal_size: 磁盘/20 (实际最大100GB)
max_wal_size: 磁盘/5 (实际最大400GB)
max_slot_wal_keep_size: 磁盘×3/10 (实际最大600GB)
temp_file_limit: 磁盘/5 (实际最大400GB)   # OLTP: 磁盘/20，实际最大100GB

更大的 temp_file_limit 允许更大的中间结果溢出到磁盘。

Vacuum 配置

OLAP 模板使用更激进的 vacuum 设置：

vacuum_cost_delay: 10ms         # OLTP: 20ms，更快的 vacuum
vacuum_cost_limit: 10000        # OLTP: 2000，每轮更多工作
autovacuum_max_workers: 3
autovacuum_naptime: 1min
autovacuum_vacuum_scale_factor: 0.08
autovacuum_analyze_scale_factor: 0.04

分析型数据库通常有大量批量写入，需要更激进的 vacuum 策略来回收空间。

查询优化 

random_page_cost: 1.1
effective_io_concurrency: 200
default_statistics_target: 1000    # OLTP: 400，更精确的统计信息

更高的 default_statistics_target 提供更精确的查询计划，对复杂分析查询尤为重要。

日志与监控 

log_min_duration_statement: 1000    # OLTP: 100ms，放宽慢查询阈值
log_statement: ddl
log_checkpoints: on
log_lock_waits: on
log_temp_files: 1024
log_autovacuum_min_duration: 1s
track_io_timing: on
track_cost_delay_timing: on         # PG18+，跟踪 vacuum 代价延迟
track_functions: all
track_activity_query_size: 8192

客户端超时 

deadlock_timeout: 50ms
idle_in_transaction_session_timeout: 0   # OLTP: 10min，禁用

分析查询可能需要长时间持有事务，因此禁用空闲事务超时。

与 OLTP 模板的主要差异

参数 OLAP OLTP 差异原因
max_connections 500 500-1000 分析负载连接数少
work_mem 上限 8GB 1GB 支持更大的内存排序
maintenance_work_mem 50% buffer 25% buffer 加速索引创建
max_locks_per_transaction 2-4x 1-2x 更多表参与查询
max_parallel_workers 80% cpu 50% cpu 激进并行
max_parallel_workers_per_gather 50% cpu 20% cpu 激进并行
parallel_setup_cost 1000 2000 默认值，鼓励并行
parallel_tuple_cost 0.1 0.2 默认值，鼓励并行
enable_partitionwise_join on off 分区表优化
enable_partitionwise_aggregate on off 分区表优化
vacuum_cost_delay 10ms 20ms 激进 vacuum
vacuum_cost_limit 10000 2000 激进 vacuum
temp_file_limit 1/5 磁盘 1/20 磁盘 允许更大临时文件
io_workers 50% cpu 25% cpu 更多并行 IO
log_min_duration_statement 1000ms 100ms 放宽慢查询阈值
default_statistics_target 1000 400 更精确统计
idle_in_transaction_session_timeout 禁用 10min 允许长事务

性能调优建议

结合 TimescaleDB

OLAP 模板与 TimescaleDB 配合使用效果极佳：

pg-timeseries:
  vars:
    pg_conf: olap.yml
    pg_libs: 'timescaledb, pg_stat_statements, auto_explain'
    pg_extensions:
      - timescaledb

结合 pg_duckdb

对于极致的分析性能，可以结合 pg_duckdb：

pg-analytics:
  vars:
    pg_conf: olap.yml
    pg_libs: 'pg_duckdb, pg_stat_statements, auto_explain'

列式存储

考虑使用 Citus 的列式存储或 pg_mooncake：

pg_extensions:
  - citus_columnar  # 或 pg_mooncake

资源隔离

对于混合负载，建议将分析查询隔离到专用从库：

pg-mixed:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }               # OLTP 写入
    10.10.10.12: { pg_seq: 2, pg_role: replica }               # OLTP 读取
    10.10.10.13: { pg_seq: 3, pg_role: offline }               # OLAP 分析
  vars:
    pg_cluster: pg-mixed

监控指标

关注以下监控指标：

  • 查询时间：长查询的执行时间分布
  • 并行度：并行工作进程的使用率
  • 临时文件：临时文件的大小和数量
  • 磁盘 IO：顺序扫描和索引扫描的 IO 量
  • 缓存命中率：shared_buffers 和 OS 缓存的命中率

参考资料

15.4 - CRIT 模板

面向一致性优先业务的 PostgreSQL 参数模板，启用严格同步复制、数据校验和详细连接日志。

crit.yml 面向一致性和审计要求较高的事务型业务。它强制启用数据校验和与 Patroni 严格同步模式，增加连接日志，并调整部分 WAL、超时和并行查询参数。

该模板会增加写入延迟，并可能在没有可用同步副本时阻塞写入。使用前应确认一致性目标、故障域、客户端提交设置和可用性要求。

建议同时评估 node_tune: crit，但主机调优与数据库参数可以独立选择。

使用方法 

pg-critical:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
    10.10.10.13: { pg_seq: 3, pg_role: replica }
  vars:
    pg_cluster: pg-critical
    pg_conf: crit.yml
    node_tune: crit

三节点拓扑可以在一个节点故障后保留重新选择同步副本的空间，但是否持续可写还取决于剩余节点状态、DCS、网络和同步副本选择。应在目标拓扑上执行故障演练。

严格同步复制

CRIT 不使用 pg_rpo 推导同步模式，而是固定启用：

synchronous_mode: true
synchronous_mode_strict: true

synchronous_mode_strict 禁止 Patroni 在没有同步副本时自动退回异步复制，因此主库会阻塞需要同步确认的写入。

在以下前提下，该模式以不丢失已确认事务为目标：

  • 会话没有将 synchronous_commit 降低为 local、off 等异步级别；
  • 提交时同步副本正常确认 WAL；
  • 故障切换只选择包含所需 WAL 的合格节点。

因此，RPO 结论必须结合客户端参数、复制状态和故障模型验证，不能只根据模板名称确定。

需要多个同步副本确认时，可以通过 Patroni 动态配置设置：

pg edit-config pg-critical
synchronous_node_count: 2

同步副本数量越多，可接受写入的节点条件越严格。

数据校验和

CRIT 初始化配置始终包含：

initdb:
  - data-checksums

这会忽略 pg_checksum 的关闭设置，并为新集群启用页级校验和。校验和用于发现写入后发生的页面损坏，不检测逻辑错误或所有内存错误。

连接与查询日志

CRIT 记录 DDL、执行时间超过 100 ms 的语句和连接断开事件：

log_statement: ddl
log_min_duration_statement: 100
log_disconnections: 'on'

PostgreSQL 18 及以上版本使用：

log_connections: 'receipt,authentication,authorization'

较早版本使用 log_connections: on。这些日志可以支持连接审计，但不等同于 SQL 细粒度审计。需要记录对象读写、角色或语句类别时，应另行启用 pgaudit。

track_activity_query_size 设置为 32 KiB，以保留更长的活动查询文本。日志可能包含 SQL 和业务数据，应限制访问并设置合适的保留周期。

Watchdog

CRIT 会将默认关闭的 Patroni watchdog 模式转换为 automatic：

watchdog:
  mode: automatic
  device: /dev/watchdog

automatic 仅在系统存在可用 watchdog 设备时启用。需要强制 fencing 时，应确认硬件、虚拟化平台和设备权限后显式使用 required；配置错误会影响主库启动和故障切换。

主要参数差异

参数 CRIT OLTP 默认 影响
synchronous_mode 固定启用 由 pg_rpo 推导 一致性优先
synchronous_mode_strict true 按通用模板 无同步副本时阻塞写入
data-checksums 强制启用 由 pg_checksum 控制 页面损坏检测
max_parallel_workers_per_gather 0 根据 CPU 计算 降低并行查询波动
wal_writer_delay 10ms 20ms 更频繁处理 WAL
wal_writer_flush_after 0 1MB 改变 WAL 刷写行为
idle_replication_slot_timeout 3d 7d 更快清理闲置复制槽
idle_in_transaction_session_timeout 1min 10min 更快终止空闲事务
track_activity_query_size 32KiB 8KiB 保留更长查询文本
log_connections 详细连接事件 PostgreSQL 18 默认记录授权 增加连接审计信息
log_disconnections on off 记录断开事件

CRIT 还会禁用单个查询的并行 gather，并调整并行成本、autovacuum、WAL 和统计参数。完整值以实际版本的 roles/pgsql/templates/crit.yml 为准。

预加载扩展

CRIT 使用 pg_libs 生成 shared_preload_libraries。由于角色默认值已经将 pg_libs 设置为：

pg_libs: 'pg_stat_statements, auto_explain'

单独选择 crit.yml 不会自动加载 passwordcheck。需要口令复杂度检查时应显式配置：

pg_libs: '$libdir/passwordcheck, pg_stat_statements, auto_explain'

ha/safe 已包含该覆盖值。需要 pgaudit 时，也应显式加入 pg_libs 并配置审计范围：

pg_libs: '$libdir/passwordcheck, pg_stat_statements, auto_explain, pgaudit'
pg_parameters:
  pgaudit.log: 'ddl, role, write'

性能与可用性影响

  • 同步提交需要等待同步副本，写入延迟至少包含副本网络与 WAL 持久化时间；
  • 严格同步模式在没有可用同步副本时阻塞写入；
  • 禁用并行 gather 可能降低大型查询吞吐，但减少并行执行造成的资源波动；
  • 更详细的日志和统计会增加 I/O、CPU 与存储占用；
  • 更短的空闲事务超时可能终止长时间保持事务但未执行语句的应用会话。

影响大小取决于硬件、网络、查询和客户端行为，应使用实际负载测试，不宜采用固定的延迟或吞吐百分比。

上线检查

  • 至少部署一个可用同步副本，并验证节点故障时的写入行为
  • 检查应用是否修改 synchronous_commit
  • 根据可用性要求选择 watchdog automatic 或 required
  • 验证连接日志的采集、访问权限和保留周期
  • 需要口令检查或 SQL 审计时，显式配置 pg_libs 和扩展参数
  • 使用生产负载测试写入延迟、吞吐和空闲事务超时
  • 执行主库、同步副本、DCS 和网络分区故障演练

相关文档

15.5 - TINY 模板

针对微型实例和资源受限环境优化的 PostgreSQL 配置模板

tiny.yml 是针对 微型实例 和资源受限环境优化的配置模板。适用于 1-3 核 CPU 的服务器，特点是最小化资源占用、保守的内存分配、禁用并行查询。

建议同时使用 node_tune = tiny 进行操作系统级别的配套调优。

适用场景

TINY 模板适用于以下场景：

  • 开发测试：本地开发环境、CI/CD 测试
  • 低配虚拟机：1-2 核 CPU、1-4GB 内存的云主机
  • 边缘计算：树莓派、嵌入式设备
  • Demo 演示：快速体验 Pigsty 功能
  • 个人项目：资源有限的个人博客、小型应用

资源限制：

  • 1-3 核 CPU
  • 1-8 GB 内存
  • 有限的磁盘空间
  • 可能与其他服务共享资源

使用方法

在集群定义中指定 pg_conf = tiny.yml：

pg-dev:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-dev
    pg_conf: tiny.yml    # PostgreSQL 微型实例模板
    node_tune: tiny      # 操作系统微型实例调优

单节点开发环境：

pg-local:
  hosts:
    127.0.0.1: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-local
    pg_conf: tiny.yml    # PostgreSQL 微型实例模板
    node_tune: tiny      # 操作系统微型实例调优

参数详解

连接管理 

max_connections: 250   # OLTP: 500-1000，减少连接开销
superuser_reserved_connections: 10

微型实例不需要处理大量并发连接，250 个连接足以应对开发测试场景。

内存配置

TINY 模板使用保守的内存分配策略：

参数 计算公式 说明
shared_buffers 内存 × pg_shared_buffer_ratio 默认比例 0.25
maintenance_work_mem shared_buffers × 25% 用于 VACUUM、CREATE INDEX
work_mem 16MB - 256MB 更小的排序/哈希内存
effective_cache_size 总内存 - shared_buffers 可用于缓存的预估内存

work_mem 计算逻辑（与 OLTP 不同）：

work_mem = min(max(shared_buffers / max_connections, 16MB), 256MB)

更小的 work_mem 上限（256MB vs OLTP 的 1GB）避免内存溢出。

并行查询（完全禁用）

TINY 模板完全禁用了并行查询：

max_worker_processes: max(cpu + 12, 20)     # OLTP: max(cpu + 16, 24)
max_parallel_workers: 50% × cpu (最小1)      # OLTP: 50% (最小2)
max_parallel_workers_per_gather: 0           # 禁用并行查询
max_parallel_maintenance_workers: 33% × cpu (最小1)

max_parallel_workers_per_gather: 0 确保查询不会启动并行工作进程，避免在低核心环境下争抢资源。

IO 配置（PG18） 

io_workers: 3   # 固定值，OLTP: 25% cpu (4-16)

固定的低 IO 工作线程数量，适合资源受限环境。

Vacuum 配置 

vacuum_cost_delay: 20ms
vacuum_cost_limit: 2000
autovacuum_max_workers: 2          # OLTP: 3，减少一个工作进程
autovacuum_naptime: 1min
# autovacuum_vacuum_scale_factor 使用默认值
# autovacuum_analyze_scale_factor 使用默认值

减少 autovacuum 工作进程数量，降低后台资源占用。

查询优化 

random_page_cost: 1.1
effective_io_concurrency: 200
default_statistics_target: 200     # OLTP: 400，降低统计精度以节省空间

较低的 default_statistics_target 减少 pg_statistic 表的大小。

日志配置 

log_min_duration_statement: 100    # 与 OLTP 相同
log_statement: ddl
log_checkpoints: on
log_lock_waits: on
log_temp_files: 1024
# log_connections 使用默认设置（不额外记录）

TINY 模板不启用额外的连接日志，以减少日志量。

客户端超时 

deadlock_timeout: 50ms
idle_in_transaction_session_timeout: 10min   # 与 OLTP 相同

扩展配置 

shared_preload_libraries: 'pg_stat_statements, auto_explain'

pg_stat_statements.max: 2500      # OLTP: 10000，减少内存占用
pg_stat_statements.track: all
pg_stat_statements.track_utility: off
pg_stat_statements.track_planning: off

pg_stat_statements.max 从 10000 降到 2500，减少约 75% 的内存占用。

与 OLTP 模板的主要差异

参数 TINY OLTP 差异原因
max_connections 250 500-1000 减少连接开销
work_mem 上限 256MB 1GB 避免内存溢出
max_worker_processes max(cpu+12, 20) max(cpu+16, 24) 减少后台进程
max_parallel_workers_per_gather 0 20% cpu 禁用并行查询
autovacuum_max_workers 2 3 减少后台负载
default_statistics_target 200 400 节省空间
pg_stat_statements.max 2500 10000 减少内存占用
io_workers 3 25% cpu 固定低值

资源估算

以下是 TINY 模板在不同配置下的资源使用估算：

1 核 1GB 内存 

shared_buffers: ~256MB
work_mem: ~16MB
maintenance_work_mem: ~64MB
max_connections: 250
max_worker_processes: 20

PostgreSQL 进程内存占用：约 400-600MB

2 核 4GB 内存 

shared_buffers: ~1GB
work_mem: ~32MB
maintenance_work_mem: ~256MB
max_connections: 250
max_worker_processes: 20

PostgreSQL 进程内存占用：约 1.5-2GB

4 核 8GB 内存

此配置建议使用 OLTP 模板而非 TINY 模板：

pg-small:
  vars:
    pg_conf: oltp.yml   # 4核8GB可以使用OLTP模板

性能调优建议

进一步减少资源

如果资源极度受限，可以考虑：

pg_parameters:
  max_connections: 100           # 进一步减少
  shared_buffers: 128MB          # 进一步减少
  maintenance_work_mem: 32MB
  work_mem: 8MB

禁用不需要的扩展 

pg_libs: 'pg_stat_statements'    # 只保留必要扩展

关闭不需要的功能 

pg_parameters:
  track_io_timing: off           # 禁用 IO 时间跟踪
  track_functions: none          # 禁用函数跟踪

使用外部连接池

即使在微型实例上，使用 PgBouncer 也能显著提高并发能力：

pg-tiny:
  vars:
    pg_conf: tiny.yml
    pg_default_service_dest: pgbouncer
    pgbouncer_poolmode: transaction

云平台推荐规格

AWS

  • t3.micro：1 vCPU, 1GB RAM - 适合 TINY
  • t3.small：2 vCPU, 2GB RAM - 适合 TINY
  • t3.medium：2 vCPU, 4GB RAM - 可考虑 OLTP

阿里云

  • ecs.t6-c1m1.small：1 vCPU, 1GB RAM - 适合 TINY
  • ecs.t6-c1m2.small：1 vCPU, 2GB RAM - 适合 TINY
  • ecs.t6-c1m4.small：1 vCPU, 4GB RAM - 适合 TINY

腾讯云

  • SA2.SMALL1：1 vCPU, 1GB RAM - 适合 TINY
  • SA2.SMALL2：1 vCPU, 2GB RAM - 适合 TINY
  • SA2.SMALL4：1 vCPU, 4GB RAM - 适合 TINY

边缘设备部署

树莓派 4 

pg-pi:
  hosts:
    192.168.1.100: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-pi
    pg_conf: tiny.yml       # PostgreSQL 微型实例模板
    node_tune: tiny         # 操作系统微型实例调优
    pg_storage_type: SSD    # 建议使用 SSD 存储

Docker 容器 

pg-docker:
  hosts:
    172.17.0.2: { pg_seq: 1, pg_role: primary }
  vars:
    pg_cluster: pg-docker
    pg_conf: tiny.yml       # PostgreSQL 微型实例模板
    node_tune: tiny         # 操作系统微型实例调优

升级到 OLTP

当您的应用增长，需要更多资源时，可以轻松升级到 OLTP 模板：

  1. 升级虚拟机规格（4核 8GB 以上）
  2. 修改集群配置：
pg-growing:
  vars:
    pg_conf: oltp.yml    # 从 tiny.yml 改为 oltp.yml
    node_tune: oltp      # 从 tiny 改为 oltp
  1. 重新配置集群 或重新部署

参考资料

16 - 常见问题

PostgreSQL 常见问题答疑

我当前执行安装的用户为何不能使用 pg 管理别名？

从 Pigsty v4.0 开始，使用 pg 管理别名管理全局的 Patroni / PostgreSQL 集群的权限被收紧到了管理节点上的管理员分组（admin）。

node.yml 剧本创建的管理员（dba）默认具有此权限，而其他用户如果想要获得这个权限，需要你显式地将该用户加入到 admin 组中。

sudo usermod -aG admin <username>

PGSQL初始化失败：Fail to wait for postgres/patroni primary

这种错误信息存在多种可能，需要你 检查 Ansible，Systemd / Patroni / PostgreSQL 日志，找出真正的原因。

  • 可能性1：集群配置错误，找出错误的配置项修改并应用。
  • 可能性2：在部署中存在同名集群，或者之前的同名集群主节点被不正确地移除
  • 可能性3：在 DCS 中有同名集群残留的垃圾元数据。先用 etcdctl get --prefix /pg/<cls>/ 核对精确键空间；确认备份与完整集群名后，才可用 etcdctl del --prefix /pg/<cls>/ 清理。末尾 / 是边界，不能省略，否则会同时匹配名称以该集群名开头的其他集群。这是破坏性操作，优先使用受控的下线流程。
  • 可能性4：你的 PostgreSQL 或节点相关 RPM 包没有被成功安装
  • 可能性5：你的 Watchdog 内核模块没有正确启用加载
  • 可能性6：你在初始化数据库时指定的语言 Locale 不存在（例如，使用了 en_US.UTF8，但没有安装英文语言包或 Locale 支持）
  • 如果你遇到了其他的原因，欢迎提交 Issue 或向社区求助。

PGSQL初始化失败：Fail to wait for postgres/patroni replica

存在几种可能的原因：

立即失败：通常是由于配置错误、网络问题、损坏的 DCS 元数据等原因。你必须检查 /pg/log 找出实际原因。

过了一会儿失败：这可能是由于源实例数据损坏。查看 PGSQL FAQ：如何在数据损坏时创建副本？

过了很长时间再超时：如果 wait for postgres replica 任务耗时 30 分钟或更长时间并由于超时而失败，这对于大型集群（例如，1TB+，可能需要几小时创建一个副本）是很常见的。

在这种情况下，底层创建副本的过程仍在进行。你可以使用 pg list <cls> 检查集群状态并等待副本赶上主节点。然后使用以下命令继续以下任务，完成完整的从库初始化：

./pgsql.yml -t pg_hba,pg_reload,pg_backup,pgbouncer,pg_vip,pg_dns,pg_service,pg_exporter,pg_register -l <problematic_replica>

PGSQL初始化失败：ABORT due to pg_safeguard enabled

这意味着正准备清理的 PostgreSQL 实例打开了防误删保险， 禁用 pg_safeguard 以移除 Postgres 实例。

如果防误删保险 pg_safeguard 打开，那么你就不能使用 bin/pgsql-rm 和 pgsql-rm.yml 剧本移除正在运行的 PGSQL 实例了。

要禁用 pg_safeguard，你可以在配置清单中将 pg_safeguard 设置为 false，或者在执行剧本时使用命令参数 -e pg_safeguard=false。

./pgsql-rm.yml -e pg_safeguard=false -l <cls_to_remove>    # 强制覆盖 pg_safeguard

如何确保故障转移中数据不丢失？

使用 crit.yml 参数模板，设置 pg_rpo 为 0，或 配置集群 为同步提交模式。

考虑使用 同步备库 和 法定多数提交 来确保故障转移过程中的零数据丢失。

更多细节，可以参考 安全考量 - 可用性 的相关介绍。

磁盘写满了如何抢救？

如果磁盘写满了，连 Shell 命令都无法执行，rm -rf /pg/dummy 可以释放一些救命空间。

默认情况下，pg_dummy_filesize 设置为 64MB。在生产环境中，建议将其增加到 8GB 或更大。

它将被放置在 PGSQL 主数据磁盘上的 /pg/dummy 路径下。你可以删除该文件以释放一些紧急空间：

至少可以让你在该节点上运行一些 shell 脚本来进一步回收其他空间（例如日志/WAL，过时数据，WAL 归档与备份）。

当集群数据已经损坏时如何创建副本？

Pigsty 在所有实例的 patroni 配置中设置了 clonefrom: true 标签，标记该实例可用于创建副本。

如果某个实例有损坏的数据文件，导致创建新副本的时候出错中断，那么你可以设置 clonefrom: false 来避免从损坏的实例中拉取数据。具体操作如下

$ vi /etc/patroni/patroni.yml

tags:
  nofailover: false
  clonefrom: true      # ----------> change to false
  noloadbalance: false
  nosync: false
  version:  '18'
  spec: '4C.8G.50G'
  conf: 'oltp.yml'
  
$ systemctl reload patroni    # 重新加载 Patroni 配置

PostgreSQL 监控的性能损耗如何？

一个常规 PostgreSQL 实例抓取耗时大约 200ms。抓取间隔默认为 10 秒，对于一个生产多核数据库实例来说几乎微不足道。

请注意，Pigsty 默认开启了库内对象监控，所以如果您的数据库内有数以十万计的表/索引对象，抓取可能耗时会增加到几秒。

您可以修改 Prometheus 的抓取频率，请确保一点：抓取周期应当显著高于一次抓取的时长。

如何监控一个现存的 PostgreSQL 实例？

在 PGSQL Monitor 中提供了详细的监控配置说明。

如何手工从监控中移除 PostgreSQL 监控目标？ 

./pgsql-rm.yml -t rm_metrics -l <cls>     # 将集群 'cls' 的所有实例从 victoria 中移除
bin/pgmon-rm <ins>     # 用于从 Victoria 中移除单个实例 'ins' 的监控对象，特别适合移除添加的外部实例

17 - 其他说明

其他说明与杂项文档

17.1 - 用户/角色

用户/角色指的是使用 SQL 命令 CREATE USER/ROLE 创建的，数据库集簇内的逻辑对象。

在这里的上下文中，用户指的是使用 SQL 命令 CREATE USER/ROLE 创建的，数据库集簇内的逻辑对象。

在 PostgreSQL 中，用户直接隶属于数据库集簇而非某个具体的数据库。因此在创建业务数据库和业务用户时，应当遵循"先用户，后数据库"的原则。

定义用户

Pigsty 通过两个配置参数定义数据库集群中的角色与用户：

  • pg_default_roles：定义全局统一使用的角色和用户
  • pg_users：在数据库集群层面定义业务用户和角色

前者用于定义了整套环境中共用的角色与用户，后者定义单个集群中特有的业务角色与用户。二者形式相同，均为用户定义对象的数组。

你可以定义多个用户/角色，它们会按照先全局，后集群，最后按数组内排序的顺序依次创建，所以后面的用户可以属于前面定义的角色。

下面是 Pigsty 演示环境中默认集群 pg-meta 中的业务用户定义：

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_users:
      - {name: dbuser_meta     ,password: DBUser.Meta     ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: pigsty admin user }
      - {name: dbuser_view     ,password: DBUser.Viewer   ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer for meta database }
      - {name: dbuser_grafana  ,password: DBUser.Grafana  ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for grafana database    }
      - {name: dbuser_bytebase ,password: DBUser.Bytebase ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for bytebase database   }
      - {name: dbuser_kong     ,password: DBUser.Kong     ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for kong api gateway    }
      - {name: dbuser_gitea    ,password: DBUser.Gitea    ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for gitea service       }
      - {name: dbuser_wiki     ,password: DBUser.Wiki     ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for wiki.js service     }
      - {name: dbuser_noco     ,password: DBUser.Noco     ,pgbouncer: true ,roles: [dbrole_admin]    ,comment: admin user for nocodb service      }

每个用户/角色定义都是一个 object，可能包括以下字段，以 dbuser_meta 用户为例：

- name: dbuser_meta               # 必需，`name` 是用户定义的唯一必选字段
  password: DBUser.Meta           # 可选，密码，可以是 scram-sha-256 哈希字符串或明文
  login: true                     # 可选，默认情况下可以登录
  superuser: false                # 可选，默认为 false，是超级用户吗？
  createdb: false                 # 可选，默认为 false，可以创建数据库吗？
  createrole: false               # 可选，默认为 false，可以创建角色吗？
  inherit: true                   # 可选，默认情况下，此角色可以使用继承的权限吗？
  replication: false              # 可选，默认为 false，此角色可以进行复制吗？
  bypassrls: false                # 可选，默认为 false，此角色可以绕过行级安全吗？
  pgbouncer: true                 # 可选，默认为 false，将此用户添加到 pgbouncer 用户列表吗？（使用连接池的生产用户应该显式定义为 true）
  connlimit: -1                   # 可选，用户连接限制，默认 -1 禁用限制
  expire_in: 3650                 # 可选，此角色过期时间：从创建时 + n天计算（优先级比 expire_at 更高）
  expire_at: '2030-12-31'         # 可选，此角色过期的时间点，使用 YYYY-MM-DD 格式的字符串指定一个特定日期（优先级没 expire_in 高）
  comment: pigsty admin user      # 可选，此用户/角色的说明与备注字符串
  roles: [dbrole_admin]           # 可选，默认角色为：dbrole_{admin,readonly,readwrite,offline}
  parameters: {}                  # 可选，使用 `ALTER ROLE SET` 针对这个角色，配置角色级的数据库参数
  pool_mode: transaction          # 可选，默认为 transaction 的 pgbouncer 池模式，用户级别
  pool_connlimit: 100             # 可选，用户级连接池最大连接数；省略时继承全局默认 100
  search_path: public             # 可选，根据 postgresql 文档的键值配置参数（例如：使用 pigsty 作为默认 search_path）
  • 唯一必需的字段是 name，它应该是 PostgreSQL 集群中的一个有效且唯一的用户名。
  • 角色不需要 password，但对于可登录的业务用户，通常是需要指定一个密码的。
  • password 可以是明文或 scram-sha-256 / md5 哈希字符串，请最好不要使用明文密码。
  • 用户/角色按数组顺序逐一创建，因此，请确保角色/分组的定义在成员之前。
  • login、superuser、createdb、createrole、inherit、replication、bypassrls 是布尔标志。
  • pgbouncer 默认是禁用的：要将业务用户添加到 pgbouncer 用户列表，您应当显式将其设置为 true。

ACL 系统

Pigsty 提供一套内置的访问控制 / ACL 模型，可以将默认业务角色分配给用户：

  • dbrole_readwrite：全局读写访问的角色（主属业务使用的生产账号应当具有数据库读写权限）
  • dbrole_readonly：全局只读访问的角色（如果别的业务想要只读访问，可以使用此角色）
  • dbrole_admin：拥有 DDL 权限的角色 （业务管理员，需要在应用中建表的场景）
  • dbrole_offline：独立的只读角色，通常用于个人查询、ETL 和分析任务；实例范围需要通过 HBA 显式限制

如果您希望重新设计您自己的 ACL 系统，可以考虑定制以下参数和模板：

创建用户

在 pg_default_roles 和 pg_users 中 定义 的用户和角色，将在集群初始化的 PROVISION 阶段中自动逐一创建。 如果您希望在现有的集群上 创建用户，可以使用 bin/pgsql-user 工具。 将新用户/角色定义添加到 all.children.<cls>.pg_users，并使用以下方法创建该数据库：

bin/pgsql-user <cls> <username>    # pgsql-user.yml -l <cls> -e username=<username>

不同于数据库，创建用户的剧本总是幂等的。当目标用户已经存在时，Pigsty 会修改目标用户的属性使其符合配置。所以在现有集群上重复运行它通常不会有问题。

请使用剧本创建用户

我们不建议您手工创建新的业务用户，特别当您想要创建的用户使用默认的 pgbouncer 连接池时：除非您愿意手工负责维护 Pgbouncer 中的用户列表并与 PostgreSQL 保持一致。 使用 bin/pgsql-user 工具或 pgsql-user.yml 剧本创建新数据库时，会将此数据库一并添加到 Pgbouncer用户 列表中。

修改用户

修改 PostgreSQL 用户的属性的方式与 创建用户 相同。

首先，调整您的用户定义，修改需要调整的属性，然后执行以下命令应用：

bin/pgsql-user <cls> <username>    # pgsql-user.yml -l <cls> -e username=<username>

请注意，修改用户不会删除用户，而是通过 ALTER USER 命令修改用户属性；也不会回收用户的权限与分组，并使用 GRANT 命令授予新的角色。

Pgbouncer用户

默认情况下启用 Pgbouncer，并作为连接池中间件，其用户默认被管理。

Pigsty 默认将 pg_users 中显式带有 pgbouncer: true 标志的所有用户添加到 pgbouncer 用户列表中。

Pgbouncer 连接池中的用户在 /etc/pgbouncer/userlist.txt 中列出：

"postgres" ""
"dbuser_wiki" "SCRAM-SHA-256$4096:+77dyhrPeFDT/TptHs7/7Q==$KeatuohpKIYzHPCt/tqBu85vI11o9mar/by0hHYM2W8=:X9gig4JtjoS8Y/o1vQsIX/gY1Fns8ynTXkbWOjUfbRQ="
"dbuser_view" "SCRAM-SHA-256$4096:DFoZHU/DXsHL8MJ8regdEw==$gx9sUGgpVpdSM4o6A2R9PKAUkAsRPLhLoBDLBUYtKS0=:MujSgKe6rxcIUMv4GnyXJmV0YNbf39uFRZv724+X1FE="
"dbuser_monitor" "SCRAM-SHA-256$4096:fwU97ZMO/KR0ScHO5+UuBg==$CrNsmGrx1DkIGrtrD1Wjexb/aygzqQdirTO1oBZROPY=:L8+dJ+fqlMQh7y4PmVR/gbAOvYWOr+KINjeMZ8LlFww="
"dbuser_meta" "SCRAM-SHA-256$4096:leB2RQPcw1OIiRnPnOMUEg==$eyC+NIMKeoTxshJu314+BmbMFpCcspzI3UFZ1RYfNyU=:fJgXcykVPvOfro2MWNkl5q38oz21nSl1dTtM65uYR1Q="
"dbuser_kong" "SCRAM-SHA-256$4096:bK8sLXIieMwFDz67/0dqXQ==$P/tCRgyKx9MC9LH3ErnKsnlOqgNd/nn2RyvThyiK6e4=:CDM8QZNHBdPf97ztusgnE7olaKDNHBN0WeAbP/nzu5A="
"dbuser_grafana" "SCRAM-SHA-256$4096:HjLdGaGmeIAGdWyn2gDt/Q==$jgoyOB8ugoce+Wqjr0EwFf8NaIEMtiTuQTg1iEJs9BM=:ed4HUFqLyB4YpRr+y25FBT7KnlFDnan6JPVT9imxzA4="
"dbuser_gitea" "SCRAM-SHA-256$4096:l1DBGCc4dtircZ8O8Fbzkw==$tpmGwgLuWPDog8IEKdsaDGtiPAxD16z09slvu+rHE74=:pYuFOSDuWSofpD9OZhG7oWvyAR0PQjJBffgHZLpLHds="
"dbuser_dba" "SCRAM-SHA-256$4096:zH8niABU7xmtblVUo2QFew==$Zj7/pq+ICZx7fDcXikiN7GLqkKFA+X5NsvAX6CMshF0=:pqevR2WpizjRecPIQjMZOm+Ap+x0kgPL2Iv5zHZs0+g="
"dbuser_bytebase" "SCRAM-SHA-256$4096:OMoTM9Zf8QcCCMD0svK5gg==$kMchqbf4iLK1U67pVOfGrERa/fY818AwqfBPhsTShNQ=:6HqWteN+AadrUnrgC0byr5A72noqnPugItQjOLFw0Wk="

而用户级别的连接池参数则是使用另一个单独的文件： /etc/pgbouncer/useropts.txt 进行维护，比如：

dbuser_dba                  = pool_mode=session max_user_connections=16
dbuser_monitor              = pool_mode=session max_user_connections=8

当您 创建数据库 时，Pgbouncer 的数据库列表定义文件将会被刷新，并通过在线重载配置的方式生效，不会影响现有的连接。

Pgbouncer 使用和 PostgreSQL 同样的 dbsu 运行，默认为 postgres 操作系统用户，您可以使用 pgb 别名，使用 dbsu 访问 pgbouncer 管理功能。

连接池用户配置文件 userlist.txt 与 useropts.txt 会在您 创建用户 时自动刷新，并通过在线重载配置的方式生效，正常不会影响现有的连接。

请注意，pgbouncer_auth_query 参数允许你使用动态查询来完成连接池用户认证，当您懒得管理连接池中的用户时，这是一种折中的方案。

17.2 - 数据库

数据库指的是使用 SQL 命令 CREATE DATABASE 创建的，数据库集簇内的逻辑对象。

在这里的上下文中，数据库指的是使用 SQL 命令 CREATE DATABASE 创建的，数据库集簇内的逻辑对象。

一组 PostgreSQL 服务器可以同时服务于多个 数据库 （Database）。在 Pigsty 中，你可以在集群配置中 定义 好所需的数据库。

Pigsty 会对默认模板数据库 template1 进行修改与定制，创建默认模式，安装默认扩展，配置默认权限，新创建的数据库默认会从 template1 继承这些设置。

默认情况下，所有业务数据库都会被1:1添加到 Pgbouncer 连接池中；pg_exporter 默认会通过 自动发现 机制查找所有业务数据库并进行库内对象监控。

定义数据库

业务数据库定义在数据库集群参数 pg_databases 中，这是一个数据库定义构成的对象数组。 数组内的数据库按照 定义顺序 依次创建，因此后面定义的数据库可以使用先前定义的数据库作为 模板。

下面是 Pigsty 演示环境中默认集群 pg-meta 中的数据库定义：

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_databases:
      - { name: meta ,baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [{name: postgis, schema: public}, {name: timescaledb}]}
      - { name: grafana  ,owner: dbuser_grafana  ,revokeconn: true ,comment: grafana primary database }
      - { name: bytebase ,owner: dbuser_bytebase ,revokeconn: true ,comment: bytebase primary database }
      - { name: kong     ,owner: dbuser_kong     ,revokeconn: true ,comment: kong the api gateway database }
      - { name: gitea    ,owner: dbuser_gitea    ,revokeconn: true ,comment: gitea meta database }
      - { name: wiki     ,owner: dbuser_wiki     ,revokeconn: true ,comment: wiki meta database }
      - { name: noco     ,owner: dbuser_noco     ,revokeconn: true ,comment: nocodb database }

每个数据库定义都是一个 object，可能包括以下字段，以 meta 数据库为例：

- name: meta                      # 必选，`name` 是数据库定义的唯一必选字段
  baseline: cmdb.sql              # 可选，数据库 sql 的基线定义文件路径（ansible 搜索路径中的相对路径，如 files/）
  pgbouncer: true                 # 可选，是否将此数据库添加到 pgbouncer 数据库列表？默认为 true
  schemas: [pigsty]               # 可选，要创建的附加模式，由模式名称字符串组成的数组
  extensions:                     # 可选，要安装的附加扩展： 扩展对象的数组
    - { name: postgis , schema: public }  # 可以指定将扩展安装到某个模式中，也可以不指定（不指定则安装到 search_path 首位模式中）
    - { name: timescaledb }               # 例如有的扩展会创建并使用固定的模式，就不需要指定模式。
  comment: pigsty meta database   # 可选，数据库的说明与备注信息
  owner: postgres                 # 可选，数据库所有者，默认为 postgres
  template: template1             # 可选，要使用的模板，默认为 template1，目标必须是一个模板数据库
  encoding: UTF8                  # 可选，数据库编码，默认为 UTF8（必须与模板数据库相同）
  locale: C                       # 可选，数据库地区设置，默认为 C（必须与模板数据库相同）
  lc_collate: C                   # 可选，数据库 collate 排序规则，默认为 C（必须与模板数据库相同），没有理由不建议更改。
  lc_ctype: C                     # 可选，数据库 ctype 字符集，默认为 C（必须与模板数据库相同）
  tablespace: pg_default          # 可选，默认表空间，默认为 'pg_default'
  allowconn: true                 # 可选，是否允许连接，默认为 true。显式设置 false 将完全禁止连接到此数据库
  revokeconn: false               # 可选，撤销公共连接权限。默认为 false，设置为 true 时，属主和管理员之外用户的 CONNECT 权限会被回收
  register_datasource: true       # 可选，是否将此数据库注册到 grafana 数据源？默认为 true，显式设置为 false 会跳过注册
  connlimit: -1                   # 可选，数据库连接限制，默认为 -1 ，不限制，设置为正整数则会限制连接数。
  pool_auth_user: dbuser_meta     # 可选，连接到此 pgbouncer 数据库的所有连接都将使用此用户进行验证（启用 pgbouncer_auth_query 才有用）
  pool_mode: transaction          # 可选，数据库级别的 pgbouncer 池化模式，默认为 transaction
  pool_size: 50                   # 可选，数据库级别的 pgbouncer 默认池子大小，默认为 50
  pool_reserve: 30                # 可选，数据库级别的 pgbouncer 池子保留空间，默认为 30，当默认池子不够用时，最多再申请这么多条突发连接。
  pool_size_min: 0                # 可选，数据库级别的 pgbouncer 池的最小大小，默认为 0
  pool_connlimit: 100           # 可选，数据库级别的最大数据库连接数，默认为 100

唯一必选的字段是 name，它应该是当前 PostgreSQL 集群中有效且唯一的数据库名称，其他参数都有合理的默认值。

  • name：数据库名称，必选项。
  • baseline：SQL 文件路径（Ansible 搜索路径，通常位于 files），用于初始化数据库内容。
  • owner：数据库属主，默认为 postgres
  • template：数据库创建时使用的模板，默认为 template1
  • encoding：数据库默认字符编码，默认为 UTF8，默认与实例保持一致。建议不要配置与修改。
  • locale：数据库默认的本地化规则，默认为 C，建议不要配置，与实例保持一致。
  • lc_collate：数据库默认的本地化字符串排序规则，默认与实例设置相同，建议不要修改，必须与模板数据库一致。强烈建议不要配置，或配置为 C。
  • lc_ctype：数据库默认的 LOCALE，默认与实例设置相同，建议不要修改或设置，必须与模板数据库一致。建议配置为 C 或 en_US.UTF8。
  • allowconn：是否允许连接至数据库，默认为 true，不建议修改。
  • revokeconn：是否回收连接至数据库的权限？默认为 false。如果为 true，则数据库上的 PUBLIC CONNECT 权限会被回收。只有默认用户（dbsu|monitor|admin|replicator|owner）可以连接。此外，admin|owner 会拥有 GRANT OPTION，可以赋予其他用户连接权限。
  • tablespace：数据库关联的表空间，默认为 pg_default。
  • connlimit：数据库连接数限制，默认为 -1，即没有限制。
  • extensions：对象数组，每一个对象定义了一个数据库中的 扩展，以及其安装的 模式。
  • parameters：KV 对象，每一个 KV 定义了一个需要针对数据库通过 ALTER DATABASE 修改的参数。
  • pgbouncer：布尔选项，是否将该数据库加入到 Pgbouncer 中。所有数据库都会加入至 Pgbouncer 列表，除非显式指定 pgbouncer: false。
  • comment：数据库备注信息。
  • pool_auth_user：启用 pgbouncer_auth_query 时，连接到此 pgbouncer 数据库的所有连接都将使用这里指定的用户执行认证查询。你需要使用一个具有访问 pg_shadow 表权限的用户。
  • pool_mode：数据库级别的 pgbouncer 池化模式，默认为 transaction，即事物池化。如果留空，会使用 pgbouncer_poolmode 参数作为默认值。
  • pool_size：数据库级别的 pgbouncer 默认池子大小，默认为 50
  • pool_reserve：数据库级别的 pgbouncer 池子保留空间，默认为 30，当默认池子不够用时，最多再申请这么多条突发连接。
  • pool_size_min： 数据库级别的 pgbouncer 池的最小大小，默认为 0
  • pool_connlimit： 数据库级别的 pgbouncer 连接池最大数据库连接数，默认为 100

新创建的数据库默认会从 template1 数据库 Fork 出来，这个模版数据库会在 PG_PROVISION 阶段进行定制修改： 配置好扩展，模式以及默认权限，因此新创建的数据库也会继承这些配置，除非您显式使用一个其他的数据库作为模板。

关于数据库访问权限，请参考 访问控制：数据库隔离。

创建数据库

在 pg_databases 中 定义 的数据库将在集群初始化时自动创建。 如果您希望在现有集群上 创建数据库，可以使用 bin/pgsql-db 包装脚本。 将新的数据库定义添加到 all.children.<cls>.pg_databases 中，并使用以下命令创建该数据库：

bin/pgsql-db <cls> <dbname>    # pgsql-db.yml -l <cls> -e dbname=<dbname>

下面是新建数据库时的一些注意事项：

创建数据库的剧本默认为幂等剧本，不过当您当使用 baseline 脚本时就不一定了：这种情况下，通常不建议在现有数据库上重复执行此操作，除非您确定所提供的 baseline SQL 也是幂等的。

我们不建议您手工创建新的数据库，特别当您使用默认的 pgbouncer 连接池时：除非您愿意手工负责维护 Pgbouncer 中的数据库列表并与 PostgreSQL 保持一致。 使用 pgsql-db 工具或 pgsql-db.yml 剧本创建新数据库时，会将此数据库一并添加到 Pgbouncer 数据库 列表中。

如果您的数据库定义有一个非常规 owner（默认为 dbsu postgres），那么请确保在创建该数据库前，属主用户已经存在。 最佳实践永远是在创建数据库之前 创建 用户。

Pgbouncer数据库

Pigsty 会默认为 PostgreSQL 实例 1:1 配置启用一个 Pgbouncer 连接池，使用 /var/run/postgresql Unix Socket 通信。

连接池可以优化短连接性能，降低并发征用，以避免过高的连接数冲垮数据库，并在数据库迁移时提供额外的灵活处理空间。

Pigsty 默认将 pg_databases 中的所有数据库都添加到 pgbouncer 的数据库列表中。 您可以通过在数据库 定义 中显式设置 pgbouncer: false 来禁用特定数据库的 pgbouncer 连接池支持。

Pgbouncer 数据库列表在 /etc/pgbouncer/database.txt 中定义，数据库定义中关于连接池的参数会体现在这里：

meta                        = host=/var/run/postgresql mode=session
grafana                     = host=/var/run/postgresql mode=transaction
bytebase                    = host=/var/run/postgresql auth_user=dbuser_meta
kong                        = host=/var/run/postgresql pool_size=32 reserve_pool=64
gitea                       = host=/var/run/postgresql min_pool_size=10
wiki                        = host=/var/run/postgresql
noco                        = host=/var/run/postgresql
mongo                       = host=/var/run/postgresql

当您 创建数据库 时，Pgbouncer 的数据库列表定义文件将会被刷新，并通过在线重载配置的方式生效，正常不会影响现有的连接。

Pgbouncer 使用和 PostgreSQL 同样的 dbsu 运行，默认为 postgres 操作系统用户，您可以使用 pgb 别名，使用 dbsu 访问 pgbouncer 管理功能。

若要把某个托管数据库的 Pgbouncer 流量切换到其他节点，应修改实际承载路由的 /etc/pgbouncer/database.txt，然后依次重载配置并重建已有服务端连接：

# 仅修改 mydb 的后端目标
sed -i -E '/^mydb[[:space:]]*=/ s#host=[^[:space:]]+#host=10.10.10.12#' /etc/pgbouncer/database.txt
pgb -c "RELOAD;"
pgb -c "RECONNECT mydb;"
pgb -c "WAIT_CLOSE mydb;"

当前源码附带的 pgb-route 函数只修改 /etc/pgbouncer/pgbouncer.ini，而 Pigsty 管理的数据库路由位于被该文件 include 的 database.txt 中，因此它不会改变这些托管路由；请勿用它替代上述操作。

17.3 - 服务/接入

分离读写操作，正确路由流量，稳定可靠地交付 PostgreSQL 集群提供的能力。

分离读写操作，正确路由流量，稳定可靠地交付 PostgreSQL 集群提供的能力。

服务 是一种抽象：它是数据库集群对外提供能力的形式，并封装了底层集群的细节。

服务对于生产环境中的 稳定接入 至关重要，在 高可用 集群自动故障时方显其价值，单机用户 通常不需要操心这个概念。

单机用户

“服务” 的概念是给生产环境用的，个人用户/单机集群可以不折腾，直接拿实例名/IP 地址访问数据库。

例如，Pigsty 默认的单节点 pg-meta.meta 数据库，就可以直接用下面三个不同的用户连接上去。

psql postgres://dbuser_dba:[email protected]/meta     # 直接用 DBA 超级用户连上去
psql postgres://dbuser_meta:[email protected]/meta   # 用默认的业务管理员用户连上去
psql postgres://dbuser_view:DBUser.Viewer@pg-meta/meta     # 用默认的只读用户走实例域名连上去

服务概述

在真实世界生产环境中，我们会使用基于复制的主从数据库集群。集群中有且仅有一个实例作为领导者（主库）可以接受写入。 而其他实例（从库）则会从持续从集群领导者获取变更日志，与领导者保持一致。同时，从库还可以承载只读请求，在读多写少的场景下可以显著分担主库的负担， 因此对集群的写入请求与只读请求进行区分，是一种十分常见的实践。

此外对于高频短连接的生产环境，我们还会通过连接池中间件（Pgbouncer）对请求进行池化，减少连接与后端进程的创建开销。但对于 ETL 与变更执行等场景，我们又需要绕过连接池，直接访问数据库。 同时，高可用集群在故障时会出现故障切换（Failover），故障切换会导致集群的领导者出现变更。因此高可用的数据库方案要求写入流量可以自动适配集群的领导者变化。 这些不同的访问需求（读写分离，池化与直连，故障切换自动适配）最终抽象出 服务 （Service）的概念。

通常来说，数据库集群都必须提供这种最基础的服务：

  • 读写服务（primary）：可以读写数据库

对于生产数据库集群，至少应当提供这两种服务：

  • 读写服务（primary）：写入数据：只能由主库所承载。
  • 只读服务（replica）：读取数据：可以由从库承载，没有从库时也可由主库承载

此外，根据具体的业务场景，可能还会有其他的服务，例如：

  • 默认直连服务（default）：允许（管理）用户，绕过连接池直接访问数据库的服务
  • 离线从库服务（offline）：不承接线上只读流量的专用从库，用于 ETL 与分析查询
  • 同步从库服务（standby）：没有复制延迟的只读服务，由 同步备库/主库处理只读查询
  • 延迟从库服务（delayed）：访问同一个集群在一段时间之前的旧数据，由 延迟从库 来处理

默认服务

Pigsty 默认为每个 PostgreSQL 数据库集群提供四种不同的服务，以下是默认服务及其定义：

服务 端口 描述
primary 5433 生产读写，连接到主库连接池（6432）
replica 5434 生产只读，连接到备库连接池（6432）
default 5436 管理，ETL 写入，直接访问主库（5432）
offline 5438 OLAP、ETL、个人用户、交互式查询

以默认的 pg-meta 集群为例，它提供四种默认服务：

psql postgres://dbuser_meta:DBUser.Meta@pg-meta:5433/meta   # pg-meta-primary : 通过主要的 pgbouncer(6432) 进行生产读写
psql postgres://dbuser_meta:DBUser.Meta@pg-meta:5434/meta   # pg-meta-replica : 通过备份的 pgbouncer(6432) 进行生产只读
psql postgres://dbuser_dba:DBUser.DBA@pg-meta:5436/meta     # pg-meta-default : 通过主要的 postgres(5432) 直接连接
psql postgres://dbuser_stats:DBUser.Stats@pg-meta:5438/meta # pg-meta-offline : 通过离线的 postgres(5432) 直接连接

从示例集群 架构图 上可以看出这四种服务的工作方式：

pigsty-ha.png

这里 pg-meta 的实际 DNS 目标由 pg_dns_target 决定：默认 auto 在启用 L2 VIP 时指向 VIP，否则指向清单中的主实例 IP。默认配置并不启用 VIP，详见 服务接入。

服务实现

在 Pigsty 中，服务使用 节点 上的 haproxy 来实现，通过主机节点上的不同端口进行区分。

Pigsty 所纳管的每个节点上都默认启用了 Haproxy 以对外暴露服务，而数据库节点也不例外。 集群中的节点尽管从数据库的视角来看有主从之分，但从服务的视角来看，每个节点都是相同的： 这意味着即使您访问的是从库节点，只要使用正确的服务端口，就依然可以使用到主库读写的服务。 这样的设计可以屏蔽复杂度：所以您只要可以访问 PostgreSQL 集群上的任意一个实例，就可以完整的访问到所有服务。

这样的设计类似于 Kubernetes 中的 NodePort 服务，同样在 Pigsty 中，每一个服务都包括以下两个核心要素：

  1. 通过 NodePort 暴露的访问端点（端口号，从哪访问？）
  2. 通过 Selectors 选择的目标实例（实例列表，谁来承载？）

Pigsty 的服务交付边界止步于集群的 HAProxy，用户可以用各种手段访问这些负载均衡器，请参考 接入服务。

所有的服务都通过配置文件进行声明，例如，PostgreSQL 默认服务就是由 pg_default_services 参数所定义的：

pg_default_services:
- { name: primary ,port: 5433 ,dest: default  ,check: /primary   ,selector: "[]" }
- { name: replica ,port: 5434 ,dest: default  ,check: /read-only ,selector: "[]" , backup: "[? pg_role == `primary` || pg_role == `offline` ]" }
- { name: default ,port: 5436 ,dest: postgres ,check: /primary   ,selector: "[]" }
- { name: offline ,port: 5438 ,dest: postgres ,check: /replica   ,selector: "[? pg_role == `offline` || pg_offline_query ]" , backup: "[? pg_role == `replica` && !pg_offline_query]"}

您也可以在 pg_services 中定义额外的服务，参数 pg_default_services 与 pg_services 都是由 服务定义 对象组成的数组。

定义服务

Pigsty 允许您定义自己的服务：

  • pg_default_services：所有 PostgreSQL 集群统一对外暴露的服务，默认有四个。
  • pg_services：额外的 PostgreSQL 服务，可以视需求在全局或集群级别定义。
  • haproxy_services：直接定制 HAProxy 服务内容，可以用于其他组件的接入

对于 PostgreSQL 集群来说，通常只需要关注前两者即可。 每一条服务定义都会在所有相关 HAProxy 实例的配置目录下生成一个新的配置文件：/etc/haproxy/conf.d/<pg_cluster>-<service>.cfg 下面是一个自定义的服务样例 standby：当您想要对外提供没有复制延迟的只读服务时，就可以在 pg_services 新增这条记录：

- name: standby                   # 必选，服务名称，最终的 svc 名称会使用 `pg_cluster` 作为前缀，例如：pg-meta-standby
  port: 5435                      # 必选，暴露的服务端口（作为 kubernetes 服务节点端口模式）
  ip: "*"                         # 可选，服务绑定的 IP 地址，默认情况下为所有 IP 地址
  selector: "[]"                  # 必选，服务成员选择器，使用 JMESPath 来筛选配置清单
  backup: "[? pg_role == `primary`]"  # 可选，服务成员选择器（备份），也就是当默认选择器选中的实例都宕机后，服务才会由这里选中的实例成员来承载
  dest: default                   # 可选，目标端口，default|postgres|pgbouncer|<port_number>，默认为 'default'，即由 pg_default_service_dest 决定
  check: /sync                    # 可选，健康检查 URL 路径，默认为 /，这里使用 Patroni API：/sync ，只有同步备库和主库才会返回 200 健康状态码 
  maxconn: 5000                   # 可选，允许的前端连接最大数，默认为5000
  balance: roundrobin             # 可选，haproxy 负载均衡算法（默认为 roundrobin，其他选项：leastconn）
  options: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'

而上面的服务定义，在样例的三节点 pg-test 上将会被转换为 HAProxy 配置文件 /etc/haproxy/conf.d/pg-test-standby.cfg：

#---------------------------------------------------------------------
# service: pg-test-standby @ 10.10.10.11:5435
#---------------------------------------------------------------------
# service instances 10.10.10.11, 10.10.10.13, 10.10.10.12
# service backups   10.10.10.11
listen pg-test-standby
    bind *:5435            # <--- 绑定了所有IP地址上的 5435 端口
    mode tcp               # <--- 负载均衡器工作在 TCP 协议上
    maxconn 5000           # <--- 最大连接数为 5000，可按需调大
    balance roundrobin     # <--- 负载均衡算法为 rr 轮询，还可以使用 leastconn 
    option httpchk         # <--- 启用 HTTP 健康检查
    option http-keep-alive # <--- 保持HTTP连接
    http-check send meth OPTIONS uri /sync   # <---- 这里使用 /sync ，Patroni 健康检查 API ，只有同步备库和主库才会返回 200 健康状态码。 
    http-check expect status 200             # <---- 健康检查返回代码 200 代表正常
    default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
    # servers： # pg-test 集群全部三个实例都被 selector: "[]" 圈中，成为 pg-test-standby 服务的后端；/sync 健康检查只放行主库和同步备库。
    server pg-test-1 10.10.10.11:6432 check port 8008 weight 100 backup  # <----- 唯独主库满足条件 pg_role == `primary`， 被 backup selector 选中。
    server pg-test-3 10.10.10.13:6432 check port 8008 weight 100         #        因此作为服务的兜底实例：平时不承载请求，其他从库全部宕机后，才会承载只读请求，从而最大避免了读写服务受到只读服务的影响
    server pg-test-2 10.10.10.12:6432 check port 8008 weight 100         #

在这里，pg-test 集群全部三个实例都被 selector: "[]" 给圈中了，渲染进入 pg-test-standby 服务的后端服务器列表中。但是因为还有 /sync 健康检查，Patroni Rest API 只有在主库和 同步备库 上才会返回代表健康的 HTTP 200 状态码，因此只有主库和同步备库才能真正承载请求。 此外，主库因为满足条件 pg_role == primary， 被 backup selector 选中，被标记为了备份服务器，只有当没有其他实例（也就是同步备库）可以满足需求时，才会顶上。

Primary服务

Primary 服务可能是生产环境中最关键的服务，它在 5433 端口提供对数据库集群的读写能力，服务定义如下：

- { name: primary ,port: 5433 ,dest: default  ,check: /primary   ,selector: "[]" }
  • 选择器参数 selector: "[]" 意味着所有集群成员都将被包括在 Primary 服务中
  • 但只有主库能够通过健康检查（check: /primary），实际承载 Primary 服务的流量。
  • 目的地参数 dest: default 意味着 Primary 服务的目的地受到 pg_default_service_dest 参数的影响
  • dest 默认值 default 会被替换为 pg_default_service_dest 的值，默认为 pgbouncer。
  • 默认情况下 Primary 服务的目的地默认是主库上的连接池，也就是由 pgbouncer_port 指定的端口，默认为 6432

如果 pg_default_service_dest 的值为 postgres，那么 primary 服务的目的地就会绕过连接池，直接使用 PostgreSQL 数据库的端口（pg_port，默认值 5432），对于一些不希望使用连接池的场景，这个参数非常实用。

示例：pg-test-primary 的 haproxy 配置
listen pg-test-primary
    bind *:5433         # <--- primary 服务默认使用 5433 端口
    mode tcp
    maxconn 5000
    balance roundrobin
    option httpchk
    option http-keep-alive
    http-check send meth OPTIONS uri /primary # <--- primary 服务默认使用 Patroni RestAPI /primary 健康检查
    http-check expect status 200
    default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
    # servers
    server pg-test-1 10.10.10.11:6432 check port 8008 weight 100
    server pg-test-3 10.10.10.13:6432 check port 8008 weight 100
    server pg-test-2 10.10.10.12:6432 check port 8008 weight 100

Patroni 的 高可用 机制确保任何时候最多只会有一个实例的 /primary 健康检查为真，因此 Primary 服务将始终将流量路由到主实例。

使用 Primary 服务而不是直连数据库的一个好处是，如果集群因为某种情况出现了双主（比如在没有 watchdog 的情况下 kill -9杀死主库 Patroni），Haproxy 在这种情况下仍然可以避免脑裂，因为它只会在 Patroni 存活且返回主库状态时才会分发流量。

Replica服务

Replica 服务在生产环境中的重要性仅次于 Primary 服务，它在 5434 端口提供对数据库集群的只读能力，服务定义如下：

- { name: replica ,port: 5434 ,dest: default  ,check: /read-only ,selector: "[]" , backup: "[? pg_role == `primary` || pg_role == `offline` ]" }
  • 选择器参数 selector: "[]" 意味着所有集群成员都将被包括在 Replica 服务中
  • 所有实例都能够通过健康检查（check: /read-only），承载 Replica 服务的流量。
  • 备份选择器：[? pg_role == 'primary' || pg_role == 'offline' ] 将主库和 离线从库 标注为备份服务器。
  • 只有当所有 普通从库 都宕机后，Replica 服务才会由主库或离线从库来承载。
  • 目的地参数 dest: default 意味着 Replica 服务的目的地也受到 pg_default_service_dest 参数的影响
  • dest 默认值 default 会被替换为 pg_default_service_dest 的值，默认为 pgbouncer，这一点和 Primary服务 相同
  • 默认情况下 Replica 服务的目的地默认是从库上的连接池，也就是由 pgbouncer_port 指定的端口，默认为 6432
示例：pg-test-replica 的 haproxy 配置
listen pg-test-replica
    bind *:5434
    mode tcp
    maxconn 5000
    balance roundrobin
    option httpchk
    option http-keep-alive
    http-check send meth OPTIONS uri /read-only
    http-check expect status 200
    default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
    # servers
    server pg-test-1 10.10.10.11:6432 check port 8008 weight 100 backup
    server pg-test-3 10.10.10.13:6432 check port 8008 weight 100
    server pg-test-2 10.10.10.12:6432 check port 8008 weight 100

Replica 服务非常灵活：如果有存活的专用 Replica 实例，那么它会优先使用这些实例来承载只读请求，只有当从库实例全部宕机后，才会由主库来兜底只读请求。对于常见的一主一从双节点集群就是：只要从库活着就用从库，从库挂了再用主库。

此外，除非专用只读实例全部宕机，Replica 服务也不会使用专用 Offline 实例，这样就避免了在线快查询与离线慢查询混在一起，相互影响。

Default服务

Default 服务在 5436 端口上提供服务，它是 Primary 服务的变体。

Default 服务总是绕过连接池直接连到主库上的 PostgreSQL，这对于管理连接、ETL 写入、CDC 数据变更捕获等都很有用。

- { name: default ,port: 5436 ,dest: postgres ,check: /primary   ,selector: "[]" }

如果 pg_default_service_dest 被修改为 postgres，那么可以说 Default 服务除了端口和名称内容之外，与 Primary 服务是完全等价的。在这种情况下，您可以考虑将 Default 从默认服务中剔除。

示例：pg-test-default 的 haproxy 配置
listen pg-test-default
    bind *:5436         # <--- 除了监听端口/目标端口和服务名，其他配置和 primary 服务一模一样
    mode tcp
    maxconn 5000
    balance roundrobin
    option httpchk
    option http-keep-alive
    http-check send meth OPTIONS uri /primary
    http-check expect status 200
    default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
    # servers
    server pg-test-1 10.10.10.11:5432 check port 8008 weight 100
    server pg-test-3 10.10.10.13:5432 check port 8008 weight 100
    server pg-test-2 10.10.10.12:5432 check port 8008 weight 100

Offline服务

Offline 服务在 5438 端口上提供服务，它绕开连接池直接访问 PostgreSQL 数据库，通常用于慢查询/分析查询/ETL 读取/个人用户交互式查询，其服务定义如下：

- { name: offline ,port: 5438 ,dest: postgres ,check: /replica   ,selector: "[? pg_role == `offline` || pg_offline_query ]" , backup: "[? pg_role == `replica` && !pg_offline_query]"}

Offline 服务将流量直接路由到专用的 离线从库 上，或者带有 pg_offline_query 标记的普通 只读实例。

  • 选择器参数从集群中筛选出了两种实例：pg_role = offline 的离线从库，或是带有 pg_offline_query = true 标记的普通 只读实例
  • 专用离线从库和打标记的普通从库主要的区别在于：前者默认不承载 Replica服务 的请求，避免快慢请求混在一起，而后者默认会承载。
  • 备份选择器参数从集群中筛选出了一种实例：不带 offline 标记的普通从库，这意味着如果离线实例或者带 Offline 标记的普通从库挂了之后，其他普通的从库可以用来承载 Offline 服务。
  • 健康检查 /replica 只会针对从库返回 200， 主库会返回错误，因此 Offline 服务 永远不会将流量分发到主库实例上去，哪怕集群中只剩这一台主库。
  • 同时，主库实例既不会被选择器圈中，也不会被备份选择器圈中，因此它永远不会承载 Offline 服务。因此 Offline 服务总是可以避免用户访问主库，从而避免对主库的影响。
示例：pg-test-offline 的 haproxy 配置
listen pg-test-offline
    bind *:5438
    mode tcp
    maxconn 5000
    balance roundrobin
    option httpchk
    option http-keep-alive
    http-check send meth OPTIONS uri /replica
    http-check expect status 200
    default-server inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100
    # servers
    server pg-test-3 10.10.10.13:5432 check port 8008 weight 100
    server pg-test-2 10.10.10.12:5432 check port 8008 weight 100 backup

Offline 服务提供受限的只读服务，通常用于两类查询：交互式查询（个人用户），慢查询长事务（分析/ETL）。

Offline 服务需要额外的维护照顾：HAProxy 的 /replica 健康检查会在主从切换后自动拒绝新主库，但 selector 使用的是配置清单中的静态 pg_role / pg_offline_query 标签。对于一主一从、仅从库承载 Offline 查询的精简集群，切换后可能暂时没有合格后端。 仅重载未修改的清单并不会把原主库加入 Offline 后端。需要先按新的规划调整清单标签（或 pg_offline_query）再 重载服务，或者将主库切回原节点。

如果您的业务模型较为简单，您可以考虑剔除 Default 服务与 Offline 服务，使用 Primary 服务与 Replica 服务直连数据库。

重载服务

当集群成员发生变化（添加/删除副本）、服务定义或静态选择标签变化、相对权重调整时，需要 重载服务。Primary/Replica 服务的正常主备切换由 Patroni 健康检查自动接管，不需要为此单独重载。

bin/pgsql-svc <cls> [ip...]         # 为 lb 集群或 lb 实例重载服务
# ./pgsql.yml -t pg_service         # 重载服务的实际 ansible 任务

接入服务

Pigsty 的服务交付边界止步于集群的 HAProxy，用户可以用各种手段访问这些负载均衡器。

典型的做法是使用 DNS 或 VIP 接入，将其绑定在集群所有或任意数量的负载均衡器上。

pigsty-access.jpg

你可以使用不同的 主机 & 端口 组合，它们以不同的方式提供 PostgreSQL 服务。

主机

类型 样例 描述
集群域名 pg-test 通过集群域名访问（由 dnsmasq @ infra 节点解析）
集群 VIP 地址 10.10.10.3 通过由 vip-manager 管理的 L2 VIP 地址访问，绑定到主节点
实例主机名 pg-test-1 通过任何实例主机名访问（由 dnsmasq @ infra 节点解析）
实例 IP 地址 10.10.10.11 访问任何实例的 IP 地址

端口

Pigsty 使用不同的 端口 来区分 pg services

端口 服务 类型 描述
5432 postgres 数据库 直接访问 postgres 服务器
6432 pgbouncer 中间件 访问 postgres 前先通过连接池中间件
5433 primary 服务 访问主 pgbouncer (或 postgres)
5434 replica 服务 访问备份 pgbouncer (或 postgres)
5436 default 服务 访问主 postgres
5438 offline 服务 访问离线 postgres

组合

# 通过集群域名访问（以下示例假定已启用 L2 VIP；未启用时默认指向清单主实例 IP）
postgres://test@pg-test:5432/test # DNS -> L2 VIP -> 主直接连接
postgres://test@pg-test:6432/test # DNS -> L2 VIP -> 主连接池 -> 主
postgres://test@pg-test:5433/test # DNS -> L2 VIP -> HAProxy -> 主连接池 -> 主
postgres://test@pg-test:5434/test # DNS -> L2 VIP -> HAProxy -> 备份连接池 -> 备份
postgres://dbuser_dba@pg-test:5436/test # DNS -> L2 VIP -> HAProxy -> 主直接连接 (用于管理员)
postgres://dbuser_stats@pg-test:5438/test # DNS -> L2 VIP -> HAProxy -> 离线直接连接 (用于 ETL/个人查询)

# 通过集群 VIP 直接访问
postgres://[email protected]:5432/test # L2 VIP -> 主直接访问
postgres://[email protected]:6432/test # L2 VIP -> 主连接池 -> 主
postgres://[email protected]:5433/test # L2 VIP -> HAProxy -> 主连接池 -> 主
postgres://[email protected]:5434/test # L2 VIP -> HAProxy -> 备份连接池 -> 备份
postgres://[email protected]:5436/test # L2 VIP -> HAProxy -> 主直接连接 (用于管理员)
postgres://[email protected]:5438/test # L2 VIP -> HAProxy -> 离线直接连接 (用于 ETL/个人查询)

# 直接指定任何集群实例名
postgres://test@pg-test-1:5432/test # DNS -> 数据库实例直接连接 (单例访问)
postgres://test@pg-test-1:6432/test # DNS -> 连接池 -> 数据库
postgres://test@pg-test-1:5433/test # DNS -> HAProxy -> 连接池 -> 数据库读/写
postgres://test@pg-test-1:5434/test # DNS -> HAProxy -> 连接池 -> 数据库只读
postgres://dbuser_dba@pg-test-1:5436/test # DNS -> HAProxy -> 数据库直接连接
postgres://dbuser_stats@pg-test-1:5438/test # DNS -> HAProxy -> 数据库离线读/写

# 直接指定任何集群实例 IP 访问
postgres://[email protected]:5432/test # 数据库实例直接连接 (直接指定实例, 没有自动流量分配)
postgres://[email protected]:6432/test # 连接池 -> 数据库
postgres://[email protected]:5433/test # HAProxy -> 连接池 -> 数据库读/写
postgres://[email protected]:5434/test # HAProxy -> 连接池 -> 数据库只读
postgres://[email protected]:5436/test # HAProxy -> 数据库直接连接
postgres://[email protected]:5438/test # HAProxy -> 数据库离线读/写

# 智能客户端：自动进行读写分离
postgres://[email protected]:6432,10.10.10.12:6432,10.10.10.13:6432/test?target_session_attrs=primary
postgres://[email protected]:6432,10.10.10.12:6432,10.10.10.13:6432/test?target_session_attrs=prefer-standby

覆盖服务

你可以通过多种方式覆盖默认的服务配置，一种常见的需求是让 Primary服务 与 Replica服务 绕过 Pgbouncer 连接池，直接访问 PostgreSQL 数据库。

为了实现这一点，你可以将 pg_default_service_dest 更改为 postgres，这样所有服务定义中 svc.dest='default' 的服务都会使用 postgres 而不是默认的 pgbouncer 作为目标。

如果您已经将 Primary服务 指向了 PostgreSQL，那么 default服务 就会比较多余，可以考虑移除。

如果您不需要区分个人交互式查询，分析/ETL 慢查询，可以考虑从默认服务列表 pg_default_services 中移除 Offline服务。

如果您不需要只读从库来分担在线只读流量，也可以从默认服务列表中移除 Replica服务。

委托服务

Pigsty 通过节点上的 haproxy 暴露 PostgreSQL 服务。整个集群中的所有 haproxy 实例都使用相同的 服务定义 进行配置。

但是，你可以将 pg 服务委托给特定的节点分组（例如，专门的 haproxy 负载均衡器集群），而不是 PostgreSQL 集群成员上的 haproxy。

为此，你需要使用 pg_default_services 覆盖默认的服务定义，并将 pg_service_provider 设置为代理组名称。

例如，此配置将在端口 10013 的 proxy haproxy 节点组上公开 pg 集群的主服务。

pg_service_provider: proxy       # 使用端口 10013 上的 `proxy` 组的负载均衡器
pg_default_services:  [{ name: primary ,port: 10013 ,dest: postgres  ,check: /primary   ,selector: "[]" }]

用户需要确保每个委托服务的端口，在代理集群中都是 唯一 的。

在 20 节点生产环境仿真 沙箱 中提供了一个使用专用负载均衡器集群的例子：conf/ha/simu.yml

17.4 - 认证 / HBA

Pigsty 中基于主机的身份认证 HBA（Host-Based Authentication）详解。

Pigsty 中基于主机的身份认证 HBA（Host-Based Authentication）详解。

认证是 访问控制 与 默认权限 的基础，PostgreSQL 支持多种 认证 方法。

这里主要介绍 HBA：Host Based Authentication，HBA 规则定义了哪些用户能够通过哪些方式从哪些地方访问哪些数据库。

客户端认证

要连接到 PostgreSQL 数据库，用户必须先经过认证（默认使用密码）。

您可以在连接字符串中提供密码（不安全）或使用 PGPASSWORD 环境变量或 .pgpass 文件传递密码。参考 psql 文档和 PostgreSQL连接字符串 以获取更多详细信息。

psql 'host=<host> port=<port> dbname=<dbname> user=<username> password=<password>'
psql postgres://<username>:<password>@<host>:<port>/<dbname>
PGPASSWORD=<password>; psql -U <username> -h <host> -p <port> -d <dbname>

例如，连接 Pigsty 默认的 meta 数据库，可以使用以下连接串：

psql 'host=10.10.10.10 port=5432 dbname=meta user=dbuser_dba password=DBUser.DBA'
psql postgres://dbuser_dba:[email protected]:5432/meta
PGPASSWORD=DBUser.DBA; psql -U dbuser_dba -h 10.10.10.10 -p 5432 -d meta

默认配置下，Pigsty 会启用服务端 SSL 加密，但不验证客户端 SSL 证书。要使用客户端 SSL 证书连接，你可以使用 PGSSLCERT 和 PGSSLKEY 环境变量或 sslkey 和 sslcert 参数提供客户端参数。

psql 'postgres://dbuser_dba:[email protected]:5432/meta?sslkey=/path/to/dbuser_dba.key&sslcert=/path/to/dbuser_dba.crt'

客户端证书（CN = 用户名）可以使用本地 CA 与 cert.yml 剧本签发。

定义HBA

在 Pigsty 中，有四个与 HBA 规则有关的参数：

这些都是 HBA 规则对象的数组，每个 HBA 规则都是以下两种形式之一的对象：

1. 原始形式

原始形式的 HBA 与 PostgreSQL pg_hba.conf 的格式几乎完全相同：

- title: allow intranet password access
  role: common
  rules:
    - host   all  all  10.0.0.0/8      md5
    - host   all  all  172.16.0.0/12   md5
    - host   all  all  192.168.0.0/16  md5

在这种形式中，rules 字段是字符串数组，每一行都是条原始形式的 HBA规则。title 字段会被渲染为一条注释，解释下面规则的作用。

role 字段用于说明该规则适用于哪些实例角色，当实例的 pg_role 与 role 相同时，HBA 规则将被添加到这台实例的 HBA 中。

  • role: common 的 HBA 规则将被添加到所有实例上。
  • role: primary 的 HBA 规则只会添加到主库实例上。
  • role: replica 的 HBA 规则只会添加到从库实例上。
  • role: offline 的 HBA 规则将被添加到离线实例上（pg_role = offline 或 pg_offline_query = true）

2. 别名形式

别名形式允许您用更简单清晰便捷的方式维护 HBA 规则：它用 addr、auth、user 和 db 字段替换了 rules。 title、role 和 order 字段则仍然生效。

- addr: 'intra'    # world|intra|infra|admin|local|localhost|cluster|<cidr>
  auth: 'pwd'      # trust|pwd|ssl|cert|deny|<official auth method>
  user: 'all'      # all|${dbsu}|${repl}|${admin}|${monitor}|<user>|<group>
  db: 'all'        # all|replication|....
  rules: []        # raw hba string precedence over above all
  title: allow intranet password access
  order: 100       # 排序权重，数字小的排前面（可选，默认追加到最后）
  • addr: where 哪些 IP 地址段受本条规则影响？
    • world：所有的 IP 地址
    • intra：所有的内网 IP 地址段： '10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'
    • infra：Infra 节点的 IP 地址
    • admin: admin_ip 管理节点的 IP 地址
    • local：本地 Unix Socket
    • localhost：本地 Unix Socket 以及 TCP 127.0.0.1/32 环回地址
    • cluster：同一个 PostgresQL 集群所有成员的 IP 地址
    • <cidr>：一个特定的 CIDR 地址块或 IP 地址
  • auth: how 本条规则指定的认证方式？
    • deny：拒绝访问
    • trust：直接信任，不需要认证
    • pwd：密码认证，根据 pg_pwd_enc 参数选用 md5 或 scram-sha-256 认证
    • sha/scram-sha-256：强制使用 scram-sha-256 密码认证方式。
    • md5: md5 密码认证方式，但也可以兼容 scram-sha-256 认证，不建议使用。
    • ssl：在密码认证 pwd 的基础上，强制要求启用 SSL
    • ssl-md5：在密码认证 md5 的基础上，强制要求启用 SSL
    • ssl-sha：在密码认证 sha 的基础上，强制要求启用 SSL
    • os/ident：使用操作系统用户的身份进行 ident 认证
    • peer：使用 peer 认证方式，类似于 os ident
    • cert：使用基于客户端 SSL 证书的认证方式，证书 CN 为用户名
  • user: who：哪些用户受本条规则影响？
  • db: which：哪些数据库受本条规则影响？
    • all：所有数据库
    • replication：允许建立复制连接（不指定特定数据库）
    • 某个特定的数据库

3. 定义位置

通常，全局的 HBA 定义在 all.vars 中，如果您想要修改全局默认的 HBA 规则，可以从 conf/ha/full.yml 模板中复制一份到 all.vars 中进行修改。

而集群特定的 HBA 规则定义在数据库的集群级配置中：

下面是一些集群 HBA 规则的定义例子：

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_hba_rules:
      - { user: dbuser_view ,db: all    ,addr: infra        ,auth: pwd  ,title: '允许 dbuser_view 从基础设施节点密码访问所有库'}
      - { user: all         ,db: all    ,addr: 100.0.0.0/8  ,auth: pwd  ,title: '允许所有用户从K8S网段密码访问所有库'          }
      - { user: '${admin}'  ,db: world  ,addr: 0.0.0.0/0    ,auth: cert ,title: '允许管理员用户从任何地方用客户端证书登陆'       }

重载HBA

HBA 是一个静态的规则配置文件，修改后需要重载才能生效。默认的 HBA 规则集合因为不涉及 Role 与集群成员，所以通常不需要重载。

如果您设计的 HBA 使用了特定的实例角色限制，或者集群成员限制，那么当集群实例成员发生变化（新增/下线/主从切换），一部分 HBA 规则的生效条件/涉及范围发生变化，通常也需要 重载HBA 以反映最新变化。

要重新加载 postgres/pgbouncer 的 hba 规则：

bin/pgsql-hba <cls>                 # 重新加载集群 `<cls>` 的 hba 规则
bin/pgsql-hba <cls> ip1 ip2...      # 重新加载特定实例的 hba 规则

底层实际执行的 Ansible 剧本命令为：

./pgsql.yml -l <cls> -e pg_reload=true -t pg_hba,pg_reload
./pgsql.yml -l <cls> -e pg_reload=true -t pgbouncer_hba,pgbouncer_reload

默认HBA

Pigsty 有一套默认的 HBA 规则，对于绝大多数场景来说，它已经足够安全了。这些规则使用别名形式，因此基本可以自我解释。

pg_default_hba_rules:             # postgres 全局默认的HBA规则，按 order 排序
  - {user: '${dbsu}'    ,db: all         ,addr: local     ,auth: ident ,title: 'dbsu access via local os user ident'  ,order: 100}
  - {user: '${dbsu}'    ,db: replication ,addr: local     ,auth: ident ,title: 'dbsu replication from local os ident' ,order: 150}
  - {user: '${repl}'    ,db: replication ,addr: localhost ,auth: pwd   ,title: 'replicator replication from localhost',order: 200}
  - {user: '${repl}'    ,db: replication ,addr: intra     ,auth: pwd   ,title: 'replicator replication from intranet' ,order: 250}
  - {user: '${repl}'    ,db: postgres    ,addr: intra     ,auth: pwd   ,title: 'replicator postgres db from intranet' ,order: 300}
  - {user: '${monitor}' ,db: all         ,addr: localhost ,auth: pwd   ,title: 'monitor from localhost with password' ,order: 350}
  - {user: '${monitor}' ,db: all         ,addr: infra     ,auth: pwd   ,title: 'monitor from infra host with password',order: 400}
  - {user: '${admin}'   ,db: all         ,addr: infra     ,auth: ssl   ,title: 'admin @ infra nodes with pwd & ssl'   ,order: 450}
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: ssl   ,title: 'admin @ everywhere with ssl & pwd'    ,order: 500}
  - {user: '+dbrole_readonly',db: all    ,addr: localhost ,auth: pwd   ,title: 'pgbouncer read/write via local socket',order: 550}
  - {user: '+dbrole_readonly',db: all    ,addr: intra     ,auth: pwd   ,title: 'read/write biz user via password'     ,order: 600}
  - {user: '+dbrole_offline' ,db: all    ,addr: intra     ,auth: pwd   ,title: 'allow etl offline tasks from intranet',order: 650}
pgb_default_hba_rules:            # pgbouncer 全局默认的HBA规则，按 order 排序
  - {user: '${dbsu}'    ,db: pgbouncer   ,addr: local     ,auth: peer  ,title: 'dbsu local admin access with os ident',order: 100}
  - {user: 'all'        ,db: all         ,addr: localhost ,auth: pwd   ,title: 'allow all user local access with pwd' ,order: 150}
  - {user: '${monitor}' ,db: pgbouncer   ,addr: intra     ,auth: pwd   ,title: 'monitor access via intranet with pwd' ,order: 200}
  - {user: '${monitor}' ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other monitor access addr' ,order: 250}
  - {user: '${admin}'   ,db: all         ,addr: intra     ,auth: pwd   ,title: 'admin access via intranet with pwd'   ,order: 300}
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other admin access addr'   ,order: 350}
  - {user: 'all'        ,db: all         ,addr: intra     ,auth: pwd   ,title: 'allow all user intra access with pwd' ,order: 400}

注意：order 字段控制规则渲染顺序。0-99 用于高优先规则（如黑名单），100-650 为默认规则区间，1000+ 用于追加规则。详见 HBA 配置。

示例：渲染 pg_hba.conf
#==============================================================#
# File      :   pg_hba.conf
# Desc      :   Postgres HBA Rules for pg-meta-1 [primary]
# Time      :   2023-01-11 15:19
# Host      :   pg-meta-1 @ 10.10.10.10:5432
# Path      :   /pg/data/pg_hba.conf
# Note      :   ANSIBLE MANAGED, DO NOT CHANGE!
# Author    :   Ruohang Feng ([email protected])
# License   :   Apache-2.0
#==============================================================#

# addr alias
# local     : /var/run/postgresql
# admin     : 10.10.10.10
# infra     : 10.10.10.10
# intra     : 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16

# user alias
# dbsu    :  postgres
# repl    :  replicator
# monitor :  dbuser_monitor
# admin   :  dbuser_dba

# dbsu access via local os user ident [default]
local    all                postgres                              ident

# dbsu replication from local os ident [default]
local    replication        postgres                              ident

# replicator replication from localhost [default]
local    replication        replicator                            scram-sha-256
host     replication        replicator         127.0.0.1/32       scram-sha-256

# replicator replication from intranet [default]
host     replication        replicator         10.0.0.0/8         scram-sha-256
host     replication        replicator         172.16.0.0/12      scram-sha-256
host     replication        replicator         192.168.0.0/16     scram-sha-256

# replicator postgres db from intranet [default]
host     postgres           replicator         10.0.0.0/8         scram-sha-256
host     postgres           replicator         172.16.0.0/12      scram-sha-256
host     postgres           replicator         192.168.0.0/16     scram-sha-256

# monitor from localhost with password [default]
local    all                dbuser_monitor                        scram-sha-256
host     all                dbuser_monitor     127.0.0.1/32       scram-sha-256

# monitor from infra host with password [default]
host     all                dbuser_monitor     10.10.10.10/32     scram-sha-256

# admin @ infra nodes with pwd & ssl [default]
hostssl  all                dbuser_dba         10.10.10.10/32     scram-sha-256

# admin @ everywhere with ssl & pwd [default]
hostssl  all                dbuser_dba         0.0.0.0/0          scram-sha-256

# pgbouncer read/write via local socket [default]
local    all                +dbrole_readonly                      scram-sha-256
host     all                +dbrole_readonly   127.0.0.1/32       scram-sha-256

# read/write biz user via password [default]
host     all                +dbrole_readonly   10.0.0.0/8         scram-sha-256
host     all                +dbrole_readonly   172.16.0.0/12      scram-sha-256
host     all                +dbrole_readonly   192.168.0.0/16     scram-sha-256

# allow etl offline tasks from intranet [default]
host     all                +dbrole_offline    10.0.0.0/8         scram-sha-256
host     all                +dbrole_offline    172.16.0.0/12      scram-sha-256
host     all                +dbrole_offline    192.168.0.0/16     scram-sha-256

# allow application database intranet access [common] [DISABLED]
#host    kong            dbuser_kong         10.0.0.0/8          md5
#host    bytebase        dbuser_bytebase     10.0.0.0/8          md5
#host    grafana         dbuser_grafana      10.0.0.0/8          md5
示例：渲染 pgb_hba.conf
#==============================================================#
# File      :   pgb_hba.conf
# Desc      :   Pgbouncer HBA Rules for pg-meta-1 [primary]
# Time      :   2023-01-11 15:28
# Host      :   pg-meta-1 @ 10.10.10.10:5432
# Path      :   /etc/pgbouncer/pgb_hba.conf
# Note      :   ANSIBLE MANAGED, DO NOT CHANGE!
# Author    :   Ruohang Feng ([email protected])
# License   :   Apache-2.0
#==============================================================#

# PGBOUNCER HBA RULES FOR pg-meta-1 @ 10.10.10.10:6432
# ansible managed: 2023-01-11 14:30:58

# addr alias
# local     : /var/run/postgresql
# admin     : 10.10.10.10
# infra     : 10.10.10.10
# intra     : 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16

# user alias
# dbsu    :  postgres
# repl    :  replicator
# monitor :  dbuser_monitor
# admin   :  dbuser_dba

# dbsu local admin access with os ident [default]
local    pgbouncer          postgres                              peer

# allow all user local access with pwd [default]
local    all                all                                   scram-sha-256
host     all                all                127.0.0.1/32       scram-sha-256

# monitor access via intranet with pwd [default]
host     pgbouncer          dbuser_monitor     10.0.0.0/8         scram-sha-256
host     pgbouncer          dbuser_monitor     172.16.0.0/12      scram-sha-256
host     pgbouncer          dbuser_monitor     192.168.0.0/16     scram-sha-256

# reject all other monitor access addr [default]
host     all                dbuser_monitor     0.0.0.0/0          reject

# admin access via intranet with pwd [default]
host     all                dbuser_dba         10.0.0.0/8         scram-sha-256
host     all                dbuser_dba         172.16.0.0/12      scram-sha-256
host     all                dbuser_dba         192.168.0.0/16     scram-sha-256

# reject all other admin access addr [default]
host     all                dbuser_dba         0.0.0.0/0          reject

# allow all user intra access with pwd [default]
host     all                all                10.0.0.0/8         scram-sha-256
host     all                all                172.16.0.0/12      scram-sha-256
host     all                all                192.168.0.0/16     scram-sha-256

安全加固

对于那些需要更高安全性的场合，我们提供了一个安全加固的配置模板 conf/ha/safe.yml，使用了以下的默认 HBA 规则集：

pg_default_hba_rules:             # postgres host-based auth rules by default, order by `order`
  - {user: '${dbsu}'    ,db: all         ,addr: local     ,auth: ident ,title: 'dbsu access via local os user ident'  ,order: 100}
  - {user: '${dbsu}'    ,db: replication ,addr: local     ,auth: ident ,title: 'dbsu replication from local os ident' ,order: 150}
  - {user: '${repl}'    ,db: replication ,addr: localhost ,auth: ssl   ,title: 'replicator replication from localhost',order: 200}
  - {user: '${repl}'    ,db: replication ,addr: intra     ,auth: ssl   ,title: 'replicator replication from intranet' ,order: 250}
  - {user: '${repl}'    ,db: postgres    ,addr: intra     ,auth: ssl   ,title: 'replicator postgres db from intranet' ,order: 300}
  - {user: '${monitor}' ,db: all         ,addr: localhost ,auth: pwd   ,title: 'monitor from localhost with password' ,order: 350}
  - {user: '${monitor}' ,db: all         ,addr: infra     ,auth: ssl   ,title: 'monitor from infra host with password',order: 400}
  - {user: '${admin}'   ,db: all         ,addr: infra     ,auth: ssl   ,title: 'admin @ infra nodes with pwd & ssl'   ,order: 450}
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: cert  ,title: 'admin @ everywhere with ssl & cert'   ,order: 500}
  - {user: '+dbrole_readonly',db: all    ,addr: localhost ,auth: ssl   ,title: 'pgbouncer read/write via local socket',order: 550}
  - {user: '+dbrole_readonly',db: all    ,addr: intra     ,auth: ssl   ,title: 'read/write biz user via password'     ,order: 600}
  - {user: '+dbrole_offline' ,db: all    ,addr: intra     ,auth: ssl   ,title: 'allow etl offline tasks from intranet',order: 650}
pgb_default_hba_rules:            # pgbouncer host-based authentication rules, order by `order`
  - {user: '${dbsu}'    ,db: pgbouncer   ,addr: local     ,auth: peer  ,title: 'dbsu local admin access with os ident',order: 100}
  - {user: 'all'        ,db: all         ,addr: localhost ,auth: pwd   ,title: 'allow all user local access with pwd' ,order: 150}
  - {user: '${monitor}' ,db: pgbouncer   ,addr: intra     ,auth: ssl   ,title: 'monitor access via intranet with pwd' ,order: 200}
  - {user: '${monitor}' ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other monitor access addr' ,order: 250}
  - {user: '${admin}'   ,db: all         ,addr: intra     ,auth: ssl   ,title: 'admin access via intranet with pwd'   ,order: 300}
  - {user: '${admin}'   ,db: all         ,addr: world     ,auth: deny  ,title: 'reject all other admin access addr'   ,order: 350}
  - {user: 'all'        ,db: all         ,addr: intra     ,auth: ssl   ,title: 'allow all user intra access with pwd' ,order: 400}

认证方法与默认边界见 身份认证，生产加固步骤见 安全考量。

17.5 - 访问控制

PostgreSQL 访问控制的概念、配置与管理入口。

Pigsty 的访问控制文档已按用途拆分：

  • 访问控制概念：角色模型、默认权限、数据库 ACL 和实例隔离边界。
  • 访问控制配置：pg_default_roles、pg_users、pg_default_privileges 等参数。
  • 身份认证：HBA、SCRAM、证书认证与凭据管理。
  • HBA 配置：PostgreSQL 与 PgBouncer 规则语法。
  • 用户管理：在现有集群中创建、更新和删除用户。

dbrole_offline 只提供独立的只读对象权限，不会自动限制实例范围。若要仅允许其访问离线实例，应为对应 HBA 规则显式设置 role: offline，并验证在线与离线实例生成的 pg_hba.conf。