Reference on PIG

pig

Mon, 01 Jan 0001 00:00:00 +0000

The pig CLI provides a comprehensive toolkit for managing PostgreSQL installations, extensions, repositories, and extension builds from source. Use pig help <command> to view command documentation.

pig repo: manage software repositories
pig ext: manage PostgreSQL extensions
pig build: build extensions from source
pig install: install packages with the native package manager and translate PostgreSQL aliases
pig sty: manage Pigsty installation and Grafana dashboards
pig inventory: inspect, edit, validate, and exchange the Pigsty inventory (new in v1.6.0)
pig do: run Pigsty administration playbook tasks
pig pe: access pg_exporter metrics and configuration
pig pg: manage local PostgreSQL servers
pig pt: run patronictl transparently with service and config helpers
pig pb: manage pgBackRest backup and restore
pig pitr: run the full PITR workflow
pig context: output an environment context snapshot for humans and agents
pig status / update / version: inspect environment status, upgrade pig, and print version information

Overview

pig - The Linux package manager for PostgreSQL

Usage:
  pig [command]

Examples:

  pig repo add -ru            # overwrite existing repo and update cache
  pig install pg18            # install PostgreSQL 18 PGDG packages
  pig install pg_duckdb       # install a specific PostgreSQL extension
  pig install pgactive -v 18  # install extension for a specific PG version

  visit https://pigsty.io/ext/ for details

PostgreSQL Extension Manager
  build       Build Postgres extensions
  ext         Manage PostgreSQL extensions (pgext)
  repo        Manage Linux software repo (apt/dnf)

Pigsty Management Commands
  context     Show environment context snapshot
  do          Run admin tasks
  inventory   Inspect, edit, validate, check, and exchange Pigsty Inventory
  patroni     Run patronictl with Pigsty service and config helpers (alias: pt)
  pg_exporter Manage pg_exporter and metrics (alias: pe)
  pgbackrest  Manage pgBackRest backup and restore (alias: pb)
  pitr        Point-in-time recovery using pgBackRest
  postgres    Manage local PostgreSQL server and databases (alias: pg)
  sty         Manage Pigsty installation and controller services

Additional Commands:
  completion  Generate shell completion scripts
  help        Help about any command
  install     Install packages using native package manager
  status      Show environment status
  update      Upgrade pig itself
  version     Show pig version info

Flags:
      --debug              enable debug mode
  -h, --help               help for pig
  -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
  -o, --output string      output format: text, yaml, json, json-pretty (default "text")

Use "pig [command] --help" for more information about a command.

pig repo

Manage APT/YUM repositories for PostgreSQL packages. See pig repo for details.

pig repo

Mon, 01 Jan 0001 00:00:00 +0000

The pig repo command is a comprehensive package repository manager. It can add, remove, create, and manage repositories on RPM systems (RHEL/CentOS/Rocky/Alma) and Debian systems (Debian/Ubuntu).

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              # prefer the bundled China-region mirrors
  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

Command	Description	Notes
`repo list`	Print available repositories and modules
`repo info`	Show repository details
`repo status`	Show current repository status
`repo add`	Add repositories	Requires sudo or root
`repo set`	Clear, overwrite, and update repositories	Requires sudo or root
`repo rm`	Remove repositories	Requires sudo or root
`repo update`	Update repository cache	Requires sudo or root
`repo create`	Create local YUM/APT repository	Requires sudo or root
`repo cache`	Create offline package from local repo	Requires sudo or root
`repo boot`	Bootstrap repository from offline package	Requires sudo or root
`repo reload`	Refresh repository catalog

Quick Start

# Method 1: replacement mode — use only when PIG should own the host's repo definitions
pig repo add all --remove --update    # remove old repos, add all required repos, update cache

# Method 1 variant: one step
pig repo set                          # = pig repo add all --remove --update

# Method 2: gentle mode - only add required repos and keep current repo configuration
pig repo add pgsql                    # add PGDG and Pigsty PGSQL repositories
pig repo add pigsty --region=china    # add Pigsty repositories with China region
pig repo add pgdg   --region=europe   # add PGDG repositories with Europe region
pig repo add infra  --region=default  # add INFRA repositories with default region
pig repo add all -m                   # explicitly select the bundled China-region mirrors

