PGSQL配置

您需要通过配置，向Pigsty表达自己对数据库的需求。Pigsty提供了100+参数来对PostgreSQL集群进行完备的描述。但用户通常只需要关心身份参数与中的个别参数即可：前者表达数据库集群“是谁？在哪？”，后者表达这个数据库“啥样？有啥？”。

Pigsty中，关于PostgreSQL数据库的参数分为7个主要章节：

PG_IDENTITY : 定义PostgreSQL数据库集群的身份
: 定制集群模板：用户，数据库，服务，权限规则
PG_INSTALL : 安装PostgreSQL软件包，扩展插件，准备目录结构与工具脚本
: 生成配置模板，拉起PostgreSQL集群，搭建主从复制，启用连接池
PG_PROVISION : PGSQL集群模板置备，创建用户与数据库，配置权限角色HBA，模式与扩展。
: PGSQL指标暴露器，数据库与连接池配置监控组件
PG_SERVICE : 对外暴露PostgreSQL服务，安装负载均衡器 HAProxy，启用VIP，配置DNS。

pg_cluster，，pg_seq 属于 身份参数 。

除IP地址外，这三个参数是定义一套新的数据库集群的最小必须参数集，一个典型案例如下所示。

其他参数都可以继承自全局配置或默认配置，但身份参数必须显式指定，手工分配，目前PGSQL身份参数如下：

名称	类型	层级	说明
	`string`	C	PG数据库集群名称
pg_seq	`number`	I	PG数据库实例序号
	`enum`	I	PG数据库实例角色
pg_shard	`string`	C	PG数据库分片集簇名（占位）
	`number`	C	PG数据库分片集簇号（占位）

pg_cluster 标识了集群的名称，在集群层面进行配置。
在实例层面进行配置，标识了实例的角色，只有primary角色会进行特殊处理，如果不填，默认为replica角色，此外，还有特殊的delayed与offline角色。
pg_seq用于在集群内标识实例，通常采用从0或1开始递增的整数，一旦分配不再更改。
{{ pg_cluster }}-{{ pg_seq }} 被用于唯一标识实例，即pg_instance
{{ pg_cluster }}-{{ pg_role }} 用于标识集群内的服务，即pg_service
与 pg_sindex 用于水平分片集群，为Citus与Greenplum多集群管理预留。

PG数据库集群名称，类型：string，层级：集群，没有默认值。必选参数，必须由用户提供。

集群名将用作集群内资源的命名空间，命名需要遵循特定命名规则：[a-z][a-z0-9-]*，以兼容不同约束对身份标识的要求。

`pg_shard`

PG集群所属的Shard (保留), 类型：string，层级：集群，没有默认值，可选参数。

只有分片集群需要设置此参数。当多个数据库集群以水平分片的方式共同服务于同一个业务时，Pigsty将这一组集群称为 分片集簇（Sharding Cluster） 。 pg_shard是数据库集群所属分片集簇的名称，一个分片集簇可以指定任意名称，但Pigsty建议采用具有意义的命名规则。

例如参与分片集簇的集群，可以使用分片集簇名 + shard + 集群所属分片编号pg_sindex构成集群名称：

shard:  test
pg-testshard1
pg-testshard3
pg-testshard4

`pg_sindex`

PG集群的分片号 (保留), 类型：int，层级：C，无默认值。

集群在分片集簇中的编号，与 pg_shard 配合使用通常从0或1开始依次分配。只有分片集群需要设置此参数。

`gp_role`

当前PG集群在GP中的角色, 类型：enum，层级：C，默认值为：

Greenplum/MatrixDB 专用，用于指定GP部署中，此PG集群扮演的角色，可选值为：

master ：协调者节点
segment ：数据节点

为身份参数，集群级参数，当部署GPSQL时为必选参数。

`pg_role`

PG数据库实例角色, 类型：enum，层级：I，无默认值，必选参数，必须由用户提供。

数据库实例的角色，默认角色包括：primary, replica, offline

primary: 集群主库，集群中必须有一个且只能有一个成员为primary
replica: 集群从库，用于承担在线只读流量。
offline: 集群离线从库，用于承担离线只读流量，例如统计分析/ETL/个人查询等。

身份参数，必填参数，实例级参数

`pg_seq`

PG数据库实例序号, 类型：int，层级：I，无默认值，必选参数，必须由用户提供。

数据库实例的序号，在集群内部唯一，用于区别与标识集群内的不同实例，从0或1开始分配。

`pg_instances`

当前节点上的所有PG实例, 类型：{port:ins}，层级：I，默认值为：

当节点上部署由超过一个PG实例时，例如Greenplum的Segments，或使用监管已有实例，可使用此参数描述。 pg_instances 是一个对象数组，键为实例端口，值为一个字典，内容可以是任意板块的参数，详情请参考 MatrixDB部署

`pg_upstream`

实例的复制上游节点, 类型：string，层级：I，默认值为空。

实例级配置项，内容为IP地址或主机名，用于指明流复制上游节点。

当为集群的从库配置该参数时，填入的IP地址必须为集群内的其他节点。实例会从该节点进行流复制，此选项可用于构建级连复制。
当为集群的主库配置该参数时，意味着整个集群将以 备集群（Standby Cluster）的形式运行，从上游节点接受变更。集群中的primary将扮演standby leader 的角色。

灵活使用此参数的能力，可以搭建异地灾备的集群，完成分片集群的分裂，实现延时从库。

`pg_offline_query`

是否允许离线查询, 类型：bool，层级：I，默认值为：false

设置为true时，无论当前实例的角色为何，用户组dbrole_offline都可以连接至该实例并执行离线查询。

