Citus 12.1 is out! Now with PG16 Support. Read all about it in Naisila’s 12.1 blog post. 💥
Citus is a great extension for scaling out Postgres databases horizontally. You can use Citus either on the cloud on Azure or you can download Citus open source and install it wherever. In this blog post, we will focus on Citus open source packaging and installation.
When you go to the Citus download page to download the Citus packages—or you visit the Citus open source docs—many of you jump straight to the install instructions and the particular OS you’re looking for. That way, you can get straight to sharding Postgres with Citus.
But what if you want to see which operating systems the Citus packages support? Or what if you want to install Citus with an older version of Postgres?
This post will answer these types of nitty-gritty questions about Citus packages and their usages. Specifically, this post will cover these questions:
Citus is a Postgres extension which executes side by side with Postgres. You can get detailed information about Postgres extensions on the PostgreSQL wiki and this Citus blog post about what it means to be a Postgres extension. Additionally, you can get lots more information about Citus in the Citus docs
When you install Citus, you execute two commands as shown on the Citus Downloads page. For example, the commands below are the current installation commands for Debian-based systems. At the time of publication of this blog post, these commands will install Postgres 14 and Citus 10.2. We’re using the Debian-based install command as an example... Since both
rpm package installations use two commands to do the install, it is enough to illustrate this point with just the
deb packages example:
curl https://install.citusdata.com/community/deb.sh | sudo bash sudo apt-get -y install postgresql-14-citus-10.2
The first command above (that starts with
curl) is the package repository installation script. This script installs both the
Before installing these two repos, the script performs some validations such as operating system and release version checks to be able to validate installation environment.
The second command:
sudo apt-get -y install postgresql-14-citus-10.2
is a package installation script which installs the versions specified in the command (i.e. Postgres 14 and Citus 10.2 in the example above.)
So, if you install using commands given in the Citus Download page, the Postgres server and required packages for Citus will both be installed automatically (even though the Citus and Postgres are separate packages that is installed in your system.)
Citus open source packages can be downloaded from 4 different package repositories.
|Package Repository||Package Type||Description|
|Main package repository for Citus. All packages released up to now are stored here. You can search for and download any packages using PackageCloud’s easy-to-use interface.|
|PGDG||Rpm||Package repository for Postgres and its extensions, graciously supported by the Postgres community’s packaging team. Keep in mind that sometimes the versions available on PGDG will lag the latest release slightly. Also, PGDG does not support multiple versions. Therefore, you can install only the latest version of Citus on PGDG.|
|PGXN||Zip-based packages||Postgres Extension Network is a central repository for all Postgres extensions. It has its own client and if you have a server which has PGXN client installed on it and want to manage all the Postgres extensions in one place, you can use this option.|
|Docker Hub||Docker images||Citus Docker images include Postgres and Citus together and are pre-configured which makes them good alternatives for you to try out Citus locally.Note that the docker images for Citus are only for development purposes—and are not optimized for production usage. Therefore, if you need to use Citus for test and production servers, Linux packages from one of the other repositories are the best option.|
The main package repository for Citus open source is PackageCloud. All the Citus versions are stored in there and are ready for deployment.
If you want to install an older version of Citus (or install Citus with an older version of Postgres), first you need to install the package repository with the command below:
When downloading previous versions, you need to change the version in the second installation command.
Let’s evaluate the second install command for both
rpm based package installation scripts:
The file name pattern for
deb packages is different. Here’s a comparison for the
package_name structure for each:
If you want to use an older version of Postgres (or of Citus), you can do a parameter replace and switch out the Citus major minor versions and/or the Postgres versions in the package installation commands that you see on the Citus download page. Assuming you get the syntax correct, and if Citus has a package for that specific version, then your customized package download will start and will use the different/older versions that you want.
It is easy to download with parameter replacement if you are sure about what version you want.
If you are not sure about which version of Postgres (and/or Citus) you’d like to install, you may want to search for the desired package versions instead. In that case you can use PackageCloud’s interface to browse and search for the version you want—and then download the packages.
Our Citus open source packages mainly support these stable releases of operating systems:
If a new stable release is added for one of the operating systems above and includes Postgres support, we add support for this release. On occasion, some of you have asked us to add support for non-stable releases. However, we don’t support non-stable releases until they become stable.
When do we decide to stop support of new Citus releases for an operating system? We take 2 criteria into account:
Let me clarify the cases with some real time examples:
The docker images for Citus include both Postgres and Citus together and are pre-configured, which makes them good alternatives for you to experiment with Citus locally.
As you might expect, the Citus docker images are only meant for development purposes (and to give you a quick way to try out Citus and get started)—and they are not optimized for production usage.
Therefore, if you need to use Citus just for development, docker images are the best option since installation effort is near zero. If you need to use Citus for test and production servers, Linux packages are the best option.
The support matrix for the currently supported OS releases (at the time of publication of this blog post) that maps the OS release versions to the Citus versions is as follows:
|OS/Release||Still Supported||Starting with OS Release #||Ending with OS Release # **|
|Enterprise Linux/CentOS 8||Yes||9.0.0|
|Enterprise Linux/ CentOS 7||Yes||5.0.0|
|Enterprise Linux/ CentOS 6||No||5.0.0||9.4.4|
|Oracle Linux 8||Yes||10.0.6|
|Oracle Linux 7||Yes||5.0.0|
|Oracle Linux 6||No||5.0.0||9.4.4|
** As of date of blog post publication. Blank field = still supported for new releases when this blog post was published.
If you have any requests or questions about Citus open source packaging, you can report it to us by opening an issue in our Citus packaging repo on GitHub.
Oh, and if you’re looking for more information about the Citus extension, here are 4 good places to get started: