Skip to content

ClickHouse Overview

The Hydrolix system is a data lake solution built on top of the ClickHouse engine. Most ClickHouse tools interoperate with the Hydrolix query system.

Clients may authenticate with credentials or present an authorization token.

ClickHouse native protocol⚓︎

The ClickHouse server interface supports clients and libraries capable of the ClickHouse native protocol.

The tunables native_port with default of 9000 and native_tls_port with a default of 9440, control the TCP port on which the server listens.

The examples on this page use the latter as most clusters are secured by TLS. See also Enable TLS.

Use tunable disable_traefik_native_port to turn off the server.

Authenticate with credentials⚓︎

If the credentials are valid, the ClickHouse server starts an interactive session.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$ clickhouse-client --host {myhost}.hydrolix.live --port 9440 --user 'username@example.com' --secure
ClickHouse client version 25.3.2.39 (official build).
Connecting to {myhost}.hydrolix.live:9440 as user username@example.com.
Password for user (mailto:username@example.com): 
Connecting to {myhost}.hydrolix.live:9440 as user username@example.com.
Connected to ClickHouse server version 24.8.6.

ClickHouse server version is older than ClickHouse client. It may indicate that the server is out of date and can be upgraded.

query-peer :)

If the credentials are invalid, the server sends the following error message. This includes the response from the Config API used by the ClickHouse server to authenticate the user.

1
2
3
4
5
6
$ clickhouse-client --host {myhost}.hydrolix.live --port 9440 --user 'username@example.com' --secure
ClickHouse client version 25.6.4.12 (official build).
Connecting to {myhost}.hydrolix.live:9440 as user username@example.com.
Password for user (mailto:username@example.com): 
Connecting to {myhost}.hydrolix.live:9440 as user username@example.com.
Code: 516. DB::Exception: Received from {myhost}.hydrolix.live:9440. DB::Exception: Address: 10.2.4.74:34902 failed to authenticate user 'username@example.com' due to <TurbineApiAuthenticatorError api login failed with provided username/password 'username@example.com'. <HttpPermanentResponseError error=request_failed status_code=401 path=/config/v1/login {"detail":"Could not login"}>>. (AUTHENTICATION_FAILED)

Present an authorization token⚓︎

The ClickHouse server recognizes authorization tokens, which are issued to authenticated users.

The auth token is communicated over the ClickHouse protocol to the server in the password field. The username required for this feature is __api_token__.

Acquire a token⚓︎

Get the bearer token, which is good for the next 24 hours, to authenticate future API calls. This command assumes you've set the $HDX_HOSTNAME, $HDX_USER and $HDX_PASSWORD environment variables:

1
2
3
4
5
6
7
8
export HDX_TOKEN=$(
  curl -v -X POST -H "Content-Type: application/json" \
  https://$HDX_HOSTNAME/config/v1/login/ \
  -d "{
    \"username\":\"$HDX_USER\",
    \"password\":\"$HDX_PASSWORD\"  
  }" | jq -r ".auth_token.access_token"
)

If the token is valid, the ClickHouse server starts an interactive session.

1
2
3
4
5
6
7
8
$ clickhouse-client --secure --host {myhost}.hydrolix.live --port 9440 --user '__api_token__' --password="$HDX_TOKEN"
ClickHouse client version 25.6.4.12 (official build).
Connecting to {myhost}.hydrolix.live:9440 as user __api_token__.
Connected to ClickHouse server version 24.8.6.

ClickHouse server version is older than ClickHouse client. It may indicate that the server is out of date and can be upgraded.

query-peer :) Bye.

If the token is invalid, the following error message is returned.

1
2
3
4
$ clickhouse-client --secure --host {myhost}.hydrolix.live --port 9440 --user '__api_token__' --password="invalid_token"
ClickHouse client version 25.6.4.12 (official build).
Connecting to {myhost}.hydrolix.live:9440 as user __api_token__.
Code: 516. DB::Exception: Received from {myhost}.hydrolix.live:9440. DB::Exception: username@example.com: Authentication failed: password is incorrect, or there is no user with such name.. (AUTHENTICATION_FAILED)

Version mismatch warning⚓︎

Hydrolix ClickHouse engine versioning

Your ClickHouse client may report server version mismatch. The Hydrolix fork of the ClickHouse engine follows upstream, so isn't synchronized.