参数列表

PGSQL 模块提供的 PostgreSQL 相关配置参数详解

PGSQL 模块需要在 Pigsty 管理的节点上安装（即节点已经配置了 NODE 模块），同时还要求您的部署中有一套可用的 ETCD 集群来存储集群元数据。

在单个节点上安装 PGSQL 模块将创建一个独立的 PGSQL 服务器/实例，即主实例。在额外节点上安装将创建只读副本，可以作为备用实例，并用于承载分担只读请求。您还可以创建用于 ETL/OLAP/交互式查询的离线实例，使用同步备库和法定人数提交来提高数据一致性，甚至搭建备份集群和延迟集群以快速应对人为失误与软件缺陷导致的数据损失。

您可以定义多个 PGSQL 集群并进一步组建一个水平分片集群： Pigsty 支持原生的 citus 集群组，可以将您的标准 PGSQL 集群原地升级为一个分布式的数据库集群。

Pigsty v4.0 默认使用 PostgreSQL 18，并新增了 pg_io_method、pgbackrest_exporter 等参数。

参数组	功能说明
`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,polar,ivory,oracle,gpsql
`pg_cluster`	`string`	`C`	pgsql 集群名称, 必选身份参数
`pg_seq`	`int`	`I`	pgsql 实例号, 必选身份参数
`pg_role`	`enum`	`I`	pgsql 实例角色, 必选身份参数, 可为 primary，replica，offline
`pg_instances`	`dict`	`I`	在一个节点上定义多个 pg 实例，使用 `{port:ins_vars}` 格式
`pg_upstream`	`ip`	`I`	级联从库或备份集群或的复制上游节点IP地址
`pg_shard`	`string`	`C`	pgsql 分片名，对 citus 与 gpsql 等水平分片集群为必选身份参数
`pg_group`	`int`	`C`	pgsql 分片号，正整数，对 citus 与 gpsql 等水平分片集群为必选身份参数
`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`	postgres 数据目录，默认为 `/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`	恢复点目标（字节），默认为 `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_clean`	`bool`	`C`	在初始化时删除以前的 pg 备份数据？
`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 网络接口，默认为 eth0
`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 兼容内核
polar：PolarDB for PostgreSQL 内核
oracle：PolarDB for Oracle 内核
gpsql：Greenplum 并行数据库集群（监控）

如果 pg_mode 设置为 citus 或 gpsql，则需要两个额外的必选身份参数 pg_shard 和 pg_group 来定义水平分片集群的身份。

在这两种情况下，每一个 PostgreSQL 集群都是一组更大的业务单元的一部分。

`pg_cluster`

参数名称： pg_cluster，类型： string，层次：C

PostgreSQL 集群名称，必选的身份标识参数，没有默认值

集群名将用作资源的命名空间。

集群命名需要遵循特定的命名模式：[a-z][a-z0-9-]*，即，只使用数字与小写字母，且不以数字开头，以符合标识上的不同约束的要求。

`pg_seq`

参数名称： pg_seq，类型： int，层次：I

PostgreSQL 实例序列号，必选的身份标识参数，无默认值。

此实例的序号，在其集群内是唯一分配的，通常使用自然数，从0或1开始分配，通常不会回收重用。

`pg_role`

参数名称： pg_role，类型： enum，层次：I

PostgreSQL 实例角色，必选的身份标识参数，无默认值。取值可以是：primary, replica, offline

PGSQL 实例的角色，可以是：primary、replica、standby 或 offline。

primary: 主实例，在集群中有且仅有一个。
replica: 用于承载在线只读流量的副本，高负载下可能会有轻微复制延迟（10ms~100ms, 100KB）。
offline: 用于处理离线只读流量的离线副本，如统计分析/ETL/个人查询等。

`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 水平分片名称，对于分片集群来说（例如 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 水平分片集群的分片索引号，对于分片集群来说（例如 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。

当某个 PostgreSQL 实例启用此参数时，属于 dbrole_offline 分组的用户可以直接连接到该 PostgreSQL 实例上执行离线查询（慢查询，交互式查询，ETL/分析类查询）。

带有此标记的实例在效果上类似于为实例设置 pg_role = offline ，唯一的区别在于 offline 实例默认不会承载 replica 服务的请求，是作为专用的离线/分析从库实例而存在的。

如果您没有富余的实例可以专门用于此目的，则可以挑选一台普通的从库，在实例层次启用此参数，以便在需要时承载离线查询。

`PG_BUSINESS`

定制集群模板：用户，数据库，服务，权限规则。

用户需重点关注此部分参数，因为这里是业务声明自己所需数据库对象的地方。

业务用户定义： pg_users
业务数据库定义： pg_databases
集群专有服务定义： pg_services （全局定义：pg_default_services）
PostgreSQL集群/实例特定的HBA规则： pg_hba_rules
Pgbouncer连接池特定HBA规则： pgb_hba_rules
定时任务（crontab）定义： pg_crontab

默认的数据库用户及其凭据，强烈建议在生产环境中修改这些用户的密码。

PG管理员用户：pg_admin_username / pg_admin_password
PG复制用户： pg_replication_username / pg_replication_password
PG监控用户：pg_monitor_username / pg_monitor_password

