Pigsty v5.0 Documentation

Sat, 11 Jan 2025 00:00:00 +0000

The Pigsty v5.0 documentation focuses on Pigsty itself: architecture, installation, deployment, configuration, operations, and the complete manual for every first-party module.

v5.0 Docs Preview OINK 0.6.0 Local First

Press ⌘+ with K on macOS, or Ctrl+ with K, to open offline search and the command palette anywhere on the site.

Get Started

About Pigsty

Learn about Pigsty’s features, architecture, design principles, use cases, and project background.

Features

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

“PostgreSQL In Great STYle”: Postgres, Infras, Graphics, Service, Toolbox, it’s all Yours.

—— Battery-included, local-first PostgreSQL distribution, open-source RDS alternative

Value Propositions

Extensibility: Powerful extensions out of the box: deep integration of PostGIS, TimescaleDB, Citus, PGVector, 575 plugins, and 12 PG kernels.
Reliability: Quickly create high-availability, self-healing PostgreSQL clusters with built-in point-in-time recovery, access control, a self-signed CA, and TLS.
Observability: Based on Prometheus & Grafana modern observability stack, providing stunning monitoring best practices. Modular design, can be used independently: Gallery & Demo.
Availability: Deliver stable, reliable, auto-routed, transaction-pooled, read-write separated high-performance database services, with flexible access modes via HAProxy, Pgbouncer, and VIP.
Maintainability: Easy to use, Infrastructure as Code, Management SOPs, auto-tuning, local software repository, Vagrant sandbox and Terraform templates, zero-downtime migration solutions.
Composability: Modular architecture design, reusable Infra, various optional modules: Redis, Silo object storage, ETCD, DuckDB, Docker, Supabase.

Overview

Pigsty is a better local open-source RDS for PostgreSQL alternative:

RPO Trade-offs

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

RPO (Recovery Point Objective) defines the maximum amount of data loss allowed when the primary fails.

For scenarios where data integrity is critical, such as financial transactions, RPO = 0 is typically required, meaning no data loss is allowed.

However, stricter RPO targets come at a cost: higher write latency, reduced system throughput, and the risk that replica failures may cause primary unavailability. For typical scenarios, some data loss is acceptable in exchange for higher availability and performance.

History

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

Historical Origins

The Pigsty project began in 2018-2019, originating from Tantan. Tantan is an internet dating app — China’s Tinder, now acquired by Momo. Tantan was a Nordic-style startup with a Swedish engineering founding team.

Tantan had excellent technical taste, using PostgreSQL and Go as its core technology stack. The entire Tantan system architecture was modeled after Instagram, designed entirely around the PostgreSQL database. Up to several million daily active users, millions of TPS, and hundreds of TB of data, the data component used only PostgreSQL. Almost all business logic was implemented using PG stored procedures — even including 100ms recommendation algorithms! It was arguably the most complex PostgreSQL-at-scale use case in China at the time.

News & Events

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

Get Started

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

Pigsty uses a scalable architecture design, suitable for both large-scale production environments and single-node development/demo environments. This guide focuses on the latter.

If you intend to learn about Pigsty, you can start with the Quick Start single-node deployment. A Linux virtual machine with 1C/2G is sufficient to run Pigsty.

You can use a Linux MiniPC, free/discounted virtual machines provided by cloud providers, Windows WSL, or create a virtual machine on your own laptop for Pigsty deployment. Pigsty provides out-of-the-box Vagrant templates and Terraform templates to help you provision Linux VMs with one click locally or in the cloud.

Roadmap

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

Release Strategy

Pigsty uses semantic versioning: <major>.<minor>.<patch>. Alpha/Beta/RC versions will have suffixes like -a1, -b1, -c1 appended to the version number.

Major version updates signify incompatible foundational changes and major new features; minor version updates typically indicate regular feature updates and small API changes; patch version updates mean bug fixes and package version updates.

Pigsty plans to release one major version update per year. Minor version updates usually follow PostgreSQL’s minor version update rhythm, catching up within a month at the latest after a new PostgreSQL version is released. Pigsty typically plans 4-6 minor versions per year. For complete release history, please refer to Release Notes.

Join the Community

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

GitHub

Our GitHub repository is: https://github.com/pgsty/pigsty. Please give us a ⭐️ star!

We welcome anyone to submit new Issues or create Pull Requests, propose feature suggestions, and contribute to Pigsty.

Please note that for issues related to Pigsty documentation, please submit Issues in the github.com/pgsty/pigsty.cc repository.

Press ⌘+ with K on macOS, or Ctrl+ with K, to search the documentation, extension catalog, and blog directly.

Maintainers

Pigsty is built by its maintainers and community.

Privacy Policy

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

Pigsty Software

When you install Pigsty software, if you use offline package installation in a network-isolated environment, we will not receive any data about you.

If you choose online installation, when downloading related packages, our servers or cloud provider servers will automatically log the visiting machine’s IP address and/or hostname in the logs, along with the package names you downloaded.

We will not share this information with other organizations unless required by law. (Honestly, we’d have to be really bored to look at this stuff.)

License

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

License Summary

Pigsty core uses Apache-2.0; documentation uses CC BY 4.0.

Official License: https://github.com/pgsty/pigsty/blob/main/LICENSE

Pigsty Core

The Pigsty core is licensed under Apache License 2.0.

Apache-2.0 is a permissive open-source license. You may freely use, modify, and distribute the software for commercial purposes without opening your own source code or adopting the same license.

What This License Grants	What This License Does NOT Grant	License Conditions
Commercial use	Trademark use	Include license and copyright notice
Modification	Liability & warranty	State changes
Distribution
Patent grant
Private use

