CMD: build

How to setup building infrastructure with pig build subcommand?

The pig build command simplifies the full workflow for building PostgreSQL extensions from source. It provides build infrastructure setup, dependency management, and compilation environments for standard and custom PostgreSQL extensions across supported operating systems.

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

Command	Description	Notes
`build spec`	Initialize build specification directory
`build repo`	Initialize required repositories	Requires sudo or root
`build tool`	Initialize build tools	Requires sudo or root
`build rust`	Install Rust toolchain	Requires sudo or root
`build pgrx`	Install and initialize pgrx	Requires sudo or root
`build proxy`	Initialize build proxy
`build get`	Download source tarballs
`build dep`	Install extension build dependencies	Requires sudo or root
`build ext`	Build extension packages	Requires sudo or root
`build pkg`	Complete pipeline: get, dep, ext	Requires sudo or root

Quick Start

The fastest way to set up a build environment and build an extension:

# Step 1: initialize build specs
pig build spec

# Step 2: build an extension with the complete pipeline
pig build pkg citus

# Built packages will be placed under:
# - EL: ~/ext/pkg/ (also available via ~/rpmbuild/RPMS/)
# - Debian: ~/ext/pkg/ (also available via ~/debbuild/DEBS/)

For finer control:

# Environment setup
pig build spec                   # initialize build specs
pig build repo                   # configure repositories
pig build tool                   # install build tools

# Build steps
pig build get citus              # download source
pig build dep citus              # install dependencies
pig build ext citus              # build package

# Or run all three steps at once
pig build pkg citus              # get + dep + ext

Build Infrastructure

Directory Layout

~/ext/                           # real working directory
├── pkg/                         # built package output
├── src/                         # source tarball downloads
├── log/                         # build logs
└── tmp/                         # temporary files

~/rpmbuild/                      # EL build directory
├── RPMS -> ~/ext/pkg            # RPM output symlink
├── SOURCES -> ~/ext/src         # source symlink
├── SPECS/
├── BUILD/
├── BUILDROOT/
└── SRPMS/

~/debbuild/                      # Debian / Ubuntu build directory
├── DEBS -> ~/ext/pkg            # DEB output symlink
├── SOURCES -> ~/ext/src         # source symlink
├── SPECS/
└── BUILD/

Build output locations:

EL systems: ~/ext/pkg/, also accessible through ~/rpmbuild/RPMS/
Debian systems: ~/ext/pkg/, also accessible through ~/debbuild/DEBS/

build spec

Set up build specifications and directory layout.

pig build spec                   # initialize ~/ext at the default location
pig build spec -f                # force re-download of the build spec tarball
pig build spec -m                # prefer the pigsty.cc China mirror

What it does:

Downloads the RPM or DEB build specification tarball.
Creates ~/ext/{pkg,src,log,tmp} and the platform build directory.
Links RPMS/DEBS and SOURCES to ~/ext/pkg and ~/ext/src.
Syncs makefiles, specs, and Debian packaging files with incremental rsync.

Working directory: ~/ext/ stores sources, packages, logs, and temporary files. The platform packaging directory is ~/rpmbuild/ or ~/debbuild/.

build repo

Initialize package repositories required for building extensions.

pig build repo                   # equivalent to: pig repo set -ru
pig build repo -m                # use China mirrors (Tencent Cloud first for PGDG)
pig build repo -b                # include PostgreSQL beta repository

What it does: initializes build repositories with pig repo set -ru: remove old repositories, add required repositories, and refresh package caches.

Options:

-m|--mirror: prefer China mirrors (Tencent Cloud first for PGDG).
-b|--beta: include the PostgreSQL beta repository module, currently for PG19 beta builds.

build tool

Install development tools and compilers.

pig build tool                   # install default toolset
pig build tool mini              # minimal toolset
pig build tool full              # full toolset
pig build tool rust              # add Rust development tools
pig build tool -b                # include PostgreSQL beta build packages

Toolsets:

Minimal (mini): GCC/Clang compilers, Make, core build tools, PostgreSQL development headers, and basic libraries.
Default: minimal tools plus extra compilers, development libraries, and packaging tools such as rpmbuild and dpkg-dev.
Full (full): default tools plus language-specific development tools and advanced debugging or profiling utilities.

On EL systems, the default build toolset installs explicit PostgreSQL development/server packages for the stable active majors. Use --beta when you also need the current beta major.

build rust

Install the Rust toolchain required by Rust-based extensions.

pig build rust                   # install with confirmation
pig build rust -y                # force reinstall Rust toolchain
pig build rust -m                # use rsproxy.cn and Cargo mirror config

Installed components: Rust compiler (rustc), Cargo, Rust standard library, and development tools.

Options:

-y|--yes: force Rust reinstallation even if Cargo already exists.
-m|--mirror: download rustup from the China mirror and write ~/.cargo/config.toml for rsproxy.cn.

build pgrx

Install and initialize PGRX, the PostgreSQL extension framework for Rust.

pig build pgrx                   # install latest stable version (0.19.1)
pig build pgrx -v 0.19.1         # install a specific pgrx version
pig build pgrx --pg 18,17,16     # initialize pgrx for selected PG versions
pig build pgrx --pg init         # run cargo pgrx init without PG arguments
pig build pgrx -b                # include beta PostgreSQL pg_config in auto-detect

Prerequisites: Rust toolchain and PostgreSQL development headers must be installed first.

Options:

-v|--pgrx: cargo-pgrx version to install.
--pg: comma-separated PostgreSQL majors, init for no PostgreSQL arguments, or empty for auto-detection.
-b|--beta: include the current beta major during auto-detection.

