文档

• 1: 平台支持
• 2: 快速开始
• 3: 命名空间隔离
• 4: SQL 命令
• 5: 备份
• 6: 副本（只读备用）
• 7: 故障转移：副本提升
• 8: 管理
• 9: 克隆
• 10: 扩展
  • 10.1: 扩展目录
  • 10.2: 常用扩展
• 11: 数据导入/导出
• 12: 恢复
• 13: HA 集群
  • 13.1: Patroni 高可用
  • 13.2: Patroni 动态配置
  • 13.3: Patroni REST API
  • 13.4: HA 集群扩展安装
  • 13.5: Patroni 集群备份
  • 13.6: Patroni 集群恢复
  • 13.7: HA Exec / psql
  • 13.8: 示例：HA 集群 + 自签 CA 的 MinIO
  • 13.9: 生成证书 —— pg cert
  • 13.10: S3 存储高可用方案
• 14: 自签证书
• 15: 开机自启
• 16: 插件 (Addons)
  • 16.1: PgBouncer
  • 16.2: Etcd
  • 16.3: PgDog
  • 16.4: Garage
  • 16.5: PostgREST
  • 16.6: SeaweedFS
  • 16.7: RustFS
  • 16.8: HAProxy
  • 16.9: Silo
  • 16.10: MinIO
  • 16.11: Redis
  • 16.12: Predixy
  • 16.13: pgAdmin 4
  • 16.14: Nginx
  • 16.15: Grafana
  • 16.16: Prometheus
  • 16.17: Alertmanager
  • 16.18: Gitea
  • 16.19: VictoriaMetrics
  • 16.20: BeeGFS
  • 16.21: VMCluster
  • 16.22: JuiceFS
  • 16.23: VictoriaLogs
  • 16.24: vlagent
  • 16.25: VLCluster
  • 16.26: ZeroFS
  • 16.27: DuckDB
  • 16.28: Node_exporter
  • 16.29: InfluxDB
  • 16.30: Pg_exporter
  • 16.31: influx2tsdb
  • 16.32: ClickHouse
  • 16.33: Kafka
  • 16.34: RabbitMQ
  • 16.35: RocketMQ
• 17: 健康巡检
• 18: 配置调优
• 19: KV 缓存
• 20: 工具箱
  • 20.1: ZFS 存储管理
  • 20.2: PGMQ 消息队列
  • 20.3: SQLite + Litestream
  • 20.4: TimescaleDB
• 21: 日志
• 22: 销毁

1 - 平台支持

pgcli 在 Linux 和 macOS 上都是驱动 Podman 容器运行的。 两者的根本区别在于容器如何获得网络：

• Linux 原生运行 Podman，容器共享宿主网络栈（--network host），彼此通过 127.0.0.1 互访。这是零开销路径，也是唯一支持跨主机拓扑的路径。
• macOS 把 Podman 跑在 podman machine 虚拟机里。此处的 host 网络绑定的是 虚拟机的回环，Mac 看不到；于是 pgcli 改为加入共享 bridge 网络 （pgcli-net）并发布各端口 —— Mac 通过 gvproxy 用 127.0.0.1:<port> 访问，容器之间则通过 bridge 上的容器名互访。这适用于单主机 （开发/测试），不是跨主机 HA 路径。

下表是当前支持矩阵。“macOS（单主机）“表示单机完全可用；那些必须向其它机器 广播可路由地址、或依赖 Linux 专属容器内部机制的功能，仍是 仅 Linux。

支持矩阵

图例：✅ 支持 · ✅ 备注 支持但有所述限制 · ⚠️ 该平台上已实现但未实测 · ❌ 不支持。

实例类功能

所有构建在受管 PostgreSQL 实例之上的功能在两个平台都可用 —— 生命周期命令、 pg psql / pg exec、日志、命名空间、导入/导出、克隆、扩展、备份/恢复 （pgBackRest）、物理副本、故障切换。macOS 的 bridge 路径（发布端口 + 容器名 DNS）最早由实例、副本/备份路径验证；代理插件复用的正是这一套。

macOS 上这些都是单主机：跨主机副本、跨多机的连接池属于 Linux 的 --network host + LAN 地址能力。

开机自启

两个平台都支持，但机制不同：

• Linux —— systemd 的 user unit。
• macOS —— launchd 的 LaunchAgent。LaunchAgent 在用户登录时运行，而 非系统启动时 —— 因为 rootless podman 无法在有人登录前启动。请预期容器在你 登录后才拉起。见开机自启。

插件

各组件的网络模型不同：

• PgBouncer 与 PgDog —— 纯代理，macOS 上支持单主机 dev/test。macOS 下它们加入 pgcli-net 并发布端 口；客户端连接仍是 127.0.0.1:<port>。后端地址的注意事项（remote/后端主机 必须是从 Mac 可达的地址，而不是 127.0.0.1）见各自页面的"平台支持"一 节。
• etcd —— 仅 Linux。成员以 host 网络运行，并把 client/peer URL 作为永久的集群状态写进 raft 成员列表；要移植 macOS 的 bridge + 容器名模型就得重写这份状态，在完成该设计之前保持仅 Linux。
• Patroni（pg ha）—— 仅 Linux。成员依赖 podman 的 host 网络；root 和 rootless podman 均可使用。podman machine 虚拟机的 uid 映射与 host 网络模型不吻合。这些命令在 macOS 上会快速失 败并给出清晰提示。见 Patroni 高可用。
• HAProxy —— 仅 Linux。它通过主机网络代理 Patroni 成员，而 podman machine 虚拟机不提供该能力；manager 在 macOS 上快速 失败。
• MinIO —— 两个平台都支持。对象存储，单机或跨 主机分布式纠删码集群皆可。Linux 上经主机网络提供服务；macOS 上加入 pgcli-net 并发布 API 与控制台端 口，Mac 通过 127.0.0.1:<port> 即可访问（与代理插件同一条路径）。公开镜像 为双架构（amd64 + arm64）。
• silo —— 两个平台都支持。Pigsty 的 MinIO 分支， 网络模型与 MinIO 完全一致：Linux 走 host 网络，macOS 加入 pgcli-net 并发布 端口。公开镜像为双架构（amd64 + arm64）。
• rustfs —— 实际上仅 Linux。pgcli 运行一个定制 wrapper 镜像（ghcr.io/mars-base/pgcli/pgcli-rustfs），其 entrypoint 在容器 内部先把 bind 挂载的数据/证书目录 chown 成 rustfs 固定的 uid 10001，再降权到 非特权用户。wrapper 镜像为双架构构建，Go manager 也有与 MinIO/silo 相同的 macOS bridge 路径（发布端口），故 macOS 预期可用 —— 但本插件的 e2e 覆盖只在 Linux 上跑过，在 Mac 上实测之前请按仅 Linux 对待。
• Redis —— Linux 已实测；macOS 预期可用。纯上游 docker.io/library/redis 镜像，没有 wrapper、也没有固定容器 uid，因此不需要 rustfs 那套属主机制。Linux 上走 host 网络（端口按 listen 落在全部网卡或仅 回环）；macOS 上加入 pgcli-net 并发布端口，pg redis-cli 拨 host.containers.internal —— 与对象存储相同的 bridge 路径，代码完备但尚未在 Mac 上跑过，e2e 覆盖目前仅限 Linux。
• Predixy —— 仅 Linux。 与 HAProxy 一样，它需要 host 网络才能拨通后端的集群节点（单机与跨机集群都已验证）。wrapper 镜像只有 amd64 —— 上游只发 amd64 二进制 —— 因此 arm64 主机需要 --platform linux/amd64 模拟运行，而 macOS 的 podman machine 路径根本不存在。
• pgAdmin 4 —— Linux 已实测；macOS 预期可用。纯 上游 docker.io/dpage/pgadmin4 镜像，没有 wrapper —— 镜像自己的 entrypoint 把 /var/lib/pgadmin chown 给 uid 5050 并降权，所以 pgcli 传 --user 0、从不在 宿主上 chown（与 rustfs 不同）。Linux 上走 host 网络，端口取自 pgadmin_start_port（默认仅回环）；macOS 上加入 pgcli-net 并发布端口、 listen 放宽到 0.0.0.0 —— 与 redis/对象存储相同的 bridge 路径，代码完备但 尚未在 Mac 上跑过，e2e 覆盖目前仅限 Linux。
• Grafana —— Linux 已实测；macOS 预期可用。纯上 游 docker.io/grafana/grafana 镜像，没有 wrapper。镜像固化 USER 472，且 entrypoint 完全不做任何属主管理，所以 pgcli 在创建容器前自己把宿主数据目录 chown 成 472:0 —— rootless podman 下经 podman unshare chown，pgcli 以 root 跑在 rootful 宿主上则直接递归 chown。Linux 上走 host 网络，端口取自 grafana_start_port（默认开放全部网 卡）；macOS 上加入 pgcli-net 并发布端口、listen 放宽到 0.0.0.0 —— 与 pgAdmin/redis 相同的 bridge 路径，代码完备但尚未在 Mac 上跑过，e2e 覆盖目前 仅限 Linux。
• Prometheus —— Linux 已实测；macOS 预期可用。 纯上游 docker.io/prom/prometheus 镜像，没有 wrapper，属主形态与 Grafana 一致（固化 USER nobody，uid/gid 65534，entrypoint 不做任何属主管理）—— pgcli 在创建容器前先把宿主 TSDB 目录 chown 过去：rootless podman 下经 podman unshare chown 65534:65534，pgcli 以 root 跑在 rootful 宿主上则直接 递归 chown。与 Grafana 不同，它靠一份 bind mount 的 prometheus.yml（渲染 而来，或从 --conf-file 拷贝）加镜像名之后的 CLI flag 配置，而非环境变量。 Linux 上走 host 网络，端口取自 prometheus_start_port（默认开放全部网卡）—— 且该默认背后没有任何鉴权：不像 Grafana 的 0.0.0.0 有密码兜底，这里的 暴露面只靠网络边界。macOS 上加入 pgcli-net 并发布端口 —— 与 Grafana 相同的 bridge 路径，代码完备但尚未在 Mac 上跑过，e2e 覆盖目前仅限 Linux。
• Alertmanager —— Linux；macOS 代码完备、未 实测。Prometheus 的下游告警路由端，也是它的近乎完全同构体：纯上游 docker.io/prom/alertmanager 镜像，属主形态一致（固化 USER nobody，uid/gid 65534，entrypoint 不做属主管理——pgcli 预 chown 宿主状态目录），靠一份 bind mount 的 alertmanager.yml（渲染而来，或从 --conf-file 拷贝）加镜像名之后的 CLI flag 配置。两个 Alertmanager 特有的事实：--cluster.listen-address= 始终以 空串传入，所以单实例永不开启 HA gossip 端口（TCP+UDP 9094）；而与 Prometheus 不同，镜像里那条无鉴权的 POST /-/reload 路由无法关闭——pgcli 用 SIGHUP 重载、从而永远不依赖那条路由，但路由本身照样敞开。这叠在一个比 Prometheus 更 尖锐的暴露面上：Listen 默认 0.0.0.0 且完全无鉴权，能连到端口即可创建 silence——悄悄压掉 oncall 期待的每一条通知。macOS 上加入 pgcli-net 并发布 端口 —— 同一条 bridge 路径，代码完备但尚未在 Mac 上跑过。
• Gitea —— Linux；macOS 代码完备、未实测。自托管 Git 服务，跑纯上游 docker.io/gitea/gitea 镜像（rootful 构建——rootless 变体的 数据布局互不兼容，pgcli 永不选它）。属主形态与 Grafana 同构只是数字不同：守护 进程 su-exec 降到固化的 git 用户，uid/gid 1000（经 USER_UID/USER_GID 钉死，宿主预 chown 无从漂移），不带 --user flag；pgcli 同样预 chown 宿主 /data 目录。配置只经环境变量（GITEA__* 每次启动折叠进持久化的 app.ini）——这也正是 SECRET_KEY/INTERNAL_TOKEN 绝不注入的原因：重新生成的 secret 会在重装时静默重设幸存数据库的密钥。安装免向导（INSTALL_LOCK），admin 随后经容器内 CLI 创建。单端口惯例之外有两张可选面孔：--dsn 把元数据搬到外置 PostgreSQL（pgcli 从不建库也从不删库）；git-over-ssh 跑在镜像自带的 OpenSSH sshd 上，而这个 sshd 在每个实例上都无条件在跑（s6 服务关不掉）。 --ssh-port N 让它变成 N 端口上的活克隆端点；默认关时它只是 parked 在池端口上 ——但无论如何都得给它 park 个地方：宿主网络下若留在 22 就会永远跟宿主 sshd 死磕。Listen 默认 0.0.0.0（Git 服务天然要给别的机器克隆），由自动生成的 admin 密码与关闭自助 注册兜底。macOS 上加入 pgcli-net 并发布 Web 端口、以及启用 SSH 时的 SSH 端口；代码完备但尚未在 Mac 上跑过。
• BeeGFS —— 仅 Linux；macOS 上直接拒绝安装。 首个多容器插件：一条配置 = 一个单机收敛文件系统——三个容器（mgmtd + meta + storage）按依赖顺序启动、以集群为单位管理。它是唯一没有 bridge 路径、也没有 bridge 兜底的插件：BeeGFS 说的是自家 TCP/UDP 协议（不是 HTTP），守护进程跑 --network host、直接绑协议原生端口——而 8.4 的 meta（8005）与 storage（8003）根本没有监听口覆盖手段，所以每台宿主只容得下 一个文件系统（守卫拦截，而非端口池）。macOS 没有可 bridge 过去的等价形态： 没有 host 网络就没有正确的 BeeGFS 拓扑，所以 Mac 上 pg addon install beegfs 快速失败而不是半可用。属主形态与 Gitea/Grafana 相反：镜像以 root 运行并 自属 bind 挂载目录，pgcli 从不 chown 任何东西。客户端侧是内核模块（DKMS）， 无法容器化——pgcli 刻意从不安装、从不挂载，改用 pg addon beegfs mount-hint 输出逐字的客户端配置。
• nginx —— 两个平台都支持（macOS 轻度实测）。HTTP 反向代理，Linux 上走 host 网络；macOS 上加入 pgcli-net 并发布端口，与对象 存储同一条 bridge 路径 —— 已跑通过但未经负载考验。上游镜像多架构 （amd64 + arm64）。
• pg mc（MinIO 客户端）—— 两个平台都支持。它在一次性容器里运行 mc：宿主的 ~/.mc/config.json 按其原生默认路径挂载，cp/mirror/diff 的本地文件参数也会按真实路径动态 挂载 —— macOS 上要求位于家目录之下（podman machine 只共享家目录）。Linux 上走 host 网络，127.0.0.1 别名可直达本机 addon 实例；macOS 上容器在 bridge 网络里，127.0.0.1 是容器自己的回环 —— 本机 addon 请用 host.containers.internal:<port>，远端存储用可路由地址。

确认当前平台

pg start 会在横幅里打印检测到的平台，便于确认当前走的是哪条路径：

=== pg start ===
Platform: linux        # 或：macOS

2 - 快速开始

几分钟内让 pgcli 运行起来。

安装

使用单条命令安装 pgcli：

curl -fsSL https://raw.githubusercontent.com/mars-base/pgcli/main/scripts/install.sh | bash

此脚本将：

• 为你的平台下载最新的 pgcli 二进制文件
• 安装到 /usr/local/bin（如果没有 sudo 则安装到 ~/.local/bin）
• 将 pgcli 添加到你的 PATH

