Pigsty

https://pigsty.io/docs/
Admin
Pigsty is an open-source, infrastructure-as-code platform designed for deploying, managing, and...
Tokens:957,436
Snippets:12,515
Trust Score:8.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Pigsty Quick Start Installation Steps

Source: https://pigsty.io/docs/pig/sty

A simplified sequence of commands to quickly bootstrap and deploy Pigsty on the current node. This is a common workflow for initial setup.

```bash
pig sty init                     # install Pigsty to ~/pigsty
pig sty boot                     # install Ansible prerequisites
pig sty conf                     # generate configuration
pig sty deploy                   # run deployment playbook

```

--------------------------------

### Start Backup Quickly Example

Source: https://pigsty.io/docs/pgbackrest/command/backup

Force a checkpoint to start the backup immediately. Otherwise, the backup will start after the next regular checkpoint.

```bash
--start-fast
```

--------------------------------

### PIG Quick Start Commands

Source: https://pigsty.io/docs/pig

Demonstrates essential PIG commands for setting up repositories, installing PostgreSQL kernels, and installing extensions for a specific version or the active version. Use these commands after PIG installation to manage your PostgreSQL environment.

```bash
$ pig repo set                        # One-time setup for Linux, Pigsty + PGDG repos (overwrites!)
$ pig install pg18                    # Install PostgreSQL 18 kernel (native PGDG packages)
$ pig install pg_duckdb -v 18         # Install pg_duckdb extension (for PG 18)
$ pig install -y postgis timescaledb  # Install multiple extensions for current active PG version
$ pig install -y vector               # You can use extension name (vector) or package name (pgvector)!
```

--------------------------------

### Quick Start: Build Citus Extension

Source: https://pigsty.io/docs/pig/build

A quick start example to build the `citus` extension. This involves setting up the build environment and then executing the package build command.

```bash
pig build spec
pig build pkg citus
```

--------------------------------

### Quick Start Installation

Source: https://pigsty.io/docs/pgsql/kernel/openhalo

Install Pigsty and deploy a MySQL-compatible cluster using the standard installation flow with the 'mysql' template.

```bash
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty;
./configure -c mysql    # Use MySQL (openHalo) template
./deploy.yml            # Install (change passwords in pigsty.yml before production use)
```

--------------------------------

### Quick Start Installation and Configuration

Source: https://pigsty.io/docs/app/hindsight

Installs Pigsty, configures Hindsight to use it, and deploys the application. Edit `pigsty.yml` to set domain, database password, and LLM settings before deployment.

```bash
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/hindsight
vi pigsty.yml                 # edit domain, database password, and LLM settings
./deploy.yml
./docker.yml
./app.yml
```

--------------------------------

### Install Pig and Setup Repositories

Source: https://pigsty.io/docs/pig/start

Installs PIG from Cloudflare, sets up PIG, Pigsty, and PGDG repositories, and installs PostgreSQL 18 with extensions.

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

--------------------------------

### Pig CLI Usage Examples

Source: https://pigsty.io/docs/pig/cmd

Demonstrates common usage patterns for adding repositories, installing PostgreSQL versions, and installing specific PostgreSQL extensions.

```bash
pig repo add -ru            # overwrite existing repo and update cache

```

```bash
pig install pg18            # install PostgreSQL 18 PGDG packages

```

```bash
pig install pg_duckdb       # install a specific PostgreSQL extension

```

```bash
pig install pgactive -v 18  # install extension for a specific PG version

```

--------------------------------

### Quick Start Installation

Source: https://pigsty.io/docs/pgsql/kernel/percona

Install Pigsty and configure it to use the Percona PostgreSQL kernel with TDE. This involves downloading the Pigsty installer and running the configuration and deployment commands.

```bash
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty;
./configure -c pgtde     # Use percona postgres kernel
./deploy.yml             # Set up everything with pigsty

```

--------------------------------

### Quick Start Installation and Configuration

Source: https://pigsty.io/docs/app/insforge

Follow these steps to quickly install and configure InsForge using Pigsty. Ensure you update the pigsty.yml file with your specific secrets and domain before deployment.

```bash
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/insforge
vi pigsty.yml                 # required: JWT_SECRET, admin password, database password, domain
./deploy.yml
./docker.yml
./app.yml
```

--------------------------------

### Complete Cluster Example Configuration

Source: https://pigsty.io/docs/pgsql/config/hba