对于实例数量较少（例如一主一从）的情况较为实用，用户可以将唯一的从库标记为pg_offline_query = true，从而接受ETL，慢查询与交互式访问。

`pg_backup`

是否在实例上存储冷备份, 类型：bool，层级：I，默认值为：false

未实现，保留标记位，带有该标记的实例节点会用于存储基础冷备份。

`pg_weight`

实例在负载均衡中的相对权重, 类型：int，层级：I，默认值为：100

当您希望调整实例在服务中的相对权重时，可在实例层次修改此参数，并按中介绍的方法应用生效。

`pg_hostname`

将PG实例名称设为HOSTNAME, 类型：bool，层级：C/I，默认值为：false，在Demo中默认为真。

是否在初始化节点时，将PostgreSQL的实例名与集群名一并用作节点的名称与集群名，默认禁用。

当采用节点:PG 1:1 独占部署模式时，您可以将PG实例的身份赋予节点，保持节点与PG的监控身份一致。

`pg_preflight_skip`

跳过PG身份参数校验, 类型：bool，层级：C/A，默认值为：false

如果您不希望初始化新的数据库集群（例如与已有实例打交道时），则可以通过此参数完整跳过Patroni与Postgres初始化的任务。

`PG_BUSINESS`

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

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

业务用户定义：
业务数据库定义： pg_databases
集群专有服务定义：
集群/实例特定的HBA规则： pg_hba_rules_extra
Pgbounce特定HBA规则：

特殊的数据库用户，强烈建议在生产环境中修改这些用户的密码。

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

`pg_users`

业务用户定义, 类型：user[]，层级：C，默认值为空数组。

用于在数据库集群层面定义业务用户，数组中的每一个对象定义了一个，一个完整的用户定义如下：

pg_users:                           # define business users/roles on this cluster, array of user definition
  # define admin user for meta database (This user are used for pigsty app deployment by default)
  - name: dbuser_meta               # required, `name` is the only mandatory field of a user definition
    password: md5d3d10d8cad606308bdb180148bf663e1  # md5 salted password of 'DBUser.Meta'
    # optional, plain text and md5 password are both acceptable (prefixed with `md5`)
    login: true                     # optional, can login, true by default  (new biz ROLE should be false)
    superuser: false                # optional, is superuser? false by default
    createdb: false                 # optional, can create database? false by default
    createrole: false               # optional, can create role? false by default
    inherit: true                   # optional, can this role use inherited privileges? true by default
    replication: false              # optional, can this role do replication? false by default
    bypassrls: false                # optional, can this role bypass row level security? false by default
    pgbouncer: true                 # optional, add this user to pgbouncer user-list? false by default (production user should be true explicitly)
    connlimit: -1                   # optional, user connection limit, default -1 disable limit
    expire_in: 3650                 # optional, now + n days when this role is expired (OVERWRITE expire_at)
    expire_at: '2030-12-31'         # optional, YYYY-MM-DD 'timestamp' when this role is expired  (OVERWRITTEN by expire_in)
    comment: pigsty admin user      # optional, comment string for this user/role
    roles: [dbrole_admin]           # optional, belonged roles. default roles are: dbrole_{admin,readonly,readwrite,offline}
    parameters:                     # optional, role level parameters with `ALTER ROLE SET`
      log_min_duration_statements: 1000                  
    search_path: public         # key value config parameters according to postgresql documentation (e.g: use pigsty as default search_path)
  - {name: dbuser_view , password: DBUser.Viewer  ,pgbouncer: true ,roles: [dbrole_readonly], comment: read-only viewer for meta database}
  # define additional business users for prometheus & grafana (optional)
  - {name: dbuser_grafana    , password: DBUser.Grafana    ,pgbouncer: true ,roles: [dbrole_admin], comment: admin user for grafana database }
  - {name: dbuser_prometheus , password: DBUser.Prometheus ,pgbouncer: true ,roles: [dbrole_admin], comment: admin user for prometheus database }

每一个用户或角色必须指定 name ，其余字段均为可选项，name必须在此列表中唯一。
password是可选项，如果留空则不设置密码，可以使用MD5密文密码。
login, superuser, createdb, createrole, inherit, replication, bypassrls 都是布尔类型，用于设置用户属性。如果不设置，则采用系统默认值。
用户通过CREATE USER创建，所以默认具有login属性，如果创建的是角色，需要指定login: false。
expire_at与expire_in用于控制用户过期时间，expire_at使用形如YYYY-mm-DD的日期时间戳。expire_in使用从现在开始的过期天数，如果expire_in存在则会覆盖expire_at选项。
新用户默认不会添加至Pgbouncer用户列表中，必须显式定义pgbouncer: true，该用户才会被加入到Pgbouncer用户列表。
用户/角色会按顺序创建，后面定义的用户可以属于前面定义的角色。
用户可以通过roles字段为业务用户添加默认权限组：
- dbrole_readonly：默认生产只读用户，具有全局只读权限。（只读生产访问）
- dbrole_offline：默认离线只读用户，在特定实例上具有只读权限。（离线查询，个人账号，ETL）
- dbrole_readwrite：默认生产读写用户，具有全局CRUD权限。（常规生产使用）
- dbrole_admin：默认生产管理用户，具有执行DDL变更的权限。（管理员）

应当为生产账号配置 pgbouncer: true，允许其通过连接池访问，普通用户不应当通过连接池访问数据库。

`pg_databases`

业务数据库定义, 类型：database[]，层级：C，默认值为空数组。

