PGEXT.CLOUD – 命令参考

命令：repo

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

pig repo 命令是一个综合性的软件包仓库管理工具。它提供了添加、移除、创建和管理软件仓库的功能，支持 RPM 系统（RHEL/CentOS/Rocky/Alma）和 Debian 系统（Debian/Ubuntu）。

pig repo - Manage Linux APT/YUM Repo

  pig repo list                    # available repo list             (info)
  pig repo info   [repo|module...] # show repo info                  (info)
  pig repo status                  # show current repo status        (info)
  pig repo add    [repo|module...] # add repo and modules            (root)
  pig repo rm     [repo|module...] # remove repo & modules           (root)
  pig repo update                  # update repo pkg cache           (root)
  pig repo create                  # create repo on current system   (root)
  pig repo boot                    # boot repo from offline package  (root)
  pig repo cache                   # cache repo as offline package   (root)

Examples:
  pig repo add -ru                 # add all repo and update cache (brute but effective)
  pig repo add pigsty -u           # gentle version, only add pigsty repo and update cache
  pig repo add node pgdg pigsty    # essential repo to install postgres packages
  pig repo add all                 # all = node + pgdg + pigsty
  pig repo add all extra           # extra module has non-free and some 3rd repo for certain extensions
  pig repo update                  # update repo cache
  pig repo create                  # update local repo /www/pigsty meta
  pig repo boot                    # extract /tmp/pkg.tgz to /www/pigsty
  pig repo cache                   # cache /www/pigsty into /tmp/pkg.tgz

命令	描述	备注
`repo list`	打印可用仓库与模块列表
`repo info`	获取仓库详细信息
`repo status`	显示当前仓库状态
`repo add`	添加新仓库	需要 sudo 或 root 权限
`repo set`	清空、覆盖并更新仓库	需要 sudo 或 root 权限
`repo rm`	移除仓库	需要 sudo 或 root 权限
`repo update`	更新仓库缓存	需要 sudo 或 root 权限
`repo create`	创建本地 YUM/APT 仓库	需要 sudo 或 root 权限
`repo cache`	从本地仓库创建离线包	需要 sudo 或 root 权限
`repo boot`	从离线包引导仓库	需要 sudo 或 root 权限
`repo reload`	刷新仓库目录

快速入门

# 方法 1：清理干净现有仓库，添加所有必要仓库并更新缓存（推荐）
pig repo add all --remove --update    # 移除旧仓库，添加所有必要仓库，更新缓存

# 方法 1 变体：一步到位
pig repo set                          # = pig repo add all --remove --update

# 方法 2：温和方式 - 仅添加所需仓库，保留你目前的仓库配置
pig repo add pgsql                    # 添加 PGDG 和 Pigsty PGSQL 仓库
pig repo add pigsty --region=china    # 添加 Pigsty 仓库，指定使用中国区域
pig repo add pgdg   --region=europe   # 添加 PGDG 仓库，指定使用欧洲区域
pig repo add pgdg   --mirror          # PGDG 优先使用腾讯云镜像
pig repo add infra  --region=default  # 添加 INFRA 仓库 ，指定使用默认区域

# 如果上面没有-u|--update 选项一步到位，请额外执行此命令
pig repo update                       # 更新系统包缓存

模块

在 pig 中，APT/YUM 仓库被组织为模块 —— 服务于特定目的的一组仓库。

模块	说明	仓库列表
`all`	安装 PG 所需的全部核心模块	`node` + `infra` + `pgsql`
`pgsql`	PGDG + Pigsty PG 扩展	`pigsty-pgsql` + `pgdg`
`pigsty`	Pigsty Infra + PGSQL 仓库	pigsty-infra, pigsty-pgsql
`pgdg`	PGDG 官方仓库	pgdg-common, pgdg14-18
`node`	Linux 系统仓库	base, updates, extras, epel, baseos, appstream…
`infra`	基础设施组件仓库	pigsty-infra, nginx, docker-ce
`docker`	Docker 仓库	docker-ce
`beta`	PostgreSQL 19 Beta 版本	pgdg19-beta, pgdg-beta
`extra`	PGDG Non-Free 与三方扩展	pgdg-extras, timescaledb, citus
`groonga`	PGroonga 仓库	groonga
`mssql`	Wiltondb 仓库（已弃用）	babelfish
`percona`	Percona PG + PG_TDE	percona
`llvm`	LLVM 工具链仓库	llvm
`kube`	Kubernetes 仓库	kubernetes
`grafana`	Grafana 仓库	grafana
`haproxy`	HAProxy 仓库	haproxyd, haproxyu
`redis`	Redis 仓库	redis
`mongo`	MongoDB 仓库	mongo
`mysql`	MySQL 仓库	mysql
`click`	ClickHouse 仓库	clickhouse
`gitlab`	GitLab 仓库	gitlab-ce, gitlab-ee

除此之外，pig 还自带了一些其他数据库的 APT/DNF 仓库：redis, kubernetes, grafana, clickhouse, gitlab, haproxy, mongodb, mysql，在此不再展开。

通常来说，为了安装 PostgreSQL node （Linux 系统仓库）和 pgsql（PGDG + Pigsty）是必选项，infra 仓库是可选项（包含了一些工具，IvorySQL Kernel 等）。您可以使用特殊的 all 模块，一次性添加所有需要的仓库到系统中，对绝大多数用户来说，这是合适的起点。

pig repo add all      # 添加 node,pgsql,infra 三个仓库到系统中
pig repo add          # 不添加任何参数时，默认使用 all 模块
pig repo set          # 使用 set 替代 add 时，将清理备份现有仓库定义并覆盖式更新

仓库定义

Pigsty 中可用仓库的完整定义位于 cli/repo/assets/repo.yml。

您可以创建 ~/.pig/repo.yml 文件，显式修改并覆盖 pig 的仓库定义。在编辑仓库定义文件时，您可以在 baseurl 处添加额外的区域镜像，例如指定中国，欧洲地区的镜像仓库 URL。当 pig 使用 --region 参数指定特定的区域时，pig 会优先查找对应区域的仓库 URL，如果不存在，则会 Fallback 到 default 的仓库 URL。

从 v1.7.0 起，repo add 或 repo set 指定 --mirror 时会明确选择内置的china 定义。PGDG 优先使用腾讯云，并保留定义中声明的 Pigsty 回退；其他模块使用各自维护中的中国区域 URL。pig 不再通过单独的运行时代理路由改写 PGDG URL。

普通 EL 仓库保留 DNF 原生模块过滤。只有显式声明 module_hotfixes=1 的定义（主要是 Pigsty 与 PGDG 仓库）会覆盖模块流；渲染 EL7 YUM 配置时会移除该键。

repo list

pig repo list 将列出当前系统可用的所有仓库模块。

pig repo list                # 列出当前系统可用仓库
pig repo list all            # 列出所有仓库（不过滤）

repo info

显示特定仓库或模块的详细信息，包括 URL、元数据和区域镜像，以及 .repo / .list 仓库文件内容。

pig repo info pgdg               # 显示 pgdg 模块的信息
pig repo info pigsty pgdg        # 显示多个模块的信息
pig repo info all                # 显示所有模块的信息

repo status

显示系统上的当前仓库配置。

pig repo status

repo add

添加仓库配置文件到系统。需要 root/sudo 权限。

pig repo add pgdg                # 添加 PGDG 仓库
pig repo add pgdg pigsty         # 添加多个仓库
pig repo add all                 # 添加所有必要仓库 (pgdg + pigsty + node)
pig repo add pigsty -u           # 添加并更新缓存
pig repo add all -r              # 添加前移除现有仓库
pig repo add all -ru             # 移除、添加并更新（完全重置）
pig repo add pgdg --region=china # 使用中国镜像
pig repo add pgdg -m             # 选择中国定义；PGDG 优先使用腾讯云

选项：

-r|--remove：添加新仓库前移除现有仓库
-u|--update：添加仓库后运行包缓存更新
--region <region>：使用区域镜像仓库（default / china / europe）
-m|--mirror：明确选择内置的 china 仓库定义

平台	模块位置
EL	`/etc/yum.repos.d/<module>.repo`
Debian	`/etc/apt/sources.list.d/<module>.list`

repo set

等同于 repo add --remove --update。清空现有仓库并设置新仓库，然后更新缓存。

pig repo set                     # 替换为默认仓库
pig repo set pgdg pigsty         # 替换为特定仓库并更新
pig repo set all --region=china  # 使用中国镜像
pig repo set -m                  # 明确选择内置的中国区域定义

repo rm

移除仓库配置文件并备份它们。

pig repo rm                      # 移除所有仓库
pig repo rm pgdg                 # 移除特定仓库
pig repo rm pgdg pigsty -u       # 移除并更新缓存

平台	备份位置
EL	`/etc/yum.repos.d/backup/`
Debian	`/etc/apt/sources.list.d/backup/`

repo update

更新包管理器缓存以反映仓库更改。

pig repo update                  # 更新包缓存

平台	等效命令
EL	`dnf makecache`
Debian	`apt update`

repo create

为离线安装创建本地包仓库。

pig repo create                  # Linux：/www/pigsty；macOS：当前目录
pig repo create /srv/repo        # 在自定义位置创建

当前实现会优先使用 PATH 中的 sow。在 Linux 上选择 SOW 后，会对每个目标目录以 sudo 执行等价命令：

sow create --pigsty --timeout 10m -- /absolute/repository/path

在 macOS 上必须安装 SOW，执行时不使用 sudo，默认目标为当前目录。Linux 上如果没有安装 sow，EL 会回退到 createrepo_c，Debian/Ubuntu 会回退到 dpkg-dev 提供的 dpkg-scanpackages；首选后端与平台回退均不可用时，pig repo create 才会失败。SOW 一旦被选中，其执行错误会直接返回，不会再用旧后端重试。10m 只限制等待 SOW 目录锁的时间，并不限制仓库索引本身的执行时间。

SOW 的 --pigsty 事务会：

只扫描顶层普通 .rpm 与 .deb 文件，不递归，也不跟随符号链接。
按解析后的软件包事实，删除 32 位 x86 包（RPM 的 i386/i486/i586/i686、DEB 的 i386），以及二进制包名恰为 patroni、上游版本恰为 3.0.4 的包。
以原子方式生成对应的 RPM/DEB 元数据，最后写入 repo_complete；marker 按 basename 排序，记录剩余顶层软件包的 SHA-256。

非软件包文件与目录不会被改动；候选软件包无法解析或逻辑坐标冲突时，SOW 事务会失败关闭。旧版回退脚本的清理与元数据语义不同，并在 repo_complete 中写入软件包的 MD5 列表。任一后端退出后，PIG 都会要求 repo_complete 存在且为普通文件，但不会校验 marker 内容或其中哈希。若交付流程把 marker 当作放行条件，调用方应自行完成这些验证。

repo cache

创建仓库内容的压缩 tarball 用于离线分发。

pig repo cache                   # 默认：/www 到 /tmp/pkg.tgz
pig repo cache -d /srv           # 自定义源目录

选项：

-d, --dir：源目录（默认：/www/）
-p, --path：输出路径（默认：/tmp/pkg.tgz）

repo boot

从离线包解压并设置本地仓库。

pig repo boot                    # 默认：/tmp/pkg.tgz 到 /www
pig repo boot -p /mnt/pkg.tgz   # 自定义包路径
pig repo boot -d /srv           # 自定义目标目录

选项：

-p, --path：包路径（默认：/tmp/pkg.tgz）
-d, --dir：目标目录（默认：/www/）

repo reload

从 GitHub 刷新仓库元数据到最新版本。

pig repo reload                  # 刷新仓库目录

更新后的文件会放置于 ~/.pig/repo.yml 中。

CMD: ext

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

pig ext 命令是一个用于管理 PostgreSQL 扩展的全能工具。它允许用户搜索、安装、移除、更新和管理 PostgreSQL 扩展，甚至支持内核包的管理。

pig ext - Manage PostgreSQL Extensions

  pig repo add -ru             # add all repo and update cache (brute but effective)
  pig ext add pg18             # install optional postgresql 18 package
  pig ext list duck            # search extension in catalog
  pig ext scan -v 18           # scan installed extension for pg 18
  pig ext add pg_duckdb        # install certain postgresql extension

Examples:
  pig ext list    [query]      # list & search extension
  pig ext info    [ext...]     # get information of a specific extension
  pig ext status  [-v]         # show installed extension and pg status
  pig ext add     [ext...]     # install extension for current pg version
  pig ext rm      [ext...]     # remove extension for current pg version
  pig ext update  [ext...]     # update extension to the latest version
  pig ext import  [ext...]     # download extension to local repo
  pig ext link    [ext...]     # link postgres installation to path
  pig ext reload               # reload the latest extension catalog data

命令	描述	备注
`ext list`	搜索扩展
`ext info`	显示扩展详细信息
`ext avail`	显示扩展可用性矩阵
`ext status`	显示已安装的扩展
`ext scan`	扫描已安装的扩展
`ext add`	安装扩展	需要 sudo 或 root 权限
`ext rm`	移除扩展	需要 sudo 或 root 权限
`ext update`	更新扩展	需要 sudo 或 root 权限
`ext import`	下载扩展以供离线使用	需要 sudo 或 root 权限
`ext link`	链接 PG 版本到 PATH	需要 sudo 或 root 权限
`ext reload`	刷新扩展目录

快速入门

在安装 PostgreSQL 扩展前，你需要先添加 pig repo add：

pig repo add pgdg pigsty -u    # 温和方式添加 pgdg 和 pigsty 仓库
pig repo set                   # 粗暴方式移除并添加所有所需仓库

然后你可以搜索并安装 PostgreSQL 扩展：

pig ext install pg_duckdb
pig ext install pg_partman
pig ext install pg_cron
pig ext install pg_repack
pig ext install pg_stat_statements
pig ext install pg_stat_kcache

可用扩展及其名称请查阅 扩展列表。

使用说明：

未指定 PostgreSQL 版本时，工具会尝试从 PATH 中的 pg_config 自动检测当前活动的 PostgreSQL 安装。
PostgreSQL 可通过主版本号（-v）或 pg_config 路径（-p）指定。
- 若指定 -v，pig 会使用该版本 PGDG 内核包的默认路径。
  - EL 发行版为 /usr/pgsql-$v/bin/pg_config，
  - DEB 发行版为 /usr/lib/postgresql/$v/bin/pg_config 等。
- 若指定 -p，则直接用该路径定位 PostgreSQL。
扩展管理器会根据操作系统自动适配不同的包格式：
- RHEL/CentOS/Rocky Linux/AlmaLinux 使用 RPM 包
- Debian/Ubuntu 使用 DEB 包
某些扩展可能有依赖项，安装时会自动解决。
谨慎使用 -y 参数，它会自动确认所有提示。

Pigsty 假定你已安装官方 PGDG 内核包，如未安装，可用如下命令：

pig ext install pg18          # 安装 PostgreSQL 18 内核（除 devel 包）

ext list

列出（或搜索）扩展目录中的可用扩展。

pig ext list                     # 列出所有扩展
pig ext list duck                # 搜索包含 "duck" 的扩展
pig ext list -v 18               # 按 PG 版本筛选
pig ext ls olap                  # 列出 olap 类别扩展
pig ext ls gis -v 16             # 列出 PG 16 的 GIS 类扩展
pig ext ls rag                   # 列出 RAG 类别扩展

分类筛选通过查询参数直接指定分类名实现，支持的分类包括：time, gis, rag, fts, olap, feat, lang, type, func, util, admin, stat, sec, fdw, sim, etl。

选项：

-v|--version：按 PG 版本筛选
--pkg：显示包名而非扩展名，仅列出主导扩展

Status 列说明：

installed：扩展已安装（绿色）
available：扩展可用但未安装（黄色）
not avail：扩展在当前系统不可用（红色）

默认扩展目录定义在 cli/ext/assets/extension.csv。

可用 pig ext reload 命令更新到最新扩展目录，数据将下载到 ~/.pig/extension.csv；在线最新版目录同步发布于 pigsty.io/ext/data/extension.csv。

ext info

显示指定扩展的详细信息。

pig ext info postgis        # 显示 PostGIS 详细信息
pig ext info timescaledb    # 显示 TimescaleDB 信息
pig ext info vector postgis # 显示多个扩展信息

ext avail

显示扩展的可用性矩阵，展示扩展在不同操作系统、架构和 PostgreSQL 版本上的可用情况。

pig ext avail                     # 显示当前系统上所有包的可用性
pig ext avail timescaledb         # 显示 timescaledb 的可用性矩阵
pig ext avail postgis pg_duckdb   # 显示多个扩展的可用性
pig ext av pgvector               # 显示 pgvector 的可用性
pig ext matrix citus              # avail 命令的别名