A comprehensive example demonstrating cluster setup with multiple hosts, variables, and detailed HBA rules for blacklisting, whitelisting, ETL tasks, and monitoring, along with Pgbouncer rules.

```yaml
pg-prod:
  hosts:
    10.10.10.11: {pg_seq: 1, pg_role: primary}
    10.10.10.12: {pg_seq: 2, pg_role: replica}
    10.10.10.13: {pg_seq: 3, pg_role: offline}
  vars:
    pg_cluster: pg-prod

    pg_hba_rules:
      # Blacklist: known malicious IP (highest priority)
      - {user: all, db: all, addr: '10.1.1.100/32', auth: deny, order: 0, title: 'blacklist'}

      # App server whitelist (high priority)
      - {user: app_user, db: app_db, addr: '192.168.1.0/24', auth: ssl, order: 50, title: 'app servers'}

      # ETL tasks: offline instances only
      - {user: etl_user, db: all, addr: '172.20.0.0/16', auth: pwd, role: offline, title: 'etl tasks'}

      # Cluster internal monitoring
      - {user: '${monitor}', db: all, addr: cluster, auth: pwd, order: 380, title: 'cluster monitor'}

    pgb_hba_rules:
      # App via connection pool
      - {user: '+dbrole_readwrite', db: all, addr: '192.168.1.0/24', auth: ssl, title: 'app via pgbouncer'}
```

--------------------------------

### Pigsty Quick Start Deployment

Source: https://pigsty.io/docs/piglet

Execute these commands to install Pigsty, configure it for VIBE mode, and deploy the core infrastructure, JuiceFS, and VIBE components.

```bash
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./configure -c vibe -g # Use vibe mode, generate random passwords!
./deploy.yml           # Deploy infrastructure and PostgreSQL
./juice.yml            # Deploy JuiceFS filesystem
./vibe.yml             # Deploy Claude Code, Codex CLI, Code-Server, JupyterLab

```

--------------------------------

### Quick Start: Initialize and Build Extension

Source: https://pigsty.io/docs/pig/build

Initialize build specifications and then build an extension package using the complete pipeline. Built packages are placed in the ~/ext/pkg/ directory.

```bash
# 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/)
```

--------------------------------

### Install and Configure Supabase with Pigsty

Source: https://pigsty.io/docs/app/supabase

This snippet shows the commands to install Pigsty, configure it for Supabase, edit settings, and deploy the standard single-node setup. It also includes steps to install the Docker module and start Supabase components.

```bash
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./configure -c supabase    # Use supabase config (change credentials in pigsty.yml)
vi pigsty.yml              # Edit domain, passwords, keys...
./deploy.yml               # Standard single-node Pigsty deployment
./docker.yml               # Install Docker module
./app.yml                  # Start Supabase stateless components (may be slow)
```

--------------------------------

### Example Database Configurations

Source: https://pigsty.io/docs/pgbouncer/config

Illustrates how to specify connection strings for different databases, including host and port details.

```ini
foodb = host=host1.example.com port=5432
bardb = host=localhost dbname=bazdb
```

--------------------------------

### ETCD Initialization Examples

Source: https://pigsty.io/docs/etcd/param

Examples demonstrating how to initialize an ETCD cluster or add a new member to an existing one.

```bash
# Create new cluster (default behavior)
./etcd.yml

# Add new member to existing cluster
./etcd.yml -l <new_ip> -e etcd_init=existing

# Or use the convenience script (automatically sets etcd_init=existing)
bin/etcd-add <new_ip>

```

--------------------------------

### Quick Start PostgREST Deployment

Source: https://pigsty.io/docs/app/postgrest

Navigate to the PostgREST app directory, configure environment variables in .env, and start the service using make.

```bash
cd ~/pigsty/app/postgrest
vi .env         # check DB_URI / DB_SCHEMA / JWT
make up
```

--------------------------------

### Archive Get Async Command Log Output

Source: https://pigsty.io/docs/pgbackrest/user-guide

Example log output from the archive-get async command, showing process start, WAL file retrieval details, and command completion. This helps in understanding the command's operational flow and identifying potential issues.