用于在数据库集群层面定义业务用户，数组中的每一个对象定义了一个业务数据库，一个完整的数据库定义如下：

pg_databases:                       # define business databases on this cluster, array of database definition
  # define the default `meta` database
  - name: meta                      # required, `name` is the only mandatory field of a database definition
    baseline: cmdb.sql              # optional, database sql baseline path, (relative path among ansible search path, e.g files/)
    owner: postgres                 # optional, database owner, postgres by default
    template: template1             # optional, which template to use, template1 by default
    encoding: UTF8                  # optional, database encoding, UTF8 by default. (MUST same as template database)
    locale: C                       # optional, database locale, C by default.  (MUST same as template database)
    lc_collate: C                   # optional, database collate, C by default. (MUST same as template database)
    lc_ctype: C                     # optional, database ctype, C by default.   (MUST same as template database)
    tablespace: pg_default          # optional, default tablespace, 'pg_default' by default.
    allowconn: true                 # optional, allow connection, true by default. false will disable connect at all
    revokeconn: false               # optional, revoke public connection privilege. false by default. (leave connect with grant option to owner)
    pgbouncer: true                 # optional, add this database to pgbouncer database list? true by default
    comment: pigsty meta database   # optional, comment string for this database
    connlimit: -1                   # optional, database connection limit, default -1 disable limit
    schemas: [pigsty]               # optional, additional schemas to be created, array of schema names
    extensions:                     # optional, additional extensions to be installed: array of schema definition `{name,schema}`
      - {name: adminpack, schema: pg_catalog}    # install adminpack to pg_catalog and install postgis to public
      - {name: postgis, schema: public}          # if schema is omitted, extension will be installed according to search_path.

每个数据库定义中，数据库名称 name 为必选项，其余均为可选项。

name：数据库名称，必选项。
owner：数据库属主，默认为
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：数据库备注信息。

`pg_services_extra`

集群专有服务定义, 类型：service[]，层级：C，默认值为：

用于在数据库集群层面定义额外的服务，数组中的每一个对象定义了一个服务，一个完整的服务定义如下：

- name: default           # service's actual name is {{ pg_cluster }}-{{ service.name }}
  src_ip: "*"             # service bind ip address, * for all, vip for cluster virtual ip address
  src_port: 5436          # bind port, mandatory
  dst_port: postgres      # target port: postgres|pgbouncer|port_number , pgbouncer(6432) by default
  check_method: http      # health check method: only http is available for now
  check_port: patroni     # health check port:  patroni|pg_exporter|port_number , patroni by default
  check_url: /primary     # health check url path, / as default
  check_code: 200         # health check http code, 200 as default
  selector: "[]"          # instance selector
  haproxy:                # haproxy specific fields
    maxconn: 3000         # default front-end connection
    balance: roundrobin   # load balance algorithm (roundrobin by default)
    default_server_options: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'

每一个集群都可以定义多个服务，每个服务包含任意数量的集群成员，服务通过端口进行区分，name与src_port为必选项，且必须在数组内唯一。

必选项目

名称（service.name）：

服务名称，服务的完整名称以数据库集群名为前缀，以service.name为后缀，通过-连接。例如在pg-test集群中name=primary的服务，其完整服务名称为pg-test-primary。
端口（service.port）：

在Pigsty中，服务默认采用NodePort的形式对外暴露，因此暴露端口为必选项。但如果使用外部负载均衡服务接入方案，您也可以通过其他的方式区分服务。
选择器（service.selector）：

选择器指定了服务的实例成员，采用JMESPath的形式，从所有集群实例成员中筛选变量。默认的[]选择器会选取所有的集群成员。

可选项目

备份选择器（service.selector）：

可选的 备份选择器service.selector_backup会选择或标记用于服务备份的实例列表，即集群中所有其他成员失效时，备份实例才接管服务。例如可以将primary实例加入replica服务的备选集中，当所有从库失效后主库依然可以承载集群的只读流量。
源端IP（service.src_ip） ：

表示服务对外使用的IP地址，默认为*，即本机所有IP地址。使用vip则会使用vip_address变量取值，或者也可以填入网卡支持的特定IP地址。
宿端口（service.dst_port）：

服务的流量将指向目标实例上的哪个端口？postgres 会指向数据库监听的端口，pgbouncer会指向连接池所监听的端口，也可以填入固定的端口号。
健康检查方式（service.check_method）:

服务如何检查实例的健康状态？目前仅支持HTTP
健康检查端口（service.check_port）:

服务检查实例的哪个端口获取实例的健康状态？ patroni会从Patroni（默认8008）获取，pg_exporter会从PG Exporter（默认9630）获取，用户也可以填入自定义的端口号。
健康检查路径（service.check_url）:

服务执行HTTP检查时，使用的URL PATH。默认会使用/作为健康检查，PG Exporter与Patroni提供了多样的健康检查方式，可以用于主从流量区分。例如，/primary仅会对主库返回成功，/replica仅会对从库返回成功。/read-only则会对任何支持只读的实例（包括主库）返回成功。
健康检查代码（service.check_code）:

HTTP健康检查所期待的代码，默认为200
Haproxy特定配置（service.haproxy） ：

关于服务供应软件（HAproxy）的专有配置项
- <service>.haproxy
这些参数现在中定义，使用service.haproxy来覆盖实例的参数配置。
- maxconn
HAProxy最大前后端连接数，默认为3000
- balance
haproxy负载均衡所使用的算法，可选策略为roundrobin与leastconn，默认为roundrobin
- default_server_options
Haproxy 后端服务器实例的默认选项

默认为： 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'

`pg_hba_rules_extra`

