Citus quickstart

Citus turns Postgres into a distributed database. Citus is supported for use on Crunchy Bridge, but requires some additional configuration in order to operate most effectively. This guide will walk you through the steps of setting up Citus on Crunchy Bridge.

Provisioning a Cluster Group

When you configure a group of clusters to use Citus, querying your data will often mean drawing results that span across multiple nodes. Because of this, you want your Postgres instances to be located very close together. Crunchy Bridge enables this kind of geographic colocation using Cluster Groups. Cluster Groups ensure that all the provisioned are connected within the same VPC and region, reducing latency and maximizing network performance as much as possible.


Note: Due to increased overhead and coordination cost, all clusters provisioned within a Cluster Group are subject to a 10% surcharge.

To provision a Cluster Group, navigate to Team settings and then to Cluster Group.

Before provisioning your Cluster Group, you will first need to decide on your desired cloud provider (AWS, Azure, or GCP) and region. When provisioning, you will specify Citus as the kind of Cluster Group.

Provision your instances

After your Cluster Group has been created, next you need to provision your Postgres clusters within the group. You'll need one coordinator node, and one cluster for each desired worker node. When provisioning your clusters, remember that the actual cost billed to you per cluster will include a 10% surcharge.

To provision additional Citus nodes in the Cluster Group after the initial setup, navigate to the Cluster Group and provision the additional clusters from the Cluster Group interface.

Installing Citus and connecting nodes

Once the coordinator and worker nodes have all been created, the next step is to install Citus. To do this, connect to each of your nodes and run:

GRANT local_network_trust TO postgres;


The Citus installation commands shown above need to be run on every node, including the coordinator and all workers.

Once you've installed Citus on the coordinator and every worker node, next you need to connect your worker nodes to the coordinator. This process is done on the coordinator node. Connect to the coordinator and run the following command once for each worker, substituting the specific hostname for each worker node:

select * from citus_add_node('', 5432);


You can find the hostname of any cluster in the Cluster Overview section of the dashboard, or by running cb info <cluster ID> on the CLI.

Once everything is wired up, you can execute a query to see all of your worker nodes in the Citus metadata:

FROM pg_dist_node;

Getting started with Citus

Now that you've configured your Citus Cluster you're ready to begin using Citus on Crunchy Bridge.

To learn more about Citus on Crunchy Bridge, check out Citus use cases or review Citus terminology.