The Citus add-on is a fully-managed
database service that provides a distributed cluster of PostgreSQL
servers with the Citus extension installed and configured.
The Citus extension horizontally scales PostgreSQL across multiple machines
using sharding and replication. Its query engine parallelizes incoming SQL
queries across these servers to enable human real-time (less than a second)
responses on large datasets.
It is an open-source extension on top of PostgreSQL rather than an entire fork,
which gives developers and enterprises the power and familiarity of a
traditional relational database. As an extension, Citus supports new PostgreSQL
releases, allowing users to benefit from new features while maintaining
compatibility with existing PostgreSQL tools.
Citus is accessible over the PostgreSQL protocol, and works with any supported
Postgres client libraries for
Java,
Ruby,
Jruby,
Python,
Go,
and Node.js.
When to Use Citus
Citus provides users real-time responsiveness over large datasets, most commonly seen in rapidly growing event systems or with time series data. Example use cases include:
Analytic dashboards with sub-second response times
Exploratory queries on unfolding events
Large dataset archival and reporting
Analyzing sessions with funnel, segmentation, and cohort queries
For concrete examples check out our customer use cases. Typical Citus workloads involve ingesting large volumes of data and running analytic queries on that data in real-time.
Provisioning the add-on
Citus can be attached to a Heroku application via the CLI:
A list of all plans available can be found here.
Once Citus has been added a CITUS_URL setting will be available in the app configuration and will contain the canonical URL used to access the newly provisioned Citus formation. This can be confirmed using the heroku config:get command.
After installing Citus the application should be configured to fully integrate with the add-on.
Creating distributed tables
Because Citus is an extension on top of Postgres, creating, modifying, updating, and deleting data works exactly the same as vanilla Postgres. To take advantage of the distributed features of Citus, you must mark specific tables as distributed tables.
To create distributed tables on your Citus cluster you first run:
And then to actually create your shards you’d run:
For more on detailed usage and setup you can read the Citus Docs
Local development setup
In many cases, a normal Postgres database can be used locally, and instructions
for setting up a local Postgres server can be found
here.
In cases where higher fidelity is necessary you can either run install a local, single-machine cluster or run against a remote Citus formation by provisioning the add-on and locally replicating the config vars so your development environment can operate against the service.
Remote service setup
The Citus add-on can be used remotely in lieu of setting up a local single-machine cluster. First provision the add-on using the above guide. You can then use the CITUS_URL for local development. Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command for each value that you want to add to your .env file.
Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.
For more information, see the Heroku Local article.
Single-machine local cluster setup
Citus can be installed for use in a local development environment as a single-machine cluster. Typically this entails installing the database and pointing the CITUS_URL to this local cluster.
Instructions for setting up a local, single-machine Citus cluster can be found here with instructions for Mac OS, Fedora/CentOS/Red Hat, Ubuntu/Debian, and Docker.
Removing the add-on
Citus can be removed via the CLI.
This will destroy all associated data and cannot be undone!
Before removing Citus, a data export can be performed by pg_dump.
Support
All Citus support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at our public slack channel.