Pigsty Documentation

Pigsty documentation sites (pigsty.cc, pigsty.io, pgsty.com) use Creative Commons Attribution 4.0 International (CC BY 4.0).

Sponsor Us

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

Pigsty is a free and open-source software, passionately developed by PostgreSQL community members, aiming to integrate the power of the PostgreSQL ecosystem and promote the widespread adoption of PostgreSQL. If our work has helped you, please consider sponsoring or supporting our project:

Sponsor us directly with financial support - express your sincere support in the most direct and powerful way!
Consider purchasing our Technical Support Services. We can provide professional PostgreSQL high-availability cluster deployment and maintenance services, making your budget worthwhile!
Share your Pigsty use cases and experiences through articles, talks, and videos.
Allow us to mention your organization in “Users of Pigsty.”
Recommend/refer our project and services to friends, colleagues, and clients in need.
Follow our WeChat Official Account and share relevant technical articles to groups and your social media.

Angel Investors

Pigsty is a project invested by Miracle Plus (formerly YC China) S22. We thank Miracle Plus and Dr. Qi Lu for their support of this project!

User Cases

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

According to Google Analytics PV and download statistics, Pigsty currently has approximately 100,000 users, with half from mainland China and half from other regions globally. They span across multiple industries including internet, cloud computing, finance, autonomous driving, manufacturing, tech innovation, ISV, and defense. If you are using Pigsty and are willing to share your case and Logo with us, please contact us - we offer one free consultation session as a token of appreciation.

Subscription

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

Pigsty aims to unite the power of the PostgreSQL ecosystem and help users make the most of the world’s most popular database, PostgreSQL, with self-driving database management software.

While Pigsty itself has already resolved many issues in PostgreSQL usage, achieving truly enterprise-grade service quality requires expert support and comprehensive coverage from the original provider. We deeply understand the importance of professional commercial support for enterprise customers. Therefore, Pigsty Enterprise Edition provides a series of value-added services on top of the open-source version, helping users better utilize PostgreSQL and Pigsty for customers to choose according to their needs.

FAQ

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

What is Pigsty, and what is it not?

Pigsty is a PostgreSQL database distribution, a local-first open-source RDS cloud database solution. Pigsty is not a Database Management System (DBMS), but rather a tool, distribution, solution, and best practice for managing DBMS.

Analogy: The database is the car, then the DBA is the driver, RDS is the taxi service, and Pigsty is the autonomous driving software.

Architecture

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

Pigsty uses a modular architecture with a declarative interface. You can freely combine modules like building blocks as needed.

Pigsty adopts a modular design that can be freely combined and used on demand (use one or all) to suit different scenarios.
Pigsty uses config inventory and config parameters to describe the entire deployment environment, implemented via Ansible playbooks.
Pigsty can run on any node—physical or virtual—as long as the OS is compatible.

Modules

Pigsty uses a modular design with six main default modules: PGSQL, INFRA, NODE, ETCD, REDIS, and MINIO.

ER Model

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

The largest entity concept in Pigsty is a Deployment. The main entities and relationships (E-R diagram) in a deployment are shown below:

A deployment can also be understood as an Environment. For example, Production (Prod), User Acceptance Testing (UAT), Staging, Testing, Development (Devbox), etc. Each environment corresponds to a Pigsty inventory that describes all entities and attributes in that environment.

Typically, an environment includes shared infrastructure (INFRA), which broadly includes ETCD (HA DCS) and MINIO (centralized backup repository), serving multiple PostgreSQL database clusters (and other database module components). (Exception: there are also deployments without infrastructure)

Cost Reference

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

Overview

The cost data below is intended to illustrate order-of-magnitude differences. Cloud vendor pricing and discounts vary over time, region, instance size, and purchase model.

EC2	Core·Month	RDS	Core·Month
DHH Self-Hosted Core-Month Price (192C 384G)	25.32	Junior Open Source DB DBA Reference Salary	¥15K/person·month
IDC Self-Hosted (Dedicated Physical: 64C384G)	19.53	Mid-Level Open Source DB DBA Reference Salary	¥30K/person·month
IDC Self-Hosted (Container, 500% Oversold)	7	Senior Open Source DB DBA Reference Salary	¥60K/person·month
UCloud Elastic VM (8C16G, Oversold)	25	ORACLE Database License	10000
Aliyun ECS 2x Memory (Dedicated, No Oversold)	107	Aliyun RDS PG 2x Memory (Dedicated)	260
Aliyun ECS 4x Memory (Dedicated, No Oversold)	138	Aliyun RDS PG 4x Memory (Dedicated)	320
Aliyun ECS 8x Memory (Dedicated, No Oversold)	180	Aliyun RDS PG 8x Memory (Dedicated)	410
AWS C5D.METAL 96C 200G (Monthly No Prepaid)	100	AWS RDS PostgreSQL db.T2 (2x)	440
AWS C5D.METAL 96C 200G (3-Year Prepaid)	80	AWS RDS PostgreSQL db.M5 (4x)	611
AWS C7A.METAL 192C 384G (3-Year Prepaid)	104.8	AWS RDS PostgreSQL db.R6G (8x)	786

RDS Cost Reference

Payment Model	Price	Annualized (¥10K)
IDC Self-Hosted (Single Physical Machine)	¥75K / 5 years	1.5
IDC Self-Hosted (2-3 Machines for HA)	¥150K / 5 years	3.0 ~ 4.5
Aliyun RDS On-Demand	¥87.36/hour	76.5
Aliyun RDS Monthly (Baseline)	¥42K / month	50
Aliyun RDS Annual (85% off)	¥425,095 / year	42.5
Aliyun RDS 3-Year Prepaid (50% off)	¥750,168 / 3 years	25
AWS On-Demand	$25,817 / month	217
AWS 1-Year No Prepaid	$22,827 / month	191.7
AWS 3-Year Full Prepaid	$120K + $17.5K/month	175
AWS China/Ningxia On-Demand	¥197,489 / month	237
AWS China/Ningxia 1-Year No Prepaid	¥143,176 / month	171
AWS China/Ningxia 3-Year Full Prepaid	¥647K + ¥116K/month	160.6

Here’s a comparison of self-hosted vs cloud database costs:

Open-Source Impact

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

China PostgreSQL Ecosystem Projects

Sorted by GitHub stars in descending order. Last updated: 2026-08-13 (Beijing time).

Project	Star	Author	Type	Summary
`pgsty/pigsty`	5521	Ruohang Feng @ PGSTY	Distribution	Out-of-the-box PostgreSQL distribution
`polardb/PolarDB-for-PostgreSQL`	3191	Alibaba Cloud	Kernel	Open-source PolarDB for PostgreSQL kernel
`tensorchord/pgvecto.rs`	2181	TensorChord	Extension	Vector search extension written in Rust
`tensorchord/VectorChord`	1770	TensorChord	Extension	Next-generation vector search extension
`Tencent/TBase`	1439	Tencent Cloud	Kernel	Tencent distributed HTAP database kernel
`apache/cloudberry`	1315	HashData	Kernel	Open-source MPP data warehouse kernel
`IvorySQL/IvorySQL`	1051	HighGo	Kernel	Oracle-compatible PostgreSQL fork
`pgplex/pgschema`	995	Chen Tianzhou	Tool	Declarative Postgres schema migration CLI
`amutu/zhparser`	869	Jov	Extension	Chinese full-text parser based on SCWS
`opengauss-mirror/openGauss-server`	784	Huawei	Kernel	Early PostgreSQL 9.2 kernel fork
`HaloTech-Co-Ltd/openHalo`	437	HaloTech	Kernel	PostgreSQL kernel compatible with MySQL wire protocol
`jaiminpan/pg_jieba`	417	Pan Jiamin	Extension	Chinese full-text search extension based on Jieba
`alitrack/duckdb_fdw`	409	Li Hongyan	Extension	DuckDB foreign data wrapper
`tensorchord/VectorChord-bm25`	375	TensorChord	Extension	Native BM25 ranking index for PostgreSQL
`pgsty/pg_exporter`	359	Ruohang Feng @ PGSTY	Tool	Metrics exporter for PostgreSQL and Pgbouncer
`ChenHuajun/pg_roaringbitmap`	286	Chen Huajun @ Suning	Extension	PostgreSQL RoaringBitmap bitmap extension
`pgsty/pig`	199	Ruohang Feng @ PGSTY	Tool	PostgreSQL extension package manager
`tensorchord/pg_bestmatch.rs`	101	TensorChord	Extension	BM25 sparse-vector generation in PostgreSQL
`wublabdubdub/PDU-PostgreSQLDataUnloader`	101	Zhang Chen	Tool	PostgreSQL database rescue and unloading tool
`tensorchord/pg_tokenizer.rs`	45	TensorChord	Extension	Full-text search tokenizer extension
`jaiminpan/pg_scws`	41	Pan Jiamin	Extension	Chinese tokenizer extension based on SCWS
`pgsty/pgext`	31	Ruohang Feng @ PGSTY	Tool	PostgreSQL extension catalog and metadata tool

tooltip:
  trigger: axis
  axisPointer: { type: shadow }
  formatter: $fn:tipfmt
grid: { left: 320, right: 72, top: 20, bottom: 26 }
xAxis:
  type: value
  max: 5600
  name: GitHub Stars
  nameLocation: middle
  nameGap: 24
  axisLabel: { formatter: $fn:fnum }
  splitLine: { show: true, lineStyle: { type: dashed, opacity: 0.45 } }
yAxis:
  type: category
  inverse: true
  axisLabel:
    align: right
    margin: 8
    width: 300
    overflow: truncate
    fontSize: 11
    fontFamily: monospace
  data:
    - 'pgsty/pigsty'
    - 'polardb/PolarDB-for-PostgreSQL'
    - 'tensorchord/pgvecto.rs'
    - 'tensorchord/VectorChord'
    - 'Tencent/TBase'
    - 'apache/cloudberry'
    - 'IvorySQL/IvorySQL'
    - 'pgplex/pgschema'
    - 'amutu/zhparser'
    - 'opengauss-mirror/openGauss-server'
    - 'HaloTech-Co-Ltd/openHalo'
    - 'jaiminpan/pg_jieba'
    - 'alitrack/duckdb_fdw'
    - 'tensorchord/VectorChord-bm25'
    - 'pgsty/pg_exporter'
    - 'ChenHuajun/pg_roaringbitmap'
    - 'pgsty/pig'
    - 'tensorchord/pg_bestmatch.rs'
    - 'wublabdubdub/PDU-PostgreSQLDataUnloader'
    - 'tensorchord/pg_tokenizer.rs'
    - 'jaiminpan/pg_scws'
    - 'pgsty/pgext'
series:
  - name: Star
    type: bar
    barWidth: 20
    showBackground: true
    backgroundStyle: { color: "rgba(148, 163, 184, 0.16)" }
    itemStyle:
      color: $fn:barclr
      borderRadius: [0, 5, 5, 0]
    label:
      show: true
      position: right
      formatter: $fn:labfmt
      color: '#334155'
      fontWeight: 600
    data: [5521, 3191, 2181, 1770, 1439, 1315, 1051, 995, 869, 784, 437, 417, 409, 375, 359, 286, 199, 101, 101, 45, 41, 31]