```log
-------------------PROCESS START-------------------
P00   INFO: archive-get:async command begin 2.58.0: [000000070000000000000024, 000000070000000000000025, 000000070000000000000026, 000000070000000000000027, 000000070000000000000028, 000000070000000000000029, 00000007000000000000002A, 00000007000000000000002B] --archive-async --exec-id=1380-8760a6e0 --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/postgresql/16/demo --process-max=2 --repo1-host=repository --spool-path=/var/spool/pgbackrest --stanza=demo
P00   INFO: get 8 WAL file(s) from archive: 000000070000000000000024...00000007000000000000002B

P01 DETAIL: found 000000070000000000000024 in the repo1: 16-1 archive
P02 DETAIL: found 000000070000000000000025 in the repo1: 16-1 archive
P01 DETAIL: found 000000070000000000000026 in the repo1: 16-1 archive
P02 DETAIL: found 000000070000000000000027 in the repo1: 16-1 archive

P00 DETAIL: unable to find 000000070000000000000028 in the archive
P00   INFO: archive-get:async command end: completed successfully
       [filtered 14 lines of output]
P00   INFO: archive-get:async command begin 2.58.0: [000000070000000000000028, 000000070000000000000029, 00000007000000000000002A, 00000007000000000000002B, 00000007000000000000002C, 00000007000000000000002D, 00000007000000000000002E, 00000007000000000000002F] --archive-async --exec-id=1431-a78c4f0a --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/postgresql/16/demo --process-max=2 --repo1-host=repository --spool-path=/var/spool/pgbackrest --stanza=demo
P00   INFO: get 8 WAL file(s) from archive: 000000070000000000000028...00000007000000000000002F

P02 DETAIL: found 000000070000000000000029 in the repo1: 16-1 archive
P01 DETAIL: found 000000070000000000000028 in the repo1: 16-1 archive
P02 DETAIL: found 00000007000000000000002A in the repo1: 16-1 archive
P01 DETAIL: found 00000007000000000000002B in the repo1: 16-1 archive
P02 DETAIL: found 00000007000000000000002C in the repo1: 16-1 archive
P01 DETAIL: found 00000007000000000000002D in the repo1: 16-1 archive

P00 DETAIL: unable to find 00000007000000000000002E in the archive
P00   INFO: archive-get:async command end: completed successfully
       [filtered 11 lines of output]
```

--------------------------------

### Start PostgreSQL Service

Source: https://pigsty.io/docs/pgbackrest/user-guide-rhel

Use this command to start the PostgreSQL service on the primary node after installation or upgrade.

```bash
sudo systemctl start postgresql-14.service
```

--------------------------------

### Quick Start Deployment

Source: https://pigsty.io/docs/app/kong

Navigate to the Kong app directory, configure environment variables in .env, and run the make command to deploy Kong.

```bash
cd ~/pigsty/app/kong
vi .env         # check KONG_PG_* and port settings
make
```

--------------------------------

### Scan Installed Extensions

Source: https://pigsty.io/docs/pig/ext

Scan installed extensions for a specific PostgreSQL version, for example, version 18.

```bash
pig ext scan -v 18
```

--------------------------------

### Installing PostgreSQL Extensions

Source: https://pigsty.io/docs/pgsql/param

An example of how to specify PostgreSQL extensions to install. Multiple extensions can be listed on a single line, separated by spaces, or aliases can be used to install common sets of extensions.

```yaml
pg_extensions:
  - postgis timescaledb pgvector
  - pgsql-fdw     # use alias to install common FDWs at once

```

--------------------------------

### Quick Start Gitea Deployment

Source: https://pigsty.io/docs/app/gitea

Navigate to the Gitea app directory, configure the .env file for domain, ports, and database settings, and then start the deployment.

```bash
cd ~/pigsty/app/gitea
vi .env         # check domain, ports, database settings
make up
```

--------------------------------

### Install pg_exporter with Pigsty

Source: https://pigsty.io/docs/pg_exporter/install

Use this command to install pg_exporter via the Pigsty distribution, which simplifies setup by including Prometheus and Grafana.

```bash
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty;
```

--------------------------------

### Example: Create Backup

Source: https://pigsty.io/docs/pig/pb

Shows how to create a backup. If no previous backup exists, it creates a full backup; otherwise, it creates an incremental backup.

```bash
pig pb backup                    # auto: full if none, else incr
```

--------------------------------

### Install Ansible on MacOS

Source: https://pigsty.io/docs/setup/playbook

Installs Ansible using Homebrew and its dependency jmespath using pip on macOS. This setup is suitable for managing remote servers from a Mac.

```bash
brew install ansible
pip3 install jmespath

```

--------------------------------

### 20-Node Production Simulation Example

Source: https://pigsty.io/docs/deploy/install

