Citus 11 for PostgreSQL: Fully Open‑Source and Queryable from Any Node

Overview

Citus 11.0 is a major release of the PostgreSQL extension that adds distributed‑database capabilities. All previously enterprise‑only features are now fully open source, allowing developers to interact directly with the code, avoid vendor lock‑in, and benefit from new scalability improvements.

Non‑blocking Shard Rebalancer

The most exciting open‑source feature is the non‑blocking shard mover. In Citus 10, moving shards blocked writes to the affected shards. Citus 11 uses logical replication for shard moves, so only a brief write latency occurs while data is transferred to new nodes, provided every table has a primary key.

Query from Any Node

Citus 11 introduces automatic schema and metadata synchronization. Previously, only the coordinator held metadata, so distributed queries had to run through it. Now all nodes have up‑to‑date metadata, allowing any worker node to execute distributed queries and enabling load‑balancing of heavy query workloads.

Figure 1 shows a Citus 10.2 cluster where metadata exists only on the coordinator. Figure 2 shows a Citus 11.0 cluster where the same metadata is automatically synchronized to all nodes, allowing any node to run distributed queries.

Upgrade Procedure

Upgrading an existing Citus cluster to version 11 is straightforward:

Install the new package and restart PostgreSQL.

On every node run: ALTER EXTENSION citus UPDATE; After all nodes are upgraded, connect to the coordinator and execute: CALL citus_finish_citus_upgrade(); No application changes are required; the coordinator continues to handle queries, but you may optionally route queries to worker nodes for better load distribution. The upgrade also introduces deprecations:

Shard placement failure : the failure‑based placement mechanism is removed.

Append distributed tables : existing append‑distributed tables become read‑only; migration to hash‑distributed tables is recommended.

Distributed cstore_fdw tables : using cstore_fdw with distributed tables is no longer recommended; conversion to columnar storage is advised.

Where Are My Shards?

With metadata now hidden, shards are not listed by default when querying a worker node. To view shards, set the citus.show_shards_for_app_name_prefixes parameter. For example:

-- Show shards only to pgAdmin and psql (based on their application_name):
set citus.show_shards_for_app_name_prefixes to 'pgAdmin,psql';

-- Show shards to all applications:
set citus.show_shards_for_app_name_prefixes to '*';
\d
List of relations
┌────────┬──────────────┬───────┬───────┐
│ Schema │     Name     │ Type  │ Owner │
├────────┼──────────────┼───────┼───────┤
│ public │ citus_tables │ view  │ marco │
│ public │ ref          │ table │ marco │
│ public │ test         │ table │ marco │
│ public │ ref_102040   │ table │ marco │
│ public │ test_102105  │ table │ marco │
│ public │ test_102107  │ table │ marco │
└────────┴──────────────┴───────┴───────┘

Hidden Preview Feature: Triggers on Distributed Tables

Triggers are a core PostgreSQL feature for maintaining complex data models. With metadata on every node, triggers defined on a distributed table’s shards can now fire on the worker node that stores the shard, affecting other distributed tables.

Citus pushes trigger calls to each shard, but it cannot infer the trigger’s logic. To avoid transactional issues, triggers should only access rows that share the same shard key. Users must enable the citus.enable_unsafe_triggers setting explicitly.

CREATE TABLE data (key text primary key, value jsonb);
SELECT create_distributed_table('data','key');
CREATE TABLE data_audit (operation text, key text, new_value jsonb, change_time timestamptz default now());
SELECT create_distributed_table('data_audit','key', colocate_with => 'data');
-- we know this function only writes to a co‑located table using the same key
CREATE OR REPLACE FUNCTION audit_trigger() RETURNS trigger AS $$
DECLARE
BEGIN
    INSERT INTO data_audit VALUES (TG_OP, COALESCE(OLD.key, NEW.key), NEW.value);
    RETURN NULL;
END;
$$ LANGUAGE plpgsql;
SET citus.enable_unsafe_triggers TO on;
CREATE TRIGGER data_audit_trigger
AFTER INSERT OR UPDATE OR DELETE ON data
FOR EACH ROW EXECUTE FUNCTION audit_trigger();

When used carefully—accessing only the co‑located shard key—triggers reduce the need for distributed queries and network round‑trips, improving overall scalability.