PGEXT.CLOUD – CMD Docs

CMD: 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 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: clean existing repositories, add all required repos, and update cache (recommended)
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 pgdg   --mirror          # use Tencent Cloud first for PGDG
pig repo add infra  --region=default  # add INFRA repositories with default region

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

Module	Description	Repository List
`all`	All core modules required to install PG	`node` + `infra` + `pgsql`
`pgsql`	PGDG + Pigsty PG extensions	`pigsty-pgsql` + `pgdg`
`pigsty`	Pigsty Infra + PGSQL repositories	pigsty-infra, pigsty-pgsql
`pgdg`	PGDG official repositories	pgdg-common, pgdg14-18
`node`	Linux system repositories	base, updates, extras, epel, baseos, appstream…
`infra`	Infrastructure component repositories	pigsty-infra, nginx, docker-ce
`docker`	Docker repository	docker-ce
`beta`	PostgreSQL 19 beta repositories	pgdg19-beta, pgdg-beta
`extra`	PGDG non-free and third-party extensions	pgdg-extras, timescaledb, citus
`groonga`	PGroonga repository	groonga
`mssql`	WiltonDB repository (deprecated)	babelfish
`percona`	Percona PG + PG_TDE	percona
`llvm`	LLVM toolchain repository	llvm
`kube`	Kubernetes repository	kubernetes
`grafana`	Grafana repository	grafana
`haproxy`	HAProxy repositories	haproxyd, haproxyu
`redis`	Redis repository	redis
`mongo`	MongoDB repository	mongo
`mysql`	MySQL repository	mysql
`click`	ClickHouse repository	clickhouse
`gitlab`	GitLab repository	gitlab-ce, gitlab-ee

Pig also includes APT/DNF repositories for other databases and systems such as redis, kubernetes, grafana, clickhouse, gitlab, haproxy, mongodb, and mysql.

In general, node (Linux system repositories) and pgsql (PGDG + Pigsty) are required for PostgreSQL installation. The infra repository is optional and contains tools, IvorySQL kernel packages, and similar components. The special all module adds all required repositories at once and is a suitable starting point for most users.

pig repo add all      # add node, pgsql, and infra repositories
pig repo add          # default to the all module when no argument is given
pig repo set          # set clears/backups existing definitions and overwrites with new repo definitions

Repository Definitions

The full repository definition bundled with Pigsty is in cli/repo/assets/repo.yml.

You can create ~/.pig/repo.yml to explicitly modify and override pig’s repository definitions. When editing repository definitions, you can add extra regional mirror URLs under baseurl, such as China or Europe mirrors. When --region is specified, pig first looks for the matching regional URL and falls back to the default URL if the region is unavailable.

Since v1.7.0, --mirror on repo add or repo set explicitly selects the bundled china definitions. PGDG uses Tencent Cloud first and retains any declared Pigsty fallback; other modules use their maintained China-region URLs. Pig no longer rewrites PGDG URLs through a separate runtime proxy route.

Ordinary EL repositories keep native DNF module filtering. Only definitions that explicitly declare module_hotfixes=1—notably Pigsty and PGDG repositories—override module streams, and the key is removed when rendering EL7 YUM configuration.

repo list

pig repo list lists all repository modules available on the current system.

pig repo list                # list repositories available on current system
pig repo list all            # list all repositories without filtering

repo info

Show detailed information for specific repositories or modules, including URLs, metadata, regional mirrors, and .repo / .list repository file content.

pig repo info pgdg               # show pgdg module information
pig repo info pigsty pgdg        # show multiple modules
pig repo info all                # show all modules

repo status

Show current repository configuration on the system.

pig repo status

repo add

Add repository configuration files to the system. Requires root/sudo privileges.

pig repo add pgdg                # add PGDG repository
pig repo add pgdg pigsty         # add multiple repositories
pig repo add all                 # add all required repositories (pgdg + pigsty + node)
pig repo add pigsty -u           # add and update cache
pig repo add all -r              # remove existing repos before adding
pig repo add all -ru             # remove, add, and update (full reset)
pig repo add pgdg --region=china # use China mirror
pig repo add pgdg -m             # select China definitions; Tencent first for PGDG

Options:

-r|--remove: remove existing repositories before adding new ones
-u|--update: run package cache update after adding repositories
--region <region>: use regional mirror repositories (default / china / europe)
-m|--mirror: explicitly select the bundled china definitions

Platform	Module Location
EL	`/etc/yum.repos.d/<module>.repo`
Debian	`/etc/apt/sources.list.d/<module>.list`

repo set

Equivalent to repo add --remove --update. It clears existing repositories, sets up new ones, then updates cache.

pig repo set                     # replace with default repositories
pig repo set pgdg pigsty         # replace with selected repositories and update
pig repo set all --region=china  # use China mirror
pig repo set -m                  # explicitly select the bundled China definitions

repo rm

Remove repository configuration files and back them up.

pig repo rm                      # remove all repositories
pig repo rm pgdg                 # remove selected repository
pig repo rm pgdg pigsty -u       # remove and update cache

Platform	Backup Location
EL	`/etc/yum.repos.d/backup/`
Debian	`/etc/apt/sources.list.d/backup/`

repo update

Update package-manager cache to reflect repository changes.

pig repo update                  # update package cache

Platform	Equivalent Command
EL	`dnf makecache`
Debian	`apt update`

repo create

Create a local package repository for offline installation.

pig repo create                  # Linux: /www/pigsty; macOS: current directory
pig repo create /srv/repo        # create at custom location

The current implementation prefers sow when it is available in PATH. On Linux, the SOW backend runs the equivalent of the following with sudo for every target directory:

sow create --pigsty --timeout 10m -- /absolute/repository/path

On macOS, SOW is required, runs without sudo, and the default target is the current directory. On Linux, if sow is not installed, EL falls back to createrepo_c and Debian/Ubuntu falls back to dpkg-scanpackages from dpkg-dev. If neither the preferred backend nor the platform fallback is available, pig repo create fails. A SOW execution error is returned directly rather than retried through the legacy backend. The 10m timeout limits the wait for SOW’s directory lock; it does not cap repository indexing time.

SOW’s --pigsty transaction:

Scans only top-level regular .rpm and .deb files—no recursion and no symlink following.
Removes parsed 32-bit x86 packages (RPM i386/i486/i586/i686, DEB i386) and packages whose binary name is exactly patroni with upstream version exactly 3.0.4.
Builds the applicable RPM/DEB metadata atomically and writes repo_complete last. The marker contains SHA-256 hashes for remaining top-level packages, sorted by basename.

Non-package files and directories are left untouched; malformed package candidates or conflicting package coordinates make the SOW transaction fail closed. The legacy fallback has different cleanup and metadata semantics and writes an MD5 package list to repo_complete. After either backend exits, PIG requires repo_complete to exist as a regular file, but it does not validate the marker contents or hashes. Consumers that use the marker as a delivery gate should perform that verification themselves.

repo cache

Create a compressed tarball of repository contents for offline distribution.

pig repo cache                   # default: /www to /tmp/pkg.tgz
pig repo cache -d /srv           # custom source directory

Options:

-d, --dir: source directory, default /www/
-p, --path: output path, default /tmp/pkg.tgz

repo boot

Extract and set up a local repository from an offline package.

pig repo boot                    # default: /tmp/pkg.tgz to /www
pig repo boot -p /mnt/pkg.tgz    # custom package path
pig repo boot -d /srv            # custom target directory

Options:

-p, --path: package path, default /tmp/pkg.tgz
-d, --dir: target directory, default /www/

repo reload

Refresh repository metadata from GitHub to the latest version.

pig repo reload                  # refresh repository catalog

The updated file is placed in ~/.pig/repo.yml.

CMD: ext

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

