Task

Citus is a PostgreSQL extension that turns PostgreSQL into a distributed database. It scales horizontally across nodes to process large data volumes and query workloads. Patroni v3.0+ provides native high-availability support for Citus. This …

In a typical 3-node HA deployment, simultaneous failure of two nodes removes the majority. The system usually cannot complete automatic failover and needs manual intervention. First, assess the two failed servers. If they can restart quickly, …

Bytebase is a database schema change and version management tool. Pigsty provides a Compose template in app/bytebase. It listens on 8887 by default and uses BB_PGURL to connect to external PostgreSQL. Quick Start cd ~/pigsty/app/bytebase vi .env # …

pgAdmin is an open-source PostgreSQL administration and development GUI. Pigsty v4.5.0 provides the app/pgadmin Docker Compose template. It can generate a server list and password file from the current inventory. Change the defaults first The …

kafka.yml deploys Apache Kafka 4.1+ dynamic KRaft and applies security, resources, and monitoring. kafka-rm.yml removes members or tears down clusters. Cluster Completeness Constraint Each selected kafka_cluster must include every member. Partial …

KAFKA installs Kafka in /opt/kafka and manages it with Systemd. Declare persistent settings in pigsty.yml. Do not edit generated node files manually. These CLI examples use the generated /etc/kafka/admin.properties. Keep --command-config even with …

Service Management systemctl status code-server systemctl restart code-server systemctl status jupyter systemctl restart jupyter Logs: journalctl -u code-server -f journalctl -u jupyter -f Workspace and Context vibe_dir creates these under …

VIBE provides the vibe.yml playbook to deploy Code-Server, JupyterLab, Node.js, Claude Code, and Codex CLI. vibe.yml includes only the node_id and vibe roles. It does not include node/infra. Run deploy.yml first, or explicitly run node.yml and …

Common operations: Initialize Instance Reconfigure Remove Instance Add New Instance Shared Mount Across Nodes PITR Recovery Troubleshooting Performance Tuning See FAQ for more. Initialize Instance ./juice.yml -l <host> ./juice.yml -l <host> -e …

The JUICE module provides the juice.yml playbook to deploy and remove JuiceFS instances. juice.yml Task structure in juice.yml: juice_id : validate config, check port conflicts juice_install : install juicefs package juice_cache : create shared cache …

The Docker module provides the docker.yml playbook to install Docker Daemon and Docker Compose. docker.yml Playbook source file: docker.yml The playbook installs docker-ce and docker-compose-plugin on target nodes that have docker_enabled: true. It …

You can use PostgreSQL as Grafana’s backend database. This tutorial explains the Pigsty deployment system through these tasks: How to create a new database cluster How to create new business users in an existing cluster How to create new business …

Use these standard operating procedures (SOPs) to administer Redis. The REDIS module defaults to redis_type: redis. With redis_type: valkey, the server and client commands become valkey-server and valkey-cli. The examples use the default redis-cli. …

The REDIS module provides two playbooks for deploying/removing Redis clusters/nodes/instances: redis.yml: Deploy Redis cluster/node/instance redis-rm.yml: Remove Redis cluster/node/instance redis.yml The redis.yml playbook for deploying Redis …

Create Cluster To create a cluster, define it in the config inventory and run the minio.yml playbook. minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio, minio_type: silo } } The configuration above defines an SNSD …

The MINIO module provides two built-in playbooks: minio.yml: Install and configure Silo minio-rm.yml: Remove Silo, its configuration, and optionally its data minio.yml minio.yml runs with hosts: all, but its pre-tasks skip hosts where minio_cluster …

The ETCD module provides two core playbooks. Use etcd.yml to install and configure etcd clusters. Use etcd-rm.yml to remove clusters or members. Architecture Change: Pigsty v3.6+ Since Pigsty v3.6, the etcd.yml playbook focuses on cluster …

Use these standard procedures to administer etcd: Create Cluster: Initialize an etcd cluster Destroy Cluster: Destroy an etcd cluster CLI Environment: Configure etcd client to access server cluster RBAC Authentication: Use etcd RBAC auth Reload …

Here are common administration operations for the NODE module: Add Node Remove Node Create Admin Bind VIP Add Node Monitoring Other Tasks For more questions, see FAQ: NODE Add Node To add a node to Pigsty, first configure passwordless SSH and sudo …

Pigsty provides two playbooks related to the NODE module: node.yml: Add nodes to Pigsty and configure them to the desired state node-rm.yml: Remove managed nodes from Pigsty Use bin/node-add and bin/node-rm as shortcuts to run these playbooks. …