# 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: -1              # 可选，用户级别的连接池最大连接数，默认 -1 不限制

`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: 64                   # 可选，数据库级别的 pgbouncer 默认池子大小，默认为 64
  pool_reserve: 32                # 可选，数据库级别的 pgbouncer 池子保留空间，默认为 32，当默认池子不够用时，最多再申请这么多条突发连接
  pool_size_min: 0                # 可选，数据库级别的 pgbouncer 池的最小大小，默认为 0
  pool_connlimit: 100             # 可选，数据库级别的最大数据库连接数，默认为 100

在每个数据库定义对象中，只有 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_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 中提供了大量别名，方便在不同发行版之间屏蔽包名差异。以下是 EL9 平台可用的扩展组合供参考（按需挑选即可）：

pg_extensions: # extensions to be installed on this cluster
  - timescaledb periods temporal_tables emaj table_version pg_cron pg_later pg_background pg_timetable
  - postgis pgrouting pointcloud pg_h3 q3c ogr_fdw geoip #pg_geohash #mobilitydb
  - pgvector pgvectorscale pg_vectorize pg_similarity pg_tiktoken pgml #smlar
  - pg_search pg_bigm zhparser hunspell
  - hydra pg_analytics pg_lakehouse pg_duckdb duckdb_fdw pg_fkpart pg_partman plproxy #pg_strom citus
  - pg_hint_plan age hll rum pg_graphql pg_jsonschema jsquery index_advisor hypopg imgsmlr pg_ivm pgmq pgq #rdkit
  - pg_tle plv8 pllua plprql pldebugger plpgsql_check plprofiler plsh #pljava plr pgtap faker dbt2
  - prefix semver pgunit md5hash asn1oid roaringbitmap pgfaceting pgsphere pg_country pg_currency pgmp numeral pg_rational pguint ip4r timestamp9 chkpass #pg_uri #pgemailaddr #acl #debversion #pg_rrule
  - topn pg_gzip pg_http pg_net pg_html5_email_address pgsql_tweaks pg_extra_time pg_timeit count_distinct extra_window_functions first_last_agg tdigest aggs_for_arrays pg_arraymath pg_idkit pg_uuidv7 permuteseq pg_hashids
  - sequential_uuids pg_math pg_random pg_base36 pg_base62 floatvec pg_financial pgjwt pg_hashlib shacrypt cryptint pg_ecdsa pgpcre icu_ext envvar url_encode #pg_zstd #aggs_for_vecs #quantile #lower_quantile #pgqr #pg_protobuf
  - pg_repack pg_squeeze pg_dirtyread pgfincore pgdd ddlx pg_prioritize pg_checksums pg_readonly safeupdate pg_permissions pgautofailover pg_catcheck preprepare pgcozy pg_orphaned pg_crash pg_cheat_funcs pg_savior table_log pg_fio #pgpool pgagent
  - pg_profile pg_show_plans pg_stat_kcache pg_stat_monitor pg_qualstats pg_store_plans pg_track_settings pg_wait_sampling system_stats pg_meta pgnodemx pg_sqlog bgw_replstatus pgmeminfo toastinfo pagevis powa pg_top #pg_statviz #pgexporter_ext #pg_mon
  - passwordcheck supautils pgsodium pg_vault anonymizer pg_tde pgsmcrypto pgaudit pgauditlogtofile pg_auth_mon credcheck pgcryptokey pg_jobmon logerrors login_hook set_user pg_snakeoil pgextwlist pg_auditor noset #sslutils
  - wrappers multicorn odbc_fdw mysql_fdw tds_fdw sqlite_fdw pgbouncer_fdw mongo_fdw redis_fdw pg_redis_pubsub kafka_fdw hdfs_fdw firebird_fdw aws_s3 log_fdw #oracle_fdw #db2_fdw #jdbc_fdw
  - orafce pgtt session_variable pg_statement_rollback pg_dbms_metadata pg_dbms_lock pgmemcache #pg_dbms_job #wiltondb
  - pglogical pgl_ddl_deploy pg_failover_slots wal2json wal2mongo decoderbufs decoder_raw mimeo pgcopydb pgloader pg_fact_loader pg_bulkload pg_comparator pgimportdoc pgexportdoc #repmgr #slony
  - gis-stack rag-stack fdw-stack fts-stack etl-stack feat-stack olap-stack supa-stack stat-stack json-stack

完整列表请参考：roles/node_id/vars

`PG_BOOTSTRAP`

使用 Patroni 引导拉起 PostgreSQL 集群，并设置 1:1 对应的 Pgbouncer 连接池。

它还会使用 PG_PROVISION 中定义的默认角色、用户、权限、模式、扩展来初始化数据库集群

pg_data: /pg/data                 # postgres data directory, `/pg/data` by default
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,fsync,worker,io_uring, worker by default
pg_rto: norm                      # shared rto mode: fast,norm,safe,wide (or seconds for compatibility)
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，层次：C

Postgres 数据目录，默认为 /pg/data。

这是一个指向底层实际数据目录的符号链接，在多处被使用，请不要修改它。参阅 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 启用大页，那么此参数值应当适当小于