Skip to main content
ClickHouse is a high-performance column-oriented, distributed, OLAP (Online Analytical Processing) database.
It allows you to generate real-time analytical data reports using SQL queries.
For more information, see the ClickHouse documentation.
Upsun supports ClickHouse with the following limitations:
  • High availability of service isn’t supported.
  • You can only configure single-node ClickHouse clusters.

​
Supported versions

Upsun plans on supporting long-term support ClickHouse versions in priority.

​
Relationship reference

For each service defined via a relationship to your application, Upsun automatically generates corresponding environment variables within your application container, in the $<RELATIONSHIP-NAME>_<SERVICE-PROPERTY> format. Here is example information available through the service environment variables themselves, or through the PLATFORM_RELATIONSHIPS environment variable.
You can obtain the complete list of available service environment variables in your app container by running upsun ssh env.Note that the information about the relationship can change when an app is redeployed or restarted or the relationship is changed. So your apps should only rely on the service environment variables directly rather than hard coding any values.

​
Usage example

​
1. Configure the service

To define the service, use the clickhouse type: Note that changing the name of the service replaces it with a brand new service and all existing data is lost. Back up your data before changing the service.

​
2. Define the relationship

To define the relationship, use one of the following endpoints.

​
clickhouse endpoint

The clickhouse endpoint allows you to use the Native Protocol port (also known as ClickHouse TCP protocol). This protocol is used by ClickHouse apps and processes such as clickhouse-server, clickhouse-client, and native ClickHouse tools. It is also used for inter-server communication for distributed queries. Use the following configuration:
You can define SERVICE_NAME as you like.

​
clickhouse-http endpoint

The clickhouse-http endpoint allows you to use the HTTP API Port for HTTP requests. This protocol is used by JDBC, ODBC, and web interfaces. Use the following configuration: You can define SERVICE_NAME and <RELATIONSHIP_NAME> as you like, so long as it’s unique between all defined services and relationships and matches in both the application and services configuration. With this definition, the application container (<APP_NAME>:) now has access to the service via the corresponding service environment variables.

​
Example configuration

If you want to change the clickhouse endpoint to clickhouse-http, you need to use explicit endpoint definition as it defaults to clickhouse endpoint when using default endpoint (aka. as relationship definition).

​
Multiple databases

You can configure multiple databases, much like with PostgreSQL. To do so, you can use a configuration similar to the following:

​
Exporting Data

ClickHouse data can be exported using the native clickhouse-client tool over an SSH tunnel.
  1. Open an SSH tunnel to your ClickHouse service:
Terminal
upsun tunnel:single --relationship <RELATIONSHIP_NAME>
By default this opens the tunnel on 127.0.0.1:30000.
  1. Export a table or the result of a query to a file:
Terminal
clickhouse-client \
  --host 127.0.0.1 \
  --port 9000 \
  --user <CLICKHOUSE_USERNAME> \
  --password <CLICKHOUSE_PASSWORD> \
  --database <CLICKHOUSE_PATH> \
  --query "SELECT * FROM <TABLE_NAME>" \
  --format CSVWithNames > table_export.csv
You can replace CSVWithNames with any ClickHouse output format such as Parquet, JSONEachRow, or Native depending on your needs.
  1. To export the full schema of your database:
Terminal
clickhouse-client \
  --host 127.0.0.1 \
  --port 9000 \
  --user <CLICKHOUSE_USERNAME> \
  --password <CLICKHOUSE_PASSWORD> \
  --query "SHOW CREATE TABLE <TABLE_NAME>"
The credentials (<CLICKHOUSE_USERNAME>, <CLICKHOUSE_PASSWORD>, <CLICKHOUSE_PATH>) are available in the service environment variables. Run upsun ssh -- env | grep CLICKHOUSE to retrieve them.
Last modified on March 11, 2026