初始化配置

# 创建基础目录
mkdir -p ~/pg

# 初始化配置并创建默认实例
pg config init --add default --base-dir ~/pg

# 将数据和备份分离到不同磁盘（生产环境推荐）
pg config init --base-dir /data/pg --backup-dir /mnt/backup/pg --add default

这会在 ~/.pgcli/pg.yaml 创建带有合理默认值的配置，包括：

• 名为 default 的默认实例
• 数据目录 ~/pg/default
• 从 35432 开始自动分配的端口

--backup-dir 可选但生产环境推荐：它将备份数据和日志放在与实例数据不同的 路径上，防止数据盘故障连累备份丢失。

启动实例

# 启动默认实例
pg start

# 查看状态和连接信息
pg status

输出会显示连接 URL、管理员密码和备份状态。

连接到数据库

# 使用 pgcli 内置的 psql 封装
pg psql

# 或使用 pg status 中显示的连接字符串直接连接
psql postgres://admin:<password>@localhost:35432/admin_db

# 直接执行 SQL
pg exec "SELECT version()"

基本操作

# 列出所有实例
pg list

# 停止实例
pg stop

# 停止所有实例、备份容器和 PgBouncer
pg stop --all

# 启动实例
pg start

# 查看实例状态
pg status

# 执行 SQL
pg exec "SELECT version();"

多实例管理

# 创建额外实例
pg create -i proj01 --base-dir /data/pg
pg create -i proj02 --base-dir /data/pg

# 列出所有实例
pg list

# 启动所有实例
pg start --all

多配置文件（隔离环境）

为同一主机上的隔离测试环境或每个项目一个配置， 使用不同的 --namespace 和不重叠的端口范围生成独立的配置文件。

# 环境 "t1"：容器前缀 pgcli-pg-t1-*，PG 端口从 38000 开始
pg config init -o ~/.pgcli-t1/pg.yaml --namespace t1 --pg-start-port 38000 --pg-ssh-port 43000 --add proj1

# 环境 "t2"：不同的命名空间、端口，以及独立的备份磁盘
pg config init -o ~/.pgcli-t2/pg.yaml --namespace t2 --base-dir /data/t2 --backup-dir /mnt/backup/t2 --pg-start-port 38100 --pg-ssh-port 43100 --add proj2

# 使用 -c 管理各环境
pg -c ~/.pgcli-t1/pg.yaml start -i proj1
pg -c ~/.pgcli-t2/pg.yaml list

规划建议：

• 始终使用显式的 --namespace 以避免容器名称冲突。
• 同一主机上的端口范围不能重叠。
• 命名空间在创建时固化到容器名称中。 后期更改需要 pg destroy 后重新初始化。

交互式 psql 会话

# 打开交互式 psql（默认实例）
pg psql

# 为指定实例打开 psql
pg psql -i proj01

# 从 stdin 读取 SQL（非交互，用于脚本）
echo "SELECT version();" | pg psql

# 执行单条 SQL 命令
pg psql -- -c "SHOW work_mem"

# 连接到不同数据库
pg psql -- -d postgres

# 使用 psql 元命令
pg psql -- -c "\dt"     # 列出表
pg psql -- -c "\du"     # 列出用户
pg psql -- -c "\l"      # 列出数据库

# 通过连接字符串连接远程数据库
pg psql --dsn postgres://user:pass@host:5432/db

在交互式 psql 中你可以使用：

• 带历史记录和 tab 补全的 SQL 查询
• psql 元命令（\dt、\du、\l 等）
• \q 退出

容器 Shell

# 在容器中打开 bash（默认实例）
pg shell

# 为指定实例打开 shell
pg shell -i proj01

# 直接运行命令
pg shell -- -c "ls -la /var/lib/postgresql/data"

# 查看日志
pg shell -- -c "tail -f /var/log/postgresql/postgresql-*.log"

Shell 以 root 身份在容器内运行，可以完全访问：

• PostgreSQL 数据目录（/var/lib/postgresql/data）
• 配置文件
• 日志文件（/var/log/postgresql/）
• 所有系统工具和实用程序

下一步

• 了解备份与恢复
• 设置复制以实现高可用
• 探索扩展管理
• 配置开机自启用于生产部署
• 了解管理

3 - 命名空间隔离

命名空间允许你在单台主机上创建完全隔离的环境，非常适合将生产、开发和测试环境分开，避免容器名称冲突或端口冲突。

什么是命名空间？

命名空间是应用于配置文件中所有容器名称的前缀。这种隔离机制确保：

• 容器名称不冲突：每个命名空间有自己的容器前缀
• 端口范围分离：每个配置文件从自己的范围分配端口
• 备份容器隔离：每个命名空间有自己的 pgBackRest 容器
• 配置文件独立：每个环境使用单独的配置文件

使用场景：生产和开发环境

一个常见场景是在同一台服务器上运行生产和开发环境：

# 创建生产环境
pg config init \
  --namespace prod \
  --pg-start-port 35432 \
  --pg-ssh-port 42201 \
  --add app-db \
  -o ~/.pgcli-prod/pg.yaml

# 创建开发环境
pg config init \
  --namespace dev \
  --pg-start-port 38000 \
  --pg-ssh-port 43000 \
  --add app-db \
  -o ~/.pgcli-dev/pg.yaml

这会创建两个完全隔离的环境：

管理多个环境

使用 -c 标志指定要使用的配置文件：

# 启动生产数据库
pg -c ~/.pgcli-prod/pg.yaml start -i app-db

# 启动开发数据库
pg -c ~/.pgcli-dev/pg.yaml start -i app-db

# 列出生产环境实例
pg -c ~/.pgcli-prod/pg.yaml list

# 列出开发环境实例
pg -c ~/.pgcli-dev/pg.yaml list

工作原理

容器命名

命名空间为 prod，实例为 app-db：

• 实例容器：pgcli-pg-prod-app-db
• 备份容器：pgcli-backup-prod
• 网络：pgcli-net-prod（如果使用独立网络）

没有命名空间（或 --namespace ""）：

• 实例容器：pgcli-pg-default-app-db
• 备份容器：pgcli-backup-default

端口分配

配置文件中的每个实例获得顺序端口：

• 第一个实例：pg_start_port（例如 35432）
• 第二个实例：pg_start_port + 1（例如 35433）
• 依此类推…

SSH 端口同理。

配置持久化

命名空间和端口范围保存在配置文件中：

namespace: prod
pg_start_port: 35432
pg_ssh_port: 42201

最佳实践

1. 始终使用显式命名空间

在一台主机上运行多个配置时，永远不要依赖默认命名空间：

# 错误：两个配置都会使用 "default" 命名空间并冲突
pg config init --add app -o ~/.pgcli-prod/pg.yaml
pg config init --add app -o ~/.pgcli-dev/pg.yaml  # 冲突！

# 正确：显式命名空间
pg config init --namespace prod --add app -o ~/.pgcli-prod/pg.yaml
pg config init --namespace dev --add app -o ~/.pgcli-dev/pg.yaml

2. 使用不重叠的端口范围

确保配置之间的端口范围不重叠：

# 生产：35432-35999, 42201-42999
pg config init --namespace prod \
  --pg-start-port 35432 \
  --pg-ssh-port 42201 \
  --add app -o ~/.pgcli-prod/pg.yaml

# 开发：38000-38999, 43000-43999
pg config init --namespace dev \
  --pg-start-port 38000 \
  --pg-ssh-port 43000 \
  --add app -o ~/.pgcli-dev/pg.yaml

# 测试：40000-40999, 44000-44999
pg config init --namespace test \
  --pg-start-port 40000 \
  --pg-ssh-port 44000 \
  --add app -o ~/.pgcli-test/pg.yaml

为每个环境中的多个实例预留足够的端口空间。

3. 命名空间在创建时固化

命名空间在创建时嵌入容器名称。之后更改会破坏关联：

# 使用命名空间 "prod" 创建
pg -c ~/.pgcli-prod/pg.yaml start -i app-db
# 容器：pgcli-pg-prod-app-db

# 编辑配置将命名空间改为 "production"
# 这样不行 - 容器名称不匹配！

# 正确做法：销毁并重建
pg -c ~/.pgcli-prod/pg.yaml destroy -i app-db --clean-data
pg -c ~/.pgcli-prod/pg.yaml create -i app-db
pg -c ~/.pgcli-prod/pg.yaml start -i app-db

4. 使用 Shell 别名简化操作

创建别名避免重复输入 -c：

# 添加到 ~/.bashrc 或 ~/.zshrc
alias pg-prod='pg -c ~/.pgcli-prod/pg.yaml'
alias pg-dev='pg -c ~/.pgcli-dev/pg.yaml'
alias pg-test='pg -c ~/.pgcli-test/pg.yaml'

# 然后使用：
pg-prod start -i app-db
pg-dev list
pg-test destroy -i test-db --force

高级用法：带副本的多环境

你甚至可以设置隔离的复制环境：

# 生产：主实例 + 副本
pg -c ~/.pgcli-prod/pg.yaml create -i primary --base-dir /data/prod
pg -c ~/.pgcli-prod/pg.yaml replica create replica -i primary

# 开发：独立的主实例 + 副本
pg -c ~/.pgcli-dev/pg.yaml create -i primary --base-dir /data/dev
pg -c ~/.pgcli-dev/pg.yaml replica create replica -i primary

每个环境维护自己的复制槽、备份 stanza 和数据目录。

故障排除

容器名称冲突

Error: container "pgcli-pg-default-app-db" already exists

原因：两个配置使用了相同的命名空间。

解决：使用不同的命名空间，或先销毁冲突的实例。

端口已被占用

Error: listen tcp 0.0.0.0:35432: bind: address already in use

原因：配置之间的端口范围重叠。

解决：使用不重叠的端口范围，并预留足够间距。

更改命名空间后找不到实例

Error: instance "app-db" exists in config but container not found

原因：创建实例后更改了配置文件中的命名空间。

解决：销毁并重建实例，或恢复命名空间更改。

总结

命名空间为单台主机上的多环境提供完全隔离：

• 独立配置：每个环境有自己的 pg.yaml
• 不同命名空间：防止容器名称冲突
• 不重叠端口：避免端口冲突
• 独立操作：每个环境使用 -c 单独管理

非常适合在同一台服务器上运行生产、开发、测试和预发布环境，互不干扰。

4 - SQL 命令

两种对实例运行 SQL 的方式：pg exec 用于一次性 SQL 或容器命令，pg psql 用于交互式会话，pg shell 用于在容器内打开交互式 bash shell。

pg exec

SQL 模式（默认）

没有 -- 的参数作为 SQL 通过 psql 执行，使用实例配置的用户和数据库。

pg exec "SELECT version()"
pg exec -i proj01 "SELECT count(*) FROM users"
pg exec "CREATE TABLE test (id serial PRIMARY KEY, msg text)"

容器命令模式（– 之后）

-- 之后的参数直接在容器内运行（以 root 身份）。

pg exec -- pg_isready
pg exec -- ls -la /var/lib/postgresql/data
pg exec -- bash -c "cat /var/lib/postgresql/data/postgresql.conf"
pg exec -- tail -f /var/log/postgresql/postgresql-*.log

远程数据库（–dsn）

通过连接字符串对任何可达数据库执行 SQL，使用临时容器。--dsn 仅支持 SQL 模式；容器命令需要本地实例。

pg exec --dsn postgres://user:pass@host:5432/db "SELECT count(*) FROM users"

pg psql

交互式会话

pg psql                          # 默认实例
pg psql -i proj01                # 特定实例

在 shell 内你获得完整的 psql 功能：带历史记录和 tab 补全的 SQL、元命令（\dt、\du、\l），以及 \q 退出。

非交互式（脚本）

echo "SELECT version();" | pg psql        # 来自 stdin 的 SQL
pg psql -- -c "SHOW work_mem"             # 单条命令
pg psql -- -d other_db                    # 连接到不同数据库
pg psql -- -U other_user                  # 以不同用户连接

切换到 postgres 超级用户

某些管理任务（例如创建某些扩展、修改系统级设置）需要 postgres 超级用户权限。使用 -- 传递 psql 参数并切换用户：

pg psql -i pg01 -- -U postgres -d postgres

推荐方法：日常操作使用实例默认用户（admin），仅在需要超级用户权限时切换到 postgres。这比修改配置文件或重启容器更安全更方便。

示例场景：

# 创建需要超级用户权限的扩展
pg psql -i pg01 -- -U postgres -d postgres -c "CREATE EXTENSION pg_cron"

# 配置 cron.database_name（pg_cron 特定参数）
pg psql -i pg01 -- -U postgres -d postgres -c "ALTER SYSTEM SET cron.database_name = 'pg01_db'"

# 查看系统级配置
pg psql -i pg01 -- -U postgres -d postgres -c "SHOW shared_preload_libraries"

远程数据库（–dsn）

pg psql --dsn postgres://user:pass@host:5432/db

pg shell

在 PostgreSQL 容器内打开交互式 bash shell。

pg shell                             # 交互式 bash
pg shell -i proj01                   # 特定实例
pg shell -- -c "ls -la /var/lib/postgresql/data"
pg shell -- -c "cat /etc/postgresql/postgresql.conf"

使用场景：

• 检查 PostgreSQL 数据目录和日志文件
• 运行容器内部命令（如 psql、pg_isready、pg_repack）
• 调试扩展安装和配置文件

规则

• --dsn 和 --instance 互斥：连接字符串确定主机、端口和数据库，因此 -i 被拒绝以避免静默误用。
• 使用 --dsn 时，数据库是 URL 的路径部分：postgres://user:pass@host:5432/mydb 连接到 mydb。要使用另一个数据库，更改路径。
• 使用本地实例时，-- 传递原始 psql 参数（包括 -d/-U），覆盖实例默认值。

5 - 备份

快照

# 创建快照（完整备份）
pg snapshot create -i proj01

# 创建差异备份（推荐）
pg snapshot create --type diff -i proj01

# 快照期间流式输出备份容器日志
pg snapshot create --tail-logs -i proj01

# 列出快照
pg snapshot list -i proj01

# 限制显示的快照数量
pg snapshot list --limit 5 -i proj01

# 删除快照
pg snapshot delete 20260826-073712F -i proj01

快照类型：

• full — 完整备份（默认，自包含）
• diff — 自上次完整备份以来的更改
• incr — 自上次备份以来的更改

共享备份容器

所有实例共享单个 pgbackrest 容器；每个实例在存储库中都有自己的 stanza。

一份配置一个仓库。 这个容器只服务一个仓库——data_dir 下的本地目 录，或配置了 backup.repo.s3 时那唯一的一个 S3 端点——环境里的每个 stanza （普通实例与 Patroni 集群一视同仁）都推给它。不存在按实例或按集群选仓库： 于是一个 pgcli 环境就只备份到一个 store。若想把第二个 store（比如再 pg addon install minio 一个）只喂给部分集群，就跑第二份配置 （pg config init --namespace …）、配上它自己的备份容器——完整走法见 示例：HA 集群 + 自签 CA 的 MinIO。

# 初始化共享 pgbackrest 容器（构建镜像、创建目录、生成配置）
pg backup setup

# 使用自定义基础目录存储备份数据和日志
pg backup setup --base-dir /mnt/backup

# 启动 / 停止备份容器
pg backup start
pg backup stop

