Citus — Distributed PostgreSQL for Sharding and HTAP

Introduction

Citus is an open-source Postgres extension (Apache 2.0, maintained by Microsoft) that transforms a single-node Postgres into a distributed SQL database. It shards tables across worker nodes, parallelises queries, supports columnar storage for analytics and keeps the full Postgres surface area — JSONB, PostGIS, extensions, triggers, indexes, ACID.

What Citus Does

• Distributes tables by a shard key across N worker Postgres nodes.
• Parallelises SELECT, INSERT ... SELECT, UPDATE, DELETE and DDL across shards.
• Provides reference tables that are replicated to every node for joins with fact tables.
• Ships a columnar access method for compressed analytical storage and fast scans.
• Supports schema-based sharding and tenant-isolation patterns for multi-tenant SaaS.

Architecture Overview

A coordinator node stores metadata and receives client connections. Tables are sharded into many logical pieces, each a regular Postgres table on a worker. The coordinator rewrites queries into per-shard fragments executed in parallel by workers, then merges the results. Reference tables are replicated on every worker so joins happen locally. MX mode lets workers accept connections directly for horizontal client scaling.

Self-Hosting & Configuration

• Install via apt/yum packages, Docker Compose, or CREATE EXTENSION citus; on any Postgres 14+.
• Pick a shard key with good cardinality and co-locate related tables on the same key.
• Use citus.shard_count and citus.shard_replication_factor for sizing and fault tolerance.
• Enable columnar storage per partition (USING columnar) for historical data.
• Scale by running SELECT citus_add_node() and rebalance_table_shards() online.

Key Features

• Real HTAP: mixed OLTP and OLAP on the same tables with columnar partitions.
• Rolling upgrades and online shard rebalancing — no downtime.
• Full PostgreSQL compatibility including CTEs, window functions, JSONB, PostGIS, pg_trgm.
• Multi-tenant sharding with CREATE DATABASE ... WITH TEMPLATE and schema-based isolation.
• Works on managed Azure Cosmos DB for PostgreSQL and any self-hosted Postgres fleet.

Comparison with Similar Tools

• TimescaleDB — also an extension; focused on time-series, single-node primarily.
• CockroachDB / YugabyteDB — Postgres-like but not extensions; distributed by design.
• Vitess — sharding for MySQL; different ecosystem.
• pg_shard / PL/Proxy — older sharding approaches; Citus is their spiritual successor.
• Postgres-XL — distributed fork that drifts from mainline; Citus stays upstream-compatible.

FAQ

Q: Is Citus a fork of Postgres? A: No — it is an extension. You run standard Postgres and CREATE EXTENSION citus. Q: What workloads fit Citus best? A: Multi-tenant SaaS, real-time analytics dashboards, time-series and HTAP workloads. Q: Can I use existing Postgres tools? A: Yes — pg_dump, logical replication, psql, pgBouncer, Postgres JDBC/drivers all work. Q: Does Microsoft still maintain it? A: Yes — active development on GitHub, with regular releases tracking new Postgres majors.

Sources

• https://github.com/citusdata/citus
• https://docs.citusdata.com/