PIG CLI
CMD Docs
CMD: build

CMD: build

The pig build command is a powerful tool that simplifies the entire workflow of building PostgreSQL extensions from source. It provides a complete build infrastructure setup, dependency management, and compilation environment for both standard and custom PostgreSQL extensions across different operating systems.

Subcommands

Command Description
spec Initialize building spec repo
repo Initialize required repos
tool Initialize build tools
rust Install Rust toolchain
pgrx Install and initialize pgrx (requires Rust)
proxy Initialize build proxy
get Download source code tarball
dep Install extension build dependencies
ext Build extension package
pkg Complete build pipeline: get, dep, ext

Overview 

Build Postgres Extension  Usage:  pig build [command]  Aliases:  build, b  Examples: pig build - Build Postgres Extension  Environment Setup:  pig build spec # init build spec and directory (~ext)  pig build repo # init build repo (=repo set -ru)  pig build tool [mini|full|...] # init build toolset  pig build rust [-y] # install Rust toolchain  pig build pgrx [-v <ver>] # install & init pgrx (0.16.1)  pig build proxy [id@host:port ] # init build proxy (optional)  Package Building:  pig build pkg [ext|pkg...] # complete pipeline: get + dep + ext  pig build get [ext|pkg...] # download extension source tarball  pig build dep [ext|pkg...] # install extension build dependencies  pig build ext [ext|pkg...] # build extension package  Quick Start:  pig build spec # setup build spec and directory  pig build pkg citus # build citus extension  Available Commands:  dep Install extension build dependencies  ext Build extension package  get Download source code tarball  pgrx Install and initialize pgrx (requires Rust)  pkg Complete build pipeline: get, dep, ext  proxy Initialize build proxy  repo Initialize required repos  rust Install Rust toolchain  spec Initialize building spec repo  tool Initialize build tools  Flags:  -h, --help help for build  Global Flags:  --debug enable debug mode  -H, --home string pigsty home path  -i, --inventory string config inventory path  --log-level string log level: debug, info, warn, error, fatal, panic (default "info")  --log-path string log file path, terminal by default

Quick Start

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

# Step 1: Initialize build specifications pig build spec  # Step 2: Build an extension (complete pipeline) pig build pkg citus  # The built package will be available in: # - EL: ~/rpmbuild/RPMS/ # - Debian: ~/

For a more controlled approach:

# Setup environment pig build spec # Initialize build specs pig build repo # Setup repositories pig build tool # Install build tools  # Build process pig build get citus # Download source pig build dep citus # Install dependencies pig build ext citus # Build package  # Or do all three steps at once pig build pkg citus # get + dep + ext

Build Infrastructure

Build Specifications

The build system uses specification files that define how each extension should be built. These specs include:

  • Source code location and version
  • Build dependencies
  • Compilation flags
  • PostgreSQL version compatibility
  • Platform-specific build instructions

Directory Structure 

~/ext/ # Default build spec directory ├── Makefile # Master build makefile ├── <extension>/ # Per-extension directory │ ├── Makefile # Extension-specific makefile │ ├── <extension>.spec # RPM spec file (EL) │ └── debian/ # Debian packaging files │ ├── control │ ├── rules │ └── ...

Build output locations:

  • EL Systems: ~/rpmbuild/RPMS/<arch>/
  • Debian Systems: ~/ (deb files)

Command Reference

build spec

Sets up the build specification repository and directory structure.

pig build spec # Initialize at default location ~/ext

What it does:

  1. Clones or updates the extension build spec repository
  2. Creates necessary directory structure
  3. Sets up makefiles and build scripts
  4. Prepares platform-specific packaging files

Repository Location:

  • Default: ~/ext/
  • Contains build specifications for 100+ extensions

Example:

# Initialize specs pig build spec  # Check available extensions ls ~/ext/  # View specific extension spec cat ~/ext/citus/Makefile

build repo

Initializes required package repositories for building extensions.

pig build repo # Equivalent to: pig repo set -ru

What it does:

  • Removes existing repositories
  • Adds all required repositories (pgdg, pigsty, node)
  • Updates package cache

This ensures you have access to all necessary packages and dependencies for building.

build tool

Installs the necessary development tools and compilers.

pig build tool # Install default toolset pig build tool mini # Minimal toolset pig build tool full # Complete toolset pig build tool rust # Add Rust development tools

Tool Packages:

Minimal (mini):

  • GCC/Clang compiler
  • Make and build essentials
  • PostgreSQL development headers
  • Basic libraries

Default:

  • All minimal tools
  • Additional compilers (g++, clang++)
  • Development libraries
  • Packaging tools (rpmbuild, dpkg-dev)

Full (full):

  • All default tools
  • Language-specific tools (Python, Perl, Ruby dev)
  • Advanced debugging tools
  • Performance analysis tools

Common packages installed:

# EL Systems gcc gcc-c++ make cmake postgresql17-devel rpm-build rpmdevtools git wget curl  # Debian Systems build-essential postgresql-server-dev-17 dpkg-dev debhelper git wget curl