PostgreSQL Distribution Impact Metrics

Sorted by GitHub stars in descending order, with commercial products that do not publish stars listed last. Last updated: 2026-08-13 (Beijing time).

Infra as Code

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

Pigsty follows the IaC and GitOPS philosophy: use a declarative config inventory to describe the entire environment, and materialize it through idempotent playbooks.

Users describe their desired state declaratively through parameters, and playbooks idempotently adjust target nodes to reach that state. This is similar to Kubernetes CRDs & Operators, but Pigsty implements this functionality on bare metal and virtual machines through Ansible.

Pigsty was born to solve the operational management problem of ultra-large-scale PostgreSQL clusters. The idea behind it is simple — we need the ability to replicate the entire infrastructure (100+ database clusters + PG/Redis + observability) on ready servers within ten minutes. No GUI + ClickOps can complete such a complex task in such a short time, making CLI + IaC the only choice — it provides precise, efficient control.

Deployment

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

Unlike Getting Started, production Pigsty deployments require more Architecture Planning and Preparation.

This chapter helps you understand the complete deployment process and provides best practices for production environments.

Before deploying to production, we recommend testing in Pigsty’s Sandbox to fully understand the workflow. Use Vagrant to create a local 4-node sandbox, or leverage Terraform to provision larger simulation environments in the cloud.

For production, you typically need at least three nodes for high availability. You should understand Pigsty’s core Concepts and common administration procedures, including Configuration, Ansible Playbooks, and Security Hardening for enterprise compliance.

High Availability

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

Overview

Pigsty’s PostgreSQL clusters come with out-of-the-box high availability, with core capabilities provided by Patroni, Etcd, and HAProxy.

When your PostgreSQL cluster has two or more instances, you automatically have self-healing database high availability without any additional configuration — as long as any instance in the cluster survives, the cluster can provide complete service. Clients only need to connect to any node in the cluster to get full service without worrying about primary-replica topology changes.

RTO Trade-offs

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

RTO (Recovery Time Objective) defines the maximum time required for the system to restore write capability when the primary fails.

For critical transaction systems where availability is paramount, the shortest possible RTO is typically required, such as under one minute.

However, shorter RTO comes at a cost: increased false failover risk. Network jitter may be misinterpreted as a failure, leading to unnecessary failovers. For cross-datacenter/cross-region deployments, RTO requirements are typically relaxed (e.g., 1-2 minutes) to reduce false failover risk.

Inventory

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

Every Pigsty deployment corresponds to an Inventory that describes key properties of the infrastructure and database clusters.

Configuration File

Pigsty uses Ansible YAML configuration format by default, with a single YAML configuration file pigsty.yml as the inventory.

~/pigsty
  ^---- pigsty.yml   # <---- Default configuration file

You can directly edit this configuration file to customize your deployment, or use the configure wizard script provided by Pigsty to automatically generate an appropriate configuration file.

Configure

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

Pigsty provides a configure script as a configuration wizard that automatically generates an appropriate pigsty.yml configuration file based on your current environment.

This is an optional script: if you already understand how to configure Pigsty, you can directly edit the pigsty.yml configuration file and skip the wizard.

Quick Start

Enter the pigsty source home directory and run ./configure to automatically start the configuration wizard. Without any arguments, it defaults to the meta single-node configuration template:

Parameters

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

In the inventory, you can use various parameters to fine-tune Pigsty customization. These parameters cover everything from infrastructure settings to database configuration.

Parameter List

According to the current source and parameter reference pages, Pigsty’s 10 official modules expose 373 public parameters for fine-grained control. See Reference - Parameter List for the complete list. The native MySQL 8.4 pilot module exposes 13 additional public parameters that are listed separately and excluded from this total.

Conf Templates

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

In Pigsty, deployment blueprint details are defined by the inventory, which is the pigsty.yml configuration file. You can customize it through declarative configuration.

However, writing configuration files directly can be daunting for new users. To address this, we provide some ready-to-use configuration templates covering common usage scenarios.

Each template is a predefined pigsty.yml configuration file containing reasonable defaults suitable for specific scenarios.

You can choose a template as your customization starting point, then modify it as needed to meet your specific requirements.

Use CMDB as Config Inventory

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

Pigsty allows you to use a PostgreSQL metabase as a dynamic configuration source, replacing static YAML configuration files for more powerful configuration management capabilities.

Overview

CMDB (Configuration Management Database) is a method of storing configuration information in a database for management.

In Pigsty, the default configuration source is a static YAML file pigsty.yml, which serves as Ansible’s inventory.

This approach is simple and direct, but when infrastructure scales and requires complex, fine-grained management and external integration, a single static file becomes insufficient.

Security and Compliance

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

The database is usually the most sensitive component in an information system: it stores the most valuable data, so attacks and failures can have the most serious consequences. Database security is not a feature that can be enabled with one switch. It is the combined answer to a series of questions: Who can connect? What can they do after connecting? Can traffic be intercepted? Are operations recorded? Can damaged, lost, or deleted data be recovered?

Security Model

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

Before examining individual security features, answer two more fundamental questions: Where is the root of trust? and How many defensive layers exist? The first determines what deserves the strongest protection. The second determines what remains when one layer fails.

Trust Boundaries

Pigsty is an Ansible-based declarative deployment system. Like other control-plane systems, its admin node is the control plane and the node that requires the strongest protection.

