Upgrading Citus

Upgrading Citus Versions

Upgrading the Citus version requires first obtaining the new Citus extension and then installing it in each of your database instances. Citus uses separate packages for each minor version to ensure that running a default package upgrade will provide bug fixes but never break anything. Let’s start by examining patch upgrades, the easiest kind.

Patch Version Upgrade

To upgrade a Citus version to its latest patch, issue a standard upgrade command for your package manager. Assuming version 12.1 is currently installed on Postgres 16:

Ubuntu or Debian

sudo apt-get update
sudo apt-get install --only-upgrade postgresql-16-citus-12.1
sudo service postgresql restart

Fedora, CentOS, or Red Hat

sudo yum update citus121_16
sudo service postgresql-16 restart

Major and Minor Version Upgrades

Major and minor version upgrades follow the same steps, but be careful: they can make backward-incompatible changes in the Citus API. It is best to review the Citus changelog before an upgrade and look for any changes which may cause problems for your application.


Starting at version 8.1, new Citus nodes expect and require encrypted inter-node communication by default, whereas nodes upgraded to 8.1 from an earlier version preserve their earlier SSL settings. Be careful when adding a new Citus 8.1 (or newer) node to an upgraded cluster that does not yet use SSL. The adding a worker section covers that situation.

Each major and minor version of Citus is published as a package with a separate name. Installing a newer package will automatically remove the older version.

Step 1. Update Citus Package

If upgrading both Citus and Postgres, always be sure to upgrade the Citus extension first, and the PostgreSQL version second (see Upgrading PostgreSQL version from 15 to 16). Here is how to do a Citus upgrade from 11.3 to 12.1 on Postgres 15:

Ubuntu or Debian

sudo apt-get update
sudo apt-get install postgresql-15-citus-12.1
sudo service postgresql restart

Fedora, CentOS, or Red Hat

# Fedora, CentOS, or Red Hat
sudo yum swap citus113_15 citus121_15
sudo service postgresql-15 restart

Step 2. Apply Update in DB

After installing the new package and restarting the database, run the extension upgrade script.

-- you must restart PostgreSQL before running this

-- you should see the upgraded Citus version
SELECT * FROM citus_version();

-- if upgrading to Citus 11.x or later,
-- run on the coordinator node
CALL citus_finish_citus_upgrade();


If upgrading to Citus 11.x from an earlier major version, the citus_finish_citus_upgrade() procedure will make sure that all worker nodes have the right schema and metadata. It may take several minutes to run, depending on how much metadata needs to be synced.


During a major version upgrade, from the moment of yum installing a new version, Citus will refuse to run distributed queries until the server is restarted and ALTER EXTENSION is executed. This is to protect your data, as Citus object and function definitions are specific to a version. After a yum install you should (a) restart and (b) run alter extension. In rare cases if you experience an error with upgrades, you can disable this check via the citus.enable_version_checks configuration parameter. You can also contact us providing information about the error, so we can help debug the issue.

Upgrading PostgreSQL version from 15 to 16


Do not attempt to upgrade both Citus and Postgres versions at once. If both upgrades are desired, upgrade Citus first.

Also, if you’re running Citus 10.0 or 10.1, don’t upgrade your Postgres version. Upgrade to at least Citus 10.2 and then perform the Postgres upgrade.

Record the following paths before you start (your actual paths may be different than those below):

Existing data directory (e.g. /opt/pgsql/15/data)

export OLD_PG_DATA=/opt/pgsql/15/data

Existing PostgreSQL installation path (e.g. /usr/pgsql-15)

export OLD_PG_PATH=/usr/pgsql-15

New data directory after upgrade

export NEW_PG_DATA=/opt/pgsql/16/data

New PostgreSQL installation path

export NEW_PG_PATH=/usr/pgsql-16

For Every Node

  1. Back up Citus metadata in the old coordinator node.

-- run this on the coordinator and worker nodes

SELECT citus_prepare_pg_upgrade();
  1. Configure the new database instance to use Citus.

  • Include Citus as a shared preload library in postgresql.conf:

    shared_preload_libraries = 'citus'
  • DO NOT CREATE Citus extension

  • DO NOT start the new server

  1. Stop the old server.

  2. Check upgrade compatibility.

    $NEW_PG_PATH/bin/pg_upgrade -b $OLD_PG_PATH/bin/ -B $NEW_PG_PATH/bin/ \
                                -d $OLD_PG_DATA -D $NEW_PG_DATA --check

    You should see a “Clusters are compatible” message. If you do not, fix any errors before proceeding. Please ensure that

  • NEW_PG_DATA contains an empty database initialized by new PostgreSQL version

  • The Citus extension IS NOT created

  1. Perform the upgrade (like before but without the --check option).

$NEW_PG_PATH/bin/pg_upgrade -b $OLD_PG_PATH/bin/ -B $NEW_PG_PATH/bin/ \
                            -d $OLD_PG_DATA -D $NEW_PG_DATA
  1. If you did not set up TLS configuration yourself, Citus will have done that and you need to copy the Citus-generated postgresql.auto.conf file along with the generated certificate files (server.crt and server.key)

cp $OLD_PG_DATA/postgresql.auto.conf $NEW_PG_DATA/
cp $OLD_PG_DATA/server.crt $NEW_PG_DATA/
cp $OLD_PG_DATA/server.key $NEW_PG_DATA/
  1. Start the new server.

  • DO NOT run any query before running the queries given in the next step

  1. Restore metadata on new coordinator node.

-- run this on the coordinator and worker nodes

SELECT citus_finish_pg_upgrade();