Getting Started

Quick start with pig, the PostgreSQL package manager

Here is a simple getting started tutorial to help you experience the core capabilities of the PIG package manager.

Short Version

curl -fsSL https://repo.pigsty.io/pig | bash   # Install PIG from Cloudflare
pig repo set                                   # One-time setup for Linux, Pigsty + PGDG repos (overwrites!)
pig install -v 18 -y pg18 pg_duckdb vector     # Install PG 18 kernel, pg_duckdb, pgvector extensions...

Installation

You can install pig with the following command:

China Mainland:

curl -fsSL https://repo.pigsty.cc/pig | bash

Global (Cloudflare CDN):

curl -fsSL https://repo.pigsty.io/pig | bash

PIG binary is about 4 MB. On Linux it uses rpm or dpkg to install the latest available version:

$ curl -fsSL https://repo.pigsty.cc/pig | bash
[INFO] kernel = Linux
[INFO] machine = x86_64
[INFO] package = deb
[INFO] pkg_url = https://repo.pigsty.cc/pkg/pig/v1.0.0/pig_1.0.0-1_amd64.deb
[INFO] download = /tmp/pig_1.0.0-1_amd64.deb
[INFO] downloading pig v1.0.0
curl -fSL https://repo.pigsty.cc/pkg/pig/v1.0.0/pig_1.0.0-1_amd64.deb -o /tmp/pig_1.0.0-1_amd64.deb
######################################################################## 100.0%
[INFO] md5sum = a543882aa905713a0c50088d4e848951b6957a37a1594d7e9f3fe46453d5ce66
[INFO] installing: dpkg -i /tmp/pig_1.0.0-1_amd64.deb
(Reading database ... 166001 files and directories currently installed.)
Preparing to unpack /tmp/pig_1.0.0-1_amd64.deb ...
Unpacking pig (1.0.0-1) ...
Setting up pig (1.0.0-1) ...
[INFO] pig v1.0.0 installed successfully
check https://pgext.cloud for details

Check Environment

PIG is a Go-written binary program, installed by default at /usr/bin/pig. pig version prints version information:

$ pig version
pig version 1.0.0 linux/amd64
build: HEAD dc8f343 2026-01-26T15:52:04Z

Use pig status to print the current environment status, OS code, PG installation status, repository accessibility and latency.

$ pig status

# [Configuration] ================================
Pig Version      : 1.0.0
Pig Config       : /home/vagrant/.pig/config.yml
Log Level        : info
Log Path         : stderr

# [OS Environment] ===============================
OS Distro Code   : u24
OS OSArch        : arm64
OS Package Type  : deb
OS Vendor ID     : ubuntu
OS Version       : 24
OS Version Full  : 24.04
OS Version Code  : noble

# [PG Environment] ===============================
Installed:
- PostgreSQL 18.1 (Ubuntu 18.1-1.pgdg24.04+2)  398 Extensions

Active:
PG Version      :  PostgreSQL 18.1 (Ubuntu 18.1-1.pgdg24.04+2)
Config Path     :  /usr/bin/pg_config
Binary Path     :  /usr/lib/postgresql/18/bin
Library Path    :  /usr/lib/postgresql/18/lib
Extension Path  :  /usr/share/postgresql/18/extension

# [Pigsty Environment] ===========================
Inventory Path   : Not Found
Pigsty Home      : Not Found

# [Network Conditions] ===========================
pigsty.cc  ping ok: 802 ms
pigsty.io  ping ok: 1410 ms
Internet Access   :  true
Pigsty Repo       :  pigsty.io
Inferred Region   :  china
Latest Pigsty Ver :  v4.1.0

Automation Tips

For production recovery tasks, it is recommended to run --dry-run first to preview the PITR execution plan before actually executing:

pig pitr -d --dry-run         # preview recovery steps only, no execution
pig pitr -d -y                # skip confirmation (automation scenarios)

List Extensions