# If the commands above did not use -u|--update, run this as an extra step
pig repo update                       # update system package cache

Modules

In pig, APT/YUM repositories are organized as modules: groups of repositories serving a specific purpose.

pig ext

Mon, 01 Jan 0001 00:00:00 +0000

The pig ext command searches the extension catalog and manages PostgreSQL extension packages on a host. It can resolve names, inspect package availability, install/remove/update RPM or DEB packages, and handle PostgreSQL kernel packages. Database-local activation and migration are deliberately outside this command group’s scope.

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

Command	Description	Notes
`ext list`	Search extensions
`ext info`	Show extension details
`ext avail`	Show extension availability matrix
`ext status`	Show host-visible extension files/packages	Does not query every database
`ext scan`	Scan installed control/library files	Does not query every database
`ext add`	Install extensions	Requires sudo or root
`ext rm`	Remove extensions	Requires sudo or root
`ext update`	Update extensions	Requires sudo or root
`ext import`	Download extensions for offline use	Requires sudo or root
`ext link`	Link a PG version into PATH	Requires sudo or root
`ext reload`	Refresh extension catalog

Quick Start

Before installing PostgreSQL extensions, add the required repositories with pig repo add:

pig build

Mon, 01 Jan 0001 00:00:00 +0000

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

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	Requires sudo or root
`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:

pig sty

Mon, 01 Jan 0001 00:00:00 +0000

pig can also be used as a CLI tool for Pigsty, a batteries-included free PostgreSQL RDS solution. It brings HA, PITR, monitoring, infrastructure as code (IaC), and rich extension support to your PostgreSQL clusters.

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

Command	Description	Notes
`sty init`	Install Pigsty
`sty boot`	Bootstrap the Pigsty controller	Auto-elevates when needed
`sty conf`	Generate and validate Inventory	Native Go workflow
`sty deploy`	Run deployment playbook
`sty list`	List available Pigsty versions
`sty get`	Download Pigsty source tarball
`sty grafana`	Manage Grafana dashboards (alias `gf`)	New in v1.6.0

Since v1.8.0, pig sty boot and pig sty conf are native Go workflows. They no longer invoke Pigsty’s legacy bootstrap or configure shell scripts. Since v1.6.0, the former pig sty edit / validate / check commands moved to the root-level pig inventory command group, and the experimental pig sty dashboard was replaced by pig sty grafana.

pig do

Mon, 01 Jan 0001 00:00:00 +0000

pig do exposes common Pigsty administrative playbooks as explicit CLI operations. It uses the selected Pigsty home and Inventory, builds the corresponding playbook command, and returns the operation through PIG’s legacy structured-result adapter.

These commands change remote systems. Review the selected cluster, node, instance, and Inventory before execution. The command family does not provide a general --plan mode.

pig do pgsql-add  pg-test 10.10.10.12     # add one PostgreSQL instance
pig do pgsql-rm   pg-test 10.10.10.12     # remove one PostgreSQL instance
pig do pgsql-db   pg-meta app             # create or update a database
pig do pgsql-user pg-meta dbuser_app      # create or update a user
pig do node-pkg   pg-meta restic          # install a package on selected nodes
pig do redis-add  redis-meta              # initialize a Redis cluster

Command overview

Command	Purpose	Required arguments
`pgsql-add`	Add a PostgreSQL cluster or instances	cluster, optional IPs
`pgsql-rm`	Remove a PostgreSQL cluster or instances	cluster, optional IPs
`pgsql-db`	Create or update a database declaration	cluster, database
`pgsql-user`	Create or update a user declaration	cluster, user
`pgsql-ext`	Install extensions through Pigsty	cluster, optional extensions
`pgsql-hba`	Refresh PostgreSQL HBA rules	cluster
`pgsql-svc`	Refresh PostgreSQL service definitions	cluster
`pgmon-add` / `pgmon-rm`	Add or remove a remote monitoring target	cluster
`node-add` / `node-rm`	Add or remove selected nodes	one or more selectors
`node-repo`	Configure repository modules on selected nodes	optional selector and modules
`node-pkg`	Install or update packages on selected nodes	selector, optional packages
`repo-build`	Rebuild the Pigsty infrastructure repository	none
`redis-add` / `redis-rm`	Add or remove Redis clusters, nodes, or instances	selector, optional ports

Run pig do COMMAND --help for the aliases and exact examples of one operation.

pig inventory

Mon, 01 Jan 0001 00:00:00 +0000

The pig inventory command group (alias pig inv), introduced in v1.6.0, provides lossless inspection, editing, validation, and readiness checks for the Pigsty inventory (pigsty.yml), plus an experimental cmdb subtree that exchanges the inventory with the PostgreSQL CMDB.

The lossless engine preserves YAML comments, formatting, key order, anchors, and line endings byte-for-byte; edit re-parses the whole document before writing and writes atomically — invalid YAML can never reach disk.

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

Command	Alias	Description
`inv status`		Inspect the active inventory source (without executing)
`inv list`	`ls`	List inventory topology and value kinds (`--depth`)
`inv show`		Show verbatim inventory YAML (may contain secrets)
`inv edit`	`e`	Edit the inventory or one fragment in `$EDITOR`
`inv validate`	`v`	Validate one complete static Pigsty inventory
`inv check`	`ck`	Check inventory, controller, and target readiness
`inv diff`		Compare declarations of two inventories (value-free)
`inv cmdb`		Exchange with the PostgreSQL CMDB (experimental)

The inventory path comes from pig’s config resolution (the global -i/--inventory flag or the Pigsty home directory), and every command supports -o json|yaml structured output.

pig postgres

Mon, 01 Jan 0001 00:00:00 +0000

The pig pg command (alias pig postgres) manages local PostgreSQL servers and databases. It wraps local primitives such as pg_ctl, psql, and vacuumdb; use pig pt for Patroni cluster operations and pig pitr for orchestrated PITR.

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

Command Overview

Service Control (pg_ctl wrapper):

pig patroni

Mon, 01 Jan 0001 00:00:00 +0000

Since v1.6.0, the pig patroni command (alias pig pt) is a transparent launcher for the installed patronictl binary: pig only owns config-file selection and a few local helpers, while every other command and all of its arguments are forwarded unchanged to patronictl — with native flags, prompts, output, and exit codes. New patronictl features work without waiting for a pig release.

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.

The first non-option command token decides the dispatch:

pig pe

Mon, 01 Jan 0001 00:00:00 +0000

pig pe (aliases: pgexp, pgexporter) is a legacy convenience wrapper for a running pg_exporter. It reads the default metrics and statistics endpoints and can request a configuration reload. It is not a general or versioned pg_exporter client.

pig pe get                     # print pg_ metrics
pig pe list                    # list metric families from HELP lines
pig pe stat                    # print exporter statistics
pig pe reload                  # request configuration reload

Endpoint selection

The default endpoint is http://127.0.0.1:9630. Select another exporter with persistent options:

pig pgbackrest

Mon, 01 Jan 0001 00:00:00 +0000

The pig pgbackrest command (alias pig pb) manages pgBackRest backups and provides low-level restore primitives. It wraps common pgbackrest operations for a simplified backup management experience. All commands run as the database superuser (default postgres). For orchestrated point-in-time recovery on managed clusters, prefer pig pitr.

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

Command Overview

Information Query:

pig pitr

Mon, 01 Jan 0001 00:00:00 +0000

The pig pitr command performs point-in-time recovery through pgBackRest and conservatively handles the local PostgreSQL and Patroni lifecycle. Unlike the lower-level pig pb restore, pig pitr runs pre-restore checks, stops Patroni and PostgreSQL when needed, executes restore, then decides whether to start PostgreSQL based on the selected options.

Note: for a managed default data directory, pig pitr leaves Patroni stopped after recovery. Validate the restored result first, then manually restore Patroni management. This command does not automatically rejoin a Patroni cluster, perform failover, or validate cluster member state.