这是本节的多页打印视图。
点击此处打印.
返回本页常规视图.
PIG 包管理器
PostgreSQL 扩展生态包管理器
—— Postgres Install Genius，PostgreSQL 生态中缺失的扩展包管理器
PIG 包管理器是一个专门用于安装、管理、构建 PostgreSQL 及其扩展的命令行工具，使用 Go 开发，开箱即用，简单易用，小巧玲珑（4MB）。
PIG 包管理器并非重新发明的土鳖轮子，而是 依托 （PiggyBack）现有 Linux 发行版包管理器 （apt/dnf）的一个高级抽象层。
它屏蔽了不同操作系统，不同芯片架构，以及不同 PG 大版本的管理差异，让您用简单的几行命令，就可以完成 PG 内核与 444+ 扩展的安装与管理。
PIG 同时也是一套 Agentic Native CLI：支持全局 -o|--output 结构化输出（yaml / json / json-pretty），
并提供可供 AI/自动化发现能力的 能力地图 与 命令 Schema。例如：
pig --help -o yaml # 输出能力地图（Capability Map）
pig ext --help -o json # 输出命令 Schema（参数/flags/风险/并行/确认等级等）
请注意：对于扩展安装来说，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 二进制包大约 4 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.0.0/pig_1.0.0-1_amd64.deb
[INFO] download = /tmp/pig_1.0.0-1_amd64.deb
[INFO] downloading pig v1.0.0
curl -fSL https://repo.pigsty.cc/pkg/pig/v1.0.0/pig_1.0.0-1_amd64.deb -o /tmp/pig_1.0.0-1_amd64.deb
######################################################################## 100.0%
[INFO] md5sum = a543882aa905713a0c50088d4e848951b6957a37a1594d7e9f3fe46453d5ce66
[INFO] installing: dpkg -i /tmp/pig_1.0.0-1_amd64.deb
(Reading database ... 166001 files and directories currently installed.)
Preparing to unpack /tmp/pig_1.0.0-1_amd64.deb ...
Unpacking pig (1.0.0-1) ...
Setting up pig (1.0.0-1) ...
[INFO] pig v1.0.0 installed successfully
check https://pgext.cloud for details
检查环境
PIG 是一个由 Go 编写的二进制程序，默认安装路径为 /usr/bin/pig，pig version 会打印版本信息：
$ pig version
pig version 1.0.0 linux/amd64
build: HEAD dc8f343 2026-01-26T15:52:04Z
使用 pig status 命令，会打印当前环境的状态，操作系统代码，PG的安装情况，仓库的可访问性与延迟。
$ pig status
# [Configuration] ================================
Pig Version : 1.0.0
Pig Config : /home/vagrant/.pig/config.yml
Log Level : info
Log Path : stderr
# [OS Environment] ===============================
OS Distro Code : u24
OS OSArch : arm64
OS Package Type : deb
OS Vendor ID : ubuntu
OS Version : 24
OS Version Full : 24.04
OS Version Code : noble
# [PG Environment] ===============================
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
# [Pigsty Environment] ===========================
Inventory Path : Not Found
Pigsty Home : Not Found
# [Network Conditions] ===========================
pigsty.cc ping ok: 802 ms
pigsty.io ping ok: 1410 ms
Internet Access : true
Pigsty Repo : pigsty.io
Inferred Region : china
Latest Pigsty Ver : v4.0.0
Agentic / 自动化输出
全局 -o|--output 可切换结构化输出，适合脚本与 AI 代理：
pig --help -o yaml # 能力地图（Capability Map）
pig ext --help -o json # 命令 Schema
pig repo list -o yaml # 结构化结果
pig pitr -d --plan -o json # 结构化执行计划
-o json-pretty 会输出带缩进的 JSON；未覆盖结构化输出的命令仍保持文本输出。
列出扩展
使用 pig ext list 命令，可以打印内置的 PG 扩展数据目录。
$ pig ext list
Name Status Version Cate Flags License Repo PGVer Package Description
---- ------ ------- ---- ------ ------- ------ ----- ------------ ---------------------
timescaledb installed 2.24.0 TIME -dsl-- Timescale PIGSTY 15-18 postgresql-18-timescaledb-tsl Enables scalable inserts and complex queries for time-series dat
timescaledb_toolkit installed 1.22.0 TIME -ds-t- Timescale PIGSTY 15-18 postgresql-18-timescaledb-toolkit Library of analytical hyperfunctions, time-series pipelining, an
timeseries installed 0.2.0 TIME -d---- PostgreSQL PIGSTY 13-18 postgresql-18-pg-timeseries Convenience API for time series stack
periods installed 1.2.3 TIME -ds--- PostgreSQL PGDG 13-18 postgresql-18-periods Provide Standard SQL functionality for PERIODs and SYSTEM VERSIO
temporal_tables installed 1.2.2 TIME -ds--r BSD 2-Clause PIGSTY 13-18 postgresql-18-temporal-tables temporal tables
.........
pg_fact_loader not avail 2.0.1 ETL -ds--x MIT PGDG 13-17 postgresql-18-pg-fact-loader build fact tables with Postgres
pg_bulkload installed 3.1.23 ETL bds--- BSD 3-Clause PIGSTY 13-18 postgresql-18-pg-bulkload pg_bulkload is a high speed data loading utility for PostgreSQL
test_decoding available - ETL --s--x PostgreSQL CONTRIB 13-18 postgresql-18 SQL-based test/example module for WAL logical decoding
pgoutput available - ETL --s--- PostgreSQL CONTRIB 13-18 postgresql-18 Logical Replication output plugin
(444 Rows) (Status: installed, available, not avail | Flags: b = HasBin, d = HasDDL, s = HasLib, l = NeedLoad, t = Trusted, r = Relocatable, x = Unknown)
所有的扩展元数据都在一份名为 extension.csv 的数据文件中定义，
这份文件会随着 pig 版本发布不断更新，您可以直接使用 pig ext reload 命令更新这份数据文件。
更新后的文件会默认放置于 ~/.pig/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 18，可以直接使用下面这些别名：
pgsql | pg18 | pg17 | pg16 | pg15 | pg14 | pg13 |
|---|
pgsql | pg18 | pg17 | pg16 | pg15 | pg14 | pg13 |
pgsql-mini | pg18-mini | pg17-mini | pg16-mini | pg15-mini | pg14-mini | pg13-mini |
pgsql-core | pg18-core | pg17-core | pg16-core | pg15-core | pg14-core | pg13-core |
pgsql-full | pg18-full | pg17-full | pg16-full | pg15-full | pg14-full | pg13-full |
pgsql-main | pg18-main | pg17-main | pg16-main | pg15-main | pg14-main | pg13-main |
pgsql-client | pg18-client | pg17-client | pg16-client | pg15-client | pg14-client | pg13-client |
pgsql-server | pg18-server | pg17-server | pg16-server | pg15-server | pg14-server | pg13-server |
pgsql-devel | pg18-devel | pg17-devel | pg16-devel | pg15-devel | pg14-devel | pg13-devel |
pgsql-basic | pg18-basic | pg17-basic | pg16-basic | pg15-basic | pg14-basic | pg13-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 17 pgvector=0.7.2 # install pgvector 0.7.2 for PG 17
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
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
Extension Stat : 329 Installed (PIGSTY 234, PGDG 95) + 69 CONTRIB = 398 Total
Name Version Cate Flags License Repo Package Description
---- ------- ---- ------ ------- ------ ------------ ---------------------
timescaledb 2.24.0 TIME -dsl-- Timescale PIGSTY postgresql-18-timescaledb-tsl Enables scalable inserts and complex queries for time-series dat
timescaledb_toolkit 1.22.0 TIME -ds-t- Timescale PIGSTY postgresql-18-timescaledb-toolkit Library of analytical hyperfunctions, time-series pipelining, an
timeseries 0.2.0 TIME -d---- PostgreSQL PIGSTY postgresql-18-pg-timeseries Convenience API for time series stack
periods 1.2.3 TIME -ds--- PostgreSQL PGDG postgresql-18-periods Provide Standard SQL functionality for PERIODs and SYSTEM VERSIO
temporal_tables 1.2.2 TIME -ds--r BSD 2-Clause PIGSTY postgresql-18-temporal-tables temporal tables
postgis 3.6.1 GIS -ds--- GPL-2.0 PGDG postgresql-18-postgis-3 PostGIS geometry and geography spatial types and functions
postgis_topology 3.6.1 GIS -ds--- GPL-2.0 PGDG postgresql-18-postgis-3 PostGIS topology spatial types and functions
postgis_raster 3.6.1 GIS -ds--- GPL-2.0 PGDG postgresql-18-postgis-3 PostGIS raster types and functions
vector 0.8.1 RAG -ds--r PostgreSQL PGDG postgresql-18-pgvector vector data type and ivfflat and hnsw access methods
pg_duckdb 1.1.0 OLAP -dsl-- MIT PIGSTY postgresql-18-pg-duckdb DuckDB Embedded in Postgres
如果您的当前系统路径中找不到 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.24.0 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 及其 444+ 扩展。
无论是 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 就是帮你解锁它的神灯。毕竟，从没有人抱怨 “扩展太多”。
Agentic Native CLI
PIG 从设计上面向 AI 代理与自动化：全局 -o|--output 可切换文本与结构化输出（yaml / json / json-pretty），
并提供命令能力发现所需的 能力地图 与 命令 Schema。
pig --help -o yaml # 输出能力地图（Capability Map）
pig ext --help -o json # 输出命令 Schema
pig repo list -o yaml # 结构化结果：success / code / message / data
《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 | 13-18 | 即将EOL |
el8.aarch64 | EL | 8 | 8.10 | RockyLinux 8 ARM | 13-18 | 即将EOL |
el9.x86_64 | EL | 9 | 9.6 | RockyLinux 9 x86 | 13-18 | ✅ |
el9.aarch64 | EL | 9 | 9.6 | RockyLinux 9 ARM | 13-18 | ✅ |
el10.x86_64 | EL | 10 | 10.0 | RockyLinux 10 x86 | 13-18 | ✅ |
el10.aarch64 | EL | 10 | 10.0 | RockyLinux 10 ARM | 13-18 | ✅ |
d11.x86_64 | Debian | 11 | 11.11 | Debian 11 x86 | 13-18 | EOL |
d11.aarch64 | Debian | 11 | 11.11 | Debian 11 ARM | 13-18 | EOL |
d12.x86_64 | Debian | 12 | 12.12 | Debian 12 x86 | 13-18 | ✅ |
d12.aarch64 | Debian | 12 | 12.12 | Debian 12 ARM | 13-18 | ✅ |
d13.x86_64 | Debian | 13 | 13.1 | Debian 13 x86 | 13-18 | ✅ |
d13.aarch64 | Debian | 13 | 13.1 | Debian 13 ARM | 13-18 | ✅ |
u20.x86_64 | Ubuntu | 20 | 20.04.6 | Ubuntu 20.04 x86 | 13-18 | EOL |
u20.aarch64 | Ubuntu | 20 | 20.04.6 | Ubuntu 20.04 ARM | 13-18 | EOL |
u22.x86_64 | Ubuntu | 22 | 22.04.5 | Ubuntu 22.04 x86 | 13-18 | ✅ |
u22.aarch64 | Ubuntu | 22 | 22.04.5 | Ubuntu 22.04 ARM | 13-18 | ✅ |
u24.x86_64 | Ubuntu | 24 | 24.04.3 | Ubuntu 24.04 x86 | 13-18 | ✅ |
u24.aarch64 | Ubuntu | 24 | 24.04.3 | Ubuntu 24.04 ARM | 13-18 | ✅ |
说明：
- EL 指 RHEL 兼容发行版，包括 RHEL、CentOS、RockyLinux、AlmaLinux、OracleLinux 等
- EOL 表示该操作系统已经或即将停止支持，建议升级到更新版本
- ✅ 表示完整支持，推荐使用
- PG 版本 13-18 表示支持 PostgreSQL 13、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 进行安装。
指定版本
您可以指定特定版本进行安装，将版本号作为参数传入即可：
默认安装（Cloudflare CDN）：
curl -fsSL https://repo.pigsty.io/pig | bash -s 1.0.0
中国镜像：
curl -fsSL https://repo.pigsty.cc/pig | bash -s 1.0.0
发布页下载
你也可以直接从 Pigsty 仓库下载 pig 安装包（RPM/DEB/ 压缩包）：GitHub 最新版本发布页
latest
└── v1.0.0
├── pig_1.0.0-1_amd64.deb
├── pig_1.0.0-1_arm64.deb
├── pig-1.0.0-1.aarch64.rpm
├── pig-1.0.0-1.x86_64.rpm
├── pig-v1.0.0.linux-amd64.tar.gz
├── pig-v1.0.0.linux-arm64.tar.gz
├── pig-v1.0.0.darwin-amd64.tar.gz
└── pig-v1.0.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 get -u; go build
所有 RPM / DEB 包都通过 GitHub CI/CD 流程使用 goreleaser 自动化构建。
4 - 版本
pig —— PostgreSQL 包管理器的发布说明
最新稳定版本是 v1.0.0。
v1.0.0
本版本引入三组主要的新子命令（pig pg、pig pt、pig pb），用于管理 PostgreSQL、Patroni 和 pgBackRest，同时新增编排式 PITR 命令，并增强扩展可用性显示。
新增命令
pig pg - PostgreSQL 实例管理
pg start/stop/restart/reload - 控制 PostgreSQL 服务pg status/log/ps/conf/hba - 查看实例状态与配置pg psql - 启动 psql 控制台pg role - 检测实例角色（主库/从库）pg promote/checkpoint/vacuumdb - 维护操作
pig pt - Patroni 集群管理
pt list/config - 查看集群状态与配置pt restart/reload/reinit - 管理集群成员pt switchover/failover - 集群切换操作pt pause/resume - 控制自动故障切换pt start/stop/status/log - Patroni 服务管理
pig pb - pgBackRest 备份管理
pb info/ls - 查看备份信息pb backup/restore/expire - 备份操作pb create/upgrade/delete - Stanza 管理pb check/start/stop/log - 控制操作
pig pitr - 编排式时间点恢复
- 自动协调 Patroni/PostgreSQL
- 多种恢复目标：时间、LSN、XID、还原点
- 支持 dry-run 模式与恢复后指引
新功能
- 为
pig ext avail 和 pig ext ls 添加可用性矩阵
改进
- 统一 pg/pt/pb 命令别名风格
- 规范化错误消息格式
- 代码重构与清理
Bug 修复
校验和
306637079e942bcac9ccbc089cd09a80051898f8db1630269bb1acd3fbdaa872 pig-1.0.0-1.aarch64.rpm
d2b9440410f00efbca174d63b507c39d97fc55f402d8e9290ee054c1b1c6414c pig-1.0.0-1.x86_64.rpm
c8a169e48a8168ee03db508ca2edc22b56ecf6997bae924e9023796ab7ae4e62 pig-v1.0.0.darwin-amd64.tar.gz
c0996037bfeffeae241b545e69d46c06e7fec2d7d456885229f3af9a7f9ea2f8 pig-v1.0.0.darwin-arm64.tar.gz
13837c6f2379edf965888bad9e373e69f70cb72e8428bca18c2c804e2bd879f6 pig-v1.0.0.linux-amd64.tar.gz
08207dfedd6f72745631596a3d3293de65cc12e1544956a643d1da2165d2c876 pig-v1.0.0.linux-arm64.tar.gz
a543882aa905713a0c50088d4e848951b6957a37a1594d7e9f3fe46453d5ce66 pig_1.0.0-1_amd64.deb
4cd6ec54261b09025c12e9c56bcc0cd3c11779ea0e8becdbd4f901cf2e7c8995 pig_1.0.0-1_arm64.deb
发布：https://github.com/pgsty/pig/releases/tag/v1.0.0
v0.8.0
扩展更新
- 扩展总数达到 440 个
- 新增扩展：pg_ai_query 0.1.1
- 新增扩展：pg_textsearch 0.1.0
- 新增扩展：pg_clickhouse 0.1.0
- pg_biscuit 从 1.0 升级至 2.0.1（切换至新仓库，更名为 biscuit）
- pg_search 从 0.20.3 升级至 0.20.5
- pg_duckdb 升级至官方正式版 1.1.1
- vchord_bm25 从 0.2.2 升级至 0.3.0
- pg_semver 从 0.40.0 升级至 0.41.0
- pg_timeseries 从 0.1.7 升级至 0.1.8
- 修复 debian/ubuntu pg18 扩展问题：supautils、pg_summarize、pg_vectorize、pg_tiktoken、pg_tzf、pglite_fusion、pgsmcrypto、pgx_ulid、plprql
- pigsty 版本号同步至 4.0.0
仓库更新
- 因上游变更移除 pgdg yum sysupdate 仓库
- 因上游变更移除 pgdg yum llvmjit 软件包
- 修复 el9.aarch64 上 patroni 3.0.4 重复软件包问题
- 为 el 仓库定义添加优先级，docker 仓库不可用时自动跳过
- 添加 epel 10 / pgdg 9/10 操作系统小版本热修复
校验和
e457832fb290e2f9975bf719966dc36e650bdcbf8505d319c9e0431f4c03bc9e pig-0.8.0-1.aarch64.rpm
c97b1bfdd7541f0f464cab0ecc273e65535c8dd2603c38d5cf8dccbf7e95b523 pig-0.8.0-1.x86_64.rpm
d892f06d3d3b440671529f40e6cc7949686e0167e2a4758adc666b8a3d75254d pig-v0.8.0.darwin-amd64.tar.gz
222413bafdf5a62dc682dac32ea1118cbc34ec3544e2a1b85076ec450b9cc7ae pig-v0.8.0.darwin-arm64.tar.gz
d50aa9806bbab8fee5ad9228e104fc9e7ead48729228116b5bf889000791fedc pig-v0.8.0.linux-amd64.tar.gz
d2f410f7b243a8323c8d479f462a0267ac72d217aa4a506c80b5a9927d12dff8 pig-v0.8.0.linux-arm64.tar.gz
4ccd330a995911d4f732e8c9d62aa0db479c21c9596f64c4bc129ec43f156abe pig_0.8.0-1_amd64.deb
5cb9eccce659110f3ba58e502575564bd6befffd51992a43d84df5a17f8eb8a0 pig_0.8.0-1_arm64.deb
发布：https://github.com/pgsty/pig/releases/tag/v0.8.0
v0.7.5
扩展更新
- timescaledb 2.23.1 -> 2.24.0
- pg_search 0.20.0 -> 0.20.3
- convert 0.0.4 -> 0.0.5
- pglinter 1.0.0 -> 1.0.1
- pgdd 0.6.0 -> 0.6.1
- pg_session_jwt 0.3.3 -> 0.4.0
- pg_anon 2.4.1 -> 2.5.1
- pg_enigma 0.4.0 -> 0.5.0
- wrappers 0.5.6 -> 0.5.7
- pg_vectorize 0.25.0 -> 0.26.0
仓库更新
使用修复后的阿里云 PGDG 镜像仓库
校验和
9de11ac1404fc4100074113f2a5d50e4ec42c353b6e122a0b29edc17e53feca6 pig-0.7.5-1.aarch64.rpm
071d655580f1cc63b33d41a8fb49368556b7b5a276318f4bd772a6ab50e22b34 pig-0.7.5-1.x86_64.rpm
befe0a8f786e5243669ed7219acde8156d13d9adb0a5c2fb88ccf0f614a51f9b pig-v0.7.5.darwin-amd64.tar.gz
4766b4e9ba390a32a7115e9f2dd6b65cf158439e28f9c099bab5c7f2e588bae2 pig-v0.7.5.darwin-arm64.tar.gz
dc45726c5e7fccd502cacaffc94c659570844151cdc279f2cac6500836071ade pig-v0.7.5.linux-amd64.tar.gz
1483cf967d4bc9c12d4c6724567644d6b88fcd2a93aaf1d317fc6ad4e1672c13 pig-v0.7.5.linux-arm64.tar.gz
0152b7bd254eccadd640e563845abd9fa62efa68f11c6b67a5f9f0eebfa2d92e pig_0.7.5-1_amd64.deb
7d22116d26ca09c5e2b8afbf086bb1acb1aea1148905efcc38944c18908fb105 pig_0.7.5-1_arm64.deb
发布：https://github.com/pgsty/pig/releases/tag/v0.7.5
v0.7.4
- 更新扩展版本与元数据：
pg_search，pgmq，pg_stat_monitor - 更新 PGDG 仓库 URL 变化，
extras 仓库现在位于 yum 仓库顶层 - 将 ivorysql 更新至 5.0 版本，与 PG 18 兼容
- 将 Percona Postgres TDE 内核更新至 18.1
Checksums
5769b0051f04dcda22dd92b30b8effc8ddfa40097308bded76ce2b38d012ce57 pig-0.7.4-1.aarch64.rpm
d15c829fa2e3ce8dcd1adc063c107607b8e70f2cf747646aaa2fa257cdbf979c pig-0.7.4-1.x86_64.rpm
bb4c90e253a3d470e50316e633a41e90ed2d4a5c5a1fd3a8dbb68ee87d831d47 pig-v0.7.4.darwin-amd64.tar.gz
faaf7ac7b08390f5048c081bb7a78100714387e35dc890e26d9746fc1caef415 pig-v0.7.4.darwin-arm64.tar.gz
037cacddd0dc1283f13dd2c9bace87ad7f2c74ffc245e629f1420be94bbf93df pig-v0.7.4.linux-amd64.tar.gz
2ce819b2c3686cfb9f86790fdf61acd30bf7798bd6cd3c4f589df22e273dc867 pig-v0.7.4.linux-arm64.tar.gz
97f62d62f1cca61ce6d335efed88e3855d94ea2cd4ed941f2755fbac73931fcd pig_0.7.4-1_amd64.deb
d2b80af89ed42601716f6b41eda3f8bee16db34023527df9deef8a43aa25a498 pig_0.7.4-1_arm64.deb
发布：https://github.com/pgsty/pig/releases/tag/v0.7.4
v0.7.3
- 新增 pig repo reload 命令，更新仓库元数据
- 修复 EL PGDG sysupdate aarch64 仓库问题。
- 修复 EL10.aarch64 PGDG 仓库重命名问题。
- 订正了若干扩展版本
- 更新 Pigsty 版本至 3.7.0
校验和
786d72f6b685d6d6abf5f255f0a7de9204988a05630a26a53bfc7631823c0c6f pig-0.7.3-1.aarch64.rpm
da59e24ef79d1164e348bacc43e3222e8e2778ec0e103e7ffc0c6df064758e8f pig-0.7.3-1.x86_64.rpm
73062a979749095e89abc07dd583d34d4f57908bb4ee935cf7640f129ca6a2cb pig-v0.7.3.darwin-amd64.tar.gz
ca5f5576f6d0d9be1d10cad769821be9daa62220b2fb56b94d6e4c0cede6da61 pig-v0.7.3.darwin-arm64.tar.gz
d193b4b87cf9a6e4775b1b07709802d30f0233ccb1b728843a09decb545168d3 pig-v0.7.3.linux-amd64.tar.gz
e7f612df0e8e4d9fac6df3765862b9e491bb50aad651856abf7a6935986e6f99 pig-v0.7.3.linux-arm64.tar.gz
3d5306ce95dcf704dd498b05325d942637564b13115f1e5a5bb9ef6781df1ba6 pig_0.7.3-1_amd64.deb
32e695ba2d49a741d8cd92008f8f2dec29f10754d35b732035f48517b382c30d pig_0.7.3-1_arm64.deb
发布：https://github.com/pgsty/pig/releases/tag/v0.7.3
v0.7.2
批量更新扩展，数量达到 437 个
新增 PGDG EL10 Sysupdate 仓库
新增 LLVM APT 仓库
在 pig build 命令中使用可选的本地 extension.csv 扩展定义问题。
更新的扩展： vchord pg_later pgvectorscale pglite_fusion pgx_ulid pg_search citus timescaledb pg_profile pg_stat_monitor documentdb
新增的扩展：pglinter pg_typeid pg_enigma pg_retry pg_biscuit pg_weighted_statistics
校验和
f303c391fc28bc74832712e0aa58319abe0ebcae4f6c07fdf9a9e542b735d2ec pig-0.7.2-1.aarch64.rpm
c096a61a4e3a49b1238659664bbe2cd7f29954c43fb6bb8e8e9fb271f95a612e pig-0.7.2-1.x86_64.rpm
5e037c891dff23b46856485108d6f64bede5216dfbd4f38a481f0d0672ee910b pig-v0.7.2.darwin-amd64.tar.gz
736b4b47999c543c3c886781f4d8dddbf4276f363c35c7bf50094b6f18d14600 pig-v0.7.2.darwin-arm64.tar.gz
20b13f059efed29dd76f6927b3e8d7b597c0c8d734f9e22ba3d0a2af6dbcd3bf pig-v0.7.2.linux-amd64.tar.gz
9548b530c05f2ffdc8d73b8f890718d47b74a51eb62852a99c08b1b52e47f014 pig-v0.7.2.linux-arm64.tar.gz
b6faad9f92b926546a10f590274f2cb2afff21b9cea878094cfc5caf09e67d2c pig_0.7.2-1_amd64.deb
452f73f1fa035e5417ab49fc51d797925550179ffcc023e8f03d80144309212a pig_0.7.2-1_arm64.deb
发布：https://github.com/pgsty/pig/releases/tag/v0.7.2
v0.7.1
校验和
a696c9ec784e2fc248e5f3d87cc8aae4116e890f78c5997957d30593f2c85ca6 pig-0.7.1-1.aarch64.rpm
f669538a99cd1dc592d3005b949628fcceb9e78114fc78862d7726b340ee194d pig-0.7.1-1.x86_64.rpm
e42bdaaf93b720c5b76b32b57362320e4b447109740c76089aefe030b7c8b836 pig-v0.7.1.darwin-amd64.tar.gz
b4c240aadad34e785666ee0a755d9b7455724f790c2d088a1dd7c37ad3b2a457 pig-v0.7.1.darwin-arm64.tar.gz
ffc687add0ca71ac90cba5749c8a7a6075cf7618cba85584072831cf3eb182f7 pig-v0.7.1.linux-amd64.tar.gz
7b0d1f158150d0a40c525692f02b6bce9f5b4ac523a4e59278d702c334e222e1 pig-v0.7.1.linux-arm64.tar.gz
43e91a3bea273d7cacb2d7a58c0a5745501dbd06348b5cb3af971171fae70268 pig_0.7.1-1_amd64.deb
fc2a34aeb46e07cb0ae93611de47d6622c3bd46fe4c415ce4c9091840e0e08a2 pig_0.7.1-1_arm64.deb
发布：https://github.com/pgsty/pig/releases/tag/v0.7.1
v0.7.0
- 提供针对 Debian 13 和 EL 10 发行版的支持
- 大批量扩展更新至最新版本，带有 PostgreSQL 18 支持。
- 几乎所有 Rust 扩展现已通过 pgrx 0.16.1 支持 PG 18
pig build 命令彻底重做pig build pkg <pkg> 现在会一条龙完成扩展的下载，依赖安装，构建pig build pgrx 命令现在从 pig build rust 中分离pig build pgrx [-v pgrx_version] 现在可以直接使用现有的 PG 安装pig build dep 现在会处理 EL 和 Debian 系统下的扩展依赖pig build ext 命令现在有了更为紧凑和美观的输出，可在 EL 下不依赖 build 脚本直接构建 RPMpig build spec 现在支持直接从Pigsty仓库下载 spec 文件包pig build repo / pig repo add / pig repo set 现在默认使用 node,pgsql,infra 仓库模块，取代原本的 node,pgdg,pigsty
- 大量优化了错误日志记录。
- 基于 hugo 与 hextra 全新目录网站
校验和
ad60f9abcde954769e46eb23de61965e pig_0.7.0-1_amd64.deb
aa15d7088d561528e38b2778fe8f7cf9 pig_0.7.0-1_arm64.deb
05549fe01008e04f8d5a59d4f2a5f0b8 pig-0.7.0-1.aarch64.rpm
0cc9e46c7c72d43c127a6ad115873b67 pig-0.7.0-1.x86_64.rpm
ddacfb052f3f3e5567a02e92fdb31cdd pig-v0.7.0.darwin-amd64.tar.gz
17d25b565308d3d35513e4b0d824946b pig-v0.7.0.darwin-arm64.tar.gz
ee7e055ceff638039956765fb747f80b pig-v0.7.0.linux-amd64.tar.gz
284e674807b87447d4b33691fd7a420d pig-v0.7.0.linux-arm64.tar.gz
发布：https://github.com/pgsty/pig/releases/tag/v0.7.0
v0.6.2
- 使用 PG 18 官方正式仓库取代原本的 Testing Beta 仓库 instead of testing repo
- 在接收 Pigsty 版本字符串的时候，自动添加
v 前缀 - 改进了网络检查与下载的逻辑
校验和
01f5b7dc20644226c762dbb229768347 pig_0.6.2-1_amd64.deb
ce4f00256adc12cbea91467b7f2241cd pig_0.6.2-1_arm64.deb
cefc36ae8f348aede533b30836fba720 pig-0.6.2-1.aarch64.rpm
d04a287c6eb92b11ecbf99542c2db602 pig-0.6.2-1.x86_64.rpm
e637ca86a7f38866c67686b060223d9a pig-v0.6.2.darwin-amd64.tar.gz
79749bc69c683586bd8d761bdf6af98e pig-v0.6.2.darwin-arm64.tar.gz
ad4f02993c7d7d8eec142f0224551bb4 pig-v0.6.2.linux-amd64.tar.gz
9793affa4a0cb60e9753e65b7cba3dca pig-v0.6.2.linux-arm64.tar.gz
发布：https://github.com/pgsty/pig/releases/tag/v0.6.2
v0.6.1
- 新增 el10 与 debian 13 trixie 的支持存根
- 专门的新文档网站： https://pgext.cloud/pig
- 使用 go 1.25 重新构建，新增 CI/CD 管道
- 在中国大陆使用 PIGSTY PGDG 镜像
- 移除空的
pgdg-el10fix 仓库 - 使用 Pigsty WiltonDB 镜像
- 修复 EL 10 专用的 EPEL 仓库
- pig version 输出构建环境信息
发布：https://github.com/pgsty/pig/releases/tag/v0.6.1
v0.6.0
- 新扩展目录：https://ext.pgsty.com
- 新子命令：
pig install 简化 pig ext install - 添加新内核支持：带 pg_tde 的 percona
- 添加新包：Google GenAI MCP 数据库工具箱
- 添加新仓库：percona 仓库和 clickhouse 仓库
- 将扩展摘要信息链接更改为 https://ext.pgsty.com
- 修复 orioledb 在 Debian/Ubuntu 系统上的问题
- 修复 EL 发行版上的 epel 仓库
- 将 golang 升级到 1.24.5
- 将 pigsty 升级到 v3.6.0
校验和
1804766d235b9267701a08f95903bc3b pig_0.6.0-1_amd64.deb
35f4efa35c1eaecdd12aa680d29eadcb pig_0.6.0-1_arm64.deb
b523b54d9f2d7dcc5999bcc6bd046b1d pig-0.6.0-1.aarch64.rpm
9434d9dca7fd9725ea574c5fae1a7f52 pig-0.6.0-1.x86_64.rpm
f635c12d9ad46a779aa7174552977d11 pig-v0.6.0.linux-amd64.tar.gz
165af4e63ec0031d303fe8b6c35c5732 pig-v0.6.0.linux-arm64.tar.gz
发布：https://github.com/pgsty/pig/releases/tag/v0.6.0
v0.5.0
- 将扩展列表更新至 422 个
- 新扩展：来自 AWS 的 pgactive
- 将 timescaledb 升级到 2.20.3
- 将 citus 升级到 13.1.0
- 将 vchord 升级到 0.4.3
- 修复错误：pgvectorscale debian/ubuntu pg17 失败
- 将 kubernetes 仓库升级到 1.33
- 将默认 pigsty 版本升级到 3.5.0
校验和
9ec6f3caf3edbe867caab5de0e0ccb33 pig_0.5.0-1_amd64.deb
4fbb0a42cd8a88bce50b3c9d85745d77 pig_0.5.0-1_arm64.deb
9cf8208396b068cab438f72c90d39efe pig-0.5.0-1.aarch64.rpm
d9a8d78c30f45e098b29c3d16471aa8d pig-0.5.0-1.x86_64.rpm
761df804ff7b83965c41492700717674 pig-v0.5.0.linux-amd64.tar.gz
5d1830069d98030728f08835f883ea39 pig-v0.5.0.linux-arm64.tar.gz
发布：https://github.com/pgsty/pig/releases/tag/v0.5.0
v0.4.2
- 将扩展列表更新至 421 个
- 为 Debian / Ubuntu 添加 openhalo/orioledb 支持
- pgdd 0.6.0 (pgrx 0.14.1)
- convert 0.0.4 (pgrx 0.14.1)
- pg_idkit 0.3.0 (pgrx 0.14.1)
- pg_tokenizer.rs 0.1.0 (pgrx 0.13.1)
- pg_render 0.1.2 (pgrx 0.12.8)
- pgx_ulid 0.2.0 (pgrx 0.12.7)
- pg_ivm 1.11.0 适用于 debian/ubuntu
- orioledb 1.4.0 beta11
- 重新添加 el7 仓库
校验和
bbf83fa3e3ec9a4dca82eeed921ae90a pig_0.4.2-1_amd64.deb
e45753335faf80a70d4f2ef1d3100d72 pig_0.4.2-1_arm64.deb
966d60bbc2025ba9cc53393011605f9f pig-0.4.2-1.aarch64.rpm
1f31f54da144f10039fa026b7b6e75ad pig-0.4.2-1.x86_64.rpm
1eec26c4e69b40921e209bcaa4fe257a pig-v0.4.2.linux-amd64.tar.gz
768d43441917a3625c462ce9f2b9d4ef pig-v0.4.2.linux-arm64.tar.gz
发布：https://github.com/pgsty/pig/releases/tag/v0.4.2
v0.4.1
- 将扩展列表更新至 414 个
- 在
pig ext scan 映射中添加 citus_wal2json 和 citus_pgoutput - 添加 PG 18 beta 仓库
- 添加 PG 18 包别名
发布：https://github.com/pgsty/pig/releases/tag/v0.4.1
v0.4.0
- 更新扩展列表，可用扩展达到 407 个
- 添加
pig do 子命令用于执行 Pigsty playbook 任务 - 添加
pig pt 子命令用于包装 Patroni 命令行工具 - 添加扩展别名：
openhalo 和 orioledb - 添加
gitlab-ce / gitlab-ee 仓库区分 - 使用最新 Go 1.24.2 构建并升级依赖项版本
- 修复特定条件下
pig ext status 的 panic 问题 - 修复
pig ext scan 无法匹配多个扩展的问题
发布：https://github.com/pgsty/pig/releases/tag/v0.4.0
v0.3.4
curl https://repo.pigsty.io/pig | bash -s 0.3.4
- 常规扩展元数据更新
- 使用阿里云 epel 镜像代替损坏的清华大学 tuna 镜像
- 升级 pigsty 版本字符串
- 在仓库列表中添加
gitlab 仓库
发布：https://github.com/pgsty/pig/releases/tag/v0.3.4
v0.3.3
- 添加
pig build dep 命令安装扩展构建依赖项 - 更新默认仓库列表
- 为
mssql 模块（wiltondb/babelfish）使用 pigsty.io 镜像 - 将 docker 模块合并到
infra - 从 el7 目标中移除 pg16/17
- 允许在 el7 中安装扩展
- 更新包别名
发布：https://github.com/pgsty/pig/releases/tag/v0.3.3
v0.3.2
增强功能
- 新扩展
- 使用
upx 减少二进制大小 - 移除嵌入的 pigsty 以减少二进制大小
发布：https://github.com/pgsty/pig/releases/tag/v0.3.2
v0.3.1
常规错误修复
- 修复仓库格式字符串
- 修复扩展信息链接
- 更新 pg_mooncake 元数据
发布：https://github.com/pgsty/pig/releases/tag/v0.3.1
v0.3.0
pig 项目现在有了新的 主页，以及 PostgreSQL 扩展 目录。
发布：https://github.com/pgsty/pig/releases/tag/v0.3.0
v0.2.2
Pig v0.2.2 中提供 404 个扩展
发布：https://github.com/pgsty/pig/releases/tag/v0.2.2
v0.2.0
发布：https://github.com/pgsty/pig/releases/tag/v0.2.0
v0.1.4
发布：https://github.com/pgsty/pig/releases/tag/v0.1.4
v0.1.3
v0.1.3，常规更新，现在可用 390 个扩展！
发布：https://github.com/pgsty/pig/releases/tag/v0.1.3
v0.1.2
351 个 PostgreSQL 扩展，包括强大的 postgresql-anonymizer 2.0
发布：https://github.com/pgsty/pig/releases/tag/v0.1.2
v0.1.0
pig CLI v0.1 发布
发布：https://github.com/pgsty/pig/releases/tag/v0.1.0
v0.0.1
创世发布
发布：https://github.com/pgsty/pig/releases/tag/v0.0.1
5 - 命令参考
6 - pig
pig CLI 命令参考概览
pig CLI 提供了全面的工具集，用于管理 PostgreSQL 安装、扩展、软件仓库以及从源码构建扩展。使用 pig help <command> 查看命令文档。
概览
pig - PostgreSQL 的 Linux 包管理器
Usage:
pig [command]
Examples:
pig repo add -ru # 覆盖现有仓库并更新缓存
pig install pg17 # 安装 PostgreSQL 17 PGDG 软件包
pig install pg_duckdb # 安装指定的 PostgreSQL 扩展
pig install pgactive -v 18 # 为特定 PG 版本安装扩展
访问 https://pgext.cloud 获取详情
PostgreSQL Extension Manager
build 构建 Postgres 扩展
ext 管理 PostgreSQL 扩展 (pgext)
repo 管理 Linux 软件仓库 (apt/dnf)
Pigsty Management Commands
do 运行管理任务
patroni 使用 patronictl 管理 Patroni 集群
pg_exporter 管理 pg_exporter 与监控指标
pgbackrest 管理 pgBackRest 备份与恢复
pitr 编排式时间点恢复
postgres 管理本地 PostgreSQL 服务器与数据库
sty 管理 Pigsty 安装
Additional Commands:
completion 生成指定 shell 的自动补全脚本
help 获取任何命令的帮助信息
install 使用原生包管理器安装软件包
status 显示环境状态
update 升级 pig 自身
version 显示 pig 版本信息
Flags:
--debug 启用调试模式
-h, --help 获取帮助信息
-H, --home string Pigsty 主目录路径
-i, --inventory string 配置清单路径
-o, --output string 输出格式：text、yaml、json、json-pretty
--log-level string 日志级别: debug, info, warn, error, fatal, panic (默认 "info")
--log-path string 日志文件路径，默认为终端输出
使用 "pig [command] --help" 获取命令的详细信息。
Agentic Native CLI
pig 支持面向 AI/自动化的结构化输出与能力发现：
pig --help -o yaml # 输出能力地图（Capability Map）
pig ext --help -o json # 输出命令 Schema（参数/flags/元数据）
pig ext list -o json # 结构化结果：success / code / message / data
补充说明：-o json-pretty 会输出带缩进的 JSON；当前主要覆盖 ext / repo / pitr 与 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（用于 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 sty
安装 Pigsty 发行版，详情请参考 pig sty
pig sty init # 安装 Pigsty 到 ~/pigsty
pig sty boot # 安装 Ansible 依赖
pig sty conf # 生成配置
pig sty deploy # 运行部署 playbook
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 log tail # 实时查看日志
pig pt
管理 Patroni HA 集群，详情请参考 pig pt
pig pt list # 列出集群成员
pig pt config # 显示集群配置
pig pt config 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 # 恢复到最新
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" # 恢复到指定时间
pig pitr -I # 恢复到备份一致性点
pig pitr -d --plan # 显示执行计划
pig pitr -d --dry-run # alias for --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 仓库并更新缓存
pig repo add pigsty --region=china # 添加 Pigsty 仓库，指定使用中国区域
pig repo add pgdg --region=default # 添加 PGDG ，指定使用默认区域
pig repo add infra --region=europe # 添加 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, pgdg13-18 |
node | Linux 系统仓库 | base, updates, extras, epel, baseos, appstream… |
infra | 基础设施组件仓库 | pigsty-infra, nginx, docker-ce |
beta | PostgreSQL 19 Beta 版本 | pgdg19-beta, pgdg-beta |
extra | PGDG Non-Free 与三方扩展 | pgdg-extras, timescaledb, citus |
groonga | PGroonga 仓库 | groonga |
mssql | WiltonDB 仓库 | wiltondb |
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 -f # 强制覆盖现有文件
pig repo cache -d /srv # 自定义源目录
选项：
-d, --dir：源目录（默认：/www/）-p, --path：输出路径（默认：/tmp/pkg.tgz）-f：强制覆盖现有包
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 pg17 # install optional postgresql 17 package
pig ext list duck # search extension in catalog
pig ext scan -v 17 # scan installed extension for pg 17
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 -u # 粗暴方式移除并添加所有所需仓库
然后你可以搜索并安装 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 vector ai # 搜索多个关键词
pig ext list -v 17 # 按 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。
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）、架构（x86_64/aarch64）和 PostgreSQL 版本（13-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 install。
pig ext add pg_duckdb # 安装 pg_duckdb
pig ext add pg_duckdb -v 17 # 为 PG 17 安装
pig ext add pg_duckdb -y # 自动确认安装
pig ext add vector postgis # 安装多个扩展
# 使用别名
pig install pg_duckdb
pig install pg_duckdb -v 17 -y
# 安装 PostgreSQL 内核
pig ext install pgsql # 安装最新版 postgresql 内核
pig ext a pg17 # 安装 postgresql 17 内核包
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：自动确认安装-n|--no-translation：禁用别名翻译
ext rm
移除一个或多个 PostgreSQL 扩展。也可以使用别名 pig remove。
pig ext rm pg_duckdb # 移除 pg_duckdb
pig ext rm pg_duckdb -v 17 # 移除 PG 17 版本
pig ext rm pgvector -y # 自动确认移除
pig remove pg_duckdb # 使用别名
ext update
将已安装扩展更新到最新版。
pig ext update # 更新所有已安装扩展
pig ext update pg_duckdb # 更新特定扩展
pig ext update postgis timescaledb # 更新多个扩展
pig ext update -y # 自动确认更新
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 17 # 链接 PG 17 到 /usr/pgsql
pig ext link /usr/pgsql-16 # 从指定路径链接到 /usr/pgsql
pig ext link null # 取消当前 PostgreSQL 链接
该命令会创建 /usr/pgsql 软链接，并写入 /etc/profile.d/pgsql.sh。
ext reload
从 GitHub 刷新扩展元数据。
更新后的文件会放置于 ~/.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.16.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: ~/rpmbuild/RPMS/
# - Debian: ~/
更精细的控制方式：
# 设置环境
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/ # 默认构建规范目录
├── Makefile # 主构建 makefile
├── <extension>/ # 每个扩展的目录
│ ├── Makefile # 扩展特定的 makefile
│ ├── <extension>.spec # RPM 规范文件（EL）
│ └── debian/ # Debian 打包文件
│ ├── control
│ ├── rules
│ └── ...
构建输出位置：
- EL 系统：
~/rpmbuild/RPMS/<arch>/ - Debian 系统：
~/（deb 文件）
build spec
设置构建规范仓库和目录结构。
pig build spec # 在默认位置初始化 ~/ext
功能：
- 克隆或更新扩展构建规范仓库
- 创建必要的目录结构
- 设置 makefile 和构建脚本
- 准备平台特定的打包文件
仓库位置： 默认 ~/ext/，包含 100+ 扩展的构建规范。
build repo
初始化构建扩展所需的包仓库。
pig build repo # 等同于：pig repo set -ru
功能： 移除现有仓库、添加所有必需仓库（pgdg、pigsty、node）、更新包缓存。
安装必要的开发工具和编译器。
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 编译器（rustc）、Cargo 包管理器、Rust 标准库、开发工具。
build pgrx
安装并初始化 PGRX（Rust 的 PostgreSQL 扩展框架）。
pig build pgrx # 安装最新稳定版 (0.16.1)
pig build pgrx -v 0.15.0 # 安装特定版本
前提条件： 必须先安装 Rust 工具链、PostgreSQL 开发头文件。
build proxy
为受限互联网访问的构建环境设置代理配置。
pig build proxy # 交互式设置
pig build proxy user@host:8080 # 直接配置
pig build proxy http://proxy.company.com:3128
build get
下载扩展源代码 tarball。
pig build get citus # 单个扩展
pig build get citus pgvector # 多个扩展
pig build get all # 所有可用扩展
pig build get std # 标准扩展
build dep
安装构建扩展所需的依赖。
pig build dep citus # 单个扩展
pig build dep citus pgvector # 多个扩展
pig build dep citus --pg 17,16 # 为特定 PG 版本
build ext
编译扩展并创建安装包。
pig build ext citus # 构建单个扩展
pig build ext citus pgvector # 构建多个
pig build ext citus --pg 17 # 为特定 PG 版本
pig build ext citus -s # 包含调试符号（仅 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 # 包含调试符号
常见工作流
工作流 1：构建标准扩展
# 1. 设置构建环境（一次性）
pig build spec
pig build repo
pig build tool
# 2. 构建扩展
pig build pkg pg_partman
# 3. 安装构建的包
sudo rpm -ivh ~/rpmbuild/RPMS/x86_64/pg_partman*.rpm # EL
sudo dpkg -i ~/pg_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 cargo-pgrx --force
# 重新初始化 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] # 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 -y # 自动确认
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 17 -c rich # 使用 conf/rich.yml 模板，PostgreSQL 17
pig sty conf -r china -s # 使用中国区镜像源，跳过 IP 探测
pig sty conf -x # 从环境变量写入代理配置到配置文件
pig sty conf -c full -g -o ha.yml # 完整 HA 模板，随机密码输出到 ha.yml
选项：
-c|--conf：配置模板名称（meta/rich/slim/full/supabase/…）--ip：主节点 IP 地址-v|--version：PostgreSQL 主版本（18/17/16/15/14/13）-r|--region：上游仓库区域（default/china/europe）-o|--output：输出配置文件路径（默认：pigsty.yml）-s|--skip：跳过 IP 探测-p|--port：SSH 端口-x|--proxy：从环境变量写入代理配置-n|--non-interactive：非交互模式-g|--generate：生成随机默认密码（推荐！）
详见：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 等原生工具，提供简化的服务器管理体验。
pig pg - Manage local PostgreSQL server and databases.
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)
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)
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 vacuum | vac, vc | 清理表 | 封装 vacuumdb |
pg analyze | ana, az | 分析表 | 封装 vacuumdb –analyze-only |
pg freeze | frz | 冻结清理表 | 封装 vacuumdb –freeze |
pg repack | rp | 在线重整表 | 需要 pg_repack 扩展 |
日志工具：
| 命令 | 别名 | 描述 | 备注 |
|---|
pg log | l | 日志管理 | 父命令 |
pg log list | ls | 列出日志文件 | |
pg log tail | t, f | 实时查看日志 | tail -f |
pg log cat | c | 输出日志内容 | |
pg log less | vi, v | 用 less 查看 | |
pg log grep | g, search | 搜索日志 | |
服务子命令（pg svc）：
| 命令 | 别名 | 描述 |
|---|
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 vacuum mydb # 清理指定数据库
pig pg analyze mydb # 分析指定数据库
pig pg repack mydb # 在线重整数据库
# 日志查看
pig pg log tail # 实时查看最新日志
pig pg log grep ERROR # 搜索错误日志
pig pg log list --log-dir /var/log/pg # 使用自定义日志目录
全局参数
以下参数适用于所有 pig pg 子命令：
| 参数 | 简写 | 默认值 | 说明 |
|---|
--version | -v | 自动检测 | PostgreSQL 主版本号 |
--data | -D | /pg/data | 数据目录路径 |
--dbsu | -U | postgres | 数据库超级用户（或 $PIG_DBSU 环境变量） |
版本检测逻辑：
- 如果指定了
-v，使用指定版本 - 否则从数据目录的
PG_VERSION 文件读取版本 - 如果都无法获取，使用 PATH 中的默认 PostgreSQL
服务控制命令
pg init
初始化 PostgreSQL 数据目录。封装 initdb 命令。
pig pg init # 使用默认设置初始化
pig pg init -v 17 # 指定 PostgreSQL 17
pig pg init -D /data/pg17 # 指定数据目录
pig pg init -k # 启用数据校验和
pig pg init -f # 强制初始化（删除已有数据）
pig pg init -- --waldir=/wal # 传递额外参数给 initdb
选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|
--encoding | -E | UTF8 | 数据库编码 |
--locale | | C | 区域设置 |
--data-checksum | -k | false | 启用数据校验和 |
--force | -f | false | 强制初始化，删除已有数据（危险！） |
安全机制： 即使使用 --force，如果 PostgreSQL 正在运行，命令也会拒绝执行，以防止数据丢失。
pg start
启动 PostgreSQL 服务器。
pig pg start # 使用默认设置启动
pig pg up # 别名
pig pg boot # 别名
pig pg start -D /data/pg17 # 指定数据目录
pig pg start -l /pg/log/pg.log # 重定向输出到日志文件
pig pg start -o "-p 5433" # 传递参数给 postgres
pig pg start -y # 强制启动（跳过运行检查）
选项：
| 参数 | 简写 | 说明 |
|---|
--log | -l | 重定向 stdout/stderr 到日志文件 |
--timeout | -t | 等待超时（秒） |
--no-wait | -W | 不等待启动完成 |
--options | -o | 传递给 postgres 的选项 |
--yes | -y | 强制启动（即使已运行） |
pg stop
停止 PostgreSQL 服务器。
pig pg stop # 快速停止（默认）
pig pg down # 别名
pig pg halt # 别名
pig pg stop -m smart # 等待客户端断开
pig pg stop -m immediate # 立即关闭
选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|
--mode | -m | fast | 关闭模式：smart/fast/immediate |
--timeout | -t | 60 | 等待超时（秒） |
--no-wait | -W | false | 不等待关闭完成 |
关闭模式说明：
| 模式 | 说明 |
|---|
smart | 等待所有客户端断开后关闭 |
fast | 回滚活动事务，断开客户端，正常关闭 |
immediate | 立即终止所有进程，下次启动需要恢复 |
pg restart
重启 PostgreSQL 服务器。
pig pg restart # 快速重启
pig pg reboot # 别名
pig pg restart -m immediate # 立即重启
pig pg restart -o "-p 5433" # 使用新选项重启
选项： 与 pg stop 相同，另外支持 --options（-o）传递给 postgres。
pg reload
重载 PostgreSQL 配置。向服务器发送 SIGHUP 信号。
pig pg reload # 重载配置
pig pg hup # 别名
pig pg reload -D /data/pg17 # 指定数据目录
pg status
显示 PostgreSQL 服务器状态。此命令不仅显示 pg_ctl status 的结果，还会显示 postgres 相关进程和 Pigsty 相关服务的状态。
pig pg status # 查看服务状态
pig pg st # 别名
pig pg status -D /data/pg17 # 指定数据目录
输出内容：
pg_ctl status 输出（进程是否运行、PID 等）- PostgreSQL 进程列表（
ps -u postgres） - 相关服务状态：
postgres：PostgreSQL systemd 服务patroni：Patroni HA 管理服务pgbouncer：连接池服务pgbackrest：备份服务vip-manager：VIP 管理服务haproxy：负载均衡服务
将备库提升为主库。
pig pg promote # 提升备库
pig pg pro # 别名
pig pg promote -D /data/pg17 # 指定数据目录
选项：
| 参数 | 简写 | 说明 |
|---|
--timeout | -t | 等待超时（秒） |
--no-wait | -W | 不等待提升完成 |
pg role
检测 PostgreSQL 实例的角色（主库或备库）。
pig pg role # 输出：primary、replica 或 unknown
pig pg role -V # 详细输出，显示检测过程
pig pg role -D /data/pg17 # 指定数据目录
选项：
| 参数 | 简写 | 说明 |
|---|
--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 sql # 别名
pig pg connect # 别名
pig pg psql mydb # 连接到指定数据库
pig pg psql mydb -c "SELECT 1" # 执行单条命令
pig pg psql -f script.sql # 执行 SQL 脚本文件
选项：
| 参数 | 简写 | 说明 |
|---|
--command | -c | 执行单条 SQL 命令 |
--file | -f | 执行 SQL 脚本文件 |
pg ps
显示 PostgreSQL 当前连接。查询 pg_stat_activity 视图。
pig pg ps # 显示客户端连接
pig pg activity # 别名
pig pg act # 别名
pig pg ps -a # 显示所有连接（包括系统进程）
pig pg ps -u admin # 按用户筛选
pig pg ps -d mydb # 按数据库筛选
选项：
| 参数 | 简写 | 说明 |
|---|
--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 -w 5 -x # 每 5 秒重复执行
选项：
| 参数 | 简写 | 说明 |
|---|
--execute | -x | 实际执行（默认为 dry-run） |
--pid | | 终止指定 PID |
--user | -u | 按用户筛选 |
--database | -d | 按数据库筛选 |
--state | -s | 按状态筛选（idle/active/idle in transaction） |
--query | -q | 按查询模式筛选 |
--all | -a | 包括复制连接 |
--cancel | -c | 取消查询而非终止连接 |
--watch | -w | 每 N 秒重复执行 |
安全说明： --state 和 --query 参数会进行标识符验证，只接受简单的字母数字模式，以防止 SQL 注入。
数据库维护命令
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 -n myschema # 清理指定 schema 中的表
pig pg vacuum mydb --full # VACUUM FULL（需要排他锁）
选项：
| 参数 | 简写 | 说明 |
|---|
--all | -a | 处理所有数据库 |
--schema | -n | 指定 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 # 分析指定表
选项： 与 pg vacuum 相同（不含 --full）。
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 -n myschema # 重整指定 schema 中的表
pig pg repack mydb -j 4 # 使用 4 个并行任务
pig pg repack mydb --dry-run # 显示将被重整的表
选项：
| 参数 | 简写 | 说明 |
|---|
--all | -a | 处理所有数据库 |
--schema | -n | 指定 schema |
--table | -t | 指定表名 |
--verbose | -V | 详细输出 |
--jobs | -j | 并行任务数（默认 1） |
--dry-run | -N | 显示将被重整的表 |
日志命令
日志命令用于查看 PostgreSQL 日志文件。默认日志目录为 /pg/log/postgres，可通过 --log-dir 参数指定其他目录。
日志命令全局参数：
| 参数 | 说明 |
|---|
--log-dir | 日志目录路径（默认：/pg/log/postgres） |
权限处理： 如果当前用户没有权限读取日志目录，命令会自动使用 sudo 重试。
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 | 显示的行数 |
pg log cat
输出日志文件内容。
pig pg log cat # 输出最新日志
pig pg log c # 别名
pig pg log cat -n 100 # 输出最后 100 行
pig pg log cat postgresql.csv # 输出指定日志文件
选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|
--lines | -n | 100 | 显示的行数 |
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 g ERROR # 别名
pig pg log search ERROR # 别名
pig pg log grep -i error # 忽略大小写
pig pg log grep -C 3 ERROR # 显示前后 3 行上下文
pig pg log grep ERROR pg.csv # 搜索指定日志文件
选项：
| 参数 | 简写 | 说明 |
|---|
--ignore-case | -i | 忽略大小写 |
--context | -C | 显示 N 行上下文 |
pg svc 子命令
pg svc 提供通过 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 - 维护命令（vacuum/analyze）调用
vacuumdb - repack 命令调用
pg_repack - 日志命令调用
tail、less、grep 等系统工具 pg svc 命令调用 systemctl
如需使用原生工具的完整功能，可直接调用相应命令。
权限处理：
- 如果当前用户已是 DBSU：直接执行命令
- 如果当前用户是 root：使用
su - postgres -c "..." 执行 - 其他用户：使用
sudo -inu postgres -- ... 执行
安全性考虑：
--state、--query、--schema、--table 等参数都经过标识符验证，防止 SQL 注入pg kill 默认为 dry-run 模式，避免误操作- 日志命令在权限不足时自动使用 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 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 perform manual failover
pig pt config <action> manage cluster config
Service Management (via systemctl):
pig pt status show comprehensive patroni status
pig pt start start patroni service (shortcut)
pig pt stop stop patroni service (shortcut)
pig pt svc start start patroni service
pig pt svc stop stop patroni service
pig pt svc restart restart patroni service
pig pt svc status show patroni service status
Logs:
pig pt log [-f] [-n 100] view patroni logs
命令概览
集群操作（patronictl 封装）：
| 命令 | 别名 | 描述 | 实现方式 |
|---|
pt list | ls, l | 列出集群成员 | patronictl list -e -t |
pt restart | reboot, rt | 重启 PostgreSQL 实例 | patronictl restart |
pt reload | rl, hup | 重载 PostgreSQL 配置 | patronictl reload |
pt reinit | ri | 重新初始化成员 | patronictl reinit |
pt switchover | sw | 计划内主从切换 | patronictl switchover |
pt failover | fo | 手动故障切换 | patronictl failover |
pt pause | p | 暂停自动故障切换 | patronictl pause |
pt resume | r | 恢复自动故障切换 | patronictl resume |
pt config | cfg, c | 查看或修改集群配置 | patronictl show-config / edit-config |
服务管理（systemctl 封装）：
| 命令 | 别名 | 描述 | 实现方式 |
|---|
pt start | boot, up | 启动 Patroni 服务 | systemctl start patroni |
pt stop | halt, dn, down | 停止 Patroni 服务 | systemctl stop patroni |
pt status | st, stat | 显示服务状态 | systemctl status patroni |
pt log | l, lg | 查看 Patroni 日志 | journalctl -u patroni |
服务子命令（pt svc）：
| 命令 | 别名 | 描述 |
|---|
pt svc start | boot, up | 启动 Patroni 服务 |
pt svc stop | halt, dn, down | 停止 Patroni 服务 |
pt svc restart | reboot, rt | 重启 Patroni 服务 |
pt svc reload | rl, hup | 重载 Patroni 服务 |
pt svc status | st, stat | 显示服务状态 |
快速入门
# 查看集群成员状态
pig pt list # 列出默认集群成员
pig pt list pg-meta # 列出指定集群成员
pig pt list -W # 持续监视模式
pig pt list -w 5 # 每 5 秒刷新一次
# 查看和修改集群配置
pig pt config # 显示当前集群配置
pig pt config ttl=60 # 修改单个配置项（直接生效）
pig pt config ttl=60 loop_wait=15 # 修改多个配置项
# 集群运维操作
pig pt restart # 重启所有成员的 PostgreSQL
pig pt restart pg-test-1 # 重启指定成员
pig pt switchover # 计划内主从切换
pig pt pause # 暂停自动故障切换
pig pt resume # 恢复自动故障切换
# 管理 Patroni 服务
pig pt status # 查看服务状态
pig pt start # 启动服务
pig pt stop # 停止服务
pig pt log -f # 实时查看日志
全局参数
以下参数适用于所有 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 pg-test -W -w 3 # 监视 pg-test 集群，3 秒刷新
选项：
| 参数 | 简写 | 说明 |
|---|
--watch | -W | 启用持续监视模式 |
--interval | -w | 监视刷新间隔（秒） |
pt restart
通过 Patroni 重启 PostgreSQL 实例。这会触发 PostgreSQL 的滚动重启，而非重启 Patroni 守护进程本身。
pig pt restart # 重启所有成员（交互式）
pig pt restart pg-test-1 # 重启指定成员
pig pt restart -f # 跳过确认直接重启
pig pt restart --role=replica # 仅重启从库
pig pt restart --pending # 重启待重启的成员
选项：
| 参数 | 简写 | 说明 |
|---|
--force | -f | 跳过确认 |
--role | | 按角色筛选（primary/replica） |
--pending | | 仅重启待重启的成员 |
pt reload
通过 Patroni 重载 PostgreSQL 配置。这会触发所有成员执行配置重载。
pt reinit
重新初始化集群成员。这会从主库重新同步数据。
pig pt reinit pg-test-1 # 重新初始化指定成员
pig pt reinit pg-test-1 -f # 跳过确认
pig pt reinit pg-test-1 --wait # 等待完成
选项：
| 参数 | 简写 | 说明 |
|---|
--force | -f | 跳过确认 |
--wait | -w | 等待重新初始化完成 |
警告： 此操作会删除目标成员的所有数据并重新同步。
pt switchover
执行计划内的主从切换。
pig pt switchover # 交互式切换
pig pt switchover -f # 跳过确认
pig pt switchover --leader pg-1 # 指定当前主库
pig pt switchover --candidate pg-2 # 指定新主库
选项：
| 参数 | 简写 | 说明 |
|---|
--force | -f | 跳过确认 |
--leader | | 指定当前主库 |
--candidate | | 指定候选新主库 |
pt failover
执行手动故障切换。用于主库不可用时强制切换。
pig pt failover # 交互式故障切换
pig pt failover -f # 跳过确认
pig pt failover --candidate pg-2 # 指定新主库
选项：
| 参数 | 简写 | 说明 |
|---|
--force | -f | 跳过确认 |
--candidate | | 指定候选新主库 |
pt pause
暂停 Patroni 的自动故障切换。
pig pt pause # 暂停自动故障切换
pig pt pause --wait # 等待确认
选项：
使用场景： 在执行维护操作（如大版本升级、存储迁移）时暂停自动故障切换，防止误触发。
pt resume
恢复 Patroni 的自动故障切换。
pig pt resume # 恢复自动故障切换
pig pt resume --wait # 等待确认
选项：
pt config
显示或修改集群配置。不带参数时显示当前配置，带 key=value 参数时修改配置。
pig pt config # 显示当前集群配置
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 参数
子命令：
| 子命令 | 说明 |
|---|
show（默认） | 显示当前配置 |
edit | 交互式编辑配置 |
set key=value | 直接设置配置项 |
pg key=value | 设置 PostgreSQL 参数 |
常用配置项：
| 配置项 | 说明 | 默认值 |
|---|
ttl | Leader 锁的生存时间（秒） | 30 |
loop_wait | 主循环休眠时间（秒） | 10 |
retry_timeout | DCS 和 PostgreSQL 操作超时（秒） | 10 |
maximum_lag_on_failover | 故障切换时允许的最大延迟（字节） | 1048576 |
注意： 此命令修改的是存储在 DCS（如 etcd）中的集群动态配置，而非本地配置文件 /etc/patroni/patroni.yml。
服务管理命令
pt start
启动 Patroni 服务。
pig pt start # 启动 Patroni 服务
pig pt up # 别名
pig pt boot # 别名
等效于执行 sudo systemctl start patroni。
pt stop
停止 Patroni 服务。
pig pt stop # 停止 Patroni 服务
pig pt down # 别名
pig pt halt # 别名
等效于执行 sudo systemctl stop patroni。
注意： 停止 Patroni 服务会导致该节点上的 PostgreSQL 实例也被停止（取决于 Patroni 配置）。
pt status
显示 Patroni 服务的综合状态，包括：
- systemd 服务状态
- Patroni 进程信息
- 集群成员状态
pt log
查看 Patroni 服务日志。
pig pt log # 显示最近 50 行日志
pig pt log -f # 实时跟踪日志输出
pig pt log -n 100 # 显示最近 100 行日志
pig pt log -f -n 200 # 显示最近 200 行并持续跟踪
选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|
--follow | -f | false | 实时跟踪日志输出 |
--lines | -n | 50 | 显示的日志行数 |
等效于执行 journalctl -u patroni [-f] [-n N]。
pt svc 子命令
pt svc 提供与顶层服务命令相同的功能，用于明确操作的是 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 | boot, up |
pt svc stop | halt, dn, down |
pt svc restart | reboot, rt |
pt svc reload | rl, hup |
pt svc status | st, stat |
设计说明
与 patronictl 的关系：
pig pt 封装了 patronictl 的常用操作：
- 集群查询：
list、config show - 集群管理：
restart、reload、reinit、switchover、failover、pause、resume - 配置修改：
config set、config edit - 服务管理命令（start/stop/restart/reload/status）调用
systemctl log 命令调用 journalctl
默认配置路径：
| 配置项 | 默认值 |
|---|
| Patroni 配置文件 | /etc/patroni/patroni.yml |
| 服务名称 | patroni |
权限处理：
- 如果当前用户已是 DBSU：直接执行命令
- 如果当前用户是 root：使用
su - postgres -c "..." 执行 - 其他用户：使用
sudo -inu postgres -- ... 执行
平台支持：
此命令专为 Linux 系统设计，依赖 systemctl 和 journalctl。
13 - pig pgbackrest
使用 pig pgbackrest 子命令管理 pgBackRest 备份与时间点恢复
pig pgbackrest 命令（别名 pig pb）用于管理 pgBackRest 备份和时间点恢复（PITR）。它封装了常用的 pgbackrest 操作，提供简化的备份管理体验。所有命令均以数据库超级用户身份（默认 postgres）执行。
pig pb - Manage pgBackRest backup and point-in-time recovery.
Information:
pig pb info show backup info
pig pb ls list backups
pig pb ls repo list configured repositories
pig pb ls stanza list all stanzas
Backup & Restore:
pig pb backup create backup (auto: full/incr)
pig pb backup full create full backup
pig pb restore restore from backup (PITR)
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 # restore to latest (default)
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 | 显示备份仓库信息 | pgbackrest info |
pb ls | 列出备份集 | pgbackrest info |
pb ls repo | 列出配置的仓库 | 解析 pgbackrest.conf |
pb ls stanza | 列出所有 stanza | 解析 pgbackrest.conf |
备份与恢复：
| 命令 | 描述 | 实现方式 |
|---|
pb backup | 创建备份 | pgbackrest backup |
pb restore | 从备份恢复（PITR） | pgbackrest restore |
pb expire | 清理过期备份 | pgbackrest expire |
Stanza 管理：
| 命令 | 描述 | 实现方式 |
|---|
pb create | 创建 stanza（首次设置） | pgbackrest stanza-create |
pb upgrade | 升级 stanza（PG 大版本升级后） | pgbackrest stanza-upgrade |
pb delete | 删除 stanza（危险操作！） | pgbackrest stanza-delete |
控制命令：
| 命令 | 别名 | 描述 | 实现方式 |
|---|
pb check | | 验证备份仓库完整性 | pgbackrest check |
pb start | | 启用 pgBackRest 操作 | pgbackrest start |
pb stop | | 禁用 pgBackRest 操作 | pgbackrest stop |
pb log | l, lg | 查看日志 | tail/cat 日志文件 |
快速入门
# 查看备份信息
pig pb info # 显示所有备份信息
pig pb info -o json # 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 # 增量备份
# 恢复（PITR）
pig pb restore # 恢复到最新（WAL 流末尾）
pig pb restore -I # 恢复到备份一致性点
pig pb restore -t "2025-01-01 12:00:00+08" # 恢复到指定时间
pig pb restore -n savepoint # 恢复到命名还原点
# Stanza 管理
pig pb create # 初始化 stanza
pig pb upgrade # PG 大版本升级后升级 stanza
pig pb check # 验证仓库完整性
# 清理
pig pb expire # 按保留策略清理
pig pb expire --dry-run # 干运行模式
全局参数
以下参数适用于所有 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 -o json # JSON 格式输出
pig pb info --set 20250101-120000F # 显示特定备份集详情
选项：
| 参数 | 简写 | 说明 |
|---|
--output | -o | 输出格式：text、json |
--set | | 显示特定备份集详情 |
pb ls
列出备份仓库中的资源。
pig pb ls # 列出所有备份（默认）
pig pb ls backup # 列出所有备份（显式）
pig pb ls repo # 列出配置的仓库
pig pb ls stanza # 列出所有 stanza
pig pb ls cluster # 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 --dry-run # 干运行模式（仅显示）
选项：
| 参数 | 说明 |
|---|
--set | 删除特定备份集 |
--dry-run | 干运行模式：仅显示将删除的内容 |
保留策略配置：
保留策略在 pgbackrest.conf 中配置：
[global]
repo1-retention-full=2 # 保留的全量备份数
repo1-retention-diff=4 # 保留的差异备份数
repo1-retention-archive=2 # WAL 归档保留策略
恢复命令
pb restore
从备份恢复，支持时间点恢复（PITR）。
# 恢复目标（互斥选项）
pig pb restore # 恢复到最新（默认）
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 -n my-savepoint # 恢复到命名还原点
pig pb restore -l "0/7C82CB8" # 恢复到 LSN
pig pb restore -x 12345 # 恢复到事务 ID
# 备份集选择（可与恢复目标组合）
pig pb restore -b 20251225-120000F # 从特定备份集恢复
# 其他选项
pig pb restore -t "..." -X # 排他模式（在目标前停止）
pig pb restore -t "..." -P # 恢复后自动提升
pig pb restore -y # 跳过确认倒计时
恢复目标选项：
| 参数 | 简写 | 说明 |
|---|
--default | -d | 恢复到 WAL 流末尾（最新数据） |
--immediate | -I | 恢复到备份一致性点 |
--time | -t | 恢复到指定时间戳 |
--name | -n | 恢复到命名还原点 |
--lsn | -l | 恢复到指定 LSN |
--xid | -x | 恢复到指定事务 ID |
备份集和其他选项：
| 参数 | 简写 | 说明 |
|---|
--set | -b | 从特定备份集恢复（可与目标组合） |
--data | -D | 目标数据目录 |
--exclusive | -X | 排他模式：在目标前停止 |
--promote | -P | 恢复后自动提升为主库 |
--yes | -y | 跳过确认和倒计时 |
时间格式：
支持多种时间格式输入，自动补全时区（支持非整小时时区如 +05:30）：
| 格式 | 示例 | 说明 |
|---|
| 完整格式 | 2025-01-01 12:00:00+08 | 包含时区的完整时间戳 |
| 仅日期 | 2025-01-01 | 自动补全为当天 00:00:00（当前时区） |
| 仅时间 | 12:00:00 | 自动补全为今天（当前时区） |
恢复流程：
- 验证参数和环境
- 检查 PostgreSQL 已停止
- 显示恢复计划，等待确认（5 秒倒计时）
- 执行 pgbackrest restore
- 提供恢复后的操作指引
重要提示： 恢复前必须先停止 PostgreSQL：
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 --force # 删除 stanza（需要 --force）
pig pb delete --force --yes # 跳过倒计时确认
选项：
| 参数 | 简写 | 说明 |
|---|
--force | -f | 确认删除（必需） |
--yes | -y | 跳过倒计时确认 |
警告： 这是一个破坏性且不可逆的操作！所有备份将被永久删除。
命令包含多重安全机制：
- 必须提供
--force 参数 - 5 秒倒计时确认（可按 Ctrl+C 取消）
- 使用
--yes 可跳过倒计时
控制命令
pb check
验证备份仓库的完整性和配置。
此命令检查：
- WAL 归档配置是否正确
- 仓库是否可访问
- stanza 配置是否有效
pb start
启用 pgBackRest 操作。
在执行 pb stop 后使用此命令恢复正常操作。
pb stop
禁用 pgBackRest 操作（用于维护）。
pig pb stop # 禁用操作
pig pb stop --force # 终止正在运行的操作
选项：
使用场景：
在进行系统维护时，使用此命令阻止新的备份操作启动。
日志命令
pb log
查看 pgBackRest 日志文件。日志目录为 /pg/log/pgbackrest/。
pig pb log # 列出日志文件
pig pb log list # 列出日志文件
pig pb log tail # 实时查看最新日志
pig pb log tail -n 100 # 显示最后 100 行并跟踪
pig pb log cat # 显示最新日志内容
pig pb log cat -n 50 # 显示最后 50 行
pig pb log cat pg-meta-backup.log # 显示指定日志文件
子命令：
| 子命令 | 别名 | 说明 |
|---|
| list | ls | 列出日志文件 |
| tail | follow, f | 实时跟踪最新日志 |
| cat | show | 显示日志内容 |
选项：
| 参数 | 简写 | 默认值 | 说明 |
|---|
--lines | -n | 50 | 显示的行数 |
权限处理：
如果当前用户没有权限读取日志目录，命令会自动使用 sudo 重试。
设计说明
命令执行方式：
所有 pig pb 命令都以数据库超级用户（DBSU）身份执行。这是因为 pgBackRest 需要访问 PostgreSQL 数据文件和 WAL 归档。
执行逻辑：
- 如果当前用户已是 DBSU：直接执行命令
- 如果当前用户是 root：使用
su - postgres -c "..." 执行 - 其他用户：使用
sudo -inu postgres -- ... 执行
与 pgbackrest 的关系：
pig pb 并非 pgbackrest 的完整封装，而是针对常用操作的上层抽象：
- 自动检测 stanza 名称，无需每次指定
- 备份前自动检查主库角色
- 恢复时显示计划并要求确认
- 提供人性化的时间格式输入
- 恢复后提供操作指引
如需使用 pgbackrest 的完整功能，请直接使用 pgbackrest 命令。
默认配置路径：
| 配置项 | 默认值 |
|---|
| 配置文件 | /etc/pgbackrest/pgbackrest.conf |
| 日志目录 | /pg/log/pgbackrest |
| 数据目录 | 配置文件中的 pg1-path，或 $PGDATA 环境变量，或 /pg/data |
安全考虑：
pb delete 需要 --force 确认，并有 5 秒倒计时pb restore 显示恢复计划，有 5 秒倒计时确认pb backup 默认检查主库角色，防止在备库执行- 日志命令的文件名参数会过滤路径，防止路径遍历攻击
平台支持：
此命令专为 Linux 系统设计，依赖 Pigsty 的默认目录结构。
14 - pig pitr
使用 pig pitr 命令执行编排式时间点恢复（PITR）
pig pitr 命令用于执行编排式时间点恢复（Orchestrated Point-In-Time Recovery）。与 pig pb restore 不同，此命令会自动协调 Patroni、PostgreSQL 和 pgBackRest，完成完整的 PITR 工作流。
pig pitr - Perform PITR with automatic Patroni/PostgreSQL lifecycle management.
This command orchestrates a complete PITR workflow:
1. Stop Patroni service (if running)
2. Ensure PostgreSQL is stopped (with retry and fallback)
3. Execute pgbackrest restore
4. Start PostgreSQL
5. 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, -n Recover to named restore point
--lsn, -l Recover to specific LSN
--xid, -x Recover to specific transaction ID
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 (most common)
pig pitr -t "2025-01-01 12:00" # Recover to specific time
pig pitr -I # Recover to backup consistency point
pig pitr -d --plan # Show execution plan without running
pig pitr -d --dry-run # alias for --plan
pig pitr -d -y # Skip confirmation (for automation)
pig pitr -d --skip-patroni # Skip Patroni management
pig pitr -d --no-restart # Don't auto-start PostgreSQL after restore
命令概览
pig pitr 是一个高度自动化的恢复命令，它会：
- 自动停止 Patroni 服务（如果正在运行）
- 确保 PostgreSQL 已停止（带重试和降级策略）
- 执行 pgBackRest 恢复
- 启动 PostgreSQL
- 提供恢复后的操作指引
与 pig pb restore 的区别：
| 特性 | pig pitr | pig pb restore |
|---|
| 停止 Patroni | 自动 | 手动 |
| 停止 PostgreSQL | 自动（带重试） | 需要预先停止 |
| 启动 PostgreSQL | 自动 | 手动 |
| 恢复后指引 | 提供详细指引 | 无 |
| 适用场景 | 生产环境完整恢复 | 底层操作或脚本集成 |
快速入门
# 最常用：恢复到最新数据
pig pitr -d
# 恢复到指定时间点
pig pitr -t "2025-01-01 12:00:00+08"
# 恢复到备份一致性点（最快）
pig pitr -I
# 查看执行计划（不实际执行）
pig pitr -d --plan
pig pitr -d --plan -o yaml # 结构化执行计划（YAML）
# 跳过确认（用于自动化）
pig pitr -d -y
# 从特定备份集恢复
pig pitr -d -b 20251225-120000F
# 独立 PostgreSQL（非 Patroni 管理）
pig pitr -d --skip-patroni
# 恢复后不自动启动 PostgreSQL
pig pitr -d --no-restart
参数说明
恢复目标（必选其一）
| 参数 | 简写 | 说明 |
|---|
--default | -d | 恢复到 WAL 流末尾（最新数据） |
--immediate | -I | 恢复到备份一致性点 |
--time | -t | 恢复到指定时间戳 |
--name | -n | 恢复到命名还原点 |
--lsn | -l | 恢复到指定 LSN |
--xid | -x | 恢复到指定事务 ID |
备份选择
流程控制
| 参数 | 简写 | 说明 |
|---|
--skip-patroni | -S | 跳过 Patroni 停止操作 |
--no-restart | -N | 恢复后不自动启动 PostgreSQL |
--plan | | 仅显示执行计划，不实际执行 |
--dry-run | | --plan 的别名 |
--yes | -y | 跳过确认倒计时 |
结构化执行计划
当使用 --plan / --dry-run 时，可配合 -o yaml|json 输出结构化执行计划，适合自动化审阅与编排。
pig pitr -d --plan -o json
恢复选项
| 参数 | 简写 | 说明 |
|---|
--exclusive | -X | 排他模式：在目标前停止 |
--promote | -P | 恢复后自动提升为主库 |
配置参数
| 参数 | 简写 | 说明 |
|---|
--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 | 自动补全为当天 00:00:00（当前时区） |
| 仅时间 | 12:00:00 | 自动补全为今天（当前时区） |
执行流程
第一阶段：预检查
- 验证恢复目标参数（必须且只能指定一个）
- 检查数据目录是否存在且已初始化
- 检测 Patroni 服务状态
- 检测 PostgreSQL 运行状态
第二阶段：停止 Patroni
如果 Patroni 服务正在运行且未指定 --skip-patroni：
- 执行
systemctl stop patroni - 等待 PostgreSQL 随 Patroni 自动停止
第三阶段：确保 PostgreSQL 停止
采用渐进式策略确保 PostgreSQL 完全停止：
- 等待自动停止：Patroni 停止后等待 30 秒
- 优雅停止：使用
pg_ctl stop -m fast（最多重试 3 次，指数退避） - 立即停止：使用
pg_ctl stop -m immediate - 强制终止：使用
kill -9（最后手段）
第四阶段：执行恢复
调用 pgBackRest 执行实际的数据恢复：
pgbackrest restore --target-action=promote ...
第五阶段：启动 PostgreSQL
除非指定 --no-restart，否则自动启动 PostgreSQL：
第六阶段：恢复后指引
显示详细的后续操作指引，包括：
- 如何验证恢复的数据
- 如何提升为主库
- 如何恢复 Patroni 集群管理
- 如何重新创建 pgBackRest stanza
使用示例
场景一：误删数据恢复
# 1. 查看可用的备份
pig pb info
# 2. 恢复到误删前的时间点
pig pitr -t "2025-01-15 09:30:00+08"
# 3. 验证数据
pig pg psql
SELECT * FROM important_table;
# 4. 确认无误后提升为主库
pig pg promote
场景二：恢复到最新状态
# 服务器故障后恢复到最新数据
pig pitr -d
场景三：快速恢复到备份点
# 恢复到备份一致性点（不需要回放 WAL）
pig pitr -I
场景四：自动化脚本
# 跳过所有确认，适合自动化
pig pitr -d -y
场景五：独立 PostgreSQL 实例
# 非 Patroni 管理的实例
pig pitr -d --skip-patroni
场景六：仅恢复不启动
# 恢复后手动检查，再决定是否启动
pig pitr -d --no-restart
# 检查恢复的数据目录
ls -la /pg/data/
# 手动启动
pig pg start
执行计划示例
执行 pig pitr -d --plan（或 --dry-run）会显示类似以下的执行计划：
══════════════════════════════════════════════════════════════════
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
══════════════════════════════════════════════════════════════════
[Dry-run mode] No changes made.
恢复后操作
成功恢复后，命令会显示详细的后续操作指引：
══════════════════════════════════════════════════════════════════
PITR Complete
══════════════════════════════════════════════════════════════════
[1] Verify recovered data:
pig pg psql
[2] If satisfied, promote to primary:
pig pg promote
[3] To resume Patroni cluster management:
WARNING: Ensure data is correct before starting Patroni!
systemctl start patroni
Or if you want this node to be the leader:
1. Promote PostgreSQL first: pig pg promote
2. Then start Patroni: systemctl start patroni
[4] Re-create pgBackRest stanza if needed:
pig pb create
══════════════════════════════════════════════════════════════════
安全机制
确认倒计时
除非使用 --yes 参数，命令执行前会显示 5 秒倒计时：
WARNING: This will overwrite the current database!
Press Ctrl+C to cancel, or wait for countdown...
Starting PITR in 5 seconds...
渐进式停止策略
为确保数据安全，停止 PostgreSQL 采用渐进式策略：
- 先尝试优雅停止（保证数据一致性）
- 失败后尝试立即停止
- 最后才使用 kill -9（仅在极端情况）
恢复验证
恢复后自动验证 PostgreSQL 是否成功启动，如果失败会提示检查日志。
设计说明
与其他命令的关系：
pig pitr 内部调用 pig pt stop、pig pg stop、pig pg start 和 pig pb restore- 提供比单独命令更高级别的自动化协调
- 适合生产环境的完整 PITR 工作流
错误处理：
- 每个阶段都有详细的错误信息
- 失败时提示相关日志位置
- 支持中断后手动继续
权限执行：
- 如果当前用户已是 DBSU：直接执行命令
- 如果当前用户是 root：使用
su - postgres -c "..." 执行 - 其他用户：使用
sudo -inu postgres -- ... 执行
平台支持：
此命令专为 Linux 系统设计，依赖 Pigsty 的默认目录结构。