集群/实例特定的HBA规则, 类型：rule[]，层级：C，默认值为：

设置数据库的客户端IP黑白名单规则。对象数组，每一个对象都代表一条规则，每一条规则由三部分组成：

title，规则标题，会转换为HBA文件中的注释
role，应用角色，common代表应用至所有实例，其他取值（如replica, offline）则仅会安装至匹配的角色上。例如role='replica'代表这条规则只会应用到pg_role == 'replica' 的实例上。
rules，字符串数组，每一条记录代表一条最终写入pg_hba.conf的规则。

作为一个特例，role == 'offline' 的HBA规则，还会额外安装至 pg_offline_query == true 的实例上。

与之类似，但通常用于全局统一的HBA规则设置，pg_hba_rules_extra 会以同样的方式追加至pg_hba.conf中。

如果用户需要彻底覆写集群的HBA规则，即不想继承全局HBA配置，则应当在集群层面配置并覆盖全局配置。

`pgbouncer_hba_rules_extra`

Pgbounce特定HBA规则, 类型：rule[]，层级：C，默认值为空数组。

与类似，用于在集群层次对Pgbouncer的HBA规则进行额外配置。

`pg_admin_username`

用于执行PostgreSQL数据库管理任务（DDL变更）的数据库用户名，默认带有超级用户权限。

`pg_admin_password`

PG管理用户密码, 类型：string，层级：G，默认值为："DBUser.DBA"

用于执行PostgreSQL数据库管理任务（DDL变更）的数据库用户密码，必须使用明文，默认为DBUser.DBA，强烈建议修改！

在生产环境部署时，强烈建议修改此参数！

`pg_replication_username`

PG复制用户, 类型：string，层级：G，默认值为："replicator"

用于执行PostgreSQL流复制，建议在全局保持一致。

`pg_replication_password`

PG复制用户的密码, 类型：string，层级：G，默认值为："DBUser.Replicator"

用于执行PostgreSQL流复制的数据库用户密码，必须使用明文。默认为DBUser.Replicator。

在生产环境部署时，强烈建议修改此参数！

`pg_monitor_username`

PG监控用户, 类型：string，层级：G，默认值为："dbuser_monitor"

用于执行PostgreSQL与Pgbouncer监控任务的数据库用户名

`pg_monitor_password`

PG监控用户密码, 类型：string，层级：G，默认值为："DBUser.Monitor"

用于执行PostgreSQL与Pgbouncer监控任务的数据库用户密码，必须使用明文。

在生产环境部署时，强烈建议修改此参数。

PG Install 部分负责在一台装有基本软件的机器上完成所有PostgreSQL依赖项的安装。用户可以配置数据库超级用户的名称、ID、权限、访问，配置安装所用的源，配置安装地址，安装的版本，所需的软件包与扩展插件。

这里的大多数参数只需要在整体升级数据库大版本时修改，用户可以通过指定需要安装的软件版本，并在集群层面进行覆盖，为不同的集群安装不同的数据库版本。

`pg_dbsu`

PG操作系统超级用户, 类型：string，层级：C，默认值为："postgres"

数据库默认使用的操作系统用户（超级用户）的用户名称，默认为postgres，通常不建议修改。当安装 Greenplum / MatrixDB 时，建议修改本参数为对应推荐值：gpadmin|mxadmin。

`pg_dbsu_uid`

超级用户UID, 类型：int，层级：C，默认值为：26

数据库默认使用的操作系统用户（超级用户）的UID。默认值为26，与CentOS下PostgreSQL官方RPM包配置一致，不建议修改。

`pg_dbsu_sudo`

超级用户的Sudo权限, 类型：enum，层级：C，默认值为："limit"

none：没有sudo权限
all：带有完整sudo权限，但需要密码。
nopass：不需要密码的完整sudo权限（不建议）

数据库超级用户的默认权限为受限的sudo权限：limit。

`pg_dbsu_home`

超级用户的家目录, 类型：path，层级：C，默认值为："/var/lib/pgsql"

数据库超级用户的家目录，默认为/var/lib/pgsql

`pg_dbsu_ssh_exchange`

是否交换超级用户密钥, 类型：bool，层级：C，默认值为：true

是否在执行的机器之间交换的SSH公私钥。

`pg_version`

安装的数据库大版本, 类型：int，层级：C，默认值为：14

当前实例安装的PostgreSQL大版本号，默认为14，最低支持至10。

请注意，PostgreSQL的物理流复制无法跨越大版本，请在全局/集群层面配置此变量，确保整个集群内所有实例都有着相同的大版本号。

`pgdg_repo`

是否添加PG官方源？, 类型：bool，层级：C，默认值为：false

标记，是否使用PostgreSQL官方源？默认不使用。使用该选项，可以在没有本地源的情况下，直接从互联网官方源下载安装PostgreSQL相关软件包。

`pg_add_repo`

是否添加PG相关上游源？, 类型：bool，层级：C，默认值为：false

如果使用，则会在安装PostgreSQL前添加PGDG的官方源。

`pg_bin_dir`

PG二进制目录, 类型：path，层级：C，默认值为："/usr/pgsql/bin"

默认为/usr/pgsql/bin/，这是一个安装过程中手动创建的软连接，指向安装的具体Postgres版本目录。

例如/usr/pgsql -> /usr/pgsql-14。详情请参考 FHS

安装的PG软件包列表, 类型：string[]，层级：C，默认值为：

软件包中的${pg_version}会被替换为实际安装的PostgreSQL版本 pg_version。

当您为某一个特定集群指定特殊的时，可以相应在集群层面调整此参数（例如安装PG14 beta时某些扩展还不存在）