Use the pig ext list command to print the built-in PG extension catalog.

$ pig ext list

Name                            Status              Version     Cate   Flags   License       Repo     PGVer  Package                               Description
----                            ------              -------     ----   ------  -------       ------   -----  ------------                          ---------------------
timescaledb                     installed  2.24.0      TIME   -dsl--  Timescale     PIGSTY   15-18  postgresql-18-timescaledb-tsl         Enables scalable inserts and complex queries for time-series dat
timescaledb_toolkit             installed  1.22.0      TIME   -ds-t-  Timescale     PIGSTY   15-18  postgresql-18-timescaledb-toolkit     Library of analytical hyperfunctions, time-series pipelining, an
timeseries                      installed  0.2.0       TIME   -d----  PostgreSQL    PIGSTY   13-18  postgresql-18-pg-timeseries           Convenience API for time series stack
periods                         installed  1.2.3       TIME   -ds---  PostgreSQL    PGDG     13-18  postgresql-18-periods                 Provide Standard SQL functionality for PERIODs and SYSTEM VERSIO
temporal_tables                 installed  1.2.2       TIME   -ds--r  BSD 2-Clause  PIGSTY   13-18  postgresql-18-temporal-tables         temporal tables
.........
pg_fact_loader                  not avail  2.0.1       ETL    -ds--x  MIT           PGDG     13-17  postgresql-18-pg-fact-loader          build fact tables with Postgres
pg_bulkload                     installed  3.1.23      ETL    bds---  BSD 3-Clause  PIGSTY   13-18  postgresql-18-pg-bulkload             pg_bulkload is a high speed data loading utility for PostgreSQL
test_decoding                   available  -           ETL    --s--x  PostgreSQL    CONTRIB  13-18  postgresql-18                         SQL-based test/example module for WAL logical decoding
pgoutput                        available  -           ETL    --s---  PostgreSQL    CONTRIB  13-18  postgresql-18                         Logical Replication output plugin


(450 Rows) (Status: installed, available, not avail | Flags: b = HasBin, d = HasDDL, s = HasLib, l = NeedLoad, t = Trusted, r = Relocatable, x = Unknown)

All extension metadata is defined in a data file named extension.csv. This file is updated with each pig release. You can update it directly using the pig ext reload command. The updated file is placed in ~/.pig/extension.csv by default. You can view and modify it, and you can also find the authoritative version in the project.

Add Repositories

To install extensions, you first need to add upstream repositories. pig repo can be used to manage Linux APT/YUM/DNF software repository configuration.

You can use the straightforward pig repo set to overwrite existing repository configuration, ensuring only necessary repositories exist in the system:

pig repo set                # One-time setup for all repos including Linux system, PGDG, PIGSTY (PGSQL+INFRA)

Warning: pig repo set will back up and clear existing repository configuration, then add required repositories with overwrite semantics.

Or choose the gentler pig repo add to add needed repositories:

pig repo add pgdg pigsty     # Add PGDG official repo and PIGSTY supplementary repo
pig repo add pgsql           # [Optional] Add PGDG and PIGSTY together as one "pgsql" module
pig repo update              # Update cache: apt update / yum makecache

PIG detects your network environment and chooses Cloudflare global CDN or China cloud CDN, but you can force a specific region with --region:

pig repo set      --region=china              # use China mirror for faster downloads
pig repo add pgdg --region=default --update   # force PGDG upstream repo

PIG does not support offline installation. You can download RPM/DEB packages yourself and copy them to isolated servers for installation. The related PIGSTY project provides local software repositories. You can use pig to install pre-downloaded extensions from local repos.

Install PG

After adding repositories, you can use pig ext add to install extensions (and related packages):

pig ext add -v 18 -y pgsql timescaledb postgis vector pg_duckdb pg_mooncake # install PG 18 kernel and extensions, auto-confirm