build rust

Installs the Rust programming language toolchain, required for Rust-based extensions.

pig build rust # Install with confirmation pig build rust -y # Auto-confirm installation

What it installs:

  • Rust compiler (rustc)
  • Cargo package manager
  • Rust standard library
  • Development tools

Installation method:

  • Uses rustup installer
  • Installs to user home directory
  • Automatically configures PATH

Example:

# Install Rust pig build rust -y  # Verify installation rustc --version cargo --version

build pgrx

Installs and initializes PGRX (PostgreSQL extension framework for Rust).

pig build pgrx # Install latest stable (0.16.1) pig build pgrx -v 0.15.0 # Install specific version

Prerequisites:

  • Rust toolchain must be installed first
  • PostgreSQL development headers

What it does:

  1. Installs cargo-pgrx tool
  2. Initializes PGRX for installed PostgreSQL versions
  3. Sets up development environment

Example:

# Install Rust first pig build rust -y  # Install PGRX pig build pgrx  # Initialize for specific PG versions cargo pgrx init --pg17=/usr/pgsql-17/bin/pg_config

build proxy

Sets up proxy configuration for build environments with restricted internet access.

pig build proxy # Interactive setup pig build proxy user@host:8080 # Direct configuration pig build proxy http://proxy.company.com:3128

Configures proxy for:

  • System environment (HTTP_PROXY, HTTPS_PROXY)
  • Package managers (yum/dnf, apt)
  • Build tools (cargo, npm, pip)
  • Git configuration

Example:

# Setup corporate proxy pig build proxy proxy.corp.com:8080  # With authentication pig build proxy user:[email protected]:8080

build get

Downloads extension source code tarballs.

pig build get citus # Single extension pig build get citus pgvector # Multiple extensions pig build get all # All available extensions pig build get std # Standard extensions

Source locations:

  • Downloads to: ~/ext/<extension>/
  • Source types:
    • Release tarballs from GitHub
    • Official project downloads
    • Source repositories

Example:

# Download specific version pig build get citus  # Check downloaded source ls ~/ext/citus/*.tar.gz

build dep

Installs required dependencies for building extensions.

pig build dep citus # Single extension pig build dep citus pgvector # Multiple extensions pig build dep citus --pg 17,16 # For specific PG versions

Options:

  • --pg: Comma-separated PostgreSQL versions (e.g., ‘17,16’)

Dependency types:

  • Build tools (compilers, make)
  • Development libraries
  • PostgreSQL headers
  • Extension-specific requirements

Example:

# Install dependencies for Citus pig build dep citus  # For multiple PostgreSQL versions pig build dep citus --pg 17,16,15

build ext

Compiles the extension and creates installation packages.

pig build ext citus # Build single extension pig build ext citus pgvector # Build multiple pig build ext citus --pg 17 # For specific PG version pig build ext citus -s # With debug symbols (RPM only)

Options:

  • --pg: Target PostgreSQL versions
  • -s, --symbol: Include debug symbols

Build process:

  1. Extracts source code
  2. Configures build environment
  3. Compiles extension
  4. Creates platform package (RPM/DEB)
  5. Signs package (if configured)

