上手
下面是一个简单的上手教程，带您体验 PIG 包管理器的核心能力。
简短版本
curl -fsSL https://repo.pigsty.io/pig | bash # 从 Cloudflare 安装 PIG
pig repo set # 一次性设置好 Linux, Pigsty + PGDG 仓库（覆盖式！）
pig install -v 18 -y pg18 pg_duckdb vector # 安装 PG 18 内核，pg_duckdb, pgvector 扩展……安装
您可以使用以下命令 一键安装 pig：
中国大陆：
curl -fsSL https://repo.pigsty.cc/pig | bash全球网站（Cloudflare CDN）：
curl -fsSL https://repo.pigsty.io/pig | bashPIG 二进制包大约 5 MB，在 Linux 上会自动使用 rpm 或 dpkg 安装最新可用版本：
$ curl -fsSL https://repo.pigsty.cc/pig | bash
[INFO] kernel = Linux
[INFO] machine = x86_64
[INFO] package = deb
[INFO] pkg_url = https://repo.pigsty.cc/pkg/pig/v1.5.0/pig_1.5.0-1_amd64.deb
[INFO] download = /tmp/pig_1.5.0-1_amd64.deb
[INFO] downloading pig v1.5.0
curl -fSL https://repo.pigsty.cc/pkg/pig/v1.5.0/pig_1.5.0-1_amd64.deb -o /tmp/pig_1.5.0-1_amd64.deb
######################################################################## 100.0%
[INFO] md5sum = b7d18865090df8c03523c79ec2744e91
[INFO] installing: dpkg -i /tmp/pig_1.5.0-1_amd64.deb
(Reading database ... 166001 files and directories currently installed.)
Preparing to unpack /tmp/pig_1.5.0-1_amd64.deb ...
Unpacking pig (1.5.0-1) ...
Setting up pig (1.5.0-1) ...
[INFO] pig v1.5.0 installed successfully
check https://pgext.cloud for details检查环境
PIG 是一个由 Go 编写的二进制程序，默认安装路径为 /usr/bin/pig，pig version 会打印版本信息：
$ pig version
pig version 1.5.0 linux/amd64使用 pig status 命令，会打印当前环境的状态，操作系统代码，PG 的安装情况，仓库的可访问性与延迟。
$ pig status
# [Configuration] ================================
Pig Version : 1.5.0
Pig Config : /home/vagrant/.pig/config.yml
Log Level : info
Log Path : stderr
# [OS Environment] ===============================
OS Distro Code : u26
OS OSArch : arm64
OS Package Type : deb
OS Vendor ID : ubuntu
OS Version : 26
OS Version Full : 26.04
OS Version Code : resolute
# [PG Environment] ===============================
Installed:
* PostgreSQL 18.4 (Ubuntu 18.4-1.pgdg26.04+1) 72 Extensions
Active:
PG Version : PostgreSQL 18.4 (Ubuntu 18.4-1.pgdg26.04+1)
Config Path : /usr/lib/postgresql/18/bin/pg_config
Binary Path : /usr/lib/postgresql/18/bin
Library Path : /usr/lib/postgresql/18/lib
Extension Path : /usr/share/postgresql/18/extension
# [Pigsty Environment] ===========================
Inventory Path : Not Found
Pigsty Home : Not Found
# [Network Conditions] ===========================
pigsty.cc ping ok: 376 ms
pigsty.io ping ok: 1270 ms
Internet Access : true
Pigsty Repo : pigsty.io
Inferred Region : china
Latest Pigsty Ver : v4.4.0自动化建议
对于生产环境恢复任务，建议先使用 --plan 预览 PITR 执行计划，再决定是否实际执行：
pig pitr -d --plan # 仅预览恢复步骤，不执行
pig pitr -d -y # 跳过确认（自动化场景）列出扩展
使用 pig ext list 命令，可以打印内置的 PG 扩展数据目录。
$ pig ext list
✓ Found 531 extensions
Name Status Version Cate Flags License Repo PGVer Package Description
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
timescaledb available 2.28.2 TIME -dslt- Timescale PIGSTY 15-18 postgresql-18-timescaledb-tsl Enables scalable inserts and complex queries for time-series dat
timescaledb_toolkit available 1.23.0 TIME -ds--- Timescale PIGSTY 15-18 postgresql-18-timescaledb-toolkit Library of analytical hyperfunctions, time-series pipelining, an
timeseries available 0.2.1 TIME -d---- PostgreSQL PIGSTY 14-18 postgresql-18-pg-timeseries Convenience API for time series stack
periods available 1.2.3 TIME -ds--- PostgreSQL PGDG 14-18 postgresql-18-periods Provide Standard SQL functionality for PERIODs and SYSTEM VERSIO
........
pg_bulkload available 3.1.23 ETL bds--- BSD 3-Clause PIGSTY 14-18 postgresql-18-pg-bulkload pg_bulkload is a high speed data loading utility for PostgreSQL
test_decoding available - ETL --s--x PostgreSQL CONTRIB 14-18 postgresql-18 SQL-based test/example module for WAL logical decoding
pgoutput available - ETL --s--- PostgreSQL CONTRIB 14-18 postgresql-18 Logical Replication output plugin
(531 Rows)所有的扩展元数据都在一份名为 extension.csv 的数据文件中定义，
这份文件会随着 pig 版本发布不断更新，您可以直接使用 pig ext reload 命令更新这份数据文件。
更新后的文件会默认放置于 ~/.pig/extension.csv 中，您可以查阅与更改；在线最新版目录可在 pigsty.io/ext/data/extension.csv 获取。
添加仓库
要想安装扩展，首先需要添加上游仓库。pig repo 可用于管理 Linux APT/YUM/DNF 软件仓库配置。
您可以使用简单粗暴直接的版本 pig repo set 覆盖式写入现有仓库配置，该命令确保系统中只存在必须的仓库配置：
pig repo set # 一次性配置好所有仓库，包括 Linux 系统仓库，PGDG，PIGSTY (PGSQL+INFRA) 仓库警告：
pig repo set会备份并清理现有的仓库配置，然后添加所需的仓库，实现 Overwrite 语义，请务必注意！
或者选择使用温和的 pig repo add 添加所需的仓库：
pig repo add pgdg pigsty # 添加 PGDG 官方仓库 和 PIGSTY 补充仓库
pig repo add pgsql # 【可选】您也可以选择将 PGDG 和 PIGSTY 合在一起，当成一个 "pgsql" 模块整体添加
pig repo update # 更新缓存：apt update / yum makecachePIG 会检测您的网络环境，并选择使用 Cloudflare 全球 CDN，或者中国境内云 CDN，但您可以通过 --region 参数强制指定区域。
pig repo set --region=china # 使用中国区域镜像仓库加速下载
pig repo add pgdg --region=default --update # 强制指定使用 PGDG 上游仓库PIG 本身不支持离线安装，您可以自行下载 RPM/DEB 包，拷贝到网络隔离的生产服务器安装。 相关项目 PIGSTY 提供本地软件仓库，支持可以使用 pig 从本地软件仓库安装已经下载好的扩展。
安装 PG
添加仓库后，您可以使用 pig ext add 子命令安装扩展（以及相关软件包）
pig ext add -v 18 -y pgsql timescaledb postgis vector pg_duckdb pg_mooncake # 安装 PG 18 内核与扩展，自动确认
# 该命令会自动执行翻译，将软件包翻译为
INFO[20:34:44] translate alias 'pgsql' to package: postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl
INFO[20:34:44] translate extension 'timescaledb' to package: timescaledb-tsl_18
INFO[20:34:44] translate extension 'postgis' to package: postgis36_18
INFO[20:34:44] translate extension 'vector' to package: pgvector_18
INFO[20:34:44] translate extension 'pg_duckdb' to package: pg_duckdb_18
INFO[20:34:44] translate extension 'pg_mooncake' to package: pg_mooncake_18
INFO[20:34:44] installing packages: dnf install -y postgresql18 postgresql18-server postgresql18-libs postgresql18-contrib postgresql18-plperl postgresql18-plpython3 postgresql18-pltcl timescaledb-tsl_18 postgis36_18 pgvector_18 pg_duckdb_18 pg_mooncake_18这里使用了 “别名翻译” 机制，将清爽的 PG 内核/扩展 逻辑包名翻译为实际的 RPM/DEB 列表。如果您不需要别名翻译机制，可以直接使用 apt/dnf 安装，
或者使用变体 pig install 的 -n|--no-translation 参数：
pig install vector # 带有翻译机制，安装当前 PG 18 对应的 pgvector_18 或 postgresql-18-pgvector
pig install vector -n # 关闭翻译机制，安装名为 vector 的日志收集组件（来自 pigsty-infra 仓库）别名翻译
PostgreSQL 内核与扩展对应着一系列的 RPM/DEB 包，记住这些包是一件麻烦事，所以 pig 提供了许多常用的别名，帮助您简化安装过程：
例如在 EL 系统上， 下面的别名将会被翻译为右侧的对应 RPM 包列表：
pgsql: "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl"
pg18: "postgresql18 postgresql18-server postgresql18-libs postgresql18-contrib postgresql18-plperl postgresql18-plpython3 postgresql18-pltcl"
pg18-client: "postgresql18"
pg18-server: "postgresql18-server postgresql18-libs postgresql18-contrib"
pg18-devel: "postgresql18-devel"
pg18-basic: "pg_repack_18 wal2json_18 pgvector_18"
pg17-mini: "postgresql17 postgresql17-server postgresql17-libs postgresql17-contrib"
pg16-full: "postgresql16 postgresql16-server postgresql16-libs postgresql16-contrib postgresql16-plperl postgresql16-plpython3 postgresql16-pltcl postgresql16-llvmjit postgresql16-test postgresql16-devel"
pg15-main: "postgresql15 postgresql15-server postgresql15-libs postgresql15-contrib postgresql15-plperl postgresql15-plpython3 postgresql15-pltcl pg_repack_15 wal2json_15 pgvector_15"
pg14-core: "postgresql14 postgresql14-server postgresql14-libs postgresql14-contrib postgresql14-plperl postgresql14-plpython3 postgresql14-pltcl"注意这里的 $v 占位符会被替换为 PG 大版本号，因此当您使用 pgsql 别名时，$v 会被实际替代为 18，17 这样的大版本号。
因此，当您安装 pg18-server 别名时，EL 上实际安装的是 postgresql18-server, postgresql18-libs, postgresql18-contrib，在 Debian / Ubuntu 上安装的是 postgresql-18，pig 会处理好所有细节。
常用 PostgreSQL 别名
"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","pgsql": "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v",
"pgsql-mini": "postgresql-$v postgresql-client-$v",
"pgsql-core": "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v",
"pgsql-full": "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v postgresql-server-dev-$v",
"pgsql-main": "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v postgresql-$v-repack postgresql-$v-wal2json postgresql-$v-pgvector",
"pgsql-client": "postgresql-client-$v",
"pgsql-server": "postgresql-$v",
"pgsql-devel": "postgresql-server-dev-$v",
"pgsql-basic": "postgresql-$v-repack postgresql-$v-wal2json postgresql-$v-pgvector",上面这些别名可以直接使用，并通过参数实例化大版本号，也可以使用另一种带有大版本号的别名变体：即将 pgsql 替换为 pg18, pg17, pgxx 等具体大版本号。
当前活跃支持的 PostgreSQL 主版本范围为 14-18，例如对于 PostgreSQL 18，可以直接使用下面这些别名：
pgsql |
pg18 |
pg17 |
pg16 |
pg15 |
pg14 |
|---|---|---|---|---|---|
pgsql |
pg18 |
pg17 |
pg16 |
pg15 |
pg14 |
pgsql-mini |
pg18-mini |
pg17-mini |
pg16-mini |
pg15-mini |
pg14-mini |
pgsql-core |
pg18-core |
pg17-core |
pg16-core |
pg15-core |
pg14-core |
pgsql-full |
pg18-full |
pg17-full |
pg16-full |
pg15-full |
pg14-full |
pgsql-main |
pg18-main |
pg17-main |
pg16-main |
pg15-main |
pg14-main |
pgsql-client |
pg18-client |
pg17-client |
pg16-client |
pg15-client |
pg14-client |
pgsql-server |
pg18-server |
pg17-server |
pg16-server |
pg15-server |
pg14-server |
pgsql-devel |
pg18-devel |
pg17-devel |
pg16-devel |
pg15-devel |
pg14-devel |
pgsql-basic |
pg18-basic |
pg17-basic |
pg16-basic |
pg15-basic |
pg14-basic |
| {.full-width} |
安装扩展
pig 会检测当前系统环境中的 PostgreSQL 安装情况。如果检测到环境中（以 PATH 中的 pg_config 为准）有活跃的 PG 安装，那么 pig 会自动安装对应 PG 大版本所需的扩展，无需您显式指定 PG 大版本。
pig install pg_smtp_client # 更简单
pig install pg_smtp_client -v 18 # 显示指定大版本，更稳定可靠
pig install pg_smtp_client -p /usr/lib/postgresql/16/bin/pg_config # 另一种指定 PG 版本的方式
dnf install pg_smtp_client_18 # 最直接……，但并非所有扩展都这么简单……提示：如需将特定大版本的 PostgreSQL 内核二进制加入 PATH，可用 pig ext link 命令：
pig ext link pg18 # 创建 /usr/pgsql 软链接，并写入 /etc/profile.d/pgsql.sh
. /etc/profile.d/pgsql.sh # 立即生效，更新 PATH 环境变量如果你想要安装特定版本的软件，可以使用 name=ver 的语法：
pig ext add -v 18 pgvector=0.7.2 # install pgvector 0.7.2 for PG 18
pig ext add pg16=16.5 # install PostgreSQL 16 with a specific minor version警告：请注意，目前只有 PGDG YUM 仓库提供扩展历史版本，PIGSTY 仓库与 PGDG APT 仓库都只提供扩展的 最新版本。
显示扩展
pig ext status 命令可以用于显示当前安装的扩展。
$ pig ext status
✓ PostgreSQL 18: 72 extensions installed (3 shown)
PostgreSQL 18: PostgreSQL 18.4 (Ubuntu 18.4-1.pgdg26.04+1)
Binary: /usr/lib/postgresql/18/bin
Extension: /usr/share/postgresql/18/extension
Extension Stat: 3 Installed (PGDG 3, PIGSTY 0) + 69 CONTRIB = 72 Total
Name Version Cate Flags License Repo Package Description
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
pg_repack 1.5.3 ADMIN bds--- PostgreSQL PGDG postgresql-18-repack Reorganize tables in PostgreSQL databases with minimal locks
vector 0.8.4 RAG -ds--r PostgreSQL PGDG postgresql-18-pgvector vector data type and ivfflat and hnsw access methods
wal2json 2.6 ETL --s--x BSD 3-Clause PGDG postgresql-18-wal2json Changing data capture in JSON format如果您的当前系统路径中找不到 PostgreSQL（以 PATH 中的 pg_config 为准），建议显式通过 -v|-p 指定 PG 大版本号或 pg_config 路径，以避免版本探测歧义。
扫描扩展
pig ext scan 提供更底层的扩展扫描功能，将扫描指定 PostgreSQL 目录下的共享库，从而发现安装了哪些扩展：
$ pig ext scan
Installed:
- PostgreSQL 18.4 (Ubuntu 18.4-1.pgdg26.04+1) 72 Extensions
Active:
PG Version : PostgreSQL 18.4 (Ubuntu 18.4-1.pgdg26.04+1)
Config Path : /usr/lib/postgresql/18/bin/pg_config
Binary Path : /usr/lib/postgresql/18/bin
Library Path : /usr/lib/postgresql/18/lib
Extension Path : /usr/share/postgresql/18/extension
Name Version SharedLibs Description Meta
---- ------- ---------- ----------- ----
pg_repack 1.5.3 pg_repack.so Reorganize tables in PostgreSQL databases with minimal locks module_pathname=$libdir/pg_repack relocatable=false lib=pg_repack.so
vector 0.8.4 vector.so vector data type and ivfflat and hnsw access methods relocatable=true lib=vector.so
wal2json 2.6 wal2json.so Changing data capture in JSON format lib=wal2json.so
...容器实战
您可以创建一台全新的虚拟机，或者使用下面的 Docker 容器进行功能测试，创建一个 d13 目录，创建 Dockerfile：
FROM debian:13
USER root
WORKDIR /root/
CMD ["/bin/bash"]
RUN apt update && apt install -y ca-certificates curl && curl https://repo.pigsty.io/pig | bashdocker 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
Last updated on