build proxy

Configure a proxy for build environments with restricted internet access.

pig build proxy                  # interactive setup
pig build proxy user@host:8080   # use default local endpoint 127.0.0.1:12345
pig build proxy user@host:8080 127.0.0.1:1080

build get

Download extension source tarballs.

pig build get citus              # single extension
pig build get citus pgvector     # multiple extensions
pig build get pdu pgdog          # use built-in source aliases
pig build get citus -f           # re-download even if the file already exists
pig build get citus -m           # prefer the pigsty.cc China mirror

Arguments to pig build get are extension names, package names, or source filenames. Unknown names are treated as source filenames. It does not expand all or std into built-in package sets; list the target package names explicitly for batch downloads.

Some source packages do not map directly to extension names, so pig build get includes special aliases for direct source downloads.

pig build get pdu                # download pdu-3.0.25.12.tar.gz
pig build get pgdog              # download pgdog-0.1.32.tar.gz
pig build get pgedge-17          # download PostgreSQL 17 plus pgEdge suite sources
pig build get babelfish-18       # download Babelfish PG18 source bundle
pig build get orioledb-16        # download OrioleDB plus PG16 patch bundle
pig build get onesparse          # download onesparse, graphblas, and lagraph

Common special source aliases include: babelfish / babelfish-17 / babelfish-18, ivorysql, orioledb / orioledb-16 / orioledb-17 / orioledb-18, cloudberry / cloudberry-backup / cloudberry-pxf, pgedge / pgedge-15 / pgedge-16 / pgedge-17 / pgedge-18, polardb, polarstore, zlog, pdu, pgdog, rdkit, onesparse, libpgfeutils, and libfq.

build dep

Install dependencies required to build extensions.

pig build dep citus              # single extension
pig build dep citus pgvector     # multiple extensions
pig build dep citus --pg 17,16   # for selected PG versions

Options:

--pg: specify one or more PostgreSQL major versions. If omitted, pig infers versions from extension metadata or local PostgreSQL installations.

build ext

Compile extensions and create installation packages.

pig build ext citus              # build one extension
pig build ext citus pgvector     # build multiple extensions
pig build ext citus --pg 17      # build for a selected PG version
pig build ext citus -s           # include debug symbols (RPM only)

Options:

--pg: specify one or more PostgreSQL major versions.
-s|--symbol: build debug symbol packages (RPM only).

build pkg

Run the complete build pipeline: download, dependency installation, and build.

pig build pkg citus              # build one extension
pig build pkg citus pgvector     # build multiple extensions
pig build pkg citus --pg 17,16   # build for multiple PG versions
pig build pkg citus -s           # include debug symbols
pig build pkg citus -m           # prefer the pigsty.cc China mirror for sources
pig build pkg cloudberry         # build cloudberry, backup, and pxf in order

Options:

--pg: specify one or more PostgreSQL major versions.
-s|--symbol: build debug symbol packages (RPM only).
-m|--mirror: prefer the pigsty.cc mirror when downloading source files.

pig build pkg cloudberry is a suite workflow: it downloads the full Cloudberry source bundle, builds the core package first, installs the local artifact, then builds cloudberry-backup and cloudberry-pxf.

Common Workflows

Workflow 1: Build a Standard Extension

# 1. Set up the build environment once
pig build spec
pig build repo
pig build tool

# 2. Build the extension
pig build pkg pg_partman

# 3. Install the built package
sudo rpm -ivh ~/ext/pkg/pg_partman*.rpm  # EL
sudo dpkg -i ~/ext/pkg/*partman*.deb     # Debian

Workflow 2: Build a Rust Extension

# 1. Set up Rust environment
pig build spec
pig build tool
pig build rust                   # add -y only if you need to force reinstall
pig build pgrx

# 2. Build Rust extension
pig build pkg pgmq

# 3. Install
sudo pig ext add pgmq

Workflow 3: Build Multiple Versions

# Build for multiple PostgreSQL versions
pig build pkg citus --pg 15,16,17

# Results in packages for each version:
# citus_15-*.rpm
# citus_16-*.rpm
# citus_17-*.rpm

Troubleshooting

Build Tools Not Found

# Install build tools
pig build tool

# For specific compiler sets
sudo dnf groupinstall "Development Tools"  # EL
sudo apt install build-essential          # Debian

Missing Dependencies

# Install extension dependencies
pig build dep <extension>

# Check error messages for specific packages
# Install manually if needed
sudo dnf install <package>  # EL
sudo apt install <package>  # Debian

PostgreSQL Headers Not Found

# Install PostgreSQL development package
sudo pig ext install pg18-devel

# Or specify pg_config path
export PG_CONFIG=/usr/pgsql-18/bin/pg_config

Rust/PGRX Issues

# Reinstall Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Update PGRX
cargo install --locked cargo-pgrx@0.19.1

# Reinitialize PGRX
cargo pgrx init

Extension Build Matrix

Common Extensions to Build

Extension	Type	Build Time	Complexity	Special Requirements
pg_repack	C	Fast	Simple	None
pg_partman	SQL/PLPGSQL	Fast	Simple	None
citus	C	Medium	Medium	None
timescaledb	C	Slow	Complex	CMake
postgis	C	Very slow	Complex	GDAL, GEOS, Proj
pg_duckdb	C++	Medium	Medium	C++17 compiler
pgroonga	C	Medium	Medium	Groonga libraries
pgvector	C	Fast	Simple	None
plpython3	C	Medium	Medium	Python development
pgrx extensions	Rust	Slow	Complex	Rust, PGRX