# 删除备份容器及其生成的配置（pgbackrest.conf、ssh_config）。备份数据与
# SSH 密钥对会保留，之后 `pg backup setup` 可直接重新接上同一个仓库；
# --clean-data 则连本地仓库、日志与凭据一起删除。
pg backup remove
pg backup remove --clean-data

# 显示备份容器状态
pg backup status

# 列出 backup 容器管理的全部 stanza（每个 PITR 实例一个、每个 Patroni 集群
# 一个）。下面的 stanza-upgrade 用的就是这些名字——它们是仓库里的备份对象
# 标识，不是容器名。
pg backup list-stanza

# 数据目录被重建后（restore、recreate、reinit）刷新 stanza 元数据。此后
# 备份会报 "[051] system-id ... do not match stanza"；stanza-upgrade 重新
# 同步它而不删除已有备份。必须显式给出 stanza 名（有意不提供全量升级）。
pg backup stanza-upgrade pgcli_default
pg backup stanza-upgrade pgcli_default pgcli_app-default

备份基础设施（网络、镜像、目录、配置、容器）在 pg start 时自动准备；手动运行 pg backup setup 重新初始化，例如更改基础目录之后。

S3 对象存储仓库

Patroni 集群的备份与 WAL 归档可以推送到任意 S3 兼容存储（MinIO、silo、rustfs、 garage、AWS S3……）。配置写在 pg.yaml 的 backup.repo.s3 下：

backup:
  repo:
    s3:
      endpoint: 10.0.0.9:9000     # host:port，不带 scheme
      bucket: pgbackrest
      access_key: admin
      secret_key: <密码>           # 与其它 pgcli 密码一样存于 pg.yaml
      ca_file: /home/you/.pgcli/tls/minio/store/ca.crt   # 私有 CA 时必填

然后（重）跑 setup，它会自动完成归档编排：

pg backup setup

• HTTPS 是硬性要求。 pgBackRest 拒绝明文 S3（上游明确不实现），端点必须 提供 TLS。pgcli 自带的 MinIO 用 pg addon install minio --tls 开启原生 HTTPS —— pgcli 会生成自签 CA，并把 ca.crt 路径填进上面的 ca_file。 外部端点（真实 AWS S3 等公签证书）留空 ca_file 即可；实在无法提供 CA 时 可用 verify_tls: false 逃生（不做证书校验）。
• 远端存储主机取 CA——无需 scp。 MinIO 在另一台机器时，用一次 TLS 握手就 能取回信任锚，不必拷贝文件：pg backup fetch-ca <存储主机>:9002 从端点下发 的证书里取出信任锚，存到 <base-dir>/backup/repo-ca/ 下并打印 SHA-256 指纹——这本质是"首次使用即信任"（TOFU），所以信任前先把指纹与存储主机对拍 一次，再把文件交给 pg backup setup --s3-ca-file <路径>。它覆盖 pgcli 会提供 的两种 TLS 形态：开 --tls 的 MinIO（下发的是生成好的"叶+CA"链，取出的是 签名根）；以及喂了 pg cert 自签叶证书的 MinIO（叶本身就是信任锚，原样保存 即可）。公共 CA 签发的端点根本不需要 ca_file，此命令对它们没有意义。
• 跨机 HA 免手工分发。 Patroni 集群分散在多台主机时，ca_file 与备份 SSH 公钥只需在一台主机配好：pg backup setup 把 CA 发布进集群的 etcd 注册表， ca_file 留空的加入者自动拉取；各主机的备份公钥在 pg ha create 时发布， 由 setup 合并进每个成员的 authorized_keys。注册表里只放公开材料（CA 证书、SSH 公钥），绝不含私钥或 S3 secret_key。详见 HA 文档"备份跨机 leader"一节。
• 归档自动化。 setup 检测到 Patroni 成员的归档配置过期时，会 pause 集群、 按"副本先、leader 后"重建成员容器（recreate 即重启，archive_mode 是 postmaster 级参数）、resume。每个成员的 patroni.yml 会注入同一份 archive_command（每个集群一个 stanza，成员互为 pg*-host，pgBackRest 自动定位 primary），WAL 从此持续 push 到 S3。
• 作用范围。 S3 仓库只作用于 Patroni 集群的 stanza；pg 直接管理的普通 实例备份仍走本地仓库，互不影响。

等价的一次性 flag 写法（secret_key 建议手编 pg.yaml，避免落入 shell 历史）：

pg backup setup --s3-endpoint 10.0.0.9:9000 --s3-bucket pgbackrest \
    --s3-access-key admin --s3-ca-file ~/.pgcli/tls/minio/store/ca.crt

6 - 副本（只读备用）

创建现有实例的只读物理副本。副本通过 PostgreSQL 物理复制从其主实例持续流式传输 WAL，并提供只读查询服务——适用于读写分离、报告或作为热备。

# 创建默认实例的副本
pg replica create ro1

# 创建特定实例的副本
pg replica create ro1 -i proj01

# 列出副本和复制延迟
pg replica list

发生了什么

1. 预检 — 主实例必须正在运行（在任何配置写入之前验证；停止的主实例会失败但没有副作用）
2. 注册 — 添加新实例条目，使用主实例的数据库名称和密码（参见注释），禁用 PITR，replica_of 设置为主实例
3. 复制设置 — 在主实例上：
   • pg_hba.conf 为回环地址和 RFC1918 范围添加 host replication 条目（幂等）
   • 创建物理复制槽 pgcli_r_<name>，保留 WAL 以确保副本不会落后于 WAL 回收
4. 基础备份 — pg_basebackup -R 将主实例的数据目录复制到副本的数据目录，写入 primary_conninfo（带密码）和 standby.signal，使副本以备用模式启动
5. 启动 — 副本容器启动并持续流式传输 WAL

验证

# 只读备用？
pg exec -i ro1 "SELECT pg_is_in_recovery()"      # t

# 写入被拒绝
pg exec -i ro1 "INSERT INTO t VALUES (1)"         # 只读事务错误

# 流式传输活跃
pg exec -i ro1 "SELECT pg_is_in_recovery(), now() - pg_last_xact_replay_timestamp()"

# 主实例上的槽是活跃的
pg exec -i primary "SELECT slot_name, active FROM pg_replication_slots"

# 概览
pg list                              # ROLE/PRIMARY 列
pg replica list                      # NAME/PRIMARY/STATUS/LAG
pg status -i ro1                     # Role: standby (replica of ...)

销毁

销毁副本是两步操作：

# 步骤 1：销毁副本实例（移除容器 + 数据 + 配置条目）
pg destroy -i ro1 --clean-data --force

# 步骤 2：在主实例上删除复制槽（如果已不存在则为无操作）
pg replica drop ro1 -i <primary>

步骤 1 必须在步骤 2 之前运行：PostgreSQL 拒绝删除仍在流式传输的槽（replication slot is active），因此必须先销毁副本以关闭其流式连接。

注意： 如果主实例是本地 pgcli 管理的实例（同一主机），可以跳过步骤 2 — destroy 会自动清理槽。当从副本主机无法访问主实例时需要步骤 2。

跨网络副本

上述同主机流程假设主实例和副本共享一个服务器（一个 podman 守护进程，一个网络）。对于在另一台主机上的副本，pgcli 在每一侧运行一个命令——无需 SSH，唯一的跨机器信息就是你作为参数传递的内容：

# ---- 在主实例主机上：准备主实例（首先运行）----
pg replica create ro1 -i pg01 --replica-host 10.0.0.21

# ---- 在副本主机上：复制数据并启动副本（其次运行）----
pg replica create ro1 --primary-dsn "postgres://admin:<password>@10.0.0.20:35432/pg01_db" --primary-name pg01

获取主实例 DSN

如果主实例是 pgcli 管理的实例，使用 pg status 获取其连接信息：

pg status -i pg01
# ...
#   Connection: postgres://admin:<password>@127.0.0.1:35432/pg01_db

然后将 127.0.0.1 替换为从副本主机看到的主实例主机 IP（例如 10.0.0.20）——用户、密码和数据库按原样使用。注意主实例主机必须接受从副本主机到该端口的 TCP 连接（防火墙/安全组）。

每一侧的作用：

• 主实例侧（--replica-host <ip|hostname>）：仅准备主实例——本地不创建任何内容。它将 host replication all <addr> 条目追加到 pg_hba.conf 并创建物理槽 pgcli_r_<name>，然后打印要在副本主机上运行的确切 --primary-dsn 命令。IP 地址获得 /32（IPv6 为 /128）掩码；主机名按原样写入。已在托管 RFC1918 范围（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）内的 IP 会被跳过去重。幂等——重新运行不会添加重复行。
• 副本侧（--primary-dsn）：首先验证主实例上存在槽（验证连接性和顺序——在主实例侧之前运行会失败并带有可操作的错误消息且没有副作用），然后注册实例，通过网络从 DSN 运行 pg_basebackup（主机网络），并启动备用实例。

副本侧仅在副本主机上运行：副本实例的用户、数据库和密码来自 DSN（物理复制复制 pg_authid，因此本地密码必须等于主实例的密码）。主实例名称使用 --primary-name 给出并记录为 replica_of；它不必存在于副本主机的配置中，-i 不用于远程主实例——如果给出，它保持其严格含义并且必须引用真实的本地实例。

销毁是对称的，每个主机一个命令——按此顺序：

# 1. 在副本主机上：移除容器 + 配置，还通过 DSN 删除远程主实例上的槽
#    （如果主实例可达则自动）
pg destroy -i ro1

# 2. 在主实例主机上（仅当步骤 1 的 DSN 连接失败时）：
#    手动删除槽
pg replica drop ro1 -i pg01

步骤 1 必须在步骤 2 之前运行：PostgreSQL 拒绝删除仍在流式传输的槽（replication slot is active），因此必须先销毁副本以关闭其流式连接。

自动槽清理： 当跨主机副本设置了 PrimaryDSN 时，destroy 会自动尝试通过 DSN 删除远程主实例上的复制槽。如果主实例可达，则无需手动步骤 2。replica drop 是幂等的——当槽已不存在时重新运行会作为无操作成功。

非 pgcli 主实例

主实例不必由 pgcli 管理——只要主实例侧已手动准备（槽检查仅验证槽是否存在，不验证谁创建了它），副本侧可以对任何 PostgreSQL 服务器工作：

1. 在 pg_hba.conf 中允许从副本主机复制，然后重新加载（SELECT pg_reload_conf()）：

   host replication <replica user> <replica ip>/32 scram-sha-256

2. 使用确切名称 pgcli_r_<replica-name> 创建物理槽（副本侧检查此名称）：

   SELECT pg_create_physical_replication_slot('pgcli_r_ro1');

   需要 wal_level = replica（或 logical）和具有 REPLICATION 权限的用户——DSN 用户。

然后副本侧命令不变：

pg replica create ro1 --primary-dsn "postgres://<user>:<pass>@<primary ip>:5432/<db>" --primary-name pg01

销毁时，主实例侧没有 pgcli——在 pg destroy -i ro1 之后，手动删除槽：

SELECT pg_drop_replication_slot('pgcli_r_ro1');

如果基础备份失败（例如网络中断），销毁副本并重新运行副本侧命令——主实例侧的槽和 hba 条目保持有效。

注释

• 只读 — 副本拒绝所有写入（cannot execute INSERT in a read-only transaction）。要使其可写你需要提升它（pg_ctl promote），这尚未作为 pgcli 命令暴露
• 相同数据，相同密码 — 物理复制是主实例的逐字节复制，包括 pg_authid。因此副本的管理员密码和数据库名称与主实例相同；只有容器名称、端口和数据目录不同。使用 --dsn 风格的连接时使用副本的端口
• 副本上禁用 PITR — 备用实例不归档任何内容，也不在 pgBackRest 备份容器中注册；备份在主实例上运行
• 主实例必须正在运行 — 初始创建（pg_basebackup）和持续流式传输都需要；如果主实例重启，副本会自动重新连接（槽显示为 active）
• 延迟显示 — replica list 延迟（now() - pg_last_xact_replay_timestamp()）在主实例空闲时会增长；它会在下一个复制的事务时降回零。这是预期的空闲行为，不是漂移
• 幂等启动 — 重复的 pg start -i ro1 在数据目录已初始化时跳过基础备份

7 - 故障转移：副本提升

当当前主实例失败时，将副本提升为新的主实例。pgcli 提供 3 步手动故障转移工作流——每个步骤在其各自的主机上运行，不自动检测同主机与跨主机拓扑。

概述

                    ┌─────────────┐
                    │   primary   │  ← 崩溃 / 变得不可用
                    │  (pg01)     │
                    └──────┬──────┘
                           │ WAL 流式传输
               ┌───────────┼───────────┐
               ▼           ▼           ▼
          ┌─────────┐ ┌─────────┐ ┌─────────┐
          │  ro1    │ │  ro2    │ │  ro3    │
          │ replica │ │ replica │ │ replica │
          └─────────┘ └─────────┘ └─────────┘

故障转移后（提升 ro1 → 新主实例）：

                    ┌─────────────┐
                    │   ro1       │  ← 新主实例（已提升）
                    │  (primary)  │
                    └──────┬──────┘
                           │ WAL 流式传输
               ┌───────────┼───────────┐
               ▼           ▼           ▼
          ┌─────────┐ ┌─────────┐ ┌─────────┐
          │  ro2    │ │  ro3    │ │  pg01   │
          │ replica │ │ replica │ │ replica │  ← 降级的旧主实例
          └─────────┘ └─────────┘ └─────────┘

3 步故障转移

每个步骤都是独立的命令。按顺序在各自的主机上运行它们。

# 步骤 1：在被提升的副本上
pg replica promote ro1

# 步骤 2：在旧主实例主机上（当它恢复时）
pg replica drop ro1 -i pg01

# 步骤 3：在每个剩余副本主机上
pg replica repoint ro2 --primary-dsn "postgres://admin:<pw>@<new-primary-ip>:<port>/<db>" --primary-name ro1
pg replica repoint ro3 --primary-dsn "postgres://admin:<pw>@<new-primary-ip>:<port>/<db>" --primary-name ro1

步骤 1：pg replica promote <name>

在被提升为主实例的副本主机上运行。

pg replica promote ro1

发生了什么：

1. 验证实例是副本（ReplicaOf 已设置）且容器正在运行
2. 调用 pg_promote()（PostgreSQL 12+ 原生提升——无需容器重启）
3. 等待恢复结束（通常亚秒级）
4. 通过 ALTER SYSTEM RESET 从 postgresql.auto.conf 清理 primary_conninfo
5. 更新配置：清除 ReplicaOf 和 PrimaryDSN，启用 PITR
6. 自动初始化 PITR：
   • pgBackRest stanza 创建
   • archive_mode / archive_command 配置
   • PostgreSQL 重启以应用 postmaster 级别参数
7. 打印下一步指令

幂等： 如果副本已被提升（例如通过手动 pg_ctl promote），命令会跳到配置更新。

步骤 2：pg replica drop <name> -i <old-primary>

在旧主实例主机上运行以清理复制槽。此步骤仅在特定场景中需要。

pg replica drop ro1 -i pg01

这会在旧主实例上删除物理复制槽 pgcli_r_ro1。没有清理，槽会无限期保留 WAL，直到主实例磁盘空间耗尽。

何时运行：

保持旧主实例不变？ 如果你想保留旧主实例及其原始数据（例如用于取证分析或作为只读归档），你可以简单地不理会它——不要在其上运行 drop 或 repoint。旧主实例继续作为具有陈旧数据的独立实例运行。只是要注意被提升副本的复制槽仍然存在并会累积 WAL；你可能想要仅删除那个特定的槽（pg replica drop ro1 -i pg01）同时保持其他一切不变。

