citus
Citus 分布式 PostgreSQL 集群，提供水平扩展与分片能力
citus 配置模板使用 Citus 扩展部署分布式 PostgreSQL 集群，提供透明的水平扩展与数据分片能力。
配置概览
- 配置名称：
citus - 节点数量： 五节点（1 协调节点 + 4 数据节点）
- 配置说明：Citus 分布式 PostgreSQL 集群
- 适用系统：
el8,el9,el10,d12,d13,u22,u24 - 适用架构：
x86_64 - 相关配置：
meta
启用方式：
./configure -c citus [-i <primary_ip>]
配置内容
源文件地址：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
...配置解读
citus 模板部署 Citus 分布式 PostgreSQL 集群，适合需要水平扩展的大规模数据场景。
关键特性：
- 透明数据分片，自动分布数据到多个节点
- 并行查询执行，聚合多节点结果
- 支持分布式事务（2PC）
- 保持 PostgreSQL SQL 兼容性
架构说明：
- 协调节点 (pg-citus0)：接收查询，路由到数据节点
- 数据节点 (pg-citus1~3)：存储分片数据
适用场景：
- 单表数据量超过单机容量
- 需要水平扩展写入和查询性能
- 多租户 SaaS 应用
- 实时分析型工作负载
注意事项：
- Citus 支持 PostgreSQL 14~17
- 分布式表需要指定分布列
- 部分 PostgreSQL 特性可能受限（如外键跨分片）
- 不支持 ARM64 架构