跳转到主要内容

pig build

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

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

pig build - Build Postgres Extension

Environment Setup:
  pig build spec                   # init build spec and directory (~ext)
  pig build repo                   # init build repo (=repo set -ru)
  pig build 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.2)
  pig build proxy                  # install or verify the vray package
  pig build proxy id@host:port     # configure the optional build proxy

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 初始化构建代理 需要 sudo 或 root 权限
build get 下载源代码 tarball
build dep 安装扩展构建依赖 需要 sudo 或 root 权限
build ext 构建扩展包 需要 sudo 或 root 权限
build pkg 完整构建流程：get、dep、ext 需要 sudo 或 root 权限

快速入门

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

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

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

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

更精细的控制方式：

# 设置环境
pig build spec                   # 初始化构建规范
pig build repo                   # 设置仓库
pig build 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

构建基础设施

目录结构

PIG 构建目录

  • ~/ext/
    • pkg/
    • src/
    • log/
    • tmp/
  • ~/rpmbuild/
    • RPMS -> ~/ext/pkg
    • SOURCES -> ~/ext/src
    • SPECS/
    • BUILD/
    • BUILDROOT/
    • SRPMS/
  • ~/debbuild/
    • DEBS -> ~/ext/pkg
    • SOURCES -> ~/ext/src
    • SPECS/
    • BUILD/

~/ext/ 是真实工作目录：pkg 保存构建产物，src 保存源码压缩包，log / tmp 分别保存构建日志和临时文件；平台专用目录则把输出与源码位置链接回这里。

构建输出位置：

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

build spec

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

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

功能：

  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

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

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

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

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 的扩展所需。

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 扩展框架）。

pig build pgrx                   # 安装最新稳定版 (0.19.2)
pig build pgrx -v 0.19.2         # 安装特定版本
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

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

首次使用前，需要先配置一个提供 vray 的软件仓库，通常可运行 pig build repo（或使用等价的既有仓库配置）。 该命令通过 dnf、yum 或 apt-get 安装 vray，写入 /etc/v2ray.json 与 /etc/profile.d/proxy.sh，然后重启 v2ray 服务，因此需要 sudo 或 root 权限。 该软件包必须提供 v2ray 服务账户与 systemd unit。连通性检查失败时命令会返回非零退出状态。

远端用户 ID 应按凭据处理。PIG 会在诊断与结构化结果中遮盖它，但它仍作为命令参数传入， 可能被 shell 历史保留；调用方应遵循所在 shell 或自动化环境的凭据处理策略。

pig build proxy                  # 仅安装或确认 vray 软件包
pig build proxy user@host:8080   # 使用默认本地端口 127.0.0.1:12345
pig build proxy user@host:8080 127.0.0.1:1080

build get

下载扩展源代码 tarball。

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

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

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

pig build get pdu                # 下载 pdu-3.0.25.12.tar.gz
pig build get pgdog              # 下载 pgdog-0.1.32.tar.gz
pig build get pgedge             # 同时下载 PostgreSQL 与 spock 源码
pig build get onesparse          # 同时下载 onesparse、graphblas、lagraph

当前常见的特殊源码 alias 包括：babelfishpg / babelfish、agensgraph / agentsgraph、oriolepg / orioledb、cloudberry、pgedge、pdu、pgdog、rdkit、onesparse、libfepgutils。

build dep

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

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

选项：

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

build ext

编译扩展并创建安装包。

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

选项：

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

build pkg

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

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

选项：

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

常见工作流

工作流 1：构建标准扩展 

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

# 2. 构建扩展
pig build pkg pg_partman

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

工作流 2：构建 Rust 扩展 

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

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

# 3. 安装
sudo pig ext add pgmq

工作流 3：构建多个版本 

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

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

故障排除

找不到构建工具 

# 安装构建工具
pig build tool

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

缺少依赖 

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

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

找不到 PostgreSQL 头文件 

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

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

Rust/PGRX 问题 

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

# 更新 PGRX
cargo install --locked [email protected]

# 重新初始化 PGRX
cargo pgrx init

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

扩展构建矩阵

常见构建的扩展

扩展 类型 构建时间 复杂度 特殊要求
pg_repack C 快速 简单 无
pg_partman SQL/PLPGSQL 快速 简单 无
citus C 中等 中等 无
timescaledb C 慢 复杂 CMake
postgis C 非常慢 复杂 GDAL、GEOS、Proj
pg_duckdb C++ 中等 中等 C++17 编译器
pgroonga C 中等 中等 Groonga 库
pgvector C 快速 简单 无
plpython3 C 中等 中等 Python 开发
pgrx 扩展 Rust 慢 复杂 Rust、PGRX
最后修改 2026-09-03 · chore(ci): update docs toolchain (d9065c0)