--- title: "Deploy Citus" description: "Distributed PostgreSQL for scalable apps, sharding, and parallel queries." category: "Storage" url: https://railway.com/deploy/citus --- # Deploy Citus Distributed PostgreSQL for scalable apps, sharding, and parallel queries. **[Deploy Citus on Railway](https://railway.com/template/citus)** - **Creator:** INF Labs - **Category:** Storage ## Template content ### citus-coordinator https://www.gravatar.com/avatar/dd38f13be11e2b1f99d378cb71587d9f?s=120&r=g&d=404 - **Image:** citusdata/citus:14.1.0 - **Start command:** `/bin/bash -c 'export PATH="/usr/lib/postgresql/18/bin:$PATH"; docker-entrypoint.sh postgres & PG_PID=$!; until pg_isready -h 127.0.0.1 -p 5432 -U "$POSTGRES_USER"; do sleep 2; done; until pg_isready -h citus-worker-1.railway.internal -p 5432 -U "$POSTGRES_USER"; do sleep 2; done; until pg_isready -h citus-worker-2.railway.internal -p 5432 -U "$POSTGRES_USER"; do sleep 2; done; until pg_isready -h citus-worker-3.railway.internal -p 5432 -U "$POSTGRES_USER"; do sleep 2; done; psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "CREATE EXTENSION IF NOT EXISTS citus;" -c "SELECT citus_set_coordinator_host(\$\$citus-coordinator.railway.internal\$\$, 5432);" -c "SELECT citus_add_node(\$\$citus-worker-1.railway.internal\$\$, 5432) WHERE NOT EXISTS (SELECT 1 FROM pg_dist_node WHERE nodename = \$\$citus-worker-1.railway.internal\$\$ AND nodeport = 5432);" -c "SELECT citus_add_node(\$\$citus-worker-2.railway.internal\$\$, 5432) WHERE NOT EXISTS (SELECT 1 FROM pg_dist_node WHERE nodename = \$\$citus-worker-2.railway.internal\$\$ AND nodeport = 5432);" -c "SELECT citus_add_node(\$\$citus-worker-3.railway.internal\$\$, 5432) WHERE NOT EXISTS (SELECT 1 FROM pg_dist_node WHERE nodename = \$\$citus-worker-3.railway.internal\$\$ AND nodeport = 5432);"; wait "$PG_PID"'` ### citus-worker-3 https://www.gravatar.com/avatar/dd38f13be11e2b1f99d378cb71587d9f?s=120&r=g&d=404 - **Image:** citusdata/citus:14.1.0 ### citus-worker-1 https://www.gravatar.com/avatar/dd38f13be11e2b1f99d378cb71587d9f?s=120&r=g&d=404 - **Image:** citusdata/citus:14.1.0 ### citus-worker-2 https://www.gravatar.com/avatar/dd38f13be11e2b1f99d378cb71587d9f?s=120&r=g&d=404 - **Image:** citusdata/citus:14.1.0 ## Documentation # Deploy and Host Citus on Railway Citus is an open-source PostgreSQL extension that transforms PostgreSQL into a distributed database. It enables horizontal scaling through sharding, parallel query execution, and distributed tables while preserving the familiar PostgreSQL ecosystem, SQL syntax, drivers, and tooling. ## About Hosting Citus Hosting Citus on Railway lets you run a distributed PostgreSQL cluster without manually provisioning multiple servers. This template uses a coordinator and three worker nodes. The coordinator acts as the main PostgreSQL entry point and manages distributed metadata, while the worker nodes store distributed table shards and execute queries in parallel. Each node uses persistent storage, and internal cluster communication runs through Railway's private network. Only the coordinator needs to be exposed to external PostgreSQL clients. This architecture is suitable for applications that have outgrown a single PostgreSQL instance and need horizontal scaling while retaining PostgreSQL compatibility. ## Common Use Cases - Scale PostgreSQL horizontally across multiple nodes - Shard large tables across distributed workers - Build scalable multi-tenant SaaS applications - Run parallel analytical queries on PostgreSQL data - Handle large event, telemetry, and time-series datasets - Distribute high-volume application workloads - Scale reporting and aggregation queries - Reduce pressure on a single PostgreSQL server - Build distributed data platforms using familiar PostgreSQL tooling ## Dependencies for Citus Hosting - Citus coordinator node - Three Citus worker nodes - Persistent storage for each PostgreSQL node - Railway private networking between coordinator and workers - PostgreSQL-compatible clients and drivers ## Citus Architecture This template uses a four-node Citus cluster: ```text External Applications │ ▼ Citus Coordinator │ │ Railway Private Network │ ┌────┼────┐ ▼ ▼ ▼ Worker Worker Worker 1 2 3 │ │ │ Volume Volume Volume ```` The coordinator is responsible for: * Accepting PostgreSQL client connections * Managing distributed table metadata * Planning distributed queries * Routing queries to the appropriate worker nodes * Coordinating parallel query execution The workers are responsible for: * Storing distributed table shards * Executing queries against local shards * Returning partial results to the coordinator * Providing horizontal storage and compute capacity Each node uses its own persistent storage because distributed table data is physically stored across the worker nodes. ## Citus vs Similar Platforms | Feature | Citus | PostgreSQL | CockroachDB | ClickHouse | | ---------------------------- | ----: | ---------: | ----------: | ---------: | | PostgreSQL compatibility | ✅ | ✅ | ⚠️ | ❌ | | Horizontal scaling | ✅ | ❌ | ✅ | ✅ | | Distributed tables | ✅ | ❌ | ✅ | ✅ | | Automatic sharding | ✅ | ❌ | ✅ | ✅ | | Parallel distributed queries | ✅ | ❌ | ✅ | ✅ | | OLTP workloads | ✅ | ✅ | ✅ | ⚠️ | | Analytical workloads | ✅ | ⚠️ | ⚠️ | ✅ | | Standard PostgreSQL drivers | ✅ | ✅ | Mostly | ❌ | | PostgreSQL extensions | ✅ | ✅ | Limited | ❌ | | Multi-tenant SaaS workloads | ✅ | ⚠️ | ✅ | ⚠️ | | Familiar PostgreSQL SQL | ✅ | ✅ | Mostly | ❌ | Citus is a strong choice when PostgreSQL compatibility is important but a single PostgreSQL server is no longer sufficient. PostgreSQL remains simpler for smaller workloads that fit comfortably on one server. CockroachDB provides a distributed SQL architecture with strong resilience features, but it is not a PostgreSQL extension and differs internally from PostgreSQL. ClickHouse is highly optimized for analytical workloads, but is not designed as a drop-in PostgreSQL replacement for transactional applications. ## Why Use Citus? Citus allows applications to scale PostgreSQL without abandoning the PostgreSQL ecosystem. Instead of moving to an entirely different distributed database, Citus extends PostgreSQL with distributed tables, shard placement, and parallel query execution. This makes it especially suitable for systems that already depend on PostgreSQL-compatible drivers, ORMs, extensions, and operational tooling. Citus is commonly useful when data can be distributed using a natural key such as: * Tenant ID * Customer ID * Account ID * Device ID * Organization ID Choosing the right distribution column allows related data to remain colocated on the same worker, reducing cross-node communication and improving distributed query performance. ## Horizontal Scaling Distributed tables are divided into shards and distributed across worker nodes. As the dataset grows, additional workers can be added to increase: * Storage capacity * Query throughput * Parallel processing capacity * Aggregate compute resources Shard placement can then be rebalanced across the available workers. This scale-out architecture allows workloads to grow beyond the practical limits of a single PostgreSQL instance. ## Why Deploy Citus on Railway? Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it. By deploying Citus on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway. ## Similar templates - [Garage S3 Storage](https://railway.com/deploy/garage-s3-storage) — Ultra-light S3 server: fast, open-source, plug-and-play. - [Redis](https://railway.com/deploy/redis-1) — Self Host Latest Redis with Railway - [EasyImg](https://railway.com/deploy/easyimg) — Simple self-hostable Nuxt.js personal image hosting system. Open this page in a browser: https://railway.com/deploy/citus