步骤 3：pg replica repoint <name> --primary-dsn <dsn> --primary-name <name>

在每个剩余副本主机上运行以将其重新指向新主实例。

pg replica repoint ro2 \
  --primary-dsn "postgres://admin:<password>@10.0.0.11:35439/pg01_db" \
  --primary-name ro1

发生了什么：

1. 通过 DSN 查询新主实例的扩展（pg_extension 目录）
2. 如果存在非内置扩展（例如 pg_cron、timescaledb），构建本地 -ext 镜像并匹配包
3. 停止旧副本容器并销毁其数据目录
4. 通过 DSN 在新主实例上创建复制槽
5. 更新配置：ReplicaOf、PrimaryDSN、ImageTag、Extensions，禁用 PITR
6. 通过 pg_basebackup -R 从新主实例重新初始化
7. 以备用模式启动副本容器

为什么销毁 + 重建而不是 ALTER SYSTEM SET？

提升后，新主实例进入新时间线。旧时间线上的其他副本不能简单地更改 primary_conninfo——PostgreSQL 会拒绝连接：

FATAL: requested starting point on timeline 1 is not in this server's history

唯一安全的方法是从新主实例进行完整的 pg_basebackup。

获取主实例 DSN

从被提升副本主机上的 pg status 获取新主实例的连接字符串：

pg status -i ro1
# Connection: postgres://admin:<password>@127.0.0.1:35439/pg01_db

将 127.0.0.1 替换为从副本主机可达的新主实例主机 IP（例如 10.0.0.11）。

降级旧主实例

当旧主实例恢复时，你可以使用相同的 repoint 命令将其作为新主实例的副本重新加入：

# 在旧主实例主机上
pg replica repoint pg01 \
  --primary-dsn "postgres://admin:<password>@10.0.0.11:35439/pg01_db" \
  --primary-name ro1

即使 pg01 曾是主实例（未设置 ReplicaOf）这也有效。该命令：

1. 停止 pg01 并销毁其数据（包括旧的 PITR stanza）
2. 在新主实例上为 pg01 创建复制槽
3. 设置 ReplicaOf = "ro1"，PITR.Enabled = false
4. 通过 pg_basebackup 从新主实例重新初始化

重新指向后，pg01 作为只读副本从新主实例流式传输 WAL——没有 WAL 归档，没有备份。

扩展同步

当副本被重新指向新主实例时，pgcli 会自动同步扩展：

1. 查询 — 通过 DSN 连接到新主实例并查询 pg_extension 获取已安装的扩展
2. 过滤 — 识别非内置扩展（需要外部包的扩展，例如 pg_cron、pgmq、timescaledb）
3. 构建 — 如果存在非内置扩展，构建本地 -ext 镜像：
   • 如果本地 -ext 镜像已存在，在其上安装缺失的包（重用 Pigsty 仓库——快速）
   • 如果没有 -ext 镜像，从基础镜像构建并设置 Pigsty 仓库
   • apt-get install 是幂等的——安装已存在的包是无操作
4. 应用 — 副本启动时，ApplyExtensions 将 shared_preload_libraries 写入 postgresql.conf
5. 跳过 CREATE EXTENSION — 副本是只读的；扩展通过 pg_basebackup + WAL 流式传输从主实例复制

这确保副本容器具有 postgresql.auto.conf 中引用的所需共享库（例如 pg_cron）。

同主机 vs 跨主机

pgcli 不自动检测拓扑。你选择在每个命令运行的位置：

--primary-dsn 必须使用从 repoint 运行所在主机可达的 IP/主机名。

完整示例

# ── 初始设置：pg01（主实例）+ ro1, ro2（副本）在同一主机 ──

$ pg list
NAME    ROLE      PRIMARY   STATUS
pg01    primary   -         Up 2 hours
ro1     replica   pg01      Up 1 hour
ro2     replica   pg01      Up 1 hour

# ── pg01 崩溃 ──

# 步骤 1：提升 ro1
$ pg replica promote ro1
  [OK] pg_promote() signaled
  [OK] recovery ended, instance is now read-write
  [OK] primary_conninfo removed from postgresql.auto.conf
  [OK] config updated (ReplicaOf/PrimaryDSN cleared, PITR re-enabled)
-> Initializing PITR (backup stanza + archive_mode)...
  [OK] pgBackRest stanza created
-> archive_command configured
  [OK] WAL archiver caught up
✓ Replica "ro1" promoted to primary

# 步骤 2：在旧主实例上清理（如果 pg01 永久丢失则跳过）
$ pg replica drop ro1 -i pg01
  [OK] replication slot "pgcli_r_ro1" removed from primary "pg01"

# 步骤 3：将 ro2 重新指向新主实例
$ pg replica repoint ro2 \
    --primary-dsn "postgres://admin:<password>@127.0.0.1:35437/pg01_db" \
    --primary-name ro1
  [OK] extension image built with pg_cron, pgmq, timescaledb
  [OK] replication slot "pgcli_r_ro2" created on new primary
  [OK] config updated (ReplicaOf = "ro1")
✓ Replica "ro2" re-pointed to "ro1"

# ── pg01 恢复，降级为副本 ──
$ pg replica repoint pg01 \
    --primary-dsn "postgres://admin:<password>@127.0.0.1:35437/pg01_db" \
    --primary-name ro1
  [OK] backup stanza removed: pgcli_pg01
  [OK] replication slot "pgcli_r_pg01" created on new primary
  [OK] config updated (ReplicaOf = "ro1", PITR disabled)
✓ Replica "pg01" re-pointed to "ro1"

# ── 最终状态 ──
$ pg list
NAME    ROLE      PRIMARY   STATUS
pg01    replica   ro1       Up 30 seconds    # 已降级
ro1     primary   -         Up 10 minutes    # 新主实例
ro2     replica   ro1       Up 5 minutes

跨主机示例

# ── 设置：ra3（主实例，主机 A）+ ra2（副本，主机 A）+ ro2（副本，主机 B）──

# ra3 崩溃。在主机 A 上，提升 ra2：
$ pg replica promote ra2
  [OK] pg_promote() signaled
  [OK] recovery ended
  [OK] PITR initialized (stanza + archive_mode)
✓ Replica "ra2" promoted to primary

# 在主机 B（10.0.0.12）上，将 ro2 重新指向新主实例 ra2（主机 A = 10.0.0.11）：
$ pg replica repoint ro2 \
    --primary-dsn "postgres://admin:<password>@10.0.0.11:35438/pg01_db" \
    --primary-name ra2
-> New primary has 3 non-builtin extension(s): pg_cron, pgmq, timescaledb
-> Extension image already has all required packages
  [OK] replication slot "pgcli_r_ro2" created on new primary
  [OK] config updated (ReplicaOf = "ra2", image = ...-ext)
✓ Replica "ro2" re-pointed to "ra2"

# 验证跨主机复制：
$ pg exec -i ra2 "INSERT INTO test(msg) VALUES ('after failover')"
$ pg exec -i ro2 "SELECT * FROM test ORDER BY id DESC LIMIT 1"
   msg: after failover

级联复制

副本本身可以作为下游副本的主实例，形成级联链。这减少主实例的负载并启用分层拓扑。

primary (ra3)
  ├─→ replica (ra2) ← ra2_ro1 的上游
  │     └─→ replica (ra2_ro1)
  └─→ replica (pg01)

工作原理

1. 创建副本的副本：使用副本作为 -i 目标

   # ra2 是 ra3 的副本，创建 ra2_ro1 作为 ra2 的副本
   pg replica create ra2_ro1 -i ra2

2. WAL 传播：

   • ra2 从 ra3 流式传输 WAL
   • ra2_ro1 从 ra2 流式传输 WAL
   • 数据流：ra3 → ra2 → ra2_ro1

3. 复制槽：每个链接维护自己的槽

   • ra3 有槽 pgcli_r_ra2
   • ra2 有槽 pgcli_r_ra2_ro1

优势

• 减少主实例负载：只有直接副本连接到主实例
• 地理分布：主实例 → 区域副本 → 本地副本
• 网络效率：本地副本可以共享区域上游

限制

• 增加延迟：每一跳增加复制延迟
• 级联故障：如果 ra2 失败，ra2_ro1 失去其上游
• 提升复杂性：提升 ra2_ro1 需要将其重新指向新主实例

验证级联

# 检查 ra2 的下游副本
pg exec -i ra2 "SELECT client_addr, state FROM pg_stat_replication"

# 检查 ra2_ro1 的上游
pg exec -i ra2_ro1 "SELECT conninfo FROM pg_stat_wal_receiver"

级联故障转移

如果 ra2（中间节点）失败：

# 选项 1：将 ra2_ro1 直接重新指向 ra3
pg replica repoint ra2_ro1 \
  --primary-dsn "postgres://admin:password@ra3-host:5432/pg01_db" \
  --primary-name ra3

# 选项 2：等待 ra2 恢复（一旦 ra2 重新连接到 ra3 自动进行）

如果 ra3（主实例）失败且 ra2 被提升：

# 步骤 1：提升 ra2
pg replica promote ra2

# 步骤 2：ra2_ro1 自动跟随（它已经从 ra2 复制）
# ra2_ro1 无需操作

# 步骤 3：将其他副本重新指向新主实例
pg replica repoint pg01 \
  --primary-dsn "postgres://admin:password@ra2-host:5432/pg01_db" \
  --primary-name ra2

注释

• pg_promote() — PostgreSQL 12+ 原生函数，无需容器重启。实例就地退出恢复并立即变为可读写
• 时间线分歧 — 提升后，新主实例在新时间线上。其他副本不能用 ALTER SYSTEM SET primary_conninfo 重新指向——它们必须通过 pg_basebackup 重建
• 被提升副本上的 PITR — 提升后，pgBackRest stanza 和 WAL 归档自动初始化（无需手动执行 pg start）。被提升的副本没有先前的备份历史
• 复制槽 — 旧主实例为被提升副本的槽在提升后变得陈旧。pg replica drop 清理它。如果旧主实例被降级为副本，repoint 销毁旧数据且陈旧的槽不再被引用
• 扩展 — 副本容器通过 postgresql.auto.conf 从主实例继承 shared_preload_libraries。repoint 命令确保本地镜像在重建副本之前具有所需的扩展包
• 跳过 CREATE EXTENSION — 副本是只读的；pg_basebackup 从主实例复制扩展元数据，因此不需要 CREATE EXTENSION（且会失败 “cannot execute CREATE EXTENSION in a read-only transaction”）

8 - 管理

Shell 补全

为命令、标志和实例名称启用 tab 补全。

Bash

# Linux
pg completion bash > /etc/bash_completion.d/pg

# macOS（使用 Homebrew bash-completion）
pg completion bash > $(brew --prefix)/etc/bash_completion.d/pg

# 或在当前会话中加载
source <(pg completion bash)

Zsh

# 启用补全系统（一次）
echo "autoload -U compinit; compinit" >> ~/.zshrc

# 安装补全
pg completion zsh > "${fpath[1]}/_pg"

Fish

pg completion fish > ~/.config/fish/completions/pg.fish

PowerShell

pg completion powershell > pg.ps1
# 从你的 PowerShell 配置文件加载

PostgreSQL 配置

通过 pg exec 使用 ALTER SYSTEM 修改 PostgreSQL 运行时参数，然后重新加载：

# 更改参数
pg exec "ALTER SYSTEM SET work_mem = '256MB'"
pg exec "SELECT pg_reload_conf()"

# 针对特定实例
pg exec -i proj01 "ALTER SYSTEM SET effective_cache_size = '4GB'"
pg exec -i proj01 "SELECT pg_reload_conf()"

注意： 某些参数（例如 shared_buffers、max_connections）需要重启而不是重新加载。使用 pg stop && pg start 应用这些更改。

配置文件管理

检查或验证配置文件（默认为 ~/.pgcli/pg.yaml，使用 -c 覆盖）。

# 显示当前配置（YAML）
pg config show

# 以 JSON 格式显示配置
pg config show --json

# 验证配置文件结构
pg config validate

Init 生成默认配置；--add 在同一文件中创建命名实例，-o 写入自定义路径：

pg config init --add default --base-dir /data/pg
pg config init --add proj01 --base-dir /data/pg -o ./my-pg.yaml

# 将数据和备份分离到不同磁盘
pg config init --base-dir /data/pg --backup-dir /mnt/backup/pg --add default

--backup-dir 将备份数据和日志放在与实例数据不同的路径上。这是典型的生产环境 配置：PG 数据在一块磁盘，备份在另一块，防止数据盘故障连累备份丢失。

在一个主机上运行多个配置的隔离参数（参见快速开始进行规划）：

pg config init --namespace t1 --pg-start-port 38000 --pg-ssh-port 43000 --add proj01 -o ~/.pgcli-t1/pg.yaml

所有都保存到配置文件中（namespace、pg_start_port、pg_ssh_port）；跨配置使用不重叠的端口范围，这样分配永远不会冲突。

9 - 克隆

创建新实例，其数据从现有实例复制，直接流式传输——磁盘上无临时文件。

# 克隆默认实例
pg clone test02

# 克隆特定实例
pg clone test02 -i proj01

# 通过连接字符串克隆远程数据库
pg clone test02 --dsn postgres://user:pass@host:5432/db

# 新实例的自定义数据目录
pg clone test02 -i proj01 --base-dir /data/pg

发生了什么

1. 预检 — 在创建任何内容之前验证源：
   • 本地实例：容器必须正在运行
   • --dsn：认证的 SELECT 1 必须成功（捕获错误密码、不可达主机）
2. 创建 — 新实例条目添加到配置，带有随机密码、自己的容器名称、数据目录和自动分配的端口
3. 启动 — 新实例启动（与 pg start 相同的工作流）
4. 流式传输 — 源数据管道传输到目标，每秒显示一次实时传输进度

注释

• 源实例必须正在运行（或 --dsn 目标可达）；错误的源会立即失败且无副作用
• 新实例名称在配置中不能已存在
• --dsn 和 --instance 互斥：使用 --dsn 时连接字符串确定主机、端口和数据库
• 新实例获得新的随机密码——在克隆输出或 pg status -i <name> 中查找
• 仅逻辑复制（模式 + 数据）；对于大型数据库，物理方法可能更快

10 - 扩展

pgcli 支持从 Pigsty DEB 仓库安装和管理 PostgreSQL 扩展。

工作原理

扩展被烘焙到派生容器镜像中：

1. pg extension install 构建新镜像（基于当前镜像 + Pigsty 仓库 + 扩展包）
2. 停止并移除旧容器
3. 从新镜像重新创建容器（主机数据卷被保留）
4. 更新配置文件中的 image_tag

这种方法的优势：

• 扩展在容器重建后仍然存在（烘焙到镜像层）
• pg start 不需要在每次启动时运行 apt-get install
• 扩展文件是持久的并与容器生命周期解耦

命令

安装扩展

# 安装单个扩展
pg extension install pg_stat_statements

# 安装多个扩展（单次镜像构建，逗号分隔）
pg extension install pgmq,uuid-ossp,pg_stat_statements

# 针对特定实例
pg extension install pg_stat_statements -i pg01

重启确认： 需要 shared_preload_libraries 的扩展（例如 pg_stat_statements、pg_cron）需要 PostgreSQL 重启。默认情况下，会提示你确认：

