PGSQL on PIGSTY

被动故障切换

Mon, 01 Jan 0001 00:00:00 +0000

RTO 时序图

故障模型

项目	最好	最坏	平均	说明
租约过期	`ttl - loop`	`ttl`	`ttl - loop/2`	最好：即将刷新时宕机最坏：刚刷新完就宕机
从库检测	`0`	`loop`	`loop / 2`	最好：恰好在检测点最坏：刚错过检测点
抢锁提拔	`0`	`2`	`1`	最好：直接抢锁提升最坏：API 超时+Promote
健康检查	`(rise-1) × fastinter`	`(rise-1) × fastinter + inter`	`(rise-1) × fastinter + inter/2`	最好：检查前状态变化最坏：检查后瞬间状态变化

被动故障与主动故障的核心区别：

默认配置模板的参数优化策略说明

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 默认提供了四套场景化参数模板，可以通过 pg_conf 参数指定并使用。

tiny.yml：为小节点、虚拟机、小型演示优化（1-8核，1-16GB）
oltp.yml：为 OLTP 工作负载和延迟敏感应用优化（4C8GB+）（默认模板）
olap.yml：为 OLAP 工作负载和吞吐量优化（4C8G+）
crit.yml：为数据一致性和关键应用优化（4C8G+）

Pigsty 会针对这四种默认场景，采取不同的参数优化策略，如下所示：

内存参数调整

Pigsty 默认会检测系统的内存大小，并以此为依据设定最大连接数量与内存相关参数。

pg_max_conn：postgres 最大连接数，auto 将使用不同场景下的推荐值
pg_shared_buffer_ratio：内存共享缓冲区比例，默认为 0.25

默认情况下，Pigsty 使用 25% 的内存作为 PostgreSQL 共享缓冲区，剩余的 75% 作为操作系统缓存。

默认情况下，如果用户没有设置一个 pg_max_conn 最大连接数，Pigsty 会根据以下规则使用默认值：

oltp: 500 (pgbouncer) / 1000 (postgres)
crit: 500 (pgbouncer) / 1000 (postgres)
tiny: 300
olap: 300

其中对于 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 核数进行参数优化。在所有策略中，总并行进程数量（总预算）通常设置为 CPU 核数 + 8，且保底为 16 个，从而为逻辑复制与扩展预留足够的后台 worker 数量，OLAP 和 TINY 模板根据场景略有不同。

管理 PostgreSQL 数据库集群

Mon, 01 Jan 0001 00:00:00 +0000

速查手册

