POSETTE 2024 is a wrap! 💯 Thanks for joining the fun! Missed it? Watch all 42 talks online 🍿
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:
- Do you have to install Postgres separately before installing Citus?
- Where can you download Citus packages, from which package repos?
- How can you download older versions of Citus (or Citus for older versions of Postgres)?
- Which OS versions does Citus support?
- What are the docker images used for?
- Is there a matrix of all the operating systems supported by Citus?
- Where can packaging-related requests be reported?
Do you have to install Postgres separately before installing Citus?
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 deb and 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
- Postgres repository, and
- Citus PackageCloud package installation repository
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.)
Where can you download Citus packages, from which package repos?
Citus open source packages can be downloaded from 4 different package repositories.
| Package Repository | Package Type | Description |
|---|---|---|
| PackageCloud | Deb Rpm | 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. |
How can you download older versions of Citus (or Citus for older versions of Postgres)?
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:
| Deb | curl https://install.citusdata.com/community/deb.sh | sudo bash |
| Rpm | curl https://install.citusdata.com/community/rpm.sh | sudo bash |
When downloading previous versions, you need to change the version in the second installation command.
Let’s evaluate the second install command for both .deb and rpm based package installation scripts:
| Deb | sudo apt-get -y install postgresql-14-citus-10.2 |
| Rpm | sudo yum install -y citus102_14 |
The file name pattern for rpm and deb packages is different. Here’s a comparison for the package_name structure for each:
| Deb | sudo apt-get -y install postgresql-<postgres_version>-citus-<citus_major_version>.<citus_minor_version> |
| Rpm | sudo yum install -y citus <citus_major_version><citus_minor_version>_<postgres_version> |
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.
Browsing and searching for release versions on PackageCloud
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.
- Go to the Citus Community on PackageCloud
- Enter the version you want to download in the search box
- Click on the package name you want to install.
- Copy and execute the command in the install section
Which OS versions does Citus support?
Our Citus open source packages mainly support these stable releases of operating systems:
- Debian
- Ubuntu
- Red Hat
- CentOS
- Fedora
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:
- Add/drop support decision of Operating System maintainers for OS releases.
- Add/drop support decision of Postgres Maintainers for OS releases.
Let me clarify the cases with some real time examples:
- Debian 8 Jessie: Debian dropped support for Debian 8 (code name jessie) as June 2020. Citus dropped support for this release after 9.5 release but kept the packages released before for Debian 8.
- Ubuntu Xenial: Postgres team dropped support for Ubuntu Xenial as of September 2021 so that we dropped support for Ubuntu/Xenial after 10.1.1 release as of September 2021 as well and kept the packages released before for Ubuntu/Xenial
What are the docker images used for?
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.
Is there a matrix of all the operating systems supported by Citus?
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 |
| Debian Bullseye | Yes | 10.0.6 | |
| Debian Buster | Yes | 9.0.0 | |
| Debian Stretch | Yes | 7.0.2 | |
| Debian Jessie | No | 5.0.0 | 8.3.3 |
| Debian Wheezy | No | 5.0.0 | 8.0.2 |
| Ubuntu Bionic | Yes | 7.2.2 | |
| Ubuntu Focal | Yes | 9.3.3 | |
| Ubuntu Xenial | No | 7.0.2 | 10.0.5 |
| Ubuntu Precise | No | 5.0.0 | 6.2.3 |
| Ubuntu Trusty | No | 5.0.0 | 8.3.3 |
| Ubuntu Wily | No | 5.0.0 | 5.2.1 |
** As of date of blog post publication. Blank field = still supported for new releases when this blog post was published.
Where can packaging-related requests be reported?
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:
