How to Get Citus

Citus Open Source icon

Citus Open Source

With Citus, you can scale Postgres with superpowers like distributed tables, distributed SQL engine, columnar, & more.

Azure cloud icon

Citus on Azure

You can also spin up a Citus cluster in the cloud on Azure with Azure Cosmos DB for PostgreSQL.

Why Citus?

  • Distributed Scale

    Scale Postgres by distributing data & queries. You can start with a single Citus node, and simply add nodes & rebalance shards in order to grow.

  • Simplified Architecture

    Reduce your infrastructure headaches by using a single database for both your transactional and analytical workloads.

  • Parallelized Performance

    Speed up queries by 20x to 300x (or more) through parallelism, keeping more data in memory, higher I/O bandwidth, and columnar compression.

  • Citus elicorn icon
    Open Source

    Download and use Citus open source for free. You can manage Citus yourself, embrace open source, and help us improve Citus via GitHub.

  • Postgres elephant outline icon
    Power of Postgres

    Citus is an extension (not a fork) to the latest Postgres versions, so you can use your familiar SQL toolset & leverage your Postgres expertise.

  • managed database service cloud icon
    Managed Database Service

    Focus on your application and forget about your database. Run your app on Citus in the cloud with Azure Cosmos DB for PostgreSQL.

2 Ways to Shard Postgres with Citus

Row-based sharding

Row-based sharding is the traditional way Citus does sharding and is useful for all use cases, especially real-time analytics, time series, & IOT.

row-based sharding worker node 1 row-based sharding worker node 2

Schema-based sharding

First introduced in Citus 12, schema-based sharding is easier to use since you don’t need a distribution key. Good for multi-tenant SaaS & microservices.

schema-based sharding worker node 1 schema-based sharding worker node 2

Why Scale Out Postgres? Performance.

Side-By-Side Performance Comparison

YouTube video still: High performance PostgreSQL with Postgres & Hyperscale (Citus)

Watch this demo to see how Citus gives this application ~20X faster transactions and 300X – 150,000X faster analytics queries.

What’s New in Citus?

Citus 12.1 flag

Citus 12.1

Citus 12.1 is out & includes support for Postgres 16! With logical replication enhancements and outer join performance improvements.

Read 12.1 post  |  12.1 updates

Citus Con 2023

Citus Con: An Event for Postgres 2023 is a wrap! Watch the livestream replays or the on-demand sessions. Be inspired.

Watch the replays

newspaper in front of a cloud icon

New Azure Home

We have a new home on Azure! You can now find the Citus managed database service in Azure Cosmos DB for PostgreSQL.

Read the docs  |  Try for free

Citus 12.1 is out! Read all about it in the Citus 12.1 blog post!