# This command will translate aliases to actual packages
INFO[20:34:44] translate alias 'pgsql' to package: postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl
INFO[20:34:44] translate extension 'timescaledb' to package: timescaledb-tsl_18
INFO[20:34:44] translate extension 'postgis' to package: postgis36_18
INFO[20:34:44] translate extension 'vector' to package: pgvector_18
INFO[20:34:44] translate extension 'pg_duckdb' to package: pg_duckdb_18
INFO[20:34:44] translate extension 'pg_mooncake' to package: pg_mooncake_18
INFO[20:34:44] installing packages: dnf install -y postgresql18 postgresql18-server postgresql18-libs postgresql18-contrib postgresql18-plperl postgresql18-plpython3 postgresql18-pltcl timescaledb-tsl_18 postgis36_18 pgvector_18 pg_duckdb_18 pg_mooncake_18

This uses the “alias translation” mechanism to map clean PG kernel/extension logical names into real RPM/DEB lists. If you do not need translation, use apt/dnf directly, or use the -n|--no-translation option with the pig install variant:

pig install vector     # with translation, installs pgvector_18 or postgresql-18-pgvector for current PG 18
pig install vector -n  # no translation, installs a component named vector (from pigsty-infra repo)

Alias Translation

PostgreSQL kernels and extensions map to many RPM/DEB packages. Remembering them is painful, so pig provides common aliases to simplify installation.

For example, on EL systems the following aliases translate to the RPM lists on the right:

pgsql:        "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl"
pg18:         "postgresql18 postgresql18-server postgresql18-libs postgresql18-contrib postgresql18-plperl postgresql18-plpython3 postgresql18-pltcl"
pg18-client:  "postgresql18"
pg18-server:  "postgresql18-server postgresql18-libs postgresql18-contrib"
pg18-devel:   "postgresql18-devel"
pg18-basic:   "pg_repack_18 wal2json_18 pgvector_18"
pg17-mini:    "postgresql17 postgresql17-server postgresql17-libs postgresql17-contrib"
pg16-full:    "postgresql16 postgresql16-server postgresql16-libs postgresql16-contrib postgresql16-plperl postgresql16-plpython3 postgresql16-pltcl postgresql16-llvmjit postgresql16-test postgresql16-devel"
pg15-main:    "postgresql15 postgresql15-server postgresql15-libs postgresql15-contrib postgresql15-plperl postgresql15-plpython3 postgresql15-pltcl pg_repack_15 wal2json_15 pgvector_15"
pg14-core:    "postgresql14 postgresql14-server postgresql14-libs postgresql14-contrib postgresql14-plperl postgresql14-plpython3 postgresql14-pltcl"

Note the $v placeholder is replaced by the PG major version. When you use the pgsql alias, $v becomes 18, 17, etc. So when you install the pg18-server alias, EL actually installs postgresql18-server, postgresql18-libs, postgresql18-contrib, while Debian/Ubuntu installs postgresql-18. Pig handles all details.

Common PostgreSQL Aliases

Alias translation list for EL

"pgsql":        "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl",
"pgsql-mini":   "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib",
"pgsql-core":   "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl",
"pgsql-full":   "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl postgresql$v-llvmjit postgresql$v-test postgresql$v-devel",
"pgsql-main":   "postgresql$v postgresql$v-server postgresql$v-libs postgresql$v-contrib postgresql$v-plperl postgresql$v-plpython3 postgresql$v-pltcl pg_repack_$v wal2json_$v pgvector_$v",
"pgsql-client": "postgresql$v",
"pgsql-server": "postgresql$v-server postgresql$v-libs postgresql$v-contrib",
"pgsql-devel":  "postgresql$v-devel",
"pgsql-basic":  "pg_repack_$v wal2json_$v pgvector_$v",

Alias translation list for Debian/Ubuntu