Authentication

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

PostgreSQL uses pg_hba.conf for Host-Based Authentication: who may connect, from where, to which database, and how they must prove their identity.

The mechanism is powerful, but expensive to maintain manually across a cluster. Primary and replica instances may require different rules, and every instance stores its own configuration in the data directory. Without a common declaration and refresh process, rules can drift between instances.

Pigsty applies the same declarative configuration model here: HBA rules are part of the inventory and are rendered and distributed consistently by playbooks.

Access Control

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

Authentication answers “Who are you?” Authorization answers “What may you do?”

Privilege failures rarely result from a lack of mechanisms—PostgreSQL GRANT and REVOKE are sufficiently precise. The usual problem is the absence of conventions that are applied by default: an application account is made the owner at launch, temporary superuser access is not revoked after troubleshooting, or grants are missed when new tables are created and cause failures in production.

Encrypted Communication

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

TLS can provide three separate protections: transport encryption, server authentication, and client authentication. Each must be configured independently. Enabling server-side TLS does not mean the client verifies the server identity, nor does it mean the server requires a client certificate.

The main operational cost of TLS is not the encryption algorithm but certificate issuance, distribution, trust, and rotation. Without centralized management, internal services often encrypt traffic while skipping certificate verification—or remain on plaintext connections.

Data Security

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

Network boundaries, authentication, and access control reduce the likelihood of an incident. When hardware fails, credentials leak, or an operator makes a mistake, data-layer controls must limit the impact and support recovery.

Data security answers four questions: Is the data intact? Can it be recovered? If copied, does it remain confidential? Can you determine what happened?

Integrity

Bad disk sectors, memory bit flips, and storage firmware defects can cause silent data corruption: the data is damaged without an immediate error. Pigsty enables page checksums by default (pg_checksum: true). The cluster is initialized with data-checksums, so PostgreSQL calculates a checksum when writing a page and verifies it when reading.

Compliance

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

Compliance is not a product you can buy. It is a state that must be demonstrated continuously through three elements:

Configuration: whether security controls are enabled. Pigsty directly provides this part.
Process: access approval, change management, recovery exercises, and related procedures. The organization must establish these.
Evidence: records showing that configuration and process remain effective. Pigsty’s inventory, runtime logs, and monitoring system can provide part of this evidence.

This page begins with a pre-launch hardening checklist and then maps Pigsty security capabilities to common compliance frameworks. The mappings support architecture and gap analysis; they are not an MLPS assessment conclusion, a SOC 2 audit opinion, or legal advice.

Single-Node Installation

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

This is the Pigsty single-node install guide Single Node. For multi-node HA production deployment, refer to the Deployment docs.

Pigsty single-node installation consists of three steps: Install, Configure, and Deploy.

Summary

Prepare a node with compatible OS, and run as an admin user with nopass ssh and sudo:

Choose a Pigsty download mirror:

pigsty.io (Global)

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

pigsty.cc (China)

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

This command runs the install script, downloads and extracts Pigsty source to your home directory and installs dependencies. Then complete Configure and Deploy:

Docker Deployment

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

Pigsty is designed for native Linux, but can also run in Linux containers with systemd. If you don’t have native Linux (e.g., macOS or Windows), use Docker to spin up a local single-node Pigsty for testing.

Quick Start

Enter the docker/ dir in Pigsty source and launch with one command:

cd ~/pigsty/docker
make launch          # Start container + generate config + deploy

After deployment, access services:

Web Interface

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

After single-node installation, you’ll have the INFRA module installed on the current node, which includes an out-of-the-box Nginx web server.

The default server configuration provides a WebUI graphical interface for displaying monitoring dashboards and unified proxy access to other component web interfaces.

Access

You can access this graphical interface by entering the deployment node’s IP address in your browser. By default, Nginx serves on standard ports 80/443.

Customize Pigsty with Configuration

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

Besides using the configuration wizard to auto-generate configs, you can write Pigsty config files from scratch. This tutorial guides you through building a complex inventory step by step.

If you define NODE, INFRA, ETCD, MINIO, and PGSQL in the inventory upfront, deploy.yml can deploy this core path in one run—but it hides the details. Optional modules such as Docker, Redis, Kafka, native MySQL, JUICE, and VIBE require their own playbooks.

This doc breaks down all modules and playbooks, showing how to incrementally build from a simple config to a complete deployment.

Run Playbooks with Ansible

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

Pigsty uses Ansible to manage clusters, a very popular large-scale/batch/automation ops tool in the SRE community.

Ansible can use declarative approach for server configuration management. All module deployments are implemented through a series of idempotent Ansible playbooks.

For example, in single-node deployment, you’ll use the deploy.yml playbook. Pigsty has more built-in playbooks, you can choose to use as needed.

Understanding Ansible basics helps with better use of Pigsty, but this is not required, especially for single-node deployment.

Offline Installation

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

Pigsty installs from Internet upstream by default, but some envs are isolated from the Internet. To address this, Pigsty supports offline installation using offline packages. Think of them as Linux-native Docker images.

Overview

Offline packages bundle all required RPM/DEB packages and dependencies; they are snapshots of the local APT/YUM repo after a normal installation.

In serious prod deployments, we strongly recommend using offline packages. They ensure all future nodes have consistent software versions with the existing env, and avoid online installation failures caused by upstream changes (quite common!), guaranteeing you can run it independently forever.

Slim Installation

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

If you only want HA PostgreSQL database cluster itself without monitoring, infra, etc., consider Slim Installation.

Slim installation has no INFRA module, no monitoring, no local repo—just ETCD and PGSQL and partial NODE functionality.