Output locations:

  • EL: ~/rpmbuild/RPMS/<arch>/*.rpm
  • Debian: ~/*.deb

Example:

# Build Citus for PostgreSQL 17 pig build ext citus --pg 17  # Check built package ls ~/rpmbuild/RPMS/x86_64/citus*.rpm # EL ls ~/citus*.deb # Debian

build pkg

Executes the complete build pipeline: download, dependencies, and build.

pig build pkg citus # Build single extension pig build pkg citus pgvector # Build multiple pig build pkg citus --pg 17,16 # For multiple PG versions pig build pkg citus -s # With debug symbols

Equivalent to running:

pig build get <extension> pig build dep <extension> pig build ext <extension>

Options:

  • --pg: Target PostgreSQL versions
  • -s, --symbol: Include debug symbols

Example:

# Complete build pipeline pig build pkg citus --pg 17  # Build multiple extensions pig build pkg citus pg_partman timescaledb

Common Workflows

Workflow 1: Building Standard Extension 

# 1. Setup build environment (once) pig build spec pig build repo pig build tool  # 2. Build extension pig build pkg pg_partman  # 3. Install built package sudo rpm -ivh ~/rpmbuild/RPMS/x86_64/pg_partman*.rpm # EL sudo dpkg -i ~/pg_partman*.deb # Debian

Workflow 2: Building Rust Extension 

# 1. Setup Rust environment pig build spec pig build tool pig build rust -y pig build pgrx  # 2. Build Rust extension pig build pkg pgmq  # 3. Install sudo pig ext add pgmq

Workflow 3: Building Multiple Versions 

# Build extension 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

Workflow 4: Custom Extension Build 

# 1. Create custom spec mkdir ~/ext/myextension cd ~/ext/myextension  # 2. Create Makefile cat > Makefile << 'EOF' EXTENSION = myextension VERSION = 1.0.0 REPO_URL = https://github.com/myorg/myextension include ../Makefile EOF  # 3. Build pig build pkg myextension

Workflow 5: Debugging Build Issues 

# Build with debug output pig build pkg citus --debug  # Build with debug symbols pig build pkg citus -s  # Step-by-step debugging pig build get citus # Check source download pig build dep citus # Verify dependencies pig build ext citus --debug # Debug compilation

Workflow 6: Building for Distribution 

# 1. Build multiple extensions extensions="citus pg_partman timescaledb pgvector" for ext in $extensions; do  pig build pkg $ext --pg 16,17 done  # 2. Collect packages mkdir ~/packages cp ~/rpmbuild/RPMS/x86_64/*.rpm ~/packages/ # EL cp ~/*.deb ~/packages/ # Debian  # 3. Create repository pig repo create ~/packages  # 4. Distribute tar czf extensions.tar.gz ~/packages

Extension Build Specifications

Standard Extensions

Extensions with official build support:

  • Distributed: citus, pg_partman
  • Time-series: timescaledb, pg_cron
  • Analytics: pg_duckdb, parquet_fdw
  • Search: pgroonga, pg_bigm
  • Languages: plpython3, plperl, pltcl

Build Requirements

Different extensions have different requirements:

Simple C Extensions:

  • PostgreSQL development headers
  • C compiler (gcc/clang)
  • Make

Complex Extensions:

  • Additional libraries (e.g., GDAL for PostGIS)
  • Language runtimes (Python, Perl, etc.)
  • Special compilers (Rust, Go)

Rust Extensions (via PGRX):

  • Rust toolchain
  • PGRX framework
  • Cargo build system

Platform Differences

EL Systems (RHEL/Rocky/Alma):

  • Uses RPM spec files
  • Builds with rpmbuild
  • Outputs to ~/rpmbuild/RPMS/

Debian/Ubuntu Systems:

  • Uses debian/ directory structure
  • Builds with dpkg-buildpackage
  • Outputs to ~/

Troubleshooting

Build Tools Not Found 

# Install build tools pig build tool  # For specific compiler 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 pg17-devel  # Or specify pg_config path export PG_CONFIG=/usr/pgsql-17/bin/pg_config

Rust/PGRX Issues 

# Reinstall Rust curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh  # Update PGRX cargo install cargo-pgrx --force  # Reinitialize PGRX cargo pgrx init

Source Download Failures 

# Check network/proxy pig build proxy  # Download manually cd ~/ext/<extension> wget <source_url>  # Continue build pig build dep <extension> pig build ext <extension>

Build Failures 

# Check build logs tail -f ~/rpmbuild/BUILD/*/config.log # EL  # Common fixes: # 1. Update build tools pig build tool full  # 2. Clear build cache rm -rf ~/rpmbuild/BUILD/*  # 3. Try with different PG version pig build pkg <extension> --pg 16

Best Practices

  1. Setup Once, Build Many: Initialize the build environment once, then build multiple extensions

  2. Use pkg Command: For standard builds, use pig build pkg for the complete pipeline

  3. Check Compatibility: Verify extension supports your PostgreSQL version before building

  4. Keep Specs Updated: Regularly update build specs with pig build spec

  5. Test Builds: Test built packages in development before production deployment

  6. Document Custom Builds: Keep notes on custom build flags or modifications

  7. Use Version Control: Track custom build specs in version control

  8. Parallel Builds: Build independent extensions in parallel for efficiency

  9. Cache Dependencies: Keep commonly used dependencies installed to speed up builds

  10. Sign Packages: For distribution, sign packages with GPG for security

Advanced Topics

Custom Build Flags 

# Set custom CFLAGS export CFLAGS="-O3 -march=native" pig build ext <extension>  # PostgreSQL-specific flags export PG_CPPFLAGS="-DUSE_SPECIAL_FEATURE" pig build ext <extension>

Cross-Compilation 

# For different architecture export CC=aarch64-linux-gnu-gcc export ARCH=arm64 pig build ext <extension>

Debugging Symbols 

# Build with debug symbols pig build ext <extension> -s  # For debugging export CFLAGS="-g -O0" pig build ext <extension>

Custom PostgreSQL Builds 

# For custom PostgreSQL installation export PG_CONFIG=/opt/postgresql/bin/pg_config export PKG_CONFIG_PATH=/opt/postgresql/lib/pkgconfig pig build ext <extension>

Continuous Integration 

#!/bin/bash # CI build script set -e  # Setup pig build spec pig build tool  # Build matrix for pg_version in 15 16 17; do  for extension in citus pgvector timescaledb; do  pig build pkg $extension --pg $pg_version  done done  # Test installations for rpm in ~/rpmbuild/RPMS/x86_64/*.rpm; do  sudo rpm -Uvh --test $rpm done

Extension Build Matrix

Commonly Built Extensions

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 library
pgvector C Fast Simple None
plpython3 C Medium Medium Python dev
pgrx extensions Rust Slow Complex Rust, PGRX
Last updated on
CMD: styCMD: pg