这是本节的多页打印视图。 .

返回本页常规视图.

pig 1.8 文档

PostgreSQL 扩展生态包管理器与管理命令行工具

—— Postgres Install Genius，PostgreSQL 生态中缺失的扩展包管理器

PIG 包管理器是一个专门用于安装、管理、构建 PostgreSQL 及其扩展的命令行工具，使用 Go 开发，开箱即用，简单易用，小巧玲珑（约 5MB）。 PIG 包管理器并非重新发明的土鳖轮子，而是 依托 （PiggyBack）现有 Linux 发行版包管理器 （apt/dnf）的一个高级抽象层。 它屏蔽了不同操作系统，不同芯片架构，以及不同 PG 大版本的管理差异，让您用简单的几行命令，就可以完成 PG 内核与 575 个已打包扩展的安装与管理。

PIG 的命令设计同样适合自动化脚本：提供统一的参数风格、清晰的错误提示，以及如 --plan 等预览开关与确认步骤。

请注意：对于扩展安装来说，pig 并非必须组件，您依然可以使用 apt / dnf 等包管理器直接访问 Pigsty PGSQL 仓库。

  • 简介：为什么需要专用的 PG 包管理器？
  • 上手：快速上手与样例
  • 安装：下载、安装、更新 pig

快速上手

使用以下命令即可在您的系统上 安装 PIG 包管理器：

默认安装（Cloudflare CDN）：

BASH
curl -fsSL https://repo.pigsty.io/pig | bash

中国镜像：

BASH
curl -fsSL https://repo.pigsty.cc/pig | bash

安装完成后，几行命令即可 快速开始。例如，若需安装 PG 18 与相应的 pg_duckdb 扩展：

BASH
$ 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 sty：管理 Pigsty 安装与 Grafana 仪表盘
  • pig inventory：检视、编辑、校验与交换 Pigsty 配置清单
  • pig context：采集主机、PostgreSQL、Patroni、pgBackRest 与扩展上下文
  • pig pg：管理本地 PostgreSQL 服务
  • pig pt：透明运行 patronictl 管理 Patroni HA 集群
  • pig pb：管理 pgBackRest 备份
  • pig pitr：时间点恢复工作流

关于

pig 命令行工具由 Vonng（冯若航 rh@vonng.com）开发，并以 Apache 2.0 许可证开源。

您还可以参考 PIGSTY 项目，提供了包括扩展交付在内的完整 PostgreSQL RDS DBaaS 使用体验。

  • PGEXT：扩展数据与管理工具
  • PIG：PostgreSQL 包管理器
  • PIGSTY：开箱即用的 PostgreSQL 发行版

1 - 上手

快速上手 pig，PostgreSQL 包管理器

下面是一个简单的上手教程，带您体验 PIG 包管理器的核心能力。

简短版本

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

中国大陆：

BASH
curl -fsSL https://repo.pigsty.cc/pig | bash

全球网站（Cloudflare CDN）：

BASH
curl -fsSL https://repo.pigsty.io/pig | bash

PIG 二进制包大约 5 MB，在 Linux 上会自动使用 rpm 或 dpkg 安装所选镜像中的最新可用版本。下方示例输出中的 X.Y.Z 代表该镜像版本：

BASH
$ 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/vX.Y.Z/pig_X.Y.Z-1_amd64.deb
[INFO] download = /tmp/pig_X.Y.Z-1_amd64.deb
[INFO] downloading pig vX.Y.Z
curl -fSL https://repo.pigsty.cc/pkg/pig/vX.Y.Z/pig_X.Y.Z-1_amd64.deb -o /tmp/pig_X.Y.Z-1_amd64.deb
######################################################################## 100.0%
[INFO] installing: dpkg -i /tmp/pig_X.Y.Z-1_amd64.deb
(Reading database ... 166001 files and directories currently installed.)
Preparing to unpack /tmp/pig_X.Y.Z-1_amd64.deb ...
Unpacking pig (X.Y.Z-1) ...
Setting up pig (X.Y.Z-1) ...
[INFO] pig vX.Y.Z installed successfully
check https://pgext.cloud for details

检查环境

PIG 是一个由 Go 编写的二进制程序，默认安装路径为 /usr/bin/pig，pig version 会打印版本信息：

BASH
$ pig version
pig version 1.7.0 linux/amd64

使用 pig status 命令，会打印当前环境的状态，操作系统代码，PG 的安装情况，仓库的可访问性与延迟。

BASH
$ pig status
# [Configuration] ================================
Pig Version      : 1.7.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.6 (Ubuntu 18.6-1.pgdg26.04+1)  72  Extensions