`pg_extensions`

安装的PG插件列表, 类型：string[]，层级：C，默认值为：

pg_repack_${pg_version}
pg_qualstats_${pg_version}
pg_stat_kcache_${pg_version}
pg_stat_monitor_${pg_version}
wal2json_${pg_version}"

软件包中的${pg_version}会被替换为实际安装的PostgreSQL大版本号。

`PG_BOOTSTRAP`

在一台安装完Postgres的机器上，创建并拉起一套数据库。

集群身份定义，清理现有实例，创建目录结构，拷贝工具与脚本，配置环境变量
渲染Patroni模板配置文件，使用Patroni拉起主库，使用Patroni拉起从库
配置Pgbouncer，初始化业务用户与数据库，将数据库与数据源服务注册至DCS。

通过可以使用默认的数据库集群模板（普通事务型 OLTP/普通分析型 OLAP/核心金融型 CRIT/微型虚机 TINY）。如果希望创建自定义的模板，可以在roles/postgres/templates中克隆默认配置并自行修改后采用，详情请参考：定制PGSQL集群。

`pg_safeguard`

安全保险，禁止清除存在的PostgreSQL实例, 类型：bool，层级：C/A，默认值为：false

如果为true，任何情况下，Pigsty剧本都不会移除运行中的PostgreSQL实例，包括 pgsql-remove.yml。

详情请参考。

`pg_clean`

是否抹除运行中的PostgreSQL实例？类型：bool，层级：C/A，默认值为：false。

针对剧本的抹除豁免，如果指定该参数为真，那么在 pgsql.yml 剧本执行时，会自动抹除已有的PostgreSQL实例

这是一个危险的操作，因此必须显式指定。

当安全保险参数打开时，本参数无效。

`pg_data`

PostgreSQL数据目录, 类型：path，层级：C，默认值为："/pg/data"，不建议更改。

`pg_fs_main`

PostgreSQL主数据盘挂载点, 类型：path，层级：C，默认值为："/data"

主数据盘目录，默认为/data，Pigsty的默认目录结构假设系统中存在一个主数据盘挂载点，用于盛放数据库目录与其他状态。

`pg_fs_bkup`

PostgreSQL备份盘挂载点, 类型：path，层级：C，默认值为："/data/backups"

Pigsty的默认目录结构假设系统中存在一个备份数据盘挂载点，用于盛放备份与归档数据。备份盘并不是必选项，如果系统中不存在备份盘，用户也可以指定一个主数据盘上的子目录作为备份盘根目录挂载点。

`pg_dummy_filesize`

占位文件/pg/dummy的大小, 类型：size，层级：C，默认值为："64MiB"

占位文件是一个预分配的空文件，占据一定量的磁盘空间。当出现磁盘满故障时，移除该占位文件可以紧急释放一些磁盘空间应急使用，生产环境建议使用4GiB，8GiB。

`pg_listen`

PG监听的IP地址, 类型：ip，层级：C，默认值为："0.0.0.0"

数据库监听的IP地址，默认为所有IPv4地址0.0.0.0，如果要包括所有IPv6地址，可以使用*。

`pg_port`

PG监听的端口, 类型：int，层级：C，默认值为：5432，不建议修改。

`pg_localhost`

PG使用的UnixSocket地址, 类型：ip|path，层级：C，默认值为："/var/run/postgresql"

Unix Socket目录用于盛放PostgreSQL与Pgbouncer的Unix socket文件，当客户端未指定IP地址访问数据库时，会通过本地Unix Socket访问，默认为/var/run/postgresql。

`patroni_enabled`

Patroni是否启用, 类型：bool，层级：C，默认值为：true

布尔类型，标记位，默认为真，是否启用 Patroni （与Postgres）？如果为假，那么Pigsty将直接跳过Patroni与Postgres拉起的流程。该选项通常在接入已有实例时使用。

`patroni_mode`

Patroni配置模式, 类型：enum，层级：C，默认值为："default"

default: 正常启用Patroni，并进入高可用自动切换模式。
pause: 启用Patroni，但在完成初始化后自动进入维护模式（不自动执行主从切换）
remove: 依然使用Patroni初始化集群，但初始化完成后移除Patroni

`pg_dcs_type`

PG高可用使用的DCS类型, 类型: enum，层级: G，默认值为: "consul".

有两种可用的DCS类型：consul 与 etcd，默认为Consul，对应的DCS类型consul_enabled 或需要在Pigsty全局配置启用。

`pg_namespace`

Patroni使用的DCS命名空间, 类型：path，层级：C，默认值为："/pg"

`patroni_port`

Patroni服务端口, 类型：int，层级：C，默认值为：8008

Patroni API服务器默认监听并对外暴露服务与健康检查的端口。

`patroni_watchdog_mode`

Patroni Watchdog模式, 类型：enum，层级：C，默认值为："automatic"

当发生主从切换时，Patroni会尝试在提升从库前关闭主库。如果指定超时时间内主库仍未成功关闭，Patroni会根据配置使用Linux内核模块softdog进行fencing关机。

off：不使用watchdog
automatic：如果内核启用了softdog，则启用watchdog，不强制，默认行为。
required：强制使用watchdog，如果系统未启用softdog则拒绝启动。

启用Watchdog意味着系统会优先确保数据一致性，而放弃可用性，如果您的系统更重视可用性，则可以关闭Watchdog，建议关闭元节点上的Watchdog。

`pg_conf`

Patroni使用的配置模板, 类型：string，层级：C，默认值为："tiny.yml"

拉起Postgres集群所用的Patroni模板。Pigsty预制了4种模板

