This document provides a comprehensive introduction to Pigsty, explaining what it is, its design philosophy, architecture, and core concepts. It serves as the entry point for understanding how Pigsty works as a system. For detailed installation instructions, see Installation Guide. For hands-on tutorials, see Quick Start Tutorial.
Pigsty is an enterprise-grade, open-source PostgreSQL distribution that provides a complete battery-included solution for self-hosting PostgreSQL databases with high availability, point-in-time recovery, infrastructure as code, and comprehensive monitoring.
Pigsty Positioning
| Aspect | Description |
|---|---|
| Product Type | PostgreSQL Distribution (like PGDG, but with more) |
| Deployment Model | Self-hosted on bare Linux (x86_64/aarch64) |
| Core Technology | PostgreSQL + Patroni + ETCD + Victoria + Grafana |
| Target Users | Developers, DBAs, DevOps engineers, SMBs |
| Alternative To | Cloud RDS services, manual PostgreSQL setup |
| Key Differentiator | 460+ extensions, 12 kernels, full observability, one-command deploy |
The acronym PIGSTY stands for: PostgreSQL Infrastructure with Graphics, Service, Toolbox—it's all Yours.
Sources: README.md1-76 pigsty.yml1-21
Pigsty is built on the following core principles:
Pigsty comes with everything needed to run production PostgreSQL: 460+ extensions pre-compiled and packaged, 12 PostgreSQL kernel variants (including PostgreSQL, Citus, Babelfish, IvorySQL, PolarDB, etc.), complete monitoring stack, backup tools, connection pooling, load balancing, and DNS resolution.
Key Components:
The system is organized into independent, composable modules:
Each module is managed by an Ansible playbook (e.g., infra.yml, pgsql.yml) and can be deployed independently or together.
All infrastructure is described declaratively in a single configuration file: pigsty.yml. The system reads this configuration and materializes the desired state.
Every component is instrumented with metrics exporters. The Victoria monitoring stack collects, stores, and visualizes all metrics, logs, and traces. 150+ pre-built Grafana dashboards provide instant visibility.
Pigsty runs on bare Linux without requiring Docker or Kubernetes. It maintains its own package repository and can operate completely offline, making it suitable for air-gapped environments.
Sources: README.md26-36 Makefile1-100 roles/infra/defaults/main.yml1-50
Pigsty is organized into distinct layers, each serving a specific purpose:
| Component | Purpose | Location in Code |
|---|---|---|
configure script | Environment detection & config generation | configure1-60 |
bootstrap script | Package repo setup & Ansible installation | bootstrap1-100 |
deploy.yml playbook | Main deployment orchestration | pigsty.yml1-21 |
pigsty.yml config | Central configuration database | pigsty.yml22-220 |
roles/infra/ | Infrastructure service management | roles/infra/defaults/main.yml1-184 |
roles/pgsql/ | PostgreSQL cluster management | Referenced in playbooks |
files/grafana/ | Dashboard definitions | bin/release46 |
files/victoria/ | Monitoring rules & configs | bin/release46 |
Sources: README.md197-217 configure1-60 bootstrap1-100
Pigsty's functionality is organized into modules, each responsible for a specific aspect of the system.
The INFRA module provides foundational infrastructure services:
Configuration Variables:
version: Pigsty version string (e.g., v4.2.1)admin_ip: Admin node IP addressregion: Upstream mirror region (default, china, europe)nginx_enabled: Enable/disable Nginxvmetrics_enabled: Enable/disable VictoriaMetricsgrafana_enabled: Enable/disable GrafanaThe NODE module handles host-level initialization and monitoring:
node_exporter (port 9100), vector (port 9598)The PGSQL module manages PostgreSQL database clusters:
The ETCD module provides distributed consensus:
| Module | Purpose | Playbook |
|---|---|---|
| MINIO | S3-compatible object storage for backups | minio.yml |
| REDIS | Cache clusters (standalone, sentinel, cluster) | redis.yml |
| DOCKER | Container runtime for stateless apps | docker.yml |
| FERRET | MongoDB wire protocol via FerretDB | mongo.yml |
| JUICE | Distributed filesystem via JuiceFS | juice.yml |
| VIBE | Development environment (VS Code, Jupyter) | vibe.yml |
Sources: README.md203-233 roles/infra/defaults/main.yml1-184 Makefile142-216
Pigsty uses a hierarchical YAML configuration stored in pigsty.yml:
Variable Hierarchy (precedence from highest to lowest):
-e)hosts)vars under cluster)all.vars)roles/*/defaults/main.yml)Pigsty provides 50+ pre-built configuration templates in conf/:
| Category | Templates | Purpose |
|---|---|---|
| Main | meta.yml, slim.yml, rich.yml | Single-node configurations |
| HA | dual.yml, trio.yml, full.yml | Multi-node HA setups |
| App | supabase.yml, odoo.yml, nocodb.yml | Application templates |
| Build | oss.yml, pro.yml, v17.yml, v18.yml | Build matrix configs |
| Demo | Various module demos | Testing & examples |
The configure Script:
pigsty.yml from templates with environment detectioncheck_ipaddr(): Detect primary IP address configure368-445check_region(): Determine mirror region (default/china/europe) configure96-110check_version(): Validate PostgreSQL version configure116-137check_config(): Load template and generate final config configure578-671pigsty.yml with environment-specific valuesSources: pigsty.yml1-220 configure1-60 configure578-671
Pigsty installation follows a three-phase workflow:
Key Scripts:
| Script | Purpose | Key Functions |
|---|---|---|
bin/install (get) | Download Pigsty source | download_file() bin/install82-103 |
bootstrap | Setup repo & install Ansible | check_repo() bootstrap313-360 add_local_repo() bootstrap577-608 |
configure | Generate configuration | check_ipaddr() configure368-445 check_config() configure578-671 |
Core Playbooks:
| Playbook | Purpose | Modules Installed |
|---|---|---|
deploy.yml | Complete deployment | INFRA, NODE, ETCD, PGSQL |
infra.yml | Infrastructure services | Nginx, Victoria, Grafana, DNS |
node.yml | Node initialization | Packages, tuning, exporters |
etcd.yml | ETCD cluster | ETCD consensus service |
pgsql.yml | PostgreSQL cluster | Postgres, Patroni, PgBouncer, HAProxy |
The Makefile provides convenient shortcuts:
Sources: Makefile49-217 bootstrap1-100 configure1-671 bin/install1-160
Pigsty uses the Victoria stack for observability:
Key Configuration Variables:
vmetrics_enabled: Enable VictoriaMetrics roles/infra/defaults/main.yml65vmetrics_port: VictoriaMetrics port (8428) roles/infra/defaults/main.yml67vlogs_enabled: Enable VictoriaLogs roles/infra/defaults/main.yml73grafana_enabled: Enable Grafana roles/infra/defaults/main.yml105grafana_port: Grafana port (3000) roles/infra/defaults/main.yml106Pigsty includes 150+ pre-built Grafana dashboards organized by prefix:
| Prefix | Category | Examples |
|---|---|---|
pgsql-* | PostgreSQL | pgsql-cluster, pgsql-instance, pgsql-database |
node-* | Node/Host | node-overview, node-cluster |
infra-* | Infrastructure | infra-overview, infra-home |
redis-* | Redis | redis-overview, redis-cluster |
etcd-* | ETCD | etcd-overview, etcd-cluster |
Sources: roles/infra/defaults/main.yml63-123 README.md30
Pigsty implements a sophisticated HA architecture for PostgreSQL:
HA Configuration Variables:
pg_cluster: Cluster identifier pigsty.yml39pg_role: Instance role (primary, replica, offline) pigsty.yml35-37pg_seq: Instance sequence number pigsty.yml35-37pg_vip_enabled: Enable VIP management pigsty.yml64pg_vip_address: Virtual IP address pigsty.yml65patroni_port: Patroni API port (8008) roles/infra/defaults/main.yml159etcd_port: ETCD client port (2379) roles/infra/defaults/main.yml145HA Features:
Sources: pigsty.yml33-67 roles/infra/defaults/main.yml145-172
Pigsty maintains a local package repository for offline installation:
Repository Categories:
| Category | Packages | Purpose |
|---|---|---|
node-bootstrap | ansible, python3, utils | Bootstrap tools |
node-package | system tools, monitoring | Node utilities |
infra-package | grafana, victoria, nginx | Infrastructure services |
pgsql-main | postgresql-server, libs | PostgreSQL core |
pg18-* | Extensions for PG 18 | postgis, pgvector, timescaledb, etc. |
Bootstrap Script Functions:
check_repo(): Detect and extract offline packages bootstrap313-360add_local_repo(): Configure local repository bootstrap577-608add_upstream_repo(): Add internet mirrors bootstrap641-690Repository Configuration:
/tmp/pkg.tgz/www/pigsty/default, china, europeSources: bootstrap313-690 Makefile145-176
Pigsty supports 460+ PostgreSQL extensions across 12 kernel variants. Extensions are organized by category:
| Category | Key Extensions |
|---|---|
| GIS | postgis, h3, geoip |
| Vector | pgvector, pgvectorscale |
| Time-series | timescaledb, timeseries |
| Full-text | zhparser, pg_search |
| Analytics | duckdb_fdw, parquet_s3_fdw |
| Graph | age, apache-age |
| Language | plpython3u, plpgsql, plperl |
| Utilities | pg_stat_statements, pg_cron, pgaudit |
Extension Management:
Sources: pigsty.yml42 pigsty.yml56 README.md71-73
Pigsty supports multiple Linux distributions and architectures:
| Distribution | Versions | Package Format |
|---|---|---|
| Enterprise Linux | 7, 8, 9, 10 (Rocky, RHEL, CentOS) | RPM (yum/dnf) |
| Debian | 11, 12, 13 | DEB (apt) |
| Ubuntu | 20.04, 22.04, 24.04 | DEB (apt) |
| Architecture | x86_64 (amd64), aarch64 (arm64) | Both |
Detection Logic:
Sources: configure239-260 bootstrap169-231 README.md79-84
To get started with Pigsty:
Download and Extract:
Bootstrap (setup repo and Ansible):
Configure (generate pigsty.yml):
Deploy (install everything):
After deployment, access:
http://admin_ip:3000 (admin/pigsty)postgres://admin_ip:5432/postgreshttp://admin_ip or http://i.pigstyFor detailed installation steps, see Installation Guide. For a hands-on tutorial, see Quick Start Tutorial. For system architecture details, see System Architecture.
Sources: README.md86-106 bin/install1-160 Makefile53-60
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.