"pgsql":        "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v",
"pgsql-mini":   "postgresql-$v postgresql-client-$v",
"pgsql-core":   "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v",
"pgsql-full":   "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v postgresql-server-dev-$v",
"pgsql-main":   "postgresql-$v postgresql-client-$v postgresql-plpython3-$v postgresql-plperl-$v postgresql-pltcl-$v postgresql-$v-repack postgresql-$v-wal2json postgresql-$v-pgvector",
"pgsql-client": "postgresql-client-$v",
"pgsql-server": "postgresql-$v",
"pgsql-devel":  "postgresql-server-dev-$v",
"pgsql-basic":  "postgresql-$v-repack postgresql-$v-wal2json postgresql-$v-pgvector",

These aliases can be instantiated with major versions, or you can use versioned aliases like pg18, pg17, etc. For example, for PostgreSQL 18 you can use:

pgsqlpg18pg17pg16pg15pg14pg13
pgsqlpg18pg17pg16pg15pg14pg13
pgsql-minipg18-minipg17-minipg16-minipg15-minipg14-minipg13-mini
pgsql-corepg18-corepg17-corepg16-corepg15-corepg14-corepg13-core
pgsql-fullpg18-fullpg17-fullpg16-fullpg15-fullpg14-fullpg13-full
pgsql-mainpg18-mainpg17-mainpg16-mainpg15-mainpg14-mainpg13-main
pgsql-clientpg18-clientpg17-clientpg16-clientpg15-clientpg14-clientpg13-client
pgsql-serverpg18-serverpg17-serverpg16-serverpg15-serverpg14-serverpg13-server
pgsql-develpg18-develpg17-develpg16-develpg15-develpg14-develpg13-devel
pgsql-basicpg18-basicpg17-basicpg16-basicpg15-basicpg14-basicpg13-basic

Install Extensions

Pig detects your PostgreSQL installation. If there is an active PG installation (detected via pg_config in PATH), pig installs extensions for that PG major by default.

pig install pg_smtp_client          # simplest
pig install pg_smtp_client -v 18    # specify major version (more stable)
pig install pg_smtp_client -p /usr/lib/postgresql/16/bin/pg_config   # another way to target PG

dnf install pg_smtp_client_18       # most direct, but not all extensions are that simple

Tip: to add a specific PG major version into PATH, use pig ext link:

pig ext link pg18             # create /usr/pgsql symlink and write /etc/profile.d/pgsql.sh
. /etc/profile.d/pgsql.sh     # take effect now and update PATH

If you want a specific package version, use name=ver syntax:

pig ext add -v 17 pgvector=0.7.2 # install pgvector 0.7.2 for PG 17
pig ext add pg16=16.5            # install PostgreSQL 16 with a specific minor version

Warning: currently only PGDG YUM repositories provide historical extension versions. PIGSTY repo and PGDG APT repo only provide the latest extension versions.

Show Extensions

pig ext status shows installed extensions.

$ pig ext status

Installed:
- PostgreSQL 18.1 (Ubuntu 18.1-1.pgdg24.04+2)  398 Extensions

Active:
PG Version      :  PostgreSQL 18.1 (Ubuntu 18.1-1.pgdg24.04+2)
Config Path     :  /usr/bin/pg_config
Binary Path     :  /usr/lib/postgresql/18/bin
Library Path    :  /usr/lib/postgresql/18/lib
Extension Path  :  /usr/share/postgresql/18/extension
Extension Stat  :  329 Installed (PIGSTY 234, PGDG 95) + 69 CONTRIB = 398 Total