常规OLTP模板，默认配置
olap.yml OLAP模板，提高并行度，针对吞吐量优化，针对长时间运行的查询进行优化。
) 核心业务模板，基于OLTP模板针对安全性，数据完整性进行优化，采用同步复制，强制启用数据校验和。
tiny.yml 微型数据库模板，针对低资源场景进行优化，例如运行于虚拟机中的演示数据库集群。

`pg_libs`

PG默认加载的共享库, 类型：string，层级：C，默认值为："timescaledb, pg_stat_statements, auto_explain"

填入Patroni模板中shared_preload_libraries参数的字符串，控制PG启动预加载的动态库。在当前版本中，默认会加载以下库：timescaledb, pg_stat_statements, auto_explain

如果您希望默认启用Citus支持，则需要修改该参数，将 citus 添加至首位：citus, timescaledb, pg_stat_statements, auto_explain

`pg_delay`

搭建延时从库集群时的延迟时长，类型：，层级：I，默认值为：0

为指定一个具体的延迟时长，只可在Standby Cluster初始化时指定。

`pg_checksum`

是否启用数据校验和, 类型：bool，层级：C，默认值为："false"

当使用核心库模板 crit 时，数据校验和无法配置，强制打开，其他情况请按需启用。

`pg_encoding`

PG字符集编码, 类型：enum，层级：C，默认值为："UTF8"。如无特殊需求，不建议修改此参数。

`pg_locale`

PG使用的本地化规则, 类型：enum，层级：C，默认值为："C"

如无特殊需求，不建议修改此参数，不当的排序规则可能对数据库性能产生显著影响。

`pg_lc_collate`

PG使用的本地化排序规则, 类型：enum，层级：C，默认值为："C"

默认为C，如无特殊需求，，强烈不建议修改此参数。用户总是可以通过COLLATE表达式实现本地化排序相关功能，错误的本地化排序规则可能导致某些操作产生成倍的性能损失，请在真的有本地化需求的情况下修改此参数。

`pg_lc_ctype`

默认为en_US.UTF8，因为一些PG扩展（pg_trgm）需要额外的字符分类定义才可以针对国际化字符正常工作，因此Pigsty默认会使用en_US.UTF8字符集定义，不建议修改此参数。

`pgbouncer_enabled`

是否启用Pgbouncer, 类型：bool，层级：C，默认值为：true

`pgbouncer_port`

Pgbouncer端口, 类型：int，层级：C，默认值为：6432

`pgbouncer_poolmode`

Pgbouncer池化模式, 类型：enum，层级：C，默认值为："transaction"

transaction，事务级连接池，默认，性能好，但影响 PreparedStatements 与其他一些会话级功能的使用。
session，会话级连接池，兼容性最强。
statements，语句级连接池，若您的查询均为点查，可以考虑使用此模式。

`pgbouncer_max_db_conn`

Pgbouncer最大单DB连接数, 类型：int，层级：C，默认值为：100

允许连接池与单个数据库之间建立的最大连接数，默认值为100

使用Transaction Pooling模式时，活跃服务端连接数通常处于个位数。如果采用Session Pooling模式，可以适当增大此参数。

PG_BOOTSTRAP负责拉起一套全新的Postgres集群，而负责在这套全新的数据库集群中创建默认的对象，包括

基本角色：只读角色，读写角色、管理角色
基本用户：复制用户、超级用户、监控用户、管理用户
模板数据库中的默认权限
默认模式
默认扩展
HBA黑白名单规则

Pigsty提供了丰富的定制选项，如果您希望进一步客制化PG集群，可以参考定制：PGSQL集群

`pg_provision`

是否置备PG集群？（应用模板）, 类型：bool，层级：C，默认值为：true

是否对拉起的PostgreSQL集群执行置备任务？设置为假会跳过 PG_TEMPLATE定义的任务。但注意，数据库超级用户、复制用户、管理用户、监控用户四个默认用户的创建不受此影响。

`pg_init`

自定义PG初始化脚本, 类型：string，层级：C，默认值为："pg-init"

用于初始化数据库模板的Shell脚本位置，默认为pg-init，该脚本会被拷贝至/pg/bin/pg-init后执行。

默认的pg-init 只是预渲染SQL命令的包装：

/pg/tmp/pg-init-roles.sql ：根据pg_default_roles生成的默认角色创建脚本
/pg/tmp/pg-init-template.sql，根据, pg_default_schemas, 生产的SQL命令。会同时应用于默认模版数据库template1与默认管理数据库postgres。

# system default roles
psql postgres -qAXwtf /pg/tmp/pg-init-roles.sql
# system default template
psql template1 -qAXwtf /pg/tmp/pg-init-template.sql
# make postgres same as templated database (optional)
psql postgres  -qAXwtf /pg/tmp/pg-init-template.sql

用户可以在自定义的pg-init脚本中添加自己的集群初始化逻辑。

`pg_default_roles`

默认创建的角色与用户, 类型：role[]，层级：G/C，默认值为：

