Deploy and Host ClickHouse on Railway

ClickHouse is the fastest and most resource efficient open-source database for real-time apps and analytics.

About Hosting ClickHouse

ClickHouse processes analytical queries 100-1000x faster than traditional row-oriented systems with the same available I/O throughput and CPU capacity. Columnar storage format allows fitting more hot data in RAM, which leads to shorter response times.

Common Use Cases

Real-time Applications: Build applications requiring fast data processing and low-latency query responses
Analytics Platforms: Process large volumes of analytical data with high performance and efficiency
Data Warehousing: Store and analyze structured data with columnar storage optimization

Dependencies for ClickHouse Hosting

The Railway template includes the required ClickHouse database engine with pre-configured columnar storage and performance optimizations.

Deployment Dependencies

ClickHouse Official Website

Implementation Details

ClickHouse Features:

Blazing fast: High-performance query processing optimized for analytical workloads
Linearly scalable: Horizontal scaling capabilities for growing data requirements
Highly reliable: Robust database engine designed for production environments

Docker Configuration:

ClickHouse runs as a Docker container based on the official clickhouse/clickhouse-server image. The container exposes port 8123 for the HTTP interface and port 9000 for the native client.

Default Setup:

By default, ClickHouse will be accessible only via the Docker network and runs as the default user without password. The predefined user default does not have network access unless the password is set.

Data Persistence:

The template mounts the following volumes for data persistence:

/var/lib/clickhouse/ - main folder where ClickHouse stores the data
/var/log/clickhouse-server/ - logs

Environment Variables:

CLICKHOUSE_DB: Create a default database on container start
CLICKHOUSE_USER: Create a custom user on container start
CLICKHOUSE_PASSWORD: Set password for the user
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: Enable default access management
CLICKHOUSE_SKIP_USER_SETUP: Make default user available without password (insecure)
CLICKHOUSE_RUN_AS_ROOT: Run server from root (useful for user namespace)

Database Initialization:

The container supports initialization scripts by mounting files under /docker-entrypoint-initdb.d/. It will run any *.sql files, execute *.sh scripts, and source non-executable shell scripts for additional setup before starting the service.

Client Access:

Connect using the native client or HTTP interface with curl commands. The HTTP interface allows SQL queries via REST API, while the native client provides full ClickHouse functionality.

Configuration:

Two variables add ClickHouse configuration without a custom image. Each is written to a config file when the container starts:

CLICKHOUSE_EXTRA_CONFIG_XML: server settings, written to /etc/clickhouse-server/config.d/
CLICKHOUSE_EXTRA_USERS_XML: users and profiles, written to /etc/clickhouse-server/users.d/

System Logs:

ClickHouse writes its own diagnostic logs to the data volume and keeps them forever by default, which can fill a volume with tens of gigabytes over a few months. This template keeps query_log, part_log and error_log for CLICKHOUSE_LOG_RETENTION_DAYS days (default 7) and disables the high-volume diagnostic logs. Edit CLICKHOUSE_EXTRA_CONFIG_XML to change which logs are kept.

Existing Deployments:

Services deployed from this template before October 2026 keep the old behavior, and their system logs grow without limit. To apply the fix:

Copy the start command and the CLICKHOUSE_LOG_RETENTION_DAYS, CLICKHOUSE_EXTRA_CONFIG_XML and CLICKHOUSE_EXTRA_USERS_XML variables from this template into your service. The easiest way is to deploy this template into a scratch project and copy the values from there.
Deploy from source. Redeploying the previous deployment reuses the old settings.
Drop the old log tables, for example DROP TABLE system.trace_log. Disabling a log stops new writes but does not delete existing data.

Why Deploy ClickHouse 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 ClickHouse 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.