Capabilities of Distributed Postgres With Citus

  • Distributed
    SQL Engine
    Distributed query engine Distributed query planner & adaptive executor that parallelizes queries across shards and nodes.
    Distributed schemas Transparently shard your database by schema name across a cluster of Postgres nodes to leverage their combined CPU, memory, disk, and I/O.
    Distributed tables Shard tables across a cluster of Postgres nodes to leverage their combined CPU, memory, disk, and I/O.
    Reference tables Replicate tables to enable JOINs, foreign keys from distributed tables, & faster reads.
    Co-located shards Optimize performance for joins and foreign keys by co-locating shards of distributed tables.
    Parallel distributed SELECT Parallelize analytical queries across the distributed cluster for maximum performance.
    Parallel distributed DML Transform data inside the database with parallelized update, delete, & commands.
    Full SQL query routing Route complex SQL queries and transactions across a cluster with minimal overhead.
    Distributed transactions Perform complex transactions, stored procedures, and more in atomic distributed transactions.
    Parallelized COPY Employ parallel indexing, constraint checking, and disk writes to speed up data loading streams.
    Change Data Capture (CDC, in Preview) Citus 11.3 adds a new citus.enable_change_data_capture setting (in preview) that enables logical replication for distributed tables and reference tables to the CDC clients.
    Columnar storage Compress local and/or distributed tables to save on storage, reduce I/O bandwidth, & speed up analytics queries.
  • Scale Out
    Sharding Transparently distributes tables and schemas across Citus worker nodes, to enable scale out & improve performance.
    Easy to add nodes Easy to add more Citus nodes, whether starting with Citus on a single node or a multi-node cluster.
    Shard rebalancer Redistribute shards across nodes and track rebalancer progress in a Citus cluster. Online, non-blocking, fully open source. In 11.1, added background shard rebalancer.
    Single-node Citus Be scale-out ready by starting (or testing) on a single Citus node. So you can easily add nodes later.
    Distributed Postgres cluster Combine the compute, memory, disk, & IO of multiple database nodes into one database.
    Tenant monitoring New in 11.3, use citus_stat_tenants view to monitor your tenant’s usage statistics
    Tenant isolation Isolate shards for large SaaS tenants to improve performance for other SaaS tenants. Fully open source, and with zero-downtime.
    Sharding flexibility Tooling to change how data is distributed: change shard count, undistribute tables, distribute schemas, undistributed schemas, change distribution column.
    Query from any node Automatic metadata syncing (added in Citus 11) means you can now query from any node if you need to reach higher query throughput.
    HA with Patroni New to Citus 11.2 integration with Patroni 3.0 gives you fully declarative clustering with high availability and automatic failover.
  • Power of
    Open Source PostgreSQL & Citus are built on one of the most collaborative open source ecosystems.
    Packaged as an extension Citus is an extension to Postgres (not a fork)—so when you use Citus, you’re also using Postgres.
    Postgres tooling & ecosystem Rich ecosystem of Postgres tooling & integrations.
    Joins One of the reasons (along with foreign keys & constraints) that teams who need scale want to keep using Postgres.
    Indexes Postgres offers different index types: B-tree, GIN, BRIN, GiST, as well as partial indexes.
    Stored procedures Ability to run functions within the database to execute complex transactions efficiently.
    UPDATE/DELETE Staple of relational databases: the ability to update (modify) or delete older data.
    Constraints Constraints are a powerful construct to enforce rules and keep invalid data out of your Postgres database.
    Time Partitioning Citus works with native Postgres range partitioning, and also provides tooling for easily managing time partitions.
    JSON & JSONB JSON and JSONB data types are a popular way to store & index semi-structured data in Postgres.
    Rich datatypes Citus works well with the 40+ data types in Postgres, plus the ability to create custom, user-defined types.
    Postgres extension compatibility Popular extensions often used with Citus: PostGIS, HLL, pg_cron, pg_stat_statements, t-digest, pgvector, pg_partman, TopN, & more.
  • Managed
    Citus on Azure Citus is available as a managed service with Azure Cosmos DB for PostgreSQL.
    Postgres versions & upgrades Postgres 11, 12, 13, 14, 15, & 16 all available. In-place major PG version upgrades available, with minimal downtime.
    Single node Be scale-out ready by starting small on a single PostgreSQL node. Also handy for testing.
    Scaling up Compute goes up to 104 vcores per node. Easy to increase or decrease compute/memory—and increase storage—on your Azure Cosmos DB for PostgreSQL coordinator & worker nodes.
    Scaling out Easy to add nodes to your Azure Cosmos DB for PostgreSQL cluster with just a few clicks in the portal. Completely online operation with zero application downtime.
    High Availability HA uses standby replicas for all nodes in a cluster, with streaming replication & automated failover.
    Automated backup & restore Automated backups stored in multiple Azure availability zones. Backups stored for 35 days. Point in time recovery (PITR) is supported. You can fork your cluster using PITR, too.
    Geo-redundant DR If something goes wrong with your primary cluster, or with an entire region, you can open a read replica for writes as part of your disaster recovery.
    Monitoring & alerts Automated monitoring, configurable metrics dashboard, plus alert setup through Azure Monitor.
    Security controls Encryption at rest & in flight, firewall rules, and 2FA. Also private link.
    Pay as you go or prepay Pay-as-you-go pricing, or prepay with reserved capacity discounts.
    Azure ecosystem integrations Azure Data Factory, Azure Monitor, Azure Service Health, Azure Data Studio. Also, Azure Stream Analytics (in preview).
    Global read replicas Read-only replicas of Azure Cosmos DB for PostgreSQL clusters available globally, in any supported Azure region. Can be used for DR.
    Managed PgBouncer Outsource PgBouncer administration to Azure.
    Compliance Certifications achieved with Azure Cosmos DB for PostgreSQL: HITRUST, HIPAA, SOC 2 Type 2, ISO 27001, FedRAMP High, & more.
    Functional parity You get functional parity between your local desktop and the cloud by using Citus open source on your desktop and Azure Cosmos DB for PostgreSQL in the cloud.
    Free trial Develop for free with the free trial for Azure Cosmos DB for PostgreSQL.
  • Resources
    Getting Started tips Getting Started page includes a curated set of docs, videos, tutorials, & blog posts to help get you started.
    Packages Download & installation instructions for setting up Citus on a single-node or on a multi-node cluster.
    Documentation Open source Citus docs cover concepts, architecture, admin, tutorials, use case guides, & troubleshooting.
    Videos Playlist of demos & videos can also be found in the Learn Your Way blade on the Citus Getting Started page.
    Release Notes The Updates pages give you all the details about content of each new version.
    Citus Public Slack Citus Slack is for community Q&A about the Citus extension to Postgres.
    Citus Blog Citus Blog publishes engineering posts about Postgres, Citus, sharding, & distributed databases.
    Azure Cosmos DB for PostgreSQL Blog Blog posts about Citus on Azure can be found on the Azure Cosmos DB for PostgreSQL devblog—as well as on Microsoft Tech Community where we used to blog about Hyperscale (Citus) topics too.
    Citus Newsletter Subscribe to the monthly newsletter with thousands of subscribers for useful tech content on Postgres & Citus.
    GitHub repo Open source GitHub repo contains the source code, open issues, changelogs, README, & more.
    Citus Con Videos This playlist includes the 13 user and developer talks from the inaugural Citus Con: An Event for Postgres.

Is Citus Right For You?

Not every application benefits from distributing Postgres, parallelizing queries, compressing tables via columnar, and the ability to scale from a single node to a distributed database cluster. But many do. Some popular use cases for the Citus database: multi-tenant SaaS apps, real-time analytics, time series, & microservices.

Citus workloads Venn diagram
When Not to Use Citus—because not all workloads need Postgres at any scale
  • If you do not expect your app to grow & Postgres on a single node supports your app just fine.
  • If you only need offline analytics & do not need real-time ingest nor real-time queries.
  • If your app does not need to support a large number of concurrent users.
Postgres icon

Scale Out Your Database Without Giving Up Postgres

  • The Citus database is a PostgreSQL extension and not a fork, in sync with all the latest releases.
  • Leverage your PostgreSQL expertise and all your familiar tools in the Postgres ecosystem.
  • Take advantage of all the innovations in Postgres—including rich data types and extensions like JSONB, PostGIS, HyperLogLog, pg_stat_statements, and full text search.
  • Scale out your database without giving up SQL. You don’t get joins from NoSQL databases. And application-level sharding solutions will not give you joins when you need them.
  • Citus makes it simple to shard Postgres. We’ve done the distributed systems engineering work to scale out Postgres for you. So you can use Postgres at any scale—from a single node to a large distributed cluster.