This example demonstrates the Vagrant configuration and startup process for a 20-node production simulation, including PostgreSQL, metadata, proxy, and MinIO nodes. It uses Ubuntu 24.04 x86_64 images.

```json
                                                                                                                               # 6 x pgsql nodes                                                                                                            { "name" => "pg-src-1" , "ip" => "10.10.10.31" , "cpu" => "2" , "mem" => "4096"  ,  "image" => "bento/ubuntu-24.04"  },      { "name" => "pg-src-2" , "ip" => "10.10.10.32" , "cpu" => "2" , "mem" => "4096"  ,  "image" => "bento/ubuntu-24.04"  },      { "name" => "pg-src-3" , "ip" => "10.10.10.33" , "cpu" => "2" , "mem" => "4096"  ,  "image" => "bento/ubuntu-24.04"  },      { "name" => "pg-dst-1" , "ip" => "10.10.10.41" , "cpu" => "2" , "mem" => "4096"  ,  "image" => "bento/ubuntu-24.04"  },      { "name" => "pg-dst-2" , "ip" => "10.10.10.42" , "cpu" => "2" , "mem" => "4096"  ,  "image" => "bento/ubuntu-24.04"  },      { "name" => "pg-dst-3" , "ip" => "10.10.10.43" , "cpu" => "2" , "mem" => "4096"  ,  "image" => "bento/ubuntu-24.04"  },
                                                                                                                                 ]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   [INFO] write config to /data/pgsty/pigsty/vagrant/Vagrantfile                                                                cd vagrant && vagrant up                                                                                                     Bringing machine 'meta1' up with 'libvirt' provider...
                                                                       Bringing machine 'meta2' up with 'libvirt' provider...
                                                                       Bringing machine 'meta3' up with 'libvirt' provider...
                                                                       Bringing machine 'proxy1' up with 'libvirt' provider...
                                                                      Bringing machine 'proxy2' up with 'libvirt' provider...
                                                                      Bringing machine 'minio1' up with 'libvirt' provider...
                                                                      Bringing machine 'minio2' up with 'libvirt' provider...
                                                                      Bringing machine 'minio3' up with 'libvirt' provider...
                                                                      Bringing machine 'minio4' up with 'libvirt' provider...
                                                                      Bringing machine 'etcd1' up with 'libvirt' provider...
                                                                       Bringing machine 'etcd2' up with 'libvirt' provider...
                                                                       Bringing machine 'etcd3' up with 'libvirt' provider...
                                                                       Bringing machine 'etcd4' up with 'libvirt' provider...
                                                                       Bringing machine 'etcd5' up with 'libvirt' provider...
                                                                       Bringing machine 'pg-src-1' up with 'libvirt' provider...
                                                                    Bringing machine 'pg-src-2' up with 'libvirt' provider...
                                                                    Bringing machine 'pg-src-3' up with 'libvirt' provider...
                                                                    Bringing machine 'pg-dst-1' up with 'libvirt' provider...
                                                                    Bringing machine 'pg-dst-2' up with 'libvirt' provider...
                                                                    Bringing machine 'pg-dst-3' up with 'libvirt' provider...
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   
```

--------------------------------

### Finer Control: Environment Setup and Build Steps

Source: https://pigsty.io/docs/pig/build

Provides commands for detailed control over the build environment setup, including initializing specs, configuring repositories, installing tools, downloading sources, installing dependencies, and building packages. The 'pig build pkg citus' command combines these steps.

```bash
# 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
```

--------------------------------

### Slim Installation Steps

Source: https://pigsty.io/docs/setup/slim

Execute these commands to download Pigsty, configure it for slim installation using `slim.yml`, and then run the slim playbook.

```bash
curl https://repo.pigsty.io/get | bash
./configure -g -c slim
./slim.yml
```

--------------------------------

### Example: Create Full Backup

Source: https://pigsty.io/docs/pig/pb

Demonstrates how to explicitly create a full backup using the `pig pb backup full` command.

```bash
pig pb backup full               # full backup
```

--------------------------------

### Example Configure Wizard Output

Source: https://pigsty.io/docs/deploy/install

This output shows the interactive process of the `configure` wizard, including environment detection, IP address candidate selection, and a reminder to check and change passwords.