Slim installation is suitable for:

Only needing PostgreSQL database itself, no observability infra required.
Extremely resource-constrained envs unwilling to bear infra overhead (~0.2 vCPU / 500MB on single node).
Already having external monitoring system, wanting to use your own unified monitoring framework.
Not needing the Grafana visualization dashboard component.

Limitations of slim installation:

No INFRA module, cannot use WebUI and local software repo features.
Offline Install is limited to single-node mode; multi-node slim install can only be done online.

Overview

To use slim installation, you need to:

Security Recommendations

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

The default configuration targets local demonstrations and development or testing on a trusted intranet. If other hosts can reach the deployment, complete at least three checks: credentials, network boundaries, and critical files.

Production environments should also review the Security Model, Compliance, and Security Considerations.

Passwords

Pigsty default credentials are public in the source code and documentation and must not be used directly in production.

The configuration wizard can randomize built-in parameters and example credentials that it recognizes:

Concepts

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

Pigsty is a portable, extensible open-source PostgreSQL distribution for building production-grade database services in local environments with declarative configuration and automation. It has a vast ecosystem providing a complete set of tools, scripts, and best practices to bring PostgreSQL to enterprise-grade RDS service levels.

Pigsty’s name comes from PostgreSQL In Great STYle, also understood as Postgres, Infras, Graphics, Service, Toolbox, it’s all Yours—a self-hosted PostgreSQL solution with graphical monitoring that’s all yours. You can find the source code on GitHub, visit the official documentation for more information, or experience the Web UI in the online demo.

Install Pigsty for Production

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

This is the Pigsty production multi-node deployment guide. For single-node Demo/Dev setups, see Getting Started.

Summary

Prepare nodes with SSH access following your architecture plan, install a compatible Linux OS, then execute with an admin user having passwordless ssh and sudo:

curl -fsSL https://repo.pigsty.io/get | bash;         # International
curl -fsSL https://repo.pigsty.cc/get | bash;         # Backup Mirror

This runs the install script, downloading and extracting Pigsty source to your home directory with dependencies installed. Complete configuration and deployment to finish.

Prepare Resources for Serious Deployment

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

Pigsty runs on nodes (physical machines or VMs). This document covers the planning and preparation required for deployment.

Node

Pigsty currently runs on Linux kernel with x86_64 / aarch64 architecture. A “node” refers to an SSH accessible resource that provides a bare Linux OS environment. It can be a physical machine, virtual machine, or a systemd-enabled container equipped with systemd, sudo, and sshd.

Deploying Pigsty requires at least 1 node. You can prepare more and deploy everything in one pass via playbooks, or add nodes later. The minimum spec requirement is 1C1G, but at least 1C2G is recommended. Higher is better—no upper limit. Parameters are auto-tuned based on available resources.

Planning Architecture and Nodes

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

Pigsty uses a modular architecture. You can combine modules like building blocks and express your intent through declarative configuration.

Common Patterns

Here are common deployment patterns for reference. Customize based on your requirements:

Pattern	INFRA	ETCD	PGSQL	MINIO	Description
Single-node (`meta`)	1	1	1		Single-node deployment default
Slim deploy (`slim`)		1	1		Database only, no monitoring infra
Infra-only (`infra`)	1				Monitoring infrastructure only
Rich deploy (`rich`)	1	1	1	1	Single-node + object storage + local repo with all extensions

Multi-node Pattern	INFRA	ETCD	PGSQL	MINIO	Description
Two-node (`dual`)	1	1	2		Semi-HA, tolerates specific node failure
Three-node (`trio`)	3	3	3		Standard HA, tolerates any one failure
Four-node (`full`)	1	1	1+3		Demo setup, single INFRA/ETCD
Production (`simu`)	2	3	n	n	2 INFRA, 3 ETCD
Large-scale (custom)	3	5	n	n	3 INFRA, 5 ETCD

Your architecture choice depends on reliability requirements and available resources. Serious production deployments require at least 3 nodes for HA configuration. With only 2 nodes, use Semi-HA configuration.

Setup Admin User and Privileges

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

Pigsty requires an OS admin user with passwordless SSH and Sudo privileges on all managed nodes.

This user must be able to SSH to all managed nodes and execute sudo commands on them.

User

Typically use names like dba or admin, avoiding root and postgres:

Using root for deployment is possible but not a production best practice.
Using postgres (pg_dbsu) as admin user is strictly prohibited.

Passwordless

The passwordless requirement is optional if you can accept entering a password for every ssh and sudo command.

Sandbox

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

Pigsty provides a standard 4-node sandbox environment for learning, testing, and feature demonstration.

The sandbox uses fixed IP addresses and predefined identity identifiers, making it easy to reproduce various demo use cases.

Description

The default sandbox environment consists of 4 nodes, using the ha/full.yml configuration template.

ID	IP Address	Node	PostgreSQL	INFRA	ETCD	MINIO
1	`10.10.10.10`	`meta`	`pg-meta-1`	`infra-1`	`etcd-1`	`minio-1`
2	`10.10.10.11`	`node-1`	`pg-test-1`
3	`10.10.10.12`	`node-2`	`pg-test-2`
4	`10.10.10.13`	`node-3`	`pg-test-3`

The sandbox configuration can be summarized as the following config:

Vagrant

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

Vagrant is a popular local virtualization tool that creates local virtual machines in a declarative manner.

Pigsty requires a Linux environment to run. You can use Vagrant to easily create Linux virtual machines locally for testing.

The currently recommended and validated baselines are Rocky Linux 9.8 / 10.2, Debian 12.15 / 13.6, and Ubuntu 22.04.5 / 24.04.4 / 26.04.0. Major-version Vagrant aliases map to pinned box versions.

