这是本节的多页打印视图。
点击此处打印.
返回本页常规视图.
pig 1.5 文档
PostgreSQL 扩展生态包管理器与管理命令行工具
—— Postgres Install Genius，PostgreSQL 生态中缺失的扩展包管理器
PIG 包管理器是一个专门用于安装、管理、构建 PostgreSQL 及其扩展的命令行工具，使用 Go 开发，开箱即用，简单易用，小巧玲珑（约 5MB）。
PIG 包管理器并非重新发明的土鳖轮子，而是 依托 （PiggyBack）现有 Linux 发行版包管理器 （apt/dnf）的一个高级抽象层。
它屏蔽了不同操作系统，不同芯片架构，以及不同 PG 大版本的管理差异，让您用简单的几行命令，就可以完成 PG 内核与 531 个扩展的安装与管理。
PIG 的命令设计同样适合自动化脚本：提供统一的参数风格、清晰的错误提示，以及如 --plan 等预览开关与确认步骤。
请注意：对于扩展安装来说，pig 并非必须组件，您依然可以使用 apt / dnf 等包管理器直接访问 Pigsty PGSQL 仓库。
- 简介：为什么需要专用的 PG 包管理器？
- 上手：快速上手与样例
- 安装：下载、安装、更新 pig
快速上手
使用以下命令即可在您的系统上 安装 PIG 包管理器：
默认安装（Cloudflare CDN）：
curl -fsSL https://repo.pigsty.io/pig | bash
中国镜像：
curl -fsSL https://repo.pigsty.cc/pig | bash
安装完成后，几行命令即可 快速开始。例如，若需安装 PG 18 与相应的 pg_duckdb 扩展：
$ pig repo set # 一次性设置好 Linux, Pigsty + PGDG 仓库（覆盖式！）
$ pig install pg18 # 安装 PostgreSQL 18 内核（原生 PGDG 包）
$ pig install pg_duckdb -v 18 # 安装 pg_duckdb 扩展（针对当前 pg 18）
$ pig install -y postgis timescaledb # 针对当前活跃PG版本，安装多个扩展
$ pig install -y vector # 您可以使用扩展名称（vector）或者扩展包名称（pgvector）来安装扩展！
命令参考
你可以执行 pig help <command> 获取子命令的详细帮助。
扩展管理：
Pigsty 管理：
关于
pig 命令行工具由 Vonng（冯若航 rh@vonng.com）开发，并以 Apache 2.0 许可证开源。
您还可以参考 PIGSTY 项目，提供了包括扩展交付在内的完整 PostgreSQL RDS DBaaS 使用体验。
1 - 上手
快速上手 pig，PostgreSQL 包管理器
下面是一个简单的上手教程，带您体验 PIG 包管理器的核心能力。
简短版本
curl -fsSL https://repo.pigsty.io/pig | bash # 从 Cloudflare 安装 PIG
pig repo set # 一次性设置好 Linux, Pigsty + PGDG 仓库（覆盖式！）
pig install -v 18 -y pg18 pg_duckdb vector # 安装 PG 18 内核，pg_duckdb, pgvector 扩展……
安装
您可以使用以下命令 一键安装 pig：
中国大陆：
curl -fsSL https://repo.pigsty.cc/pig | bash
全球网站（Cloudflare CDN）：
curl -fsSL https://repo.pigsty.io/pig | bash
PIG 二进制包大约 5 MB，在 Linux 上会自动使用 rpm 或 dpkg 安装最新可用版本：
$ curl -fsSL https://repo.pigsty.cc/pig | bash
[INFO] kernel = Linux
[INFO] machine = x86_64
[INFO] package = deb
[INFO] pkg_url = https://repo.pigsty.cc/pkg/pig/v1.5.0/pig_1.5.0-1_amd64.deb
[INFO] download = /tmp/pig_1.5.0-1_amd64.deb
[INFO] downloading pig v1.5.0
curl -fSL https://repo.pigsty.cc/pkg/pig/v1.5.0/pig_1.5.0-1_amd64.deb -o /tmp/pig_1.5.0-1_amd64.deb
######################################################################## 100.0%
[INFO] md5sum = b7d18865090df8c03523c79ec2744e91
[INFO] installing: dpkg -i /tmp/pig_1.5.0-1_amd64.deb
(Reading database ... 166001 files and directories currently installed.)
Preparing to unpack /tmp/pig_1.5.0-1_amd64.deb ...
Unpacking pig (1.5.0-1) ...
Setting up pig (1.5.0-1) ...
[INFO] pig v1.5.0 installed successfully
check https://pgext.cloud for details
检查环境
PIG 是一个由 Go 编写的二进制程序，默认安装路径为 /usr/bin/pig，pig version 会打印版本信息：
$ pig version
pig version 1.5.0 linux/amd64
使用 pig status 命令，会打印当前环境的状态，操作系统代码，PG 的安装情况，仓库的可访问性与延迟。
$ pig status
# [Configuration] ================================
Pig Version : 1.5.0
Pig Config : /home/vagrant/.pig/config.yml
Log Level : info
Log Path : stderr
# [OS Environment] ===============================
OS Distro Code : u26
OS OSArch : arm64
OS Package Type : deb
OS Vendor ID : ubuntu
OS Version : 26
OS Version Full : 26.04
OS Version Code : resolute
# [PG Environment] ===============================
Installed:
* PostgreSQL 18.4 (Ubuntu 18.4-1.pgdg26.04+1) 72 Extensions
Active:
PG Version : PostgreSQL 18.4 (Ubuntu 18.4-1.pgdg26.04+1)
Config Path : /usr/lib/postgresql/18/bin/pg_config
Binary Path : /usr/lib/postgresql/18/bin
Library Path : /usr/lib/postgresql/18/lib
Extension Path : /usr/share/postgresql/18/extension
# [Pigsty Environment] ===========================
Inventory Path : Not Found
Pigsty Home : Not Found
# [Network Conditions] ===========================
pigsty.cc ping ok: 376 ms
pigsty.io ping ok: 1270 ms
Internet Access : true
Pigsty Repo : pigsty.io
Inferred Region : china
Latest Pigsty Ver : v4.4.0
自动化建议
对于生产环境恢复任务，建议先使用 --plan 预览 PITR 执行计划，再决定是否实际执行：
pig pitr -d --plan # 仅预览恢复步骤，不执行
pig pitr -d -y # 跳过确认（自动化场景）
列出扩展
使用 pig ext list 命令，可以打印内置的 PG 扩展数据目录。
$ pig ext list
✓ Found 531 extensions
Name Status Version Cate Flags License Repo PGVer Package Description
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
timescaledb available 2.28.2 TIME -dslt- Timescale PIGSTY 15-18 postgresql-18-timescaledb-tsl Enables scalable inserts and complex queries for time-series dat
timescaledb_toolkit available 1.23.0 TIME -ds--- Timescale PIGSTY 15-18 postgresql-18-timescaledb-toolkit Library of analytical hyperfunctions, time-series pipelining, an
timeseries available 0.2.1 TIME -d---- PostgreSQL PIGSTY 14-18 postgresql-18-pg-timeseries Convenience API for time series stack
periods available 1.2.3 TIME -ds--- PostgreSQL PGDG 14-18 postgresql-18-periods Provide Standard SQL functionality for PERIODs and SYSTEM VERSIO
........
pg_bulkload available 3.1.23 ETL bds--- BSD 3-Clause PIGSTY 14-18 postgresql-18-pg-bulkload pg_bulkload is a high speed data loading utility for PostgreSQL
test_decoding available - ETL --s--x PostgreSQL CONTRIB 14-18 postgresql-18 SQL-based test/example module for WAL logical decoding
pgoutput available - ETL --s--- PostgreSQL CONTRIB 14-18 postgresql-18 Logical Replication output plugin
(531 Rows)
所有的扩展元数据都在一份名为 extension.csv 的数据文件中定义，
这份文件会随着 pig 版本发布不断更新，您可以直接使用 pig ext reload 命令更新这份数据文件。
更新后的文件会默认放置于 ~/.pig/extension.csv 中，您可以查阅与更改；在线最新版目录可在 pigsty.io/ext/data/extension.csv 获取。
添加仓库
要想安装扩展，首先需要添加上游仓库。pig repo 可用于管理 Linux APT/YUM/DNF 软件仓库配置。
您可以使用简单粗暴直接的版本 pig repo set 覆盖式写入现有仓库配置，该命令确保系统中只存在必须的仓库配置：
pig repo set # 一次性配置好所有仓库，包括 Linux 系统仓库，PGDG，PIGSTY (PGSQL+INFRA) 仓库
警告：pig repo set 会备份并清理现有的仓库配置，然后添加所需的仓库，实现 Overwrite 语义，请务必注意！
或者选择使用温和的 pig repo add 添加所需的仓库：
pig repo add pgdg pigsty # 添加 PGDG 官方仓库 和 PIGSTY 补充仓库
pig repo add pgsql # 【可选】您也可以选择将 PGDG 和 PIGSTY 合在一起，当成一个 "pgsql" 模块整体添加
pig repo update # 更新缓存：apt update / yum makecache
PIG 会检测您的网络环境，并选择使用 Cloudflare 全球 CDN，或者中国境内云 CDN，但您可以通过 --region 参数强制指定区域。
pig repo set --region=china # 使用中国区域镜像仓库加速下载
pig repo add pgdg --region=default --update # 强制指定使用 PGDG 上游仓库
PIG 本身不支持离线安装，您可以自行下载 RPM/DEB 包，拷贝到网络隔离的生产服务器安装。
相关项目 PIGSTY 提供本地软件仓库，支持可以使用 pig 从本地软件仓库安装已经下载好的扩展。
安装 PG
添加仓库后，您可以使用 pig ext add 子命令安装扩展（以及相关软件包）
pig ext add -v 18 -y pgsql timescaledb postgis vector pg_duckdb pg_mooncake # 安装 PG 18 内核与扩展，自动确认
# 该命令会自动执行翻译，将软件包翻译为
INFO[20:34:44] translate alias 'pgsql' to package: postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl
INFO[20:34:44] translate extension 'timescaledb' to package: timescaledb-tsl_18
INFO[20:34:44] translate extension 'postgis' to package: postgis36_18
INFO[20:34:44] translate extension 'vector' to package: pgvector_18
INFO[20:34:44] translate extension 'pg_duckdb' to package: pg_duckdb_18
INFO[20:34:44] translate extension 'pg_mooncake' to package: pg_mooncake_18
INFO[20:34:44] installing packages: dnf install -y postgresql18 postgresql18-server postgresql18-libs postgresql18-contrib postgresql18-plperl postgresql18-plpython3 postgresql18-pltcl timescaledb-tsl_18 postgis36_18 pgvector_18 pg_duckdb_18 pg_mooncake_18
这里使用了 “别名翻译” 机制，将清爽的 PG 内核/扩展 逻辑包名翻译为实际的 RPM/DEB 列表。如果您不需要别名翻译机制，可以直接使用 apt/dnf 安装，
或者使用变体 pig install 的 -n|--no-translation 参数：
pig install vector # 带有翻译机制，安装当前 PG 18 对应的 pgvector_18 或 postgresql-18-pgvector
pig install vector -n # 关闭翻译机制，安装名为 vector 的日志收集组件（来自 pigsty-infra 仓库）
别名翻译
PostgreSQL 内核与扩展对应着一系列的 RPM/DEB 包，记住这些包是一件麻烦事，所以 pig 提供了许多常用的别名，帮助您简化安装过程：
例如在 EL 系统上， 下面的别名将会被翻译为右侧的对应 RPM 包列表：
pgsql: "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl"
pg18: "postgresql18 postgresql18-server postgresql18-libs postgresql18-contrib postgresql18-plperl postgresql18-plpython3 postgresql18-pltcl"
pg18-client: "postgresql18"
pg18-server: "postgresql18-server postgresql18-libs postgresql18-contrib"
pg18-devel: "postgresql18-devel"
pg18-basic: "pg_repack_18 wal2json_18 pgvector_18"
pg17-mini: "postgresql17 postgresql17-server postgresql17-libs postgresql17-contrib"
pg16-full: "postgresql16 postgresql16-server postgresql16-libs postgresql16-contrib postgresql16-plperl postgresql16-plpython3 postgresql16-pltcl postgresql16-llvmjit postgresql16-test postgresql16-devel"
pg15-main: "postgresql15 postgresql15-server postgresql15-libs postgresql15-contrib postgresql15-plperl postgresql15-plpython3 postgresql15-pltcl pg_repack_15 wal2json_15 pgvector_15"
pg14-core: "postgresql14 postgresql14-server postgresql14-libs postgresql14-contrib postgresql14-plperl postgresql14-plpython3 postgresql14-pltcl"
注意这里的 $v 占位符会被替换为 PG 大版本号，因此当您使用 pgsql 别名时，$v 会被实际替代为 18，17 这样的大版本号。
因此，当您安装 pg18-server 别名时，EL 上实际安装的是 postgresql18-server, postgresql18-libs, postgresql18-contrib，在 Debian / Ubuntu 上安装的是 postgresql-18，pig 会处理好所有细节。
常用 PostgreSQL 别名
EL 使用的别名翻译列表
"pgsql": "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl",
"pgsql-mini": "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib",
"pgsql-core": "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl",
"pgsql-full": "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl postgresql$v-llvmjit postgresql$v-test postgresql$v-devel",
"pgsql-main": "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl pg_repack_$v wal2json_$v pgvector_$v",
"pgsql-client": "postgresql$v",
"pgsql-server": "postgresql$v-server postgresql$v-libs postgresql$v-contrib",
"pgsql-devel": "postgresql$v-devel",
"pgsql-basic": "pg_repack_$v wal2json_$v pgvector_$v",
Debian / Ubuntu 系统使用的别名翻译
"pgsql": "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v",
"pgsql-mini": "postgresql-$v postgresql-client-$v",
"pgsql-core": "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v",
"pgsql-full": "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v postgresql-server-dev-$v",
"pgsql-main": "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v postgresql-$v-repack postgresql-$v-wal2json postgresql-$v-pgvector",
"pgsql-client": "postgresql-client-$v",
"pgsql-server": "postgresql-$v",
"pgsql-devel": "postgresql-server-dev-$v",
"pgsql-basic": "postgresql-$v-repack postgresql-$v-wal2json postgresql-$v-pgvector",
上面这些别名可以直接使用，并通过参数实例化大版本号，也可以使用另一种带有大版本号的别名变体：即将 pgsql 替换为 pg18, pg17, pgxx 等具体大版本号。
当前活跃支持的 PostgreSQL 主版本范围为 14-18，例如对于 PostgreSQL 18，可以直接使用下面这些别名：
pgsql | pg18 | pg17 | pg16 | pg15 | pg14 |
|---|
pgsql | pg18 | pg17 | pg16 | pg15 | pg14 |
pgsql-mini | pg18-mini | pg17-mini | pg16-mini | pg15-mini | pg14-mini |
pgsql-core | pg18-core | pg17-core | pg16-core | pg15-core | pg14-core |
pgsql-full | pg18-full | pg17-full | pg16-full | pg15-full | pg14-full |
pgsql-main | pg18-main | pg17-main | pg16-main | pg15-main | pg14-main |
pgsql-client | pg18-client | pg17-client | pg16-client | pg15-client | pg14-client |
pgsql-server | pg18-server | pg17-server | pg16-server | pg15-server | pg14-server |
pgsql-devel | pg18-devel | pg17-devel | pg16-devel | pg15-devel | pg14-devel |
pgsql-basic | pg18-basic | pg17-basic | pg16-basic | pg15-basic | pg14-basic |
安装扩展
pig 会检测当前系统环境中的 PostgreSQL 安装情况。如果检测到环境中（以 PATH 中的 pg_config 为准）有活跃的 PG 安装，那么 pig 会自动安装对应 PG 大版本所需的扩展，无需您显式指定 PG 大版本。
pig install pg_smtp_client # 更简单
pig install pg_smtp_client -v 18 # 显示指定大版本，更稳定可靠
pig install pg_smtp_client -p /usr/lib/postgresql/16/bin/pg_config # 另一种指定 PG 版本的方式
dnf install pg_smtp_client_18 # 最直接……，但并非所有扩展都这么简单……
提示：如需将特定大版本的 PostgreSQL 内核二进制加入 PATH，可用 pig ext link 命令：
pig ext link pg18 # 创建 /usr/pgsql 软链接，并写入 /etc/profile.d/pgsql.sh
. /etc/profile.d/pgsql.sh # 立即生效，更新 PATH 环境变量
如果你想要安装特定版本的软件，可以使用 name=ver 的语法：
pig ext add -v 18 pgvector=0.7.2 # install pgvector 0.7.2 for PG 18
pig ext add pg16=16.5 # install PostgreSQL 16 with a specific minor version
警告：请注意，目前只有 PGDG YUM 仓库提供扩展历史版本，PIGSTY 仓库与 PGDG APT 仓库都只提供扩展的 最新版本。
显示扩展
pig ext status 命令可以用于显示当前安装的扩展。
$ pig ext status
✓ PostgreSQL 18: 72 extensions installed (3 shown)
PostgreSQL 18: PostgreSQL 18.4 (Ubuntu 18.4-1.pgdg26.04+1)
Binary: /usr/lib/postgresql/18/bin
Extension: /usr/share/postgresql/18/extension
Extension Stat: 3 Installed (PGDG 3, PIGSTY 0) + 69 CONTRIB = 72 Total
Name Version Cate Flags License Repo Package Description
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
pg_repack 1.5.3 ADMIN bds--- PostgreSQL PGDG postgresql-18-repack Reorganize tables in PostgreSQL databases with minimal locks
vector 0.8.4 RAG -ds--r PostgreSQL PGDG postgresql-18-pgvector vector data type and ivfflat and hnsw access methods
wal2json 2.6 ETL --s--x BSD 3-Clause PGDG postgresql-18-wal2json Changing data capture in JSON format
如果您的当前系统路径中找不到 PostgreSQL（以 PATH 中的 pg_config 为准），建议显式通过 -v|-p 指定 PG 大版本号或 pg_config 路径，以避免版本探测歧义。
扫描扩展
pig ext scan 提供更底层的扩展扫描功能，将扫描指定 PostgreSQL 目录下的共享库，从而发现安装了哪些扩展：
$ pig ext scan
Installed:
- PostgreSQL 18.1 (Ubuntu 18.1-1.pgdg24.04+2) 398 Extensions
Active:
PG Version : PostgreSQL 18.1 (Ubuntu 18.1-1.pgdg24.04+2)
Config Path : /usr/bin/pg_config
Binary Path : /usr/lib/postgresql/18/bin
Library Path : /usr/lib/postgresql/18/lib
Extension Path : /usr/share/postgresql/18/extension
Name Version SharedLibs Description Meta
---- ------- ---------- --------------------- ------
timescaledb 2.25.1 Enables scalable inserts and complex queries... module_pathname=$libdir/timescaledb-2.24.0 relocatable=false trusted=true lib=...
timescaledb_toolkit 1.22.0 Library of analytical hyperfunctions... relocatable=false superuser=false module_pathname=$libdir/timescaledb_toolkit lib=...
periods 1.2 Provide Standard SQL functionality for PERIODs module_pathname=$libdir/periods relocatable=false requires=btree_gist lib=periods.so
pg_cron 1.6 Job scheduler for PostgreSQL relocatable=false schema=pg_catalog module_pathname=$libdir/pg_cron lib=pg_cron.so
postgis 3.6.1 PostGIS geometry and geography spatial types... module_pathname=$libdir/postgis-3 relocatable=false lib=postgis-3.so
vector 0.8.1 vector data type and ivfflat and hnsw access... relocatable=true lib=vector.so
pg_duckdb 1.1.0 DuckDB Embedded in Postgres module_pathname=$libdir/pg_duckdb relocatable=false schema=public lib=...
...
容器实战
您可以创建一台全新的虚拟机，或者使用下面的 Docker 容器进行功能测试，创建一个 d13 目录，创建 Dockerfile：
FROM debian:13
USER root
WORKDIR /root/
CMD ["/bin/bash"]
RUN apt update && apt install -y ca-certificates curl && curl https://repo.pigsty.io/pig | bash
docker build -t d13:latest .
docker run -it d13:latest /bin/bash
pig repo set --region=china # 添加中国区域的仓库
pig install -y pg18 # 安装 PGDG 18 内核包
pig install -y postgis timescaledb pgvector pg_duckdb
2 - 简介
为什么我们还需要一个新的包管理器？尤其是针对 Postgres 扩展？
你是否曾因安装或升级 PostgreSQL 扩展而头疼？翻查过时的文档、晦涩难懂的配置脚本，或是在 GitHub 上苦寻分支与补丁？
Postgres 丰富的扩展生态同时意味着复杂的部署流程 —— 在多发行版、多架构环境下尤为棘手。而 PIG 可以为您解决这些烦恼。
这正是 Pig 诞生的初衷。Pig 由 Go 语言开发，致力于一站式管理 Postgres 及其 531 个扩展。
无论是 TimescaleDB、Citus、PGVector，还是 30+ Rust 扩展，亦或 自建 Supabase 所需的全部组件 —— Pig 统一的 CLI 让一切触手可及。
它彻底告别源码编译与杂乱仓库，直接提供版本对齐的 RPM/DEB 包，完美兼容 Debian、Ubuntu、RedHat 等主流发行版，支持 x86 与 Arm 架构，无需猜测，无需折腾。
Pig 并非重复造轮子，而是充分利用系统原生包管理器（APT、YUM、DNF），严格遵循 PGDG 官方 打包规范，确保无缝集成。
你无需在"标准做法"与"快捷方式"之间权衡；Pig 尊重现有仓库，遵循操作系统最佳实践，与现有仓库和软件包和谐共存。
如果你的 Linux 系统和 PostgreSQL 大版本不在 支持的列表 中，你还可以使用 pig build 直接针对特定组合编译扩展。
想让你的 Postgres 如虎添翼、远离繁琐？欢迎访问 PIG 官方文档 获取文档、指南，并查阅庞大的 扩展列表，
让你的本地 Postgres 数据库一键进化为全能的多模态数据中台。
如果说 Postgres 的未来是无可匹敌的可扩展性，那么 Pig 就是帮你解锁它的神灯。毕竟，从没有人抱怨 “扩展太多”。
自动化友好
PIG 的命令体系可直接用于自动化脚本：参数风格统一、输出稳定，并在高风险操作中提供 --plan 预览或确认步骤，减少误操作风险。
《ANNOUNCE pig: The Postgres Extension Wizard》
Linux 兼容性
PIG 与 Pigsty 扩展仓库支持以下 Linux 发行版和 PostgreSQL 版本组合：
| OS 代码 | 厂商 | 大版本 | 小版本 | 全名 | PG 版本 | 备注 |
|---|
el7.x86_64 | EL | 7 | 7.9 | CentOS 7 x86 | 13-15 | EOL |
el8.x86_64 | EL | 8 | 8.10 | RockyLinux 8 x86 | 14-18 | 即将 EOL |
el8.aarch64 | EL | 8 | 8.10 | RockyLinux 8 ARM | 14-18 | 即将 EOL |
el9.x86_64 | EL | 9 | 9.7 | RockyLinux 9 x86 | 14-18 | ✅ |
el9.aarch64 | EL | 9 | 9.7 | RockyLinux 9 ARM | 14-18 | ✅ |
el10.x86_64 | EL | 10 | 10.1 | RockyLinux 10 x86 | 14-18 | ✅ |
el10.aarch64 | EL | 10 | 10.1 | RockyLinux 10 ARM | 14-18 | ✅ |
d11.x86_64 | Debian | 11 | 11.11 | Debian 11 x86 | 14-18 | EOL |
d11.aarch64 | Debian | 11 | 11.11 | Debian 11 ARM | 14-18 | EOL |
d12.x86_64 | Debian | 12 | 12.13 | Debian 12 x86 | 14-18 | ✅ |
d12.aarch64 | Debian | 12 | 12.13 | Debian 12 ARM | 14-18 | ✅ |
d13.x86_64 | Debian | 13 | 13.3 | Debian 13 x86 | 14-18 | ✅ |
d13.aarch64 | Debian | 13 | 13.3 | Debian 13 ARM | 14-18 | ✅ |
u22.x86_64 | Ubuntu | 22 | 22.04.5 | Ubuntu 22.04 x86 | 14-18 | ✅ |
u22.aarch64 | Ubuntu | 22 | 22.04.5 | Ubuntu 22.04 ARM | 14-18 | ✅ |
u24.x86_64 | Ubuntu | 24 | 24.04.4 | Ubuntu 24.04 x86 | 14-18 | ✅ |
u24.aarch64 | Ubuntu | 24 | 24.04.4 | Ubuntu 24.04 ARM | 14-18 | ✅ |
u26.x86_64 | Ubuntu | 26 | 26.04.0 | Ubuntu 26.04 x86 | 14-18 | ✅ |
u26.aarch64 | Ubuntu | 26 | 26.04.0 | Ubuntu 26.04 ARM | 14-18 | ✅ |
说明：
- EL 指 RHEL 兼容发行版，包括 RHEL、CentOS、RockyLinux、AlmaLinux、OracleLinux 等
- EOL 表示该操作系统已经或即将停止支持，建议升级到更新版本
- ✅ 表示完整支持，推荐使用
- PG 版本 14-18 表示支持 PostgreSQL 14、15、16、17、18 五个大版本
3 - 安装
如何下载与安装 pig 包管理器
脚本安装
安装 pig 最简单的方式是运行以下安装脚本：
默认安装（Cloudflare CDN）：
curl -fsSL https://repo.pigsty.io/pig | bash
中国镜像：
curl -fsSL https://repo.pigsty.cc/pig | bash
该脚本会从 Pigsty 软件仓库 下载最新版 pig 的 RPM / DEB 包，并通过 rpm 或 dpkg 进行安装。
脚本安装面向 Linux x86_64 / aarch64 的 RPM / DEB 系发行版；macOS 可使用发布压缩包中的二进制。
指定版本
您可以指定特定版本进行安装，将版本号作为参数传入即可：
默认安装（Cloudflare CDN）：
curl -fsSL https://repo.pigsty.io/pig | bash -s 1.5.0
中国镜像：
curl -fsSL https://repo.pigsty.cc/pig | bash -s 1.5.0
发布产物下载
你也可以直接从 Pigsty 软件仓库下载 pig 安装包（RPM/DEB/ 压缩包）。当前 v1.5.0 发布产物位于：
latest
└── v1.5.0
├── pig_1.5.0-1_amd64.deb
├── pig_1.5.0-1_arm64.deb
├── pig-1.5.0-1.aarch64.rpm
├── pig-1.5.0-1.x86_64.rpm
├── pig-v1.5.0.linux-amd64.tar.gz
├── pig-v1.5.0.linux-arm64.tar.gz
├── pig-v1.5.0.darwin-amd64.tar.gz
└── pig-v1.5.0.darwin-arm64.tar.gz
将其解压后，将二进制文件放入您的 PATH 系统路径中即可。
仓库安装
pig 软件位于 pigsty-infra 仓库中。你可以将该仓库添加到操作系统后，使用操作系统的包管理器进行安装：
YUM
对于 RHEL，RockyLinux，CentOS，Alma Linux，OracleLinux 等 EL 系发行版：
sudo tee /etc/yum.repos.d/pigsty-infra.repo > /dev/null <<-'EOF'
[pigsty-infra]
name=Pigsty Infra for $basearch
baseurl=https://repo.pigsty.io/yum/infra/$basearch
enabled = 1
gpgcheck = 0
module_hotfixes=1
EOF
sudo yum makecache;
sudo yum install -y pig
APT
对于 Debian，Ubuntu 等 DEB 系发行版：
sudo tee /etc/apt/sources.list.d/pigsty-infra.list > /dev/null <<EOF
deb [trusted=yes] https://repo.pigsty.io/apt/infra generic main
EOF
sudo apt update;
sudo apt install -y pig
更新
若要将现有 pig 版本升级至最新可用版本，可以使用以下命令：
pig update # 将 pig 自身升级到最新版
若要将现有 pig 的扩展数据升级至最新可用版本，可以使用以下命令：
pig ext reload # 将 pig 扩展数据更新至最新版本
卸载
apt remove -y pig # Debian / Ubuntu 等 Debian 系统
yum remove -y pig # RHEL / CentOS / RockyLinux 等 EL 系发行版
rm -rf /usr/bin/pig # 若直接使用二进制安装，删除二进制文件即可
构建
你也可以自行构建 pig。pig 使用 Go 语言开发，构建非常容易，源码托管在 github.com/pgsty/pig
git clone https://github.com/pgsty/pig.git; cd pig
go mod download
make build
所有 RPM / DEB 包都通过 GitHub CI/CD 流程使用 goreleaser 自动化构建。
5 - 命令参考
6 - pig
pig CLI 命令参考概览
pig CLI 提供了全面的工具集，用于管理 PostgreSQL 安装、扩展、软件仓库以及从源码构建扩展。使用 pig help <command> 查看命令文档。
概览
pig - PostgreSQL 的 Linux 包管理器
Usage:
pig [command]
Examples:
pig repo add -ru # 覆盖现有仓库并更新缓存
pig install pg18 # 安装 PostgreSQL 18 PGDG 软件包
pig install pg_duckdb # 安装指定的 PostgreSQL 扩展
pig install pgactive -v 18 # 为特定 PG 版本安装扩展
访问 https://pigsty.io/ext/ 获取详情
PostgreSQL Extension Manager
build 构建 Postgres 扩展
ext 管理 PostgreSQL 扩展 (pgext)
repo 管理 Linux 软件仓库 (apt/dnf)
Pigsty Management Commands
do 运行管理任务
pg 管理本地 PostgreSQL 服务器与数据库
pt 使用 patronictl 管理 Patroni 集群
pb 管理 pgBackRest 备份与恢复
pe 管理 pg_exporter 与监控指标
pitr 编排式时间点恢复
sty 管理 Pigsty 安装
context 显示环境上下文快照
Additional Commands:
completion 生成指定 shell 的自动补全脚本
help 获取任何命令的帮助信息
install 使用原生包管理器安装软件包
status 显示环境状态
update 升级 pig 自身
version 显示 pig 版本信息
Flags:
--debug 启用调试模式
-h, --help 获取帮助信息
-H, --home string Pigsty 主目录路径
-i, --inventory string 配置清单路径
--log-level string 日志级别: debug, info, warn, error, fatal, panic (默认 "info")
--log-path string 日志文件路径，默认为终端输出
-o, --output string 输出格式：text, yaml, json, json-pretty（默认 "text"）
使用 "pig [command] --help" 获取命令的详细信息。
pig repo
管理 PostgreSQL 软件包的 APT/YUM 仓库，详情请参考 pig repo
pig repo list # 列出可用仓库
pig repo info pgdg # 显示仓库详情
pig repo status # 检查当前仓库状态
pig repo add pgdg pigsty -u # 添加仓库
pig repo rm old-repo # 移除仓库
pig repo update # 更新软件包缓存
pig repo create /www/pigsty # 创建本地仓库
pig repo cache # 创建离线包
pig repo boot # 从离线包引导
pig ext
管理 PostgreSQL 扩展和内核包，详情请参考 pig ext
pig ext list duck # 搜索扩展
pig ext info pg_duckdb # 扩展详情
pig ext status # 显示已安装的扩展
pig ext add pg_duckdb -y # 安装扩展
pig ext rm old_extension # 移除扩展
pig ext update # 更新扩展
pig ext scan # 扫描已安装的扩展
pig ext import pg_duckdb # 下载以供离线使用
pig ext link 17 # 链接 PG 版本到 PATH
pig ext reload # 刷新扩展目录
pig build
从源码构建 PostgreSQL 扩展，详情请参考 pig build
# 环境设置
pig build spec # 初始化构建规格
pig build repo # 设置仓库
pig build tool # 安装构建工具
pig build rust -y # 强制重装 Rust（默认不重装）
pig build pgrx # 安装 PGRX 框架
# 构建扩展
pig build pkg citus # 完整构建流程 = get + dep + ext
pig build get citus # 下载源码
pig build dep citus # 安装依赖
pig build ext citus # 构建包
pig install
使用系统原生包管理器安装软件包，并对 PostgreSQL 内核、扩展及常用别名做包名翻译。需要直接传递系统包名时，可使用 -n/--no-translation。
pig install pg_duckdb # 安装扩展并自动翻译包名
pig install pg18 # 安装 PostgreSQL 18 内核包组
pig install nginx htop vim # 安装多个系统包
pig install unknown-package -n # 禁用翻译，按原始包名安装
pig install pg18 --plan # 预览安装计划
pig install pg_vector -y # 自动确认安装
pig sty
安装 Pigsty 发行版，详情请参考 pig sty
pig sty init # 安装 Pigsty 到 ~/pigsty
pig sty boot # 安装 Ansible 依赖
pig sty conf # 生成配置
pig sty deploy # 运行部署 playbook
pig context
输出环境上下文快照，覆盖主机、PostgreSQL、Patroni、pgBackRest 与已安装扩展。该命令适合排障和自动化脚本快速了解当前节点状态。
pig context # 文本输出
pig context -o json # JSON 输出
pig context -m postgres # 只输出 PostgreSQL 模块（默认包含 host）
pig context -m postgres,!host # 排除 host 模块
pig pg
管理本地 PostgreSQL 服务器，详情请参考 pig pg
pig pg init # 初始化数据目录
pig pg start # 启动 PostgreSQL
pig pg stop # 停止 PostgreSQL
pig pg status # 查看状态
pig pg psql mydb # 连接数据库
pig pg ps # 查看当前连接
pig pg vacuum mydb # 清理数据库
pig pg tune -p olap # 生成调优参数
pig pg fork dev # 创建本地一次性物理副本
pig pg fork list # 列出本地 fork
pig pg log tail # 实时查看日志
pig pt
管理 Patroni HA 集群，详情请参考 pig pt
pig pt list # 列出集群成员
pig pt config show # 显示集群配置
pig pt config set ttl=60 # 修改集群配置
pig pt status # 查看服务状态
pig pt log -f # 实时查看日志
pig pb
管理 pgBackRest 备份与恢复，详情请参考 pig pb
pig pb info # 显示备份信息
pig pb ls # 列出所有备份
pig pb backup # 创建备份
pig pb backup full # 全量备份
pig pb restore -d # 恢复到最新
pig pb restore -t "2025-01-01" # 恢复到指定时间
pig pb log tail # 实时查看日志
pig pitr
执行编排式时间点恢复（PITR），详情请参考 pig pitr
pig pitr -d # 恢复到最新数据
pig pitr -t "2025-01-01 12:00:00+08" # 恢复到指定时间
pig pitr -I # 恢复到备份一致性点
pig pitr -d --plan # 显示执行计划（不实际执行）
pig pitr -d -y # 跳过确认（自动化）
7 - pig repo
使用 pig repo 子命令管理软件仓库
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 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。
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
显示系统上的当前仓库配置。
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 # 使用中国镜像
选项：
-r|--remove：添加新仓库前移除现有仓库-u|--update：添加仓库后运行包缓存更新--region <region>：使用区域镜像仓库（default / china / europe）
| 平台 | 模块位置 |
|---|
| 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 # 使用中国镜像
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
更新包管理器缓存以反映仓库更改。
| 平台 | 等效命令 |
|---|
| EL | dnf makecache |
| Debian | apt update |
repo create
为离线安装创建本地包仓库。
pig repo create # 在默认位置创建 (/www/pigsty)
pig repo create /srv/repo # 在自定义位置创建
| 平台 | 依赖软件 |
|---|
| EL | createrepo_c |
| Debian | dpkg-dev |
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.yml 中。
8 - pig ext
使用 pig ext 子命令管理 PostgreSQL 扩展
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 # 自动确认更新
选项：
-v|--version：指定 PG 大版本-y|--yes：自动确认更新
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 null # 取消当前 PostgreSQL 链接
pig ext link none # null / none / nil / nop / no 均可取消链接
该命令会创建 /usr/pgsql 软链接，并写入 /etc/profile.d/pgsql.sh。
ext reload
刷新扩展元数据。
更新后的文件会放置于 ~/.pig/extension.csv 中。
9 - pig build
使用 pig build 子命令从源码构建扩展
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 tool [mini|full|...] # init build toolset
pig build rust [-y] # install Rust toolchain
pig build pgrx [-v <ver>] # 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 repo set -ru 初始化构建所需仓库：移除旧仓库、添加所需仓库并更新包缓存。
安装必要的开发工具和编译器。
pig build tool # 安装默认工具集
pig build tool mini # 最小工具集
pig build tool full # 完整工具集
pig build tool rust # 添加 Rust 开发工具
工具包：
- 最小（
mini）： GCC/Clang 编译器、Make 和构建必需品、PostgreSQL 开发头文件、基本库 - 默认： 所有最小工具、额外编译器（g++、clang++）、开发库、打包工具（rpmbuild、dpkg-dev）
- 完整（
full）： 所有默认工具、语言特定工具（Python、Perl、Ruby 开发）、高级调试工具、性能分析工具
build rust
安装 Rust 编程语言工具链，基于 Rust 的扩展所需。
pig build rust # 带确认安装
pig build rust -y # 强制重新安装 Rust 工具链
安装内容： Rust 编译器（rustc）、Cargo 包管理器、Rust 标准库、开发工具。
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 参数
前提条件： 必须先安装 Rust 工具链、PostgreSQL 开发头文件。
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 # 同时下载 PostgreSQL 与 spock 源码
pig build get onesparse # 同时下载 onesparse、graphblas、lagraph
当前常见的特殊源码 alias 包括：babelfishpg / babelfish、agensgraph / agentsgraph、oriolepg / orioledb、cloudberry、pgedge、pdu、pgdog、rdkit、onesparse、libfepgutils。
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 中国镜像下载源码
选项：
--pg：指定一个或多个 PostgreSQL 大版本-s|--symbol：构建调试符号包（仅 RPM）-m|--mirror：下载源码时优先使用 pigsty.cc 镜像
常见工作流
工作流 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 |
10 - pig sty
使用 pig sty 子命令管理 Pigsty 安装
pig 也可作为 Pigsty 的命令行工具使用 —— 这是一款开箱即用的免费 PostgreSQL RDS 解决方案。
它为你的 PostgreSQL 集群带来高可用（HA）、PITR、监控、基础设施即代码（IaC）以及丰富的扩展支持。
pig sty - Init (Download), Bootstrap, Configure, and Deploy Pigsty
pig sty init [-pfvd] # install pigsty (~/pigsty by default)
pig sty boot [-rpk] # install ansible and prepare offline pkg
pig sty conf [-cvrsoxnpg --raw] # configure pigsty and generate config
pig sty deploy # use pigsty to deploy everything (CAUTION!)
pig sty get # download pigsty source tarball
pig sty list # list available pigsty versions
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 | 安装 Ansible 依赖 | 需要 sudo 或 root 权限 |
sty conf | 生成配置 | |
sty deploy | 运行部署 playbook | |
sty list | 列出可用 Pigsty 版本 | |
sty get | 下载 Pigsty 源码压缩包 | |
快速入门
你可以使用 pig sty 子命令在当前节点引导部署 Pigsty。
pig sty init # 安装 Pigsty 到 ~/pigsty
pig sty boot # 安装 Ansible 依赖
pig sty conf # 生成配置
pig sty deploy # 运行部署 playbook
详细入门指南请参阅：https://pigsty.io/docs/setup/install/
sty init
下载并安装 Pigsty 发行版到 ~/pigsty 目录。
pig sty init # 使用最新版本安装到 ~/pigsty
pig sty init -f # 安装并覆盖已有 pigsty 目录
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 目录-v|--version：pigsty 版本号-d|--dir：下载目录（默认 “/tmp”）
sty boot
安装 Ansible 及其依赖。
pig sty boot # 安装 Ansible
pig sty boot -r china # 使用中国区域镜像
pig sty boot -k # 保留已有仓库
pig sty boot -p /path/to/pkg # 指定离线包路径
选项：
-r|--region：区域（default, china, europe…）-p|--path：离线包路径-k|--keep：保留已有仓库
详见：https://pigsty.io/zh/docs/setup/offline/#bootstrap
sty conf
使用 ./configure 配置 Pigsty，生成配置文件。
pig sty conf # 使用默认 meta.yml 配置
pig sty conf -g # 生成随机密码（推荐！）
pig sty conf -c rich # 使用 conf/rich.yml 模板（包含更多扩展）
pig sty conf -c ha/full # 使用 conf/ha/full.yml 4 节点高可用模板
pig sty conf -c slim # 使用 conf/slim.yml 模板（最小化安装）
pig sty conf -c supabase # 使用 conf/supabase.yml 模板（自托管）
pig sty conf -v 18 -c rich # 使用 conf/rich.yml 模板，PostgreSQL 18
pig sty conf -r china -s # 使用中国区镜像源，跳过 IP 探测
pig sty conf -x # 从环境变量写入代理配置到配置文件
pig sty conf -c full -g -O ha.yml # 完整 HA 模板，随机密码输出到 ha.yml
pig sty conf --raw # 使用旧版 shell configure 工作流
选项：
-c|--conf：配置模板名称（meta/rich/slim/full/supabase/…）--ip：主节点 IP 地址-v|--version：PostgreSQL 主版本（18/17/16/15/14；19 beta 可显式指定）-r|--region：上游仓库区域（default/china/europe）-O|--output-file：输出配置文件路径（默认：pigsty.yml）-s|--skip：跳过 IP 探测-p|--port：SSH 端口-x|--proxy：从环境变量写入代理配置-n|--non-interactive：非交互模式-g|--generate：生成随机默认密码（推荐！）--raw：使用旧版 shell configure 工作流
详见：https://pigsty.io/docs/setup/install/#configure
sty deploy
使用 deploy.yml 剧本部署 Pigsty。
pig sty deploy # 执行 deploy.yml（如果找不到则使用 install.yml）
pig sty install # 与 deploy 相同（向后兼容）
pig sty d # 短别名
pig sty de # 短别名
pig sty ins # 短别名
此命令从您的 Pigsty 安装目录执行 deploy.yml 剧本。为保持向后兼容性，如果 deploy.yml 不存在但 install.yml 存在，将使用 install.yml 代替。
警告：此操作会修改您的系统。请谨慎使用！
sty list
列出可用的 Pigsty 版本。
sty get
下载 Pigsty 源码压缩包。
pig sty get # 下载最新版本
pig sty get v3.4.0 # 下载指定版本
11 - pig postgres
使用 pig postgres 子命令管理本地 PostgreSQL 服务器
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_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。
12 - pig patroni
使用 pig patroni 子命令管理 Patroni 服务与集群
pig patroni 命令（别名 pig pt）用于管理 Patroni 服务和 PostgreSQL HA 集群。它封装了常用的 patronictl 和 systemctl 操作，提供简化的集群管理体验。
pig pt - Manage Patroni cluster using patronictl commands.
Cluster Operations (via patronictl):
pig pt list [cluster] list cluster members
pig pt restart [member] restart PostgreSQL (rolling restart)
pig pt reload reload PostgreSQL config
pig pt reinit <member> reinitialize a member
pig pt pause pause automatic failover
pig pt resume resume automatic failover
pig pt switchover perform planned switchover
pig pt failover [candidate] perform manual failover
pig pt config <action> manage cluster config (edit|show|set|pg)
Service Management (via systemctl):
pig pt status show comprehensive patroni status
pig pt svc start (pig pt start) start patroni service
pig pt svc stop (pig pt stop) stop patroni service
pig pt svc restart restart patroni service
pig pt svc reload reload patroni service
pig pt svc status show patroni service status
Logs:
pig pt log [-f] [-n 50] view patroni logs
pig pt log tail [-n 50] follow patroni logs
pig pt log show [-n 50] show patroni log snapshot
pig pt log grep <pattern> search patroni logs
pt start / pt stop 是 pt svc start / pt svc stop 的隐藏快捷入口；pt svc 是显式的 Patroni 守护进程管理入口。
短参数契约：如果命令作用域内没有冲突，--wait 必须提供 -w 缩写。当前适用于 pt reinit、pt pause、pt resume；pt list -w 保留为该命令自己的刷新间隔参数。
切换前置检查契约：pt switchover 与 pt failover 在执行或要求确认前，会通过与 pig pt list / pig pt config show 相同的结构化接口读取当前拓扑，确认集群名、当前 Leader、候选从库以及 Patroni pause 状态。如果集群处于 pause 模式，pig 会拒绝切换并提示先执行 pig pt resume。
命令概览
集群操作（patronictl 封装）：
以下命令用于通过 Patroni 管理 PostgreSQL 集群。
| 命令 | 缩写 | 描述 | 实现方式 |
|---|
pt list | ls | 列出集群成员 | patronictl list -e -t |
pt restart | rs | 重启 PostgreSQL 实例 | patronictl restart |
pt reload | rl | 重载 PostgreSQL 配置 | patronictl reload |
pt reinit | ri | 重新初始化成员 | patronictl reinit |
pt switchover | so | 计划内主从切换 | patronictl switchover |
pt failover | fo | 手动故障切换 | patronictl failover |
pt pause | p | 暂停自动故障切换 | patronictl pause |
pt resume | r | 恢复自动故障切换 | patronictl resume |
pt config | c | 查看或修改集群配置 | patronictl show-config / edit-config |
服务子命令（pt service，封装 systemctl）：
以下命令通过 systemctl 管理 Patroni 服务本身。
| 命令 | 缩写 | 描述 |
|---|
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 | 显示服务状态 |
服务管理（systemctl 封装）：
以下顶层命令用于直接查看或管理 Patroni 服务；其中 pt start / pt stop 是隐藏快捷入口。
| 命令 | 缩写 | 描述 | 实现方式 |
|---|
pt start | up | 启动 Patroni 服务 | systemctl start patroni |
pt stop | dn | 停止 Patroni 服务 | systemctl stop patroni |
pt status | st | 显示综合状态 | systemctl status + ps + patronictl list |
pt log | l | 查看 Patroni 日志 | 读取 Patroni 日志目录中的日志文件 |
快速入门
# 查看集群成员状态
pig pt list # 列出默认集群成员
pig pt list pg-meta # 列出指定集群成员
pig pt list -W # 持续监视模式
pig pt list -w 5 # 每 5 秒刷新一次
# 查看和修改集群配置
pig pt config # 显示当前集群配置（默认 show）
pig pt config set ttl=60 # 修改单个配置项（直接生效）
pig pt config set ttl=60 loop_wait=15 # 修改多个配置项
pig pt config pg max_connections=200 # 修改 PostgreSQL 参数
# 集群运维操作
pig pt restart # 重启所有成员的 PostgreSQL（需要确认）
pig pt restart pg-test-1 # 重启指定成员
pig pt restart --pending # 应用待重启成员（直接执行）
pig pt restart -y # 集群级重启，跳过确认
pig pt switchover # 计划内主从切换
pig pt pause # 暂停自动故障切换
pig pt resume # 恢复自动故障切换
# 管理 Patroni 服务
pig pt status # 查看服务状态
pig pt start # 隐藏快捷入口：等价于 pig pt svc start
pig pt stop # 隐藏快捷入口：等价于 pig pt svc stop
pig pt svc start # 启动服务
pig pt svc stop # 停止服务
pig pt log -f # 实时查看日志
pig pt log grep ERROR # 搜索日志
全局参数
以下参数适用于所有 pig pt 子命令：
| 参数 | 简写 | 说明 |
|---|
--dbsu | -U | 数据库超级用户（默认：$PIG_DBSU 或 postgres） |
集群操作命令
pt list
列出 Patroni 集群成员状态。该命令封装了 patronictl list，并默认添加 -e（扩展输出）和 -t（显示时间戳）参数。
pig pt list # 列出默认集群成员
pig pt list pg-meta # 列出指定集群
pig pt list -W # 持续监视模式
pig pt list -w 5 # 每 5 秒刷新一次
pig pt list -w 0.5 # 每 0.5 秒刷新一次
pig pt list pg-test -W -w 3 # 监视 pg-test 集群，3 秒刷新
选项：
| 参数 | 简写 | 说明 |
|---|
--watch | -W | 启用持续监视模式 |
--interval | -w | 监视刷新间隔（秒，支持 0.5 这类小数） |
watch 模式使用实时 patronictl 透传输出，不能与 -o json / -o yaml 结构化输出一起使用；结构化输出会返回 CodePtWatchModeUnsupported。
pt restart
通过 Patroni 重启 PostgreSQL 实例。这会触发 PostgreSQL 的滚动重启，而非重启 Patroni 守护进程本身。
pig pt restart # 重启所有成员（交互式）
pig pt restart pg-test-1 # 重启指定成员
pig pt restart -y # 集群级重启，跳过确认
pig pt restart --role=replica # 仅重启从库
pig pt restart --pending # 重启待重启的成员
pig pt restart --plan # 预览执行计划
选项：
| 参数 | 简写 | 说明 |
|---|
--yes | -y | 跳过确认 |
--role | -r | 按角色筛选（leader/replica/any） |
--pending | -p | 仅重启待重启的成员 |
--plan | | 仅显示执行计划 |
pt restart 是条件确认：指定单个成员或使用 --pending 时直接执行；未指定成员的集群级滚动重启需要确认，结构化输出中需要显式 --yes。
底层 patronictl restart 始终由 pig 传入 --force，不会再触发 patronictl 自己的交互提示。
pt reload
通过 Patroni 重载 PostgreSQL 配置。这会触发所有成员执行配置重载。
pt reinit
重新初始化集群成员。这会从主库重新同步数据。
pig pt reinit pg-test-1 # 重新初始化指定成员
pig pt reinit pg-test-1 -y # 跳过确认
pig pt reinit pg-test-1 -w # 等待完成
pig pt reinit pg-test-1 --plan # 预览执行计划
选项：
| 参数 | 简写 | 说明 |
|---|
--yes | -y | 跳过确认 |
--wait | -w | 等待重新初始化完成 |
--plan | | 仅显示执行计划 |
警告： 此操作会删除目标成员的所有数据并重新同步。文本模式会要求确认；JSON/YAML 执行模式需要显式 --yes。
pt switchover
通过 Patroni 执行计划内的主从切换。（命令别名：so）
pig pt switchover # 交互式切换
pig pt switchover -y # 跳过确认
pig pt switchover -l pg-1 -c pg-2 # 指定当前主库和新主库
pig pt switchover -s "2026-07-01T12:00:00" # 定时切换
pig pt switchover --plan # 预览执行计划
pig pt so -c pg-test-1 -y # 无需确认直接切换至 pg-test-1 实例
选项：
| 参数 | 简写 | 说明 |
|---|
--yes | -y | 跳过确认 |
--leader | -l | 指定当前主库 |
--candidate | -c | 指定候选新主库 |
--scheduled | -s | 定时切换时间 |
--plan | | 仅显示执行计划 |
相比 patronictl 命令行，pig 会从 /etc/patroni/patroni.yml 中解析并填充集群 scope，避免用户手动输入集群名称。
执行或确认前，pig 会读取当前拓扑：集群名、当前 Leader、候选从库以及 pause 状态。如果集群已经 pause，命令会拒绝执行并提示先运行 pig pt resume。
如果未指定 --candidate，pig 不会自行挑选实例，而是将候选选择交给 patronictl / Patroni；确认提示会说明“将 leadership 转移给 Patroni 选择的最适格从库”，并列出当前观察到的候选成员。需要指定新主实例时，使用 --candidate/-c。
pt failover
执行手动故障切换。用于主库不可用时强制切换。（命令别名：fo）
与 switchover 不同，failover 不要求当前主库可用，但您 必须 指定一个候选新主库。候选可以通过 --candidate/-c 指定，也可以作为唯一位置参数传入：pig pt failover <member>。
pig pt failover --candidate pg-2 # 交互式故障切换
pig pt failover pg-2 # 位置参数形式，等效于 -c pg-2
pig pt failover -c pg-2 -y # 跳过确认
pig pt failover -c pg-2 --plan # 预览执行计划
pig pt fo pg-test-2 -y # 简写 + 确认
选项：
| 参数 | 简写 | 说明 |
|---|
--yes | -y | 跳过确认 |
--candidate | -c | 指定候选新主库；也可使用位置参数 |
--plan | | 仅显示执行计划 |
执行或确认前，pig 会读取当前拓扑并检查 pause 状态。如果集群已经 pause，命令会拒绝执行并提示先运行 pig pt resume。确认提示会包含集群名、当前 Leader、指定候选新主库以及当前观察到的候选成员，并保留故障切换可能丢数据的警告。
pt pause
暂停 Patroni 的自动故障切换，进入维护模式，防止在维护期间触发故障切换。
如果集群已经处于维护模式，则该命令会报错。
pig pt pause # 暂停自动故障切换
pig pt pause -w # 等待确认
选项：
使用场景： 在执行维护操作（如大版本升级、存储迁移）时暂停自动故障切换，防止误触发。
pt resume
恢复 Patroni 的自动故障切换，退出维护模式。
如果集群未处于维护模式，则该命令会报错。
pig pt resume # 恢复自动故障切换
pig pt resume -w # 等待确认
选项：
pt config
显示或修改集群配置。show 显示当前配置，set 修改 Patroni 动态配置，pg 修改 PostgreSQL 参数。
pig pt config show # 显示当前集群配置
pig pt config edit # 交互式编辑配置
pig pt config set ttl=60 # 设置 TTL 为 60 秒
pig pt config set ttl=60 loop_wait=15 # 同时修改多个配置项
pig pt config pg max_connections=200 # 修改 PostgreSQL 参数
pig pt config set ttl=60 --plan # 预览配置修改
子命令：
| 子命令 | 说明 |
|---|
show | 显示当前配置 |
edit | 交互式编辑配置 |
set key=value | 直接设置配置项 |
pg key=value | 设置 PostgreSQL 参数 |
选项：
| 参数 | 说明 |
|---|
--plan | 对 set / pg 操作仅显示执行计划 |
当你修改 Patroni 本身的配置参数时，需要使用 pig pt config set k=v 命令。set 与 pg 都要求参数是 key=value 形式，非 key=value token 会被拒绝，而不是静默忽略。edit 是交互式操作，不支持结构化输出。
| 配置项 | 说明 | 默认值 |
|---|
ttl | Leader 锁的生存时间（秒） | 30 |
loop_wait | 主循环休眠时间（秒） | 10 |
retry_timeout | DCS 和 PostgreSQL 操作超时（秒） | 10 |
maximum_lag_on_failover | 故障切换时允许的最大延迟（字节） | 1048576 |
当你修改 PostgreSQL 本身的配置参数时，需要使用 pig pt config pg k=v 命令。该命令会识别已知的 postmaster-context 参数；若修改需要重启的 PostgreSQL 参数，计划和结构化结果会给出 pig pt list 与 pig pt restart --pending 后续动作。
注意： 此命令修改的是存储在 DCS（如 etcd）中的集群动态配置，而非本地配置文件 /etc/patroni/patroni.yml。
例如：
pig pt config set ttl=60 --plan
pig pt config pg shared_buffers=4GB --plan
服务管理命令
pt start
启动 Patroni 服务。
pig pt start # 启动 Patroni 服务
pig pt up # 别名
等效于执行 sudo systemctl start patroni。
pt stop
停止 Patroni 服务。
pig pt stop # 停止 Patroni 服务
pig pt dn # 别名
等效于执行 sudo systemctl stop patroni。
注意： 停止 Patroni 服务会导致该节点上的 PostgreSQL 实例也被停止（取决于 Patroni 配置）。
pt status
显示 Patroni 服务的综合状态，包括：
- systemd 服务状态
- Patroni 进程信息
- 集群成员状态
pt log
查看 Patroni 服务日志。日志目录默认从 /etc/patroni/patroni.yml 的 log.dir 读取，未配置时回退到 /pg/log/patroni；也可用 --log-dir 显式指定。只有 pt log 与 pt log show 支持 -o json 输出 JSONL；日志快照不支持 yaml 与 json-pretty，follow/tail/grep 不支持结构化输出。
pig pt log # 显示最近 50 行日志
pig pt log -f # 实时跟踪日志输出
pig pt log show # 显示最近日志
pig pt log tail # 跟踪日志
pig pt log grep ERROR # 搜索日志
pig pt log -n 100 # 显示最近 100 行日志
pig pt log -f -n 200 # 显示最近 200 行并持续跟踪
子命令：
| 子命令 | 别名 | 说明 |
|---|
show | cat, c, s | 输出最近 Patroni 日志 |
tail | t, f, follow | 持续跟踪 Patroni 日志 |
grep | g, search | 搜索 Patroni 日志 |
选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|
--follow | -f | false | 实时跟踪日志输出 |
--lines | -n | 50 | 显示的日志行数 |
--log-dir | | 自动解析 | 日志目录 |
pt svc 子命令
pt svc（也可写作 pt service）提供与顶层服务命令相同的功能，用于明确操作的是 Patroni 守护进程：
pig pt svc start # 启动 Patroni 服务
pig pt svc stop # 停止 Patroni 服务
pig pt svc restart # 重启 Patroni 服务
pig pt svc reload # 重载 Patroni 服务
pig pt svc status # 显示服务状态
别名对照：
| 命令 | 别名 |
|---|
pt svc start | up |
pt svc stop | dn |
pt svc restart | rs |
pt svc reload | rl |
pt svc status | st |
其中 start 和 stop 有专门的 pt start 和 pt stop 的快捷方式，方便用户直接管理 Patroni 服务。
但请注意，pt restart 并非是 pt svc restart 的快捷方式，而是用于 Patroni 重启 PostgreSQL 集群的命令，二者功能不同。
设计说明
与 patronictl 的关系：
pig pt 封装了 patronictl 的常用操作：
- 集群查询：
list、config show - 集群管理：
restart、reload、reinit、switchover、failover、pause、resume - 配置修改：
config set、config pg、config edit - 服务管理命令（start/stop/restart/reload/status）调用
systemctl log 命令读取 Patroni 日志目录中的日志文件
默认配置路径：
| 配置项 | 默认值 |
|---|
| Patroni 配置文件 | /etc/patroni/patroni.yml |
| 日志目录 | 配置文件 log.dir，回退 /pg/log/patroni |
| 服务名称 | patroni |
权限处理：
- 如果当前用户已是 DBSU：直接执行命令
- 如果当前用户是 root：使用
su - postgres -c "..." 执行 - 其他用户：使用
sudo -inu postgres -- ... 执行
平台支持：
此命令专为 Linux 系统设计，服务管理依赖 systemctl，日志功能依赖可读取的 Patroni 日志文件。
13 - pig pgbackrest
使用 pig pgbackrest 子命令管理 pgBackRest 备份与时间点恢复
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 # 跳过主库角色检查
选项：
备份类型：
| 类型 | 说明 |
|---|
| (空) | 自动模式：无备份则全量，否则增量 |
| 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
验证备份仓库的完整性和配置。
此命令检查：
- WAL 归档配置是否正确
- 仓库是否可访问
- stanza 配置是否有效
pb start
启用 pgBackRest 操作。
在执行 pb stop 后使用此命令恢复正常操作。
pb stop
禁用 pgBackRest 操作（用于维护）。
pig pb stop # 禁用操作
pig pb stop --force # 终止正在运行的操作
选项：
使用场景：
在进行系统维护时，使用此命令阻止新的备份操作启动。
日志命令
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 配置下必须显式指定 --stanzapb restore 需要显式恢复目标，校验 --time，并在没有 --yes 时要求交互式 y/yes 确认pb backup 默认检查主库角色，防止在备库执行pb log tail 不支持结构化输出；需要 JSONL 快照时使用 pb log show -n N -o json
平台支持：
此命令专为 Linux 系统设计，依赖 Pigsty 的默认目录结构。
14 - pig pitr
使用 pig pitr 命令执行编排式时间点恢复（PITR）
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 参数可以写在 -- 之后：
第五阶段：启动或保持停止
除非指定 --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 --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，便于自动化区分用户输入和实际恢复目标。
设计说明
权限执行：
- 如果当前用户已是 DBSU：直接执行命令
- 如果当前用户是 root：使用
su - postgres -c 执行 - 其他用户：使用
sudo -inu postgres -- 执行
平台支持：
此命令专为 Linux 系统设计，依赖 pgBackRest、systemd（托管服务场景）以及 DBSU 可访问的数据目录与日志路径。