# 交互式确认（默认）
pg extension install pg_stat_statements
# 输出：
# Installing extensions that require shared_preload_libraries will cause a PostgreSQL restart.
# Extensions to be installed: [pg_stat_statements]
# This will cause a brief interruption to database connections.
# Restart PostgreSQL now? [y/N]:

# 跳过确认并自动重启
pg extension install pg_stat_statements --auto-restart

如果你拒绝重启，可以稍后应用更改：

pg stop -i pg01
pg start -i pg01

列出已安装扩展

pg extension list -i pg01

示例输出：

Installed extensions in "pg01":
  pg_stat_statements (managed)
  uuid-ossp (managed)
  plpgsql (unmanaged)

• managed：由 pgcli 跟踪（记录在配置中，包含在镜像中）
• unmanaged：手动安装的扩展（不在配置中跟踪）

移除扩展

pg extension remove pgmq -i pg01

工作流：

1. DROP EXTENSION IF EXISTS pgmq
2. 更新配置和 shared_preload_libraries
3. 无镜像重建 — -ext 镜像在实例间共享，包永远不会被卸载

重启确认： 如果移除需要 shared_preload_libraries 的扩展（例如 pg_stat_statements、pg_cron），会在重启前提示你确认：

# 交互式确认（默认）
pg extension remove pg_stat_statements -i pg01
# 输出：
# Removing extensions that require shared_preload_libraries will cause a PostgreSQL restart.
# Extensions to be removed: [pg_stat_statements]
# This will cause a brief interruption to database connections.
# Restart PostgreSQL now? [y/N]:

# 跳过确认并自动重启
pg extension remove pg_stat_statements -i pg01 --auto-restart

如果你拒绝重启，可以稍后应用更改：

pg stop -i pg01
pg start -i pg01

查看可用扩展

pg extension available

列出所有 440 个已知扩展：

• 45 个内置（contrib，已在基础镜像中——无需镜像构建）
• 395 个 Pigsty 目录（来自 Pigsty DEB 仓库，需要镜像构建）

扩展目录

参见扩展目录获取 45 个内置扩展完整列表（无需安装）。

参见常用扩展获取常用扩展详细使用示例。

目录外的扩展

只有目录中的扩展（builtin + Pigsty）可以通过 pg extension install 安装。未知扩展名称会在构建开始前被拒绝：

  [X] Unknown extension(s): [nonexistent_ext]

      These extensions are not in the Pigsty catalog or builtin contrib list.
      Check available extensions: pg extension available
      Full Pigsty catalog: https://pigsty.cc/ext/list/

完整目录：https://pigsty.cc/ext/list/

配置

安装扩展后，配置会被更新：

instances:
  pg01:
    extensions:
      - pg_stat_statements
      - uuid-ossp
      - pgmq
    podman:
      image_tag: ghcr.io/mars-base/pgcli/pgcli-pg:18-2.58.0-ext

image_tag 指向包含所有已安装扩展的派生镜像。

共享预加载库

需要 shared_preload_libraries 的扩展会在 postgresql.conf 中自动配置：

# === pgcli extensions (managed — do not edit) ===
shared_preload_libraries = 'pg_stat_statements,pg_cron'
# === end pgcli extensions ===

必须最先加载的扩展（如 citus、timescaledb）会自动放在位置 0，不管安装 顺序如何 —— 如果它们出现在其他位置，PostgreSQL 会 FATAL。

这是 postmaster 级别参数；更改后必须重启 PostgreSQL。

故障排除

扩展安装失败

  [X] Unknown extension(s): [nonexistent_ext]

原因：扩展名称不在内置 contrib 列表或 Pigsty 目录中。

解决方法：

• 验证扩展名称：pg extension available
• 检查 Pigsty 目录：https://pigsty.cc/ext/list/
• 注意确切的 SQL 扩展名称（例如 vector 而不是 pgvector）

CREATE EXTENSION 失败

ERROR: extension "pgmq" already exists

扩展已安装但未在配置中跟踪。你可以安全地忽略这个，或手动将其添加到配置：

extensions:
  - pgmq

共享预加载库冲突

如果 shared_preload_libraries 在 postgresql.conf 中被手动编辑，pgcli 的标记块会覆盖它。

解决方法：删除手动配置并让 pgcli 管理它。

注释

• 扩展数量：45 个内置（contrib）+ 395 个 Pigsty 目录 = 440 个已知扩展
• 镜像大小：每个扩展增加 10-50MB 到镜像，但 Pigsty 包已优化
• 构建时间：首次扩展安装需要 1-3 分钟（下载 + 构建）；后续安装更快（缓存命中）
• 副本行为：副本可以安装扩展，但 CREATE EXTENSION 会被拒绝（只读）。在主实例上安装；副本通过物理复制同步
• 扩展升级：ALTER EXTENSION ... UPDATE TO ... 尚不支持；通过 pg exec 手动运行

10.1 - 扩展目录

本页列出基础镜像中所有内置扩展。使用示例请参见常用扩展。

内置扩展（45 个）

这些扩展已包含在 PostgreSQL 基础镜像中，无需镜像构建或 pg extension install。直接运行 CREATE EXTENSION 即可启用。

需要 shared_preload_libraries

这些扩展启用后需要重启 PostgreSQL。通过 pg extension install 安装时，pgcli 会自动处理重启。

无需重启

这些扩展可以通过 CREATE EXTENSION 立即启用，无需重启。

10.2 - 常用扩展

最常用 PostgreSQL 扩展的使用示例，已在 PG 18 + pgcli 环境下测试通过。

性能与监控

# 一次性安装所有扩展
pg extension install pg_stat_statements,pg_repack,pg_prewarm --auto-restart

# 查找 top 5 慢查询
pg exec "SELECT query, calls, total_exec_time::numeric(10,2) AS ms
         FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 5;"

# 重组膨胀表
pg exec -- pg_repack -U admin -d default_db -t my_table --no-superuser-check

# 预热表
pg exec "SELECT pg_prewarm('my_table');"

数据类型与标识符

# UUID 生成（PG 18 内置——无需安装扩展）
pg exec "SELECT gen_random_uuid();"  # v4 随机 UUID（PG 13 起内置）
pg exec "SELECT uuidv7();"           # v7 时间有序 UUID（PG 18 新增）

# uuid-ossp 扩展——仅在需要 v1/v3/v5 UUID 时安装
pg exec "CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";"
pg exec "SELECT uuid_generate_v1();"  # v1 时间戳 + MAC 地址
pg exec "SELECT uuid_generate_v3(uuid_ns_url(), 'https://example.com');"  # v3 基于 MD5
pg exec "SELECT uuid_generate_v5(uuid_ns_url(), 'https://example.com');"  # v5 基于 SHA-1

# 键值存储
pg exec "SELECT 'theme => dark, lang => en'::hstore -> 'theme';"
# 返回: dark

# 不区分大小写匹配
pg exec "CREATE TABLE users (email citext);
         INSERT INTO users VALUES ('Alice@Example.COM');
         SELECT * FROM users WHERE email = 'alice@example.com';"

搜索与文本

# 模糊搜索
pg exec "SELECT name, similarity(name, 'John') FROM users
         ORDER BY similarity(name, 'John') DESC LIMIT 5;"

# 创建三元组索引加速模糊搜索
pg exec "CREATE INDEX users_name_trgm_idx ON users USING gin (name gin_trgm_ops);"

# 去除重音
pg exec "SELECT unaccent('Crème Brûlée');"  -- 返回 'Creme Brulee'

# 组合使用实现不区分重音的模糊搜索
pg exec "SELECT name FROM users WHERE name % unaccent('Creme Brulee');"

安全与加密

# 使用 bcrypt 哈希密码
pg exec "SELECT crypt('my_password', gen_salt('bf'));"

# 验证密码
pg exec "SELECT (crypt('my_password', stored_hash) = stored_hash);"

# 对称加密/解密
pg exec "SELECT pgp_sym_decrypt(pgp_sym_encrypt('secret', 'key'), 'key');"

# 启用特定操作的审计日志
pg exec "SET pgaudit.log = 'read, ddl';"

地理空间

pg extension install postgis --auto-restart

# 创建包含空间数据的表
pg exec "CREATE TABLE places (id serial, name text, geom geometry(Point, 4326));"
pg exec "INSERT INTO places (name, geom) VALUES
         ('San Francisco', ST_MakePoint(-122.4, 37.8)),
         ('London', ST_MakePoint(-0.1276, 51.5074));"

# 查找 5km 范围内的地点
pg exec "SELECT name FROM places
         WHERE ST_DWithin(geom, ST_MakePoint(-122.4, 37.8)::geography, 5000);"

# 计算两个城市间的距离（米）
pg exec "SELECT ST_Distance(
           ST_MakePoint(-74.006, 40.7128)::geography,
           ST_MakePoint(-0.1276, 51.5074)::geography);"

AI 与向量搜索

pg extension install vector --auto-restart

# 创建带向量列的表
pg exec "CREATE TABLE items (id serial PRIMARY KEY, embedding vector(3));"
pg exec "INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]'), ('[7,8,9]');"

# 查找最近邻（欧几里得距离）
pg exec "SELECT id FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;"

# 创建 IVFFlat 索引加速近似搜索
pg exec "CREATE INDEX items_embedding_idx ON items USING ivfflat (embedding vector_l2_ops);"

时序数据

pg extension install timescaledb --auto-restart

# 创建超级表
pg exec "CREATE TABLE sensor (time timestamptz NOT NULL, value float);
         SELECT create_hypertable('sensor', 'time');"

# 时间桶聚合
pg exec "SELECT time_bucket('1 hour', time) AS bucket, avg(value)
         FROM sensor GROUP BY bucket ORDER BY bucket;"

定时任务与分布式

pg extension install pg_cron --auto-restart

# 调度每日清理任务（午夜运行）
pg exec "SELECT cron.schedule('cleanup', '0 0 * * *',
         'DELETE FROM logs WHERE created_at < now() - interval ''30 days''');"

# 列出已调度的任务
pg exec "SELECT jobid, schedule, command FROM cron.job;"

# 取消调度
pg exec "SELECT cron.unschedule('cleanup');"

外部数据

# 创建外部服务器
pg exec "CREATE SERVER remote FOREIGN DATA WRAPPER postgres_fdw
         OPTIONS (host '10.0.0.2', port '5432', dbname 'analytics');"

# 创建用户映射
pg exec "CREATE USER MAPPING FOR current_user SERVER remote
         OPTIONS (user 'reader', password 'secret');"

# 导入远程 schema 作为外部表
pg exec "IMPORT FOREIGN SCHEMA public FROM SERVER remote INTO remote_schema;"

# 像查询本地表一样查询远程数据
pg exec "SELECT * FROM remote_schema.events LIMIT 10;"

pg extension install pg_duckdb --auto-restart

# 在 DuckDB 中执行 SQL —— duckdb.query 是表函数（必须在 FROM 子句中使用）
pg exec "SELECT * FROM duckdb.query(\$\$ SELECT 42 AS answer, 'hello' AS msg \$\$);"

# 将表导出为 Parquet 文件
pg exec "COPY my_table TO '/tmp/my_table.parquet' (FORMAT 'parquet');"

# 直接读取 Parquet/CSV 文件
pg exec "SELECT * FROM duckdb.query(\$\$
         SELECT * FROM read_parquet('/tmp/my_table.parquet') WHERE id > 2 \$\$);"

# 将整个查询下推到 DuckDB 执行（OLAP 加速）
pg exec "SET duckdb.force_execution = true;
         SELECT category, sum(amount) FROM sales GROUP BY category;"

# 纯 DuckDB SQL（完全绕过 PostgreSQL 规划器）
pg exec "SELECT * FROM duckdb.raw_query(\$\$ SELECT range AS n FROM range(1, 6) \$\$);"

# --- 从 S3 / MinIO 读取文件（无需复制文件） ---

# 先创建 S3 secret（use_ssl 是文本类型：'true'/'false'）
pg exec "SELECT duckdb.create_simple_secret('S3', '<access_key>', '<secret_key>',
         '', 'us-east-1', 'path', '', 'minio.example.com:9000',
         's3://bucket', '', 'false');"

# 直接查询 bucket 中的 CSV
pg exec "SELECT * FROM duckdb.query(\$\$
         SELECT category, count(*) AS cnt, sum(sales) AS total_sales
         FROM read_csv('s3://bucket/products.csv', auto_detect=true)
         GROUP BY category ORDER BY total_sales DESC \$\$);"

兼容性说明

11 - 数据导入/导出

导出和导入数据库到转储文件。支持自定义格式（推荐）和纯 SQL，带有自动 gzip 压缩。还支持在实例间管道传输。

# 导出为自定义格式（推荐，最快恢复）
pg export -i proj01 -o backup.dump

# 导出为 SQL 格式（人类可读）
pg export -i proj01 -o backup.sql

# 导出时使用 gzip 压缩（从 .gz 扩展名自动检测）
pg export -i proj01 -o backup.dump.gz
pg export -i proj01 -o backup.sql.gz

# 导出特定数据库
pg export -i proj01 -d mydb -o backup.dump

# 导出时指定压缩级别（0-9）
pg export -i proj01 -o backup.sql.gz --compress=9

# 导出时显示详细输出（显示进度）
pg export -i proj01 -o backup.dump -v

# 从自定义格式导入
pg import -i proj02 backup.dump

# 从 SQL 格式导入
pg import -i proj02 backup.sql

# 导入压缩文件（从 .gz 扩展名自动检测）
pg import -i proj02 backup.dump.gz

# 导入到特定数据库
pg import -i proj02 -d mydb backup.dump

# 导入时清理（恢复前删除现有对象）
pg import -i proj02 --clean backup.dump

# 导入时显示详细输出
pg import -i proj02 backup.dump -v

# 在实例间管道传输（无临时文件）
pg export -i proj01 | pg import -i proj02
pg export -i proj01 -d mydb | pg import -i proj02 -d mydb --clean

# 通过 SSH 跨主机管道传输
pg export -i proj01 | ssh user@remote "pg import -i proj02"
ssh user@remote "pg export -i proj01" | pg import -i proj02
ssh user@host1 "pg export -i proj01" | ssh user@host2 "pg import -i proj02"

# 通过连接字符串使用远程数据库（--dsn）
pg export --dsn postgres://user:pass@host:5432/mydb -o backup.dump
pg import --dsn postgres://user:pass@host:5432/mydb backup.dump --clean
pg export -i proj01 | pg import --dsn postgres://user:pass@host:5432/mydb
pg export --dsn postgres://user:pass@host1:5432/db1 | pg import --dsn postgres://user:pass@host2:5432/db2

# DSN 也可用于本地实例（当端口与默认值不同时很有用）
pg export --dsn postgres://admin:pass@127.0.0.1:35432/mydb | pg import --dsn postgres://admin:pass@127.0.0.1:35433/mydb --clean

格式比较：

格式检测： 使用魔数（基于内容）配合扩展名回退。

• 以 PGDMP 开头的文件 → 自定义格式
• .sql 或 .sql.gz → 纯 SQL 格式
• .gz 扩展名或 gzip 魔数（0x1f 0x8b） → 自动解压
• 如果内容检测失败则使用扩展名作为回退

远程数据库（–dsn）： 使用连接字符串连接到任何 PostgreSQL 实例。

• 无需本地 PostgreSQL 安装
• 适用于本地到远程、远程到本地和远程到远程迁移
• 支持与本地实例相同的所有标志（-o、-d、--clean、-v、--compress）