```text
vagrant@meta:~/pigsty$ ./configure
configure pigsty v4.3.0 begin
[ OK ] region = china
[ OK ] kernel  = Linux
[ OK ] machine = x86_64
[ OK ] package = deb,apt
[ OK ] vendor  = ubuntu (Ubuntu)
[ OK ] version = 22 (22.04)
[ OK ] sudo = vagrant ok
[ OK ] ssh = vagrant@127.0.0.1 ok
[WARN] Multiple IP address candidates found:
    (1) 192.168.121.38	    inet 192.168.121.38/24 metric 100 brd 192.168.121.255 scope global dynamic eth0
    (2) 10.10.10.10	    inet 10.10.10.10/24 brd 10.10.10.255 scope global eth1
[ OK ] primary_ip = 10.10.10.10 (from demo)
[ OK ] admin = vagrant@10.10.10.10 ok
[ OK ] mode = meta (ubuntu22.04)
[ OK ] locale  = C.UTF-8
[ OK ] ansible = ready
[ OK ] pigsty configured
[WARN] don't forget to check it and change passwords!
proceed with ./deploy.yml

```

--------------------------------

### Multi-Core PgBouncer Setup (Process 1)

Source: https://pigsty.io/docs/pgbouncer/config

Configuration for the first PgBouncer process in a multi-core setup using `so_reuseport`. This example defines database connections and peer settings.

```ini
[databases]
postgres = host=localhost dbname=postgres

[peers]
1 = host=/tmp/pgbouncer1
2 = host=/tmp/pgbouncer2

[pgbouncer]
listen_addr=127.0.0.1
auth_file=auth_file.conf
so_reuseport=1
unix_socket_dir=/tmp/pgbouncer1
peer_id=1

```

--------------------------------

### Quick Start Deployment Commands

Source: https://pigsty.io/docs/app/registry

Commands to bootstrap Pigsty, configure the registry application, update configuration, and deploy the application.

```bash
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/registry
vi pigsty.yml                 # update domains, certs, and ports if needed
./deploy.yml
./docker.yml
./app.yml
```

--------------------------------

### Build a Standard Extension

Source: https://pigsty.io/docs/pig/build

Steps to set up the build environment, build a standard extension package, and install it.

```bash
# 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
```

--------------------------------

### Example: Show Backup Info

Source: https://pigsty.io/docs/pig/pb

Demonstrates how to display all backup information using the `pig pb info` command.

```bash
pig pb info                      # show all backup info
```

--------------------------------

### Slim Installation Configuration File

Source: https://pigsty.io/docs/conf/slim

This is the main configuration file for the slim installation. It defines the cluster setup, including etcd and PostgreSQL configurations, users, databases, and HBA rules.

```yaml
---
#==============================================================#
# File      :   slim.yml
# Desc      :   Pigsty slim installation config template
# Ctime     :   2020-05-22
# Mtime     :   2025-12-28
# Docs      :   https://pigsty.io/docs/conf/slim
# License   :   Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright :   2018-2026  Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#

# This is the config template for slim / minimal installation
# No monitoring & infra will be installed, just raw postgresql
#
# Usage:
#   curl https://repo.pigsty.io/get | bash
#   ./configure -c slim
#   ./slim.yml

all:
  children:

    etcd: # dcs service for postgres/patroni ha consensus
      hosts: # 1 node for testing, 3 or 5 for production
        10.10.10.10: { etcd_seq: 1 }  # etcd_seq required
        #10.10.10.11: { etcd_seq: 2 }  # assign from 1 ~ n
        #10.10.10.12: { etcd_seq: 3 }  # odd number please
      vars: # cluster level parameter override roles/etcd
        etcd_cluster: etcd  # mark etcd cluster name etcd

    #----------------------------------------------#
    # PostgreSQL Cluster
    #----------------------------------------------#
    pg-meta:
      hosts:
        10.10.10.10: { pg_seq: 1, pg_role: primary }
        #10.10.10.11: { pg_seq: 2, pg_role: replica } # you can add more!
        #10.10.10.12: { pg_seq: 3, pg_role: replica, pg_offline_query: true }
      vars:
        pg_cluster: pg-meta
        pg_users:
          - { name: dbuser_meta ,password: DBUser.Meta   ,pgbouncer: true ,roles: [dbrole_admin   ] ,comment: pigsty admin user }
          - { name: dbuser_view ,password: DBUser.Viewer ,pgbouncer: true ,roles: [dbrole_readonly] ,comment: read-only viewer  }
        pg_databases:
          - { name: meta, baseline: cmdb.sql ,comment: pigsty meta database ,schemas: [pigsty] ,extensions: [ vector ]}
        pg_hba_rules:   # https://pigsty.io/docs/pgsql/config/hba
          - { user: all ,db: all ,addr: intra ,auth: pwd ,title: 'everyone intranet access with password' ,order: 800 }
        pg_crontab:     # https://pigsty.io/docs/pgsql/admin/crontab
          - '00 01 * * * /pg/bin/pg-backup full'

  vars:
    version: v4.3.0                   # pigsty version string
    admin_ip: 10.10.10.10             # admin node ip address
    region: default                   # upstream mirror region: default,china,europe
    nodename_overwrite: false           # do not overwrite node hostname on single node mode
    node_repo_modules: node,infra,pgsql # add these repos directly to the singleton node
    node_tune: oltp                     # node tuning specs: oltp,olap,tiny,crit
    pg_conf: oltp.yml                   # pgsql tuning specs: {oltp,olap,tiny,crit}.yml
    pg_version: 18                      # Default PostgreSQL Major Version is 18
    pg_packages: [ pgsql-main, pgsql-common ]   # pg kernel and common utils
    #pg_extensions: [ pg18-time ,pg18-gis ,pg18-rag ,pg18-fts ,pg18-olap ,pg18-feat ,pg18-lang ,pg18-type ,pg18-util ,pg18-func ,pg18-admin ,pg18-stat ,pg18-sec ,pg18-fdw ,pg18-sim ,pg18-etl]

    #----------------------------------------------#
    # PASSWORD : https://pigsty.io/docs/setup/security/
    #----------------------------------------------#
    grafana_admin_password: pigsty
    grafana_view_password: DBUser.Viewer
    pg_admin_password: DBUser.DBA
    pg_monitor_password: DBUser.Monitor
    pg_replication_password: DBUser.Replicator
    patroni_password: Patroni.API
    haproxy_admin_password: pigsty
    minio_secret_key: S3User.MinIO
    etcd_root_password: Etcd.Root
...

```