Pigsty maintains a self-signed Certificate Authority (CA) on the admin node by default. It signs certificates for PostgreSQL, Patroni, etcd, Silo, Nginx, and other internal services. Public Nginx entries can use Certbot/Let’s Encrypt certificates …

Use this guide for daily INFRA administration. It covers installation, removal, scaling, and component maintenance. Install INFRA Module Use the infra.yml playbook to install the INFRA module on the infra group: ./infra.yml # Install INFRA module on …

Use domain names instead of IP addresses to access Pigsty’s various web services. Quick Start Add the following static resolution records to /etc/hosts: 10.10.10.10 i.pigsty Replace IP address with your actual Pigsty node’s IP. Why Use Domain Names …

Pigsty’s REPO role downloads required packages and creates a local YUM/APT repository under /www/pigsty. Nginx can serve this repository. The current package candidate is SOW 0.3.0. SOW generates metadata for both repository types. The source no …

Pigsty installs Nginx on INFRA nodes as the entry point for all web services. It listens on standard ports 80/443. In Pigsty, you can configure Nginx to provide various services through inventory: Expose web interfaces for monitoring components like …

This section covers daily administration and operations for Pigsty deployments.

Pigsty provides three playbooks related to the INFRA module: deploy.yml: Deploy the NODE, INFRA, ETCD, MINIO, and PGSQL core modules on all nodes in one pass infra.yml: Initialize Pigsty infrastructure on infra nodes infra-rm.yml: Remove …

If all cluster nodes share one L2 network, you can optionally define an L2 VIP for the PostgreSQL cluster. The VIP uses Master-Backup mode. It always points to the node that runs the cluster primary instance. VIP-Manager manages the VIP. It reads the …

Pigsty provides playbooks for cluster provisioning, scaling, user and database management, monitoring, backup, recovery, and migration. Playbook Function pgsql.yml Initialize PostgreSQL cluster or add new replicas pgsql-rm.yml Remove PostgreSQL …

Accidental Data Deletion For a small accidental DELETE, consider pg_surgery or pg_dirtyread for selective recovery in place. -- Immediately disable Auto Vacuum on this table and abort Auto Vacuum worker processes for this table ALTER TABLE …

Pigsty v4.5.0 provides two local shell utilities: pg-fork copies a PostgreSQL data directory and gives the copy a separate port. pg-pitr invokes pgBackRest to restore a stopped data directory to a selected target. Use these utilities for sandbox …

Use node_hugepage_count and node_hugepage_ratio or /pg/bin/pg-tune-hugepage To enable HugePages, consider node_hugepage_count and node_hugepage_ratio. Apply these settings with ./node.yml -t node_tune. HugePages have advantages and disadvantages for …

This tutorial performs a PostgreSQL PITR drill in Pigsty v4.5.0’s four-node sandbox. It runs pgsql-pitr.yml in the sequence down → pitr → up. Separate validation steps precede data overwrite, timeline promotion, and HA reconstruction. For one current …

Cloning restores production history into another cluster and leaves the production cluster unchanged. This makes cloning a useful recovery method with less risk to production. You can recover accidentally deleted data from the clone, validate backups …

Pigsty provides three restore interfaces. They use the same parameter semantics for different scopes: Entry point Use case What it controls pgsql-pitr.yml Production cluster recovery HA pause, multiple nodes, etcd cleanup, restore, and restart pig …