关于现有数据的说明： 导入到包含现有表的数据库会失败，除非你使用 --clean 标志，它会在恢复前删除对象。导入到已包含数据的数据库时使用 --clean。

用例：

• 在实例间迁移数据：pg export -i proj01 | pg import -i proj02
• 跨主机迁移：pg export -i proj01 | pg import --dsn postgres://user:pass@remote:5432/db
• 与团队共享数据库：pg export -i proj01 -o dump.dump.gz（压缩，更小文件）
• 重大更改前备份：pg export -i proj01 -o pre-migration.sql.gz
• CI/CD 管道：导出测试数据，导入到新的测试数据库

12 - 恢复

时间点恢复（PITR）

恢复到首次备份后的任意时间点。

# 恢复（只读，提交前检查）
pg restore --time "2026-08-26 15:30:00+00"

# 预览将要恢复的内容而不执行（试运行）
pg restore --time "2026-08-26 15:30:00+00" --dry-run

# 恢复期间流式输出恢复容器日志
pg restore --time "2026-08-26 15:30:00+00" --tail-logs

# 如果需要可以尝试不同的时间
pg restore --time "2026-08-26 15:25:00+00"

# 提升为读写（切换时间线）
pg restore --time "2026-08-26 15:30:00+00" --promote

# 跳过确认
pg restore --time "2026-08-26 15:30:00+00" --promote --force

时间格式：

• 2026-08-26 15:30:00+08:00 — 带时区偏移
• 2026-08-26 15:30:00+08 — 仅时区小时
• 2026-08-26 15:30:00Z — UTC
• 2026-08-26 15:30:00 — 假定为 UTC

恢复工作流： 停止 → 恢复 → 启动 → WAL 重放到目标时间

注意： --promote 之后，在进行进一步的 PITR 之前需要创建新的完整快照。

Patroni 集群

Patroni HA 集群用 pg ha restore 恢复，是上面单实例命令的集群版对应物。它接受 相同的 --time（全部格式），并支持 --dry-run、--tail-logs、--force。

# 预览恢复计划，不触碰集群
pg ha restore app --time "2026-08-26 15:30:00+00" --dry-run

# 恢复，同时流式输出承载 bootstrap 成员的恢复日志
pg ha restore app --time "2026-08-26 15:30:00+00" --tail-logs

# 指定由哪个本机成员承载 bootstrap（默认：第一个本机成员）
pg ha restore app --time "2026-08-26 15:30:00+00" --member node1

# 跳过确认提示
pg ha restore app --time "2026-08-26 15:30:00+00" --force

原理： 先 pause 集群（冻结 failover，免得本机停掉 leader 时远端副本被 promote 抢走 leadership），再移除集群的 DCS 身份，然后让一个本机成员通过 Patroni 的自定义 bootstrap 方法，从 pgBackRest 仓库把（已清空的）数据目录恢复到目标 时间点。该成员在新时间线上启动并自动 promote 成可写 leader；其余成员——本机的、 跨主机的——都经 DCS 重新加入它。前提是该 stanza 已配好 WAL 归档，由带 S3 仓库的 pg backup setup 预置（见 HA 备份插件）。

与单实例恢复的差异：

• 总是 promote。 没有"挂起只读、检查、再换个时间重试"的两步——集群在目标点 直接以可写状态起来。执行前用 --dry-run 确认目标时间。
• 必须在拥有成员的主机上运行，且动手前先检测 leader。 pg ha restore 在执行 任何破坏性操作之前，会先从 DCS 读取当前 leader，判断它是否是本机的可控成员。 真实执行时若 leader 不在本机（远端成员，或本机视图里根本没有的跨主机成员），会 直接拒绝；--dry-run 则只是告警。原因：破坏性路径会清掉 DCS 身份并让本机 成员重新 bootstrap，若本机停不掉当前 leader，它会在 旧时间线 上抢先重新抢回 DCS，与 bootstrap 竞态。先把 leader 切到本机（pg ha switchover/failover）， 或到 leader 所在主机执行。leader 读不到/为空时不阻断（覆盖首次 bootstrap 的场景）。
• 没有 --promote flag —— promote 是自动的。

恢复工作流： 预检（leader 必须是本机成员）→ pause 集群 → 停本机成员 → 清 DCS → 清空并用仓库 bootstrap 一个成员 → 它 promote 成新时间线的 leader → 其余成员作为副本 重新加入。

恢复之后： 建一个新的完整快照以给新时间线重新定位—— pg ha snapshot create app --type full。这步通常直接成功：同一 stanza 的 pgBackRest 恢复在时间线切换时保持 system-id 不变，所以首个快照不会报 [051] system-id ... do not match stanza，也不需要 stanza-upgrade。若有副本没有 自动重新加入，用 pg ha ctl app -- reinit app-<ns> <member> --force 重建它。

13 - HA 集群

Patroni 是 PostgreSQL 高可用的事实标准：它掌管每个 postmaster 的生命周期、在成员间流式复制、并在 leader 失联时执行自动 failover。pgcli 把 Patroni 作为独立的顶级命令 pg ha 暴露出来——它是一种独立的模式，既不是普通的 pg 实例，也不是用 pg addon install 安装的插件。

关于归属。 Patroni 相关页面原先挂在 插件 Addons 下。现在它们独立成 HA 集群这一节，因为 pg ha 并不通过插件系统安装——插件索引里提到它只是为了方便 检索。etcd DCS 与 HAProxy 负载均衡仍是插件页面（etcd、 HAProxy）；本节会在相关处链回去。

子页面

典型路径

# 一台主机：引导集群（基于已安装的 etcd 插件成员）
pg ha create app --member node1 --etcd m1
pg ha create app --member node2 --etcd m1

# 其它主机用同一套密码登记自己的成员
pg ha passwords app --file app-passwd.yml
ssh other-host
pg ha create app --member node3 --advertise-host 10.0.0.12 \
    --etcd-endpoints 10.0.0.9:2379 --passwords-file app-passwd.yml

# 直接跑 SQL —— leader 由 pgcli 从 DCS 解析
pg ha exec app "SELECT version()"
pg ha psql app

# 备份它，并且能回到过去
pg backup setup --s3-endpoint ...
pg ha snapshot create app --type full
pg ha restore app --time "2026-08-26 15:30:00+00"

相关

• 插件：etcd（DCS）、HAProxy （可扛故障切换的稳定客户端端点，可选读写分离）、MinIO（备份所在的 S3 仓库）
• 恢复 → Patroni 集群：与单实例恢复共通的 PITR 基础
• Failover：副本提升：非 Patroni 的单副本提升路径（pg replica）
• Namespace 隔离 —— scope、stanza、容器名都带 namespace 前缀

13.1 - Patroni 高可用

Patroni 是 PostgreSQL 高可用的事实标准：它 管理每个 postmaster 的生命周期、在成员间流式复制，并在 leader 失联时执行 自动故障切换。pgcli 将 Patroni 作为独立的模式暴露 —— pg ha —— 而不是 把它揉进普通的 pg 实例管理路径。

这是独立模式，不是 addon 子命令。 拥有 PostgreSQL 进程的是 Patroni （不是 pgcli）。pg ha 成员不会出现在 cfg.Instances 里，不复用实例 生命周期代码，也不是 pg create 创建的。它唯一借鉴 addon 体系的地方，是 用 etcd 做 DCS。

仅支持 Linux，与 etcd addon 一样：Patroni 成员依赖 podman 的 host 网络。root 和 rootless podman 均可使用。macOS 上这些命令会快速失败并给出 清晰提示。

所有权边界

最需要先理解的一件事，是谁拥有什么：

pgcli 从不直接编辑运行中 PostgreSQL 的配置，也从不跑 initdb —— 这两件事都 是 Patroni 做的。这也是为什么普通 PG 镜像的 docker-entrypoint-initdb.d 约定（admin 角色 / 默认库）在这里不适用：Patroni 自己 bootstrap 集群， 角色体系是 postgres（superuser）、replicator、rewind_user。

容器生命周期 ≠ 安全的 PG 重启

因为 Patroni 是容器里的 PID 1：

• pg ha create 是重装语义（stop + 重建容器）。重建 leader 会让该节点 完全离线并触发故障切换。改成员配置靠重跑 create 是安全的；动态参数 请优先用 pg ha edit-config，它绝不碰容器。
• pg ha start / pg ha stop 是裸的容器 start/stop。停掉 leader 容器和 该节点宕机一样具有破坏性 —— Patroni 会切到副本。计划内运维请先 pg ha pause（关掉自动 failover），再停容器。
• paused 的集群在 resume 之前没有自动 failover。

工作原理

pg ha 每个成员跑一个 Patroni 容器。同一 scope 的所有成员指向同一个 DCS（一个 etcd 集群），DCS 保存集群的动态配置和 leader 锁：

1. 某个 scope 的第一次 pg ha create 完成 bootstrap：Patroni 跑 initdb，抢下 leader，成为 leader。
2. 之后的每个成员自动从当前 leader pg_basebackup 并开始流复制 —— 没有 flag 区分"添加"还是"加入"。
3. pg ha 的控制命令（switchover、pause 等）在临时容器里对 DCS 跑 patronictl，所以即使本机没有成员容器在跑也能工作。

DCS 是唯一真相来源：Patroni 每个周期都从 DCS 重新渲染每个成员的 postgresql.conf/pg_hba.conf，手工改盘上文件会丢 —— 请用 pg ha edit-config。

Scope 与 DCS 存储路径

pg ha create <scope> 里的 <scope> 就是 Patroni 集群名 —— 一个 HA 集群 的身份标识。所有接收 scope 的命令（status、switchover、failover、 pause、ctl 等）指的都是同一个集群；某 scope 的第一次 create 完成 bootstrap，之后同 scope 的 create 是加成员。（--member 是集群内部逐主 机的节点名 —— 每台机器一个成员。）

pg.yaml 中集群以该 scope 为 key 存放在 addons.patroni.<scope> 下。

etcd 里实际存了什么

Patroni 把一切存在固定的 etcd namespace + scope 之下：

• namespace： /service/ —— Patroni 的顶层键，pgcli 不改动。
• scope： pgcli 写入 patroni.yml 的是 PatroniScope(scope)，即你起的名字 加上 pgcli 的 namespace 后缀。Patroni 自己没有 namespace 概念（其 etcd 前缀就是裸 scope），pgcli 把后缀烘进 scope，防止两个 pgcli namespace 共用一 套 etcd 时串群。

因此一个集群在 etcd 里的完整前缀是：

/service/<scope>[-<namespace>]/          # 例：/service/app/（无 namespace）
                                         #     /service/app-prod/（namespace: prod）
├── initialize       # bootstrap 标记（只写一次）
├── leader           # 当前主；值 = 成员名
├── members/<member> # 每个成员的注册信息（conn_url、api_url、状态）
├── status           # 集群 LSN / 状态
├── config           # 动态配置（pause 标记也在这里）
├── history          # 配置修订历史
├── failover         # 手动 failover 请求
└── sync             # 同步复制状态

前缀以下的键属于 Patroni 自己的 DCS 布局。想查看，把 pg etcdctl 指向同机 器/同配置里一个运行中的 etcd 成员：

ETCDCTL_ENDPOINTS=http://127.0.0.1:2379 pg etcdctl get /service/ -- --prefix --keys-only

注意：即使建集群时用的是裸名字，这里显示的 scope 也会带着 namespace 后缀。

安装

前置条件：一个 DCS。要么复用本地 etcd addon 成员，要么指向外部 etcd。

# 1. 一个 DCS —— 这里用 etcd addon（多节点配置见 etcd 页面）
pg addon install etcd --name m1

# 2. 第一个成员 bootstrap 集群（成为 leader）
pg ha create app --member node1 --etcd m1

# 3. 后续成员自动以副本身份加入
pg ha create app --member node2 --etcd m1
pg ha create app --member node3 --etcd m1

# 4. 观察
pg ha status app

pg ha status app 渲染 patronictl list —— 恰好一行 Leader，其余是 Replica … streaming：

+ Cluster: app (7683433951661608987) +-----------+----+-------------+-----+------------+-----+
| Member | Host            | Role    | State     | TL | Receive LSN | Lag | Replay LSN | Lag |
+--------+-----------------+---------+-----------+----+-------------+-----+------------+-----+
| node1  | 127.0.0.1:5432  | Leader  | running   |  1 |             |     |            |     |
| node2  | 127.0.0.1:5433  | Replica | streaming |  1 |   0/3000060 |   0 |  0/3000060 |   0 |
| node3  | 127.0.0.1:5434  | Replica | streaming |  1 |   0/3000060 |   0 |  0/3000060 |   0 |
+--------+-----------------+---------+-----------+----+-------------+-----+------------+-----+

不带参数时，pg ha status 汇总每个集群：容器状态、成员数、每个成员的 pg=/rest= 端口。

DCS 选型

Patroni 只需要一个可达的 etcd 集群，因此有两种布局：

• 同机部署 —— 把 etcd 成员作为 addon 跑在和 Patroni 成员相同的主机上，用 --etcd m1,m2,m3 指定。最省事：一台机器同时扮演两个角色，不多占主机。适合 起步的 3 节点 HA 集群。

• 专用 DCS 主机 —— 把 etcd 集群跑在单独的（虚拟）机器上，再用 --etcd-endpoints 让每个 Patroni 成员指向它。下面每一行都在不同主机上执行 （pgcli 是按主机管理的）：

  # 主机 E1 (10.0.0.20) —— bootstrap etcd 集群
  pg addon install etcd --name e1 --cluster prod \
      --advertise-host 10.0.0.20 --client-port 2379 --peer-port 2380
  
  # 主机 E2 (10.0.0.21) —— 加入
  pg addon install etcd --name e2 --cluster prod \
      --advertise-host 10.0.0.21 --client-port 2379 --peer-port 2380 \
      --join http://10.0.0.20:2379
  
  # 主机 E3 (10.0.0.22) —— 加入
  pg addon install etcd --name e3 --cluster prod \
      --advertise-host 10.0.0.22 --client-port 2379 --peer-port 2380 \
      --join http://10.0.0.20:2379
  
  # 主机 A / B / C —— 每台一个 Patroni 成员，endpoint 列表完全相同
  pg ha create app --member node1 --advertise-host 10.0.0.11 \
      --etcd-endpoints 10.0.0.20:2379,10.0.0.21:2379,10.0.0.22:2379

  这是可用性更高的拓扑：etcd 的 quorum 不会随某台 PG 主机一起消失，重装数据库 机器也不会顺带带走 DCS。PG 主机只是访问 DCS；--etcd-endpoints 列出全部 成员的 client URL，因此某一台 etcd 主机宕机时 Patroni 会自动顺延到下一个 endpoint（写入仍然需要 etcd 自身的 quorum —— 3 台中要活 2 台）。每台 PG 主机 上的 endpoint 列表要保持一致。

  只写一个 endpoint（--etcd-endpoints 10.0.0.20:2379）也能用 —— 那一台 etcd 成员会服务整个集群，另外两台被它挡在后面。但这又把单点引回来了：E1 一 宕，Patroni 就够不到 DCS，哪怕 etcd 的 quorum 是健康的；leader 续不上锁 就会自我降级。你实际有几个成员，就把它们全部列出来。

生产环境推荐独立的奇数（3 或 5）成员 etcd 集群；同机部署用于开发和小型部署即 可。

命令

