Citus: scaling Postgres horizontally without leaving it
Actualizado: 2026-05-03
Postgres is a wonderful database until you stop fitting on a single node. At that point three paths open up: move everything to a distributed database like CockroachDB or YugabyteDB, build manual sharding with external tooling, or use Citus. This post focuses on Citus because in 2025 it has finally found its place: no longer a risky bet or a commercial promise, but a solid Postgres extension solving a concrete problem with less disruption than the alternatives.
Key takeaways
- Citus adds an extension to the coordinator and worker nodes that intercepts query planning and distributes it, while presenting as a single Postgres from the outside.
- The distribution key is the most important decision you’ll make: it conditions the performance of every subsequent query.
- Citus shines in three scenarios: multi-tenant with clean per-customer partitioning, real-time analytics on time-series data, and applications that grew inside Postgres to need the next jump without a rewrite.
- Queries crossing distinct distribution keys are slow because the coordinator has to move data between workers.
- Citus works best when adopted as an early architectural decision, not a late patch.
The short history: from commercial fork to open extension
Citus was born in 2011 as a startup offering distributed Postgres. Microsoft bought the company in 2019 and for two years the project visibly chilled. The turn came in 2022, when Microsoft open-sourced the entirety of the code, including the historic enterprise features, under AGPLv3. Citus is now a Postgres extension you can install via apt, compile from source, or deploy on any distribution without license payments. The current 13.x series is compatible with Postgres 17.
How Citus works
The core idea is designed with Postgres in mind from day one. Instead of rewriting the storage engine, it adds an extension to the coordinator and worker nodes that intercepts query planning and distributes it. From outside, the cluster looks like a single Postgres.
Citus distinguishes three table types:
- Distributed tables: partition by a column called the distribution key, which defines which worker holds each row.
- Reference tables: replicate across all nodes because they’re small and join-heavy with distributed ones.
- Local tables: stay only on the coordinator for data that doesn’t need to scale.
The ideal distribution key spreads data uniformly and appears in most filters and joins. The clearest success cases are multi-tenant applications where the customer identifier is the natural key.
Where it fits well and where it hurts
Citus shines in three concrete scenarios:
- Multi-tenant: where data partitions cleanly by customer or organization. Scaling is almost linear: the cluster grows by adding workers.
- Real-time analytics on time-series-like data: Citus splits aggregate queries in parallel across workers. Improvement factors of ten to twenty versus a monolithic Postgres with the same total hardware.
- Applications that grew inside Postgres to a large node and need the next jump without a full rewrite.
Where it hurts:
- Queries crossing distinct distribution keys are slow because the coordinator has to move data between workers.
- Multi-partition transaction support exists, but is slower and more fragile than local transactions in a single Postgres.
- Operations: a Citus cluster is more complex than a single Postgres, with a coordinator that’s a single point of failure unless HA is set up.
When it pays off
Citus pays off when three signals align:
- Your app already runs on Postgres.
- It has grown to need more than one server.
- It has a clear natural partitioning by customer, region, project, or similar.
If all three signals are present, Citus offers the lowest-disruption path. If the third is missing, you’ll pick a bad distribution key and Citus will deliver worse results than a bigger monolithic node.
Citus works best when adopted as an early architectural decision, not a late patch. If the system already has performance issues today, stabilize the single node first with read replicas and caches, then plan Citus as the next phase.
Conclusion
Citus is the right answer for a specific niche: Postgres that has grown beyond what a single node can handle, with a naturally partitionable load. Outside that niche, distributed alternatives or scale-up are better options. Inside it, Citus offers the lowest-disruption path of any alternative.