# - default roles - #
pg_default_roles:
  # default roles
  - { name: dbrole_readonly  , login: false , comment: role for global read-only access  }                            # production read-only role
  - { name: dbrole_readwrite , login: false , roles: [dbrole_readonly], comment: role for global read-write access }  # production read-write role
  - { name: dbrole_offline , login: false , comment: role for restricted read-only access (offline instance) }        # restricted-read-only role
  - { name: dbrole_admin , login: false , roles: [pg_monitor, dbrole_readwrite] , comment: role for object creation }  # production DDL change role
  # default users
  - { name: postgres , superuser: true , comment: system superuser }                             # system dbsu, name is designated by `pg_dbsu`
  - { name: dbuser_dba , superuser: true , roles: [dbrole_admin] , comment: system admin user }  # admin dbsu, name is designated by `pg_admin_username`
  - { name: replicator , replication: true , bypassrls: true , roles: [pg_monitor, dbrole_readonly] , comment: system replicator }                   # replicator
  - { name: dbuser_monitor , roles: [pg_monitor, dbrole_readonly] , comment: system monitor user , parameters: {log_min_duration_statement: 1000 } } # monitor user
  - { name: dbuser_stats , password: DBUser.Stats , roles: [dbrole_offline] , comment: business offline user for offline queries and ETL }           # ETL user

本参数定义了PostgreSQL中的与默认用户，形式为对象数组，对象定义形式与中保持一致。

`pg_default_privilegs`

定义数据库模板中的默认权限, 类型：string[]，层级：G/C，默认值为：

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, UPDATE, DELETE        ON TABLES    TO dbrole_readwrite
  - GRANT USAGE,  UPDATE                ON SEQUENCES TO dbrole_readwrite
  - GRANT TRUNCATE, REFERENCES, TRIGGER ON TABLES    TO dbrole_admin
  - GRANT CREATE                        ON SCHEMAS   TO dbrole_admin

详细信息请参考。

默认创建的模式, 类型：string[]，层级：G/C，默认值为：[monitor]

Pigsty默认会创建名为monitor的模式用于安装监控扩展。

`pg_default_extensions`

默认安装于模板数据库的扩展，对象数组，类型为extension[]，层级：G/C，默认值为：

如果扩展没有指定schema字段，扩展会根据当前的search_path安装至对应模式中，例如public。

`pg_reload`

是否重载数据库配置（HBA）, 类型：bool，层级：A，默认值为：true

设置为true时，Pigsty会在生成HBA规则后立刻执行pg_ctl reload应用。

当您希望生成pg_hba.conf文件，并手工比较后再应用生效时，可以指定-e pg_reload=false来禁用它。

`pg_hba_rules`

PostgreSQL全局HBA规则, 类型：rule[]，层级：G/C，默认值为：

pg_hba_rules:
  - title: allow meta node password access
    role: common
    rules:
      - host    all     all                         10.10.10.10/32      md5
  - title: allow intranet admin password access
    role: common
    rules:
      - host    all     +dbrole_admin               10.0.0.0/8          md5
      - host    all     +dbrole_admin               172.16.0.0/12       md5
      - host    all     +dbrole_admin               192.168.0.0/16      md5
  - 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: allow local read-write access (local production user via pgbouncer)
    role: common
    rules:
      - local   all     +dbrole_readwrite                               md5
      - host    all     +dbrole_readwrite           127.0.0.1/32        md5
  - title: allow read-only user (stats, personal) password directly access
    role: replica
    rules:
      - local   all     +dbrole_readonly                               md5
      - host    all     +dbrole_readonly           127.0.0.1/32        md5

本参数在形式上与 pg_hba_rules_extra 完全一致，建议在全局配置统一的，针对特定集群使用 pg_hba_rules_extra 进行额外定制。两个参数中的规则都会依次应用，后者优先级更高。

`pgbouncer_hba_rules`

PgbouncerL全局HBA规则, 类型：rule[]，层级：G/C，默认值为：

pgbouncer_hba_rules:
  - title: local password access
    role: common
    rules:
      - local  all          all                                     md5
      - host   all          all                     127.0.0.1/32    md5
  - title: 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

默认的Pgbouncer HBA规则很简单：

允许从本地使用密码登陆
允许从内网网断使用密码登陆

用户可以按照自己的需求进行定制。

`PG_EXPORTER`

PG Exporter 用于监控Postgres数据库与Pgbouncer连接池

`pg_exporter_config`

PG指标定义配置文件, 类型：string，层级：C，默认值为："pg_exporter.yml"

pg_exporter使用的默认配置文件，定义了Pigsty中的数据库与连接池监控指标。默认为 pg_exporter.yml

Pigsty使用的PG Exporter配置文件默认从PostgreSQL 10.0 开始提供支持，目前支持至最新的PG 14版本。此外还有一些可选的配置模板：

：只包含基本指标，不包含数据库内对象监控指标
pg_exporter_fast.yml：缓存时间更短的指标定义

`pg_exporter_enabled`

启用PG指标收集器, 类型：bool，层级：C，默认值为：true

是否安装并配置pg_exporter，为false时，将跳过当前节点上 pg_exporter 的配置，并在注册监控目标时跳过此Exporter。

`pg_exporter_port`

PG指标暴露端口, 类型：int，层级：C，默认值为：9630

`pg_exporter_params`

PG Exporter额外的URL参数, 类型：string，层级：C/I，默认值为："sslmode=disable"

`pg_exporter_url`

采集对象数据库的连接串（覆盖）, 类型：string，层级：C/I，默认值为：""

PG Exporter用于连接至数据库的PGURL，应当为访问postgres管理数据库的URL，该选项以环境变量的方式配置于 /etc/default/pg_exporter 中。

可选参数，默认为空字符串，如果配置了选项，则会直接使用该URL作为监控连接串。否则Pigsty将使用以下规则生成监控的目标URL：

pg_monitor_username : 监控用户名
: 监控用户密码
pg_localhost : PG监听的本地IP地址或Unix Socket Dir
: PG监听的端口
pg_exporter_params : PG Exporter需要的额外参数

以上参数将按下列方式进行拼接