可用性矩阵会显示扩展在各个操作系统（EL8/9/10, Debian 12/13, Ubuntu 22/24/26）、架构（x86_64/aarch64）和 PostgreSQL 版本（14-18）上的可用情况。

ext status

显示当前 PostgreSQL 实例已安装扩展的状态。

pig ext status              # 显示已安装扩展
pig ext status -c           # 包含 contrib 扩展
pig ext status -v 16        # 显示 PG 16 已安装扩展

选项：

-c|--contrib：结果中包含 contrib 扩展

ext scan

扫描当前 PostgreSQL 实例已安装的扩展。

pig ext scan [-v version]

该命令会扫描 postgres 扩展目录，查找所有实际已安装的扩展。

ext add

安装一个或多个 PostgreSQL 扩展。pig ext add 的同级别名包括 pig ext install、pig ext ins 与 pig ext a。顶层 pig install 是另一个原生包管理器包装命令，也支持 PostgreSQL 与扩展包 alias 翻译。

pig ext add pg_duckdb            # 安装 pg_duckdb
pig ext add pg_duckdb -v 18      # 为 PG 18 安装
pig ext add pg_duckdb -y         # 自动确认安装
pig ext add vector postgis       # 安装多个扩展
pig ext add postgis --plan       # 预览安装计划，不执行

# 使用别名
pig install pg_duckdb
pig install pg_duckdb -v 18 -y

# 安装 PostgreSQL 内核
pig ext install pgsql            # 安装最新版 postgresql 内核
pig ext a pg18                   # 安装 postgresql 18 内核包
pig ext ins pg16                 # 安装 postgresql 16 内核包
pig ext install pg15-core        # 安装 postgresql 15 核心包
pig ext install pg14-main -y     # 安装 pg 14 + 常用扩展（vector, repack, wal2json）

选项：

-v|--version：指定 PG 大版本
-y|--yes：自动确认安装
--plan：预览安装计划，不执行包管理器命令

ext rm

移除一个或多个 PostgreSQL 扩展。

pig ext rm pg_duckdb             # 移除 pg_duckdb
pig ext rm pg_duckdb -v 18       # 移除 PG 18 版本
pig ext rm pgvector -y           # 自动确认移除
pig ext rm pgvector --plan       # 预览移除计划，不执行

选项：

-v|--version：指定 PG 大版本
-y|--yes：自动确认移除
--plan：预览移除计划，不执行包管理器命令

ext update

将指定的已安装扩展更新到最新版。出于安全考虑，无参数 pig ext update 不会更新所有扩展，而是 no-op；必须显式写出要更新的目标。

pig ext update                   # no-op：必须显式指定目标
pig ext update pg_duckdb         # 更新特定扩展
pig ext update postgis timescaledb  # 更新多个扩展
pig ext update pg_duckdb -y      # 自动确认更新
pig ext update pg_duckdb -m      # 先从镜像刷新目录再更新

选项：

-v|--version：指定 PG 大版本
-y|--yes：自动确认更新
-m|--mirror：更新前从 pigsty.cc 镜像重新加载扩展目录

ext import

下载扩展包到本地仓库，便于离线安装。

pig ext import postgis                # 导入 PostGIS 包
pig ext import timescaledb pg_cron    # 导入多个扩展包
pig ext import pg16                   # 导入 PostgreSQL 16 包
pig ext import pgsql-common           # 导入常用工具包
pig ext import -d /www/pigsty postgis # 指定路径导入

选项：

-d|--repo：指定仓库目录（默认：/www/pigsty）

ext link

将指定 PG 版本链接到系统 PATH。

pig ext link 18                  # 链接 PG 18 到 PATH
pig ext link 16                  # 链接 PG 16 到 /usr/pgsql
pig ext link /usr/pgsql-16       # 从指定路径链接到 /usr/pgsql
pig ext link polar               # 从 /usr/polar-17 链接 PolarDB 17
pig ext link null                # 取消当前 PostgreSQL 链接
pig ext link none                # null / none / nil / nop / no 均可取消链接

该命令会创建 /usr/pgsql 软链接，并写入 /etc/profile.d/pgsql.sh。

ext reload

刷新扩展元数据。

pig ext reload                   # 刷新扩展目录

更新后的文件会放置于 ~/.pig/extension.csv 中。

CMD: sty

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

pig 也可作为 Pigsty 的命令行工具使用 —— 这是一款开箱即用的免费 PostgreSQL RDS 解决方案。它为你的 PostgreSQL 集群带来高可用（HA）、PITR、监控、基础设施即代码（IaC）以及丰富的扩展支持。

pig sty - Init (Download), Bootstrap, Configure, and Deploy Pigsty

  pig sty init    [-mpfvd]        # install pigsty (~/pigsty by default)
  pig sty boot    [-rmpk]         # native controller bootstrap
  pig sty conf    [mode] [flags]  # native Inventory-aware configuration
  pig sty deploy                  # use pigsty to deploy everything (CAUTION!)
  pig sty get                     # download pigsty source tarball
  pig sty list                    # list available pigsty versions
  pig sty grafana <verb>          # manage grafana dashboards (native HTTP)

Examples:
  pig sty init                 # extract and init ~/pigsty
  pig sty boot                 # install ansible & other deps
  pig sty conf                 # generate pigsty.yml config file
  pig sty deploy               # run the deploy.yml playbook

命令	描述	备注
`sty init`	安装 Pigsty
`sty boot`	原生引导 Pigsty 控制节点	需要时自动提权至 root
`sty conf`	原生生成并校验 Inventory	Go 工作流
`sty deploy`	运行部署 playbook
`sty list`	列出可用 Pigsty 版本
`sty get`	下载 Pigsty 源码压缩包
`sty grafana`	管理 Grafana 仪表盘（别名 `gf`）	v1.6.0 新增

v1.8.0 起，pig sty boot 与 pig sty conf 均由 Go 原生实现，不再调用 Pigsty 旧版 bootstrap / configure Shell 脚本。v1.6.0 起，原先的pig sty edit / validate / check 已上移为根级pig inventory 命令组；实验性的 pig sty dashboard 由pig sty grafana 取代。

快速入门

你可以使用 pig sty 子命令在当前节点引导部署 Pigsty。

pig sty boot                     # 准备控制节点；需要时自动提权
pig sty conf -g                  # 生成并校验 pigsty.yml
pig inventory edit              # 可选：检查并调整 Inventory
pig sty deploy                   # 运行部署 playbook

详细入门指南请参阅：https://pigsty.cc/docs/setup/install/

sty boot 会以尽力而为的方式初始化缺失的默认 ~/pigsty 目录。若需要指定 Pigsty 版本或安装路径，请先显式执行 pig sty init。

sty init

下载并安装 Pigsty 发行版到 ~/pigsty 目录。

pig sty init                   # 使用最新版本安装到 ~/pigsty
pig sty init -f                # 安装并覆盖已有 pigsty 目录
pig sty init -m                # 优先从 pigsty.cc 镜像下载安装包
pig sty init -p /tmp/pigsty    # 安装到指定目录 /tmp/pigsty
pig sty init -v 3.4            # 获取并安装指定版本 v3.4.1
pig sty init 3                 # 获取并安装指定主版本 v3 最新

选项：

-p|--path：目标安装目录（默认 “~/pigsty”）
-f|--force：强制覆盖已存在的 pigsty 目录
-m|--mirror：优先使用 pigsty.cc 镜像源
-v|--version：pigsty 版本号
-d|--dir：下载目录（默认 “/tmp”）

sty boot

使用 Go 原生工作流引导 Pigsty 控制节点。该命令能够准备可用的 Ansible 环境、处理在线与离线仓库、修复常见控制节点前置条件，并返回结构化结果；整个过程不再委托给 Pigsty 旧版bootstrap 脚本，下载与解压软件包也不依赖 curl、wget、tar 或 gzip。

sudo pig sty boot                         # 使用默认区域在线引导
sudo pig sty boot -r china                # 使用中国区域仓库
sudo pig sty boot -m                      # 等价于 --region china
sudo pig sty boot -k                      # 保留现有仓库定义
sudo pig sty boot -p /path/to/pkg.tgz     # 使用显式离线包
sudo pig sty boot -p https://host/pkg.tgz # 下载并使用离线包
sudo pig sty boot -o json                 # 返回机器可读的结果与告警

命令可以不带 sudo 直接调用：Pig 会先解析并下载显式来源，需要 root 权限时再通过 sudo 进行一次自重启。设置 PIG_NO_SUDO=1 可禁用自动提权；设置 PIG_NON_INTERACTIVE=1 可让 sudo 使用非交互模式。

引导阶段

原生工作流依次完成：

在 Debian 12/13 上尽可能检查并修复 en_US.UTF-8，避免 Ansible 因继承到坏 locale 而无法启动。
实际执行 ansible-playbook，发现它使用的 Python 解释器，并校验 yaml、jmespath，以及 cryptography 或 OpenSSL 两者之一；仅有二进制文件但无法运行，不会被判定为就绪。
解析仓库来源，按需准备离线内容，并且只在 Ansible 缺失或不可用时安装精简的控制节点软件包集。
安装后再次校验 Ansible；如果新软件包补齐了 locale 工具，也会重试 locale 准备。
探测控制节点辅助工具，为发起调用的管理员用户修复到 127.0.0.1 的密钥 SSH，并尽可能初始化缺失的默认 ~/pigsty 目录。

即使 Ansible 已经可用，显式指定、自动发现或已经提交的离线来源仍会被准备，因此可以在一个已经就绪的控制节点上使用 sty boot 预置离线仓库。

来源选择与工作模式

结果中会记录以下四种引导模式之一：

模式	含义
`ready`	Ansible 已经可用，也不需要准备离线来源。
`offline`	选择了显式、可信自动发现或已提交的离线仓库。
`online`	配置所选区域的在线仓库以修复控制节点。
`existing`	使用 `--keep` 在线刷新失败后，成功回退到现有仓库定义。

来源优先级与安全规则是确定的：

--path 接受本地归档或 HTTP(S) URL。包含凭据的 URL 会被拒绝；显式来源无效时直接失败，不会悄悄回退到在线模式。
自动发现的 /tmp/pkg.tgz 必须是普通文件，不可被组或其他用户写入，且属主为 root 或发起 sudo 的用户；不安全的候选会被忽略并产生告警。
已完整提交的 /www/pigsty 仓库优先于选中的离线包；两者同时存在时复用现有仓库，离线包保持不动并给出告警。
Pig 使用 Go 原生能力下载并解压归档。如果 /www 不存在，会先创建 /data/nginx 与预期的/www -> /data/nginx 符号链接，再提交仓库内容。

离线模式只启用严格的 pigsty-local 仓库；在线模式配置所选区域，安装 Pigsty 内嵌签名密钥并启用仓库签名校验，同时安装 node 与 pigsty 控制节点模块。

仓库事务与失败边界

默认策略会在替换仓库定义前创建备份。仓库配置或软件包安装失败时，Pig 会尝试恢复备份，并在结果中明确标记回滚成功或失败。--keep 会切换为增量策略：保留现有定义，在线刷新失败时可以回退到已有仓库，也不需要执行替换回滚。

显式来源无效、需要安装时软件包管理器不受支持、仓库或软件包操作失败，以及安装后 Ansible 仍不可用，都会让命令失败。locale 修复、可选辅助工具探测、本机 SSH 修复与 Pigsty 目录初始化属于建议性收尾步骤；失败只会作为告警保留，不会否定已经可用的控制节点。

选项：

-r|--region：区域（default, china, europe…）
-m|--mirror：等价于 --region china；不能与 --region 同时使用
-p|--path：离线包文件或 HTTP(S) URL；显式指定的来源无效时直接失败
-k|--keep：保留现有仓库定义，不执行替换

结构化输出

自动化场景可使用全局 -o json 或 -o yaml。结果类型为 pig.sty.boot/v2，包含 Ansible 状态、工作模式与软件包管理器、仓库策略与回滚结果、来源与仓库路径、locale、本机 SSH 与 Pigsty 目录初始化状态、是否发生变更、告警，以及以下后续建议：

pig sty conf -g
pig inv edit
pig sty deploy

结构化模式会抑制动态进度信息，保证 stdout 可以直接被程序解析。

详见：https://pigsty.cc/docs/setup/offline/#bootstrap

sty conf

使用 Go 原生工作流生成 Pigsty Inventory。sty conf 从 <PIGSTY_HOME>/conf 下读取一个模板，执行有边界的结构化变更，校验完整候选配置，最后原子写入仅属主可读的 Inventory；它不会调用或回退到 ./configure。

pig sty conf                         # 使用 conf/meta.yml，写入 pigsty.yml
pig sty conf -g                      # 生成随机密码（推荐）
pig sty conf rich                    # 位置参数选择 conf/rich.yml
pig sty conf -c ha/full              # 等价的参数形式；不要与位置参数并用
pig sty conf ha/trio --ip 10.0.0.10,10.0.0.11,10.0.0.12
pig sty conf --domain infra.example.com
pig sty conf rich -v 18              # 为通用模板请求 PostgreSQL 18
pig sty conf -r china -s             # 中国区域、保留占位 IP、跳过管理员预检
pig sty conf -x                       # 写入代理环境变量
pig sty conf full -g -O ha.yml       # 写入自定义的仅属主可读文件
pig sty conf -n --ip 10.0.0.10 -o json

默认模式为 meta；pig sty c 与 pig sty configure 是命令别名。注意大写 -O 用于指定 Inventory 输出文件，全局小写 -o 用于选择 text、JSON 或 YAML 命令输出。

模板与输出安全

模式必须是 <PIGSTY_HOME>/conf 下用斜杠分隔的安全相对名称，.yml 后缀可省略；绝对路径、目录穿越、空路径段与路径逃逸都会被拒绝。
相对输出路径基于 <PIGSTY_HOME> 解析，绝对输出路径保持不变。
目标文件不能通过相同路径、已有符号链接、带符号链接的父目录或硬链接指回源模板；已有输出符号链接一律拒绝。
Pig 会先解析源模板并拒绝冲突的 IP 映射，再执行外部预检。解析、变更、预检或校验失败均不会改动目标文件。
成功结果以 0600 权限原子写入。

结构化变更

命令操作解析后的 YAML 结构与有边界的标量，而不是进行宽泛的文本替换：

输入	原生行为
`--ip A,B,...`	最多接收十个互不相同的地址，依次映射到 `10.10.10.10` 至 `10.10.10.19`；替换同时完成，因此地址互换安全，VIP 等无关地址保持不变。
未指定 `--ip`	探测本机网卡；候选不唯一时交互选择，`--non-interactive` 或 stdin 已关闭时则失败并提示使用 `--ip`。
`--domain NAME`	只替换精确的 `i.pigsty`，不会误改 `cli.pigsty` 或 `i.pigsty.cc`；NAME 必须是合法 DNS 域名。
小规格控制节点	探测到 CPU 少于四核时，将 `node_tune: oltp` 与 `pg_conf: oltp.yml` 改为对应的 `tiny` 配置。
`--region REGION`	非默认区域会更新 `all.vars.region`；`china` 还会启用模板中已有的 Docker 与 pip 镜像值，但不会凭空补造模板中不存在的配置。
`--proxy`	将非空的 `HTTP_PROXY`/`http_proxy`、`HTTPS_PROXY`（缺失时回退到 `ALL_PROXY`）、`ALL_PROXY` 与 `NO_PROXY` 写入 `all.vars.proxy_env`；必要时补充安全的默认 no-proxy 列表。
`--version MAJOR`	通用模板支持 PostgreSQL 14-18，以及显式指定的 19 beta，并选择匹配的 locale；版本固定的 `mssql`、`polar` 与 `pgNN` 模式保留模板版本并给出告警。
`--generate`	每个已知凭据标识符生成一个 24 位随机值，并一致替换其生效值和文档化占位符。

如果某个 IP 映射会与未替换的 Inventory 键冲突，命令会按无效参数拒绝执行。某个已提供地址在模板中没有对应占位槽时，不会被静默忽略，而是作为 discarded-IP 告警保留在结构化结果中。

指定 PostgreSQL 19 beta 时，如果模板包含预期的软件仓库列表，Pig 还会在 pgsql 后启用beta 仓库。conf/build/ 下的模式有意绕过 IP 映射与控制节点管理员预检，以保持构建模板可移植。