操作	快捷命令	说明
创建集群	`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/pgsql-add pg-test # 例子，添加 pg-test 分组下的节点，实际执行 ./node.yml -l pg-test

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

集群实例

Mon, 01 Jan 0001 00:00:00 +0000

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

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

读写主库：定义单一实例集群。
只读从库：定义具有一个主库和一个副本的基本 HA 集群。
离线从库：定义专用于 OLAP/ETL/交互式查询的实例
同步备库：启用同步提交以确保没有数据丢失。
法定人数提交：使用多数同步提交获得更高的一致性级别。
备份集群：克隆现有集群并跟随它
延迟集群：克隆现有集群用于紧急数据恢复
Citus集群：定义一个 Citus 分布式数据库集群

读写主库

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

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

这段配置言简意赅，自我描述，仅由 身份参数 构成，请注意 Ansible Group 分组名应当与 pg_cluster 保持一致。

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

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

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

OLTP 模板

Mon, 01 Jan 0001 00:00:00 +0000

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 # 操作系统调优模板（默认值）

或显式指定：

内核版本

Mon, 01 Jan 0001 00:00:00 +0000

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

Pigsty v4.3 当前支持 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 兼容语法）
`oriole`	OrioleDB 存储引擎
`agens`	AgensGraph 图数据库内核
`pgedge`	pgEdge 分布式复制内核
`oracle`	PostgreSQL + ora 兼容（`pg_mode: oracle`）

选择模式后，Pigsty 会自动加载对应的模板、依赖包与 Patroni 配置。以部署 Citus 为例：

管理 PostgreSQL 业务用户

Mon, 01 Jan 0001 00:00:00 +0000

快速上手

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 用户

关于用户定义参数的完整参考，请查阅 用户配置。关于用户的访问权限，请参考 ACL：角色权限。

主动故障检测

Mon, 01 Jan 0001 00:00:00 +0000

RTO 时序图

故障模型

项目	最好	最坏	平均	说明
故障检测	`0`	`loop`	`loop/2`	最好：PG 恰好在检测前崩溃最坏：PG 刚检测完就崩溃
重启超时	`0`	`start`	`start`	最好：PG 瞬间自愈最坏：等满 start 超时才释放租约
从库检测	`0`	`loop`	`loop/2`	最好：恰好在检测点最坏：刚错过检测点
抢锁提拔	`0`	`2`	`1`	最好：直接抢锁提升最坏：API 超时 + Promote
健康检查	`(rise-1) × fastinter`	`(rise-1) × fastinter + inter`	`(rise-1) × fastinter + inter/2`	最好：检查前状态变化最坏：检查后瞬间状态变化

主动故障与被动故障的核心区别：

OLAP 模板

Mon, 01 Jan 0001 00:00:00 +0000

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 模板用于专用的离线从库：

别名翻译

Mon, 01 Jan 0001 00:00:00 +0000

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 内核，扩展，以及工具包：

管理 PostgreSQL 业务数据库

Mon, 01 Jan 0001 00:00:00 +0000

快速上手

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 数据库

关于数据库定义参数的完整参考，请查阅 数据库配置。关于数据库的访问权限，请参考 ACL：数据库权限。

CRIT 模板

Mon, 01 Jan 0001 00:00:00 +0000

crit.yml 是针对核心金融业务优化的配置模板。适用于 4-128 核 CPU 的服务器，特点是强制同步复制、数据校验和、完整审计日志、严格的安全设置。这个模板牺牲一定的性能来换取最高级别的数据安全性。

建议同时使用 node_tune = crit 进行操作系统级别的配套调优，优化脏页数量。

适用场景

CRIT 模板适用于以下场景：

金融交易：银行转账、支付清算、证券交易
核心账务：总账系统、会计系统
合规审计：需要完整操作记录的业务
关键业务：任何不能容忍数据丢失的场景

特征需求：

零数据丢失（RPO = 0）
数据完整性校验
完整的审计日志
严格的安全策略
可以接受一定的性能损失

使用方法

在集群定义中指定 pg_conf = crit.yml：

pg-finance:
 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-finance
 pg_conf: crit.yml  # PostgreSQL 关键业务模板
 node_tune: crit  # 操作系统关键业务调优

建议：关键业务集群至少配置 3 个节点，以确保在一个节点故障时仍能保持同步复制。

管理 Patroni 高可用

Mon, 01 Jan 0001 00:00:00 +0000

概览

Pigsty 使用 Patroni 管理 PostgreSQL 集群，它可以用来修改集群配置，查看集群状态，执行主从切换，重启集群，重做从库等操作。

要使用 Patroni 进行管理，您需要有以下两种身份之一：

从 INFRA 节点 上使用 管理员用户，可以管理环境中的所有集群。
从 PGSQL节点 上使用 pg_dbsu （默认为 postgres），可以管理当前集群。

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 参数。

用户/角色

Mon, 01 Jan 0001 00:00:00 +0000

在本文中，“用户”（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 字段外，其他字段均为可选字段：

TINY 模板

Mon, 01 Jan 0001 00:00:00 +0000

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 个连接足以应对开发测试场景。

Pgbouncer 连接池管理

Mon, 01 Jan 0001 00:00:00 +0000

概览

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: 64 # 默认池大小
 pool_reserve: 32 # 保留池大小
 pool_size_min: 0 # 最小池大小
 pool_connlimit: 100 # 最大数据库连接数
 - name: internal
 pgbouncer: false # 不加入连接池

用户管理：在 pg_users 中定义的用户，需要显式设置 pgbouncer: true 才会加入连接池用户列表。

数据库

Mon, 01 Jan 0001 00:00:00 +0000

在本文中，“数据库”（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 字段外，其他字段均为可选字段：

HBA 规则

Mon, 01 Jan 0001 00:00:00 +0000

概述

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

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

参数配置

Mon, 01 Jan 0001 00:00:00 +0000

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。更多详情请参阅 场景模板。

访问控制

Mon, 01 Jan 0001 00:00:00 +0000

访问控制由“角色体系 + 权限模板 + HBA”共同决定。本节聚焦于如何通过配置参数声明角色与对象权限。

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

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

理解这些参数后，你就可以写出完全可复现的权限配置。

默认角色体系（pg_default_roles）

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

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

这些定义位于 pg_default_roles，理论上可以自定义，但若要替换名称，必须同步更新 HBA/ACL/脚本中的引用。

示例：为离线任务额外加一个 dbrole_etl：

pg_default_roles:
 - { name: dbrole_etl, login: false, roles: [dbrole_offline], comment: 'etl read-only role' }
 - { name: dbrole_admin, login: false, roles: [pg_monitor, dbrole_readwrite, dbrole_etl] }

效果：所有继承 dbrole_admin 的用户自动拥有 dbrole_etl 权限，可访问 offline 实例并执行 ETL。

管理 PostgreSQL 组件服务

Mon, 01 Jan 0001 00:00:00 +0000

概述

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 服务失效时的应急逃生窗口。

管理 PostgreSQL 定时任务

Mon, 01 Jan 0001 00:00:00 +0000

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'

推荐的维护计划

升级 PostgreSQL 大小版本

Mon, 01 Jan 0001 00:00:00 +0000

快速上手

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;'

关于在线迁移的详细流程，请参考 在线迁移 文档。

管理 PostgreSQL 扩展插件

Mon, 01 Jan 0001 00:00:00 +0000

快速上手

Pigsty 提供 510 扩展，使用扩展涉及四个步骤：下载、安装、配置、启用。

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 # 安装指定扩展

关于扩展的完整参考，请查阅 扩展插件 章节。关于可用扩展列表，请参考 扩展目录。

PG 高可用

Mon, 01 Jan 0001 00:00:00 +0000

概览

Pigsty 的 PostgreSQL 集群带有开箱即用的高可用方案，由 Patroni、Etcd 和 HAProxy 提供核心能力。

当您的 PostgreSQL 集群含有两个或更多实例时，您无需任何配置即拥有了硬件故障自愈的数据库高可用能力 —— 只要集群中有任意实例存活，集群就可以对外提供完整的服务，而客户端只要连接至集群中的任意节点，即可获得完整的服务，而无需关心主从拓扑变化。

在默认配置下，主库故障恢复时间目标 RTO ≈ 45s，数据恢复点目标 RPO < 1MB；从库故障 RPO = 0，RTO ≈ 0 (闪断)；在一致性优先模式下，可确保故障切换数据零损失： RPO = 0。以上指标均可通过参数，根据您的实际硬件条件与可靠性要求 按需配置。

Pigsty 内置了 HAProxy 负载均衡器用于自动流量切换，提供 DNS/VIP/LVS 等多种接入方式供客户端选用。故障切换与主动切换对业务侧除零星闪断外几乎无感知，应用不需要修改连接串重启。极小的维护窗口需求带来了极大的灵活便利：您完全可以在无需应用配合的情况下滚动维护升级整个集群。硬件故障可以等到第二天再抽空善后处置的特性，让研发，运维与 DBA 都能在故障时安心睡个好觉。

许多大型组织与核心机构已经在生产环境中长时间使用 Pigsty，最大的部署有 25K CPU 核心与 220+ PostgreSQL 超大规格实例（64c / 512g / 3TB NVMe SSD）；在这一部署案例中，五年内经历了数十次硬件故障与各类事故，但依然可以保持高于 99.999% 的总体可用性战绩。

高可用（High-Availability）解决什么问题？

将数据安全 C/IA 中的可用性提高到一个新高度：RPO ≈ 0, RTO < 45s。
获得无缝滚动维护的能力，最小化维护窗口需求，带来极大便利。
硬件故障可以立即自愈，无需人工介入，运维 DBA 可以睡个好觉。
从库可以用于承载只读请求，分担主库负载，让资源得以充分利用。

高可用有什么代价？

基础设施依赖：高可用需要依赖 DCS (etcd/zk/consul) 提供共识。
起步门槛增加：一个有意义的高可用部署环境至少需要 三个节点。
额外的资源消耗：一个新从库就要消耗一份额外资源，不算大问题。
复杂度代价显著升高：备份成本显著加大，需要使用工具压制复杂度。

高可用的局限性

RPO 利弊权衡

Mon, 01 Jan 0001 00:00:00 +0000

RPO（Recovery Point Objective，恢复点目标）定义了在主库发生故障时，允许丢失的最大数据量。

对于金融交易这类数据完整性至关重要的场景，通常要求 RPO = 0，即不允许任何数据丢失；

然而更为严格的 RPO 指标是有代价的，它会引入更高的写入延迟，降低系统吞吐量，并且存在从库故障导致主库不可用的风险。因此对于常规场景，通常可以接受一定量的数据丢失（例如允许丢失不超过 1MB 的数据），以换取更高的可用性与性能。

利弊权衡

通常在异步复制场景下，从库和主库之间会存在一定的复制延迟（取决于网络和吞吐量，正常在 10KB-100KB / 100µs-10ms 的数量级），这意味着当主库发生故障时，从库可能还没有完全同步主库的最新数据。这时候如果出现故障切换，新的主库可能会丢失一些尚未复制的数据。

潜在数据丢失量的上限由 pg_rpo 参数控制，默认为 1048576 （1MB），这意味着在故障转移期间最多可以容忍 1MiB 的数据丢失。

当集群主库宕机时，如果有任何一个从库的复制延迟在这个值以内，Pigsty 将自动提升该从库为新的主库。然而当所有从库副本的复制延迟都超出这个阈值时，Pigsty 将拒绝进行 [自动故障切换] 以避免数据丢失。此时需要人工介入进行决策 —— 等待主库恢复（可能永远也不会恢复），还是接受数据损失并强制提升一个从库为新的主库。

您需要根据业务的需求偏好配置这个值，在 可用性 和 一致性 之间进行 利弊权衡。增大这个值可以提高自动故障切换的成功率，但也会增加潜在的数据丢失量上限。

当您指定 pg_rpo = 0 时，Pigsty 将启用 同步复制，确保主库在确认至少一个从库持久化数据后才返回写入成功。这种配置能确保没有复制延迟，但会带来显著的写入延迟，并降低整体的吞吐量。

flowchart LR
 A([主库故障]) --> B{同步复制?}

 B -->|否| C{延迟 < RPO?}
 B -->|是| D{同步从库<br/>可用?}

 C -->|是| E[有损自动故障切换<br/>RPO < 1MB]
 C -->|否| F[拒绝自动切换<br/>等待主库恢复<br/>或人工介入决策]

 D -->|是| G[无损自动故障切换<br/>RPO = 0]
 D -->|否| H{严格模式?}

 H -->|否| C
 H -->|是| F

 style A fill:#dc3545,stroke:#b02a37,color:#fff
 style E fill:#F0AD4E,stroke:#146c43,color:#fff
 style G fill:#198754,stroke:#146c43,color:#fff
 style F fill:#BE002F,stroke:#565e64,color:#fff

保护模式

Pigsty 提供三种保护模式，以帮助用户在不同的 RPO 要求下进行利弊权衡，类似于 Oracle Data Guard 的数据保护模式。

PGSQL 架构

Mon, 01 Jan 0001 00:00:00 +0000

PGSQL 模块在生产环境中以集群的形式组织，这些集群是由一组通过 主-备 关联的数据库实例组成的 逻辑实体。

概览

PGSQL 模块 包含下列组件，协同提供生产级 PostgreSQL 高可用集群服务：

组件	简介	描述
`postgres`	数据库	世界上最先进的开源关系型数据库，PGSQL 模块的核心。
`patroni`	高可用	托管 PostgreSQL 进程，协调故障转移、选主、配置变更。
`pgbouncer`	连接池	轻量级连接池中间件，复用连接、降低开销、提供额外灵活性。
`pgbackrest`	备份恢复	全量/增量备份与 WAL 归档，支持本地与对象存储。
`pg_exporter`	指标导出	导出 PostgreSQL 监控指标供 Prometheus 抓取。
`pgbouncer_exporter`	指标导出	导出 Pgbouncer 连接池指标。
`pgbackrest_exporter`	指标导出	导出 pgBackrest 备份状态指标。
`vip-manager`	VIP 管理	将 L2 VIP 绑定到当前主库节点，实现透明漂移。【可选】

其中 vip-manager 为按需启用的组件。此外，PGSQL 还会使用到其他模块中的组件：

组件	模块	简介	描述
`haproxy`	NODE	负载均衡	对外暴露服务端口，根据角色分发流量至主库或从库。
`vector`	NODE	日志采集	收集 PostgreSQL、Patroni、Pgbouncer 等日志推送至中心。
`etcd`	ETCD	DCS	分布式一致性存储，用于保存集群元数据与领导者信息。

如果用类比来形容，PostgreSQL 数据库内核就是 CPU，而整个 PGSQL 模块将其封装为一台完整的计算机。 Patroni 与 Etcd 组成高可用子系统，pgBackRest 与 MinIO 组成备份恢复子系统。 HAProxy 与 Pgbouncer、vip-manager 组成接入子系统。各种 Exporter 与 Vector 构成可观测性子系统；最后还可以替换不同的 内核 CPU 与 扩展卡。

RTO 利弊权衡

Mon, 01 Jan 0001 00:00:00 +0000

RTO（Recovery Time Objective，恢复时间目标）定义了在主库发生故障时，系统恢复写入能力所需的最长时间。

对于核心交易系统这类可用性至关重要的场景，通常要求 RTO 尽可能短，例如一分钟内。

然而更短的 RTO 指标是有代价的，它会增加误切风险：网络抖动可能被误判为故障，导致不必要的故障切换。因此对于跨机房/跨地域部署的场景，通常需要放宽 RTO 要求（例如 1-2 分钟），以降低误切风险。

利弊权衡

故障切换时的不可用时长上限由 pg_rto 参数控制。Pigsty 提供了四种预设的 RTO 模式： fast、norm、safe、wide，分别针对不同的网络条件与部署场景进行了优化，默认使用 norm 模式（约 45 秒）。您也可以使用秒数直接指定 RTO 上限，系统会自动映射到最接近的模式。

当主库发生故障时，整个恢复流程涉及多个阶段：Patroni 检测故障、DCS 锁过期、新主选举、执行 promote、HAProxy 感知新主。减小 RTO 意味着缩短各阶段的超时时间，这会使集群对网络抖动更加敏感，从而增加误切风险。

您需要根据实际网络条件选择合适的模式，在 恢复速度 与 误切风险 之间取得平衡。网络质量越差，越应该选择保守的模式；网络质量越好，越可以选择激进的模式。

flowchart LR
 A([主库故障]) --> B{Patroni<br/>检测到?}

 B -->|PG崩溃| C[尝试本地重启]
 B -->|节点宕机| D[等待 TTL 过期]

 C -->|成功| E([本地恢复])
 C -->|失败/超时| F[释放 Leader 锁]

 D --> F
 F --> G[从库竞选]
 G --> H[执行 Promote]
 H --> I[HAProxy 感知]
 I --> J([服务恢复])

 style A fill:#dc3545,stroke:#b02a37,color:#fff
 style E fill:#198754,stroke:#146c43,color:#fff
 style J fill:#198754,stroke:#146c43,color:#fff

四种模式

Pigsty 提供四种 RTO 模式，以帮助用户在不同的网络条件下进行利弊权衡。

故障切换模型

Mon, 01 Jan 0001 00:00:00 +0000

Patroni 故障按故障对象分类可以分为以下 10 类，按照检测路径不同，可以进一步归纳为五类，在本节内详细展开。

#	故障场景	描述	最终走哪条路径
1	PG 进程崩溃	crash、OOM killed	主动检测
2	PG 拒绝连接	max_connections	主动检测
3	PG 假活	进程在但无响应	主动检测 (检测超时)
4	Patroni 进程崩溃	kill -9、OOM	被动检测
5	Patroni 假活	进程在但卡住	Watchdog
6	节点宕机	断电、硬件故障	被动检测
7	节点假活	IO hang、CPU 饥饿	Watchdog
8	主库 ↔ DCS 网络中断	防火墙、交换机故障	网络分区
9	存储故障	磁盘坏、磁盘满、挂载失败	主动检测或 Watchdog
10	手动切换	Switchover/Failover	手动触发

但是在 RTO 计算上，最终所有故障都会收敛到两条路径上，本节深入探讨了这两种情况下的 RTO 上下限与均值。

flowchart LR
 A([主库故障]) --> B{Patroni<br/>检测到?}

 B -->|PG崩溃| C[尝试本地重启]
 B -->|节点宕机| D[等待 TTL 过期]

 C -->|成功| E([本地恢复])
 C -->|失败/超时| F[释放 Leader 锁]

 D --> F
 F --> G[从库竞选]
 G --> H[执行 Promote]
 H --> I[HAProxy 感知]
 I --> J([服务恢复])

 style A fill:#dc3545,stroke:#b02a37,color:#fff
 style E fill:#198754,stroke:#146c43,color:#fff
 style J fill:#198754,stroke:#146c43,color:#fff

时间点恢复

Mon, 01 Jan 0001 00:00:00 +0000

当您不小心删除了数据、表、甚至整个数据库时，PITR 能力让您回到过去任意时刻，避免软件缺陷与人为失误导致的数据损失。

—— 这个曾经只有资深 DBA 才能施展的『魔法』，现在对所有用户都可以轻松做到零配置开箱即用。

概览

Pigsty 的 PostgreSQL 集群带有自动配置的时间点恢复（PITR）方案，基于 pgBackRest 与可选的对象存储仓库 MinIO 提供。

高可用方案 可以解决硬件故障，但却对软件缺陷与人为失误导致的数据删除/覆盖写入/删库等问题却无能为力。对于这种情况，Pigsty 提供了开箱即用的 时间点恢复（Point in Time Recovery, PITR）能力，无需额外配置即默认启用。

Pigsty 为您提供了基础备份与 WAL 归档的默认配置，您可以使用本地目录与磁盘，亦或专用的 MinIO 集群或 S3 对象存储服务来存储备份并实现异地容灾。当您使用本地磁盘时，默认保留恢复至过去一天内的任意时间点的能力。当您使用 MinIO 或 S3 时，默认保留恢复至过去一周内的任意时间点的能力。只要存储空间管够，您尽可保留任意长地可恢复时间段，丰俭由人。

时间点恢复解决什么问题？

容灾能⼒增强：RPO 从 ∞ 降⾄⼗⼏MB， RTO 从 ∞ 降⾄⼏⼩时/⼏刻钟。
确保数据安全：C/I/A 中的 数据完整性：避免误删导致的数据⼀致性问题。
确保数据安全：C/I/A 中的 数据可⽤性：提供对“永久不可⽤”这种灾难情况的兜底

单实例配置策略	事件	RTO	RPO
什么也不做	宕机	永久丢失	全部丢失
基础备份	宕机	取决于备份大小与带宽（几小时）	丢失上一次备份后的数据（几个小时到几天）
基础备份 + WAL 归档	宕机	取决于备份大小与带宽（几小时）	丢失最后尚未归档的数据（几十 MB）

时间点恢复有什么代价？

降低数据安全中的 C：机密性，产生额外泄漏点，需要额外对备份进⾏保护。
额外的资源消耗：本地存储或⽹络流量 / 带宽开销，通常并不是⼀个问题。
复杂度代价升⾼：⽤户需要付出备份管理成本。

时间点恢复的局限性

如果只有 PITR 用于故障恢复，则 RTO 与 RPO 指标相比 高可用方案 更为逊色，通常应两者组合使用。

时间点恢复的工作原理

Mon, 01 Jan 0001 00:00:00 +0000

时间点恢复（PITR）的核心原理是：基础备份 + WAL 归档 = 任意时间点恢复能力。在 Pigsty 中，这一能力由 pgBackRest 实现，并通过 定时备份 + WAL 归档 自动运行。

三要素

要素	作用	Pigsty 实现
基础备份	提供一致的物理快照，决定恢复起点	`pg-backup` + `pgbackrest` + `pg_crontab`
WAL 归档	记录备份后的所有变更，决定恢复路径	`archive_mode=on` + `archive_command=pgbackrest ... archive-push`
恢复目标	指定恢复停止位置	`pg_pitr` 参数 / `pg-pitr` 脚本 / `pgbackrest restore`

基础备份

基础备份是数据库在某一时刻的物理快照，是 PITR 的恢复起点。Pigsty 通过 pgBackRest 生成基础备份，并提供 pg-backup 脚本封装常用操作。

备份类型

类型	说明	恢复开销
全量备份（Full）	复制全部数据文件	恢复最快，空间占用最大
差异备份（Differential）	相对最近一次全量备份的变化	恢复需要全量 + 差异
增量备份（Incremental）	相对最近一次任意备份的变化	空间最省，恢复需要完整链路

Pigsty 的默认行为

pg-backup 默认执行增量备份，若不存在全量备份会自动补一次全量。
备份任务通过 pg_crontab 配置，写入 postgres 用户的 crontab。
脚本会自动识别节点角色，只有主库实际执行，从库会直接退出。

备份频率越高，需要重放的 WAL 越少，恢复速度越快。更多细节请参阅 备份机制 与 备份策略。

时间点恢复的实现架构

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 使用 pgBackRest 作为 PostgreSQL 备份与恢复引擎，提供开箱即用的时间点恢复（PITR）能力。

本文从架构层面说明：备份由谁执行、数据流向哪里、仓库如何组织、故障切换后如何保持连续性。

概览

PITR 架构由三条主线构成：备份执行链路、WAL 归档链路、恢复执行链路。

链路	入口	引擎	终点
备份	`pg-backup` + `pg_crontab`	`pgbackrest backup`	备份仓库 `backup/`
WAL 归档	PostgreSQL `archive_command`	`pgbackrest archive-push`	备份仓库 `archive/`
恢复	`pg_pitr` / `pg-pitr` / `pgsql-pitr.yml`	`pgbackrest restore`	目标数据目录

更多执行细节见 备份机制 与 恢复操作。

组件与职责

组件	角色	描述
PostgreSQL	数据源	产生数据文件与 WAL 归档流
pgBackRest	备份引擎	执行备份、接收/拉取 WAL、执行恢复
pg-backup	备份入口	Pigsty 封装脚本，执行 `pgbackrest backup`
pg_pitr / pg-pitr	恢复入口	Pigsty 封装参数/脚本，执行 `pgbackrest restore`
备份仓库	存储后端	保存 `backup/` 与 `archive/`，支持 `local` / `minio` / `s3` 等仓库
pgbackrest_exporter	监控输出	导出备份状态指标，默认监听 `9854` 端口

数据流

flowchart TB
 subgraph cluster["PostgreSQL 集群"]
 direction TB
 primary["Primary<br/>PostgreSQL"]
 pb["pgBackRest"]
 cron["pg-backup / pg_crontab"]
 end
 repo["备份仓库<br/>local / minio / s3"]
 restore["恢复目标数据目录"]

 cron --> pb
 primary -->|base backup| pb
 primary -->|WAL archive| pb
 pb -->|backup/archive| repo
 repo -->|restore/archive-get| pb
 pb -->|restore| restore

要点：

时间点恢复的策略权衡

Mon, 01 Jan 0001 00:00:00 +0000

设计 PITR 策略时，最核心的权衡来自三个维度： 备份仓库位置、恢复窗口长度、恢复速度与空间成本。

本文帮助您在这些维度之间做出可操作的选择。

本地 vs 远程

备份仓库的位置是 PITR 策略设计的第一步。

本地仓库

将备份存储在主库本地磁盘（pgbackrest_method = local）：

优势

配置简单，开箱即用
恢复速度快（本地 I/O）
无外部依赖

劣势

无异地容灾能力，主机故障时备份可能一同丢失
受限于本地磁盘容量
备份与生产数据位于同一故障域

远程仓库

将备份存储到 MinIO / S3 等对象存储（pgbackrest_method = minio|s3）：

优势

异地容灾，备份独立于数据库主机
容量几乎无限，多集群可共享
可配合加密、版本控制等安全策略

劣势

恢复速度受网络带宽影响
依赖对象存储的可用性
部署与运维成本更高

如何选择

场景	推荐仓库	理由
开发测试	local	简单够用，容灾要求低
单机生产	minio / s3	主机故障仍可恢复
集群生产	local + minio	兼顾恢复速度与异地容灾
关键业务	多远程仓库	多地容灾，最高保护

仓库配置细节请参阅 备份仓库。

空间 vs 窗口

恢复窗口越长，所需存储空间越大。窗口长度由 备份保留策略 + WAL 归档保留 决定。

时间点恢复的典型场景

Mon, 01 Jan 0001 00:00:00 +0000

PITR 的价值不在于“回滚数据库”本身，而在于把不可逆的人为/软件错误变回可恢复的问题。它覆盖的场景从“误删一张表”到“整个机房不可用”，本质上解决的是逻辑错误与灾难恢复。

整体认知（Overview）

PITR 解决以下问题：

场景类型	典型问题	推荐策略	恢复目标
误删/误更新数据（DML）	`DELETE/UPDATE` 无条件执行，脚本误操作	分支恢复优先	`time` / `xid`
误删表/库/Schema（DDL）	`DROP TABLE/DATABASE`、错误迁移	分支恢复	`time` / `name`
批量错误/发布事故	Bug 批量污染数据，修复脚本失败	分支恢复 + 验证	`time` / `xid`
数据审计/问题复盘	需要查看历史状态，核对差异	分支恢复（只读）	`time` / `lsn`
机房级灾难/全量丢失	硬件故障、勒索、机房断电	原地恢复或重建集群	`latest` / `time`

一个简单的判断原则

只要写入已经造成业务错误，就应该考虑 PITR。
需要在线验证或只恢复部分数据 → 分支恢复。
必须尽快恢复服务 → 原地恢复（可接受停机）。

flowchart TD
 A["发现问题"] --> B{"能否停机？"}
 B -->|能| C["原地恢复<br/>最短恢复路径"]
 B -->|不能| D["分支恢复<br/>先验证后切换"]
 C --> E["恢复成功后重建备份"]
 D --> F["验证/导出/切流量"]

场景详情

误删/误更新数据（DML）

典型问题：

安全合规

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 的安全目标是 CIA 三元组：

机密性：防止未授权访问与泄露
完整性：防止数据被篡改或静默损坏
可用性：防止故障导致业务中断

Pigsty 的安全理念：

默认安全：开箱即用的安全基线，配置少、覆盖广。
纵深防御：多层保护叠加，单点失守不致系统失守。
最小权限：角色与权限模型贯彻最小授权原则。
可合规：安全能力与流程结合即可通过合规检查。

默认安全基线（解决什么问题）

安全选项	默认值	解决的问题
密码加密	`pg_pwd_enc: scram-sha-256`	防止弱哈希与明文泄露
数据校验	`pg_checksum: true`	检测静默数据损坏
HBA 分层	管理员外网必须 `ssl`	防止外网明文访问
本地 CA	`ca_create: true`	统一证书信任链
备份恢复	`pgbackrest_enabled: true`	防止误删误改不可恢复
Nginx HTTPS	`nginx_sslmode: enable`	防止 Web 入口明文泄露
MinIO HTTPS	`minio_https: true`	防止备份链路窃听
OS 基线	SELinux `permissive`	为强制模式预留基础

默认配置以“可用、可扩展”为先，生产环境应根据合规要求加固。

加固路线图

Pigsty 提供安全增强模板 conf/ha/safe.yml，可快速将默认基线升级到更高安全级别：

强制 SSL 与证书认证
密码强度与过期策略
连接与断开日志
防火墙与 SELinux 加固

本章内容

章节	说明	核心问题
纵深防御	七层安全模型与基线	安全体系整体如何落地？
身份认证	HBA 规则、密码策略、证书认证	如何验证用户身份？
访问控制	角色系统、权限模型、数据库隔离	如何控制用户权限？
加密通信	TLS、本地 CA、证书管理	如何保护传输与证书？
数据安全	校验和、备份、加密与恢复	数据如何完整可恢复？
合规清单	等保三级与 SOC2 对照	如何满足合规要求？

七层安全模型

Mon, 01 Jan 0001 00:00:00 +0000

安全不是一道墙，而是一座城。Pigsty 采用纵深防御策略，在七个层次上构建多重保护，即使某一层被突破，仍有其他层提供保护。

这种分层思路解决三类核心风险：

边界被突破：降低“单点失守导致全盘失守”的概率。
内部滥用：即使内部账号被盗，也能通过最小权限限制破坏范围。
不可预期故障：硬件、软件、人为错误都能被“多层兜底”。

概览

L1 物理与介质安全

物理层失守时，唯一的对抗手段是数据本身的自我保护。

身份认证

Mon, 01 Jan 0001 00:00:00 +0000

身份认证解决三个核心问题：

你是谁：身份是否唯一可识别？
你怎么证明：密码/证书是否足够安全？
你从哪里来：来源是否受控？

Pigsty 使用 HBA 规则 + 密码/证书 完成身份认证，并以 SCRAM 为默认密码哈希方案。

认证链路

flowchart LR
 C[客户端] --> HBA[HBA 规则]
 HBA --> A1[密码 SCRAM]
 HBA --> A2[证书认证]
 HBA --> A3[本地 ident/peer]
 A1 --> RBAC[角色与权限]
 A2 --> RBAC
 A3 --> RBAC

HBA 决定“谁能从哪里来”，认证方式决定“如何证明身份”。

HBA 分层模型

Pigsty 默认 HBA 规则已经分层：

本地使用 ident/peer，最安全。
内网使用 scram 密码认证。
外网管理员必须走 ssl。

这解决了“同一个用户在不同来源使用不同认证强度”的问题。

HBA 规则的关键能力

顺序优先：支持 order 排序，数值越小优先级越高。
地址别名：local / localhost / intra / world 等。
角色条件：primary/replica/offline 可精细化控制。

密码认证

默认密码哈希算法：

访问控制

Mon, 01 Jan 0001 00:00:00 +0000

访问控制解决两个核心问题：

你能做什么：读/写/DDL 的权限边界
你能访问哪些数据：跨库、跨模式的隔离边界

Pigsty 通过 RBAC 角色体系 + 默认权限策略 将“最小权限”落实为默认行为。

四层角色模型

flowchart TB
 subgraph Admin["dbrole_admin（管理员）"]
 A1["可执行 DDL / CREATE / ALTER"]
 A2["继承 dbrole_readwrite"]
 end
 subgraph RW["dbrole_readwrite（读写）"]
 RW1["可 INSERT/UPDATE/DELETE"]
 RW2["继承 dbrole_readonly"]
 end
 subgraph RO["dbrole_readonly（只读）"]
 RO1["可 SELECT 所有表"]
 end
 subgraph Offline["dbrole_offline（离线）"]
 OFF1["仅离线实例可用"]
 end

 Admin --> RW --> RO

解决的问题

生产账号天然拥有过高权限
DDL 与 DML 不分离导致误操作风险

默认角色与系统用户

Pigsty 默认提供四个角色与四个系统用户（来自源码默认值）：

角色/用户	属性	继承/角色	描述
`dbrole_readonly`	`NOLOGIN`	-	全局只读访问
`dbrole_offline`	`NOLOGIN`	-	受限只读（离线实例）
`dbrole_readwrite`	`NOLOGIN`	`dbrole_readonly`	全局读写访问
`dbrole_admin`	`NOLOGIN`	`pg_monitor, dbrole_readwrite`	管理员 / 对象创建
`postgres`	`SUPERUSER`	-	系统超级用户
`replicator`	`REPLICATION`	`pg_monitor, dbrole_readonly`	复制用户
`dbuser_dba`	`SUPERUSER`	`dbrole_admin`	管理员用户
`dbuser_monitor`	-	`pg_monitor, dbrole_readonly`	监控用户

这套默认角色可以覆盖绝大多数业务场景。

加密通信与本地 CA

Mon, 01 Jan 0001 00:00:00 +0000

加密通信解决三个问题：

窃听：防止明文流量被监听
篡改：防止中间人修改数据
冒充：防止服务端/客户端被伪造

Pigsty 通过 本地 CA + TLS 为数据库与基础设施组件提供统一的信任根。

本地 CA 的作用

Pigsty 默认会在管理节点生成自签 CA：

files/pki/ca/ca.key # CA 私钥（必须严格保护）
files/pki/ca/ca.crt # CA 根证书（可分发）

源码默认值：

ca_create: true：找不到 CA 时自动生成。
ca_cn: pigsty-ca：CA 证书 CN 固定为 pigsty-ca。
根证书有效期约 100 年（自签）。
由 CA 签发的服务器/客户端证书有效期 cert_validity: 7300d（20 年）。

证书覆盖范围

本地 CA 会签发多种组件证书，统一信任链：

组件	目的	典型路径
PostgreSQL / PgBouncer	连接加密	`/pg/cert/`
Patroni	API 通信	`/pg/cert/`
etcd	DCS 加密	`/etc/etcd/`
MinIO	对象存储 HTTPS	`~minio/.minio/certs/`
Nginx	Web 入口 HTTPS	`/etc/nginx/conf.d/cert/`

解决的问题：不同组件自建证书会产生信任碎片，统一 CA 可以一次分发，多处复用。

数据安全

Mon, 01 Jan 0001 00:00:00 +0000

数据安全关注三件事：完整性、可恢复性、保密性。Pigsty 在默认配置中已启用关键能力，并支持按需加固。

数据完整性

解决的问题

磁盘坏块、内存错误导致的静默损坏
意外写入导致的数据污染

Pigsty 支持

数据校验和：默认 pg_checksum: true，初始化时启用 data-checksums。
副本兜底：主库坏块可从从库恢复（与 HA 配合使用）。

可恢复性（备份与 PITR）

解决的问题

误删误改
灾难性故障导致数据丢失

Pigsty 支持

pgBackRest 默认启用：pgbackrest_enabled: true。
本地仓库：默认保留 2 份完整备份。
远程仓库：可接入 MinIO，支持对象存储与多副本。
PITR：结合 WAL 归档进行任意时间点恢复。

数据保密性

解决的问题

备份被窃导致数据外泄
介质被盗导致明文数据泄露

Pigsty 支持

备份加密：MinIO 仓库支持 AES-256-CBC（cipher_type）。
透明加密（可选）：通过 pg_tde 等扩展实现数据静态加密。
密钥隔离：建议将 cipher_pass 与 CA 私钥分离管理。

审计与可追溯

解决的问题

无法追责与还原操作
合规审计缺少证据

Pigsty 支持

日志收集：模板默认启用 logging_collector。
DDL 审计：log_statement: ddl。
慢查询：log_min_duration_statement。
连接日志：log_connections（PG18+）。
审计扩展：pgaudit、pgauditlogtofile 可选。

加固建议

对远程备份强制加密与专用密钥。
定期演练 PITR，验证恢复链路。
对关键业务启用 pgaudit。
结合高可用形成“备份 + 副本”双层兜底。

接下来

🔐 加密通信：证书管理与 TLS
✅ 合规清单：审计与合规要求
⏰ 备份恢复：PITR 机制与实践

合规清单

Mon, 01 Jan 0001 00:00:00 +0000

合规不是“开关”，而是 配置 + 流程 + 证据 的组合：

配置：安全能力是否启用（HBA/TLS/审计/备份）
流程：是否有权限管理、变更、备份演练等制度
证据：日志、配置快照、备份报告、监控告警

本页以 SOC2 与等保三级为切入点，说明 Pigsty 的安全能力与合规映射。

默认凭证清单（必须修改）

来自源码默认值：

组件	默认用户名	默认密码
PostgreSQL 管理员	`dbuser_dba`	`DBUser.DBA`
PostgreSQL 监控	`dbuser_monitor`	`DBUser.Monitor`
PostgreSQL 复制	`replicator`	`DBUser.Replicator`
Patroni API	`postgres`	`Patroni.API`
HAProxy 管理	`admin`	`pigsty`
Grafana 管理	`admin`	`pigsty`
MinIO Root	`minioadmin`	`S3User.MinIO`
etcd Root	`root`	`Etcd.Root`

生产环境必须修改。

证据准备（建议）

证据类型	说明	Pigsty 支持
配置快照	HBA、角色、TLS、备份策略	`pigsty.yml` / inventory 配置
访问控制	角色与权限	`pg_default_roles` / `pg_default_privileges`
连接审计	连接、断开、DDL	`log_connections` / `log_statement`
备份报告	完整备份与恢复记录	pgBackRest 日志与任务
监控告警	异常事件记录	Prometheus + Grafana
证书管理	CA/证书分发记录	`files/pki/` / `/etc/pki/ca.crt`

SOC2 视角（示例映射）

SOC2 的核心是 安全、可用性、机密性。以下为常见控制点的概念映射：

快速上手 PostgreSQL

Mon, 01 Jan 0001 00:00:00 +0000

PostgreSQL（简称 PG）是世界上最先进、最流行的开源关系型数据库，你可以用它来存储和检索多模态数据。

本指南面向有基础 Linux 基本命令行操作经验、但对 PostgreSQL 不太熟悉的开发者，带你快速上手 Pigsty 中的 PG。

我们假设您是个人用户，使用默认单机模式进行部署。关于生产环境多节点高可用集群的使用，请参考 生产服务接入。

基本知识

默认 单机安装 模板下，您将在当前节点上创建一个名为 pg-meta 的 PostgreSQL 数据库集群，只有一个主库实例。

PostgreSQL 监听在 5432 端口，集群中带有一个预置的数据库 meta 可供使用。

您可以在安装完毕后退出当前管理用户 ssh 会话，并重新登陆刷新环境变量后，通过简单地敲一个 pp 回车，通过命令行工具 psql 访问该数据库集群：

vagrant@pg-meta-1:~$ pp
psql (18.2 (Ubuntu 18.2-1.pgdg24.04+2))
Type "help" for help.

postgres=#

您也可以切换为操作系统的 postgres 用户，直接执行 psql 命令，即可连接到默认的 postgres 管理数据库上。

连接数据库

想要访问 PostgreSQL 数据库，您需要使用命令行工具或者图形化客户端工具，填入 PostgreSQL 的 连接字符串：

postgres://username:password@host:port/dbname

一些驱动和工具也可能会要求你分别填写这些参数，通常以下五项为必选项：

参数	说明	示例值	备注
`host`	数据库服务器地址	`10.10.10.10`	换为你的节点 IP 地址或域名，本机可以省略
`port`	端口号	`5432`	PG 默认端口，可以省略
`username`	用户名	`dbuser_dba`	Pigsty 默认的数据库管理员
`password`	密码	`DBUser.DBA`	Pigsty 默认的管理员密码，（请修改密码）
`dbname`	数据库名	`meta`	默认模板的数据库名称

个人使用时可以直接使用 Pigsty 默认的数据库超级用户 dbuser_dba 进行连接和管理，数据库管理用户 dbuser_dba 拥有数据库的全部权限。默认情况下，如果您在配置 Pigsty 时指定了 configure -g 参数，密码会随机生成，并保存在 ~/pigsty/pigsty.yml 文件中，可以通过以下命令查看：

运维 SOP 索引

Mon, 01 Jan 0001 00:00:00 +0000

上手路线

顺序	要解决的问题	入口
1	Pigsty 由哪些模块组成？	积木式架构，PGSQL 架构，PGSQL 集群模型
2	怎么先跑起来？	快速上手，图形界面，快速上手 PostgreSQL
3	配置文件该怎么看？	声明式配置，配置清单，配置参数
4	生产部署要准备什么？	架构规划，资源准备，管理机制
5	怎么部署多节点集群？	生产部署，执行剧本，PGSQL 剧本
6	日常怎么管库？	PGSQL 日常管理，集群管理，用户管理，数据库管理
7	怎么验证可靠性？	PG 高可用，Patroni 管理，备份恢复，恢复操作

任务索引

任务	先看	操作入口
准备服务器、磁盘、网络、VIP	资源准备，架构规划，Linux 兼容性	生产部署
准备 SSH、Sudo、管理用户	管理机制	生产部署
本地或云上搭沙箱	沙箱环境	Vagrant，Terraform
单机体验	快速上手	`./configure -g`，`./deploy.yml`
多节点生产部署	部署，生产部署	`./deploy.yml`，`./pgsql.yml`
离线环境部署	离线安装	软件仓库管理
选择配置模板	配置模板，模板列表	`./configure -c <template>`
规划集群名、库名、用户名	PGSQL 集群模型	`pg_cluster`，`pg_databases`，`pg_users`
创建数据库集群	集群实例配置	集群管理，`./pgsql.yml -l <cluster>`
新增业务用户	用户/角色配置	用户管理，`./pgsql-user.yml -l <cluster>`
新增业务数据库	数据库配置	数据库管理，`./pgsql-db.yml -l <cluster>`
配置访问入口	服务/接入	`pg_services`，`pg_default_services`
修改 HBA	HBA 配置	HBA 管理
主从切换	Patroni 管理	`patronictl switchover`
HA 故障演练	PG 高可用，RPO，RTO	3坏2应急处理
配置 VIP	HA 服务接入	配置 PG VIP
配置备份策略	备份策略	备份管理命令
做 PITR 时间点恢复	时间点恢复	恢复操作
误删数据、表、库	误删处理	手工恢复
克隆恢复集群	克隆数据库集群	Fork 实例
使用 MinIO 存备份	MINIO 模块	MinIO 配置，备份仓库
查看监控告警	监控系统	PGSQL 监控，PGSQL 仪表盘
排查数据库故障	PGSQL 常见问题	故障排查，组件管理
扩容、缩容 PG 集群	集群实例配置	集群管理
升级 PostgreSQL	版本升级	内核版本
安装或启用扩展	扩展插件	扩展管理
迁移已有数据库	数据迁移	迁移剧本
做安全加固	安全考量	访问控制，CA 与证书
管理域名与 Web 入口	域名管理	Nginx 管理
维护基础设施	INFRA 管理预案	`infra.yml`，`infra-rm.yml`
维护 Etcd	ETCD 配置	ETCD 管理，ETCD FAQ
部署应用模板	应用	Docker 模块，`./app.yml`

准备与部署

生产部署先看 架构规划 和 资源准备。这两篇解决节点数量、磁盘、文件系统、网络、VIP、域名、软件源这些问题。

模块：PGSQL

Mon, 01 Jan 0001 00:00:00 +0000

世界上最先进的开源关系型数据库！

而 Pigsty 帮它进入全盛状态：开箱即用、可靠、可观测、可维护、可伸缩！配置 | 管理 | 剧本 | 监控 | 参数

概览

了解关于 PostgreSQL 的重要主题与概念。

配置

描述你想要的 PostgreSQL 集群

身份参数：定义 PostgreSQL 集群的身份参数
读写主库：创建由单一主库构成的单实例“集群”
只读从库：创建一主一从的两节点基础高可用集群
离线从库：创建专用于 OLAP/ETL/交互式查询的特殊只读实例
同步备库：启用同步提交，以确保没有数据丢失
法定人数：使用法定人数同步提交以获得更高的一致性级别
备份集群：克隆现有集群，并保持同步（异地灾备集群）
延迟集群：克隆现有集群，并延迟重放，用于紧急数据恢复
Citus集群：定义并创建 Citus 水平分布式数据库集群
大版本切换：使用不同的 PostgreSQL 大版本部署集群

管理

管理您所创建的 PostgreSQL 集群。

剧本

使用幂等的剧本，将您的描述变为现实。

pgsql.yml：初始化 PostgreSQL 集群或添加新的从库。
pgsql-rm.yml：移除 PostgreSQL 集群，或移除某个实例
pgsql-user.yml：在现有的 PostgreSQL 集群中添加新的业务用户
pgsql-db.yml：在现有的 PostgreSQL 集群中添加新的业务数据库
pgsql-monitor.yml：将远程 postgres 实例纳入监控中
pgsql-migration.yml：为现有的 PostgreSQL 集群生成迁移手册和脚本

监控

在 Grafana 仪表盘中查阅 PostgreSQL 的详情状态。

配置指南

Mon, 01 Jan 0001 00:00:00 +0000

PGSQL 集群模型

Mon, 01 Jan 0001 00:00:00 +0000

PGSQL 模块在生产环境中以集群的形式组织，这些集群是由一组由主-备关联的数据库实例组成的逻辑实体。

每个集群都是一个自治的业务单元，由至少一个 主库实例 组成，并通过服务向外暴露能力。

在 Pigsty 的 PGSQL 模块中有四种核心实体：

集群（Cluster）：自治的 PostgreSQL 业务单元，用作其他实体的顶级命名空间。
服务（Service）：对外暴露能力的命名抽象，路由流量，并使用节点端口暴露服务。
实例（Instance）：由在单个节点上的运行进程和数据库文件组成的单一 PostgreSQL 服务器。
节点（Node）：运行 Linux + Systemd 环境的硬件资源抽象，可以是裸机、VM、容器或 Pod。

辅以“数据库”“角色”两个业务实体，共同组成完整的逻辑视图。如下图所示：

具体样例

让我们来看两个具体的例子，以四节点的 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 }

上面的配置片段定义了一个如下所示的 高可用 PostgreSQL 集群，该集群中的相关实体包括：

集群	Cluster
`pg-test`	PostgreSQL 3 节点高可用集群
实例	Instance
`pg-test-1`	1 号 PostgreSQL 实例，默认为主库
`pg-test-2`	2 号 PostgreSQL 实例，初始为从库
`pg-test-3`	3 号 PostgreSQL 实例，初始为从库
服务	Service
`pg-test-primary`	读写服务（路由到主库 pgbouncer）
`pg-test-replica`	只读服务（路由到从库 pgbouncer）
`pg-test-default`	直连读写服务（路由到主库 postgres）
`pg-test-offline`	离线读取服务（路由到专用 postgres）
节点	Nodes
`node-1`	`10.10.10.11` 1 号节点，对应 `pg-test-1` PG 实例
`node-2`	`10.10.10.12` 2 号节点，对应 `pg-test-2` PG 实例
`node-3`	`10.10.10.13` 3 号节点，对应 `pg-test-3` PG 实例

集群配置

Mon, 01 Jan 0001 00:00:00 +0000

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

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

配置入口

准备清单：复制 pigsty/conf/*.yml 模板或从零开始编写 Ansible Inventory，将集群分组（all.children.<cls>.hosts）与全局变量（all.vars）写入同一个文件。
定义参数：在 vars 区块中覆盖需要的 PGSQL 参数。全局 → 集群 → 主机的覆盖顺序决定了最终值。
应用配置：运行 ./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 会负责执行并确保幂等。

服务/接入

Mon, 01 Jan 0001 00:00:00 +0000

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

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

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

单机用户

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

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

psql postgres://dbuser_dba:DBUser.DBA@10.10.10.10/meta # 直接用 DBA 超级用户连上去
psql postgres://dbuser_meta:DBUser.Meta@10.10.10.10/meta # 用默认的业务管理员用户连上去
psql postgres://dbuser_view:DBUser.View@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 集群为例，它提供四种默认服务：

访问控制

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 提供了一套开箱即用的，基于角色系统和权限系统的访问控制模型。

权限控制很重要，但很多用户做不好。因此 Pigsty 提供了一套开箱即用的精简访问控制模型，为您的集群安全性提供一个兜底。

角色系统

Pigsty 默认的角色系统包含四个默认角色和四个默认用户：

角色名称	属性	所属	描述
`dbrole_readonly`	`NOLOGIN`		角色：全局只读访问
`dbrole_readwrite`	`NOLOGIN`	dbrole_readonly	角色：全局读写访问
`dbrole_admin`	`NOLOGIN`	pg_monitor,dbrole_readwrite	角色：管理员/对象创建
`dbrole_offline`	`NOLOGIN`		角色：受限的只读访问
`postgres`	`SUPERUSER`		系统超级用户
`replicator`	`REPLICATION`	pg_monitor,dbrole_readonly	系统复制用户
`dbuser_dba`	`SUPERUSER`	dbrole_admin	pgsql 管理用户
`dbuser_monitor`		pg_monitor	pgsql 监控用户

这些角色与用户的详细定义如下所示：

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 ,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] ,pgbouncer: true ,parameters: {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment: pgsql monitor user }

默认角色

Pigsty 中有四个默认角色：

用户/角色

Mon, 01 Jan 0001 00:00:00 +0000

在这里的上下文中，用户指的是使用 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 用户为例：

数据库

Mon, 01 Jan 0001 00:00:00 +0000

在这里的上下文中，数据库指的是使用 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 数据库为例：

服务/接入

Mon, 01 Jan 0001 00:00:00 +0000

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

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

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

单机用户

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

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

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

服务概述

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

读写服务（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 集群为例，它提供四种默认服务：

认证 / HBA

Mon, 01 Jan 0001 00:00:00 +0000

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:DBUser.DBA@10.10.10.10: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:DBUser.DBA@10.10.10.10:5432/meta?sslkey=/path/to/dbuser_dba.key&sslcert=/path/to/dbuser_dba.crt'

客户端证书（CN = 用户名）可以使用本地 CA 与 cert.yml 剧本签发。

访问控制

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 提供了一套开箱即用的，基于角色系统和权限系统的访问控制模型。

权限控制很重要，但很多用户做不好。因此 Pigsty 提供了一套开箱即用的精简访问控制模型，为您的集群安全性提供一个兜底。

角色系统

Pigsty 默认的角色系统包含四个默认角色和四个默认用户：

角色名称	属性	所属	描述
`dbrole_readonly`	`NOLOGIN`		角色：全局只读访问
`dbrole_readwrite`	`NOLOGIN`	dbrole_readonly	角色：全局读写访问
`dbrole_admin`	`NOLOGIN`	pg_monitor,dbrole_readwrite	角色：管理员/对象创建
`dbrole_offline`	`NOLOGIN`		角色：受限的只读访问
`postgres`	`SUPERUSER`		系统超级用户
`replicator`	`REPLICATION`	pg_monitor,dbrole_readonly	系统复制用户
`dbuser_dba`	`SUPERUSER`	dbrole_admin	pgsql 管理用户
`dbuser_monitor`		pg_monitor	pgsql 监控用户

这些角色与用户的详细定义如下所示：

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 ,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] ,pgbouncer: true ,parameters: {log_min_duration_statement: 1000 } ,pool_mode: session ,pool_connlimit: 8 ,comment: pgsql monitor user }

默认角色

Pigsty 中有四个默认角色：

管理任务

Mon, 01 Jan 0001 00:00:00 +0000

数据库管理与运维任务

日常管理

Mon, 01 Jan 0001 00:00:00 +0000

故障排查

Mon, 01 Jan 0001 00:00:00 +0000

本文档列举了 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 集成的 MinIO 对象存储可能会被用于 PG 备份保存。

明确占用空间最大的目录后，可进一步使用 du -sh <目录> 深入查找特定大型文件或子目录。

误删处理

Mon, 01 Jan 0001 00:00:00 +0000

误删数据

如果是小批量 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 类误操作，通常按照以下流程决定恢复方案。

确认此数据是否可以通过业务系统或其他数据系统找回，如果可以，直接从业务侧修复。
确认是否有延迟从库，如果有，推进延迟从库至误删时间点，查询出来恢复。
如果数据已经确认删除，确认备份信息，恢复范围是否覆盖误删时间点，如果覆盖，开始 PITR
确认是整集群原地 PITR 回滚，还是新开服务器重放，还是用从库来重放，并执行恢复策略

误删集群

如果出现整个数据库集群通过 Pigsty 管理命令被误删的情况，例如错误的执行 pgsql-rm.yml 剧本或 bin/pgsql-rm 命令。除非您指定了 pg_rm_backup 参数为 false，否则备份会与数据库集群一起被删除。

警告：在这种情况，您的数据将无法找回！请务必三思而后行！

建议：对于生产环境，您可以在配置清单中全局配置此参数为 false，在移除集群时保留备份。

数据迁移

Mon, 01 Jan 0001 00:00:00 +0000

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:DBUser.DBA@10.10.10.10: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:DBUser.DBA@10.10.10.11: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 参数来覆盖订阅连接串的默认值。

参考资料

Mon, 01 Jan 0001 00:00:00 +0000

参数配置与参考文档

监控系统

Mon, 01 Jan 0001 00:00:00 +0000

本文介绍了 Pigsty 的监控系统架构，包括监控指标，日志，与目标管理的方式。以及如何监控现有PG集群与远程 RDS服务。

监控概览

Pigsty 使用现代的可观测技术栈对 PostgreSQL 进行监控：

使用 Grafana 进行指标可视化和 PostgreSQL 数据源。
使用 VictoriaMetrics 来采集 PostgreSQL / Pgbouncer / Patroni / HAProxy / Node 的指标
使用 VictoriaLogs 来记录 PostgreSQL / Pgbouncer / Patroni / pgBackRest 以及主机组件的日志
Pigsty 提供了开箱即用的 Grafana 仪表盘，展示与 PostgreSQL 有关的方方面面。

监控指标

PostgreSQL 本身的监控指标完全由 pg_exporter 配置文件所定义：pg_exporter.yml 它将进一步被 Prometheus 记录规则和告警规则进行加工处理：files/prometheus/rules/pgsql.yml。

Pigsty 使用三个身份标签：cls、ins、ip，它们将附加到所有指标和日志上。此外，Pgbouncer 的监控指标，主机节点 NODE，与负载均衡器的监控指标也会被 Pigsty 所使用，并尽可能地使用相同的标签以便于关联分析。

{ cls: pg-meta, ins: pg-meta-1, ip: 10.10.10.10 }
{ cls: pg-meta, ins: pg-test-1, ip: 10.10.10.11 }
{ cls: pg-meta, ins: pg-test-2, ip: 10.10.10.12 }
{ cls: pg-meta, ins: pg-test-3, ip: 10.10.10.13 }

日志

监控面板

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 为 PostgreSQL 提供了诸多开箱即用的 Grafana 监控仪表盘： Demo & Gallery。

在 Pigsty 中共有 26 个与 PostgreSQL 相关的监控面板，按照层次分为总览，集群，实例，数据库四大类，按照数据来源又分为 PGSQL，PGCAT，PGLOG 三大类。

总览

总览	集群	实例	数据库
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

概览

指标列表

Mon, 01 Jan 0001 00:00:00 +0000

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

3坏2应急处理

Sat, 11 Jan 2025 00:00:00 +0000

如果经典3节点高可用部署同时出现两台（多数主体）故障，系统通常无法自动完成故障切换，需要人工介入：

首先判断另外两台服务器的情况，如果短时间内可以拉起，优先选择拉起另外两台服务。否则进入 紧急止血流程

紧急止血流程假设您的管理节点故障，只有单台普通数据库节点存活，在这种情况下，最快的恢复操作流程为：

调整 HAProxy 配置，将流量指向主库。
关闭 Patroni，手动提升 PostgreSQL 从库为主库。

调整HAProxy配置

如果你通过其他方式绕开 HAProxy 访问集群，那么可以跳过这一步。如果你通过 HAProxy 方式访问数据库集群，那么你需要调整负载均衡配置，将读写流量手工指向主库。

编辑 /etc/haproxy/<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），而是直接将写入流量指向当前主库

使用 VIP-Manager 为 PostgreSQL 集群配置二层 VIP

Mon, 01 Jan 0001 00:00:00 +0000

您可以在 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: eth1

请注意，pg_vip_address 必须是一个合法的 IP 地址，带有网段，且在当前二层网络中可用。

Citus 集群部署

Sat, 11 Jan 2025 00:00:00 +0000

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/citus.yml

这里使用 Pigsty 四节点沙箱，定义了一个 Citus 集群 pg-citus，其中包括一个两节点的协调者集群 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: eth1  # vip interface for all members
 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 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: 'sslmode=require 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 扩展被下载，安装，加载并启用，这涉及到以下四个参数

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

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 在生产环境中是一个高危操作，务必三思而后行。

出于防止误删的目的，Pigsty 的 PGSQL 模块提供了防误删保险，由 pg_safeguard 参数控制。当 pg_safeguard 设置为 true 时，pgsql-rm.yml 剧本会立即中止执行，防止误删数据库集群。

# 将会中止执行，保护数据安全
./pgsql-rm.yml -l pg-test

# 通过命令行参数强制覆盖保护开关
./pgsql-rm.yml -l pg-test -e pg_safeguard=false

除了 pg_safeguard 外，pgsql-rm.yml 还提供了更细粒度的控制参数：

扩展插件

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 提供 510 扩展，覆盖时序、地理、向量、全文检索、分析、特性增强等 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 ]  # 安装：安装扩展软件包

PostgreSQL

Mon, 01 Jan 0001 00:00:00 +0000

PostgreSQL 是世界上最先进和最受欢迎的开源数据库。

默认安装 PostgreSQL 18，支持 PostgreSQL 14 ~ 18，并提供 510 个 PG 扩展。

快速开始

使用 pgsql 配置模板安装 Pigsty。

./configure -c pgsql # 使用 postgres 内核
./deploy.yml # 使用 pigsty 设置一切

大多数配置模板默认使用 PostgreSQL 内核，例如：

meta : 默认，带有核心扩展（vector、postgis、timescale）的 postgres
rich：安装了所有扩展的 postgres
slim：仅 postgres，无监控基础设施
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' }
 node_crontab: [ '00 01 * * * postgres /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 参数进行配置：

Citus

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 原生支持 Citus。这是一个基于原生 PostgreSQL 内核的分布式水平扩展插件。

安装

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 所示：

Babelfish

Mon, 01 Jan 0001 00:00:00 +0000

Babelfish 是一个提供 MS SQL Server 线缆协议兼容性的内核分支 + 扩展，由 AWS 开源。

概览

Pigsty 允许您使用 mssql 模式部署 Babelfish 内核，在 PostgreSQL 上提供：

SQL Server 线缆协议兼容（TDS 协议，1433 端口）
T-SQL 语法兼容
与 Pigsty 现有能力（高可用、备份、监控、IaC）统一集成

在 Pigsty v4.x 中，Babelfish 默认基于 PostgreSQL 17，并已经纳入 Pigsty 标准交付链路。支持所有 Linux 平台

快速开始

使用 Pigsty 内置模板：

./configure -c mssql
./deploy.yml

部署完成后可直接使用 SQL Server 客户端连接：

sqlcmd -S <ip>,1433 -U dbuser_mssql -P DBUser.MSSQL -d mssql

关键配置

mssql 模板中的核心参数如下：

pg_mode: mssql
pg_version: 17
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 集群会同时提供两类访问：

IvorySQL

Mon, 01 Jan 0001 00:00:00 +0000

IvorySQL 是一个开源的，旨在基于 PG 提供 “Oracle 兼容性” 的 PostgreSQL 内核分支。

概览

IvorySQL 内核支持在 Pigsty 开源版本中提供，您的服务器需要互联网访问，直接从 IvorySQL 的官方仓库下载相关软件包。

请注意，直接将 IvorySQL 加入 Pigsty 默认软件仓库中会影响原生 PostgreSQL 内核的安装。Pigsty 专业版提供包括 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

安装

如果您的环境有互联网访问，您可以使用以下方式，直接将 IvorySQL 仓库加入到节点上，然后执行 PGSQL 剧本进行安装

./node.yml -t node_repo -e '{"node_repo_modules":"local,node,pgsql,ivory"}'

配置

以下参数需要针对 IvorySQL 数据库集群进行配置：

PolarDB PG

Mon, 01 Jan 0001 00:00:00 +0000

概览

Pigsty 允许使用 PolarDB 创建带有 “国产化信创资质” 的 PostgreSQL 集群！

PolarDB for PostgreSQL 当前以 PostgreSQL 17 为基线，Pigsty 中的 polar 模板、默认路径与扩展说明也已经同步到 PG17。任何兼容 PostgreSQL 线缆协议的客户端工具都可以访问 PolarDB 集群。

Pigsty 的 PGSQL 仓库中提供了 PolarDB PG 开源版安装包，但不会在 Pigsty 安装时下载到本地软件仓库。

安装

使用 Pigsty 内置模板：

./configure -c polar
./deploy.yml

变更摘要

项目	旧文档 / 旧默认值	当前值
内核基线	PostgreSQL 15	PostgreSQL 17
默认 PolarDB 路径	`/u01/polardb_pg`	`/u01/polardb_pg_17`
支持架构	`x86_64`	`x86_64`, `aarch64`
可用扩展数	旧文档正文写为 61	`pg_available_extensions` 查询结果为 93
复制用户要求	`replicator` 需要 `SUPERUSER`	保持不变

配置

以下参数需要针对 PolarDB 数据库集群进行特殊配置：

PolarDB Oracle

Mon, 01 Jan 0001 00:00:00 +0000

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 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

Percona

Mon, 01 Jan 0001 00:00:00 +0000

Percona Postgres 是一个带有 pg_tde（透明数据加密）扩展的补丁 Postgres 内核。

Pigsty v4.3.0 的 percona-main 包集使用 Percona PostgreSQL 18，并额外安装 pg_tde、PostGIS、pgvector、wal2json、pg_repack、pgaudit、pg_stat_monitor 等常用组件。

Percona 透明数据加密（TDE）性能测试

快速开始

使用 Pigsty 标准安装流程，配合 pgtde 配置模板。

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty;
./configure -c pgtde # 使用 percona postgres 内核
./deploy.yml # 使用 pigsty 设置一切

配置

需要调整以下参数来部署 Percona 集群：

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 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' }
 node_crontab: [ '00 01 * * * postgres /pg/bin/pg-backup full' ] # 每天凌晨 1 点进行全量备份

 # Percona PostgreSQL TDE 临时设置
 pg_packages: [ percona-main, pgsql-common ]  # 安装 percona postgres 包
 pg_libs: 'pg_tde, pgaudit, pg_stat_statements, pg_stat_monitor, auto_explain'

扩展

Percona 提供了 80 个可用的扩展，包括 pg_tde, pgvector, postgis, pgaudit, set_user, pg_stat_monitor 等实用三方扩展。

openHalo

Mon, 01 Jan 0001 00:00:00 +0000

OpenHalo 是一个开源的 PostgreSQL 内核，提供 MySQL 线协议兼容性。

openHalo 基于 PostgreSQL 14.18 内核版本，提供与 MySQL 5.7.32-log / 8.0 版本的线协议兼容性。Pigsty 通过 pg_mode: mysql 与 openhalo 包别名交付。

Pigsty 在所有支持的 Linux 平台上为 OpenHalo 提供部署支持。

RPM 构建 SPEC: github.com/pgsty/rpm/rpmbuild/specs/openhalodb.spec
DEB 构建 SPEC: github.com/pgsty/deb/debbuild/openhalodb

快速开始

使用 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'}
 node_crontab: [ '00 01 * * * postgres /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 兼容功能。

Greenplum

Mon, 01 Jan 0001 00:00:00 +0000

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 实例上采集监控指标。

OrioleDB

Mon, 01 Jan 0001 00:00:00 +0000

OrioleDB 是一个 PostgreSQL 存储引擎扩展，声称能够提供 4 倍 OLTP 性能，没有 xid 环绕和表膨胀问题，并具有"云原生"（数据存储在 S3）能力。

OrioleDB 的当前 Pigsty 模板固定使用 PostgreSQL 17 兼容系，安装补丁版 PostgreSQL 内核与 orioledb 扩展。

您可以使用 Pigsty 将 OrioleDB 作为 RDS 运行。oriole 包别名在 EL 平台映射到 orioledb_17 oriolepg_17，在 Debian/Ubuntu 平台映射到 oriolepg-17 oriolepg-17-orioledb。

快速开始

按照 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'}
 node_crontab: [ '00 01 * * * postgres /pg/bin/pg-backup full' ] # 每天凌晨 1 点进行全量备份

 # OrioleDB 临时设置
 pg_mode: oriole  # oriole 兼容模式
 pg_packages: [ oriole, pgsql-common ]  # 安装 OrioleDB 内核
 pg_libs: 'orioledb, pg_stat_statements, auto_explain' # 加载 OrioleDB 扩展

使用

要使用 OrioleDB，请安装 oriole 包别名；Pigsty 会按平台解析为对应的 PG17 内核与扩展包。

Cloudberry

Mon, 01 Jan 0001 00:00:00 +0000

Cloudberry 是一个源自 Greenplum 社区的开源 MPP 数据仓库内核，适合大规模并行分析场景。

概览

在 Pigsty 中，Cloudberry 沿用 gpsql 模式接入，与 Greenplum / MatrixDB 共享一套身份模型、监控逻辑与目录约定。

内核包名：cloudberry
模式标识：pg_mode: gpsql
角色标识：gp_role: master | segment
当前仓库版本：Cloudberry 2.0.0
当前版本字符串：PostgreSQL 14.4 (Apache Cloudberry 2.0.0-incubating build 1)
默认二进制目录：/usr/local/cloudberry

需要特别说明的是，Pigsty 当前对 Cloudberry 的支持重点在于：软件包交付、节点管理、监控纳管、访问控制与配置编排。对于 MPP 集群初始化、扩容、重平衡和上游专有运维动作，仍建议使用 Cloudberry 官方工具链完成。

根据当前发布说明，Cloudberry 目前在 Pigsty 仓库中为 仅 RPM 构建 的内核。

安装

当前版本暂未提供独立的 cloudberry 一键模板。更常见的使用方式是：

将目标节点纳入 Pigsty 管理。
安装 cloudberry 内核包。
通过 gpsql 模式描述 coordinator / segment 拓扑。
使用 Pigsty 统一接入监控、账号、访问控制与备份体系。

如果只是为节点安装内核包，可直接执行：

Neon

Mon, 01 Jan 0001 00:00:00 +0000

Neon 采用了存储与计算分离架构，提供了丝滑的自动扩缩容，Scale to Zero，以及数据库版本分叉等独家能力。

Neon 官网：https://neon.tech/

Neon 编译后的二进制产物过于庞大，目前不对开源版用户提供，目前处于试点阶段，有需求请联系 Pigsty 销售。

AgensGraph

Mon, 01 Jan 0001 00:00:00 +0000

AgensGraph 是基于 PostgreSQL 的属性图数据库内核，支持 openCypher 查询，并允许 Cypher 与 SQL 混合使用。

概览

Pigsty 通过 pg_mode: agens 接入 AgensGraph，并保留标准 PostgreSQL 集群的大部分运维体验。

内核包：agensgraph
模式标识：pg_mode: agens
当前模板版本：AgensGraph 2.16
当前版本字符串：PostgreSQL 16.9 (AgensGraph 2.16)
当前内置模板：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: 16

 children:
 pg-meta:
 vars:
 pg_mode: agens
 pg_packages: [ agensgraph, pgsql-common ]

AgensGraph 不需要像 pgEdge / Babelfish 那样额外预加载一组专有库，因此大多数 Pigsty 的标准 HA、备份、监控、访问控制与 IaC 用法都保持不变。如果你的负载以图遍历和复杂路径查询为主，通常应重点关注 work_mem、shared_buffers 与代价参数，而不是简单沿用默认 OLTP 习惯。

pgEdge

Mon, 01 Jan 0001 00:00:00 +0000

pgEdge 是面向边缘场景的分布式 PostgreSQL 发行版，核心能力建立在 Spock 多主逻辑复制之上。

概览

Pigsty 通过 pg_mode: pgedge 接入 pgEdge，并用标准 PG 集群编排流程交付其核心组件：

pgedge：PG18 兼容内核
spock：多主（active-active）逻辑复制
snowflake：分布式唯一序列
lolor：大对象逻辑复制兼容层

当前 Pigsty 仓库中，pgEdge PG18 对应包为 pgedge-18 18.3，并同时提供 spock 5.0.6、snowflake 2.4 与 lolor 1.2.2。PG17 包仍可作为过渡版本保留，但 pgedge 配置模板已经默认使用 pg_version: 18。对客户端来说，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 配置模板。

场景模板

Mon, 01 Jan 0001 00:00:00 +0000

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 配套使用。

使用模板

要使用特定的配置模板，只需在集群定义中设置 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 模板：

内核分支

Mon, 01 Jan 0001 00:00:00 +0000

在 Pigsty 中，您可以使用不同风味的 PostgreSQL 分支或兼容栈替换原生 PG 内核，获得 SQL Server / MySQL / Oracle 兼容、多主复制、图查询、MPP 数仓、透明加密等能力。

当前口径为 Pigsty v4.3.0：默认 PostgreSQL 大版本是 18，原生 PostgreSQL 支持 14-18，扩展目录收录 510 个扩展。原生 PostgreSQL 是基准入口；兼容内核或生态栈按 12 类口径组织。不同内核的交付深度并不相同，生产使用前请按目标版本单独验证。

内核 / 生态栈	关键特性	Pigsty 兼容口径
PostgreSQL	原生内核，扩展齐备	PG14-18，默认 PG18，510 扩展
Supabase	后端即服务	基于 PostgreSQL，当前模板默认 PG18，Supabase 扩展包覆盖 PG15-18
Citus	水平分片，多租户	Citus 扩展随 PG14-18 包别名交付
Babelfish	SQL Server 兼容	`pg_mode: mssql`，PG17
IvorySQL	Oracle 兼容	`pg_mode: ivory`，IvorySQL 5 / PG18
OpenHalo	MySQL 兼容	`pg_mode: mysql`，PG14
Percona	透明数据加密	Percona PostgreSQL 18 / `pg_tde`
FerretDB	MongoDB 兼容	DocumentDB/FerretDB 栈，当前演示模板使用 PG18
OrioleDB	OLTP 存储引擎	`pg_mode: oriole`，PG17
PolarDB	Aurora 风格共享存储	`pg_mode: polar`，PG17
Cloudberry	开源 MPP 数仓	`pg_mode: gpsql`，Cloudberry 2.1 / PG14.4
AgensGraph	属性图 + Cypher	`pg_mode: agens`，PG16
pgEdge	Spock 多主复制	`pg_mode: pgedge`，PG18

快速开始

Mon, 01 Jan 0001 00:00:00 +0000

在 Pigsty 中使用扩展需要四个步骤：下载、安装、配置、启用。

下载：将扩展软件包下载到本地仓库（默认本地仓库只保证基础内核与 pgsql-main 包集）
安装：在集群节点上安装扩展软件包
配置：部分扩展需要预加载或配置参数
启用：在数据库中执行 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 数据库中可用。

扩展简介

Mon, 01 Jan 0001 00:00:00 +0000

扩展是 PostgreSQL 的灵魂所在。Pigsty 收录了 510 个预编译、开箱即用的扩展插件，充分释放 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 ]。

软件包

Mon, 01 Jan 0001 00:00:00 +0000

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 冲突。

下载扩展

Mon, 01 Jan 0001 00:00:00 +0000

在安装扩展前，需要确保扩展软件包已下载到本地仓库或可从上游获取。

默认行为

Pigsty 默认会把基础 PostgreSQL 18 内核包下载到本地软件仓库。默认额外下载集为 repo_extra_packages_default: [ pgsql-main ]，包含 PostgreSQL 内核、客户端、过程语言，以及 pg_repack、wal2json、pgvector 等基础扩展包。

如果需要 510 个扩展目录中的其他扩展，请显式加入 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 仓库会移除或与其保持一致。

安装扩展

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 使用操作系统的包管理器（yum/apt）安装扩展软件包。

参数	用途	默认行为
`pg_packages`	全局通用软件包	确保存在（不升级）
`pg_extensions`	集群特定扩展	安装最新版本

集群初始化时安装

在集群配置中声明扩展，初始化时自动安装：

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 版本的包名：

配置扩展

Mon, 01 Jan 0001 00:00:00 +0000

部分扩展需要预加载动态库或配置参数后才能使用，本节介绍如何配置扩展。

预加载扩展

大多数扩展安装后可直接使用 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 参数指定预加载的扩展：

启用扩展

Mon, 01 Jan 0001 00:00:00 +0000

安装扩展软件包后，需要在数据库中执行 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）。

更新扩展

Mon, 01 Jan 0001 00:00:00 +0000

扩展更新涉及两个层面：软件包更新（操作系统层面）和扩展对象更新（数据库层面）。

更新软件包

使用包管理器更新扩展的软件包：

# 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');

注意事项

备份优先：更新扩展前建议先备份数据库，特别是涉及数据类型变更的扩展。

移除扩展

Mon, 01 Jan 0001 00:00:00 +0000

移除扩展涉及两个层面：删除扩展对象（数据库层面）和卸载软件包（操作系统层面）。

删除扩展对象

使用 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 中，删除后需要从预加载列表移除：

常见问题

Mon, 01 Jan 0001 00:00:00 +0000

我当前执行安装的用户为何不能使用 `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 del --prefix /pg/<cls> 来手工删除残留数据（请小心）
可能性4：你的 PostgreSQL 或节点相关 RPM 包没有被成功安装
可能性5：你的 Watchdog 内核模块没有正确启用加载
可能性6：你在初始化数据库时指定的语言 Locale 不存在（例如，使用了 en_US.UTF8，但没有安装英文语言包或 Locale 支持）
如果你遇到了其他的原因，欢迎提交 Issue 或向社区求助。

PGSQL初始化失败：Fail to wait for postgres/patroni replica

存在几种可能的原因：

默认扩展

Mon, 01 Jan 0001 00:00:00 +0000

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`	-	在线重组表

这些扩展提供基础的监控、运维和功能增强能力。

扩展仓库

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 提供补充扩展仓库，在 PGDG 官方仓库基础上提供额外的扩展包。

YUM 仓库

适用于 EL 7/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

仓库地址

国际: https://repo.pigsty.io/yum/
中国: https://repo.pigsty.cc/yum/

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

仓库地址

国际: https://repo.pigsty.io/apt/
中国: https://repo.pigsty.cc/apt/

GPG 签名

所有软件包均使用 GPG 签名：

其他说明

Mon, 01 Jan 0001 00:00:00 +0000

服务接入

Mon, 01 Jan 0001 00:00:00 +0000

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

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

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

单机用户

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

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

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

服务概述

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

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

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

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

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

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

接入服务

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

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

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