-- 之后的 flag 原样到达 patronictl（cobra 会剥掉 --），所以 pg ha ctl app -- show-config、pg ha ctl app -- topology、 pg ha edit-config app -- -s synchronous_mode=true --force 都能用。 edit-config --show 是 ctl … -- show-config 的便捷别名。

跨主机成员

每台主机各自跑自己的 pgcli，只管本机的成员；集群通过共享 DCS 汇合，所以 两台主机的 pg.yaml 各自持有同一个 scope 的一部分视图。

# host A (10.0.0.11) —— bootstrap（自带 etcd，或外部 DCS）
pg ha create app --member node1 --advertise-host 10.0.0.11 \
    --etcd-endpoints 10.0.0.9:2379,10.0.0.10:2379

# host A —— 导出第一台生成的密码，供其他主机使用
pg ha passwords app --file app-passwd.yml

# host B (10.0.0.12) —— 加入，共用同一个 DCS 与同一套密码
pg ha create app --member node2 --advertise-host 10.0.0.12 \
    --etcd-endpoints 10.0.0.9:2379,10.0.0.10:2379 \
    --passwords-file app-passwd.yml

跨主机清单（以下每一项都必须在每台主机上对齐）：

1. 端口 —— 自动分配是按主机的，但 connect_address 存在 DCS 里全集群共 享。请在每台主机上把 --host-port / --restapi-port 设成相同值，否则 副本之间连不通。
2. 密码 —— Patroni 的复制 / rewind / REST-API 鉴权是全集群一致的。用 pg ha passwords app --file app-passwd.yml 导出第一台生成的那套，对每台其 他 pg ha create 传 --passwords-file app-passwd.yml。
3. --advertise-host —— 跨主机成员必传；它把监听地址翻成 0.0.0.0 并把 可达 IP 写进 connect_address。留空则该成员只走回环。第一个（bootstrap） 成员也不例外：它就是 leader，其 connect_address 会写进 DCS，之后每台主 机的 pg_basebackup 都拨这个地址 —— 用默认值引导的集群永远无法再加跨机成 员。只要以后可能在别的主机加成员，第一次 create 就该传本机 LAN IPv4。
4. 防火墙 —— 在成员之间两两放行两个端口（PG + REST API）。

pgcli 不校验对端配置；pg ha status 会显示每个成员的 connect_address，便于 自查可达性。

备份跨主机 leader

每台主机的 pg.yaml 只记录本机成员，所以本机默认看不到另一台主机上的 leader —— 而 pgBackRest 的 stanza-create / 全量备份恰恰要求连到 leader。

这一步现在自动完成：pg ha create 成功装好一个成员后，会把它 pgcli 私有的 端口（SSH / REST API）写进 etcd 的 /pgcli/ha/<scope>/<member> 注册表（拓扑本身 —— 成员名 + host:pgport —— Patroni 早已存在 DCS 里）。备份配置生成时用 patronictl list 拿全集群拓扑、再查注册表补齐每个远端成员的 SSH 端口，于是 pgbackrest.conf / ssh_config 自动包含所有主机的成员，pg1-host 与 SSH HostName 直接指向远端 IP（本机成员仍走 127.0.0.1）。pg ha start/stop/remove、 autostart 与 pg ha extension 会跳过非本机成员 —— 它们归各自主机的 pgcli 管。

刷新备份配置即可：

pg backup setup

跨机备份互信现在全自动。cluster-wide stanza 把每个成员列成一个 pg*-host， 所以从任意主机发起全量备份 / check，pgBackRest 会 SSH 探测所有主机的成员来 找 primary——这些成员的 sshd 都必须接受发起方主机的备份公钥，且其 --advertise-host 已把监听翻成 0.0.0.0（见上文），跨机 SSH 才可达。 pg backup setup 负责打通：各主机 create 时把本机备份公钥发布进同一个 /pgcli/ha/<scope>/<member> 注册表；setup 把全集群成员的公钥合并成一个每集群 一份的 authorized_keys 文件，成员容器把它作为额外的 AuthorizedKeysFile bind-mount 进去。sshd 每次登录都重新读该文件，合并又是原地覆写，所以后来加入的 主机无需重启就被运行中的成员信任（该挂载只在首次出现时随归档配置的 pause 窗口 recreate 一次性补上）。pg ha remove 掉成员会同时删其注册表 key，下次合并就不再 信任它。

S3 仓库 CA 也走同一条路：配了 ca_file 的主机把证书发布到 /pgcli/ha/<scope>/.repo/ca，ca_file 留空的加入者自动拉取、并把本地 ca_file 指到拉下来的副本。若存储主机又是另一台机器，首台主机也能免拷文件拿到 CA—— pg backup fetch-ca <存储主机>:<端口> 直接从端点的 TLS 链里取回（见 MinIO 文档）。 注册表里只允许公开材料——SSH 公钥与自签 CA 证书；私钥、 密码、S3 secret_key 绝不写入（etcd 这条链路无认证）。

兜底：若某远端成员是那台主机升级 pgcli 之前创建的、尚未注册端口，生成器会把 它的 SSH 端口回退到本 scope 的基础端口（每台主机都从 patroni_ssh_start_port 起，通常首个成员即猜对）。猜错时，手动登记这一个成员覆盖之（不创建任何容器）：

pg ha remote app --member node3 --ssh-port 42301   # 写 members.<m>.remote_host
pg ha remote remove app --member node3             # 撤销该登记

S3 备份与 WAL 归档

Patroni 集群默认不开归档——只有全量备份永远做不到时间点恢复。开启 S3 仓库 （见备份文档）即随之打开。每个集群是一个 stanza——pgcli_<scope>，与带 namespace 的 DCS scope 一致，两个 pgcli namespace 共用一个 S3 桶也撞不上——其备份侧配置把每个成员列为一个 pg*-host，pgBackRest 自己找到 primary，failover 后也无需改配置。 pg backup setup 会把同一份 archive_command 渲染进每个成员本地的 patroni.yml（pgcli 绝不把归档 GUC 写进 DCS——那是 edit-config 的地盘； 而只要 DCS 不管理某个 key，Patroni 就会采用本地值），在 pause 窗口内按"副本 先、leader 后"重建过期的成员容器（recreate 同时就是 archive_mode 需要的 postmaster 重启），并为集群执行 stanza-create + check。此后 WAL 由持有 leader 锁的成员持续推送到 S3。

每个成员会有短暂离线、最后有一次计划内的 leader 降级——与 pg ha create 的 recreate 语义相同。

密码

某个 scope 的第一次 pg ha create 生成四份凭据 —— superuser、 replication、rewind，以及 restapi basic-auth 对（restapi_user / restapi_password）—— 存在 pg.yaml 的对应集群下。命令行上永远不用传密码： 第一个成员自动生成，pg ha passwords 把存储的这套导出成 --passwords-file 的格式，供其它主机复用：

pg ha passwords app                          # 把存储的这套以 YAML 打到 stdout
pg ha passwords app --file app-passwd.yml    # 或写入文件（权限 0600）

（不加 --file 则输出到 stdout —— 建议用 --file，免得密码落进 shell 历史和 滚屏。）

四个角色及其默认用户名（由 pgcli 固定 —— 你只设置密码，密码默认按每个角色 生成随机 16 位字符串）。长度可用 --password-length 覆盖（pg ha create / pg create，8–64）；它只对"生成"这条路径生效，对 --passwords-file 或已存储的 密码集无效：

postgres / replicator / rewind_user 这些用户名被写进渲染出的 patroni.yml （postgresql.authentication）；可生成 / 用 --passwords-file 提供的只是密码部分。 restapi_user 是唯一可通过密码文件覆盖的用户名。

需要完全自己掌控（或想手写这份文件）时，用同样格式配 --passwords-file：

# app-passwd.yml
superuser: <postgres superuser 密码>
replication: <replicator 密码>
rewind: <rewind_user 密码>
restapi_user: postgres          # 可选，默认 postgres
restapi_password: <REST API basic-auth 密码>

pg ha create app --member node1 --etcd m1 --passwords-file app-passwd.yml

pg ha create 会打印每份密码的来源（生成并存盘 vs. 来自文件路径）。渲染出的 patroni.yml 以 0600 权限写入，因为它内嵌了所有这些密码。

开机自启

和其他基础 addon 一样，Patroni 成员的容器可以在主机重启后被拉起 —— 但它只 启动已存在的容器，读取盘上已有的 patroni.yml；绝不重新渲染配置或重建 数据。

pg autostart enable --ha --scope app --name node1

成员一次切一个（--ha --scope <scope> --name <member>）。相对 DCS 的启动顺序 无所谓：Patroni 会重试直到 etcd 应答，然后正常重选。启动服务的机制见 autostart 页面。

日志

pg logs addon patroni --scope app --name node1          # 最近 50 行
pg logs addon patroni --scope app --name node1 -f       # 跟踪

容器名为 pgcli-patroni-<scope>-<member>（设置了 namespace 时带前缀）。

连接

pg ha exec 和 pg ha psql 是零配置路径：pgcli 自己从 DCS 解析出 leader，用存储的超管密码认证，在一次性的临时容器里跑 psql —— 不用手拼 dsn、不用进成员容器，而且远端成员同样可达（就是普通 TCP + scram，所以另一台主机上的副本也能连；用 --member 指定具体节点）。

pg ha exec app "SELECT version()"
pg ha exec app --member node2 "SELECT pg_is_in_recovery()"   # 只读，打在副本上
pg ha psql app                                               # 交互式

pgcli 之外的客户端，连的是 leader 的 PostgreSQL 端口。用 pg ha status app 找 leader （Leader 行的 Host 就是它的 connect_address），再把 pg psql 指过去。 单机默认（仅回环）成员下，就是 127.0.0.1:<host_port>。

pg psql --dsn postgres://postgres@127.0.0.1:<leader_port>/postgres

failover 后 leader 会变，所以固定连接串应当避免 —— 除非前面有连接池或 Patroni REST API 的 leader 重定向兜着。

如果需要稳定的、能扛住故障切换的连接端点 —— 以及可选的读写分离 —— 在集群前面 放一个 HAProxy。

计划内主从切换

failover 由 Patroni 掌握，pg ha 只是包装了 patronictl 里"主动挪 leader"的 几个动词。三个命令都只吃 scope：

pg ha switchover app                     # patronictl 交互式询问候选
pg ha switchover app --candidate node2   # 事先指定
pg ha switchover app --candidate node2 --yes   # 脚本化，跳过所有确认

pg ha failover   app --candidate node2 --yes   # 立即提升，不做握手
pg ha pause      app                          # 关掉自动 failover
pg ha resume     app                          # 恢复

• switchover 是计划内的、优雅的那一种：当前 leader 先降级，候选再被提升， 切换瞬间没有在途事务。前提是双方健康且已追平。旧 leader 会在几秒后自动 以 streaming 副本身份回归（Patroni 重启它的 postmaster 时，短暂看到它 stopped 是正常的）。切换会开一条新的 timeline —— 这是正常的，不是脑裂。
• failover 不做握手，直接把副本立即提升。只在 leader 已经挂了、或你有意 丢弃它时使用；对健康集群跑一次只是多一次抖动。凡是计划内的操作，都用 switchover。
• pause 在整个集群范围内关掉自动 failover。任何有计划的容器操作之前 都应该先 pause —— 例如 pg ha stop --all、pg ha create 重建、 pg ha extension —— 否则 Patroni 会在你脚下把一个副本提升走。pg ha resume 再打开。（paused 的集群没有自动 failover，直到 resume 为止。）

这些都是纯 DCS 操作 —— 在一次性容器里跑 patronictl，不碰任何成员的容器或 数据，成员分散在不同主机也照样能切。和所有 pg ha 控制命令一样，scope 会被 解析成带 namespace 后缀的 DCS 键（app → app-default），本机 leader 和 跨主机 leader 的切法完全一样。

由于客户端连的是 leader 的端口，switchover 之后连接目标会跟着变 —— 参见 连接；想要一个稳定的端点，就在前面放 HAProxy。

pg ha vs. pg replica —— 怎么选

pgcli 有两种拿到副本的方式：

需要靠手工控制的副本，用 pg replica。需要集群在节点宕机时无人介入也能活， 用 pg ha。

配置

每个成员渲染的 patroni.yml 完全由 pg.yaml 里 addons.patroni.<scope> 派 生。一条典型记录：

addons:
  patroni:
    app:
      name: app
      etcd_members: [m1]                # 或 etcd_endpoints 指向外部 DCS
      passwords:
        superuser: <superuser-password>
        replication: <replication-password>
        rewind: <rewind-password>
        restapi_user: postgres
        restapi_password: <restapi-password>
      members:
        node1:
          container_name: pgcli-patroni-app-node1
          image_tag: ghcr.io/mars-base/pgcli/pgcli-patroni:18-4.1.5
          host_port: 35590
          restapi_port: 39090
          data_dir: /home/you/.pgcli/addon/patroni/app/node1
          autostart: false

端口来自两个独立池 —— patroni_start_port（默认 35532）给 PostgreSQL， patroni_restapi_start_port（默认 39060）给 REST API —— 所以 Patroni 成员永远 不会和普通实例或 addon 端口相撞。

DCS 的 scope 键 = scope 加命名空间后缀（Patroni 自己没有 namespace 概念，所以 把前缀烙进 scope，好让两个 pgcli namespace 共用一个 etcd 时不串台）。

默认 patroni.yml

下面是 pgcli 渲染并以只读方式挂载到每个成员容器里的配置文件。密码在 bootstrap 时自动生成；可用 --passwords-file 提供自己的密码集。

scope: app-default
namespace: /service/
name: node1

etcd3:
    hosts: 10.0.0.11:2379       # 来自 --etcd-endpoints 或本地 etcd 成员
    protocol: http

restapi:
    listen: 0.0.0.0:8009
    connect_address: 10.0.0.11:8009
    authentication:
        username: postgres
        password: <自动生成>

bootstrap:
    dcs:
        ttl: 30
        loop_wait: 10
        retry_timeout: 10
        maximum_lag_on_failover: 1048576
        postgresql:
            use_pg_rewind: true
            use_slots: true
            parameters:
                wal_level: replica
                hot_standby: "on"
    initdb:
        - encoding: UTF8
        - data-checksums
    pg_hba:
        - local all all trust
        - local replication all trust
        - host all all all scram-sha-256
        - host replication all all scram-sha-256

postgresql:
    listen: 0.0.0.0:35532
    connect_address: 10.0.0.11:35532
    data_dir: /var/lib/postgresql/data
    bin_dir: /usr/lib/postgresql/18/bin
    pgpass: /patroni/.pgpass
    use_unix_socket: true
    use_unix_socket_repl: true
    authentication:
        superuser:
            username: postgres
            password: <自动生成>
        replication:
            username: replicator
            password: <自动生成>
        rewind:
            username: rewind_user
            password: <自动生成>
    parameters:
        unix_socket_directories: /var/lib/postgresql

要点：

• scope = Patroni 集群名。与 namespace 组合后形成 etcd 键前缀。
• etcd3.hosts = 只写 host:port（不带 http:// 前缀）。多端点逗号分隔。
• bootstrap.dcs 里的值仅为默认值 —— 只在首次 bootstrap 时生效；之后用 pg ha edit-config 修改。
• postgresql.listen: 0.0.0.0 在传了 --advertise-host（跨主机）时才会设置；否则监听 127.0.0.1。
• 密码 在首次 bootstrap 时自动生成并存入 pg.yaml；可通过 pg ha passwords 导出。