生效口令标识符包括 grafana_admin_password、pg_admin_password、pg_monitor_password、pg_replication_password、patroni_password、haproxy_admin_password、minio_secret_key 与 etcd_root_password。随机生成还覆盖文档中的DBUser.Meta、DBUser.Viewer、S3User.Backup、S3User.Meta、S3User.Data、DBUser.Supa 和 Vibe.Coding 占位符；同一标识符出现多次时会使用同一个生成值。

选项：

-c|--conf：模板模式，等价于位置参数 [mode]，两种形式不能同时使用
--ip：最多十个互不相同、逗号分隔的 IPv4 地址
--domain：将精确的 i.pigsty 占位符替换为合法 DNS 域名
-v|--version：PostgreSQL 主版本（18/17/16/15/14；19 beta 可显式指定）
-r|--region：上游仓库区域（default/china/europe）
-m|--mirror：等价于 --region china；不能与 --region 同时使用
-O|--output-file：输出配置文件路径（默认：pigsty.yml）
-s|--skip：保留占位 IP 并跳过管理员 SSH/sudo 预检；不能与 --ip 同时使用
-p|--port：SSH 端口
-x|--proxy：将非空代理环境变量写入 all.vars.proxy_env
-n|--non-interactive：IP 候选不唯一时拒绝猜测，不进入交互选择
-g|--generate：将已知演示口令替换为 24 位随机值

预检与校验

未使用 --skip 时，Pig 会检查内核、架构、软件包管理器、平台厂商、控制节点资源、sudo/管理员权限、本机 SSH 与 Ansible 可用性；SSH 检查使用 --port 指定的端口。在 Inventory 仍可安全生成时，这些诊断以可操作告警返回；无效参数与不安全的配置变换仍然是错误。

渲染候选必须通过 Pig 原生 Inventory 校验；如果存在 ansible-inventory，还会在提交文件前执行一次有时间边界的外部解析。--skip 会保留占位 IP，并跳过管理员 SSH/sudo 预检，但不会禁用模板解析、安全变更、Inventory 校验或原子写入。

结构化输出

使用全局 -o json 或 -o yaml 时，结果类型为 pig.sty.configure/v1，会报告模式、源模板与输出路径、区域、所选主地址、已应用与被丢弃的 IP、域名、SSH 端口、请求与实际 PostgreSQL 版本、原生工作流标记、生成的机密标识符及告警。随机口令值绝不会输出。

详见：https://pigsty.cc/docs/setup/install/#配置

sty deploy

使用 deploy.yml 剧本部署 Pigsty。

pig sty deploy       # 执行 deploy.yml（如果找不到则使用 install.yml）
pig sty d            # 短别名
pig sty de           # 短别名

此命令从您的 Pigsty 安装目录执行 deploy.yml 剧本。为保持向后兼容性，如果 deploy.yml 不存在但 install.yml 存在，将使用 install.yml 代替。

警告：此操作会修改您的系统，且 调用即执行——deploy 不设 --yes 确认门，误触发时请用 Ctrl+C 中断。（v1.6.0 起 pig sty install / ins 别名已移除。）

sty list

列出可用的 Pigsty 版本。

pig sty list                     # 列出可用版本

sty get

下载 Pigsty 源码压缩包。

pig sty get                      # 下载最新版本
pig sty get v3.4.0               # 下载指定版本
pig sty get -m                   # 优先使用 pigsty.cc 镜像

sty grafana

自 v1.6.0 起，pig sty grafana（别名 gf）通过 Grafana 原生 HTTP API 管理仪表盘，取代了实验性的 pig sty dashboard。PATH 参数可以指向 grafana 根目录、单个文件夹或单个仪表盘 JSON 文件；缺省时解析 <PIGSTY_HOME>/files/grafana，不会回退到当前目录。

pig sty grafana info             # 检查 Grafana 健康、认证与基本信息
pig sty grafana list             # 列出当前组织的全部仪表盘
pig sty grafana boot             # 围绕现有 pigsty 仪表盘引导 Grafana
pig sty grafana init             # 加载完整仪表盘集，然后引导 Grafana
pig sty grafana load [PATH]      # 按本地路径加载仪表盘
pig sty grafana dump [PATH]      # 导出远端仪表盘到本地路径
pig sty grafana clean [PATH]     # 删除本地路径对应的远端仪表盘（--dry-run/--yes）
pig sty grafana lang zh-Hans     # 设置组织与当前用户语言
pig sty grafana style            # 设置组织与当前用户界面风格

连接与凭据：

参数	说明
`--endpoint`	Grafana 地址与路径前缀（默认 `http://i.pigsty/ui`）
`--username`	Grafana API 用户名
`--password`	Grafana API 密码（不安全：对进程列表与 shell 历史可见）
`--password-file`	仅属主可读的密码文件（推荐）

密码解析顺序：--password → --password-file → GRAFANA_PASSWORD 环境变量 → Inventory 中的 all.vars.grafana_admin_password。 HTTP 客户端带有超时与响应大小限制，并拒绝重定向；TLS 证书默认校验。

传统仪表盘与 schema v2 资源

load 与 init 同时接受传统 Grafana 仪表盘 JSON，以及具有以下精确身份的资源格式：

{"apiVersion":"dashboard.grafana.app/v2","kind":"Dashboard","metadata":{"name":"pgsql-overview","namespace":"default"},"spec":{}}

加载时，PIG 不会把两种格式悄悄压平为同一种：

传统 JSON 从顶层 uid 取得身份，并调用旧版 dashboard API。
Schema v2 从 metadata.name 取得 UID；缺少 namespace 时默认使用 default，spec 必须是对象，并通过 Grafana dashboard resource API 写入。
JSON 文件名去掉 .json 后必须与解析出的 UID 一致。本地目录只允许一层文件夹，其目录名会成为 Grafana folder UID。
对 schema v2，PIG 保留 spec 与 grafana.app/message 注解，根据本地文件夹写入 grafana.app/folder，并在 upsert 前主动去掉由服务端管理的 metadata/status。
dump 只有在目标文件已经以 v2 形式存在时才保持 schema v2；此时会使用该文件的 namespace 拉取原生 v2 资源。全新导出目标默认写成传统 JSON；仅存在于本地的文件不会被 dump 删除。