--------------------------------

### Start Bytebase Application

Source: https://pigsty.io/docs/app/bytebase

Navigate to the Bytebase app directory and start the application using make. Ensure to check the .env file for configuration like BB_PORT, BB_DOMAIN, and BB_PGURL before starting.

```shell
cd ~/pigsty/app/bytebase
vi .env         # check BB_PORT / BB_DOMAIN / BB_PGURL
make up
```

--------------------------------

### Install Docker Runtime with Pigsty

Source: https://pigsty.io/docs/pilot/kube

Installs Docker CE and Docker Compose plugin using Pigsty. This requires manual setup of the cri-dockerd bridge component if Docker is used as the runtime.

```bash
./node.yml -t node_install -e '{"node_repo_modules":"node,infra","node_packages":["docker-ce,docker-compose-plugin"]}'
```

--------------------------------

### Start Patroni Cluster Components

Source: https://pigsty.io/docs/patroni/readme

Initiates the etcd distributed consensus store and starts two Patroni instances for a PostgreSQL HA cluster. Ensure you have the Patroni repository cloned or installed locally.

```bash
> etcd --data-dir=data/etcd --enable-v2=true
> ./patroni.py postgres0.yml
> ./patroni.py postgres1.yml
```

--------------------------------

### Example Peer Configurations

Source: https://pigsty.io/docs/pgbouncer/config

Illustrates how to configure two different peers using their respective IDs and connection strings, one using a host and the other a Unix socket.

```ini
1 = host=host1.example.com
2 = host=/tmp/pgbouncer-2  port=5555
```

--------------------------------

### Rich Configuration File Example

Source: https://pigsty.io/docs/conf/rich

An example of the 'rich.yml' configuration file, detailing settings for a feature-rich single-node Pigsty installation. This includes cluster definitions, node roles, and PostgreSQL extension configurations.