动态配置

Patroni 的动态配置存在 DCS（etcd）的 /service/<scope>/config 下。每个成员 在每个循环（每 loop_wait 秒）都读取并应用这些配置 —— 所以 pg ha edit-config 是调优运行时参数的正确方式，无需重启容器。

bootstrap.dcs 是一次性的。 patroni.yml 里的 bootstrap.dcs 块只在某 scope 的第一个成员执行 pg ha create（即集群 bootstrap）时生效。一旦 Patroni 把配置写入 DCS，之后对 YAML 文件中 bootstrap.dcs 的任何修改都会被 完全忽略 —— 即使重新执行 pg ha create（重装）也一样。bootstrap 之后要 改动态配置，请用 pg ha edit-config。

常见的误区：重新跑 pg ha create 不会重新读取 YAML 里的 bootstrap.dcs —— Patroni 看到 DCS 里已有 config 键，就直接使用它。

方式	说明
pg ha edit-config app -- -s key=value	推荐，pgcli 的标准方式
pg ha ctl app -- edit-config	透传到 patronictl，效果一样
Patroni REST API（PATCH /config）	需要能访问到某个成员的 REST API 端口

持久化： 改动直接写入 etcd，不是容器里的文件。容器重启、pg ha start/stop， 甚至 pg ha create（重装）都不会丢失这些设置 —— 新成员会自动从 DCS 拿到最新配置。

查看当前配置

pg ha edit-config app --show

这是 pg ha ctl app -- show-config 的便捷别名。输出是存在 /service/<scope>/config 里的完整 JSON。

修改参数

# 设置单个参数
pg ha edit-config app -- -s loop_wait=5

# 设置多个参数
pg ha edit-config app -- -s loop_wait=5 -s retry_timeout=3

# 不确认直接应用（脚本场景）
pg ha edit-config app -- -s loop_wait=5 --force

# 交互式编辑（用 $EDITOR 打开当前配置）
pg ha edit-config app

改动后，所有成员在下一个循环（loop_wait 秒内）应用。无需重启。

常用可调参数

PostgreSQL 运行时参数也可以在 postgresql.parameters 下设置：

pg ha edit-config app -- -s 'postgresql.parameters.max_connections=200'
pg ha edit-config app -- -s 'postgresql.parameters.work_mem=64MB'

这会触发 PostgreSQL reload（或重启，取决于参数的 context）。查阅 pg_hba.conf 和 postgresql.conf 参数文档，了解哪些设置需要重启。

不要直接编辑的内容

• 不要直接编辑磁盘上的 patroni.yml —— 每次 pg ha create 都会从 pg.yaml 重新生成，且 Patroni 的动态配置从 DCS 读取。
• 不要直接编辑 postgresql.conf —— Patroni 每个循环都会从 DCS 配置覆盖它。
• 不要改 scope 或 namespace —— 这些在 bootstrap 时烙进 DCS 键，无法修改， 只能重建集群。

完整参数参考： Patroni 动态配置 涵盖所有 DCS 可调参数，包含默认值、约束条件和示例。

扩展安装

pg ha extension install app pg_stat_statements,pg_cron   # 安装
pg ha extension list app                                  # 列出
pg ha extension remove app pg_cron                        # 卸载

完整参考： HA 集群扩展安装 涵盖编排顺序、跨主机工作流、 shared_preload_libraries 排序规则以及纯内置扩展快速路径。

注意

• 仅 Linux（root 或 rootless）。 rootless 成员通过 --userns=keep-id 以宿主用户身份运行；root 成员会将配置和数据目录 chown 给 postgres （uid 999），这样容器才能读 0600 的配置、写自己的数据目录。
• pg_hba.conf 有意保持宽松（host all all all scram-sha-256 + replication 一行，另加两行 local ... trust）。rootless podman 的 pasta 会改写回环源地址， 而 Patroni 在自定义 bootstrap 期间生成的 pg_hba 只放行它自己解析出的回环 TCP 地址——两者相加会让 Patroni 连不上自己的实例、卡死 pg ha restore。所以 postgresql.use_unix_socket/use_unix_socket_repl 被设为 true，让 Patroni 改用 unix socket 连自己的 postmaster，绕过改写。收紧成固定白名单是后续待做的 改进 —— 现阶段别把这些端口暴露给不受信网络。
• DCS（etcd）本身也有安全注意事项 —— 见 etcd 页面：pgcli 管理 的 etcd 不启用 TLS 或鉴权。
• 没有 init.sh / docker-entrypoint-initdb.d。 Patroni 自己 bootstrap 集群，所以普通实例的 admin/默认库约定在这里不存在；连 postgres （superuser）来建角色。
• use_slots / use_pg_rewind 已启用：Patroni 接管复制槽，并能用 pg_rewind 让宕过的 leader 重新加入，而不必全量 rebase。

13.2 - Patroni 动态配置

这些参数存储在 DCS（etcd）的 /service/<scope>/config 下，应用于集群的所有成员。使用 pg ha edit-config 修改：

pg ha edit-config app -- -s loop_wait=5
pg ha edit-config app -- -s 'postgresql.parameters.max_connections=200'
pg ha edit-config app --show          # 查看当前配置

参考：Patroni 官方文档、 Pigsty 动态配置。

bootstrap.dcs 是一次性的。 patroni.yml 里的 bootstrap.dcs 块只在某 scope 的第一个成员 bootstrap 集群时生效。一旦 Patroni 把配置写入 DCS，之后 对 YAML 文件中 bootstrap.dcs 的任何修改都会被完全忽略 —— 即使重新执行 pg ha create（重装）也一样。重新跑 pg ha create 不会重新读取 bootstrap.dcs —— Patroni 看到 DCS 里已有 config 键，就直接使用它。

核心时序参数

修改 loop_wait、retry_timeout 或 ttl 时的约束：

loop_wait + 2 * retry_timeout <= ttl

故障切换参数

复制模式

PostgreSQL 设置

通过 postgresql.parameters 键设置 PostgreSQL 参数：

pg ha edit-config app -- -s 'postgresql.parameters.max_connections=200'
pg ha edit-config app -- -s 'postgresql.parameters.work_mem=64MB'
pg ha edit-config app -- -s 'postgresql.parameters.wal_log_hints=on'

备用集群

如果定义了此节，集群将作为备用集群引导，从远端主库流式复制。

复制槽

永久槽示例

slots:
  permanent_physical_slot:
    type: physical
  permanent_logical_slot:
    type: logical
    database: my_db
    plugin: pgoutput

ignore_slots:
  - name: externally_managed_slot
    type: physical

节点固定的物理槽

对于固定的集群拓扑，为每个节点定义永久物理槽，防止临时中断期间槽被删除：

slots:
  node1:
    type: physical
  node2:
    type: physical
  node3:
    type: physical

警告： 永久复制槽仅从 primary/standby_leader 同步到副本。应用程序应在 leader 节点上使用它们。在副本上使用永久槽会导致整个集群的 pg_wal 无限增长。例外：与 Patroni 成员名匹配的物理槽（由 Patroni 创建和维护）在所有节点间同步，用于节点间复制。

查看当前配置

pg ha edit-config app --show

或直接从 etcd 读取：

ETCDCTL_ENDPOINTS=http://10.0.0.1:2379 pg etcdctl get /service/app-default/config -- --prefix

13.3 - Patroni REST API

Patroni 在每个成员上暴露一个 HTTP REST API，提供健康检查端点（供负载均衡器和 Kubernetes 探针使用）、监控数据（含 Prometheus 指标）以及集群管理操作。

参考：Patroni 官方文档、 Pigsty REST API。

查找 REST API

每个成员的 REST API 端口由 pgcli 自动分配，存储在 pg.yaml 的 addons.patroni.<scope>.members.<name>.restapi_port 下。端口也写入渲染后的 patroni.yml 的 restapi.connect_address。

# 查找 REST API 端口
pg ha status app          # 显示每个成员的 pg= 和 rest= 端口

认证

pgcli 在 REST API 上启用了 basic-auth（用户名 postgres，自动生成密码）。 但认证是按方法区分的，而非一律要求：

这是有意设计：只读健康检查保持开放，让负载均衡器或 Prometheus 无需凭据即可 轮询；而改变集群状态的操作（POST /failover、PATCH /config）需要认证。凭据 的存在是为了让 patronictl 和其他 Patroni 成员能执行写操作。

所以负载均衡器健康检查不需要认证：

# 无需 -u —— leader 返回 200，replica 返回 503
curl -s http://<host>:<port>/primary -w "%{http_code}"

写操作才需要认证。密码与 patroni.yml 的 restapi.authentication 中使用的 restapi_password 相同。通过导出命令获取：

# 导出密码到文件，然后提取 restapi_password
pg ha passwords app --file app-passwd.yml
grep restapi_password app-passwd.yml
# restapi_password: <密码>

# 示例：带认证的写操作
curl -u postgres:<restapi-密码> -X PATCH http://<host>:<port>/config -d '{"ttl": 60}'

健康检查端点

所有健康检查端点响应 GET 请求。Patroni 返回描述节点状态的 JSON 文档，附带 HTTP 状态码。仅需状态码时可用 HEAD 或 OPTIONS 代替 GET（无响应体）。

仅主库端点（仅 leader 返回 200）

以下端点仅在节点为当前持有 leader 锁的 leader 时返回 HTTP 200：

# leader 返回 200，replica 返回 503
curl -s -u postgres:<pw> http://<leader-host>:<port>/primary -w "%{http_code}"

这些端点适用于负载均衡器健康检查，将写操作仅路由到当前主库。

仅副本端点（仅 replica 返回 200）

# 仅流式副本
curl -s -u postgres:<pw> "http://<replica-host>:<port>/replica?replication_state=streaming"

# 延迟 < 1 MB 的副本
curl -s -u postgres:<pw> "http://<replica-host>:<port>/replica?lag=1048576"

只读端点（主库和副本均返回 200）

PostgreSQL 健康

Kubernetes 探针

# Kubernetes 探针示例
livenessProbe:
  httpGet:
    scheme: HTTP
    path: /liveness
    port: 8008          # REST API 端口
  initialDelaySeconds: 3
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

readinessProbe:
  httpGet:
    scheme: HTTP
    path: /readiness
    port: 8008
  initialDelaySeconds: 3
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

监控端点

GET /patroni

以 JSON 返回详细的节点状态。Patroni 在 leader 竞选期间内部调用，也供监控系统使用：

curl -s -u postgres:<pw> http://<host>:<port>/patroni | jq .

响应字段：

GET /cluster

返回完整的集群拓扑 —— 所有成员及其角色、状态和复制状态：

curl -s -u postgres:<pw> http://<host>:<port>/cluster | jq .

{
  "members": [
    {
      "name": "node1",
      "role": "leader",
      "state": "running",
      "api_url": "http://10.0.0.11:8008/patroni",
      "host": "10.0.0.11",
      "port": 35532,
      "timeline": 1
    },
    {
      "name": "node2",
      "role": "replica",
      "state": "streaming",
      "host": "10.0.0.11",
      "port": 35533,
      "timeline": 1,
      "receive_lag": 0,
      "receive_lsn": "0/3000168",
      "replay_lag": 0,
      "replay_lsn": "0/3000168"
    }
  ],
  "scope": "app-default"
}

GET /config

返回存储在 DCS 中的当前动态配置：

curl -s -u postgres:<pw> http://<host>:<port>/config | jq .

等同于 pg ha edit-config <scope> --show。

GET /history

返回时间线历史。未发生时间线切换时（新集群）为空数组 []。

GET /metrics

以 Prometheus 格式返回监控数据，供 Prometheus 或兼容系统抓取：

curl -s -u postgres:<pw> http://<host>:<port>/metrics

关键指标：

基于标签的过滤

健康检查端点接受查询参数，按成员 patroni.yml 的 tags 节中定义的自定义 标签过滤：

# 仅带 dc=us-east 标签的副本
curl -u postgres:<pw> "http://<host>:<port>/replica?dc=us-east"

# 仅带 region=primary 标签的 leader
curl -u postgres:<pw> "http://<host>:<port>/leader?region=primary"

实用模式

负载均衡器路由

由于 GET 健康检查无需认证，负载均衡器可以直接轮询 REST API 端点。模式 （源自 Patroni 官方 haproxy.cfg 示例）是：后端 TCP 端口是 PostgreSQL 端口，但健康检查 走 REST API 端口，用 GET /，仅 leader 返回 200。

单一读写入口（所有流量 → 当前 leader）：

global
    maxconn 100

defaults
    log global
    mode tcp
    retries 2
    timeout client 30m
    timeout connect 4s
    timeout server 30m
    timeout check 5s

listen stats
    mode http
    bind *:7000
    stats enable
    stats uri /

listen app
    bind *:5000
    option httpchk
    http-check expect status 200
    default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions
    server node1 <ip>:35532 maxconn 100 check port 8008
    server node2 <ip>:35533 maxconn 100 check port 8009

• check port 8008 / 8009 —— HTTP 健康检查走 REST API 端口，而非 PG 端口。
• GET / 仅在 leader 返回 200 → HAProxy 只把 leader 标记为 UP。
• on-marked-down shutdown-sessions —— 故障切换时，旧 leader 的连接被切断，客户端重连到新 leader。
• fall 3 / rise 2 配合 inter 3s —— 约 9 秒标记下线，约 6 秒标记上线。

读写分离 —— 再加一个用 GET /replica（仅 replica 返回 200）的 listener 承接读流量：

listen app_rw
    bind *:5000
    mode tcp
    option httpchk GET /
    http-check expect status 200
    default-server inter 3s fall 3 rise 2 on-marked-down shutdown-sessions
    server node1 <ip>:35532 maxconn 100 check port 8008
    server node2 <ip>:35533 maxconn 100 check port 8009

listen app_ro
    bind *:5001
    mode tcp
    option httpchk GET /replica
    http-check expect status 200
    default-server inter 3s fall 3 rise 2
    server node1 <ip>:35532 maxconn 100 check port 8008
    server node2 <ip>:35533 maxconn 100 check port 8009

• app_rw（:5000）—— GET / → 仅 leader 为 UP → 写操作落到 leader。
• app_ro（:5001）—— GET /replica → 仅 replica 为 UP → 读操作分摊到副本。

配合上文副本端点里的 GET /replica?lag=1MB，可把延迟过大的副本踢出读池。

curl 监控脚本

快速健康检查脚本：

#!/bin/bash
# 检查所有成员 —— GET 无需认证
for port in 8008 8009; do
  code=$(curl -s http://10.0.0.11:$port/health -o /dev/null -w "%{http_code}")
  echo "端口 $port: HTTP $code"
done

Prometheus 抓取配置

GET /metrics 无需认证，因此抓取配置不带凭据也能工作：

scrape_configs:
  - job_name: patroni
    static_configs:
      - targets:
        - '10.0.0.11:8008'   # node1
        - '10.0.0.11:8009'   # node2
    metrics_path: /metrics

13.4 - HA 集群扩展安装

在 Patroni 管理的 HA 集群中安装 PostgreSQL 扩展，与单节点实例有本质区别。 本页解释原因，并介绍 pg ha extension 命令子树。

为什么不能用 pg extension install？

单节点流程（pg extension install <instance> <ext>）的工作方式是：

1. 用 Pigsty 包构建 -ext 派生镜像
2. 停止并用新镜像重建容器
3. 编辑 postgresql.conf 设置 shared_preload_libraries
4. 在容器内执行 CREATE EXTENSION