Quick Start

Install Dependencies

First, ensure you have Vagrant and a virtual machine provider (such as VirtualBox or libvirt) installed on your system.

Terraform

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

Terraform is a popular “Infrastructure as Code” tool that you can use to create virtual machines on public clouds with one click.

Pigsty currently provides example Terraform templates for Alibaba Cloud, AWS (global and China), Azure, GCP, Tencent Cloud, Hetzner, Vultr, DigitalOcean, and Linode. The aliyun-s3.tf template also creates a private OSS bucket and dedicated RAM read/write credentials for S3/pgBackRest scenarios.

Quick Start

Install Terraform

On macOS, you can use Homebrew to install Terraform:

Security Considerations

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

Pigsty defaults target development, testing, and demonstrations on a trusted intranet. A production deployment must configure credentials, network boundaries, authentication, certificates, backup, and audit according to its threat model.

See Security and Compliance for mechanisms and boundaries, and the Launch Hardening Checklist for executable checks. ha/safe is a hardening example, not a substitute for reviewing each control.

Confidentiality

Critical Files

Protect these assets:

About

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

References

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

Modules

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

Official Modules

Module	Category	Status	Docs Path	Summary
`PGSQL`	Core	GA	`/docs/pgsql`	High-availability PostgreSQL clusters with built-in backup, monitoring, SOP, and extension ecosystem.
`INFRA`	Core	GA	`/docs/infra`	Local software repository + VictoriaMetrics/Logs/Traces + Grafana infrastructure stack.
`NODE`	Core	GA	`/docs/node`	Node initialization and convergence: system tuning, admin, HAProxy, Vector, Keepalived, etc.
`ETCD`	Core	GA	`/docs/etcd`	DCS for PostgreSQL HA (service discovery, config, leader-election metadata).
`MINIO`	Extension	GA	`/docs/minio`	Deploys Silo S3-compatible object storage, suitable for PostgreSQL backups.
`REDIS`	Extension	GA	`/docs/redis`	Redis by default, or Valkey, in standalone, Sentinel, or native-cluster mode with monitoring.
`DOCKER`	Extension	GA	`/docs/docker`	Docker daemon and the runtime capability for containerized apps.
`JUICE`	Extension	BETA	`/docs/juice`	JuiceFS distributed file system using PostgreSQL as metadata engine.
`VIBE`	Extension	BETA	`/docs/vibe`	Browser-based dev environment with Code-Server, JupyterLab, Node.js, Claude Code, and Codex CLI.
`KAFKA`	Extension	BETA	`/docs/kafka`	Apache Kafka 4.x dynamic KRaft cluster deployment, security baseline, and monitoring.

Core Modules

Pigsty provides four core modules that are important for delivering complete highly available PostgreSQL services:

File Hierarchy

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

Pigsty FHS

Pigsty’s home directory is located at ~/pigsty by default. The file structure within this directory is as follows:

- app/   {open=false}
  - Application template resources
- bin/   {open=false}
  - Management and operations scripts
- files/
  - victoria/   {open=false}
    - Rules and operations scripts
  - grafana/   {open=false}
    - Grafana dashboards
  - postgres/   {open=false}
    - PostgreSQL management scripts
  - migration/   {open=false}
    - Data-migration task definitions
  - pki/   {open=false}
    - Self-signed CA and certificates
- roles/   {open=false}
  - Ansible role implementations
- templates/   {open=false}
  - Ansible templates
- vagrant/   {open=false}
  - Vagrant sandbox definitions
- terraform/   {open=false}
  - Terraform cloud-resource templates
- configure
- ansible.cfg
- pigsty.yml
- *.yml

/infra is a runtime symlink to /data/infra, which keeps observability data and generated configuration together:

Configuration Templates

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

Use -c with configure to select a template. Its value is a path relative to conf/ without the .yml suffix. If omitted, Pigsty uses the default meta template.

Category	Templates
Solo Templates	`meta`, `rich`, `fat`, `slim`, `infra`, `vibe`, `docker`
Kernel Templates	`pgsql`, `pg19`, `mssql`, `polar`, `ivory`, `agens`, `pgedge`, `mysql` (OpenHalo), `mongo`, `pgtde`, `oriole`
HA Templates	`ha/simu`, `ha/octo`, `ha/citus`, `ha/full`, `ha/safe`, `ha/trio`, `ha/dual`
App Templates	`supabase`, `app/odoo`, `app/dify`, `app/insforge`, `app/hindsight`, `app/electric`, `app/maybe`, `app/teable`, `app/mattermost`, `app/registry`, `app/immich`, `app/jumpserver`
Misc Templates	`demo/bare`, `demo/el`, `demo/debian`, `demo/demo`, `demo/kernel`, `demo/redis`, `demo/minio`, `demo/kafka`, `demo/mysql` (native MySQL pilot), `demo/remote`, `demo/saas`, `demo/wool`, `build/oss`, `build/dev`

Operations SOP Index

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

Getting Started Path

Order	Question	Entry
1	What modules does Pigsty include?	Modular Architecture, PGSQL Architecture, PGSQL Cluster Model
2	How do I get it running first?	Quick Start, Web UI, PostgreSQL Quick Start
3	How should I read the config file?	Declarative Configuration, Configuration Guide, Configuration Parameters
4	What should I prepare for production?	Planning, Preparation, Administration Model
5	How do I deploy a multi-node cluster?	Production Deployment, Playbooks, PGSQL Playbooks
6	How do I operate databases daily?	PGSQL Administration, Cluster Management, User Management, Database Management
7	How do I validate reliability?	PostgreSQL HA, Patroni Management, Backup & Restore, Restore Operations