其他 dashboard.grafana.app/* 版本或结构不完整的资源封装会被直接拒绝，不会被静默当成传统仪表盘。因此，要往返保持 v2 格式，必须保留已有的本地 v2 文件作为格式契约。

pig pg

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

pig pg 命令（别名 pig postgres）用于管理本地 PostgreSQL 服务器和数据库。它封装了 pg_ctl、psql、vacuumdb 等本地原语；集群级 Patroni 操作请使用 pig pt，编排式 PITR 请使用 pig pitr。

pig pg - Local PostgreSQL primitives (pg_ctl / psql / local files).

Server Control (via pg_ctl):
  pig pg init     [-v ver] [-D datadir]     initialize data directory
  pig pg start    [-D datadir]              start PostgreSQL server
  pig pg stop     [-D datadir] [-m fast]    stop PostgreSQL server
  pig pg restart  [-D datadir] [-m fast]    restart PostgreSQL server
  pig pg reload   [-D datadir]              reload configuration
  pig pg status   [-D datadir]              show server status
  pig pg promote  [-D datadir]              promote standby to primary
  pig pg role     [-D datadir] [-V]         detect instance role (primary/replica)

Service Management (via systemctl):
  pig pg svc start                          start postgres systemd service
  pig pg svc stop                           stop postgres systemd service
  pig pg svc restart                        restart postgres systemd service
  pig pg svc reload                         reload postgres systemd service
  pig pg svc status                         show postgres service status

Connection & Query:
  pig pg psql     [db] [-c cmd]             connect to database via psql
  pig pg ps       [-a] [-u user]            show current connections
  pig pg kill     [-x] [-u user]            terminate connections (dry-run by default)
  pig pg clone    <src> [dst]               clone database with CREATE DATABASE TEMPLATE

Database Maintenance:
  pig pg vacuum   [db] [-a] [-t table]      vacuum tables
  pig pg analyze  [db] [-a] [-t table]      analyze tables
  pig pg freeze   [db] [-a] [-t table]      vacuum freeze tables
  pig pg repack   [db] [-a] [-t table]      repack tables (online rebuild)

Tuning:
  pig pg tune     [-p profile]              generate optimized parameters

Instance Fork:
  pig pg fork init <name> [-D datadir]      fork PGDATA into /pg/data-<name>
  pig pg fork list                          list managed forks
  pig pg fork start|stop|rm <name>          manage fork lifecycle

Utilities:
  pig pg log <list|tail|cat|less|grep>      view PostgreSQL logs

命令概览

服务控制（pg_ctl 封装）：

命令	别名	描述	备注
`pg init`	`initdb, i`	初始化数据目录	封装 initdb
`pg start`	`boot, up`	启动 PostgreSQL	封装 pg_ctl start
`pg stop`	`halt, down`	停止 PostgreSQL	封装 pg_ctl stop
`pg restart`	`reboot`	重启 PostgreSQL	封装 pg_ctl restart
`pg reload`	`hup`	重载配置	封装 pg_ctl reload
`pg status`	`st, stat`	查看服务状态	显示进程与相关服务状态
`pg promote`	`pro`	提升备库为主库	封装 pg_ctl promote
`pg role`	`r`	检测实例角色	输出 primary/replica

连接与查询：

命令	别名	描述	备注
`pg psql`	`sql, connect`	连接到数据库	封装 psql
`pg ps`	`activity, act`	显示当前连接	查询 pg_stat_activity
`pg kill`	`k`	终止连接	默认 dry-run 模式
`pg clone`		克隆单个数据库	`CREATE DATABASE ... TEMPLATE ... FILE_COPY`

数据库维护：

命令	别名	描述	备注
`pg vacuum`	`vac, vc`	清理表	封装 vacuumdb
`pg analyze`	`ana, az`	分析表	封装 vacuumdb –analyze-only
`pg freeze`		冻结清理表	封装 vacuumdb –freeze
`pg repack`	`rp`	在线重整表	需要 pg_repack 扩展

参数调优：

命令	别名	描述	备注
`pg tune`	`tuning`	生成 PostgreSQL 调优参数	自动探测硬件，支持结构化输出

实例 Fork：

命令	别名	描述	备注
`pg fork`		`fork init` 的便捷写法	默认创建托管 fork，不自动启动
`pg fork init`	`create`	创建本地一次性物理副本	默认 `/pg/data-<name>`
`pg fork list`		列出托管 fork	扫描 `/pg/data-*`
`pg fork start`		启动已有 fork	支持托管名或 `--dst-data` 非托管目录
`pg fork stop`		停止已有 fork	支持 shutdown mode
`pg fork rm`	`remove, delete`	删除 fork	运行中的 fork 需 `--stop`

日志工具：

命令	别名	描述	备注
`pg log`	`l`	日志管理	父命令
`pg log list`	`ls`	列出日志文件
`pg log tail`	`t, f`	实时查看日志	tail -f
`pg log show`	`cat, c`	输出日志内容
`pg log less`	`vi, v`	用 less 查看
`pg log grep`	`g, search`	搜索日志

服务子命令（pg svc，也可写作 pg service 或 pg s）：

命令	别名	描述
`pg svc start`	`boot, up`	启动 postgres 服务
`pg svc stop`	`halt, dn, down`	停止 postgres 服务
`pg svc restart`	`reboot, rt`	重启 postgres 服务
`pg svc reload`	`rl, hup`	重载 postgres 服务
`pg svc status`	`st, stat`	显示服务状态

快速入门

# 服务控制
pig pg init                       # 初始化数据目录
pig pg start                      # 启动 PostgreSQL
pig pg status                     # 查看状态
pig pg stop                       # 停止 PostgreSQL
pig pg restart                    # 重启 PostgreSQL
pig pg reload                     # 重载配置

# 连接与查询
pig pg psql                       # 连接到 postgres 数据库
pig pg psql mydb                  # 连接到指定数据库
pig pg ps                         # 查看当前连接
pig pg kill -x                    # 终止连接（需要 -x 确认执行）
pig pg clone meta meta_fork       # 克隆单个数据库

# 数据库维护
pig pg vacuum mydb                # 清理指定数据库
pig pg analyze mydb               # 分析指定数据库
pig pg repack mydb                # 在线重整数据库

# 参数调优
pig pg tune                       # 自动探测硬件并生成调优参数
pig pg tune -p olap               # 使用 OLAP 负载画像
pig pg tune -c 8 -m 32768 -d 500  # 手工覆盖 CPU / 内存 / 磁盘

# 实例 Fork
pig pg fork dev                   # 创建 /pg/data-dev
pig pg fork init dev --start      # 创建并启动 fork，自动分配高位端口
pig pg fork init dev -s --dst-port 15433  # 创建并在指定端口启动
pig pg fork list                  # 列出 /pg/data-* fork

# 日志查看
pig pg log tail                   # 实时查看最新日志
pig pg log list --log-dir /var/log/pg  # 使用自定义日志目录
pig pg log grep ERROR             # 搜索日志

全局参数

以下参数适用于所有 pig pg 子命令：

参数	简写	默认值	说明
`--version`	`-v`	自动检测	PostgreSQL 主版本号（形如 18，17）
`--data`	`-D`	`/pg/data`	数据目录路径
`--dbsu`	`-U`	`postgres`	数据库超级用户（或 `$PIG_DBSU` 环境变量）

版本检测逻辑：

如果指定了 -v，使用指定 PG 大版本
否则从数据目录的 PG_VERSION 文件读取版本
如果都无法获取，使用 PATH 中的默认 PostgreSQL 大版本

服务控制命令

pg init

初始化 PostgreSQL 数据目录，封装 initdb 命令。

校验和默认打开，除非使用 -K|--no-data-checksums 显式关闭
优先使用平台无关的 C.UTF-8 内置 Locale （PG 17 及以上版本），如果不支持则优先使用系统的 C.UTF-8 / C Locale，都不满足时使用系统默认 Locale。
如果数据目录已存在，命令会拒绝执行，除非使用 -f|--force 强制覆盖。如果数据目录上有 PostgreSQL 正在运行，即使使用 -f|--force，命令也会拒绝执行，以防止数据丢失
您可以使用 -- 追加额外参数给 initdb，例如 --waldir=/wal 指定 WAL 日志目录。但如果要覆盖 Locale / Encoding 等参数，建议直接使用 initdb 命令。

pig pg init                       # 使用默认设置初始化
pig pg init -v 18                 # 指定 PostgreSQL 18
pig pg init -D /data/pg18         # 指定数据目录
pig pg init -K                    # 关闭数据校验和
pig pg init -f                    # 强制初始化（删除已有数据）
pig pg init -- --waldir=/wal      # 传递额外参数给 initdb

选项：

参数	简写	默认值	说明
`--no-data-checksums`	`-K`	false	禁用数据校验和
`--force`	`-f`	false	强制初始化，删除已有数据（危险！）
`--yes`	`-y`	false	与 `--force` 配合时跳过覆盖确认提示

pg start

使用 pg_ctl start 命令启动 PostgreSQL 服务器。如果 PostgreSQL 由 Patroni 管理，建议使用 pig pt start 通过启动 patroni 的方式来启动。如果 PostgreSQL 由 Systemd 管理，可以使用 pig pg svc start 来启动服务。

pig pg start                      # 使用默认设置启动
pig pg up                         # 别名
pig pg start -D /data/pg18        # 指定数据目录
pig pg start -l /pg/log/pg.log    # 重定向输出到日志文件
pig pg start -O "-p 5433"         # 传递参数给 postgres
pig pg start -o json              # 结构化输出 JSON

选项：

参数	简写	说明
`--log`	`-l`	重定向 stdout/stderr 到日志文件
`--timeout`	`-t`	等待超时（秒）
`--no-wait`		不等待启动完成
`--options`	`-O`	传递给 postgres 的选项

如果 PostgreSQL 已经运行，命令会提示，并打印现有 Postmaster 进程 PID，不会报错。

pg stop

使用 pg_ctl stop 命令停止 PostgreSQL 服务器。

请注意如果 PostgreSQL 由 Patroni 管理，直接使用 pg_ctl stop 停止数据库可能会导致 Patroni 认为数据库异常退出，自动重启或触发自动故障转移。建议在 Patroni 管理的环境中使用 pig pt stop 或 pig pt svc stop 来停止 patroni ，从而停止 PostgreSQL。

pig pg stop                       # 快速停止（默认）
pig pg down                       # 别名
pig pg halt                       # 别名
pig pg stop -m smart              # 等待客户端断开
pig pg stop -m immediate          # 立即关闭
pig pg stop --plan                # 预览停止计划

选项：

参数	简写	默认值	说明
`--mode`	`-m`	fast	关闭模式：smart/fast/immediate
`--timeout`	`-t`	60	等待超时（秒）
`--no-wait`		false	不等待关闭完成
`--plan`		false	只预览本地 `pg_ctl stop` 计划，不执行

关闭模式说明：

模式	说明
`smart`	等待所有客户端断开后关闭
`fast`	回滚活动事务，断开客户端，正常关闭
`immediate`	立即终止所有进程，下次启动需要恢复

pg restart

使用 pg_ctl restart 重启 PostgreSQL 服务器。

pig pg restart                    # 快速重启
pig pg reboot                     # 别名
pig pg restart -m immediate       # 立即重启
pig pg restart -O "-p 5433"       # 使用新选项重启
pig pg restart --plan             # 预览重启计划

选项： 与 pg stop 相同，另外支持 --options（-O）传递给 postgres。

pg reload

使用 pg_ctl reload 重载 PostgreSQL 配置。向服务器发送 SIGHUP 信号。

pig pg reload                     # 重载配置
pig pg hup                        # 别名
pig pg reload -D /data/pg18       # 指定数据目录

pg status

显示 PostgreSQL 服务器状态。此命令不仅显示 pg_ctl status 的结果，还会显示 postgres 相关进程和 Pigsty 相关服务的状态。

pig pg status                     # 查看服务状态
pig pg st                         # 别名
pig pg status -D /data/pg18       # 指定数据目录

输出内容：

pg_ctl status 输出（进程是否运行、PID 等）
PostgreSQL 进程列表（ps -u postgres）
相关服务状态：
- postgres：PostgreSQL systemd 服务
- patroni：Patroni HA 管理服务
- pgbouncer：连接池服务
- pgbackrest：备份服务
- vip-manager：VIP 管理服务
- haproxy：负载均衡服务

pg promote

使用 pg_ctl promote 命令将备库提升为主库。

pig pg promote                    # 提升备库
pig pg promote -D /data/pg18      # 指定数据目录
pig pg promote --plan             # 预览提升计划
pig pg promote -y                 # 跳过确认提示

选项：

参数	简写	说明
`--timeout`	`-t`	等待超时（秒）
`--no-wait`		不等待提升完成
`--plan`		仅预览提升计划
`--yes`	`-y`	跳过确认提示

pg role

检测 PostgreSQL 实例的角色（主库或备库）。

pig pg role                       # 输出：primary、replica 或 unknown
pig pg role -V                    # 详细输出，显示检测过程
pig pg role -D /data/pg18         # 指定数据目录

选项：

参数	简写	说明
`--verbose`	`-V`	显示详细检测过程

输出说明：

primary：当前实例为主库
replica：当前实例为备库
unknown：无法确定实例角色

检测策略（按优先级）：

进程检测：检查 walreceiver、recovery 等进程
SQL 查询：执行 pg_is_in_recovery() 查询（需要 PostgreSQL 运行）
数据目录检查：检查 standby.signal、recovery.signal、recovery.conf 文件

连接与查询命令

pg psql

通过 psql 连接到 PostgreSQL 数据库。

pig pg psql                       # 连接到 postgres 数据库
pig pg psql mydb                  # 连接到指定数据库
pig pg psql mydb -c "SELECT 1"    # 执行单条命令
pig pg psql -f script.sql         # 执行 SQL 脚本文件

选项：

参数	简写	说明
`--command`	`-c`	执行单条 SQL 命令
`--file`	`-f`	执行 SQL 脚本文件

如果指定全局 -D/--data，pg psql 会以数据库超级用户读取该数据目录下的 postmaster.pid，并使用其中记录的端口和 Unix socket 目录连接该实例。若无法读取或解析 postmaster 信息，命令会直接失败，而不是静默连接到默认实例。

pg ps

显示 PostgreSQL 当前连接。查询 pg_stat_activity 视图。

pig pg ps                         # 显示客户端连接
pig pg ps -a                      # 显示所有连接（包括系统进程）
pig pg ps -u dbuser_monitor       # 按用户筛选
pig pg ps -d meta                 # 按数据库筛选

选项：

参数	简写	说明
`--all`	`-a`	显示所有连接（包括系统进程）
`--user`	`-u`	按用户筛选
`--database`	`-d`	按数据库筛选

pg kill

终止 PostgreSQL 连接。默认为 dry-run 模式，需要 -x 参数才会实际执行。

pig pg kill                       # 显示将被终止的连接（dry-run）
pig pg kill -x                    # 实际终止连接
pig pg kill --pid 12345 -x        # 终止指定 PID
pig pg kill -u admin -x           # 终止指定用户的连接
pig pg kill -d mydb -x            # 终止指定数据库的连接
pig pg kill -s idle -x            # 终止空闲连接
pig pg kill --cancel -x           # 取消查询而非终止连接
pig pg kill --watch 5 -x           # 每 5 秒重复执行
pig pg kill --plan                # 预览终止连接计划

选项：

参数	简写	说明
`--execute`	`-x`	实际执行（默认为 dry-run）
`--pid`		终止指定 PID
`--user`	`-u`	按用户筛选
`--database`	`-d`	按数据库筛选
`--state`	`-s`	按状态筛选（idle/active/idle in transaction）
`--query`	`-q`	按查询模式筛选
`--all`	`-a`	包括复制连接
`--cancel`	`-c`	取消查询而非终止连接
`--watch`		每 N 秒重复执行
`--plan`		预览执行计划，不终止连接

安全说明： --state 和 --query 参数会进行标识符验证，只接受简单的字母数字模式，以防止 SQL 注入。

pg clone

克隆数据库集群中的一个数据库，对于 PG 18 及以上版本优先使用 CoW 原地瞬间克隆

在当前 PostgreSQL 实例内克隆一个数据库。该命令封装 CREATE DATABASE ... TEMPLATE ... STRATEGY FILE_COPY，并会在克隆前终止源数据库上的现有会话，语义与 Pigsty 的 pgsql-db clone 工作流一致。

pig pg clone meta                       # 克隆 meta 为 meta_1/meta_2/...
pig pg clone meta meta_fork             # 克隆为指定数据库名
pig pg clone meta meta_fork --owner dba # 尝试修改新库 owner
pig pg clone meta meta_fork --port 5433 # 连接指定本地端口
pig pg clone meta meta_fork --plan      # 预览克隆计划

选项：

参数	简写	说明
`--port`		PostgreSQL 端口（默认 `5432` 或 `$PG_PORT`）
`--conn-db`		执行 `CREATE DATABASE` 的连接库，克隆 `postgres` 时默认 `template1`
`--owner`		克隆后尝试修改新库 owner
`--conn-limit`		新库连接数限制（`-1` 无限制，`0` 禁止连接）
`--plan`		仅显示执行计划
`--yes`	`-y`	跳过确认提示

说明： PostgreSQL 18+ 且 file_copy_method=clone 可用时，数据库克隆可使用 CoW 语义；否则会退化为普通文件复制。该命令克隆的是单个数据库逻辑对象，不会创建新的 PostgreSQL 实例。

数据库维护命令

pg vacuum

清理数据库表。封装 vacuumdb 命令。

pig pg vacuum                     # 清理当前数据库
pig pg vac                        # 别名
pig pg vacuum mydb                # 清理指定数据库
pig pg vacuum -a                  # 清理所有数据库
pig pg vacuum mydb -t mytable     # 清理指定表
pig pg vacuum mydb --schema myschema  # 清理指定 schema 中的表
pig pg vacuum mydb --full         # VACUUM FULL（需要排他锁）

选项：

参数	简写	说明
`--all`	`-a`	处理所有数据库
`--schema`		指定 schema
`--table`	`-t`	指定表名
`--verbose`	`-V`	详细输出
`--full`	`-F`	VACUUM FULL（需要排他锁）

安全说明： --schema 和 --table 参数会进行标识符验证，只接受有效的 PostgreSQL 标识符格式。

pg analyze

分析数据库表以更新统计信息。

pig pg analyze                    # 分析当前数据库
pig pg ana                        # 别名
pig pg analyze mydb               # 分析指定数据库
pig pg analyze -a                 # 分析所有数据库
pig pg analyze mydb -t mytable    # 分析指定表

选项：

参数	简写	说明
`--all`	`-a`	处理所有数据库
`--schema`		指定 schema
`--table`	`-t`	指定表名
`--verbose`	`-V`	详细输出

pg freeze

对数据库表执行冻结清理（vacuum freeze），防止事务 ID 回卷。

pig pg freeze                     # 冻结清理当前数据库
pig pg freeze mydb                # 冻结清理指定数据库
pig pg freeze -a                  # 冻结清理所有数据库
pig pg freeze mydb -t mytable     # 冻结清理指定表

选项： 与 pg vacuum 相同（不含 --full）。

pg repack

在线重整数据库表。需要安装 pg_repack 扩展。

pig pg repack mydb                # 重整数据库中所有表
pig pg rp mydb                    # 别名
pig pg repack -a                  # 重整所有数据库
pig pg repack mydb -t mytable     # 重整指定表
pig pg repack mydb --schema myschema  # 重整指定 schema 中的表
pig pg repack mydb -j 4           # 使用 4 个并行任务
pig pg repack mydb --plan         # 显示将被重整的表

选项：

参数	简写	说明
`--all`	`-a`	处理所有数据库
`--schema`		指定 schema
`--table`	`-t`	指定表名
`--verbose`	`-V`	详细输出
`--jobs`	`-j`	并行任务数（默认 1）
`--plan`		显示将被重整的表

参数调优命令

pg tune

根据当前 PostgreSQL 主版本、主机硬件资源和工作负载画像，生成一组推荐的 PostgreSQL 参数。默认自动探测 CPU、内存与数据盘容量，并以文本形式输出配置项。

pig pg tune                       # 自动探测硬件，使用 oltp 画像
pig pg tuning                     # 别名
pig pg tune -p olap               # 使用 OLAP 画像
pig pg tune -p tiny               # 小规格实例
pig pg tune -c 8 -m 32768 -d 500  # 覆盖自动探测结果
pig pg tune -C 500                # 覆盖 max_connections
pig pg tune -R 0.30               # 调整 shared_buffers 比例
pig pg tune -o json               # 结构化输出 JSON
pig pg tune -o yaml               # 结构化输出 YAML

选项：

参数	简写	默认值	说明
`--profile`	`-p`	oltp	调优画像：`oltp` / `olap` / `tiny` / `crit`
`--cpu`	`-c`	0	CPU 核数，0 表示自动探测
`--mem`	`-m`	0	内存大小（MB），0 表示自动探测
`--disk`	`-d`	0	数据盘容量（GB），0 表示自动探测
`--max-conn`	`-C`	0	覆盖 `max_connections`，0 表示使用画像默认值
`--shmem-ratio`	`-R`	0.25	`shared_buffers` 占内存比例，取值范围 `0.1 ~ 0.4`

画像说明：

画像	适用场景	特点
`oltp`	通用在线事务处理	平衡连接数、缓存与并行度
`olap`	分析型负载	更激进地使用并行与工作内存
`tiny`	小规格实例	控制内存占用与并行度
`crit`	延迟敏感场景	限制并行 gather，偏向稳态响应

说明：

生成结果会随当前 PostgreSQL 主版本自动裁剪，例如 io_workers 仅会在 PG 18+ 输出。
文本输出可直接重定向到配置片段，结构化输出适合自动化脚本消费。
该命令当前生成建议参数，不会直接修改数据库配置文件。

实例 Fork

pg fork

创建一个本地一次性 PostgreSQL 物理副本，适合临时分析、排障、恢复验证和开发测试。托管 fork 默认写入 /pg/data-<name>，不会注册到 Pigsty、systemd 或 Patroni；显式指定 --dst-data 时会创建非托管 fork，不会被 fork list 枚举。

pig pg fork dev                       # 创建 /pg/data-dev，不启动
pig pg fork init dev --start          # 创建后启动，端口从 15432 开始自动探测
pig pg fork init dev -s --dst-port 15433    # 创建后在指定端口启动
pig pg fork init dev -D /pg/data2 --src-port 15431  # 指定源目录与源端口
pig pg fork init dev --dst-data /tmp/dev    # 创建非托管 fork
pig pg fork list                      # 列出托管 fork
pig pg fork start dev                 # 启动已有托管 fork
pig pg fork stop dev                  # 停止已有托管 fork
pig pg fork rm dev --stop             # 停止并删除运行中的 fork
pig pg fork init dev --plan           # 仅显示执行计划

创建选项：

参数	简写	默认值	说明
`--dst-data`		`/pg/data-<name>`	非托管目标数据目录
`--dst-port`		自动探测	目标端口，从 15432 起寻找空闲端口
`--src-data`		`/pg/data` 或 `$PG_DATA`	源数据目录；也可用全局 `pg -D/--data` 设置
`--src-port`		`5432` 或 `$PG_PORT`	源端口
`--start`	`-s`	false	创建后启动 fork
`--force`	`-f`	false	覆盖已有且已停止的目标目录，并跳过确认
`--timeout`	`-t`	60	启动等待超时（秒）
`--yes`	`-y`	false	跳过确认提示
`--plan`		false	只显示执行计划，不执行

管理子命令：

命令	常用参数	说明
`pig pg fork list`	`--plan`, `-o json/yaml`	列出托管 fork
`pig pg fork start <name> or --dst-data <dir>`	`--dst-data`, `--dst-port`, `-t/--timeout`, `--plan`	启动已有 fork
`pig pg fork stop <name> or --dst-data <dir>`	`--dst-data`, `-m/--mode`, `-t/--timeout`, `--plan`	停止已有 fork
`pig pg fork rm <name> or --dst-data <dir>`	`--dst-data`, `--stop`, `-m/--mode`, `-t/--timeout`, `-f/--force`, `-y/--yes`, `--plan`	删除 fork；运行中的 fork 需 `--stop`

行为说明：

源实例运行时，命令会使用 PostgreSQL 低级备份 API 创建一致的物理副本；源实例停止时，可执行冷复制。
命令会优先使用 CoW/reflink；如果只能普通复制，会在交互模式中提示空间风险并等待确认。
为避免误删源数据，目标目录不能是 /、/pg、源 PGDATA、自身父目录或子目录；软链接会先解析到真实路径再判断。
复制完成后会清理 fork 中的运行态与复制状态，并写入 fork.json。只有指定 -s|--start 时才会启动新实例。
托管 fork 必须通过名称管理；非托管 fork 需要通过 --dst-data 指定目录来启动、停止或删除。

列出 fork：

pig pg fork list 扫描 /pg/data-* 并读取 fork.json。文本状态只区分 forked 与 orphan，不实时判断实例是否正在运行。

结构化输出：

pig pg fork init dev --plan -o yaml
pig pg fork list -o json

日志命令

日志命令用于查看 PostgreSQL 日志文件。默认日志目录为 /pg/log/postgres，可通过 --log-dir 参数指定其他目录。默认 pg log 动作显示最新 CSV 日志快照；使用 pg log -f 或 pg log tail 实时跟踪。只有 pg log 与 pg log show 支持 -o json 将 CSV 日志行转换为 JSONL；日志快照不支持 yaml 与 json-pretty，follow/tail、less、grep 不支持结构化输出。

日志命令全局参数：

参数	说明
`--log-dir`	日志目录路径（默认：`/pg/log/postgres`）
`--lines` / `-n`	显示行数（默认 50）
`--follow` / `-f`	跟踪最新日志（仅 `pg log` 父命令）

权限处理： 如果当前用户没有权限读取日志目录，命令会自动使用 sudo 重试。

pg log

显示最新日志快照；配合 -f 时跟踪最新日志。

pig pg log                        # 显示最新 50 行
pig pg log -n 100                 # 显示最新 100 行
pig pg log -f                     # 跟踪最新日志

pg log list

列出日志目录中的日志文件。

pig pg log list                              # 列出默认目录中的日志
pig pg log ls                                # 别名
pig pg log list --log-dir /var/log/postgres  # 列出指定目录中的日志

pg log tail

实时查看日志文件（类似 tail -f）。默认查看最新的 CSV 日志文件。

pig pg log tail                   # 查看最新日志
pig pg log t                      # 别名
pig pg log f                      # 别名
pig pg log tail postgresql.csv    # 查看指定日志文件
pig pg log tail -n 100            # 显示最后 100 行后开始跟踪
pig pg log tail --log-dir /var/log/postgres  # 使用自定义目录

选项：

参数	简写	默认值	说明
`--lines`	`-n`	50	显示的行数
`--follow`	`-f`	false	兼容性 no-op；`tail` 本身总是跟踪

pg log show

输出日志文件内容。

pig pg log show                   # 输出最新日志
pig pg log cat                    # show 的别名
pig pg log c                      # show 的别名
pig pg log show -n 100            # 输出最后 100 行
pig pg log show postgresql.csv    # 输出指定日志文件

选项：

参数	简写	默认值	说明
`--lines`	`-n`	50	显示的行数

pg log less

用 less 打开日志文件。默认定位到文件末尾（+G）。

pig pg log less                   # 用 less 打开最新日志
pig pg log vi                     # 别名
pig pg log v                      # 别名
pig pg log less postgresql.csv    # 打开指定日志文件

pg log grep

搜索日志文件内容。

pig pg log grep ERROR             # 搜索 ERROR
pig pg log grep --ignore-case error  # 忽略大小写
pig pg log grep -C 3 ERROR        # 显示上下文
pig pg log grep ERROR pg.csv      # 搜索指定日志文件

选项：

参数	简写	说明
`--ignore-case`		忽略大小写
`--context`	`-C`	显示上下文行数

pg svc 子命令

pg svc（也可写作 pg service 或 pg s）提供通过 systemctl 管理 PostgreSQL 服务的功能：

pig pg svc start                 # 启动 postgres 服务
pig pg svc stop                  # 停止 postgres 服务
pig pg svc restart               # 重启 postgres 服务
pig pg svc reload                # 重载 postgres 服务
pig pg svc status                # 显示服务状态

别名对照：

命令	别名
`pg svc start`	`boot, up`
`pg svc stop`	`halt, dn, down`
`pg svc restart`	`reboot, rt`
`pg svc reload`	`rl, hup`
`pg svc status`	`st, stat`

设计说明

与原生工具的关系：

pig pg 并非对 PostgreSQL 原生工具的简单封装，而是针对常用操作的上层抽象：

服务控制命令（init/start/stop/restart/reload/promote）调用 pg_ctl
status 命令除了 pg_ctl status 外，还显示进程和相关服务状态
连接管理命令（psql/ps/kill）调用 psql
clone 命令调用 SQL 创建数据库副本
维护命令（vacuum/analyze）调用 vacuumdb
repack 命令调用 pg_repack
fork 命令使用 PostgreSQL 低级备份 API 与本地文件复制创建一次性物理副本
日志命令调用 tail、less、grep 等系统工具
pg svc 命令调用 systemctl

如需使用原生工具的完整功能，可直接调用相应命令。

权限处理：

如果当前用户已是 DBSU：直接执行命令
如果当前用户是 root：使用 su - postgres -c "..." 执行
其他用户：使用 sudo -inu postgres -- ... 执行

安全性考虑：

--state、--query、--schema、--table 等参数都经过标识符验证，防止 SQL 注入
pg kill 默认为 dry-run 模式，避免误操作
pg clone 会终止源数据库现有会话，建议在维护窗口使用
pg fork 会拒绝危险目标路径；普通复制 fallback 会提示空间风险
日志命令在权限不足时自动使用 sudo

平台支持：

此命令专为 Linux 系统设计，部分功能依赖 systemctl。

命令：build

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

pig build 命令是一个强大的工具，简化了从源码构建 PostgreSQL 扩展的整个工作流程。它提供了完整的构建基础设施设置、依赖管理，以及标准和自定义 PostgreSQL 扩展在不同操作系统上的编译环境。

pig build - Build Postgres Extension

Environment Setup:
  pig build spec                   # init build spec and directory (~ext)
  pig build repo                   # init build repo (=repo set -ru)
  pig build repo --beta            # init build repo with PostgreSQL beta repo
  pig build tool  [mini|full|...]  # init build toolset
  pig build rust  [-y] [-m]        # install Rust toolchain
  pig build pgrx  [-v <ver>] [-b]  # install & init pgrx (0.19.1)
  pig build proxy [id@host:port ]  # init build proxy (optional)

Package Building:
  pig build pkg   [ext|pkg...]     # complete pipeline: get + dep + ext
  pig build get   [ext|pkg...]     # download extension source tarball
  pig build dep   [ext|pkg...]     # install extension build dependencies
  pig build ext   [ext|pkg...]     # build extension package

Quick Start:
  pig build spec                   # setup build spec and directory
  pig build pkg citus              # build citus extension

命令	描述	备注
`build spec`	初始化构建规范目录
`build repo`	初始化所需仓库	需要 sudo 或 root 权限
`build tool`	初始化构建工具	需要 sudo 或 root 权限
`build rust`	安装 Rust 工具链	需要 sudo 或 root 权限
`build pgrx`	安装并初始化 pgrx	需要 sudo 或 root 权限
`build proxy`	初始化构建代理
`build get`	下载源代码 tarball
`build dep`	安装扩展构建依赖	需要 sudo 或 root 权限
`build ext`	构建扩展包	需要 sudo 或 root 权限
`build pkg`	完整构建流程：get、dep、ext	需要 sudo 或 root 权限

快速入门

设置构建环境并构建扩展的最快方式：

# 步骤 1：初始化构建规范
pig build spec

# 步骤 2：构建扩展（完整流程）
pig build pkg citus

# 构建的包将位于：
# - EL: ~/ext/pkg/（同时可从 ~/rpmbuild/RPMS/ 访问）
# - Debian: ~/ext/pkg/（同时可从 ~/debbuild/DEBS/ 访问）

更精细的控制方式：

# 设置环境
pig build spec                   # 初始化构建规范
pig build repo                   # 设置仓库
pig build tool                   # 安装构建工具

# 构建过程
pig build get citus              # 下载源码
pig build dep citus              # 安装依赖
pig build ext citus              # 构建包

# 或一次完成所有三个步骤
pig build pkg citus              # get + dep + ext

构建基础设施

目录结构

~/ext/                           # 真实工作目录
├── pkg/                         # 构建产物输出目录
├── src/                         # 源码 tarball 下载目录
├── log/                         # 构建日志目录
└── tmp/                         # 临时目录

~/rpmbuild/                      # EL 构建目录
├── RPMS -> ~/ext/pkg            # RPM 产物软链接
├── SOURCES -> ~/ext/src         # 源码软链接
├── SPECS/
├── BUILD/
├── BUILDROOT/
└── SRPMS/

~/debbuild/                      # Debian / Ubuntu 构建目录
├── DEBS -> ~/ext/pkg            # DEB 产物软链接
├── SOURCES -> ~/ext/src         # 源码软链接
├── SPECS/
└── BUILD/

构建输出位置：

EL 系统：~/ext/pkg/，并通过 ~/rpmbuild/RPMS/ 软链接访问
Debian 系统：~/ext/pkg/，并通过 ~/debbuild/DEBS/ 软链接访问

build spec

设置构建规范与目录结构。

pig build spec                   # 在默认位置初始化 ~/ext
pig build spec -f                # 强制重新下载构建规范 tarball
pig build spec -m                # 优先使用 pigsty.cc 中国镜像

功能：

下载 RPM 或 DEB 构建规范 tarball
创建 ~/ext/{pkg,src,log,tmp} 与平台构建目录
将 RPMS/DEBS 与 SOURCES 软链接到 ~/ext/pkg 和 ~/ext/src
通过增量 rsync 同步 makefile、spec 与 Debian 打包文件

工作目录： 默认使用 ~/ext/ 保存源码、产物、日志与临时文件；平台打包目录为 ~/rpmbuild/ 或 ~/debbuild/。

build repo

初始化构建扩展所需的包仓库。

pig build repo                   # 等同于：pig repo set -ru
pig build repo -m                # 使用中国镜像（PGDG 首选腾讯云）
pig build repo -b                # 包含 PostgreSQL beta 仓库

功能： 以 pig repo set -ru 初始化构建所需仓库：移除旧仓库、添加所需仓库并更新包缓存。

选项：

-m|--mirror：优先使用中国镜像（PGDG 首选腾讯云）
-b|--beta：包含 PostgreSQL beta 仓库模块，当前用于 PG19 beta 构建

build tool

安装必要的开发工具和编译器。

pig build tool                   # 安装默认工具集
pig build tool mini              # 最小工具集
pig build tool full              # 完整工具集
pig build tool rust              # 添加 Rust 开发工具
pig build tool -b                # 包含 PostgreSQL beta 构建包

工具包：

最小（mini）： GCC/Clang 编译器、Make 和构建必需品、PostgreSQL 开发头文件、基本库
默认： 所有最小工具、额外编译器（g++、clang++）、开发库、打包工具（rpmbuild、dpkg-dev）
完整（full）： 所有默认工具、语言特定工具（Python、Perl、Ruby 开发）、高级调试工具、性能分析工具

在 EL 系统上，默认工具集会安装稳定活跃 PostgreSQL 主版本对应的显式 devel/server 包；需要当前 beta 主版本时使用 --beta。

build rust

安装 Rust 编程语言工具链，基于 Rust 的扩展所需。

pig build rust                   # 带确认安装
pig build rust -y                # 强制重新安装 Rust 工具链
pig build rust -m                # 使用 rsproxy.cn 与 Cargo 镜像配置

安装内容： Rust 编译器（rustc）、Cargo 包管理器、Rust 标准库、开发工具。

选项：

-y|--yes：即使 Cargo 已存在也强制重新安装 Rust
-m|--mirror：从中国镜像下载 rustup，并写入面向 rsproxy.cn 的 ~/.cargo/config.toml

build pgrx

安装并初始化 PGRX（Rust 的 PostgreSQL 扩展框架）。

pig build pgrx                   # 安装最新稳定版 (0.19.1)
pig build pgrx -v 0.19.1         # 安装特定版本
pig build pgrx --pg 18,17,16     # 为指定 PG 版本初始化 pgrx
pig build pgrx --pg init         # 只执行 cargo pgrx init，不传 PG 参数
pig build pgrx -b                # 自动探测时包含 beta PostgreSQL pg_config

前提条件： 必须先安装 Rust 工具链、PostgreSQL 开发头文件。

选项：

-v|--pgrx：要安装的 cargo-pgrx 版本
--pg：逗号分隔的 PostgreSQL 主版本，init 表示不传 PostgreSQL 参数，留空则自动探测
-b|--beta：自动探测时包含当前 beta 主版本

build proxy

为受限互联网访问的构建环境设置代理配置。

pig build proxy                  # 交互式设置
pig build proxy user@host:8080   # 使用默认本地端口 127.0.0.1:12345
pig build proxy user@host:8080 127.0.0.1:1080

build get

下载扩展源代码 tarball。

pig build get citus              # 单个扩展
pig build get citus pgvector     # 多个扩展
pig build get pdu pgdog          # 使用内置源码 alias
pig build get citus -f           # 已存在时仍重新下载
pig build get citus -m           # 优先使用 pigsty.cc 中国镜像

pig build get 的参数是扩展名、包名或源码文件名；未知名称会按源码文件名处理。它不会把 all 或 std 展开为内置集合。需要批量下载时，请显式列出目标包名。

一些源码包并不直接对应扩展名，pig build get 内置了特殊 alias 以便直接下载源码。

pig build get pdu                # 下载 pdu-3.0.25.12.tar.gz
pig build get pgdog              # 下载 pgdog-0.1.32.tar.gz
pig build get pgedge-17          # 下载 PostgreSQL 17 与 pgEdge 套件源码
pig build get babelfish-18       # 下载 Babelfish PG18 源码包
pig build get orioledb-16        # 下载 OrioleDB 与 PG16 patch bundle
pig build get onesparse          # 同时下载 onesparse、graphblas、lagraph

当前常见的特殊源码 alias 包括：babelfish / babelfish-17 / babelfish-18、ivorysql、orioledb / orioledb-16 / orioledb-17 / orioledb-18、cloudberry / cloudberry-backup / cloudberry-pxf、pgedge / pgedge-15 / pgedge-16 / pgedge-17 / pgedge-18、polardb、polarstore、zlog、pdu、pgdog、rdkit、onesparse、libpgfeutils、libfq。

build dep

安装构建扩展所需的依赖。

pig build dep citus              # 单个扩展
pig build dep citus pgvector     # 多个扩展
pig build dep citus --pg 17,16   # 为特定 PG 版本

选项：

--pg：指定一个或多个 PostgreSQL 大版本；未指定时按扩展元数据或本机安装自动推断

build ext

编译扩展并创建安装包。

pig build ext citus              # 构建单个扩展
pig build ext citus pgvector     # 构建多个
pig build ext citus --pg 17      # 为特定 PG 版本
pig build ext citus -s           # 包含调试符号（仅 RPM）

选项：

--pg：指定一个或多个 PostgreSQL 大版本
-s|--symbol：构建调试符号包（仅 RPM）

build pkg

执行完整的构建流程：下载、依赖和构建。

pig build pkg citus              # 构建单个扩展
pig build pkg citus pgvector     # 构建多个
pig build pkg citus --pg 17,16   # 为多个 PG 版本
pig build pkg citus -s           # 包含调试符号
pig build pkg citus -m           # 优先使用 pigsty.cc 中国镜像下载源码
pig build pkg cloudberry         # 按顺序构建 cloudberry、backup、pxf

选项：

--pg：指定一个或多个 PostgreSQL 大版本
-s|--symbol：构建调试符号包（仅 RPM）
-m|--mirror：下载源码时优先使用 pigsty.cc 镜像

pig build pkg cloudberry 是套件构建流程：先下载完整 Cloudberry 源码包，构建并安装本地核心产物，然后继续构建 cloudberry-backup 与 cloudberry-pxf。

常见工作流

工作流 1：构建标准扩展

# 1. 设置构建环境（一次性）
pig build spec
pig build repo
pig build tool

# 2. 构建扩展
pig build pkg pg_partman

# 3. 安装构建的包
sudo rpm -ivh ~/ext/pkg/pg_partman*.rpm  # EL
sudo dpkg -i ~/ext/pkg/*partman*.deb     # Debian

工作流 2：构建 Rust 扩展

# 1. 设置 Rust 环境
pig build spec
pig build tool
pig build rust                   # 如需强制重装可追加 -y
pig build pgrx

# 2. 构建 Rust 扩展
pig build pkg pgmq

# 3. 安装
sudo pig ext add pgmq

工作流 3：构建多个版本

# 为多个 PostgreSQL 版本构建扩展
pig build pkg citus --pg 15,16,17

# 结果为每个版本生成包：
# citus_15-*.rpm
# citus_16-*.rpm
# citus_17-*.rpm

故障排除

找不到构建工具

# 安装构建工具
pig build tool

# 对于特定编译器
sudo dnf groupinstall "Development Tools"  # EL
sudo apt install build-essential          # Debian

缺少依赖

# 安装扩展依赖
pig build dep <extension>

# 检查错误消息以了解特定包
# 如需要，手动安装
sudo dnf install <package>  # EL
sudo apt install <package>  # Debian

找不到 PostgreSQL 头文件

# 安装 PostgreSQL 开发包
sudo pig ext install pg18-devel

# 或指定 pg_config 路径
export PG_CONFIG=/usr/pgsql-18/bin/pg_config

Rust/PGRX 问题

# 重新安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 更新 PGRX
cargo install --locked cargo-pgrx@0.19.1

# 重新初始化 PGRX
cargo pgrx init

扩展构建矩阵

常见构建的扩展

扩展	类型	构建时间	复杂度	特殊要求
pg_repack	C	快速	简单	无
pg_partman	SQL/PLPGSQL	快速	简单	无
citus	C	中等	中等	无
timescaledb	C	慢	复杂	CMake
postgis	C	非常慢	复杂	GDAL、GEOS、Proj
pg_duckdb	C++	中等	中等	C++17 编译器
pgroonga	C	中等	中等	Groonga 库
pgvector	C	快速	简单	无
plpython3	C	中等	中等	Python 开发
pgrx 扩展	Rust	慢	复杂	Rust、PGRX

pig inventory

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

pig inventory 命令组（别名 pig inv）自 v1.6.0 起提供，用于以无损方式检视、编辑、校验与体检 Pigsty 配置清单（pigsty.yml），并可通过实验性的 cmdb 子命令与 PostgreSQL CMDB 交换配置。

无损引擎会逐字节保留 YAML 的注释、格式、键序、锚点与换行风格；edit 在写盘前重新解析整个文档并原子写入，非法 YAML 不可能落盘。

Inspect, edit, validate, check, and exchange Pigsty Inventory

Usage:
  pig inventory [command]

Aliases:
  inventory, inv

Available Commands:
  check       Check Inventory, controller, and opt-in target readiness
  cmdb        Exchange Inventory with Pigsty's existing PostgreSQL CMDB (experimental)
  diff        Compare declarations without emitting Inventory values
  edit        Edit Inventory or one selected YAML fragment
  list        List ordered Inventory topology and value kinds
  show        Show verbatim Inventory YAML (may contain secrets)
  status      Inspect the active Inventory source without executing it
  validate    Validate one complete static Pigsty Inventory

命令	别名	说明
`inv status`		检视当前生效的清单来源（不执行清单）
`inv list`	`ls`	列出清单拓扑与取值类型（`--depth` 限制深度）
`inv show`		原样显示清单 YAML（可能包含敏感信息）
`inv edit`	`e`	在 `$EDITOR` 中编辑清单或选中片段
`inv validate`	`v`	校验一份完整的静态 Pigsty 清单
`inv check`	`ck`	检查清单、控制器与目标节点就绪状态
`inv diff`		对比两份清单的声明差异（不输出取值）
`inv cmdb`		与 PostgreSQL CMDB 交换配置（实验性）

清单路径默认取自 pig 的配置解析（-i/--inventory 全局参数或 Pigsty 安装目录），所有命令支持 -o json|yaml 结构化输出。

快速入门

pig inventory status                     # 当前生效的清单来源是什么？
pig inventory list                       # 浏览清单拓扑
pig inventory edit pg-meta               # 只编辑 pg-meta 集群片段
pig inventory validate                   # 全量校验
pig inventory check -p ssh --sudo        # 附加 SSH/sudo 就绪探测
pig inventory diff /path/other.yml       # 与另一份清单对比声明

选择器

list / show / edit 接受可选的选择器参数，定位清单中的一个片段：

pig inv e                                # 整个清单
pig inv e vars                           # all.vars 全局参数
pig inv e pg-meta                        # 一个集群分组
pig inv e pg-meta.vars.pg_databases      # 嵌套键路径
pig inv e 'pg-meta.hosts["10.10.10.10"]' # 含点的键（如 IP）用引号方括号

inv edit

在 $EDITOR 中打开选中片段，保存退出后 pig 会：重新应用缩进与换行 → 重新解析整个文档 （失败则中止并保留临时文件）→ 检查磁盘上的文件在编辑期间是否被并发修改 → 原子写入。

pig inventory edit                       # 编辑整个清单
pig inv e pg-meta                        # 编辑一个片段
pig inv e vars --from vars.yml           # 从文件（或 stdin：-）替换选中片段

参数	说明
`--from`	从常规文件或 stdin（`-`）替换选中片段，跳过编辑器

注意：编辑成功后，pig 会把清单文件权限收紧为 0600（清单可能包含数据库密码等敏感信息），结果中的 mode_tightened 字段会予以提示。如有其他用户或工具直接读取该文件，请相应调整权限或属主。

inv validate

校验一份完整的静态 Pigsty 清单：YAML 结构、Ansible 约定与 Pigsty 语义（如 admin_ip、infra 分组、主机 IPv4 键等）逐层检查，诊断信息不回显敏感取值。

pig inventory validate                   # 校验当前清单
pig inv v ./pigsty.yml                   # 校验指定文件
pig inv v --strict                       # 警告视为失败
pig inv v --ansible                      # 额外用 ansible-inventory 交叉解析
pig inv v --strict -o json               # 结构化输出（CI 友好）

参数	说明
`--strict`	把校验警告当作失败
`--ansible`	额外使用带边界的 `ansible-inventory` 适配器交叉解析
`--timeout`	`--ansible` 兼容性校验超时（默认 10s）

validate 是 Pigsty 语义校验器，不是通用 Ansible linter；其规则与 Pigsty 自带的bin/validate 保持对齐（个别地方更严格）。此外，清单解析对重复键与多文档 YAML 直接拒绝——此类文件连 show / edit 都无法使用。

inv check

在静态校验之上做就绪体检：默认只检查清单与控制器本地条件，可用 --profile 追加探测。

pig inventory check                      # 清单 + 控制器基础检查
pig inv ck -p ansible                    # 追加 ansible 环境检查
pig inv ck -p network                    # 追加网络可达性探测
pig inv ck -p ssh --user admin           # 追加 SSH 登录探测
pig inv ck -p ssh --sudo                 # SSH 探测并验证 sudo -n

参数	简写	说明
`--profile`	`-p`	追加探测：`ansible` / `network` / `ssh`
`--user`		显式 SSH 用户（默认控制器当前用户）
`--port`		TCP/SSH 目标端口（默认 22）
`--sudo`		在 ssh 探测中额外验证 `sudo -n true`

inv cmdb（实验性）

实验性功能：接口与行为可能变化。

pig inventory cmdb 通过原生 PostgreSQL 驱动，与 Pigsty 既有的 CMDB 模式（files/cmdb.sql，pigsty / pglog schema）交换配置清单。连接解析顺序：-d/--database（库名、URI 或 libpq conninfo）→ METADB_URL 环境变量 → service=meta。

子命令	说明
`check`	只读：验证 CMDB 投影，并可选校验与静态清单的一致性
`init`	应用 `cmdb.sql` 基线（存在既有 schema 时需 `--yes` 确认；支持 `--plan` 预览）
`load`	用静态清单替换全部 CMDB 声明行（单事务；需 `--yes`；支持 `--plan`/`--strict`）
`dump`	将 CMDB 导出为静态清单文件（目标不同时需 `--force` 覆盖）
`enable`	守卫式切换 `ansible.cfg` 的 inventory 指向 CMDB（`inventory.sh`）
`disable`	切回静态 `pigsty.yml`（与 `enable` 均支持 `--plan`，原子写入可回滚）

pig inventory cmdb check                 # 验证 CMDB 状态
pig inventory cmdb init --plan           # 预览初始化计划
pig inventory cmdb load -y               # 将静态清单载入 CMDB
pig inventory cmdb dump -f pigsty.yml    # 将 CMDB 导出为静态清单
pig inventory cmdb enable                # 切换 ansible 清单源到 CMDB
pig inventory cmdb disable               # 切回静态 pigsty.yml

注意：init 会直接应用 cmdb.sql 基线，不会先备份既有 CMDB——对已有数据的 CMDB 执行前请自行备份；load 会替换全部声明行。破坏性操作均有基于目标指纹的确认门，结构化输出模式下必须显式 --yes。

pig pt

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

pig patroni 命令（别名 pig pt）自 v1.6.0 起是已安装 patronictl 的透明启动器： pig 只负责选择配置文件与少量本地辅助命令，其余一切命令与参数原样转发给 patronictl，使用原生的参数、交互确认、输出与退出码——patronictl 的新功能无需等待 pig 发版即可使用。

pig pt transparently launches the installed patronictl binary.

Pig only owns config-file selection and these local helpers:
  pig pt set KEY=VALUE...       update PostgreSQL or scalar Patroni settings
  pig pt start|stop             manage the local patroni service
  pig pt service <action>       start, stop, restart, reload, or show service
  pig pt status                 show local and cluster status
  pig pt log ...                view local Patroni logs

Every other command and all arguments after it are passed unchanged to
patronictl. Use "pig pt -- COMMAND ..." to bypass a local-name collision.

第一个非选项命令词决定分发方式：

set、start/up、stop/dn、service/svc、status/st、log/l 走 pig 的本地实现；
其余任何命令词（list、restart、reload、reinit、switchover、failover、pause、resume、show-config、edit-config、query、history、topology、dsn、version 等）连同其后的全部参数，逐字转发给 patronictl；
pig pt -- <命令> ... 可以绕过本地命令名冲突（例如 pig pt -- set 会把 set 交给 patronictl）；
pig pt 不带命令时打印 pig 帮助，不会运行 patronictl；原生子命令帮助用 pig pt <命令> --help，patronictl 根帮助用 pig pt -- --help。

命令概览

透传命令（patronictl 原生）：

示例	说明
`pig pt list [CLUSTER]`	列出集群成员（原生输出，`--format json` 可用）
`pig pt restart CLUSTER [MEMBER]`	重启集群 / 成员的 PostgreSQL（原生确认）
`pig pt reload CLUSTER`	重载 PostgreSQL 配置
`pig pt reinit CLUSTER MEMBER`	重新初始化成员（从主库重新同步数据）
`pig pt switchover CLUSTER [--candidate X]`	计划内主从切换
`pig pt failover CLUSTER --candidate MEMBER`	手动故障切换（位置参数是集群名）
`pig pt pause / resume CLUSTER`	暂停 / 恢复自动故障切换（维护模式）
`pig pt show-config / edit-config`	查看 / 编辑集群动态配置
`pig pt query -c 'select 1'`	原生查询（此处 `-c` 是 query 自己的 SQL 参数）

转发命令的位置参数遵循 patronictl 原生的集群优先（CLUSTER-first）语义，确认提示、输出格式与退出码（含 Click 用法错误退出码 2）均由 patronictl 负责。

本地命令（pig 实现）：

命令	别名	说明
`pt set`		修改 PostgreSQL 参数或 Patroni 标量配置（语法糖）
`pt status`	`st`	综合状态：systemd 服务 + Patroni 进程 + 集群成员
`pt service`	`svc`	管理本地 patroni systemd 服务
`pt start`	`up`	隐藏快捷入口，等价于 `pt svc start`
`pt stop`	`dn`	隐藏快捷入口，等价于 `pt svc stop`
`pt log`	`l`	查看本地 Patroni 日志（show / tail / grep）

注意：顶层 pt restart 不是重启 patroni 守护进程的快捷方式，它会转发给patronictl restart 用于重启 PostgreSQL；重启守护进程请使用 pt svc restart。

快速入门

# 集群操作（原生透传，集群优先语义）
pig pt list pg-meta                         # 列出集群成员
pig pt list pg-meta --format json           # 原生 JSON 输出
pig pt restart pg-test --pending            # 应用待重启成员
pig pt restart pg-test pg-test-1            # 重启指定成员
pig pt switchover pg-test --candidate pg-2  # 计划内切换
pig pt failover pg-test --candidate pg-2    # 手动故障切换
pig pt pause pg-test                        # 进入维护模式
pig pt show-config pg-test                  # 查看动态配置

# 配置修改（本地语法糖，一次 edit-config 调用）
pig pt set ttl=60                           # Patroni 标量配置 → --set
pig pt set max_connections=200              # PostgreSQL 参数 → --pg
pig pt set ttl=60 max_connections=200 -y    # 混合修改，跳过确认
pig pt set shared_buffers=4GB --plan        # 仅预览翻译后的原生命令

# 服务与日志（本地实现）
pig pt status                               # 综合状态
pig pt svc restart                          # 重启 patroni 守护进程
pig pt log -f                               # 实时跟踪日志
pig pt log grep ERROR                       # 搜索日志

Pig/PT 选项

以下包装层选项必须出现在原生命令之前；一旦出现原生命令词，其后的所有参数都属于 patronictl：

参数	简写	说明
`--config-file`	`-c`	显式指定 Patroni/patronictl 配置文件
`--dbsu`		执行 patronictl 的 OS 用户（默认 `$PIG_DBSU` 或 `postgres`）
`--dcs-url`	`-d`	覆盖 Patroni DCS URL（`--dcs` 为其别名）
`--insecure`	`-k`	允许 TLS 连接不校验证书

pig pt -c /path/patroni.yml list pg-meta   # 包装层 -c：配置文件
pig pt query -c 'select 1'                 # 原生 query 的 -c：SQL 语句，不会被 pig 截获

v1.6.0 起 --dbsu 不再提供 -U 简写（pg / pb 命令不受影响）。

配置文件解析

每次配置相关的 patronictl 调用都会由 pig 注入唯一的根 -c <路径>，解析优先级：

命令前显式给出的 -c/--config-file；
非空的 PATRONICTL_CONFIG_FILE 环境变量；
/etc/patroni/patroni.yml（存在且以 DBSU 身份可读）；
/infra/conf/patronictl.yml（存在且以 DBSU 身份可读）；
兜底回退 /etc/patroni/patroni.yml，让 patronictl 的报错指向常规位置。

显式路径与环境变量路径具有权威性：文件缺失或不可读时 pig 不会静默换用其他候选；相对路径会在切换 OS 用户前转换为绝对路径。常规候选文件的可读性按**实际执行用户（DBSU）**探测，而非简单检查权限位。解析是惰性的：pt svc start 这类纯 systemd 操作不会触发配置解析；原生 -h/--help 走免配置快速路径，在未配置 Patroni 的机器上也能查看帮助。

透传执行与输出模式

转发执行直接继承 stdin / stdout / stderr 与终端：原生交互确认、edit-config 的编辑器、--watch 流式刷新、退出码全部保真；pig 不做输出捕获、不重复渲染错误、不重试、也不在执行前后读取集群或 DCS 状态。逻辑调用形态为：

patronictl -c <选中配置> [--dcs-url URL] [--insecure] <原生命令与参数...>

结构化输出：转发路径只支持 pig 的 text 模式。在原生命令之前出现的-o json / -o yaml 会被明确拒绝（提示改用原生输出选项）；出现在原生命令之后的参数原样转发，由 patronictl 自行校验：

pig -o json pt list          # 拒绝：请使用原生输出选项
pig pt -o json list          # 拒绝：请使用原生输出选项
pig pt list --format json    # 原样转发，patronictl 原生 JSON
pig pt list -o json          # 原样转发，由 patronictl 校验

本地命令（set / status / log / service）保留 pig 的结构化输出行为。

pt set

pt set 是唯一的本地配置语法糖，作用于选中配置对应的集群：

pig pt set KEY=VALUE [KEY=VALUE ...] [--yes] [--plan]

键分类规则：

以下 Patroni 顶层标量键翻译为原生 --set：loop_wait、ttl、retry_timeout、primary_race_backoff、maximum_lag_on_failover、maximum_lag_on_syncnode、max_timelines_history、primary_start_timeout、primary_stop_timeout、synchronous_mode、synchronous_mode_strict、synchronous_node_count、failsafe_mode、check_timeline、member_slots_ttl（pause 不在其列——请使用原生 pause/resume）；
其余键一律视为 PostgreSQL 参数，翻译为原生 --pg（含 timescaledb.telemetry_level 这类带点自定义 GUC）；
以 postgresql.、standby_cluster.、slots.、ignore_slots. 开头的结构性键会被拒绝，并提示改用原生 pig pt edit-config --set。

所有键值对按输入顺序合并为一次原生 edit-config 调用，产生一次 diff、一次确认、一次 DCS 更新：

pig pt set ttl=60 max_connections=200 synchronous_mode=on
# 等价于：patronictl -c <选中配置> edit-config --set ttl=60 --pg max_connections=200 --set synchronous_mode=on

--yes/-y 追加原生 --force 跳过确认；默认由 patronictl 显示 diff 并负责确认；
--plan 不执行任何修改，仅渲染选中配置与翻译后的原生命令（计划可能包含敏感值）；
结构化输出模式下执行必须携带 --yes（禁止隐藏交互提示）；
值按 YAML 解析：KEY=null 与 KEY= 均表示删除该键，pig 原样传递；
修改需要重启的 PostgreSQL 参数后，pig 会提示后续操作：先 pig pt list，再 pig pt restart CLUSTER --pending（需显式集群名）。

服务管理

pt service（别名 pt svc）管理本地 patroni systemd 服务：

命令	别名	说明
`pt service start`	`pt svc up`	启动 Patroni 服务
`pt service stop`	`pt svc dn`	停止 Patroni 服务
`pt service restart`	`pt svc rs`	重启 Patroni 服务
`pt service reload`	`pt svc rl`	重载 Patroni 服务
`pt service status`	`pt svc st`	显示服务状态

顶层 pt start / pt stop（别名 up / dn）是隐藏快捷入口，调用同一本地实现。停止 Patroni 服务可能导致该节点上的 PostgreSQL 一并停止（取决于 Patroni 配置）。

pt status

显示综合状态：systemd 服务状态、Patroni 进程信息、以及来自 patronictl 的集群成员状态。

pig pt status
pig pt st -o json                # 结构化输出

pt log

查看本地 Patroni 日志。日志目录取自选中配置的 log.dir，未配置时回退到 /pg/log/patroni，也可用 --log-dir 显式指定。仅 pt log 与 pt log show 支持 -o json（JSONL 快照）； follow / tail / grep 是终端流式操作，不支持结构化输出。

pig pt log                     # 显示最近 50 行日志
pig pt log -f                  # 实时跟踪日志输出
pig pt log -n 100              # 显示最近 100 行
pig pt log show -o json        # JSONL 快照
pig pt log tail -n 100         # 跟踪日志
pig pt log grep ERROR          # 搜索日志

子命令	别名	说明
`show`	`cat, c, s`	输出最近 Patroni 日志
`tail`	`t, f, follow`	持续跟踪 Patroni 日志
`grep`	`g, search`	搜索 Patroni 日志

参数	简写	默认值	说明
`--follow`	`-f`	false	实时跟踪日志输出
`--lines`	`-n`	50	显示的日志行数
`--log-dir`		自动解析	日志目录

从 v1.5.x 迁移

v1.6.0 的透传重写是破坏性变更，升级前请检查自动化脚本：

v1.5.x 用法	v1.6.0 用法
`pig pt failover <候选成员>`	⚠ `pig pt failover CLUSTER --candidate MEMBER`（位置参数语义反转：现在是集群名）
`pig pt restart [成员]`（自动定位集群）	`pig pt restart CLUSTER [MEMBER]`（需显式集群名）
`pig pt list -o json`	`pig pt list --format json`（原生 JSON，schema 不同）
`pig pt config show`	`pig pt show-config`
`pig pt config edit`	`pig pt edit-config`
`pig pt config set K=V` / `pg K=V`	`pig pt set K=V`
`pig pt restart -y`（pig 确认门）	原生确认由 patronictl 负责；`pt set -y` 仍有效
`pig pt list -W` / `-w 5`	原生 `pig pt list --watch`（patronictl 语义）
别名 `ls/rs/rl/ri/so/fo/p/r/c`	已移除，使用完整原生命令名
`--dbsu -U`	`--dbsu`（`-U` 简写已移除）

此外：转发命令的退出码为 patronictl 原生值（用法错误为 2）； switchover / failover 不再有 pig 侧的 pause 预检——维护模式语义完全由 Patroni 负责。

设计说明

单一权威：集群控制路径只有一条——已安装的 patronictl + 一份选中配置，经由 Patroni REST API / DCS 生效。pig 不内嵌 DCS 客户端或 REST 控制引擎，不维护 patronictl 命令清单，不对转发命令做确认、预检、重试或结果改写。

权限处理（与 v1.5.x 相同）：

当前用户已是 DBSU：直接执行；
当前用户是 root：su - postgres -c "..." 执行；
其他用户：sudo -inu postgres -- ... 执行。

平台支持：此命令专为 Linux 设计，服务管理依赖 systemctl，日志功能依赖可读取的 Patroni 日志文件。

pig pb

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

pig pgbackrest 命令（别名 pig pb）用于管理 pgBackRest 备份，并提供低层 restore 原语。它封装了常用的 pgbackrest 操作，提供简化的备份管理体验。所有命令均以数据库超级用户身份（默认 postgres）执行。托管集群的编排式时间点恢复请优先使用 pig pitr。

pig pb - Manage pgBackRest backup and point-in-time recovery.

Information:
  pig pb info                      show backup info
  pig pb list                      list backups
  pig pb list repo                 list configured repositories
  pig pb list stanza               list all stanzas

Backup & Restore:
  pig pb backup                    create backup (auto: full/incr)
  pig pb backup full               create full backup
  pig pb restore                   low-level restore primitive
  pig pb restore -t "..."          restore to specific time
  pig pb expire                    cleanup expired backups

Stanza Management:
  pig pb create                    create stanza (first-time setup)
  pig pb upgrade                   upgrade stanza (after PG upgrade)
  pig pb delete                    delete stanza (DANGEROUS!)

Control:
  pig pb check                     verify backup integrity
  pig pb start                     enable pgBackRest operations
  pig pb stop                      disable pgBackRest operations
  pig pb log                       view pgBackRest logs

Examples:
  pig pb info                      # show all backup info
  pig pb backup                    # auto: full if none, else incr
  pig pb backup full               # full backup
  pig pb restore -d                # restore to latest (end of WAL)
  pig pb restore -t "2025-01-01 12:00:00+08"  # restore to time
  pig pb create                    # initialize stanza
  pig pb expire                    # cleanup per retention policy

命令概览

信息查询：

命令	缩写	描述	实现方式
`pb info`	`i`	显示备份仓库信息	`pgbackrest info`
`pb list`	`ls`	列出备份集，仓库，Stanza	`pgbackrest info`

备份与恢复：

命令	缩写	描述	实现方式
`pb backup`	`b`	创建备份	`pgbackrest backup`
`pb restore`	`r`	低层备份恢复原语	`pgbackrest restore`
`pb expire`	`e`	清理过期备份	`pgbackrest expire`

Stanza 管理：

命令	缩写	描述	实现方式
`pb create`	`c`	创建 stanza（首次设置）	`pgbackrest stanza-create`
`pb upgrade`	`u`	升级 stanza（PG 大版本升级后）	`pgbackrest stanza-upgrade`
`pb delete`	`d`	删除 stanza（危险操作！）	`pgbackrest stanza-delete`

控制命令：

命令	别名	描述	实现方式
`pb check`	`ck`	验证备份仓库完整性	`pgbackrest check`
`pb start`	`up`	启用 pgBackRest 操作	`pgbackrest start`
`pb stop`	`dw`	禁用 pgBackRest 操作	`pgbackrest stop`
`pb log`	`l`	查看日志	最新日志快照 / tail

快速入门

# 查看备份信息
pig pb info                          # 显示所有备份信息
pig pb info -o json                  # Result 包装的结构化 JSON 输出
pig pb info --raw --raw-output json  # pgBackRest 原生 JSON 输出
pig pb ls                            # 列出所有备份
pig pb ls repo                       # 列出配置的仓库
pig pb ls stanza                     # 列出所有 stanza

# 创建备份（必须在主库执行）
pig pb backup                        # 自动模式：无备份则全量，否则增量
pig pb backup full                   # 全量备份
pig pb backup diff                   # 差异备份
pig pb backup incr                   # 增量备份

# 恢复（低层 restore 原语，至少指定一个恢复目标）
pig pb restore -d                    # 恢复到最新（WAL 流末尾）
pig pb restore -I                    # 恢复到备份一致性点
pig pb restore -t "2025-01-01 12:00:00+08"  # 恢复到指定时间
pig pb restore --name savepoint      # 恢复到命名还原点

# Stanza 管理
pig pb create                        # 初始化 stanza
pig pb upgrade                       # PG 大版本升级后升级 stanza
pig pb check                         # 验证仓库完整性

# 清理
pig pb expire                        # 按保留策略清理
pig pb expire --plan                 # 仅预览清理计划

全局参数

以下参数适用于所有 pig pb 子命令：

参数	简写	说明
`--stanza`	`-s`	pgBackRest stanza 名称（自动检测）
`--config`	`-c`	配置文件路径
`--repo`	`-r`	仓库编号（多仓库场景）
`--dbsu`	`-U`	数据库超级用户（默认：`$PIG_DBSU` 或 `postgres`）

Stanza 自动检测：

如果未指定 -s 参数，pig 会从配置文件中自动检测 stanza 名称：

读取配置文件（默认 /etc/pgbackrest/pgbackrest.conf）
查找非 [global*] 开头的 section
使用找到的第一个 stanza

如果配置文件中有多个 stanza，会发出警告并使用第一个。此时应显式指定 --stanza 参数。

多仓库支持：

pgBackRest 支持配置多个仓库（repo1、repo2 等）。使用 -r 参数指定操作的目标仓库：

pig pb backup -r 1                   # 备份到 repo1
pig pb backup -r 2                   # 备份到 repo2
pig pb info -r 2                     # 查看 repo2 的备份信息

信息查询命令

pb info

显示备份仓库详细信息，包括所有备份集和 WAL 归档状态。

pig pb info                          # 显示所有备份信息
pig pb info --raw --raw-output json  # 原始 JSON 输出
pig pb info --set 20250101-120000F   # 显示特定备份集详情

选项：

参数	简写	说明
`--raw`	`-R`	原始输出模式（透传 pgBackRest 输出）
`--raw-output`		原始输出格式：text、json（仅 `--raw` 模式）
`--set`		显示特定备份集详情

pb ls

列出备份仓库中的资源。

pig pb ls                            # 列出所有备份（默认）
pig pb ls backup                     # 列出所有备份（显式）
pig pb ls repo                       # 列出配置的仓库
pig pb ls stanza                     # 列出所有 stanza

类型说明：

类型	描述	数据来源
backup	列出所有备份集（默认）	pgbackrest info
repo	列出配置的仓库	解析 pgbackrest.conf
stanza	列出所有 stanza	解析 pgbackrest.conf

备份命令

pb backup

创建物理备份。备份只能在主库实例上执行。

pig pb backup                        # 自动模式
pig pb backup full                   # 全量备份
pig pb backup diff                   # 差异备份
pig pb backup incr                   # 增量备份
pig pb backup --force                # 跳过主库角色检查

选项：

参数	简写	说明
`--force`	`-f`	跳过主库角色检查

备份类型：

类型	说明
(空)	自动模式：无备份则全量，否则增量
full	全量备份：备份所有数据
diff	差异备份：自上次全量备份以来的变更
incr	增量备份：自上次任意备份以来的变更

主库检查：

执行备份前，命令会自动检查当前实例是否为主库。如果是备库，命令会报错退出。使用 --force 可跳过此检查。

pb expire

按保留策略清理过期的备份和 WAL 归档。

pig pb expire                        # 按策略清理
pig pb expire --set 20250101-*       # 删除特定备份集
pig pb expire --set 20250101-* -y    # 跳过删除备份集确认
pig pb expire --plan                 # 仅预览清理计划，不删除

选项：

参数	简写	说明
`--set`		删除特定备份集
`--plan`		仅预览清理计划，不删除备份
`--yes`	`-y`	与 `--set` 配合时跳过确认提示

保留策略配置：

保留策略在 pgbackrest.conf 中配置：

[global]
repo1-retention-full=2               # 保留的全量备份数
repo1-retention-diff=4               # 保留的差异备份数
repo1-retention-archive=2            # WAL 归档保留策略

恢复命令

pb restore

从备份恢复，支持时间点恢复目标。必须显式指定一个恢复目标（-d/-I/-t/--name/--lsn/--xid）；不带参数仅显示帮助信息。

# 恢复目标（互斥选项）
pig pb restore -d                    # 恢复到最新（显式）
pig pb restore -I                    # 恢复到备份一致性点
pig pb restore -t "2025-01-01 12:00:00+08"  # 恢复到指定时间
pig pb restore -t "2025-01-01"       # 恢复到日期（当天 00:00:00）
pig pb restore -t "12:00:00"         # 恢复到时间（今天）
pig pb restore --name my-savepoint   # 恢复到命名还原点
pig pb restore --lsn "0/7C82CB8"     # 恢复到 LSN
pig pb restore --xid 12345           # 恢复到事务 ID

# 备份集选择（必须与恢复目标组合）
pig pb restore -b 20251225-120000F -d  # 从特定备份集恢复到最新

# 其他选项
pig pb restore -t "..." -X           # 排他模式（在目标前停止）
pig pb restore -t "..." --target-action=promote  # 到达目标后提升
pig pb restore -t "..." -T current   # 沿当前时间线恢复
pig pb restore -d --plan             # 仅预览恢复计划
pig pb restore -d -y                 # 跳过 y/yes 交互确认
pig pb restore -d -- --delta         # 在 -- 后透传 pgBackRest restore 参数

恢复目标选项：

参数	简写	说明
`--default`	`-d`	恢复到 WAL 流末尾（最新数据）
`--immediate`	`-I`	恢复到备份一致性点
`--time`	`-t`	恢复到指定时间戳
`--name`		恢复到命名还原点
`--lsn`		恢复到指定 LSN
`--xid`		恢复到指定事务 ID

备份集和其他选项：

参数	简写	说明
`--set`	`-b`	从特定备份集恢复（可与目标组合）
`--data`	`-D`	目标数据目录
`--exclusive`	`-X`	排他模式：在目标前停止
`--target-action`		到达恢复目标后的动作：pause/promote/shutdown
`--target-timeline`	`-T`	恢复时间线：latest/current/N/0xN
`--plan`		仅预览恢复计划，不执行
`--yes`	`-y`	跳过交互式 y/yes 确认
`--` 后的原生参数		透传 pgBackRest restore 参数，例如 `-- --delta`

组合规则： --target-action 不能与 --default 同时使用，因为 --default 已表示恢复到 WAL 末尾。--exclusive/-X 必须配合明确的停止目标使用：--time、--lsn 或 --xid。

-- 后的原生 pgBackRest restore 参数不能覆盖 Pig 已管理的恢复目标、生命周期、数据目录、仓库、配置和选择参数；请使用 Pig 的一等参数设置这些语义。表空间/链接迁移类参数（如 --tablespace-map、--link-map、--link-all）仍可透传。

时间格式：

支持多种时间格式输入，自动补全时区（支持非整小时时区如 +05:30）：

格式	示例	说明
完整格式	`2025-01-01 12:00:00+08`	包含时区的完整时间戳
仅日期	`2025-01-01`	自动补全为当天 00:00:00（当前时区）
仅时间	`12:00:00`	自动补全为今天（当前时区）

恢复流程：

验证参数和环境
检查 PostgreSQL 已停止
显示恢复计划，等待交互式 y/yes 确认
执行 pgbackrest restore
提供恢复后的操作指引

重要提示： 恢复前必须先停止 PostgreSQL；如果该 PGDATA 由 Patroni 管理，应使用 pig pitr 编排 Patroni、PostgreSQL 与 pgBackRest：

pig pg stop                          # 停止 PostgreSQL
pig pb restore -t "..."              # 执行恢复
pig pg start                         # 启动 PostgreSQL

Stanza 管理命令

pb create

初始化新的 stanza。必须在首次备份前执行。

pig pb create                        # 创建 stanza
pig pb create --no-online            # PostgreSQL 未运行时创建
pig pb create --force                # 强制创建

选项：

参数	简写	说明
`--no-online`		PostgreSQL 未运行时创建
`--force`	`-f`	强制创建

pb upgrade

PostgreSQL 大版本升级后更新 stanza。

pig pb upgrade                       # 升级 stanza
pig pb upgrade --no-online           # PostgreSQL 未运行时升级

选项：

参数	说明
`--no-online`	PostgreSQL 未运行时升级

使用场景：

当 PostgreSQL 进行大版本升级（如 16 → 17）后，需要执行此命令更新 stanza 元数据。

pb delete

删除 stanza 及其所有备份。

pig pb delete                        # 删除 stanza（交互式 y/N 确认）
pig pb delete --yes                  # 跳过 y/yes 交互确认
pig pb delete --plan                 # 预览删除计划

选项：

参数	简写	说明
`--plan`		仅预览删除计划，不执行
`--yes`	`-y`	跳过交互式 y/yes 确认

警告： 这是一个破坏性且不可逆的操作！所有备份将被永久删除。

命令包含多重安全机制：

文本模式下要求交互式 y/yes 确认，除非指定 --yes
结构化输出模式必须显式指定 --yes
配置文件存在多个 stanza 且未显式 --stanza 时，拒绝自动选择删除目标

控制命令

pb check

验证备份仓库的完整性和配置。

pig pb check                         # 验证仓库

此命令检查：

WAL 归档配置是否正确
仓库是否可访问
stanza 配置是否有效

pb start

启用 pgBackRest 操作。

pig pb start                         # 启用操作

在执行 pb stop 后使用此命令恢复正常操作。

pb stop

禁用 pgBackRest 操作（用于维护）。

pig pb stop                          # 禁用操作
pig pb stop --force                  # 终止正在运行的操作

选项：

参数	简写	说明
`--force`	`-f`	终止正在运行的操作

使用场景：

在进行系统维护时，使用此命令阻止新的备份操作启动。

日志命令

pb log

查看 pgBackRest 日志文件。日志目录优先读取 pgBackRest 配置中的 log-path，未配置时使用 /pg/log/pgbackrest/。父命令默认显示最新日志快照，实时跟踪请使用 tail 或 -f。只有 pb log 与 pb log show 支持 -o json 输出 JSONL；日志快照不支持 yaml 与 json-pretty，follow/tail 不支持结构化输出。

pig pb log                           # 显示最新日志行
pig pb log list                      # 列出日志文件
pig pb log tail                      # 实时查看最新日志
pig pb log tail -n 100               # 显示最后 100 行并跟踪
pig pb log show                      # 显示最新日志内容
pig pb log show -n 50                # 显示最后 50 行
pig pb log cat                       # show 的别名

子命令：

子命令	别名	说明
list	ls	列出日志文件
show	cat, c	显示最新日志内容
tail	t, f, follow	实时跟踪最新日志

选项：

参数	简写	默认值	说明
`--lines`	`-n`	50	显示的行数
`--follow`	`-f`	false	父命令 `pb log` 使用该参数进入跟踪；`pb log tail` 中为 no-op，因为 tail 总是跟踪

权限处理：

如果当前用户没有权限读取日志目录，命令会自动使用 sudo 重试。

设计说明

命令执行方式：

所有 pig pb 命令都以数据库超级用户（DBSU）身份执行。这是因为 pgBackRest 需要访问 PostgreSQL 数据文件和 WAL 归档。

执行逻辑：

如果当前用户已是 DBSU：直接执行命令
如果当前用户是 root：使用 su - postgres -c "..." 执行
其他用户：使用 sudo -inu postgres -- ... 执行

与 pgbackrest 的关系：

pig pb 并非 pgbackrest 的完整封装，而是针对常用操作的上层抽象：

自动检测 stanza 名称，无需每次指定
备份前自动检查主库角色
恢复时显示计划并要求交互式 y/yes 确认
提供人性化的时间格式输入
恢复后提供操作指引

如需使用 pgbackrest 的完整功能，请直接使用 pgbackrest 命令。

默认配置路径：

配置项	默认值
配置文件	`/etc/pgbackrest/pgbackrest.conf`
日志目录	`/pg/log/pgbackrest`
数据目录	配置文件中的 `pg1-path`，或 `$PGDATA` 环境变量，或 `/pg/data`

安全考虑：

pb delete 在没有 --yes 时要求交互式 y/yes 确认，多 stanza 配置下必须显式指定 --stanza
pb restore 需要显式恢复目标，校验 --time，并在没有 --yes 时要求交互式 y/yes 确认
pb backup 默认检查主库角色，防止在备库执行
pb log tail 不支持结构化输出；需要 JSONL 快照时使用 pb log show -n N -o json

平台支持：

此命令专为 Linux 系统设计，依赖 Pigsty 的默认目录结构。

pig pitr

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

pig pitr 命令用于通过 pgBackRest 执行时间点恢复，并以保守方式处理本地 PostgreSQL 与 Patroni 生命周期。与底层的 pig pb restore 不同，pig pitr 会先做恢复前检查，必要时停止 Patroni 与 PostgreSQL，执行 restore，然后按参数决定是否启动 PostgreSQL。

请注意：对于托管的默认数据目录，pig pitr 恢复后会让 Patroni 保持停止。请先验证恢复结果，再由人工恢复 Patroni 管理；该命令不会自动重入 Patroni 集群、执行故障切换，或验证集群成员状态。

pig pitr - Perform PITR with pgBackRest restore and conservative PostgreSQL stop/start handling.

For the managed default data directory, this command may:
  1. Stop Patroni only to keep the target PGDATA offline during restore
  2. Ensure PostgreSQL is stopped (fast stop with retry; destructive fallback only with --force-stop)
  3. Execute pgbackrest restore
  4. Start PostgreSQL unless --no-restart is used
  5. Leave Patroni stopped; provide post-restore guidance

Recovery Targets (at least one required):
  --default, -d      Recover to end of WAL stream (latest)
  --immediate, -I    Recover to backup consistency point
  --time, -t         Recover to specific timestamp
  --name             Recover to named restore point
  --lsn              Recover to specific LSN
  --xid              Recover to specific transaction ID

Backup and Target Options:
  --set, -b          Select backup set to start recovery from
  --target-action    Action when target is reached: pause, promote, shutdown
  --target-timeline  Recover along timeline: latest, current, N, or 0xN

Use --no-restart with --target-action=shutdown because PostgreSQL exits
after reaching the recovery target.

Custom -D side restores require --no-restart. The custom directory must
already exist, be owned by the configured DBSU (postgres by default), and
be writable by that user. Pig does not create this directory automatically.

Additional pgBackRest arguments:
  Put raw pgBackRest restore arguments after -- so Cobra stops parsing them.
  Example: pig pitr -d -- --delta

Time Format:
  - Full: "2025-01-01 12:00:00+08"
  - Date only: "2025-01-01" (defaults to 00:00:00)
  - Time only: "12:00:00" (defaults to today)

Examples:
  pig pitr -d                                      # Recover to latest
  pig pitr -t "2025-01-01 12:00:00+08"            # Recover to time
  pig pitr -d --plan                               # Preview plan
  pig pitr -d -y                                   # Skip y/yes confirmation
  pig pitr -d --no-restart                         # Leave PostgreSQL stopped
  pig pitr -d -D /tmp/pg-restore --no-restart      # Side restore

命令概览

pig pitr 的默认目标是恢复 Pigsty 管理的主数据目录。典型流程如下：

验证恢复目标参数，必须指定 -d/-I/-t/--name/--lsn/--xid 之一
解析 pgBackRest 配置与目标数据目录
对默认数据目录恢复时，若 Patroni 正在运行，则停止 Patroni
确保 PostgreSQL 已停止
调用 pgbackrest restore
除非指定 --no-restart，否则启动 PostgreSQL
输出恢复后验证与 Patroni 恢复指引

与 pig pb restore 的区别：

特性	`pig pitr`	`pig pb restore`
停止 Patroni	默认数据目录恢复时自动停止	手动处理
停止 PostgreSQL	自动检查并停止	必须预先停止
启动 PostgreSQL	默认自动启动，可用 `--no-restart` 禁用	手动处理
Patroni 恢复	不自动恢复，验证后人工处理	不处理
适用场景	生产恢复编排	底层 restore 或脚本集成

快速入门

# 最常用：恢复到 WAL 流末尾
pig pitr -d

# 恢复到指定时间点
pig pitr -t "2025-01-01 12:00:00+08"

# 恢复到备份一致性点
pig pitr -I

# 查看执行计划，不实际执行
pig pitr -d --plan

# 跳过确认，适合自动化脚本
pig pitr -d -y

# 从特定备份集恢复
pig pitr -d -b 20251225-120000F

# 恢复默认数据目录，但恢复后不启动 PostgreSQL
pig pitr -d --no-restart

# side restore：恢复到自定义目录，不触碰 Patroni 与 /pg/data
install -d -m 700 -o postgres -g postgres /tmp/pg-restore
pig pitr -d -D /tmp/pg-restore --no-restart

# 额外 pgBackRest restore 参数写在 -- 之后
pig pitr -d -- --delta

参数说明

恢复目标（必选其一）

参数	简写	说明
`--default`	`-d`	恢复到 WAL 流末尾（最新数据）
`--immediate`	`-I`	恢复到备份一致性点
`--time`	`-t`	恢复到指定时间戳
`--name`		恢复到命名还原点
`--lsn`		恢复到指定 LSN
`--xid`		恢复到指定事务 ID

备份与目标选项

参数	简写	说明
`--set`	`-b`	从特定备份集开始恢复
`--target-action`		到达恢复目标后的动作：pause/promote/shutdown
`--target-timeline`	`-T`	恢复时间线：latest/current/N/0xN
`--exclusive`	`-X`	排他模式：在目标前停止

--target-action=shutdown 必须配合 --no-restart，因为 PostgreSQL 到达目标后会退出。--target-action 不能与 --default 同时使用，因为 --default 已表示恢复到 WAL 末尾。--exclusive/-X 必须配合明确的停止目标使用：--time、--lsn 或 --xid。

-- 后的原生 pgBackRest restore 参数不能覆盖 Pig 已管理的恢复目标、生命周期、数据目录、仓库、配置和选择参数；这些语义应使用 Pig 的一等参数设置。该限制与 pig pb restore 的 passthrough blocklist 一致。

流程控制

参数	简写	说明
`--no-restart`		restore 后不启动 PostgreSQL
`--plan`		仅显示执行计划，不执行
`--yes`	`-y`	跳过交互式 y/yes 确认
`--timeout`		PostgreSQL 启动/恢复等待超时，默认 120 秒
`--force-stop`		fast stop 失败时允许 immediate shutdown 与 kill fallback

配置参数

参数	简写	说明
`--stanza`	`-s`	pgBackRest stanza 名称
`--config`	`-c`	pgBackRest 配置文件路径
`--repo`	`-r`	仓库编号
`--dbsu`	`-U`	数据库超级用户（默认：`postgres`）
`--data`	`-D`	目标数据目录

时间格式

--time 参数支持多种时间格式，会按当前时区补全缺失部分：

格式	示例	说明
完整格式	`2025-01-01 12:00:00+08`	包含时区的完整时间戳
无时区日期时间	`2025-01-01 12:00:00`	自动补当前本地时区，`T` 分隔符也可接受
仅日期	`2025-01-01`	自动补全为当天 00:00:00
仅时间	`12:00:00`	自动补全为今天的该时间

计划输出与可重放的 next-action 命令会把仅日期、仅时间目标规范化为带时区的确定性时间戳；该规则与 pig pb restore --plan 一致。

托管目录与 Side Restore

托管 PostgreSQL 数据目录来自有效 pgBackRest 配置中的 pg1-path 与命令参数，而不是硬编码 /pg/data。例如托管 PGDATA 是 /var/lib/pgsql/18/data 时，仍然按托管恢复处理。路径比较会在需要时以数据库超级用户解析软链接，因此指向托管 PGDATA 的软链接不会被误判为 side restore。

显式 -D/--data 且解析后不同于托管目录时，才是 side restore。side restore 必须使用 --no-restart，不会停止 Patroni，也不会管理默认 PostgreSQL 服务；恢复后请手工使用类似 pg_ctl -D <dir> -o "-p 5433" start、pg_ctl -D <dir> status 和 pgbackrest --pg1-path=<dir> stanza-create 的命令处理。side restore 目录必须已存在且归属 DBSU；与托管 PGDATA 不同，它不要求预先包含 PG_VERSION 初始化标记。Pig 不会自动创建该目录，因为命令需要在 destructive restore 前完成路径归类、owner 检查和安全提示。

install -d -m 700 -o postgres -g postgres /tmp/pg-restore
pig pitr -d -D /tmp/pg-restore --no-restart

对于非 /pg/data 的托管 PGDATA，恢复后的 runbook 命令会显式带上有效数据目录，例如：

pig pg start -D /var/lib/pgsql/18/data
pig pg psql -D /var/lib/pgsql/18/data
pig pg promote -D /var/lib/pgsql/18/data

pig pg psql -D <dir> 会读取该目录的 postmaster.pid，使用其中记录的端口和 socket 目录连接恢复后的实例；无法解析 postmaster 信息时不会静默回退到默认连接目标。

执行流程

第一阶段：预检查

验证恢复目标参数，缺失目标时只显示帮助并返回错误
解析有效 pgBackRest 配置、stanza、仓库与托管 pg1-path
检查托管数据目录存在且已初始化
对 side restore，检查自定义目录存在且归属 DBSU
验证所选 stanza 正常且存在备份；指定 --set 时验证对应备份集存在
检测 Patroni 服务状态与 PostgreSQL 运行状态

第二阶段：处理 Patroni

托管数据目录恢复时，如果 Patroni 正在运行，命令会停止 Patroni，让目标 PGDATA 在 restore 期间保持离线。恢复完成后 Patroni 会保持停止。自定义 -D side restore 不触碰托管数据目录，因此不会停止 Patroni。

第三阶段：确保 PostgreSQL 停止

命令会先等待 Patroni 停止后 PostgreSQL 自动退出，再重试 pg_ctl stop -m fast。如果 PostgreSQL 仍无法停止，默认不会使用更激进手段；只有显式指定 --force-stop，才允许 immediate shutdown 与最终的 kill fallback。

第四阶段：执行恢复

调用 pgBackRest 执行 restore，并把恢复目标、备份集、时间线、target action 等参数映射到 pgbackrest restore。原生 pgBackRest 参数可以写在 -- 之后：

pig pitr -d -- --delta

第五阶段：启动或保持停止

除非指定 --no-restart，命令会在 restore 后启动 PostgreSQL，并等待恢复完成。对于 --default 与 --target-action=promote，命令会等待恢复实例上的 pg_is_in_recovery() 变为 false；恢复与后续 SQL 探测会绑定恢复数据目录 postmaster.pid 中的端口，并在存在时使用其中的 socket 目录。以下情况必须或通常应使用 --no-restart：

自定义 -D side restore，因为恢复出的配置仍保留原端口，需要手动指定空闲端口启动
--target-action=shutdown，因为 PostgreSQL 到达恢复目标后会退出
需要人工检查恢复目录后再决定是否启动

使用示例

场景一：误删数据恢复

# 1. 查看可用备份
pig pb info

# 2. 预览恢复计划
pig pitr -t "2025-01-15 09:30:00+08" --plan

# 3. 执行恢复
pig pitr -t "2025-01-15 09:30:00+08"

# 4. 验证数据
pig pg psql
SELECT * FROM important_table;

场景二：恢复到最新状态

pig pitr -d

场景三：恢复到备份一致性点

pig pitr -I

场景四：恢复后保持停止

pig pitr -d --no-restart

# PostgreSQL 与 Patroni 都保持停止；手动检查目录或日志后再启动
pig pg start

场景五：自定义目录 side restore

install -d -m 700 -o postgres -g postgres /tmp/pg-restore
pig pitr -d -D /tmp/pg-restore --no-restart

# 使用空闲端口手动启动 side restore
pg_ctl -D /tmp/pg-restore -o "-p 5433" start

执行计划示例

执行 pig pitr -d --plan 会显示类似以下的计划：

══════════════════════════════════════════════════════════════════
 PITR Execution Plan
══════════════════════════════════════════════════════════════════

Current State:
  Data Directory:  /pg/data
  Database User:   postgres
  Patroni Service: active
  PostgreSQL:      running (PID: 12345)

Recovery Target:
  Latest (end of WAL stream)

Execution Steps:
  [1] Stop Patroni service
  [2] Ensure PostgreSQL is stopped
  [3] Execute pgBackRest restore
  [4] Start PostgreSQL
  [5] Print post-restore guidance

══════════════════════════════════════════════════════════════════

恢复后操作

成功恢复后，请先验证数据，再决定如何恢复服务编排：

# 验证数据
pig pg psql

# 如果恢复到了手工目标，且需要提升为主库
pig pg promote

# 验证完成后再恢复 Patroni 管理
systemctl start patroni

# 如有需要，重新创建 pgBackRest stanza
pig pb create

托管数据目录恢复后，Patroni 保持停止是刻意设计：避免恢复出的旧状态在未经确认前重新进入 HA 编排。

安全机制

恢复目标必填： 不指定 -d/-I/-t/--name/--lsn/--xid 时，命令只显示帮助，不执行 restore。

确认机制： 文本模式下，破坏性恢复会在执行前要求交互式 y/yes 确认；自动化脚本可使用 -y|--yes。结构化输出模式不会交互提示，必须使用 --yes 执行或 --plan 预览。

Patroni 边界： 托管数据目录恢复时，命令会在需要时停止 Patroni，防止 Patroni 在 restore 期间重新拉起 PostgreSQL。恢复后不会自动重入 Patroni。

Side restore 边界： 自定义 -D side restore 必须使用 --no-restart，因为恢复出来的 PostgreSQL 配置仍使用原端口；side restore 不管理 Patroni 或默认 PostgreSQL 服务。

失败边界： 如果 restore 在 Patroni 已停止后失败，Patroni 会保持停止，目标数据目录可能已经部分恢复。修复底层问题后应重新执行 PITR，或先验证恢复状态；不要在未确认前启动 Patroni。如果 restore 已执行但 PostgreSQL 启动失败，同样应先检查 PostgreSQL/pgBackRest 日志并验证数据目录，再决定是否恢复 Patroni 管理。

结构化输出： 结构化执行需要 --yes；--plan 是预览路径。成功执行后的结构化 PITR 结果会把恢复后操作放在 Result envelope 的 next_actions，而不是 data 内部。data 包含 requested_data_dir、effective_data_dir、managed_data_dir 与 side_restore，便于自动化区分用户输入和实际恢复目标。

设计说明

pig pitr 调用 pgBackRest restore，并在本地处理 Patroni/PostgreSQL 停止与可选启动。
pig pitr 不是集群恢复总控，不负责 Patroni failover、rejoin、VIP 或应用流量切换。
需要底层 restore 语义或脚本细粒度控制时，使用 pig pb restore。
需要手工切换 Patroni 集群时，使用 pig pt switchover CLUSTER 或 pig pt failover CLUSTER --candidate MEMBER（v1.6.0 起为 patronictl 原生透传，集群名必填）。

权限执行：

如果当前用户已是 DBSU：直接执行命令
如果当前用户是 root：使用 su - postgres -c 执行
其他用户：使用 sudo -inu postgres -- 执行

平台支持：

此命令专为 Linux 系统设计，依赖 pgBackRest、systemd（托管服务场景）以及 DBSU 可访问的数据目录与日志路径。