The pig ext command is an all-in-one tool for managing PostgreSQL extensions. It lets you search, install, remove, update, and manage PostgreSQL extensions, and it can also handle PostgreSQL kernel packages.

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 installed extensions
`ext scan`	Scan installed extensions
`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 repo add pgdg pigsty -u    # gentle way to add pgdg and pigsty repos
pig repo set                   # brute-force way to remove and add all required repos

Then search and install PostgreSQL extensions:

pig ext install pg_duckdb
pig ext install pg_partman
pig ext install pg_cron
pig ext install pg_repack
pig ext install pg_stat_statements
pig ext install pg_stat_kcache

See the extension list for available extensions and package names.

Notes:

If no PostgreSQL version is specified, pig tries to detect the active PostgreSQL installation from pg_config in PATH.
PostgreSQL can be selected by major version (-v) or by pg_config path (-p).
- With -v, pig uses the default PGDG kernel package path for that major version.
  - EL distros: /usr/pgsql-$v/bin/pg_config
  - DEB distros: /usr/lib/postgresql/$v/bin/pg_config
- With -p, pig locates PostgreSQL directly from that path.
The extension manager automatically adapts to the OS package format:
- RPM packages for RHEL/CentOS/Rocky Linux/AlmaLinux
- DEB packages for Debian/Ubuntu
Extension dependencies are resolved automatically when possible.
Use -y carefully because it auto-confirms prompts.

Pigsty assumes official PGDG kernel packages are installed. If not, install them with:

pig ext install pg18          # install PostgreSQL 18 kernel packages except devel

ext list

List or search extensions in the extension catalog.

pig ext list                     # list all extensions
pig ext list duck                # search extensions containing "duck"
pig ext list -v 18               # filter by PG version
pig ext ls olap                  # list OLAP category extensions
pig ext ls gis -v 16             # list GIS extensions for PG 16
pig ext ls rag                   # list RAG category extensions

Category filtering is done by passing the category name as the query. Supported categories include: time, gis, rag, fts, olap, feat, lang, type, func, util, admin, stat, sec, fdw, sim, and etl.

Options:

-v|--version: filter by PG version
--pkg: show package names instead of extension names, listing only leading extensions

Status column:

installed: extension is installed
available: extension is available but not installed
not avail: extension is not available on the current system

The default extension catalog is defined in cli/ext/assets/extension.csv.

Use pig ext reload to refresh to the latest catalog. The downloaded catalog is stored at ~/.pig/extension.csv; the latest online catalog is also published at pigsty.io/ext/data/extension.csv.

ext info

Show detailed information for selected extensions.

pig ext info postgis        # show PostGIS details
pig ext info timescaledb    # show TimescaleDB details
pig ext info vector postgis # show multiple extensions

ext avail

Show the extension availability matrix across operating systems, architectures, and PostgreSQL versions.

pig ext avail                     # show package availability on current system
pig ext avail timescaledb         # show timescaledb availability matrix
pig ext avail postgis pg_duckdb   # show multiple extensions
pig ext av pgvector               # show pgvector availability
pig ext matrix citus              # alias for avail

The matrix shows availability across operating systems (EL8/9/10, Debian 12/13, Ubuntu 22/24/26), architectures (x86_64/aarch64), and PostgreSQL versions (14-18).

ext status

Show installed extension status for the current PostgreSQL instance.

pig ext status              # show installed extensions
pig ext status -c           # include contrib extensions
pig ext status -v 16        # show installed extensions for PG 16

Options:

-c|--contrib: include contrib extensions in the result

ext scan

Scan installed extensions for the current PostgreSQL instance.

pig ext scan [-v version]

This command scans the PostgreSQL extension directory and finds extensions that are actually installed.

ext add

Install one or more PostgreSQL extensions. Same-level aliases for pig ext add include pig ext install, pig ext ins, and pig ext a. The top-level pig install command is a separate native package-manager wrapper that also supports PostgreSQL and extension alias translation.

pig ext add pg_duckdb            # install pg_duckdb
pig ext add pg_duckdb -v 18      # install for PG 18
pig ext add pg_duckdb -y         # auto-confirm installation
pig ext add vector postgis       # install multiple extensions
pig ext add postgis --plan       # preview install plan without executing

# Using alias
pig install pg_duckdb
pig install pg_duckdb -v 18 -y

# Install PostgreSQL kernel packages
pig ext install pgsql            # install latest PostgreSQL kernel
pig ext a pg18                   # install PostgreSQL 18 kernel packages
pig ext ins pg16                 # install PostgreSQL 16 kernel packages
pig ext install pg15-core        # install PostgreSQL 15 core packages
pig ext install pg14-main -y     # install PG 14 + common extensions (vector, repack, wal2json)

Options:

-v|--version: specify PG major version
-y|--yes: auto-confirm installation
--plan: preview the install plan without running package-manager commands

ext rm

Remove one or more PostgreSQL extensions.

pig ext rm pg_duckdb             # remove pg_duckdb
pig ext rm pg_duckdb -v 18       # remove PG 18 package
pig ext rm pgvector -y           # auto-confirm removal
pig ext rm pgvector --plan       # preview remove plan without executing

Options:

-v|--version: specify PG major version
-y|--yes: auto-confirm removal
--plan: preview the remove plan without running package-manager commands

ext update

Update explicitly selected installed extensions to the latest version. For safety, pig ext update with no arguments is a no-op; you must name the targets explicitly.

pig ext update                   # no-op: explicit targets are required
pig ext update pg_duckdb         # update one extension
pig ext update postgis timescaledb  # update multiple extensions
pig ext update pg_duckdb -y      # auto-confirm update
pig ext update pg_duckdb -m      # refresh catalog from mirror first

Options:

-v|--version: specify PG major version
-y|--yes: auto-confirm update
-m|--mirror: reload the extension catalog from the pigsty.cc mirror before updating

ext import

Download extension packages into a local repository for offline installation.

pig ext import postgis                # import PostGIS packages
pig ext import timescaledb pg_cron    # import multiple extension packages
pig ext import pg16                   # import PostgreSQL 16 packages
pig ext import pgsql-common           # import common utility packages
pig ext import -d /www/pigsty postgis # import to a selected path

Options:

-d|--repo: local repository directory (default: /www/pigsty)

ext link

Link a selected PG version into the system PATH.

pig ext link 18                  # link PG 18 to PATH
pig ext link 16                  # link PG 16 to /usr/pgsql
pig ext link /usr/pgsql-16       # link from a selected path to /usr/pgsql
pig ext link polar               # link PolarDB 17 from /usr/polar-17
pig ext link null                # remove current PostgreSQL link
pig ext link none                # null / none / nil / nop / no all remove the link

This command creates the /usr/pgsql symlink and writes /etc/profile.d/pgsql.sh.

ext reload

Refresh extension metadata.

pig ext reload                   # refresh extension catalog

The updated catalog is stored at ~/.pig/extension.csv.

CMD: 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 formerpig sty edit / validate / check commands moved to the root-level pig inventory command group, and the experimentalpig sty dashboard was replaced by pig sty grafana.

Quick Start

Use pig sty to bootstrap and deploy Pigsty on the current node.

pig sty boot                     # prepare the controller; auto-elevates when needed
pig sty conf -g                  # generate and validate pigsty.yml
pig inventory edit              # optional: review and adjust the Inventory
pig sty deploy                   # run deployment playbook

See the detailed setup guide: https://pigsty.io/docs/setup/install/

sty boot initializes a missing default ~/pigsty tree on a best-effort basis. Usepig sty init first when you need to select an explicit Pigsty version or installation path.

sty init

Download and install the Pigsty distribution into ~/pigsty.

pig sty init                   # install latest version to ~/pigsty
pig sty init -f                # install and overwrite existing pigsty directory
pig sty init -m                # prefer the pigsty.cc mirror for downloads
pig sty init -p /tmp/pigsty    # install to selected directory /tmp/pigsty
pig sty init -v 3.4            # fetch and install selected version v3.4.1
pig sty init 3                 # fetch and install latest v3 major version

Options:

-p|--path: target installation directory, default ~/pigsty
-f|--force: force overwrite of existing pigsty directory
-m|--mirror: prefer the pigsty.cc mirror
-v|--version: Pigsty version
-d|--dir: download directory, default /tmp

sty boot

Bootstrap the Pigsty controller with the native Go workflow. The command prepares a usable Ansible environment, supports online and offline repositories, repairs common controller prerequisites, and reports a structured result. It never delegates to Pigsty’s legacybootstrap script and does not require curl, wget, tar, or gzip for package download and extraction.

sudo pig sty boot                         # online bootstrap with the default region
sudo pig sty boot -r china                # use China-region repositories
sudo pig sty boot -m                      # equivalent to --region china
sudo pig sty boot -k                      # preserve existing repository definitions
sudo pig sty boot -p /path/to/pkg.tgz     # use an explicit offline package
sudo pig sty boot -p https://host/pkg.tgz # download and use an offline package
sudo pig sty boot -o json                 # machine-readable result and warnings

You may invoke the command without sudo. Pig resolves and downloads an explicit source first, then re-executes itself through sudo once when root access is required. Set PIG_NO_SUDO=1 to disable automatic elevation, or PIG_NON_INTERACTIVE=1 to make the sudo attempt non-interactive.

Bootstrap stages

The native workflow performs these stages:

On Debian 12/13, check and repair en_US.UTF-8 when possible so Ansible can start.
Execute ansible-playbook, discover its Python interpreter, and verify yaml, jmespath, and either cryptography or OpenSSL. A binary that cannot actually run is not considered ready.
Resolve the repository source, prepare offline content when selected, and install the lean controller package set only when Ansible is missing or unusable.
Verify Ansible again after package installation and retry locale preparation when packages may have made locale tools available.
Probe controller helpers, repair key-based SSH to 127.0.0.1 for the invoking admin user, and initialize a missing default ~/pigsty tree when possible.

Explicit, automatically discovered, and already committed offline sources are prepared even when Ansible is already usable. This makes sty boot suitable for staging an offline repository on an otherwise ready controller.

Source selection and modes

The result records one of four bootstrap modes:

Mode	Meaning
`ready`	Ansible was already usable and no offline source needed preparation.
`offline`	An explicit, trusted automatic, or committed offline repository was selected.
`online`	Regional online repositories were configured to repair the controller.
`existing`	An online refresh failed under `--keep`, and existing repository definitions were successfully used as a fallback.

Source precedence and safety rules are deterministic:

--path accepts a local archive or an HTTP(S) URL. URL credentials are rejected, and a bad explicit source is a hard error rather than an online fallback.
An automatically discovered /tmp/pkg.tgz must be a regular, non-group/world-writable file owned by root or the invoking sudo user. Unsafe candidates are ignored with a warning.
A completed /www/pigsty repository takes precedence over a selected package. If both exist, the committed repository is reused and the package is left untouched with a warning.
Archives are downloaded and extracted by Pig itself. If /www does not exist, Pig creates/data/nginx and the expected /www -> /data/nginx symbolic link before committing content.

Offline mode enables only the strict pigsty-local repository. Online mode configures the selected region, installs Pigsty’s embedded signing key with repository signature checks enabled, and installs the node and pigsty controller modules.

Repository transaction and failure boundary

By default, repository definitions are backed up before replacement. If repository setup or package installation fails, Pig attempts to restore the backup and reports whether rollback succeeded or failed. --keep changes the policy to additive operation: existing definitions are preserved, online refresh may fall back to them, and no replacement rollback is required.

Invalid explicit sources, unsupported package management when installation is required, repository/package failures, and an unusable post-install Ansible runtime are command failures. Locale repair, optional helper probes, localhost SSH repair, and Pigsty tree initialization are advisory finishing steps; their failures are retained as warnings in an otherwise usable result.

Options:

-r|--region: region, such as default, china, europe
-m|--mirror: equivalent to --region china; mutually exclusive with --region
-p|--path: offline package file or HTTP(S) URL; an invalid explicit source is a hard error
-k|--keep: preserve existing repositories instead of replacing them

Structured output

Use the global -o json or -o yaml flag for automation. The payload kind ispig.sty.boot/v2 and includes the Ansible state, selected mode and package manager, repository policy and rollback result, source and repository paths, locale, localhost SSH and Pigsty tree initialization status, whether the machine changed, warnings, and these recommended next steps:

pig sty conf -g
pig inv edit
pig sty deploy

Dynamic progress is suppressed in structured mode, so stdout remains machine-readable.

See: https://pigsty.io/docs/setup/offline/#bootstrap

sty conf

Generate Pigsty Inventory through the native Go workflow. sty conf reads one template below<PIGSTY_HOME>/conf, applies bounded structural mutations, validates the complete candidate, and atomically writes an owner-only Inventory. It does not invoke or fall back to ./configure.

pig sty conf                         # use conf/meta.yml and write pigsty.yml
pig sty conf -g                      # generate random passwords (recommended)
pig sty conf rich                    # positional mode selects conf/rich.yml
pig sty conf -c ha/full              # equivalent flag form; do not combine both forms
pig sty conf ha/trio --ip 10.0.0.10,10.0.0.11,10.0.0.12
pig sty conf --domain infra.example.com
pig sty conf rich -v 18              # request PostgreSQL 18 for a generic template
pig sty conf -r china -s             # China region, placeholder IP, no admin preflight
pig sty conf -x                       # materialize proxy environment variables
pig sty conf full -g -O ha.yml       # custom owner-only output file
pig sty conf -n --ip 10.0.0.10 -o json

The default mode is meta; pig sty c and pig sty configure are command aliases. Note that-O selects the Inventory output file, while the global lowercase -o selects text, JSON, or YAML command output.

Template and output safety

A mode is a slash-separated relative name below <PIGSTY_HOME>/conf; .yml is optional. Absolute paths, traversal, empty segments, and path escape are rejected.
Relative output paths are resolved below <PIGSTY_HOME>; absolute output paths are retained.
The destination cannot alias the source through the same path, an existing symlink, a symlinked parent, or a hard link. An existing output symlink is always refused.
Pig parses the source and rejects conflicting IP mappings before running external preflight checks. A parse, mutation, preflight, or validation failure leaves the destination unchanged.
A successful result is written atomically with mode 0600.

Structural mutations

The command edits parsed YAML structures and bounded scalar tokens rather than applying broad text substitutions:

Input	Native behavior
`--ip A,B,...`	Maps up to ten distinct addresses, in order, to `10.10.10.10` through `10.10.10.19`. Replacement is simultaneous, so swaps are safe and unrelated VIPs remain intact.
no `--ip`	Detects local interfaces. Interactive mode asks when selection is ambiguous; `--non-interactive` or closed stdin fails with guidance to pass `--ip`.
`--domain NAME`	Replaces only the exact `i.pigsty` token, not names such as `cli.pigsty` or `i.pigsty.cc`; NAME must be a valid DNS domain.
small controller	When detected CPU count is below four, rewrites `node_tune: oltp` and `pg_conf: oltp.yml` to their `tiny` profiles.
`--region REGION`	Updates `all.vars.region` for non-default regions. `china` also activates template-provided Docker and pip mirrors, but never invents values absent from the template.
`--proxy`	Writes non-empty `HTTP_PROXY`/`http_proxy`, `HTTPS_PROXY` (falling back to `ALL_PROXY`), `ALL_PROXY`, and `NO_PROXY` values into `all.vars.proxy_env`; a safe default no-proxy list is used when needed.
`--version MAJOR`	Updates generic templates for PostgreSQL 14-18, or explicit 19 beta, and selects the matching locale. Version-pinned `mssql`, `polar`, and `pgNN` modes keep their template version and report a warning.
`--generate`	Generates one 24-character value per known credential identifier and consistently replaces its active values and documented placeholders.

An IP mapping that would collide with an unreplaced Inventory key is rejected as an invalid argument. A supplied address with no matching placeholder slot is retained in structured output as a discarded-IP warning rather than being silently ignored.

For PostgreSQL 19 beta, Pig also enables the beta repository after pgsql when the template contains the expected repository list. Modes below conf/build/ intentionally bypass IP mapping and controller-admin preflight so build templates remain portable.

Active password identifiers are grafana_admin_password, pg_admin_password,pg_monitor_password, pg_replication_password, patroni_password,haproxy_admin_password, minio_secret_key, and etcd_root_password. Generation also covers the documented DBUser.Meta, DBUser.Viewer, S3User.Backup, S3User.Meta, S3User.Data,DBUser.Supa, and Vibe.Coding placeholders. Repeated occurrences of one identifier receive the same generated value.

Options:

-c|--conf: template mode, equivalent to positional [mode]; the two forms are exclusive
--ip: up to ten distinct comma-separated IPv4 addresses
--domain: replace the exact i.pigsty placeholder with a valid DNS domain
-v|--version: PostgreSQL major version, 18/17/16/15/14; 19 beta can be specified explicitly
-r|--region: upstream repository region, such as default/china/europe
-m|--mirror: equivalent to --region china; mutually exclusive with --region
-O|--output-file: output config file path, default pigsty.yml
-s|--skip: keep the placeholder IP and skip admin SSH/sudo preflight; exclusive with --ip
-p|--port: SSH port
-x|--proxy: write non-empty proxy environment variables into all.vars.proxy_env
-n|--non-interactive: refuse ambiguous IP selection instead of prompting
-g|--generate: replace known demo credentials with random 24-character values

Preflight and validation

Unless --skip is used, Pig inspects the kernel, architecture, package manager, platform vendor, controller resources, sudo/admin access, localhost SSH, and Ansible availability. --port is used for the SSH check. These diagnostics are returned as actionable warnings where the Inventory can still be generated; invalid arguments and unsafe configuration transformations remain errors.

The rendered candidate must pass Pig’s native Inventory validation. When ansible-inventory is available, Pig also runs a bounded external parse before committing the file. --skip preserves placeholder IPs and bypasses admin SSH/sudo preflight, but it does not disable template parsing, safe mutation, Inventory validation, or atomic writing.

Structured output

With global -o json or -o yaml, the payload kind is pig.sty.configure/v1. It reports the mode, source and output paths, region, chosen primary address, applied and discarded IPs, domain, SSH port, requested and effective PostgreSQL versions, native-workflow marker, generated secret identifiers, and warnings. Secret values are never printed.

See: https://pigsty.io/docs/setup/install/#configure

sty deploy

Deploy Pigsty with the deploy.yml playbook.

pig sty deploy       # run deploy.yml, falling back to install.yml if not found
pig sty d            # short alias
pig sty de           # short alias

This command runs the deploy.yml playbook from your Pigsty installation directory. For backward compatibility, if deploy.yml does not exist but install.yml exists, install.yml is used instead.

Warning: This operation modifies your system, and invocation is explicit consent — deploy starts immediately without a --yes gate; use Ctrl+C to interrupt a mistaken run. (The pig sty install / ins aliases were removed in v1.6.0.)

sty list

List available Pigsty versions.

pig sty list                     # list available versions

sty get

Download the Pigsty source tarball.

pig sty get                      # download latest version
pig sty get v3.4.0               # download selected version
pig sty get -m                   # prefer the pigsty.cc mirror

sty grafana

Since v1.6.0, pig sty grafana (alias gf) manages Grafana dashboards through the native HTTP API, replacing the experimental pig sty dashboard. The PATH argument may select the grafana root, one direct folder, or one dashboard JSON file; without PATH, pig resolves<PIGSTY_HOME>/files/grafana and never falls back to the current directory.

pig sty grafana info             # check Grafana health, authentication, and basic info
pig sty grafana list             # list all dashboards in the active organization
pig sty grafana boot             # bootstrap Grafana around the existing pigsty dashboards
pig sty grafana init             # load the complete dashboard corpus, then bootstrap
pig sty grafana load [PATH]      # load dashboards selected by a local path
pig sty grafana dump [PATH]      # export remote dashboards into a local path
pig sty grafana clean [PATH]     # delete dashboards selected by a path (--dry-run/--yes)
pig sty grafana lang zh-Hans     # set the organization and current-user language
pig sty grafana style            # set the organization and current-user visual style

Connection and credentials:

Option	Description
`--endpoint`	Grafana origin and optional path prefix (default `http://i.pigsty/ui`)
`--username`	Grafana API username
`--password`	Grafana API password (insecure: visible in process arguments and shell history)
`--password-file`	Owner-only file containing the password (recommended)