Task Index

Task	Read First	Operation Entry
Prepare servers, disks, networks, VIPs	Preparation, Planning, Linux Compatibility	Production Deployment
Prepare SSH, sudo, and admin users	Administration Model	Production Deployment
Build a local or cloud sandbox	Sandbox	Vagrant, Terraform
Single-node trial	Quick Start	`./configure -g`, `./deploy.yml`
Multi-node production deployment	Deployment, Production Deployment	`./deploy.yml`, `./pgsql.yml`
Deploy in an offline environment	Offline Installation	Repository Management
Choose a config template	Config Templates, Template List	`./configure -c <template>`
Plan cluster, database, and user names	PGSQL Cluster Model	`pg_cluster`, `pg_databases`, `pg_users`
Create a PostgreSQL cluster	Cluster Instance Config	Cluster Management, `./pgsql.yml -l <cluster>`
Add business users	User/Role Config	User Management, `./pgsql-user.yml -l <cluster>`
Add business databases	Database Config	Database Management, `./pgsql-db.yml -l <cluster>`
Configure access endpoints	Service/Access	`pg_services`, `pg_default_services`
Modify HBA	HBA Config	HBA Management
Switchover	Patroni Management	`patronictl switchover`
HA drills	PostgreSQL HA, RPO, RTO	3-of-2 Failure Drill
Configure VIP	HA Service Access	Configure PG VIP
Configure backup policy	Backup Policy	Backup Admin Commands
Perform PITR	Point-in-Time Recovery	Restore Operations
Recover dropped data, tables, or databases	Drop Recovery	Manual Recovery
Clone or fork a cluster	Clone Database Cluster	Fork Instance
Use Silo for backups	MINIO Module	Silo Config, Backup Repository
View monitoring and alerts	Monitoring System	PGSQL Monitoring, PGSQL Dashboards
Troubleshoot database failures	PGSQL FAQ	Troubleshooting, Component Management
Scale PostgreSQL clusters	Cluster Instance Config	Cluster Management
Upgrade PostgreSQL	Version Upgrade	Kernel Versions
Install or enable extensions	Extensions	Extension Management
Migrate existing databases	Data Migration	Migration Playbook
Harden security	Security Considerations	Access Control, CA & Certificates
Manage domains and web entrypoints	Domain Management	Nginx Management
Maintain infrastructure	INFRA Administration	`infra.yml`, `infra-rm.yml`
Maintain Etcd	ETCD Config	ETCD Management, ETCD FAQ
Deploy app templates	Applications	Docker Module, `./app.yml`

Preparation And Deployment

For production deployment, start with Planning and Preparation. These two pages cover node count, disks, filesystems, networks, VIPs, domains, and software sources.

FAQ

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

What components are included in the INFRA module?

Strictly following the current source, the infra role directly manages:

Nginx: Exposes Grafana, VictoriaMetrics (VMUI), Alertmanager, and other WebUIs, and hosts local YUM/APT repositories.
DNSMasq: Provides DNS registration and resolution.
VictoriaMetrics suite: VictoriaMetrics, VMAlert, VictoriaLogs, and VictoriaTraces.
Alertmanager, Blackbox Exporter, and Grafana: Alert dispatch, blackbox probing, and visualization.

infra.yml also chains the CA, repository, NODE, HAProxy, and node-monitoring roles, so it configures supporting capabilities such as the self-signed CA, Chronyd, Node Exporter, and Vector on Infra nodes. ETCD, PostgreSQL, and Docker are separate modules and are not deployed by infra.yml; use etcd.yml, pgsql.yml, and docker.yml, respectively.

FAQ

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

What is etcd’s role in Pigsty?

etcd is a distributed, reliable key-value store for critical system data. Pigsty uses etcd as DCS (Distributed Config Store) service for Patroni, storing PG HA status.

Patroni uses etcd for: cluster failure detection, auto failover, primary-replica switchover, and cluster config management.

etcd is critical for PostgreSQL HA, and its own availability depends on a reachable majority. Production deployments normally spread three or five voting members across independent failure domains.

PIGSTY on Pigsty v5.0

Pigsty v5.0 Documentation

Get Started

Features

Value Propositions

Overview

RPO Trade-offs

History

Historical Origins

News & Events

Recent News

Get Started

Roadmap

Release Strategy

Join the Community

GitHub

Maintainers

Privacy Policy

Pigsty Software

License

License Summary

Pigsty Core

Pigsty Documentation

Sponsor Us

Sponsor Us

Angel Investors

User Cases

Subscription

FAQ

What is Pigsty, and what is it not?

Architecture

Modules

ER Model

Cost Reference

Overview

RDS Cost Reference

Open-Source Impact

China PostgreSQL Ecosystem Projects

PostgreSQL Distribution Impact Metrics

Infra as Code

Deployment

High Availability

Overview

RTO Trade-offs

Inventory

Configuration File

Configure

Quick Start

Parameters

Parameter List

Conf Templates

Use CMDB as Config Inventory

Overview

Security and Compliance

Security Model

Trust Boundaries

Authentication

Access Control

Encrypted Communication

Data Security

Integrity

Compliance

Single-Node Installation

Summary

Docker Deployment

Quick Start

Web Interface

Access

Customize Pigsty with Configuration

Run Playbooks with Ansible

Offline Installation

Overview

Slim Installation

Overview

Security Recommendations

Passwords

Concepts

Install Pigsty for Production

Summary

Prepare Resources for Serious Deployment