On a database node, run backup commands as the database superuser (pg_dbsu, which defaults to postgres. Use one of these interfaces: pig pb: the PIG CLI wrapper, with automatic stanza detection, DBSU switching, and safety checks; this is the …

Two parameters select the backup location. pgbackrest_repo defines candidate repositories. pgbackrest_method selects one repository. Pigsty converts repository keys to pgBackRest repo1-* options, so you can use any supported pgBackRest repository …

The chart below shows the “Recovery Window” and “Backup Storage Usage” on one timeline (0~108h). Use it to compare the two metrics. The 30-day example uses a database size of 100GB and daily writes of 10GB. It shows both metrics with weekly full …

Pigsty’s backup and restore operations execute pgBackRest commands. For safe operation, understand the pgBackRest model and how Pigsty maps its orchestration parameters to native options. Core pgBackRest Concepts Stanza: the Cluster’s Backup Identity …

Pigsty includes the pgsql-migration.yml playbook for online database migration with logical replication. The generated automation scripts can reduce application downtime to a few seconds. Logical replication requires PostgreSQL 10 or later. If the …

This document lists possible PostgreSQL and Pigsty failures. It gives standard procedures to locate, resolve, and analyze them. Disk Space Exhausted Disk space exhaustion is the most common type of failure. Symptoms If the database disk is full, …

Pigsty uses pgBackRest for PostgreSQL backups. It supports full, differential, and incremental backups, parallel processing, encryption, and Silo/S3 object storage. By default, Pigsty configures backup and WAL archiving for every PGSQL cluster. This …

Source: https://patroni.readthedocs.io/en/latest/contributing_guidelines.html Chatting For questions, interactive troubleshooting, or discussion with other users, join #patroni on PostgreSQL Slack. Reporting bugs Before you report a bug, reproduce …

Source: https://patroni.readthedocs.io/en/latest/existing_data.html This section describes the process for converting a standalone PostgreSQL instance into a Patroni cluster. To deploy a Patroni cluster without using a pre-existing PostgreSQL …

Source: https://patroni.readthedocs.io/en/latest/kubernetes.html Patroni can store cluster state and the leader key in Kubernetes objects. This lets it run Postgres in Kubernetes without a separate consistency store, such as an extra Etcd …

Source: https://patroni.readthedocs.io/en/latest/pause.html The goal Patroni sometimes needs to suspend cluster management while it retains cluster state in the DCS. Examples include major version upgrades and corruption recovery. During these …

Quick Start PostgreSQL has two types of version upgrade: minor and major. Their risk and complexity differ substantially. Type Example Downtime Data Compatibility Risk Minor upgrade 17.2 → 17.3 Seconds (rolling) Fully compatible Low Major upgrade 17 …

Quick Start Pigsty provides 600 extensions. To use an extension, complete four steps: download, install, configure, and enable. pg-meta: hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } } vars: pg_cluster: pg-meta pg_extensions: [ postgis, …

Source: https://patroni.readthedocs.io/en/latest/standby_cluster.html Patroni supports cascading replication to a remote datacenter or region through the standby cluster feature. A standby cluster has: A standby leader, which behaves like a regular …

Pigsty uses crontab to schedule routine backups, transaction freezing, and reorganization of bloated tables and indexes. Quick Reference Operation Quick Command Description Configure Cron Jobs ./pgsql.yml -t pg_crontab -l <cls> Apply pg_crontab …

Overview The Pigsty PGSQL module has multiple components. Each component runs as a systemd service on nodes, except pgBackRest. To maintain production PostgreSQL clusters, learn how these components work and how to manage them. Component Port Service …

Source: https://patroni.readthedocs.io/en/latest/replica_bootstrap.html Patroni supports custom replica creation and custom bootstrap for a new, empty cluster. These are separate operations. Patroni creates replicas only when the cluster has an …

Overview Pigsty uses Pgbouncer for PostgreSQL connection pooling. By default, it listens on port 6432 and proxies connections to local PostgreSQL on port 5432. This component is optional. If you do not need many connections, transaction pooling, or …

Quick Start Pigsty manages HBA rules declaratively. First define HBA rules in the inventory. Then run bin/pgsql-hba <cls> to refresh them. pg-meta: hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } } vars: pg_cluster: pg-meta pg_hba_rules: # <--- …

Overview Pigsty uses Patroni to manage PostgreSQL clusters. It handles configuration changes, status checks, switchovers, restarts, replica reinitialization, and other operations. To manage clusters with Patroni, use one of these identities: On an …

Source: https://www.pgbouncer.org/usage.html · 1.26.0 source Synopsis pgbouncer [-d][-v][-u user] <pgbouncer.ini> pgbouncer -V|-h On Windows, the options are: pgbouncer.exe [-v][-u user] <pgbouncer.ini> pgbouncer.exe -V|-h Additional options for …

Install PIG with the Linux installer, a system package, or a release archive. The current version is v1.10.0. The download page lists all release files. Script installation On Linux, run: curl -fsSL https://repo.pigsty.io/pig | bash In mainland …

Quick Start Pigsty manages databases declaratively. First define databases in the inventory. Then run bin/pgsql-db <cls> <dbname> to create or modify them. pg-meta: hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } } vars: pg_cluster: pg-meta …

Quick Start Pigsty manages users declaratively. First define users in the inventory. Then run bin/pgsql-user <cls> <username> to create or modify them. pg-meta: hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } } vars: pg_cluster: pg-meta …

Quick Reference Action Command Description Create Cluster bin/pgsql-add <cls> Create a new PostgreSQL cluster Expand Cluster bin/pgsql-add <cls> <ip...> Add replica to existing cluster Shrink Cluster bin/pgsql-rm <cls> <ip...> Remove instance from …