postgres://{{ pg_monitor_username }}:{{ pg_monitor_password }}@:{{ pg_port }}/postgres{% if pg_exporter_params != '' %}?{{ pg_exporter_params }}{% if pg_localhost != '' %}&host={{ pg_localhost }}{% endif %}{% endif %}

如果指定了参数，则Exporter会直接使用该连接串。

注意：当您只需要监控某一个特定业务数据库时，您可以直接使用该数据库的PGURL。如果您希望监控某一个数据库实例上所有的业务数据库，则建议使用管理数据库postgres的PGURL。

`pg_exporter_auto_discovery`

是否自动发现实例中的数据库, 类型：bool，层级：C/I，默认值为：true

是否启用自动数据库发现，默认开启。开启后，PG Exporter会自动检测目标实例中数据库列表的变化，并为每一个数据库创建一条抓取连接

关闭时，库内对象监控不可用。（如果您不希望在监控系统中暴露业务相关数据，可以关闭此特性）

`pg_exporter_exclude_database`

数据库自动发现排除列表, 类型：string，层级：C/I，默认值为："template0,template1,postgres"

逗号分隔的数据库名称列表，启用自动数据库发现时，此列表中的数据库不会被监控（被排除在监控对象之外）。

`pg_exporter_include_database`

数据库自动发现囊括列表, 类型：string，层级：C/I，默认值为：""

逗号分隔的数据库名称列表，启用自动数据库发现时，不在此列表中的数据库不会被监控（显式指定需要监控的数据库）。

`pg_exporter_options`

PG Exporter命令行参数, 类型：string，层级：C/I，默认值为："--log.level=info --log.format=\"logger:syslog?appname=pg_exporter&local=7\""

`pgbouncer_exporter_enabled`

启用PGB指标收集器, 类型：bool，层级：C，默认值为：true

`pgbouncer_exporter_port`

PGB指标暴露端口, 类型：int，层级：C，默认值为：9631

`pgbouncer_exporter_url`

采集对象连接池的连接串, 类型：string，层级：C/I，默认值为：""

PGBouncer Exporter用于连接至数据库的URL，应当为访问pgbouncer管理数据库的URL。可选参数，默认为空字符串。

Pigsty默认使用以下规则生成监控的目标URL，如果配置了pgbouncer_exporter_url选项，则会直接使用该URL作为连接串。

PG_EXPORTER_URL='postgres://{{ pg_monitor_username }}:{{ pg_monitor_password }}@:{{ pgbouncer_port }}/pgbouncer?host={{ pg_localhost }}&sslmode=disable'

该选项以环境变量的方式配置于 /etc/default/pgbouncer_exporter 中。

`pgbouncer_exporter_options`

PGB Exporter命令行参数, 类型：string，层级：C/I，默认值为："--log.level=info --log.format=\"logger:syslog?appname=pgbouncer_exporter&local=7\""

即将INFO级日志打入syslog中。

对外暴露PostgreSQL服务，安装负载均衡器 HAProxy，启用VIP，配置DNS。

`pg_services`

全局通用PG服务定义, 类型：[]service，层级：G，默认值为：

由服务定义对象构成的数组，定义了每一个数据库集群中对外暴露的服务。形式上与保持一致。

`haproxy_enabled`

是否启用Haproxy, 类型：bool，层级：C/I，默认值为：true

Pigsty默认会在所有数据库节点上部署Haproxy，您可以通过覆盖实例级变量，仅在特定实例/节点上启用Haproxy负载均衡器。

`haproxy_reload`

是否重载Haproxy配置, 类型：bool，层级：A，默认值为：true

如果关闭，则Pigsty在渲染HAProxy配置文件后不会执行Reload操作，给用户手工介入检查确认的机会。

`haproxy_auth_enabled`

是否对Haproxy管理界面启用认证, 类型：bool，层级：G/C，默认值为：false

默认不启用，建议在生产环境启用，或在Nginx或其他接入层添加访问控制。

`haproxy_admin_username`

HAproxy管理员名称, 类型：string，层级：G，默认值为："admin"

`haproxy_admin_password`

HAproxy管理员密码, 类型：string，层级：G，默认值为："pigsty"

`haproxy_exporter_port`

HAproxy指标暴露器端口, 类型：int，层级：C，默认值为：9101

`haproxy_client_timeout`

HAproxy客户端超时, 类型：interval，层级：C，默认值为："24h"

`haproxy_server_timeout`

HAproxy服务端超时, 类型：interval，层级：C，默认值为："24h"

`vip_mode`

VIP模式：none, 类型：enum，层级：C，默认值为："none"

none：不设置VIP，默认选项。
l4 ：预留值，通过外部L4负载均衡器进行流量分发。（未纳入Pigsty当前实现中）

VIP用于确保读写服务与负载均衡器的高可用，当使用L2 VIP时，Pigsty的VIP由vip-manager托管，会绑定在集群主库上。

这意味着您始终可以通过VIP访问集群主库，或者通过VIP访问主库上的负载均衡器（如果主库的压力很大，这样做可能会有性能压力）。

`vip_reload`

是否重载VIP配置, 类型：bool，层级：A，默认值为：true

`vip_address`

集群使用的VIP地址, 类型：string，层级：C，默认值为：

`vip_cidrmask`

VIP地址的网络CIDR掩码长度, 类型：int，层级：C，默认值为：

`vip_interface`

VIP使用的网卡, 类型：string，层级：C/I，默认值为：

`dns_mode`

DNS配置模式（保留参数）, 类型：enum，层级：C，默认值为：

DNS解析对象选择器（保留参数）, 类型：，层级：C，默认值为：