Name                          Version  Cate  Flags   License     Repo    Package                               Description
----                          -------  ----  ------  -------     ------  ------------                          ---------------------
timescaledb                   2.24.0   TIME  -dsl--  Timescale   PIGSTY  postgresql-18-timescaledb-tsl         Enables scalable inserts and complex queries for time-series dat
timescaledb_toolkit           1.22.0   TIME  -ds-t-  Timescale   PIGSTY  postgresql-18-timescaledb-toolkit     Library of analytical hyperfunctions, time-series pipelining, an
timeseries                    0.2.0    TIME  -d----  PostgreSQL  PIGSTY  postgresql-18-pg-timeseries           Convenience API for time series stack
periods                       1.2.3    TIME  -ds---  PostgreSQL  PGDG    postgresql-18-periods                 Provide Standard SQL functionality for PERIODs and SYSTEM VERSIO
temporal_tables               1.2.2    TIME  -ds--r  BSD 2-Clause PIGSTY postgresql-18-temporal-tables         temporal tables
postgis                       3.6.1    GIS   -ds---  GPL-2.0     PGDG    postgresql-18-postgis-3               PostGIS geometry and geography spatial types and functions
postgis_topology              3.6.1    GIS   -ds---  GPL-2.0     PGDG    postgresql-18-postgis-3               PostGIS topology spatial types and functions
postgis_raster                3.6.1    GIS   -ds---  GPL-2.0     PGDG    postgresql-18-postgis-3               PostGIS raster types and functions
vector                        0.8.1    RAG   -ds--r  PostgreSQL  PGDG    postgresql-18-pgvector                vector data type and ivfflat and hnsw access methods
pg_duckdb                     1.1.0    OLAP  -dsl--  MIT         PIGSTY  postgresql-18-pg-duckdb               DuckDB Embedded in Postgres

If PostgreSQL cannot be found in your current PATH (via pg_config), it is recommended to explicitly specify PG major with -v|-p to avoid version detection ambiguity.

Scan Extensions

pig ext scan provides a lower-level scan. It scans shared libraries under the target PG directory to discover installed extensions:

$ pig ext scan

Installed:
- PostgreSQL 18.1 (Ubuntu 18.1-1.pgdg24.04+2)  398 Extensions

Active:
PG Version      :  PostgreSQL 18.1 (Ubuntu 18.1-1.pgdg24.04+2)
Config Path     :  /usr/bin/pg_config
Binary Path     :  /usr/lib/postgresql/18/bin
Library Path    :  /usr/lib/postgresql/18/lib
Extension Path  :  /usr/share/postgresql/18/extension

Name                 Version  SharedLibs                                       Description                       Meta
----                 -------  ----------                                       ---------------------             ------
timescaledb          2.24.0   Enables scalable inserts and complex queries...  module_pathname=$libdir/timescaledb-2.24.0 relocatable=false trusted=true lib=...
timescaledb_toolkit  1.22.0   Library of analytical hyperfunctions...          relocatable=false superuser=false module_pathname=$libdir/timescaledb_toolkit lib=...
periods              1.2      Provide Standard SQL functionality for PERIODs   module_pathname=$libdir/periods relocatable=false requires=btree_gist lib=periods.so
pg_cron              1.6      Job scheduler for PostgreSQL                     relocatable=false schema=pg_catalog module_pathname=$libdir/pg_cron lib=pg_cron.so
postgis              3.6.1    PostGIS geometry and geography spatial types...  module_pathname=$libdir/postgis-3 relocatable=false lib=postgis-3.so
vector               0.8.1    vector data type and ivfflat and hnsw access...  relocatable=true lib=vector.so
pg_duckdb            1.1.0    DuckDB Embedded in Postgres                      module_pathname=$libdir/pg_duckdb relocatable=false schema=public lib=...
...

Container Practice

You can create a new VM or use the following Docker container for testing. Create a d13 directory and a Dockerfile:

FROM debian:13
USER root
WORKDIR /root/
CMD ["/bin/bash"]

RUN apt update && apt install -y ca-certificates curl && curl https://repo.pigsty.io/pig | bash

docker build -t d13:latest .
docker run -it d13:latest /bin/bash

pig repo set --region=china    # add China region repos
pig install -y pg18            # install PGDG 18 kernel packages
pig install -y postgis timescaledb pgvector pg_duckdb

Last Modified 2026-02-14: docs(juice): refine JuiceFS config semantics and metric names (0510c97)