citus
Citus distributed PostgreSQL cluster, provides horizontal scaling and sharding capabilities
The citus configuration template deploys a distributed PostgreSQL cluster using the Citus extension, providing transparent horizontal scaling and data sharding capabilities.
Overview
- Config Name:
citus - Node Count: Five nodes (1 coordinator + 4 data nodes)
- Description: Citus distributed PostgreSQL cluster
- OS Distro:
el8,el9,el10,d12,d13,u22,u24 - OS Arch:
x86_64 - Related:
meta
Usage:
./configure -c citus [-i <primary_ip>]
Content
Source: pigsty/conf/citus.yml
---
#==============================================================#
# File : citus.yml
# Desc : 1-node Citus (Distributive) Config Template
# Ctime : 2020-05-22
# Mtime : 2025-12-28
# Docs : https://doc.pgsty.com/config
# License : Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright : 2018-2026 Ruohang Feng / Vonng ([email protected])
#==============================================================#
# This is the config template for Citus Distributive Cluster
# tutorial: https://doc.pgsty.com/pgsql/kernel/citus
#
# Usage:
# curl https://repo.pigsty.io/get | bash
# ./configure -c citus
# ./deploy.yml
all:
children:
infra: { hosts: { 10.10.10.10: { infra_seq: 1 }} ,vars: { repo_enabled: false }}
etcd: { hosts: { 10.10.10.10: { etcd_seq: 1 }} ,vars: { etcd_cluster: etcd }}
#minio: { hosts: { 10.10.10.10: { minio_seq: 1 }} ,vars: { minio_cluster: minio }}
#----------------------------------------------#
# pg-citus: 10 node citus cluster
#----------------------------------------------#
pg-citus: # the citus group contains 5 clusters
hosts:
10.10.10.10: { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.60/24 ,pg_seq: 0, pg_role: primary }
#10.10.10.11: { pg_group: 0, pg_cluster: pg-citus0 ,pg_vip_address: 10.10.10.60/24 ,pg_seq: 1, pg_role: replica }
#10.10.10.12: { pg_group: 1, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.61/24 ,pg_seq: 0, pg_role: primary }
#10.10.10.13: { pg_group: 1, pg_cluster: pg-citus1 ,pg_vip_address: 10.10.10.61/24 ,pg_seq: 1, pg_role: replica }
#10.10.10.14: { pg_group: 2, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.62/24 ,pg_seq: 0, pg_role: primary }
#10.10.10.15: { pg_group: 2, pg_cluster: pg-citus2 ,pg_vip_address: 10.10.10.62/24 ,pg_seq: 1, pg_role: replica }
#10.10.10.16: { pg_group: 3, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.63/24 ,pg_seq: 0, pg_role: primary }
#10.10.10.17: { pg_group: 3, pg_cluster: pg-citus3 ,pg_vip_address: 10.10.10.63/24 ,pg_seq: 1, pg_role: replica }
#10.10.10.18: { pg_group: 4, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.64/24 ,pg_seq: 0, pg_role: primary }
#10.10.10.19: { pg_group: 4, pg_cluster: pg-citus4 ,pg_vip_address: 10.10.10.64/24 ,pg_seq: 1, pg_role: replica }
vars:
pg_mode: citus # pgsql cluster mode: citus
pg_shard: pg-citus # citus shard name: pg-citus
pg_primary_db: citus # primary database used by citus
pg_dbsu_password: DBUser.Postgres # enable dbsu password access for citus
pg_extensions: [ citus, postgis, pgvector, topn, pg_cron, hll ] # install these extensions
pg_libs: 'citus, pg_cron, pg_stat_statements' # citus will be added by patroni automatically
pg_users: [{ name: dbuser_citus ,password: DBUser.Citus ,pgbouncer: true ,roles: [ dbrole_admin ] }]
pg_databases: [{ name: citus ,owner: dbuser_citus ,extensions: [ citus, vector, topn, pg_cron, hll ] }]
pg_parameters:
cron.database_name: citus
citus.node_conninfo: 'sslrootcert=/pg/cert/ca.crt sslmode=verify-full'
pg_hba_rules:
- { user: 'all' ,db: all ,addr: 127.0.0.1/32 ,auth: ssl ,title: 'all user ssl access from localhost' }
- { user: 'all' ,db: all ,addr: intra ,auth: ssl ,title: 'all user ssl access from intranet' }
pg_vip_enabled: true # enable vip for citus cluster
pg_vip_interface: eth1 # vip interface for all members (you can override this in each host)
vars: # global variables
#----------------------------------------------#
# INFRA : https://doc.pgsty.com/infra/param
#----------------------------------------------#
version: v4.0.0 # pigsty version string
admin_ip: 10.10.10.10 # admin node ip address
region: default # upstream mirror region: default,china,europe
infra_portal: # infra services exposed via portal
home : { domain: i.pigsty } # default domain name
#----------------------------------------------#
# NODE : https://doc.pgsty.com/node/param
#----------------------------------------------#
nodename_overwrite: true # overwrite hostname since this is a multi-node tempalte
node_repo_modules: node,infra,pgsql # add these repos directly to the singleton node
node_tune: oltp # node tuning specs: oltp,olap,tiny,crit
#----------------------------------------------#
# PGSQL : https://doc.pgsty.com/pgsql/param
#----------------------------------------------#
pg_version: 17 # Default PostgreSQL Major Version is 17
pg_conf: oltp.yml # pgsql tuning specs: {oltp,olap,tiny,crit}.yml
pg_packages: [ pgsql-main, pgsql-common ] # pg kernel and common utils
#pg_extensions: [ pg17-time ,pg17-gis ,pg17-rag ,pg17-fts ,pg17-olap ,pg17-feat ,pg17-lang ,pg17-type ,pg17-util ,pg17-func ,pg17-admin ,pg17-stat ,pg17-sec ,pg17-fdw ,pg17-sim ,pg17-etl]
#repo_extra_packages: [ pgsql-main, citus, postgis, pgvector, pg_cron, hll, topn ]
#----------------------------------------------#
# PASSWORD : https://doc.pgsty.com/config/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
...Explanation
The citus template deploys a Citus distributed PostgreSQL cluster, suitable for large-scale data scenarios requiring horizontal scaling.
Key Features:
- Transparent data sharding, automatically distributes data to multiple nodes
- Parallel query execution, aggregates results from multiple nodes
- Supports distributed transactions (2PC)
- Maintains PostgreSQL SQL compatibility
Architecture:
- Coordinator Node (pg-citus0): Receives queries, routes to data nodes
- Data Nodes (pg-citus1~3): Stores sharded data
Use Cases:
- Single table data volume exceeds single-node capacity
- Need horizontal scaling for write and query performance
- Multi-tenant SaaS applications
- Real-time analytical workloads
Notes:
- Citus supports PostgreSQL 14~17
- Distributed tables require specifying a distribution column
- Some PostgreSQL features may be limited (e.g., cross-shard foreign keys)
- ARM64 architecture not supported
Feedback
Was this page helpful?
Thanks for the feedback! Please let us know how we can improve.
Sorry to hear that. Please let us know how we can improve.