Password resolution order: --password → --password-file → the GRAFANA_PASSWORD environment variable → all.vars.grafana_admin_password from the inventory. The HTTP client enforces timeouts and response-size limits, refuses redirects, and verifies TLS certificates by default.

Legacy dashboards and schema v2 resources

load and init accept both classic Grafana dashboard JSON and the resource form whose identity is exactly:

{"apiVersion":"dashboard.grafana.app/v2","kind":"Dashboard","metadata":{"name":"pgsql-overview","namespace":"default"},"spec":{}}

The two formats are not flattened into one another during loading:

Classic JSON takes its UID from top-level uid and uses the legacy dashboard API.
Schema v2 takes its UID from metadata.name, defaults a missing namespace to default, requires an object-valued spec, and uses Grafana’s dashboard resource API.
The JSON filename (without .json) must match the resolved UID. Only one local folder layer is allowed; its directory name becomes the Grafana folder UID.
For schema v2, PIG preserves spec and the grafana.app/message annotation, sets grafana.app/folder from the local folder, and deliberately removes server-managed metadata/status before upsert.
dump preserves schema v2 only when the target file already exists locally in v2 form; it then fetches the native v2 resource using that file’s namespace. A new dump target defaults to classic JSON. Local-only files are never deleted by dump.

Other dashboard.grafana.app/* versions or malformed resource envelopes are rejected instead of being silently treated as classic dashboards. Format preservation therefore depends on keeping the existing local file when round-tripping v2 resources.

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

CMD: inventory

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

The pig inventory command group (alias pig inv), introduced in v1.6.0, provideslossless 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.

Quick Start

pig inventory status                     # which inventory source is active?
pig inventory list                       # browse the inventory topology
pig inventory edit pg-meta               # edit only the pg-meta cluster fragment
pig inventory validate                   # full validation
pig inventory check -p ssh --sudo        # add SSH/sudo readiness probes
pig inventory diff /path/other.yml       # compare declarations with another file

Selectors

list / show / edit accept an optional selector that addresses one fragment:

pig inv e                                # the whole inventory
pig inv e vars                           # all.vars global parameters
pig inv e pg-meta                        # one cluster group
pig inv e pg-meta.vars.pg_databases      # a nested key path
pig inv e 'pg-meta.hosts["10.10.10.10"]' # dotted keys (e.g. IPs) via quoted brackets

inv edit

Opens the selected fragment in $EDITOR. After you save and exit, pig re-applies indentation and newline style → re-parses the whole document (aborting and keeping the temp file on failure) → checks that the on-disk file was not concurrently modified → writes atomically.

pig inventory edit                       # edit the whole inventory
pig inv e pg-meta                        # edit one fragment
pig inv e vars --from vars.yml           # replace the fragment from a file (or stdin: -)

Option	Description
`--from`	Replace the selected fragment from a regular file or stdin (`-`), skipping the editor

Note: after a successful edit, pig tightens the inventory file mode to 0600 (the file may contain database passwords and other secrets); the result reports this via themode_tightened field. If other users or tools read the file directly, adjust permissions or ownership accordingly.

inv validate

Validates one complete static Pigsty inventory: YAML structure, Ansible conventions, and Pigsty semantics (such as admin_ip, the infra group, and IPv4 host keys) are checked layer by layer; diagnostics never echo sensitive values.

pig inventory validate                   # validate the active inventory
pig inv v ./pigsty.yml                   # validate a specific file
pig inv v --strict                       # treat warnings as failures
pig inv v --ansible                      # cross-check with ansible-inventory
pig inv v --strict -o json               # structured output (CI-friendly)

Option	Description
`--strict`	Treat validation warnings as failures
`--ansible`	Also parse with a bounded `ansible-inventory` adapter
`--timeout`	Timeout for `--ansible` compatibility validation (default 10s)

validate is a Pigsty-semantics validator, not a generic Ansible linter; its rules stay aligned with Pigsty’s own bin/validate (intentionally stricter in a few places). Also note that parsing outright rejects duplicate keys and multi-document YAML — such files cannot even be used with show / edit.

inv check

Readiness checks on top of static validation: by default only the inventory and local controller conditions are checked; add probes with --profile.

pig inventory check                      # inventory + controller basics
pig inv ck -p ansible                    # add ansible environment checks
pig inv ck -p network                    # add network reachability probes
pig inv ck -p ssh --user admin           # add SSH login probes
pig inv ck -p ssh --sudo                 # SSH probes plus sudo -n validation

Option	Short	Description
`--profile`	`-p`	Additional probes: `ansible` / `network` / `ssh`
`--user`		Explicit SSH user (defaults to the controller user)
`--port`		TCP/SSH target port (default 22)
`--sudo`		With the ssh profile, also observe `sudo -n true`

inv cmdb (experimental)

Experimental: interfaces and behavior may change.

pig inventory cmdb exchanges the inventory with Pigsty’s existing CMDB schema (files/cmdb.sql, the pigsty / pglog schemas) over a native PostgreSQL driver. Connection resolution: -d/--database (database name, URI, or libpq conninfo) →METADB_URL environment variable → service=meta.

Subcommand	Description
`check`	Read-only: verify CMDB projections, optionally against the static inventory
`init`	Apply the `cmdb.sql` baseline (`--yes` required over existing schemas; `--plan` preview)
`load`	Replace all CMDB declaration rows from the static inventory (single transaction; `--yes`; `--plan`/`--strict`)
`dump`	Export the CMDB as a static inventory file (`--force` to overwrite a differing target)
`enable`	Guarded switch of the `ansible.cfg` inventory to the CMDB (`inventory.sh`)
`disable`	Switch back to the static `pigsty.yml` (both support `--plan`; atomic, rollback-safe writes)

pig inventory cmdb check                 # verify CMDB state
pig inventory cmdb init --plan           # preview the init plan
pig inventory cmdb load -y               # load the static inventory into the CMDB
pig inventory cmdb dump -f pigsty.yml    # export the CMDB as a static inventory
pig inventory cmdb enable                # switch the ansible inventory source to the CMDB
pig inventory cmdb disable               # switch back to the static pigsty.yml

Note: init applies the cmdb.sql baseline directly and does not take a backup of an existing CMDB — back it up yourself before running against real data; load replaces all declaration rows. Destructive operations are gated by a target-fingerprint confirmation, and structured output mode requires an explicit --yes.

CMD: pg

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):

Command	Alias	Description	Notes
`pg init`	`initdb, i`	Initialize data directory	Wraps initdb
`pg start`	`boot, up`	Start PostgreSQL	Wraps pg_ctl start
`pg stop`	`halt, down`	Stop PostgreSQL	Wraps pg_ctl stop
`pg restart`	`reboot`	Restart PostgreSQL	Wraps pg_ctl restart
`pg reload`	`hup`	Reload configuration	Wraps pg_ctl reload
`pg status`	`st, stat`	Show service status	Shows processes & related services
`pg promote`	`pro`	Promote replica to primary	Wraps pg_ctl promote
`pg role`	`r`	Detect instance role	Outputs primary/replica

Connection & Query:

Command	Alias	Description	Notes
`pg psql`	`sql, connect`	Connect to database	Wraps psql
`pg ps`	`activity, act`	Show current connections	Queries pg_stat_activity
`pg kill`	`k`	Terminate connections	Default dry-run mode
`pg clone`		Clone a single database	`CREATE DATABASE ... TEMPLATE ... FILE_COPY`

Database Maintenance:

Command	Alias	Description	Notes
`pg vacuum`	`vac, vc`	Vacuum tables	Wraps vacuumdb
`pg analyze`	`ana, az`	Analyze tables	Wraps vacuumdb –analyze-only
`pg freeze`		Freeze vacuum	Wraps vacuumdb –freeze
`pg repack`	`rp`	Online table repacking	Requires pg_repack extension

Parameter Tuning:

Command	Alias	Description	Notes
`pg tune`	`tuning`	Generate PostgreSQL tuning parameters	Auto-detects hardware and supports structured output

Instance Fork:

Command	Alias	Description	Notes
`pg fork`		Shortcut for `fork init`	Creates a managed fork by default, does not start it
`pg fork init`	`create`	Create a local one-off physical copy	Default `/pg/data-<name>`
`pg fork list`		List managed forks	Scans `/pg/data-*`
`pg fork start`		Start an existing fork	Supports managed names or unmanaged `--dst-data` directories
`pg fork stop`		Stop an existing fork	Supports shutdown mode
`pg fork rm`	`remove, delete`	Remove a fork	Running forks require `--stop`

Log Tools:

Command	Alias	Description	Notes
`pg log`	`l`	Log management	Parent command
`pg log list`	`ls`	List log files
`pg log tail`	`t, f`	Real-time log viewing	tail -f
`pg log show`	`cat, c`	Output log content
`pg log less`	`vi, v`	View with less
`pg log grep`	`g, search`	Search logs

Service Subcommand (pg svc, also pg service or pg s):

Command	Alias	Description
`pg svc start`	`boot, up`	Start postgres service
`pg svc stop`	`halt, dn, down`	Stop postgres service
`pg svc restart`	`reboot, rt`	Restart postgres service
`pg svc reload`	`rl, hup`	Reload postgres service
`pg svc status`	`st, stat`	Show service status

Quick Start

# Service control
pig pg init                       # Initialize data directory
pig pg start                      # Start PostgreSQL
pig pg status                     # Check status
pig pg stop                       # Stop PostgreSQL
pig pg restart                    # Restart PostgreSQL
pig pg reload                     # Reload configuration

# Connection & query
pig pg psql                       # Connect to postgres database
pig pg psql mydb                  # Connect to specific database
pig pg ps                         # View current connections
pig pg kill -x                    # Terminate connections (requires -x to execute)
pig pg clone meta meta_fork       # Clone a single database

# Database maintenance
pig pg vacuum mydb                # Vacuum specific database
pig pg analyze mydb               # Analyze specific database
pig pg repack mydb                # Online repack database

# Parameter tuning
pig pg tune                       # Auto-detect hardware and generate tuned parameters
pig pg tune -p olap               # Use the OLAP workload profile
pig pg tune -c 8 -m 32768 -d 500  # Override CPU / memory / disk detection

# Instance fork
pig pg fork dev                   # Create /pg/data-dev
pig pg fork init dev --start      # Create and start fork, auto-assign high port
pig pg fork init dev -s --dst-port 15433  # Create and start on specified port
pig pg fork list                  # List /pg/data-* forks

# Log viewing
pig pg log tail                   # Real-time view latest log
pig pg log list --log-dir /var/log/pg  # Custom log directory
pig pg log grep ERROR             # Search logs

Global Options

These options apply to all pig pg subcommands:

Option	Short	Default	Description
`--version`	`-v`	auto-detect	PostgreSQL major version
`--data`	`-D`	`/pg/data`	Data directory path
`--dbsu`	`-U`	`postgres`	Database superuser (or `$PIG_DBSU` env)
`--systemd`	`-S`	false	Use systemctl instead of pg_ctl

Version Detection Logic:

If -v specified, use that version
Otherwise read from PG_VERSION file in data directory
If neither available, use default PostgreSQL in PATH

Service Control Commands

pg init

Initialize PostgreSQL data directory. Wraps initdb.

Data checksums are enabled by default unless explicitly disabled with -K|--no-data-checksums.
Prefer the platform-independent built-in C.UTF-8 locale on PG 17+, fall back to system C.UTF-8 / C, then system default locale.
If the data directory already exists, the command refuses to run unless -f|--force is used. If PostgreSQL is running on that data directory, it refuses even with --force to prevent data loss.
Extra arguments after -- are passed to initdb, for example --waldir=/wal. Use initdb directly if you need to override locale or encoding options.

pig pg init                       # Initialize with defaults
pig pg init -v 18                 # Specify PostgreSQL 18
pig pg init -D /data/pg18         # Specify data directory
pig pg init -K                    # Disable data checksums
pig pg init -f                    # Force init (remove existing data)
pig pg init -- --waldir=/wal      # Pass extra args to initdb

Options:

Option	Short	Default	Description
`--no-data-checksums`	`-K`	false	Disable data checksums
`--force`	`-f`	false	Force init and remove existing data (dangerous!)
`--yes`	`-y`	false	Skip overwrite confirmation when used with `--force`

Safety: Even with --force, command refuses to run if PostgreSQL is running.

pg start

Start PostgreSQL server.

pig pg start                      # Start with defaults
pig pg start -D /data/pg18        # Specify data directory
pig pg start -l /pg/log/pg.log    # Redirect output to log file
pig pg start -O "-p 5433"         # Pass options to postgres
pig pg start -o json              # Structured JSON output
pig pg start -S                   # Use systemctl to start

Options:

Option	Short	Description
`--log`	`-l`	Redirect stdout/stderr to log file
`--timeout`	`-t`	Wait timeout (seconds)
`--no-wait`		Don’t wait for startup completion
`--options`	`-O`	Options to pass to postgres

If PostgreSQL is already running, the command prints the existing postmaster PID and returns successfully.

pg stop

Stop PostgreSQL server.

pig pg stop                       # Fast shutdown (default)
pig pg stop -m smart              # Wait for clients to disconnect
pig pg stop -m immediate          # Immediate shutdown
pig pg stop -S                    # Use systemctl to stop
pig pg stop --plan                # Preview stop plan

Options:

Option	Short	Default	Description
`--mode`	`-m`	fast	Shutdown mode: smart/fast/immediate
`--timeout`	`-t`	60	Wait timeout (seconds)
`--no-wait`		false	Don’t wait for shutdown completion
`--plan`		false	Preview local `pg_ctl stop` plan only

Shutdown Modes:

Mode	Description
`smart`	Wait for all clients to disconnect
`fast`	Rollback active transactions, disconnect clients, clean shutdown
`immediate`	Terminate all processes immediately, requires recovery on next start

pg restart

Restart PostgreSQL server.

pig pg restart                    # Fast restart
pig pg restart -m immediate       # Immediate restart
pig pg restart -O "-p 5433"       # Restart with new options
pig pg restart -S                 # Use systemctl to restart
pig pg restart --plan             # Preview restart plan

Options: Same as pg stop, plus --options (-O) to pass to postgres.

pg reload

Reload PostgreSQL configuration. Sends SIGHUP signal to server.

pig pg reload                     # Reload configuration
pig pg reload -D /data/pg18       # Specify data directory
pig pg reload -S                  # Use systemctl reload

pg status

Show PostgreSQL server status. Displays not only pg_ctl status output, but also postgres processes and Pigsty-related service status.

pig pg status                     # Check service status
pig pg status -D /data/pg18       # Specify data directory

Output includes:

pg_ctl status output (running status, PID, etc.)
PostgreSQL process list (ps -u postgres)
Related service status:
- postgres: PostgreSQL systemd service
- patroni: Patroni HA manager
- pgbouncer: Connection pooler
- pgbackrest: Backup service
- vip-manager: VIP manager
- haproxy: Load balancer

pg promote

Promote replica to primary.

pig pg promote                    # Promote replica
pig pg promote -D /data/pg18      # Specify data directory
pig pg promote --plan             # Preview promotion plan
pig pg promote -y                 # Skip confirmation prompt

Options:

Option	Short	Description
`--timeout`	`-t`	Wait timeout (seconds)
`--no-wait`		Don’t wait for promotion completion
`--plan`		Preview promotion plan only
`--yes`	`-y`	Skip confirmation prompt

pg role

Detect PostgreSQL instance role (primary or replica).

pig pg role                       # Output: primary, replica, or unknown
pig pg role -V                    # Verbose output, show detection process
pig pg role -D /data/pg18         # Specify data directory

Options:

Option	Short	Description
`--verbose`	`-V`	Show detailed detection process

Output:

primary: Current instance is primary
replica: Current instance is replica
unknown: Cannot determine instance role

Detection Strategy (by priority):

Process detection: Check for walreceiver, recovery processes
SQL query: Execute pg_is_in_recovery() (requires PostgreSQL running)
Data directory check: Check for standby.signal, recovery.signal, recovery.conf files

Connection & Query Commands

pg psql

Connect to PostgreSQL database via psql.

pig pg psql                       # Connect to postgres database
pig pg psql mydb                  # Connect to specific database
pig pg psql mydb -c "SELECT 1"    # Execute single command
pig pg psql -f script.sql         # Execute SQL script file

Options:

Option	Short	Description
`--command`	`-c`	Execute single SQL command
`--file`	`-f`	Execute SQL script file

pg ps

Show PostgreSQL current connections. Queries pg_stat_activity view.

pig pg ps                         # Show client connections
pig pg ps -a                      # Show all connections (including system)
pig pg ps -u admin                # Filter by user
pig pg ps -d mydb                 # Filter by database

Options:

Option	Short	Description
`--all`	`-a`	Show all connections (including system)
`--user`	`-u`	Filter by user
`--database`	`-d`	Filter by database

pg kill

Terminate PostgreSQL connections. Default is dry-run mode, requires -x to execute.

pig pg kill                       # Show connections to be terminated (dry-run)
pig pg kill -x                    # Actually terminate connections
pig pg kill --pid 12345 -x        # Terminate specific PID
pig pg kill -u admin -x           # Terminate user's connections
pig pg kill -d mydb -x            # Terminate database connections
pig pg kill -s idle -x            # Terminate idle connections
pig pg kill --cancel -x           # Cancel queries instead of terminating
pig pg kill --watch 5 -x          # Repeat every 5 seconds
pig pg kill --plan                # Preview connection termination plan

Options:

Option	Short	Description
`--execute`	`-x`	Actually execute (default is dry-run)
`--pid`		Terminate specific PID
`--user`	`-u`	Filter by user
`--database`	`-d`	Filter by database
`--state`	`-s`	Filter by state (idle/active/idle in transaction)
`--query`	`-q`	Filter by query pattern
`--all`	`-a`	Include replication connections
`--cancel`	`-c`	Cancel queries instead of terminating
`--watch`		Repeat every N seconds
`--plan`		Preview execution plan without terminating connections

Security: --state and --query parameters are validated to accept only simple alphanumeric patterns, preventing SQL injection.

pg clone

Clone a database inside the current PostgreSQL instance. This command wraps CREATE DATABASE ... TEMPLATE ... STRATEGY FILE_COPY, terminates existing sessions on the source database before cloning, and follows the same semantics as Pigsty’s pgsql-db clone workflow.

pig pg clone meta                       # Clone meta as meta_1/meta_2/...
pig pg clone meta meta_fork            # Clone to a specific database name
pig pg clone meta meta_fork --owner dba # Try to change new database owner
pig pg clone meta meta_fork --port 5433 # Connect to a specific local port
pig pg clone meta meta_fork --plan      # Preview clone plan

Options:

Option	Short	Description
`--port`		PostgreSQL port, default `5432` or `$PG_PORT`
`--conn-db`		Database used to execute `CREATE DATABASE`; defaults to `template1` when cloning `postgres`
`--owner`		Try to change the owner of the cloned database
`--conn-limit`		Connection limit for the new database (`-1` unlimited, `0` disallow connections)
`--plan`		Show execution plan only
`--yes`	`-y`	Skip confirmation prompt

Notes: On PostgreSQL 18+ with file_copy_method=clone, database cloning can use CoW semantics; otherwise it falls back to ordinary file copy. This command clones a single database and does not create a new PostgreSQL instance.

Database Maintenance Commands

pg vacuum

Vacuum database tables. Wraps vacuumdb.

pig pg vacuum                     # Vacuum current database
pig pg vacuum mydb                # Vacuum specific database
pig pg vacuum -a                  # Vacuum all databases
pig pg vacuum mydb -t mytable     # Vacuum specific table
pig pg vacuum mydb -n myschema    # Vacuum tables in schema
pig pg vacuum mydb --full         # VACUUM FULL (requires exclusive lock)

Options:

Option	Short	Description
`--all`	`-a`	Process all databases
`--schema`	`-n`	Specify schema
`--table`	`-t`	Specify table
`--verbose`	`-V`	Verbose output
`--full`	`-F`	VACUUM FULL (requires exclusive lock)

Security: --schema and --table parameters are validated for proper PostgreSQL identifier format.

pg analyze

Analyze database tables to update statistics.

pig pg analyze                    # Analyze current database
pig pg analyze mydb               # Analyze specific database
pig pg analyze -a                 # Analyze all databases
pig pg analyze mydb -t mytable    # Analyze specific table

Options: Same as pg vacuum (without --full).

pg freeze

Freeze vacuum database to prevent transaction ID wraparound.

pig pg freeze                     # Freeze current database
pig pg freeze mydb                # Freeze specific database
pig pg freeze -a                  # Freeze all databases

Options: Same as pg analyze.

pg repack

Online table repacking. Requires pg_repack extension.

pig pg repack mydb                # Repack all tables in database
pig pg repack -a                  # Repack all databases
pig pg repack mydb -t mytable     # Repack specific table
pig pg repack mydb -n myschema    # Repack tables in schema
pig pg repack mydb -j 4           # Use 4 parallel jobs
pig pg repack mydb --plan         # Show tables to be repacked

Options:

Option	Short	Description
`--all`	`-a`	Process all databases
`--schema`	`-n`	Specify schema
`--table`	`-t`	Specify table
`--verbose`	`-V`	Verbose output
`--jobs`	`-j`	Number of parallel jobs (default 1)
`--plan`	`-N`	Show tables to be repacked

Parameter Tuning Commands

pg tune

Generate a recommended set of PostgreSQL parameters based on the current PostgreSQL major version, host hardware, and workload profile. By default, it auto-detects CPU, memory, and data disk size, then prints the result as text output.

pig pg tune                       # auto-detect hardware, use oltp profile
pig pg tuning                     # alias
pig pg tune -p olap               # use OLAP profile
pig pg tune -p tiny               # for small instances
pig pg tune -c 8 -m 32768 -d 500  # override hardware detection
pig pg tune -C 500                # override max_connections
pig pg tune -R 0.30               # adjust shared_buffers ratio
pig pg tune -o json               # structured JSON output
pig pg tune -o yaml               # structured YAML output

Options:

Option	Short	Default	Description
`--profile`	`-p`	oltp	Tuning profile: `oltp` / `olap` / `tiny` / `crit`
`--cpu`	`-c`	0	CPU cores, `0` means auto-detect
`--mem`	`-m`	0	Total memory in MB, `0` means auto-detect
`--disk`	`-d`	0	Data disk size in GB, `0` means auto-detect
`--max-conn`	`-C`	0	Override `max_connections`, `0` uses profile default
`--shmem-ratio`	`-R`	0.25	Fraction of memory used for `shared_buffers`, range `0.1 ~ 0.4`

Profiles:

Profile	Best for	Characteristics
`oltp`	General transactional workloads	Balanced connection count, cache, and parallelism
`olap`	Analytical workloads	More aggressive parallelism and work memory
`tiny`	Small instances	Constrained memory footprint and parallelism
`crit`	Latency-sensitive workloads	Restricts parallel gather and favors stable response time

Notes:

Generated parameters are automatically gated by PostgreSQL major version. For example, io_workers is only emitted for PG 18+.
Text output can be redirected into a config snippet, while structured output is better suited for automation.
The command currently generates recommendations only; it does not modify PostgreSQL configuration files directly.

Instance Fork

pg fork

Create a local one-off PostgreSQL physical copy for temporary analysis, troubleshooting, recovery validation, and development testing. Managed forks are written to /pg/data-<name> by default and are not registered with Pigsty, systemd, or Patroni. When --dst-data is specified explicitly, the command creates an unmanaged fork that is not enumerated by fork list.

pig pg fork dev                       # Create /pg/data-dev, do not start
pig pg fork init dev --start          # Create and start, probing ports from 15432
pig pg fork init dev -s --dst-port 15433    # Create and start on specified port
pig pg fork init dev -D /pg/data2 --src-port 15431  # Specify source dir and source port
pig pg fork init dev --dst-data /tmp/dev    # Create unmanaged fork
pig pg fork list                      # List managed forks
pig pg fork start dev                 # Start existing managed fork
pig pg fork stop dev                  # Stop existing managed fork
pig pg fork rm dev --stop             # Stop and remove a running fork
pig pg fork init dev --plan           # Show execution plan only

Create Options:

Option	Short	Default	Description
`--dst-data`		`/pg/data-<name>`	Unmanaged target data directory
`--dst-port`		auto-detect	Target port, probes free ports starting at 15432
`--src-data`		`/pg/data` or `$PG_DATA`	Source data directory; can also be set globally with `pg -D/--data`
`--src-port`		`5432` or `$PG_PORT`	Source port
`--start`	`-s`	false	Start the fork after creation
`--force`	`-f`	false	Overwrite an existing stopped target directory and skip confirmation
`--timeout`	`-t`	60	Startup wait timeout in seconds
`--yes`	`-y`	false	Skip confirmation prompt
`--plan`		false	Show execution plan only

Management Commands:

Command	Common Options	Description
`pig pg fork list`		List managed forks
`pig pg fork start <name> or --dst-data <dir>`	`--dst-data`, `--dst-port`, `-t/--timeout`, `--plan`	Start existing fork
`pig pg fork stop <name> or --dst-data <dir>`	`--dst-data`, `-m/--mode`, `-t/--timeout`, `--plan`	Stop existing fork
`pig pg fork rm <name> or --dst-data <dir>`	`--dst-data`, `--stop`, `-m/--mode`, `-t/--timeout`, `-f/--force`, `-y/--yes`, `--plan`	Remove fork; running forks require `--stop`

Behavior Notes:

When the source instance is running, the command uses PostgreSQL low-level backup APIs to create a consistent physical copy; when the source is stopped, it can perform a cold copy.
The command prefers CoW/reflink. If only ordinary copy is available, interactive mode warns about disk-space risk and waits for confirmation.
To avoid deleting source data by mistake, the target directory cannot be /, /pg, source PGDATA, or a parent/child of source PGDATA. Symlinks are resolved before checks.
After copy, runtime and replication state is cleaned from the fork and fork.json is written. The new instance starts only when -s|--start is specified.
Managed forks must be managed by name. Unmanaged forks require --dst-data when starting, stopping, or removing.

List Forks:

pig pg fork list scans /pg/data-* and reads fork.json. Text status only distinguishes forked and orphan; it does not check live process state.

Structured Output:

pig pg fork init dev --plan -o yaml
pig pg fork list -o json

Log Commands

Log commands view PostgreSQL log files. Default log directory is /pg/log/postgres, can be changed via --log-dir.

Log Command Global Options:

Option	Description
`--log-dir`	Log directory path (default: `/pg/log/postgres`)
`--lines` / `-n`	Number of lines to show, default 50
`--follow` / `-f`	Follow latest log, only on parent `pg log`

Permission Handling: If current user lacks permission to read log directory, command automatically retries with sudo. -o json emits JSONL log records; log snapshots do not support yaml or json-pretty.

pg log

Show the latest log snapshot; with -f, follow the latest log.

pig pg log                        # Show latest 50 lines
pig pg log -n 100                 # Show latest 100 lines
pig pg log -f                     # Follow latest log

pg log list

List log files in log directory.

pig pg log list                              # List logs in default directory
pig pg log list --log-dir /var/log/postgres  # List logs in specified directory

pg log tail

Real-time log viewing (like tail -f). Default views latest CSV log file.

pig pg log tail                   # View latest log
pig pg log tail postgresql.csv    # View specific log file
pig pg log tail -n 100            # Show last 100 lines then follow
pig pg log tail --log-dir /var/log/postgres  # Use custom directory

Options:

Option	Short	Default	Description
`--lines`	`-n`	50	Number of lines to show

pg log show

Output log file content.

pig pg log show                   # Output latest log
pig pg log cat                    # Alias for show
pig pg log c                      # Alias for show
pig pg log show -n 100            # Output last 100 lines
pig pg log show postgresql.csv    # Output specific log file

Options:

Option	Short	Default	Description
`--lines`	`-n`	50	Number of lines to show

pg log less

Open log file with less. Defaults to end of file (+G).

pig pg log less                   # Open latest log with less
pig pg log vi                     # Alias
pig pg log v                      # Alias
pig pg log less postgresql.csv    # Open specific log file

pg log grep

Search log file content.

pig pg log grep ERROR             # Search for ERROR
pig pg log grep --ignore-case error  # Ignore case
pig pg log grep -C 3 ERROR        # Show context
pig pg log grep ERROR pg.csv      # Search specific log file

Options:

Option	Short	Description
`--ignore-case`		Ignore case
`--context`	`-C`	Show context lines

pg svc Subcommand

pg svc (also pg service or pg s) provides systemctl-based PostgreSQL service management:

pig pg svc start                 # Start postgres service
pig pg svc stop                  # Stop postgres service
pig pg svc restart               # Restart postgres service
pig pg svc reload                # Reload postgres service
pig pg svc status                # Show service status

Alias Reference:

Command	Alias
`pg svc start`	`boot, up`
`pg svc stop`	`halt, dn, down`
`pg svc restart`	`reboot, rt`
`pg svc reload`	`rl, hup`
`pg svc status`	`st, stat`

Design Notes

Relationship with Native Tools:

pig pg is not a simple wrapper of PostgreSQL native tools, but a higher-level abstraction for common operations:

Service control commands (init/start/stop/restart/reload/promote) call pg_ctl
status command shows process and related service status beyond pg_ctl status
Connection management commands (psql/ps/kill) call psql
clone command uses SQL to create a database copy
Maintenance commands (vacuum/analyze/freeze) call vacuumdb
repack command calls pg_repack
fork command uses PostgreSQL low-level backup APIs and local file copy to create one-off physical copies
Log commands call system tools like tail, less, grep

For full native tool functionality, call the respective commands directly.

Security Considerations:

--state, --query, --schema, --table parameters are validated to prevent SQL injection
pg kill defaults to dry-run mode to prevent accidents
pg clone terminates existing sessions on the source database; use it during a maintenance window
pg fork rejects dangerous target paths; ordinary-copy fallback warns about disk-space risk
Log commands auto-retry with sudo when permissions insufficient

Platform Support:

This command is designed for Linux systems. Some features depend on systemctl, and log commands depend on readable PostgreSQL log files plus common tools such as tail, less, and grep.

CMD: pt

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:

set, start/up, stop/dn, service/svc, status/st, and log/l select pig’s local implementation;
every other token (list, restart, reload, reinit, switchover, failover,pause, resume, show-config, edit-config, query, history, topology, dsn,version, …) and everything after it is forwarded verbatim to patronictl;
pig pt -- <command> ... bypasses local-name collisions (e.g. pig pt -- set hands set to patronictl);
pig pt with no command prints pig’s help and does not run patronictl; use pig pt <command> --help for native subcommand help and pig pt -- --help for patronictl root help.

Command Overview

Forwarded commands (native patronictl):

Example	Description
`pig pt list [CLUSTER]`	List cluster members (native output, `--format json`)
`pig pt restart CLUSTER [MEMBER]`	Restart PostgreSQL of a cluster / member (native prompt)
`pig pt reload CLUSTER`	Reload PostgreSQL configuration
`pig pt reinit CLUSTER MEMBER`	Reinitialize a member (resync from primary)
`pig pt switchover CLUSTER [--candidate X]`	Planned switchover
`pig pt failover CLUSTER --candidate MEMBER`	Manual failover (positional arg is the cluster)
`pig pt pause / resume CLUSTER`	Enter / leave maintenance mode
`pig pt show-config / edit-config`	Show / edit cluster dynamic configuration
`pig pt query -c 'select 1'`	Native query (`-c` here is query’s own SQL option)

Forwarded positionals follow patronictl’s native cluster-first semantics; confirmation prompts, output formats, and exit codes (including Click usage-error exit code 2) are all owned by patronictl.

Local commands (implemented by pig):

Command	Alias	Description
`pt set`		Update PostgreSQL params or scalar Patroni settings
`pt status`	`st`	Combined status: systemd + processes + cluster
`pt service`	`svc`	Manage the local patroni systemd service
`pt start`	`up`	Hidden shortcut for `pt svc start`
`pt stop`	`dn`	Hidden shortcut for `pt svc stop`
`pt log`	`l`	View local Patroni logs (show / tail / grep)

Note: top-level pt restart is not a daemon shortcut — it forwards topatronictl restart (restarting PostgreSQL). Use pt svc restart to restart the patroni daemon itself.

Quick Start

# Cluster operations (native passthrough, cluster-first)
pig pt list pg-meta                         # list cluster members
pig pt list pg-meta --format json           # native JSON output
pig pt restart pg-test --pending            # apply pending restarts
pig pt restart pg-test pg-test-1            # restart a specific member
pig pt switchover pg-test --candidate pg-2  # planned switchover
pig pt failover pg-test --candidate pg-2    # manual failover
pig pt pause pg-test                        # enter maintenance mode
pig pt show-config pg-test                  # show dynamic configuration

# Configuration sugar (local, one edit-config call)
pig pt set ttl=60                           # scalar Patroni key → --set
pig pt set max_connections=200              # PostgreSQL parameter → --pg
pig pt set ttl=60 max_connections=200 -y    # mixed change, skip confirmation
pig pt set shared_buffers=4GB --plan        # preview the translated native command

# Service and logs (local)
pig pt status                               # combined status
pig pt svc restart                          # restart the patroni daemon
pig pt log -f                               # follow logs
pig pt log grep ERROR                       # search logs

Pig/PT Options

These wrapper-level options must precede the native command; once the native command token appears, all remaining tokens belong to patronictl:

Option	Short	Description
`--config-file`	`-c`	Explicit Patroni/patronictl configuration file
`--dbsu`		OS user used to execute patronictl (default `$PIG_DBSU` or `postgres`)
`--dcs-url`	`-d`	Override the Patroni DCS URL (`--dcs` is an alias)
`--insecure`	`-k`	Allow TLS without certificate verification

pig pt -c /path/patroni.yml list pg-meta   # wrapper-level -c: config file
pig pt query -c 'select 1'                 # native query's -c: SQL, not stolen by pig

Since v1.6.0, --dbsu no longer has the -U shorthand (the pg / pb commands keep it).

Config-File Resolution

Every config-aware patronictl invocation receives exactly one pig-selected root -c <path>, resolved in this order:

explicit -c/--config-file given before the command;
non-empty PATRONICTL_CONFIG_FILE environment variable;
/etc/patroni/patroni.yml (exists and readable as the DBSU);
/infra/conf/patronictl.yml (exists and readable as the DBSU);
fallback to /etc/patroni/patroni.yml, so patronictl’s error names the conventional path.

Explicit and environment paths are authoritative: pig does not silently substitute another candidate when they are missing or unreadable; relative paths are made absolute before switching OS user. Conventional candidates are probed for readability as the resolved DBSU (not by mode bits). Resolution is lazy: pure systemd operations like pt svc start never probe a config, and native -h/--help takes a config-independent fast path that works on machines without Patroni configured.

Transparent Execution and Output Modes

Forwarded execution directly inherits stdin / stdout / stderr and the terminal: native prompts, the edit-config editor, --watch streaming, and exit codes are all preserved. Pig performs no output capture, no duplicate error rendering, no retries, and no cluster/DCS reads before or after execution. The logical invocation is:

patronictl -c <selected-config> [--dcs-url URL] [--insecure] <native argv...>

Structured output: the forwarding path supports pig’s text mode only. A pig-o json / -o yaml placed before the native command is rejected (with guidance to use patronictl’s native output options); anything after the native command is forwarded as-is and validated by patronictl:

pig -o json pt list          # rejected: use native output options
pig pt -o json list          # rejected: use native output options
pig pt list --format json    # forwarded: native patronictl JSON
pig pt list -o json          # forwarded unchanged; patronictl validates it

Local commands (set / status / log / service) keep pig’s structured output behavior.

pig pt set

pt set is the only local configuration sugar; it edits the cluster selected by the resolved configuration:

pig pt set KEY=VALUE [KEY=VALUE ...] [--yes] [--plan]

Key classification:

These scalar Patroni dynamic keys translate to native --set:loop_wait, ttl, retry_timeout, primary_race_backoff,maximum_lag_on_failover, maximum_lag_on_syncnode, max_timelines_history,primary_start_timeout, primary_stop_timeout, synchronous_mode,synchronous_mode_strict, synchronous_node_count, failsafe_mode,check_timeline, member_slots_ttl (pause is deliberately excluded — use native pause/resume);
every other key is treated as a PostgreSQL parameter and translates to native --pg (including dotted custom GUCs like timescaledb.telemetry_level);
structural keys starting with postgresql., standby_cluster., slots., orignore_slots. are rejected, pointing to native pig pt edit-config --set.

All pairs merge into one native edit-config call in input order — one diff, one confirmation, one DCS update:

pig pt set ttl=60 max_connections=200 synchronous_mode=on
# equivalent: patronictl -c <selected> edit-config --set ttl=60 --pg max_connections=200 --set synchronous_mode=on

--yes/-y appends native --force to skip confirmation; otherwise patronictl shows the diff and owns confirmation;
--plan mutates nothing and renders the selected config plus the translated native command (plans may contain sensitive values);
in structured output mode, execution requires an explicit --yes (hidden prompts are forbidden);
values parse as YAML: both KEY=null and KEY= remove a key, passed unchanged;
after changing restart-required PostgreSQL parameters, pig suggests the follow-up: first pig pt list, then pig pt restart CLUSTER --pending (explicit cluster required).

Service Management

pt service (alias pt svc) manages the local patroni systemd unit:

Command	Alias	Description
`pt service start`	`pt svc up`	Start the Patroni service
`pt service stop`	`pt svc dn`	Stop the Patroni service
`pt service restart`	`pt svc rs`	Restart the Patroni service
`pt service reload`	`pt svc rl`	Reload the Patroni service
`pt service status`	`pt svc st`	Show service status

Top-level pt start / pt stop (aliases up / dn) are hidden shortcuts to the same local implementation. Stopping the Patroni service may also stop PostgreSQL on this node (depending on Patroni configuration).

pt status

Shows combined status: systemd service state, Patroni process info, and cluster members from patronictl.

pig pt status
pig pt st -o json                # structured output

pt log

View local Patroni logs. The log directory comes from log.dir in the selected config, falling back to /pg/log/patroni, or set it explicitly with --log-dir. Only pt log andpt log show support -o json (JSONL snapshot); follow / tail / grep are terminal streams without structured output.

pig pt log                     # show last 50 lines
pig pt log -f                  # follow log output
pig pt log -n 100              # show last 100 lines
pig pt log show -o json        # JSONL snapshot
pig pt log tail -n 100         # follow logs
pig pt log grep ERROR          # search logs

Subcommand	Aliases	Description
`show`	`cat, c, s`	Print recent Patroni logs
`tail`	`t, f, follow`	Follow Patroni logs
`grep`	`g, search`	Search Patroni logs

Option	Short	Default	Description
`--follow`	`-f`	false	Follow log output
`--lines`	`-n`	50	Number of lines shown
`--log-dir`		auto	Log directory

Migrating from v1.5.x

The v1.6.0 passthrough rewrite is a breaking change — review automation before upgrading:

v1.5.x usage	v1.6.0 usage
`pig pt failover <candidate>`	⚠ `pig pt failover CLUSTER --candidate MEMBER` (the positional is now the cluster)
`pig pt restart [member]` (auto scope)	`pig pt restart CLUSTER [MEMBER]` (explicit cluster)
`pig pt list -o json`	`pig pt list --format json` (native JSON, different schema)
`pig pt config show`	`pig pt show-config`
`pig pt config edit`	`pig pt edit-config`
`pig pt config set K=V` / `pg K=V`	`pig pt set K=V`
`pig pt restart -y` (pig gate)	native patronictl confirmation; `pt set -y` still works
`pig pt list -W` / `-w 5`	native `pig pt list --watch` (patronictl semantics)
aliases `ls/rs/rl/ri/so/fo/p/r/c`	removed — use full native command names
`--dbsu -U`	`--dbsu` (`-U` shorthand removed)

Also: forwarded commands return native patronictl exit codes (usage errors exit 2), and the pig-side pause-guard preflight for switchover/failover is gone — maintenance-mode semantics are fully owned by Patroni.

Design Notes

Single authority: there is one cluster-control path — the installed patronictl plus one selected config, acting through the Patroni REST API / DCS. Pig embeds no DCS client or REST control engine, keeps no patronictl command inventory, and adds no confirmation, preflight, retry, or output rewriting to forwarded commands.

Privilege handling (unchanged from v1.5.x):

if the current user is already the DBSU: execute directly;
if the current user is root: execute via su - postgres -c "...";
otherwise: execute via sudo -inu postgres -- ....

Platform: designed for Linux; service management relies on systemctl, and the log helpers require readable Patroni log files.

CMD: pb

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:

Command	Alias	Description	Implementation
`pb info`	`i`	Show backup repository info	`pgbackrest info`
`pb list`	`ls`	List backup sets, repos, and stanzas	`pgbackrest info`

Backup & Restore:

Command	Alias	Description	Implementation
`pb backup`	`b`	Create backup	`pgbackrest backup`
`pb restore`	`r`	Low-level restore primitive	`pgbackrest restore`
`pb expire`	`e`	Clean up expired backups	`pgbackrest expire`

Stanza Management:

Command	Alias	Description	Implementation
`pb create`	`c`	Create stanza (first-time setup)	`pgbackrest stanza-create`
`pb upgrade`	`u`	Upgrade stanza after PG major upgrade	`pgbackrest stanza-upgrade`
`pb delete`	`d`	Delete stanza (dangerous!)	`pgbackrest stanza-delete`

Control Commands:

Command	Alias	Description	Implementation
`pb check`	`ck`	Verify backup repository integrity	`pgbackrest check`
`pb start`	`up`	Enable pgBackRest operations	`pgbackrest start`
`pb stop`	`dw`	Disable pgBackRest operations	`pgbackrest stop`
`pb log`	`l`	View logs	latest log snapshot / tail

Quick Start

# View backup info
pig pb info                          # Show all backup info
pig pb info -o json                  # Result-wrapped structured JSON output
pig pb info --raw --raw-output json  # Native pgBackRest JSON output
pig pb ls                            # List all backups
pig pb ls repo                       # List configured repos
pig pb ls stanza                     # List all stanzas

# Create backup (must run on primary)
pig pb backup                        # Auto mode: full if none, else incr
pig pb backup full                   # Full backup
pig pb backup diff                   # Differential backup
pig pb backup incr                   # Incremental backup

# Restore (low-level restore primitive, at least one recovery target is required)
pig pb restore -d                    # Restore to latest (end of WAL)
pig pb restore -I                    # Restore to backup consistency point
pig pb restore -t "2025-01-01 12:00:00+08"  # Restore to specific time
pig pb restore --name savepoint      # Restore to named restore point

# Stanza management
pig pb create                        # Initialize stanza
pig pb upgrade                       # Upgrade stanza after PG major upgrade
pig pb check                         # Verify repository integrity

# Cleanup
pig pb expire                        # Clean up per retention policy
pig pb expire --plan                 # Preview cleanup plan only

Global Options

These options apply to all pig pb subcommands:

Option	Short	Description
`--stanza`	`-s`	pgBackRest stanza name (auto-detected)
`--config`	`-c`	Config file path
`--repo`	`-r`	Repository number (multi-repo scenario)
`--dbsu`	`-U`	Database superuser (default: `$PIG_DBSU` or `postgres`)

Stanza Auto-Detection:

If -s is not specified, pig auto-detects the stanza name from the config file:

Read the config file (default /etc/pgbackrest/pgbackrest.conf)
Find sections that do not start with [global*]
Use the first stanza found

If the config file contains multiple stanzas, pig emits a warning and uses the first one. In that case, specify --stanza explicitly.

Multi-Repo Support:

pgBackRest supports multiple repositories (repo1, repo2, etc.). Use -r to choose the target repository:

pig pb backup -r 1                   # Backup to repo1
pig pb backup -r 2                   # Backup to repo2
pig pb info -r 2                     # View repo2 backup info

Information Commands

pb info

Show detailed backup repository information, including all backup sets and WAL archive status.

pig pb info                          # Show all backup info
pig pb info --raw --raw-output json  # Raw JSON output
pig pb info --set 20250101-120000F   # Show details for a specific backup set

Options:

Option	Short	Description
`--raw`	`-R`	Raw output mode (passes through pgBackRest output)
`--raw-output`		Raw output format: text, json (only in `--raw` mode)
`--set`		Show details for a specific backup set

pb ls

List resources in the backup repository.

pig pb ls                            # List all backups (default)
pig pb ls backup                     # List all backups (explicit)
pig pb ls repo                       # List configured repos
pig pb ls stanza                     # List all stanzas

Types:

Type	Description	Data Source
backup	List all backup sets (default)	pgbackrest info
repo	List configured repos	Parse pgbackrest.conf
stanza	List all stanzas	Parse pgbackrest.conf

Backup Commands

pb backup

Create a physical backup. Backups can only run on the primary instance.

pig pb backup                        # Auto mode
pig pb backup full                   # Full backup
pig pb backup diff                   # Differential backup
pig pb backup incr                   # Incremental backup
pig pb backup --force                # Skip primary role check

Options:

Option	Short	Description
`--force`	`-f`	Skip primary role check

Backup Types:

Type	Description
(empty)	Auto mode: full if no backup exists, otherwise incremental
full	Full backup: backup all data
diff	Differential backup: changes since the last full backup
incr	Incremental backup: changes since the last backup of any type

Primary Check:

Before running a backup, the command automatically checks whether the current instance is primary. If it is a replica, the command exits with an error. Use --force to skip this check.

pb expire

Clean up expired backups and WAL archives according to the retention policy.

pig pb expire                        # Clean up per policy
pig pb expire --set 20250101-*       # Delete a specific backup set
pig pb expire --set 20250101-* -y    # Skip confirmation when deleting backup set
pig pb expire --plan                 # Preview cleanup plan only, do not delete

Options:

Option	Short	Description
`--set`		Delete a specific backup set
`--plan`		Preview cleanup plan only, do not delete backups
`--yes`	`-y`	Skip confirmation prompt when used with `--set`

Retention Policy:

Retention policy is configured in pgbackrest.conf:

[global]
repo1-retention-full=2               # Full backups to retain
repo1-retention-diff=4               # Differential backups to retain
repo1-retention-archive=2            # WAL archive retention policy

Restore Commands

pb restore

Restore from backup with recovery target support. At least one recovery target (-d/-I/-t/--name/--lsn/--xid) must be specified explicitly. Without parameters, help is shown.

# Recovery target (mutually exclusive options)
pig pb restore -d                    # Restore to latest (explicit)
pig pb restore -I                    # Restore to backup consistency point
pig pb restore -t "2025-01-01 12:00:00+08"  # Restore to specific time
pig pb restore -t "2025-01-01"       # Restore to date (00:00:00 that day)
pig pb restore -t "12:00:00"         # Restore to time (today)
pig pb restore --name my-savepoint   # Restore to named restore point
pig pb restore --lsn "0/7C82CB8"     # Restore to LSN
pig pb restore --xid 12345           # Restore to transaction ID

# Backup set selection (must combine with a recovery target)
pig pb restore -b 20251225-120000F -d  # Restore from specific backup set to latest

# Other options
pig pb restore -t "..." -X           # Exclusive mode (stop before target)
pig pb restore -t "..." --target-action=promote  # Promote after reaching target
pig pb restore -t "..." -T current   # Recover along current timeline
pig pb restore -d --plan             # Preview restore plan only
pig pb restore -d -y                 # Skip interactive y/yes confirmation
pig pb restore -d -- --delta         # Pass native pgBackRest restore args after --

Recovery Target Options:

Option	Short	Description
`--default`	`-d`	Restore to end of WAL stream (latest data)
`--immediate`	`-I`	Restore to backup consistency point
`--time`	`-t`	Restore to specific timestamp
`--name`		Restore to named restore point
`--lsn`		Restore to specific LSN
`--xid`		Restore to specific transaction ID

Backup Set and Other Options:

Option	Short	Description
`--set`	`-b`	Restore from a specific backup set (can combine with target)
`--data`	`-D`	Target data directory
`--exclusive`	`-X`	Exclusive mode: stop before target
`--target-action`		Action after reaching recovery target: pause/promote/shutdown
`--target-timeline`	`-T`	Recovery timeline: latest/current/N/0xN
`--plan`		Preview restore plan only, do not execute
`--yes`	`-y`	Skip interactive y/yes confirmation
Native args after `--`		Pass through pgBackRest restore args, for example `-- --delta`

Combination Rules: --target-action cannot be used with --default, because --default already means recovery to the end of the WAL stream. --exclusive/-X must be used with an explicit stop target: --time, --lsn, or --xid.

Native pgBackRest restore args after -- cannot override recovery targets, lifecycle, data directory, repository, config, or selection semantics already managed by Pig. Use Pig’s first-class options for those semantics. Tablespace/link migration options such as --tablespace-map, --link-map, and --link-all can still be passed through.

Time Formats:

Supports multiple time formats and auto-completes timezones (including non-integer-hour zones such as +05:30):

Format	Example	Description
Full format	`2025-01-01 12:00:00+08`	Complete timestamp with timezone
Date only	`2025-01-01`	Auto-completes to 00:00:00 that day (current timezone)
Time only	`12:00:00`	Auto-completes to today (current timezone)

Restore Flow:

Validate parameters and environment
Check that PostgreSQL is stopped
Show restore plan and wait for interactive y/yes confirmation
Execute pgbackrest restore
Provide post-restore guidance

Important: Stop PostgreSQL before restore. If the PGDATA is managed by Patroni, use pig pitr to orchestrate Patroni, PostgreSQL, and pgBackRest:

pig pg stop                          # Stop PostgreSQL
pig pb restore -t "..."              # Execute restore
pig pg start                         # Start PostgreSQL

Stanza Management Commands

pb create

Initialize a new stanza. Must run before the first backup.

pig pb create                        # Create stanza
pig pb create --no-online            # Create when PostgreSQL is not running
pig pb create --force                # Force create

Options:

Option	Short	Description
`--no-online`		Create when PostgreSQL is not running
`--force`	`-f`	Force create

pb upgrade

Update stanza after a PostgreSQL major version upgrade.

pig pb upgrade                       # Upgrade stanza
pig pb upgrade --no-online           # Upgrade when PostgreSQL is not running

Options:

Option	Description
`--no-online`	Upgrade when PostgreSQL is not running

Use Case:

After a PostgreSQL major version upgrade (for example, 16 -> 17), run this command to update stanza metadata.

pb delete

Delete a stanza and all its backups.

pig pb delete                        # Delete stanza (interactive y/N confirmation)
pig pb delete --yes                  # Skip interactive y/yes confirmation
pig pb delete --plan                 # Preview delete plan

Options:

Option	Short	Description
`--plan`		Preview delete plan only, do not execute
`--yes`	`-y`	Skip interactive y/yes confirmation

Warning: This is a destructive and irreversible operation. All backups will be permanently deleted.

The command includes multiple safety mechanisms:

In text mode, it requires interactive y/yes confirmation unless --yes is specified
Structured output mode requires explicit --yes
If the config file contains multiple stanzas and --stanza is not specified, pig refuses to auto-select a deletion target

Control Commands

pb check

Verify backup repository integrity and configuration.

pig pb check                         # Verify repository

This command checks:

WAL archive configuration correctness
Repository accessibility
Stanza configuration validity

pb start

Enable pgBackRest operations.

pig pb start                         # Enable operations

Use this command after pb stop to resume normal operations.

pb stop

Disable pgBackRest operations for maintenance.

pig pb stop                          # Disable operations
pig pb stop --force                  # Terminate running operations

Options:

Option	Short	Description
`--force`	`-f`	Terminate running operations

Use Case:

Use this command during system maintenance to prevent new backup operations from starting.

Log Commands

pb log

View pgBackRest log files. The log directory is read from pgBackRest config log-path first, and falls back to /pg/log/pgbackrest/ when not configured. The parent command shows the latest log snapshot by default; use tail or -f for live follow. Only pb log and pb log show support -o json JSONL output; log snapshots do not support yaml or json-pretty, and follow/tail does not support structured output.

pig pb log                           # Show latest log lines
pig pb log list                      # List log files
pig pb log tail                      # Real-time view latest log
pig pb log tail -n 100               # Show last 100 lines and follow
pig pb log show                      # Show latest log content
pig pb log show -n 50                # Show last 50 lines
pig pb log cat                       # Alias for show

Subcommands:

Subcommand	Aliases	Description
list	ls	List log files
show	cat, c	Show latest log content
tail	t, f, follow	Real-time follow latest log

Options:

Option	Short	Default	Description
`--lines`	`-n`	50	Number of lines to show
`--follow`	`-f`	false	Makes parent command `pb log` follow; no-op in `pb log tail` because tail always follows

Permission Handling:

If the current user does not have permission to read the log directory, the command automatically retries with sudo.

Design Notes

Command Execution:

All pig pb commands run as the database superuser (DBSU), because pgBackRest needs access to PostgreSQL data files and WAL archives.

Execution logic:

If the current user is DBSU: execute directly
If the current user is root: use su - postgres -c "..." to execute
Other users: use sudo -inu postgres -- ... to execute

Relationship with pgbackrest:

pig pb is not a complete wrapper for pgbackrest; it is a higher-level abstraction for common operations:

Auto-detect stanza name without specifying it every time
Auto-check primary role before backup
Show restore plan and require interactive y/yes confirmation before restore
Provide user-friendly time format input
Provide post-restore guidance

For full pgbackrest functionality, use the pgbackrest command directly.

Default Configuration Paths:

Config	Default
Config file	`/etc/pgbackrest/pgbackrest.conf`
Log directory	`/pg/log/pgbackrest`
Data directory	`pg1-path` from config, or `$PGDATA`, or `/pg/data`

Security Considerations:

pb delete requires interactive y/yes confirmation when --yes is not specified, and --stanza must be explicit under multi-stanza configs
pb restore requires an explicit recovery target, validates --time, and requires interactive y/yes confirmation when --yes is not specified
pb backup checks primary role by default to prevent running on a replica
pb log tail does not support structured output; use pb log show -n N -o json when a JSONL snapshot is required

Platform Support:

This command is designed for Linux systems and depends on Pigsty’s default directory layout.

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

pig pitr - Perform PITR with pgBackRest restore and conservative PostgreSQL stop/start handling.

For the managed default data directory, this command may:
  1. Stop Patroni only to keep the target PGDATA offline during restore
  2. Ensure PostgreSQL is stopped (fast stop with retry; destructive fallback only with --force-stop)
  3. Execute pgbackrest restore
  4. Start PostgreSQL unless --no-restart is used
  5. Leave Patroni stopped; provide post-restore guidance

Recovery Targets (at least one required):
  --default, -d      Recover to end of WAL stream (latest)
  --immediate, -I    Recover to backup consistency point
  --time, -t         Recover to specific timestamp
  --name             Recover to named restore point
  --lsn              Recover to specific LSN
  --xid              Recover to specific transaction ID

Backup and Target Options:
  --set, -b          Select backup set to start recovery from
  --target-action    Action when target is reached: pause, promote, shutdown
  --target-timeline  Recover along timeline: latest, current, N, or 0xN

Use --no-restart with --target-action=shutdown because PostgreSQL exits
after reaching the recovery target.

Custom -D side restores require --no-restart. The custom directory must
already exist, be owned by the configured DBSU (postgres by default), and
be writable by that user. Pig does not create this directory automatically.

Additional pgBackRest arguments:
  Put raw pgBackRest restore arguments after -- so Cobra stops parsing them.
  Example: pig pitr -d -- --delta

Time Format:
  - Full: "2025-01-01 12:00:00+08"
  - Date only: "2025-01-01" (defaults to 00:00:00)
  - Time only: "12:00:00" (defaults to today)

Examples:
  pig pitr -d                                      # Recover to latest
  pig pitr -t "2025-01-01 12:00:00+08"            # Recover to time
  pig pitr -d --plan                               # Preview plan
  pig pitr -d -y                                   # Skip y/yes confirmation
  pig pitr -d --no-restart                         # Leave PostgreSQL stopped
  pig pitr -d -D /tmp/pg-restore --no-restart      # Side restore

Overview

The default target of pig pitr is the Pigsty-managed primary data directory. A typical workflow:

Validate recovery target parameters. One of -d/-I/-t/--name/--lsn/--xid is required.
Resolve pgBackRest configuration and target data directory.
For default data-directory recovery, stop Patroni if it is running.
Ensure PostgreSQL is stopped.
Run pgbackrest restore.
Start PostgreSQL unless --no-restart is specified.
Print post-recovery validation and Patroni recovery guidance.

Comparison with pig pb restore:

Feature	`pig pitr`	`pig pb restore`
Stop Patroni	Automatic for default data-directory recovery	Manual
Stop PostgreSQL	Checks and stops automatically	Must be pre-stopped
Start PostgreSQL	Automatic by default, can be disabled with `--no-restart`	Manual
Patroni recovery	Not automatic; restore manually after verification	Not handled
Use case	Production recovery orchestration	Low-level restore or scripting

Quick Start

# Most common: recover to the end of the WAL stream
pig pitr -d

# Recover to a specific point in time
pig pitr -t "2025-01-01 12:00:00+08"

# Recover to the backup consistency point
pig pitr -I

# Preview the execution plan without running
pig pitr -d --plan

# Skip confirmation, suitable for automation
pig pitr -d -y

# Recover from a specific backup set
pig pitr -d -b 20251225-120000F

# Restore the default data directory but do not start PostgreSQL afterward
pig pitr -d --no-restart

# Side restore: restore to a custom directory without touching Patroni or /pg/data
install -d -m 700 -o postgres -g postgres /tmp/pg-restore
pig pitr -d -D /tmp/pg-restore --no-restart

# Extra native pgBackRest restore arguments go after --
pig pitr -d -- --delta

Parameters

Recovery Target

At least one recovery target is required.

Parameter	Short	Description
`--default`	`-d`	Recover to the end of the WAL stream, the latest data
`--immediate`	`-I`	Recover to the backup consistency point
`--time`	`-t`	Recover to a specific timestamp
`--name`		Recover to a named restore point
`--lsn`		Recover to a specific LSN
`--xid`		Recover to a specific transaction ID

Backup And Target Options

Parameter	Short	Description
`--set`	`-b`	Start recovery from a specific backup set
`--target-action`		Action when the recovery target is reached: pause/promote/shutdown
`--target-timeline`	`-T`	Recovery timeline: latest/current/N/0xN
`--exclusive`	`-X`	Exclusive mode: stop before target

Use --target-action=shutdown with --no-restart, because PostgreSQL exits after reaching that recovery target. --target-action cannot be used with --default, because --default already means recovery to the end of WAL. --exclusive/-X requires a precise stop-before target: --time, --lsn, or --xid.

Native pgBackRest restore arguments after -- cannot override recovery target, lifecycle, data directory, repository, config, or selection parameters managed by Pig. Use Pig’s first-class parameters for these semantics. This restriction is consistent with the pig pb restore passthrough blocklist.

Flow Control

Parameter	Short	Description
`--no-restart`		Do not start PostgreSQL after restore
`--plan`		Show execution plan only, do not execute
`--yes`	`-y`	Skip interactive y/yes confirmation
`--timeout`		PostgreSQL startup/recovery wait timeout, default 120 seconds
`--force-stop`		Allow immediate shutdown and kill fallback if fast stop fails

Configuration

Parameter	Short	Description
`--stanza`	`-s`	pgBackRest stanza name
`--config`	`-c`	pgBackRest config file path
`--repo`	`-r`	Repository number
`--dbsu`	`-U`	Database superuser, default `postgres`
`--data`	`-D`	Target data directory

Time Format

The --time parameter supports multiple formats and completes missing parts using the current timezone:

Format	Example	Description
Full	`2025-01-01 12:00:00+08`	Complete timestamp with timezone
Date time without timezone	`2025-01-01 12:00:00`	Adds the current local timezone automatically; `T` separator is also accepted
Date only	`2025-01-01`	Completes to 00:00:00 on that date
Time only	`12:00:00`	Completes to that time today

Plan output and replayable next-action commands normalize date-only and time-only targets into deterministic timestamps with timezone. This rule is consistent with pig pb restore --plan.

Managed Directory And Side Restore

The managed PostgreSQL data directory comes from the effective pgBackRest pg1-path and command parameters. It is not hardcoded to /pg/data. For example, if managed PGDATA is /var/lib/pgsql/18/data, the command still treats it as a managed restore. Path comparison resolves symlinks as the database superuser when needed, so a symlink to managed PGDATA is not mistaken for a side restore.

An explicit -D/--data that resolves to a path different from the managed directory is a side restore. Side restores must use --no-restart; they do not stop Patroni and do not manage the default PostgreSQL service. After restore, handle the side instance manually with commands such as pg_ctl -D <dir> -o "-p 5433" start, pg_ctl -D <dir> status, and pgbackrest --pg1-path=<dir> stanza-create. The side-restore directory must already exist and be owned by the DBSU. Unlike managed PGDATA, it does not need a pre-existing PG_VERSION marker. Pig does not create this directory automatically because it needs a concrete path for destructive-restore classification, owner checks, and safe guidance before restore.

install -d -m 700 -o postgres -g postgres /tmp/pg-restore
pig pitr -d -D /tmp/pg-restore --no-restart

For managed PGDATA outside /pg/data, post-restore runbook commands explicitly include the effective data directory:

pig pg start -D /var/lib/pgsql/18/data
pig pg psql -D /var/lib/pgsql/18/data
pig pg promote -D /var/lib/pgsql/18/data

pig pg psql -D <dir> reads postmaster.pid under that directory and uses the recorded port and socket directory to connect to the restored instance. If postmaster information cannot be resolved, it does not silently fall back to the default connection target.

Execution Flow

Phase 1: Pre-Checks

Validate recovery target parameters; missing targets only print help and return an error.
Resolve effective pgBackRest config, stanza, repository, and managed pg1-path.
Check that the managed data directory exists and is initialized.
For side restore, check that the custom data directory exists and is owned by the DBSU.
Verify the selected stanza is healthy and has backups; if --set is specified, verify that backup set exists.
Detect Patroni service state and PostgreSQL runtime state.

Phase 2: Patroni Handling

For managed data-directory recovery, if Patroni is running, the command stops Patroni so the target PGDATA stays offline during restore. Patroni remains stopped after recovery. A custom -D side restore does not touch the managed data directory and therefore does not stop Patroni.

Phase 3: Ensure PostgreSQL Is Stopped

The command first waits for PostgreSQL to exit after Patroni stops, then retries pg_ctl stop -m fast. If PostgreSQL still cannot stop, it does not use more aggressive methods by default. Only explicit --force-stop allows immediate shutdown and final kill fallback.

Phase 4: Restore

The command runs pgBackRest restore and maps recovery target, backup set, timeline, target action, and related options into pgbackrest restore. Native pgBackRest arguments can be placed after --:

pig pitr -d -- --delta

Phase 5: Start Or Stay Stopped

Unless --no-restart is specified, the command starts PostgreSQL after restore and waits for recovery completion. For --default and --target-action=promote, it waits until pg_is_in_recovery() becomes false on the recovered instance. Recovery and subsequent SQL probes bind to the port recorded in postmaster.pid for the restored data directory and use the socket directory there when present. Use --no-restart when:

Running a custom -D side restore, because the restored config still keeps the original port and must be started manually on a free port.
Using --target-action=shutdown, because PostgreSQL exits after reaching the recovery target.
You need to inspect the restored directory before deciding whether to start.

Examples

Scenario 1: Recover Dropped Data

# 1. View available backups
pig pb info

# 2. Preview recovery plan
pig pitr -t "2025-01-15 09:30:00+08" --plan

# 3. Execute recovery
pig pitr -t "2025-01-15 09:30:00+08"

# 4. Verify data
pig pg psql
SELECT * FROM important_table;

Scenario 2: Recover To Latest

pig pitr -d

Scenario 3: Recover To Backup Consistency Point

pig pitr -I

Scenario 4: Keep Stopped After Restore

pig pitr -d --no-restart

# PostgreSQL and Patroni both remain stopped; inspect directory or logs before starting
pig pg start

Scenario 5: Custom Directory Side Restore

install -d -m 700 -o postgres -g postgres /tmp/pg-restore
pig pitr -d -D /tmp/pg-restore --no-restart

# Start the side restore manually on a free port
pg_ctl -D /tmp/pg-restore -o "-p 5433" start

Execution Plan Example

Running pig pitr -d --plan shows a plan like:

══════════════════════════════════════════════════════════════════
 PITR Execution Plan
══════════════════════════════════════════════════════════════════

Current State:
  Data Directory:  /pg/data
  Database User:   postgres
  Patroni Service: active
  PostgreSQL:      running (PID: 12345)

Recovery Target:
  Latest (end of WAL stream)

Execution Steps:
  [1] Stop Patroni service
  [2] Ensure PostgreSQL is stopped
  [3] Execute pgBackRest restore
  [4] Start PostgreSQL
  [5] Print post-restore guidance

══════════════════════════════════════════════════════════════════

Post-Recovery Actions

After successful recovery, verify data before restoring orchestration:

# Verify data
pig pg psql

# If recovered to a manual target and promotion is needed
pig pg promote

# Restore Patroni management only after validation
systemctl start patroni

# Re-create pgBackRest stanza if needed
pig pb create

Leaving Patroni stopped after managed data-directory recovery is intentional. It prevents restored old state from re-entering HA orchestration before validation.

Safety Mechanisms

Recovery target required: Without -d/-I/-t/--name/--lsn/--xid, the command only shows help and does not run restore.

Confirmation: In text mode, destructive recovery asks for interactive y/yes confirmation before execution. Automation can use -y|--yes. Structured output mode does not prompt interactively; it must use --yes to execute or --plan to preview.

Patroni boundary: For managed data-directory recovery, the command stops Patroni when needed to prevent Patroni from restarting PostgreSQL during restore. It does not automatically rejoin Patroni after recovery.

Side restore boundary: A custom -D side restore must use --no-restart because the restored PostgreSQL config still uses the original port. Side restore does not manage Patroni or the default PostgreSQL service.

Failure boundary: If restore fails after Patroni has been stopped, Patroni remains stopped and the target data directory may be partially restored. Fix the underlying issue and rerun PITR, or validate the recovery state first; do not start Patroni before confirmation. If restore has run but PostgreSQL startup fails, inspect PostgreSQL and pgBackRest logs and validate the data directory before deciding whether to restore Patroni management.

Structured output: Structured execution requires --yes; --plan is the preview path. After successful execution, structured PITR results put post-restore actions in the Result envelope’s next_actions, not inside data. data includes requested_data_dir, effective_data_dir, managed_data_dir, and side_restore so automation can distinguish user input from the actual recovery target.

Design Notes

pig pitr calls pgBackRest restore and handles local Patroni/PostgreSQL stop and optional start.
pig pitr is not a cluster recovery controller. It does not handle Patroni failover, rejoin, VIP, or application traffic switching.
Use pig pb restore when you need lower-level restore semantics or fine-grained scripting control.
Use pig pt switchover CLUSTER or pig pt failover CLUSTER --candidate MEMBER when you need manual Patroni cluster switching (native patronictl passthrough since v1.6.0; the cluster name is required).

Privilege execution:

If the current user is the DBSU: execute directly.
If the current user is root: execute with su - postgres -c.
Other users: execute with sudo -inu postgres --.

Platform support:

This command is designed for Linux and depends on pgBackRest, systemd for managed service scenarios, and data/log paths accessible by the DBSU.