```yaml
---
#==============================================================#
# File      :   rich.yml
# Desc      :   Pigsty feature-rich 1-node online install config
# Ctime     :   2020-05-22
# Mtime     :   2025-12-12
# Docs      :   https://pigsty.io/docs/conf/rich
# License   :   Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright :   2018-2026  Ruohang Feng / Vonng (rh@vonng.com)
#==============================================================#

# This is the enhanced version of default meta.yml, which has:
# - almost all available postgres extensions
# - build local software repo for entire env
# - 1 node minio used as central backup repo
# - cluster stub for 3-node pg-test / ferret / redis
# - stub for nginx, certs, and website self-hosting config
# - detailed comments for database / user / service
#
# Usage:
#   curl https://repo.pigsty.io/get | bash
#   ./configure -c rich
#   ./deploy.yml

all:

  #==============================================================#
  # Clusters, Nodes, and Modules
  #==============================================================#
  children:

    #----------------------------------------------#
    # PGSQL : https://pigsty.io/docs/pgsql
    #----------------------------------------------#
    # this is an example single-node postgres cluster with pgvector installed, with one biz database & two biz users
    pg-meta:
      hosts:
        10.10.10.10: { pg_seq: 1, pg_role: primary } # <---- primary instance with read-write capability
        #x.xx.xx.xx: { pg_seq: 2, pg_role: replica } # <---- read only replica for read-only online traffic
        #x.xx.xx.xy: { pg_seq: 3, pg_role: offline } # <---- offline instance of ETL & interactive queries
      vars:
        pg_cluster: pg-meta

        # install, load, create pg extensions: https://pigsty.io/docs/pgsql/ext/
        pg_extensions: [ postgis, timescaledb, pgvector, pg_wait_sampling ]
        pg_libs: 'timescaledb, pg_stat_statements, auto_explain, pg_wait_sampling'

```

--------------------------------

### Minio Configuration Example

Source: https://pigsty.io/docs/conf/meta

Example configuration for setting up Minio object storage, including host definitions, user credentials, and policies.

```yaml
#minio:
#  hosts:
#    10.10.10.10: { minio_seq: 1 }
#  vars:
#    minio_cluster: minio
#    minio_users:                      # list of minio user to be created
#      - { access_key: pgbackrest  ,secret_key: S3User.Backup ,policy: pgsql }
#      - { access_key: s3user_meta ,secret_key: S3User.Meta   ,policy: meta  }
#      - { access_key: s3user_data ,secret_key: S3User.Data   ,policy: data  }
```

--------------------------------

### Configure Extensions in Pigsty Variables

Source: https://pigsty.io/docs/pgsql/admin/ext

Define the list of extensions to be installed in the `pg_extensions` variable within the `all.children.<cls>.vars` section of your Pigsty configuration. This allows for automatic installation during cluster setup.

```yaml
#all.children.pg-meta.vars:
pg_extensions: [ postgis, timescaledb, pgvector ]
```

--------------------------------

### Launch Pigsty with Docker (Step-by-step)

Source: https://pigsty.io/docs/setup/docker

Execute these commands sequentially to start the container, enter it, generate configuration, and deploy Pigsty. This allows for inspection at each stage. Navigate to the `~/pigsty/docker` directory first.

```bash
cd ~/pigsty/docker
make up              # Start container
make exec            # Enter container
./configure -c docker -g --ip 127.0.0.1  # Generate config (optional, pre-configured)
./deploy.yml         # Execute deployment
```

--------------------------------

### Example: Initialize Stanza

Source: https://pigsty.io/docs/pig/pb

Demonstrates the command to initialize a new pgBackRest stanza, typically used for first-time setup.

```bash
pig pb create                    # initialize stanza
```

--------------------------------

### Basic Node Package Configuration

Source: https://pigsty.io/docs/node/param

Example of configuring upstream repository, removal of existing repos, and specifying packages to install.

```yaml
node_repo_modules: local          # upstream repo to be added on node, local by default.
node_repo_remove: true            # remove existing repo on node?
node_packages: [openssh-server]   # packages to be installed current nodes with latest version
#node_default_packages:           # default packages to be installed on all nodes
```

--------------------------------

### Run Single-Node Trial Deployment

Source: https://pigsty.io/docs/sop

Execute the deployment script for a single-node trial setup. This is a starting point for testing Pigsty.

```bash
./configure -g
./deploy.yml
```

--------------------------------

### Build a Rust Extension

Source: https://pigsty.io/docs/pig/build

Instructions for setting up the Rust environment, building a Rust extension, and installing it.

```bash
# 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
```

--------------------------------

### Example Resource Configuration with Scaling

Source: https://pigsty.io/docs/deploy/vagrant

Illustrates how resource scaling affects the configuration, showing an example where default 2c4g is adjusted to 8c16g.

```ruby
Specs = [
  { "name" => "meta" , "ip" => "10.10.10.10", "cpu" => "8" , "mem" => "16384" , "image" => "cloud-image/ubuntu-24.04" },
]
```

--------------------------------

### Configure Replication Capacity

Source: https://pigsty.io/docs/pgsql/kernel/pgedge

