> ## Documentation Index > Fetch the complete documentation index at: https://developer.upsun.com/llms.txt > Use this file to discover all available pages before exploring further. # ClickHouse 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](https://ClickHouse.com/docs). > [!NOTE] > > Upsun Cloud supports ClickHouse with the following limitations: > > * High availability of service isn't supported. > * You can only configure single-node ClickHouse clusters. ## Supported versions * 26.8 * 26.3 Upsun plans on supporting long-term support ClickHouse versions in priority. ## Deprecated versions The following versions are still available in your projects, but they're at their end of life and are no longer receiving security updates from upstream. * 25.8 * 25.3 * 24.3 * 23.8 To ensure your project remains stable in the future, switch to a [supported version](#supported-versions). ## Retired versions The following versions have been retired and are no longer available. If your project uses a retired version, you must update to a [supported version](#supported-versions). *No retired versions.* ## Relationship reference For each service [defined via a relationship](#usage-example) to your application, Upsun Cloud automatically generates corresponding environment variables within your application container, in the `$_` format. Here is example information available through the [service environment variables](https://developer.upsun.com/docs/development/variables#service-environment-variables) themselves, or through the [`PLATFORM_RELATIONSHIPS` environment variable](https://developer.upsun.com/docs/development/variables/use-variables#use-provided-variables). > [tab] Service environment variables > > 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](https://developer.upsun.com/docs/development/variables#service-environment-variables) directly rather than hard coding any values. > > CLICKHOUSE\_USERNAME=main > CLICKHOUSE\_FRAGMENT= > CLICKHOUSE\_IP=123.456.78.90 > CLICKHOUSE\_CLUSTER=azertyuiop-main-afdwftq > CLICKHOUSE\_HOST=clickhouse.internal > CLICKHOUSE\_PATH=main > CLICKHOUSE\_QUERY=\{'is\_master': true} > CLICKHOUSE\_PASSWORD=ChangeMe > CLICKHOUSE\_PORT=9000 > CLICKHOUSE\_HOST\_MAPPED=false > CLICKHOUSE\_SERVICE=clickhouse > CLICKHOUSE\_HOSTNAME=azertyuiopqsdfghjklm.clickhouse.service.\_.eu-1.platformsh.site > CLICKHOUSE\_EPOCH=0 > CLICKHOUSE\_REL=clickhouse > CLICKHOUSE\_SCHEME=https/http > CLICKHOUSE\_TYPE=clickhouse:\{\{version:clickhouse:latest}} > CLICKHOUSE\_PUBLIC=false > > [tab] `PLATFORM_RELATIONSHIPS` environment variable > > For some advanced use cases, you can use the [`PLATFORM_RELATIONSHIPS` environment variable](https://developer.upsun.com/docs/development/variables/use-variables#use-provided-variables). > The structure of the `PLATFORM_RELATIONSHIPS` environment variable can be obtained by running `upsun relationships` in your terminal: > > \{ > "username": "main", > "fragment": null, > "ip": "123.456.78.90", > "cluster": "azertyuiop-main-afdwftq", > "host": "clickhouse.internal", > "path": "main", > "query": \{ > "is\_master": true > }, > "password": "ChangeMe", > "port": 9000, > "host\_mapped": false, > "service": "clickhouse", > "hostname": "azertyuiopqsdfghjklm.clickhouse.service.\_.eu-1.platformsh.site", > "epoch": 0, > "rel": "clickhouse", > "scheme": "https", > "type": "clickhouse:\{\{version:clickhouse:latest}}", > "public": false > } > > > Here is an example of how to gather [`PLATFORM_RELATIONSHIPS` environment variable](https://developer.upsun.com/docs/development/variables/use-variables#use-provided-variables) information in a [`.environment` file](https://developer.upsun.com/docs/development/variables/set-variables#when-to-use-env-files): > > ```bash .environment theme={null} > # Decode the built-in credentials object variable. > export RELATIONSHIPS_JSON="$(echo "$PLATFORM_RELATIONSHIPS" | base64 --decode)" > > # Set environment variables for individual credentials. > export APP_CLICKHOUSE_HOST=="$(echo "$RELATIONSHIPS_JSON" | jq -r '.clickhouse[0].host')" > ``` ## Usage example ### 1. Configure the service To define the service, use the `clickhouse` type: services: \# The name of the service container. Must be unique within a project. \: type: clickhouse:\ 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: > [tab] Using default endpoints > > applications: > \# The name of the app container. Must be unique within a project. > \: > \# Relationships enable access from this app to a given service. > \# The example below shows simplified configuration leveraging a default service > \# (identified from the relationship name) and a default endpoint. > \# See the Application reference for all options for defining relationships and endpoints. > relationships: > \: > > > You can define `SERVICE_NAME` as you like. > [tab] Using explicit endpoints > > applications: > \# The name of the app container. Must be unique within a project. > \: > \# Relationships enable access from this app to a given service. > \# The example below shows configuration with an explicitly set service name and endpoint. > \# See the Application reference for all options for defining relationships and endpoints. > relationships: > \: > service: \ > endpoint: clickhouse > > > You can define `SERVICE_NAME` and `` as you like, but it's best if they're distinct. > With this definition, the application container (`:`) now has access to the service via the corresponding [service environment variables](https://developer.upsun.com/docs/development/variables#service-environment-variables). #### `clickhouse-http` endpoint The `clickhouse-http` endpoint allows you to use the HTTP API Port for HTTP requests. This protocol is used by [JDBC](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/), [ODBC](https://learn.microsoft.com/en-us/sql/odbc/microsoft-open-database-connectivity-odbc?view=sql-server-ver16), and web interfaces. Use the following configuration: applications: \# The name of the app container. Must be unique within a project. \: \# Relationships enable access from this app to a given service. \# The example below shows configuration with an explicitly set service name and endpoint. \# See the Application reference for all options for defining relationships and endpoints. relationships: \: service: \ endpoint: clickhouse-http services: \# The name of the service container. Must be unique within a project. \: type: clickhouse:\ You can define `SERVICE_NAME` and `` 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 (`:`) now has access to the service via the corresponding [service environment variables](https://developer.upsun.com/docs/development/variables#service-environment-variables). ### Example configuration > [tab] With `clickhouse` default endpoint > > applications: > \# The name of the app container. Must be unique within a project. > myapp: > \# The location of the application's code. > source: > root: "/" > \# Relationships enable access from this app to a given service. > \# The example below shows simplified configuration leveraging a default service > \# (identified from the relationship name) and a default endpoint. > \# See the Application reference for all options for defining relationships and endpoints. > relationships: > clickhouse: > services: > \# The name of the service container. Must be unique within a project. > clickhouse: > type: clickhouse:\{\{version:clickhouse:latest}} > [tab] With `clickhouse` explicit endpoint > > applications: > \# The name of the app container. Must be unique within a project. > myapp: > \# The location of the application's code. > source: > root: "/" > \# Relationships enable access from this app to a given service. > \# The example below shows configuration with an explicitly set service name and endpoint. > \# See the Application reference for all options for defining relationships and endpoints. > relationships: > clickhouse: > service: clickhouse > endpoint: clickhouse > services: > \# The name of the service container. Must be unique within a project. > clickhouse: > type: clickhouse:\{\{version:clickhouse:latest}} > [tab] With `clickhouse-http` endpoint > > applications: > \# The name of the app container. Must be unique within a project. > myapp: > \# The location of the application's code. > source: > root: "/" > \# Relationships enable access from this app to a given service. > \# The example below shows configuration with an explicitly set service name and endpoint. > \# See the Application reference for all options for defining relationships and endpoints. > relationships: > clickhouse: > service: clickhouse > endpoint: clickhouse-http > services: > \# The name of the service container. Must be unique within a project. > clickhouse: > type: clickhouse:\{\{version:clickhouse:latest}} 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](https://developer.upsun.com/docs/add-services/postgresql#multiple-databases). To do so, you can use a configuration similar to the following: \# Complete list of all available properties: /docs/configure-apps/app-reference applications: myapp: \# Relationships enable access from this app to a given service. \# The example below shows configuration with explicitly set service names and endpoints. \# See the Application reference for all options for defining relationships and endpoints. relationships: clickhouse-admin: service: clickhouse endpoint: admin clickhouse-reporter: service: clickhouse endpoint: reporter clickhouse-importer: service: clickhouse endpoint: importer services: clickhouse: type: clickhouse:\{\{version:clickhouse:latest}} configuration: databases: \- main \- legacy endpoints: admin: port: 9000 # binary port privileges: main: admin legacy: admin reporter: default\_database: main port: 8123 # http port privileges: main: ro importer: default\_database: legacy port: 9000 # binary port privileges: legacy: rw ## 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: ```bash Terminal theme={null} upsun tunnel:single --relationship ``` By default this opens the tunnel on `127.0.0.1:30000`. 2. Export a table or the result of a query to a file: ```bash Terminal theme={null} clickhouse-client \ --host 127.0.0.1 \ --port 9000 \ --user \ --password \ --database \ --query "SELECT * FROM " \ --format CSVWithNames > table_export.csv ``` You can replace `CSVWithNames` with any [ClickHouse output format](https://clickhouse.com/docs/en/interfaces/formats) such as `Parquet`, `JSONEachRow`, or `Native` depending on your needs. 3. To export the full schema of your database: ```bash Terminal theme={null} clickhouse-client \ --host 127.0.0.1 \ --port 9000 \ --user \ --password \ --query "SHOW CREATE TABLE " ``` The credentials (``, ``, ``) are available in the service environment variables. Run `upsun ssh -- env | grep CLICKHOUSE` to retrieve them. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.