Active:
PG Version      :  PostgreSQL 18.6 (Ubuntu 18.6-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 :  4.5.0

自动化建议

对于生产环境恢复任务，建议先使用 --plan 预览 PITR 执行计划，再决定是否实际执行：

BASH
pig pitr -d --plan            # 仅预览恢复步骤，不执行
pig pitr -d -y                # 跳过确认（自动化场景）

列出扩展

先使用 pig ext reload 刷新在线目录，再使用 pig ext list 打印当前的 PG 扩展数据目录。

BASH
$ pig ext list
✓ Found 575 extensions
Name                Status     Version     Cate   Flags   License         Repo     PGVer  Package                               Description
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
timescaledb         available  2.29.1      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

(575 Rows)

所有的扩展元数据都在一份名为 extension.csv 的数据文件中定义， 这份文件会随着 pig 版本发布不断更新，您可以直接使用 pig ext reload 命令更新这份数据文件。 更新后的文件会默认放置于 ~/.pig/extension.csv 中，您可以查阅与更改；在线最新版目录可在 pigsty.io/ext/data/extension.csv 获取。

当前文档统一按 575 个已打包扩展表述；各扩展在不同 PostgreSQL 版本、操作系统与架构上的可用性，以实时支持矩阵为准。

添加仓库

要想安装扩展，首先需要添加上游仓库。pig repo 可用于管理 Linux APT/YUM/DNF 软件仓库配置。

您可以使用简单粗暴直接的版本 pig repo set 覆盖式写入现有仓库配置，该命令确保系统中只存在必须的仓库配置：

BASH
pig repo set                # 一次性配置好所有仓库，包括 Linux 系统仓库，PGDG，PIGSTY (PGSQL+INFRA) 仓库

警告：pig repo set 会备份并清理现有的仓库配置，然后添加所需的仓库，实现 Overwrite 语义，请务必注意！

或者选择使用温和的 pig repo add 添加所需的仓库：

BASH
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 参数强制指定区域。 在中国网络环境中，-m|--mirror 会明确选择内置的 china 仓库定义，包括 pigsty.cc 与维护中的国内镜像。

BASH
pig repo set      --region=china              # 使用中国区域镜像仓库加速下载
pig repo add pgdg --region=default --update   # 强制指定使用 PGDG 上游仓库
pig repo set -m                                # 使用中国区域镜像覆盖式设置仓库

PIG 本身不支持离线安装，您可以自行下载 RPM/DEB 包，拷贝到网络隔离的生产服务器安装。 相关项目 PIGSTY 提供本地软件仓库，支持可以使用 pig 从本地软件仓库安装已经下载好的扩展。

安装 PG

添加仓库后，您可以使用 pig ext add 子命令安装扩展（以及相关软件包）

BASH
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 参数：

BASH
pig install vector     # 带有翻译机制，安装当前 PG 18 对应的 pgvector_18 或 postgresql-18-pgvector
pig install vector -n  # 关闭翻译机制，安装名为 vector 的日志收集组件（来自 pigsty-infra 仓库）

别名翻译

PostgreSQL 内核与扩展对应着一系列的 RPM/DEB 包，记住这些包是一件麻烦事，所以 pig 提供了许多常用的别名，帮助您简化安装过程：

例如在 EL 系统上， 下面的别名将会被翻译为右侧的对应 RPM 包列表：

YAML
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 使用的别名翻译列表

BASH
"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 系统使用的别名翻译

BASH
"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，可以直接使用下面这些别名：

pgsqlpg18pg17pg16pg15pg14
pgsqlpg18pg17pg16pg15pg14
pgsql-minipg18-minipg17-minipg16-minipg15-minipg14-mini
pgsql-corepg18-corepg17-corepg16-corepg15-corepg14-core
pgsql-fullpg18-fullpg17-fullpg16-fullpg15-fullpg14-full
pgsql-mainpg18-mainpg17-mainpg16-mainpg15-mainpg14-main
pgsql-clientpg18-clientpg17-clientpg16-clientpg15-clientpg14-client
pgsql-serverpg18-serverpg17-serverpg16-serverpg15-serverpg14-server
pgsql-develpg18-develpg17-develpg16-develpg15-develpg14-devel
pgsql-basicpg18-basicpg17-basicpg16-basicpg15-basicpg14-basic

安装扩展

pig 会检测当前系统环境中的 PostgreSQL 安装情况。如果检测到环境中（以 PATH 中的 pg_config 为准）有活跃的 PG 安装，那么 pig 会自动安装对应 PG 大版本所需的扩展，无需您显式指定 PG 大版本。

BASH
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 命令：

BASH
pig ext link pg18             # 创建 /usr/pgsql 软链接，并写入 /etc/profile.d/pgsql.sh
. /etc/profile.d/pgsql.sh     # 立即生效，更新 PATH 环境变量

如果你想要安装特定版本的软件，可以使用 name=ver 的语法：

BASH
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 命令可以用于显示当前安装的扩展。

以下输出用于展示命令格式，是一次环境快照；PostgreSQL 小版本与扩展版本会随操作系统仓库更新，请以本机实时输出和当前软件包目录为准。

BASH
$ pig ext status

✓ PostgreSQL 18: 72 extensions installed (3 shown)
PostgreSQL 18: PostgreSQL 18.6 (Ubuntu 18.6-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 目录下的共享库，从而发现安装了哪些扩展：

以下同样是历史环境快照，而不是 v4.5.0 候选软件包版本清单。

BASH
$ 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：

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
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 及其 575 个扩展。 无论是 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_64EL77.9CentOS 7 x8613-15EOL
el8.x86_64EL88.10RockyLinux 8 x8614-18即将 EOL
el8.aarch64EL88.10RockyLinux 8 ARM14-18即将 EOL
el9.x86_64EL99.8RockyLinux 9 x8614-18✅
el9.aarch64EL99.8RockyLinux 9 ARM14-18✅
el10.x86_64EL1010.2RockyLinux 10 x8614-18✅
el10.aarch64EL1010.2RockyLinux 10 ARM14-18✅
d11.x86_64Debian1111.11Debian 11 x8614-18EOL
d11.aarch64Debian1111.11Debian 11 ARM14-18EOL
d12.x86_64Debian1212.15Debian 12 x8614-18✅
d12.aarch64Debian1212.15Debian 12 ARM14-18✅
d13.x86_64Debian1313.6Debian 13 x8614-18✅
d13.aarch64Debian1313.6Debian 13 ARM14-18✅
u22.x86_64Ubuntu2222.04.5Ubuntu 22.04 x8614-18✅
u22.aarch64Ubuntu2222.04.5Ubuntu 22.04 ARM14-18✅
u24.x86_64Ubuntu2424.04.4Ubuntu 24.04 x8614-18✅
u24.aarch64Ubuntu2424.04.4Ubuntu 24.04 ARM14-18✅
u26.x86_64Ubuntu2626.04.0Ubuntu 26.04 x8614-18✅
u26.aarch64Ubuntu2626.04.0Ubuntu 26.04 ARM14-18✅

说明：

  • EL 指 RHEL 兼容发行版，包括 RHEL、CentOS、RockyLinux、AlmaLinux、OracleLinux 等
  • EOL 表示该操作系统已经或即将停止支持，建议升级到更新版本
  • ✅ 表示完整支持，推荐使用
  • PG 版本 14-18 表示支持 PostgreSQL 14、15、16、17、18 五个大版本

3 - 安装

如何下载与安装 pig 包管理器

脚本安装

安装 pig 最简单的方式是运行以下安装脚本：

默认安装（Cloudflare CDN）：

BASH
curl -fsSL https://repo.pigsty.io/pig | bash

中国镜像：

BASH
curl -fsSL https://repo.pigsty.cc/pig | bash

该脚本会从 Pigsty 软件仓库 下载最新版 pig 的 RPM / DEB 包，并通过 rpm 或 dpkg 进行安装。 脚本安装面向 Linux x86_64 / aarch64 的 RPM / DEB 系发行版；macOS 可使用发布压缩包中的二进制。

指定版本

您可以指定已经发布到所选镜像的特定版本，将版本号作为参数传入即可：

默认安装（Cloudflare CDN）：

BASH
curl -fsSL https://repo.pigsty.io/pig | bash -s X.Y.Z

中国镜像：

BASH
curl -fsSL https://repo.pigsty.cc/pig | bash -s X.Y.Z

镜像发布可能晚于 GitHub Release；如需精确获取当前版本，请使用下方 GitHub 制品。

发布产物下载

当前 v1.8.0 安装包（RPM/DEB/压缩包）可从 GitHub Release 获取，发布哈希见 checksums.txt。直接下载格式如下：

  • https://github.com/pgsty/pig/releases/download/v1.8.0/<filename>
TEXT
v1.8.0
├── pig_1.8.0-1_amd64.deb
├── pig_1.8.0-1_arm64.deb
├── pig-1.8.0-1.aarch64.rpm
├── pig-1.8.0-1.x86_64.rpm
├── pig-v1.8.0.linux-amd64.tar.gz
├── pig-v1.8.0.linux-arm64.tar.gz
├── pig-v1.8.0.darwin-amd64.tar.gz
└── pig-v1.8.0.darwin-arm64.tar.gz

将其解压后，将二进制文件放入您的 PATH 系统路径中即可。 对应的 Pigsty 镜像目录会在软件仓库同步后可用；使用锁定版本的安装命令前，请先检查目标 URL。

仓库安装

pig 软件位于 pigsty-infra 仓库中。你可以将该仓库添加到操作系统后，使用操作系统的包管理器进行安装：

YUM

对于 RHEL，RockyLinux，CentOS，Alma Linux，OracleLinux 等 EL 系发行版：

BASH
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 系发行版：

BASH
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 版本升级至最新可用版本，可以使用以下命令：

BASH
pig update            # 将 pig 自身升级到最新版
pig update -m         # 使用 pigsty.cc 镜像升级
pig update -v X.Y.Z   # 升级到已发布在当前软件仓库中的指定版本

若要将现有 pig 的扩展数据升级至最新可用版本，可以使用以下命令：

BASH
pig ext reload        # 将 pig 扩展数据更新至最新版本

卸载

BASH
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

BASH
git clone https://github.com/pgsty/pig.git; cd pig
go mod download
make build

所有 RPM / DEB 包都通过 GitHub CI/CD 流程使用 goreleaser 自动化构建。

4 - 版本

pig —— PostgreSQL 包管理器的发布说明

最新稳定版本是 v1.8.0。

版本日期摘要GitHub
v1.8.02026-08-14原生 sty boot 与 sty conf，575 个已打包扩展v1.8.0
v1.7.02026-08-12EL 模块策略、中国镜像与 EL7 兼容目录，575 个扩展v1.7.0
v1.6.22026-08-11572 个扩展，Grafana schema v2，SOW 优先的软件仓库生成v1.6.2
v1.6.12026-07-30扩展目录刷新，内置 Pigsty 版本对齐到 4.5.0v1.6.1
v1.6.02026-07-28562 个已打包扩展，pt 原生透传，inventory 与 CMDB，Grafana 管理v1.6.0
v1.5.12026-07-08PG 内核分支包更新，镜像模式，修复若干问题v1.5.1
v1.5.02026-07-04531 个扩展，pigsty v4.4，pg/pb/pt/pitr 重做，clone/forkv1.5.0
v1.4.22026-06-18524 个扩展，PG19 beta，pgrx 0.18.1，Patroni 修复v1.4.2
v1.4.12026-05-01510 个扩展，支持 Ubuntu 26.04，仓库校准v1.4.1
v1.4.02026-04-19510 个扩展，pgrx 0.18.0，更多构建规格v1.4.0
v1.3.42026-04-14504 扩展更新与发布产物校验和刷新v1.3.4
v1.3.32026-04-10481 扩展与 Go 1.26.2 更新v1.3.3
v1.3.22026-03-23例行元数据更新，新增 pg tune 与构建别名v1.3.2
v1.3.12026-03-05PG13 退役，支持窗口统一为 PG14-18，扩展增至 464v1.3.1
v1.3.02026-02-27构建链路强化，扩展增至 461，新内核支持v1.3.0
v1.2.02026-02-23统一别名，例行更新，计划模式，仓库修复v1.2.0
v1.1.02026-02-12451 扩展，Agent-Native CLI 框架v1.1.0
v1.0.02026-01-26444, 新增 pg/pt/pb/pitr 子命令，可用性矩阵v1.0.0
v0.8.02025-12-26440 extensions，移除 sysupdate 仓库v0.8.0
v0.7.52025-12-12常规扩展更新，使用修复后的阿里云镜像v0.7.5
v0.7.42025-12-01更新 ivory/pgtde 内核与 pgdg extras 仓库v0.7.4
v0.7.32025-11-24修复 el10 & debian13 仓库配置v0.7.3
v0.7.22025-11-20437 个扩展，修复 pig build 的一些问题v0.7.2
v0.7.12025-11-10新网站，改进容器内的使用体验v0.7.1
v0.7.02025-11-05强化 build 能力，大批量包更新v0.7.0
v0.6.22025-10-03正式提供 PG 18 支持v0.6.2
v0.6.12025-08-14CI/CD, el10 存根，PGDG 中国镜像v0.6.1
v0.6.02025-07-17423 个扩展，percona pg_tde，mcp 工具箱v0.6.0
v0.5.02025-06-30422 个扩展，新的扩展目录v0.5.0
v0.4.22025-05-27421 个扩展，halo 和 oriole debv0.4.2
v0.4.12025-05-07414 个扩展，pg18 别名支持v0.4.1
v0.4.02025-05-01do 和 pt 子命令，halo 和 orioledbv0.4.0
v0.3.42025-04-05常规更新v0.3.4
v0.3.32025-03-25别名、仓库、依赖v0.3.3
v0.3.22025-03-21新扩展v0.3.2
v0.3.12025-03-19轻微错误修复v0.3.1
v0.3.02025-02-24新主页和扩展目录v0.3.0
v0.2.22025-02-22404 个扩展v0.2.2
v0.2.02025-02-14400 个扩展v0.2.0
v0.1.42025-02-12常规错误修复v0.1.4
v0.1.32025-01-23390 个扩展v0.1.3
v0.1.22025-01-12anon 扩展和其他 350 个扩展v0.1.2
v0.1.12025-01-09更新扩展列表v0.1.1
v0.1.02024-12-29repo、ext、sty 和自更新v0.1.0
v0.0.12024-12-23创世发布v0.0.1

v1.8.0

Pig v1.8.0 是 v1.7.0 之上的控制节点工作流更新版本：pig sty boot 与 pig sty conf 已由 Go 原生实现，不再包装旧版 bootstrap 与 configure Shell 脚本。 已打包 PostgreSQL 扩展数量保持 575，内置 Pigsty 版本保持 4.5.0。

主要变化

  • pig sty boot 现在可以自动提权，实际校验 Ansible 及其 Python 运行时，并支持显式本地包、 HTTP(S) URL、可信自动离线包、已提交本地仓库与区域在线仓库。仓库替换默认带备份与失败回滚， 本机 SSH 和缺失的 ~/pigsty 则以尽力而为方式修复。
  • pig sty conf 现在从安全模板原生生成 Inventory，支持最多十个 IP、精确域名替换、区域与代理、 PostgreSQL 版本和随机口令配置；候选配置通过完整校验后，以 0600 权限原子写入。
  • 引导下载与解压不再依赖 curl、wget、tar 或 gzip；离线模式严格限定为 pigsty-local，并补齐 /www -> /data/nginx 仓库布局。
  • EL8 及以上软件包操作统一优先使用 DNF，本地 RPM 依赖按提供能力解析；例行刷新扩展元数据与 可用性矩阵，并升级到 Go 1.26.6 发布工具链。

兼容性提醒

  • pig sty boot 不再执行 <PIGSTY_HOME>/bootstrap，依赖脚本副作用的自动化需要迁移到原生命令。
  • pig sty conf --raw 已移除；--conf MODE 与位置参数 MODE 等价。--ip 最多接受十个地址， 且不能与 --skip 同时使用。
  • EL8 及以上使用 DNF；有限的 EL7 兼容目录继续使用独立的传统 YUM 路径。

校验和

制品：GitHub Release · checksums.txt

BASH
02fd2628810c1b00de730ece32b09dba1318be4c99a4ff1a0551740e32bf223b  pig-1.8.0-1.aarch64.rpm
72ba72a00af52a84b08b1346f85b42668b52bc097e315774ff9f501ca23ece8b  pig-1.8.0-1.x86_64.rpm
f023a5c9049dc532a057e932c73a8197683eaf4d97cb7a8f219492da1ad2a65f  pig-v1.8.0.darwin-amd64.tar.gz
e0ccf61c4d135dbc45359c207751092aeb6df788e826bb73eccc1a1ed8800998  pig-v1.8.0.darwin-arm64.tar.gz
a24a08c1b8d54adcdef5a99ed7b91caeedef1552a1440b1258eb4eb07fb20353  pig-v1.8.0.linux-amd64.tar.gz
9d23875804f87e78039498245059fd6b765831f027aacfc511ad0ac42711fa7b  pig-v1.8.0.linux-arm64.tar.gz
96259ff7584cd52254c91a9fd7d77bd577f23c55cb09f4bc995a3ca0fcbc7321  pig_1.8.0-1_amd64.deb
2e7370211514df6355ef96fb812670febe6ee1b85a28378432c33ebdaecb4b63  pig_1.8.0-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.8.0

v1.7.0

Pig v1.7.0 是 v1.6.2 之上的仓库兼容性与目录更新版本：明确中国镜像选择语义，默认保留 DNF 原生模块过滤，恢复精简的 EL7 仓库目录，并将内置扩展快照从 572 个增加到 575 个。内置 Pigsty 版本仍为 4.5.0。

主要变化

  • -m|--mirror 现在直接选择内置的 china 仓库定义。PGDG、Rocky Linux、Debian、Ubuntu、Docker 等区域路由使用维护中的镜像列表，不再进行旧版运行时 PGDG 代理改写。
  • EL 仓库不再全局注入 module_hotfixes=1。确实需要覆盖模块流的 Pigsty 与 PGDG 仓库会显式启用；BaseOS、AppStream、EPEL 等普通仓库继续使用 DNF 原生模块过滤。
  • EL7 保留有意精简的兼容目录：面向 x86_64 的 CentOS 7 Base/Updates/Extras/SCLo 与 EPEL 归档源，以及共享的 Pigsty 和仍受支持的 PGDG 条目。渲染 EL7 YUM 配置时会移除仅适用于 DNF 的 module_hotfixes。
  • 当目录中没有匹配当前平台的仓库定义时，仓库设置会明确报告平台不受支持，而不是继续处理空仓库集合。

扩展目录

  • 已打包扩展数量从 572 增加到 575，没有移除项。
  • 新增 pg_local_cache 1.2.0、pg_statviz 0.1.0、pg_policy 0.1.0。
  • 更新 biscuit 3.0.0、pg_clickhouse 0.10.0、pg_search 0.25.2、pg_turbovec 软件包 1.29.0、pg_uuid_v8 1.1.0，以及 Debian q3c 2.0.5 软件包。

兼容性提醒

  • 本版本没有移除命令或全局参数。
  • -m|--mirror 现在明确选择中国区域，不再进行 PGDG 代理改写；需要固定路由时请使用 --region=default|china|europe。
  • 自定义 EL 仓库如果确实需要覆盖模块流，必须显式设置 meta.module_hotfixes: 1；普通操作系统仓库会有意省略该设置，EL7 上则会移除它。
  • EL7 已停止维护，仅提供有限兼容性；当前 PostgreSQL 与扩展软件包应优先使用 EL8 或更高版本。

校验和

制品：GitHub Release · checksums.txt

BASH
e3a339fefdd2203825d15438b52f18e729547eb88dae014212a46006a9bd47d1  pig-1.7.0-1.aarch64.rpm
34ce29d75ef9f669f3bf832cc812ae082abda7320ee2b2336ea61e701b9b67f8  pig-1.7.0-1.x86_64.rpm
d26803c685ba29c01cb8e6dfe50c6c1b0f004173be82015618fa8cdf6a329ba7  pig-v1.7.0.darwin-amd64.tar.gz
ea8120d48b93da936919f590ebbefeb72e73277e6bc133c1ef0bb1abc055d3ce  pig-v1.7.0.darwin-arm64.tar.gz
40295b64a2423094fa6f4e6d31da8d8ad5b26698c397d8916c0289591522d0bf  pig-v1.7.0.linux-amd64.tar.gz
7929091732957d85751ef3381285a1e5b0c3c7f82c0e00fc24ed085c496012d5  pig-v1.7.0.linux-arm64.tar.gz
41523c15f36a6c1acaf4af5c851d2626472fc15c21d25f91fc1e991fe8411072  pig_1.7.0-1_amd64.deb
adf7b2d9ce8fe42bad935428d16a9c998337df986b1065e0761dc167ce837ef5  pig_1.7.0-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.7.0

v1.6.2

Pig v1.6.2 是 v1.6.1 之上的功能与目录更新版本：已打包扩展从 562 个增加到 572 个，新增 Grafana 仪表盘 schema v2 原生支持，并改进本地软件仓库生成流程。内置 Pigsty 版本继续锁定为 4.5.0。

主要变化

  • pig sty grafana 现在同时支持传统仪表盘 JSON 与原生 dashboard.grafana.app/v2 Dashboard 资源。载入 v2 仪表盘时使用 Grafana resource API，确保标签页与 section 变量可以完整往返；导出到现有 v2 文件时保持 v2 格式，新文件默认仍使用传统格式。
  • pig repo create 在 SOW 可用时优先执行 sow create --pigsty --timeout 10m -- <dir>，要求生成的 repo_complete 完成标记存在且为普通文件；Linux 上仍可回退到 createrepo_c / dpkg-scanpackages。
  • macOS 现在可通过 SOW 创建本地软件仓库，默认使用当前目录且无需 sudo；Linux 默认目录仍为 /www/pigsty。
  • 发布元数据升级到 1.6.2，内置 Pigsty 版本保持 4.5.0。

扩展目录

  • 已打包扩展数量从 562 增加到 572，没有移除项。
  • 新增 10 个扩展：pg_turbovec、pg_disorder、pg_mentat、plruby、jsonb_plruby、hstore_plruby、ltree_plruby、pg_describe、cat_tools、pg_vault_tde。
  • 更新 12 个扩展版本：timescaledb 2.29.1、q3c 2.0.5、pgmnemo 0.16.1、pg_search 0.25.1、citus 14.2.0、citus_columnar 14.2.0、provsql 1.12.0、plpgsql_check 2.10.4、pg_rational 0.0.3、pgbson 2.1.0、pg_readme 0.7.1、pg_readme_test_extension 0.7.1。
  • 刷新软件包元数据与可用性矩阵；运行 pig ext reload 可以用最新在线目录替换内置的发布快照。

兼容性提醒

  • 本版本没有移除命令或全局参数。
  • 安装 SOW 后，pig repo create 会优先使用 SOW 而非传统 Linux 生成器，并在报告成功前检查完成标记是否存在。
  • 目录总数不代表每个包都适用于所有 PostgreSQL / 操作系统 / 架构组合；请在目标主机上使用 pig ext avail NAME 查看实际可用矩阵。

校验和

制品：GitHub Release · checksums.txt

BASH
6697a96bbf476e697a5c3da8b6c861719e4b7208e1e4fe927cf4b475ea1f162f  pig-1.6.2-1.aarch64.rpm
ad0b311867bc6cd689dd73e9a96b84f1fe0f49f6c0f1184abf9eb3232a07a184  pig-1.6.2-1.x86_64.rpm
bb167e04fceb6cebee5c8a2423279cefb4474f46301a5055c464ac98294dc9db  pig-v1.6.2.darwin-amd64.tar.gz
3de74e33321884a0c36596c1e7df9370be594a315395538e9ba5b775bbc1a79d  pig-v1.6.2.darwin-arm64.tar.gz
7b69214e115e6815e772b7e179aa4070bd8553e585b164ba3a0f69a1d53a0294  pig-v1.6.2.linux-amd64.tar.gz
b511e727642987867be5921d72e8019e9c6186b82e63ddc34ad653773abed5a8  pig-v1.6.2.linux-arm64.tar.gz
3d1a80b833c6179b84ac5cc590ad06695b187b2bb4a09f544b1a14f9684dc4bc  pig_1.6.2-1_amd64.deb
00e4c84cd6b07a98401c73fb58dedaafe34bc794d7604edbcb76c5de39b0fb44  pig_1.6.2-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.6.2

v1.6.1

Pig v1.6.1 是一次维护版本，刷新了内置扩展目录，并将内置 Pigsty 版本对齐到 4.5.0；没有新增命令或参数变更。

主要变化

  • 依据 Pigsty 软件仓库重新生成内置 extension.csv，全新安装无需先运行 pig ext reload，即可使用当前软件包元数据。
  • pig sty 与 pig status 报告的内置 Pigsty 版本从 4.4.0 更新到 4.5.0。
  • 保持 562 个已打包扩展，覆盖 PostgreSQL 14-18、EL 8/9/10、Debian 12/13、Ubuntu 22/24/26，以及 x86_64 / aarch64 双架构。

校验和

制品：Pigsty 镜像 · checksums.txt

BASH
088e62bf7c64dbbe1d66cb54e6a6971e4d245e76ac0b9ab9de2280053b692e77  pig-1.6.1-1.aarch64.rpm
11b81f43754bcd7691752025ff0a95aa39745883d1cc17183e81fd357f50f5d3  pig-1.6.1-1.x86_64.rpm
f0512d26fd934a9ac7b0bf5aba22aba151991a4edcc8e995441f79f66fc6080a  pig-v1.6.1.darwin-amd64.tar.gz
595f122c210b1e5a5211de5b397bfcf2a803179f52a97aa38e68e8c567381533  pig-v1.6.1.darwin-arm64.tar.gz
d6c0ad7784c8df33539d60cb22259bb1b6f92a6fc26543f4384448dd630a83fd  pig-v1.6.1.linux-amd64.tar.gz
017fbae1c32858b5438514685e45959ceaeb6bf29ae11ecf0496b52d00908627  pig-v1.6.1.linux-arm64.tar.gz
571bc16bc8490190935ecb6d8dde9c5827e63eced0b7bbd05cfad1e4363e385b  pig_1.6.1-1_amd64.deb
54010b414aaf3971c435db714d5e1c0e039f30a11adf95a902040e177f911fa6  pig_1.6.1-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.6.1

v1.6.0

Pig v1.6.0 是一个大版本：pig pt 重写为 patronictl 原生透传，新增根级 pig inventory 命令组提供 pigsty.yml 的无损编辑与校验（附带实验性的 PostgreSQL CMDB 交换能力），pig sty grafana 提供原生 Grafana 仪表盘管理，已打包扩展目录增至 562 个。

主要变化

  • pig pt 重写为 patronictl 原生透传：所有集群命令（list、restart、switchover、failover、edit-config 等）直接转发，使用原生参数、交互确认、输出与退出码，patronictl 的新功能无需等待 pig 发版即可使用。本地保留 status、log、set、service/svc 辅助命令，新增 -c/--config-file、-d/--dcs-url、-k/--insecure 选项与 pig pt -- … 逃逸写法。
  • 新增根级 pig inventory 命令组（别名 inv）：status / list / show / edit / validate / check / diff —— 无损 YAML 引擎逐字节保留注释、格式、键序与锚点；edit 先校验再原子写入，非法 YAML 不可能落盘。
  • 新增 实验性 pig inventory cmdb 子命令（check / init / load / dump / enable / disable），通过原生驱动与 Pigsty 的 PostgreSQL CMDB 交换配置清单，破坏性操作带超时限界与摘要锁定的确认门。
  • 新增 pig sty grafana（别名 gf）通过 HTTP 原生管理 Grafana 仪表盘：info / list / boot / load / init / dump / clean / lang / style。pig sty 命令面简化：移除 sty edit / validate / check / cmdb / dashboard / release，改用 pig inventory、pig sty grafana 与 pig sty list / get。
  • 可靠性强化：仓库 / 目录 / 下载写入全部原子化（中断不再留下半截文件）；结构化输出 -o json|yaml 下 stdout 只包含结果信封，被包裹命令的输出走 stderr；退出码更精确（用法错误 → 2，缺少 --yes 确认 → 7）；Ansible 列表变量改用 JSON 编码防注入。
  • 仓库刷新：MySQL 仓库升级到 8.4 LTS，新增 Percona XtraBackup（pxb84）与 MySQL Tools 仓库，Kubernetes 升级到 v1.36，LLVM apt 覆盖 Debian/Ubuntu 26，Percona TDE 改用 repo.percona.com 官方源，移除 wiltondb 仓库。
  • 工具链：Go 1.26.5，新增原生 PostgreSQL 驱动（pgx v5），内置 Pigsty 版本 4.4.0。

扩展目录

  • 已打包扩展数量从 531 增加到 562；PGEXT.CLOUD 总目录收录 2230 个扩展。
  • 新增 33 个扩展，包括 pg_lake 家族（pg_lake、pg_lake_table、pg_lake_engine、pg_lake_iceberg、pg_lake_copy）、pg_jieba、pg_cjk_parser、pg_fts、pgmonitor、pgmemento、pg_tiktoken_c、online_advisor、pgsqlmock、plx 等。
  • 移除 2 个：pg_analytics、spat；刷新 58 个扩展版本，包括 vector 0.8.5、timescaledb 2.28.3、pg_search 0.24.3、pg_tde 2.2.1、powa 5.2.0。
  • 包别名与 Pigsty 同步：kafka 更名为 kafka-stack；Debian/Ubuntu 的 postgresql 别名收窄为仅 postgresql-$v（完整开发套件请用 pgsql / pgsql-full）。

兼容性提醒

  • ⚠ pig pt failover <name>：位置参数现在是 集群名 而不是晋升候选成员 —— 请改用 pig pt failover CLUSTER --candidate MEMBER，升级前务必检查 failover 自动化脚本。
  • pig pt 位置参数改为原生的集群优先形式（restart CLUSTER [MEMBER]）；转发命令返回 patronictl 原生退出码、由 patronictl 自行交互确认（-y 不再门禁这些命令），且不再支持 -o json（请改用原生 --format json）。pig pt config 由 pig pt set K=V 与原生 show-config / edit-config 取代。
  • 结构化输出模式下，被包裹工具的输出移至 stderr，stdout 只有 JSON/YAML 信封 —— 请更新解析混合输出的脚本。
  • pig inventory edit 编辑成功后会将配置文件权限收紧为 0600（文件可能包含数据库凭据）。

校验和

BASH
6899e8a3e1c0adfe8c0c177c0632b0a00821b304ed5998fcbdf28d02660c6768  pig-1.6.0-1.aarch64.rpm
cabe593fe7f5c31cdbcd8d546ae4925b57f98f70c564452335568389f3f9737c  pig-1.6.0-1.x86_64.rpm
1f46d4a0b4710eed06b2cf8e7e17ee04b8d65331697c5c65afd513cc28282231  pig-v1.6.0.darwin-amd64.tar.gz
845decb95697fc68bc5e12bc80cecfd4c6d23160afee96568b699d82f2e9261d  pig-v1.6.0.darwin-arm64.tar.gz
4f1bb4fda8131db9f40db15e1575a6045b373dee609250cf5ee2bdedc2db89e2  pig-v1.6.0.linux-amd64.tar.gz
4384d11150e31d614ed4ac3de4d6bf7ee7fa111ac84f5575753bb9f2f31f4ed8  pig-v1.6.0.linux-arm64.tar.gz
e35ef0f2c76afe5f3512d34c0440abd8c0106c0e2775c5452e167ae3a4127e8e  pig_1.6.0-1_amd64.deb
c3bc6d04c6acd7e5c3164a33b7525b25a93e2de9822ce957c15c18ee0d551901  pig_1.6.0-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.6.0

v1.5.1

Pig v1.5.1 是一次构建与仓库维护版本，更新了多款 PG 内核分支包。

主要变化

  • 镜像/代理模式覆盖 repo、build、sty、update、ext update 等流程；pig build rust -m 会写入 Cargo 镜像配置并使用 rsproxy.cn。
  • 新增 PostgreSQL 19 beta 的 repo、tool、pgrx 显式构建开关：pig build repo --beta、pig build tool --beta、pig build pgrx -b；稳定默认值仍保持 PostgreSQL 18 与 PG14-18 窗口。
  • 刷新 IvorySQL、PolarDB、OrioleDB、OpenHaloDB、Babelfish、pgEdge 套件等内核与 fork 包别名。
  • 改进 Cloudberry 套件构建流程，覆盖 cloudberry、cloudberry-backup、cloudberry-pxf。
  • 刷新 Cloudberry、Babelfish、OrioleDB、pgEdge、PolarDB、polarstore、zlog、libpgfeutils、libfq 等源码与包元数据。
  • 改进较新 EL release 字符串处理，包括 EL9.6+ / EL10+ 上的 PGDG 仓库，以及 EPEL 在 EL10 上使用的 10z stream。
  • 刷新扩展版本，包括 pg_ivm 1.15、spock 5.0.10、snowflake 2.5.0、pg_tde 2.2、decoderbufs 3.6.0、IvorySQL 5.4 包。

校验和

BASH
bc83887d640ed299a967b4eda2ae6db621a985abfa022fccabf508f7ec7b98e3  pig-1.5.1-1.aarch64.rpm
f0eab8e638d9e00a9172751446db869d0fe6ca7f382c7d540a931e0764014c0a  pig-1.5.1-1.x86_64.rpm
b32d894dc444ef2b9ec00816d50d82b5834e64c35b3bb18f08b6286a7ca8e8e7  pig-v1.5.1.darwin-amd64.tar.gz
4d768829b7e93fac6c732e27f665d3ab3945ec8bc1c336e5b91980932e8c9932  pig-v1.5.1.darwin-arm64.tar.gz
69f4a016af52f1ee8f1a1ffc1e405bb3be551c3813b6d24f70ef8394330be5eb  pig-v1.5.1.linux-amd64.tar.gz
f49becb5fd556b36a9aa8de0c27bdbe210f7958f59254d780774828f2340e77b  pig-v1.5.1.linux-arm64.tar.gz
a0d15145409d8a2629a74d3071f7af593e470920f22d9af4bf6f96725dbb6d49  pig_1.5.1-1_amd64.deb
f05b9b5abef5992ed16cbb5b6a6e3e5e58230072e3665ecc57b9ce2df3edb9a6  pig_1.5.1-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.5.1

v1.5.0

Pig v1.5.0 是一次面向 PostgreSQL 日常运维的版本：新增本地数据库 clone / fork 工作流，明确 pg、pt、pb、pitr 的职责边界，并收紧高风险操作的预览、确认与结构化输出行为。

主要变化

  • pig pg 更聚焦本地 PostgreSQL 操作。新增 pig pg clone 用于快速创建数据库级副本，新增 pig pg fork 用于创建一次性物理实例分叉，适合本地验证、恢复演练和隔离实验。
  • 恢复流程拆得更清楚：pig pitr 作为 Patroni / PostgreSQL / pgBackRest 的恢复编排入口；pig pb restore 保持为低层 pgBackRest restore 原语。恢复命令现在必须指定明确目标，并提供更具体的 plan 与恢复后指引。
  • Patroni 操作更可预期：pig pt restart、reinit、switchover、failover 等高风险操作统一由 Pig 负责确认与 plan 输出；pig pt config pg 会提示是否需要 pig pt restart --pending。
  • 自动化脚本更安全：结构化输出不再隐式确认破坏性操作，执行高风险动作需要显式 -y/--yes；--plan 与 next_actions 更一致，方便先预览、再执行。
  • 日志与状态输出更适合排障：pg、pb、pt 的日志命令补齐 latest / tail / show / grep 等常用入口，结构化日志快照使用 JSONL 语义。
  • 构建与发布默认值更新：Pig 版本为 1.5.0，内置 Pigsty 版本为 4.4.0，pig build pgrx 默认 cargo-pgrx 升级到 0.19.1。

扩展目录

  • 可用扩展数量从 524 增加到 531，没有移除项。
  • 新增扩展：pg_ducklake、pgdisablelogerror、pg_stat_log、pg_stat_plans、passwordpolicy、db2fce、plpgsql_wrap。
  • 刷新一批已有扩展版本与包元数据，代表性更新包括 timescaledb 2.28.2、postgis 3.6.4、vector 0.8.4、biscuit 2.4.1、citus 14.1.0、orioledb 1.8、documentdb 0.113、credcheck 5.0、pgtt 4.5。
  • orioledb alias 不再固定到 PG17，而是按请求的 PostgreSQL 主版本解析；EL9 ARM64 Patroni alias 也调整为 noarch 包。

兼容性提醒

  • 自动化执行破坏性操作时请使用 -y/--yes；结构化输出模式不会再替代人工确认。
  • pig pb restore / pig pitr 需要明确指定一个恢复目标；自动 promote 类行为请使用 --target-action=promote。
  • 若干易混淆短参数经过整理；日志命令的 -o json 表示 JSONL 快照，不用于 tail / follow 这类流式交互场景。

校验和

BASH
9f83b78ed2eccedd55a86c634f88364f1945c3cefa1b23efdd72a7cf2062e1df  pig-1.5.0-1.aarch64.rpm
b792001498e9907d4659db46640f9c5164152b20689f90f93418f76fb4633e6e  pig-1.5.0-1.x86_64.rpm
ae1081dfbff8564ecdf713c85e8025c91bfd38e6575ea9ac99a92f968ab8a29d  pig-v1.5.0.darwin-amd64.tar.gz
6d69efcdcdc79fd90d2112e1e8042887020402aa037252d89d632243e7085dc6  pig-v1.5.0.darwin-arm64.tar.gz
8f914821b317cde73d3aec4ed311d5e90710bbc8cb372c1de3322083c31f4a85  pig-v1.5.0.linux-amd64.tar.gz
d4de9ef1c28d0a3661c4a4d47c469b7bfd5f5bddb610325796afb669ab162234  pig-v1.5.0.linux-arm64.tar.gz
35fd32affb4cb5bcca845d47a768782fb7005f06fcc1bcb5b7755d2627f96245  pig_1.5.0-1_amd64.deb
2be1df804d3f630560bc3ced0107c49ffad8bb52b004f72c7f8b4d09dc8d3e04  pig_1.5.0-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.5.0

v1.4.2

  • 内置扩展目录从 510 个可用扩展刷新到 524 个，新增 14 个扩展：pg_stl、pgmnemo、psql_bm25s、pg_orca、pg_sorted_heap、graph、pgrdf、fsm_core、jsonschema、pg_durable、pg_mockable、pg_uuid_v8、pg_stat_backtrace、pg_projection。
  • 更新 48 个已有扩展的软件包元数据，包括 timescaledb 2.28.0、timescaledb_toolkit 1.23.0、pg_task 2.1.29、pg_search 0.24.0、pg_clickhouse 0.3.2、pg_graphql 1.6.1、documentdb 0.112、toastinfo 1.7、wrappers 0.6.1、pgclone 4.3.2 等；没有扩展被移除或降级。
  • 新增 PostgreSQL 19 beta 的安装、构建、配置支持。PG19 可以作为显式指定的安装版本使用，但自动探测、目录展示与 latest alias 的稳定默认版本仍保持为 PostgreSQL 18。
  • 新增 pg19 软件包别名与 PG19 分类别名解析。PG19 分类别名借用 PostgreSQL 18 的可见性模板，并且 beta 软件包展开只包含 PGDG 来源条目。
  • pig sty conf -v 19 会在模板支持时自动启用 beta 仓库模块；当模板没有针对 PG19 beta 调优，或无法自动启用 beta 仓库时，会给出明确警告。
  • 修复 Patroni 集群操作：patronictl restart、reinit、switchover、failover 现在会传入解析出的 CLUSTER_NAME；pig pt list 也支持可选集群名参数。
  • pig build pgrx 的默认 pgrx 版本从 0.18.0 升级到 0.18.1。
  • 发布元数据更新到 v1.4.2，刷新 Go module checksum，并补充 PG19 alias / 配置生成与 Patroni cluster-scope 行为的针对性测试。

校验和

BASH
790afe4d6622cb041b06c622bc466cb1b2960a77487f368238027fb4a3a5ef93  pig-1.4.2-1.aarch64.rpm
ef918166b38a5eb1d108a928718c9e2cb8c3590e5a1f72effee942faca9b4bea  pig-1.4.2-1.x86_64.rpm
3e37ff22aed076cbdd453911dc89fcc9340b1a4faac62c0580094bc1eb2d6273  pig-v1.4.2.darwin-amd64.tar.gz
5eb7db776cb149331ebb33e3e6164e1cf711d0107941b92c6930a1d4c4b4eb23  pig-v1.4.2.darwin-arm64.tar.gz
c536c324e40a861217e31f4699ee5f0e6c2daeb4e6f0f0e8cc5f606da9d787eb  pig-v1.4.2.linux-amd64.tar.gz
8b2d5746264a95269535e5a426f78fe0020f73fa3391fcb613f274551c4786ab  pig-v1.4.2.linux-arm64.tar.gz
566e06f6da1fe9d635c41258d20cd9ff10de4e6e74b3b41ba2c6204ba22743c8  pig_1.4.2-1_amd64.deb
8c09e741975cb2f74b0f88c5995a8fa43d6c30a9a7ab7aaf0b8d83a7c66e1fc1  pig_1.4.2-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.4.2

v1.4.1

  • 扩展目录更新到 510 个扩展，新增 3 个扩展，更新 17 个扩展。
  • 新增 Ubuntu 26.04 resolute 支持，移除 Ubuntu 20.04 focal 支持。
  • 将 el9.aarch64 特例中的 patroni / patroni-etcd 提升到 4.1.2。
  • 校准上游软件仓库定义。

校验和

BASH
2b96e06d26e7425b13ac1f27d620b24b258f232bfc1d84c0b3aa2ee6505ea8aa  pig-1.4.1-1.aarch64.rpm
30a68d2fb97bb1d146ec57bcec2f279ce7fa4cf075fdcc9afc3d143f9a365896  pig-1.4.1-1.x86_64.rpm
ff4ac1a15f6a1e0aa935922a4e402a428fd3579c0143a5e411e835089a55cc2c  pig-v1.4.1.darwin-amd64.tar.gz
a23048d854bc2bef74a2b5cf42bd2f4aae79f3c9df3181a829ddf2167d939dc2  pig-v1.4.1.darwin-arm64.tar.gz
74feec28ee879853633d8e9f3722c95aa25c47a3d3f6fb5bde3f3609b5c09378  pig-v1.4.1.linux-amd64.tar.gz
d50d1ce2b0d682a4ced72a4a11e6bddbd90f9dccbd16eae886045845eec83104  pig-v1.4.1.linux-arm64.tar.gz
3fe640c3b6678fe4cef527a58dca54285f15d56c8fe0b3c2ed8b6879e1e91d41  pig_1.4.1-1_amd64.deb
d09fd6e747cb65acda225ffd5448a8fba3f676ce8044f4237d75a59b3d6a5b4e  pig_1.4.1-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.4.1

v1.4.0

  • 刷新扩展目录，可用扩展总数增加到 510，并更新 timescaledb 2.26.3、decoderbufs 3.5.0、pgclone 4.0.0、nominatim_fdw 1.3 等版本。
  • 默认 pgrx 从 0.17.0 升级到 0.18.0，同步对齐相关 Rust 扩展构建版本。
  • 为 pig build get 刷新权威源码包映射，覆盖 Cloudberry / OrioleDB 构建输入，以及 RDKit / OneSparse 相关附加源码。
  • 修复 repo set 标志位隔离问题，并修正 PostgreSQL schema 级维护 SQL。
  • el9.aarch64 上的 patroni 升级到 4.1.1。

校验和

BASH
c8d2f46ea1b25f7d4665ee0994f0cb403a59f1464f80b3ecfa575ac283e5ecd0  pig-1.4.0-1.aarch64.rpm
fb1fd2f4f1e71894779de7b11a42960c09261620dffa0b54ff7f84e60efbf976  pig-1.4.0-1.x86_64.rpm
aa08045a31c26b9a6bfb770753817581c819022a6ed899e44f7b5a31f57f1733  pig-v1.4.0.darwin-amd64.tar.gz
80e50dd2ccd08d4a4016e85518186e156498e00c56a898e65acb96466db339f0  pig-v1.4.0.darwin-arm64.tar.gz
e425bf35ab6cb7907e94caca802b4418e3baf4bb1642dd957ab4baaa9db9f583  pig-v1.4.0.linux-amd64.tar.gz
840a21695955d64af7df12f7157b49573b18586bb2bf9cc5e7079074b86d39b7  pig-v1.4.0.linux-arm64.tar.gz
401d91bae78b14e3dcc338aaac9e451e94282c79efbe9affabcfeb8b36ece587  pig_1.4.0-1_amd64.deb
d60515f72fb9f8963554dc5668d2398e5ecefd0153a7756a9d555de90115bcce  pig_1.4.0-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.4.0

v1.3.4

扩展数量更新至 504 个。

校验和

BASH
dc78def9a1e5eb483ac5df4c87f4ac0ef2018bb12b4bedff650d8ba4d58a05fd  pig-1.3.4-1.aarch64.rpm
998fcbdab1846c94c3155391d2100dad9b0fe338f48212022db38980bb11e696  pig-1.3.4-1.x86_64.rpm
031048c561abbeeeaa73fa3ac919b9fb89479b61c8a759bee5db2efba2e8a1df  pig-v1.3.4.darwin-amd64.tar.gz
e13c939330d32fa91819ce2da88d121fb02a1063240dbf6cc8fa7975960f8fd3  pig-v1.3.4.darwin-arm64.tar.gz
46aa321cf45fc9be635d91b38969b7f3602b7f226f43e5ee0e7614a030945c64  pig-v1.3.4.linux-amd64.tar.gz
f25c4f336edba5c9d2145368082f54e5b1a8b2d4261285b7a1721c088df4caa4  pig-v1.3.4.linux-arm64.tar.gz
563516047e37b25da01da9e25bcbada2c55642d1636b1bdab7d62488f9dcdfbb  pig_1.3.4-1_amd64.deb
81bb482892f7fd4be862d0f377cb37d01c925006c96998d81d94c770ed9652ba  pig_1.3.4-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.3.4

v1.3.3

  • 扩展目录刷新，可用扩展总数增加到 481 个。
  • Go 工具链从 1.26.0 升级到 1.26.2。

扩展更新

扩展名旧版本新版本备注
timescaledb2.25.22.26.2正常，PG15-18
pg_background1.81.9.2仅 DEB，PG14-18
pg_ivm1.131.14升级，PG14-18
system_stats3.24.0升级，PG14-18
nominatim_fdw1.1.01.2升级，PG14-18
pg_textsearch0.5.01.0.0PG17-18
pg_clickhouse0.1.50.1.10正常，PG14-18
pg_search0.22.20.22.6手工下载，PG15-18
pg_store_plans1.91.10升级，PG14-18
pg_dispatch0.1.5新增，PG14-18
pg_fsql1.1.0新增，PG14-18
pg_liquid0.1.7新增，PG14-18
pg_regresql2.0.0新增，PG14-18
pg_slug_gen1.0.0新增，PG15-18
pg_stat_ch0.3.3新增，PG16-18
pg_variables1.2.5新增，PG14-18
pgcalendar1.1.0新增，PG14-18
pgclone2.2.0新增，PG14-18
pgelog1.0.2新增，PG14-18
pglock1.0.0新增，PG14-18
pgproto0.2.1新增，PG14-18
postgresbson2.0.2新增，PG14-18
rdf_fdw2.4.0新增，PG14-18
parray_gin1.4.0新增，PG14-18

校验和

BASH
e74418061ea975fbc3e8a89b31f274d7dc3617d12b9d681e5c8ef03584392088  pig-1.3.3-1.aarch64.rpm
8450e3e1076425fc8a10f24cc5fd833c3d2d880bab12baff5c10e59a31f62231  pig-1.3.3-1.x86_64.rpm
952a0e94b9020fca5add91f8e9a398fbedfda5d2e5c8736e59ddaa2b7152c826  pig-v1.3.3.darwin-amd64.tar.gz
c896b4fd44b19a250f4c3c47dc78643e10e92fde8cb6531b08cdc78e3623bb8a  pig-v1.3.3.darwin-arm64.tar.gz
d18a92f9aa05d6315c5e9bfde3245afc08fca93d200a8063aa20cb40feb8e85e  pig-v1.3.3.linux-amd64.tar.gz
62d020072360229b47f6c430b014344b912f2d9b58fd528154ae9c4ee805190a  pig-v1.3.3.linux-arm64.tar.gz
7a613a1f1c323ee78276b1733df026b8b0f415e0057b4cb8e509f771bfd3d614  pig_1.3.3-1_amd64.deb
f4c91ce86b787b6ab8cd584949d38c2ca87eb82d5e066bab91b80345252f43d8  pig_1.3.3-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.3.3

v1.3.2

例行维护版本。

  • 例行刷新部分扩展版本元数据与扩展目录条目，扩展版本更新。
  • 新增 pig pg tune 子命令，可根据硬件资源与工作负载画像生成 PostgreSQL 调优参数建议。
  • 为 pig build get 新增 pdu 与 pgdog 两个源码包 alias。
  • 调整 pgext.cloud 的 URL 至新版本的扩展目录 pigsty.io/ext

校验和

BASH
d760f47652ff3e2e4a61eb7b9a68ca68665b2b36c187c52f5eaf50d2f007d8f3  pig-1.3.2-1.aarch64.rpm
c2e02e62497f4c2055a9b448ddb3a24c618fcd488580c28b2b9a0e7cedacef55  pig-1.3.2-1.x86_64.rpm
b8d066ddefa4530946c74c30e7e4acdab6abf8da70a47dcfe2a77719b79e397f  pig-v1.3.2.darwin-amd64.tar.gz
a90e78d879fd720fd2865870c696aed7952558d5ae75591deced3121f2aab1f9  pig-v1.3.2.darwin-arm64.tar.gz
2fe3a9ffbb6383154dfd25ed79420b210828eabf6a96a8af6e8feb9d744b9559  pig-v1.3.2.linux-amd64.tar.gz
522290aaf14f98f0bae83ce75cc76749f2a4e72742eb5c3cba36a1d2fa4d12c2  pig-v1.3.2.linux-arm64.tar.gz
d6c1cf2c52962045f6bbfb2a669058e7f903088526591d6c939e7723f3928d30  pig_1.3.2-1_amd64.deb
4352385c629b26a1837054445a546da89591499848b557699c2fb70fde9377aa  pig_1.3.2-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.3.2

v1.3.1

这是从 v1.3.0 到 v1.3.1 的一次小型维护版本。

  • 由于 PGDG 上游已移除 PG13 归档与分发，pig 同步移除 PG13 安装/构建支持。
  • 活跃支持的 PostgreSQL 主版本现在为 14-18。
  • 扩展目录刷新（461 -> 464），新增 pg_pinyin、pg_eviltransform、qos。
  • Percona PPG 上游仓库更新到 18.3。
  • 修复 pig build 依赖/构建同步问题，rsync 增加 --keep-dirlinks 参数。
  • YUM 仓库中 Nginx 从 infra 模块拆分为独立模块索引（nginx）。

校验和

BASH
196e57c7dd46cdedd90ab75965a766f74aabc3bc23ddc8fb757473647bed7b8f  pig-1.3.1-1.aarch64.rpm
e4bdd52ef635524d5aec95f6a5abd76bd49940584ecbb00bd309a4f9186292ac  pig-1.3.1-1.x86_64.rpm
4f3f9479344c158e1c5edc3003471be6b595c01b7d86104bf676b34f8faadce5  pig-v1.3.1.darwin-amd64.tar.gz
05ae2f550ef5062ab5714518a24bbf52f48079ca6d0190359fae5b8f4cb7f20d  pig-v1.3.1.darwin-arm64.tar.gz
940645497e907e56bfd387a478e580ac930aaa72593cc9d04225a08b37880ec4  pig-v1.3.1.linux-amd64.tar.gz
8b2c204fd6c933a1097cd1cd0ce491b02ba5c0025626a331a199684ceca3ab43  pig-v1.3.1.linux-arm64.tar.gz
1cfc23d147795cc4c1ea9596e6978d79ff1ec34c02850fbb224f7c2844548ea5  pig_1.3.1-1_amd64.deb
e495678ae1c762194a56e8c9969fd2109e7a59830f34a4747039fb978f7820cc  pig_1.3.1-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.3.1

v1.3.0

这是从 v1.2.0 到 v1.3.0 的一次工程强化与目录扩展版本：15 commits、74 files changed、代码行 +1184 / -236。

该版本重点围绕 pig build 构建链路和 ext 目录/别名能力增强，并将可用扩展数量从 451 增加到 461。

主要变化

  • 构建源码下载增强（pig build get）：
    • 支持从扩展 Source 字段解析多源码（空格/换行/Tab 分隔）并去重。
    • 新增 agensgraph / agentsgraph 源码映射。
    • pgedge 构建源码改为同时下载 postgresql-17.9.tar.gz 与 spock-5.0.5.tar.gz。
  • 依赖解析与安装优化（pig build dep）：
    • RPM 依赖安装可从 spec 的 pgmajorversion 宏推断 PG 主版本，spec 缺失改为显式报错。
    • DEB 依赖解析支持 Build-Depends / Build-Depends-Arch / Build-Depends-Indep 的多行、候选依赖、架构限定与 profile 清理。
    • 支持 PGVERSION 占位符自动展开（优先 --pg，其次已安装版本与扩展元数据）。
    • 依赖安装失败降级为 warning，批量流程继续执行。
  • DEB 构建结果判定修正（pig build ext/pkg）：
    • 构建命令退出码成功即判定成功，产物发现改为 best-effort 警告，避免误判失败。
    • 成功但无产物时不再显示空包列表横幅；部分产物场景标记 warning 而非 fail。
    • 构建日志中的源码与版本显示改为读取扩展元数据真实值，避免错误拼接 name-version。
  • 扩展操作输出语义改进（pig ext rm/update）：
    • 别名解析后，removed/updated 返回值改为“实际包名”，方便自动化脚本精确比对。
  • 扩展目录与别名更新：
    • 新增别名：agensgraph / agens、pgedge、babelfishpg。
    • openhalodb 对齐 PG14 包命名，ivorysqldb 命名对齐。
    • fork 元数据与可用性矩阵批量刷新（含 timescaledb、pgmq、orioledb、documentdb、pg_tde、babelfishpg_* 等条目）。
  • 工程与发布：
    • 版本号提升到 v1.3.0（包含 v1.2.1 过渡提交），版权年份更新到 2026，README 同步更新到 461 扩展与最新 alias 说明。

兼容性提醒

  • pig ext rm/update 结构化输出中的 removed/updated 字段由扩展名切换为包名；如果你的自动化逻辑按扩展别名匹配，请同步调整。

新增扩展（451 -> 461）

扩展名版本说明
aux_mysql1.5openHalo MySQL 兼容辅助模块（PG14）
gb18030_20221.0IvorySQL 编码转换模块
ivorysql_ora1.0IvorySQL Oracle 兼容扩展
ora_btree_gin1.0Oracle 类型 GIN 索引支持
ora_btree_gist1.0Oracle 类型 GiST 索引支持
pg_get_functiondef1.0获取函数定义
plisql1.0PL/iSQL 过程语言
snowflake2.4pgEdge Snowflake ID 生成扩展
spock5.0.5pgEdge 多主逻辑复制扩展
lolor1.2.2pgEdge 大对象逻辑复制兼容扩展

完整提交列表（v1.2.0..v1.3.0）

  • b8ecf8d 版本字符串更新到 1.2.1
  • 55df9a4 build/get 支持多源码解析与 pgedge spock 源码
  • da8e347 新增 agensgraph 和 pgedge 别名
  • 86edbd7 ext rm/update 输出显示解析后的包名
  • ef3c905 build/dep 改进 rpm/deb 依赖解析
  • 7144e09 刷新 fork 元数据与可用性矩阵条目
  • befffbf DEB 构建将成功命令视作权威结果
  • 33fd517 DEB 成功但无产物时不再显示空包列表横幅
  • 3b450f2 下载源码时避免将扩展名与版本错误拼接
  • 33847ab ext rm/update 满足 staticcheck S1011
  • b8b917d 依赖安装失败降级为 warning
  • 8110c00 调整 ivorysqldb / babelfishpg 别名
  • fac9faf 版本提升到 1.3.0
  • 1f88f06 版权年份更新为 2026
  • c804757 v1.3.0 发布提交

校验和

BASH
196f32419886da095f303b1bcad2729b674abc03d412199e88a39390b2616534  pig-1.3.0-1.aarch64.rpm
a2dcc930dd47a08e85285c1fb7925e1355a1e67d458a265a7ef6d9666bc8e7ec  pig-1.3.0-1.x86_64.rpm
c7ebda6b9839408b12ffe1c8ea561f03e1793aae0732f9bbe2320a0d45160714  pig-v1.3.0.darwin-amd64.tar.gz
b717b485ed0a4a8c11dd8bf918400595b21df5ef43818836ec332f8518674c1a  pig-v1.3.0.darwin-arm64.tar.gz
40e6570c6ba0fe36c97950ff8de585eecb6bc1f862509a04f410a5f08ee90148  pig-v1.3.0.linux-amd64.tar.gz
d61430eeafc8005a22918a9aa60dea5c987916f9834331b5484f761b8235644f  pig-v1.3.0.linux-arm64.tar.gz
62c9a4fadc7dda393d6f28ab83b5f3d741e7d7f7de7abe40a5b89c393288519c  pig_1.3.0-1_amd64.deb
19261ae50e873a05a10a6ad500ab1b429b22e2612325c09f9cd5443dcd34308b  pig_1.3.0-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.3.0

v1.2.0

  • 扩展目录与别名解析增强：

    • 引入动态 PG 分类别名解析，按 PG 主版本选择别名映射。
    • 引入 OS 维度别名覆盖（ansible/bootstrap），并在未知发行版回退中收敛为 PGDG-only。
    • 新增 node/infra、babelfish/cloudberry 等别名并更新扩展元数据，减少包解析歧义。

  • 高风险操作计划预览：

    • 新增 pig install --plan，支持结构化执行计划输出。
    • 统一 pig pitr 与 pgBackRest repack/expire 的计划预览语义。
    • 新增 plan flag 一致性测试，确保子命令行为对齐。

  • sty 原生配置能力：

    • 新增 pig sty configure 命令及完整执行流（preflight、参数处理、执行编排）。
    • 统一 sty conf/configure 行为，默认走原生实现并保留 --raw 回退。
    • 补充 configure 主流程、preflight、路由与安装联动测试，提升可维护性。

  • 仓库/构建/可靠性修复：

    • 修复 repo cache 在 os.Stat 错误场景中的 nil dereference。
    • 对齐 Ubuntu 与 Debian 仓库 channel 映射，补充 reload 镜像拉取超时控制。
    • 加固 repo rm 对 dotted module 名称的安全删除与路径校验。
    • 修复 sty init 与 build 相关符号链接保留、跨设备迁移与目标目录处理问题。
    • 改进文本输出与矩阵配色渲染，修复 ext 命令空参数与空目标校验问题。

  • 35 Commit，66 文件变更，代码行：+5006 / -379

  • PG 扩展与内核包更新

包名旧版本新版本备注
timescaledb2.25.02.25.1
citus14.0.0-314.0.0-4使用最新官方版本重新构建
age1.7.01.7.0新增 PG 17 的 1.7.0 版本支持
pg_background-1.8仅构建 DEB 包，RPM 来自 PGDG
pgmq1.10.01.10.1当前没有该扩展包
pg_search0.21.60.21.8直接下载使用
oriolepg17.1117.16OriolePG 内核更新
orioledbbeta12beta14配套 OriolePG 17.16
cloudberry-2.0.0新增包
babelfishpg-5.5.0新增 BabelfishPG 包组
babelfish-5.5.0新增 Babelfish 兼容包
antlr4-runtime413-4.13新增 Babelfish 依赖运行时

校验和

BASH
344b77385fa9c3d4fe5e1961340e68716251e38d1cb8308f5af45ce8a03cd206  pig-1.2.0-1.aarch64.rpm
aa9cf1820a9045cc42f0d66689d5e8679cb71452042f3f01ddd4c3a518a2b757  pig-1.2.0-1.x86_64.rpm
f26e4d9e9fa76c39f7c591c18a09287ca3388e016d121c196302ee9eafb5b678  pig-v1.2.0.darwin-amd64.tar.gz
2ca41efc3495822305f6e6a3ae1825d57cc97e764f280581f833c72e6e5019a2  pig-v1.2.0.darwin-arm64.tar.gz
f7aa291b3534d92d0459b6e8301190e39c63db14a45a6c097d4c5d3062c35181  pig-v1.2.0.linux-amd64.tar.gz
38007ecd6d7a69bae0e3d8f7c78f1a4c8bbaead320b7ac319b0d94d6b53853f0  pig-v1.2.0.linux-arm64.tar.gz
e824716ddfbf3805dc0a1fd6d97917241b7780503657e9fd40a37beb6b398d7a  pig_1.2.0-1_amd64.deb
b67baa404d877b37004331041cb270c85b8f9a3f8a92a5083390a54d76553d2a  pig_1.2.0-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.2.0

v1.1.0

该版本是从 v1.0.0 到 v1.1.0 的一次规划中架构级升级（79 commits，193 files 变更）， 核心目标是把 pig 从“人类可用 CLI”推进到“Agent-native 可编排 CLI”。

新增七个扩展，总可用扩展数量达到 451 个。

新功能

  • Agent-native 统一输出框架落地：引入全局 --output（text/yaml/json/json-pretty），为 ext/repo/pg/pt/pb/pitr/status/version/context 等命令提供统一 Result 结构、稳定状态码与可机器解析输出。
  • 引入 ANCS（Agent Native Command Schema）元数据体系：为命令补齐 type/volatility/parallel/risk/confirm/os_user/cost 等语义字段，help 在结构化模式下可直接输出命令能力树，便于 Agent 自动发现能力与风险边界。
  • 新增 pig context（pig ctx）环境快照命令：一次调用聚合主机、PostgreSQL、Patroni、pgBackRest、扩展信息，专门面向 Agent 工作流做上下文注入。
  • Plan 能力从 PITR 扩展到更多高风险动作：新增 pig ext add/rm --plan、pig pg stop/restart --plan、pig pt switchover/failover --plan，并统一为可审阅执行计划（动作、影响面、风险、预期结果）。
  • 结构化结果覆盖进一步完善：pgbackrest info 可嵌入原生 JSON 信息，Patroni/PostgreSQL/PITR/Repo/Ext 子系统的结构化返回与辅助 DTO 统一，兼容自动化消费。
  • 兼容层增强：对 pg_exporter/pg_probe/do/sty 等存量命令引入 legacy structured wrapper，在保留旧交互行为的同时提供结构化执行结果与输出捕获。
  • Pigsty 版本更新至 v4.1.0

扩展更新

扩展旧版本新版本
timescaledb2.24.02.25.0
citus14.0.0-214.0.0-3
pg_incremental1.2.01.4.1
pg_bigm1.2-202406061.2-20250903
pg_net0.20.00.20.2
pgmq1.9.01.10.0
pg_textsearch0.4.00.5.0
pljs1.0.41.0.5
sslutils1.4-11.4-2
table_version1.11.01.11.1
supautils3.0.23.1.0
pg_math1.01.1.0
pgsentinel1.3.11.4.0
pg_uri1.201512241.20251029
pgcollection1.1.01.1.1
pg_readonly1.0.31.0.4
timestamp91.4.0-11.4.0-2
pg_uint1281.1.11.2.0
pg_roaringbitmap0.5.51.1.0
plprql18.0.018.0.1
pglinter1.0.11.1.0
pg_jsonschema0.3.30.3.4
pg_anon2.5.13.0.1
vchord1.0.01.1.0
pg_search0.21.40.21.6/0.21.7
pg_graphql1.5.12-11.5.12-2
pg_summarize0.0.1-20.0.1-3
nominatim_fdw-1.1.0
pg_utl_smtp-1.0.0
pg_strict-1.0.2
pg_track_optimizer-0.9.1
pgmb-1.0.0

Bug 修复

  • 安全修复：修复 pig build proxy 在异常地址输入下的解析 panic 问题。
  • 安全修复：修复 pig pg log 文件名路径穿越风险，阻止通过 ../../ 访问日志目录外文件。
  • 安全加固：加强 installer/repo 路径处理与引号处理，降低路径注入与异常路径误用风险。
  • 构建链路可靠性修复：pig build get/pkg/ext 在下载或构建失败时正确传递错误并返回非零退出码；修复 DEB 构建中 pg_ver 不匹配导致的误报失败。
  • 仓库与目录刷新修复：ext/repo reload 支持静默镜像回退；repo add/set/rm 在缓存更新失败时正确返回错误状态。
  • 扩展管理修复：ext update 调整为显式目标更新并修复状态漂移问题；ext import 将请求的 DEB 资源下载到指定 repo 目录。
  • 输出与可观察性修复：修复结构化输出 exit code 与文本渲染一致性问题；修复 pg status 权限处理与解析稳定性问题。

校验和

BASH
95245dc035270df2b02cdd5d19afac57ccf4949a61b07b1b806fffde3a3b780e  pig-1.1.0-1.aarch64.rpm
8b1a26f1b5dd002841a0b31904eea8ce94d1e6c4acde4704a78d9e121e1656f4  pig-1.1.0-1.x86_64.rpm
dbd079510513f1cd0521b0871cc6fe3eed8f7fa26f66c04c682568c43e24c456  pig-v1.1.0.darwin-amd64.tar.gz
3f3ba081b54569a7de4d9a8fce72c02c84d9e1cbeb53173567f970c7291af251  pig-v1.1.0.darwin-arm64.tar.gz
ad61384bf01cbb8346ce869da0bc893203ad316c516fb9420cb748f1519a005e  pig-v1.1.0.linux-amd64.tar.gz
7713632beea1e6ca5c3e2e7172c4adee13a2b1b256755f6c2898b6ca98ee1e00  pig-v1.1.0.linux-arm64.tar.gz
70cfc41b7b0aad48f29e12c22c34afd55b938bf50868ac8ab067b9cb62ccb867  pig_1.1.0-1_amd64.deb
fc5cf16671254f8f3495ff7e80c9d77d06b2328c1a247f90f96cf1e918e0ad0e  pig_1.1.0-1_arm64.deb

发布：https://github.com/pgsty/pig/releases/tag/v1.1.0

v1.0.0

本版本引入三组主要的新子命令（pig pg、pig pt、pig pb），用于管理 PostgreSQL、Patroni 和 pgBackRest，同时新增编排式 PITR 命令，并增强扩展可用性显示。

新增命令

  • pig pg - PostgreSQL 实例管理

    • pg init/start/stop/restart/reload/status - 控制与管理 PostgreSQL 实例
    • pg role/promote - 检测和切换实例角色（主库/从库）
    • pg psql/ps/kill - 连接与会话管理
    • pg vacuum/analyze/freeze/repack - 数据库维护操作
    • pg log - 日志查看（list/tail/cat/less）

  • 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、还原点
    • 支持计划预览模式与恢复后指引

新功能

  • 为 pig ext avail 和 pig ext ls 添加可用性矩阵

改进

  • 统一 pg/pt/pb 命令别名风格
  • 规范化错误消息格式
  • 代码重构与清理

Bug 修复

  • 修复 UTIL 扩展分类缺失问题

校验和

BASH
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 操作系统小版本热修复

校验和

BASH
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 镜像仓库

校验和

BASH
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

BASH
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

校验和

BASH
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

校验和

BASH
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

  • 全新的网站： /ext/
  • 修复了不必要的 sudo 使用问题，现在可以方便的在容器中使用
  • 允许 pig ext link 命令使用形如 pg17 pg18 的参数形式
  • 新增环境变量 PIG_NO_SUDO，强制不使用 sudo 执行命令
  • RPM 变更日志：为几乎所有扩展新增 PG 18 支持
  • DEB 变更日志：为几乎所有扩展新增 PG 18 支持
  • Infra 变更日志：例行更新至最新版本

校验和

BASH
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 脚本直接构建 RPM
    • pig build spec 现在支持直接从 Pigsty 仓库下载 spec 文件包
    • pig build repo / pig repo add / pig repo set 现在默认使用 node,pgsql,infra 仓库模块，取代原本的 node,pgdg,pigsty
  • 大量优化了错误日志记录。
  • 基于 hugo 与 hextra 全新目录网站

校验和

BASH
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 前缀
  • 改进了网络检查与下载的逻辑

校验和

BASH
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 的支持存根
  • 专门的新文档网站： /ext/pig/
  • 使用 go 1.25 重新构建，新增 CI/CD 管道
  • 在中国大陆使用 PIGSTY PGDG 镜像
  • 移除空的 pgdg-el10fix 仓库
  • 使用 Pigsty Babelfish 镜像
  • 修复 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

校验和

BASH
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

校验和

TEXT
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 仓库

校验和

BASH
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

BASH
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 模块（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.1

更新扩展列表。

发布：https://github.com/pgsty/pig/releases/tag/v0.1.1

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

pig CLI 命令参考概览

pig CLI 提供了全面的工具集，用于管理 PostgreSQL 安装、扩展、软件仓库以及从源码构建扩展。使用 pig help <command> 查看命令文档。

  • pig repo：管理软件仓库
  • pig ext：管理 PostgreSQL 扩展
  • pig build：从源码构建扩展
  • pig install：使用原生包管理器安装包，并对 PostgreSQL 别名做翻译
  • pig sty：管理 Pigsty 安装与 Grafana 仪表盘
  • pig inventory：检视、编辑、校验与交换 Pigsty 配置清单（v1.6.0 新增）
  • pig do：执行 Pigsty 管理 playbook 任务
  • pig pe：访问 pg_exporter 指标与配置
  • pig pg：管理本地 PostgreSQL 服务器
  • pig pt：透明运行 patronictl，附带服务与配置辅助命令
  • pig pb：管理 pgBackRest 备份与恢复
  • pig pitr：进行完整 PITR 工作流
  • pig context：输出面向人工和 Agent 的环境上下文快照
  • pig status / update / version：查看环境、升级 pig、打印版本信息

概览

BASH
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
  context     显示环境上下文快照
  do          运行管理任务
  inventory   检视、编辑、校验与交换 Pigsty 配置清单
  patroni     透明运行 patronictl（附 Pigsty 服务与配置辅助）
  pg_exporter 管理 pg_exporter 与监控指标
  pgbackrest  管理 pgBackRest 备份与恢复
  pitr        使用 pgBackRest 进行时间点恢复
  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   配置清单路径
      --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

BASH
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

BASH
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

BASH
# 环境设置
pig build spec                   # 初始化构建规格
pig build repo                   # 设置仓库
pig build repo --beta            # 设置仓库，并额外启用 PostgreSQL 19 beta 仓库
pig build tool                   # 安装构建工具
pig build tool --beta            # 安装构建工具，并额外安装 PG19 beta 构建包
pig build rust -y                # 强制重装 Rust（默认不重装）
pig build rust -m                # 使用中国镜像安装 Rust，并写入 Cargo 镜像配置
pig build pgrx                   # 安装 PGRX 框架
pig build pgrx -b                # 自动探测时包含 PostgreSQL 19 beta pg_config

# 构建扩展
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。

BASH
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

BASH
pig sty init                     # 安装 Pigsty 到 ~/pigsty
pig sty boot                     # 安装 Ansible 依赖
pig sty conf                     # 生成配置
pig sty deploy                   # 运行部署 playbook
pig sty list                     # 列出可用 Pigsty 版本
pig sty get 4.5.0                # 下载指定 Pigsty 版本
pig sty grafana list             # 管理 Grafana 仪表盘（info/list/boot/load/init/dump/clean/lang/style）

pig inventory

检视、编辑、校验、体检并与 CMDB 交换 Pigsty 配置清单（pigsty.yml），根级命令组，别名 inv， 详情请参考 pig inventory。（v1.6.0 新增）

BASH
pig inventory status             # 检视当前生效的清单来源
pig inventory list               # 列出清单拓扑与取值类型
pig inventory show               # 原样显示清单 YAML（可能包含敏感信息）
pig inventory edit               # 在 $EDITOR 中编辑清单或选中片段
pig inventory validate           # 校验一份完整的静态 Pigsty 清单
pig inventory check              # 检查清单、控制器与目标节点就绪状态
pig inventory diff other.yml     # 对比声明差异（不输出取值）
pig inventory cmdb check         # 与 PostgreSQL CMDB 交换（实验性）

pig do

执行 Pigsty 管理任务，底层调用对应的 Ansible playbook。

BASH
pig do pgsql-add  <cls> [ip...]       # 添加集群或实例
pig do pgsql-rm   <cls> [ip...]       # 移除集群或实例
pig do pgsql-db   <cls> <dbname>      # 创建或更新数据库
pig do pgsql-user <cls> <username>    # 创建或更新用户
pig do pgsql-ext  <cls> [ext...]      # 安装扩展
pig do node-pkg   <sel> [pkg...]      # 安装节点软件包

pig pe

访问 pg_exporter 暴露的 PostgreSQL 监控指标，默认连接 127.0.0.1:9630。

BASH
pig pe list                    # 列出可用指标类型
pig pe get                     # 获取所有 pg_ 前缀指标
pig pe stat                    # 查看 exporter 统计信息
pig pe reload                  # 重载 pg_exporter 配置
pig pe --host 127.0.0.1 -p 9630 get

pig context

输出环境上下文快照，覆盖主机、PostgreSQL、Patroni、pgBackRest 与已安装扩展。该命令适合排障和自动化脚本快速了解当前节点状态。

BASH
pig context                      # 文本输出
pig context -o json              # JSON 输出
pig context -m postgres          # 只输出 PostgreSQL 模块（默认包含 host）
pig context -m postgres,!host    # 排除 host 模块

pig pg

管理本地 PostgreSQL 服务器，详情请参考 pig pg

BASH
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

透明运行 patronictl 管理 Patroni HA 集群，详情请参考 pig pt

BASH
pig pt list pg-meta              # 列出集群成员（原生透传）
pig pt show-config pg-meta       # 显示集群动态配置（原生透传）
pig pt set ttl=60                # 本地语法糖：修改 Patroni/PG 配置
pig pt restart pg-test --pending # 应用待重启成员（原生透传）
pig pt status                    # 本地命令：综合服务与集群状态
pig pt log -f                    # 本地命令：实时查看日志

pig pb

管理 pgBackRest 备份与恢复，详情请参考 pig pb

BASH
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

BASH
pig pitr -d                      # 恢复到最新数据
pig pitr -t "2025-01-01 12:00:00+08"  # 恢复到指定时间
pig pitr -I                      # 恢复到备份一致性点
pig pitr -d --plan               # 显示执行计划（不实际执行）
pig pitr -d -y                   # 跳过确认（自动化）

辅助命令

BASH
pig status                       # 显示当前环境状态
pig status -o json               # 结构化状态输出
pig update                       # 将 pig 自身升级到最新版
pig update -m                    # 使用 pigsty.cc 镜像升级
pig update -v X.Y.Z              # 升级到已发布在当前软件仓库中的指定版本
pig version                      # 显示 pig 版本信息
pig version -o json              # 结构化版本输出

6 - pig repo

使用 pig repo 子命令管理软件仓库

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

BASH
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 add all -m              # 优先使用内置的中国区域镜像
  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刷新仓库目录

快速入门

BASH
# 方法 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 仓库 ，指定使用默认区域
pig repo add all -m                   # 明确选择内置的中国区域镜像

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

模块

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

模块说明仓库列表
all安装 PG 所需的全部核心模块node + infra + pgsql
pgsqlPGDG + Pigsty PG 扩展pigsty-pgsql + pgdg
pigstyPigsty Infra + PGSQL 仓库pigsty-infra, pigsty-pgsql
pgdgPGDG 官方仓库pgdg-common, pgdg14-18
nodeLinux 系统仓库base, updates, extras, epel, baseos, appstream…
infra基础设施组件仓库pigsty-infra, nginx, docker-ce
dockerDocker 仓库docker-ce
betaPostgreSQL 19 Beta 版本pgdg19-beta, pgdg-beta
extraPGDG Non-Free 与三方扩展pgdg-extras, timescaledb, citus
groongaPGroonga 仓库groonga
mssqlWiltondb 仓库（已弃用）babelfish
perconaPercona PG + PG_TDEpercona
llvmLLVM 工具链仓库llvm
kubeKubernetes 仓库kubernetes
grafanaGrafana 仓库grafana
haproxyHAProxy 仓库haproxyd, haproxyu
redisRedis 仓库redis
mongoMongoDB 仓库mongo
mysqlMySQL 仓库mysql
clickClickHouse 仓库clickhouse
gitlabGitLab 仓库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 模块，一次性添加所有需要的仓库到系统中，对绝大多数用户来说，这是合适的起点。

BASH
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 参数指定特定区域时，会优先查找对应区域的仓库 URL，不存在时回退到 default。从 v1.7.0 起，-m|--mirror 会明确选择内置的 china 定义，包括 pigsty.cc 与维护中的国内镜像，不再在运行时将 PGDG URL 改写到代理端点。

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

repo list

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

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

repo info

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

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

repo status

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

BASH
pig repo status

repo add

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

BASH
pig repo add pgdg                # 添加 PGDG 仓库
pig repo add pgdg pigsty         # 添加多个仓库
pig repo add all                 # 添加所有必要仓库 (pgdg + pigsty + node)
pig repo add pigsty -u           # 添加并更新缓存
pig repo add all -r              # 添加前移除现有仓库
pig repo add all -ru             # 移除、添加并更新（完全重置）
pig repo add pgdg --region=china # 使用中国镜像
pig repo add pgsql -m            # 明确选择中国区域镜像

选项：

  • -r|--remove：添加新仓库前移除现有仓库
  • -u|--update：添加仓库后运行包缓存更新
  • -m|--mirror：明确选择内置的 china 仓库定义
  • --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。清空现有仓库并设置新仓库，然后更新缓存。

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

repo set 支持与 repo add 相同的 --region 与 -m|--mirror 区域选择；它始终是覆盖式语义，相当于 repo add all --remove --update。

repo rm

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

BASH
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

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

BASH
pig repo update                  # 更新包缓存
平台等效命令
ELdnf makecache
Debianapt update

repo create

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

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

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

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

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

SOW 的 --pigsty 事务会：

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

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

repo cache

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

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

选项：

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

repo boot

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

BASH
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 刷新仓库元数据到最新版本。

BASH
pig repo reload                  # 刷新仓库目录

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

7 - pig ext

使用 pig ext 子命令管理 PostgreSQL 扩展

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

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

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

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

BASH
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

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

使用说明：

  1. 未指定 PostgreSQL 版本时，工具会尝试从 PATH 中的 pg_config 自动检测当前活动的 PostgreSQL 安装。
  2. 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。
  3. 扩展管理器会根据操作系统自动适配不同的包格式：
    • RHEL/CentOS/Rocky Linux/AlmaLinux 使用 RPM 包
    • Debian/Ubuntu 使用 DEB 包
  4. 某些扩展可能有依赖项，安装时会自动解决。
  5. 谨慎使用 -y 参数，它会自动确认所有提示。

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

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

ext list

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

BASH
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

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

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

ext avail

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

BASH
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 实例已安装扩展的状态。

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

选项：

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

ext scan

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

BASH
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 翻译。

BASH
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 扩展。

BASH
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；必须显式写出要更新的目标。

BASH
pig ext update                   # no-op：必须显式指定目标
pig ext update pg_duckdb         # 更新特定扩展
pig ext update postgis timescaledb  # 更新多个扩展
pig ext update pg_duckdb -y      # 自动确认更新
pig ext update pg_duckdb -m      # 选择内置中国区域软件源

选项：

  • -v|--version：指定 PG 大版本
  • -y|--yes：自动确认更新
  • -m|--mirror：优先使用 pigsty.cc 镜像作为更新来源

ext import

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

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

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

BASH
pig ext link 18                  # 链接 PG 18 到 PATH
pig ext link pg17                # pg 前缀会被剥离，链接 PG 17
pig ext link 16                  # 链接 PG 16 到 /usr/pgsql
pig ext link /usr/pgsql-16       # 从指定路径链接到 /usr/pgsql
pig ext link polar               # 链接 PolarDB / PolarPG 安装
pig ext link /usr/polar-17       # 从指定 PolarDB 路径链接
pig ext link null                # 取消当前 PostgreSQL 链接
pig ext link none                # null / none / nil / nop / no 均可取消链接

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

ext reload

刷新扩展元数据。

BASH
pig ext reload                   # 刷新扩展目录

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

8 - pig build

使用 pig build 子命令从源码构建扩展

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

BASH
pig build - Build Postgres Extension

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

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

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

快速入门

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

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

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

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

更精细的控制方式：

BASH
# 设置环境
pig build spec                   # 初始化构建规范
pig build repo                   # 设置仓库
pig build repo --beta            # 设置仓库，并额外启用 PostgreSQL 19 beta 仓库
pig build tool                   # 安装构建工具
pig build tool --beta            # 安装构建工具，并额外安装 PG19 beta 构建包

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

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

构建基础设施

目录结构

TEXT
~/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

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

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

功能：

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

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

build repo

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

BASH
pig build repo                   # 等同于：pig repo set -ru
pig build repo -m                # 选择内置中国区域软件源
pig build repo --beta            # 同时启用 PostgreSQL 19 beta 仓库模块

功能： 以 pig repo set -ru 初始化构建所需仓库：移除旧仓库、添加所需仓库并更新包缓存。--beta/-b 会把 beta 模块追加到仓库模块列表，用于显式构建 PostgreSQL 19 beta 相关包；稳定默认路径仍只使用 PG14-18。

选项：

  • -b|--beta：额外启用 PostgreSQL beta 仓库模块
  • -m|--mirror：选择内置的 china 区域软件源

build tool

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

BASH
pig build tool                   # 安装默认工具集
pig build tool mini              # 最小工具集
pig build tool full              # 完整工具集
pig build tool rust              # 添加 Rust 开发工具
pig build tool --beta            # 额外安装 PG19 beta 构建依赖

工具包：

  • 最小（mini）： GCC/Clang 编译器、Make 和通用构建必需品；不安装 PostgreSQL server/devel 包
  • 默认 / full： 编译器、开发库、打包工具（rpmbuild、dpkg-dev）以及稳定 PG14-18 构建依赖
  • --beta： 在默认工具集基础上额外安装 PG19 beta 的 server/devel 构建包

build rust

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

BASH
pig build rust                   # 带确认安装
pig build rust -y                # 强制重新安装 Rust 工具链
pig build rust -m                # 使用中国镜像安装 Rust，并写入 Cargo 镜像配置

安装内容： Rust 编译器（rustc）、Cargo 包管理器、Rust 标准库、开发工具。-m|--mirror 会使用镜像模式，并为 Cargo 写入 rsproxy.cn 相关配置。

build pgrx

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

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

前提条件： 必须先安装 Rust 工具链、PostgreSQL 开发头文件。默认自动探测只覆盖稳定 PG14-18；需要 PG19 beta 时使用 -b|--beta，或通过 --pg 19 显式指定。

build proxy

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

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

BASH
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 以便直接下载源码。

BASH
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

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

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

选项：

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

build ext

编译扩展并创建安装包。

BASH
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

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

BASH
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：构建标准扩展

BASH
# 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 扩展

BASH
# 1. 设置 Rust 环境
pig build spec
pig build tool
pig build rust                   # 如需强制重装可追加 -y
pig build rust -m                # 中国网络环境可使用镜像模式
pig build pgrx

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

# 3. 安装
sudo pig ext add pgmq

工作流 3：构建多个版本

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

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

故障排除

找不到构建工具

BASH
# 安装构建工具
pig build tool

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

缺少依赖

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

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

找不到 PostgreSQL 头文件

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

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

Rust/PGRX 问题

BASH
# 重新安装 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

# 需要 PG19 beta 时
pig build repo --beta
pig build tool --beta
pig build pgrx -b

扩展构建矩阵

常见构建的扩展

扩展类型构建时间复杂度特殊要求
pg_repackC快速简单无
pg_partmanSQL/PLPGSQL快速简单无
citusC中等中等无
timescaledbC慢复杂CMake
postgisC非常慢复杂GDAL、GEOS、Proj
pg_duckdbC++中等中等C++17 编译器
pgroongaC中等中等Groonga 库
pgvectorC快速简单无
plpython3C中等中等Python 开发
pgrx 扩展Rust慢复杂Rust、PGRX

9 - pig sty

使用 pig sty 子命令管理 Pigsty 安装

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

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

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

Examples:
  pig sty init                 # extract and init ~/pigsty
  pig sty boot                 # install ansible & other deps
  pig sty conf                 # generate pigsty.yml config file
  pig sty deploy               # run the deploy.yml playbook
命令描述备注
sty init安装 Pigsty
sty boot原生引导 Pigsty 控制节点需要时自动提权至 root
sty conf原生生成并校验 InventoryGo 工作流
sty deploy运行部署 playbook
sty list列出可用 Pigsty 版本
sty get下载 Pigsty 源码压缩包
sty grafana管理 Grafana 仪表盘（别名 gf）v1.6.0 新增

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

快速入门

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

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

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

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

sty init

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

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

选项：

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

sty boot

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

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

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

引导阶段

原生工作流依次完成：

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

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

来源选择与工作模式

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

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

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

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

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

仓库事务与失败边界

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

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

选项：

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

结构化输出

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

BASH
pig sty conf -g
pig inv edit
pig sty deploy

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

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

sty conf

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

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

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

模板与输出安全

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

结构化变更

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

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

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

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

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

选项：

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

预检与校验

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

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

结构化输出

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

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

sty deploy

使用 deploy.yml 剧本部署 Pigsty。

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

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

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

sty list

列出可用的 Pigsty 版本。

BASH
pig sty list                     # 列出可用版本

sty get

下载 Pigsty 源码压缩包。

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

sty grafana

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

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

连接与凭据：

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

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

传统仪表盘与 schema v2 资源

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

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

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

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

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

10 - pig inventory

检视、编辑、校验、体检并与 CMDB 交换 Pigsty 配置清单

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

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

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

Usage:
  pig inventory [command]

Aliases:
  inventory, inv

Available Commands:
  check       Check Inventory, controller, and opt-in target readiness
  cmdb        Exchange Inventory with Pigsty's existing PostgreSQL CMDB (experimental)
  diff        Compare declarations without emitting Inventory values
  edit        Edit Inventory or one selected YAML fragment
  list        List ordered Inventory topology and value kinds
  show        Show verbatim Inventory YAML (may contain secrets)
  status      Inspect the active Inventory source without executing it
  validate    Validate one complete static Pigsty Inventory
命令别名说明
inv status检视当前生效的清单来源（不执行清单）
inv listls列出清单拓扑与取值类型（--depth 限制深度）
inv show原样显示清单 YAML（可能包含敏感信息）
inv edite在 $EDITOR 中编辑清单或选中片段
inv validatev校验一份完整的静态 Pigsty 清单
inv checkck检查清单、控制器与目标节点就绪状态
inv diff对比两份清单的声明差异（不输出取值）
inv cmdb与 PostgreSQL CMDB 交换配置（实验性）

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

快速入门

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

选择器

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

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

inv edit

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

BASH
pig inventory edit                       # 编辑整个清单
pig inv e pg-meta                        # 编辑一个片段
pig inv e vars --from vars.yml           # 从文件（或 stdin：-）替换选中片段
参数说明
--from从常规文件或 stdin（-）替换选中片段，跳过编辑器

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

inv validate

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

BASH
pig inventory validate                   # 校验当前清单
pig inv v ./pigsty.yml                   # 校验指定文件
pig inv v --strict                       # 警告视为失败
pig inv v --ansible                      # 额外用 ansible-inventory 交叉解析
pig inv v --strict -o json               # 结构化输出（CI 友好）
参数说明
--strict把校验警告当作失败
--ansible额外使用带边界的 ansible-inventory 适配器交叉解析
--timeout--ansible 兼容性校验超时（默认 10s）

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

inv check

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

BASH
pig inventory check                      # 清单 + 控制器基础检查
pig inv ck -p ansible                    # 追加 ansible 环境检查
pig inv ck -p network                    # 追加网络可达性探测
pig inv ck -p ssh --user admin           # 追加 SSH 登录探测
pig inv ck -p ssh --sudo                 # SSH 探测并验证 sudo -n
参数简写说明
--profile-p追加探测：ansible / network / ssh
--user显式 SSH 用户（默认控制器当前用户）
--portTCP/SSH 目标端口（默认 22）
--sudo在 ssh 探测中额外验证 sudo -n true

inv cmdb（实验性）

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

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

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

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

11 - pig postgres

使用 pig postgres 子命令管理本地 PostgreSQL 服务器

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

BASH
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 initinitdb, i初始化数据目录封装 initdb
pg startboot, up启动 PostgreSQL封装 pg_ctl start
pg stophalt, down停止 PostgreSQL封装 pg_ctl stop
pg restartreboot重启 PostgreSQL封装 pg_ctl restart
pg reloadhup重载配置封装 pg_ctl reload
pg statusst, stat查看服务状态显示进程与相关服务状态
pg promotepro提升备库为主库封装 pg_ctl promote
pg roler检测实例角色输出 primary/replica

连接与查询：

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

数据库维护：

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

参数调优：

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

实例 Fork：

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

日志工具：

命令别名描述备注
pg logl日志管理父命令
pg log listls列出日志文件
pg log tailt, f实时查看日志tail -f
pg log showcat, c输出日志内容
pg log lessvi, v用 less 查看
pg log grepg, search搜索日志

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

命令别名描述
pg svc startboot, up启动 postgres 服务
pg svc stophalt, dn, down停止 postgres 服务
pg svc restartreboot, rt重启 postgres 服务
pg svc reloadrl, hup重载 postgres 服务
pg svc statusst, stat显示服务状态

快速入门

BASH
# 服务控制
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-Upostgres数据库超级用户（或 $PIG_DBSU 环境变量）

版本检测逻辑：

  1. 如果指定了 -v，使用指定 PG 大版本
  2. 否则从数据目录的 PG_VERSION 文件读取版本
  3. 如果都无法获取，使用 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 命令。
BASH
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-Kfalse禁用数据校验和
--force-ffalse强制初始化，删除已有数据（危险！）
--yes-yfalse与 --force 配合时跳过覆盖确认提示

pg start

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

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

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

选项：

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

关闭模式说明：

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

pg restart

使用 pg_ctl restart 重启 PostgreSQL 服务器。

BASH
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 信号。

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

pg status

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

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

输出内容：

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

pg promote

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

BASH
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 实例的角色（主库或备库）。

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

选项：

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

输出说明：

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

检测策略（按优先级）：

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

连接与查询命令

pg psql

通过 psql 连接到 PostgreSQL 数据库。

BASH
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 视图。

BASH
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 参数才会实际执行。

BASH
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 工作流一致。

BASH
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      # 预览克隆计划

选项：

参数简写说明
--portPostgreSQL 端口（默认 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 命令。

BASH
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-FVACUUM FULL（需要排他锁）

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

pg analyze

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

BASH
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 回卷。

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

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

pg repack

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

BASH
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、内存与数据盘容量，并以文本形式输出配置项。

BASH
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-poltp调优画像：oltp / olap / tiny / crit
--cpu-c0CPU 核数，0 表示自动探测
--mem-m0内存大小（MB），0 表示自动探测
--disk-d0数据盘容量（GB），0 表示自动探测
--max-conn-C0覆盖 max_connections，0 表示使用画像默认值
--shmem-ratio-R0.25shared_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 枚举。

BASH
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-port5432 或 $PG_PORT源端口
--start-sfalse创建后启动 fork
--force-ffalse覆盖已有且已停止的目标目录，并跳过确认
--timeout-t60启动等待超时（秒）
--yes-yfalse跳过确认提示
--planfalse只显示执行计划，不执行

管理子命令：

命令常用参数说明
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，不实时判断实例是否正在运行。

结构化输出：

BASH
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 时跟踪最新日志。

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

pg log list

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

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

pg log tail

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

BASH
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-n50显示的行数
--follow-ffalse兼容性 no-op；tail 本身总是跟踪

pg log show

输出日志文件内容。

BASH
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-n50显示的行数

pg log less

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

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

pg log grep

搜索日志文件内容。

BASH
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 服务的功能：

BASH
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 startboot, up
pg svc stophalt, dn, down
pg svc restartreboot, rt
pg svc reloadrl, hup
pg svc statusst, 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

透明运行 patronictl，附带 Pigsty 服务、配置与日志辅助命令

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

BASH
pig pt transparently launches the installed patronictl binary.

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

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

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

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

命令概览

透传命令（patronictl 原生）：

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

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

本地命令（pig 实现）：

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

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

快速入门

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

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

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

Pig/PT 选项

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

参数简写说明
--config-file-c显式指定 Patroni/patronictl 配置文件
--dbsu执行 patronictl 的 OS 用户（默认 $PIG_DBSU 或 postgres）
--dcs-url-d覆盖 Patroni DCS URL（--dcs 为其别名）
--insecure-k允许 TLS 连接不校验证书
BASH
pig pt -c /path/patroni.yml list pg-meta   # 包装层 -c：配置文件
pig pt query -c 'select 1'                 # 原生 query 的 -c：SQL 语句，不会被 pig 截获

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

配置文件解析

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

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

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

透传执行与输出模式

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

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

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

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

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

pt set

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

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

键分类规则：

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

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

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

服务管理

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

命令别名说明
pt service startpt svc up启动 Patroni 服务
pt service stoppt svc dn停止 Patroni 服务
pt service restartpt svc rs重启 Patroni 服务
pt service reloadpt svc rl重载 Patroni 服务
pt service statuspt svc st显示服务状态

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

pt status

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

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

pt log

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

BASH
pig pt log                     # 显示最近 50 行日志
pig pt log -f                  # 实时跟踪日志输出
pig pt log -n 100              # 显示最近 100 行
pig pt log show -o json        # JSONL 快照
pig pt log tail -n 100         # 跟踪日志
pig pt log grep ERROR          # 搜索日志
子命令别名说明
showcat, c, s输出最近 Patroni 日志
tailt, f, follow持续跟踪 Patroni 日志
grepg, search搜索 Patroni 日志
参数简写默认值说明
--follow-ffalse实时跟踪日志输出
--lines-n50显示的日志行数
--log-dir自动解析日志目录

从 v1.5.x 迁移

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

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

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

设计说明

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

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

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

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

13 - pig pgbackrest

使用 pig pgbackrest 子命令管理 pgBackRest 备份与时间点恢复

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

BASH
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 infoi显示备份仓库信息pgbackrest info
pb listls列出备份集，仓库，Stanzapgbackrest info

备份与恢复：

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

Stanza 管理：

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

控制命令：

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

快速入门

BASH
# 查看备份信息
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-spgBackRest stanza 名称（自动检测）
--config-c配置文件路径
--repo-r仓库编号（多仓库场景）
--dbsu-U数据库超级用户（默认：$PIG_DBSU 或 postgres）

Stanza 自动检测：

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

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

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

多仓库支持：

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

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

信息查询命令

pb info

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

BASH
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

列出备份仓库中的资源。

BASH
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

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

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

选项：

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

备份类型：

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

主库检查：

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

pb expire

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

BASH
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 中配置：

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

恢复命令

pb restore

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

BASH
# 恢复目标（互斥选项）
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自动补全为今天（当前时区）

恢复流程：

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

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

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

Stanza 管理命令

pb create

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

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

选项：

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

pb upgrade

PostgreSQL 大版本升级后更新 stanza。

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

选项：

参数说明
--no-onlinePostgreSQL 未运行时升级

使用场景：

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

pb delete

删除 stanza 及其所有备份。

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

选项：

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

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

命令包含多重安全机制：

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

控制命令

pb check

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

BASH
pig pb check                         # 验证仓库

此命令检查：

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

pb start

启用 pgBackRest 操作。

BASH
pig pb start                         # 启用操作

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

pb stop

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

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

选项：

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

使用场景：

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

日志命令

pb log

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

BASH
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 的别名

子命令：

子命令别名说明
listls列出日志文件
showcat, c显示最新日志内容
tailt, f, follow实时跟踪最新日志

选项：

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

权限处理：

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

设计说明

命令执行方式：

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

执行逻辑：

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

与 pgbackrest 的关系：

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

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

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

默认配置路径：

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

安全考虑：

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

平台支持：

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

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 集群、执行故障切换，或验证集群成员状态。

BASH
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 管理的主数据目录。典型流程如下：

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

与 pig pb restore 的区别：

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

快速入门

BASH
# 最常用：恢复到 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-restartrestore 后不启动 PostgreSQL
--plan仅显示执行计划，不执行
--yes-y跳过交互式 y/yes 确认
--timeoutPostgreSQL 启动/恢复等待超时，默认 120 秒
--force-stopfast stop 失败时允许 immediate shutdown 与 kill fallback

配置参数

参数简写说明
--stanza-spgBackRest stanza 名称
--config-cpgBackRest 配置文件路径
--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 检查和安全提示。

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

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

BASH
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 参数可以写在 -- 之后：

BASH
pig pitr -d -- --delta

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

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

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

使用示例

场景一：误删数据恢复

BASH
# 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;

场景二：恢复到最新状态

BASH
pig pitr -d

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

BASH
pig pitr -I

场景四：恢复后保持停止

BASH
pig pitr -d --no-restart

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

场景五：自定义目录 side restore

BASH
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 会显示类似以下的计划：

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

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

恢复后操作

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

BASH
# 验证数据
pig pg psql

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

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

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

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

安全机制

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

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

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

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

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

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

设计说明

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

权限执行：

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

平台支持：

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