Example pg_parameters for configuring logical replication capacity and unique node IDs for multi-master setups.

```yaml
pg_parameters:
  wal_level: logical
  max_replication_slots: 16
  max_wal_senders: 16
  'snowflake.node': 1

```

--------------------------------

### Define MinIO Cluster Configuration

Source: https://pigsty.io/docs/minio/usage

Configure a MinIO cluster in the inventory file. This example shows a single-node, single-disk setup.

```yaml
minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }
```

--------------------------------

### Configure Slim Installation

Source: https://pigsty.io/docs/conf/slim

Use this command to initiate the slim installation process. The configuration file `slim.yml` will be executed afterwards.

```bash
./configure -c slim [-i <primary_ip>]
./slim.yml   # Execute slim installation
```

--------------------------------

### pgBackRest Stanza Create Output

Source: https://pigsty.io/docs/pgbackrest/user-guide

Example output from the `pgbackrest stanza-create` command, indicating the start and successful completion of the stanza creation process.

```text
P00   INFO: stanza-create command begin 2.58.0: --exec-id=1060-8b7025bb --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/postgresql/16/demo --repo1-cipher-pass= --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --stanza=demo
P00   INFO: stanza-create for stanza 'demo' on repo1

P00   INFO: stanza-create command end: completed successfully
```

--------------------------------

### Install Pigsty and Configure Dify

Source: https://pigsty.io/docs/app/dify

This snippet shows the initial steps to set up Pigsty, configure it for Dify, and edit essential configuration parameters before deployment. Ensure you are on a compatible Linux server.

```bash
curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap                # Install Pigsty dependencies
./configure -c app/dify    # Use Dify configuration template
vi pigsty.yml              # Edit passwords, domains, keys, etc.

./deploy.yml               # Install Pigsty
./docker.yml               # Install Docker and Compose
./app.yml                  # Install Dify
```

--------------------------------

### Configure PostgreSQL Libraries and Extensions

Source: https://pigsty.io/docs/conf/debian

Specify shared preload libraries and extensions to be installed on the PostgreSQL cluster. This example adds `pg_stat_statements` and `auto_explain`.

```yaml
# define pg extensions: https://pigsty.io/docs/pgsql/ext/ 
pg_libs: 'pg_stat_statements, auto_explain' # add timescaledb to shared_preload_libraries
#pg_extensions: [] # extensions to be installed on this cluster
```

--------------------------------

### Example Host Configurations

Source: https://pigsty.io/docs/pgbouncer/config

Provides examples of valid 'host' values for peer connections, including localhost, IP addresses, IPv6 addresses, and Unix domain sockets.

```ini
host=localhost
host=127.0.0.1
host=2001:0db8:85a3:0000:0000:8a2e:0370:7334
host=/var/run/pgbouncer-1
```

--------------------------------

### Setup Node CA Certificate

Source: https://pigsty.io/docs/node/playbook

Use `./node.yml` with the `-t node_ca` task to install the node's Certificate Authority (CA) certificate.

```bash
./node.yml -t node_ca
```

--------------------------------

### Example Backup Info Output

Source: https://pigsty.io/docs/pgbackrest/user-guide-rhel

This is an example output from the `pgbackrest info` command, showing details for two full backups of the 'demo' stanza.

```text
stanza: demo
    status: ok
    cipher: none

    db (current) 
        wal archive min/max (13): 000000070000000000000023/000000070000000000000025

        full backup: 20260119-092306F

            timestamp start/stop: 2026-01-19 09:23:06+00 / 2026-01-19 09:23:08+00

            wal start/stop: 000000070000000000000023 / 000000070000000000000023
            database size: 30.8MB, database backup size: 30.8MB
            repo1: backup set size: 3.8MB, backup size: 3.8MB

        full backup: 20260119-092309F

            timestamp start/stop: 2026-01-19 09:23:09+00 / 2026-01-19 09:23:11+00

            wal start/stop: 000000070000000000000024 / 000000070000000000000025
            database size: 30.8MB, database backup size: 30.8MB
            repo1: backup set size: 3.8MB, backup size: 3.8MB


```

--------------------------------

### Configure UV Virtual Environment and Pip Packages

Source: https://pigsty.io/docs/node/param

Example of setting a UV virtual environment path and specifying pip packages to install within it.

```yaml
node_uv_env: /data/venv
node_pip_packages: 'ansible pgcli requests pandas'
```
Tokens:
Raw